Rogeeandrogee
fb83285617
* HH-445: deploy production observability and runbooks * fix(ops): share production database DSN * fix(HH-445): enforce database TLS gate * fix(HH-445): preserve production serve command * fix(prod): require external database dependencies * fix(prod): unify database host rejection gates * test(prod): enforce exact database TLS runbook contract --------- Co-authored-by: Rogee <rogee@ipao.vip>
169 lines
10 KiB
Markdown
169 lines
10 KiB
Markdown
# 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/01-product-requirements.md) | 产品需求规格文档 — 产品定义、用户角色、核心价值、技术栈 | 活跃 |
|
||
| [product/02-architecture.md](product/02-architecture.md) | 技术架构设计文档 v3.0 — 项目结构、分层架构、数据库设计、模块划分 | 活跃，统计已更新 |
|
||
| [product/03-design-project-structure.md](product/03-design-project-structure.md) | 设计阶段产出 — 项目结构与模块划分详细设计 | 设计文档，已落地 |
|
||
| [product/04-design-database.md](product/04-design-database.md) | 设计阶段产出 — 87 表数据库设计，含表结构、索引、关联 | 设计文档，以迁移文件为权威 |
|
||
| [product/05-design-routing-and-api.md](product/05-design-routing-and-api.md) | 设计阶段产出 — 路由注册与 API 契约设计 | 设计文档，以 router.go 为权威 |
|
||
| [product/06-design-channel-abstraction.md](product/06-design-channel-abstraction.md) | 设计阶段产出 — 渠道 Provider 接口与多态 Channel 模型 | 设计文档，已落地 |
|
||
| [product/07-design-auth-and-realtime.md](product/07-design-auth-and-realtime.md) | 设计阶段产出 — JWT/OAuth/MFA/SAML/RBAC + WebSocket | 设计文档，已落地 |
|
||
| [product/08-ai-roadmap.md](product/08-ai-roadmap.md) | AI 功能支持评估与开发路线图 — Captain AI / Copilot / RAG / Multi-LLM | 活跃 |
|
||
| [product/09-enterprise-features.md](product/09-enterprise-features.md) | 企业版功能分析 — SLA/Audit/CustomRole/Company/语音通话/Captain AI | 活跃，设计参考 |
|
||
|
||
### 2. 功能对标与开发跟踪（tracking/）
|
||
|
||
| 文档 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| [tracking/01-chatwoot-parity-tracker.md](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](requirements/M01-accounts-and-users.md) |
|
||
| M02 | Inbox 与渠道管理 | [requirements/M02-inbox-and-channels.md](requirements/M02-inbox-and-channels.md) |
|
||
| M03 | 对话与消息 | [requirements/M03-conversation-and-message.md](requirements/M03-conversation-and-message.md) |
|
||
| M04 | 联系人管理 | [requirements/M04-contact-management.md](requirements/M04-contact-management.md) |
|
||
| M05 | 团队与分配 | [requirements/M05-team-and-assignment.md](requirements/M05-team-and-assignment.md) |
|
||
| M06 | 自动化与模板 | [requirements/M06-automation-and-templates.md](requirements/M06-automation-and-templates.md) |
|
||
| M07 | 报告与 CSAT | [requirements/M07-reporting-and-csat.md](requirements/M07-reporting-and-csat.md) |
|
||
| M07 | 渠道集成（综合） | [requirements/M07-channel-integration-consolidated.md](requirements/M07-channel-integration-consolidated.md) |
|
||
| M08 | 通知与 Webhook | [requirements/M08-notification-and-webhook.md](requirements/M08-notification-and-webhook.md) |
|
||
| M09 | 知识库与帮助中心 | [requirements/M09-knowledge-base.md](requirements/M09-knowledge-base.md) |
|
||
| M10 | Captain AI 与 Copilot | [requirements/M10-captain-and-copilot.md](requirements/M10-captain-and-copilot.md) |
|
||
| M11 | 企业版功能 | [requirements/M11-enterprise-features.md](requirements/M11-enterprise-features.md) |
|
||
| M12 | 平台与集成 | [requirements/M12-platform-and-integration.md](requirements/M12-platform-and-integration.md) |
|
||
|
||
### 4. 实现计划（plans/）
|
||
|
||
大型功能的待实施计划与已执行历史计划。
|
||
|
||
| 文档 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| [plans/2026-07-12-copilot-configuration.md](plans/2026-07-12-copilot-configuration.md) | Copilot 配置中心：平台 Provider、账户策略、密钥掩码、运行时热切换 | 待实施 |
|
||
| [plans/2026-05-24-agent-agentbot-assignment-policy.md](plans/2026-05-24-agent-agentbot-assignment-policy.md) | Agent + AgentBot + AssignmentPolicy 实现计划 | 历史 |
|
||
| [plans/2026-05-24-companies-campaign-helpcenter.md](plans/2026-05-24-companies-campaign-helpcenter.md) | Companies + Campaign + HelpCenter + Notes + Labels + Attachments 实现计划 | 历史 |
|
||
|
||
### 5. Parity 对齐工具与报告（parity/）
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [parity/route-parity.md](parity/route-parity.md) | 路由 parity 报告 — GoChat vs Chatwoot 路由对比 |
|
||
| [parity/chatwoot-routes-static.md](parity/chatwoot-routes-static.md) | Chatwoot routes.rb 静态路由声明（Ruby 不可用时回退） |
|
||
| [parity/gochat-routes.txt](parity/gochat-routes.txt) | GoChat 注册路由 dump（由 cmd/route_parity 生成） |
|
||
| [parity/frontend-contract-inventory.md](parity/frontend-contract-inventory.md) | 前端契约清单 — Chatwoot 前端 API 客户端调用盘点 |
|
||
| [parity/contract-fixture-coverage.md](parity/contract-fixture-coverage.md) | 契约 fixture 覆盖度跟踪 |
|
||
| [parity/frontend-smoke-report.md](parity/frontend-smoke-report.md) | 前端 smoke 测试报告 |
|
||
| [parity/placeholder-audit.md](parity/placeholder-audit.md) | 占位符审计 — chatwootParityStub 扫描结果 |
|
||
|
||
### 6. QA 报告（qa/）
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [qa/2026-07-09-test-plan-round4.md](qa/2026-07-09-test-plan-round4.md) | CDP 全页功能测试 Round 4 测试计划 |
|
||
| [qa/2026-07-09-qa-report-round4.md](qa/2026-07-09-qa-report-round4.md) | CDP 全页功能测试 Round 4 — 最新一轮 QA |
|
||
|
||
### 7. 运维与部署（ops/）
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [ops/01-rolling-upgrade.md](ops/01-rolling-upgrade.md) | 滚动升级策略 — 蓝绿部署、数据库迁移、健康检查 |
|
||
| [ops/02-production-operations.md](ops/02-production-operations.md) | 生产预检、TLS、容量、轮换、事故、日志、停服与灾备 runbooks |
|
||
| [ops/03-observability-drill.md](ops/03-observability-drill.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` 作为索引，所有文档内容归入功能子目录。
|