telegram-bot-workers/docs/plans/2026-02-05-conversation-storage-design.md

# 대화 저장 시스템 리팩토링 설계

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 기존 요약 기반 대화 저장을 전체 대화 기록 보존 시스템으로 전환

**Architecture:** 사용자별 동적 테이블 생성 + 메타 테이블 관리 + 6개월 후 아카이브

**Tech Stack:** Cloudflare Workers, D1 SQLite, OpenAI GPT-4o-mini

---

## 1. 데이터베이스 구조

### 메타 테이블 (`conversation_tables`)
```sql
CREATE TABLE conversation_tables (
  telegram_id TEXT PRIMARY KEY,
  table_name TEXT NOT NULL,           -- conv_123456789
  message_count INTEGER DEFAULT 0,
  last_message_at DATETIME,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_conv_tables_last_msg ON conversation_tables(last_message_at DESC);
```

### 동적 사용자 테이블 (`conv_{telegram_id}`)
```sql
CREATE TABLE conv_{telegram_id} (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  role TEXT NOT NULL CHECK(role IN ('user', 'assistant')),
  content TEXT NOT NULL,
  tool_calls TEXT,      -- JSON: [{name, arguments, id}]
  tool_results TEXT,    -- JSON: [{tool_call_id, result}]
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_conv_{telegram_id}_created ON conv_{telegram_id}(created_at DESC);
```

### 기존 테이블 변경
- `message_buffer`: 마이그레이션 후 삭제
- `summaries`: 유지 (아카이브 요약 저장용)

---

## 2. 서비스 구조

### ConversationService (`src/services/conversation-service.ts`)

```typescript
interface ConversationMessage {
  id?: number;
  role: 'user' | 'assistant';
  content: string;
  tool_calls?: string;    // JSON
  tool_results?: string;  // JSON
  created_at?: string;
}

// 테이블 생성/확인
export async function ensureConversationTable(db: D1Database, telegramId: string): Promise<string>

// 메시지 저장
export async function saveMessage(db: D1Database, telegramId: string, message: ConversationMessage): Promise<void>

// 최근 메시지 조회
export async function getRecentMessages(db: D1Database, telegramId: string, limit: number): Promise<ConversationMessage[]>

// 키워드 검색
export async function searchRelevantMessages(db: D1Database, telegramId: string, keywords: string[], limit: number): Promise<ConversationMessage[]>

// 스마트 컨텍스트 (최근 20개 + 관련 10개)
export async function getSmartContext(db: D1Database, telegramId: string, currentMessage: string): Promise<ConversationMessage[]>

// 통계 조회
export async function getConversationStats(db: D1Database, telegramId: string): Promise<ConversationStats>
```

### ArchiveService (`src/services/archive-service.ts`)

```typescript
// 전체 아카이브 (Cron)
export async function archiveOldConversations(env: Env): Promise<ArchiveResult>

// 사용자별 아카이브
export async function archiveUserConversations(env: Env, telegramId: string, olderThanDays: number): Promise<number>

// 아카이브 요약 생성
export async function generateArchiveSummary(env: Env, messages: ConversationMessage[]): Promise<string>
```

---

## 3. 아카이브 정책

- **트리거**: 6개월(180일) 이상 된 대화
- **주기**: 매일 UTC 15:00 (KST 00:00)
- **단위**: 100개 메시지씩 요약
- **저장**: summaries 테이블에 기간 정보 포함

### 아카이브 프로세스
```
1. conversation_tables 순회
2. 각 conv_{id}에서 180일 이상 된 메시지 조회
3. 100개 단위로 AI 요약 생성
4. summaries에 저장: "[2024-01-01 ~ 2024-06-30 아카이브] 요약내용..."
5. 원본 메시지 삭제
6. message_count 업데이트
```

---

## 4. AI 컨텍스트 구성

### 스마트 컨텍스트 알고리즘
```
1. 최근 20개 메시지 가져오기
2. 현재 메시지에서 키워드 추출 (명사, 2글자 이상, 최대 5개)
3. 키워드로 과거 대화 검색 (LIKE %keyword%)
4. 관련 대화 최대 10개 추가
5. 중복 제거 + 시간순 정렬
6. 아카이브 요약도 컨텍스트에 포함
```

### 키워드 추출
- 불용어 제외: 은, 는, 이, 가, 을, 를, 에, 도, 로, 의, 와, 과
- 최소 2글자 이상
- 최대 5개 키워드

---

## 5. 사용자 명령어

| 명령어 | 설명 |
|--------|------|
| `/history` | 최근 20개 대화 조회 |
| `/history N` | 최근 N개 대화 조회 |
| `/search 키워드` | 키워드로 대화 검색 |
| `/stats` | 대화 통계 (총 메시지, 첫 대화일 등) |

---

## 6. 마이그레이션 계획

### Step 1: 스키마 생성
- `conversation_tables` 메타 테이블 생성

### Step 2: 데이터 이동
- 기존 `message_buffer` 데이터 → 각 사용자 `conv_{id}` 테이블로 이동
- 기존 사용자 목록 기반으로 테이블 생성

### Step 3: 코드 배포
- conversation-service.ts 추가
- archive-service.ts 추가
- summary-service.ts 수정
- index.ts 수정
- commands.ts 수정

### Step 4: 정리
- message_buffer 테이블 삭제 (검증 후)

---

## 7. 파일 변경 목록

### 신규 파일
- `src/services/conversation-service.ts`
- `src/services/archive-service.ts`
- `migrations/008_conversation_tables.sql`

### 수정 파일
- `src/summary-service.ts` - getSmartContext 사용으로 변경
- `src/index.ts` - saveMessage 호출로 변경
- `src/commands.ts` - /history, /search, /stats 추가
- `src/types.ts` - ConversationMessage 타입 추가

### 삭제 (마이그레이션 후)
- `message_buffer` 테이블 관련 코드