rogee/gochat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b36cf079dbcf045ccd67fca0fa471e7100b1ade4
gochat/docs/requirements/M7-channel-integration-consolidated.md
T
Rogee 8ac150bc7b second commit
2026-06-04 15:44:48 +08:00

14 KiB
Raw Blame History

M7: PM渠道集成需求梳理 — 综合需求文档

文档版本: v1.0
创建日期: 2026-05-25
目的: 整合项目现有文档中的渠道集成需求，以当前代码真实实现状态为基准修正过时信息，输出一份可用于后续开发排期的权威参考

一、现状勘误：早期文档中的过时描述

以下为 docs/CHANNEL_INTEGRATION_PRIORITIES.md 及相关早期文档中的过时描述，现已基于代码审查修正：

早期文档描述 真实实现状态 依据
InboxHandler 为 stub 已有完整 CRUD 实现 — List/Create/Get/Update/Delete + WebWidget 创建/配置/删除 internal/handler/api/v1/inbox_handler.go 约360行
Webhook 路由尚未实现 已存在真实路由 — Facebook (GET+POST)、Instagram (POST)、Telegram (POST)、WhatsApp (GET+POST) internal/router/router.go webhookGroup
InboxMember 路由不存在 已存在 — List/Add/Update/UpdateMultiple/Remove 5个端点 router.go inboxes/:inbox_id/members
WhatsApp 为 stub 完整实现 — provider + service + webhook_handler + pipeline + media + repository internal/channel/whatsapp/ 多文件
Facebook 无 OAuth 流程 FacebookChannelHandler 有完整 OAuth — Authorization(GET) + OAuthCallback(POST) + CreateFacebookPage(POST) + DeleteFacebookPage(DELETE) + ReauthorizeFacebookPage(POST) internal/handler/api/v1/facebook_channel_handler.go 约360行
PushDelivery 不存在 PushProvider 接口已定义且有实现 internal/service/push_delivery_service.go

未修正的差距（真实存在的 gap）

Gap 说明
FacebookChannelHandler 路由未接线 5个 OAuth 端点已实现但 未在 router.go 中注册路由，无法通过 API 调用
Email channel 仅骨架 只有 pipeline.go 骨架，无 provider/service/webhook_handler
Twilio SMS 仅有 stub 模型 internal/model/channel/twilio_sms.go.txt (.go.txt 后缀说明未编译)
LINE 仅有 stub 模型 internal/model/channel/line.go.txt (.go.txt 后缀)
API channel 仅有 stub 模型 internal/model/channel/api.go.txt (.go.txt 后缀)
Instagram Provider 为空壳 internal/channel/provider/instagram.go 仅729行注释/接口声明

二、渠道架构概览

2.1 Provider 抽象层（核心接口）

定义于 internal/channel/provider.go：

type Provider interface {
    Name() string
    ChannelType() string
    ProcessIncoming(ctx context.Context, rawPayload []byte) (*IncomingMessage, error)
    SendOutgoing(ctx context.Context, msg *OutgoingMessage) error
    ValidateConfig(config json.RawMessage) error
    BuildAuthURL(state string) string
    ExchangeToken(code string) (*TokenResult, error)
}

注册机制: channel.Register(provider) — 全局注册表，重复注册返回 error
接线机制: internal/app/bootstrap.go (194-324行) 按顺序注册 fbProvider → igProvider → tgProvider → waProvider（含 service/repo/pipeline）

2.2 Inbox Config 模型

Inbox 模型的 ChannelConfig 字段为 JSON text，各渠道有专属 config 结构：

渠道类型 Config 结构体 文件位置
Web Widget WebWidgetConfig model/channel/
Telegram TelegramInboxConfig model/channel/
Instagram InstagramInboxConfig model/channel/
WhatsApp WhatsAppInboxConfig model/channel/
Facebook FacebookInboxConfig model/channel/
Email 无专属结构 —
Twilio SMS stub (.go.txt) model/channel/twilio_sms.go.txt
LINE stub (.go.txt) model/channel/line.go.txt
API stub (.go.txt) model/channel/api.go.txt

三、各渠道实现状态详评

3.1 WhatsApp — 完整实现 ★★★★★

实现程度: 生产级

模块 文件 状态
Provider internal/channel/whatsapp/provider.go (21,878 chars) 完整
Service internal/channel/whatsapp/service.go (21,783 chars) 完整
Webhook Handler internal/channel/whatsapp/webhook_handler.go (2,578 chars) 完整
Pipeline internal/channel/whatsapp/pipeline.go 完整
Media internal/channel/whatsapp/media.go 完整
Repository internal/channel/whatsapp/repository.go 完整
Model internal/model/channel/whatsapp.go (6,650 chars) 完整
Webhook Route GET + POST /webhooks/whatsapp/:phone_number_id 已接线
Bootstrap 注册 ✅ 已接线

能力: 收发消息、webhook 验证、media 下载/上传、pipeline 处理链

3.2 Facebook — OAuth 完整但路由未接线 ★★★☆☆

实现程度: OAuth 流程完整，但 API 端点不可达

模块 文件 状态
Provider internal/channel/facebook/provider.go (4,009 chars) 基础实现
FacebookChannelHandler internal/handler/api/v1/facebook_channel_handler.go (~360行) 完整 OAuth
Webhook Route GET + POST /webhooks/facebook/:page_id 已接线
Bootstrap 注册 ✅ fbProvider 已接线
API 路由 未在 router.go 注册 ❌ 不可达

FacebookChannelHandler 端点（已实现但未接线）:

方法 路径（应注册为） 功能
GET /api/v1/accounts/:id/facebook/authorization 获取 FB OAuth 授权 URL
POST /api/v1/accounts/:id/facebook/oauth_callback FB OAuth 回调
POST /api/v1/accounts/:id/facebook/pages 创建 FB Page Inbox
DELETE /api/v1/accounts/:id/facebook/pages/:page_id 删除 FB Page Inbox
POST /api/v1/accounts/:id/facebook/pages/:page_id/reauthorize 重新授权 FB Page

关键差距: handler 已写完但路由缺失，开发者无法通过 API 调用任何 OAuth 功能

3.3 Telegram — 基础实现 ★★★☆☆

模块 状态
Provider internal/channel/provider/telegram.go — 需确认实现深度
Webhook Route POST /webhooks/telegram/:bot_token — 已接线
Bootstrap 注册 ✅ tgProvider — 已接线
Bot 创建 API 待确认

3.4 Instagram — 空壳 ★☆☆☆☆

模块 状态
Provider internal/channel/provider/instagram.go (729 chars) — 仅声明/注释
Webhook Route POST /webhooks/instagram/:page_id — 路由已接线但 handler 为 stub
Bootstrap 注册 ✅ igProvider — 已注册但无实际逻辑

3.5 Web Widget — 完整实现 ★★★★★

模块 状态
Inbox CRUD 完整 — Create/Get/Update/Delete via InboxHandler
WebWidget 专属 CreateWebWidgetInbox / GetConfig / UpdateConfig / DeleteWebWidgetInbox
InboxMember 5个端点全部已接线
Route /api/v1/accounts/:id/inboxes/web_widget 等 — 已接线

3.6 Email — 仅骨架 ★☆☆☆☆

模块 状态
Pipeline internal/channel/email/pipeline.go — 骨架
Provider 无
Service 无
Webhook 无
Model 无专属 config 结构

3.7 Twilio SMS / LINE / API — Stub 模型 ★☆☆☆☆

均为 .go.txt 后缀的 stub 文件，未参与编译：

  • internal/model/channel/twilio_sms.go.txt
  • internal/model/channel/line.go.txt
  • internal/model/channel/api.go.txt

无 Provider/Service/Webhook/Route 实现。

四、Chatwoot 渠道功能对比

基于 docs/comparison/Gochat-vs-Chatwoot-Full-Comparison.md 和 docs/architecture/P2D-渠道抽象层设计.md 的分析：

4.1 Chatwoot 已支持的渠道 vs GoChat 状态

渠道 Chatwoot GoChat 差距
Web Widget ✅ 完整 ✅ 完整 无差距
Facebook ✅ 完整（OAuth + Page 管理 + 收发消息） ⚠️ OAuth 已写但路由未接线 需接线 5 个 API 端点
WhatsApp (Cloud API) ✅ 完整 ✅ 完整 无差距
Telegram ✅ 完整（Bot 创建 + 收发） ⚠️ 基础实现 需补全 Bot 创建 API
Instagram ✅ 完整 ❌ 空壳 需从零实现
Email (IMAP/SMTP) ✅ 完整 ❌ 仅骨架 需从零实现
Twilio SMS ✅ 完整 ❌ Stub 模型 需从零实现
LINE ✅ 完整 ❌ Stub 模型 需从零实现
API Channel ✅ 完整 ❌ Stub 模型 需从零实现
Slack ✅ 完整 ❌ 无实现 Chatwoot 独有

4.2 Chatwoot 的渠道管理功能（GoChat 差距）

Chatwoot 功能 GoChat 状态
渠道 OAuth 授权流程（FB/IG/WA） FB handler 存在但未接线；WA 已完整
Inbox 创建/更新/删除 已完整
Agent 分配（InboxMember） 已完整
自动分配规则 ❌ 未实现
渠道优先级/Business Hours ❌ 未实现
联系人跨渠道合并 ❌ 未实现
草稿/已读/未读状态 ❌ 待确认
文件附件（跨渠道） WA 有 media 处理，其他渠道待确认
消息模板 ❌ 未实现
CSAT 满意度调查 ❌ 未实现

五、优先级排序建议

基于以下维度综合评分：

  • 业务价值: 客户需求紧迫度
  • 实现成本: 当前代码基础 + 工作量
  • Chatwoot 对齐: 与竞品功能差距
  • 技术依赖: 是否依赖前置工作

P0 — 立即修复（阻塞性 Gap）

# 项 原因 预估工作量
P0-1 Facebook OAuth API 路由接线 Handler 已写完，仅缺路由注册，修复后 FB 渠道可立即使用 0.5天

P1 — 近期实现（高业务价值 + 低成本）

# 项 原因 预估工作量
P1-1 Telegram Bot 创建/管理 API Webhook 已有，补全 Bot 注册流程即可上线 2-3天
P1-2 Instagram Provider 完整实现 Webhook 路由已接线，需补 provider/service/handler 5-7天
P1-3 Email 渠道（IMAP/SMTP） 企业场景核心需求，Chatwoot 标配 7-10天

P2 — 中期实现（中业务价值 + 中成本）

# 项 原因 预估工作量
P2-1 Twilio SMS Provider 国际客户常用，但可后置 5-7天
P2-2 LINE Provider 日本/东南亚市场专用 5-7天
P2-3 API Channel 开放 API 对接第三方系统 3-5天
P2-4 自动分配规则 Chatwoot 标配，提升运营效率 3-5天

P3 — 远期实现（低紧迫度或高成本）

# 项 原因 预估工作量
P3-1 联系人跨渠道合并 复杂度高，依赖统一联系人模型 7-10天
P3-2 CSAT 满意度调查 增值功能，非核心 3-5天
P3-3 消息模板 WA/FB 营销场景增值 5-7天
P3-4 Slack 渠道 Chatwoot 有但国内场景低频 7-10天

六、技术实现路线

6.1 新渠道接入标准流程

基于 WhatsApp 完整实现提炼的接入模板：

1. 定义 Channel Config 模型 (internal/model/channel/<channel>.go)
2. 实现 Provider 接口 (internal/channel/<channel>/provider.go)
   - Name(), ChannelType(), ProcessIncoming(), SendOutgoing()
   - ValidateConfig(), BuildAuthURL(), ExchangeToken()
3. 实现 Service 层 (internal/channel/<channel>/service.go)
4. 实现 Webhook Handler (internal/channel/<channel>/webhook_handler.go)
5. 实现 Pipeline 处理链 (internal/channel/<channel>/pipeline.go)
6. 实现 Repository (internal/channel/<channel>/repository.go)
7. 注册 Webhook 路由 (internal/router/router.go — webhookGroup)
8. 注册管理 API 路由 (internal/router/router.go — accounts/:id/inboxes)
9. Bootstrap 注册 Provider (internal/app/bootstrap.go)

6.2 P0-1 修复方案：Facebook OAuth 路由接线

在 internal/router/router.go 的 accounts Group 内添加：

// Facebook channel management routes
fbChannel := accountScoped.Group("/facebook")
{
    fbChannel.GET("/authorization", h.FacebookChannel.Authorization)
    fbChannel.POST("/oauth_callback", h.FacebookChannel.OAuthCallback)
    fbChannel.POST("/pages", h.FacebookChannel.CreateFacebookPage)
    fbChannel.DELETE("/pages/:page_id", h.FacebookChannel.DeleteFacebookPage)
    fbChannel.POST("/pages/:page_id/reauthorize", h.FacebookChannel.ReauthorizeFacebookPage)
}

同时确保 FacebookChannelHandler 已在 handler 依赖注入中初始化。

七、风险与注意事项

7.1 技术风险

风险 说明 缓解措施
Provider 注册冲突 channel.Register() 不允许重复注册 开发时注意注册顺序和条件
ChannelConfig JSON 解析 各渠道 config 结构差异大 ValidateConfig() 必须严格校验
Webhook 验证机制 FB/WA 使用 GET 验证 + POST 接收 参考 WA webhook_handler 已有模式
OAuth Token 存储 FB/WA OAuth token 需持久化 参考 WhatsApp service 的 token 管理

7.2 优先级调整因素

  • 国内市场优先: LINE/Twilio SMS 可降优先级，微信/钉钉可考虑替代
  • 企业客户驱动: Email 和 API Channel 需根据客户签约排期
  • 技术债务: stub 文件 (.go.txt) 需统一清理或正式纳入编译

八、参考资料索引

文档 路径 内容
渠道优先级排序（需修正） docs/CHANNEL_INTEGRATION_PRIORITIES.md 早期评估，含多处过时描述
渠道抽象层设计 docs/architecture/P2D-渠道抽象层设计.md Provider 接口设计文档
产品需求文档 docs/PRD.md M2 收件箱与渠道需求
M2 需求 docs/requirements/M2-inbox-and-channels.md Inbox + Channel 详细需求
Chatwoot 对比 docs/comparison/Gochat-vs-Chatwoot-Full-Comparison.md 竞品功能对比
路由差距分析 docs/ROUTE_GAP_ANALYSIS.md API 路由差距（含过时描述需修正）
Provider 接口核心 internal/channel/provider.go Provider/IncomingMessage/OutgoingMessage 定义
Provider 注册表 internal/channel/registry.go Register()/GetProvider() 实现
Bootstrap 接线 internal/app/bootstrap.go (194-324行) 依赖注入和 Provider 注册
路由配置 internal/router/router.go 所有已注册路由

本文档为 M7 需求梳理产出物，基于代码审查修正了早期文档中的过时描述，反映项目渠道集成的真实当前状态。后续开发排期应以此文档为权威参考。

Reference in New Issue View Git Blame Copy Permalink