# 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 个 | 高 | 大量业务逻辑（过滤、批量操作、通知推送等）缺失 |