gochat/docs/gochat-chatwoot-gap-report.md

GoChat vs Chatwoot 1:1 复制差距报告

生成时间: 2026-06-01 基准: chatwoot-reference (Ruby) vs gochat (Go)

---

一、总体覆盖率

维度	Chatwoot	GoChat	覆盖率
API Controller/Handler	136	107	78.7%
路由注册	136 controllers	80 handler refs	58.8%
Service 层	197	97	49.2%
Model	52	119*	—
API Action 方法	265	140	52.8%
Handler 方法真实实现	—	597 real / 33 stub	94.8% 非stub

*GoChat model 数量多于 Chatwoot 是因为拆分了子模型和辅助结构体

核心差距：API action 覆盖率仅 52.8%，Service 层差 100 个

---

二、P0：完全缺失的 Handler（28个）

Chatwoot 有对应 controller，GoChat 无任何对应 handler。

2.1 核心业务缺失（必须实现）

Chatwoot Controller	缺失 Actions	优先级	说明
AgentsController	index, create, update, destroy, bulk_create	P0	Agent 管理（创建/删除/批量创建）是核心功能
InboxesController	index, show, assignable_agents, campaigns, avatar, create, update, reset_secret, destroy	P0	Inbox 管理 9 个 action 全缺，路由已注册 h.Inbox. 但 handler 未实现
CsatSurveyResponsesController	index, metrics, download	P0	CSAT 问卷响应查看/下载
CategoriesController	index, show, create, update, destroy, reorder	P0	Helpcenter 分类 CRUD
BulkActionsController	create	P1	批量操作入口
SearchController	index, conversations, contacts, messages, articles	P0	全局搜索 5 个端点
ContactInboxesController	filter	P1	Contact-Inbox 过滤
InboxMembersController	show, create, update, destroy	P1	路由有 h.InboxMember. 但 4 个 action 全缺
LabelsController	index, show, create, update, destroy	P1	路由有 h.Label. 但 5 个 action 全缺
UploadController	create	P1	文件上传

2.2 集成/渠道缺失

Chatwoot Controller	缺失 Actions	说明
CallbacksController	register_facebook_page, log_additional_info, facebook_pages, reauthorize_page	Facebook 回调处理
Integrations::AppsController	index, show	集成 App 列表/详情
Integrations::HooksController	create, update, destroy	集成 Hook CRUD
Integrations::DyteController	create_a_meeting, add_participant_to_meeting	Dyte 视频会议
Integrations::LinearController	destroy, teams, team_entities, create_issue, link_issue, unlink_issue, linked_issues, search_issue	Linear 项目管理集成（8 action）
Integrations::NotionController	destroy	Notion 集成删除
Integrations::ShopifyController	auth, orders	Shopify 电商集成
Google::AuthorizationsController	create	Google OAuth 授权

2.3 AI/Captain 缺失

Chatwoot Controller	缺失 Actions	说明
Captain::PreferencesController	show, update	AI 助手偏好设置
Captain::TasksController	rewrite, summarize, reply_suggestion, label_suggestion, follow_up	AI 助手任务（5 action）

2.4 Reporting/分析缺失

Chatwoot Controller	缺失 Actions	说明
V2::LiveReportsController	conversation_metrics, grouped_conversation_metrics	实时报表
V2::SummaryReportsController	agent, channel	汇总报表
V2::YearInReviewsController	show	年度回顾

2.5 其他缺失

Chatwoot Controller	缺失 Actions	说明
AssignmentPoliciesController	index, show, create, update, destroy	路由有注册但映射失败
SlaPoliciesController	index, show, create, update, destroy	SLA 策略 CRUD

---

三、P1：部分匹配的 Handler（12个）

存在 handler 但缺少部分 action。

Chatwoot Controller	GoChat Handler	覆盖	缺失 Actions
ContactsController	ContactHandler	10/13 (77%)	filter, destroy_custom_attributes, avatar
ConversationsController	ConversationHandler	13/20 (65%)	attachments, pending_to_open_by_bot, should_assign_conversation, toggle_priority, toggle_typing_status, update_last_seen, custom_attributes
PortalsController	PortalHandler	6/8 (75%)	logo, send_instructions
NotificationsController	NotificationHandler	5/8 (62%)	read_all, destroy_all, unread_count
ProfilesController	ProfileHandler	3/7 (43%)	auto_offline, availability, resend_confirmation, reset_access_token
Articles::BulkActionsController	ArticleHandler	2/3 (67%)	translate
Conversations::MessagesController	ConversationHandler	4/6 (67%)	retry, translate
AssignmentPolicies::InboxesController	AssignmentPolicyHandler	0/1 (0%)	index
InboxMembersController	InboxMemberHandler	0/4 (0%)	show, create, update, destroy
LabelsController	LabelHandler	0/5 (0%)	index, show, create, update, destroy
SearchController	SearchHandler	0/5 (0%)	index, conversations, contacts, messages, articles
UploadController	UploadHandler	0/1 (0%)	create

---

四、Stub/Placeholder 方法（33个）

方法已声明但实现为 stub/placeholder，未包含真实业务逻辑。

Handler	Stub Method	说明
account	UpdateActiveAt	活跃时间更新
campaign	Start, Stop	Campaign 启停
captain_preference	Delete	AI偏好删除
company	AddContact, DeleteNote, RemoveContact	Company 关联操作
contact	Delete, DeleteCustomAttributes	联系人删除
email_channel	Delete	Email渠道删除
facebook_channel	DeleteFacebookPage, ReauthorizeFacebookPage	Facebook 页面管理
google_channel	Delete	Google渠道删除
inbox	RegisterWebhook, SetAgentBot	Inbox Webhook注册/AgentBot设置
integration_hook	ProcessHookEvent	Hook事件处理
line_channel	Delete	LINE渠道删除
linear_integration	Delete	Linear集成删除
microsoft_channel	Delete	Microsoft渠道删除
notification	DestroyAll, MarkAllRead, UpdateSettings	通知批量操作
notion_integration	Delete	Notion集成删除
saml	SPInitiatedSLO	SAML SLO
shopify_integration	Delete	Shopify集成删除
slack_integration	Delete	Slack集成删除
tiktok_channel	DeleteTikTokChannel	TikTok渠道删除
twilio_channel	Delete	Twilio渠道删除
twitter_channel	Delete	Twitter渠道删除
webwidget_offline	DismissOfflineMessage	离线消息dismiss
webwidget_theme	DeletePreChatForm, DeleteThemeConfig	Widget配置删除
whatsapp_call	Delete	WhatsApp通话删除

---

五、未注册路由的 Handler（30个）

Handler 文件存在但未在 router.go 注册路由（HTTP 不可访问）。

关键缺失路由：

Handler	应注册路由	优先级
AuthHandler	/api/v1/auth/*	P0
AgentCapacityHandler	/api/v1/accounts/:account_id/agent_capacity_policies/*	P1
AuditHandler	/api/v1/accounts/:account_id/audits/*	P2
CustomRoleHandler	/api/v1/accounts/:account_id/custom_roles/*	P1
IntegrationHookHandler	/api/v1/accounts/:account_id/integrations/hooks/*	P1
NoteHandler	/api/v1/accounts/:account_id/contacts/:contact_id/notes/*	P0
NotificationSettingHandler	/api/v1/accounts/:account_id/notification_settings/*	P1
WidgetHandler	/widget/*	P1
WebhookHandler	/api/v1/accounts/:account_id/webhooks/*	P1

其余 21 个为 SSO/LDAP/OIDC/MFA 等认证相关和渠道集成（Twilio/Slack/Shopify 等），优先级较低。

---

六、Model 层差距

6.1 Chatwoot 有但 GoChat 缺的 Model

Model	重要性	说明
WorkingHour	P1	营业时间（影响自动分配和 SLA）
NotificationSubscription	P2	推送订阅管理
PlatformAppPermissible	P1	Platform App 权限
PlatformBanner	P1	Platform Banner（已有 BannerHandler 但 model 不匹配）
Webhook	P2	旧版 Webhook
EmailTemplate	P2	邮件模板

其余（ApplicationRecord, DataImport, Integrations, JsonbAttributesLengthValidator, Kbase, SuperAdmin）是 Rails 内部/辅助模型，无需复制。

6.2 已有 Model 但可能缺少字段

需逐一对比 Chatwoot model 的字段与 GoChat model 字段。关键可疑差距：

• User: 缺 availability_status, auto_offline 字段（Profile handler 43% 覆盖）
• Conversation: 缺 priority, pending_by_bot 状态相关字段
• Inbox: 缺 agent_bot 关联
• Contact: 缺自定义属性删除逻辑

---

七、Service 层差距（最严重）

Chatwoot 197 services vs GoChat 97 services，差 100 个 service。

7.1 关键缺失 Service 分类

分类	Chatwoot 数量	GoChat 状态	差距说明
conversations	14	部分	缺 filter_service, message_window_service, permission_filter_service, typing_status_manager, unread_counts 全套(9)
contacts	6	部分	缺 bulk_action_service, contactable_inboxes_service, filter_service, sync_attributes
instagram	10	无	完全缺失 Instagram 渠道 service
whatsapp	7+	部分	缺 send_on_whatsapp_service, incoming_message_service 等
telegram	3	部分	缺 send_on_telegram_service
auto_assignment	5	✅ 已实现	GoChat 有完整 autoassignment 包
automation_rules	3	部分	缺 action_service, condition_validation_service
notification	多个	部分	缺 push_notification_service
search	多个	无	搜索 service 完全缺失（search 包被标记 bak_offline）
reporting	多个	部分	有 reporting 包但缺具体聚合 service
portal/kbase	多个	部分	缺 portal 相关子 service
captain/ai	多个	部分	有 llm 包但缺具体 captain service
email/imap	5	无	IMAP 邮件获取完全缺失
line	2	部分	LINE 渠道 service
twilio	多个	部分	SMS/WhatsApp 渠道
sla	多个	部分	SLA 计算 service
macro	多个	部分	Macro 执行 service
crm	9	无	CRM 集成（LeadSquared 等）完全缺失
facebook	1	部分	缺 send_on_facebook_service

7.2 GoChat 已实现的 Service 亮点

• autoassignment: 完整实现（round_robin, rate_limiter, listener）
• automation: 16 个文件，较完整
• auth: 14 个文件，SSO/MFA/OIDC/SAML/LDAP 全覆盖
• channel: 13 个文件，多渠道支持
• middleware: 19 个文件，中间件完整
• ws: 8 个文件，WebSocket/SSE 实现

---

八、优化计划

Phase 1: P0 核心功能补齐（2-3周）

目标：API action 覆盖率从 52.8% → 70%

任务	工作量	依赖
实现 AgentsController（5 action）	3天	Agent model + AgentService
实现 InboxesController（9 action）	5天	InboxService 完善
实现 SearchController（5 action）	3天	SearchService（需解冻 search_bak）
实现 CategoriesController（6 action）	2天	CategoryService 完善
实现 CsatSurveyResponsesController（3 action）	2天	CsatSurveyService
实现缺失路由注册（30个 handler → router.go）	2天	各 handler 已存在
补齐 ContactHandler 3 action	1天	Contact model
补齐 ConversationHandler 7 action	3天	ConversationService
补齐 NotificationHandler 3 action	1天	NotificationService
补齐 ProfileHandler 4 action	1天	User model 字段

Phase 2: P1 功能补齐（2-3周）

目标：API action 覆盖率从 70% → 85%

任务	工作量
33 stub 方法改为真实实现	5天
Label CRUD 5 action	1天
InboxMember CRUD 4 action	1天
Upload create action	1天
IntegrationHook CRUD	2天
IntegrationApp list/show	1天
WorkingHour model + service	2天
Conversation unread_counts 全套	3天
Contact filter/bulk services	2天
Notification push service	2天

Phase 3: 渠道集成补齐（3-4周）

目标：API action 覆盖率从 85% → 95%

任务	工作量
Instagram 渠道 service（10个）	5天
IMAP 邕件获取（5个）	3天
Facebook callback 处理	2天
Slack integration service	2天
Linear integration service	3天
Shopify integration service	2天
Dyte integration service	1天
Captain/AI task services	3天

Phase 4: 测试覆盖 & 稳定性（持续）

任务	说明
Handler 测试覆盖率 80%	当前 71.4%，需继续写 0%-coverage handler 测试
Service 层测试	当前缺失大量 service 测试
集成测试	渠道回调、事件发布等集成测试
E2E 测试	关键业务链路 E2E

---

九、关键发现总结

1. 最大差距在 Service 层：差 100 个 service（197 vs 97），大量业务逻辑未实现
2. 路由注册是隐性差距：30 个 handler 存在但路由未注册，等于 30 个 handler 完全不可用
3. Conversation 是最大单点差距：13/20 action 覆盖，缺 7 个关键 action（priority, typing_status, bot assignment 等）
4. Search 功能完全缺失：search 包标记 bak_offline，5 个搜索端点全部 0% 覆盖
5. 33 个 stub 方法：方法声明了但返回 placeholder，无真实业务逻辑
6. 渠道集成大面积缺失：Instagram(10), IMAP(5), CRM(9), Linear(8) 等渠道 service 全无
7. 已有亮点：autoassignment 完整、auth 完整、automation 较完整、WebSocket/SSE 实现

---

十、风险评估

风险	级别	说明
Search 包标记 bak_offline	高	搜索功能完全不可用，需决定重新实现还是解冻
Conversation 65% 覆盖	高	核心功能缺 7 action，影响日常使用
30 个 handler 未注册路由	中	功能已实现但无法访问，注册后立即可用
33 个 stub 方法	中	方法存在但返回空，需逐一实现真实逻辑
渠道集成缺失	中	Instagram/IMAP/CRM 等渠道无法接入
Service 层差 100 个	高	大量业务逻辑（过滤、批量操作、通知推送等）缺失