MG-01-005 网关决策记录

媒体供应模块内的决策日志。跨仓或架构级决策以 ADR 决策索引为准（媒体供应方向见 ADR-0003、ADR-0014）。

状态说明：以当前有效边界为准。供应执行规则与历史实现证据保留；客户身份、售价、结算、全量旧跨仓契约及图像开放计划不代表当前验收范围。

本文记录首版设计基线。更改公开 API、请求模式、重试、降级、成本或健康语义时，必须新增决策条目。

D-024：对齐 2026-09-12 全系统多仓与统一供应入口（2026-09-18）

依据用户本轮指令及全系统已确认决定，修订 2026-09-05 main 边界与 D-022 的客户归属文字。新平台客户身份/Key/销售目录/价格/预留/结算和客户任务归 Core；产品 Workflow 归产品仓。目标 Core Worker → new-api → 媒体网关；不把 Core 直连媒体、全量旧 B1/Manifest/Observation 设为合并前置。保留现有 OpenAI/ModelArk、供应 UI、视频执行内核和 Provider 轮询。 serviceauth 内部身份不是客户归属；跨仓关联、幂等恢复、费用证据和结果授权仍待联调。当前只验收内部视频，图片/音频扩展单列；uumi 客户业务单列；本次代码合并不授权生产或收费调用。详情以 CURRENT_BOUNDARY.md 和 PLATFORM_INTEGRATION.md 为准；D-023 归档规则继续有效。

D-023：渠道移除采用可恢复归档（2026-09-10）

用户要求补齐渠道移除。实现为 archived，不是硬删除；名称、凭据、供给、绑定、成本版本、测试证据和历史 Attempt 均保留，不取消已创建的 Attempt。
管理 API DELETE /admin/v1/channels/{id} 使用 If-Match；渠道归档和全部子供给 enabled=false, production_ready=false 在同一事务提交，并记录审计。
默认渠道/供给列表隐藏归档渠道及其子供给；管理员可用 include_archived=true 查看。
POST /admin/v1/channels/{id}/restore 使用 If-Match，只恢复渠道为 disabled，不自动启用供给或发布模型。归档期间不能通过普通 PATCH、导入、凭据轮换、测试或启用复活。
沿用现有渠道停用对后续调度的排除规则，历史执行继续使用固定凭据；不改变重试、健康分类或供给归属。名称唯一约束保留，重新接入同名渠道应先恢复。

D-022：收敛为内部视频供给服务（2026-09-10）

状态：内部视频范围保留；客户归属与调用链由 D-024 修订。
新平台用户、客户 Key、销售目录、售价与结算由 Core 持有；new-api 保留供应入口。本服务移除对应运行时 API 和 UI；OMG-908 分支保留但停止集成。
服务仅对内部调用者开放，调用密钥和管理密钥分离；不开放匿名管理，不执行公网部署。
本轮只做视频。模型入口采用 seedance-2.0/2.5 等标准名称，同时允许显式绑定具体供给的独立别名；售卖逻辑不进入本网关。此项取代 D-019 的三个名称限制。
保留上游连接、凭据加密、精确供给能力/成本、确定性调度、两级健康、异步任务/结果。管理页名称为“视频供给路由”；参考旧页功能而不移植旧路由表、优先级或权重。
兼容迁移保留历史数据和内部归属外键，不通过破坏性删表移除用户管理。
真实测试授权：每个当前启用视频渠道一次最短文生视频调用，停用渠道仅配置校验；无自动重提，无生产写入/发布/切流，未验证供给保持 disabled。
详细契约见 docs/02-architecture/INTERNAL_VIDEO_SERVICE.md。D-015、D-020 及其他历史文档中的用户、广场、售价和图像首发要求不再适用于当前服务。
本地验证补充：仅 development 且 HTTP 监听地址为显式回环地址时，结果服务基址可使用 HTTPS localhost/回环 IP；生产仍要求公网 HTTPS。此例外只影响本服务生成的结果链接，不影响上游素材下载、SSRF 校验或对象存储重定向白名单。

D-001：建立独立新项目

状态：已接受
决策：新建空仓库，不在 new-api 或废弃 model-schedule 上继续叠加。
原因：旧系统包含大量无关功能和不适合媒体供给的分组、优先级、权重及双重配置。

D-002：废弃旧 model-schedule

状态：已接受
决策：/Users/wangzihao/Documents/model-schedule 不作为实现或设计基础。
原因：上一轮任务、统一持久 Task、首版范围和路由规则与当前需求冲突。

D-003：选择性复用 new-api

状态：已接受
决策：只复用经过审查的 Provider 协议适配和 UI 基础，不复用旧媒体调度。
参考提交：de3dfd82b675e21316a150d24edaf7b112f889cb。

D-004：单一供给配置源

状态：已接受
决策：供给 SKU 是能力、价格、容量、协议和模型健康的唯一来源。
后果：公开模型绑定只引用 Supply ID，不复制能力和价格；取消独立视频供给路由。

D-005：不用优先级与权重

状态：已接受
决策：采用硬条件过滤和可解释的字典序选择。
策略：stable_first 或 cost_first。

D-006：图像与视频执行模式

状态：已接受
决策：图像默认同步，显式请求才异步；视频默认异步。
后果：所有调用有使用记录，但只有异步调用创建可查询任务。

D-007：统一使用记录

状态：已接受
决策：不拆分使用日志、绘图日志和视频日志。
后果：一个使用记录页面按媒体类型、执行模式和状态筛选。

D-008：两级健康与精确 SKU

状态：已接受
决策：至少维护渠道账户和模型供给两个健康层级。
后果：模型、分辨率、能力版本或计费版本需要独立故障隔离时，应建成独立 SKU。

D-009：一次换供给重试

状态：已接受
决策：最多两次 Provider 提交，即首次加一次换供给重试。
条件：只有明确的供给、渠道或容量故障可重试；内容和请求错误不重试。
截止：任务创建 20 分钟后不再开始新的 Provider 提交。

D-010：多渠道增加总体并发

状态：已接受
决策：多个供给同时处理不同请求；默认不将一个请求并行提交给多个 Provider。
原因：避免重复生成、重复成本和不可解释结果。

D-011：受控能力降级

状态：已接受
决策：精确供给全部不可用时，可以执行预定义且经过验证的降级链。
限制：
- 不能任意替换模型；
- 不能执行未声明的请求变换；
- 降级模型、移除字段和成本上限必须预先配置；
- 模型广场和 API 文档必须披露；
- 使用记录和任务响应必须标记 degraded 及实际损失。

D-012：成本是调度事实，不是支付系统

状态：已接受
决策：保存 Provider 成本、报价和实际结算，但不建设充值、余额和支付。
后果：价格缺失或币种不可比较的供给不能进入生产自动调度。

D-013：PostgreSQL、Redis 与对象存储

状态：已接受
决策：
- PostgreSQL 是配置、请求、任务和审计的权威来源；
- Redis 承担队列唤醒、实时健康、容量租约和短期缓存；
- S3/R2 保存异步素材和平台生成结果；
- 首版不支持 MySQL 或 SQLite 生产运行。

D-014：UI 重新建立信息架构

状态：已接受
决策：复用 new-api 默认前端的视觉风格和无业务耦合组件，不复用其完整路由树。
后果：不出现聊天、Playground、充值、个人资料和通用系统设置页面。

D-015：本地账号密码

状态：已接受
决策：首版后台使用本地账号密码和安全 Session，用户 API Key 独立管理。
后果：不迁移 new-api 登录态，不建设 OAuth；管理员在新系统重建少量用户。

D-016：首批覆盖全部现有媒体渠道

状态：已接受
决策：new-api 当前启用的全部图像与视频渠道均纳入首批适配和受控真实冒烟。
后果：
- 当前停用或自动停用的媒体渠道只导入为 disabled Draft；
- Draft 不参与调度、不执行付费冒烟；
- 每个 production-ready Supply 只执行满足证据要求的最少真实调用；
- 无法安全制造的错误使用官方文档和脱敏历史响应补充。

D-017：单机 Docker Compose，暂不切流

状态：已接受
决策：首版交付到一台新的独立服务器，使用 Docker Compose 运行 API、Worker、 PostgreSQL、Redis 和对象存储依赖。
后果：
- API、Dispatcher、Poller 和 Reconciler 使用同一不可变镜像、不同启动角色；
- 开发完成后先完成隔离验收和回滚演练；
- 本轮不修改现网域名、反向代理或 new-api 媒体入口；
- 用户另行确认切换窗口后才执行生产流量切换。

D-018：真人视频优先使用无限制供给

状态：已接受
决策：请求包含真人素材时，先排除明确禁止真人素材的 Supply；其余硬能力相同的候选中，allowed 必须优先于 restricted，然后才应用稳定优先或成本优先排序。
原因：主要客户请求包含真人素材；即使受限供给当前更便宜或短期成功率更高，也不应在存在无限制供给时优先承担真人请求。
后果：真人政策是视频专属路由维度；图像调度不携带该字段。只有无限制供给均不可用时，才允许使用已验证可处理当前素材的 restricted 供给。

D-019：Seedance 官方双协议与公开配置价格

状态：已接受
决策：Seedance 视频公开入口采用 new-api/Sora POST /v1/videos 与 ByteDance ModelArk POST /api/v3/contents/generations/tasks；旧 /v1/media/generate 和 /v1/media/status 不再作为新客户端契约。
规范化：两种协议进入同一个 Video Domain Request、任务、调度、成本和审计链路； Sora 的 billing_mode 默认 per_second，只允许显式切换为 per_request，且计费方式必须参与供给硬过滤，禁止静默改用另一种价格。
模型：Sora/ModelArk 只接受 seedance-2.0、seedance-2.0-fast 和 seedance-2.0-mini 三个公开模型名，分辨率使用独立字段选择。
价格：模型广场公开当前用户可调用模型的“配置价格”，按模型、分辨率、素材配置（例如 431/933）和计费方式展示。该价格是已发布 Binding 所引用 Supply 当前 Cost Rule 的只读投影，不写入 Public Model，不返回 Channel、Supply、上游模型或成本规则 ID。
边界：本批次先交付两种协议的创建和单任务查询。ModelArk 素材库、任务列表、终态删除和尾帧提取必须由独立资产生命周期任务实现，不能用未持久化的内存兼容层伪造。
修订：本条“价格”段的 Cost Rule 直接公开方式由 D-020 取代；协议、模型和能力边界不变。

D-020：系统默认售价与用户专属售价

状态：已接受
决策：模型广场价格改为独立的客户售价簿。每个公开模型规格必须先配置系统默认售价；管理员可以再为单个用户配置同一规格的专属售价。
解析：当前用户有专属售价时返回专属售价，同时返回对应默认售价；没有专属售价时返回默认售价。没有默认售价的规格不在模型广场展示，专属售价不能脱离默认售价单独存在。
边界：客户售价不参与 Supply 选择、成本护栏、预计 Provider 成本或实际结算；Supply Cost Rule 仍是调度成本的唯一来源。客户组仍只控制模型访问和请求限制，不携带价格。
安全：公开 API 只返回默认售价、当前用户有效售价和售价来源，不返回其他用户售价、 Provider 成本、Channel、Supply 或 Cost Rule 标识。首版不增加余额、扣费、充值或支付。
管理：默认售价与用户专属售价均使用定点十进制、完整替换和乐观版本控制，并记录管理员审计事件。

D-021：图像与视频独立运营平面

状态：已接受
决策：Channel 必须固定属于 image 或 video，同一 Channel 不得同时挂载图像和视频 Supply。需要同时接入两类媒体的 Provider 账户必须分别创建图像 Channel 和视频 Channel，分别维护容量、健康、Credential Version 和 Supply。
管理：后台拆为图像渠道、图像模型路由、视频渠道和视频模型路由四个入口；创建、导入、能力、测试、计费和路由表单使用各自固定 DTO，不再通过媒体类型下拉框复用一套流程。
调度：运营人员只能调整 Public Model Binding 的参与状态和 exact/fallback/degraded 角色，或切换 stable_first/cost_first；仍禁止数字优先级、权重和渠道亲和度。
发布：运营页的 Binding 和策略写操作必须串行完成“保存配置 → 重新发布”。只有重新通过完整发布门禁后才影响新 Attempt；发布失败时保持 unpublished，并明确提示模型已暂停新请求，禁止把仅保存未发布显示成更新成功。
统计：按 Channel 和具体 Supply 从 Attempt 权威记录聚合调用量、成功率、错误分布、趋势和最近失败。健康窗口计数不替代调用统计，24 小时按小时、7/30 天按天聚合。
供给身份：431/900/903/933、分辨率和请求参数都不是模型唯一标识；同一 Channel 下每个具体 upstream_model + request_profile + variant_key 独立成为 Supply。若分辨率会改变实际上游模型，则按上游模型拆成不同 Supply。
代码边界：图像和视频的应用流程、DTO、表单与路由说明独立实现；只允许共享鉴权、加密、审计、定点金额、分页和图表绘制等无媒体业务语义的基础设施。

MG-01-005 网关决策记录

On this page