Files

T

rogee aeddedf2a3 Reorganize repo: backend/, deploy/, docs/ layout + AGENTS.md

Restructure the monorepo into clear top-level directories:
- backend/: Go module root (cmd, internal, pkg, configs, migrations,
  docs/swagger, scripts, tests, go.mod, Makefile, .air.toml)
- deploy/: Docker (Dockerfile, docker-compose*), quickstart, fluentd
- docs/: project documentation + reports/ (moved from repo root)
- AGENTS.md: new AI coding-agent guide at repo root

Update all references to the new layout:
- Dockerfile: COPY backend/go.mod, COPY backend/ (context = repo root)
- docker-compose files: context ../.., dockerfile deploy/docker/Dockerfile,
  env_file ../../.env, volume mounts ../../backend:/app
- deploy/quickstart/compose.yaml: dockerfile deploy/docker/Dockerfile
- CI: working-directory: backend for go commands, file deploy/docker/Dockerfile,
  coverage path backend/coverage.out, health_check backend/scripts/
- backend/Makefile: docker target uses -f ../deploy/docker/Dockerfile ../
- README: architecture tree, quickstart, config paths updated

Move root stray scripts (rename_models.*, run_m11_tests.sh, verify_build.sh,
gorm_bool_main.go) to backend/scripts/legacy/. All moves via git mv to
preserve history. Build, vet, SQLite tests, and docker compose config verified.

2026-07-07 14:44:12 +08:00

22 KiB

Raw Blame History

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完成时的验收标准:

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

22 KiB Raw Blame History