bedbb1e9ec
Some checks failed
CI / test (push) Has been cancelled
핵심 기능: - 단축근무·표준·반일 등 다양한 근무 패턴 (5개 프리셋 + 사용자 정의) - Windows 이벤트 뷰어 자동 출퇴근 감지 - 30분 단위 연장근무 적립/사용 시스템 - 1.0/0.5/0.25일 연차·반차·반반차 - 자동 점심·저녁·외출·자동 백업·화면 잠금 자동 외출 - 한국 공휴일 자동 등록 (음력 포함, holidays 패키지) - matplotlib 차트 기반 주간/월간/패턴 통계 - 미니 위젯 + 시스템 트레이 통합 - 한국어/English i18n - 자가 업데이트 (updater.exe + Gitea Releases) 아키텍처: - core/ (db, time_calculator, notifier, i18n, version, settings_keys) - ui/ (main_window + 9 dialogs + 3 controllers) - utils/ (backup, lock_detector, debug_log, updater_client, time_format) - tests/ (66 pytest 단위) + 통합/i18n GUI 검증 CI/CD: - .gitea/workflows/ci.yml: push 시 pytest + 통합 테스트 - .gitea/workflows/release.yml: v* 태그 push 시 두 .exe 자동 빌드 + Releases 첨부 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
161 lines
4.2 KiB
Markdown
161 lines
4.2 KiB
Markdown
# 설치 가이드
|
|
|
|
## 1. Python 설치
|
|
|
|
Python 3.9 이상이 필요합니다.
|
|
|
|
### Windows
|
|
1. https://www.python.org/downloads/ 방문
|
|
2. "Download Python 3.x.x" 클릭
|
|
3. 설치 시 **"Add Python to PATH"** 체크 필수!
|
|
|
|
확인:
|
|
```bash
|
|
python --version
|
|
```
|
|
|
|
## 2. 프로젝트 다운로드
|
|
|
|
프로젝트를 다운로드하거나 압축을 해제합니다.
|
|
|
|
## 3. 패키지 설치
|
|
|
|
프로젝트 폴더에서 명령 프롬프트(cmd) 또는 PowerShell을 엽니다.
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 설치되는 패키지:
|
|
1. **PyQt5** - GUI 프레임워크
|
|
2. **pywin32** - Windows API 접근
|
|
3. **python-dateutil** - 날짜 계산
|
|
4. **matplotlib** - 그래프
|
|
5. **plyer** - 알림 시스템
|
|
6. **holidays** - 한국 공휴일 자동 등록 (음력 명절 포함)
|
|
|
|
## 4. 리소스 다운로드 (선택)
|
|
|
|
리소스가 없어도 프로그램은 작동하지만, 더 예쁜 UI를 위해 다운로드를 권장합니다.
|
|
|
|
```bash
|
|
python download_resources.py
|
|
```
|
|
|
|
이 스크립트는 무료 리소스 다운로드 링크를 안내합니다.
|
|
|
|
### 수동 다운로드:
|
|
|
|
#### 아이콘
|
|
다음 사이트에서 다운로드:
|
|
- **Flaticon**: https://www.flaticon.com/
|
|
- **Material Design Icons**: https://materialdesignicons.com/
|
|
- **Icons8**: https://icons8.com/
|
|
|
|
다운로드 후 `resources/icons/` 폴더에 저장
|
|
|
|
필요한 아이콘:
|
|
- `app_icon.ico` (512x512)
|
|
- `clock.png`, `timer.png`, `lunch.png`
|
|
- `calendar.png`, `statistics.png`, `vacation.png`
|
|
- `settings.png`, `notification.png`
|
|
|
|
#### 사운드
|
|
다음 사이트에서 다운로드:
|
|
- **Mixkit**: https://mixkit.co/free-sound-effects/ (추천)
|
|
- **Freesound**: https://freesound.org/
|
|
- **Zapsplat**: https://www.zapsplat.com/
|
|
|
|
다운로드 후 `resources/sounds/` 폴더에 저장
|
|
|
|
필요한 사운드:
|
|
- `clock_out_alarm.wav` - 퇴근시간 알림
|
|
- `notification.wav` - 일반 알림
|
|
- `success.wav` - 성공 효과음
|
|
|
|
## 5. 실행
|
|
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
### 관리자 권한으로 실행 (권장)
|
|
|
|
Windows 이벤트 뷰어 접근을 위해 관리자 권한이 필요할 수 있습니다.
|
|
|
|
1. **방법 1**: cmd를 관리자 권한으로 실행
|
|
- Windows 키 + X
|
|
- "명령 프롬프트(관리자)" 또는 "Windows PowerShell(관리자)" 선택
|
|
- 프로젝트 폴더로 이동: `cd "경로"`
|
|
- `python main.py` 실행
|
|
|
|
2. **방법 2**: 바로가기 생성
|
|
- `python main.py`를 실행하는 배치 파일(.bat) 생성
|
|
- 우클릭 → 속성 → 고급 → "관리자 권한으로 실행" 체크
|
|
|
|
## 6. 첫 실행
|
|
|
|
1. 프로그램이 실행되면 자동으로 데이터베이스(`database.db`) 생성
|
|
2. Windows 이벤트 뷰어에서 오늘의 부팅 시간 자동 감지
|
|
3. 감지된 시간이 출근시간으로 설정됨
|
|
|
|
## 문제 해결
|
|
|
|
### pywin32 설치 오류
|
|
```bash
|
|
pip install --upgrade pywin32
|
|
python -m pywin32_postinstall -install
|
|
```
|
|
|
|
### PyQt5 설치 오류
|
|
```bash
|
|
pip install --upgrade pip
|
|
pip install PyQt5
|
|
```
|
|
|
|
### "DLL load failed" 오류
|
|
Visual C++ Redistributable 설치 필요:
|
|
https://aka.ms/vs/17/release/vc_redist.x64.exe
|
|
|
|
### 이벤트 뷰어 접근 불가
|
|
- 관리자 권한으로 실행
|
|
- 또는 설정에서 수동 입력 모드 사용
|
|
|
|
## 업그레이드
|
|
|
|
```bash
|
|
pip install --upgrade -r requirements.txt
|
|
```
|
|
|
|
## 제거
|
|
|
|
1. 프로젝트 폴더 삭제
|
|
2. 패키지 제거 (선택):
|
|
```bash
|
|
pip uninstall PyQt5 pywin32 python-dateutil pandas matplotlib plyer
|
|
```
|
|
|
|
## 프로덕션 빌드 (PyInstaller)
|
|
|
|
소스 없이 실행 파일만 배포하려면:
|
|
```bash
|
|
python -m PyInstaller --clean main.spec # → dist/main.exe (~73MB)
|
|
python -m PyInstaller --clean updater.spec # → dist/updater.exe (~6MB, 자가 업데이터)
|
|
```
|
|
|
|
배포 패키지에는 두 .exe를 함께 포함시켜 같은 폴더에 두세요.
|
|
자동 업데이트는 main.exe가 같은 폴더의 updater.exe를 호출해야 동작합니다.
|
|
|
|
빌드 시 주의:
|
|
- `dist/main.exe`가 실행 중이면 `PermissionError` 발생 → 종료 후 재실행
|
|
- `holidays` 등 옵셔널 패키지는 설치된 환경에서 빌드해야 포함됨
|
|
|
|
## 환경 변수
|
|
|
|
- `CLOCKOUT_DEBUG=1` — 디버그 로그를 `~/.clockout_logs/debug.log`로 출력
|
|
- `CLOCKOUT_DEBUG_DIR=경로` — 로그 저장 위치 변경
|
|
|
|
## 다음 단계
|
|
|
|
설치가 완료되었다면 [README.md](README.md)를 참고하여 프로그램을 사용하세요!
|