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>
192 lines
6.8 KiB
Markdown
192 lines
6.8 KiB
Markdown
# 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 차트
|
|
- 일별 근무시간 + 연장 누적 막대 그래프
|
|
- 요일별 평균 근무시간
|
|
- 근무 패턴 인사이트 (정적 통계 요약)
|
|
|
|
### 8. 공휴일 관리
|
|
- 한국 공휴일 자동 등록 (`holidays` 패키지)
|
|
- 양력 + **음력 명절(설날/추석/석가탄신일)** + 임시공휴일
|
|
- 사용자 정의 공휴일 직접 추가
|
|
- 공휴일 근무 시 모든 시간 연장근무 적립
|
|
|
|
### 9. 미니 위젯 + 시스템 트레이
|
|
- Always-on-top 미니 위젯으로 남은 시간 큰 글씨 표시
|
|
- 트레이 메뉴에서 빠른 점심/외출/퇴근/통계/캘린더 접근
|
|
|
|
### 10. 데이터 신뢰성
|
|
- **DB 자동 백업** — 1일 1회 `~/.clockout_backups/`에 회전 (최신 7개 보관)
|
|
- **클라우드 동기화** — DB 경로를 OneDrive/Dropbox 폴더로 변경 가능
|
|
- 마이그레이션 sentinel로 1회 실행 보장
|
|
|
|
### 11. 자동 업데이트
|
|
- 시작 시 백그라운드 버전 체크 (Gitea Releases API)
|
|
- 새 버전 발견 시 알림 + 사용자 동의 후 자동 다운로드·교체·재시작
|
|
- F5 또는 설정 → 데이터 관리 → "업데이트 확인" 으로 수동 트리거
|
|
- 실패 시 자동 롤백
|
|
|
|
### 12. 다국어 지원 (i18n)
|
|
- 한국어 / English 전환
|
|
- 알림 메시지·UI 라벨 28개 카테고리
|
|
- HelpView 6개 탭 ko/en HTML 콘텐츠
|
|
|
|
### 13. 단축키
|
|
- `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가 발생 — 종료 후 재실행하세요.
|
|
|
|
## 릴리스 (Gitea Actions)
|
|
|
|
태그 push로 자동 릴리스:
|
|
```bash
|
|
# version.py 업데이트 후
|
|
git tag v2.2.0
|
|
git push origin v2.2.0
|
|
```
|
|
|
|
[.gitea/workflows/release.yml](.gitea/workflows/release.yml)이 자동으로:
|
|
1. 단위/통합 테스트 실행
|
|
2. main.exe + updater.exe 빌드
|
|
3. ZIP 패키징
|
|
4. Gitea Releases에 첨부
|
|
|
|
⚠️ Gitea Actions 활성화 + `RELEASE_TOKEN` secret(저장소 쓰기 권한) 등록 필요.
|
|
|
|
## 주의사항
|
|
|
|
### 관리자 권한
|
|
일부 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
|
|
- 라이선스: 개인 및 상업적 사용 가능
|