docs: design tianyiyun seedance channel

docs/superpowers/specs/2026-07-08-doubao-tianyiyun-channel-design.md

@@ -0,0 +1,184 @@
+# 天翼云 Seedance 渠道设计文档
+
+**日期**: 2026-07-08
+**状态**: 待用户审阅
+**方案**: A - 新增独立渠道类型 `DoubaoVideoCompatibleTianyiYun`
+
+---
+
+## 1. 背景与目标
+
+天翼云 Seedance 渠道提供与 Doubao/Seedance 类似的异步视频生成能力。截图中的上游 API 使用：
+
+- 提交任务: `POST https://ai.ctaigw.cn/v1/contents/generations/tasks`
+- 查询任务: `GET https://ai.ctaigw.cn/v1/contents/generations/tasks/{task_id}`
+- 鉴权: `Authorization: Bearer {api_key}`
+- 模型:
+  - `cdance2.0-0611`
+  - `cdance2.0-fast-0611`
+
+目标是在 new-api 中新增独立渠道类型，复用现有 Seedance/Doubao 对外入口与任务链路，不把天翼云行为混入火山 Doubao 或 Aiping 渠道。
+
+---
+
+## 2. 范围
+
+### 2.1 包含
+
+- 新增 channel type: `DoubaoVideoCompatibleTianyiYun`
+- 默认 base URL: `https://ai.ctaigw.cn`
+- 复用现有 new-api 侧 Seedance/Doubao 入口:
+  - `POST /api/v3/contents/generations/tasks`
+  - `GET /api/v3/contents/generations/tasks/{task_id}`
+- 新增任务适配器，转发到天翼云上游:
+  - `POST /v1/contents/generations/tasks`
+  - `GET /v1/contents/generations/tasks/{task_id}`
+- 支持模型列表:
+  - `cdance2.0-0611`
+  - `cdance2.0-fast-0611`
+- 前端渠道类型枚举增加新渠道，管理员可在渠道管理中创建该渠道。
+- 实现后使用用户提供的 key 发起一次真实最短任务验证。
+
+### 2.2 不包含
+
+- 不新增用户侧公开路由 `/v1/contents/generations/tasks`
+- 不修改现有火山 Doubao 官方渠道语义
+- 不修改现有 `DoubaoVideoCompatibleAiping` 渠道语义
+- 不在代码、文档、日志或测试 fixture 中保存用户提供的真实 API key
+
+---
+
+## 3. 总体设计
+
+新增渠道保持独立：
+
+```text
+用户请求
+  -> POST /api/v3/contents/generations/tasks
+  -> 现有 token auth / distribute / task relay
+  -> ChannelTypeDoubaoVideoCompatibleTianyiYun
+  -> doubao_tianyiyun TaskAdaptor
+  -> POST https://ai.ctaigw.cn/v1/contents/generations/tasks
+```
+
+查询任务：
+
+```text
+用户请求
+  -> GET /api/v3/contents/generations/tasks/{public_task_id}
+  -> 本地任务表定位 upstream task id
+  -> doubao_tianyiyun FetchTask
+  -> GET https://ai.ctaigw.cn/v1/contents/generations/tasks/{upstream_task_id}
+```
+
+这样做的理由：
+
+- 渠道类型边界清楚，排查日志、计费、状态映射时不会混淆 Aiping 与天翼云。
+- 对外入口复用已有 Seedance/Doubao 任务接口，客户端不需要学习新的 new-api 路由。
+- 上游路径差异只封装在新适配器中，后续如果天翼云返回结构变化，影响范围较小。
+
+---
+
+## 4. 模型与请求体
+
+用户侧模型名直接使用天翼云模型 ID：
+
+- `cdance2.0-0611`
+- `cdance2.0-fast-0611`
+
+管理员仍可使用现有模型映射能力，把内部展示模型映射到天翼云模型 ID。
+
+请求体字段优先沿用现有 Doubao/Aiping Seedance 结构：
+
+- `model`
+- `content`
+- `ratio`
+- `duration`
+- `watermark`
+- 其它已由 Doubao/Aiping 适配器支持的 Seedance 字段，在不改变语义的情况下尽量透传。
+
+适配器不额外把 `duration` 改成 `seconds`，因为截图示例明确使用 `duration`。
+
+---
+
+## 5. 状态与响应处理
+
+提交任务时，上游返回的 task id 存入本地任务记录；返回给用户的仍是 new-api public task id，避免暴露不同上游 ID 体系。
+
+查询任务时，状态映射采用现有异步任务语义：
+
+| 上游状态 | new-api 状态 |
+| --- | --- |
+| `pending`, `queued` | queued |
+| `processing`, `running` | in_progress |
+| `succeeded`, `success` | success |
+| `failed`, `expired`, `cancelled` | failure |
+| 其它未知状态 | in_progress |
+
+成功时从上游响应中提取视频 URL。优先兼容现有字段 `content.video_url`；如果真实验证发现字段不同，再按真实返回补充解析。
+
+---
+
+## 6. 渠道测试与真实验证
+
+普通渠道“测试”按钮不适合直接测试异步视频渠道。该新渠道应与现有 Doubao/Vidu 类似，避免用聊天补全接口做快速测试。
+
+实现后的验证分两层：
+
+1. 自动化测试
+   - 单元测试覆盖上游提交 URL、查询 URL、Authorization header、模型列表。
+   - mock 上游测试覆盖提交响应 task id 与查询状态解析。
+   - 回归测试确认现有 Doubao/Aiping 测试不受影响。
+
+2. 真实上游验证
+   - 使用用户本轮提供的 API key 作为运行时输入，不写入仓库。
+   - 发起一次最短 5 秒任务，使用 `cdance2.0-0611` 或 `cdance2.0-fast-0611`。
+   - 记录状态码、public task id、upstream task id、查询状态和必要错误信息。
+   - 输出中不回显 API key。
+
+---
+
+## 7. 需要修改的模块
+
+预期实现会触及：
+
+- `constant/channel.go`
+  - 在 `ChannelTypeDummy` 前新增渠道类型。
+  - 同步 `ChannelBaseURLs` 与 `ChannelTypeNames`。
+- `relay/channel/task/doubao_tianyiyun/`
+  - 新增 `constants.go`
+  - 新增 `adaptor.go`
+  - 新增测试文件。
+- `relay/relay_adaptor.go`
+  - 注册新 task adaptor。
+- `common/api_type.go`
+  - 将新渠道映射到合适的 API type，建议沿用 VolcEngine/Doubao 视频相关路径。
+- `common/endpoint_type.go`
+  - 新渠道支持 `EndpointTypeDoubaoVideo`。
+- `controller/channel-test.go`
+  - 将新异步视频渠道加入不支持普通快速测试的列表。
+- `web/src/constants/channel.constants.js`
+  - 增加新渠道枚举，方便后台创建渠道。
+
+根据实现中发现的实际依赖，可能还需要补充与模型能力、计费矩阵相关的白名单，但应保持最小改动。
+
+---
+
+## 8. 风险与约束
+
+- `ChannelBaseURLs` 是按 channel type 索引的数组，新增类型必须同步维护索引，否则会造成渠道默认 base URL 错位。
+- 当前工作区已有其它未提交改动，实现时必须只修改本设计相关文件，不回退用户或其它任务的改动。
+- 真实验证会消耗上游额度；只做一次最短任务验证，除非用户要求重复验证。
+- 如果天翼云真实返回结构与截图示例不一致，应以真实响应为准补充解析，但不要扩大到无关功能。
+
+---
+
+## 9. 验收标准
+
+- 管理后台能选择并创建 `DoubaoVideoCompatibleTianyiYun` 渠道。
+- 渠道默认 base URL 为 `https://ai.ctaigw.cn`。
+- 模型列表包含 `cdance2.0-0611` 与 `cdance2.0-fast-0611`。
+- 经由现有 `/api/v3/contents/generations/tasks` 提交时，上游请求落到 `/v1/contents/generations/tasks`。
+- 查询任务时，上游请求落到 `/v1/contents/generations/tasks/{task_id}`。
+- 单元测试和相关回归测试通过。
+- 使用真实 key 完成一次任务提交验证，并报告 task id 或明确的上游错误。