chore: complete Shangwutong connector integration

docs/runbooks/shangwutong-connector.md

@@ -1,5 +1,16 @@
 # 商务通 Connector 生产运行手册
 
+
+## 架构说明
+
+Shangwutong 是刻意采用的外部 Connector 产品形态，不是内嵌在 GoChat 主进程里的标准 `ChannelProvider` 插件。GoChat 侧负责 Inbox 配置、凭据下发、durable webhook 投递、消息导入与状态回写；`channels/shangwutong` 进程负责登录商务通、维护会话、轮询/映射真实协议事件、执行出站发送。这样做的原因是商务通协议需要长连接/心跳/本地游标/不确定投递消歧，独立进程可以隔离故障域、持久化协议状态，并避免把站点密码与会话状态塞进主 API 进程。
+
+因此，Shangwutong 不需要实现 `internal/channel.ChannelProvider` 的 14 方法接口，也不注册 `/webhooks/shangwutong/*` 平台回调路由。其稳定契约是：
+
+- GoChat → Connector：`/webhooks/gochat/v1`，使用 `X-Chatwoot-Timestamp` + `X-Chatwoot-Signature` HMAC 签名。
+- Connector → GoChat：`/api/v1/connector/shangwutong/*` 配置/状态 API，以及允许列表中的 account-scoped message/conversation API。
+- GoChat Inbox 类型仍序列化为 `Channel::Shangwutong`，前端按 API-like inbox 展示和配置。
+
 ## 1. 上线前检查
 
 1. GoChat 已部署 `Channel::Shangwutong` migration、Connector service principal、配置/状态 API 和 durable webhook worker。