# 개발 단계 가이드

> 작업 위치: MacBook Pro `~/Documents/code/hyungi_Document_Server/`
> 개발/배포: MacBook Pro (Claude Code) → Gitea push → 서버에서 pull
> 설계 원본: `docs/architecture.md`

---

## Phase 0: 기반 구축 (1~2주)

### 산출물
- `docker compose up -d` → postgres, fastapi, kordoc, caddy 구동
- DB 스키마 자동 생성 (`migrations/001_initial_schema.sql`)
- JWT + TOTP 인증 작동 (로그인, 토큰 갱신)
- NAS SMB 마운트 검증 (Docker 컨테이너에서 `/documents` 읽기/쓰기)
- `config.yaml` 로딩 검증

### 핵심 파일
- `app/main.py` — FastAPI 앱 엔트리포인트 + lifespan + APScheduler
- `app/core/config.py` — Pydantic settings (config.yaml + credentials.env 로딩)
- `app/core/database.py` — SQLAlchemy async engine + session factory
- `app/core/auth.py` — JWT 발급/검증 + TOTP 2FA
- `migrations/001_initial_schema.sql` — documents, tasks, processing_queue 테이블

### 완료 기준
- [ ] `curl localhost:8000/docs` → OpenAPI 문서 반환
- [ ] 로그인 플로우 성공 (JWT 발급 + TOTP 검증)
- [ ] `psql`로 DB 테이블 3개 존재 확인 (documents, tasks, processing_queue)
- [ ] Docker 컨테이너에서 NAS 파일 읽기/쓰기 정상

---

## Phase 1: 데이터 마이그레이션 (1~2주)

### 산출물
- `scripts/migrate_from_devonthink.py` — DEVONthink → NAS 폴더 구조 생성 + 파일 이동 + DB 등록
- kordoc-service 컨테이너 구동, 텍스트 추출 작동
- 배치: 전 문서 텍스트 추출 → AI 분류 → 벡터 임베딩

### 핵심 파일
- `scripts/migrate_from_devonthink.py` — 마이그레이션 스크립트
- `services/kordoc/server.js` — HWP/PDF 파싱 HTTP API
- `app/workers/extract_worker.py` — kordoc 호출, DB에 extracted_text 저장
- `app/workers/classify_worker.py` — MLX로 AI 분류/태그/요약
- `app/workers/embed_worker.py` — GPU 서버로 벡터 임베딩

### 완료 기준
- [ ] PostgreSQL 문서 수 = DEVONthink 문서 수
- [ ] 텍스트 추출 성공률 >95%
- [ ] 20건 분류 spot-check 통과 (도메인, 태그 정확도)
- [ ] 벡터 임베딩 정상 생성 (embedding 컬럼 NOT NULL 비율)

---

## Phase 2: 핵심 기능 (2~3주)

### 산출물
- 문서 CRUD API (`/api/documents/`)
- 전문검색 + 벡터검색 API (`/api/search/`)
- 문서 뷰어: PDF(pdf.js), Markdown, Synology Office iframe, HWP(kordoc Markdown)
- Inbox 자동분류 파이프라인 (감지→추출→분류→임베딩→폴더 이동)
- 파일 변경 감지 (해시 비교 → 재가공)

### 핵심 파일
- `app/api/documents.py` — 문서 CRUD
- `app/api/search.py` — GIN/pg_trgm + pgvector 검색
- `app/workers/file_watcher.py` — NAS 파일 변경 감지
- `frontend/src/routes/documents/+page.svelte` — 문서 탐색
- `frontend/src/lib/components/DocumentViewer.svelte` — 포맷별 뷰어

### 완료 기준
- [ ] 검색 API가 ranked 결과 반환
- [ ] Inbox에 파일 업로드 → 자동 분류 + Knowledge 폴더 이동 확인
- [ ] PDF, Markdown, HWP 뷰어 정상 렌더링
- [ ] 파일 수정 후 해시 변경 감지 → 재가공 큐 등록

---

## Phase 3: 자동화 이전 (1~2주)

### 산출물
- `app/workers/law_monitor.py` — 법령 변경 → NAS 저장 + DB 등록 + CalDAV 태스크
- `app/workers/mailplus_archive.py` — IMAP 수집 → NAS 저장 + DB 등록 + SMTP 알림
- `app/workers/daily_digest.py` — PostgreSQL/CalDAV 쿼리 → Markdown 생성 + SMTP 발송
- APScheduler 스케줄 등록 (07:00, 07:00+18:00, 20:00)
- CalDAV 태스크 연동 (Synology Calendar)

### v1→v2 코드 재활용
v1 코드 참조: `git show v1-final:scripts/<파일명>`

| v1 | v2 | 변경 |
|-----|-----|------|
| `scripts/law_monitor.py` | `app/workers/law_monitor.py` | `import_to_devonthink()` → `save_to_nas()` + `register_in_db()` + `create_caldav_task()` |
| `scripts/mailplus_archive.py` | `app/workers/mailplus_archive.py` | `import_to_devonthink()` → `save_to_nas()` + `register_in_db()` + `send_smtp_notification()` |
| `scripts/pkm_daily_digest.py` | `app/workers/daily_digest.py` | DEVONthink/OmniFocus 쿼리 → PostgreSQL/CalDAV 쿼리 |
| `scripts/pkm_utils.py` | `app/core/utils.py` | `run_applescript*()` 제거, 나머지 유지 |

### 완료 기준
- [ ] 법령 모니터 실행 → NAS 파일 + DB 레코드 + CalDAV VTODO 생성
- [ ] 이메일 수집 → NAS 저장 + DB 등록 정상
- [ ] 다이제스트 → Markdown 생성 + SMTP 발송 확인
- [ ] APScheduler 스케줄 3개 정상 등록 확인

---

## Phase 4: UI 완성 (2~3주)

### 산출물
- 대시보드 위젯: 오늘 할일, Inbox 미분류, 법령 알림, 최근 문서, 시스템 상태
- 태그/폴더 탐색 사이드바
- 메타데이터 패널 (AI 요약, pgvector 관련 문서 5건, 가공 이력)
- Inbox 분류 UI (수동 오버라이드 + 배치 승인)
- 반응형 모바일 대응
- 내보내기 API (Markdown → DOCX/HWPX via kordoc)

### 핵심 파일
- `app/api/dashboard.py`, `tasks.py`, `export.py`
- `frontend/src/lib/components/Sidebar.svelte`, `MetadataPanel.svelte`, `TaskWidget.svelte`
- `frontend/src/routes/inbox/+page.svelte`
- `frontend/src/routes/settings/+page.svelte`

### 완료 기준
- [ ] 전체 워크플로우: 로그인 → 대시보드 → 검색 → 문서 조회 → 태스크 → Inbox 분류
- [ ] 모바일 브라우저에서 정상 표시
- [ ] 내보내기 API로 DOCX 생성 확인

---

## Phase 5: DEVONthink 퇴역 (2주)

### 산출물
- 2주간 v1+v2 병행 운영
- 비교 리포트: 문서 수, 검색 품질, 자동화 안정성
- Mac mini: main 브랜치 전환 + `docker compose up -d`
- 기존 launchd plist 해제 (`launchctl unload`)
- DEVONthink DB 종료
- NAS `Document_Server/DEVONThink/` 아카이브

### 완료 기준
- [ ] Mac mini `docker compose up -d` 후 전체 기능 정상
- [ ] DEVONthink 없이 1주 운영 안정
- [ ] 모든 자동화(법령, 이메일, 다이제스트) 정상 실행
