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

生成时间: 2026-06-04 (Phase 3 完成后更新)

## 1. 项目概况

| 指标 | Chatwoot (Ruby) | GoChat (Go) |
|------|-----------------|-------------|
| 源码文件数 | 722 `.rb` | 612 `.go` (非测试) |
| 源码行数 | 42,145 行 | 112,059 行 |
| 测试行数 | N/A | 75,685 行 |
| 测试状态 | N/A | 41 ok / 10 FAIL |
| 编译状态 | N/A | `go build ./...` PASS |

## 2. 已完成对齐 (Phase 1-3)

### Phase 1: 路由补齐 ✅
- 704条路由注册完成
- 55条P0关键路由新增
- P1 alias路径补齐(labels→tags等)
- Gin radix tree参数名冲突修复(5处)
- 路由重复注册修复

### Phase 2: Service深度对齐 ✅ (10 Streams)
| Stream | 内容 | 关键改动 |
|--------|------|----------|
| S1 | CaptainAssistant CRUD | Edited=changed逻辑 |
| S2 | ConversationFinder | labels OR语义 + FilterResult(count指标) + Query/SourceID/SORT_OPTIONS(8种排序)/updated_within |
| S3 | assignable_agents | AvailableAgent intersection(round-robin) |
| S4 | contact_merge | deep_merge字段优先级(JSON递归合并) |
| S5 | csat_survey | 5种过滤器(created_at/agent/inbox/team/rating) |
| S6 | draft_messages | 已有完整CRUD(DB-based优于Redis) |
| S7 | delivery_status | 已有service+webhook路由 |
| S8 | custom_attribute_defs | key format regex + STANDARD_ATTRIBUTES冲突检测 + expanded display_type enum |
| S9 | account_user | 新建service: AddUser/RemoveUser/UpdateAvailability/UpdateRole + EventBus publish |
| S10 | Event Bus | 新增11个topic(status_changed/contact_changed/read/mention等) + AccountUser 3个topic |

### Phase 3: 逻辑对齐 ✅ (3 Waves)
| Wave | 内容 | 关键改动 |
|------|------|----------|
| P3W1 | ConversationFinder | Query/SourceID/SORT_OPTIONS/updated_within 已在更早session实现 |
| P3W2 | 错误码批量对齐 | 500→422替换(172处→0处残留)；分布: 400(313)/422(142)/404(56)/401(13)/403(18) |
| P3W3 | 授权+EventBus | EventBus service接入(AccountUserService示范); middleware体系已完整(Auth/AccountScope/Policy/RoleCheck) |

## 3. 遗留差距 (Phase 4 待做)

### P0 紧急
- 10个FAIL测试修复(参数签名变更+validation规则变更导致)
- PolicyMiddleware路由注册 — 中间件已实现但未应用到admin-only端点(Chatwoot Pundit authorize)

### P1 重要
- EventBus service层全面接入 — AccountUserService示范完成，其余service需逐步添加Publish调用
- DI注入更新 — NewAccountUserService新增eventBus参数需在bootstrap.go更新

### P2 改进
- JSON响应字段名微调(attribute_key alias等)
- 新增测试覆盖(merge/filter/account_user/event_bus)
- .bak/.BAK文件清理

## 4. 优化计划时间线

```
Phase 4 Wave 1: 修复10个FAIL测试
Phase 4 Wave 2: PolicyMiddleware路由注册(administrator-only端点)
Phase 4 Wave 3: EventBus全面接入(逐service添加Publish) + DI更新
Phase 4 Wave 4: 新增测试覆盖 + JSON响应微调 + 清理.bak文件
```

## 5. 关键决策记录

- 路由参数名统一: /:id改为具体资源名
- widget路由加/widget/前缀分离website_token路由
- platform路由合并: /platform/api/v1前缀+middleware区分认证
- Delete返回204 No Content
- Labels过滤改为OR语义 ✅
- ConversationFinder返回FilterResult含count指标 ✅
- AvailableAgent用intersection选agent ✅
- ContactMerge: base_contact属性优先+nested递归合并 ✅
- CSAT List方法+CsatFilterParams(5种过滤器) ✅
- draft_messages: DB-based是增强实现 ✅
- delivery_status: 已有service+webhook ✅
- custom_attribute_defs: 6条validation规则对齐 ✅
- 错误码: 500→422批量替换(172处) ✅
- EventBus: topic覆盖Chatwoot所有事件类型 ✅