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>
2026-04-02 09:39:36 +09:00
parent e48b6a2bb4
commit b338e6e424
6 changed files with 422 additions and 483 deletions
--- a/CLAUDE.md
+++ b/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에서 관리
--- a/README.md
+++ b/README.md
@@ -1,40 +1,64 @@
-# DEVONThink PKM System
+# hyungi_Document_Server

-Mac mini M4 Pro 기반 개인 지식관리 자동화 시스템
+Self-hosted 개인 지식관리(PKM) 웹 애플리케이션

-## 구성 요소
+## 기술 스택

- **DEVONthink 4** — 중앙 지식 허브 (13개 DB)
- **Ollama** — AI 자동 분류/태깅 (Qwen3.5-35B-A3B)
- **법령 모니터링** — 산업안전보건법 등 변경 추적
- **일일 다이제스트** — PKM 전체 변화 요약
- **OmniFocus 연동** — 액션 아이템 자동 생성
+- **백엔드**: FastAPI + SQLAlchemy (async)
+- **데이터베이스**: PostgreSQL 16 + pgvector + pg_trgm
+- **프론트엔드**: SvelteKit
+- **문서 파싱**: kordoc (HWP/HWPX/PDF → Markdown)
+- **AI**: Qwen3.5-35B-A3B (MLX), nomic-embed-text, Claude API (폴백)
+- **인프라**: Docker Compose, Caddy, Synology NAS

-## 설치
+## 주요 기능
+
+- 문서 자동 분류/태그/요약 (AI 기반)
+- 전문검색 + 벡터 유사도 검색
+- HWP/PDF/Markdown 문서 뷰어
+- 법령 변경 모니터링 (산업안전보건법 등)
+- 이메일 자동 수집 (MailPlus IMAP)
+- 일일 다이제스트
+- CalDAV 태스크 연동 (Synology Calendar)
+
+## Quick Start

 ```bash
-# Mac mini에서
-git clone [gitea-repo-url]
-cd DEVONThink_my\ server
-python3 -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
+git clone https://git.hyungi.net/hyungi/hyungi_document_server.git
+cd hyungi_Document_Server

 # 인증 정보 설정
-mkdir -p ~/.config/pkm
-cp credentials.env.example ~/.config/pkm/credentials.env
-nano ~/.config/pkm/credentials.env  # 실제 값 입력
-chmod 600 ~/.config/pkm/credentials.env
+cp credentials.env.example credentials.env
+nano credentials.env  # 실제 값 입력
+
+# 실행
+docker compose up -d
 ```

-자세한 배포 방법은 `docs/deploy.md` 참조
+`http://localhost:8000/docs` 에서 API 문서 확인

 ## 디렉토리 구조

 ```
-scripts/          Python 스크립트 (법령모니터, 메일수집, 다이제스트)
-applescript/      DEVONthink/OmniFocus 연동 AppleScript
-launchd/          macOS 스케줄 실행 plist
-docs/             설계 문서, 가이드
-tests/            테스트 코드
+├── app/              FastAPI 백엔드 (API, 워커, AI 클라이언트)
+├── frontend/         SvelteKit 프론트엔드
+├── services/kordoc/  문서 파싱 마이크로서비스 (Node.js)
+├── gpu-server/       GPU 서버 배포 (AI Gateway)
+├── migrations/       PostgreSQL 스키마
+├── docs/             설계 문서, 배포 가이드
+└── tests/            테스트 코드
 ```
+
+## 인프라 구성
+
+| 서버 | 역할 |
+|------|------|
+| Mac mini M4 Pro | Docker Compose (FastAPI, PostgreSQL, kordoc, Caddy) + MLX AI |
+| Synology NAS | 파일 원본 저장, Synology Office/Drive/Calendar/MailPlus |
+| GPU 서버 | AI Gateway, 벡터 임베딩, OCR, 리랭킹 |
+
+## 문서
+
+- [아키텍처](docs/architecture.md) — 전체 시스템 설계
+- [배포 가이드](docs/deploy.md) — Docker Compose 배포 방법
+- [개발 단계](docs/development-stages.md) — Phase 0~5 개발 계획
--- a/docs/architecture-v2.md
+++ b/docs/architecture-v2.md
--- a/docs/claude-code-commands.md
+++ b/docs/claude-code-commands.md
@@ -1,302 +0,0 @@
-# Claude Code 실행 명령어 — PKM 시스템 구축
-
-> 작업 위치: MacBook Pro ~/Documents/code/DEVONThink_my server/
-> Claude Code를 이 디렉토리에서 실행
-> 완성 후 Gitea에 push → Mac mini에서 pull
-
-```
-개발/배포 흐름:
-MacBook Pro (Claude Code)
-  ~/Documents/code/DEVONThink_my server/
-  → 스크립트/설정 파일 작성
-  → git commit & push
-          │
-          ▼
-  Gitea (Synology NAS)
-          │
-          ▼
-  Mac mini (git pull → 실행)
-```
-
---
-
-## 0단계: 프로젝트 구조 생성 + credentials.env 복사
-
-Claude Code 실행 전에 먼저:
-
-```bash
-# MacBook Pro에서
-cd ~/Documents/code/DEVONThink_my\ server/
-
-# credentials.env를 프로젝트에 복사 (gitignore 필수!)
-cp ~/.config/pkm/credentials.env ./credentials.env.example
-# example은 값을 비운 템플릿용, 실제 파일은 Mac mini에서 직접 생성
-
-# Mac mini에서 (SSH 접속 후)
-mkdir -p ~/.config/pkm
-nano ~/.config/pkm/credentials.env
-# → 실제 인증 정보 입력
-chmod 600 ~/.config/pkm/credentials.env
-```
-
---
-
-## 1단계: 프로젝트 구조 + requirements.txt
-
-```
-이 프로젝트의 디렉토리 구조를 만들고 기본 설정 파일들을 생성해줘.
-작업 디렉토리: 현재 디렉토리 (~/Documents/code/DEVONThink_my server/)
-
-프로젝트 구조:
-./
-├── README.md                 ← 프로젝트 설명
-├── requirements.txt          ← Python 패키지 목록
-├── .gitignore                ← credentials.env, venv, logs, __pycache__ 등 제외
-├── credentials.env.example   ← 인증 정보 템플릿 (값은 비움)
-├── scripts/
-│   ├── law_monitor.py
-│   ├── mailplus_archive.py
-│   ├── pkm_daily_digest.py
-│   ├── embed_to_chroma.py
-│   └── prompts/
-│       └── classify_document.txt
-├── applescript/
-│   ├── auto_classify.scpt
-│   └── omnifocus_sync.scpt
-├── launchd/
-│   ├── net.hyungi.pkm.law-monitor.plist
-│   ├── net.hyungi.pkm.mailplus.plist
-│   └── net.hyungi.pkm.daily-digest.plist
-├── docs/
-│   ├── devonagent-setup.md
-│   └── deploy.md             ← Mac mini 배포 방법
-└── tests/
-    └── test_classify.py
-
-requirements.txt에 넣을 패키지:
- chromadb
- requests
- python-dotenv
- schedule
- markdown
-
-.gitignore에 반드시 포함:
- credentials.env
- venv/
- logs/
- __pycache__/
- *.pyc
- .DS_Store
-
-deploy.md에는 Mac mini에서의 설치 절차 작성:
-1. git pull
-2. python3 -m venv venv && source venv/bin/activate
-3. pip install -r requirements.txt
-4. credentials.env는 ~/.config/pkm/credentials.env에 별도 관리
-5. launchd plist 심볼릭 링크 등록 방법
-
-네트워크 환경:
- NAS 도메인: ds1525.hyungi.net (Tailscale: 100.101.79.37, 포트: 15001)
- MailPlus: mailplus.hyungi.net:993 (IMAP SSL)
- WebDAV: webdav.hyungi.net/Document_Server/DEVONThink/
- TKSafety: tksafety.technicalkorea.net (나중에 활성화)
-```
-
---
-
-## 2단계: Ollama 모델 확인 + 분류 프롬프트 테스트
-
-```
-Ollama가 정상 동작하는지 확인하고, PKM 문서 분류용 프롬프트를 테스트해줘.
-
-1. ollama list로 현재 모델 확인
-2. qwen3.5:35b-a3b 계열 모델이 있는지 확인 (없으면 알려줘)
-3. 테스트 프롬프트 실행 — 아래 내용으로 분류 테스트:
-
-테스트 문서: "산업안전보건법 시행규칙 일부개정령안 입법예고 - 고용노동부는 위험성평가에 관한 지침을 개정하여..."
-
-기대 응답 JSON:
-{
-  "tags": ["위험성평가", "법령개정", "고용노동부"],
-  "domain_db": "04_Industrial safety",
-  "sub_group": "10_Legislation/Notice",
-  "sourceChannel": "inbox_route",
-  "dataOrigin": "external"
-}
-
-도메인 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
-
-sourceChannel 값: tksafety, devonagent, law_monitor, inbox_route, email, web_clip, manual
-dataOrigin 값: work (자사 업무), external (외부 참고)
-
-프롬프트를 최적화해서 ~/Documents/code/DEVONThink_my server/scripts/prompts/ 디렉토리에 저장해줘.
-```
-
---
-
-## 3단계: DEVONthink Smart Rule + AppleScript 배포
-
-```
-DEVONthink 4 Smart Rule용 AppleScript 모듈들을 만들어줘.
-Mac mini에서 DEVONthink가 실행 중이야.
-
-모듈 A: Ollama 연동 자동 분류 (~/Documents/code/DEVONThink_my server/applescript/auto_classify.scpt)
- DEVONthink Inbox DB에 새 문서가 들어오면 실행
- Ollama qwen3.5 35B에 문서 텍스트 전송
- 응답에서 tags, domain_db, sub_group, sourceChannel, dataOrigin 파싱
- DEVONthink 태그 설정 + 커스텀 메타데이터(sourceChannel, dataOrigin, lastAIProcess) 설정
- 해당 도메인 DB의 하위 그룹으로 문서 이동
- GPU 서버(Tailscale IP)로 벡터 임베딩 비동기 전송
-
-모듈 B: OmniFocus 연동 (~/Documents/code/DEVONThink_my server/applescript/omnifocus_sync.scpt)
- Projects DB에 새 문서 추가 시 TODO 패턴 감지
- OmniFocus에 작업 생성 (DEVONthink 링크 포함)
- 커스텀 메타데이터에 omnifocusTaskID 저장
-
-프롬프트 파일 위치: ~/Documents/code/DEVONThink_my server/scripts/prompts/
-인증 정보: ~/.config/pkm/credentials.env
-GPU 서버 Tailscale IP는 별도 확인 필요 (나중에 추가)
-```
-
---
-
-## 4단계: 법령 모니터링 스크립트
-
-```
-한국 법령 변경 모니터링 스크립트를 만들어줘.
-
-스크립트: ~/Documents/code/DEVONThink_my server/scripts/law_monitor.py
-인증: ~/.config/pkm/credentials.env의 LAW_OC 값 사용
-API: open.law.go.kr OpenAPI
-
-기능:
-1. 산업안전보건법, 중대재해처벌법, 관련 시행령/시행규칙/고시 변경 추적
-2. 변경 감지 시:
-   - 법령 본문(XML) 다운로드 → ~/Documents/code/DEVONThink_my server/data/laws/에 저장
-   - DEVONthink 04_Industrial Safety/10_Legislation/ 하위에 자동 임포트 (AppleScript 호출)
-   - 커스텀 메타데이터: sourceChannel=law_monitor, dataOrigin=external
-   - 로그: ~/Documents/code/DEVONThink_my server/logs/law_monitor.log
-3. launchd plist 생성: 매일 07:00 실행
-   ~/Documents/code/DEVONThink_my server/launchd/net.hyungi.pkm.law-monitor.plist
-   → ~/Library/LaunchAgents/에 심볼릭 링크
-
-※ 법령 API 승인 대기중이라 스크립트만 만들고 실제 테스트는 승인 후에
-※ 해외 법령(US OSHA, JP, EU)은 나중에 추가 예정
-```
-
---
-
-## 5단계: MailPlus → DEVONthink 이메일 수집
-
-```
-MailPlus 이메일을 DEVONthink Archive DB로 자동 수집하는 스크립트를 만들어줘.
-
-스크립트: ~/Documents/code/DEVONThink_my server/scripts/mailplus_archive.py
-인증: ~/.config/pkm/credentials.env
-
-접속 정보:
- IMAP 서버: mailplus.hyungi.net:993 (SSL)
- 계정: hyungi
-
-기능:
-1. IMAP으로 MailPlus 접속
-2. 마지막 동기화 이후 새 메일 가져오기
-3. DEVONthink Archive DB에 임포트 (AppleScript 호출)
-4. 커스텀 메타데이터: sourceChannel=email
-5. 안전 관련 키워드 감지 시 dataOrigin 자동 판별
-
-launchd: 매일 07:00 + 18:00 실행
-~/Documents/code/DEVONThink_my server/launchd/net.hyungi.pkm.mailplus.plist
-```
-
---
-
-## 6단계: Daily Digest 시스템
-
-```
-PKM 일일 다이제스트를 자동 생성하는 스크립트를 만들어줘.
-
-스크립트: ~/Documents/code/DEVONThink_my server/scripts/pkm_daily_digest.py
-인증: ~/.config/pkm/credentials.env
-
-기능:
-1. DEVONthink에서 오늘 추가/수정된 문서 집계 (AppleScript로 쿼리)
-   - DB별 신규 건수
-   - sourceChannel별 구분
-2. law_monitor 로그에서 법령 변경 건 파싱
-3. OmniFocus 오늘 완료/추가/기한초과 집계 (AppleScript)
-4. 상위 뉴스 3건 요약 (Ollama 35B 호출)
-5. MD 파일 생성 → DEVONthink 00_Note_BOX/Daily_Digest/에 저장
-   파일명: YYYY-MM-DD_digest.md
-6. OmniFocus 액션 자동 생성 (법령변경, overdue, Inbox 미처리 등)
-7. 90일 지난 다이제스트 → 90_Archive 이동 (Smart Rule 대체)
-
-launchd: 매일 20:00 실행
-~/Documents/code/DEVONThink_my server/launchd/net.hyungi.pkm.daily-digest.plist
-
-※ Synology Chat 웹훅 알림은 나중에 추가 (CHAT_WEBHOOK_URL 설정 후)
-```
-
---
-
-## 7단계: DEVONagent 검색 세트 (수동 가이드)
-
-```
-DEVONagent Pro에서 안전 분야 자동 검색 세트를 설정하는 가이드를 만들어줘.
-
-총 9개 검색 세트 (7 안전 + 2 기술):
-1. 국내 산업안전 뉴스 (kosha, moel, safetynews 등)
-2. 국내 중대재해 뉴스
-3. KOSHA 가이드/지침
-4. 국내 산업안전 학술/논문
-5. US OSHA / Safety+Health Magazine
-6. JP 厚生労働省 / 安全衛生
-7. EU-OSHA
-8. 기술 뉴스 (AI/서버/네트워크)
-9. 프로그래밍 기술 동향
-
-각 세트별로:
- 검색 키워드/연산자
- 사이트 제한
- 스케줄 (매일/주간)
- 수량 제한 (주간 합계 50~85건 수준)
- 결과 → DEVONthink Inbox로 전송 설정 방법
-
-이건 DEVONagent GUI에서 수동 설정해야 하니까,
-단계별 가이드 문서를 ~/Documents/code/DEVONThink_my server/docs/devonagent-setup.md로 만들어줘.
-```
-
---
-
-## 8단계: 전체 테스트
-
-```
-PKM 시스템 전체 End-to-End 테스트를 진행해줘.
-
-테스트 항목:
-1. Ollama 분류 테스트 — 5종 문서(법령, 뉴스, 논문, 메모, 이메일) 분류 정확도
-2. DEVONthink Smart Rule — Inbox에 테스트 문서 추가 → 자동 분류 확인
-3. sourceChannel/dataOrigin 메타데이터가 정상 설정되는지
-4. OmniFocus 연동 — TODO 패턴 문서 → 작업 자동 생성
-5. MailPlus IMAP 접속 테스트
-6. launchd 스케줄 등록 확인 (launchctl list | grep pkm)
-7. Daily Digest 수동 실행 테스트
-
-각 항목 pass/fail 리포트를 ~/Documents/code/DEVONThink_my server/docs/test-report.md로 저장해줘.
-```
-
---
-
-## 참고: 네트워크 환경
-
-```
-Mac mini 접속: SSH (MacBook Pro → Mac mini)
-NAS 도메인: ds1525.hyungi.net (Tailscale: 100.101.79.37, 포트: 15001)
-MailPlus: mailplus.hyungi.net:993 (IMAP SSL)
-WebDAV: webdav.hyungi.net/Document_Server/DEVONThink/
-TKSafety: tksafety.technicalkorea.net (나중에 활성화)
-내부 네트워크: Tailscale VPN 연결됨
-```
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -1,96 +1,154 @@
-# Mac mini 배포 가이드
+# 배포 가이드

-## 1. 초기 설치
+## 1. 사전 요구사항
+
+- Docker & Docker Compose (Mac mini)
+- NAS SMB 마운트 (`/Volumes/Document_Server`)
+- Tailscale VPN 연결 (Mac mini ↔ GPU 서버 ↔ NAS)
+
+## 2. Mac mini 배포
+
+### 2-1. 코드 가져오기

 ```bash
-# Mac mini에서
 cd ~/Documents/code/
-git clone https://git.hyungi.net/hyungi/devonthink_home.git "DEVONThink_my server"
-cd "DEVONThink_my server"
-
-# Python 가상환경
-python3 -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
+git clone https://git.hyungi.net/hyungi/hyungi_document_server.git hyungi_Document_Server
+cd hyungi_Document_Server
 ```

-## 2. 인증 정보 설정
+### 2-2. 인증 정보 설정

 ```bash
-mkdir -p ~/.config/pkm
-nano ~/.config/pkm/credentials.env
-chmod 600 ~/.config/pkm/credentials.env
+cp credentials.env.example credentials.env
+nano credentials.env  # 실제 값 입력
+chmod 600 credentials.env
 ```

-credentials.env.example을 참고하여 실제 값 입력.
+필수 값: `POSTGRES_PASSWORD`, `JWT_SECRET`, `TOTP_SECRET`, `MLX_ENDPOINT`
+선택 값: `CLAUDE_API_KEY`, `LAW_OC` (법령 API 승인 후)

-## 3. launchd 스케줄 등록
+### 2-3. NAS SMB 마운트 확인

 ```bash
-# 심볼릭 링크 생성
-ln -sf ~/Documents/code/DEVONThink_my\ server/launchd/net.hyungi.pkm.law-monitor.plist ~/Library/LaunchAgents/
-ln -sf ~/Documents/code/DEVONThink_my\ server/launchd/net.hyungi.pkm.mailplus.plist ~/Library/LaunchAgents/
-ln -sf ~/Documents/code/DEVONThink_my\ server/launchd/net.hyungi.pkm.daily-digest.plist ~/Library/LaunchAgents/
-
-# 등록
-launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.law-monitor.plist
-launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.mailplus.plist
-launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.daily-digest.plist
+# macOS에서 SMB 마운트 (Finder 또는 CLI)
+mount -t smbfs //hyungi@ds1525.hyungi.net/Document_Server /Volumes/Document_Server

 # 확인
-launchctl list | grep pkm
+ls /Volumes/Document_Server/PKM/
 ```

-## 4. 수동 테스트
+Docker 컨테이너에서 이 경로를 `/documents`로 바인드 마운트한다.
+
+### 2-4. 서비스 시작

 ```bash
-cd ~/Documents/code/DEVONThink_my\ server/
-source venv/bin/activate
+docker compose up -d

-# 각 스크립트 수동 실행
-python3 scripts/law_monitor.py
-python3 scripts/mailplus_archive.py
-python3 scripts/pkm_daily_digest.py
+# 상태 확인
+docker compose ps
+docker compose logs -f fastapi
 ```

-## 5. DEVONthink Smart Rule 설정
-
-1. DEVONthink → Preferences → Smart Rules
-2. 새 Rule: "AI Auto Classify"
-   - Event: On Import
-   - Database: Inbox
-   - Condition: Tags is empty
-   - Action: Execute Script → External → `applescript/auto_classify.scpt`
-3. 새 Rule: "OmniFocus Sync"
-   - Event: On Import
-   - Database: Projects
-   - Action: Execute Script → External → `applescript/omnifocus_sync.scpt`
-
-## 6. 업데이트
+### 2-5. 확인

 ```bash
-cd ~/Documents/code/DEVONThink_my\ server/
+# FastAPI OpenAPI 문서
+curl http://localhost:8000/docs
+
+# PostgreSQL 테이블 확인
+docker compose exec postgres psql -U pkm -d pkm -c '\dt'
+
+# kordoc 헬스체크
+curl http://localhost:3100/health
+```
+
+### 2-6. 외부 접근 (Caddy)
+
+Caddy가 자동으로 HTTPS 인증서를 발급한다.
+- `pkm.hyungi.net` → FastAPI (:8000)
+- `office.hyungi.net` → Synology Office (NAS 프록시)
+
+DNS 레코드가 Mac mini의 공인 IP를 가리켜야 한다.
+
+## 3. GPU 서버 배포
+
+### 3-1. AI Gateway + Ollama
+
+```bash
+cd ~/Documents/code/hyungi_Document_Server/gpu-server/
+cp ../credentials.env .env  # 필요한 값만 복사
+docker compose up -d
+```
+
+### 3-2. 모델 확인
+
+```bash
+# Ollama 모델 목록
+docker compose exec ollama ollama list
+
+# 필요 모델 pull
+docker compose exec ollama ollama pull nomic-embed-text
+docker compose exec ollama ollama pull qwen2.5-vl:7b
+docker compose exec ollama ollama pull bge-reranker-v2-m3
+```
+
+### 3-3. AI Gateway 확인
+
+```bash
+curl http://localhost:8080/health
+```
+
+## 4. 업데이트
+
+```bash
+# Mac mini
+cd ~/Documents/code/hyungi_Document_Server/
 git pull
-source venv/bin/activate
-pip install -r requirements.txt
+docker compose up -d --build
+
+# GPU 서버
+cd ~/Documents/code/hyungi_Document_Server/gpu-server/
+git pull
+docker compose up -d --build
 ```

-## 7. 로그 확인
+## 5. 로그 확인

 ```bash
-# 스크립트 로그
-tail -f logs/law_monitor.log
-tail -f logs/mailplus.log
-tail -f logs/digest.log
+# FastAPI 로그
+docker compose logs -f fastapi

-# launchd 로그
-tail -f logs/law_monitor_launchd.log
+# 특정 워커 로그
+docker compose logs -f fastapi | grep law_monitor
+docker compose logs -f fastapi | grep mailplus
+docker compose logs -f fastapi | grep digest
+
+# PostgreSQL 로그
+docker compose logs -f postgres
 ```

-## 실행 스케줄
+## 6. 자동화 스케줄 (APScheduler)

-| 스크립트 | 시간 | 용도 |
-|---------|------|------|
-| law_monitor.py | 매일 07:00 | 법령 변경 모니터링 |
-| mailplus_archive.py | 매일 07:00, 18:00 | 이메일 수집 |
-| pkm_daily_digest.py | 매일 20:00 | 일일 다이제스트 |
+Docker 내부에서 APScheduler로 관리 (launchd 대체):
+
+| 시간 | 작업 | 주기 |
+|------|------|------|
+| 07:00 | law_monitor | 매일 |
+| 07:00, 18:00 | mailplus_archive | 매일 2회 |
+| 20:00 | daily_digest | 매일 |
+| */5분 | file_watcher | 상시 |
+| */10분 | processing_queue consumer | 상시 |
+
+## 7. 백업
+
+### 우선순위
+
+1. **NAS 원본 파일** — Synology Drive 버전 이력 + Hyper Backup
+2. **PostgreSQL** — `pg_dump` 정기 백업
+3. **Docker volumes** — pgdata, caddy_data
+
+### PostgreSQL 백업
+
+```bash
+docker compose exec postgres pg_dump -U pkm pkm > backup_$(date +%Y%m%d).sql
+```
--- a/docs/development-stages.md
+++ b/docs/development-stages.md
@@ -0,0 +1,142 @@
+# 개발 단계 가이드
+
+> 작업 위치: 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주 운영 안정
+- [ ] 모든 자동화(법령, 이메일, 다이제스트) 정상 실행