# GoChat 对齐优化计划 — 最大化并行开发

生成时间: 2026-06-03
基于: GAP_REPORT.md 差距分析 + 依赖拓扑分析

---

## 一、修正关键事实

原始差距报告中"60个stub模型未编译"的说法需修正:

- 60个 .go.txt 文件中 **50个** 已有对应的编译版本(位于 automation/csat/canned/channel 等子包)
- **仅10个** 是真正的未编译 stub: `automation_action`, `call`, `captain_assistant_inbox`,
  `channelable`, `contactable`, `data_import`, `email_template`, `enums`, `message_reaction`, `report`
- AutoMigrate 中注册的所有模型均已编译可运行
- GoChat 端点数577 ≠ 功能完成度，大量是薄壳handler(单方法, <100行)

---

## 二、依赖拓扑分析

### 2.1 模块间导入依赖矩阵

通过分析 handler/service 的 import 语句，确定模块间依赖边界:

```
                    ┌─────────────────────────┐
                    │       model (78+编译)     │ ← 所有模块的基础依赖
                    └─────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
    ┌────┴─────┐        ┌────┴─────┐        ┌────┴─────┐
    │ repository │       │  service  │       │  auth/security │
    │   (92)    │       │   (95)    │       │  (22+5)        │
    └───────────┘       └───────────┘       └───────────────┘
         │                    │
    ┌────┴──────────────┬─────┴──────────┐
    │                   │                │
┌───┴────┐     ┌───────┴──────┐   ┌─────┴─────┐
│ handler │     │  子包(automation │ │  子包(channel │
│  (106)  │     │  /csat/canned) │ │  /campaign)  │
└─────────┘     └──────────────┘   └──────────────┘
```

### 2.2 可并行的独立域

以下域之间 **无直接代码依赖**(仅共享model层)，可以完全并行开发:

| 并行域 (Stream) | 包范围 | 依赖边界 | 预估代码量 |
|----------------|--------|---------|-----------|
| **S1: SLA追踪域** | model.AppliedSLA/SlaEvent/SlaPolicy + sla相关service | 仅依赖model层 | ~400行新增 |
| **S2: CSAT收集域** | csat.CsatSurveyResponse + csat_survey_service + 公开API | 仅依赖model+automation | ~350行新增 |
| **S3: 对话查找域** | conversation_service ConversationFinder逻辑 | 依赖model+repository | ~800行新增 |
| **S4: 智能分配域** | autoassignment + assignable_agent_handler | 依赖model+repository | ~500行新增 |
| **S5: Contact级联域** | contact_merge_service 级联更新 | 依赖model+多个repository | ~600行新增 |
| **S6: 模型激活域** | 10个真实stub .go→.go 编译激活 | 仅需model层改动 | ~100行改动 |
| **S7: Channel发送域** | 各channel send_on_*_service | 依赖channel子包+model | ~1500行新增 |
| **S8: 报表聚合域** | reporting_events 聚合+rollup | 仅依赖model+repository | ~500行新增 |
| **S9: CRM集成域** | crm processor/mapper/client | 仅依赖model+service | ~600行新增 |
| **S10: 测试域** | model/service/handler test补全 | 依赖所有业务模块 | ~3000行新增 |

### 2.3 不可并行的串行依赖链

```
S6(模型激活) → S1(SLA追踪) → AppliedSLA已编译，S6不阻塞S1
S6(模型激活) → S8(报表聚合) → report.go.txt需先激活
S6(模型激活) → S9(CRM) → data_import需先激活
S6(模型激活) → 其他stub相关模块

结论: S6是前置任务，但仅需1-2天完成(10个文件改名+AutoMigrate注册)
完成S6后，S1-S9全部可并行启动
```

---

## 三、并行开发计划 — 4 Wave 执行

### Wave 0: 前置准备 (1-2天, 串行)

| 任务 | 说明 | 产出 |
|------|------|------|
| **W0-T1: 激活10个stub模型** | automation_action→automation_action.go, call→call.go, captain_assistant_inbox→captain_assistant_inbox.go, channelable→channelable.go, contactable→contactable.go, data_import→data_import.go, email_template→email_template.go, enums→enums.go(合并到common.go), message_reaction→message_reaction.go, report→report.go | 所有.go.txt改名.go, 修复编译错误, 注册AutoMigrate |
| **W0-T2: 建立测试基线** | 为78个model创建基础CRUD+约束测试模板 | model_test.go模板, 至少覆盖P0模型 |
| **W0-T3: 修复现有编译问题** | 确保所有.go.txt改名后项目编译通过 | `go build ./...` 成功 |

> W0完成后立即启动 Wave 1 的所有并行流

### Wave 1: P0核心功能补全 (2-3周, 6个并行流)

#### Stream S1: SLA追踪完善 [预计5天]

```
依赖: model.AppliedSLA/SlaEvent/SlaPolicy (已编译)
参考: Chatwoot enterprise/app/controllers/applied_slas_controller.rb (70行)
      enterprise/app/services/sla/evaluate_applied_sla_service.rb (107行)

任务清单:
  S1-1: applied_sla_service.go — 完善SLA评估逻辑
         - 会话匹配SLA策略时创建AppliedSLA
         - SLA状态跟踪(active → hit → breached)
         - 参考 Chatwoot EvaluateAppliedSlaService
  S1-2: applied_sla_handler.go — 增加download/metrics API
         - GET /api/v1/accounts/:id/applied_slas (列表+过滤)
         - GET /api/v1/accounts/:id/applied_slas/download (CSV导出)
  S1-3: sla_event_service.go — SLA阈值事件追踪
         - 当AppliedSLA达到阈值时创建SlaEvent
         - FRT/NRT事件类型处理
  S1-4: applied_sla_test.go + sla_event_test.go — 测试覆盖
```

#### Stream S2: CSAT Survey Response收集 [预计5天]

```
依赖: csat.CsatSurveyResponse (已编译), automation包
参考: Chatwoot csat_survey_responses_controller.rb (54行)

任务清单:
  S2-1: csat_survey_response_service.go — 独立service文件
         - 创建/提交/统计逻辑
         - 公开API端点 /public/api/v1/conversations/:uuid/csats
  S2-2: csat_survey_response_handler.go — 公开API handler
         - 无需认证的公开提交端点
         - 验证conversation UUID有效性
  S2-3: csat_survey_response_test.go — 测试覆盖
         - 公开端点无需认证验证
         - 统计聚合准确性
```

#### Stream S3: Conversation Finder 7过滤器 [预计7天] ⚡ 最大量

```
依赖: conversation_service, model, repository, search包
参考: Chatwoot app/finders/conversation_finder.rb (217行)
      mailbox/conversation_finder.rb + 5个strategy文件

任务清单:
  S3-1: conversation_finder.go — 核心查找器(新文件)
         - 7种过滤器实现:
           1. status (open/resolved/pending/all)
           2. assignee_type (me/unassigned/all)
           3. sort_by (latest/created_at/last_activity)
           4. order (asc/desc)
           5. labels (多标签AND/OR组合)
           6. inbox_ids (多inbox过滤)
           7. tags (自定义标签)
         - 分页: page/per_count参数
         - 精确匹配Chatwoot SQL语义
  S3-2: conversation_finder_strategy.go — 策略模式
         - BaseStrategy + 各过滤策略子类
         - 可组合的过滤链
  S3-3: conversation_handler.go — 扩展index方法
         - 传入所有7种过滤参数
         - 与现有conversation_service协同
  S3-4: conversation_finder_test.go — 7种过滤+组合测试
```

#### Stream S4: 智能分配(Assignable Agent) [预计5天]

```
依赖: autoassignment包, model, repository
参考: Chatwoot assignable_agents_controller.rb (24行) + 5个auto_assignment service

任务清单:
  S4-1: assignable_agent_service.go — 扩展智能查询
         - inbox_ids[] 过滤
         - 技能匹配(skill-based)
         - 可用性检查(online/offline)
         - 负载计算(current_conversations_count)
         - 返回带评分的排序agent列表
  S4-2: assignable_agent_handler.go — 扩展到完整Controller
         - 从76行单方法→完整查询handler
         - GET /api/v1/accounts/:id/inboxes/:id/assignable_agents
         - 支持参数: inbox_ids[], skill, availability
  S4-3: round_robin_service.go — 完善自动分配策略
         - 与现有autoassignment包联动
         - RoundRobin + LowestLoad策略完善
  S4-4: assignable_agent_test.go — 测试覆盖
```

#### Stream S5: Contact Merge级联更新 [预计5天]

```
依赖: contact_service, 7+个repository
参考: Chatwoot contact_merge_action.rb (62行)

任务清单:
  S5-1: contact_merge_service.go — 完善级联逻辑
         - 7+表级联迁移:
           contact → conversation → message → label
           → inbox_member → csat → note → custom_attribute
         - 合并前冲突检测(同名/同邮箱)
         - 合并后清理(删除source contact,去重关联)
  S5-2: contact_merge_handler.go — 扩展API
         - 从78行薄壳→完整merge handler
         - POST /api/v1/accounts/:id/actions/contact_merges
         - 验证: source≠target, 两者存在, 权限检查
  S5-3: contact_merge_test.go — 级联完整性测试
         - 7表数据一致性验证
         - 合并后关联正确性验证
```

#### Stream S6: Working Hours营业时间 [预计3天]

```
依赖: model层, campaign包(现有片段)
参考: Chatwoot working_hour.rb (93行)

任务清单:
  S6-1: working_hour_service.go — 完善营业时间约束
         - WorkingHour CRUD (周一~周日, 每天多个时段)
         - 营业时间查询: isWithinWorkingHours()
         - 影响: autoassignment(非营业时不分配), SLA计算(暂停), campaign(营业时发送)
  S6-2: working_hour_handler.go — API端点
         - CRUD /api/v1/accounts/:id/inboxes/:id/working_hours
  S6-3: working_hour_test.go — 测试覆盖
```

### Wave 1 并行执行拓扑

```
    ┌── S1 (SLA追踪) ──┐
    │                   │
    ├── S2 (CSAT收集) ──┤
    │                   │   全部可同时启动
    ├── S3 (对话查找) ──┤   无交叉依赖
    │                   │
    ├── S4 (智能分配) ──┤
    │                   │
    ├── S5 (Contact级联) ─┤
    │                   │
    └── S6 (营业时间) ──┘

    S1-S6 完成后 → 进入 Wave 2
    预计总工期: max(7天) ≈ 7个工作日 (而非串行30天)
```

---

### Wave 2: P1功能补全 + 服务深化 (3-5周, 5个并行流)

#### Stream S7: Channel Provider发送层完善 [预计10天] ⚡ 最大量

```
依赖: 各channel子包, model
参考: Chatwoot 14个 send_on_*_service

任务清单:
  S7-1: WhatsApp发送层 (最简→最完整)
         - send_on_whatsapp_service.go (消息发送+模板+媒体)
         - WhatsApp Webhook完善(消息状态回调: sent/delivered/read)
  S7-2: Twilio SMS发送层
         - send_on_twilio_sms_service.go
         - SMS状态回调处理
  S7-3: Instagram发送层
         - send_on_instagram_service.go
         - Instagram消息类型处理
  S7-4: Email Channel发送层完善
         - SMTP发送+IMAP收取(替换goimap_stub)
         - 集成Go IMAP库(如go-imap)
  S7-5: 其他channel发送层
         - LINE/TikTok/Twitter/Facebook/Microsoft/Telegram
         - 每个channel: send+webhook+callback三层
```

#### Stream S8: 报表聚合完善 [预计7天]

```
依赖: model.ReportingEvent/ReportingEventsRollup (已编译)
参考: Chatwoot reporting_events: backfill_service(142行)+rollup_service(81行)+metric_registry

任务清单:
  S8-1: reporting_backfill_service.go — 事件回填
         - 定时任务: 补全缺失的ReportingEvent
  S8-2: reporting_rollup_service.go — 聚合计算
         - 日/周/月级Rollup计算
         - agent/account/conversation维度
  S8-3: reporting_metric_registry.go — 指标注册
         - 统计指标定义(消息数/响应时间/FRT/NRT等)
  S8-4: reporting_handler.go — 扩展报表API
         - 从56行薄壳→完整报表查询
         - 多维度+时间范围过滤
```

#### Stream S9: CRM + 通知订阅 + LLM Formatter [预计7天]

```
依赖: model层, service层
参考: Chatwoot crm(9services), notification_subscription(4文件), llm_formatter(5文件)

任务清单:
  S9-1: CRM集成 (LeadSquared)
         - crm_processor_service.go
         - crm_mapper_service.go
         - crm_client_service.go
  S9-2: Notification Subscription
         - notification_subscription_model.go
         - notification_subscription_service.go
         - notification_subscription_handler.go
  S9-3: LLM Formatter完善
         - conversation_formatter.go
         - article_formatter.go
         - contact_formatter.go
         - text_formatter.go
         - (现有llm_response_parser保留为default formatter)
```

#### Stream S10: 薄壳Handler丰富化 [预计10天]

```
依赖: 对应的service/model
以下handler需要从薄壳(<100行)扩展到完整实现:

  最薄(需最大扩展):
  - assignable_agent_handler (76行) → S4已覆盖
  - contact_merge_handler (78行) → S5已覆盖
  - reporting_event_handler (56行) → S8已覆盖
  - delivery_status_handler (51行) → 需Twilio回调联动
  - captain_assistant_response_handler (46行) → 需扩展
  - captain_bulk_action_handler (62行) → 需扩展

  中等扩展:
  - push_subscription_handler (89行) → web push+FCM/APNs
  - inbox_limit_handler (88行) → 容量限制+溢出策略
  - inbox_csat_template_handler (95行) → 模板CRUD+自定义问题
  - audit_handler (82行) → 完善审计日志查询
  - conversation_participant_handler → 自动分配+负载均衡联动
  - draft_message_handler → 实时编辑+多agent协作
  - note_handler → 关联conversation+contact+company
```

#### Stream S11: 数据导入 + 邮件模板 [预计5天]

```
依赖: model.DataImport/EmailTemplate (W0激活后)
参考: Chatwoot data_import (35行model) + email_template

任务清单:
  S11-1: data_import_service.go — 批量导入联系人
         - CSV解析+验证+批量创建
         - 导入进度跟踪+错误报告
  S11-2: email_template_service.go — 件模板系统
         - DB resolver: 模板查找+变量替换
         - 通知邮件模板CRUD
  S11-3: data_import_handler.go + email_template_handler.go
```

### Wave 2 并行执行拓扑

```
    ┌── S7 (Channel发送层) ──┐  ← 最大的并行流,10天
    │                         │
    ├── S8 (报表聚合) ────────┤
    │                         │  可同时启动
    ├── S9 (CRM+通知+LLM) ───┤  无交叉依赖
    │                         │
    ├── S10 (薄壳Handler) ────┤  ← 部分依赖S7/S8/S9完成
    │                         │
    └── S11 (数据导入+模板) ──┘

    S10的前6项已在Wave 1(S4/S5/S8)覆盖
    S10其余项可与S7-S9并行,部分需等S7完成
    预计总工期: max(10天) ≈ 10个工作日 (而非串行40天)
```

---

### Wave 3: P2体验完善 + 1:1深度验证 (2-3周, 3个并行流)

#### Stream S12: P2功能实现 [预计5天]

```
任务清单:
  S12-1: message_reaction_model.go + handler/service (表情回复)
  S12-2: instance_status_handler.go (实例状态API)
  S12-3: onboarding_handler.go (新用户引导)
  S12-4: liquid_template_engine.go (Campaign模板引擎)
         - 或集成Go模板库替代Liquid
  S12-5: platform_banner_handler.go (平台公告横幅)
  S12-6: super_admin_handler.go (完整权限管理)
```

#### Stream S13: 1:1逻辑深度验证 [预计10天] ⚡ 最关键

```
对每个"已实现"模块做逐项1:1逻辑对比:
  S13-1: Conversation — 验证排序/分页/过滤/状态转换与Chatwoot完全一致
  S13-2: Message — 验证消息类型/搜索/附件/推送与Chatwoot一致
  S13-3: Inbox — 验证channel类型/成员管理/容量限制与Chatwoot一致
  S13-4: Auth — 验证SSO/MFA/权限检查与Chatwoot一致
  S13-5: Automation — 验证规则触发/动作执行/宏执行与Chatwoot一致
  S13-6: Contact — 验证搜索/合并/标签/自定义属性与Chatwoot一致
  每个验证项产出: 1:1_diff_report.md (差异清单)
```

#### Stream S14: 测试覆盖提升 [持续进行]

```
目标: 272 → 834+ test files
  S14-1: Model层测试: 6 → 63 (最优先)
  S14-2: Service层测试: 48 → 132
  S14-3: Handler层测试: 100 → 138
  S14-4: Repository层测试: 55 → 保持(GoChat独有优势)

策略: 每个Wave的Stream产出代码时，同时产出测试
      S14不是独立流,而是附加在每个Stream的任务清单中
```

---

### Wave 4: 持续优化 (与Wave 2-3并行开始)

```
  S15: 服务覆盖率提升: 25% → 80%
       - 补全每个Chatwoot service域的Go等效service
       - 优先: WhatsApp(3%→80%), Conversation(7%→80%), Message(8%→80%)
  
  S16: 性能优化
       - Repository层查询优化(N+1问题, 批量查询)
       - WebSocket推送优化
       - Cache策略(Redis缓存热数据)

  S17: 文档完善
       - API文档(Swagger/OpenAPI)
       - 架构文档更新
       - 部署文档
```

---

## 四、执行节奏总览

```
Week 1-2:   W0 (1-2天) → Wave 1 全6流并行启动
Week 2-3:   Wave 1 完成 → Wave 2 全5流并行启动
Week 4-7:   Wave 2 完成 → Wave 3 全3流并行启动
Week 8+:    Wave 3 完成 → Wave 4 持续优化

关键路径(最长): 
  W0(2天) → S3(7天) → S7(10天) → S13(10天) = 约29天
  vs 串行执行: W0+S1+S2+S3+S4+S5+S6+S7+S8+S9+S10+S11+S12+S13 = 约85天
  并行加速比: 85/29 ≈ 3x
```

---

## 五、并行开发组织建议

### 5.1 Worker分配方案

| Worker角色 | 负责Stream | 技能要求 |
|-----------|-----------|---------|
| Worker-A (核心) | S1 SLA + S2 CSAT + S6 WorkingHours | Go/Gin + GORM + model层 |
| Worker-B (对话) | S3 ConversationFinder + S4 AssignableAgent | Go + 搜索/查询逻辑 |
| Worker-C (数据) | S5 ContactMerge + S11 DataImport/Email | Go + 数据迁移逻辑 |
| Worker-D (Channel) | S7 Channel发送层 | Go + HTTP/API + 各Channel协议 |
| Worker-E (报表) | S8 Reporting + S9 CRM/Notification | Go + 统计计算 |
| Worker-F (Handler) | S10 薄壳丰富化 | Go + Handler模式 |
| Worker-G (验证) | S13 1:1深度验证 | 对比分析 + 测试编写 |
| Worker-H (测试) | S14 测试覆盖(附加到各Stream) | Go testing |

### 5.2 分支策略

```
main
  ├── wave0/stub-activation          (W0前置)
  ├── wave1/s1-sla-tracking          (S1)
  ├── wave1/s2-csat-collection       (S2)
  ├── wave1/s3-conversation-finder   (S3)
  ├── wave1/s4-assignable-agent      (S4)
  ├── wave1/s5-contact-merge         (S5)
  ├── wave1/s6-working-hours         (S6)
  ├── wave2/s7-channel-send          (S7)
  ├── wave2/s8-reporting             (S8)
  ... etc

每个Stream独立分支,完成后merge到main
冲突解决策略: model层改动先merge(W0), 业务层后merge(Wave 1-3)
```

### 5.3 每日同步点

```
1. W0完成后: 所有.go.txt激活, go build通过 → 触发Wave 1
2. Wave 1每日: 各Stream汇报进度, 检查model层是否有交叉改动
3. Wave 1完成后: P0功能可用 → 触发Wave 2
4. Wave 2完成后: P1功能可用 → 触发Wave 3
5. Wave 3完成后: 1:1验证报告 → 确认达标或迭代
```

---

## 六、风险与缓解

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 10个stub激活后编译错误 | 阻塞全部Wave 1 | W0中逐个激活+编译验证, 不批量 |
| model层交叉改动 | Stream间merge冲突 | model层改动集中在W0, 后续只加不改 |
| ConversationFinder 7种过滤语义不一致 | S3产出不达标 | 参考Chatwoot conversation_finder.rb逐行对比 |
| Channel发送层各协议差异大 | S7工期超预期 | 按channel优先级分批(WhatsApp→Twilio→其余) |
| 测试覆盖跟不上业务开发 | 回归风险 | S14附加在每个Stream, 不独立延后 |
| S13 1:1验证发现深度差距 | 需要额外迭代 | Wave 3预留buffer, 验证问题回流到对应Stream |

---

## 七、验证标准

每个Stream完成时的验收标准:

1. **编译**: `go build ./...` 通过
2. **测试**: Stream内所有新增代码有对应test文件, `go test ./internal/...` 通过
3. **1:1对比**: handler/service的行为与Chatwoot对应controller/service等价:
   - 请求参数相同
   - 响应JSON结构相同(字段名/嵌套/null处理)
   - 错误响应码相同
   - 副作用(事件触发/自动分配)相同
   - 授权检查范围相同
4. **AutoMigrate**: 新增model注册到app.go的autoMigrate列表
5. **无.go.txt残留**: 激活的stub删除对应的.go.txt文件

---

## 八、Chatwoot参考文件索引 (每个Stream的对照基准)

| Stream | Chatwoot参考文件 | 行数 |
|--------|----------------|------|
| S1 | enterprise/app/controllers/applied_slas_controller.rb | 70 |
| S1 | enterprise/app/services/sla/evaluate_applied_sla_service.rb | 107 |
| S1 | enterprise/app/models/applied_sla.rb | 77 |
| S2 | app/controllers/api/v1/accounts/csat_survey_responses_controller.rb | 54 |
| S3 | app/finders/conversation_finder.rb | 217 |
| S3 | app/services/mailbox/conversation_finder.rb | ~100 |
| S3 | app/services/mailbox/conversation_finder_strategies/ (5文件) | ~150 |
| S4 | app/controllers/api/v1/accounts/assignable_agents_controller.rb | 24 |
| S4 | app/services/auto_assignment/ (5个service) | ~200 |
| S5 | app/actions/contact_merge_action.rb | 62 |
| S6 | app/models/working_hour.rb | 93 |
| S7 | app/services/whatsapp/ (31个service) | ~3000 |
| S8 | app/services/reporting_events/ (4个service) | ~400 |
| S9 | app/services/crm/ (9个service) | ~600 |
| S9 | app/services/notification/ (5个service) | ~300 |
| S11 | app/models/data_import.rb | 35 |
| S11 | app/services/email_templates/ | ~100 |

---

*计划版本: v1.0 | 总工期预估: 7-10周 (并行) vs 20-25周 (串行) | 加速比: ~3x*