gochat/docs

GoChat 文档索引

最后更新: 2026-07-12 项目状态: 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-07-12-copilot-configuration.md	Copilot 配置中心：平台 Provider、账户策略、密钥掩码、运行时热切换	待实施
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	工具产出文件，按功能名排序

新增文档规则

1. 新文档按所属目录的前缀规则命名，序号接续当前最大值。
2. 永不使用全大写文件名（如 PRD.md、API_COVERAGE.md），一律 kebab-case。
3. requirements/ 下新模块用 MNN- 前缀，两位零填充，确保 ls 排序与模块号一致。
4. 时效性文档（QA 报告、实现计划）用 YYYY-MM-DD- 日期前缀，同一日期多篇用类型后缀区分。
5. 永久性文档（架构、需求、运维）用 NN- 序号前缀，不用日期。

文档维护规则

1. 统计数据更新：当项目代码量、路由数、迁移数显著变化时，更新 product/02-architecture.md 第 1 节和本文件快照表。
2. Parity 跟踪：所有 Chatwoot parity 相关的工作进度记录在 tracking/01-chatwoot-parity-tracker.md，不新建并行跟踪文件。
3. QA 报告：每轮 CDP 测试产出一份 test-plan + qa-report，保留最新一轮，清理历史轮次。
4. 需求文档：requirements/ 下文档是 Chatwoot 功能梳理的参考快照，不随 GoChat 实现变化更新——实现对齐情况以 parity 跟踪文档为准。
5. 设计文档：product/ 下 03-07 系列是设计阶段产出，描述设计意图，不追踪实现细节。实现与设计的差异以代码和迁移文件为权威。
6. 根目录：只保留 README.md 作为索引，所有文档内容归入功能子目录。