rogee/gochat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7b28f9227dd5da699de60c32b441eae2cc4d7984
gochat/docs/GAP_REPORT_v1.md
T
Rogee 8ac150bc7b second commit
2026-06-04 15:44:48 +08:00

14 KiB
Raw Blame History

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/
Reference in New Issue View Git Blame Copy Permalink