# 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 有 | ❌ 其他渠道缺 |