c98ca361cd
Phase 1 \u2014 \ubbf8\ub9ac \uc5f0\ucc28 \ub4f1\ub85d
- DB: get_leave_minutes_for(date) / has_full_day_leave(date) /
get_leave_records_by_date(date) / get_leave_records_by_range(start, end)
- TimeCalculator.effective_work_minutes(date_obj, db): \uc5f0\ucc28 \ubd84\ub9cc\ud07c \uc815\uaddc \uadfc\ubb34 \ucc28\uac10
- update_display() 1Hz hot-path:
\u2022 \uc885\uc77c \uc5f0\ucc28 \ub4f1\ub85d\uc77c + \ucd9c\uadfc \uc548 \ud55c \uc0c1\ud0dc \u2192 "\ud83c\udf34 \uc624\ub298\uc740 \ud734\uac00" \uce74\ub4dc \ud45c\uc2dc, \uce74\uc6b4\ud2b8\ub2e4\uc6b4 \uc81c\uac70
\u2022 \uc885\uc77c \uc5f0\ucc28 + \ucd9c\uadfc override \u2192 \ud734\uc77c\ucc98\ub7fc \uc804\uccb4 \uc801\ub9bd
\u2022 \ubd80\ubd84 \uc5f0\ucc28(\ubc18\ucc28/\uc2dc\uac04) \u2192 leave_used_today \uacbd\ub85c\ub85c \uae30\uc874 \ub2e8\ucd95 \uacc4\uc0b0 \uc720\uc9c0
- \uc790\ub3d9 \ucd9c\uadfc\uac10\uc9c0 \uac00\ub4dc: load_today_data\uc5d0\uc11c \uc885\uc77c \uc5f0\ucc28\uc77c\uc774\uba74 event_monitor \ud638\ucd9c \uc790\uccb4 \uc2a4\ud0b5
- \uc218\ub3d9 \ucd9c\uadfc \uac00\ub4dc: manual_clock_in\uc5d0\uc11c \uc885\uc77c \uc5f0\ucc28\uc77c \ud655\uc778 \ud504\ub86c\ud504\ud2b8
- AddLeaveDialog \uac80\uc99d \uac15\ud654:
\u2022 \ubbf8\ub798 1\ub144\uae4c\uc9c0 setMaximumDate
\u2022 \uc8fc\ub9d0/\uacf5\ud734\uc77c \ub4f1\ub85d \ucc28\ub2e8 (\uc774\ubbf8 \ube44\uadfc\ubb34\uc77c)
\u2022 \uac19\uc740 \ub0a0 1\uc77c \ucd08\uacfc \ub204\uc801 \ucc28\ub2e8
- leave_calendar_view: \uc608\uc815(\ud30c\ub791) / \uc0ac\uc6a9\uc644\ub8cc(\ub179/\ub178/\ubcf4) \uc0c9\uc0c1 \ubd84\ub9ac
Phase 2 \u2014 \ud1b5\ud569 \uc2a4\ucf00\uc904 + \ubc18\ubcf5 \uc5f0\ucc28
- recurring_leaves \ud14c\uc774\ube14 (pattern/leave_type/days/start/end/memo)
- core/recurring_leaves.py: weekly / biweekly / monthly \ud328\ud134 \ud30c\uc11c + expand_for_range/date
- get_leave_minutes_for() / has_full_day_leave()\uac00 \ubc18\ubcf5 \ud328\ud134\ub3c4 \ud568\uaed8 \ud569\uc0b0
- ui/recurring_leave_dialog.py: \ub9e4\uc8fc/\uaca9\uc8fc/\ub9e4\uc6d4 \uc785\ub825 + \uc785\ub825 \ub9ac\uc2a4\ud2b8 \uad00\ub9ac
- ui/schedule_view.py: \uc6d4\uac04 \uc2a4\ud50c\ub9ac\ud130 \ub808\uc774\uc544\uc6c3 (\uce98\ub9b0\ub354 + \uc0c1\uc138)
\u2022 \ud734\uc77c(\ube68\uac15) / \uc5f0\ucc28 \uc0ac\uc6a9(\ub179\u30fb\ub178\u30fb\ubcf4) / \uc608\uc815(\ud30c\ub791) / \ubc18\ubcf5(\ud68c\uc0c9) \uc0c9 \ucf54\ub4dc
\u2022 \ub0a0\uc9dc \ud074\ub9ad \u2192 \uc0c1\uc138 \ud328\ub110 (\ub3d9\uc77c\uc77c\uc790 \uad6c\uccb4 \uc5f0\ucc28 + \ubc18\ubcf5 \ub9e4\uce58)
\u2022 \ub9ac\uc2a4\ud2b8 \uc6b0\ud074\ub9ad \uc0ad\uc81c (\uad6c\uccb4 / \ubc18\ubcf5 \uad6c\ubd84)
\u2022 \uc6d4 \ubcc0\uacbd \uc2dc \uc790\ub3d9 reload
- \uc9c4\uc785\uc810: main_window.show_schedule(), tray menu '\ud83d\uddd3\ufe0f \uc2a4\ucf00\uc904', LeaveView '\ud83d\uddd3\ufe0f \uc2a4\ucf00\uc904' \ubc84\ud2bc
Tests
- tests/test_recurring_leaves.py 32\uac1c (\ud328\ud134 \ud30c\uc2f1 / \ub9e4\uce6d / expand / describe)
- tests/test_database.py +12 (TestLeaveQueriesByDate + TestRecurringLeavesDB)
- _integration_test.py +4 (S52B-S52E)
- pytest: 122 \u2192 175 \uc804\ubd80 green
- \ud1b5\ud569: 49 \u2192 53 \uc804\ubd80 green
- UI-5/UI-7 \uae30\uc874 \uace0\uc7a5 (v2.8.0 \ub514\uc790\uc778 \ub9ac\ub274\uc5bc \ub9c8\ub108)
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 — 공휴일 자동 등록 (음력 포함)
사용 방법
첫 실행
- 실행 시 오늘의 부팅 시간을 자동 감지하여 출근으로 기록
- 설정 → 근무 시간 에서 본인 근무 패턴 선택 (단축근무자는 프리셋에서)
- 설정 → 휴가 → 연간 연차 에서 본인 연차 일수 입력
단축근무 사용자 (예: 7시간 30분 + 점심 30분)
- 설정 → 근무 시간 → 근무 패턴 에서 "단축근무 7시간 30분 (점심 30분)" 선택
- 또는 사용자 정의로 시간/분 직접 입력 (5분 단위)
- 저장 → 즉시 메인 화면 반영
클라우드 동기화 (여러 PC)
- OneDrive/Dropbox 폴더 안에
database.db위치 결정 - 설정 → 데이터 관리 → DB 경로 → 변경
- 기존 DB 파일을 새 위치로 복사 → 재시작
- 다른 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
스크립트 동작:
core/version.py업데이트- pytest + 통합 테스트 실행
- main.exe + updater.exe 빌드
- ZIP 패키징
- git commit + tag + push
- Gitea API로 Release 생성 (CHANGELOG.md에서 노트 자동 추출)
- 두 .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
- 라이선스: 개인 및 상업적 사용 가능