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

# 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`：

```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 内添加：

```go
// 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 需求梳理产出物，基于代码审查修正了早期文档中的过时描述，反映项目渠道集成的真实当前状态。后续开发排期应以此文档为权威参考。*