# task-651.1 완료 보고서: 파일 자동 정리 시스템 구축

## SCQA

**S**: 시스템 운영 중 cokacdir 업로드 파일, .done.clear 이벤트, dispatch 지시서, 시스템 로그가 누적되어 디스크 공간을 점유하고 있다.

**C**: 자동 정리 메커니즘이 없어 수동 관리가 필요하며, 불필요한 임시 파일이 무한히 쌓이는 구조이다.

**Q**: 안전장치를 갖춘 자동 정리 시스템을 구축하여 불필요한 파일 누적을 방지할 수 있는가?

**A**: 4가지 카테고리별 자동 정리 스크립트(file-cleanup.py)를 TDD 방식으로 구현 완료. dry-run 기본 모드, 삭제 금지 리스트, 최소 보존 규칙 등 안전장치 적용. pytest 52건 전체 통과, pyright 에러 0건.

## 작업 내용

### 생성 파일
- `/home/jay/workspace/scripts/file-cleanup.py` — 메인 스크립트 (697줄)
- `/home/jay/workspace/scripts/file_cleanup.py` — import용 복사본 (동일 내용)
- `/home/jay/workspace/scripts/tests/test_file_cleanup.py` — 테스트 (52건)
- `/home/jay/workspace/scripts/run-file-cleanup.sh` — cron 래퍼 스크립트
- `/home/jay/workspace/uploads/` — 업로드 파일 보관 디렉토리 (신규 생성)

### 구현된 기능
1. **cokacdir 업로드 파일 정리** (30일 초과 PDF/PNG/JPG/JPEG)
2. **.done.clear 이벤트 정리** (30일 초과)
3. **dispatch 지시서 정리** (90일 초과)
4. **시스템 로그 정리** (60일 초과, 활성 로그 보존)
5. **--report 모드**: 디스크 사용량(전체/사용/여유 MB) + 정리 가능 용량
6. **--organize 모드**: cokacdir 파일을 uploads/YYYY-MM/로 이동
7. **dry-run 기본**: --execute 없이는 절대 삭제/이동 안 함

### 안전장치
- 삭제 금지 리스트: reports, research, specs, meetings, plans, CLAUDE.md, MEMORY.md, .env, .env.keys
- 카테고리별 최소 1개 파일 보존 (전체 삭제 방지)
- 프로젝트 폴더(/home/jay/projects/) 미접근
- git 관련 파일(.git, .worktrees) 미접근
- 삭제 로그 기록 → /home/jay/workspace/logs/file-cleanup.log

## 팀원 기여
- **토르(백엔드)**: file-cleanup.py 메인 구현 + 테스트 52건 작성 (TDD)
- **헤임달(테스터)**: run-file-cleanup.sh 래퍼 생성 + 통합 검증 5종

## 테스트 결과
- pytest: **52 passed, 0 failed** (0.27s)
- pyright: **0 errors, 0 warnings, 0 informations**
- dry-run 실행: 4개 카테고리 정상 출력, 실제 삭제 0건
- --report 실행: 디스크 전체 100,220MB / 사용 56,572MB / 여유 38,512MB 정상 출력
- --organize 실행: cokacdir 미디어 파일 이동 대상 정상 감지 (dry-run)
- 보호 파일 안전: 삭제 금지 대상 미포함 확인

## 발견 이슈 및 해결

### 자체 해결 (1건)
1. **경계값 비교 오차** — 정수 일수 비교(`int(days_old)`)로 수정하여 float 미세 오차 해소
   - 상세: `time.time()` 호출 시 ~0.00001초 차이로 정확히 30일인 파일이 삭제 대상에 포함되는 문제. `int(days_old) <= threshold` 비교로 안정화.

### 범위 외 미해결 (0건)
없음.

## cron 등록 안내
매일 새벽 3시 자동 실행 등록 시:
```
cokacdir --cron "파일 자동 정리 실행: bash /home/jay/workspace/scripts/run-file-cleanup.sh" --at "0 3 * * *" --chat CHAT_ID --key KEY
```

## QC 자동 검증
- **overall**: PASS (7 PASS, 3 SKIP)
- file_check: PASS (4/4 파일 확인)
- data_integrity: PASS
- test_runner: PASS (951 passed, 0 failed, 12.81s)
- tdd_check: PASS (테스트 + 구현 파일 존재 확인)
- pyright_check: PASS (0 errors)
- style_check: PASS (black OK, isort OK)
- .done 파일: 자동 생성 완료