docs: add PROGRESS.md, add bridge URLs to .env.example

Phase 1-6 구현 현황 + 파일 인벤토리 + 서비스 기동 가이드 통합 문서. .env.example에 bridge service URL 4개 추가. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-17 07:36:36 +09:00
parent 612933c2d3
commit 924560252e
2 changed files with 204 additions and 0 deletions
--- a/.env.example
+++ b/.env.example
@@ -51,3 +51,9 @@ IMAP_PASSWORD=changeme

 # DEVONthink (devonthink_bridge.py — 지식 저장소)
 DEVONTHINK_APP_NAME=DEVONthink
+
+# Bridge Service URLs (n8n Docker → macOS 네이티브 서비스)
+HEIC_CONVERTER_URL=http://host.docker.internal:8090
+CHAT_BRIDGE_URL=http://host.docker.internal:8091
+CALDAV_BRIDGE_URL=http://host.docker.internal:8092
+DEVONTHINK_BRIDGE_URL=http://host.docker.internal:8093
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -0,0 +1,198 @@
+# Progress — syn-chat-bot
+
+> 최종 업데이트: 2026-03-17
+
+## Phase별 구현 현황
+
+### Phase 1-3: RAG v2 초기 셋업 (커밋 `6e6ffaa`, 2026-03-11)
+
+- 3단계 모델 라우팅 (local / api_light / api_heavy)
+- 멀티-컬렉션 RAG (documents, tk_company, chat_memory)
+- Qwen 9B 분류기 v2 → v3 (intent, response_tier, needs_rag, rag_target)
+- 프리필터 (인사/감사 정규식 → GPU 미호출)
+- 선택적 메모리 (Qwen 판단 → 가치 있으면 벡터화)
+- bot-postgres 12테이블, Qdrant 3컬렉션
+- 페르소나 "이드" (전체/경량 프롬프트)
+- 안전장치: 토큰 검증, Rate Limit, 예산 상한, 분류기 fallback
+
+### Phase 4-5: 회사 문서 + 현장 리포팅 + 보고서 (커밋 `f42096f`, 2026-03-11)
+
+- `/문서등록` 명령어 — 청킹 → tk_company 벡터 저장 (hash 중복/버전 관리)
+- 현장 리포트 — 사진+텍스트 → Claude Haiku Vision → 구조화 → field_reports + tk_company
+- `/보고서` 명령어 — 월간 보고서 생성 (report_cache)
+- heic_converter.py — HEIC→JPEG 변환 (macOS sips)
+- chat_bridge.py — DSM Chat API 브릿지 (사진 폴링/다운로드/HEIC 자동변환)
+- API 사용량 추적 (api_usage_monthly UPSERT)
+
+### n8n Task Runner 샌드박스 대응 (커밋 `f7cccc9`, 2026-03-11)
+
+- n8n v2.11+ Code 노드 VM 샌드박스 대응
+- `fetch()`/`$http.request()` → `require('http')`/`require('https')` 패턴 전환
+- `NODE_FUNCTION_ALLOW_BUILTIN=crypto,http,https,url` 설정
+
+### Phase 5-6: Calendar/Mail/DEVONthink/OmniFocus/News (커밋 `612933c`, 2026-03-14)
+
+- 분류기 v3: calendar, reminder, mail, note intent 추가
+- caldav_bridge.py (:8092) — CalDAV REST 래퍼 (Synology Calendar CRUD)
+- devonthink_bridge.py (:8093) — DEVONthink AppleScript 래퍼
+- inbox_processor.py — OmniFocus Inbox 폴링 (LaunchAgent, 5분 간격)
+- news_digest.py — RSS 뉴스 번역·요약 (LaunchAgent, 매일 07:00)
+- Mail Processing Pipeline (7노드) — IMAP 폴링 → Qwen 분류 → mail_logs
+- 메인 파이프라인 51노드로 확장 (calendar/mail/note 핸들러)
+
+---
+
+## 파일 인벤토리
+
+### Python 서비스 (6개, 1,227줄)
+
+| 파일 | 줄수 | 포트/실행 | 역할 |
+|------|------|----------|------|
+| `caldav_bridge.py` | 269 | :8092 | CalDAV REST 래퍼 |
+| `chat_bridge.py` | 293 | :8091 | DSM Chat API 브릿지 |
+| `devonthink_bridge.py` | 125 | :8093 | DEVONthink AppleScript 래퍼 |
+| `heic_converter.py` | 25 | :8090 | HEIC→JPEG 변환 |
+| `inbox_processor.py` | 225 | LaunchAgent 5분 | OmniFocus Inbox 폴링 |
+| `news_digest.py` | 290 | LaunchAgent 07:00 | 뉴스 번역·요약 |
+
+### LaunchAgent plist (6개)
+
+| 파일 | 서비스 |
+|------|--------|
+| `com.syn-chat-bot.caldav-bridge.plist` | caldav_bridge |
+| `com.syn-chat-bot.chat-bridge.plist` | chat_bridge |
+| `com.syn-chat-bot.devonthink-bridge.plist` | devonthink_bridge |
+| `com.syn-chat-bot.heic-converter.plist` | heic_converter |
+| `com.syn-chat-bot.inbox-processor.plist` | inbox_processor |
+| `com.syn-chat-bot.news-digest.plist` | news_digest |
+
+### n8n 워크플로우 (2개)
+
+| 파일 | 노드수 | 역할 |
+|------|--------|------|
+| `main-chat-pipeline.json` | 51 | 메인 채팅 파이프라인 |
+| `mail-processing-pipeline.json` | 7 | 메일 처리 파이프라인 |
+
+### SQL (3개, 618줄)
+
+| 파일 | 역할 |
+|------|------|
+| `init/init.sql` | 초기 스키마 (5테이블) |
+| `init/migrate-v2.sql` | v2 마이그레이션 (7테이블 추가) |
+| `init/migrate-v3.sql` | v3 마이그레이션 (calendar_events 확장) |
+
+### 기타
+
+| 파일 | 역할 |
+|------|------|
+| `docker-compose.yml` | bot-n8n + bot-postgres 컨테이너 |
+| `manage_services.sh` | LaunchAgent 일괄 관리 |
+| `start-bridge.sh` | 브릿지 서비스 시작 스크립트 |
+| `init/setup-qdrant.sh` | Qdrant 3컬렉션 초기화 |
+| `.env.example` | 환경 변수 템플릿 |
+
+---
+
+## 서비스 기동 전 수동 설정 가이드
+
+맥북프로(또는 새 환경)에서 처음 기동할 때 필요한 설정.
+
+### 1. 사전 요구사항
+
+```
+# Homebrew
+brew install python@3.14
+
+# Python 가상환경
+python3 -m venv .venv
+source .venv/bin/activate
+pip install caldav aiohttp
+
+# Docker Desktop 설치 및 실행
+```
+
+### 2. NAS 설정 (192.168.1.227)
+
+- **Synology Chat**: Outgoing Webhook 생성 → URL: `http://<맥IP>:5678/webhook/chat`
+- **Synology Calendar**: `chatbot` 캘린더 생성 + CalDAV 접근용 계정
+- **MailPlus**: IMAP 접근용 계정 설정
+- **DSM Chat API**: chatbot-api 계정 생성 (사진 폴링용)
+
+### 3. macOS 앱 설정
+
+- **DEVONthink 4**: 설치 + 데이터베이스 열기 (AppleScript 접근 허용)
+- **OmniFocus**: 설치 + Inbox 사용 설정
+- **Ollama (맥미니)**: `ollama pull bge-m3 && ollama pull bge-reranker-v2-m3`
+
+### 4. GPU 서버 (192.168.1.186)
+
+- Ollama 설치 + `ollama pull qwen3.5:9b-q8_0`
+- 포트 11434 개방
+
+### 5. 환경 변수
+
+```bash
+cp .env.example .env
+# .env 파일의 모든 changeme / xxxxx 값을 실제 값으로 교체
+```
+
+### 6. Docker 기동 + DB 마이그레이션
+
+```bash
+docker compose up -d
+
+# 초기 DB 설정
+docker exec -i bot-postgres psql -U bot chatbot < init/init.sql
+docker exec -i bot-postgres psql -U bot chatbot < init/migrate-v2.sql
+docker exec -i bot-postgres psql -U bot chatbot < init/migrate-v3.sql
+
+# Qdrant 컬렉션 초기화
+bash init/setup-qdrant.sh
+```
+
+### 7. LaunchAgent 등록
+
+```bash
+# plist 파일 내 경로를 현재 환경에 맞게 수정
+# (WorkingDirectory, ProgramArguments의 Python/스크립트 경로)
+
+cp com.syn-chat-bot.*.plist ~/Library/LaunchAgents/
+bash manage_services.sh load
+```
+
+### 8. n8n 워크플로우 임포트
+
+1. `http://localhost:5678` 접속
+2. Settings → Import → `n8n/workflows/main-chat-pipeline.json`
+3. Settings → Import → `n8n/workflows/mail-processing-pipeline.json`
+4. 워크플로우 내 Credential 재설정 (PostgreSQL, HTTP Header Auth 등)
+5. 워크플로우 활성화
+
+### 9. 검증
+
+```bash
+# 브릿지 서비스 헬스체크
+curl http://localhost:8090/health   # heic_converter
+curl http://localhost:8091/health   # chat_bridge
+curl http://localhost:8092/health   # caldav_bridge
+curl http://localhost:8093/health   # devonthink_bridge
+
+# Docker 상태
+docker compose ps
+
+# DB 연결
+docker exec bot-postgres psql -U bot chatbot -c '\dt'
+```
+
+---
+
+## 다음 단계 (Phase 7+)
+
+- [ ] 전체 서비스 통합 테스트 (Synology Chat → n8n → 각 브릿지)
+- [ ] 분류기 v3 정확도 튜닝 (classification_logs 분석)
+- [ ] 비용 모니터링 대시보드 (api_usage_monthly 기반)
+- [ ] SLA 트래킹 스케줄 워크플로우 + 긴급 에스컬레이션
+- [ ] CalDAV 양방향 동기화
+- [ ] 메일 발송 (SMTP via MailPlus)
+- [ ] reminder 실구현 (알림 시간에 Synology Chat 푸시)
+- [ ] DEVONthink 검색 결과 RAG 연동