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>
This commit is contained in:
Hyungi Ahn
@@ -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 연결됨
|
||||
```
|
||||
184
docs/deploy.md
184
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
|
||||
```
|
||||
|
||||
142
docs/development-stages.md
Normal file
142
docs/development-stages.md
Normal file
@@ -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주 운영 안정
|
||||
- [ ] 모든 자동화(법령, 이메일, 다이제스트) 정상 실행
|
||||
Reference in New Issue
Block a user