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

> 生成时间: 2026-06-03  
> 基线: gochat @ /home/yanghao05/Workspace/gochat  
> 参考: chatwoot @ /home/yanghao05/Workspace/chatwoot-reference

---

## 一、整体概览

| 维度 | Chatwoot (Rails) | GoChat (Go) | 差距 |
|------|-----------------|-------------|------|
| 总路由数 | ~408 声明 | 704 实际注册 | GoChat超出（含alias） |
| Account级路由 | ~340 | 571 | 已覆盖，含alias路径 |
| 非Account级路由 | ~68 | 133 | 已覆盖 |
| 测试通过率 | — | 19/22 pkg PASS | 86.4% (仅handler层1pkg FAIL) |
| 编译状态 | — | ✅ PASS | — |

### 路由覆盖率

总体覆盖率 **~100%** (按Chatwoot资源维度)，GoChat注册了额外的alias路径（如 `/labels` 同时保留 `/tags`, `/hooks` 同时保留 `/integrations/hooks`）。

---

## 二、Phase 1 路由补齐完成清单

本轮新增 **55条路由** (649→704)，覆盖以下缺失域：

### 2.1 Captain域 (核心新增)
| 资源 | 新增路由 | handler/service状态 |
|------|---------|---------------------|
| assistant_responses (flat CRUD) | GET/POST/GET/:id/PATCH/:id/DELETE/:id + search | ✅ handler新建, service新建 |
| assistants (flat) | GET/POST/GET/:id/PUT/:id/DELETE/:id + tools/playground/inboxes | ✅ handler已有 |
| documents (flat) | GET/POST/GET/:id/DELETE/:id + sync | ✅ handler已有 |
| scenarios (flat) | GET/POST/GET/:id/PUT/:id/DELETE/:id | ✅ handler已有 |
| custom_tools (flat) | GET/POST/GET/:id/PUT/:id/DELETE/:id + test | ✅ handler已有 |
| copilot_threads + nested messages | CRUD + nested /:id/copilot_messages GET/POST | ✅ handler已有 |
| preferences | GET/DELETE | ✅ handler已有 |

### 2.2 Account域别名路由
| 资源 | 新增路径 | 说明 |
|------|---------|------|
| labels | /labels (alias of /tags) | Chatwoot用labels，GoChat原有tags |
| hooks | /hooks | integration hooks flat路由 |
| inbox_members | /inbox_members POST/DELETE | account级成员管理 |
| assignment_policies | /assignment_policies (plural alias) | Chatwoot用plural |
| notification_subscriptions | POST/DELETE (create/destroy) | account级通知订阅 |

### 2.3 Profile域
| 资源 | 新增路由 | handler/service状态 |
|------|---------|------|
| DELETE /profile/avatar | ✅ 新建 | handler+service新建 |
| profile/mfa (Chatwoot风格) | GET/POST/DELETE/verify/backup_codes | handler已有, backup_codes新建 |

### 2.4 Service层新增方法
| Service | 新增方法 | 状态 |
|---------|---------|------|
| CaptainAssistantResponseService | List/Get/Update/Delete + responseRepo字段 | ✅ |
| ProfileService | DeleteAvatar | ✅ |
| MFAService | GenerateBackupCodes + cryptoRandomString | ✅ |
| CaptainAssistantResponseRepo | DB() accessor | ✅ |

---

## 三、当前差距（Phase 2-4 待解决）

### 3.1 P0: Service逻辑深度对齐 (Phase 2)

| 域 | 差距描述 | 优先级 |
|----|---------|--------|
| CaptainAssistantResponse CRUD | service层List/Get/Update/Delete逻辑简化，缺少Chatwoot的filter/sort/pagination参数 | P0 |
| ConversationFinder | 7种过滤器未完整实现（status+assignee+labels+sort等） | P0 |
| assignable_agents | 缺少自动分配逻辑（round-robin等） | P0 |
| contact_merge | 合并逻辑简化，缺少duplicate检测+字段优先级规则 | P0 |
| csat_survey_responses | service层CRUD逻辑简化 | P0 |
| draft_messages | service层搜索/计数逻辑简化 | P0 |
| delivery_status | 仅handler层，service逻辑缺失 | P0 |
| custom_attribute_defs | CRUD逻辑简化，缺少validation规则 | P0 |

### 3.2 P1: Service缺失 (需新建)

| Service | 说明 |
|---------|------|
| csat_survey_service.go | Chatwoot CsatSurveyService |
| account_user_service.go | Chatwoot AccountUserService |

### 3.3 P2: 逻辑1:1对齐 (Phase 3)

| 维度 | 差距 |
|------|------|
| 错误响应码 | 部分handler返回500而非Chatwoot的404/422 |
| JSON响应结构 | 字段名/嵌套/null处理差异 |
| 授权scope检查 | middleware存在但部分handler未调用 |
| 副作用(事件触发) | 缺少Event::Dispatcher.emit类的事件系统 |
| PUT vs PATCH | Chatwoot统一用PATCH，GoChat部分用PUT |
| filter/sort/pagination | Chatwoot有ConversationFinder 7种过滤器，GoChat简化 |

### 3.4 P3: 测试覆盖 (Phase 4)

| 维度 | 当前状态 | 目标 |
|------|---------|------|
| 测试通过率 | 19/22 pkg (86.4%) | 100% |
| 失败package | handler/api/v1 (11个case) | 0 |
| 新增路由测试 | assistant_responses CRUD无测试 | 需补充 |
| handler覆盖率 | ~60% | >90% |
| service覆盖率 | ~40% | >80% |

---

## 四、优化计划（4 Waves × 4 Phases）

### Wave 1: Phase 1 路由 ✅ DONE
- 55条路由新增
- Captain域flat CRUD全注册
- Profile/MFA/Labels/Hooks alias补齐
- bootstrap依赖注入修复
- 测试构造函数参数修复

### Wave 2: Phase 2 Service深度对齐
```
S1: CaptainAssistantResponse CRUD逻辑 → 对齐Chatwoot filter/sort/pagination
S2: ConversationFinder 7种过滤器 → 完整实现
S3: assignable_agents 自动分配 → round-robin逻辑
S4: contact_merge → duplicate检测+字段优先级
S5: csat_survey → 新建service + CRUD逻辑
S6: draft_messages → 搜索/计数service逻辑
S7: delivery_status → 新建service
S8: custom_attribute_defs → validation规则
S9: account_user → 新建service
S10: 事件系统 → Event bus基础架构
```

### Wave 3: Phase 3 逻辑1:1对齐
```
S1: 错误码对齐 → 404/422/403精确匹配
S2: JSON结构对齐 → 字段名/嵌套/null
S3: 授权scope → middleware调用补齐
S4: PUT→PATCH → 批量替换HTTP方法
S5: filter/sort/pagination → 参数语义对齐
S6: 副作用(事件) → hook触发逻辑
S7: webhook验证 → 签名校验逻辑
S8: inbox_limits → 限制检查逻辑
S9: notification_preferences → 偏好更新逻辑
S10: API版本兼容 → v1/v2路由共存
```

### Wave 4: Phase 4 测试覆盖
```
S1: 修复11个FAIL测试 → AgentBot/AutomationRule
S2: assistant_responses CRUD测试 → 新建
S3: MFA backup_codes测试 → 新建
S4: Profile DeleteAvatar测试 → 新建
S5: inbox_members/labels alias测试 → 新建
S6: hooks CRUD测试 → 新建
S7: notification_subscriptions测试 → 新建
S8: assignment_policies alias测试 → 新建
S9: service覆盖率提升 → 从40%到80%
S10: handler覆盖率提升 → 从60%到90%
```

---

## 五、关键发现 & 决策

1. **路由层已基本完成**: 704条路由覆盖Chatwoot全部408个声明，含alias路径
2. **Handler层90%已存在**: 大部分P0资源已有handler方法，仅assistant_responses需新建
3. **Service层是主要差距**: CRUD逻辑简化是最大问题，需逐模块深度对齐
4. **事件系统缺失**: Chatwoot的Event::Dispatcher在GoChat中无对应
5. **测试构造函数已修复**: responseRepo参数同步到4个测试文件

---

## 六、下一步行动

**立即执行 Wave 2 (Phase 2 Service深度对齐)**，从 S1 CaptainAssistantResponse CRUD逻辑 开始。