docs: rewrite all documentation for v2 architecture

- CLAUDE.md: FastAPI + Docker 기반으로 전면 재작성
- README.md: v2 기술 스택 및 Quick Start
- deploy.md: Docker Compose 배포 가이드 (launchd 제거)
- development-stages.md: Phase 0~5 개발 단계 (claude-code-commands.md 대체)
- architecture-v2.md → architecture.md 승격

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -1,137 +1,154 @@
-# DEVONThink PKM 시스템 — Claude Code 작업 가이드
+# hyungi_Document_Server — Claude Code 작업 가이드
 
 ## 프로젝트 개요
 
-Mac mini M4 Pro(64GB, 4TB) 기반 개인 지식관리(PKM) 시스템.
-DEVONthink 4를 중앙 허브로, Ollama AI 자동 분류 + 법령 모니터링 + 일일 다이제스트를 자동화한다.
+Self-hosted PKM(Personal Knowledge Management) 웹 애플리케이션.
+FastAPI + PostgreSQL(pgvector) + SvelteKit + Docker Compose 기반.
+Mac mini M4 Pro를 애플리케이션 서버, Synology NAS를 파일 저장소, GPU 서버를 AI 추론에 사용한다.
 
-## 핵심 문서 (반드시 먼저 읽을 것)
+## 핵심 문서
 
-1. `docs/architecture.md` — 전체 시스템 아키텍처 (DB 구조, 태그, AI, 자동화 전체)
-2. `docs/industrial-safety-blueprint.md` — 04_Industrial Safety DB 상세 설계
-3. `docs/claude-code-commands.md` — 단계별 작업 지시서
+1. `docs/architecture.md` — 전체 시스템 아키텍처 (DB 스키마, AI 전략, 인프라, UI 설계)
+2. `docs/deploy.md` — Docker Compose 배포 가이드
+3. `docs/development-stages.md` — Phase 0~5 개발 단계별 가이드
+
+## 기술 스택
+
+| 영역 | 기술 |
+|------|------|
+| 백엔드 | FastAPI (Python 3.11+) |
+| 데이터베이스 | PostgreSQL 16 + pgvector + pg_trgm |
+| 프론트엔드 | SvelteKit |
+| 문서 파싱 | kordoc (Node.js, HWP/HWPX/PDF → Markdown) |
+| 리버스 프록시 | Caddy (자동 HTTPS) |
+| 인증 | JWT + TOTP 2FA |
+| 컨테이너 | Docker Compose |
 
 ## 네트워크 환경
 
 ```
-Mac mini (운영 서버):
-  - Ollama: http://localhost:11434
-  - DEVONthink: 로컬 실행 중
-  - OmniFocus: 로컬 실행 중
+Mac mini M4 Pro (애플리케이션 서버):
+  - Docker Compose: FastAPI(:8000), PostgreSQL(:5432), kordoc(:3100), Caddy(:80,:443)
+  - MLX Server: http://localhost:8800/v1/chat/completions (Qwen3.5-35B-A3B)
+  - 외부 접근: pkm.hyungi.net (Caddy 프록시)
 
 Synology NAS (DS1525+):
   - 도메인: ds1525.hyungi.net
   - Tailscale IP: 100.101.79.37
   - 포트: 15001
-  - WebDAV: webdav.hyungi.net/Document_Server/DEVONThink/
-  - MailPlus IMAP: mailplus.hyungi.net:993 (SSL)
+  - 파일 원본: /volume4/Document_Server/PKM/
+  - Synology Office: 문서 편집/미리보기
+  - Synology Calendar: CalDAV 태스크 관리 (OmniFocus 대체)
+  - MailPlus: IMAP(993) + SMTP(465)
 
 GPU 서버 (RTX 4070 Ti Super):
-  - 역할: 임베딩(nomic-embed-text), 비전(Qwen2.5-VL-7B), 리랭킹(bge-reranker)
-  - Tailscale IP: 별도 확인 필요
-
-TKSafety: tksafety.technicalkorea.net (설정만, 나중에 활성화)
+  - AI Gateway: http://gpu-server:8080 (모델 라우팅, 폴백, 비용 제어)
+  - nomic-embed-text: 벡터 임베딩
+  - Qwen2.5-VL-7B: 이미지/도면 OCR
+  - bge-reranker-v2-m3: RAG 리랭킹
 ```
 
 ## 인증 정보
 
-- 위치: `~/.config/pkm/credentials.env`
-- 템플릿: `./credentials.env.example`
-- 스크립트에서 python-dotenv로 로딩
-
-## DEVONthink DB 구조 (13개)
-
-```
-운영 DB (신규 생성 완료):
-  Inbox     — 모든 자료 최초 진입점
-  Archive   — 이메일, 채팅 로그
-  Projects  — 진행 중 프로젝트
-
-도메인 DB (기존, 유지):
-  00_Note_BOX, 01_Philosophie, 02_Language, 03_Engineering,
-  04_Industrial safety, 05_Programming, 07_General Book,
-  97_Production drawing, 99_Reference Data, 99_Technicalkorea
-```
-
-## 커스텀 메타데이터 필드 (DEVONthink에 등록 완료)
-
-```
-omnifocusTaskID  — Single-Line Text — OmniFocus 역링크
-sourceURL        — URL             — 원본 출처
-synologyPath     — Single-Line Text — NAS 원본 경로
-lastAIProcess    — Date            — 마지막 AI 처리 일시
-sourceChannel    — Single-Line Text — 유입 경로 (아래 값 중 하나)
-dataOrigin       — Single-Line Text — work 또는 external
-```
-
-## sourceChannel 값 (유입 경로 추적)
-
-```
-tksafety     — TKSafety API (업무 실적)      → dataOrigin = work
-devonagent   — DEVONagent 자동 수집 (뉴스)    → dataOrigin = external
-law_monitor  — 법령 API (법령 변경)           → dataOrigin = external
-inbox_route  — Inbox → AI 분류               → AI 판별
-email        — MailPlus 이메일               → AI 판별
-web_clip     — Web Clipper 스크랩             → dataOrigin = external
-manual       — 직접 추가                     → dataOrigin = work (기본)
-```
+- 위치: `credentials.env` (프로젝트 루트, .gitignore에 포함)
+- 템플릿: `credentials.env.example`
+- 스크립트에서 python-dotenv 또는 Docker env_file로 로딩
 
 ## AI 모델 구성
 
 ```
-Tier 1 (Mac mini, 상시):
-  mlx-community/Qwen3.5-35B-A3B-4bit — 태그 생성, 문서 분류, 요약
-  → http://localhost:8800/v1/chat/completions (OpenAI 호환 API)
-  → MLX 서버로 실행 중 (Ollama 아님)
+Primary (Mac mini MLX, 상시, 무료):
+  mlx-community/Qwen3.5-35B-A3B-4bit — 분류, 태그, 요약
+  → http://localhost:8800/v1/chat/completions
 
-Tier 2 (Claude API, 필요시):
+Fallback (GPU Ollama, MLX 장애 시):
+  qwen3.5:35b-a3b
+  → http://gpu-server:11434/v1/chat/completions
+
+Premium (Claude API, 종량제, 수동 트리거만):
   claude-sonnet — 복잡한 분석, 장문 처리
-  → CLAUDE_API_KEY 사용
+  → 일일 한도 $5, require_explicit_trigger: true
 
-Tier 3 (GPU 서버, 특수):
-  nomic-embed-text  — 벡터 임베딩
-  Qwen2.5-VL-7B    — 이미지/도면 OCR
-  bge-reranker-v2-m3 — RAG 리랭킹
+Embedding (GPU 서버 전용):
+  nomic-embed-text → 벡터 임베딩
+  Qwen2.5-VL-7B → 이미지/도면 OCR
+  bge-reranker-v2-m3 → RAG 리랭킹
 ```
 
-## 작업 순서
+## 프로젝트 구조
 
-docs/claude-code-commands.md의 단계를 순서대로 진행:
+```
+hyungi_Document_Server/
+├── docker-compose.yml           ← Mac mini용
+├── Caddyfile
+├── config.yaml                  ← AI 엔드포인트, NAS 경로, 스케줄
+├── credentials.env.example
+├── app/                         ← FastAPI 백엔드
+│   ├── main.py
+│   ├── core/   (config, database, auth, utils)
+│   ├── models/ (document, task, queue)
+│   ├── api/    (documents, search, tasks, dashboard, export)
+│   ├── workers/(file_watcher, extract, classify, embed, law_monitor, mailplus, digest)
+│   ├── prompts/classify.txt
+│   └── ai/client.py
+├── services/kordoc/             ← Node.js 마이크로서비스
+├── gpu-server/                  ← GPU 서버용 (별도 배포)
+│   ├── docker-compose.yml
+│   └── services/ai-gateway/
+├── frontend/                    ← SvelteKit
+├── migrations/                  ← PostgreSQL 스키마
+├── scripts/migrate_from_devonthink.py
+├── docs/
+└── tests/
+```
 
-1. **프로젝트 구조** — README.md, deploy.md 작성 (구조는 이미 생성됨)
-2. **Ollama 테스트** — 분류 프롬프트 최적화 → scripts/prompts/에 저장
-3. **AppleScript** — auto_classify.scpt, omnifocus_sync.scpt
-4. **법령 모니터링** — scripts/law_monitor.py + launchd plist
-5. **이메일 수집** — scripts/mailplus_archive.py + launchd plist
-6. **Daily Digest** — scripts/pkm_daily_digest.py + launchd plist
-7. **DEVONagent 가이드** — docs/devonagent-setup.md (수동 설정 가이드)
-8. **테스트** — tests/ + docs/test-report.md
+## 데이터 3계층
+
+1. **원본 파일** (NAS `/volume4/Document_Server/PKM/`) — 유일한 진짜 원본
+2. **가공 데이터** (PostgreSQL) — 텍스트 추출, AI 메타데이터, 검색 인덱스
+3. **파생물** (pgvector + 캐시) — 벡터 임베딩, 썸네일
 
 ## 코딩 규칙
 
-- Python 3.11+ (Mac mini 기본)
-- 인증 정보는 반드시 credentials.env에서 로딩 (하드코딩 금지)
-- AppleScript는 DEVONthink/OmniFocus와 연동 (osascript로 호출)
-- 로그는 ~/Documents/code/DEVONThink_my\ server/logs/에 저장
-- launchd plist는 launchd/ 디렉토리에 생성, Mac mini에서 심볼릭 링크로 등록
+- Python 3.11+, asyncio, type hints
+- SQLAlchemy 2.0+ async 세션
+- 인증 정보는 credentials.env에서 로딩 (하드코딩 금지)
+- 로그는 `logs/`에 저장 (Docker 볼륨)
+- AI 호출은 반드시 `app/ai/client.py`의 `AIClient`를 통해 (직접 HTTP 호출 금지)
 - 한글 주석 사용
 
-## 배포 방법
+## 개발/배포 워크플로우
 
 ```
-MacBook Pro (개발) → Gitea push → Mac mini에서 git pull
-Mac mini에서:
-  cd ~/Documents/code/DEVONThink_my\ server/
+MacBook Pro (개발) → Gitea push → 서버에서 pull
+
+개발:
+  cd ~/Documents/code/hyungi_Document_Server/
+  # 코드 작성 → git commit & push
+
+Mac mini 배포:
+  cd ~/Documents/code/hyungi_Document_Server/
   git pull
-  source venv/bin/activate
-  pip install -r requirements.txt
-  # launchd 등록은 deploy.md 참조
+  docker compose up -d
+
+GPU 서버 배포:
+  cd ~/Documents/code/hyungi_Document_Server/gpu-server/
+  git pull
+  docker compose up -d
+```
+
+## v1 코드 참조
+
+v1(DEVONthink 기반) 코드는 `v1-final` 태그로 보존:
+```bash
+git show v1-final:scripts/law_monitor.py
+git show v1-final:scripts/pkm_utils.py
+git show v1-final:scripts/prompts/classify_document.txt
 ```
 
 ## 주의사항
 
-- credentials.env는 git에 올리지 않음 (.gitignore에 포함)
-- DEVONthink, OmniFocus는 Mac mini에서 GUI로 실행 중이어야 AppleScript 작동
+- credentials.env는 git에 올리지 않음 (.gitignore)
+- NAS SMB 마운트 경로: Docker 컨테이너 내 `/documents`
 - 법령 API (LAW_OC)는 승인 대기 중 — 스크립트만 만들고 실제 호출은 승인 후
-- TKSafety 연동은 설계만 완료, 구현은 나중에
-- GPU 서버 Tailscale IP는 별도 확인 후 credentials.env에 추가
+- GPU 서버 Tailscale IP는 credentials.env에서 관리