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)

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})

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)

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)

// 전체 아카이브 (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 테이블 관련 코드