175 lines
6.9 KiB
Markdown
175 lines
6.9 KiB
Markdown
# 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逻辑 开始。 |