docs: 按功能模块重构文档结构

- 新建 01-架构设计.md:合并项目概述+系统架构+持久化设计,含 Mermaid 架构图、模块图、时序图、ER 图、部署图
- 新建 02-接口文档.md:合并接口文档+持久化 API+用户模块 API,统一格式去重
- 重编号 03~09,去掉状态标注,规划中功能标记为待实现
- 删除 PLAN_BACKEND.md、PLAN_USER_MODULE.md 及冗余文档
This commit is contained in:
hhs
2026-06-19 15:31:52 +08:00
parent dca37f3e48
commit a04275cc76
14 changed files with 606 additions and 3290 deletions

View File

@@ -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-技术名词解释** — 遇到不熟悉的名词时查阅