GoChat 文档索引
最后更新: 2026-07-09 项目状态: main 分支 @
805402f
GoChat 是 Chatwoot v4.14.0 的 Go 语言 1:1 重写。本目录包含项目的设计文档、需求规格、 架构设计、对齐计划和 QA 报告。本文档是所有 docs/ 下文档的导航入口。
当前项目快照
| 指标 | 数值 |
|---|---|
| Go 源码文件（非测试） | 692 |
| 测试文件 | 331 |
| 测试代码行 | ~117,000 |
| 源码行（非测试） | ~162,000 |
| 数据库迁移 | 53 |
| 注册 API 路由 | 972 |
| 内部包 | 30 |
| 渠道 Provider | 9 |
| AI/LLM 文件 | 18+ |
目录结构
docs/
├── README.md ← 本文件（导航索引）
├── product/ ← 产品与架构设计文档
├── tracking/ ← Chatwoot parity 开发跟踪
├── requirements/ ← M01-M12 模块需求梳理
├── plans/ ← 已执行的历史实现计划
├── parity/ ← 路由 parity 分析与前端契约验证
├── qa/ ← QA 测试报告与测试计划
└── ops/ ← 运维与部署
文档分类导航
1. 产品与架构（product/）
| 文档 | 说明 | 状态 |
|---|---|---|
| product/01-product-requirements.md | 产品需求规格文档 — 产品定义、用户角色、核心价值、技术栈 | 活跃 |
| product/02-architecture.md | 技术架构设计文档 v3.0 — 项目结构、分层架构、数据库设计、模块划分 | 活跃，统计已更新 |
| product/03-design-project-structure.md | 设计阶段产出 — 项目结构与模块划分详细设计 | 设计文档，已落地 |
| product/04-design-database.md | 设计阶段产出 — 87 表数据库设计，含表结构、索引、关联 | 设计文档，以迁移文件为权威 |
| product/05-design-routing-and-api.md | 设计阶段产出 — 路由注册与 API 契约设计 | 设计文档，以 router.go 为权威 |
| product/06-design-channel-abstraction.md | 设计阶段产出 — 渠道 Provider 接口与多态 Channel 模型 | 设计文档，已落地 |
| product/07-design-auth-and-realtime.md | 设计阶段产出 — JWT/OAuth/MFA/SAML/RBAC + WebSocket | 设计文档，已落地 |
| product/08-ai-roadmap.md | AI 功能支持评估与开发路线图 — Captain AI / Copilot / RAG / Multi-LLM | 活跃 |
| product/09-enterprise-features.md | 企业版功能分析 — SLA/Audit/CustomRole/Company/语音通话/Captain AI | 活跃，设计参考 |
2. 功能对标与开发跟踪（tracking/）
| 文档 | 说明 | 状态 |
|---|---|---|
| tracking/01-chatwoot-parity-tracker.md | Chatwoot parity 开发跟踪文档 — 唯一活跃的对齐执行跟踪器，覆盖 200+ 个 checkpoint | 权威跟踪文档，持续更新 |
3. 需求文档（requirements/）
M01-M12 模块的 Chatwoot 功能梳理文档，基于 Chatwoot 源码深度阅读 + CodeGraph 上下文梳理。
每个模块包含两份文档：
MNN-{module-name}.md— 功能需求详细梳理MNN-codegraph-context.md— CodeGraph 查询上下文快照（代码符号索引）
| 模块 | 功能域 | 需求文档 |
|---|---|---|
| M01 | 账户与用户管理 | requirements/M01-accounts-and-users.md |
| M02 | Inbox 与渠道管理 | requirements/M02-inbox-and-channels.md |
| M03 | 对话与消息 | requirements/M03-conversation-and-message.md |
| M04 | 联系人管理 | requirements/M04-contact-management.md |
| M05 | 团队与分配 | requirements/M05-team-and-assignment.md |
| M06 | 自动化与模板 | requirements/M06-automation-and-templates.md |
| M07 | 报告与 CSAT | requirements/M07-reporting-and-csat.md |
| M07 | 渠道集成（综合） | requirements/M07-channel-integration-consolidated.md |
| M08 | 通知与 Webhook | requirements/M08-notification-and-webhook.md |
| M09 | 知识库与帮助中心 | requirements/M09-knowledge-base.md |
| M10 | Captain AI 与 Copilot | requirements/M10-captain-and-copilot.md |
| M11 | 企业版功能 | requirements/M11-enterprise-features.md |
| M12 | 平台与集成 | requirements/M12-platform-and-integration.md |
4. 实现计划（plans/）
已执行完毕的大型实现计划，保留作为实现历史参考。
| 文档 | 说明 |
|---|---|
| plans/2026-05-24-agent-agentbot-assignment-policy.md | Agent + AgentBot + AssignmentPolicy 实现计划 |
| plans/2026-05-24-companies-campaign-helpcenter.md | Companies + Campaign + HelpCenter + Notes + Labels + Attachments 实现计划 |
5. Parity 对齐工具与报告（parity/）
| 文档 | 说明 |
|---|---|
| parity/route-parity.md | 路由 parity 报告 — GoChat vs Chatwoot 路由对比 |
| parity/chatwoot-routes-static.md | Chatwoot routes.rb 静态路由声明（Ruby 不可用时回退） |
| parity/gochat-routes.txt | GoChat 注册路由 dump（由 cmd/route_parity 生成） |
| parity/frontend-contract-inventory.md | 前端契约清单 — Chatwoot 前端 API 客户端调用盘点 |
| parity/contract-fixture-coverage.md | 契约 fixture 覆盖度跟踪 |
| parity/frontend-smoke-report.md | 前端 smoke 测试报告 |
| parity/placeholder-audit.md | 占位符审计 — chatwootParityStub 扫描结果 |
6. QA 报告（qa/）
| 文档 | 说明 |
|---|---|
| qa/2026-07-09-test-plan-round4.md | CDP 全页功能测试 Round 4 测试计划 |
| qa/2026-07-09-qa-report-round4.md | CDP 全页功能测试 Round 4 — 最新一轮 QA |
7. 运维与部署（ops/）
| 文档 | 说明 |
|---|---|
| ops/01-rolling-upgrade.md | 滚动升级策略 — 蓝绿部署、数据库迁移、健康检查 |
命名规范
为确保文档目录时序清晰、排序稳定、风格统一，所有 docs/ 下文件须遵循以下约束。
文件名格式
[序号前缀-]{功能描述}.md
- 全小写，单词用连字符（kebab-case）分隔，无空格、无下划线、无大写字母。
- 中文文件名仅在功能描述为专有术语时允许（当前 P2 设计文档已全部转为英文 kebab-case，不再新增中文文件名）。
序号前缀规则
| 目录 | 前缀格式 | 示例 | 说明 |
|---|---|---|---|
| product/ | NN- |
01-product-requirements.md |
按文档重要性/阅读顺序编号，两位零填充 |
| tracking/ | NN- |
01-chatwoot-parity-tracker.md |
同上 |
| ops/ | NN- |
01-rolling-upgrade.md |
同上 |
| requirements/ | MNN- |
M01-accounts-and-users.md |
M + 两位零填充模块号，保证 M01-M12 字典序正确 |
| plans/ | YYYY-MM-DD- |
2026-05-24-agent-agentbot-assignment-policy.md |
日期前缀，按创建时间排序 |
| qa/ | YYYY-MM-DD- |
2026-07-09-qa-report-round4.md |
日期前缀 + 类型 + 轮次 |
| parity/ | 无前缀 | route-parity.md |
工具产出文件，按功能名排序 |
新增文档规则
- 新文档按所属目录的前缀规则命名，序号接续当前最大值。
- 永不使用全大写文件名（如
PRD.md、API_COVERAGE.md），一律 kebab-case。 - requirements/ 下新模块用
MNN-前缀，两位零填充，确保ls排序与模块号一致。 - 时效性文档（QA 报告、实现计划）用
YYYY-MM-DD-日期前缀，同一日期多篇用类型后缀区分。 - 永久性文档（架构、需求、运维）用
NN-序号前缀，不用日期。
文档维护规则
- 统计数据更新：当项目代码量、路由数、迁移数显著变化时，更新 product/02-architecture.md 第 1 节和本文件快照表。
- Parity 跟踪：所有 Chatwoot parity 相关的工作进度记录在
tracking/01-chatwoot-parity-tracker.md，不新建并行跟踪文件。 - QA 报告：每轮 CDP 测试产出一份 test-plan + qa-report，保留最新一轮，清理历史轮次。
- 需求文档：
requirements/下文档是 Chatwoot 功能梳理的参考快照，不随 GoChat 实现变化更新——实现对齐情况以 parity 跟踪文档为准。 - 设计文档：
product/下 03-07 系列是设计阶段产出，描述设计意图，不追踪实现细节。实现与设计的差异以代码和迁移文件为权威。 - 根目录：只保留
README.md作为索引，所有文档内容归入功能子目录。