From a04275cc76f1cb93dcf4e75d56227bb64e195a3e Mon Sep 17 00:00:00 2001
From: hhs <386998068@qq.com>
Date: Fri, 19 Jun 2026 15:31:52 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8C=89=E5=8A=9F=E8=83=BD=E6=A8=A1?=
 =?UTF-8?q?=E5=9D=97=E9=87=8D=E6=9E=84=E6=96=87=E6=A1=A3=E7=BB=93=E6=9E=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新建 01-架构设计.md：合并项目概述+系统架构+持久化设计，含 Mermaid 架构图、模块图、时序图、ER 图、部署图
- 新建 02-接口文档.md：合并接口文档+持久化 API+用户模块 API，统一格式去重
- 重编号 03~09，去掉状态标注，规划中功能标记为待实现
- 删除 PLAN_BACKEND.md、PLAN_USER_MODULE.md 及冗余文档
---
 docs/01-架构设计.md                     |  389 +++++++
 docs/01-项目概述.md                     |   28 -
 docs/{03-接口文档.md => 02-接口文档.md} |  788 +++----------
 docs/02-系统架构.md                     |  256 -----
 docs/{04-技术选型.md => 03-技术选型.md} |   12 +-
 docs/{05-用户故事.md => 04-用户故事.md} |    0
 docs/{06-语音交互.md => 05-语音交互.md} |    2 +-
 docs/{07-视觉理解.md => 06-视觉理解.md} |    0
 docs/{08-成本控制.md => 07-成本控制.md} |   10 +-
 docs/{10-功能创意.md => 08-功能创意.md} |    0
 docs/11-持久化与用户系统设计.md         |  751 ------------
 docs/PLAN_BACKEND.md                    |  223 ----
 docs/PLAN_USER_MODULE.md                | 1381 -----------------------
 docs/README.md                          |   56 +-
 14 files changed, 606 insertions(+), 3290 deletions(-)
 create mode 100644 docs/01-架构设计.md
 delete mode 100644 docs/01-项目概述.md
 rename docs/{03-接口文档.md => 02-接口文档.md} (61%)
 delete mode 100644 docs/02-系统架构.md
 rename docs/{04-技术选型.md => 03-技术选型.md} (97%)
 rename docs/{05-用户故事.md => 04-用户故事.md} (100%)
 rename docs/{06-语音交互.md => 05-语音交互.md} (97%)
 rename docs/{07-视觉理解.md => 06-视觉理解.md} (100%)
 rename docs/{08-成本控制.md => 07-成本控制.md} (90%)
 rename docs/{10-功能创意.md => 08-功能创意.md} (100%)
 delete mode 100644 docs/11-持久化与用户系统设计.md
 delete mode 100644 docs/PLAN_BACKEND.md
 delete mode 100644 docs/PLAN_USER_MODULE.md

diff --git a/docs/01-架构设计.md b/docs/01-架构设计.md
new file mode 100644
index 0000000..f770b43
--- /dev/null
+++ b/docs/01-架构设计.md
@@ -0,0 +1,389 @@
+# 架构设计
+
+## 项目概述
+
+CamTalk 是一款**多模态实时 AI 视觉对话助手**。用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后，以文字和语音形式给出自然回应。
+
+核心挑战在于三个维度之间的张力：
+
+| 维度 | 关键问题 |
+|------|---------|
+| 视觉理解 | 如何准确理解摄像头画面中的人物、物体、场景？ |
+| 语音交互 | 如何让对话像真人交流一样自然、低延迟？ |
+| 成本控制 | 实时视频流 + LLM 推理，如何避免账单爆炸？ |
+
+## 系统架构
+
+三层架构：**前端做轻量预处理，后端做智能编排，云端 AI 服务按需调用**。
+
+```mermaid
+graph TB
+    subgraph Browser["浏览器客户端"]
+        UI["UI 渲染层<br/>React 18 + TypeScript"]
+        Edge["边缘预处理层<br/>VAD / 关键帧检测"]
+        Media["媒体采集层<br/>Camera / Microphone"]
+    end
+
+    subgraph Gateway["Go 网关"]
+        WS["WebSocket Handler<br/>连接管理 / 消息分发"]
+        Session["Session Manager<br/>会话状态 / 对话历史"]
+        Orch["AI Orchestrator<br/>STT→LLM→TTS 流式并行"]
+        Auth["Auth 模块<br/>JWT / bcrypt"]
+        REST["REST API<br/>健康检查 / 对话管理"]
+        Store["Store 层<br/>Repository 接口"]
+    end
+
+    subgraph AI["云端 AI 服务"]
+        STT["STT<br/>Deepgram / MiMo ASR"]
+        LLM["LLM<br/>GPT-4o / 通义千问"]
+        TTS["TTS<br/>OpenAI TTS / MiMo TTS"]
+    end
+
+    subgraph Storage["存储层"]
+        Mem["Memory<br/>进程内缓存"]
+        Redis["Redis<br/>会话状态"]
+        PG["PostgreSQL<br/>持久化存储"]
+    end
+
+    Media --> Edge
+    Edge -->|"query (image+audio)"| WS
+    UI <-->|"WebSocket"| WS
+    WS --> Session
+    WS --> Orch
+    Orch --> STT
+    Orch --> LLM
+    Orch --> TTS
+    Session --> Store
+    Store --> Mem
+    Store --> Redis
+    Store --> PG
+    REST --> Session
+    WS --> Auth
+```
+
+> 为什么单独加一层 Go 网关，而不是让前端直连 AI API？1）API Key 安全性；2）统一的速率限制和成本管控；3）多模型路由逻辑集中在一处便于维护。
+
+## 核心交互流程
+
+一次完整的"用户提问 → AI 回答"流程：
+
+```mermaid
+sequenceDiagram
+    participant B as 浏览器
+    participant G as Go 网关
+    participant S as STT
+    participant L as LLM
+    participant T as TTS
+
+    B->>B: VAD 检测到语音结束
+    B->>G: query {image, audio}
+    G->>S: 音频流
+    S-->>G: 流式文本
+    G-->>B: stt_result {text}
+
+    G->>L: [图像 + 文本 + 上下文]
+    loop LLM 流式输出
+        L-->>G: token delta
+        G-->>B: llm_chunk {delta}
+    end
+    G-->>B: llm_done {full_text, tokens}
+
+    par LLM 输出的同时
+        G->>G: 句子切分器检测到完整句子
+        G->>T: 句子文本
+        T-->>G: 音频 chunk
+        G-->>B: tts_audio {audio}
+    end
+    G-->>B: tts_audio {final: true}
+```
+
+**关键优化**：LLM 文本流和 TTS 音频流**并行推送**——客户端先逐 token 展示文字，同时 TTS 逐句子合成并推送音频，用户感知延迟大幅降低。
+
+## 技术栈
+
+### 前端
+
+| 技术 | 选型 | 选择理由 |
+|------|------|---------|
+| 框架 | React 18 + TypeScript | 组件化开发，类型安全，生态成熟 |
+| 构建 | Vite | 开发热更新快，构建产物小 |
+| 实时通信 | WebSocket（原生 API） + 自封装连接管理 | 浏览器原生支持，封装心跳/重连/消息分发 |
+| 语音检测 | @ricky0123/vad-web | 基于 WebRTC VAD，纯前端零延迟 |
+| 媒体采集 | MediaDevices API | 浏览器原生摄像头/麦克风访问 |
+
+### 后端
+
+| 技术 | 选型 | 选择理由 |
+|------|------|---------|
+| 语言 | Go | 高并发 goroutine 模型，适合长连接管理 |
+| HTTP 框架 | Gin | 高性能 HTTP 路由，中间件生态成熟 |
+| WebSocket | gorilla/websocket | Go 生态最成熟的 WebSocket 库 |
+| 会话存储 | Memory（默认） / Redis | 进程内存零依赖，Redis 支持多实例部署 |
+| 持久化存储 | PostgreSQL | 对话历史、用户数据、会话元数据 |
+| 配置管理 | Viper + godotenv | 支持 YAML + .env + 环境变量覆盖 |
+| 日志 | Zap | 高性能结构化日志 |
+
+### AI 服务
+
+| 能力 | 默认方案 | 备选方案 |
+|------|---------|---------|
+| 多模态 LLM | GPT-4o | 通义千问等 OpenAI 兼容模型 |
+| 语音识别 STT | Deepgram | MiMo ASR（小米） |
+| 语音合成 TTS | OpenAI TTS | MiMo TTS（小米） |
+
+> Go 网关的 AI 服务层统一封装不同服务商的调用接口，通过配置切换 provider。
+
+## 后端模块
+
+```mermaid
+graph LR
+    subgraph Entry["入口层"]
+        Main["main.go<br/>依赖注入 / 启动"]
+    end
+
+    subgraph Transport["传输层"]
+        WSH["WebSocket Handler<br/>连接管理 / 认证"]
+        APH["REST API Handlers<br/>Auth / Conversation / Health"]
+    end
+
+    subgraph Business["业务层"]
+        SM["Session Manager<br/>会话生命周期"]
+        ORCH["Orchestrator<br/>STT→LLM→TTS 编排"]
+        AS["Auth Service<br/>注册/登录/刷新/登出"]
+    end
+
+    subgraph AI_Layer["AI 服务层"]
+        STT_S["STT Service<br/>Deepgram / MiMo"]
+        LLM_S["LLM Service<br/>OpenAI 兼容"]
+        TTS_S["TTS Service<br/>OpenAI / MiMo"]
+    end
+
+    subgraph Data["数据层"]
+        UR["UserRepository"]
+        MR["MessageRepository"]
+        SR["SessionRepository"]
+    end
+
+    Main --> WSH
+    Main --> APH
+    Main --> SM
+    Main --> ORCH
+    Main --> AS
+
+    WSH --> SM
+    WSH --> ORCH
+    APH --> SM
+    APH --> AS
+    ORCH --> STT_S
+    ORCH --> LLM_S
+    ORCH --> TTS_S
+    SM --> MR
+    SM --> SR
+    AS --> UR
+```
+
+| 模块 | 职责 |
+|------|------|
+| WebSocket Handler | 管理客户端连接生命周期，JWT 认证，conversation_id 恢复，单播消息推送 |
+| Session Manager | 维护用户会话状态、对话历史。Memory（默认）/ Redis（可切换），30 分钟 TTL，Write-Through 到 PG |
+| AI Orchestrator | 编排 STT→LLM→TTS 流式并行管道，context 取消 + 超时控制 + 句子切分 |
+| AI Service Layer | AI 服务抽象层，多 provider 支持（Deepgram/MiMo/OpenAI 等） |
+| Auth | 用户认证与授权。JWT (HS256) 双 token 轮转，bcrypt 密码哈希，Gin 中间件 |
+| Store | 持久化存储层。UserRepository / MessageRepository / SessionRepository，内存 + PostgreSQL 双实现 |
+| REST API | 健康检查、认证、对话管理端点 |
+| Logger | Zap 结构化日志 |
+| Models | 数据模型定义 |
+| Migrations | 数据库版本化迁移，嵌入式 SQL 文件自动执行 |
+| Model Router | 根据请求类型选择 AI 模型（待实现） |
+| Rate Limiter | 令牌桶限流（待实现） |
+
+## 前端组件
+
+| 组件 | 职责 |
+|------|------|
+| AuthPage | 登录/注册表单 |
+| CameraManager | 摄像头流采集 |
+| MicManager | 麦克风音频采集 |
+| EdgeProcessor | VAD + 关键帧检测（Canvas 像素比较） |
+| WebSocketManager | WS 连接生命周期管理 |
+| ChatPanel | 消息展示、流式回复、文本输入、场景选择 |
+| VideoPreview | 摄像头画面预览 |
+| SessionSidebar | 左侧抽屉式对话列表（搜索、重命名、删除） |
+| ConfigPanel | 右侧抽屉式配置面板（主题、TTS 开关、detail level、语言、场景、账户） |
+| Toast | 轻量通知提示（3 秒自动消失） |
+
+核心 Hook：`useVisionSession()` 封装一次完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态、认证、场景模式）。
+
+## 数据库设计
+
+### ER 关系
+
+```mermaid
+erDiagram
+    users ||--o{ sessions : "1:N"
+    users ||--o{ refresh_tokens : "1:N"
+    sessions ||--o{ messages : "1:N"
+
+    users {
+        uuid id PK
+        varchar username UK
+        varchar password_hash
+        timestamptz created_at
+        timestamptz updated_at
+    }
+
+    sessions {
+        uuid id PK
+        uuid user_id FK
+        varchar title
+        jsonb config
+        timestamptz created_at
+        timestamptz updated_at
+    }
+
+    messages {
+        bigserial id PK
+        uuid session_id FK
+        varchar role
+        text content
+        integer tokens_used
+        timestamptz created_at
+    }
+
+    refresh_tokens {
+        bigserial id PK
+        uuid user_id FK
+        varchar token_hash UK
+        timestamptz expires_at
+        timestamptz created_at
+    }
+```
+
+### 表结构
+
+```sql
+-- 用户表
+CREATE TABLE users (
+    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    username      VARCHAR(64) NOT NULL UNIQUE,
+    password_hash VARCHAR(256) NOT NULL,
+    created_at    TIMESTAMPTZ DEFAULT now(),
+    updated_at    TIMESTAMPTZ DEFAULT now()
+);
+
+-- 会话表
+CREATE TABLE sessions (
+    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    title      VARCHAR(128) DEFAULT '新对话',
+    config     JSONB DEFAULT '{}',
+    created_at TIMESTAMPTZ DEFAULT now(),
+    updated_at TIMESTAMPTZ DEFAULT now()
+);
+
+-- 消息表
+CREATE TABLE messages (
+    id          BIGSERIAL PRIMARY KEY,
+    session_id  UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+    role        VARCHAR(16) NOT NULL,
+    content     TEXT NOT NULL,
+    tokens_used INTEGER DEFAULT 0,
+    created_at  TIMESTAMPTZ DEFAULT now()
+);
+
+-- 刷新令牌表
+CREATE TABLE refresh_tokens (
+    id          BIGSERIAL PRIMARY KEY,
+    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    token_hash  VARCHAR(256) NOT NULL UNIQUE,
+    expires_at  TIMESTAMPTZ NOT NULL,
+    created_at  TIMESTAMPTZ DEFAULT now()
+);
+```
+
+### 存储策略
+
+| 场景 | 存储方案 | 说明 |
+|------|---------|------|
+| 默认 | Memory（进程内） | 零依赖，快速启动。MemoryManager 支持 Write-Through 到 PG |
+| 持久化 | Memory + PostgreSQL | 通过 `storage.driver: postgres` 启用，MemoryManager 注入 PG Repository |
+| 多实例 | Redis（独立） | 通过配置切换到 RedisManager，适合多实例部署 |
+
+冷热分离：Redis/Memory 存"热数据"（当前对话上下文，微秒级读写），PostgreSQL 存"冷数据"（历史记录）。MemoryManager 的 Write-Through 机制确保每次 AppendMessage 同时写入 PG，重启后可从 PG 恢复会话。
+
+## 认证设计
+
+```mermaid
+sequenceDiagram
+    participant C as 客户端
+    participant G as Go 网关
+    participant DB as PostgreSQL
+
+    Note over C,DB: 注册流程
+    C->>G: POST /api/auth/register {username, password}
+    G->>G: bcrypt hash 密码
+    G->>DB: INSERT users
+    G->>G: 生成 access_token + refresh_token
+    G->>DB: 存 SHA256(refresh_token)
+    G-->>C: {user, access_token, refresh_token}
+
+    Note over C,DB: 登录流程
+    C->>G: POST /api/auth/login {username, password}
+    G->>DB: 查 users by username
+    G->>G: bcrypt.CompareHashAndPassword
+    G->>G: 生成 token pair
+    G->>DB: 存 SHA256(refresh_token)
+    G-->>C: {user, access_token, refresh_token}
+
+    Note over C,DB: Token 刷新（轮转）
+    C->>G: POST /api/auth/refresh {refresh_token}
+    G->>G: 校验签名和过期
+    G->>DB: 验证 hash 存在
+    G->>DB: 撤销旧 refresh_token
+    G->>G: 生成新 token pair
+    G->>DB: 存新 refresh_token hash
+    G-->>C: {access_token, refresh_token}
+```
+
+**Token 策略**：access_token 15 分钟有效，refresh_token 7 天有效。refresh 时旧 token 失效（轮转），防止重放攻击。
+
+**WebSocket 认证**：连接地址 `ws://host/ws?token=<access_token>&conversation_id=<uuid>`。HTTP Upgrade 前校验 token，失败返回 401。
+
+## 部署架构
+
+```mermaid
+graph TB
+    User["用户浏览器"] --> Nginx
+
+    subgraph Nginx["Nginx 反向代理"]
+        Static["/ → 前端静态资源"]
+        API["/api/* → Go Gateway"]
+        WS_Proxy["/ws → Go Gateway"]
+    end
+
+    subgraph Gateway_Pool["Go Gateway 实例"]
+        G1["Gateway-1"]
+        G2["Gateway-2"]
+        GN["Gateway-N"]
+    end
+
+    Nginx --> G1
+    Nginx --> G2
+    Nginx --> GN
+
+    G1 --> Redis
+    G2 --> Redis
+    GN --> Redis
+
+    G1 --> PG_DB["PostgreSQL"]
+    G2 --> PG_DB
+    GN --> PG_DB
+
+    G1 --> AI_Services["AI Services（外部 API）"]
+    G2 --> AI_Services
+    GN --> AI_Services
+```
+
+**跨域策略**：Nginx 将前端（`/`）、REST API（`/api/*`）、WebSocket（`/ws`）统一反代到同一域名，浏览器无跨域问题。
+
+**开发环境**：前端 Vite :5173 通过 `server.proxy` 转发 `/ws` 和 `/api` 到后端 :8080，无需硬编码端口。
diff --git a/docs/01-项目概述.md b/docs/01-项目概述.md
deleted file mode 100644
index 8a5a2c9..0000000
--- a/docs/01-项目概述.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# 项目概述
-
-## 概述
-
-开发一款**多模态实时对话应用**——通过摄像头与麦克风捕获用户的视觉场景与语音输入，由 AI 理解并给出自然、流畅的回应。
-
-核心挑战在于三个维度之间的张力：
-
-| 维度 | 关键问题 | 详见 |
-|------|---------|------|
-| 视觉理解 | 如何准确理解摄像头画面中的人物、物体、场景？ | `07-视觉理解.md` |
-| 语音交互 | 如何让对话像真人交流一样自然、低延迟？ | `06-语音交互.md` |
-| 成本控制 | 实时视频流 + LLM 推理，如何避免账单爆炸？ | `08-成本控制.md` |
-
-> 提升视觉精度意味着更高分辨率和更频繁的采样，但这会直接推高带宽和推理成本。架构设计需要在三者之间做好取舍。
-
-## 项目目标
-
-1. **用户故事规划**：明确"AI 能看、能听、能说"需要覆盖哪些场景 → `05-用户故事.md`
-2. **成本控制策略**：从架构设计层面融入运营成本意识 → `08-成本控制.md`
-
-## 交付物
-
-- 可运行的应用程序（摄像头 + 麦克风 → AI 回应）
-- 设计文档，覆盖：
-  - 计划实现 vs 最终实现的用户故事
-  - 成本控制技巧的构思 vs 实际采用的方案
-  - 项目架构设计与技术选型
diff --git a/docs/03-接口文档.md b/docs/02-接口文档.md
similarity index 61%
rename from docs/03-接口文档.md
rename to docs/02-接口文档.md
index 1efe171..071a75e 100644
--- a/docs/03-接口文档.md
+++ b/docs/02-接口文档.md
@@ -2,11 +2,11 @@
 
 ## 概述
 
-前后端通信接口定义。以 WebSocket 承载实时对话，REST 端点支撑基础运维。持久化已通过 PostgreSQL 实现，MemoryManager 支持 Write-Through 模式。
+前后端通信接口定义。以 WebSocket 承载实时对话，REST 端点支撑基础运维。持久化通过 PostgreSQL 实现，MemoryManager 支持 Write-Through 模式。
 
 **设计原则**：
 - WebSocket 为主：所有对话数据走 WebSocket
-- REST 为辅：仅用于健康检查、会话管理等低频操作
+- REST 为辅：仅用于健康检查、认证、对话管理等低频操作
 - 接口先行：先定义契约，再填充实现——前后端可并行开发
 
 ## 接口全景
@@ -20,7 +20,6 @@
                            /api/conversations/*
   HTTP Client       <-->  GET /api/conversations/:id   （历史消息）
                            /messages
-  HTTP Client       ~~>   POST/DELETE /api/sessions    （已废弃，保留兼容）
 ```
 
 ---
@@ -34,8 +33,6 @@
 | `token` | 是 | JWT access_token，缺失或无效时返回 401 |
 | `conversation_id` | 否 | 恢复已有对话；省略则创建新对话 |
 
-> 详见"REST API → WebSocket 认证变更"章节。
-
 ### 消息格式约定
 
 所有 WebSocket 消息均为 JSON 文本帧，统一结构：
@@ -79,7 +76,7 @@ interface ConfigMessage {
     tts_enabled?: boolean;         // 是否开启语音合成，默认 true
     detail_level?: "low" | "high"; // 图像精度，默认 "low"
     language?: string;             // 交互语言，默认 "zh-CN"
-    scenario?: string;             // 场景模式，可选值：free_chat / interviewer / english_teacher / debate / interpreter
+    scenario?: string;             // 场景模式：free_chat / interviewer / english_teacher / debate / interpreter
   };
 }
 ```
@@ -175,7 +172,7 @@ interface TTSAudioMessage {
 
 | 属性 | 值 | 说明 |
 |------|------|------|
-| 编码 | `audio/mp3`（MP3） | 浏览器 `<audio>` 原生支持，OpenAI TTS 默认输出 |
+| 编码 | `audio/mp3`（MP3） | 浏览器 `<audio>` 原生支持 |
 | 采样率 | 24kHz | OpenAI TTS 默认 |
 | 声道 | 单声道 | 语音不需要立体声 |
 | 传输 | Base64 编码的 MP3 片段 | 每个 `tts_audio` 消息携带一个句子的音频 |
@@ -199,11 +196,10 @@ class AudioPlayer {
   enqueue(base64: string, isLast: boolean) {
     this.sentenceChunks.push(base64);
     if (isLast) {
-      // 当前句子音频完整，拼接并加入播放队列
       const url = decodeBase64Audio(this.sentenceChunks.join(""), "audio/mp3");
       this.sentenceChunks = [];
       this.queue.push(url);
-      if (this.queue.length === 1) this.playNext(); // 第一句到了就开始播
+      if (this.queue.length === 1) this.playNext();
     }
   }
 
@@ -352,18 +348,6 @@ interface AuthResponse {
 }
 ```
 
-```json
-{
-  "user": {
-    "id": "550e8400-e29b-41d4-a716-446655440000",
-    "username": "alice",
-    "created_at": "2026-06-14T10:00:00Z"
-  },
-  "access_token": "eyJhbGciOiJIUzI1NiIs...",
-  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
-}
-```
-
 **错误响应**：
 
 | 状态码 | code | 场景 |
@@ -467,7 +451,7 @@ GET /api/conversations?page=1&size=20
 ```typescript
 interface ConversationListResponse {
   conversations: ConversationSummary[];
-  total: number;  // 总条数
+  total: number;
   page: number;
   size: number;
 }
@@ -481,29 +465,6 @@ interface ConversationSummary {
 }
 ```
 
-```json
-{
-  "conversations": [
-    {
-      "id": "550e8400-e29b-41d4-a716-446655440000",
-      "title": "这是一朵红色的玫瑰…",
-      "last_message": "它看起来很美丽。",
-      "message_count": 4,
-      "updated_at": "2026-06-14T10:05:30Z"
-    }
-  ],
-  "total": 1,
-  "page": 1,
-  "size": 20
-}
-```
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
-
 #### 创建对话
 
 ```
@@ -534,29 +495,10 @@ interface ConversationDetail {
     detail_level: "low" | "high";
     language: string;
   };
-  created_at: string;  // ISO 8601
+  created_at: string;
 }
 ```
 
-```json
-{
-  "id": "660e8400-e29b-41d4-a716-446655440001",
-  "title": "新对话",
-  "config": {
-    "tts_enabled": true,
-    "detail_level": "low",
-    "language": "zh-CN"
-  },
-  "created_at": "2026-06-14T11:00:00Z"
-}
-```
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
-
 #### 获取对话详情
 
 ```
@@ -569,7 +511,6 @@ GET /api/conversations/:id
 
 | 状态码 | code | 场景 |
 |--------|------|------|
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
 | 404 | `SESSION_NOT_FOUND` | 对话不存在或不属于当前用户 |
 
 #### 更新对话标题
@@ -601,7 +542,6 @@ interface UpdateTitleRequest {
 | 状态码 | code | 场景 |
 |--------|------|------|
 | 400 | `INVALID_INPUT` | title 为空或超长 |
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
 | 404 | `SESSION_NOT_FOUND` | 对话不存在或不属于当前用户 |
 
 #### 删除对话
@@ -612,13 +552,6 @@ DELETE /api/conversations/:id
 
 **成功响应** `204 No Content`（无响应体）。
 
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
-| 404 | `SESSION_NOT_FOUND` | 对话不存在或不属于当前用户 |
-
 #### 获取对话消息
 
 ```
@@ -630,84 +563,27 @@ GET /api/conversations/:id/messages?limit=50&before=<message_id>
 | 参数 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `limit` | int | 50 | 返回条数，最大 100 |
-| `before` | int64 | — | 游标分页：返回此 message_id 之前的消息（不含），用于加载更多 |
+| `before` | int64 | — | 游标分页：返回此 message_id 之前的消息（不含） |
 
 **成功响应** `200 OK`：
 
 ```typescript
 interface MessagesResponse {
   messages: StoredMessage[];
-  has_more: boolean;  // 是否还有更早的消息
+  has_more: boolean;
 }
 
 interface StoredMessage {
   id: number;           // 自增 ID，用于游标分页
   role: "user" | "assistant";
   content: string;
-  tokens_used: number;  // 该条消息消耗的 token 数
+  tokens_used: number;
   created_at: string;   // ISO 8601
 }
 ```
 
-```json
-{
-  "messages": [
-    {
-      "id": 1001,
-      "role": "user",
-      "content": "这是什么花？",
-      "tokens_used": 0,
-      "created_at": "2026-06-14T10:01:00Z"
-    },
-    {
-      "id": 1002,
-      "role": "assistant",
-      "content": "这是一朵红色的玫瑰。",
-      "tokens_used": 42,
-      "created_at": "2026-06-14T10:01:02Z"
-    }
-  ],
-  "has_more": false
-}
-```
-
 **分页用法**：首次请求不带 `before`，获取最新消息。滚动到顶部时，取当前列表最小的 `id` 作为 `before` 参数请求更早的消息。
 
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
-| 404 | `SESSION_NOT_FOUND` | 对话不存在或不属于当前用户 |
-
----
-
-### WebSocket 认证变更
-
-连接地址变更为带 token 的查询参数：
-
-```
-ws://localhost:8080/ws?token=<access_token>&conversation_id=<uuid>
-```
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `token` | 是 | JWT access_token |
-| `conversation_id` | 否 | 恢复已有对话；省略则创建新对话 |
-
-**认证失败响应**（HTTP 升级前返回）：
-
-| 状态码 | 场景 |
-|--------|------|
-| 401 | token 缺失、无效或已过期 |
-
-**conversation_id 校验失败**：
-
-| 场景 | 处理 |
-|------|------|
-| 对话不存在 | 返回 401，`{"error": "SESSION_NOT_FOUND"}` |
-| 对话不属于当前用户 | 返回 401，`{"error": "SESSION_NOT_FOUND"}`（与不存在相同，避免信息泄露） |
-
 ---
 
 ### 健康检查
@@ -731,41 +607,18 @@ GET /api/health
 
 ---
 
-### ~~旧会话接口~~（已废弃）
-
-> 以下端点已废弃，保留仅为向后兼容。新代码应使用 `/api/conversations` 系列接口。
-
-```
-POST /api/sessions          → 改用 POST /api/conversations
-DELETE /api/sessions/{id}   → 改用 DELETE /api/conversations/{id}
-```
-
-### 预留端点（暂不实现）
+### 预留端点（待实现）
 
 | 端点 | 方法 | 用途 |
 |------|------|------|
 | `/api/usage` | GET | 查询用量统计 |
 | `/api/users/{id}/preferences` | GET/PUT | 用户偏好管理 |
 
-### 已实现的认证与对话端点
-
-> 详见上方"认证接口"和"对话接口"章节。包括：
-> - `POST /api/auth/register` — 注册
-> - `POST /api/auth/login` — 登录
-> - `POST /api/auth/refresh` — 刷新 Token
-> - `POST /api/auth/logout` — 登出
-> - `GET /api/conversations` — 对话列表
-> - `POST /api/conversations` — 创建对话
-> - `GET /api/conversations/:id` — 对话详情
-> - `PATCH /api/conversations/:id` — 更新标题
-> - `DELETE /api/conversations/:id` — 删除对话
-> - `GET /api/conversations/:id/messages` — 历史消息
-
 ---
 
 ## 三、AI 服务层接口
 
-Go 网关内部与外部 AI 服务（STT、LLM、TTS）的调用契约。默认配置为 Deepgram STT、GPT-4o LLM、OpenAI TTS，但通过 OpenAI 兼容接口可灵活切换到其他服务商（如 MiMo ASR、通义千问等）。前后端联调时，后端需实现这些接口。
+Go 网关内部与外部 AI 服务（STT、LLM、TTS）的调用契约。通过 OpenAI 兼容接口可灵活切换到其他服务商。
 
 ### STT 服务接口
 
@@ -786,11 +639,12 @@ type Options struct {
 }
 ```
 
-**Deepgram 接入约定**：
-- 连接方式：WebSocket `wss://api.deepgram.com/v1/listen`
-- 音频格式：PCM 16-bit signed little-endian，16kHz 单声道（与前端 `MicManager` 输出一致）
-- 返回格式：`channel.alternatives[0].transcript`，`is_final` 字段标识最终结果
-- 超时：单次识别 5 秒超时
+**已实现 Provider**：
+
+| Provider | 连接方式 | 说明 |
+|----------|---------|------|
+| Deepgram（默认） | WebSocket `wss://api.deepgram.com/v1/listen` | 流式识别，延迟极低，模型 nova-2 |
+| MiMo ASR | HTTP POST OpenAI 兼容 `/chat/completions` | 国产替代，PCM 自动转 WAV，支持 zh/en/auto |
 
 ### LLM 服务接口
 
@@ -800,49 +654,33 @@ type Options struct {
 // Service 多模态大模型服务契约。
 type Service interface {
     // ChatStream 流式推理，返回增量文本的 channel。
-    // 调用方必须消费 channel 直到 Done=true，否则需 cancel ctx 以释放连接。
     ChatStream(ctx context.Context, req Request) (<-chan Chunk, error)
 }
 
 // Request 推理请求。
 type Request struct {
-    Image    []byte            // JPEG 图片（已从 Base64 解码）
-    Text     string            // 用户语音识别后的文本
-    History  []models.Message  // 最近 N 轮对话历史
-    Language string            // "zh-CN"
+    Image         []byte            // JPEG 图片（已从 Base64 解码）
+    Text          string            // 用户语音识别后的文本
+    History       []models.Message  // 最近 N 轮对话历史
+    Language      string            // "zh-CN"
+    SystemPrompt  string            // 系统提示词（含场景 prompt）
 }
 
 // Chunk 流式推理的一个增量片段。
 type Chunk struct {
-    Delta      string       // 增量文本
-    Done       bool         // 是否结束
+    Delta      string
+    Done       bool
     TokensUsed *TokenUsage  // 仅 Done=true 时有值
     Model      string       // 实际使用的模型名
 }
-
-// TokenUsage 用量统计。
-type TokenUsage struct {
-    Prompt     int
-    Completion int
-    Total      int
-}
 ```
 
-**OpenAI API 接入约定**：
-- 端点：`POST https://api.openai.com/v1/chat/completions`
+**接入约定**：
+- 端点：`POST {endpoint}/chat/completions`，通过配置切换
 - 图片传入：`image_url` 字段使用 `data:image/jpeg;base64,...` 格式
 - 流式响应：`stream: true`，通过 SSE 逐 chunk 返回
-- Prompt 结构：
-
-```
-system: "你是一个视觉助手。用户通过摄像头看到一个场景，并用语音向你提问。
-         请用简洁自然的中文回答。如果涉及视觉描述，先说'我看到...'。"
-user: [图片 + 用户语音文本]
-（重复 History 中的历史消息）
-```
-
 - 超时：10 秒，超时返回 `LLM_TIMEOUT` 错误
-- 模型选择：默认 `gpt-4o`，可通过配置切换到其他 OpenAI 兼容模型
+- 系统提示词：根据语言和场景（scenario）动态构建
 
 ### TTS 服务接口
 
@@ -859,25 +697,19 @@ type Service interface {
 
 // Options 合成参数。
 type Options struct {
-    Voice      string  // "alloy" | "nova" | "shimmer" | ...
+    Voice      string  // 语音名称
     Speed      float64 // 1.0 为正常语速
-    OutputFmt  string  // "mp3" — 固定使用 MP3，浏览器原生支持
+    OutputFmt  string  // "mp3"
     SampleRate int     // 24000
 }
-
-// Chunk 一个音频片段。
-type Chunk struct {
-    Audio  []byte // MP3 音频数据（未 Base64 编码，由发送层编码）
-    IsLast bool   // 是否为最后一片
-}
 ```
 
-**OpenAI TTS 接入约定**：
-- 端点：`POST https://api.openai.com/v1/audio/speech`
-- 模型：`tts-1`（低延迟优先）或 `tts-1-hd`（高音质）
-- 输出格式：`mp3`，24kHz
-- 流式：使用 `response_format: "mp3"` 并读取 response body 流
-- 超时：单个句子 5 秒超时
+**已实现 Provider**：
+
+| Provider | 端点 | 说明 |
+|----------|------|------|
+| OpenAI TTS（默认） | `POST /audio/speech` | 逐句合成，返回 MP3 流 |
+| MiMo TTS | `POST /chat/completions` | 国产替代，base64 音频响应 |
 
 ---
 
@@ -902,20 +734,15 @@ LLM 流式输出:  "这" "是一" "朵红色" "的花。" "它看起" "来很美
 **时序保证**：
 - `llm_chunk` 消息一定先于对应句子的 `tts_audio` 到达客户端
 - 用户先看到文字，紧接着听到语音（感知延迟 < 0.5 秒）
-- 不必等 LLM 全部输出完才开始 TTS
 
 ### Orchestrator 接口
 
 ```go
-// Orchestrator AI 编排器接口。
 type Orchestrator interface {
-    // ProcessQuery 处理一次完整的视觉对话请求。
-    // 通过 sender 向前端实时推送 stt_result、llm_chunk、llm_done、tts_audio 消息。
     ProcessQuery(ctx context.Context, sessionID string, req models.WsQuery,
         history []models.Message, sender Sender) error
 }
 
-// Sender 抽象 WebSocket 消息推送能力，便于测试时 mock。
 type Sender interface {
     SendSTTResult(result models.WsSTTResult) error
     SendLLMChunk(chunk models.WsLLMChunk) error
@@ -925,7 +752,7 @@ type Sender interface {
 }
 ```
 
-**Pipeline 实现**（`internal/orchestrator/pipeline.go`）：
+**Pipeline 实现流程**：
 1. Base64 解码音频/图片
 2. 调用 `stt.Recognize()` → 发送 `stt_result`
 3. 调用 `llm.ChatStream()` 获取流式输出，goroutine 消费 token → 发送 `llm_chunk` + 句子切分
@@ -948,7 +775,6 @@ type Sender interface {
 | LLM 超时（>10s） | 发送 `LLM_TIMEOUT`，取消 TTS | 提示用户重试 |
 | LLM 部分输出后失败 | 已推送的 `llm_chunk` 保留，发送 `error` 通知中断 | 显示已收到的部分文字 |
 | TTS 失败 | 静默跳过，`llm_done` 正常发送 | 只有文字回复，无语音 |
-| TTS 部分失败 | 已推送的音频保留，后续句子跳过 | 部分句子有语音 |
 | interrupt 打断 | cancel context，清空所有流 | 前端清空播放队列 |
 
 ---
@@ -957,40 +783,29 @@ type Sender interface {
 
 WebSocket Handler 和 AI Orchestrator 之间的会话管理层。负责维护会话生命周期、对话上下文和配置状态。
 
-### Redis 数据结构
+### 数据结构
 
-每个会话在 Redis 中占 2 个 key：
+**Memory 存储**（默认）：
+
+```
+MemoryManager
+├── sessions: map[string]*sessionEntry
+│   ├── session     models.Session
+│   ├── history     []models.Message
+│   ├── activeReqID string
+│   └── lastActive  time.Time
+├── msgRepo:  MessageRepository  (Write-Through, 可选)
+└── sessRepo: SessionRepository  (Write-Through, 可选)
+```
+
+**Redis 存储**（可选）：
 
 ```
 session:{id}:meta    → Hash   （会话元数据）
 session:{id}:history → List   （对话历史）
+user:{id}:sessions   → Set    （用户会话索引）
 ```
 
-**Hash — `session:{id}:meta`**
-
-| field | 类型 | 示例 | 说明 |
-|-------|------|------|------|
-| `session_id` | string | `"550e8400-..."` | 主键冗余 |
-| `config.tts_enabled` | string | `"true"` | Redis Hash 值均为 string |
-| `config.detail_level` | string | `"low"` | |
-| `config.language` | string | `"zh-CN"` | |
-| `created_at` | string | `"2026-06-13T10:00:00Z"` | RFC3339 |
-| `last_active` | string | `"2026-06-13T10:05:30Z"` | 每次消息刷新 |
-| `active_request_id` | string | `"uuid"` 或 `""` | 当前处理中的请求 ID，用于 interrupt |
-
-**List — `session:{id}:history`**
-
-每个元素是一条 JSON 序列化的 Message：
-
-```json
-{"role":"user","content":"这是什么花？"}
-{"role":"assistant","content":"这是一朵红色的玫瑰。"}
-```
-
-- `LPUSH` 新消息到左头（最新在前）
-- `LRANGE 0 {limit-1}` 取最近 N 轮
-- `LTRIM 0 {max-1}` 限制总条数（默认保留最近 20 条 = 10 轮对话）
-
 ### TTL 策略
 
 | 场景 | TTL | 说明 |
@@ -998,14 +813,12 @@ session:{id}:history → List   （对话历史）
 | 创建时 | 30 分钟 | `EXPIRE` 设置 |
 | 每次收到消息 | 重置 30 分钟 | `EXPIRE` 刷新 |
 | WebSocket 断开 | 不主动删 | 等自然过期，支持重连恢复 |
-| 超过 30 分钟无活动 | 自动过期 | Redis 自动清理 meta + history |
-| 显式销毁（REST API） | 立即 `DEL` | 两个 key 一起删 |
+| 超过 30 分钟无活动 | 自动过期 | 自动清理 |
+| 显式销毁（REST API） | 立即删除 | |
 
 ### 接口定义
 
 ```go
-// Manager 会话管理器接口。
-// WebSocket Handler 通过此接口操作会话，不直接接触存储层。
 type Manager interface {
     // Create 创建新会话，关联 user_id，返回 session ID。
     Create(ctx context.Context, userID string, config models.SessionConfig) (string, error)
@@ -1057,99 +870,96 @@ type ConversationSummary struct {
 }
 ```
 
-### WebSocket Handler 集成
+### Write-Through 机制
+
+MemoryManager 支持注入 `MessageRepository` 和 `SessionRepository`，实现写穿持久化：
 
 ```go
-// 连接建立（JWT 认证 + conversation_id 恢复）
-func (h *Handler) HandleWS(c *gin.Context) {
-    tokenStr := c.Query("token")
-    claims, err := h.tokenManager.ValidateAccess(tokenStr)
-    // ... 认证失败返回 401
-
-    conversationID := c.Query("conversation_id")
-    if conversationID != "" {
-        sess, _ := h.sessionMgr.Get(c, conversationID)
-        if sess.UserID != claims.UserID { /* 返回 SESSION_NOT_FOUND */ }
-        sessionID = conversationID
-    } else {
-        sessionID, _ = h.sessionMgr.Create(c, claims.UserID, defaultConfig)
-    }
-    // ... 进入 WS 处理循环
+opts := []session.Option{}
+if msgRepo != nil {
+    opts = append(opts, session.WithMessageRepository(msgRepo))
 }
-
-// query 分支
-case "query":
-    var msg models.WsQuery
-    json.Unmarshal(message, &msg)
-
-    sessionMgr.Touch(ctx, sessionID)                    // 刷新 TTL
-    sessionMgr.SetActiveRequest(ctx, sessionID, msg.RequestID) // 标记活跃请求
-
-    history, _ := sessionMgr.GetHistory(ctx, sessionID, 20)    // 获取对话上下文
-
-    sender := &WSClient{client: client, requestID: msg.RequestID}
-    go orch.ProcessQuery(ctx, sessionID, msg, history, sender) // 异步编排
-
-// interrupt 分支
-case "interrupt":
-    reqID, _ := sessionMgr.GetActiveRequestID(ctx, sessionID)
-    if reqID != "" {
-        cancelFunc(reqID)                                    // 取消对应 context
-        sessionMgr.ClearActiveRequest(ctx, sessionID)
-    }
-
-// 连接断开
-// 不调用 Destroy，让 session 自然过期（支持重连恢复）
+if sessRepo != nil {
+    opts = append(opts, session.WithSessionRepository(sessRepo))
+}
+sessionMgr = session.NewMemoryManager(30*time.Minute, 20, opts...)
 ```
 
-### 内存实现（默认）
+- `Create` 时同时写入 PG sessions 表
+- `AppendMessage` 时同时写入 PG messages 表
+- `Get` 时如果内存中不存在，尝试从 PG 恢复
 
-默认使用 `MemoryManager`，支持可选的 Write-Through 到 PostgreSQL：
+### 自动标题生成
+
+首条 user 消息时，如果 title 仍为 "新对话"，自动更新为消息内容前 20 个字符。
+
+---
+
+## 六、存储层接口
+
+通过 Repository 接口隔离存储层，内存和 PostgreSQL 均已实现。
+
+### UserRepository
 
 ```go
-type MemoryManager struct {
-    mu          sync.RWMutex
-    sessions    map[string]*sessionEntry
-    ttl         time.Duration
-    maxHistory  int
-    stopCleaner chan struct{}
-    msgRepo     store.MessageRepository  // 可选，Write-Through
-    sessRepo    store.SessionRepository  // 可选，Write-Through
-}
-
-type sessionEntry struct {
-    session     models.Session
-    history     []models.Message
-    activeReqID string
-    lastActive  time.Time
+type UserRepository interface {
+    Create(ctx context.Context, username, passwordHash string) (string, error)
+    FindByUsername(ctx context.Context, username string) (*User, error)
+    FindByID(ctx context.Context, id string) (*User, error)
+    SaveRefreshToken(ctx context.Context, userID, tokenHash string, expiresAt time.Time) error
+    FindRefreshToken(ctx context.Context, tokenHash string) (string, error)
+    DeleteRefreshToken(ctx context.Context, tokenHash string) error
+    DeleteUserRefreshTokens(ctx context.Context, userID string) error
 }
 ```
 
-**Write-Through 机制**：注入 `msgRepo` 和 `sessRepo` 后，每次 `AppendMessage` 同时写入 PostgreSQL，重启后可从 PG 恢复会话。`Create` 时同时写入 PG sessions 表。
-
-**自动标题**：首条 user 消息时，如果 title 仍为 "新对话"，自动更新为消息内容前 20 个字符。
-
-注入时根据配置切换：
+### MessageRepository
 
 ```go
-var sessionMgr session.Manager
-if cfg.Redis.Addr != "" {
-    sessionMgr = session.NewRedisManager(redisClient, 30*time.Minute, 20)
+type MessageRepository interface {
+    SaveMessage(ctx context.Context, sessionID string, msg models.Message, tokensUsed int) error
+    GetMessages(ctx context.Context, sessionID string, limit int, beforeID int64) ([]StoredMessage, error)
+    GetLastMessage(ctx context.Context, sessionID string) (*StoredMessage, error)
+    GetMessageCount(ctx context.Context, sessionID string) (int, error)
+    GetSessionMessageStats(ctx context.Context, sessionIDs []string) (map[string]int, error)
+}
+```
+
+### SessionRepository
+
+```go
+type SessionRepository interface {
+    Save(ctx context.Context, session models.Session) error
+    FindByID(ctx context.Context, id string) (*models.Session, error)
+    FindByUser(ctx context.Context, userID string, page, size int) ([]models.Session, int, error)
+    UpdateTitle(ctx context.Context, id string, title string) error
+    UpdateConfig(ctx context.Context, id string, config models.SessionConfig) error
+    Touch(ctx context.Context, id string) error
+    Delete(ctx context.Context, id string) error
+}
+```
+
+### 依赖注入
+
+```go
+if cfg.Storage.Driver == "postgres" {
+    pool, _ := store.NewPostgresPool(ctx, cfg.Storage.DSN)
+    userRepo = store.NewPgUserRepository(pool)
+    msgRepo = store.NewPgMessageRepository(pool)
+    sessRepo = store.NewPgSessionRepository(pool)
+    sessionMgr = session.NewMemoryManager(30*time.Minute, 20,
+        session.WithMessageRepository(msgRepo),
+        session.WithSessionRepository(sessRepo),
+    )
 } else {
-    opts := []session.Option{}
-    if msgRepo != nil {
-        opts = append(opts, session.WithMessageRepository(msgRepo))
-    }
-    if sessRepo != nil {
-        opts = append(opts, session.WithSessionRepository(sessRepo))
-    }
-    sessionMgr = session.NewMemoryManager(30*time.Minute, 20, opts...)
+    userRepo = store.NewMemUserRepository()
+    sessionMgr = session.NewMemoryManager(30*time.Minute, 20)
 }
 ```
 
 ---
 
-## 六、配置管理
+## 七、配置管理
 
 使用 Viper 加载配置，支持 YAML 文件 + 环境变量覆盖。**环境变量优先级高于配置文件**。
 
@@ -1157,16 +967,15 @@ if cfg.Redis.Addr != "" {
 
 ```
 backend/config.yaml        # 默认加载
-backend/config.dev.yaml    # 开发环境（go run 时使用）
+backend/config.dev.yaml    # 开发环境
 backend/config.prod.yaml   # 生产环境
 ```
 
-Viper 加载顺序：先读 `config.yaml`，再根据 `APP_ENV` 环境变量尝试读 `config.{env}.yaml` 覆盖，最后所有环境变量自动覆盖对应字段。此外，代码还通过 `godotenv` 加载 `.env` 文件（优先级最低，仅用于本地开发环境）。
+加载顺序：`config.yaml` → `config.{APP_ENV}.yaml` → 环境变量（前缀 `CAMTALK_`）。
 
-### Go 配置结构体
+### 配置结构体
 
 ```go
-// Config 应用配置。
 type Config struct {
     App      AppConfig      `mapstructure:"app"`
     Server   ServerConfig   `mapstructure:"server"`
@@ -1195,56 +1004,56 @@ type ServerConfig struct {
 }
 
 type SessionConfig struct {
-    TTL         int `mapstructure:"ttl"`         // 分钟，默认 30
-    MaxHistory  int `mapstructure:"max_history"`  // 条数，默认 20
+    TTL        int `mapstructure:"ttl"`         // 分钟，默认 30
+    MaxHistory int `mapstructure:"max_history"`  // 条数，默认 20
 }
 
 type RedisConfig struct {
     Addr     string `mapstructure:"addr"`      // "localhost:6379"
-    Password string `mapstructure:"password"`  // 无密码留空
+    Password string `mapstructure:"password"`
     DB       int    `mapstructure:"db"`        // 默认 0
 }
 
 type AIConfig struct {
-    STT  STTConfig  `mapstructure:"stt"`
-    LLM  LLMConfig  `mapstructure:"llm"`
-    TTS  TTSConfig  `mapstructure:"tts"`
+    STT STTConfig `mapstructure:"stt"`
+    LLM LLMConfig `mapstructure:"llm"`
+    TTS TTSConfig `mapstructure:"tts"`
 }
 
 type STTConfig struct {
-    Provider           string `mapstructure:"provider"`             // "deepgram" | "mimo" | "xiaomi"
-    APIKey             string `mapstructure:"api_key"`
-    Model              string `mapstructure:"model"`                // 默认 "nova-2"
-    Endpoint           string `mapstructure:"endpoint"`             // 默认 "wss://api.deepgram.com/v1/listen"
-    Timeout            int    `mapstructure:"timeout"`              // 秒，默认 5
-    HTTPClientTimeout  int    `mapstructure:"http_client_timeout"`  // 秒，默认 30
+    Provider          string `mapstructure:"provider"`             // "deepgram" | "mimo" | "xiaomi"
+    APIKey            string `mapstructure:"api_key"`
+    Model             string `mapstructure:"model"`                // 默认 "nova-2"
+    Endpoint          string `mapstructure:"endpoint"`
+    Timeout           int    `mapstructure:"timeout"`              // 秒，默认 5
+    HTTPClientTimeout int    `mapstructure:"http_client_timeout"`  // 秒，默认 30
 }
 
 type LLMConfig struct {
-    Provider           string `mapstructure:"provider"`             // "openai"
-    APIKey             string `mapstructure:"api_key"`
-    Model              string `mapstructure:"model"`                // 默认 "gpt-4o"
-    Endpoint           string `mapstructure:"endpoint"`             // 默认 "https://api.openai.com/v1"
-    Timeout            int    `mapstructure:"timeout"`              // 秒，默认 10
-    HTTPClientTimeout  int    `mapstructure:"http_client_timeout"`  // 秒，默认 60
+    Provider          string `mapstructure:"provider"`             // "openai"
+    APIKey            string `mapstructure:"api_key"`
+    Model             string `mapstructure:"model"`                // 默认 "gpt-4o"
+    Endpoint          string `mapstructure:"endpoint"`
+    Timeout           int    `mapstructure:"timeout"`              // 秒，默认 10
+    HTTPClientTimeout int    `mapstructure:"http_client_timeout"`  // 秒，默认 60
 }
 
 type TTSConfig struct {
-    Provider           string  `mapstructure:"provider"`             // "openai" | "mimo" | "xiaomi"
-    APIKey             string  `mapstructure:"api_key"`
-    Model              string  `mapstructure:"model"`                // 默认 "tts-1"
-    Voice              string  `mapstructure:"voice"`                // 默认 "mimo_default"
-    Speed              float64 `mapstructure:"speed"`                // 默认 1.0
-    Endpoint           string  `mapstructure:"endpoint"`             // 默认 "https://api.openai.com/v1"
-    Timeout            int     `mapstructure:"timeout"`              // 秒，默认 5
-    HTTPClientTimeout  int     `mapstructure:"http_client_timeout"`  // 秒，默认 30
-    OutputFormat       string  `mapstructure:"output_format"`        // 默认 "mp3"
-    SampleRate         int     `mapstructure:"sample_rate"`          // 默认 24000
+    Provider          string  `mapstructure:"provider"`             // "openai" | "mimo" | "xiaomi"
+    APIKey            string  `mapstructure:"api_key"`
+    Model             string  `mapstructure:"model"`                // 默认 "tts-1"
+    Voice             string  `mapstructure:"voice"`                // 默认 "mimo_default"
+    Speed             float64 `mapstructure:"speed"`                // 默认 1.0
+    Endpoint          string  `mapstructure:"endpoint"`
+    Timeout           int     `mapstructure:"timeout"`              // 秒，默认 5
+    HTTPClientTimeout int     `mapstructure:"http_client_timeout"`  // 秒，默认 30
+    OutputFormat      string  `mapstructure:"output_format"`        // 默认 "mp3"
+    SampleRate        int     `mapstructure:"sample_rate"`          // 默认 24000
 }
 
 type StorageConfig struct {
     Driver string `mapstructure:"driver"` // "memory" | "postgres"
-    DSN    string `mapstructure:"dsn"`    // PostgreSQL 连接串，driver=postgres 时必填
+    DSN    string `mapstructure:"dsn"`
 }
 
 type AuthConfig struct {
@@ -1255,14 +1064,13 @@ type AuthConfig struct {
 
 type LogConfig struct {
     Level  string `mapstructure:"level"`  // "debug" | "info" | "warn" | "error"，默认 "info"
-    Format string `mapstructure:"format"` // "json" | "console"，生产用 json
+    Format string `mapstructure:"format"` // "json" | "console"
 }
 ```
 
 ### 配置文件示例
 
 ```yaml
-# config.yaml — 所有环境共享的默认值
 app:
   env: dev
 
@@ -1312,8 +1120,8 @@ storage:
   driver: memory
 
 auth:
-  access_ttl: 15       # access token 有效期（分钟）
-  refresh_ttl: 10080   # refresh token 有效期（分钟，7 天）
+  access_ttl: 15
+  refresh_ttl: 10080
 
 log:
   level: info
@@ -1322,126 +1130,51 @@ log:
 
 ### 环境变量覆盖规则
 
-Viper 自动将配置项映射为环境变量，规则：**前缀 `CAMTALK_` + 路径大写用 `_` 连接**。
+前缀 `CAMTALK_` + 路径大写用 `_` 连接：
 
-| 配置项 | 环境变量 | 示例 |
-|--------|---------|------|
-| `server.port` | `CAMTALK_SERVER_PORT` | `8080` |
-| `redis.addr` | `CAMTALK_REDIS_ADDR` | `redis:6379` |
-| `redis.password` | `CAMTALK_REDIS_PASSWORD` | — |
-| `ai.stt.api_key` | `CAMTALK_AI_STT_API_KEY` | — |
-| `ai.llm.api_key` | `CAMTALK_AI_LLM_API_KEY` | — |
-| `ai.tts.api_key` | `CAMTALK_AI_TTS_API_KEY` | — |
-| `ai.llm.model` | `CAMTALK_AI_LLM_MODEL` | `gpt-4o` |
-| `storage.driver` | `CAMTALK_STORAGE_DRIVER` | `postgres` |
-| `storage.dsn` | `CAMTALK_STORAGE_DSN` | — |
-| `auth.jwt_secret` | `CAMTALK_AUTH_JWT_SECRET` | —（必填，仅环境变量） |
-| `auth.access_ttl` | `CAMTALK_AUTH_ACCESS_TTL` | `15` |
-| `auth.refresh_ttl` | `CAMTALK_AUTH_REFRESH_TTL` | `10080` |
-| `app.env` | `CAMTALK_APP_ENV` | `prod` |
-| `log.level` | `CAMTALK_LOG_LEVEL` | `warn` |
-| `log.format` | `CAMTALK_LOG_FORMAT` | `json` |
+| 配置项 | 环境变量 |
+|--------|---------|
+| `server.port` | `CAMTALK_SERVER_PORT` |
+| `redis.addr` | `CAMTALK_REDIS_ADDR` |
+| `ai.stt.api_key` | `CAMTALK_AI_STT_API_KEY` |
+| `ai.llm.api_key` | `CAMTALK_AI_LLM_API_KEY` |
+| `ai.tts.api_key` | `CAMTALK_AI_TTS_API_KEY` |
+| `storage.driver` | `CAMTALK_STORAGE_DRIVER` |
+| `storage.dsn` | `CAMTALK_STORAGE_DSN` |
+| `auth.jwt_secret` | `CAMTALK_AUTH_JWT_SECRET` |
+| `log.level` | `CAMTALK_LOG_LEVEL` |
 
 > API Key 和密码**只通过环境变量注入**，不写入配置文件，避免泄露到版本控制。
 
-### 配置加载代码
-
-```go
-// internal/config/config.go
-
-func Load() (*Config, error) {
-    v := viper.New()
-
-    // 1. 读默认配置文件
-    v.SetConfigName("config")
-    v.SetConfigType("yaml")
-    v.AddConfigPath(".")
-    v.AddConfigPath("./config")
-    v.AddConfigPath("./backend")
-    if err := v.ReadInConfig(); err != nil {
-        if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
-            return nil, fmt.Errorf("read config: %w", err)
-        }
-    }
-
-    // 2. 按环境覆盖
-    env := os.Getenv("APP_ENV")
-    if env == "" {
-        env = "dev"
-    }
-    v.SetConfigName("config." + env)
-    v.MergeInConfig() // 忽略文件不存在
-
-    // 3. 环境变量覆盖
-    v.SetEnvPrefix("CAMTALK")
-    v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
-    v.AutomaticEnv()
-
-    // 4. 解析
-    var cfg Config
-    if err := v.Unmarshal(&cfg); err != nil {
-        return nil, fmt.Errorf("unmarshal config: %w", err)
-    }
-    return &cfg, nil
-}
-```
-
-### main.go 集成
-
-```go
-func main() {
-    cfg, err := config.Load()
-    if err != nil {
-        log.Fatalf("load config: %v", err)
-    }
-
-    r := gin.Default()
-    // 使用 cfg.Server.Port 替代硬编码 :8080
-    addr := fmt.Sprintf("%s:%d", cfg.Server.Host, cfg.Server.Port)
-    log.Printf("CamTalk gateway starting on %s (env=%s)", addr, cfg.App.Env)
-    r.Run(addr)
-}
-```
-
-### 启动方式
+### 启动命令
 
 ```bash
-# 开发环境（默认 config.yaml，API Key 通过环境变量注入）
+# 开发环境
 CAMTALK_AI_LLM_API_KEY=sk-xxx \
 CAMTALK_AI_STT_API_KEY=xxx \
 go run ./cmd/server
 
 # 生产环境
 CAMTALK_APP_ENV=prod \
-CAMTALK_REDIS_ADDR=redis:6379 \
-CAMTALK_AI_LLM_API_KEY=sk-xxx \
-CAMTALK_AI_STT_API_KEY=xxx \
-CAMTALK_AI_TTS_API_KEY=xxx \
 CAMTALK_STORAGE_DRIVER=postgres \
 CAMTALK_STORAGE_DSN="postgres://user:pass@db:5432/camtalk?sslmode=disable" \
 CAMTALK_AUTH_JWT_SECRET="$(openssl rand -hex 32)" \
-CAMTALK_LOG_LEVEL=warn \
-CAMTALK_LOG_FORMAT=json \
 ./bin/camtalk
 ```
 
 ---
 
-## 七、数据模型
-
-> 注：Go 和 TypeScript 的数据模型定义见下方。AI 服务层的 Go 模型见上方"AI 服务层接口"章节。
+## 八、数据模型
 
 ### Go 后端模型
 
 ```go
-// ---- 核心模型（MVP 实现）----
-
 type Session struct {
-    ID        string    `json:"session_id"`
-    UserID    string    `json:"user_id"`     // 关联用户，空串表示匿名
-    Title     string    `json:"title"`       // 对话标题
-    CreatedAt time.Time `json:"created_at"`
-    UpdatedAt time.Time `json:"updated_at"`
+    ID        string        `json:"session_id"`
+    UserID    string        `json:"user_id"`
+    Title     string        `json:"title"`
+    CreatedAt time.Time     `json:"created_at"`
+    UpdatedAt time.Time     `json:"updated_at"`
     Config    SessionConfig `json:"config"`
 }
 
@@ -1452,21 +1185,11 @@ type SessionConfig struct {
     Scenario    string `json:"scenario"`     // "free_chat" | "interviewer" | "english_teacher" | "debate" | "interpreter"
 }
 
-type QueryRequest struct {
-    RequestID string `json:"request_id"`
-    Image     []byte `json:"-"`           // Base64 解码后
-    Audio     []byte `json:"-"`           // Base64 解码后
-    Text      string `json:"text"`        // 用户手动输入的文本（有值时跳过 STT）
-    MimeType  string `json:"mime_type"`
-}
-
 type Message struct {
     Role    string `json:"role"`    // "user" | "assistant"
     Content string `json:"content"`
 }
 
-// ---- 用户模块 ----
-
 type User struct {
     ID           string    `json:"id"`
     Username     string    `json:"username"`
@@ -1475,14 +1198,6 @@ type User struct {
     UpdatedAt    time.Time `json:"updated_at"`
 }
 
-type ConversationSummary struct {
-    ID           string    `json:"id"`
-    Title        string    `json:"title"`
-    LastMessage  string    `json:"last_message"`
-    MessageCount int       `json:"message_count"`
-    UpdatedAt    time.Time `json:"updated_at"`
-}
-
 type StoredMessage struct {
     ID         int64     `json:"id"`
     SessionID  string    `json:"-"`
@@ -1496,17 +1211,11 @@ type StoredMessage struct {
 ### TypeScript 前端模型
 
 ```typescript
-interface Session {
-  sessionId: string;
-  createdAt: string;
-  config: SessionConfig;
-}
-
 interface SessionConfig {
   ttsEnabled: boolean;
   detailLevel: "low" | "high";
   language: string;
-  scenario: string; // "free_chat" | "interviewer" | "english_teacher" | "debate" | "interpreter"
+  scenario: string;
 }
 
 interface ChatMessage {
@@ -1517,60 +1226,17 @@ interface ChatMessage {
   tokensUsed?: number;
 }
 
-// ---- 用户模块 ----
-
 interface AuthTokens {
   accessToken: string;
   refreshToken: string;
 }
 
 interface User {
-  id: string;          // UUID
+  id: string;
   username: string;
-  created_at: string;  // ISO 8601
-}
-
-interface AuthResponse {
-  user: User;
-  access_token: string;
-  refresh_token: string;
-}
-
-interface ConversationSummary {
-  id: string;
-  title: string;
-  last_message: string;
-  message_count: number;
-  updated_at: string;
-}
-
-interface ConversationListResponse {
-  conversations: ConversationSummary[];
-  total: number;
-  page: number;
-  size: number;
-}
-
-interface ConversationDetail {
-  id: string;
-  title: string;
-  config: SessionConfig;
   created_at: string;
 }
 
-interface StoredMessage {
-  id: number;
-  role: "user" | "assistant";
-  content: string;
-  tokens_used: number;
-  created_at: string;
-}
-
-interface MessagesResponse {
-  messages: StoredMessage[];
-  has_more: boolean;
-}
-
 // WebSocket 消息联合类型
 type ServerMessage =
   | ConnectedMessage
@@ -1590,82 +1256,6 @@ type ClientMessage =
 
 ---
 
-## 八、存储层接口设计
-
-通过 Repository 接口隔离存储层，内存和 PostgreSQL 均已实现，业务逻辑零改动。
-
-### UserRepository
-
-```go
-// UserRepository 用户数据存储契约。
-// 内存实现：MemUserRepository（测试/开发用）
-// PostgreSQL 实现：PgUserRepository
-type UserRepository interface {
-    Create(ctx context.Context, username, passwordHash string) (string, error)
-    FindByUsername(ctx context.Context, username string) (*User, error)
-    FindByID(ctx context.Context, id string) (*User, error)
-    SaveRefreshToken(ctx context.Context, userID, tokenHash string, expiresAt time.Time) error
-    FindRefreshToken(ctx context.Context, tokenHash string) (string, error)
-    DeleteRefreshToken(ctx context.Context, tokenHash string) error
-    DeleteUserRefreshTokens(ctx context.Context, userID string) error
-}
-```
-
-### MessageRepository
-
-```go
-// MessageRepository 对话消息持久化契约。
-// PostgreSQL 实现：PgMessageRepository
-// MemoryManager 通过 Write-Through 注入此接口。
-type MessageRepository interface {
-    SaveMessage(ctx context.Context, sessionID string, msg models.Message, tokensUsed int) error
-    GetMessages(ctx context.Context, sessionID string, limit int, beforeID int64) ([]StoredMessage, error)
-    GetLastMessage(ctx context.Context, sessionID string) (*StoredMessage, error)
-    GetMessageCount(ctx context.Context, sessionID string) (int, error)
-    GetSessionMessageStats(ctx context.Context, sessionIDs []string) (map[string]int, error)
-}
-```
-
-### SessionRepository
-
-```go
-// SessionRepository 会话元数据持久化契约。
-// PostgreSQL 实现：PgSessionRepository
-// MemoryManager 通过 Write-Through 注入此接口。
-type SessionRepository interface {
-    Save(ctx context.Context, session models.Session) error
-    FindByID(ctx context.Context, id string) (*models.Session, error)
-    FindByUser(ctx context.Context, userID string, page, size int) ([]models.Session, int, error)
-    UpdateTitle(ctx context.Context, id string, title string) error
-    UpdateConfig(ctx context.Context, id string, config models.SessionConfig) error
-    Touch(ctx context.Context, id string) error
-    Delete(ctx context.Context, id string) error
-}
-```
-
-### 注入方式
-
-```go
-// main.go 依赖注入
-if cfg.Storage.Driver == "postgres" {
-    pool, _ := store.NewPostgresPool(ctx, cfg.Storage.DSN)
-    userRepo = store.NewPgUserRepository(pool)
-    msgRepo = store.NewPgMessageRepository(pool)
-    sessRepo = store.NewPgSessionRepository(pool)
-    sessionMgr = session.NewMemoryManager(30*time.Minute, 20,
-        session.WithMessageRepository(msgRepo),
-        session.WithSessionRepository(sessRepo),
-    )
-} else {
-    userRepo = store.NewMemUserRepository()
-    sessionMgr = session.NewMemoryManager(30*time.Minute, 20)
-}
-```
-
-> 依赖倒置原则——业务层依赖接口，不依赖具体实现。通过配置一行代码切换存储后端。
-
----
-
 ## 九、错误码
 
 | 错误码 | HTTP 状态码 | 含义 | 客户端处理建议 |
@@ -1676,7 +1266,7 @@ if cfg.Storage.Driver == "postgres" {
 | `IMAGE_TOO_LARGE` | — | 图像超过 4MB 限制（WS） | 降低分辨率或压缩质量 |
 | `AUDIO_TOO_SHORT` | — | 音频片段 < 250ms（WS） | 忽略，等待下次语音输入 |
 | `LLM_TIMEOUT` | — | LLM 推理超时 >10s（WS） | 提示用户重试 |
-| `LLM_ERROR` | — | LLM 服务异常（WS） | 提示用户重试，服务端记录日志 |
+| `LLM_ERROR` | — | LLM 服务异常（WS） | 提示用户重试 |
 | `STT_ERROR` | — | 语音识别失败（WS） | 回退到纯文本输入模式 |
 | `TTS_ERROR` | — | 语音合成失败（WS） | 静默回退到纯文本回复 |
 | `INTERNAL_ERROR` | 500 | 服务端内部错误 | 提示用户重试 |
@@ -1685,6 +1275,8 @@ if cfg.Storage.Driver == "postgres" {
 | `INVALID_TOKEN` | 401 | JWT 无效或已过期 | 尝试 refresh，失败则重新登录 |
 | `INVALID_INPUT` | 400 | 请求参数校验失败 | 检查字段规则后重试 |
 
+---
+
 ## 十、连接管理
 
 **心跳机制**：客户端每 30 秒发送应用层 `{type: "ping"}` 消息，服务端回复 `{type: "pong"}` 并刷新心跳计时器。超过 60 秒无 `ping`，服务端判定连接断开并清理会话资源。
@@ -1704,10 +1296,4 @@ function reconnect(attempt: number) {
 
 采用 **Nginx 同源反代**方案，前后端统一到同一域名，浏览器层面不存在跨域问题。
 
-**生产环境**：Nginx 将 `/`（前端）、`/api/*`（REST）、`/ws`（WebSocket）统一反代到同一域名，详见 `02-系统架构.md` 部署架构章节。
-
-**开发环境**：前端 WebSocket 地址基于 `window.location.host` 动态构建（相对路径），通过 Vite `server.proxy` 转发到后端 `http://localhost:8080`。REST API（`/api`）同理通过 Vite 代理转发。
-
-**Go 后端 WebSocket CheckOrigin**：生产环境 Nginx 同源，`CheckOrigin` 可保持默认（拒绝跨域）。开发环境通过 Vite proxy 转发，前后端同源，无需额外配置 `CheckOrigin`。
-
-> 如果未来需要支持第三方客户端直连（如移动端），再按需添加 CORS 中间件和 `CheckOrigin` 白名单。
+**开发环境**：前端 WebSocket 地址基于 `window.location.host` 动态构建，通过 Vite `server.proxy` 转发到后端 `http://localhost:8080`。
diff --git a/docs/02-系统架构.md b/docs/02-系统架构.md
deleted file mode 100644
index 85a24ee..0000000
--- a/docs/02-系统架构.md
+++ /dev/null
@@ -1,256 +0,0 @@
-# 系统架构
-
-## 概述
-
-三层架构：**前端做轻量预处理，后端做智能编排，云端 AI 服务按需调用**。在保证交互体验的同时控制成本。
-
-## 三层架构
-
-| 层级 | 职责 | 关键约束 |
-|------|------|---------|
-| **客户端（浏览器）** | 媒体采集、边缘预处理、UI 渲染 | 浏览器资源有限，模型需轻量 |
-| **Go 网关** | 会话管理、AI 服务编排、流式管道 | 高并发、低延迟、状态管理 |
-| **AI 服务** | LLM 推理、语音识别、语音合成 | 按量计费，需控制调用频率 |
-
-> 为什么要单独加一层 Go 网关，而不是让前端直连 AI API？1）API Key 安全性；2）统一的速率限制和成本管控；3）多模型路由逻辑集中在一处便于维护。
-
-## 技术栈
-
-### 前端
-
-| 技术 | 选型 | 选择理由 |
-|------|------|---------|
-| 框架 | React 18 + TypeScript | 组件化开发，类型安全，生态成熟 |
-| 构建 | Vite | 开发热更新快，构建产物小 |
-| 实时通信 | WebSocket（原生 API） + 自封装连接管理 | 浏览器原生支持，封装心跳/重连/消息分发 |
-| 边缘推理 | ONNX Runtime Web | 浏览器端跑轻量模型（VAD、关键帧检测） |
-| 语音检测 | @ricky0123/vad-web | 基于 WebRTC VAD，纯前端零延迟 |
-| 媒体采集 | MediaDevices API | 浏览器原生摄像头/麦克风访问 |
-
-### 后端
-
-| 技术 | 选型 | 选择理由 |
-|------|------|---------|
-| 语言 | Go | 高并发 goroutine 模型，适合长连接管理 |
-| HTTP 框架 | Gin | 高性能 HTTP 路由，中间件生态成熟 |
-| WebSocket | gorilla/websocket | Go 生态最成熟的 WebSocket 库 |
-| 会话存储 | Redis（已实现） / Memory（默认） | 高速 KV 存储，Memory 为默认实现，Redis 已实现可通过配置切换 |
-| 持久化存储 | PostgreSQL（已实现） | 对话历史、用户数据、会话持久化。MemoryManager 支持 Write-Through 到 PG |
-| 配置管理 | Viper + godotenv | 支持 YAML + .env + 环境变量覆盖，详见 `03-接口文档.md` 第六章 |
-| 日志 | Zap | 高性能结构化日志 |
-
-### AI 服务
-
-| 能力 | 主选方案 | 备选方案 | 选型考量 |
-|------|---------|---------|---------|
-| 多模态 LLM | GPT-4o（默认） | 通义千问等 OpenAI 兼容模型 | 通过 OpenAI 兼容接口，可灵活切换 |
-| 语音识别 STT | Deepgram（默认） | MiMo ASR（小米） | 支持多 provider 切换 |
-| 语音合成 TTS | OpenAI TTS（默认） | MiMo TTS（小米） | 支持多 provider 切换 |
-
-> 不必绑定单一厂商。Go 网关的 AI 服务层统一封装不同服务商的调用接口，通过配置切换 provider。
-
-## 核心交互流程
-
-一次完整的"用户提问 → AI 回答"流程：
-
-```
-Browser                Go Gateway          STT         LLM         TTS
-  |                       |                  |           |           |
-  |-- VAD 检测到语音结束 --->|                  |           |           |
-  |                       |                  |           |           |
-  |-- [音频+图像] -------->|                  |           |           |
-  |                       |--- 音频流 ------->|           |           |
-  |                       |<-- 流式文本 ------|           |           |
-  |                       |                  |           |           |
-  |                       |--- [图像+文本+上下文] -------->|           |
-  |                       |<-- 流式回答文本 --------------|           |
-  |<-- 推送回答文本 --------|                  |           |           |
-  |                       |--- 回答文本 ---------------------------->|
-  |                       |<-- 流式音频 --------------------------------|
-  |<-- 推送音频流 ----------|                  |           |           |
-  |                       |                  |           |           |
-  |-> 播放音频 + 渲染文字   |                  |           |           |
-```
-
-**关键优化**：LLM 文本流和 TTS 音频流是**并行推送**的——客户端先展示文字，同时开始播放语音，用户感知延迟大幅降低。
-
-## 后端模块
-
-| 模块 | 职责 | 关键实现 | 状态 |
-|------|------|---------|------|
-| WebSocket Handler | 管理客户端连接生命周期，单播消息推送 | goroutine per connection，JWT 认证，conversation_id 恢复 | ✅ 已完成 |
-| Session Manager | 维护用户会话状态、对话历史 | Memory（默认）/ Redis（可切换），30 分钟 TTL，Write-Through 到 PG（详见 `03-接口文档.md` 第五章） | ✅ 已完成 |
-| AI Orchestrator | 编排 STT→LLM→TTS 流式并行管道 | context 取消 + 超时控制 + 句子切分 | ✅ 已完成 |
-| AI Service Layer | AI 服务抽象层（STT/LLM/TTS） | 多 provider 支持（Deepgram/MiMo/OpenAI 等） | ✅ 已完成 |
-| Auth | 用户认证与授权 | JWT (HS256) 双 token 轮转，bcrypt 密码哈希，Gin 中间件 | ✅ 已完成 |
-| Store | 持久化存储层 | UserRepository / MessageRepository / SessionRepository，内存 + PostgreSQL 双实现 | ✅ 已完成 |
-| REST API | 健康检查、认证、对话管理端点 | Gin 路由，输入校验，权限校验 | ✅ 已完成 |
-| Error Handler | 统一错误码定义与发送 | 错误码枚举 | ✅ 已完成 |
-| Logger | 日志初始化封装 | Zap 结构化日志 | ✅ 已完成 |
-| Models | 数据模型定义 | WebSocket 消息、会话、配置、用户等 | ✅ 已完成 |
-| Migrations | 数据库版本化迁移 | 嵌入式 SQL 文件，自动执行，版本跟踪 | ✅ 已完成 |
-| Model Router | 根据请求类型选择 AI 模型 | 规则引擎 + 成本阈值 | 📋 规划中 |
-| Rate Limiter | 防止单用户过度消耗 API 额度 | 令牌桶算法 | 📋 规划中 |
-
-AI Orchestrator 核心接口（`internal/orchestrator/orchestrator.go`）：
-
-```go
-// Orchestrator AI 编排器接口。
-type Orchestrator interface {
-    ProcessQuery(ctx context.Context, sessionID string, req models.WsQuery,
-        history []models.Message, sender Sender) error
-}
-```
-
-Pipeline 实现（`internal/orchestrator/pipeline.go`）流程：
-1. Base64 解码音频/图片
-2. 调用 `stt.Recognize()` → 发送 `stt_result`
-3. 调用 `llm.ChatStream()` 获取流式输出，goroutine 消费 token → 发送 `llm_chunk` + 句子切分
-4. 另一 goroutine 从句子 channel 读取 → 调用 `tts.SynthesizeStream()` → 发送 `tts_audio`
-5. 流结束 → 发送 `llm_done`
-6. TTS 失败静默跳过，STT/LLM 失败发送对应 error 消息
-
-> **关键优化**：LLM 文本流和 TTS 音频流**并行推送**——客户端先逐 token 展示文字，同时 TTS 逐句子合成并推送音频，用户感知延迟大幅降低。详细的 AI 服务层接口和编排策略见 `03-接口文档.md` 第三、四章。
-
-## 前端组件
-
-| 组件 | 职责 |
-|------|------|
-| AuthPage | 登录/注册表单，前端校验，Tab 切换 |
-| CameraManager | 摄像头流采集 |
-| MicManager | 麦克风音频采集 |
-| EdgeProcessor | VAD + 关键帧检测（Canvas 像素比较） |
-| WebSocketManager | WS 连接生命周期管理 |
-| ChatPanel | 消息展示、流式回复、文本输入、场景选择 |
-| VideoPreview | 摄像头画面预览 |
-| SessionSidebar | 左侧抽屉式对话列表（搜索、重命名、删除） |
-| ConfigPanel | 右侧抽屉式配置面板（主题、TTS 开关、detail level、语言、场景、账户） |
-| Toast | 轻量通知提示（3 秒自动消失） |
-
-核心 Hook：`useVisionSession()` 封装一次完整的视觉对话会话（摄像头、VAD、WebSocket、消息状态、认证、场景模式）。
-
-```typescript
-// useVisionSession 核心职责（简化示意）
-function useVisionSession() {
-  // 组合：useCamera + useMicrophone + useVAD + useWebSocketManager + useObservationMode
-  // 管理：消息状态、流式回复、处理标志、配置、统计、模式
-
-  // VAD onSpeechEnd: 捕获帧 + 音频 → 发送 query 消息
-  // 服务端消息处理：stt_result / llm_chunk / llm_done / tts_audio / error
-  // 文本输入：sendTextMessage() 支持手动输入文字（跳过 STT）
-  // 场景模式：config 消息支持 scenario 字段（free_chat / interviewer / english_teacher 等）
-  // 打断：interrupt() 发送中断消息 + 停止 TTS + 保存部分回复
-  // 认证：WebSocket 连接携带 JWT token，支持 conversation_id 恢复历史对话
-}
-```
-
-## 存储策略（分阶段）
-
-| 阶段 | 存储方案 | 持久化内容 | 理由 |
-|------|---------|-----------|------|
-| 当前默认 | Memory（进程内） | 会话状态 + 对话历史 | 零依赖，快速启动。MemoryManager 支持 Write-Through 到 PG |
-| 已实现 | Memory + PostgreSQL | 用户数据、对话历史、会话元数据 | 通过 `storage.driver: postgres` 启用，MemoryManager 注入 PG Repository |
-| 已实现 | Redis（独立） | 会话状态 + 对话历史 | 通过配置切换到 RedisManager，适合多实例部署 |
-
-冷热分离：Redis/Memory 存"热数据"（当前对话上下文，微秒级读写），PostgreSQL 存"冷数据"（历史记录）。MemoryManager 的 Write-Through 机制确保每次 AppendMessage 同时写入 PG，重启后可从 PG 恢复会话。
-
-### PostgreSQL 表设计（已实现）
-
-实际迁移文件位于 `backend/migrations/`，通过 `go:embed` 嵌入，启动时自动执行：
-
-```sql
--- 001_users.up.sql
-CREATE TABLE users (
-    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    username      VARCHAR(64) NOT NULL UNIQUE,
-    password_hash VARCHAR(256) NOT NULL,
-    created_at    TIMESTAMPTZ DEFAULT now(),
-    updated_at    TIMESTAMPTZ DEFAULT now()
-);
-
-CREATE TABLE refresh_tokens (
-    id          BIGSERIAL PRIMARY KEY,
-    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    token_hash  VARCHAR(256) NOT NULL UNIQUE,
-    expires_at  TIMESTAMPTZ NOT NULL,
-    created_at  TIMESTAMPTZ DEFAULT now()
-);
-
--- 002_messages.up.sql
-CREATE TABLE messages (
-    id          BIGSERIAL PRIMARY KEY,
-    session_id  UUID NOT NULL,
-    role        VARCHAR(16) NOT NULL,
-    content     TEXT NOT NULL,
-    tokens_used INTEGER DEFAULT 0,
-    created_at  TIMESTAMPTZ DEFAULT now()
-);
-
--- 003_sessions.up.sql
-CREATE TABLE sessions (
-    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    user_id    UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    title      VARCHAR(128) DEFAULT '新对话',
-    config     JSONB DEFAULT '{}',
-    created_at TIMESTAMPTZ DEFAULT now(),
-    updated_at TIMESTAMPTZ DEFAULT now()
-);
-```
-
-## 部署架构
-
-```
-用户浏览器
-    ↓
-Nginx（同源反代 + 负载均衡）
-  ├── /            → 前端静态资源（CDN 或本地 dist）
-  ├── /api/*       → Go Gateway（REST API）
-  └── /ws          → Go Gateway（WebSocket）
-        ├── Gateway-1 ──→ Redis
-        ├── Gateway-2 ──→ Redis
-        └── Gateway-N ──→ AI Services（外部 API）
-```
-
-**跨域策略**：Nginx 将前端和后端统一到同一域名下，浏览器无跨域问题。
-
-### Nginx 配置
-
-```nginx
-server {
-    listen 80;
-    server_name camtalk.example.com;
-
-    # 前端静态资源
-    location / {
-        root /var/www/camtalk/dist;
-        try_files $uri $uri/ /index.html;
-    }
-
-    # REST API 反代
-    location /api/ {
-        proxy_pass http://127.0.0.1:8080;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-
-    # WebSocket 反代
-    location /ws {
-        proxy_pass http://127.0.0.1:8080;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_read_timeout 86400s;   # 长连接超时 24h
-        proxy_send_timeout 86400s;
-    }
-}
-```
-
-> WebSocket 是长连接，Nginx 必须配置 `Upgrade` 和 `Connection` 头。`proxy_read_timeout` 需要覆盖心跳间隔（客户端 30s ping），否则 Nginx 会主动断开空闲连接。
-
-### 开发环境
-
-开发时前端（Vite :5173）和后端（Gin :8080）不同端口。前端 WebSocket 地址基于 `window.location.host` 动态构建，通过 Vite `server.proxy` 转发到后端，无需硬编码端口。
-
-`vite.config.ts` 中配置了 `/ws`（WebSocket）和 `/api`（REST）的代理，目标为 `http://localhost:8080`。
diff --git a/docs/04-技术选型.md b/docs/03-技术选型.md
similarity index 97%
rename from docs/04-技术选型.md
rename to docs/03-技术选型.md
index 95adc0b..ff2060c 100644
--- a/docs/04-技术选型.md
+++ b/docs/03-技术选型.md
@@ -4,25 +4,25 @@
 
 本文档记录项目中各项技术的**选型过程、替代方案对比和决策理由**。技术选型没有"绝对正确"，只有"更适合"。
 
-**定位**：本文档记录各项技术的选型过程和决策理由。AI 服务栈、持久化层、认证系统均已实现并通过配置灵活切换。前端边缘处理已确定技术栈。
+**定位**：本文档记录各项技术的选型过程和决策理由。
 
 ```
 技术选型
-├── AI 服务栈（✅ 已实现）
+├── AI 服务栈
 │   ├── STT: Deepgram（默认） / MiMo ASR
 │   ├── LLM: GPT-4o（默认） / 通义千问等 OpenAI 兼容模型
 │   └── TTS: OpenAI TTS（默认） / MiMo TTS
-├── 持久化层（✅ 已实现）
+├── 持久化层
 │   ├── 数据库: PostgreSQL（pgx/v5，手写 SQL）
 │   ├── 迁移: 嵌入式 SQL 文件，自动执行
 │   └── 存储模式: Memory（默认）+ Write-Through 到 PG / Redis（可切换）
-├── 认证与用户系统（✅ 已实现）
+├── 认证与用户系统
 │   ├── 认证方案: JWT (HS256), access 15min + refresh 7day
 │   ├── JWT 库: golang-jwt/jwt/v5
 │   ├── 密码哈希: bcrypt
 │   ├── 数据库驱动: pgx/v5（手写 SQL，不用 ORM）
 │   └── 前端 Token 存储: localStorage
-└── 前端边缘处理层（✅ 已实现）
+└── 前端边缘处理层
     ├── 关键帧检测: Canvas 像素比较（160x120 降采样）
     ├── 语音检测: @ricky0123/vad-web
     └── 媒体采集: MediaDevices API
@@ -64,7 +64,7 @@
 
 ---
 
-## 二、持久化层选型（已实现）
+## 二、持久化层选型
 
 ### 数据特征分析
 
diff --git a/docs/05-用户故事.md b/docs/04-用户故事.md
similarity index 100%
rename from docs/05-用户故事.md
rename to docs/04-用户故事.md
diff --git a/docs/06-语音交互.md b/docs/05-语音交互.md
similarity index 97%
rename from docs/06-语音交互.md
rename to docs/05-语音交互.md
index 9efb59d..fcbb1aa 100644
--- a/docs/06-语音交互.md
+++ b/docs/05-语音交互.md
@@ -61,7 +61,7 @@ vad.start();
 方案选择：
 - **OpenAI TTS**（默认）：音质好，延迟中等，按字符计费，模型 tts-1
 - **MiMo TTS**（小米）：国产替代，通过配置切换
-- **Edge TTS**（规划中）：微软免费方案，音质不错，延迟略高
+- **Edge TTS**（待实现）：微软免费方案，音质不错，延迟略高
 
 ## 延迟优化要点
 
diff --git a/docs/07-视觉理解.md b/docs/06-视觉理解.md
similarity index 100%
rename from docs/07-视觉理解.md
rename to docs/06-视觉理解.md
diff --git a/docs/08-成本控制.md b/docs/07-成本控制.md
similarity index 90%
rename from docs/08-成本控制.md
rename to docs/07-成本控制.md
index 6b7f2fb..7f28405 100644
--- a/docs/08-成本控制.md
+++ b/docs/07-成本控制.md
@@ -40,11 +40,11 @@ const ACTIVE_INTERVAL = 1000;  // 用户说话时 1 秒一帧
 不是所有计算都需要上云。可前置到客户端的计算：
 
 - **VAD 语音检测**：浏览器端完成，减少无效音频上传（节省 ~70% 带宽）
-- **人脸/物体检测**（规划中）：用 ONNX Runtime 跑轻量模型（如 YOLOv8-nano ~6MB，推理 ~30ms），只在检测到新物体时触发 LLM。当前 MVP 使用 Canvas 像素比较做关键帧检测
+- **人脸/物体检测**（待实现）：用 ONNX Runtime 跑轻量模型（如 YOLOv8-nano ~6MB，推理 ~30ms），只在检测到新物体时触发 LLM。当前 MVP 使用 Canvas 像素比较做关键帧检测
 - **重复画面过滤**：计算帧间相似度，对话模式 similarity > 0.9 跳过，观察模式 similarity < 0.85 触发
-- **敏感内容过滤**（规划中）：NSFW 检测前置，避免无效 API 调用
+- **敏感内容过滤**（待实现）：NSFW 检测前置，避免无效 API 调用
 
-## 策略三：模型分级——用对模型做对事（规划中）
+## 策略三：模型分级——用对模型做对事（待实现）
 
 不是每个问题都需要最贵的模型：
 
@@ -57,8 +57,8 @@ const ACTIVE_INTERVAL = 1000;  // 用户说话时 1 秒一帧
 
 > 当前 MVP 阶段使用单一模型（默认 GPT-4o），模型分级路由为未来优化方向。通过配置 `ai.llm.model` 可手动切换模型。
 
-## 策略四：缓存与复用（规划中）
+## 策略四：缓存与复用（待实现）
 
-- **语义缓存**（规划中）：相似问题直接返回缓存结果（如反复问"这是什么"）
+- **语义缓存**（待实现）：相似问题直接返回缓存结果（如反复问"这是什么"）
 - **上下文复用**：连续对话中，未变化的图像不必重复发送（已通过重复画面过滤实现）
 - **对话历史裁剪**：前端按 `MAX_HISTORY_ROUNDS = 10` 裁剪，后端按 `defaultHistorySize = 20` 裁剪，限制每轮的固定 token 开销
diff --git a/docs/10-功能创意.md b/docs/08-功能创意.md
similarity index 100%
rename from docs/10-功能创意.md
rename to docs/08-功能创意.md
diff --git a/docs/11-持久化与用户系统设计.md b/docs/11-持久化与用户系统设计.md
deleted file mode 100644
index 3f5d2c7..0000000
--- a/docs/11-持久化与用户系统设计.md
+++ /dev/null
@@ -1,751 +0,0 @@
-# 持久化与用户系统设计
-
-## 概述
-
-本文档定义用户注册/登录、JWT 认证、对话历史持久化的完整设计方案。核心目标：**用户登录后可在对话列表中选择历史对话继续交谈**。
-
-### 设计决策
-
-| 决策项 | 选择 | 理由 |
-|--------|------|------|
-| 认证方式 | JWT（access + refresh 双 token） | 无状态，适合分布式部署 |
-| 注册方式 | 用户名 + 密码 | MVP 最简方案 |
-| 密码存储 | bcrypt hash | 行业标准，抗彩虹表 |
-| 对话恢复 | 对话列表选择 | 用户可见所有历史对话，自主选择继续或新建 |
-| 对话标题 | 自动取首条用户消息前 20 字符 | 零成本，自然可读 |
-| 图像持久化 | 不存储 | 节省空间，文字历史已足够 |
-| 登录后行为 | 先选对话，再进聊天 | 明确的入口，避免困惑 |
-| WS 认证 | URL query 参数 `?token=xxx` | HTTP Upgrade 无法带 Authorization header |
-| Token 策略 | access 15min + refresh 7day | 安全性与体验平衡 |
-
----
-
-## 一、数据库设计
-
-### 1.1 ER 关系
-
-```
-users 1──N sessions 1──N messages
-  │
-  └── refresh_tokens (1──N, token 轮转管理)
-```
-
-### 1.2 表结构
-
-```sql
--- 用户表
-CREATE TABLE users (
-    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    username      VARCHAR(64) NOT NULL UNIQUE,
-    password_hash VARCHAR(256) NOT NULL,       -- bcrypt hash
-    created_at    TIMESTAMPTZ DEFAULT now(),
-    updated_at    TIMESTAMPTZ DEFAULT now()
-);
-
-CREATE INDEX idx_users_username ON users(username);
-
--- 会话（对话）表
-CREATE TABLE sessions (
-    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    title       VARCHAR(128) DEFAULT '新对话',
-    created_at  TIMESTAMPTZ DEFAULT now(),
-    updated_at  TIMESTAMPTZ DEFAULT now()
-);
-
-CREATE INDEX idx_sessions_user_id ON sessions(user_id, updated_at DESC);
-
--- 消息表
-CREATE TABLE messages (
-    id          BIGSERIAL PRIMARY KEY,
-    session_id  UUID NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
-    role        VARCHAR(16) NOT NULL,   -- "user" | "assistant"
-    content     TEXT NOT NULL,
-    tokens_used INTEGER DEFAULT 0,
-    created_at  TIMESTAMPTZ DEFAULT now()
-);
-
-CREATE INDEX idx_messages_session_id ON messages(session_id, id);
-
--- 刷新令牌表
-CREATE TABLE refresh_tokens (
-    id          BIGSERIAL PRIMARY KEY,
-    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    token_hash  VARCHAR(256) NOT NULL UNIQUE,  -- SHA256(refresh_token)
-    expires_at  TIMESTAMPTZ NOT NULL,
-    created_at  TIMESTAMPTZ DEFAULT now()
-);
-
-CREATE INDEX idx_refresh_tokens_user ON refresh_tokens(user_id);
-CREATE INDEX idx_refresh_tokens_hash ON refresh_tokens(token_hash);
-```
-
-### 1.3 与现有设计的差异
-
-| 变更 | 原设计（`02-系统架构.md`） | 新设计 | 理由 |
-|------|--------------------------|--------|------|
-| `sessions.user_id` | `NOT NULL` 无外键 | `REFERENCES users(id) ON DELETE CASCADE` | 关联用户，级联删除 |
-| `sessions.title` | 无 | `VARCHAR(128) DEFAULT '新对话'` | 对话列表展示 |
-| `messages.image_url` | 有 | 移除 | 不存储图像 |
-| `usage_daily` | 有 | MVP 暂不实现 | 按需后加 |
-| 新增 `users` | 无 | 新增 | 用户系统核心 |
-| 新增 `refresh_tokens` | 无 | 新增 | JWT refresh 机制 |
-
----
-
-## 二、JWT 认证设计
-
-### 2.1 Token 结构
-
-**access_token**：
-- payload: `{user_id, username, exp (15min), iat, iss: "camtalk"}`
-- 签名算法: HS256（对称密钥，从配置读取）
-- 存储位置: 前端 localStorage
-
-**refresh_token**：
-- payload: `{user_id, token_id (UUID), exp (7day), iat, iss: "camtalk"}`
-- 存储位置: 前端 localStorage + 数据库 `refresh_tokens` 表（存 SHA256 hash）
-
-### 2.2 认证流程
-
-#### 注册
-
-```
-用户 ──POST /api/auth/register──> 检查 username 唯一性
-                                  bcrypt hash 密码
-                                  INSERT users
-                                  ↓
-                          生成 access_token + refresh_token
-                          存 SHA256(refresh_token) 到 DB
-                                  ↓
-                          返回 {user, access_token, refresh_token}
-```
-
-#### 登录
-
-```
-用户 ──POST /api/auth/login──> 查 users 表 by username
-                               bcrypt.CompareHashAndPassword
-                               ↓
-                       生成 access_token + refresh_token
-                       存 SHA256(refresh_token) 到 DB
-                               ↓
-                       返回 {user, access_token, refresh_token}
-```
-
-#### 刷新
-
-```
-用户 ──POST /api/auth/refresh──> 校验 refresh_token 签名和过期
-                                 查 DB 验证 hash 存在
-                                 ↓
-                         撤销旧 refresh_token（DELETE）
-                         生成新的 access + refresh
-                         存新 refresh_token hash
-                                 ↓
-                         返回 {access_token, refresh_token}
-```
-
-#### 登出
-
-```
-用户 ──POST /api/auth/logout──> 撤销 refresh_token (DELETE from DB)
-                                前端清除 localStorage
-```
-
-### 2.3 Go 实现接口
-
-```go
-// internal/auth/jwt.go
-
-type Claims struct {
-    UserID   string `json:"user_id"`
-    Username string `json:"username"`
-    jwt.RegisteredClaims
-}
-
-type TokenManager struct {
-    secret     []byte
-    accessTTL  time.Duration // 15min
-    refreshTTL time.Duration // 7day
-}
-
-// GeneratePair 生成 access + refresh token 对。
-func (tm *TokenManager) GeneratePair(userID, username string) (access, refresh string, err error)
-
-// ValidateAccess 校验 access_token，返回 Claims。
-func (tm *TokenManager) ValidateAccess(tokenStr string) (*Claims, error)
-
-// ValidateRefresh 校验 refresh_token 签名和过期（不查 DB，DB 校验由 service 层负责）。
-func (tm *TokenManager) ValidateRefresh(tokenStr string) (*Claims, error)
-
-// HashToken 计算 token 的 SHA256 hash（用于 DB 存储）。
-func HashToken(token string) string
-```
-
-```go
-// internal/auth/middleware.go
-
-// AuthMiddleware Gin 中间件：从 Authorization: Bearer <token> 提取并校验。
-// 校验通过后将 Claims 写入 gin.Context。
-func AuthMiddleware(tm *TokenManager) gin.HandlerFunc {
-    return func(c *gin.Context) {
-        auth := c.GetHeader("Authorization")
-        if !strings.HasPrefix(auth, "Bearer ") {
-            c.AbortWithStatusJSON(401, gin.H{"error": "missing token"})
-            return
-        }
-        claims, err := tm.ValidateAccess(strings.TrimPrefix(auth, "Bearer "))
-        if err != nil {
-            c.AbortWithStatusJSON(401, gin.H{"error": "invalid token"})
-            return
-        }
-        c.Set("claims", claims)
-        c.Set("user_id", claims.UserID)
-        c.Next()
-    }
-}
-```
-
----
-
-## 三、REST API 设计
-
-### 3.1 认证 API（新增）
-
-#### 注册
-
-```
-POST /api/auth/register
-Content-Type: application/json
-
-{"username": "alice", "password": "s3cret123"}
-```
-
-响应：
-
-```json
-// 201 Created
-{
-  "user": {"id": "uuid", "username": "alice", "created_at": "2026-06-14T10:00:00Z"},
-  "access_token": "eyJ...",
-  "refresh_token": "eyJ..."
-}
-```
-
-错误码：`USERNAME_TAKEN`（409）、`INVALID_INPUT`（400，用户名/密码格式不合规）
-
-#### 登录
-
-```
-POST /api/auth/login
-Content-Type: application/json
-
-{"username": "alice", "password": "s3cret123"}
-```
-
-响应：
-
-```json
-// 200 OK
-{
-  "user": {"id": "uuid", "username": "alice"},
-  "access_token": "eyJ...",
-  "refresh_token": "eyJ..."
-}
-```
-
-错误码：`INVALID_CREDENTIALS`（401）
-
-#### 刷新 Token
-
-```
-POST /api/auth/refresh
-Content-Type: application/json
-
-{"refresh_token": "eyJ..."}
-```
-
-响应：
-
-```json
-// 200 OK
-{
-  "access_token": "eyJ...",
-  "refresh_token": "eyJ..."
-}
-```
-
-错误码：`INVALID_TOKEN`（401）
-
-#### 登出
-
-```
-POST /api/auth/logout
-Authorization: Bearer <access_token>
-Content-Type: application/json
-
-{"refresh_token": "eyJ..."}
-```
-
-响应：`204 No Content`
-
-### 3.2 对话管理 API（新增）
-
-所有端点需要 `Authorization: Bearer <access_token>` header。
-
-#### 获取对话列表
-
-```
-GET /api/conversations?page=1&size=20
-```
-
-响应：
-
-```json
-// 200 OK
-{
-  "conversations": [
-    {
-      "id": "uuid",
-      "title": "这是一朵红色的玫瑰花",
-      "last_message": "它看起来很美丽。",
-      "message_count": 6,
-      "updated_at": "2026-06-14T10:30:00Z"
-    }
-  ],
-  "total": 42,
-  "page": 1,
-  "size": 20
-}
-```
-
-#### 创建新对话
-
-```
-POST /api/conversations
-Content-Type: application/json
-
-{}
-```
-
-响应：
-
-```json
-// 201 Created
-{
-  "id": "uuid",
-  "title": "新对话",
-  "created_at": "2026-06-14T10:00:00Z"
-}
-```
-
-#### 获取对话详情
-
-```
-GET /api/conversations/:id
-```
-
-响应：
-
-```json
-// 200 OK
-{
-  "id": "uuid",
-  "title": "这是一朵红色的玫瑰花",
-  "created_at": "2026-06-14T10:00:00Z",
-  "updated_at": "2026-06-14T10:30:00Z",
-  "config": {"tts_enabled": true, "detail_level": "low", "language": "zh-CN"}
-}
-```
-
-#### 更新对话标题
-
-```
-PATCH /api/conversations/:id
-Content-Type: application/json
-
-{"title": "新的标题"}
-```
-
-响应：`200 OK` + 更新后的对话详情
-
-#### 删除对话
-
-```
-DELETE /api/conversations/:id
-```
-
-响应：`204 No Content`（级联删除 messages）
-
-#### 获取对话历史消息
-
-```
-GET /api/conversations/:id/messages?limit=50&before=<message_id>
-```
-
-响应：
-
-```json
-// 200 OK
-{
-  "messages": [
-    {"id": 1, "role": "user", "content": "这是什么花？", "created_at": "..."},
-    {"id": 2, "role": "assistant", "content": "这是一朵红色的玫瑰。", "tokens_used": 42, "created_at": "..."}
-  ],
-  "has_more": false
-}
-```
-
-### 3.3 现有 API 变更
-
-| 端点 | 变更 |
-|------|------|
-| `GET /api/health` | 不变 |
-| `POST /api/sessions` | **废弃**，使用 `POST /api/conversations` 替代 |
-| `DELETE /api/sessions/{id}` | **废弃**，使用 `DELETE /api/conversations/:id` 替代 |
-
-### 3.4 新增错误码
-
-| 错误码 | HTTP 状态 | 含义 |
-|--------|-----------|------|
-| `USERNAME_TAKEN` | 409 | 用户名已被注册 |
-| `INVALID_CREDENTIALS` | 401 | 用户名或密码错误 |
-| `INVALID_TOKEN` | 401 | JWT 无效或已过期 |
-| `INVALID_INPUT` | 400 | 请求参数不合规（用户名/密码长度等） |
-
----
-
-## 四、Session Manager 改造
-
-### 4.1 接口扩展
-
-```go
-// internal/session/manager.go
-
-type Manager interface {
-    // ===== 原有方法（签名变更） =====
-
-    // Create 创建新会话，关联 user_id。
-    Create(ctx context.Context, userID string, config models.SessionConfig) (string, error)
-
-    Get(ctx context.Context, sessionID string) (*models.Session, error)
-    UpdateConfig(ctx context.Context, sessionID string, patch models.SessionConfigPatch) error
-    GetHistory(ctx context.Context, sessionID string, limit int) ([]models.Message, error)
-    AppendMessage(ctx context.Context, sessionID string, msg models.Message) error
-    SetActiveRequest(ctx context.Context, sessionID string, requestID string) error
-    GetActiveRequestID(ctx context.Context, sessionID string) (string, error)
-    ClearActiveRequest(ctx context.Context, sessionID string) error
-    Touch(ctx context.Context, sessionID string) error
-    Destroy(ctx context.Context, sessionID string) error
-    ActiveCount() int
-
-    // ===== 新增方法 =====
-
-    // ListByUser 获取用户的对话列表（分页）。
-    ListByUser(ctx context.Context, userID string, page, size int) ([]ConversationSummary, int, error)
-
-    // UpdateTitle 更新对话标题。
-    UpdateTitle(ctx context.Context, sessionID string, title string) error
-
-    // LoadFromDB 从 PostgreSQL 加载历史消息到热存储（Redis/内存）。
-    // 用户选择历史对话继续交谈时调用。
-    LoadFromDB(ctx context.Context, sessionID string) error
-}
-
-// ConversationSummary 对话列表项。
-type ConversationSummary struct {
-    ID           string    `json:"id"`
-    Title        string    `json:"title"`
-    LastMessage  string    `json:"last_message"`
-    MessageCount int       `json:"message_count"`
-    UpdatedAt    time.Time `json:"updated_at"`
-}
-```
-
-### 4.2 Model 变更
-
-```go
-// internal/models/models.go
-
-type Session struct {
-    ID        string        `json:"session_id"`
-    UserID    string        `json:"user_id"`     // 新增
-    Title     string        `json:"title"`       // 新增
-    CreatedAt time.Time     `json:"created_at"`
-    UpdatedAt time.Time     `json:"updated_at"`  // 新增
-    Config    SessionConfig `json:"config"`
-}
-
-type User struct {
-    ID           string    `json:"id"`
-    Username     string    `json:"username"`
-    PasswordHash string    `json:"-"`            // 不序列化到 JSON
-    CreatedAt    time.Time `json:"created_at"`
-    UpdatedAt    time.Time `json:"updated_at"`
-}
-```
-
-### 4.3 冷热数据策略
-
-```
-当前活跃会话:  Redis/内存（热） ←→ PostgreSQL（冷，write-through）
-历史会话加载:  PostgreSQL → Redis/内存（按需恢复）
-```
-
-**Write-through 保证持久化**：每次 `AppendMessage` 同时写入 PostgreSQL，确保服务重启不丢数据。
-
-**历史对话恢复流程**：
-1. 用户从对话列表选择一个历史对话
-2. 前端带 `conversation_id` 建立 WebSocket 连接
-3. 后端调用 `sessionManager.LoadFromDB(conversationID)` 将历史消息从 PostgreSQL 加载到 Redis/内存
-4. 后续对话正常走热存储路径
-
----
-
-## 五、WebSocket 认证集成
-
-### 5.1 连接流程
-
-```
-前端                          后端
-  |                              |
-  |-- WS /ws?token=<access> ---->|
-  |   &conversation_id=<uuid>    |
-  |                              |-- 校验 access_token
-  |                              |-- 校验 conversation_id 归属
-  |                              |-- LoadFromDB（如果是历史对话）
-  |                              |-- 创建新 session（如果 conversation_id 为空）
-  |<-- connected {session_id} ---|
-  |                              |
-  |-- query {image, audio} ----->|  （正常对话流程）
-```
-
-### 5.2 Go 实现
-
-```go
-// internal/ws/handler.go
-
-func (h *Handler) HandleWS(c *gin.Context) {
-    // 1. 提取并校验 access_token
-    tokenStr := c.Query("token")
-    if tokenStr == "" {
-        c.JSON(401, gin.H{"error": "missing token"})
-        return
-    }
-    claims, err := h.tokenManager.ValidateAccess(tokenStr)
-    if err != nil {
-        c.JSON(401, gin.H{"error": "invalid token"})
-        return
-    }
-
-    // 2. 提取 conversation_id（可选）
-    conversationID := c.Query("conversation_id")
-
-    // 3. 升级 WebSocket
-    conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
-    if err != nil {
-        return
-    }
-
-    // 4. 获取或创建 session
-    var sessionID string
-    if conversationID != "" {
-        // 验证该对话属于当前用户
-        sess, err := h.sessionMgr.Get(c, conversationID)
-        if err != nil || sess.UserID != claims.UserID {
-            conn.WriteJSON(models.WsError{Type: "error", Code: "SESSION_NOT_FOUND"})
-            conn.Close()
-            return
-        }
-        // 加载历史到热存储
-        h.sessionMgr.LoadFromDB(c, conversationID)
-        sessionID = conversationID
-    } else {
-        // 创建新对话
-        sessionID, _ = h.sessionMgr.Create(c, claims.UserID, models.DefaultConfig())
-    }
-
-    // 5. 进入正常 WS 处理循环
-    h.handleSession(conn, sessionID, claims.UserID)
-}
-```
-
-### 5.3 前端连接方式
-
-```typescript
-// WebSocket 连接
-const ws = new WebSocket(
-  `wss://${window.location.host}/ws?token=${accessToken}&conversation_id=${selectedConvId || ''}`
-);
-```
-
----
-
-## 六、前端设计概要
-
-### 6.1 页面路由
-
-```
-/              → 未登录重定向到 /login
-/login         → AuthPage（登录/注册表单）
-/chat          → 主界面（需登录）
-/chat/:id      → 主界面，自动加载指定对话
-```
-
-### 6.2 组件结构
-
-```
-App
-├── AuthPage                 ← 新增：登录/注册
-└── ChatLayout（需登录）
-    ├── ConversationList     ← 新增：侧边栏对话列表
-    │   ├── 对话项（标题、最后消息、时间）
-    │   ├── 新建对话按钮
-    │   └── 删除对话按钮
-    ├── ChatPanel            ← 现有，需适配多对话
-    ├── VideoPreview         ← 现有
-    ├── MicManager           ← 现有
-    └── ConfigPanel          ← 现有
-```
-
-### 6.3 新增 Hook
-
-```typescript
-// useAuth — 认证状态管理
-function useAuth() {
-  const [user, setUser] = useState<User | null>(null);
-  const [loading, setLoading] = useState(true);
-
-  const login = async (username: string, password: string) => { ... };
-  const register = async (username: string, password: string) => { ... };
-  const logout = async () => { ... };
-  const refreshToken = async () => { ... };
-
-  // 请求拦截器：自动附加 Authorization header
-  // 401 时自动尝试 refresh，失败则跳转登录
-
-  return { user, loading, login, register, logout };
-}
-
-// useConversations — 对话列表管理
-function useConversations() {
-  const [conversations, setConversations] = useState<ConversationSummary[]>([]);
-  const [currentId, setCurrentId] = useState<string | null>(null);
-
-  const fetchList = async (page?: number) => { ... };
-  const createNew = async () => { ... };
-  const deleteConv = async (id: string) => { ... };
-  const renameConv = async (id: string, title: string) => { ... };
-  const selectConv = (id: string) => { setCurrentId(id); };
-
-  return { conversations, currentId, fetchList, createNew, deleteConv, renameConv, selectConv };
-}
-```
-
-### 6.4 对话标题自动生成
-
-```go
-// 内部逻辑：首条 user 消息的前 20 个字符作为 title
-func generateTitle(firstMessage string) string {
-    runes := []rune(firstMessage)
-    if len(runes) > 20 {
-        return string(runes[:20]) + "…"
-    }
-    return firstMessage
-}
-```
-
-在 `AppendMessage` 时，如果 session 的 title 仍为 "新对话"，自动更新为 `generateTitle(msg.Content)`。
-
----
-
-## 七、配置扩展
-
-### 7.1 Go 配置结构体
-
-```go
-type Config struct {
-    App      AppConfig      `mapstructure:"app"`
-    Server   ServerConfig   `mapstructure:"server"`
-    Auth     AuthConfig     `mapstructure:"auth"`      // 新增
-    Redis    RedisConfig    `mapstructure:"redis"`
-    AI       AIConfig       `mapstructure:"ai"`
-    Storage  StorageConfig  `mapstructure:"storage"`
-    Log      LogConfig      `mapstructure:"log"`
-}
-
-type AuthConfig struct {
-    JWTSecret  string `mapstructure:"jwt_secret"`   // 必须通过环境变量设置
-    AccessTTL  int    `mapstructure:"access_ttl"`   // 分钟，默认 15
-    RefreshTTL int    `mapstructure:"refresh_ttl"`  // 分钟，默认 10080 (7天)
-}
-```
-
-### 7.2 配置文件示例
-
-```yaml
-# config.yaml
-auth:
-  access_ttl: 15        # 分钟
-  refresh_ttl: 10080    # 7天
-
-storage:
-  driver: "memory"      # "memory" | "postgres"
-  dsn: ""
-```
-
-### 7.3 环境变量
-
-| 配置项 | 环境变量 | 说明 |
-|--------|---------|------|
-| `auth.jwt_secret` | `CAMTALK_AUTH_JWT_SECRET` | **必须设置**，JWT 签名密钥 |
-| `auth.access_ttl` | `CAMTALK_AUTH_ACCESS_TTL` | access_token 有效期（分钟） |
-| `auth.refresh_ttl` | `CAMTALK_AUTH_REFRESH_TTL` | refresh_token 有效期（分钟） |
-| `storage.driver` | `CAMTALK_STORAGE_DRIVER` | `"memory"` 或 `"postgres"` |
-| `storage.dsn` | `CAMTALK_STORAGE_DSN` | PostgreSQL 连接串 |
-
----
-
-## 八、实施阶段
-
-### Phase 1：用户认证系统 ✅
-
-- [x] 数据库 schema 迁移脚本（users, refresh_tokens 表）— `migrations/001_users.up.sql`
-- [x] `internal/auth/` 包：TokenManager, bcrypt 工具, JWT 中间件
-- [x] `internal/store/user.go`：UserRepository 接口 + PostgreSQL 实现 + 内存实现
-- [x] REST API：`/api/auth/register`, `/api/auth/login`, `/api/auth/refresh`, `/api/auth/logout`
-- [x] 单元测试 — `jwt_test.go`, `service_test.go`, `auth_test.go`, `user_test.go`
-
-### Phase 2：对话 CRUD + 消息持久化 ✅
-
-- [x] 数据库 schema 迁移脚本（sessions, messages 表）— `migrations/002_messages.up.sql`, `003_sessions.up.sql`
-- [x] `internal/store/message.go`：MessageRepository 接口 + PostgreSQL 实现
-- [x] `internal/store/session.go`：SessionRepository 接口 + PostgreSQL 实现
-- [x] Session Manager 扩展：Create 绑定 user_id, ListByUser, UpdateTitle
-- [x] REST API：`/api/conversations` CRUD + `/api/conversations/:id/messages`
-- [x] Write-through：AppendMessage 同时写 PostgreSQL
-
-### Phase 3：对话历史恢复 ✅
-
-- [x] MemoryManager 支持从 PG 透明恢复会话（Get 时自动 LoadFromDB）
-- [x] 对话标题自动生成逻辑（首条 user 消息前 20 字符）
-- [x] REST API：对话详情、历史消息查询（游标分页）
-
-### Phase 4：前端集成 ✅
-
-- [x] `useAuth` hook + AuthProvider（自动附加 token、自动 refresh）
-- [x] `AuthPage` 组件（登录/注册表单）
-- [x] `SessionSidebar` 组件（对话列表、搜索、重命名、删除）
-- [x] `useSessionList` hook（localStorage 持久化）
-- [x] 路由守卫：未登录重定向到 AuthPage
-- [x] WebSocket 连接带 token + conversation_id
-- [x] `useVisionSession` 适配多对话切换
-
-### Phase 5：配置与收尾 ✅
-
-- [x] 配置结构体扩展（AuthConfig, SessionConfig, StorageConfig）
-- [x] config.yaml 更新
-- [x] 数据库迁移嵌入式自动执行（`go:embed`）
-- [x] 集成测试 — 122 个测试函数覆盖所有模块
-- [x] 更新 `02-系统架构.md` 和 `03-接口文档.md`
diff --git a/docs/PLAN_BACKEND.md b/docs/PLAN_BACKEND.md
deleted file mode 100644
index 52cacb2..0000000
--- a/docs/PLAN_BACKEND.md
+++ /dev/null
@@ -1,223 +0,0 @@
-# CamTalk 后端完善计划
-
-> **✅ 状态：全部完成。** 所有 Phase 已实现并通过测试（约 122 个测试函数）。本文档保留作为历史参考。
-
-## Context
-
-后端当前是一个骨架：`main.go` 启动 Gin 服务器，`ws/handler.go` 实现了 WebSocket 连接生命周期和消息分发，`models/models.go` 定义了所有协议消息类型，`config/config.go` 实现了 Viper 配置加载。但所有业务逻辑都是 TODO 桩——没有 Session Manager、没有 AI 服务客户端、没有编排层、没有日志/错误工具、没有测试。前端已基本完成，正在等待后端提供真实的 AI 管道。
-
-**目标**：按设计文档（`docs/03-接口文档.md` 为最高依据）逐步填充所有业务模块，使端到端的 STT → LLM → TTS 流式管道可用。
-
----
-
-## 分阶段实施
-
-### Phase 1：基础设施（logger、errors、config 接入、graceful shutdown） ✅
-
-**目标**：为后续模块提供日志、错误码、配置等基础能力，替换 `main.go` 中的硬编码值。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 1.1 | 实现 Zap 日志封装 | `internal/logger/logger.go` | 提供 `Init(level, format)` 和全局 `*zap.SugaredLogger`，替换所有 `log.Printf` |
-| 1.2 | 实现错误码常量 + WS 错误发送工具 | `internal/errors/codes.go` | 10 个错误码常量 + `SendWSError(client, code, requestID, err)` |
-| 1.3 | main.go 接入 config.Load() | `cmd/server/main.go` | 用 `cfg.Server.Host:Port` 替换硬编码 `:8080`，初始化 logger |
-| 1.4 | 添加 graceful shutdown | `cmd/server/main.go` | `signal.NotifyContext` + `http.Server.Shutdown`，10s drain |
-| 1.5 | 添加 .gitignore | `backend/.gitignore` | 排除 `server` 二进制、`.env`、`tmp/` |
-
-> **CORS**：不在此处实现，生产环境由 Nginx 反向代理统一处理跨域。
-
----
-
-### Phase 2：Session Manager ✅
-
-**目标**：实现会话生命周期管理，让 WS handler 能追踪会话、存储对话历史。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 2.1 | 定义 SessionManager 接口 | `internal/session/manager.go` | 方法：`Create`, `Get`, `UpdateConfig`, `GetHistory`, `AppendMessage`, `SetActiveRequest`, `ClearActiveRequest`, `Touch`, `Destroy` |
-| 2.2 | 实现内存版 SessionManager | `internal/session/memory.go` | `sync.RWMutex` + `map[string]*sessionEntry`，TTL 30 分钟，历史上限 20 条 |
-| 2.3 | 实现 Redis 版 SessionManager | `internal/session/redis.go` | `session:{id}:meta` Hash + `session:{id}:history` List，TTL 刷新，选配 |
-| 2.4 | 编写 Session Manager 测试 | `internal/session/memory_test.go` | 覆盖 Create/Get/Expire/Destroy/AppendMessage/History 上限 |
-| 2.5 | WS handler 接入 SessionManager | `internal/ws/handler.go` | `ServeWS` 接收 `session.Manager` 参数；`connected` 消息后创建会话；`query` 时 Touch + SetActiveRequest；`config` 时 UpdateConfig；断开时不销毁（自然过期） |
-
----
-
-### Phase 3：AI 服务层接口 + 实现 ✅
-
-**目标**：定义并实现三个 AI 服务客户端，每个服务一个独立包。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| **3a. STT** | | | |
-| 3.1 | STT 接口定义 | `internal/ai/stt/stt.go` | `Service` 接口：`Recognize(ctx, audio []byte, opts Options) (string, error)`。`Options`: Encoding, SampleRate, Language |
-| 3.2 | Deepgram 实现 | `internal/ai/stt/deepgram.go` | WebSocket 连接 `wss://api.deepgram.com/v1/listen`，发送 PCM 音频，接收转录结果，5s 超时 |
-| 3.3 | STT 测试（mock） | `internal/ai/stt/deepgram_test.go` | httptest/WebSocket mock，验证连接、发送、超时 |
-| **3b. LLM** | | | |
-| 3.4 | LLM 接口定义 | `internal/ai/llm/llm.go` | `Service` 接口：`ChatStream(ctx, req Request) (<-chan Chunk, error)`。`Request`: Image, Text, History, Language。`Chunk`: Delta, Done, TokensUsed, Model |
-| 3.5 | OpenAI 实现 | `internal/ai/llm/openai.go` | `POST /v1/chat/completions` + `stream: true`，SSE 解析，10s 超时，image 以 `data:image/jpeg;base64,...` 传入 |
-| 3.6 | System Prompt 定义 | `internal/ai/llm/prompt.go` | 中文视觉助手提示词，根据 Language/DetailLevel 动态构建 |
-| 3.7 | LLM 测试（mock） | `internal/ai/llm/openai_test.go` | httptest mock SSE 流，验证流式解析、超时、错误处理 |
-| **3c. TTS** | | | |
-| 3.8 | TTS 接口定义 | `internal/ai/tts/tts.go` | `Service` 接口：`SynthesizeStream(ctx, textStream <-chan string, opts Options) (<-chan Chunk, error)`。`Chunk`: Audio []byte, IsLast |
-| 3.9 | OpenAI 实现 | `internal/ai/tts/openai.go` | `POST /v1/audio/speech` 模型 `tts-1`，逐句发送，返回 MP3 流，5s/句超时 |
-| 3.10 | TTS 测试（mock） | `internal/ai/tts/openai_test.go` | httptest mock，验证逐句合成、超时 |
-
----
-
-### Phase 4：AI Orchestrator（核心编排） ✅
-
-**目标**：实现 STT → LLM → TTS 流式并行管道，这是后端最关键的业务逻辑。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 4.1 | Orchestrator 接口 | `internal/orchestrator/orchestrator.go` | `ProcessQuery(ctx, sessionID, req, history, sender)` — 接收查询并执行管道 |
-| 4.2 | Sender 接口 | `internal/orchestrator/sender.go` | 抽象 WS 推送：`SendSTTResult`, `SendLLMChunk`, `SendLLMDone`, `SendTTSAudio`, `SendError`，便于测试 |
-| 4.3 | 管道实现 | `internal/orchestrator/pipeline.go` | ① `stt.Recognize()` → 发送 `stt_result` ② `llm.ChatStream()` 并行消费 token → 发送 `llm_chunk` + 句子切分 → channel ③ `tts.SynthesizeStream()` 从 channel 读取 → 发送 `tts_audio` ④ 流结束 → 发送 `llm_done` |
-| 4.4 | 句子切分器 | `internal/orchestrator/splitter.go` | 按 `。！？\n.!?` 切分，buffer size 4 channel |
-| 4.5 | 错误降级 | 同上文件 | STT 失败→STT_ERROR+abort；LLM 超时→LLM_TIMEOUT；TTS 失败→静默跳过 |
-| 4.6 | Interrupt 支持 | 同上文件 | context cancel 触发所有流中止 |
-| 4.7 | Orchestrator 测试 | `internal/orchestrator/pipeline_test.go` | mock 三个 AI service + mock sender，验证完整流程、中断、错误降级 |
-
----
-
-### Phase 5：WS Handler 完整接入 ✅
-
-**目标**：将 Session Manager + Orchestrator 串入 WebSocket handler，实现端到端消息处理。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 5.1 | Client 扩展 | `internal/ws/handler.go` | 添加 `session.Manager`、`orchestrator.Orchestrator`、`context.CancelFunc`（用于 interrupt） |
-| 5.2 | query 处理 | 同上 | 解码 audio Base64 → `stt.Recognize` 的输入；Touch 会话；设置 active request；启动 `orchestrator.ProcessQuery` goroutine |
-| 5.3 | config 处理 | 同上 | 调用 `session.UpdateConfig()` |
-| 5.4 | interrupt 处理 | 同上 | 查找 active request 的 cancel func，调用 `cancel()`，ClearActiveRequest |
-| 5.5 | Disconnect 处理 | 同上 | 取消当前活跃请求（如有），不销毁会话 |
-
----
-
-### Phase 6：REST API 补全 ✅
-
-**目标**：补全设计文档中的 REST 端点。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 6.1 | Session 路由 | `internal/api/session.go` | `POST /api/sessions` 创建会话，`DELETE /api/sessions/:id` 销毁会话 |
-| 6.2 | Health 更新 | `cmd/server/main.go` | 从 SessionManager 获取 `active_sessions` 真实值 |
-| 6.3 | 路由注册 | `cmd/server/main.go` | 统一注册 REST + WS 路由，注入依赖 |
-
----
-
-### Phase 7：Rate Limiter + Model Router（可选/MVP 后） 📋
-
-**目标**：防止滥用 + 智能模型选择，MVP 可简化或跳过。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 7.1 | 令牌桶 Rate Limiter | `internal/middleware/ratelimit.go` | `golang.org/x/time/rate` 或自实现，按 session ID 限流 |
-| 7.2 | Rate Limiter 中间件 | `internal/middleware/ratelimit.go` | 在 WS query 路径上检查，超限返回 `RATE_LIMITED` |
-| 7.3 | Model Router | `internal/ai/router.go` | 规则引擎：简单识别→GPT-4o-mini，深度分析→GPT-4o，暂不实现 o1 |
-
----
-
-### Phase 8：集成测试 + 文档同步 ✅
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 8.1 | WS 集成测试 | `internal/ws/handler_test.go` | 启动 Gin test server + gorilla websocket client，验证完整 query→stt_result→llm_chunk→llm_done→tts_audio 流程 |
-| 8.2 | 文档同步 | `docs/03-接口文档.md` | 代码实现与文档有偏差时更新文档 |
-| 8.3 | go.sum 清理 | `backend/` | `go mod tidy` 清理无用依赖 |
-
----
-
-## 关键文件清单
-
-```
-backend/
-  cmd/server/main.go                    ← Phase 1.3, 1.4, 1.5, 6.2, 6.3
-  internal/
-    config/config.go                    ← 已完成，Phase 1.3 接入
-    logger/logger.go                    ← Phase 1.1（新建）
-    errors/codes.go                     ← Phase 1.2（新建）
-    models/models.go                    ← 已完成，可能小幅扩展
-    session/
-      manager.go                        ← Phase 2.1（新建）
-      memory.go                         ← Phase 2.2（新建）
-      redis.go                          ← Phase 2.3（新建）
-      memory_test.go                    ← Phase 2.4（新建）
-    ai/
-      stt/
-        stt.go                          ← Phase 3.1（新建）
-        deepgram.go                     ← Phase 3.2（新建）
-        deepgram_test.go                ← Phase 3.3（新建）
-      llm/
-        llm.go                          ← Phase 3.4（新建）
-        openai.go                       ← Phase 3.5（新建）
-        prompt.go                       ← Phase 3.6（新建）
-        openai_test.go                  ← Phase 3.7（新建）
-      tts/
-        tts.go                          ← Phase 3.8（新建）
-        openai.go                       ← Phase 3.9（新建）
-        openai_test.go                  ← Phase 3.10（新建）
-      router.go                         ← Phase 7.3（新建）
-    orchestrator/
-      orchestrator.go                   ← Phase 4.1（新建）
-      sender.go                         ← Phase 4.2（新建）
-      pipeline.go                       ← Phase 4.3, 4.4, 4.5, 4.6（新建）
-      pipeline_test.go                  ← Phase 4.7（新建）
-    api/
-      session.go                        ← Phase 6.1（新建）
-    middleware/
-      ratelimit.go                      ← Phase 7.1, 7.2（新建）
-    ws/
-      handler.go                        ← Phase 5.1-5.5（修改）
-      handler_test.go                   ← Phase 8.1（新建）
-```
-
----
-
-## 新增依赖
-
-| 包 | 用途 | Phase |
-|----|------|-------|
-| `go.uber.org/zap` | 结构化日志 | 1 |
-| `github.com/redis/go-redis/v9` | Redis 客户端 | 2.3 |
-| `github.com/gorilla/websocket` | 已有，Deepgram WS 也复用 | 3.2 |
-
----
-
-## 执行顺序与依赖关系
-
-```
-Phase 1 (基础设施)
-  ↓
-Phase 2 (Session Manager)
-  ↓
-Phase 3 (AI 服务层)  ← 可与 Phase 2 并行开发
-  ↓
-Phase 4 (Orchestrator)  ← 依赖 Phase 2 + 3
-  ↓
-Phase 5 (WS Handler 接入)  ← 依赖 Phase 4
-  ↓
-Phase 6 (REST API)  ← 依赖 Phase 2
-  ↓
-Phase 7 (Rate Limiter + Router)  ← 独立，可推后
-  ↓
-Phase 8 (集成测试 + 文档)
-```
-
----
-
-## 验证方案
-
-1. **单元测试**：每个模块独立测试，mock 外部依赖（AI API、Redis）
-2. **集成测试**：`httptest` 启动 Gin server，用 gorilla/websocket 客户端模拟完整 query 流程
-3. **端到端手动测试**：启动后端 → 打开前端 → 摄像头+麦克风对话 → 验证 stt_result / llm_chunk / tts_audio 消息流
-4. **go vet + go test ./...** 通过
-
----
-
-## 设计文档参考
-
-- 接口规范（最高优先级）：`docs/03-接口文档.md`
-- 系统架构：`docs/02-系统架构.md`
-- 技术选型：`docs/04-技术选型.md`
-- 成本控制：`docs/08-成本控制.md`
diff --git a/docs/PLAN_USER_MODULE.md b/docs/PLAN_USER_MODULE.md
deleted file mode 100644
index 2d338ed..0000000
--- a/docs/PLAN_USER_MODULE.md
+++ /dev/null
@@ -1,1381 +0,0 @@
-# CamTalk 后端用户模块构建计划
-
-> **✅ 状态：全部完成。** 所有 Phase 已实现并通过测试。本文档保留作为历史参考。
-
-## Context
-
-后端 AI 管道（STT → LLM → TTS）已完成，现在需要实现用户系统和对话持久化。目标：**用户注册登录后，可在对话列表中选择历史对话继续交谈**。
-
-设计文档：`docs/11-持久化与用户系统设计.md`（最高依据）
-技术选型：`docs/04-技术选型.md` 第四章
-现有后端计划：`docs/PLAN_BACKEND.md`（AI 管道部分已完成）
-
-### 当前后端状态
-
-| 模块 | 状态 |
-|------|------|
-| config | ✅ 已完成，需扩展 AuthConfig |
-| logger | ✅ 已完成 |
-| errors | ✅ 已完成，需扩展用户相关错误码 |
-| models | ✅ 已完成，需扩展 User/Session |
-| session manager | ✅ 内存/Redis 已完成，需扩展 user_id 绑定 |
-| AI 服务层 | ✅ STT/LLM/TTS 已完成 |
-| orchestrator | ✅ 已完成 |
-| ws handler | ✅ 已完成，需接入 JWT 认证 |
-| REST API | ✅ sessions CRUD 已完成，需新增 auth + conversations |
-
-### 新增依赖
-
-| 包 | 用途 | 引入阶段 |
-|----|------|---------|
-| `github.com/golang-jwt/jwt/v5` | JWT 签发/校验 | Phase 1 |
-| `golang.org/x/crypto/bcrypt` | 密码哈希 | Phase 1 |
-| `github.com/jackc/pgx/v5` | PostgreSQL 驱动 | Phase 2 |
-
----
-
-## 分阶段实施
-
-### Phase 1：配置扩展 + 数据库连接 ✅
-
-**目标**：扩展配置结构体，建立 PostgreSQL 连接池。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 1.1 | 扩展 Config 结构体 | `internal/config/config.go` | 新增 `AuthConfig`（JWTSecret, AccessTTL, RefreshTTL），`StorageConfig` 已有 Driver/DSN 字段 |
-| 1.2 | 添加配置默认值 | `internal/config/config.go` | `auth.access_ttl` 默认 15，`auth.refresh_ttl` 默认 10080 |
-| 1.3 | 实现数据库连接池 | `internal/store/db.go` | `NewPostgresPool(ctx, dsn) (*pgxpool.Pool, error)`，启动时调用，注入到各 repository |
-| 1.4 | 编写 schema 迁移脚本 | `migrations/001_users.up.sql` | `users` 表 + `refresh_tokens` 表 |
-| 1.5 | 编写回滚脚本 | `migrations/001_users.down.sql` | DROP TABLE |
-| 1.6 | main.go 条件初始化 DB | `cmd/server/main.go` | `storage.driver == "postgres"` 时创建 pgxpool，否则跳过（纯内存模式） |
-
-**配置扩展示例**：
-
-```go
-// internal/config/config.go 新增
-
-type AuthConfig struct {
-    JWTSecret  string `mapstructure:"jwt_secret"`   // 必须通过 CAMTALK_AUTH_JWT_SECRET 设置
-    AccessTTL  int    `mapstructure:"access_ttl"`   // 分钟，默认 15
-    RefreshTTL int    `mapstructure:"refresh_ttl"`  // 分钟，默认 10080
-}
-```
-
-**数据库连接**：
-
-```go
-// internal/store/db.go
-
-package store
-
-import (
-    "context"
-    "github.com/jackc/pgx/v5/pgxpool"
-)
-
-func NewPostgresPool(ctx context.Context, dsn string) (*pgxpool.Pool, error) {
-    cfg, err := pgxpool.ParseConfig(dsn)
-    if err != nil {
-        return nil, err
-    }
-    cfg.MaxConns = 10
-    return pgxpool.NewWithConfig(ctx, cfg)
-}
-```
-
----
-
-### Phase 2：用户模型 + Repository ✅
-
-**目标**：定义用户数据模型和持久化接口。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 2.1 | 扩展 models | `internal/models/models.go` | 新增 `User` 结构体（ID, Username, PasswordHash, CreatedAt, UpdatedAt） |
-| 2.2 | 定义 UserRepository 接口 | `internal/store/user.go` | `Create`, `FindByUsername`, `FindByID`, `SaveRefreshToken`, `FindRefreshToken`, `DeleteRefreshToken` |
-| 2.3 | 实现 PostgreSQL UserRepository | `internal/store/user_pg.go` | pgx 实现，所有方法使用 `pgxpool.Pool` |
-| 2.4 | 实现内存 UserRepository（测试用） | `internal/store/user_mem.go` | `sync.RWMutex` + map，单元测试时注入 |
-| 2.5 | 编写 UserRepository 测试 | `internal/store/user_pg_test.go` | 需要测试 DB 或 mock |
-
-**UserRepository 接口**：
-
-```go
-// internal/store/user.go
-
-package store
-
-import (
-    "context"
-    "errors"
-    "time"
-)
-
-var (
-    ErrUserNotFound      = errors.New("user not found")
-    ErrUsernameTaken     = errors.New("username already taken")
-    ErrRefreshTokenNotFound = errors.New("refresh token not found")
-)
-
-type UserRepository interface {
-    // Create 创建用户，返回生成的 ID。
-    Create(ctx context.Context, username, passwordHash string) (string, error)
-
-    // FindByUsername 按用户名查找，不存在返回 ErrUserNotFound。
-    FindByUsername(ctx context.Context, username string) (*User, error)
-
-    // FindByID 按 ID 查找，不存在返回 ErrUserNotFound。
-    FindByID(ctx context.Context, id string) (*User, error)
-
-    // SaveRefreshToken 保存 refresh token hash。
-    SaveRefreshToken(ctx context.Context, userID, tokenHash string, expiresAt time.Time) error
-
-    // FindRefreshToken 按 token hash 查找，返回 user_id。不存在返回 ErrRefreshTokenNotFound。
-    FindRefreshToken(ctx context.Context, tokenHash string) (string, error)
-
-    // DeleteRefreshToken 按 token hash 删除。
-    DeleteRefreshToken(ctx context.Context, tokenHash string) error
-
-    // DeleteUserRefreshTokens 删除用户的所有 refresh token（登出所有设备）。
-    DeleteUserRefreshTokens(ctx context.Context, userID string) error
-}
-
-// User 用户数据模型（store 层）。
-type User struct {
-    ID           string
-    Username     string
-    PasswordHash string
-    CreatedAt    time.Time
-    UpdatedAt    time.Time
-}
-```
-
----
-
-### Phase 3：JWT + 认证服务 ✅
-
-**目标**：实现 JWT 签发/校验、bcrypt 密码处理、认证业务逻辑。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 3.1 | 实现 TokenManager | `internal/auth/jwt.go` | `GeneratePair`, `ValidateAccess`, `ValidateRefresh`, `HashToken` |
-| 3.2 | 实现密码工具 | `internal/auth/password.go` | `HashPassword(password) (string, error)`, `CheckPassword(hash, password) error` |
-| 3.3 | 实现 AuthMiddleware | `internal/auth/middleware.go` | Gin 中间件，从 `Authorization: Bearer <token>` 提取 Claims 写入 Context |
-| 3.4 | 定义 AuthService 接口 | `internal/auth/service.go` | 业务层封装：`Register`, `Login`, `Refresh`, `Logout` |
-| 3.5 | 实现 AuthService | `internal/auth/service.go` | 组合 TokenManager + UserRepository |
-| 3.6 | 编写 TokenManager 测试 | `internal/auth/jwt_test.go` | 生成/校验/过期/hash |
-| 3.7 | 编写 AuthService 测试 | `internal/auth/service_test.go` | mock UserRepository，覆盖注册重复、密码错误、token 轮转 |
-
-**TokenManager 核心实现**：
-
-```go
-// internal/auth/jwt.go
-
-type Claims struct {
-    UserID   string `json:"user_id"`
-    Username string `json:"username"`
-    jwt.RegisteredClaims
-}
-
-type TokenManager struct {
-    secret     []byte
-    accessTTL  time.Duration
-    refreshTTL time.Duration
-}
-
-func NewTokenManager(secret string, accessTTL, refreshTTL time.Duration) *TokenManager {
-    return &TokenManager{
-        secret:     []byte(secret),
-        accessTTL:  accessTTL,
-        refreshTTL: refreshTTL,
-    }
-}
-
-func (tm *TokenManager) GeneratePair(userID, username string) (access, refresh string, err error) {
-    // access_token: 15min
-    accessClaims := &Claims{
-        UserID:   userID,
-        Username: username,
-        RegisteredClaims: jwt.RegisteredClaims{
-            ExpiresAt: jwt.NewNumericDate(time.Now().Add(tm.accessTTL)),
-            IssuedAt:  jwt.NewNumericDate(time.Now()),
-            Issuer:    "camtalk",
-        },
-    }
-    accessTkn := jwt.NewWithClaims(jwt.SigningMethodHS256, accessClaims)
-    access, err = accessTkn.SignedString(tm.secret)
-    if err != nil {
-        return "", "", err
-    }
-
-    // refresh_token: 7day, 含唯一 token_id
-    tokenID := uuid.New().String()
-    refreshClaims := &Claims{
-        UserID:   userID,
-        Username: username,
-        RegisteredClaims: jwt.RegisteredClaims{
-            ID:        tokenID,
-            ExpiresAt: jwt.NewNumericDate(time.Now().Add(tm.refreshTTL)),
-            IssuedAt:  jwt.NewNumericDate(time.Now()),
-            Issuer:    "camtalk",
-        },
-    }
-    refreshTkn := jwt.NewWithClaims(jwt.SigningMethodHS256, refreshClaims)
-    refresh, err = refreshTkn.SignedString(tm.secret)
-    return
-}
-
-func (tm *TokenManager) ValidateAccess(tokenStr string) (*Claims, error) {
-    return tm.validate(tokenStr)
-}
-
-func (tm *TokenManager) ValidateRefresh(tokenStr string) (*Claims, error) {
-    return tm.validate(tokenStr)
-}
-
-func (tm *TokenManager) validate(tokenStr string) (*Claims, error) {
-    token, err := jwt.ParseWithClaims(tokenStr, &Claims{}, func(t *jwt.Token) (interface{}, error) {
-        return tm.secret, nil
-    })
-    if err != nil {
-        return nil, err
-    }
-    claims, ok := token.Claims.(*Claims)
-    if !ok || !token.Valid {
-        return nil, jwt.ErrTokenInvalidClaims
-    }
-    return claims, nil
-}
-
-// HashToken SHA256 hash，用于 DB 存储。
-func HashToken(token string) string {
-    h := sha256.Sum256([]byte(token))
-    return hex.EncodeToString(h[:])
-}
-```
-
-**AuthService 接口**：
-
-```go
-// internal/auth/service.go
-
-type RegisterRequest struct {
-    Username string `json:"username"`
-    Password string `json:"password"`
-}
-
-type LoginRequest struct {
-    Username string `json:"username"`
-    Password string `json:"password"`
-}
-
-type RefreshRequest struct {
-    RefreshToken string `json:"refresh_token"`
-}
-
-type AuthResponse struct {
-    User         UserResponse `json:"user"`
-    AccessToken  string       `json:"access_token"`
-    RefreshToken string       `json:"refresh_token"`
-}
-
-type UserResponse struct {
-    ID        string    `json:"id"`
-    Username  string    `json:"username"`
-    CreatedAt time.Time `json:"created_at"`
-}
-
-type Service interface {
-    Register(ctx context.Context, req RegisterRequest) (*AuthResponse, error)
-    Login(ctx context.Context, req LoginRequest) (*AuthResponse, error)
-    Refresh(ctx context.Context, req RefreshRequest) (*AuthResponse, error)
-    Logout(ctx context.Context, userID, refreshToken string) error
-}
-```
-
----
-
-### Phase 4：认证 REST API ✅
-
-**目标**：实现注册、登录、刷新、登出四个端点。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 4.1 | 实现 AuthHandler | `internal/api/auth.go` | `Register`, `Login`, `Refresh`, `Logout` 处理函数 |
-| 4.2 | 输入校验 | `internal/api/auth.go` | 用户名 3-64 字符，密码 8-72 字符 |
-| 4.3 | 注册路由 | `internal/api/auth.go` | `RegisterRoutes(rg *gin.RouterGroup)` |
-| 4.4 | main.go 接入 | `cmd/server/main.go` | 创建 TokenManager + AuthService + AuthHandler，注册路由 |
-| 4.5 | 编写 API 测试 | `internal/api/auth_test.go` | httptest + mock AuthService |
-
-**AuthHandler 结构**：
-
-```go
-// internal/api/auth.go
-
-type AuthHandler struct {
-    authService auth.Service
-}
-
-func NewAuthHandler(authService auth.Service) *AuthHandler {
-    return &AuthHandler{authService: authService}
-}
-
-func (h *AuthHandler) RegisterRoutes(rg *gin.RouterGroup) {
-    auth := rg.Group("/auth")
-    {
-        auth.POST("/register", h.Register)
-        auth.POST("/login", h.Login)
-        auth.POST("/refresh", h.Refresh)
-        auth.POST("/logout", auth.AuthMiddleware(), h.Logout)
-    }
-}
-```
-
-**错误响应格式**（统一现有风格）：
-
-```json
-{
-  "code": "USERNAME_TAKEN",
-  "message": "username already taken"
-}
-```
-
-新增错误码到 `internal/errors/codes.go`：
-
-```go
-const (
-    CodeUsernameTaken      = "USERNAME_TAKEN"
-    CodeInvalidCredentials = "INVALID_CREDENTIALS"
-    CodeInvalidToken       = "INVALID_TOKEN"
-    CodeInvalidInput       = "INVALID_INPUT"
-)
-```
-
----
-
-### Phase 5：Session Manager 改造 ✅
-
-**目标**：Session Manager 关联 user_id，支持对话列表查询。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 5.1 | 扩展 Session 模型 | `internal/models/models.go` | `Session` 新增 `UserID`, `Title`, `UpdatedAt` 字段 |
-| 5.2 | 扩展 Manager 接口 | `internal/session/manager.go` | `Create` 签名加 `userID`；新增 `ListByUser`, `UpdateTitle`；新增 `ConversationSummary` 类型 |
-| 5.3 | 修改 MemoryManager | `internal/session/memory.go` | `Create` 存储 userID；实现 `ListByUser`（遍历+过滤+排序）；实现 `UpdateTitle` |
-| 5.4 | 修改 RedisManager | `internal/session/redis.go` | `session:{id}:meta` 新增 `user_id`、`title` 字段；`ListByUser` 使用 Redis Set `user:{id}:sessions` 索引 |
-| 5.5 | 编写新方法测试 | `internal/session/memory_test.go` | 覆盖 ListByUser 分页、UpdateTitle、Create 带 userID |
-| 5.6 | 更新 ws handler 调用 | `internal/ws/handler.go` | `sessionMgr.Create` 调用传入 userID（此时 Phase 7 才有真实 userID，先用空字符串兼容） |
-
-**接口变更**：
-
-```go
-// internal/session/manager.go 变更
-
-type Manager interface {
-    // Create 签名变更：新增 userID 参数
-    Create(ctx context.Context, userID string, config models.SessionConfig) (string, error)
-
-    // 新增方法
-    ListByUser(ctx context.Context, userID string, page, size int) ([]ConversationSummary, int, error)
-    UpdateTitle(ctx context.Context, sessionID string, title string) error
-
-    // 其余方法不变...
-}
-
-type ConversationSummary struct {
-    ID           string    `json:"id"`
-    Title        string    `json:"title"`
-    LastMessage  string    `json:"last_message"`
-    MessageCount int       `json:"message_count"`
-    UpdatedAt    time.Time `json:"updated_at"`
-}
-```
-
-**MemoryManager ListByUser 实现思路**：
-
-```go
-func (m *MemoryManager) ListByUser(ctx context.Context, userID string, page, size int) ([]ConversationSummary, int, error) {
-    m.mu.RLock()
-    defer m.mu.RUnlock()
-
-    // 收集该用户的所有 session
-    var list []ConversationSummary
-    for _, entry := range m.sessions {
-        if entry.session.UserID != userID {
-            continue
-        }
-        summary := ConversationSummary{
-            ID:           entry.session.ID,
-            Title:        entry.session.Title,
-            MessageCount: len(entry.history),
-            UpdatedAt:    entry.lastActive,
-        }
-        if len(entry.history) > 0 {
-            summary.LastMessage = entry.history[len(entry.history)-1].Content
-        }
-        list = append(list, summary)
-    }
-
-    // 按 UpdatedAt 降序排序
-    sort.Slice(list, func(i, j int) bool {
-        return list[i].UpdatedAt.After(list[j].UpdatedAt)
-    })
-
-    total := len(list)
-
-    // 分页
-    start := (page - 1) * size
-    if start >= total {
-        return []ConversationSummary{}, total, nil
-    }
-    end := start + size
-    if end > total {
-        end = total
-    }
-
-    return list[start:end], total, nil
-}
-```
-
----
-
-### Phase 6：对话 REST API ✅
-
-**目标**：实现对话 CRUD 和历史消息查询端点。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 6.1 | 实现 ConversationHandler | `internal/api/conversation.go` | `List`, `Create`, `Get`, `UpdateTitle`, `Delete`, `GetMessages` |
-| 6.2 | 权限校验 | `internal/api/conversation.go` | 每个端点校验 session.UserID == claims.UserID |
-| 6.3 | 注册路由 | `internal/api/conversation.go` | `RegisterRoutes(rg *gin.RouterGroup)`，全部走 AuthMiddleware |
-| 6.4 | main.go 接入 | `cmd/server/main.go` | 创建 ConversationHandler 并注册 |
-| 6.5 | 编写 API 测试 | `internal/api/conversation_test.go` | httptest + mock SessionManager |
-
-**ConversationHandler 结构**：
-
-```go
-// internal/api/conversation.go
-
-type ConversationHandler struct {
-    sessionMgr session.Manager
-}
-
-func (h *ConversationHandler) RegisterRoutes(rg *gin.RouterGroup) {
-    conv := rg.Group("/conversations", auth.AuthMiddleware(tokenMgr))
-    {
-        conv.GET("", h.List)
-        conv.POST("", h.Create)
-        conv.GET("/:id", h.Get)
-        conv.PATCH("/:id", h.UpdateTitle)
-        conv.DELETE("/:id", h.Delete)
-        conv.GET("/:id/messages", h.GetMessages)
-    }
-}
-```
-
-**权限校验模式**（每个端点复用）：
-
-```go
-func (h *ConversationHandler) getSessionForUser(c *gin.Context, sessionID string) (*models.Session, error) {
-    sess, err := h.sessionMgr.Get(c.Request.Context(), sessionID)
-    if err != nil {
-        return nil, err
-    }
-    userID := c.GetString("user_id") // 从 AuthMiddleware 写入
-    if sess.UserID != userID {
-        return nil, session.ErrSessionNotFound // 返回 404 而非 403，避免信息泄露
-    }
-    return sess, nil
-}
-```
-
-**GetMessages 实现要点**：
-- 从 Session Manager 的 `GetHistory` 获取消息
-- 支持 `?limit=50&before=<message_id>` 分页
-- 内存实现中，history 是全量存储的，直接按索引切片即可
-
----
-
-### Phase 7：WebSocket 认证集成 ✅
-
-**目标**：WS 连接需要 JWT 认证，支持指定 conversation_id 恢复历史对话。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 7.1 | 修改 ServeWS 签名 | `internal/ws/handler.go` | 新增 `tokenMgr *auth.TokenManager` 参数 |
-| 7.2 | WS 连接认证 | `internal/ws/handler.go` | 从 `?token=xxx` 提取并校验 access_token，失败返回 401 |
-| 7.3 | conversation_id 处理 | `internal/ws/handler.go` | `?conversation_id=xxx` 存在时：校验归属 → LoadFromDB → 复用 session；否则创建新 session |
-| 7.4 | AppendMessage 自动标题 | `internal/session/memory.go` | 首条 user 消息时，如果 title == "新对话"，自动更新为前 20 字符 |
-| 7.5 | main.go 更新 | `cmd/server/main.go` | 传入 tokenMgr 到 ServeWS |
-| 7.7 | 编写认证测试 | `internal/ws/handler_test.go` | 测试无 token / 过期 token / 有效 token / conversation_id 恢复 |
-
-**WS 连接流程变更**：
-
-```
-客户端请求:  GET /ws?token=<access>&conversation_id=<uuid>
-
-服务端处理:
-  1. token 为空 → 401 {"error": "missing token"}
-  2. token 无效/过期 → 401 {"error": "invalid token"}
-  3. conversation_id 非空:
-     a. session 不存在或 user_id 不匹配 → 401 {"error": "SESSION_NOT_FOUND"}
-     b. sessionMgr.LoadFromDB(conversationID) → 加载历史到热存储
-     c. sessionID = conversationID
-  4. conversation_id 为空:
-     a. sessionMgr.Create(userID, defaultConfig) → 创建新 session
-  5. Upgrade WebSocket → 发送 connected 消息
-```
-
-**对话标题自动生成**：
-
-```go
-// internal/session/memory.go — AppendMessage 中追加逻辑
-
-func (m *MemoryManager) AppendMessage(ctx context.Context, sessionID string, msg models.Message) error {
-    m.mu.Lock()
-    defer m.mu.Unlock()
-
-    entry, ok := m.sessions[sessionID]
-    if !ok {
-        return ErrSessionNotFound
-    }
-
-    entry.history = append(entry.history, msg)
-    entry.lastActive = time.Now()
-
-    // 自动更新标题
-    if msg.Role == "user" && entry.session.Title == "新对话" {
-        entry.session.Title = generateTitle(msg.Content)
-    }
-
-    // 限制历史上限
-    if len(entry.history) > m.maxHistory {
-        entry.history = entry.history[len(entry.history)-m.maxHistory:]
-    }
-
-    return nil
-}
-
-func generateTitle(firstMessage string) string {
-    runes := []rune(firstMessage)
-    if len(runes) > 20 {
-        return string(runes[:20]) + "…"
-    }
-    return firstMessage
-}
-```
-
----
-
-### Phase 8：消息持久化（Write-Through） ✅
-
-**目标**：对话消息同时写入 PostgreSQL，保证重启不丢数据。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 8.1 | 定义 MessageRepository 接口 | `internal/store/message.go` | `SaveMessage`, `GetMessages`, `GetLastMessage` |
-| 8.2 | 实现 PostgreSQL MessageRepository | `internal/store/message_pg.go` | pgx 实现 |
-| 8.3 | Session Manager 注入 MessageRepository | `internal/session/memory.go` | AppendMessage 时同时调用 repo.SaveMessage（write-through） |
-| 8.4 | LoadFromDB 实现 | `internal/session/memory.go` | 从 PostgreSQL 读取消息加载到内存 history |
-| 8.5 | ConversationSummary 查询优化 | `internal/store/message_pg.go` | 对话列表的 last_message 和 message_count 通过 SQL 聚合查询 |
-
-**MessageRepository 接口**：
-
-```go
-// internal/store/message.go
-
-type MessageRepository interface {
-    // SaveMessage 保存一条消息。
-    SaveMessage(ctx context.Context, sessionID string, msg models.Message, tokensUsed int) error
-
-    // GetMessages 获取会话的消息列表（分页，按 id 升序）。
-    GetMessages(ctx context.Context, sessionID string, limit int, beforeID int64) ([]StoredMessage, error)
-
-    // GetLastMessage 获取会话的最后一条消息。
-    GetLastMessage(ctx context.Context, sessionID string) (*StoredMessage, error)
-
-    // GetMessageCount 获取会话的消息总数。
-    GetMessageCount(ctx context.Context, sessionID string) (int, error)
-}
-
-type StoredMessage struct {
-    ID         int64     `json:"id"`
-    SessionID  string    `json:"-"`
-    Role       string    `json:"role"`
-    Content    string    `json:"content"`
-    TokensUsed int       `json:"tokens_used"`
-    CreatedAt  time.Time `json:"created_at"`
-}
-```
-
-**Write-Through 模式**：
-
-```go
-// internal/session/memory.go — AppendMessage 改造
-
-func (m *MemoryManager) AppendMessage(ctx context.Context, sessionID string, msg models.Message) error {
-    // 1. 写热存储（内存/Redis）
-    m.mu.Lock()
-    entry, ok := m.sessions[sessionID]
-    if !ok {
-        m.mu.Unlock()
-        return ErrSessionNotFound
-    }
-    entry.history = append(entry.history, msg)
-    entry.lastActive = time.Now()
-    if msg.Role == "user" && entry.session.Title == "新对话" {
-        entry.session.Title = generateTitle(msg.Content)
-    }
-    if len(entry.history) > m.maxHistory {
-        entry.history = entry.history[len(entry.history)-m.maxHistory:]
-    }
-    m.mu.Unlock()
-
-    // 2. 写冷存储（PostgreSQL，异步不阻塞）
-    if m.msgRepo != nil {
-        go func() {
-            if err := m.msgRepo.SaveMessage(context.Background(), sessionID, msg, 0); err != nil {
-                logger.Log.Warnw("persist message failed", "session", sessionID, "error", err)
-            }
-        }()
-    }
-
-    return nil
-}
-```
-
----
-
-### Phase 9：旧端点废弃 + 集成收尾 ✅
-
-**目标**：废弃旧的 `/api/sessions` 端点，完成全链路集成。
-
-| # | 任务 | 文件 | 说明 |
-|---|------|------|------|
-| 9.1 | 废弃旧 session 路由 | `internal/api/session.go` | 保留代码但标记 deprecated，或直接删除 |
-| 9.2 | main.go 完整组装 | `cmd/server/main.go` | 按 storage.driver 选择注入 MemoryRepo 或 PgRepo |
-| 9.3 | .env.example 更新 | `backend/.env.example` | 新增 `CAMTALK_AUTH_JWT_SECRET`、`CAMTALK_STORAGE_*` |
-| 9.4 | config.yaml 更新 | `backend/config.yaml` | 新增 auth 配置块 |
-| 9.5 | docker-compose 添加 PG | `docker-compose.yml` | PostgreSQL 15 服务 + 环境变量 |
-| 9.6 | go mod tidy | `backend/` | 清理依赖 |
-| 9.7 | 端到端手动测试 | — | 注册 → 登录 → 创建对话 → 发送消息 → 登出 → 重新登录 → 查看对话列表 → 选择历史对话继续 |
-
-**main.go 依赖注入全貌**：
-
-```go
-func main() {
-    cfg, _ := config.Load()
-    logger.Init(cfg.Log.Level, cfg.Log.Format)
-
-    // --- 存储层 ---
-    var (
-        userRepo    store.UserRepository
-        msgRepo     store.MessageRepository
-        sessionMgr  session.Manager
-    )
-
-    if cfg.Storage.Driver == "postgres" {
-        pool, _ := store.NewPostgresPool(ctx, cfg.Storage.DSN)
-        defer pool.Close()
-        userRepo = store.NewPgUserRepository(pool)
-        msgRepo = store.NewPgMessageRepository(pool)
-        sessionMgr = session.NewMemoryManager(..., msgRepo) // 注入 msgRepo
-    } else {
-        userRepo = store.NewMemUserRepository()
-        sessionMgr = session.NewMemoryManager(...) // 无 msgRepo，纯内存
-    }
-
-    // --- 认证 ---
-    tokenMgr := auth.NewTokenManager(cfg.Auth.JWTSecret,
-        time.Duration(cfg.Auth.AccessTTL)*time.Minute,
-        time.Duration(cfg.Auth.RefreshTTL)*time.Minute)
-    authService := auth.NewAuthService(tokenMgr, userRepo)
-
-    // --- AI 服务（不变）---
-    sttService := ...
-    llmService := ...
-    ttsService := ...
-    orch := orchestrator.New(sttService, llmService, ttsService, sessionMgr, cfg)
-
-    // --- 路由 ---
-    r := gin.New()
-    apiGroup := r.Group("/api")
-    apiGroup.GET("/health", healthHandler(sessionMgr, cfg))
-
-    authHandler := api.NewAuthHandler(authService)
-    authHandler.RegisterRoutes(apiGroup)
-
-    convHandler := api.NewConversationHandler(sessionMgr, tokenMgr)
-    convHandler.RegisterRoutes(apiGroup)
-
-    r.GET("/ws", ws.ServeWS(sessionMgr, orch, cfg, tokenMgr))
-
-    // ... 启动
-}
-```
-
----
-
-## 前端 API 接口参考
-
-本章节为前端开发者提供完整的 REST API 契约。所有接口以 JSON 通信，基地址与 WebSocket 同源（开发环境 `http://localhost:8080`，生产环境通过 Nginx 反代）。
-
-### 通用约定
-
-#### 认证方式
-
-需要认证的接口在请求头携带 JWT access token：
-
-```
-Authorization: Bearer <access_token>
-```
-
-未认证或 token 过期时返回 `401 Unauthorized`。
-
-#### 错误响应格式
-
-所有错误响应统一结构：
-
-```typescript
-interface ApiError {
-  code: string;     // 机器可读错误码
-  message: string;  // 人类可读描述
-}
-```
-
-示例：
-
-```json
-{
-  "code": "USERNAME_TAKEN",
-  "message": "username already taken"
-}
-```
-
-#### 新增错误码
-
-| 错误码 | HTTP 状态码 | 含义 |
-|--------|-----------|------|
-| `USERNAME_TAKEN` | 409 | 用户名已被注册 |
-| `INVALID_CREDENTIALS` | 401 | 用户名或密码错误 |
-| `INVALID_TOKEN` | 401 | JWT 无效或已过期 |
-| `INVALID_INPUT` | 400 | 请求参数校验失败 |
-| `SESSION_NOT_FOUND` | 404 | 对话不存在或无权访问 |
-
-#### 输入校验规则
-
-| 字段 | 规则 |
-|------|------|
-| `username` | 3-64 字符，仅允许字母、数字、下划线 |
-| `password` | 8-72 字符 |
-
----
-
-### 一、认证接口（`/api/auth`）
-
-#### 1.1 注册
-
-```
-POST /api/auth/register
-Content-Type: application/json
-```
-
-**请求体**：
-
-```typescript
-interface RegisterRequest {
-  username: string;  // 3-64 字符
-  password: string;  // 8-72 字符
-}
-```
-
-**成功响应** `201 Created`：
-
-```typescript
-interface AuthResponse {
-  user: {
-    id: string;          // UUID
-    username: string;
-    created_at: string;  // ISO 8601
-  };
-  access_token: string;   // JWT，15 分钟有效
-  refresh_token: string;  // JWT，7 天有效
-}
-```
-
-```json
-{
-  "user": {
-    "id": "550e8400-e29b-41d4-a716-446655440000",
-    "username": "alice",
-    "created_at": "2026-06-14T10:00:00Z"
-  },
-  "access_token": "eyJhbGciOiJIUzI1NiIs...",
-  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
-}
-```
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 400 | `INVALID_INPUT` | 用户名/密码不符合校验规则 |
-| 409 | `USERNAME_TAKEN` | 用户名已存在 |
-
----
-
-#### 1.2 登录
-
-```
-POST /api/auth/login
-Content-Type: application/json
-```
-
-**请求体**：
-
-```typescript
-interface LoginRequest {
-  username: string;
-  password: string;
-}
-```
-
-**成功响应** `200 OK`：同 `AuthResponse` 结构。
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 400 | `INVALID_INPUT` | 请求参数缺失或格式错误 |
-| 401 | `INVALID_CREDENTIALS` | 用户名或密码错误 |
-
----
-
-#### 1.3 刷新 Token
-
-```
-POST /api/auth/refresh
-Content-Type: application/json
-```
-
-**请求体**：
-
-```typescript
-interface RefreshRequest {
-  refresh_token: string;  // 之前签发的 refresh_token
-}
-```
-
-**成功响应** `200 OK`：同 `AuthResponse` 结构（返回新的 access_token + refresh_token，旧 refresh_token 失效——Token 轮转）。
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | refresh_token 无效或已过期 |
-
----
-
-#### 1.4 登出
-
-```
-POST /api/auth/logout
-Content-Type: application/json
-Authorization: Bearer <access_token>
-```
-
-**请求体**：
-
-```typescript
-interface LogoutRequest {
-  refresh_token: string;  // 要废弃的 refresh_token
-}
-```
-
-**成功响应** `204 No Content`（无响应体）。
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | access_token 无效或已过期 |
-
----
-
-### 二、对话接口（`/api/conversations`）
-
-> 以下所有接口均需认证（`Authorization: Bearer <access_token>`），省略不重复标注。
-
-#### 2.1 对话列表
-
-```
-GET /api/conversations?page=1&size=20
-```
-
-**查询参数**：
-
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `page` | int | 1 | 页码，从 1 开始 |
-| `size` | int | 20 | 每页条数，最大 50 |
-
-**成功响应** `200 OK`：
-
-```typescript
-interface ConversationListResponse {
-  conversations: ConversationSummary[];
-  total: number;  // 总条数
-  page: number;
-  size: number;
-}
-
-interface ConversationSummary {
-  id: string;            // 对话 ID（即 session_id）
-  title: string;         // 对话标题（首条消息前 20 字）
-  last_message: string;  // 最后一条消息内容预览
-  message_count: number; // 消息总数
-  updated_at: string;    // ISO 8601，最后活跃时间
-}
-```
-
-```json
-{
-  "conversations": [
-    {
-      "id": "550e8400-e29b-41d4-a716-446655440000",
-      "title": "这是一朵红色的玫瑰…",
-      "last_message": "它看起来很美丽。",
-      "message_count": 4,
-      "updated_at": "2026-06-14T10:05:30Z"
-    }
-  ],
-  "total": 1,
-  "page": 1,
-  "size": 20
-}
-```
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
-
----
-
-#### 2.2 创建对话
-
-```
-POST /api/conversations
-Content-Type: application/json
-```
-
-**请求体**（可选，全部有默认值）：
-
-```typescript
-interface CreateConversationRequest {
-  config?: {
-    tts_enabled?: boolean;         // 默认 true
-    detail_level?: "low" | "high"; // 默认 "low"
-    language?: string;             // 默认 "zh-CN"
-  };
-}
-```
-
-**成功响应** `201 Created`：
-
-```typescript
-interface ConversationDetail {
-  id: string;
-  title: string;
-  config: {
-    tts_enabled: boolean;
-    detail_level: "low" | "high";
-    language: string;
-  };
-  created_at: string;  // ISO 8601
-}
-```
-
-```json
-{
-  "id": "660e8400-e29b-41d4-a716-446655440001",
-  "title": "新对话",
-  "config": {
-    "tts_enabled": true,
-    "detail_level": "low",
-    "language": "zh-CN"
-  },
-  "created_at": "2026-06-14T11:00:00Z"
-}
-```
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
-
----
-
-#### 2.3 获取对话详情
-
-```
-GET /api/conversations/:id
-```
-
-**成功响应** `200 OK`：同 `ConversationDetail` 结构。
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
-| 404 | `SESSION_NOT_FOUND` | 对话不存在或不属于当前用户 |
-
----
-
-#### 2.4 更新对话标题
-
-```
-PATCH /api/conversations/:id
-Content-Type: application/json
-```
-
-**请求体**：
-
-```typescript
-interface UpdateTitleRequest {
-  title: string;  // 1-100 字符
-}
-```
-
-**成功响应** `200 OK`：
-
-```json
-{
-  "id": "550e8400-e29b-41d4-a716-446655440000",
-  "title": "新的自定义标题"
-}
-```
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 400 | `INVALID_INPUT` | title 为空或超长 |
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
-| 404 | `SESSION_NOT_FOUND` | 对话不存在或不属于当前用户 |
-
----
-
-#### 2.5 删除对话
-
-```
-DELETE /api/conversations/:id
-```
-
-**成功响应** `204 No Content`（无响应体）。
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
-| 404 | `SESSION_NOT_FOUND` | 对话不存在或不属于当前用户 |
-
----
-
-#### 2.6 获取对话消息
-
-```
-GET /api/conversations/:id/messages?limit=50&before=<message_id>
-```
-
-**查询参数**：
-
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `limit` | int | 50 | 返回条数，最大 100 |
-| `before` | int64 | — | 游标分页：返回此 message_id 之前的消息（不含），用于加载更多 |
-
-**成功响应** `200 OK`：
-
-```typescript
-interface MessagesResponse {
-  messages: StoredMessage[];
-  has_more: boolean;  // 是否还有更早的消息
-}
-
-interface StoredMessage {
-  id: number;           // 自增 ID，用于游标分页
-  role: "user" | "assistant";
-  content: string;
-  tokens_used: number;  // 该条消息消耗的 token 数
-  created_at: string;   // ISO 8601
-}
-```
-
-```json
-{
-  "messages": [
-    {
-      "id": 1001,
-      "role": "user",
-      "content": "这是什么花？",
-      "tokens_used": 0,
-      "created_at": "2026-06-14T10:01:00Z"
-    },
-    {
-      "id": 1002,
-      "role": "assistant",
-      "content": "这是一朵红色的玫瑰。",
-      "tokens_used": 42,
-      "created_at": "2026-06-14T10:01:02Z"
-    }
-  ],
-  "has_more": false
-}
-```
-
-**分页用法**：首次请求不带 `before`，获取最新消息。滚动到顶部时，取当前列表最小的 `id` 作为 `before` 参数请求更早的消息。
-
-**错误响应**：
-
-| 状态码 | code | 场景 |
-|--------|------|------|
-| 401 | `INVALID_TOKEN` | 未认证或 token 过期 |
-| 404 | `SESSION_NOT_FOUND` | 对话不存在或不属于当前用户 |
-
----
-
-### 三、WebSocket 认证变更
-
-连接地址变更为带 token 的查询参数：
-
-```
-ws://localhost:8080/ws?token=<access_token>&conversation_id=<uuid>
-```
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `token` | 是 | JWT access_token |
-| `conversation_id` | 否 | 恢复已有对话；省略则创建新对话 |
-
-**认证失败响应**（HTTP 升级前返回）：
-
-| 状态码 | 场景 |
-|--------|------|
-| 401 | token 缺失、无效或已过期 |
-
-**conversation_id 校验失败**：
-
-| 场景 | 处理 |
-|------|------|
-| 对话不存在 | 返回 401，`{"error": "SESSION_NOT_FOUND"}` |
-| 对话不属于当前用户 | 返回 401，`{"error": "SESSION_NOT_FOUND"}`（与不存在相同，避免信息泄露） |
-
-**连接成功后**：`connected` 消息不变，新增 `conversation_id` 字段标识当前对话：
-
-```typescript
-interface ConnectedMessage {
-  type: "connected";
-  session_id: string;       // 对话 ID
-  conversation_id: string;  // 同 session_id，便于前端统一使用
-  server_version: string;
-}
-```
-
----
-
-### 四、前端调用示例
-
-#### 认证状态管理
-
-```typescript
-// 存储 token（建议 localStorage 或内存，视安全需求）
-interface AuthTokens {
-  accessToken: string;
-  refreshToken: string;
-}
-
-// 请求拦截器：自动附加 Authorization 头
-async function authFetch(url: string, options: RequestInit = {}): Promise<Response> {
-  const tokens = getStoredTokens();
-  const headers = {
-    ...options.headers,
-    "Authorization": `Bearer ${tokens.accessToken}`,
-  };
-
-  let resp = await fetch(url, { ...options, headers });
-
-  // 401 时尝试刷新 token
-  if (resp.status === 401 && tokens.refreshToken) {
-    const refreshResp = await fetch("/api/auth/refresh", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ refresh_token: tokens.refreshToken }),
-    });
-
-    if (refreshResp.ok) {
-      const newTokens: AuthResponse = await refreshResp.json();
-      storeTokens({
-        accessToken: newTokens.access_token,
-        refreshToken: newTokens.refresh_token,
-      });
-      // 用新 token 重试原请求
-      headers["Authorization"] = `Bearer ${newTokens.access_token}`;
-      resp = await fetch(url, { ...options, headers });
-    } else {
-      // refresh 也失败，跳转登录
-      redirectToLogin();
-    }
-  }
-
-  return resp;
-}
-```
-
-#### 注册 + 登录
-
-```typescript
-async function register(username: string, password: string): Promise<AuthResponse> {
-  const resp = await fetch("/api/auth/register", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ username, password }),
-  });
-
-  if (!resp.ok) {
-    const err: ApiError = await resp.json();
-    throw new Error(err.message); // "username already taken" 等
-  }
-
-  return resp.json();
-}
-```
-
-#### 获取对话列表
-
-```typescript
-async function getConversations(page = 1, size = 20): Promise<ConversationListResponse> {
-  const resp = await authFetch(
-    `/api/conversations?page=${page}&size=${size}`
-  );
-  if (!resp.ok) throw new Error("Failed to load conversations");
-  return resp.json();
-}
-```
-
-#### 加载对话历史消息
-
-```typescript
-async function getMessages(
-  conversationId: string,
-  limit = 50,
-  before?: number
-): Promise<MessagesResponse> {
-  let url = `/api/conversations/${conversationId}/messages?limit=${limit}`;
-  if (before !== undefined) url += `&before=${before}`;
-
-  const resp = await authFetch(url);
-  if (!resp.ok) throw new Error("Failed to load messages");
-  return resp.json();
-}
-```
-
-#### 建立 WebSocket 连接（带认证）
-
-```typescript
-function connectWebSocket(accessToken: string, conversationId?: string): WebSocket {
-  let url = `/ws?token=${encodeURIComponent(accessToken)}`;
-  if (conversationId) {
-    url += `&conversation_id=${encodeURIComponent(conversationId)}`;
-  }
-  return new WebSocket(url);
-}
-```
-
----
-
-## 关键文件清单
-
-```
-backend/
-  cmd/server/main.go                        ← Phase 1.6, 4.4, 7.5, 9.2
-  migrations/
-    001_users.up.sql                        ← Phase 1.4（新建）
-    001_users.down.sql                      ← Phase 1.5（新建）
-  internal/
-    config/config.go                        ← Phase 1.1, 1.2（修改）
-    errors/codes.go                         ← Phase 4.2（修改，新增错误码）
-    models/models.go                        ← Phase 5.1（修改）
-    store/
-      db.go                                 ← Phase 1.3（新建）
-      user.go                               ← Phase 2.2（新建）
-      user_pg.go                            ← Phase 2.3（新建）
-      user_mem.go                           ← Phase 2.4（新建）
-      user_pg_test.go                       ← Phase 2.5（新建）
-      message.go                            ← Phase 8.1（新建）
-      message_pg.go                         ← Phase 8.2（新建）
-    auth/
-      jwt.go                                ← Phase 3.1（新建）
-      password.go                           ← Phase 3.2（新建）
-      middleware.go                         ← Phase 3.3（新建）
-      service.go                            ← Phase 3.4, 3.5（新建）
-      jwt_test.go                           ← Phase 3.6（新建）
-      service_test.go                       ← Phase 3.7（新建）
-    session/
-      manager.go                            ← Phase 5.2（修改）
-      memory.go                             ← Phase 5.3, 7.4, 8.3, 8.4（修改）
-      redis.go                              ← Phase 5.4（修改）
-      memory_test.go                        ← Phase 5.5（修改）
-    api/
-      auth.go                               ← Phase 4.1, 4.3（新建）
-      auth_test.go                          ← Phase 4.5（新建）
-      conversation.go                       ← Phase 6.1, 6.2, 6.3（新建）
-      conversation_test.go                  ← Phase 6.5（新建）
-      session.go                            ← Phase 9.1（废弃/删除）
-    ws/
-      handler.go                            ← Phase 7.1, 7.2, 7.3（修改）
-      handler_test.go                       ← Phase 7.7（修改）
-```
-
----
-
-## 执行顺序与依赖关系
-
-```
-Phase 1 (配置 + DB 连接)
-  ↓
-Phase 2 (User 模型 + Repository)  ← 依赖 Phase 1
-  ↓
-Phase 3 (JWT + AuthService)        ← 依赖 Phase 2
-  ↓
-Phase 4 (Auth REST API)            ← 依赖 Phase 3
-  ↓
-Phase 5 (Session Manager 改造)     ← 依赖 Phase 1（模型扩展），可与 Phase 2-4 并行
-  ↓
-Phase 6 (Conversation REST API)    ← 依赖 Phase 4 + 5
-  ↓
-Phase 7 (WS 认证集成)              ← 依赖 Phase 3 + 5
-  ↓
-Phase 8 (消息持久化)               ← 依赖 Phase 1 + 5
-  ↓
-Phase 9 (废弃旧端点 + 集成收尾)    ← 依赖全部
-```
-
-**可并行的路径**：
-- Phase 2-4（用户认证链路）和 Phase 5（Session 改造）可并行开发
-- Phase 6（对话 API）和 Phase 7（WS 认证）可并行开发
-
----
-
-## 验证方案
-
-| 层级 | 方法 | 覆盖范围 |
-|------|------|---------|
-| 单元测试 | `go test ./internal/auth/... ./internal/store/...` | JWT 生成/校验、密码 hash、Repository CRUD |
-| API 测试 | `httptest` + `go test ./internal/api/...` | 注册/登录/刷新/登出、对话 CRUD、权限校验 |
-| 集成测试 | 启动 Gin test server + WS client | WS 认证、conversation_id 恢复、消息持久化 |
-| 端到端 | 手动测试 | 注册 → 登录 → 对话 → 登出 → 重登 → 历史列表 → 继续对话 |
-| 静态检查 | `go vet ./...` + `go test ./...` | 全量通过 |
diff --git a/docs/README.md b/docs/README.md
index ea96927..3f8ad60 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,46 +1,26 @@
 # CamTalk 设计文档
 
-CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后给出自然回应。
+CamTalk 是一款多模态实时 AI 视觉对话助手。用户通过摄像头和麦克风与 AI 交互，AI 理解视觉场景和语音输入后，以文字和语音形式给出自然回应。
 
 ## 文档索引
 
-| 文档 | 说明 | 状态 |
-|------|------|------|
-| [01-项目概述](01-项目概述.md) | 项目目标、核心挑战、交付物 | ✅ 与代码一致 |
-| [02-系统架构](02-系统架构.md) | 三层架构、技术栈、核心交互流程、前后端模块、存储策略、部署架构 | ✅ 已更新 |
-| [03-接口文档](03-接口文档.md) | WebSocket 协议、REST API、AI 服务层接口、编排器设计、Session Manager、配置管理（Viper）、数据模型、错误码、连接管理（**实现时首先阅读**） | ✅ 已更新 |
-| [04-技术选型](04-技术选型.md) | 持久化层（PostgreSQL）、认证系统和前端边缘处理层的选型对比与决策理由 | ✅ 已更新 |
-| [05-用户故事](05-用户故事.md) | P0/P1/P2 用户故事、验收标准、优先级决策依据 | ✅ 与代码一致 |
-| [06-语音交互](06-语音交互.md) | VAD → STT → LLM → TTS 全链路、延迟优化 | ✅ 与代码一致 |
-| [07-视觉理解](07-视觉理解.md) | 帧采样策略、图像编码、多模态 LLM 输入机制 | ✅ 与代码一致 |
-| [08-成本控制](08-成本控制.md) | 智能采样、端云协同、模型分级、缓存复用 | ✅ 与代码一致 |
-| [09-技术名词解释](09-技术名词解释.md) | 前端/后端/AI 服务技术名词简明解释 | ✅ 与代码一致 |
-| [10-功能创意](10-功能创意.md) | 未来功能创意清单 | 📋 愿景 |
-| [11-持久化与用户系统设计](11-持久化与用户系统设计.md) | 用户认证、JWT、对话持久化的完整设计方案 | ✅ 已全部实现 |
-| [PLAN_BACKEND.md](PLAN_BACKEND.md) | 后端 AI 管道构建计划（Session Manager → AI 服务 → Orchestrator） | ✅ 已全部完成 |
-| [PLAN_USER_MODULE.md](PLAN_USER_MODULE.md) | 后端用户模块构建计划（Auth → 对话 CRUD → 消息持久化） | ✅ 已全部完成 |
+| 文档 | 说明 |
+|------|------|
+| [01-架构设计](01-架构设计.md) | 系统架构、技术栈、模块设计、数据库、部署架构（含 Mermaid 图） |
+| [02-接口文档](02-接口文档.md) | WebSocket 协议、REST API、AI 服务层、编排器、Session Manager、配置管理、数据模型、错误码 |
+| [03-技术选型](03-技术选型.md) | 各技术的选型对比与决策理由 |
+| [04-用户故事](04-用户故事.md) | P0/P1/P2 用户故事、验收标准 |
+| [05-语音交互](05-语音交互.md) | VAD → STT → LLM → TTS 全链路、延迟优化 |
+| [06-视觉理解](06-视觉理解.md) | 帧采样策略、图像编码、多模态 LLM 输入机制 |
+| [07-成本控制](07-成本控制.md) | 智能采样、端云协同、模型分级、缓存复用 |
+| [08-功能创意](08-功能创意.md) | 未来功能创意清单 |
+| [09-技术名词解释](09-技术名词解释.md) | 前端/后端/AI 服务技术名词简明解释 |
 
 ## 推荐阅读顺序
 
-1. **01-项目概述** — 了解项目目标
-2. **02-系统架构** — 理解三层架构和技术栈全貌
-3. **03-接口文档** — 前后端通信契约，实现时的最高依据
-4. **04-技术选型** — 了解为什么选这些技术
-5. **05-用户故事** — 明确功能优先级
-6. **06~08** — 各技术领域的详细设计
-7. **09-技术名词解释** — 遇到不熟悉的名词时查阅
-8. **11-持久化与用户系统设计** — 用户认证和持久化的详细设计
-
-## 实现状态总览
-
-前后端代码已全部实现，无 TODO/FIXME 桩代码。后端约 122 个测试函数覆盖所有模块。
-
-| 层级 | 状态 | 说明 |
-|------|------|------|
-| 前端 | ✅ 已完成 | 10 个组件、3 个 Hook、10 个库模块、i18n 三语言 |
-| 后端 AI 管道 | ✅ 已完成 | STT/LLM/TTS 多 provider、Orchestrator 流式并行 |
-| 后端用户系统 | ✅ 已完成 | JWT 认证、用户注册登录、对话 CRUD、消息持久化 |
-| 后端存储层 | ✅ 已完成 | Memory + PostgreSQL + Redis 三种实现 |
-| 数据库迁移 | ✅ 已完成 | 3 个版本化迁移脚本，嵌入式自动执行 |
-| Model Router | 📋 规划中 | 按问题复杂度选择模型 |
-| Rate Limiter | 📋 规划中 | 令牌桶限流 |
+1. **01-架构设计** — 理解三层架构、技术栈和模块全貌
+2. **02-接口文档** — 前后端通信契约，实现时的最高依据
+3. **03-技术选型** — 了解为什么选这些技术
+4. **04-用户故事** — 明确功能优先级
+5. **05~07** — 各技术领域的详细设计
+6. **09-技术名词解释** — 遇到不熟悉的名词时查阅