# Xiaji-Go 多平台渠道配置与回调部署说明

## 已支持平台
- 官方 QQ Bot（qqbot_official）
- Telegram Bot（telegram）
- 飞书 Bot（feishu）

## 配置优先级
- 启动时：`数据库 channel_configs` > `config.yaml`
- 建议使用后台页面维护渠道配置：`/channels`

## 后台入口
- 渠道配置页：`/channels`
- 渠道 API：
  - `GET /api/v1/admin/channels`
  - `PATCH /api/v1/admin/channels/:platform`
  - `POST /api/v1/admin/channels/:platform/test`
- 审计查询：`GET /api/v1/admin/audit`

## 回调地址
- 飞书 webhook: `POST /webhook/feishu`

### 飞书事件订阅配置
1. 在飞书开发者后台启用事件订阅
2. 请求网址填：`https://<你的域名>/webhook/feishu`
3. 订阅事件：`im.message.receive_v1`
4. 将 `verification_token`、`app_id`、`app_secret` 写入渠道 secrets JSON

## 渠道 secrets JSON 示例

### telegram
```json
{
  "token": "123456:ABCDEF"
}
```

### qqbot_official
```json
{
  "appid": "102857798",
  "secret": "xxxxxx"
}
```

### feishu
```json
{
  "app_id": "cli_xxx",
  "app_secret": "xxx",
  "verification_token": "xxx",
  "encrypt_key": "optional"
}
```

## 连接测试说明
- Telegram：调用 `getMe`
- QQ：调用 `getAppAccessToken`
- 飞书：调用 `tenant_access_token/internal`

测试成功会把渠道状态写成 `ok`，失败写成 `error`。

## 幂等去重
- 三平台入站统一落 `message_dedup`，避免重复处理：
  - telegram: `tg:<update_id>`
  - qqbot_official: `qq:<type>:<message_id>`
  - feishu: `event_id`（回退 message_id）

## 运行建议
- 对公网暴露前请加 HTTPS（飞书回调必需）
- 建议将管理后台放在内网或反代鉴权后访问
- 定期审计 `audit_logs` 里渠道配置修改记录