Clock_out_Time_Calculator/README.md

# Clock-out Time Calculator ⏰

퇴근시간을 자동으로 계산하고 연장근무를 관리하는 Windows용 데스크톱 애플리케이션

## 주요 기능

### 1. 자동 출퇴근 관리
- Windows 이벤트 뷰어에서 컴퓨터 부팅/로그인 시간 자동 감지
- 오늘의 첫 부팅 시간을 출근시간으로 자동 기록
- 실시간 퇴근까지 남은 시간 카운트다운 (1초 갱신)
- 진행률 프로그레스 바 표시

### 2. 다양한 근무 패턴 지원
- **표준 8시간** (점심 60분)
- **단축근무 7시간 30분** (점심 30분)
- **단축근무 7시간 / 6시간**
- **반일 4시간** (점심 없음)
- **사용자 정의** — 시간/분 5분 단위 자유 입력
- 점심시간 자동 적용 옵션 (출근 후 4시간 경과)

### 3. 연장근무 30분 단위 적립 시스템
- 정규 퇴근 이후 시간을 30분 단위 절삭하여 적립
  - 1h 35m → 1h 30m, 55m → 30m, 29m → 0m
- 적립된 시간을 30분/1시간 단위로 사용 가능
- 사용 시 그날 퇴근시간 자동 단축
- 주말·공휴일 근무: 모든 시간이 연장근무로 적립

### 4. 연차/반차 관리
- 1.0일 / 0.5일(반차, 4h) / 0.25일(반반차, 2h) 지원
- 연간 연차 잔액 자동 계산
- 단축근무자 자동 환산 (7h30m 근무자 → 1일 = 450분)

### 5. 외출(자리 비움) 추적
- 외출 시작/복귀 버튼으로 분 단위 측정
- **화면 잠금 자동 외출** — PC 잠금 시 자동 시작, 풀리면 복귀

### 6. 알림 시스템
- 퇴근 30분 전 알림
- 점심시간 미등록 알림 (출근 4시간 후)
- 연장근무 적립 예정 알림
- 연장근무 누적 20시간 알림
- **건강 경고** — 3일 이상 연속 연장근무
- **주 52시간 초과** 경고
- 각 알림 개별 ON/OFF 가능

### 7. 통계·분석
- 주간/월간 요약 + matplotlib 차트
- 일별 근무시간 + 연장 누적 막대 그래프 (호버 시 정확한 수치 툴팁)
- 요일별 평균 근무시간
- 출근 시각 분포 히스토그램 (30분 단위 + 평균선)
- 근무 패턴 인사이트
- **시급 옵션 활성 시 추정 급여** (월간 + 오늘 요약)

### 8. 공휴일 관리
- 한국 공휴일 자동 등록 (`holidays` 패키지)
  - 양력 + **음력 명절(설날/추석/석가탄신일)** + 임시공휴일
- 사용자 정의 공휴일 직접 추가
- 공휴일 근무 시 모든 시간 연장근무 적립

### 9. 미니 위젯 + 시스템 트레이
- Always-on-top 미니 위젯으로 남은 시간 큰 글씨 표시
- 트레이 메뉴에서 빠른 점심/외출/퇴근/통계/캘린더 접근

### 10. 데이터 신뢰성
- **DB 자동 백업** — 1일 1회 `~/.clockout_backups/`에 회전 (최신 7개 보관)
- **클라우드 동기화** — DB 경로를 OneDrive/Dropbox 폴더로 변경 가능
- 마이그레이션 sentinel로 1회 실행 보장

### 11. 자동 업데이트
- 시작 시 백그라운드 버전 체크 (Gitea Releases API)
- 새 버전 발견 시 알림 + 사용자 동의 후 자동 다운로드·교체·재시작
- F5 또는 설정 → 데이터 관리 → "업데이트 확인" 으로 수동 트리거
- 실패 시 자동 롤백
- **main.exe 단독 배포** (updater.exe 내장, 첫 실행 시 자동 추출)

### 12. 첫 실행 온보딩 위저드
- 신규 사용자: 5단계 (환영 → 근무패턴 → 출근 감지 → 연차/시급 → Discord) 강제 표시
- 기존 사용자: 자동 완료 처리 + 도움말(F1) → "🚀 온보딩 다시 보기"

### 13. 사용자 친화 기능
- **메인 화면 인라인 편집** — 출퇴근 시각 라벨 클릭으로 즉시 수정
- **퇴근 후 "오늘 요약" 카드** — 총 근무·점심·외출·연장·추정급여 한눈에
- **장시간 근무 휴식 권고** — 4시간 연속 근무 시 토스트 + Discord push
- **점심/저녁 실제 시간 입력** — 버튼 우클릭 → 시작·종료 시각
- **캘린더 우클릭 → 과거 일자 추가/편집/삭제**
- **월간 목표** — 연장근무 상한 / 일평균 목표 + 진행률 게이지
- **CSV 가져오기** — 표준 포맷으로 타 도구에서 마이그레이션
- **자동 Crash Report** — 예외 발생 시 Gitea Issues 자동 등록 (옵션)
- **주간 자동 리포트** — 월요일 첫 출근 시 지난주 요약 push
- **휴가 캘린더** — 종일/반차/반반차 색상 구분
- **Discord 웹훅 알림** — 출퇴근/휴식권고/주간리포트 모바일 push (옵션, 서버 0)

### 14. 접근성
- 글꼴 크기 100% / 125% / 150%
- 고대비 모드 (검정 배경 + 노란 텍스트)

### 16. 다국어 지원 (i18n)
- 한국어 / English 전환 (재시작 또는 즉시 갱신)
- 알림 메시지·UI 라벨 30+ 카테고리
- HelpView 6개 탭 ko/en HTML 콘텐츠

### 17. 단축키
- `Ctrl+O` 출/퇴근 토글
- `Ctrl+L` 점심 토글, `Ctrl+D` 저녁 토글
- `Ctrl+B` 외출 관리, `Ctrl+,` 설정, `F1` 도움말
- `F5` 업데이트 확인
- `Ctrl+R` 일일보고

## 설치

### 요구사항
- Windows 10/11
- Python 3.9+
- RAM 2GB+

### 설치 단계
```bash
# 1. 저장소 가져오기 (또는 ZIP 압축 해제)

# 2. 패키지 설치
pip install -r requirements.txt

# 3. 실행
python main.py
```

### 필수 패키지 (requirements.txt)
- PyQt5 — GUI
- pywin32 — Windows 이벤트 뷰어 접근
- python-dateutil — 날짜 처리
- matplotlib — 그래프
- plyer — 시스템 알림
- holidays — 공휴일 자동 등록 (음력 포함)

## 사용 방법

### 첫 실행
1. 실행 시 오늘의 부팅 시간을 자동 감지하여 출근으로 기록
2. **설정 → 근무 시간** 에서 본인 근무 패턴 선택 (단축근무자는 프리셋에서)
3. **설정 → 휴가 → 연간 연차** 에서 본인 연차 일수 입력

### 단축근무 사용자 (예: 7시간 30분 + 점심 30분)
1. 설정 → 근무 시간 → **근무 패턴** 에서 "단축근무 7시간 30분 (점심 30분)" 선택
2. 또는 사용자 정의로 시간/분 직접 입력 (5분 단위)
3. 저장 → 즉시 메인 화면 반영

### 클라우드 동기화 (여러 PC)
1. OneDrive/Dropbox 폴더 안에 `database.db` 위치 결정
2. 설정 → 데이터 관리 → DB 경로 → 변경
3. 기존 DB 파일을 새 위치로 복사 → 재시작
4. 다른 PC에서도 같은 경로 지정 시 동일 데이터 공유

## 데이터 저장
- SQLite 데이터베이스 (`database.db`, 실행 폴더)
- 자동 백업: `~/.clockout_backups/database-YYYY-MM-DD.db` (7개 회전)

## 프로덕션 빌드

```bash
# 메인 앱 + 자가 업데이터 두 개 빌드
python -m PyInstaller --clean main.spec      # → dist/main.exe (~73MB)
python -m PyInstaller --clean updater.spec   # → dist/updater.exe (~6MB)
```

배포 시 두 .exe를 같은 폴더에 둬야 자동 업데이트가 동작합니다. 빌드 시
`dist/main.exe`가 실행 중이면 PermissionError가 발생 — 종료 후 재실행하세요.

## 릴리스 ([release.ps1](release.ps1))

로컬에서 한 줄로 빌드 → 태그 push → Gitea Release 생성 → 자산 업로드까지:

```powershell
# 최초 1회: PAT 환경변수 등록
[Environment]::SetEnvironmentVariable('GITEA_TOKEN', 'your_pat', 'User')

# 릴리스 실행
.\release.ps1 v2.2.0
```

스크립트 동작:
1. `core/version.py` 업데이트
2. pytest + 통합 테스트 실행
3. main.exe + updater.exe 빌드
4. ZIP 패키징
5. git commit + tag + push
6. Gitea API로 Release 생성 (CHANGELOG.md에서 노트 자동 추출)
7. 두 .exe + ZIP을 Release 자산으로 업로드

옵션:
- `--SkipTests`: 테스트 건너뛰기 (긴급 핫픽스)
- `--DryRun`: 실제 push/release 없이 미리보기

PAT 발급: Gitea → Settings → Applications → Generate New Token (권한: `repository: Read and Write`).

## 주의사항

### 관리자 권한
일부 Windows 이벤트 로그 접근 시 관리자 권한이 필요할 수 있습니다.
자동 감지 실패 시 수동으로 출근시간 입력 가능.

### 디버그 로그
`CLOCKOUT_DEBUG=1` 환경변수 설정 시 `~/.clockout_logs/debug.log`에 진단 로그가 기록됩니다.

## 문제 해결

### Q. 프로그램이 실행되지 않아요
A: `pip install -r requirements.txt` 로 모든 패키지 설치 확인.

### Q. 출근시간이 자동으로 감지되지 않아요
A: 관리자 권한으로 실행하거나, 메인 화면 출근시각 옆 편집 아이콘으로 수동 입력.

### Q. 단축근무인데 7시간 30분 설정이 안 돼요
A: 설정 → 근무 시간 → 근무 패턴에서 프리셋 선택 또는 시·분 직접 입력 (5분 단위).

### Q. 데이터가 사라졌어요
A: `~/.clockout_backups/` 에서 가장 최근 백업을 `database.db` 로 복사.

### Q. 영어로 사용하고 싶어요
A: 설정 → 알림 및 표시 → 언어/Language 콤보에서 English 선택 → 저장 → 재시작.

## 개발자 정보

- Version: 2.0.0
- Tech Stack: Python 3.9+, PyQt5, SQLite, pywin32, matplotlib
- 라이선스: 개인 및 상업적 사용 가능