@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/.claude/docs/mediagen-provider-onboarding-sop.md

@@ -0,0 +1,917 @@
+# Mediagen Provider Onboarding SOP
+
+> **Upstream scope**: this complete OneX reference retains its explicitly dated provider snapshot. It describes work inside the upstream Mediagen service, not product-local provider implementation. Current upstream contracts and provider documentation must be verified before use; snapshot counts and paths are not current deployment evidence.
+
+> Scope: `internal/platform/mediagen/infrastructure/providers/*` + admin runtime configuration plane
+> Audience: 任何需要新增 / 修改 / 排障 mediagen Provider Adapter 或在 admin 上线 Provider 的工程师
+> 状态：admin-integrated 锁定版（基于提交 `f2338a6d` → `211ed024`）
+> 设计权威：本文与 `backend/.claude/docs/identifier-contract.md`、`api-design.md`、`error-handling.md` 共同构成 mediagen 模块的技术契约。
+
+本文档目的：让"接入新 Provider"从一个**模糊的探索性任务**收敛为**一组可逐步勾选的工程操作**。每一步都有具体的文件路径、迁移编号、admin UI 入口、复制模板、验收门槛。**严格按照本 SOP 落地的新 Provider，零返工**。
+
+post-alignment 阶段（commits `f2338a6d` → `84953e39`）锁定了 adapter 失败归一化、lane snapshot 真相源、telemetry 强制等架构不变量；admin-integrated 阶段（commits `fc1ee8d6` → `211ed024`）把"运营人员只能写 SQL 改 lane 配置"的现状升级为"在 admin UI 全流程可视化操作 + 服务端 JSON Schema 强校验 + Dry-run + Diff + Rollback"。本 SOP 同时覆盖两条路径：迁移文件（reproducible 种子）和 admin UI（运营自服务）。
+
+---
+
+## Section 1: Provider × Capability × Endpoint Matrix
+
+### 1.1 已激活 Provider 概要（snapshot 2026-04-26）
+
+| # | Provider Code | Base URL | Auth Scheme | Transport Class | Operations | Submit Endpoint Source | Poll Endpoint Source | Cancel | 说明 |
+|---|---------------|----------|-------------|-----------------|-----------|------------------------|-----------------------|--------|-----|
+| 1 | `duomi` | `https://duomiapi.com` | submit: query `?key=`（secondary）；poll: header `Authorization: <raw token>`（primary，无 Bearer 前缀） | `http_json_poll` | t2i, i2i, t2v, i2v | `req.Endpoint`（必填） | `firstNonEmpty(req.Endpoint, "/api/video/pix/feed?task_id=%s")` | 不支持 | 双凭证 split-channel；nano-banana 同步图像生成走 `sync:<base64>` ExternalID 短路（见 §1.4） |
+| 2 | `wavespeed` | `https://api.wavespeed.ai` | header `Authorization: Bearer <api_key>` | `http_json_poll` | t2i, i2i, t2v, i2v | `req.Endpoint`（必填） | `pollEndpoint = "/api/v3/predictions/%s/result"`（adapter const） | 不支持 | 内容审核走 `has_nsfw_contents[]` 后置探测，adapter 合成 `nsfw` provider_error_code |
+| 3 | `vidu` | `https://api.vidu.com` | header `Authorization: Token <api_key>`（"Token " 前缀必填） | `http_json_poll` | i2v | `req.Endpoint`（必填） | `pollEndpoint = "/ent/v2/tasks/%s/creations"`（adapter const） | 不支持（off_peak 任务可支持，未启用） | 错误码字符串枚举（`BadRequest` / `TooManyRequests` / `AuditFailed` 等），从 `{code,reason,message}` 信封解析 |
+| 4 | `wan` | `https://dashscope.aliyuncs.com` | header `Authorization: Bearer <api_key>` + 必填 `X-DashScope-Async: enable` | `http_json_poll` | t2v, i2v | `req.Endpoint`（必填） | `pollEndpoint = "/api/v1/tasks/%s"`（adapter const，Dashscope 通用） | 不支持 | 状态枚举大写 `PENDING/RUNNING/SUCCEEDED/FAILED/SUSPENDED/CANCELED/UNKNOWN`；失败 code 在 `output.code` |
+| 5 | `pixfree` | `https://app-api.pixverse.ai/creative_platform` | n/a（browser automation 子系统注入） | `browser_automation` | t2v, i2v, extend, lip_sync | n/a（Temporal stealthActivity 内部组装） | n/a | 不支持 | 唯一非 HTTP transport；Submit/Poll 均委派 Temporal `stealthActivity`，按 model_code 路由到 5 种 payload |
+| 6 | `yunwu` | `https://yunwu.ai` | header `Authorization: Bearer <api_key>` | `http_json_poll` | t2v, i2v | `req.Endpoint`（必填） | `pollEndpoint = "/v1/video/query?id=%s"`（adapter const） | 不支持 | HTTP 200 + `error` 字段非空表示业务级失败，adapter 强制 `Status=Failed` |
+
+### 1.2 Capability 矩阵
+
+| Operation | duomi | wavespeed | vidu | wan | pixfree | yunwu |
+|-----------|:-----:|:---------:|:----:|:---:|:-------:|:-----:|
+| `t2i` | ✓ | ✓ | - | - | - | - |
+| `i2i` | ✓ | ✓ | - | - | - | - |
+| `t2v` | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| `i2v` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `v2v` | - | - | - | - | - | - |
+| `extend` | - | - | - | - | ✓ | - |
+| `lip_sync` | - | - | - | - | ✓ | - |
+| `upscale` | - | - | - | - | - | - |
+| `frame_extract` | - | - | - | - | - | - |
+
+> 共计 **27 条 active lanes**。`v2v` / `upscale` / `frame_extract` 三个 operation 在 CHECK 约束中保留但当前无 lane。
+
+### 1.3 各 Provider 现存 Lanes 明细
+
+| Provider | Lane Code | Operation | Modality | Submit Path |
+|----------|-----------|-----------|----------|-------------|
+| duomi | `duomi_flux_schnell__t2i__duomi` | t2i | image | `/v1/images/generations`（同步） |
+| duomi | `duomi_nano_banana__t2i__duomi` | t2i | image | `/api/gemini/nano-banana`（同步） |
+| duomi | `duomi_nano_banana_pro__t2i__duomi` | t2i | image | `/api/gemini/nano-banana`（同步） |
+| duomi | `duomi_nano_banana_edit__i2i__duomi` | i2i | image | `/api/gemini/nano-banana-edit`（同步） |
+| duomi | `duomi_nano_banana_pro_edit__i2i__duomi` | i2i | image | `/api/gemini/nano-banana-edit`（同步） |
+| duomi | `duomi_pixpro_kling__t2v__duomi` | t2v | video | `/api/video/pix/pro/generate` |
+| duomi | `duomi_pixpro_kling__i2v__duomi` | i2v | video | `/api/video/pix/pro/generate` |
+| wavespeed | `wavespeed_nano_banana_t2i__t2i__wavespeed` | t2i | image | `/api/v3/google/nano-banana/text-to-image` |
+| wavespeed | `wavespeed_nano_banana_pro_t2i__t2i__wavespeed` | t2i | image | `/api/v3/google/nano-banana-pro/text-to-image` |
+| wavespeed | `wavespeed_nano_banana_edit__i2i__wavespeed` | i2i | image | `/api/v3/google/nano-banana/edit` |
+| wavespeed | `wavespeed_nano_banana_pro_edit__i2i__wavespeed` | i2i | image | `/api/v3/google/nano-banana-pro/edit` |
+| wavespeed | `wavespeed_seedream_v4_edit__i2i__wavespeed` | i2i | image | `/api/v3/bytedance/seedream-v4/edit` |
+| wavespeed | `wavespeed_z_image_turbo_i2i__i2i__wavespeed` | i2i | image | `/api/v3/wavespeed-ai/z-image-turbo/image-to-image` |
+| wavespeed | `wavespeed_seedance_v1pro_t2v__t2v__wavespeed` | t2v | video | `/api/v3/bytedance/seedance-v1-pro-fast/text-to-video` |
+| wavespeed | `wavespeed_wan22_t2v_ultrafast__t2v__wavespeed` | t2v | video | `/api/v3/wavespeed-ai/wan-2.2/t2v-480p-ultra-fast` |
+| wavespeed | `wavespeed_seedance_v1pro_i2v__i2v__wavespeed` | i2v | video | `/api/v3/bytedance/seedance-v1-pro-fast/image-to-video` |
+| wavespeed | `wavespeed_wan22_i2v_ultrafast__i2v__wavespeed` | i2v | video | `/api/v3/wavespeed-ai/wan-2.2/i2v-480p-ultra-fast` |
+| vidu | `vidu_template2video__i2v__vidu` | i2v | video | `/ent/v2/template2video` |
+| wan | `wan_t2v__t2v__wan` | t2v | video | `/api/v1/services/aigc/video-generation/video-synthesis` |
+| wan | `wan_i2v__i2v__wan` | i2v | video | `/api/v1/services/aigc/video-generation/video-synthesis` |
+| pixfree | `pixfree_t2v__t2v__pixfree` | t2v | video | `api/createTextVideo`（browser automation） |
+| pixfree | `pixfree_i2v__i2v__pixfree` | i2v | video | `api/createVideo`（browser automation） |
+| pixfree | `pixfree_face_swap__i2v__pixfree` | i2v | video | `api/createTwoImageToVideo`（browser automation） |
+| pixfree | `pixfree_video_extend__extend__pixfree` | extend | video | `api/extendVideo`（browser automation） |
+| pixfree | `pixfree_lip_sync__lip_sync__pixfree` | lip_sync | video | `api/speechVideo`（browser automation） |
+| yunwu | `yunwu_sora2__t2v__yunwu` | t2v | video | `/v1/video/create` |
+| yunwu | `yunwu_sora2__i2v__yunwu` | i2v | video | `/v1/video/create` |
+
+### 1.4 Provider Quirks（坑位备忘）
+
+- **duomi 双凭证**：submit/poll 用的是不同的密钥；secondary（PHP 源 `public $key`）走 query，primary（PHP `Authorization` header）走 header。`p_ai_providers.metadata.auth_profiles.{submit,poll}` 必须分别配置。
+- **duomi nano-banana 同步路径**：图像生成端点 `/api/gemini/nano-banana(-edit)` 是同步返回的，adapter 在 Submit 时把图像 base64/URL 直接编码到 `ExternalID` 内（前缀 `sync:`），Poll 阶段识别 `sync:` 前缀走短路逻辑（不再 HTTP 调用），直接返回 `Succeeded` + Output。
+- **wavespeed NSFW**：服务端不会把 NSFW 标记成 status=failed，而是在 `data.has_nsfw_contents: bool[]` 上每个 output 一个 flag；adapter 在 Poll 终态成功后扫描这个数组，命中即合成 `provider_error_code = "nsfw"` 走 `MapProviderFailure` 翻译为 `output_policy_violation`。
+- **vidu auth 前缀**：必须是 `"Token " + api_key`（注意 Token 后面有空格），不是 Bearer，不是裸 token。
+- **wan 异步 header**：`X-DashScope-Async: enable` 缺失会被服务器拒绝，adapter 必填。Dashscope 失败时 HTTP 仍是 200，错误码在 `output.code`（如 `DataInspectionFailed` / `Throttling.RateQuota`）。
+- **pixfree non-HTTP**：`browser_automation` transport 没有 HTTP submit/poll 端点；adapter 通过 Temporal `stealthActivity` 把任务交给浏览器自动化 worker 执行。`req.Endpoint` 在此 transport class 下不读。
+- **yunwu HTTP 200 + error**：业务级失败 HTTP 仍是 200，`error` 字段非空，adapter 必须强制 `Status=Failed`，否则 poll loop 会无限轮询吞噬终态。
+
+---
+
+## Section 2: 标准化设计原则（Architectural Invariants）
+
+post-alignment 后，下列不变量是 mediagen Provider Adapter 的**法律**。新增 Provider、修改现有 Provider、排障，均不得破坏。
+
+### 2.1 单一失败归一化点：`base.MapProviderFailure`
+
+所有 adapter 的失败路径**只能**通过 `base.MapProviderFailure(ctx FailureContext)` 翻译成 `*ProviderError`。
+
+```go
+// 对应 internal/platform/mediagen/infrastructure/providers/base/failure_mapping.go
+return base.MapProviderFailure(base.FailureContext{
+    ProviderCode:      providerCode,
+    Phase:             domain.FailurePhaseSubmit,   // or Poll / Cancel
+    HTTPStatus:        resp.StatusCode,
+    ProviderErrorCode: "<provider 文档定义的稳定字符串 code>",
+    ProviderStatus:    "<业务级状态，仅在 HTTP 200 + 业务失败时填>",
+    Message:           "<人类可读错误，可空>",
+    LaneMapper:        req.FailureMapper,            // 必传，活动层从 laneSnapshot 注入
+})
+```
+
+`MapProviderFailure` 内部按四维优先级（ProviderErrorCode > ProviderStatus > HTTPStatus > Message）走 lane snapshot 的 `failure_mapper` JSON 规则 + 默认规则，得到稳定 `domain.FailureReasonCode`。Adapter **绝不**自行实现 `mapXxxFailure`。
+
+### 2.2 文案匹配禁令：禁止 `strings.Contains` 做错误分类
+
+整个 mediagen 模块**全面禁止**以下模式：
+
+```go
+// FORBIDDEN
+if strings.Contains(err.Error(), "rate limit") { ... }
+if strings.Contains(message, "content policy") { ... }
+```
+
+错误分类必须基于**结构化信号**：sentinel error（`errors.Is`）、Temporal `ApplicationError` 类型、JSON envelope 的稳定 code 字段。文案变化不得影响系统行为。
+
+### 2.3 Lane snapshot 是端点真相源
+
+- `req.Endpoint`（来自 lane revision 的 `endpoint_config.submit_path`）是 **Submit 路径的唯一真相源**。adapter 必须在 Submit 入口校验 `req.Endpoint != ""`，空值即报错。
+- Poll 端点允许在 adapter 中以 `const` 形式存在，**前提**：该 Provider 的所有 lane 共享同一 poll 路由（如 wavespeed `/api/v3/predictions/%s/result`、wan `/api/v1/tasks/%s` 是 Dashscope 平台级路由）。
+- 当 Provider 不同 lane 需要不同 poll 路由时，参考 duomi 模式：`firstNonEmpty(req.Endpoint, defaultPollTmpl)`，让 lane revision 的 `poll_config.path_template` 可覆盖。
+- **禁止**在 adapter 中 hardcode 任何 submit 路径常量。
+
+### 2.4 `req.FailureMapper` 透传链
+
+`domain.SubmitRequest` / `domain.PollRequest` / `domain.CancelRequest` 都带 `FailureMapper map[string]any` 字段。
+
+完整数据流：
+```
+p_ai_provider_lane_revisions.failure_mapper (JSONB)
+  ↓ 装载
+ProviderLaneRevisionSnapshot.FailureMapper
+  ↓ Activity 层注入
+domain.SubmitRequest.FailureMapper / PollRequest.FailureMapper / CancelRequest.FailureMapper
+  ↓ adapter 透传
+base.MapProviderFailure 入参 LaneMapper
+  ↓ 走规则匹配
+domain.FailureReasonCode（稳定枚举）
+```
+
+Adapter **不得**修改、丢弃 `req.FailureMapper`，必须透传到 `MapProviderFailure`。
+
+### 2.5 稳定 `domain.FailureReasonCode` 枚举（9 类）
+
+整个 mediagen 域只有以下 9 个 reason code 是合法的：
+
+| Code | 含义 | Retryable |
+|------|------|-----------|
+| `prompt_policy_violation` | Prompt 违反策略（用户文案侧） | 否 |
+| `input_image_policy_violation` | 输入图违反策略 | 否 |
+| `input_image_invalid` | 输入图非法（格式/尺寸/编码） | 否 |
+| `output_policy_violation` | 输出违反策略（含 NSFW） | 否 |
+| `timeout` | 调用超时 | 是 |
+| `rate_limit` | 限流 | 是 |
+| `provider_error` | Provider 5xx / 上游不可用 | HTTP 5xx 时是，其他否 |
+| `internal_error` | 平台内部错误 | 否（需人工） |
+| `user_canceled` | 用户取消 | 否 |
+
+> 新增类别需要修改 `domain.FailureReasonCode`、`ResolveFailureReasonCode`、所有 lane snapshot 的 mapper rule。**新接 Provider 时不应触发这条路径**——遇到无法归类的错误，先映射到 `provider_error`。Auth 失败、计费失败、参数错误均归 `provider_error`（HTTP 4xx 不可重试分支）。
+
+### 2.6 Idempotency 文档化
+
+- 真正实现幂等的 Provider（目前没有）：在 adapter GoDoc 中说明机制（key 名、TTL、生效条件）。
+- Provider 不实现幂等的（多数）：**禁止**伪造 `X-Idempotency-Key` header 假装支持幂等。如果代码确实发送了 `X-Idempotency-Key`，必须有注释说明是"内部 trace 标记，Provider 不强制"。
+- 重复提交保护应在 mediagen 域层（`Generation.IdempotencyKey` + DB unique 约束）解决，不依赖 Provider。
+
+### 2.7 Telemetry 强制填充
+
+`domain.ProviderTelemetry` 只有 4 个字段：
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `HTTPStatus` | `int16` | HTTP 状态码 [100,599]；0 表示非 HTTP transport（pixfree） |
+| `LatencyMs` | `int64` | 调用墙钟耗时（毫秒） |
+| `QueueMs` | `int64` | Provider 端排队耗时；不可观测时填 0 |
+| `CostUSD` | `string` | NUMERIC(12,6) 字符串；不可观测时填 `""` |
+
+**每个 adapter 在成功路径必须填充 Telemetry**。失败路径不填（`*ProviderError` 自带 StatusCode）。Activity 层 `appendSubmitLog` / `appendPollLog` 把 Telemetry 写入 `p_mediagen_execution_logs`。
+
+### 2.8 `transport_retry_count` = Temporal Activity Attempt
+
+- `p_mediagen_generations.transport_retry_count` 列由迁移 000473 创建。
+- 语义：**Temporal SDK 已执行的 Activity attempt 计数减 1**（首次成功不写入；attempt > 1 才落库）。
+- 来源：`activity.GetInfo(ctx).Attempt`（Temporal SDK 提供）。
+- **不是**业务层的"用户重试次数"。用户主动 retry 是新的 Generation。
+
+详见 `domain/generation.go` 的 `TransportRetryCount` GoDoc 与 `provider_activities.go::ProviderPoll` 的写入逻辑。
+
+### 2.9 Lane Revision JSONB 字段服务端强校验（I-9）
+
+`aiconfig.ValidateLaneRevisionFields` 在每次 `CreateProviderLaneRevision` 入口处对**所有 12 个 JSONB 字段**做形态契约校验，任何不合法的 JSON **在落库前**被拒绝。这是 D7（production code 无 stub / placeholder）+ E3（zero-tolerance hack）的工程化兜底。
+
+被校验的 12 个字段（与数据库列名 / DTO json tag 一一对应）：
+
+| # | 字段 | 校验要点 |
+|---|------|---------|
+| 1 | `endpoint_config` | `submit_path` 必填且为合法 path |
+| 2 | `auth_config` | `bindings[].location ∈ {header,query,body,cookie}`；`secret_ref ∈ {primary,secondary}` |
+| 3 | `submit_config` | HTTP method ∈ {POST, GET, PUT}（提交语义）；body schema 合法 |
+| 4 | `poll_config` | HTTP method ∈ {POST, GET, PUT, DELETE, PATCH} |
+| 5 | `cancel_config` | 同 transport 通用方法白名单；可空（不支持时） |
+| 6 | `request_defaults` | object，被 request mapper 浅合并 |
+| 7 | `input_schema` | JSON Schema draft-07 子集 |
+| 8 | `request_mapper` | `transforms[]` 每条 `{from, to, op}` 结构合法 |
+| 9 | `response_normalizer` | `paths.{status,output,error}` JSONPath 合法 |
+| 10 | `failure_mapper` | `rules[]` 每条仅含 4 维匹配键（http_status / provider_error_code / provider_status / message_contains）+ 1 个 `reason_code` ∈ §2.5 9 类 |
+| 11 | `telemetry_extractor` | 4 字段 JSONPath 合法（http_status / latency_ms / queue_ms / cost_usd） |
+| 12 | `retry_policy` | `max_attempts ≥ 0`；`backoff` 系数合法；`retryable_codes[]` ∈ §2.5 9 类 |
+
+校验失败时返回 `apierror.BadRequest("lane_revision_invalid", path)`，`path` 形如 `failure_mapper.rules[2].reason_code`，与 Stripe `parameter_invalid` 风格对齐 —— 前端 `FailureMapperRuleBuilder` 等可视化编辑器据此精确定位错误位置。
+
+**不变量**：bad config 不再"静默落库 + 运行时 panic"，所有形态错误在 admin UI Save 阶段就拒收。
+
+---
+
+## Section 3: 新增 Provider 完整流程 SOP
+
+> 这是**核心标准化文档**。每一步都对应具体文件路径或迁移编号。每完成一阶段勾选一次，杜绝跳步。
+
+### Phase A: Research（写代码前）
+
+不做研究就写代码 = 注定返工。每个新 Provider 必须先回答下列 8 个问题，研究结果落到一份 `research-{provider}.md`（可放 `/tmp/`）：
+
+| # | 必答项 | 示例（duomi） |
+|---|--------|----------------|
+| A1 | base_url（含 scheme + 是否需要尾部斜杠） | `https://duomiapi.com` |
+| A2 | auth scheme（header / query / 其他），prefix（`Bearer ` / `Token ` / 裸 token / `?key=`） | submit query `?key=`；poll header `Authorization: <raw>` |
+| A3 | 提交端点 path（区分 t2i/i2i/t2v/i2v/extend/lip_sync 各操作） | `/api/video/pix/pro/generate`（i2v/t2v）；`/api/gemini/nano-banana(-edit)`（t2i/i2i） |
+| A4 | 轮询端点 path（是否所有 lane 共享 / 是否需要 lane-specific） | `/api/video/pix/feed?task_id=%s`（视频族共享） |
+| A5 | 取消端点（不支持就明确写"none"） | none |
+| A6 | 状态枚举（大写 / 小写，完整集合） | `pending / running / succeeded / error`（小写） |
+| A7 | 同步 vs 异步（同步要明确返回内容如何编码到 ExternalID） | nano-banana 同步；pix 异步 |
+| A8 | 错误码体系（字符串 / 数字 / 文档化的稳定 enum / 文案描述） | 数字 code 在 envelope 顶层；字符串 reason 在 4xx 信封 |
+| A9 | 内容审核信号（独立 error code / success 中的 flag） | 暂无 |
+| A10 | 成本/计费字段（per-request / 账户级） | 账户级，response 不带 cost |
+
+**没有 A1-A10 的全部答案，禁止进入 Phase B**。
+
+---
+
+### Phase B: Database — 注册 Provider + Models + Lane Revisions
+
+> 两条互斥路径，按 Provider 是否需要 git-tracked 种子选择：
+>
+> | Path | 何时使用 | 入口 |
+> |------|---------|------|
+> | **B-UI（推荐，运营自服务）** | 仅当前 dev / staging / prod 实例需要这个 Provider；不需要在新 DB freshness 时自动种子 | 走 §K 全流程 admin UI 操作（`/ai/runtime/providers` + `/ai/runtime/lanes` + `/ai/runtime/lanes/:code/revisions`） |
+> | **B-Migration（reproducible 种子）** | Provider 是平台基础能力，每次 fresh DB 都要带（如默认 wavespeed / wan / pixfree）；或者需要在 PR 中 review 配置内容 | 写迁移文件，下面 §B.1 / §B.2 / §B.3 模板 |
+>
+> 两条路径的服务端契约**完全相同**：admin UI Save 走 `aiconfig.ValidateLaneRevisionFields`（§2.9），迁移 SQL 落库时不会经过 validator —— **因此走 B-Migration 路径的同学必须严格按 §B.3 模板写，validator 不是 SQL 的兜底**。
+
+#### B.1 创建 `00XXXX_seed_<provider>_provider_and_models.up.sql`
+
+```sql
+-- 1. 注册 Provider 行
+INSERT INTO p_ai_providers (
+    name, display_name, status,
+    base_url, encrypted_api_key, encrypted_secret_key,
+    provider_type, max_concurrency, default_timeout_sec, max_retries, default_priority,
+    metadata, contact_status, capabilities
+) VALUES (
+    '<provider_code>', '<Display Name>', 'active',
+    '<base_url>', '', '',
+    'media', 10, 60, 3, 0,
+    jsonb_build_object(
+        'auth_profiles', jsonb_build_object(
+            'submit', jsonb_build_object(
+                'bindings', jsonb_build_array(
+                    jsonb_build_object('location', 'header', 'name', 'Authorization', 'prefix', 'Bearer ', 'secret_ref', 'primary')
+                )
+            ),
+            'poll', jsonb_build_object(
+                'bindings', jsonb_build_array(
+                    jsonb_build_object('location', 'header', 'name', 'Authorization', 'prefix', 'Bearer ', 'secret_ref', 'primary')
+                )
+            )
+        )
+    ),
+    'unknown', '{}'
+);
+
+-- 2. 注册 Model 行（每个 lane 都需要对应 model）
+INSERT INTO p_ai_models (provider_id, model_id, model_code, capabilities, default_params, param_schema, cost_credits, ...)
+VALUES ((SELECT id FROM p_ai_providers WHERE name='<provider_code>'), '<external_model_id>', '<our_model_code>',
+    jsonb_build_object('operations', jsonb_build_array('t2v','i2v')),
+    jsonb_build_object('duration', 5),
+    jsonb_build_object(...),
+    12, ...);
+```
+
+#### B.2 创建 `00YYYY_seed_<provider>_lane_revisions.up.sql`
+
+按每个 operation 一条 lane + 一条 lane_revision 写入：
+
+```sql
+INSERT INTO p_ai_provider_lanes (provider_id, code, operation, modality, transport_class, status, model_code)
+VALUES ((SELECT id FROM p_ai_providers WHERE name='<provider_code>'),
+        '<provider_code>_<model>__<op>__<provider_code>', 'i2v', 'video',
+        'http_json_poll', 'active', '<our_model_code>');
+
+INSERT INTO p_ai_provider_lane_revisions (
+    lane_id, version,
+    endpoint_config, submit_config, poll_config,
+    failure_mapper,
+    request_defaults, request_mapper, response_normalizer, retry_policy,
+    auth_config,
+    status
+) VALUES (
+    (SELECT id FROM p_ai_provider_lanes WHERE code = '<...>'),
+    1,
+    jsonb_build_object('submit_path', '<submit path>'),
+    jsonb_build_object('method', 'POST'),
+    jsonb_build_object('method', 'GET', 'path_template', '<poll template, optional>'),
+    -- failure_mapper：见 §B.3 模板
+    '<failure_mapper json>'::jsonb,
+    '{}'::jsonb,
+    '{}'::jsonb,
+    '{}'::jsonb,
+    '{}'::jsonb,
+    '{}'::jsonb,
+    'active'
+);
+```
+
+#### B.3 `failure_mapper` 模板
+
+```json
+{
+  "rules": [
+    {"http_status": [429], "reason_code": "rate_limit"},
+    {"provider_error_code": ["<provider 限流字符串 code>"], "reason_code": "rate_limit"},
+    {"http_status": [408, 504], "reason_code": "timeout"},
+    {"http_status": [500, 502, 503], "reason_code": "provider_error"},
+    {"provider_error_code": ["<provider 内容策略 code>"], "reason_code": "output_policy_violation"},
+    {"provider_error_code": ["<provider 输入图非法 code>"], "reason_code": "input_image_invalid"}
+  ]
+}
+```
+
+> 规则**严格使用 Provider 官方文档明文定义的稳定字符串 code**。**禁止**编造（如 `"rate_limited"` / `"content_policy"` 这类通用名 —— Provider 不一定真的返回这个值）。
+> 如果 Provider 没有稳定字符串 code（如 wavespeed），就只配 `http_status` 规则；adapter 在合适时机合成虚拟 code（参考 wavespeed `nsfw`）。
+
+---
+
+### Phase C: Go Adapter — 实现 `domain.MediaProvider` 接口
+
+#### C.1 创建目录与文件
+
+```
+internal/platform/mediagen/infrastructure/providers/<provider>/
+  adapter.go
+  adapter_test.go
+```
+
+#### C.2 adapter.go 骨架（从 yunwu 或 duomi 复制起）
+
+```go
+package <provider>
+
+import (
+    "context"
+    "fmt"
+    "net/http"
+    "strings"
+    "time"
+
+    "go.uber.org/zap"
+
+    "github.com/onex-platform/backend/internal/core/httpclient"
+    "github.com/onex-platform/backend/internal/platform/mediagen/domain"
+    "github.com/onex-platform/backend/internal/platform/mediagen/infrastructure/providers/base"
+)
+
+const (
+    providerCode = "<provider>"
+    pollEndpoint = "<poll path with %s for external id>"  // 仅当 Provider 全平台共享同一 poll 路由
+)
+
+type Adapter struct {
+    base.Adapter
+}
+
+func NewAdapter(logger *zap.Logger, client *httpclient.Client, resolver base.RuntimeConfigResolver) *Adapter {
+    return &Adapter{Adapter: base.NewAdapter(providerCode, client, resolver, logger)}
+}
+
+func (a *Adapter) Code() string { return providerCode }
+
+func (a *Adapter) Capabilities() domain.Capabilities {
+    return domain.Capabilities{
+        Modalities:   []domain.Modality{domain.ModalityVideo},
+        Operations:   []domain.Operation{domain.OperationTextToVideo, domain.OperationImageToVideo},
+        AspectRatios: []string{"9:16", "16:9", "1:1"},
+        // 其余字段按 Provider 实际能力填，绝不填 stale defaults
+    }
+}
+
+// submitResponse / pollResponse：按 Provider 真实响应 schema 定义 typed struct，不要用 map[string]any
+type submitResponse struct { /* ... */ }
+type pollResponse struct { /* ... */ }
+```
+
+#### C.3 Submit 方法
+
+```go
+func (a *Adapter) Submit(ctx context.Context, req *domain.SubmitRequest) (*domain.SubmitResponse, error) {
+    if req.Endpoint == "" {
+        return nil, fmt.Errorf("<provider> submit: req.Endpoint is empty")
+    }
+    start := time.Now()
+    endpoint, err := a.ResolveEndpoint(ctx, req.Endpoint)
+    if err != nil { return nil, fmt.Errorf("<provider> submit resolve endpoint: %w", err) }
+    apiKey, err := a.ResolveAPIKey(ctx)
+    if err != nil { return nil, fmt.Errorf("<provider> submit resolve api key: %w", err) }
+
+    headers := map[string]string{"Authorization": "Bearer " + apiKey}
+
+    var result submitResponse
+    resp, err := a.Client.PostWithHeaders(ctx, endpoint, req.Payload, &result, headers)
+    duration := time.Since(start)
+
+    if err != nil {
+        a.LogSubmit("submit", req.GenerationID, duration, 0, err)
+        return nil, fmt.Errorf("<provider> submit: %w", err)
+    }
+    if !base.IsSuccessStatus(resp.StatusCode) {
+        a.LogSubmit("submit", req.GenerationID, duration, resp.StatusCode, nil)
+        return nil, base.MapProviderFailure(base.FailureContext{
+            ProviderCode:      providerCode,
+            Phase:             domain.FailurePhaseSubmit,
+            HTTPStatus:        resp.StatusCode,
+            ProviderErrorCode: extractErrorCode(&result, resp.Body),  // Provider-specific helper
+            Message:           base.FirstNonEmpty(result.Error, string(resp.Body)),
+            LaneMapper:        req.FailureMapper,
+        })
+    }
+    if result.ID == "" {
+        return nil, base.MapProviderFailure(base.FailureContext{ /* HTTP 200 但 task_id 缺失 */ })
+    }
+
+    a.LogSubmit("submit", req.GenerationID, duration, resp.StatusCode, nil)
+    return &domain.SubmitResponse{
+        ExternalID: result.ID,
+        Raw:        resp.Body,
+        Telemetry: &domain.ProviderTelemetry{
+            HTTPStatus: int16(resp.StatusCode),
+            LatencyMs:  duration.Milliseconds(),
+            CostUSD:    "",
+        },
+    }, nil
+}
+```
+
+#### C.4 Poll 方法
+
+```go
+func (a *Adapter) Poll(ctx context.Context, req *domain.PollRequest) (*domain.PollResponse, error) {
+    externalID := req.ExternalID
+    start := time.Now()
+    endpoint, err := a.ResolveEndpoint(ctx, fmt.Sprintf(pollEndpoint, externalID))
+    // ... HTTP 调用
+    if !base.IsSuccessStatus(resp.StatusCode) {
+        return nil, base.MapProviderFailure(...)
+    }
+
+    pollResp := &domain.PollResponse{
+        Status: mapStatus(result.Status),
+        Raw:    resp.Body,
+        Telemetry: &domain.ProviderTelemetry{...},
+    }
+    // 终态失败：HTTP 200 但 status=failed / error 字段非空
+    if isTerminalFailure(result) {
+        provErr := base.MapProviderFailure(base.FailureContext{
+            ProviderCode:      providerCode,
+            Phase:             domain.FailurePhasePoll,
+            HTTPStatus:        resp.StatusCode,
+            ProviderErrorCode: result.ErrorCode,
+            Message:           result.ErrorMessage,
+            LaneMapper:        req.FailureMapper,
+        })
+        category := provErr.Category
+        reasonCode := provErr.ReasonCode
+        pollResp.FailureCategory = &category
+        pollResp.FailureReasonCode = &reasonCode
+        pollResp.FailureMessage = result.ErrorMessage
+        pollResp.Status = domain.StatusFailed   // 强制终态 Failed
+    }
+    if result.OutputURL != "" {
+        pollResp.Status = domain.StatusSucceeded
+        pollResp.Progress = 1.0
+        pollResp.Output = append(pollResp.Output, domain.OutputAsset{Kind: domain.ModalityVideo, URL: result.OutputURL})
+    }
+    return pollResp, nil
+}
+```
+
+#### C.5 Cancel 方法
+
+```go
+func (a *Adapter) Cancel(ctx context.Context, req *domain.CancelRequest) error {
+    return domain.ErrCancelNotSupported   // 多数 Provider 不支持
+}
+```
+
+支持取消的，按 Submit 同样的模式：HTTP 调用 + `MapProviderFailure`。
+
+#### C.6 注册到 Wire（`providers/registry.go`）
+
+```go
+import "github.com/onex-platform/backend/internal/platform/mediagen/infrastructure/providers/<provider>"
+
+var ProviderSet = wire.NewSet(
+    NewRuntimeConfigResolver,
+    wavespeed.NewAdapter,
+    vidu.NewAdapter,
+    wan.NewAdapter,
+    duomi.NewAdapter,
+    yunwu.NewAdapter,
+    pixfree.NewAdapter,
+    <provider>.NewAdapter,                      // 新增
+    ProvideAdapterRegistry,
+)
+
+func ProvideAdapterRegistry(
+    logger *zap.Logger,
+    ws *wavespeed.Adapter, vi *vidu.Adapter, wn *wan.Adapter,
+    du *duomi.Adapter, yw *yunwu.Adapter, pf *pixfree.Adapter,
+    np *<provider>.Adapter,                     // 新增
+) (*AdapterRegistry, error) {
+    return NewAdapterRegistry(logger, ws, vi, wn, du, yw, pf, np)
+}
+```
+
+> 不需要在 `domain/enum.go` 的 `ProviderCode` 常量列表新增成员（该枚举仅用于编译期类型守卫，目前不强约束所有 Provider；但若 Provider 是面向产品对外曝光的 enum，则同步加常量）。
+
+---
+
+### Phase D: Capability gating + Cost
+
+1. 检查 `p_capability_truth_*` 表是否需要更新（仅当新 Provider 引入了新的 capability gating 规则时；常规接入不需要）。
+2. `cost_per_call_usd` 与 `cost_credits` 在 `p_ai_models` 写入时已经决定，验证：
+   ```sql
+   SELECT model_code, cost_credits, cost_per_call_usd FROM p_ai_models WHERE provider_id = ...;
+   ```
+3. 产品曝光策略由仓库外的产品 BFF 负责；OneX 只发布稳定的 Mediagen capability 与 runtime contract，不包含产品 resolver。
+
+---
+
+### Phase E: Credit Deduction
+
+Mediagen 模块已经实现 Stripe 风格 authorization → capture 的信用扣费链路（Freeze → Settle / Refund）。**新 Provider 完全继承，无需写额外信用代码**，前提：
+
+- Submit 必须发生在 `txManager.WithTransaction(ctx, fn)` 块内（执行 activity 已经如此，无需修改）。
+- Poll 终态 Succeeded → `Settle` 自动触发；终态 Failed/Canceled → `Refund` 自动触发。
+- 这套链路位于 mediagen 的 application/saga 层，对 adapter 透明。
+
+---
+
+### Phase F: 错误处理 — failure mapper 规则
+
+- 已经在 Phase B.3 的 lane revision 里写好了基础规则。
+- **新发现的 Provider 错误码**（例如某次线上排障发现 Provider 返回了未文档化的 code）：**优先走 admin UI**（无需发版、无需迁移、即时生效）：
+  1. 进入 `/ai/runtime/lanes/:laneCode/revisions`
+  2. 在左侧 RevisionTimeline 选择当前 published revision，点击 **"New Revision"**（基于当前版本派生 draft）
+  3. 切到右侧 **Failure** tab，使用 `FailureMapperRuleBuilder` 可视化编辑器（Stripe Radar 风格）：
+     - 选择匹配维度（`http_status` / `provider_error_code` / `provider_status`）
+     - 输入候选值数组（与 §B.3 模板一致：必须是 Provider 文档明文定义的稳定字符串 code）
+     - 选择 `reason_code`（dropdown 仅可选 §2.5 9 类合法枚举）
+  4. 点击 **"Dry-run"** → 粘贴一条真实 Provider 响应（例如线上日志里抓到的失败 JSON）→ 验证 `failure_resolution.reason_code` 为预期值
+  5. 点击 **"Publish"** 把 draft revision 设为 active
+- 仍然需要 git-tracked 配置时（如默认 Provider 修订）：写一条 `00XXXX_extend_<provider>_failure_mapper.up.sql`，**只动 lane revision 的 failure_mapper JSON**。无论走哪条路径，**绝不改 adapter 代码** —— adapter 的工作只是把 ProviderErrorCode 透传到 `MapProviderFailure`。
+- 服务端兜底：`aiconfig.ValidateLaneRevisionFields` 会在 Save 阶段拒收 `failure_mapper.rules[*].reason_code` 不在 9 类合法值中的 draft（`apierror.BadRequest("lane_revision_invalid", "failure_mapper.rules[N].reason_code")`）。
+
+---
+
+### Phase G: Telemetry + Observability
+
+- 已经在 Phase C 的 Submit / Poll 模板里 populated `Telemetry`。
+- Activity 层的 `appendSubmitLog` / `appendPollLog` 把 Telemetry 写入 `p_mediagen_execution_logs`。
+- Admin trace UI 读 `p_mediagen_execution_logs`，按 `generation_id` 关联。
+- 可观测性自动接入，不需要额外配置。
+
+---
+
+### Phase H: Tests
+
+#### H.1 Adapter unit tests（`<provider>/adapter_test.go`）
+
+最小覆盖面（每条都必须存在）：
+
+| 用例 | 断言 |
+|------|------|
+| Submit 成功 | 返回 SubmitResponse；ExternalID 非空；Telemetry.HTTPStatus / LatencyMs 已填 |
+| Submit HTTP 4xx 失败 | 返回 `*ProviderError`；ReasonCode 来自 mapper rule |
+| Submit HTTP 5xx 失败 | 返回 `*ProviderError`；ReasonCode = `provider_error`；Retryable=true |
+| Submit HTTP 200 但 task_id 缺失 | 返回 `*ProviderError`；不 panic |
+| Poll 成功（异步终态 Succeeded） | Status=Succeeded；Output 非空 |
+| Poll 终态失败（HTTP 200 + status=failed） | Status=Failed；FailureReasonCode 已填 |
+| Poll HTTP 4xx | 返回 `*ProviderError` |
+| `mapStatus` 全枚举映射 | 表驱动测试覆盖 Provider 所有 status 字面量 |
+| Cancel 不支持 | 返回 `domain.ErrCancelNotSupported` |
+| Cancel 支持（如适用） | 成功 + 失败两条路径 |
+
+测试**必须**用真实响应样本作为 fixture（从 Provider 文档复制粘贴），不允许 mock 一切。
+
+#### H.2 Integration test（仅当 transport 不是常规 HTTP）
+
+参考 `infrastructure/temporal/activity/runtime_execution_activities_test.go`。pixfree-class 的非 HTTP transport 必须有 integration test。
+
+---
+
+### Phase I: Wire generation
+
+```bash
+cd "$(git rev-parse --show-toplevel)/backend" && make wire 2>&1 | tail
+```
+
+期望输出：`Wire has generated wire_gen.go for ...`。失败必修。
+
+---
+
+### Phase J: Verification
+
+```bash
+cd "$(git rev-parse --show-toplevel)/backend" && \
+  go vet ./... && \
+  go build ./... && \
+  go test ./internal/platform/mediagen/... 2>&1 | tail
+```
+
+三条命令**必须全绿**。`go test` 覆盖 adapter unit tests。
+
+---
+
+### Phase K: Migration apply（dev DB）
+
+> 仅当走 §B-Migration 路径时执行；走 §B-UI 路径直接跳到 §L。
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+compose=(docker compose --env-file deployments/.env.dev \
+  -f deployments/docker-compose.yml \
+  -f deployments/docker-compose.dev.yml)
+"${compose[@]}" stop --timeout 30 \
+  platform-api platform-api-2 admin-api admin-api-2 \
+  documentation-api documentation-api-2 worker
+"${compose[@]}" run --rm --no-deps bootstrap-database bootstrap
+"${compose[@]}" run --rm --no-deps set-db-passwords
+"${compose[@]}" run --rm --no-deps migrate up
+"${compose[@]}" run --rm --no-deps grant-runtime-access
+"${compose[@]}" up -d platform-api admin-api documentation-api worker
+```
+
+期望：迁移成功执行，`schema_migrations.dirty = false`。
+
+---
+
+### Phase L: Admin Onboarding Click-Through（7 步全程在 admin UI）
+
+接入新 Provider 的最后一步是**让运营在 admin UI 验证全流程可用**。即使走了 §B-Migration 路径，下面的可视化校验仍然必须勾选 —— 它是 admin 与后端契约一致性的活体检查。
+
+| Step | UI 入口 | 操作 | 验收信号 |
+|------|---------|------|---------|
+| 1. 创建 Provider | `/ai/runtime/providers` → **"Create Provider"** 抽屉 | 填写 `name` / `display_name` / `base_url` / `api_key`（写到 secret_bundle）；展开 **Auth Profiles** 区，使用 `AuthProfileBindingEditor` 添加 submit / poll 两组绑定（每条 row：`location`, `name`, `value_prefix`, `secret_ref`） | 列表出现新行，状态标签 `active`（绿色） |
+| 2. 注册 Model | `/ai/control-plane/models` → **"Create Model"** | 选择刚才的 Provider，填 `model_id`（外部 id）/ `model_code`（我方稳定 code）/ `capabilities.operations` 数组 / `cost_credits`。该页面是 LLM 与媒体生成模型的统一注册入口，列表顶栏 `provider_type` 下拉过滤切换 LLM / media 域 | 列表筛 `provider_type=media` 后看到新行；按 `provider_id` 二次过滤可定位 |
+| 3. 创建 Lane | `/ai/runtime/lanes` → **"Create Lane"** 抽屉 | 填 `code` / `operation` / `modality` / `transport_class` / `provider_id` / `model_code`，与 §1.3 命名规范保持一致：`<provider>_<model>__<op>__<provider>` | 列表出现新 lane，`published_revision_no` 暂为空 |
+| 4. 创建 Lane Revision | `/ai/runtime/lanes/:laneCode/revisions` → **"Create Revision"**（顶栏右侧） | 在右侧 11-tab 编辑器逐 tab 填写：Endpoints / Auth / Submit / Poll / Response / Failure / Request Mapper / Reliability / Telemetry / Diff / Dry-run。可视化编辑器（`FailureMapperRuleBuilder`、`RequestMapperEditor`、`ResponseNormalizerEditor`、`RetryPolicyEditor`）兜底，运营**不需要写 JSON** | 点击 **"Save Draft"** 后，左侧 RevisionTimeline 顶部出现新 draft 行；服务端通过 `ValidateLaneRevisionFields`（12 字段全过） |
+| 5. Dry-run 验证 | 同页面 → 顶栏 **"Dry-run"** 按钮（打开 `LaneRevisionDryRunDrawer`） | 粘贴一份样本输入（参考 Phase A 研究里收集的 Provider 文档示例），运行 | 抽屉返回 `normalized_request`（被 request_mapper 应用后的最终 payload）+ `applied_transforms` 列表；点击 **"Copy as cURL"** 可直接 paste 到终端复现请求 |
+| 6. Publish | 同页面 → 顶栏 **"Publish"** 按钮（打开 `LaneRevisionPublishDialog`） | 确认 modal | Lane.`published_revision_id` 翻新；该 lane 下次 Generation 立即使用新 revision |
+| 7. Rollback（仅故障时） | 同页面 → 选中"上一个 published" 行 → 顶栏 **"Rollback"** | 确认 modal（`POST /admin/ai/provider-lanes/:id/revisions/:revisionId/rollback`，权限 `ai_lane:rollback`） | 上一版本恢复为 active；当前 broken revision 标记 `superseded`；服务端兜底：若不存在历史 published revision，rollback 直接返回 `apierror.Conflict` |
+
+> 全流程下来一个新 Provider 不需要再回 SQL 或后端代码 —— 只在 §C / §H 出现的 Go adapter 是真正需要写代码的部分；其他所有"配置化"工作都在 admin UI 完成。
+
+---
+
+## Section 4: Reference Implementation Map
+
+新 Provider 类型 → 参考已有 adapter 复制：
+
+| 新 Provider 类型 | 参考实现 | 适用原因 |
+|------------------|---------|---------|
+| HTTP 异步 + 状态字段 + 字符串 error code | `vidu/adapter.go` | post-alignment 最干净的实现，演示 `{code,reason,message}` 信封解析 + 字符串 reason 路由 |
+| HTTP 异步 + 嵌套响应（`output.*`） | `wan/adapter.go` | Dashscope 模式：`output.task_id` / `output.task_status` / `output.code`，演示嵌套 envelope 解析 |
+| HTTP 同步（图像生成立即返回） | `duomi/adapter.go`（nano-banana 分支） | 演示 `sync:<base64>` ExternalID 短路：Submit 返回的"任务 id"实际上携带最终结果，Poll 识别前缀直接 Succeeded |
+| 浏览器自动化 / 非 HTTP | `pixfree/adapter.go` | 演示 Temporal stealthActivity 委派模式 |
+| 内容审核是 success 中的 flag（非 error code） | `wavespeed/adapter.go` | 演示 `has_nsfw_contents[]` 后置探测 + 合成 `nsfw` provider_error_code |
+| Bearer auth + 自定义 header | `wan/adapter.go`（`X-DashScope-Async`） | 演示 Provider 强制必填的扩展 header |
+| Token auth（字面量 `Token ` 前缀） | `vidu/adapter.go` | 演示 auth scheme 不是 Bearer 也不是裸 token 的常量 prefix |
+| Query string auth（`?key=`） | `duomi/adapter.go` | 演示通过 lane `auth_config.location: query` 让 base 适配器自动 inject |
+| HTTP 200 + `error` 字段表达业务失败 | `yunwu/adapter.go` | 演示强制 `Status=Failed` 的 invariant（避免 poll loop 吞噬终态错误） |
+
+---
+
+## Section 5: 验收 Checklist（Pre-PR）
+
+提 PR 前**逐条勾选**。任何一条没勾，禁止 PR。
+
+- [ ] `go vet ./...` 通过
+- [ ] `go build ./...` 通过
+- [ ] `go test ./internal/platform/mediagen/...` 通过
+- [ ] 迁移在 dev DB apply 成功（`schema_migrations.dirty = false`）
+- [ ] 没有 `// TODO` / `// FIXME` / `// 暂` / `// 后续` 注释（D1）
+- [ ] 没有 `strings.Contains` 做错误分类（§2.2）
+- [ ] 没有 `gin.H` 出现在 adapter（R1，本来 adapter 就不应该有）
+- [ ] 所有 `map[string]any` 字段 / 参数都有 `//nolint:T1` 说明（T1）
+- [ ] 每次 `base.MapProviderFailure` 调用都传了 `req.FailureMapper`（§2.4）
+- [ ] `ProviderErrorCode` 用的是**官方文档明文定义的字符串 code**（不是数字字符串、不是编造名）
+- [ ] lane revision 的 `failure_mapper` JSON 列出了 Provider 文档中所有错误码组（按 §B.3 模板）
+- [ ] Submit / Poll 成功路径填充了 `ProviderTelemetry` 全部 4 字段
+- [ ] Submit / Poll 失败路径**不**填 Telemetry（让 `*ProviderError` 携带 StatusCode）
+- [ ] adapter 没有 hardcode submit 端点常量（§2.3）
+- [ ] `Capabilities()` 反映 Provider 真实模型目录（不是 stale defaults）
+- [ ] adapter unit test 覆盖 §H.1 全部 10 项最小用例
+- [ ] `make wire` 重新生成且无 diff 残留
+- [ ] `/self-review` 跑过（如果是 Level B 设计）
+
+#### Admin UI 验收（§L 走完之后）
+
+- [ ] `/ai/runtime/providers` 列出新 Provider，状态标签为 `active`（绿色）
+- [ ] `/ai/runtime/lanes` 列出新 lane，`published_revision_no` 显示具体版本号（不为空）
+- [ ] `/ai/runtime/lanes/:laneCode/revisions` 工作台正常打开（顶部 context strip 显示 Provider / Lane / Published rev；左侧 RevisionTimeline 倒序排列；右侧 11-tab 编辑器全部加载无报错）
+- [ ] Dry-run 抽屉用样本输入返回合理 `normalized_request` + `applied_transforms`，"Copy as cURL" 可一键复用
+- [ ] Publish 后 Lane.`published_revision_id` 翻新；Rollback 后恢复上一 published revision
+- [ ] `/ai/runtime/generations` 用新 lane 跑一次真实 Generation，状态最终落到 `succeeded` / `failed`（非 `pending` 卡住）
+- [ ] `/ai/runtime/execution-logs` 顶级搜索按 `lane_code` 过滤可见对应 phase（submit / poll）日志，request / response snapshot 可侧拉展开
+
+---
+
+## Section 6: Common Pitfalls（lessons learned）
+
+post-alignment 过程踩到的 5 个最大坑——新 Provider 接入时**主动避开**：
+
+### Pitfall 1: 自创 reason code
+
+**症状**：在 lane mapper 里写 `"reason_code": "credit_insufficient"` / `"safety_violation"` / `"output_invalid"`。
+**问题**：不在 `domain.FailureReasonCode` 9 类中，`ResolveFailureReasonCode` 不识别，最终落到默认分支 = `provider_error`。
+**正确**：只用 9 类合法值。Auth/billing/bad_input 类别全部映射到 `provider_error`（HTTP 4xx 不可重试）。新增类别需要 domain 层改造，不在单 Provider 接入范围。
+
+### Pitfall 2: 文案匹配错误分类
+
+**症状**：`if strings.Contains(message, "rate limit") { return rateLimit }`。
+**问题**：Provider 文案 i18n / 改版 / 不同 endpoint 文案不一致 → 系统行为漂移 → 排障时要去 grep 哪些字符串还在用。
+**正确**：100% 走结构化信号——sentinel error、typed `ApplicationError`、JSON envelope code。文案只用于 logging。
+
+### Pitfall 3: `LaneMapper: nil`
+
+**症状**：`base.MapProviderFailure(base.FailureContext{ ... /* 没传 LaneMapper */ })`。
+**问题**：lane snapshot 里精心配的 mapper rules 全部失效，Provider 错误一律落到默认分支。
+**正确**：每个 `MapProviderFailure` 调用必须 `LaneMapper: req.FailureMapper`。Code review 时 grep 这个 pattern。
+
+### Pitfall 4: Adapter hardcode submit endpoint
+
+**症状**：`const submitEndpoint = "/v1/predictions"` + `req.Endpoint` 字段被忽略。
+**问题**：lane revision 的 `endpoint_config.submit_path` 形同虚设；不同 lane 用同一 endpoint；DB 改路径不生效。
+**正确**：Submit 入口校验 `req.Endpoint != ""`；adapter 不存在 `submitEndpoint` 常量。Poll endpoint 仅当全 Provider 共享同一路由时允许 const（如 wan / wavespeed）。
+
+### Pitfall 5: status 与 error 字段独立处理
+
+**症状**：HTTP 200 + body `{"status":"processing","error":"NSFW detected"}` —— adapter 看 `status="processing"` 就返回 `Processing`，丢了 `error`。
+**问题**：activity poll loop 会一直轮询直到超时，吞噬掉了终态错误信号。
+**正确**：error/reason 字段非空时**强制** `Status=Failed`（参考 yunwu adapter 的 `pollResp.Status = domain.StatusFailed` + 注释引用 Stripe/OpenAI/Bedrock 行业惯例）。
+
+---
+
+## Section 8: 新增 Admin 功能（admin-integrated 阶段）
+
+> 适用提交：`fc1ee8d6`（admin 配置面板首发）/ `68fb828b`（rollback / diff / dry-run + JSON Schema）/ `b4d77656`（cross-generation execution log）/ `bb9e44a6`（permission seed + enum）/ `211ed024`（DTO snake_case 锁定）。
+
+### 8.1 Lane Revision 编排工作台（核心 XL 页面）
+
+**路由**：`/ai/runtime/lanes/:laneCode/revisions`
+
+**布局**：
+- **顶部 Context Strip**：固定显示当前 Provider / Lane / Published revision number，导航不丢失上下文
+- **左侧 RevisionTimeline**：vertical timeline，倒序排列所有 revision；每条带状态徽章（`draft` / `published` / `superseded` / `rolled_back`）；点击切换右侧编辑器内容
+- **右侧 11-tab 编辑器**：Endpoints / Auth / Submit / Poll / Response / Failure / Request Mapper / Reliability / Telemetry / Diff / Dry-run
+- **右上 Action Bar**：Save Draft / Publish / Rollback / New Revision / Dry-run
+
+**为什么是工作台而不是表单**：lane revision 跨 12 个 JSONB 字段，互相之间有强语义耦合（如 `failure_mapper.rules.reason_code` 必须 ⊂ `retry_policy.retryable_codes` 白名单 + §2.5 9 类）。把它们集中到一个屏幕、配合 Diff 与 Dry-run 即时验证，是行业惯例（参考 AWS Step Functions Workflow Studio、Stripe Workbench）。
+
+### 8.2 9 个可视化编辑器组件（components/platform/）
+
+| 组件 | 对应字段 | 风格参考 |
+|------|---------|---------|
+| `AuthProfileBindingEditor` | Provider.`auth_profiles.{submit,poll}.bindings[]` | AWS IAM Role Policy 行级编辑：`location` / `name` / `value_prefix` / `secret_ref` 四列 |
+| `FailureMapperRuleBuilder` | LaneRevision.`failure_mapper.rules[]` | Stripe Radar 规则编辑：`when http_status / provider_error_code / provider_status IN [...] THEN reason_code` |
+| `RequestMapperEditor` | LaneRevision.`request_mapper.transforms[]` | `from_path` → `to_path` + transform 列；JSONPath 输入即时校验 |
+| `ResponseNormalizerEditor` | LaneRevision.`response_normalizer.paths` | `status` / `output` / `error` 三个 JSONPath；右侧 sample test pane 粘贴一段响应即时验证抽取结果 |
+| `RetryPolicyEditor` | LaneRevision.`retry_policy` | ECharts log-scale backoff 曲线可视化（max_attempts / initial / multiplier / cap 四参数即时联动） |
+| `RevisionTimeline` | 全部 revisions | 垂直时间轴 + 状态徽章 |
+| `RevisionDiffViewer` | 任意两 revision | Monaco editor diff 视图（左 base / 右 compare） |
+| `LaneRevisionPublishDialog` | publish 操作 | 确认 modal，列出当前 vs draft 差异要点 |
+| `LaneRevisionDryRunDrawer` | dry-run 操作 | 抽屉表单：sample input → normalized_request + applied_transforms + cURL one-click copy |
+
+### 8.3 Dry-run 流程（不调用 Provider 不写库）
+
+```
+Operator 在工作台填好 draft → 点击 Dry-run
+  ↓
+admin-api: POST /admin/ai/provider-lanes/:id/revisions/:revisionId/dry-run
+  权限: ai_lane:dry_run（与 write / publish 解耦，运营可独立授权）
+  ↓
+Service: 构造一个虚拟 SubmitRequest (sample input + draft revision snapshot)
+         → 跑 request_mapper transforms
+         → 跑 auth_config bindings 注入
+         → 跑 endpoint_config submit_path 替换
+         → **不发起真实 HTTP / 不写 p_mediagen_execution_logs**
+  ↓
+返回: { normalized_request, applied_transforms[], curl_template, validation_warnings[] }
+```
+
+行业对齐：AWS Step Functions Workflow Studio "Test State"、Stripe Workbench "Simulator"。dry-run 是只读语义，因此走独立 `ai_lane:dry_run` 权限码（commit `bb9e44a6` 迁移 484 已注入到 admin / super_admin role）。
+
+### 8.4 Diff between revisions
+
+`GET /admin/ai/provider-lanes/:id/revisions/:revisionId/diff?against=:other`（权限 `ai_lane:read`）
+
+返回结构（与前端 DTO snake_case 对齐）：
+```json
+{
+  "left_revision_id": 42,
+  "right_revision_id": 41,
+  "changes": {
+    "failure_mapper.rules[2].reason_code": { "before": "provider_error", "after": "rate_limit" },
+    "retry_policy.max_attempts": { "before": 3, "after": 5 }
+  }
+}
+```
+
+工作台 Diff tab 内嵌 `RevisionDiffViewer`（Monaco）展示 left/right 两份原始 JSON 的差异，配合 `changes` 字段做高亮跳转。
+
+### 8.5 Rollback 安全护栏
+
+- 端点：`POST /admin/ai/provider-lanes/:id/revisions/:revisionId/rollback`（权限 `ai_lane:rollback`）
+- 服务端先校验：当前 lane 必须存在**至少一条** prior `published` revision，否则返回 `apierror.Conflict("rollback_requires_prior_published")`
+- 触发后：`previous published revision`（按 `published_at` 倒数第二条）变回 `published` 状态，当前 active revision 标记 `rolled_back`
+- 审计：通过 DomainEvent envelope `AuditChanges` 写入 `sys_audit_logs`（不走 `audit.Enrich()`，遵循 CloudTrail Envelope Pattern）
+
+### 8.6 Cross-generation Execution Log Search
+
+**路由**：`/ai/runtime/execution-logs`（顶级，非 generation 详情子页）
+**端点**：`GET /admin/v1/mediagen/execution-logs`（权限 `mediagen:execution_log:read`）
+
+排障驱动：当某条 lane 在线上突然失败率上升，SRE 不需要先逐条 generation 点进去查 —— 直接用 `lane_code` + `phase`（submit / poll）+ `outcome`（success / failure）+ 时间窗口在顶级搜索，命中后侧拉展开 request / response snapshot。
+
+支撑迁移：`000483_extend_p_mediagen_execution_logs_phase_lane.up.sql` 给 `p_mediagen_execution_logs` 加了：
+- `phase VARCHAR(20)` 列（值域：`submit` / `poll` / `cancel`，对应 `DomainMediagenExecutionLogPhase` 枚举）
+- `lane_code VARCHAR(120)` 列（冗余 lane.code，避免 join）
+- `outcome VARCHAR(20)` 列（对应 `DomainMediagenExecutionOutcome` 枚举）
+- 复合索引 `(started_at DESC, lane_code)`，命中"按时间倒序看某 lane 全部日志"的高频查询模式
+
+### 8.7 Provider / Model Toggle
+
+- `POST /admin/ai/providers/:id/toggle`（权限 `ai_provider:write`）
+- `POST /admin/ai/models/:id/toggle`（权限 `ai_model:write`）
+
+行级灰度开关，比 Update 接口更安全（toggle 不接受任何其他字段，只翻 `status` 一列），与 GitHub `enable/disable` workflow 风格对齐。
+
+### 8.8 服务端 JSON Schema 强校验
+
+见 §2.9 不变量 I-9。Save Draft / Publish 都走 `ValidateLaneRevisionFields`，bad config 在 admin UI 立即返回 `apierror.BadRequest("lane_revision_invalid", "<dot.path>")`，前端按 `path` 在对应 tab 高亮报错字段。**这是 D7（zero-tolerance for stub config）的工程化兜底**。
+
+---
+
+## Section 7: 参考资料
+
+- `internal/platform/mediagen/domain/provider_request.go` —— SubmitRequest / PollRequest / CancelRequest / ProviderTelemetry 真实定义
+- `internal/platform/mediagen/domain/failure_reason.go` —— FailureReasonCode 9 类枚举与 ResolveFailureReasonCode
+- `internal/platform/mediagen/infrastructure/providers/base/failure_mapping.go` —— MapProviderFailure 实现
+- `internal/platform/mediagen/infrastructure/providers/base/adapter.go` —— Adapter 基类
+- `internal/platform/mediagen/infrastructure/providers/registry.go` —— Wire ProviderSet 注册点
+- `internal/platform/ai/aiconfig/lane_revision_validator.go` —— 12 JSONB 字段服务端校验（§2.9 / I-9）
+- `internal/platform/ai/aiconfig/router.go` —— `/admin/ai/providers/*` + `/admin/ai/provider-lanes/*` 路由 + RBAC 绑定
+- `internal/platform/mediagen/interfaces/adminapi/routes.go` —— `/admin/v1/mediagen/generations` + `/execution-logs` 路由
+- `admin/apps/web-antd/src/views/ai/runtime/lanes/[code]/revisions/index.vue` —— Lane Revision 工作台 XL 页面
+- `admin/apps/web-antd/src/components/platform/` —— 9 个可视化编辑器组件（§8.2）
+- `admin/apps/web-antd/src/constants/permission-codes.ts` —— `MEDIAGEN_*` 权限码常量
+- `migrations/000442_create_p_ai_provider_lanes.up.sql` —— lanes / lane_revisions DDL
+- `migrations/000445_hard_cut_runtime_profile_steps_to_lane_refs.up.sql` —— bulk lane seed
+- `migrations/000472_seed_provider_lane_failure_mapper.up.sql` —— failure_mapper backfill
+- `migrations/000473_add_generation_transport_retry_count.up.sql` —— transport_retry_count 列
+- `migrations/000483_extend_p_mediagen_execution_logs_phase_lane.up.sql` —— execution_log phase + lane_code + 复合索引
+- `migrations/000484_seed_ai_lane_dry_run_permission.up.sql` —— `ai_lane:rollback` + `ai_lane:dry_run` 权限种子
+- 短表速查：`backend/.claude/docs/mediagen-provider-quick-reference.md`
+
+---
+
+## Appendix A: 提交参考链
+
+post-alignment 与 admin-integrated 两个阶段的关键提交（按时间倒序，最新 → 最旧）：
+
+| Commit | 说明 |
+|--------|-----|
+| `211ed024` | admin mediagen 合规清理 + Provider/Lane/LaneRevision DTO snake_case 与后端对齐 |
+| `bb9e44a6` | 注入 `ai_lane:rollback` 权限 + 注册 `DomainMediagenExecutionLogPhase` / `DomainMediagenExecutionOutcome` 枚举 |
+| `fc1ee8d6` | admin Provider / Lane / Lane-Revision 配置面板首发（UI 全流程） |
+| `b4d77656` | mediagen admin cross-generation execution log 搜索 + 可观测性 schema 扩展 |
+| `68fb828b` | aiconfig 增加 lane revision rollback / diff / dry-run + JSON Schema 校验 + toggle 过滤 |
+| `7526a1ed` | mediagen Provider Onboarding SOP 首版 + capability matrix |
+| `3ba754f7` | dedupe `firstNonEmpty` + `statusCodeOrDefault` 到 `providers/base/util` |
+| `84953e39` | wan adapter 重写为 Alibaba Dashscope 规范 |
+| `4d910338` | vidu adapter 对齐 Shengshu Vidu Studio 官方 API |
+| `9e621fc8` | wavespeed adapter 对齐官方 API + NSFW 后置探测 |
+| `60bf4b09` | duomi adapter 对齐官方 API（doc/26 / 52 / 85 / 86） |
+| `a0374e88` | 清理 fal / replicate / runway 三个未使用的 Provider |
+| `f2338a6d` | Stripe 风格 Provider failure mapping 标准化（post-alignment 起点） |
+
+---
+
+> **本 SOP 是 mediagen Provider 接入的唯一权威流程**。任何脱离本流程的快速接入都会导致：lane snapshot 与 adapter 行为不一致、failure_mapper 不生效、telemetry 缺失、credit 计费链路受影响。整个 alignment 批次（commits `f2338a6d` → `211ed024`）的工作量证明了这一点。