gochat/docs/CHANNEL_INTEGRATION_PRIORITIES.md

GoChat 渠道集成需求梳理与优先级排序

⚠️ 过时文档警告 — 本文档中的部分描述已过时（如 InboxHandler 为 stub、Webhook 路由不存在等），已基于 2026-05-25 的代码审查修正。
请以 docs/requirements/M7-channel-integration-consolidated.md 为权威参考，该文档反映了项目真实实现状态。

生成日期: 2026-05-24 任务: t_ffe7fa39 — 各渠道功能差距分析, 优先级排序, 实施计划

---

一、现状总览

1.1 已实现渠道（4个，可运行）

渠道	代码路径	行数	接口类型	实现状态	功能完整性
Web Widget	internal/channel/provider/web_widget.go + provider/	~400	ChannelProvider + PushProvider	✅ 完整	前端嵌入式聊天，HMAC验证，Redis推送，打字指示器，在线状态
Telegram	internal/channel/telegram/ (4文件)	~1,450	ChannelProvider	✅ 完整	Bot API集成，webhook注册，消息收发，附件支持
Email	internal/channel/email/ (8文件)	~1,754	ChannelProvider + PollingProvider	✅ 完整	IMAP轮询收信，SMTP发信，MIME解析，线程关联
Facebook Messenger	internal/channel/facebook/ (9文件)	~4,411	ChannelProvider + OAuthProvider	✅ 完整	Graph API，Page订阅，消息收发，附件上传，回执，thread control，OAuth token交换

1.2 已实现但仅注册的渠道（1个）

渠道	代码路径	行数	接口类型	实现状态	说明
Instagram DM	internal/channel/facebook/instagram_provider.go	~838	ChannelProvider + OAuthProvider	✅ 完整	与Facebook共享Graph API基础设施，通过init()注册到registry

1.3 已有模型定义但无 Provider 实现（5个）

渠道	模型文件	Provider代码	Chatwoot对等	说明
WhatsApp	internal/model/channel/whatsapp.go ✅	❌ 无	Channel::WhatsApp	模型有(phone_number_id, access_token, business_id)，缺360dialog API集成
Twilio SMS	internal/model/channel/twilio_sms.go.txt stub	❌ 无	Channel::TwilioSms	模型是stub(.txt)，需激活并实现
SMS (generic)	internal/model/channel/sms.go.txt stub	❌ 无	Chatwoot无对等	模型是stub，通用SMS provider
LINE	internal/model/channel/line.go.txt stub	❌ 无	Channel::Line	模型是stub，LINE Messaging API集成
API Channel	internal/model/channel/api.go.txt stub	❌ 无	Channel::Api	模型是stub，REST API通用接入

1.4 仅常量定义（无模型、无Provider）

渠道	ChannelType常量	模型	Provider	说明
Slack	ChannelSlack = "slack"	❌	❌	Chatwoot作为Integration而非Channel，但GoChat P2D设计将其归入ChannelType
TikTok	❌ 无常量	.txt stub有	❌	Chatwoot Enterprise功能，暂缓

1.5 完全缺失的渠道（Chatwoot有但GoChat未设计）

渠道	Chatwoot对等	GoChat状态	说明
Twitter/X DM	Channel::Twitter	❌ 完全缺失	Chatwoot曾支持但Twitter API变更后废弃，优先级极低
Google Business Messages	无（OAuth provider存在）	❌ 缺失	需Google OAuth集成
Microsoft Teams	无（OAuth provider存在）	❌ 缺失	需Microsoft OAuth集成

---

二、差距详细分析

2.1 渠道实现差距矩阵

渠道	模型	Provider	Webhook	OAuth	Polling	Push	Handler路由	配置管理	总体差距
Web Widget	✅	✅	✅	❌(不需要)	❌(不需要)	✅	✅(4路由)	✅	0% — 已完成
Telegram	✅	✅	✅	❌(不需要)	❌(不需要)	❌	✅(1 stub路由)	✅	10% — 缺PushProvider和handler路由
Email	✅	✅	✅(ActionMailbox)	❌(不需要)	✅	❌	❌	✅(IMAP/SMTP)	15% — 缺handler路由和PushProvider
Facebook	✅	✅	✅	✅	❌(不需要)	❌	❌	✅	20% — 缺handler路由和PushProvider
Instagram	✅	✅	✅(共享FB)	✅(共享FB)	❌(不需要)	❌	❌	✅	20% — 同Facebook
WhatsApp	✅模型	❌	❌	✅(需实现)	❌	❌	❌	❌	85% — 仅模型存在
Twilio SMS	stub	❌	❌	❌	❌	❌	❌	❌	95% — 仅stub模型
Twilio WhatsApp	❌	❌	❌	❌	❌	❌	❌	❌	100% — 完全缺失
LINE	stub	❌	❌	❌	❌	❌	❌	❌	95% — 仅stub模型
Slack	❌	❌	❌	✅(需实现)	❌	❌	❌	❌	100% — 完全缺失
API Channel	stub	❌	❌	❌(不需要)	❌	❌	❌	❌	95% — 仅stub模型
TikTok	stub	❌	❌	✅(需实现)	❌	❌	❌	❌	95% — 仅stub模型

2.2 跨渠道共性差距

🔴 Inbox Handler 全 Stub（影响所有渠道）

InboxHandler（45行）所有方法都是 placeholder/stub：

• List → 返回空列表硬编码
• Get → 返回 placeholder
• Create → 返回 placeholder
• Update → 501 Not Implemented
• Delete → 501 Not Implemented

这是所有渠道共享的入口问题 — 无论渠道多完整，用户都无法通过API管理Inbox。

🔴 渠道 OAuth 授权路由完全缺失

Chatwoot 有 7 条 OAuth 授权路由：

POST /api/v1/accounts/:id/instagram/authorization
POST /api/v1/accounts/:id/whatsapp/authorization
POST /api/v1/accounts/:id/tiktok/authorization
POST /api/v1/accounts/:id/twitter/authorization
POST /api/v1/accounts/:id/google/authorization
POST /api/v1/accounts/:id/microsoft/authorization
POST /api/v1/accounts/:id/notion/authorization

GoChat: 0 条路由 — Facebook/Instagram 的 OAuthProvider 代码完整，但无 API 入口让用户触发授权流程。

🔴 渠道特定配置路由缺失

Chatwoot 每个渠道都有独立的配置控制器（如 telegram_bots_controller, facebook_pages_controller），提供渠道特有的 CRUD 操作。GoChat 仅实现了 WebWidget 的 4 条配置路由，其余渠道全缺。

Chatwoot控制器	GoChat路由	缺失
telegram_bots_controller (create/update/destroy)	❌	3
facebook_pages_controller (create/destroy)	❌	2
whatsapp_controller (create/update)	❌	2
email_channels_controller (create)	❌	1

🟡 Webhook 路由仅有 Stub

当前 webhook 路由 webhookGroup.Any("/:channel_type/:identifier", webhookStub) 是一个通用 catch-all stub，没有按渠道分发到具体的 ChannelProvider webhook handler。Facebook/Telegram/Email 的 webhook_handler.go 已经写好，但未被路由接入。

🟡 Inbox Members 路由缺失

POST   /api/v1/accounts/:id/inbox_members
GET    /api/v1/accounts/:id/inbox_members/:inbox_id
DELETE /api/v1/accounts/:id/inbox_members   (collection)
PATCH  /api/v1/accounts/:id/inbox_members   (collection)

影响渠道坐席分配管理。

🟡 渠道 AgentBot 绑定缺失

Chatwoot 有 AgentBotInbox 绑定机制，GoChat 完全缺失 — 无法给特定 Inbox 绑定自动回复 Bot。

---

三、优先级排序

3.1 评估维度

维度	权重	说明
用户需求紧迫度	40%	市场需求、客户反馈、竞品对标
实现复杂度	25%	开发工时、技术难度、外部依赖
阻塞影响范围	20%	解决该差距后解锁的功能数量
商业价值	15%	对用户增长、付费转化的贡献

3.2 优先级排序结果

🔴 P0 — 必做（生产就绪阻塞项）

#	项目	工时预估	说明	阻塞影响
P0-1	Inbox Handler 真实实现	3天	将全 stub 的 5 个方法改为真实 CRUD（含渠道创建流程）	解锁所有渠道的 API 管理
P0-2	Webhook 路由接入	2天	将各渠道的 webhook_handler.go 接入 router，替换 stub	解锁 FB/Telegram/Email 消息接收
P0-3	渠道 OAuth 授权路由	2天	为 Facebook/Instagram/WhatsApp 添加 POST /authorization 路由	解锁 OAuth 渠道的配置入口
P0-4	渠道配置 CRUD 路由	3天	Telegram bots, Facebook pages, Email channels, WhatsApp 各渠道特有配置路由	解锁渠道配置管理

P0 合计: 10天

🟡 P1 — 重要（核心渠道补全）

#	项目	工时预估	说明	阻塞影响
P1-1	WhatsApp Provider 实现	5天	360dialog Cloud API 集成：模板消息、消息收发、状态回执、OAuth	第二大客户沟通渠道
P1-2	Telegram PushProvider	1天	补齐 typing indicator / online status 推送	增强用户体验
P1-3	Inbox Members 路由	2天	坐席-Inbox 绑定管理（4条路由）	解锁坐席分配
P1-4	渠道 AgentBot 绑定	2天	AgentBotInbox 绑定 + 事件监听	解锁渠道自动回复

P1 合计: 10天

🔵 P2 — 可迭代（扩展渠道）

#	项目	工时预估	说明	阻塞影响
P2-1	Twilio SMS Provider	4天	Twilio API 集成 + 模型从stub激活	企业短信需求
P2-2	LINE Provider	4天	LINE Messaging API + 模型激活	亚洲市场需求
P2-3	API Channel Provider	2天	REST API 通用接入（最简实现）	第三方系统接入
P2-4	Twilio WhatsApp Provider	3天	基于 Twilio SMS 扩展	WhatsApp 替代接入路径

P2 合计: 13天

⚪ P3 — 暂缓（低优先级/高风险）

#	项目	工时预估	说明
P3-1	Slack 集成	5天	Chatwoot 作为 IntegrationHook 而非 Channel；需重新评估是否归入 channel 层
P3-2	TikTok 渠道	4天	Enterprise 功能，OAuth复杂，API不稳定
P3-3	Twitter/X 渠道	3天	Twitter API v2 DM 功能受限，Chatwoot 已废弃
P3-4	Google Business Messages	5天	需 Google OAuth + Business Messages API
P3-5	Microsoft Teams	5天	需 Microsoft OAuth + Teams Bot Framework

---

四、实施计划

Phase 1: 渠道基础设施修复（P0，10天）

目标: 让已有渠道(Facebook/Instagram/Telegram/Email/WebWidget)可通过API完整管理

Week 1 (5天):

1. InboxHandler 真实实现 (3天)

   • List: 调用 InboxService.ListByAccount → 真实数据返回
   • Get: 调用 InboxService.GetByID → 含 channel_config 详情
   • Create: 调用 InboxService.Create → 含渠道类型分发（按 ChannelProvider.OnCreate）
   • Update: 调用 InboxService.Update → 含配置校验（按 ChannelProvider.ValidateConfig）
   • Delete: 调用 InboxService.Delete → 含 OnDestroy 生命周期回调

2. Webhook 路由接入 (2天)

   • 替换 webhookGroup.Any("/:channel_type/:identifier", webhookStub) 为渠道分发逻辑
   • Telegram: POST /webhooks/telegram/{bot_token} → telegram.WebhookHandler
   • Facebook: GET+POST /webhooks/facebook/{page_id} → facebook.WebhookHandler (GET用于验证)
   • Email: ActionMailbox 或 webhook → email.WebhookHandler
   • 保留 fallback 通用路由给未实现的渠道

Week 2 (5天):

3. 渠道 OAuth 授权路由 (2天)

   • POST /api/v1/accounts/:id/facebook/authorization → FB OAuthProvider.BuildAuthURL
   • POST /api/v1/accounts/:id/instagram/authorization → IG OAuthProvider.BuildAuthURL
   • POST /api/v1/accounts/:id/whatsapp/authorization → (未来 WhatsApp OAuth)
   • OAuth callback route: GET /api/v1/accounts/:id/:channel_type/callback → ExchangeToken

4. 渠道配置 CRUD 路由 (3天)

   • Telegram: POST/PUT/DELETE /api/v1/accounts/:id/channels/telegram_bots
   • Facebook: POST/DELETE /api/v1/accounts/:id/channels/facebook_pages
   • Email: POST /api/v1/accounts/:id/channels/email (IMAP/SMTP配置)
   • WhatsApp: POST/PUT /api/v1/accounts/:id/channels/whatsapp (配置placeholder)

Phase 2: 核心渠道扩展（P1，10天）

目标: WhatsApp上线，坐席管理补全

Week 3-4:

5. WhatsApp Provider 实现 (5天)

   • 模型激活: whatsapp.go 已有，补全字段
   • WhatsApp Cloud API: 消息收发、模板消息、状态回执
   • OAuthProvider: 360dialog token 管理
   • WebhookHandler: 状态回执 webhook
   • 渠道配置路由

6. Telegram PushProvider (1天)

   • PushTypingOn: 发送 typing indicator (chat action)
   • PushOnlineStatus: 无直接 Telegram API → 通过 Bot 状态模拟

7. Inbox Members 路由 (2天)

   • POST/GET/DELETE/PATCH /api/v1/accounts/:id/inbox_members
   • 坐席-Inbox 多对多绑定

8. AgentBot Inbox 绑定 (2天)

   • AgentBotInbox 模型 + Repository
   • POST/DELETE /api/v1/accounts/:id/agent_bots/:id/inboxes
   • 事件监听: conversation.created → agent bot 自动回复

Phase 3: 扩展渠道（P2，13天）

目标: SMS/LINE/API Channel上线，覆盖更多客户渠道

9. Twilio SMS Provider (4天)
10. LINE Provider (4天)
11. API Channel Provider (2天)
12. Twilio WhatsApp Provider (3天)

---

五、风险与依赖

风险	影响	缓解措施
WhatsApp 360dialog API 申请门槛	延误 P1-1	先用 Meta Cloud API 实现替代路径
Facebook Graph API 版本变更	影响 FB/IG 稳定性	使用稳定版 API (v18.0+)，抽象版本依赖
Twilio 费用门槛	延误 P2-1/P2-4	提供测试账号支持
LINE 开发者注册需日本企业资质	延误 P2-2	评估是否用第三方 LINE Bot SDK 代理
OAuth token 刷新机制未接入调度器	所有 OAuth 渠道风险	P0-3 需同步实现 OAuthTokenRefresher 定时刷新

---

六、关键文件索引

功能	GoChat文件	状态
ChannelProvider 接口	internal/channel/provider.go	✅ 完整
ChannelRegistry	internal/channel/registry.go	✅ 完整（缺OAuth/Polling/Push子注册表）
WebWidget Provider	internal/channel/provider/web_widget.go	✅ 完整
Telegram Provider	internal/channel/provider/telegram.go + internal/channel/telegram/	✅ 完整
Email Provider	internal/channel/provider/email.go + internal/channel/email/	✅ 完整
Facebook Provider	internal/channel/facebook/provider.go	✅ 完整
Instagram Provider	internal/channel/facebook/instagram_provider.go	✅ 完整
WhatsApp 模型	internal/model/channel/whatsapp.go	✅ 仅模型
Twilio SMS 模型	internal/model/channel/twilio_sms.go.txt	⚠️ Stub
LINE 模型	internal/model/channel/line.go.txt	⚠️ Stub
API Channel 模型	internal/model/channel/api.go.txt	⚠️ Stub
Inbox Handler	internal/handler/api/v1/inbox_handler.go	❌ 全 stub
Webhook Handler	internal/channel/webhook.go	✅ 但路由未接入
OAuth Token Refresher	P2D 设计有, 代码缺失	❌ 缺实现
渠道配置路由	仅 WebWidget 有	❌ 其他渠道缺