ff71886fd7
- i18n 사전 100% (break/overtime/leave/clockin) — 50+ 신규 키 - 런타임 재번역 인프라 (ui/i18n_runtime.py) — 재시작 없이 메인 UI 적용 - MealController 분리 — 점심/저녁 토글을 컨트롤러로 추출 - 통합 테스트 +15 (S36-S52: 온보딩/salary/CSV/notification dedupe 등) - pytest 신규 4종 + i18n_runtime 테스트 (총 122 케이스, 90→122) - README/INSTALL/CLAUDE/AGENTS v2.6+ 아키텍처 반영
185 lines
5.8 KiB
Markdown
185 lines
5.8 KiB
Markdown
# 설치 가이드
|
|
|
|
## 일반 사용자 — 빌드된 .exe로 설치 (권장)
|
|
|
|
소스 빌드 없이 즉시 사용하려면 Gitea Releases에서 받으세요.
|
|
|
|
1. https://kindnick-git.duckdns.org/kindnick/Clock_out_Time_Calculator/releases
|
|
2. 최신 릴리스의 **main.exe** (단일 파일) 다운로드
|
|
3. 원하는 폴더에 두고 더블클릭으로 실행
|
|
4. 첫 실행 시 5단계 온보딩 위저드가 안내
|
|
|
|
`main.exe` 안에 `updater.exe`가 내장되어 있어 첫 실행 시 같은 폴더로 자동 추출됩니다.
|
|
이후 새 버전이 올라오면 앱이 알림 → 동의 → 자동 다운로드·교체·재시작합니다.
|
|
|
|
> 옵션: 직접 실행하지 않고 ZIP을 받으면 `main.exe + updater.exe`가 같이 들어 있습니다.
|
|
|
|
## 개발자 — 소스에서 실행
|
|
|
|
### 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. 프로젝트 다운로드
|
|
|
|
```bash
|
|
git clone https://kindnick-git.duckdns.org/kindnick/Clock_out_Time_Calculator.git
|
|
cd Clock_out_Time_Calculator
|
|
```
|
|
|
|
또는 ZIP을 받아 압축 해제.
|
|
|
|
### 3. 패키지 설치
|
|
|
|
프로젝트 폴더에서 명령 프롬프트(cmd) 또는 PowerShell을 엽니다.
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
#### 설치되는 패키지 (requirements.txt)
|
|
1. **PyQt5** — GUI 프레임워크
|
|
2. **pywin32** — Windows API (이벤트 뷰어, 화면 잠금 감지)
|
|
3. **python-dateutil** — 날짜 계산
|
|
4. **matplotlib** — 통계 차트
|
|
5. **plyer** — 시스템 알림
|
|
6. **holidays** — 한국 공휴일 자동 등록 (음력 명절 포함)
|
|
|
|
### 4. 실행
|
|
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
#### 관리자 권한으로 실행 (권장)
|
|
|
|
Windows 이벤트 뷰어 접근을 위해 관리자 권한이 필요할 수 있습니다.
|
|
|
|
1. **방법 1**: cmd를 관리자 권한으로 실행
|
|
- Windows 키 + X → "터미널(관리자)" 또는 "PowerShell(관리자)"
|
|
- 프로젝트 폴더로 이동: `cd "경로"`
|
|
- `python main.py` 실행
|
|
|
|
2. **방법 2**: 바로가기 생성
|
|
- `python main.py`를 실행하는 배치 파일(.bat) 생성
|
|
- 우클릭 → 속성 → 고급 → "관리자 권한으로 실행" 체크
|
|
|
|
### 5. 첫 실행
|
|
|
|
1. 실행 시 자동으로 데이터베이스(`database.db`) 생성
|
|
2. 5단계 온보딩 위저드 표시
|
|
- 환영 → 근무패턴 → 출근 자동 감지 → 연차/시급 → Discord 웹훅(옵션)
|
|
3. 위저드 완료 후 메인 화면 진입
|
|
4. 이후 실행에서는 위저드 없이 바로 시작
|
|
|
|
### 6. 단축근무자 설정 (예: 7시간 30분)
|
|
|
|
온보딩에서 미설정한 경우:
|
|
1. 설정(`Ctrl+,`) → 근무 시간 → **근무 패턴**
|
|
2. "단축근무 7시간 30분 (점심 30분)" 또는 사용자 정의 선택
|
|
3. 시·분 직접 입력 가능 (5분 단위)
|
|
4. 저장 → 즉시 메인 화면 반영
|
|
|
|
## 클라우드 동기화 (여러 PC 공용)
|
|
|
|
OneDrive / Dropbox 폴더에 DB를 두면 자동 동기화됩니다 (WAL 모드).
|
|
|
|
1. OneDrive/Dropbox 안에 `database.db` 위치 결정
|
|
2. 설정 → 데이터 관리 → DB 경로 → 변경
|
|
3. 기존 DB를 새 위치로 복사 → 재시작
|
|
4. 다른 PC에서도 같은 경로 지정하면 데이터 공유
|
|
|
|
## 환경 변수
|
|
|
|
| 변수 | 용도 |
|
|
|------|------|
|
|
| `CLOCKOUT_DEBUG=1` | `~/.clockout_logs/debug.log`에 디버그 로그 출력 |
|
|
| `CLOCKOUT_DEBUG_DIR=경로` | 로그 저장 위치 변경 |
|
|
| `GITEA_TOKEN` | 릴리스 발행 시 PAT (개발자용) |
|
|
| `CODE_SIGN_CERT` / `CODE_SIGN_PASS` | Authenticode 인증서 경로/암호 (개발자용) |
|
|
|
|
## 문제 해결
|
|
|
|
### 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
|
|
|
|
### 이벤트 뷰어 접근 불가
|
|
- 관리자 권한으로 실행
|
|
- 또는 메인 화면 출근시각 옆 ✏️ 버튼으로 수동 입력
|
|
|
|
### Discord 웹훅 "실패" 표시
|
|
- v2.3.3 이전 버전에서 발생 — Cloudflare가 Python User-Agent 차단
|
|
- 최신 버전으로 업데이트하면 해결 (브라우저 UA로 우회)
|
|
|
|
### 온보딩 위저드를 다시 보고 싶음
|
|
- 도움말(F1) → "🚀 온보딩 다시 보기"
|
|
|
|
## 업그레이드
|
|
|
|
### .exe 사용자
|
|
- 앱이 자동 감지 → 알림 → 동의 → 자동 처리
|
|
- 수동 트리거: F5 또는 설정 → 데이터 관리 → "업데이트 확인"
|
|
|
|
### 소스 사용자
|
|
```bash
|
|
git pull
|
|
pip install --upgrade -r requirements.txt
|
|
```
|
|
|
|
## 제거
|
|
|
|
1. 프로젝트 폴더 삭제 (`main.exe` 또는 소스)
|
|
2. 데이터 보존하려면 `database.db`만 별도 백업
|
|
3. 자동 백업: `~/.clockout_backups/` 에 7개 회전 보관 (필요 시 삭제)
|
|
|
|
## 프로덕션 빌드 (PyInstaller)
|
|
|
|
소스 없이 실행 파일만 배포하려면:
|
|
|
|
```bash
|
|
# 자가 업데이터 먼저 빌드 (main.spec이 데이터로 임베드)
|
|
python -m PyInstaller --clean updater.spec # → dist/updater.exe (~6MB)
|
|
|
|
# updater.exe를 staging 폴더로 복사 (main.spec --clean 시 보호)
|
|
mkdir -p build/staging
|
|
cp dist/updater.exe build/staging/
|
|
|
|
# 메인 앱 빌드 (updater.exe 임베드 포함)
|
|
python -m PyInstaller --clean main.spec # → dist/main.exe (~78MB)
|
|
```
|
|
|
|
또는 [release.ps1](release.ps1) 한 번 실행으로 전체 자동화.
|
|
|
|
빌드 시 주의:
|
|
- `dist/main.exe`가 실행 중이면 `PermissionError` 발생 → 종료 후 재실행
|
|
- `holidays` 등 옵셔널 패키지는 설치된 환경에서 빌드해야 포함됨
|
|
- `main.exe` 단일 배포가 가능 (updater.exe는 첫 실행 시 자동 추출)
|
|
|
|
## 다음 단계
|
|
|
|
설치가 완료되었다면 [README.md](README.md) 와 도움말(F1)을 참고하세요.
|
|
개발자는 [CLAUDE.md](CLAUDE.md) + [AGENTS.md](AGENTS.md) 도 함께 읽으세요.
|