28 KiB
28 KiB
GoChat 产品需求规格文档 (PRD)
版本：v1.0 产出日期：2026-05-25 产品定位：开源企业级多渠道客服平台，Chatwoot 的 Go 语言 1:1 重写 目标读者：产品经理、工程师、设计师、运维
1. 产品概述
1.1 产品定义
GoChat 是一个开源的企业级多渠道客服平台，旨在为企业提供统一的客户沟通管理能力。产品以 Chatwoot（Ruby/Rails 实现）为功能基准，使用 Go 语言进行 1:1 重写，目标是达到 Chatwoot v3.x 的完整功能覆盖，同时在性能、资源消耗和部署便捷性上显著优于原版。
1.2 目标用户
| 用户角色 | 使用场景 |
|---|---|
| 企业客服坐席 | 通过统一界面处理来自多渠道的客户消息 |
| 客服团队管理者 | 管理团队、分配对话、查看报表 |
| 企业管理员 | 配置账户、渠道、自动化规则、权限 |
| 客户/终端用户 | 通过网站 widget、社交媒体、邮件等渠道与企业沟通 |
| 开发者/集成方 | 通过 API/Webhook 与外部系统对接 |
1.3 核心价值主张
- 多渠道统一收发 — 一个平台管理 Web Widget、Telegram、Facebook、Instagram、WhatsApp、Email 等所有渠道
- 智能分配与自动化 — Round-Robin/负载均衡自动分配 + 事件驱动自动化规则
- AI 增强客服 — Captain AI 助手自动回复 + Copilot 辅助坐席（建议回复/摘要/翻译）
- 知识库自助服务 — Help CenterPortal 让客户自助查找答案，减少客服负担
- 完整 CRM — 联系人管理、自定义属性、标签、笔记、公司
- 实时协作 — WebSocket 实时推送、内部笔记、对话分配
- 企业级安全 — JWT+RBAC+MFA+SAML+OAuth+CSRF+XSS防护+Rate Limiting
1.4 技术栈
| 层 | 技术 |
|---|---|
| 语言 | Go 1.24+ |
| Web框架 | Gin |
| ORM | GORM |
| 数据库 | PostgreSQL 16 (pgvector) |
| 缓存/队列 | Redis 7+ (Watermill Redis Streams) |
| WebSocket | gorilla/websocket |
| 配置 | Viper |
| 认证 | JWT + bcrypt + TOTP |
| DI | 手动构造函数注入 |
| 测试 | testify + SQLite/PG 双模式 |
2. 功能模块列表
模块编号对照
| 编号 | 模块名 | 英文名 | 优先级 |
|---|---|---|---|
| M1 | 账户与用户管理 | Accounts & Users | P0 |
| M2 | Inbox与渠道管理 | Inboxes & Channels | P0 |
| M3 | 对话与消息 | Conversations & Messages | P0 |
| M4 | 联系人管理 | Contacts & CRM | P1 |
| M5 | 团队与分配 | Teams & Assignment | P1 |
| M6 | 自动化与模板 | Automation & Macros | P1 |
| M7 | 报表与CSAT | Reporting & CSAT | P2 |
| M8 | 通知与Webhook | Notifications & Webhooks | P1 |
| M9 | 知识库 | Knowledge Base / Help Center | P2 |
| M10 | Captain AI & Copilot | Captain & Copilot | P1 |
| M11 | 企业特性 | Enterprise Features | P3 |
| M12 | 平台与集成 | Platform & Integrations | P2 |
3. 各模块功能详述
M1 — 账户与用户管理 (P0)
目标：多租户账户体系，支持一个用户关联多个账户，完善的权限管理。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| 账户 CRUD | 创建/读取/更新/删除账户，含品牌信息自动拉取 | AccountBuilder | ⚠️ 仅Delete有真实实现，其余stub |
| 用户 CRUD | 用户注册/登录/信息修改/头像上传 | User model | ✅ 基本实现 |
| AccountUser 关联 | 用户-账户多对多关联，含角色（admin/agent） | AccountUser | ✅ 实现 |
| 角色权限 (RBAC) | 自定义角色 + 精细权限策略 | CustomRole + Policy | ✅ Policy实现，CustomRole部分 |
| JWT 认证 | Access Token (15min) + Refresh Token (7d) | Devise+JWT | ✅ 完整 |
| MFA (TOTP) | 双因素认证启用/验证/禁用 | TOTP | ✅ 完整 |
| OAuth 社交登录 | Google/GitHub/Facebook OAuth | OAuth | ✅ 实现 |
| SAML SSO | 企业单点登录 | SAML | ⚠️ Enable实现，流程缺失 |
| 邮箱验证 | 注册确认邮件 + disposable domain 检测 | SignUpEmailValidation | ❌ 未实现 |
| 密码重置 | 忘记密码/重设密码流程 | PasswordReset | ✅ 实现 |
| 账户切换 | 已登录用户切换工作账户 | SwitchAccount | ✅ 实现 |
| 用户在线状态 | available/busy/offline 状态管理 | AgentAvailability | ❌ 未实现 |
M2 — Inbox与渠道管理 (P0)
目标：多渠道统一收发，每个渠道一个 Inbox，支持渠道扩展插件机制。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| Inbox CRUD | 收件箱创建/列表/更新/删除 | InboxController | ❌ 全stub |
| InboxMember 管理 | 为 Inbox 添加/移除坐席 | InboxMemberController | ❌ 路由缺失 |
| ChannelProvider 注册 | 插件式渠道注册机制 | Channelable | ✅ Registry+Provider接口完整 |
| Web Widget | 嵌入式网站聊天 widget | Channel::WebWidget | ✅ 完整 |
| Telegram | Bot API 集成，webhook 消息收发 | Channel::Telegram | ✅ 完整 |
| Facebook Messenger | Graph API + Page 订阅 + OAuth | Channel::FacebookPage | ✅ 完整 |
| Instagram DM | 共享 Meta Graph API 基础设施 | Channel::Instagram | ✅ 完整（共享FB） |
| Email (IMAP+SMTP) | 邮件收取与发送，线程关联 | Channel::Email | ✅ 完整 |
| Meta Business API / 360dialog | Channel::WhatsApp | ⚠️ 仅模型，无Provider | |
| Twilio SMS | Twilio API 集成 | Channel::TwilioSMS | ❌ 仅stub模型 |
| LINE | LINE Messaging API | Channel::Line | ❌ 仅stub模型 |
| Slack | Slack Events API | Channel::Slack | ❌ 完全缺失 |
| API Channel | REST API 接入 | Channel::Api | ❌ 仅stub模型 |
| 渠道 OAuth 授权 | Facebook/Instagram/WhatsApp OAuth 授权路由 | OAuth controllers | ❌ 路由完全缺失 |
| 渠道 Webhook 路由 | 各渠道独立 webhook endpoint | Channel webhooks | ⚠️ catch-all stub，未按渠道分发 |
| AgentBot 绑定 | Inbox 关联 AI Bot 自动回复 | AgentBotInbox | ❌ 缺失 |
| 工作时间配置 | Inbox 工作时间/离线消息设置 | WorkingHours | ❌ 未实现 |
| 欢迎语/品牌 | Inbox 独立欢迎语、品牌名、头像 | Inbox branding | ❌ 未实现 |
M3 — 对话与消息 (P0)
目标：对话是核心交互实体，消息是多态（文本/图片/文件/系统事件）。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| 对话 CRUD | 创建/获取/更新/列表对话 | ConversationController | ⚠️ 部分实现 |
| 对话状态流转 | open → resolved/pending/snoozed | Conversation status | ⚠️ 状态枚举有，流转逻辑缺 |
| 对话优先级 | low/medium/high/urgent | Conversation priority | ⚠️ 枚举有，设置逻辑缺 |
| 对话分配 | 手动/自动分配给坐席或团队 | AssignAgent/AssignTeam | ⚠️ 部分实现 |
| 对话标签 | 添加/移除对话标签 | Conversation labels | ❌ 未实现 |
| 对话 snooze | 延时唤醒对话 | SnoozeUntil | ❌ 未实现 |
| 消息 CRUD | 创建/获取/删除消息 | MessageController | ⚠️ 部分实现 |
| 消息类型 | incoming/outgoing/template/system/activity | Message types | ⚠️ 枚举有，多态处理缺 |
| 附件上传 | 图片/文件/音频/视频上传 | ActiveStorage | ⚠️ 上传安全有，消息关联缺 |
| 内部笔记 | 坐席间私有笔记 | Private notes | ❌ 未实现 |
| 来源指示 | 消息来源渠道标注 | Source attribution | ❌ 未实现 |
| 对话搜索 | 按标签/状态/坐席/团队筛选 | Conversation filter | ⚠️ 基本筛选有 |
| 批量操作 | 批量分配/关闭/标签 | BulkActions | ❌ 未实现 |
| 对话合并 | 合并重复对话 | Merge conversations | ❌ 未实现 |
| 消息转发 | 转发消息到其他对话/团队 | Message forwarding | ❌ 未实现 |
M4 — 联系人管理 (P1)
目标：完整 CRM 体系，联系人全生命周期管理。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| 联系人 CRUD | 创建/读取/更新/删除联系人 | ContactController | ✅ 实现 |
| 联系人搜索 | 全文搜索 + 自定义属性筛选 | Contact search | ⚠️ 基本搜索有 |
| 联系人合并 | 识别重复联系人并合并 | ContactMerge | ❌ 未实现 |
| ContactInbox | 联系人-收件箱关联，含 source_id | ContactInbox | ✅ 实现 |
| 自定义属性 | 自定义字段定义 + 联系人属性值 | CustomAttribute | ⚠️ 模型有，CRUD缺 |
| 自定义筛选器 | 保存的筛选条件 | CustomFilter | ❌ 未实现 |
| 笔记 (Note) | 联系人笔记添加/删除 | Note | ❌ 未实现 |
| 标签 (Label) | 联系人标签管理 | Label | ❌ 未实现 |
| 公司 (Company) | 联系人归属公司管理（企业版） | Company | ❌ 仅stub模型 |
| CSV 导入/导出 | 批量导入导出联系人 | Import/Export | ❌ 未实现 |
| IP 地址查询 | 自动查询联系人 IP 地理位置 | IpLookup | ❌ 未实现 |
| 联系人详情页 | 含对话历史+属性+笔记的详情视图 | Contact detail | ⚠️ API部分有 |
M5 — 团队与分配 (P1)
目标：团队组织坐席，自动分配策略确保对话快速流转。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| 团队 CRUD | 创建/更新/删除团队 | TeamController | ✅ 实现 |
| 团队成员管理 | 添加/移除团队成员 | TeamMember | ✅ 实现 |
| 允许自动分配 | 团队 allow_auto_assign 标志 | Team.allow_auto_assign | ✅ 实现 |
| 手动分配 | 坐席手动将对话分配给指定坐席/团队 | Manual assign | ⚠️ 部分实现 |
| Round-Robin 自动分配 | 轮询式均匀分配 | RoundRobin | ✅ 实现 |
| 负载均衡分配 | 按坐席容量分配（企业版） | AgentCapacityPolicy | ⚠️ 限流器有，完整策略缺 |
| 分配策略 V2 | 基于可用性+容量的智能分配 | AssignmentPolicyV2 | ❌ 未实现 |
| 坐席可用性 | available/busy/offline 状态切换 | AgentAvailability | ❌ 未实现 |
| 自动取消分配 | 对话解决后自动释放坐席 | Auto unassign | ❌ 未实现 |
M6 — 自动化与模板 (P1)
目标：事件驱动的自动化规则减少重复操作，模板和宏提升回复效率。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| 自动化规则 CRUD | 创建/更新/克隆/删除规则 | AutomationRuleController | ⚠️ 模型+service有 |
| 事件触发器 | conversation_created/updated/opened/resolved/message_created | event_name | ✅ 枚举定义 |
| 条件过滤器 | AND/OR 条件组合，属性+运算符+值 | ConditionsFilter | ✅ 实现 |
| 动作执行器 | 发消息/分配坐席/添加标签/更新优先级等 | ActionService | ✅ 实现 |
| AutomationRuleListener | 事件驱动规则执行 | Wisper listener | ❌ 未接入事件总线 |
| 宏操作 (Macro) | 坐席一键执行多动作序列 | Macro | ⚠️ service有 |
| 模板消息 (CannedResponse) | 预置消息模板快捷回复 | CannedResponse | ✅ 实现 |
| CSAT 调查自动化 | 对话解决后自动推送满意度调查 | CsatSurveyListener | ⚠️ service有 |
M7 — 报表与CSAT (P2)
目标：量化客服效率，客户满意度追踪。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| 报表指标 | 对话数/响应时间/解决率/坐席效率 | Report | ⚠️ 模型+Analytics有 |
| CSAT 调查 | 满意度评分收集与统计 | CsatSurveyResponse | ✅ 实现 |
| Dashboard 聚合 | 平均解决时间/对话分布等 | DashboardApp | ✅ 实现 |
| 实时报表 | 在线坐席数/活跃对话数 | LiveReport | ✅ 实现 |
| 时间范围筛选 | 按日期范围查询报表数据 | Report filter | ⚠️ 部分实现 |
| 导出报表 | CSV/PDF 导出报表数据 | Report export | ❌ 未实现 |
| 自定义报表 | 自定义报表维度和指标 | CustomReport | ❌ 未实现 |
M8 — 通知与Webhook (P1)
目标：实时通知坐席，Webhook 对接外部系统。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| 应用内通知 | 新消息/分配/提及等通知 | Notification | ⚠️ 模型+handler有 |
| WebSocket 实时推送 | 前端实时更新 | ActionCable | ⚠️ 骨架有，未联动pubsub |
| Push 订阅 | 浏览器推送 + FCM | PushSubscription | ⚠️ handler有，推送未实现 |
| 邮件通知 | 通知邮件发送 | EmailNotification | ❌ 未实现 |
| 通知设置 | 用户自定义通知偏好 | NotificationSetting | ⚠️ 模型有 |
| Account Webhook | 账户级事件 HTTP 回调 | Webhook | ✅ CRUD实现 |
| Webhook 签名 | HMAC-SHA256 签名验证 | WebhookSigning | ✅ 完整 |
| 平台级 Webhook | 全平台事件通知 | PlatformWebhook | ⚠️ service有 |
| Webhook 投递 | 含重试+去重+超时 | WebhookDelivery | ❌ 未实现 |
| 通知去重/清理 | 重复通知合并+过期清理 | Dedup/cleanup | ❌ 未实现 |
| 通知 snooze | 延时提醒 | Snooze notification | ❌ 未实现 |
M9 — 知识库 / Help Center (P2)
目标：自助服务门户，减少客服负担。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| Portal CRUD | 创建/更新/删除帮助中心门户 | Portal | ✅ 实现 |
| Category CRUD | 门户下的分类目录管理 | Category | ✅ 实现 |
| Article CRUD | 文章创建/更新/发布/删除 | Article | ✅ 实现 |
| 全文搜索 | PostgreSQL tsearch 全文检索 | PgSearch | ⚠️ service有 |
| Embedding 搜索 | pgvector 向量相似搜索 | pgvector | ⚠️ stub |
| 多语言 | 文章多语言版本管理 | Locale | ⚠️ 模型有 |
| AI 内容辅助 | Captain 辅助写作/润色 | CaptainHelp | ❌ 未实现 |
| 门户品牌 | 自定义门户外观/品牌 | Portal branding | ❌ 未实现 |
M10 — Captain AI & Copilot (P1)
目标：AI 增强客服效率，自动回复 + 坐席辅助。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| Captain Assistant CRUD | AI 助手创建/配置/删除 | CaptainAssistant | ✅ 完整 |
| Captain 文档管理 | 助手知识文档 CRUD + 搜索 | CaptainDocument | ✅ 完整 |
| Captain 场景管理 | 助手场景配置 CRUD | CaptainScenario | ✅ 完整 |
| Captain 自定义工具 | 助手外部工具 CRUD | CaptainCustomTool | ✅ 完整 |
| Copilot 建议回复 | 基于上下文生成回复建议 | SuggestReplies | ✅ 实现 |
| Copilot 摘要 | 对话摘要生成 | Summarize | ✅ 实现 |
| Copilot 翻译 | 消息实时翻译 | Translate | ✅ 实现 |
| LLM Provider | OpenAI/Ollama/volcengine 多后端 | LLM adapter | ✅ 实现 |
M11 — 企业特性 (P3)
目标：企业客户需要的高级功能。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| SLA 筡理 | 服务等级协议定义+追踪 | SlaPolicy | ❌ 仅stub模型 |
| 语音通话 | 语音通话集成 | Call | ❌ 仅stub模型 |
| 审计日志 | 操作审计追踪 | AuditLog | ❌ 仅stub模型 |
| 数据导入 | 批量数据迁移工具 | DataImport | ❌ 仅stub模型 |
| Access Token 管理 | API Token CRUD | AccessToken | ❌ 仅stub模型 |
| 邮件模板 | 自定义邮件模板 | EmailTemplate | ❌ 仅stub模型 |
| 坐席容量策略 | 按容量限制自动分配 | AgentCapacityPolicy | ⚠️ 限流器有 |
| 自定义角色 | 精细权限自定义 | CustomRole | ⚠️ 部分实现 |
| 多语言 UI | 界面国际化 | Locale | ⚠️ 模型有 |
M12 — 平台与集成 (P2)
目标：平台管理和外部系统集成。
| 功能 | 描述 | Chatwoot对等 | 实现状态 |
|---|---|---|---|
| Platform App CRUD | 平台级应用管理 | PlatformApp | ✅ 实现 |
| Platform App User | 平台级用户管理 | PlatformAppUser | ✅ 实现 |
| Hook/Integration | Integration Hook 管理（Slack/Discord等） | Hook | ⚠️ 模型有 |
| CRM 集成 | Salesforce/Hubspot 等 CRM 双向同步 | CRM Integration | ⚠️ service骨架有 |
| Dashboard App | 自定义仪表盘应用 | DashboardApp | ✅ 实现 |
| Webhook Subscription | Webhook 订阅 CRUD | WebhookSubscription | ✅ 实现 |
4. 优先级划分
4.1 P0 — 核心可用（MVP）
定义：平台可上线提供基本客服服务的最小功能集。
| 功能项 | 当前状态 | 工作量预估 |
|---|---|---|
| Inbox CRUD（非stub） | ❌ 全stub | 3天 |
| 对话 CRUD + 状态流转 | ⚠️ 部分 | 5天 |
| 消息 CRUD + 附件 | ⚠️ 部分 | 5天 |
| 渠道 Webhook 路由接入 | ⚠️ catch-all | 3天 |
| 事件总线接入（核心3个Listener） | ❌ 无业务Listener | 5天 |
| WebSocket 实时推送联动 | ⚠️ 骨架 | 3天 |
| 对话分配/取消分配 | ⚠️ 部分 | 2天 |
| 渠道 OAuth 路由（FB/IG） | ❌ 缺失 | 2天 |
| 账户 CRUD（非stub） | ❌ stub | 2天 |
| P0 合计 | — | ~30天 |
4.2 P1 — 功能补全
定义：达到 Chatwoot 核心功能的完整覆盖，可正式对外发布。
| 功能项 | 当前状态 | 工作量预估 |
|---|---|---|
| WhatsApp Provider 实现 | ⚠️ 仅模型 | 5天 |
| 对话标签/优先级/snooze | ⚠️ 枚举有 | 3天 |
| 联系人合并/搜索增强 | ⚠️ 部分 | 3天 |
| 联系人 Note/Label | ❌ | 2天 |
| 自动化规则 Listener 接入 | ⚠️ service有 | 3天 |
| 宏操作完整实现 | ⚠️ | 2天 |
| 通知创建+WebSocket推送 | ⚠️ | 3天 |
| Webhook 投递+重试 | ❌ | 3天 |
| 用户在线状态管理 | ❌ | 3天 |
| 批量对话操作 | ❌ | 2天 |
| 内部笔记 | ❌ | 2天 |
| Inbox 工作时间/欢迎语 | ❌ | 3天 |
| Swagger/OpenAPI 文档 | ❌ | 2天 |
| Database Migration 工具 | ⚠️ golang-migrate有 | 2天 |
| P1 合计 | — | ~37天 |
4.3 P2 — 体验提升
定义：提升用户体验和运营效率。
| 功能项 | 当前状态 | 工作量预估 |
|---|---|---|
| 知识库搜索增强（pgvector） | ⚠️ stub | 3天 |
| 报表导出 | ❌ | 2天 |
| Dashboard 自定义报表 | ❌ | 3天 |
| Twilio SMS/WhatsApp Provider | ❌ | 5天 |
| LINE Provider | ❌ | 3天 |
| 邮件通知 | ❌ | 2天 |
| 通知去重/清理 | ❌ | 2天 |
| Hook/Integration 完整实现 | ⚠️ | 3天 |
| CRM 集成完整实现 | ⚠️ 骨架 | 5天 |
| 联系人 CSV 导入导出 | ❌ | 2天 |
| 自定义筛选器 | ❌ | 2天 |
| P2 合计 | — | ~33天 |
4.4 P3 — 运维保障与企业特性
定义：生产运维和企业高级功能。
| 功能项 | 当前状态 | 工作量预估 |
|---|---|---|
| Prometheus 指标导出 | ❌ | 2天 |
| Grafana Dashboard 模板 | ❌ | 1天 |
| OpenTelemetry 分布式追踪 | ❌ | 3天 |
| Kubernetes Helm Chart | ❌ | 3天 |
| JSON 结构化日志 | ⚠️ zap有 | 1天 |
| 健康检查增强 | ⚠️ | 1天 |
| SLA 管理 | ❌ stub | 3天 |
| 审计日志 | ❌ stub | 2天 |
| 数据导入工具 | ❌ stub | 3天 |
| 语音通话 | ❌ stub | 5天 |
| Slack Provider | ❌ | 5天 |
| API Channel Provider | ❌ stub | 3天 |
| P3 合计 | — | ~35天 |
5. 里程碑定义
MS1 — MVP 可上线 (P0完成)
目标：平台具备基本客服能力，坐席可登录、接入渠道、处理对话。
验收标准：
- 坐席可通过 Web 登录并切换账户
- Inbox CRUD 可创建/配置/删除收件箱
- 至少 Web Widget + Telegram 两个渠道可用（含 webhook 路由接入）
- 对话创建/列表/更新/关闭完整可用
- 消息发送/接收/附件上传完整可用
- 对话自动分配（Round-Robin）可用
- WebSocket 实时推送新消息/新对话
- 核心事件总线运行（ConversationCreated → Notification → WebSocket推送）
- Facebook/Instagram OAuth 授权流程可用
- 全量 E2E 测试通过
预计完成：P0 开始后 6 周
MS2 — 功能完整 (P1完成)
目标：达到 Chatwoot 核心功能完整覆盖，可正式对外发布。
验收标准：
- WhatsApp 渠道可用
- 对话标签/优先级/snooze/批量操作完整
- 联系人管理（含合并/笔记/标签/搜索）完整
- 自动化规则事件驱动执行可用
- 宏操作可用
- 通知系统完整（创建+推送+设置+邮件）
- Webhook 投递含重试/签名可用
- 坐席在线状态管理可用
- 内部笔记可用
- Inbox 工作时间/欢迎语配置可用
- Swagger/OpenAPI 自动生成文档
- API 覆盖率达到 Chatwoot 80%+
预计完成：MS1 后 7 周
MS3 — 体验增强 (P2完成)
目标：提升用户体验，扩展渠道和集成。
验收标准：
- Twilio SMS/WhatsApp 渠道可用
- LINE 渠道可用
- 知识库向量搜索可用
- 报表导出+自定义报表可用
- CRM 集成可用
- 联系人 CSV 导入导出可用
- API 覆盖率达到 Chatwoot 95%+
预计完成：MS2 后 7 周
MS4 — 生产就绪 (P3完成)
目标：运维可观测性 + 企业特性 + 生产部署。
验收标准：
- Prometheus/Grafana 监控面板可用
- OpenTelemetry 追踪可用
- Kubernetes Helm Chart 可一键部署
- SLA 管理/审计日志可用
- Slack/API Channel 渠道可用
- CI/CD 完整流水线运行
- 性能基准测试：单坐席 < 50ms 响应延迟，1000并发对话 < 5s
预计完成：MS3 后 7 周
6. 关键架构决策
6.1 已确认的架构决策
| 决策 | 选择 | 理由 |
|---|---|---|
| 单体 vs 微服务 | 单体架构（多模块） | Chatwoot 本身是单体；Go 性能足够；渠道扩展通过插件接口 |
| DI 方式 | 手动构造函数注入 | Go 无自动 DI 容器，显式依赖更清晰 |
| 实时推送 | Redis Pub/Sub + WebSocket | 跨进程事件分发 + 前端实时更新 |
| 异步任务 | Goroutine + WorkerPool | Go 原生并发，无需 Sidekiq 类外部 Job 队列 |
| 事件分发 | Watermill + Redis Streams | 持久化消息队列，支持异步 Listener |
| DB 迁移 | GORM AutoMigrate → golang-migrate | 首版快速迭代，后续版本化迁移 |
| 多态关联 | 独立关联表 + JSON 字段 | GORM 对多态支持弱，独立表更清晰 |
| 配置管理 | Viper（env/file/DB叠加） | 多环境管理 + 热加载 |
| 认证体系 | JWT + bcrypt + TOTP + SAML + OAuth | 企业级多层认证 |
6.2 待确认的架构决策
| 决策 | 选项 | 建议 | 需确认时间 |
|---|---|---|---|
| DI 自动化 | Wire vs Dig vs 手动 | MS2后评估手动DI复杂度 | MS2 |
| 日志框架 | slog vs zap | zap（已集成） | P3 |
| 前端框架 | React vs Vue vs 无前端 | Chatwoot 用 Vue，GoChat 仅后端 | 产品决策 |
| WhatsApp 实现方式 | 360dialog API vs Baileys vs go-whatsapp | 360dialog API（官方合规） | P1开始前 |
| CRM 集成方式 | 内建 vs 外部微服务 | 内建（保持单体） | P2开始前 |
7. 非功能需求
7.1 性能要求
| 指标 | 目标值 | 测量方法 |
|---|---|---|
| API 响应延迟 (P99) | < 200ms | Prometheus histogram |
| WebSocket 消息推送延迟 | < 100ms | 客户端计时 |
| 单坐席消息处理吞吐 | > 100 msg/min | Benchmark |
| 1000 并发对话 | 系统稳定无 OOM | Load test |
| DB 查询 (Conversation list) | < 50ms | pg_stat_statements |
| 数据库连接池 | 100 连接 | PG 配置 |
7.2 安全要求
| 要求 | 当前状态 | 目标 |
|---|---|---|
| JWT 安全 | ✅ HMAC-SHA256 | 生产级密钥管理 |
| SSRF 防护 | ✅ 白名单+私有IP检测 | 持续更新白名单 |
| Rate Limiting | ✅ IP+路径 | 增加账户级限流 |
| 文件上传安全 | ✅ MIME+大小+ZIP防护 | 持续更新MIME白名单 |
| XSS 防护 | ✅ bluemonday | 持续更新策略 |
| RBAC | ✅ Policy | CustomRole 完善 |
| MFA | ✅ TOTP | SAML 完善 |
| 数据加密 | ✅ AES-256 | PII字段加密存储 |
| SQL 注入防护 | ✅ 参数化查询 | 持续审计 |
| CSRF 防护 | ⚠️ 部分 | Gin CSRF middleware |
7.3 可用性要求
| 要求 | 目标 |
|---|---|
| 服务可用性 | 99.9% (全年停机 < 8.76h) |
| 故障恢复 | < 5min 自动重启 |
| 数据备份 | PG 每日全量 + WAL 实时 |
| 滚动升级 | 零停机升级（已在 docs 有方案） |
7.4 可观测性要求
| 要求 | 目标 | 状态 |
|---|---|---|
| Prometheus 指标 | 20+ 核心指标 | ❌ 待实现 |
| Grafana Dashboard | 5+ 预设面板 | ❌ 待实现 |
| OpenTelemetry 追踪 | 关链路100%覆盖 | ❌ 待实现 |
| 结构化日志 | zap JSON输出 | ⚠️ 已集成 |
| 健康检查 | /health/live + /health/ready | ⚠️ 部分实现 |
| 告警规则 | 10+ 核心告警 | ❌ 待实现 |
8. 当前实现状态总览
8.1 量化指标
| 指标 | 数值 | Chatwoot对等 | 覆盖率 |
|---|---|---|---|
| Go 源码文件 | 299 | ~500+ | 60% |
| 测试文件 | 83 | — | — |
| 测试用例 | 141+ | — | — |
| API 路由 | 207 registrations | 327+ | 64% |
| 真实实现方法 | 56 | 150+ | 37% |
| Stub/Placeholder 方法 | 37+ | 0 | 需全部补实现 |
| 501 Not Implemented | 6 | 0 | 需全部补实现 |
| 域模型 | 58 active + ~30 stub | ~80 | 73% |
| 服务 | 38 | ~50 | 76% |
| 渠道 Provider | 5 (Widget/Telegram/Email/FB/IG) | 11 | 45% |
| 安全模块 | 14 | ~14 | 100% |
| 事件 Listener | 0 业务Listener | 9 async | 0% |
8.2 关键差距
- 事件驱动链路断裂 — 核心事件总线（Watermill+Redis Streams）骨架有，但无任何业务Listener接入。Chatwoot 的 9 个 Async Listener 是功能运转的核心（自动化规则、通知、CSAT、报表、Webhook等），GoChat 全部缺失。
- Inbox 管理 API 全 stub — 无论渠道实现多完整，坐席无法通过 API 创建/配置收件箱。
- 渠道路由接入断裂 — Facebook/Telegram/Email 的 webhook_handler.go 已写好，但未被路由接入。OAuth 授权路由完全缺失。
- WebSocket 未联动 pubsub — 前端实时推送的完整链路（事件 → pubsub → WebSocket → 客户端）未串联。
8.3 优势
- 性能 — Go 原生并发，内存占用约 Chatwoot 的 1/10
- 安全 — 14 个安全模块完整实现（JWT/MFA/OAuth/SAML/RBAC/XSS/SSRF/RateLimit等）
- AI 功能 — Captain + Copilot 完整实现，超过 Chatwoot 基础 AI 功能
- 配置管理 — Viper 多环境热加载，优于 Chatwoot 的 ENV+InstallationConfig
- 测试基础设施 — SQLite/PG 双模式测试 + E2E 套件 + 141+ 测试全通过
9. 风险与缓解
| 风险 | 严重度 | 缓解措施 |
|---|---|---|
| 事件总线接入工作量超预期 | 高 | P0 阶段先实现3个核心Listener（Notification/AutomationRule/ConversationStatus），其余逐步接入 |
| WhatsApp 360dialog API 变动 | 中 | 抽象 Provider 接口隔离 API 变动；备选 go-whatsapp meow 方案 |
| 前端缺失（GoChat 仅后端） | 高 | 明确 GoChat 是纯后端API平台；前端依赖 Chatwoot Vue 前端或独立前端项目 |
| SAML SSO 完整实现复杂 | 中 | P1 先完成 OAuth 社交登录；SAML 延到 P3 |
| 数据库迁移兼容性 | 低 | golang-migrate 已集成；保持 PG-only 生产策略 |
10. 附录
10.1 参考文档
| 文档 | 路径 |
|---|---|
| 项目架构设计 | docs/architecture/P2A-项目结构与模块划分.md |
| 数据库设计 | docs/architecture/P2B-数据库设计.md |
| 路由与API设计 | docs/architecture/P2C-路由与API设计.md |
| 渠道抽象层设计 | docs/architecture/P2D-渠道抽象层设计.md |
| 认证授权与实时通信 | docs/architecture/P2E-认证授权与实时通信.md |
| 阶段二规划 | docs/PHASE2_PLAN.md |
| 渠道集成优先级 | docs/CHANNEL_INTEGRATION_PRIORITIES.md |
| Chatwoot 功能对比 | docs/comparison/Gochat-vs-Chatwoot-Full-Comparison.md |
| 安全审计报告 | docs/SECURITY_AUDIT_REPORT.md |
| 性能基准报告 | docs/PERFORMANCE_BENCHMARK.md |
| API 覆盖报告 | docs/API_COVERAGE_REPORT.md |
| 模块需求文档(M1-M12) | docs/requirements/M{1-12}-*.md |
10.2 术语表
| 术语 | 定义 |
|---|---|
| Account | 多租户账户，一个企业/组织对应一个 Account |
| Inbox | 收件箱，一个对外沟通渠道入口，绑定一个 Channel |
| Channel | 渠道，Inbox 的底层通信渠道（WebWidget/Telegram/Facebook等） |
| Conversation | 对话，客户与团队之间的一次完整交互线程 |
| Contact | 联系人/客户，CRM 核心实体 |
| Agent | 坐席/客服人员 |
| Team | 团队，坐席的逻辑分组 |
| Captain | AI 自动回复助手 |
| Copilot | AI 坐席辅助工具 |
| Portal | Help Center 门户 |
| CSAT | Customer Satisfaction，客户满意度评分 |
| AutomationRule | 自动化规则，事件+条件+动作 |
| Macro | 宏操作，一键执行多动作 |
| CannedResponse | 模板消息，快捷回复 |
| Hook | Integration Hook，外部集成连接器 |