# Architecture

## 전체 아키텍처

```
┌─────────────────────┐
│   Synology Chat     │  사용자 인터페이스
│   (NAS 192.168.1.227)│
└─────────┬───────────┘
          │ Outgoing Webhook
          ▼
┌────────────────────────────────────────────────────────────┐
│  bot-n8n (맥미니 Docker :5678) — 51노드 파이프라인          │
│                                                            │
│  ⓪ 토큰 검증 + Rate Limit (username별 10초/5건)            │
│                                                            │
│  ① 규칙 기반 프리필터                                       │
│     └─ 인사/감사 정규식 매칭 → 하드코딩 local 응답           │
│                                                            │
│  ② 명령어 체크 (/설정, /모델, /성격, /문서등록, /보고서)      │
│     └─ 권한 체크 (ADMIN_USERNAMES allowlist)                │
│                                                            │
│  ③ GPU Qwen 9B 분류 v3 (10초 타임아웃)                     │
│     → {intent, response_tier, needs_rag, rag_target, ...}  │
│     └─ 실패 시 fallback → api_light                        │
│                                                            │
│  ③-1 Route by Intent                                       │
│     ├─ log_event  → Qwen 추출 → bge-m3 → tk_company 저장   │
│     ├─ report     → 현장 리포트 → field_reports DB 저장      │
│     ├─ calendar   → CalDAV Bridge → Synology Calendar       │
│     ├─ reminder   → calendar로 통합 처리                     │
│     ├─ mail       → 메일 요약 조회 (mail_logs)               │
│     ├─ note       → DEVONthink Bridge → 문서 저장            │
│     └─ fallback   → 일반 대화 (RAG + 3단계 라우팅)           │
│                                                            │
│  ④ [needs_rag=true] 멀티-컬렉션 RAG 검색                   │
│     documents + tk_company + chat_memory                    │
│     → bge-m3 임베딩 → Qdrant 검색 → reranker → top-3       │
│                                                            │
│  ⑤ response_tier 3단계 분기                                 │
│     ├─ local     → Qwen 9B 직접 답변                       │
│     ├─ api_light → Claude Haiku                            │
│     └─ api_heavy → 예산 체크 → Claude Opus (or 다운그레이드) │
│                                                            │
│  ⑥ 응답 전송 + chat_logs + api_usage_monthly                │
│  ⑦ [비동기] Qwen 메모리 판단 → 가치 있으면 벡터화 + DEVONthink│
│     └─ classification_logs 기록                             │
└──┬──────────┬───────────┬───────────┬──────────────────────┘
   │          │           │           │
   ▼          ▼           ▼           ▼
┌──────┐ ┌────────┐ ┌─────────┐ ┌──────────────┐
│bot-  │ │Qdrant  │ │Ollama   │ │Ollama (GPU)  │
│postgres│ │:6333  │ │:11434   │ │192.168.1.186 │
│:15478│ │3컬렉션 │ │bge-m3   │ │:11434        │
│12테이블│ │documents│ │reranker│ │qwen3.5:9b    │
│      │ │tk_company││비전모델 │ │(분류+응답)    │
│      │ │chat_memory│        │ │              │
└──────┘ └────────┘ └─────────┘ └──────────────┘

┌────────────────────────────────────────────────────────────┐
│  별도 워크플로우                                            │
│  Mail Processing Pipeline (7노드)                          │
│    └─ MailPlus IMAP 폴링 → Qwen 분류 → mail_logs 저장      │
└────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────┐
│  네이티브 서비스 (맥미니)                                    │
│                                                            │
│  heic_converter.py (:8090)                                 │
│    └─ HEIC→JPEG 변환 (macOS sips)                          │
│                                                            │
│  chat_bridge.py (:8091)                                    │
│    ├─ DSM Chat API 폴링 (5초) → 사진 감지 + ack             │
│    ├─ POST /chat/recent-photo → 사진 다운+변환               │
│    └─ HEIC 자동 변환 (→ heic_converter :8090)               │
│                                                            │
│  caldav_bridge.py (:8092)                                  │
│    └─ CalDAV REST 래퍼 (Synology Calendar CRUD)             │
│                                                            │
│  devonthink_bridge.py (:8093)                              │
│    └─ DEVONthink AppleScript 래퍼 (문서 저장·검색)           │
│                                                            │
│  inbox_processor.py (LaunchAgent, 5분)                     │
│    └─ OmniFocus Inbox 폴링 → Qwen 분류 → 자동 정리          │
│                                                            │
│  news_digest.py (LaunchAgent, 매일 07:00)                  │
│    └─ RSS 뉴스 수집 → Qwen 번역·요약 → Qdrant + Synology Chat│
└────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────┐
│  NAS 서비스 (192.168.1.227)                     │
│  Synology Chat / Calendar (CalDAV) / MailPlus   │
└────────────────────────────────────────────────┘

┌────────────────────────────────────────────────┐
│  DEVONthink 4 (맥미니)                          │
│  AppleScript 경유 문서 저장·검색                  │
└────────────────────────────────────────────────┘
```

## 3단계 라우팅 상세

### response_tier 판단 (Qwen 9B 분류기 v2)

| tier | 모델 | 비용 | 대상 |
|------|------|------|------|
| **local** | Qwen 9B (GPU) | 무료 | 인사, 잡담, 단순 확인, 감사, 짧은 반응 |
| **api_light** | Claude Haiku | ~$0.8/1M in, $4/1M out | 요약, 번역, RAG 정리, 비교 분석 |
| **api_heavy** | Claude Opus | ~$15/1M in, $75/1M out | 법률 해석, 다중 문서 분석, 보고서 작성 |

**비용 최적화 목표:**
- ~40% → local (무료, 프리필터+Qwen 직접 답변)
- ~50% → Haiku (저비용)
- ~10% → Opus (복잡한 질문만)

### 분류기 v3 출력 스키마

```json
{
  "intent": "greeting|question|log_event|calendar|reminder|mail|note|photo|command|report|other",
  "response_tier": "local|api_light|api_heavy",
  "needs_rag": true,
  "rag_target": ["documents", "tk_company", "chat_memory"],
  "department_hint": "안전|생산|구매|품질|null",
  "report_domain": "안전|시설설비|품질|null",
  "query": "검색용 쿼리"
}
```

**Intent별 처리:**
- `calendar` — CalDAV Bridge로 일정 생성/조회 (Synology Calendar)
- `reminder` — calendar로 통합 (알림 시간 포함 일정 생성)
- `mail` — mail_logs에서 최근 메일 요약 조회
- `note` — DEVONthink Bridge로 문서 저장
```

### 프리필터 → 분류기 → 모델 라우팅 흐름

```
메시지 수신
  │
  ├─ 프리필터 매칭 (인사/감사 정규식)
  │   └─ 매칭 → 하드코딩 local 응답 (GPU 서버 미호출)
  │
  └─ 미매칭 → Qwen 9B 분류기
      ├─ response_tier=local → Qwen 9B 직접 답변
      ├─ response_tier=api_light → Claude Haiku
      └─ response_tier=api_heavy → 예산 체크
            ├─ 예산 내 → Claude Opus
            └─ 초과 → Claude Haiku (다운그레이드)
```

## 3-컬렉션 RAG 상세

### 컬렉션 구조

| 컬렉션 | 용도 | 벡터 차원 | 필터 |
|--------|------|----------|------|
| `documents` | 개인/일반 문서, 메일 요약 | 1024 (bge-m3) | 없음 |
| `tk_company` | TK 회사 문서, 현장 리포트 | 1024 (bge-m3) | department, year, doc_type |
| `chat_memory` | 가치 있는 대화 기억 | 1024 (bge-m3) | username, topic, intent |

### 멀티-컬렉션 검색 흐름

```
rag_target에 따라 동적 검색:
  - 단일 컬렉션 → top-10
  - 2개 → 각 top-7
  - 3개 → 각 top-5

각 컬렉션별 필터:
  - documents: 필터 없음
  - tk_company: department + year 필터
  - chat_memory: username 필터

합산 → bge-reranker 리랭킹 (실패 시 Qdrant score 정렬) → top-3

출처 표시:
  [회사/안전/절차서] 고소작업 안전절차 - "작업 전 반드시..."
  [개인문서] Safety Engineering - "Workers at height..."
  [이전대화/2026-03-10] "고소작업은 2m 이상..."
```

### tk_company payload

```
text, year(인덱스), department(인덱스), doc_type(인덱스),
title, source_file, file_hash, chunk_index, total_chunks,
uploaded_by, created_at(인덱스)
```

### chat_memory payload

```
text, feature, intent, username(인덱스), topic(인덱스), timestamp
```

## 선택적 대화 메모리

```
응답 전송 (즉시)
    ↓ [비동기]
Qwen 9B Memorization Check:
  "저장: 사실 정보, 결정사항, 선호, 지시, 기술 정보"
  "무시: 인사, 잡담, 날씨, 봇이 모른다고 답한 것"
  출력: {"save": true/false, "topic": "general|company|technical|personal"}
    ↓
Should Memorize?
  ├─ true  → bge-m3 Embed → chat_memory 저장
  └─ false → 스킵 (chat_logs에는 기록됨)
```

- local tier (인사 등)는 메모리 체크 자체를 스킵 (GPU 절약)

## DB 스키마 상세

### 기존 테이블 (v1)

```sql
-- ai_configs: feature별 모델/프롬프트 독립 관리
-- feature: 'classifier', 'chat', 'chat_local', 'calendar', 'mail_summary'

-- routing_rules: complexity 기반 라우팅 (레거시 호환)

-- prompts: 프롬프트 버전 관리
-- feature: 'classifier' v2 (활성), 'chat_local', 'memorize_check'

-- chat_logs: 대화 기록 (v2: +username, +response_tier)

-- mail_accounts: 메일 소스 관리 (Phase 6)
```

### 신규 테이블 (v2)

```sql
-- document_ingestion_log: 문서 등록 이력 + 버전 관리
--   file_hash 중복 체크, doc_group_key로 버전 연결
--   status: processing/completed/failed/deprecated

-- field_reports: 현장 리포트 (안전/시설설비/품질 통합)
--   domain, category, severity → SLA 자동 계산
--   due_at 기반 미처리 조회

-- classification_logs: 분류기 성능 모니터링
--   input_text (200자 제한), output_json (JSONB)
--   fallback_used, latency_ms

-- mail_logs: 메일 수신 로그 + 분류

-- calendar_events: 캘린더 이벤트

-- report_cache: 보고서 캐시 (domain + year_month UNIQUE)
--   동일 파라미터 재요청 → 캐시 반환, --force로 재생성

-- api_usage_monthly: API 사용량 + 예산 상한
--   year + month + tier UNIQUE
--   estimated_cost vs budget_limit 비교 → 다운그레이드

-- news_digest_log: 뉴스 요약 이력
--   source_url UNIQUE, translated_title, summary
--   published_at, processed_at, qdrant_point_id
```

### calendar_events 확장 (v3)

```sql
-- v3에서 추가된 컬럼:
--   caldav_uid: CalDAV 이벤트 UID (Synology Calendar 연동)
--   description: 이벤트 상세 설명
--   created_by: 생성 출처 (chat, caldav_sync, manual)
```

### SLA 기준표

| domain | severity | 처리 기한 |
|--------|----------|----------|
| 안전 | 상 | 24시간 |
| 안전 | 중 | 72시간 |
| 안전 | 하 | 7일 |
| 시설설비 | 상 | 48시간 |
| 시설설비 | 중 | 5일 |
| 시설설비 | 하 | 14일 |
| 품질 | 상 | 48시간 |
| 품질 | 중 | 5일 |
| 품질 | 하 | 14일 |

## 안전장치

### 보안
- **웹훅 토큰 검증**: SYNOLOGY_CHAT_TOKEN 비교, 불일치 → reject
- **명령어 권한 체크**: ADMIN_USERNAMES allowlist
- **서비스 포트 격리**: DB/Qdrant는 127.0.0.1 바인딩
- **classification_logs**: input 200자 제한

### 비용 폭주 방지
- **규칙 기반 프리필터**: GPU 서버 다운 시에도 잡담은 API 미호출
- **Rate Limit**: username별 10초/5건 (in-memory, workflow static data)
- **예산 상한**: api_usage_monthly → 초과 시 api_heavy→api_light 다운그레이드

### 파이프라인 복원력
- **분류기 fallback**: Qwen 10초 타임아웃 → {response_tier: "api_light"}
- **리랭커 fallback**: bge-reranker 실패 → Qdrant score 정렬
- **비전 모델 fallback**: 사진 분석 실패 → 사용자 설명만으로 구조화
- **HEIC 자동 변환**: macOS sips 기반 HEIC→JPEG 변환 (heic_converter.py, port 8090)
- **사진 브릿지**: chat_bridge.py가 DSM Chat API 폴링 → 사진 감지 → ack → n8n 요청 시 다운로드+변환+base64 반환
- **이미지 base64 변환**: Ollama API는 URL 미지원, chat_bridge가 자동 다운로드 후 base64 전달

## 메인 채팅 파이프라인 v3 (51노드)

```
Webhook POST /chat
    │
    ▼
[Parse Input] — 토큰 검증 + Rate Limit + channelId/userId 추출
    │
    ├─ rejected → [Reject Response] → Send + Respond
    │
    ▼
[Has Pending Doc?] — 문서 등록 대기
    │
    ├─ pending → [Process Document] → [Log Doc Ingestion] → Send + Respond
    │
    ▼
[Regex Pre-filter] — 인사/감사 정규식
    │
    ├─ match → [Pre-filter Response] → Send + Respond
    │
    ▼
[Is Command?]
    │
    ├─ true → [Parse Command] + 권한 체크
    │          ├─ DB 필요 → [Command DB Query] → [Format] → Send + Respond
    │          └─ 직접 → [Direct Response] → Send + Respond
    │
    └─ false → [Qwen Classify v3] (10초 타임아웃)
                │
                ├─ [Log Classification] (비동기, PostgreSQL)
                │
                ├─ [Route by Intent]
                │   ├─ log_event → [Handle Log Event] (Qwen 추출→임베딩→tk_company 저장→확인응답)
                │   ├─ report   → [Handle Field Report] → [Save Field Report DB]
                │   ├─ calendar → [Handle Calendar] → CalDAV Bridge → 확인응답
                │   ├─ reminder → [Handle Calendar] (calendar로 통합)
                │   ├─ mail     → [Handle Mail] → mail_logs 조회 → 요약응답
                │   ├─ note     → [Handle Note] → DEVONthink Bridge → 확인응답
                │   └─ fallback → [Needs RAG?]
                │
                ├─ needs_rag=true
                │   → [Get Embedding] → [Multi-Collection Search]
                │   → [Build RAG Context] (출처 표시)
                │
                └─ needs_rag=false
                    → [No RAG Context]
                │
                ▼
            [Route by Tier]
                ├─ local     → [Call Qwen Response]
                ├─ api_light → [Call Haiku]
                └─ api_heavy → [Call Opus] (예산 체크 포함)
                │
                ▼
            [Send to Chat] + [Respond Webhook] + [Log to DB]
            + [API Usage Log] (API tier만)
                │
                ▼ [비동기]
            [Memorization Check] → [Should Memorize?]
                ├─ true → [Embed & Save Memory] + [DEVONthink 저장]
                └─ false → (끝)
```

## 페르소나: 이드

### 전체 프롬프트 (api_light/api_heavy)

```
당신의 이름은 "이드"입니다.

[성격]
- 배려심이 깊고 대화 상대의 기분을 우선시합니다
- 서포트하는 데 초점을 맞추며, 독선적이지 않습니다
- 의견을 제시할 때는 부드럽게, 강요하지 않습니다
- 틀린 것을 바로잡을 때도 상대방이 기분 나쁘지 않게 합니다

[말투]
- 부드러운 존댓말을 사용합니다
- 자신을 지칭할 때 겸양어를 씁니다
- 자기 이름을 직접 말하지 않습니다
- 자연스럽고 편안한 톤
- 이모지는 가끔 핵심 포인트에만 사용합니다

[응답 원칙]
- 간결하고 핵심적으로 답합니다
- 질문의 의도를 파악해서 필요한 만큼만 답합니다
- 모르는 것은 솔직하게, 추측은 추측이라고 밝힙니다
```

### 경량 프롬프트 (local tier)

```
당신은 "이드"입니다. 배려심 깊고 부드러운 존댓말을 사용하는 개인 어시스턴트입니다.
간결하게 답하고, 모르면 솔직히 말하세요. 이모지는 핵심에만.
```

## 구현 완료

### Phase 4: 회사 문서 등록
- `/문서등록 [부서] [유형] [제목]` → 청킹 → tk_company 저장
- hash 중복 체크, 문서 버전 관리

### Phase 5: 현장 리포팅 + API 사용량 추적
- 사진 + 텍스트 → Claude Haiku Vision → 구조화 → field_reports + tk_company
- `/보고서 [영역] [년월]` → 월간 보고서 생성 (report_cache)
- API 사용량 추적 (api_usage_monthly UPSERT)
- HEIC→JPEG 변환 (heic_converter.py) + chat_bridge.py (DSM Chat API 브릿지)

### Phase 6: 캘린더·메일·DEVONthink·OmniFocus·뉴스
- 분류기 v3: calendar, reminder, mail, note intent 추가
- caldav_bridge.py: CalDAV REST 래퍼 (Synology Calendar CRUD)
- devonthink_bridge.py: DEVONthink AppleScript 래퍼
- inbox_processor.py: OmniFocus Inbox 폴링 (LaunchAgent, 5분)
- news_digest.py: 뉴스 번역·요약 (LaunchAgent, 매일 07:00)
- Mail Processing Pipeline (7노드): IMAP 폴링 → 분류 → mail_logs
- 51노드 파이프라인: calendar/mail/note 핸들러 추가

## 향후 기능 (Phase 7+)

- SLA 트래킹 스케줄 워크플로우 + 긴급 에스컬레이션
- CalDAV 양방향 동기화 (Synology Calendar → bot-postgres)
- 메일 발송 (SMTP via MailPlus)
- reminder 실구현 (알림 시간에 Synology Chat 푸시)
- DEVONthink 검색 결과 RAG 연동
