# 설치 가이드

## 일반 사용자 — 빌드된 .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) 도 함께 읽으세요.