# GoChat vs Chatwoot 实现差距报告 & 优化计划

生成时间: 2026-06-03  
作者: Hermes Agent  
版本: v1.0

## 1. 项目概览

| 项目 | GoChat (Go) | Chatwoot (Ruby on Rails) |
|------|-------------|--------------------------|
| 语言/框架 | Go + Gin | Ruby on Rails |
| 数据库 | PostgreSQL | PostgreSQL |
| 实时通讯 | WebSocket (gorilla) | ActionCable |
| 搜索 | pgvector (stub) | Elasticsearch |
| IMAP | goimap_stub | Mail imap |
| 全项目文件 | 635 Go + 272 test | 722 Ruby |

### 架构层

| 层 | GoChat | Chatwoot | 差距 |
|----|--------|----------|------|
| Controller/Handler | 129 | 177 | 48 |
| Model | 104 (158含测试) | 103 | 0 |
| Service | 105 | 197 | **92** |
| Repository | 95 | ~100 (Rails无独立repo层) | - |
| Middleware | 19 | ~50 (concern) | - |
| Channel Provider | 73 | ~20 | - |
| 其他模块 | 14(auto)+ 16(automation)+ 6(campaign)+ 3(canned)+ 3(csat)+ 5(reporting)+ 4(search)+ 6(security)+ 8(ws)+ 3(pubsub) | - | - |
| 总模块目录 | 27个 | ~10 | **17差距** |

### 路由统计

| 指标 | GoChat | Chatwoot | 备注 |
|------|--------|----------|------|
| 总 HTTP 路由 | 653 | 539 | GoChat含额外路由 |
| Account-scoped 资源 | 67个 | 68个 | 基本持平 |
| 非 Account 路由 | 48条 | ~70条 | auth/profile/notification/sso等 |
| Platform 路由 | 25条 | 15条 | GoChat含更多platform路由 |
| Widget 路由 | 8条 | 10条 | 接近持平 |
| 路由参数名冲突 | 已修复5个 | 0 | ✅ |
| 路由重复注册 | 已修复2个 | 0 | ✅ |
| 参数名标准化后匹配 | 101条 | 101条 | 覆盖率18.7% |

### API方法分布

| 方法 | GoChat | Chatwoot | 差距 |
|------|--------|----------|------|
| GET | 262 | 216 | +46 |
| POST | 205 | 178 | +27 |
| DELETE | 96 | 76 | +20 |
| PUT | 57 | 1 | +56 |
| PATCH | 29 | 68 | **-39** |

**关键发现**: GoChat PATCH路由严重不足(29 vs 68)，说明部分更新逻辑用了PUT替代或完全缺失。Chatwoot大量使用PATCH做字段级更新，GoChat需补齐39条PATCH路由。

---

## 2. 核心差距分析 (资源级对比)

### P0 核心缺失 — 影响基础使用流程的必要资源

| 资源 | 状态 | 影响 |
|------|------|------|
| assignable_agents | ❌ 完全缺失 | 工单分配核心功能 |
| inbox_members | ❌ 完全缺失 | 收件箱成员管理 |
| inbox_limits | ❌ 完全缺失 | 收件箱容量限制 |
| notes | ❌ 完全缺失 | 对话备注功能 |
| draft_messages | ❌ 完全缺失 | 消息草稿箱 |
| delivery_status | ❌ 完全缺失 | 消息投递状态追踪 |
| custom_attribute_definitions | ⚠️ 部分实现 | 自定义属性定义 |
| contact_merge | ⚠️ 仅service | 联系人合并 |
| csat_template | ❌ 完全缺失 | CSAT模板管理 |
| csat_survey_responses | ⚠️ handler存在但service薄弱 | CSAT调查响应 |
| hooks | ⚠️ 仅webhook handler | 集成Hook管理 |
| notification_subscriptions | ⚠️ 仅部分路由 | 通知订阅管理 |
| participants | ⚠️ 仅部分实现 | 对话参与者管理 |
| account_users | ⚠️ 仅路由 | 账户用户管理 |
| access_tokens | ❌ 完全缺失 | 平台访问令牌 |

### P1 重要缺失 — 企业级/高级功能

| 资源 | 状态 | 影响 |
|------|------|------|
| agents | ⚠️ 仅index/create | 代理人CRUD+批量操作 |
| assignments | ❌ 完全缺失 | 对话分配记录 |
| custom_roles | ⚠️ 仅CRUD路由 | 自定义角色权限 |
| sla_policies | ⚠️ 仅CRUD路由 | SLA策略管理 |
| applied_slas | ⚠️ 仅GET路由 | SLA应用追踪 |
| dashboard_apps | ⚠️ 仅CRUD路由 | 仪表盘应用 |
| macros | ⚠️ 路由存在但service薄弱 | 宏操作 |
| mfa | ❌ 完全缺失 | 多因素认证 |
| apps | ❌ 完全缺失 | 平台应用 |
| installation_configs | ❌ 完全缺失 | 安装配置 |
| agent_capacity_policies | ⚠️ 仅路由 | 代理人容量策略 |

### P2 二级缺失 — 集成/扩展/边缘功能

| 资源 | 状态 | 影响 |
|------|------|------|
| captain/assistants | ⚠️ 仅部分路由 | AI助手(Captain) |
| captain/copilot_threads | ⚠️ 仅路由 | AI Copilot线程 |
| captain/custom_tools | ⚠️ 仅路由 | AI自定义工具 |
| captain/documents | ⚠️ 仅路由 | AI文档管理 |
| captain/scenarios | ⚠️ 仅路由 | AI场景 |
| captain/assistant_responses | ⚠️ 仅路由 | AI助手响应 |
| categories/articles | ⚠️ 仅CRUD路由 | 知识库分类/文章 |
| conference | ❌ 完全缺失 | 视频会议(Dyte) |
| team_members | ❌ 完全缺失 | 团队成员管理 |
| events | ❌ 完全缺失 | 事件追踪 |
| callback | ⚠️ 仅路由 | 回调管理 |
| whatsapp_calls | ❌ 完全缺失 | WhatsApp通话 |
| notification_settings | ⚠️ 仅路由 | 通知设置 |

---

## 3. Service层差距 (关键缺失)

| Service | GoChat | Chatwoot | 缺失 |
|---------|--------|----------|------|
| AssignableAgentService | ❌ | ✅ autoassignment模块扩展 | 缺少round-robin/负载均衡/技能匹配 |
| InboxMemberService | ❌ | ✅ | 缺少CRUD+批量操作 |
| InboxLimitService | ❌ | ✅ | 缺少容量检查+限制逻辑 |
| NoteService | ❌ | ✅ | 缺少CRUD |
| DraftMessageService | ❌ | ✅ | 缺少CRUD+发送逻辑 |
| DeliveryStatusService | ❌ | ✅ | 缺少状态追踪+更新 |
| CsatTemplateService | ❌ | ✅ | 缺少模板管理 |
| HookService | ❌ | ✅ | 缺少CRUD+事件分发 |
| AssignmentService | ❌ | ✅ | 缺少分配记录 |
| MfaService | ❌ | ✅ | 缺少启用/禁用/验证 |
| PlatformAppService | ⚠️ stub | ✅ | 需完整实现 |
| AgentCapacityPolicyService | ⚠️ stub | ✅ | 需完整实现 |
| CustomRoleService | ⚠️ stub | ✅ | 需完整实现 |
| SlaPolicyService | ⚠️ stub | ✅ | 需完整实现 |
| MacroExecutionService | ❌ | ✅ | 缺少执行引擎 |
| DashboardAppService | ⚠️ stub | ✅ | 需完整实现 |
| AppliedSlaService | ❌ | ✅ | 缺少SLA追踪 |
| SlaPolicyAssignmentService | ❌ | ✅ | 缺少策略分配 |

**Service层总计**: GoChat 105 vs Chatwoot 197, 缺失92个service

---

## 4. 业务逻辑对齐差距 (即使路由和service存在,逻辑也可能不匹配Chatwoot)

| 功能 | GoChat | Chatwoot | 差距类型 |
|------|--------|----------|----------|
| 对话自动分配 | autoassignment模块(6文件)+5个service | AutoAssignmentService+round-robin/负载均衡/技能匹配 | 逻辑简化,缺少round-robin/负载均衡 |
| 对话创建 | 基础CRUD+3个service | ConversationService+contact_inboxes/label批量操作 | 缺少contact_inboxes/label批量操作 |
| 对话搜索 | ConversationFinder(7种过滤器) | ConversationFinder(7种过滤器+排序+分页) | 缺少排序和分页 |
| 联系人搜索 | ContactFinder(2种过滤器) | ContactFinder(6种过滤器+排序+分页) | 缺少4种过滤器+排序+分页 |
| 消息发送 | 渠道差异化发送逻辑 | MessageSenderService+渠道差异化 | 需逐渠道对齐发送细节 |
| CSAT收集 | CsatSurveyResponseService | CsatSurveyResponseService+CsatTemplateService | 缺少CsatTemplateService(模板管理) |
| 联系人合并 | ContactMergeService | ContactMergeService+ContactMergeActionService | 缺少ContactMergeActionService(合并操作) |
| 实时报告 | LiveReportService | LiveReportService+ReportService+SummaryReportService+YearInReview | 缺少3个报告service |
| SLA | SlaPolicyService | SlaPolicyService+AppliedSlaService+SlaPolicyAssignmentService | 缺少2个SLA service |
| 宏操作 | MacroService | MacroService+MacroExecutionService | 缺少MacroExecutionService(执行引擎) |
| 通知 | NotificationService | NotificationService+NotificationSubscriptionService | 缺少NotificationSubscriptionService(订阅管理) |
| 自动化规则 | AutomationRuleService | AutomationRuleService+AutomationActionService | 缺少AutomationActionService(执行引擎) |

---

## 5. 测试状态

| 指标 | 数值 |
|------|------|
| 总测试数 | 2,577 |
| PASS | 2,566 |
| FAIL | 11 |
| 通过率 | 99.6% |

**FAIL测试清单(11个,全部在handler层):**

1. TestAgentBotHandlerSuite — agent_bot handler auth/middleware问题
2. TestAutomationRuleHandlerTestSuite — automation_rule handler auth问题(9个子FAIL)
3. TestConversationCrudTestSuite — conversation CRUD auth问题(10个子FAIL)
4. TestConversationHandlerTestSuite — conversation handler auth问题(5+子FAIL)
5. TestConversationParticipantHandlerTestSuite — participant handler auth问题(5+子FAIL)
6. TestDraftMessageHandlerTestSuite — draft_message handler auth问题
7. TestMessageHandlerTestSuite — message handler auth问题(5+子FAIL)
8. TestNotificationGet — notification handler DB/mock问题
9. TestNotificationGetDifferentID — notification handler DB/mock问题
10. TestNotificationHandler_SnoozeWithDB — notification handler DB/mock问题
11. TestNotificationHandler_UnreadWithDB — notification handler DB/mock问题

**所有FAIL均属于auth middleware或DB mock配置问题, 非业务逻辑错误。**

---

## 6. 优化计划 (分4 Phase推进)

### Phase 1: 路由补全 (优先级 P0 > P1)
目标: 补齐缺失路由, 覆盖率从18.7%提升至80%+

**Wave 1 (P0核心, 2周):**
- S1: assignable_agents — GET /api/v1/accounts/:id/assignable_agents
- S2: inbox_members — CRUD /api/v1/accounts/:id/inboxes/:id/inbox_members
- S3: inbox_limits — GET/POST /api/v1/accounts/:id/inboxes/:id/inbox_limits
- S4: notes — CRUD /api/v1/accounts/:id/conversations/:id/notes
- S5: draft_messages — CRUD /api/v1/accounts/:id/conversations/:id/draft_messages
- S6: delivery_status — GET /api/v1/accounts/:id/conversations/:id/messages/:id/delivery_status
- S7: contact_merge — POST /api/v1/accounts/:id/actions/contact_merge
- S8: csat_template — GET/PATCH /api/v1/accounts/:id/csat_template
- S9: csat_survey_responses — 补齐service层缺失逻辑
- S10: hooks — CRUD /api/v1/accounts/:id/integrations/:id/hooks

**Wave 2 (P1重要, 2周):**
- S11: assignments — CRUD /api/v1/accounts/:id/conversations/:id/assignments
- S12: account_users — 补齐service层缺失逻辑
- S13: access_tokens — CRUD /platform/api/v1/apps/:id/access_tokens
- S14: agents — 补齐destroy/bulk_actions
- S15: mfa — GET/POST /api/v1/profile/mfa
- S16: apps — CRUD /platform/api/v1/apps
- S17: installation_configs — CRUD /api/v1/installation_configs
- S18: agent_capacity_policies — 补齐service层缺失逻辑

**关键修正**: PATCH路由需从29→68, 补39条PATCH路由(部分更新逻辑)

### Phase 2: Service补全 (优先级 P0 > P1 > P2)
目标: 补齐92个缺失service, 从105提升至197

**Stream 1 (P0, 3周):**
- AssignableAgentService (autoassignment模块扩展)
- InboxMemberService (新增)
- InboxLimitService (新增)
- NoteService (新增)
- DraftMessageService (新增)
- DeliveryStatusService (新增)
- CsatTemplateService (新增)
- HookService (新增)
- AssignmentService (新增)
- ContactMergeActionService (新增)

**Stream 2 (P1, 3周):**
- MfaService (新增)
- PlatformAppService (从stub→完整实现)
- AgentCapacityPolicyService (从stub→完整实现)
- CustomRoleService (从stub→完整实现)
- SlaPolicyService (从stub→完整实现)
- MacroExecutionService (新增)
- DashboardAppService (从stub→完整实现)
- AppliedSlaService (新增)
- SlaPolicyAssignmentService (新增)

**Stream 3 (P2, 4周):**
- Captain各service (6个)
- NotificationSubscriptionService (新增)
- TeamMemberService (新增)
- ConferenceService (新增)
- CategoryService/ArticleService (从stub→完整实现)
- ReportService/SummaryReportService/YearInReviewService (新增)

### Phase 3: 逻辑1:1对齐验证 (优先级 P0 > P1)
目标: 验证所有已实现功能的逻辑完全匹配Chatwoot

**Stream 1 (P0, 3周):**
- 对话自动分配: round-robin/负载均衡/技能匹配
- 对话搜索: 7种过滤器+排序+分页
- 联系人搜索: 6种过滤器+排序+分页
- 消息发送: 渠道差异化发送逻辑
- CSAT: 模板管理+收集逻辑
- 联系人合并: 合并操作+关联迁移

**Stream 2 (P1, 3周):**
- 自动化规则: AutomationActionService执行引擎
- SLA: AppliedSla追踪+策略分配
- 宏操作: MacroExecutionService执行引擎
- 实时报告: 4种报告service对齐

### Phase 4: 测试覆盖提升
目标: 从272个测试提升至834+, 覆盖率从93%提升至95%+

**Stream 1 (修复现有7个FAIL, 1周):**
- 修复handler auth middleware测试问题(11个FAIL)

**Stream 2 (新增P0测试, 2周):**
- AssignableAgentService测试
- InboxMemberService测试
- NoteService测试
- DraftMessageService测试
- DeliveryStatusService测试
- ContactMergeActionService测试

**Stream 3 (新增P1/P2测试, 2周):**
- MfaService测试
- MacroExecutionService测试
- SlaPolicyService测试
- Captain各service测试

---

## 7. 关键风险和建议

| 风险 | 影响 | 建议 |
|------|------|------|
| Chatwoot routes.rb解析器产生嵌套路由串联问题 | 差距报告伪缺失 | 重写解析器,改用资源级对比而非路由路径级 |
| GoChat路由数量多于Chatwoot(653 vs 539) | 多余路由可能含冗余/错误注册 | 逐条审查多余路由, 确认是合理扩展还是误注册 |
| normalize函数标准化不足 | 低估覆盖率 | 只标准化_id结尾参数, 不标准化子段名(如avatar) |
| Service层92个缺口 | 功能不可用 | 优先补齐P0核心service |
| 11个handler测试FAIL | 功能回归测试不可靠 | 优先修复FAIL测试, 再补新service测试 |
| Chatwoot有197个service而GoChat只有105个 | Phase 2工作量巨大 | 分3波推进, P0→P1→P2 |
| 1:1对齐要求极高 | 实现细节差异大 | Phase 3需逐模块对比验证, 预计耗时最长 |
| PATCH路由严重不足(29 vs 68) | 部分更新逻辑缺失 | Phase 1需优先补齐39条PATCH路由 |
| v2 API完全缺失 | 报告API不可用 | 需新增/api/v2/路由组(12条路由) |

---

## 8. 数据来源

- GoChat路由: cmd/dump_routes输出 (653条HTTP路由)
- Chatwoot路由: scripts/parse_chatwoot_routes_v3.py解析routes.rb (539条API路由)
- GoChat文件统计: find + wc统计
- Chatwoot文件统计: find + wc统计
- 测试数据: go test ./internal/... -v输出
- Service差距: 手动比对internal/service/ vs chatwoot app/services/