# hyungi_Document_Server — Claude Code 작업 가이드

## 프로젝트 개요

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 전략, 인프라, 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 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
  - 파일 원본: /volume4/Document_Server/PKM/
  - Synology Office: 문서 편집/미리보기
  - Synology Calendar: CalDAV 태스크 관리 (OmniFocus 대체)
  - MailPlus: IMAP(993) + SMTP(465)

GPU 서버 (RTX 4070 Ti Super):
  - AI Gateway: http://gpu-server:8080 (모델 라우팅, 폴백, 비용 제어)
  - nomic-embed-text: 벡터 임베딩
  - Qwen2.5-VL-7B: 이미지/도면 OCR
  - bge-reranker-v2-m3: RAG 리랭킹
```

## 인증 정보

- 위치: `credentials.env` (프로젝트 루트, .gitignore에 포함)
- 템플릿: `credentials.env.example`
- 스크립트에서 python-dotenv 또는 Docker env_file로 로딩

## AI 모델 구성

```
Primary (Mac mini MLX, 상시, 무료):
  mlx-community/Qwen3.5-35B-A3B-4bit — 분류, 태그, 요약
  → http://localhost:8800/v1/chat/completions

Fallback (GPU Ollama, MLX 장애 시):
  qwen3.5:35b-a3b
  → http://gpu-server:11434/v1/chat/completions

Premium (Claude API, 종량제, 수동 트리거만):
  claude-sonnet — 복잡한 분석, 장문 처리
  → 일일 한도 $5, require_explicit_trigger: true

Embedding (GPU 서버 전용):
  nomic-embed-text → 벡터 임베딩
  Qwen2.5-VL-7B → 이미지/도면 OCR
  bge-reranker-v2-m3 → RAG 리랭킹
```

## 프로젝트 구조

```
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/
```

## 데이터 3계층

1. **원본 파일** (NAS `/volume4/Document_Server/PKM/`) — 유일한 진짜 원본
2. **가공 데이터** (PostgreSQL) — 텍스트 추출, AI 메타데이터, 검색 인덱스
3. **파생물** (pgvector + 캐시) — 벡터 임베딩, 썸네일

## 코딩 규칙

- 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 → 서버에서 pull

개발:
  cd ~/Documents/code/hyungi_Document_Server/
  # 코드 작성 → git commit & push

Mac mini 배포:
  cd ~/Documents/code/hyungi_Document_Server/
  git pull
  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)
- NAS SMB 마운트 경로: Docker 컨테이너 내 `/documents`
- 법령 API (LAW_OC)는 승인 대기 중 — 스크립트만 만들고 실제 호출은 승인 후
- GPU 서버 Tailscale IP는 credentials.env에서 관리