Implement unified story generation flow

docs/planning/demo-checklist.md

@@ -2,6 +2,8 @@
 
 **目标**: 演示前用 5-10 分钟确认本地 Docker 环境、核心生成链路和讲解材料处于可展示状态。
 
+**当前演示口径（2026-05-06）**: 主生成链路可作为稳定主线展示；语音共创是 Phase A Alpha，可演示回合式共创、文本降级、上传转写、观测指标和保存为 Story。管理端已能看到 ASR 维度运营摘要。外部 Registry 阻塞已通过可配置基础镜像与 npm registry 修复；当前代码 `docker compose up -d --build` 和 `SMOKE_VOICE=1` 均已通过。
+
 ---
 
 ## 1. 演示前准备
@@ -53,6 +55,12 @@ SMOKE_AUDIO=1 ./scripts/demo_smoke.sh
 SMOKE_VOICE=1 ./scripts/demo_smoke.sh
 ```
 
+需要检查真实 OpenAI ASR Key 环境时：
+
+```bash
+SMOKE_REAL_ASR=1 ./scripts/demo_smoke.sh
+```
+
 需要同时检查 TTS 和语音共创时：
 
 ```bash
@@ -81,8 +89,34 @@ SMOKE_AUDIO=1 SMOKE_VOICE=1 ./scripts/demo_smoke.sh
 - [ ] 如果启用 `SMOKE_VOICE=1`，语音共创会话可完成文本 fallback、上传回合、analytics 和 finalize 到 Story
 - [ ] 如果启用 `SMOKE_VOICE=1`，analytics 返回输入构成、语音时长、Provider 分布、ASR/TTS 成功率和低置信度确认率
 - [ ] 如果启用 `SMOKE_VOICE=1`，analytics 支持按 `provider` 和 `session_status` 筛选
+- [ ] 如果启用 `SMOKE_REAL_ASR=1`，上传回合返回 `transcription_provider=openai_asr`，转写文本非空
+- [ ] 如果启用 `SMOKE_REAL_ASR=1`，`/api/voice-sessions/analytics?provider=openai_asr` 能看到上传回合
+- [ ] Admin Provider analytics 在 `capability=asr` 下能看到语音会话数、上传回合数、ASR 成功/失败和失败原因
+- [ ] 真实 ASR 环境失败时，脚本输出包含上传响应、Voice Session 事件和 Admin ASR failure reasons
 - [ ] 验证结果已记录到 `docs/planning/demo-validation-log.md`
 
+真实 ASR 环境变量最小集：
+
+```env
+ASR_PROVIDERS=["openai_asr", "demo"]
+OPENAI_API_KEY=sk-...
+OPENAI_API_BASE=
+VOICE_TRANSCRIPTION_MODE=provider
+VOICE_TRANSCRIPTION_MODEL=gpt-4o-mini-transcribe
+VOICE_TRANSCRIPTION_LANGUAGE=zh
+```
+
+改完 `backend/.env` 后重启 backend/worker。若在 Admin Provider 表里改过 ASR 配置，先 `curl -u admin:admin -X POST http://localhost:52800/admin/providers/reload`，再重启 API 容器/进程，避免运行中缓存仍指向旧 provider。
+
+真实 ASR 常见失败口径：
+
+- `OPENAI_API_KEY 未配置`：容器或本机 API 没读到 key。
+- `HTTP 401/403`：key 错误、项目权限或网关鉴权失败。
+- `HTTP 429` / `insufficient_quota`：额度或限流问题。
+- `model_not_found`：`VOICE_TRANSCRIPTION_MODEL` 当前 key 不可用，先换回 `gpt-4o-mini-transcribe`。
+- 网络连接失败：检查代理、DNS、`OPENAI_API_BASE` 是否必须带 `/v1`。
+- 音频格式失败：传 `REAL_ASR_AUDIO_FILE=/path/to/sample.m4a` 换一段真实短音频复测。
+
 ---
 
 ## 3. 手动演示路径
@@ -121,6 +155,7 @@ SMOKE_AUDIO=1 SMOKE_VOICE=1 ./scripts/demo_smoke.sh
    - Provider: 具体供应商配置
    - Adapter: API 调用实现
    - Routing Policy: 优先级/成本/延迟/轮询
+4. 切到“语音识别”能力，说明 Voice Studio 上传转写的 ASR 调用已进入管理端运营摘要，可看语音会话、上传回合、失败原因和成本归因。
 
 ### 路径 D: 语音共创 Alpha
 
@@ -136,6 +171,7 @@ SMOKE_AUDIO=1 SMOKE_VOICE=1 ./scripts/demo_smoke.sh
 4. 演示低置信度确认：说明系统会提示“本轮系统理解为”，家长可选择继续、重说或改成文本。
 5. 点击结束并保存，确认正式 Story 进入故事库。
 6. 打开生成轨迹，说明语音共创 finalize 后的封面资产补全已经接回统一 generation job。
+7. 回到 Admin 的语音识别摘要，说明 Alpha 阶段保留 demo fallback，同时为真实 ASR Provider 验收预留运营视图。
 
 ---
 
@@ -157,7 +193,7 @@ DreamWeaver 是面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲
 
 ### 2:20 - 3:00 取舍与下一步
 
-求职版优先稳定闭环和可解释性，不做支付、多租户和复杂监控。现在 job/event 已能查询 workflow、资产补全、provider 调用轨迹和聚合指标，统一生成已迁移到后台 worker，取消/重试队列也已打通；用户端可看跨故事运营摘要，管理端可看当前环境跨用户 Provider dashboard。下一步应补跨环境汇聚、断点续跑和更完整监控。
+求职版优先稳定闭环和可解释性，不做支付、多租户和复杂监控。现在 job/event 已能查询 workflow、资产补全、provider 调用轨迹和聚合指标，统一生成已迁移到后台 worker，取消/重试队列也已打通；Voice Studio 已进入 Phase A Alpha，可演示回合式共创和保存为 Story；用户端可看跨故事运营摘要，管理端可看当前环境跨用户 Provider dashboard 和 ASR 摘要。下一步应补真实 ASR Key 环境验收、跨环境 Provider 汇聚、断点续跑和更完整监控。
 
 ---
 
@@ -170,6 +206,7 @@ DreamWeaver 是面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲
 | 图片 provider 失败 | 展示 degraded completed 与 retry 机制 |
 | 录音或 ASR 不稳定 | 切到文本 fallback，说明 Alpha 阶段已保留降级路径 |
 | 语音共创低置信度卡住 | 使用“按这个理解继续”或“改成文本输入”完成本轮 |
+| Docker Hub 拉取超时 | 当前 Dockerfile/Compose 支持基础镜像覆盖；本机 `.env` 已配置代理源，可直接 `docker compose up -d --build` |
 | Docker 冷启动慢 | 演示前提前运行 smoke 脚本并保持容器运行 |
 | Admin 页面不适合主展示 | 只用 Provider 分层说明辅助讲系统设计 |
 | 面试官追问生产部署 | 明确当前是求职版 MVP，本轮重点是产品闭环和系统边界 |