CI / test (push) Has been cancelled

Details

핵심 기능:
- 단축근무·표준·반일 등 다양한 근무 패턴 (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>

2026-04-30 12:54:40 +09:00

4.2 KiB

Raw Blame History

설치 가이드

1. Python 설치

Python 3.9 이상이 필요합니다.

Windows

https://www.python.org/downloads/ 방문
"Download Python 3.x.x" 클릭
설치 시 "Add Python to PATH" 체크 필수!

확인:

python --version

2. 프로젝트 다운로드

프로젝트를 다운로드하거나 압축을 해제합니다.

3. 패키지 설치

프로젝트 폴더에서 명령 프롬프트(cmd) 또는 PowerShell을 엽니다.

pip install -r requirements.txt

설치되는 패키지:

PyQt5 - GUI 프레임워크
pywin32 - Windows API 접근
python-dateutil - 날짜 계산
matplotlib - 그래프
plyer - 알림 시스템
holidays - 한국 공휴일 자동 등록 (음력 명절 포함)

4. 리소스 다운로드 (선택)

리소스가 없어도 프로그램은 작동하지만, 더 예쁜 UI를 위해 다운로드를 권장합니다.

python download_resources.py

이 스크립트는 무료 리소스 다운로드 링크를 안내합니다.

수동 다운로드:

아이콘

다음 사이트에서 다운로드:

Flaticon: https://www.flaticon.com/
Material Design Icons: https://materialdesignicons.com/
Icons8: https://icons8.com/

다운로드 후 resources/icons/ 폴더에 저장

필요한 아이콘:

app_icon.ico (512x512)
clock.png, timer.png, lunch.png
calendar.png, statistics.png, vacation.png
settings.png, notification.png

사운드

다음 사이트에서 다운로드:

Mixkit: https://mixkit.co/free-sound-effects/ (추천)
Freesound: https://freesound.org/
Zapsplat: https://www.zapsplat.com/

다운로드 후 resources/sounds/ 폴더에 저장

필요한 사운드:

clock_out_alarm.wav - 퇴근시간 알림
notification.wav - 일반 알림
success.wav - 성공 효과음

5. 실행

python main.py

관리자 권한으로 실행 (권장)

Windows 이벤트 뷰어 접근을 위해 관리자 권한이 필요할 수 있습니다.

방법 1: cmd를 관리자 권한으로 실행
- Windows 키 + X
- "명령 프롬프트(관리자)" 또는 "Windows PowerShell(관리자)" 선택
- 프로젝트 폴더로 이동: cd "경로"
- python main.py 실행
방법 2: 바로가기 생성
- python main.py를 실행하는 배치 파일(.bat) 생성
- 우클릭 → 속성 → 고급 → "관리자 권한으로 실행" 체크

6. 첫 실행

프로그램이 실행되면 자동으로 데이터베이스(database.db) 생성
Windows 이벤트 뷰어에서 오늘의 부팅 시간 자동 감지
감지된 시간이 출근시간으로 설정됨

문제 해결

pywin32 설치 오류

pip install --upgrade pywin32
python -m pywin32_postinstall -install

PyQt5 설치 오류

pip install --upgrade pip
pip install PyQt5

"DLL load failed" 오류

Visual C++ Redistributable 설치 필요: https://aka.ms/vs/17/release/vc_redist.x64.exe

이벤트 뷰어 접근 불가

관리자 권한으로 실행
또는 설정에서 수동 입력 모드 사용

업그레이드

pip install --upgrade -r requirements.txt

제거

프로젝트 폴더 삭제
패키지 제거 (선택):

pip uninstall PyQt5 pywin32 python-dateutil pandas matplotlib plyer

프로덕션 빌드 (PyInstaller)

소스 없이 실행 파일만 배포하려면:

python -m PyInstaller --clean main.spec      # → dist/main.exe (~73MB)
python -m PyInstaller --clean updater.spec   # → dist/updater.exe (~6MB, 자가 업데이터)

배포 패키지에는 두 .exe를 함께 포함시켜 같은 폴더에 두세요. 자동 업데이트는 main.exe가 같은 폴더의 updater.exe를 호출해야 동작합니다.

빌드 시 주의:

dist/main.exe가 실행 중이면 PermissionError 발생 → 종료 후 재실행
holidays 등 옵셔널 패키지는 설치된 환경에서 빌드해야 포함됨

환경 변수

CLOCKOUT_DEBUG=1 — 디버그 로그를 ~/.clockout_logs/debug.log로 출력
CLOCKOUT_DEBUG_DIR=경로 — 로그 저장 위치 변경

다음 단계

설치가 완료되었다면 README.md를 참고하여 프로그램을 사용하세요!

4.2 KiB Raw Blame History