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+

설치 단계

# 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개 회전)

프로덕션 빌드

# 메인 앱 + 자가 업데이터 두 개 빌드
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)

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

# 최초 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
• 라이선스: 개인 및 상업적 사용 가능