Clock_out_Time_Calculator/INSTALL.md

설치 가이드

일반 사용자 — 빌드된 .exe로 설치 (권장)

소스 빌드 없이 즉시 사용하려면 Gitea Releases에서 받으세요.

1. https://kindnick-git.duckdns.org/kindnick/Clock_out_Time_Calculator/releases
2. 최신 릴리스의 main.exe (단일 파일) 다운로드
3. 원하는 폴더에 두고 더블클릭으로 실행
4. 첫 실행 시 5단계 온보딩 위저드가 안내

main.exe 안에 updater.exe가 내장되어 있어 첫 실행 시 같은 폴더로 자동 추출됩니다. 이후 새 버전이 올라오면 앱이 알림 → 동의 → 자동 다운로드·교체·재시작합니다.

옵션: 직접 실행하지 않고 ZIP을 받으면 main.exe + updater.exe가 같이 들어 있습니다.

개발자 — 소스에서 실행

1. Python 설치

Python 3.9 이상이 필요합니다.

Windows

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

확인:

python --version

2. 프로젝트 다운로드

git clone https://kindnick-git.duckdns.org/kindnick/Clock_out_Time_Calculator.git
cd Clock_out_Time_Calculator

또는 ZIP을 받아 압축 해제.

3. 패키지 설치

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

pip install -r requirements.txt

설치되는 패키지 (requirements.txt)

1. PyQt5 — GUI 프레임워크
2. pywin32 — Windows API (이벤트 뷰어, 화면 잠금 감지)
3. python-dateutil — 날짜 계산
4. matplotlib — 통계 차트
5. plyer — 시스템 알림
6. holidays — 한국 공휴일 자동 등록 (음력 명절 포함)

4. 실행

python main.py

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

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

1. 방법 1: cmd를 관리자 권한으로 실행

   • Windows 키 + X → "터미널(관리자)" 또는 "PowerShell(관리자)"
   • 프로젝트 폴더로 이동: cd "경로"
   • python main.py 실행

2. 방법 2: 바로가기 생성

   • python main.py를 실행하는 배치 파일(.bat) 생성
   • 우클릭 → 속성 → 고급 → "관리자 권한으로 실행" 체크

5. 첫 실행

1. 실행 시 자동으로 데이터베이스(database.db) 생성
2. 5단계 온보딩 위저드 표시
   • 환영 → 근무패턴 → 출근 자동 감지 → 연차/시급 → Discord 웹훅(옵션)
3. 위저드 완료 후 메인 화면 진입
4. 이후 실행에서는 위저드 없이 바로 시작

6. 단축근무자 설정 (예: 7시간 30분)

온보딩에서 미설정한 경우:

1. 설정(Ctrl+,) → 근무 시간 → 근무 패턴
2. "단축근무 7시간 30분 (점심 30분)" 또는 사용자 정의 선택
3. 시·분 직접 입력 가능 (5분 단위)
4. 저장 → 즉시 메인 화면 반영

클라우드 동기화 (여러 PC 공용)

OneDrive / Dropbox 폴더에 DB를 두면 자동 동기화됩니다 (WAL 모드).

1. OneDrive/Dropbox 안에 database.db 위치 결정
2. 설정 → 데이터 관리 → DB 경로 → 변경
3. 기존 DB를 새 위치로 복사 → 재시작
4. 다른 PC에서도 같은 경로 지정하면 데이터 공유

환경 변수

변수	용도
CLOCKOUT_DEBUG=1	~/.clockout_logs/debug.log에 디버그 로그 출력
CLOCKOUT_DEBUG_DIR=경로	로그 저장 위치 변경
GITEA_TOKEN	릴리스 발행 시 PAT (개발자용)
CODE_SIGN_CERT / CODE_SIGN_PASS	Authenticode 인증서 경로/암호 (개발자용)

문제 해결

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

이벤트 뷰어 접근 불가

• 관리자 권한으로 실행
• 또는 메인 화면 출근시각 옆 ✏️ 버튼으로 수동 입력

Discord 웹훅 "실패" 표시

• v2.3.3 이전 버전에서 발생 — Cloudflare가 Python User-Agent 차단
• 최신 버전으로 업데이트하면 해결 (브라우저 UA로 우회)

온보딩 위저드를 다시 보고 싶음

• 도움말(F1) → "🚀 온보딩 다시 보기"

업그레이드

.exe 사용자

• 앱이 자동 감지 → 알림 → 동의 → 자동 처리
• 수동 트리거: F5 또는 설정 → 데이터 관리 → "업데이트 확인"

소스 사용자

git pull
pip install --upgrade -r requirements.txt

제거

1. 프로젝트 폴더 삭제 (main.exe 또는 소스)
2. 데이터 보존하려면 database.db만 별도 백업
3. 자동 백업: ~/.clockout_backups/ 에 7개 회전 보관 (필요 시 삭제)

프로덕션 빌드 (PyInstaller)

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

# 자가 업데이터 먼저 빌드 (main.spec이 데이터로 임베드)
python -m PyInstaller --clean updater.spec   # → dist/updater.exe (~6MB)

# updater.exe를 staging 폴더로 복사 (main.spec --clean 시 보호)
mkdir -p build/staging
cp dist/updater.exe build/staging/

# 메인 앱 빌드 (updater.exe 임베드 포함)
python -m PyInstaller --clean main.spec      # → dist/main.exe (~78MB)

또는 release.ps1 한 번 실행으로 전체 자동화.

빌드 시 주의:

• dist/main.exe가 실행 중이면 PermissionError 발생 → 종료 후 재실행
• holidays 등 옵셔널 패키지는 설치된 환경에서 빌드해야 포함됨
• main.exe 단일 배포가 가능 (updater.exe는 첫 실행 시 자동 추출)

다음 단계

설치가 완료되었다면 README.md 와 도움말(F1)을 참고하세요. 개발자는 CLAUDE.md + AGENTS.md 도 함께 읽으세요.