refactor: separate provider capability policy

docs/README.md

@@ -20,6 +20,9 @@
 - `technical/memory-system-dev.md`
   记忆系统技术说明。用于后续继续做孩子档案、故事宇宙和个性化生成。
 
+- `technical/provider-routing.md`
+  Provider Routing 技术说明。用于解释 Capability / Provider / Adapter / Routing Policy 的职责边界。
+
 ## 维护规则
 
 - 新 PRD 放到 `docs/product/`

docs/planning/week-1-execution-backlog.md

@@ -53,7 +53,7 @@
 - 已新增数据库迁移：
   - `0009_add_story_generation_statuses.py`
   - `0010_add_story_audio_cache_path.py`
-- 已完成一轮后端回归验证：`backend/` 下 `pytest -q` 结果为 `66 passed`
+- 已完成一轮后端回归验证：`backend/` 下 `pytest -q` 结果为 `71 passed`
 - 已完成全量后端 lint 清理：`ruff check app tests` 可通过
 - 已修复 admin-frontend 构建阻塞，主前端与管理端前端均可生产构建
 - 已落地首版统一资产重试入口：`POST /api/stories/{story_id}/assets/retry`
@@ -70,6 +70,11 @@
   - 绘本缺失插图补全
   - 故事音频缓存读取与 TTS 生成
 - 已引入首版服务层 `AssetCompletionResult`，用于统一表达资产补全结果
+- 已完成 Provider 分层首版落地：
+  - 新增 `provider_policy.py`，定义 Capability / Routing Policy / 默认 Provider 顺序
+  - Provider Router 专注运行时 failover、熔断、成本和指标记录
+  - 新增 `/admin/providers/capabilities` 展示能力分层
+  - 新增 `docs/technical/provider-routing.md` 作为术语表和分层说明
 
 ### What Is In Progress
 
@@ -79,7 +84,6 @@
 
 ### What Is Still Pending
 
-- Provider 的 Capability / Provider / Routing Policy 边界整理
 - Week 2 可直接执行的开发任务表
 - 演示 checklist 与最终收尾策略
 
@@ -178,7 +182,7 @@
 
 - [ ] 明确 admin-frontend 的处理方案
 - [x] 明确 Storybook 恢复方案
-- [ ] 明确 Provider 重构边界
+- [x] 明确 Provider 重构边界
 
 ---
 
@@ -191,7 +195,7 @@
 | W1-03 | Product / System | 盘点现有生成路径：普通故事、完整生成、绘本生成 | 现状流程图或对照表 | P0 | 0.5d | Done |
 | W1-04 | Product / System | 定义统一 Generation Workflow 状态模型 | 状态流转说明 | P0 | 1.0d | Done |
 | W1-05 | Product / Backend | 定义统一工作流下的 API / 数据结构影响 | 接口与模型变更清单 | P0 | 0.5d | In Progress |
-| W1-06 | Product / Backend | 梳理 Provider 概念层：Capability / Provider / Routing Policy | 分层图与术语表 | P1 | 0.5d | Pending |
+| W1-06 | Product / Backend | 梳理 Provider 概念层：Capability / Provider / Routing Policy | 分层图与术语表 | P1 | 0.5d | Done |
 | W1-07 | Product / Frontend | 梳理 Storybook 当前问题与恢复方案 | 恢复方案说明 | P0 | 0.5d | Done |
 | W1-08 | Product / Frontend | 确认 admin 前端是修复、裁剪还是暂时降级 | 决策记录 | P0 | 0.5d | Done |
 | W1-09 | Planning | 产出 Week 2 开发任务清单 | 下周 backlog | P1 | 0.5d | In Progress |

docs/product/job-search-relaunch-prd.md

@@ -182,10 +182,10 @@ DreamWeaver 是一款面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴
 
 **Acceptance Criteria**
 
-- [ ] Provider 配置以能力、供应商、模型配置的方式组织
-- [ ] 路由策略与凭证管理职责分离
-- [ ] 系统能清楚展示失败降级逻辑
-- [ ] 管理端或配置文档能说明当前有效供应链路
+- [x] Provider 配置以能力、供应商、模型配置的方式组织
+- [x] 路由策略与凭证管理职责分离
+- [x] 系统能清楚展示失败降级逻辑
+- [x] 管理端或配置文档能说明当前有效供应链路
 
 ---
 
@@ -443,7 +443,7 @@ DreamWeaver 是一款面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴
 ### Glossary
 
 - **Generation Workflow**: 从用户输入到文本、图片、语音完成的一整套生成流程。
-- **Capability**: 底层 AI 能力分类，如文本、图片、语音。
+- **Capability**: 底层 AI 能力分类，如文本、图片、语音、绘本结构。
 - **Provider**: 具体供应商，如 Gemini、OpenAI、MiniMax。
 - **Routing Policy**: 供应商选择与降级策略。
 - **Degraded Completion**: 资产部分失败但主结果可用的完成状态。

docs/technical/provider-routing.md

@@ -0,0 +1,63 @@
+# Provider Routing 技术说明
+
+本说明用于支撑求职版 DreamWeaver 的 Provider 分层表达。当前目标不是做复杂平台化，而是把 AI 能力供应链讲清楚、跑稳定、便于后续演进。
+
+## 核心概念
+
+| 概念 | 含义 | 当前代码位置 |
+| --- | --- | --- |
+| Capability | 产品需要的 AI 能力类型，例如文本、图片、语音、绘本结构 | `backend/app/services/provider_policy.py` |
+| Provider | 某个能力下的可调用供应商配置，例如 Gemini、OpenAI、CQTAI、MiniMax | `providers` 表与 `provider_cache.py` |
+| Adapter | 供应商调用实现，负责把统一入参翻译成具体 API 调用 | `backend/app/services/adapters/` |
+| Routing Policy | 调用前如何排序与选择 Provider，例如优先级、成本、延迟、轮询 | `provider_policy.py` + `provider_router.py` |
+| Failover | 当前 Provider 调用失败后自动尝试下一 Provider | `provider_router.py` |
+
+## 当前 Capability
+
+| Capability | 用途 | 默认 Provider | Demo Provider |
+| --- | --- | --- | --- |
+| `text` | 生成/润色儿童故事文本 | `gemini`, `openai` | `demo` |
+| `image` | 生成封面和绘本插图 | `cqtai` | `demo` |
+| `tts` | 故事语音合成 | `minimax`, `elevenlabs`, `edge_tts` | 无 |
+| `storybook` | 生成多页绘本结构和插图提示词 | `storybook_primary` | `demo` |
+
+`ENABLE_DEMO_PROVIDERS=true` 时，只会给具备 demo adapter 的能力前置 `demo` provider。TTS 暂无 demo adapter，因此不会插入不存在的 `tts:demo`。
+
+## 代码边界
+
+`provider_policy.py` 负责定义“产品级策略”：
+
+- Capability 清单
+- 默认 Provider 顺序
+- `.env` 中对应的 provider 列表字段
+- 默认 routing strategy
+- API key ref 到 settings 字段的映射
+- 哪些能力支持本地 demo provider
+
+`provider_router.py` 负责执行“运行时路由”：
+
+- 从 DB cache 或 `.env` 读取 Provider 配置
+- 构建 `AdapterConfig`
+- 按 Routing Policy 排序
+- 熔断过滤
+- 调用 adapter
+- 记录 metrics、health、cost
+- failover 并聚合错误
+
+`adapters/` 负责具体供应商 API：
+
+- 不决定业务工作流
+- 不读取用户故事上下文
+- 不负责 Provider 排序或熔断
+
+## 演进原则
+
+- 新增 AI 能力时，先在 `provider_policy.py` 增加 Capability，再注册 adapter。
+- 新增供应商时，先实现 adapter，再把默认顺序或 DB 配置接入对应 Capability。
+- 路由策略只影响调用顺序，不应该改变故事/绘本/音频的产品工作流。
+- 本轮求职版不做多租户供应商市场，也不做复杂负载均衡；优先保证能力分层清楚、失败可恢复、演示稳定。
+- 后台 `config_ref` 可以使用 adapter 别名，也可以直接使用 settings 字段名，例如 `text_api_key`、`antigravity_api_key`。
+
+## 面试表达口径
+
+DreamWeaver 的 Provider 体系不是把供应商暴露给用户，而是把多模型能力整理成稳定的产品能力。用户看到的是“生成故事、生成封面、播放语音”，系统内部才把它映射到 `text`、`image`、`tts`、`storybook` 这些 Capability，再通过 Routing Policy 选择具体 Provider 和 Adapter。