gochat/docs/requirements/M07-channel-integration-consolidated.md

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

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

---

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

以下为早期渠道集成文档（已清理合并至本文档）中的过时描述，现已基于代码审查修正：

早期文档描述	真实实现状态	依据
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/product/06-design-channel-abstraction.md 和 docs/tracking/01-chatwoot-parity-tracker.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/product/06-design-channel-abstraction.md	Provider 接口设计文档
产品需求文档	docs/product/01-product-requirements.md	M2 收件箱与渠道需求
M2 需求	docs/requirements/M02-inbox-and-channels.md	Inbox + Channel 详细需求
Chatwoot parity 跟踪	docs/tracking/01-chatwoot-parity-tracker.md	当前对齐进度
Provider 接口核心	internal/channel/provider.go	Provider/IncomingMessage/OutgoingMessage 定义
Provider 注册表	internal/channel/registry.go	Register()/GetProvider() 实现
Bootstrap 接线	internal/app/bootstrap.go	依赖注入和 Provider 注册
路由配置	internal/router/router.go	所有已注册路由

---

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