Merge pull request 'docs(readme): refresh stack/features/infra to 2026-05 reality' (#13) from docs/readme-refresh into main

Reviewed-on: #13

README.md

@@ -1,64 +1,108 @@
 # hyungi_Document_Server
 
-Self-hosted 개인 지식관리(PKM) 웹 애플리케이션
+Self-hosted 개인 지식관리(PKM) + 다국 뉴스 비교 분석 웹 애플리케이션.
+
+> 모델 이름·엔드포인트·머신 정보는 운영 상태에 따라 변하므로 README 에 박지 않습니다.
+> 운영 단일 진실 소스(SSOT): `~/.claude/projects/-Users-hyungiahn/memory/infra_inventory.md`.
+> 모델/엔드포인트/포트/SSH 어디서든 README 와 inventory 가 충돌하면 **inventory 가 정답**입니다.
 
 ## 기술 스택
 
-- **백엔드**: FastAPI + SQLAlchemy (async)
+- **백엔드**: FastAPI + SQLAlchemy 2.0 async, APScheduler cron
-- **데이터베이스**: PostgreSQL 16 + pgvector + pg_trgm
+- **DB**: PostgreSQL 16 + pgvector + pg_trgm (단일 `pkm` DB)
-- **프론트엔드**: SvelteKit
+- **프론트엔드**: SvelteKit 5 (runes mode) + Tailwind CSS 4
-- **문서 파싱**: kordoc (HWP/HWPX/PDF → Markdown)
+- **문서 파싱**: kordoc 마이크로서비스 (HWP/HWPX/PDF → Markdown), LibreOffice headless (오피스), marker (PDF → markdown Phase 1B)
-- **AI**: Qwen3.5-35B-A3B (MLX), nomic-embed-text, Claude API (폴백)
+- **AI 파이프라인** (역할별, 자세한 모델 매핑은 inventory):
-- **인프라**: Docker Compose, Caddy, Synology NAS
+  - 분류/요약 본체: Mac mini MLX 26B (primary)
+  - Triage / fallback / chat: GPU Ollama 4B
+  - Embedding: GPU Ollama `bge-m3` (1024d)
+  - Reranker: GPU TEI 컨테이너 `bge-reranker-v2-m3`
+  - OCR: docker compose `ocr-service` (Surya OCR GPU)
+  - STT: Mac mini MLX Whisper large-v3
+  - Premium (수동 trigger): Anthropic Claude (`require_explicit_trigger`)
+- **인증**: JWT (access) + HttpOnly cookie (refresh) + TOTP 2FA
+- **인프라**: Docker Compose, Caddy (HTTP only, 앞단 home-caddy 가 HTTPS 종료), Synology NAS NFS
 
 ## 주요 기능
 
-- 문서 자동 분류/태그/요약 (AI 기반)
+- **문서 자동 분류/태그/요약** — Triage(4B) → Deep summary(26B) tier 분리, 백로그 guard / 텍스트 슬라이스 / inconsistency 감지
-- 전문검색 + 벡터 유사도 검색
+- **하이브리드 검색** — pgvector 벡터 + pg_trgm 전문검색 + reranker (bge-reranker-v2-m3) + Ask pipeline (HyDE / evidence_service)
-- HWP/PDF/Markdown 문서 뷰어
+- **다국어 OCR** — Surya OCR GPU (한/영/일/중/독/불 등), NFC/NFD 경로 정규화
-- 법령 변경 모니터링 (산업안전보건법 등)
+- **음성/영상 전사** — MLX Whisper large-v3, `/audio` `/video` 라우트 + direct play
-- 이메일 자동 수집 (MailPlus IMAP)
+- **법령 변경 모니터링** — `law_monitor` cron, freshness decay (365일 반감기)
-- 일일 다이제스트
+- **이메일 자동 수집** — MailPlus IMAP, NFS 저장
-- CalDAV 태스크 연동 (Synology Calendar)
+- **Phase 4 Global Digest** — 매일 04:00 KST 7일 rolling 뉴스 country×topic 2-level 비교 (`/digest`)
+- **야간 뉴스 브리핑** — 매일 05:10 KST KST 자정~05:00 5시간 윈도우, topic×country 비교 분석 1페이지 카드 (`/news`)
+- **자료실 (Library)** — 카테고리 facet 분류 + AI 제안 1-click 승인
+- **메모/이벤트/공부** — 5초 행동 기록 메모, 일정/할 일/회고 events 도메인, 가스기사 학습 워크스페이스 (274 개념 + 2,100 기출)
+- **마크다운 canonical layer** — extracted_images NAS 저장 + `document_images` 메타 + 단기 토큰 인증 (`?token=`)
 
 ## Quick Start
 
 ```bash
-git clone https://git.hyungi.net/hyungi/hyungi_document_server.git hyungi_Document_Server
+git clone https://git.hyungi.net/hyungi/hyungi_document_server.git
-cd hyungi_Document_Server
+cd hyungi_document_server
 
-# 인증 정보 설정
+# 인증 정보 (DB 비밀번호, JWT secret, Claude API key 등)
 cp credentials.env.example credentials.env
-nano credentials.env  # 실제 값 입력
+$EDITOR credentials.env
 
-# 실행
+# AI 모델 / 엔드포인트 / 경로
-docker compose up -d
+$EDITOR config.yaml      # inventory 참조하면서 채움
+$EDITOR .env             # POSTGRES_PASSWORD, MAC_MINI_HOST, NAS_NFS_PATH 등
+
+docker compose up -d --build
 ```
 
-`http://localhost:8000/docs` 에서 API 문서 확인
+운영 도메인 (GPU 서버 배포 기준): `https://document.hyungi.net`
+API 문서: `https://document.hyungi.net/docs`
 
 ## 디렉토리 구조
 
 ```
-├── app/              FastAPI 백엔드 (API, 워커, AI 클라이언트)
+├── app/                FastAPI 백엔드
-├── frontend/         SvelteKit 프론트엔드
+│   ├── api/              라우터 (documents, search, briefing, digest, memos, events, study, …)
-├── services/kordoc/  문서 파싱 마이크로서비스 (Node.js)
+│   ├── workers/          APScheduler / queue (briefing_worker, digest_worker, classify_worker, …)
-├── gpu-server/       GPU 서버 배포 (AI Gateway)
+│   ├── services/         도메인 로직 (briefing/, digest/, search/, clustering_common, …)
-├── migrations/       PostgreSQL 스키마
+│   ├── ai/client.py      AIClient (call_triage / call_primary / call_fallback, parse_json_response)
-├── docs/             설계 문서, 배포 가이드
+│   ├── prompts/          *.txt 프롬프트 (분류, 요약, briefing_comparative, digest_topic, …)
-└── tests/            테스트 코드
+│   ├── policy/           AI envelope + prompt_render
+│   └── models/           SQLAlchemy ORM
+├── frontend/           SvelteKit 5 (runes mode) + Tailwind
+│   └── src/routes/       /news (아침 브리핑) /library /memos /audio /video /study /digest /ask …
+├── services/
+│   ├── kordoc/           HWP/HWPX/PDF 파싱 (Node.js)
+│   ├── ocr/              Surya OCR GPU 서비스 (FastAPI)
+│   └── marker/           PDF → markdown Phase 1B
+├── migrations/         255+ SQL migrations (schema_migrations 추적)
+├── docs/               설계 문서
+└── tests/              pytest
 ```
 
-## 인프라 구성
+`gpu-server/` 폴더는 v1 잔재로 deprecated (현재 AI Gateway 는 `~/home-gateway/` 별 repo).
 
-| 서버 | 역할 |
+## 인프라 구성 (운영 기준)
-|------|------|
+
-| Mac mini M4 Pro | Docker Compose (FastAPI, PostgreSQL, kordoc, Caddy) + MLX AI |
+| 머신 | 역할 |
-| Synology NAS | 파일 원본 저장, Synology Office/Drive/Calendar/MailPlus |
+|---|---|
-| GPU 서버 | AI Gateway, 벡터 임베딩, OCR, 리랭킹 |
+| **GPU 서버** (메인) | Docker Compose (fastapi, frontend, postgres pkm, kordoc, ocr-service, marker-service, reranker(TEI), caddy), Ollama (`bge-m3`, 4B chat), home-gateway 별 compose |
+| **Mac mini** | MLX 26B primary 추론 + MLX Whisper STT (HTTP 추론 endpoint only, ingress 역할 0) |
+| **Synology NAS** | 파일 원본 (`/volume4/Document_Server/PKM/`), Synology Office/Drive/Calendar/MailPlus, NFS export → GPU |
+| **VPS-2** (OVH) | 메일 relay (`relay.hyungi.net:587` SASL+TLS+DKIM+LE), Gitea bare mirror, Secondary MX |
+
+상세 IP / 모델 / 컨테이너 / drift / verify 명령은 `infra_inventory.md` 참조.
+
+## 운영 변경 정책
+
+1. inventory 먼저 갱신
+2. `config.yaml` / `credentials.env` 갱신
+3. deploy (commit → push Gitea → GPU `git pull && docker compose up -d --build`)
+4. verify (smoke endpoints, postgres count, 모니터링)
+
+순서를 어기면 drift. drift 발견 시 `infra_inventory.md` 의 Drift Log 에 등록 후 정정.
 
 ## 문서
 
-- [아키텍처](docs/architecture.md) — 전체 시스템 설계
+- [아키텍처](docs/architecture.md) — DB 스키마, AI 전략, UI 설계
-- [배포 가이드](docs/deploy.md) — Docker Compose 배포 방법
+- [배포 가이드](docs/deploy.md) — Docker Compose 배포
-- [개발 단계](docs/development-stages.md) — Phase 0~5 개발 계획
+- [개발 단계](docs/development-stages.md) — Phase 별 roadmap (Phase 4 Global Digest / 야간 브리핑 등 신규 phase 는 inventory + plan 파일 우선)