dreamweaver/docs/planning/demo-validation-log.md

Demo 验证记录

这份记录用于演示前快速说明“当前本地 Docker 环境已经验证到什么程度”。新的验证记录按时间倒序追加。

2026-04-24

补充验证：

• 已拉取远端 main 到 7e450aa fix: stabilize auth and generation workflows。
• 用户端 npm run build 通过，包含最新 Voice Studio、登录态修复和 generation trace 变更。
• 管理端首次 npm run build 因 Rollup Linux optional dependency 缺失失败；执行 npm install 补齐 @rollup/rollup-linux-x64-gnu 后，管理端 npm run build 通过。
• 后端当前仓库内 .venv 是 Windows 虚拟环境结构，WSL/bash 下无法直接执行 .venv/bin/python；系统也没有全局 pytest。尝试创建 Linux venv 时发现当前 WSL 缺少 python3.12-venv，尝试使用 Docker 时发现当前 WSL 未启用 Docker Desktop 集成。本轮未完成后端 pytest，需要后续在 Linux venv、Docker 或 Windows PowerShell 环境补跑。
• 语音共创 PRD 已从 Discovery Track 更新为 Phase A Alpha，并补充 Alpha 验收矩阵、退出标准和未完成项。
• 演示 checklist 已新增 Voice Studio 入口、语音共创 Alpha 手动演示路径和风险预案。
• scripts/demo_smoke.sh 已新增可选 SMOKE_VOICE=1 分支，覆盖 Voice Session 创建、文本 fallback、上传回合 demo transcript hint、会话 detail/events、voice analytics、finalize 到 Story 和故事可读性断言。
• ASR 已纳入 Provider 能力分层：默认 ASR_PROVIDERS=["demo"]，真实转写可配置 ASR_PROVIDERS=["openai_asr", "demo"] 与 OPENAI_API_KEY。
• 管理端 Provider UI 已补 asr：运营摘要支持按语音识别筛选，Provider tab 可创建/查看 ASR provider，用户端嵌入的 Provider 管理页同步新增 asr tab。
• bash -n scripts/demo_smoke.sh 通过。

执行命令：

cd frontend && npm run build
cd admin-frontend && npm run build
cd admin-frontend && npm install
cd admin-frontend && npm run build
cd backend && pytest -q
cd backend && ./.venv/bin/python --version
cd backend && python3 -m venv .venv-linux
docker compose ps
bash -n scripts/demo_smoke.sh

结果：

• 用户端 vue-tsc && vite build 通过。
• 管理端 vue-tsc && vite build 在补依赖后通过。
• scripts/demo_smoke.sh shell 语法检查通过；受当前 WSL 未启用 Docker 影响，未执行完整接口 smoke。
• 后端测试未运行成功，原因是当前执行环境缺少 Linux 可用的 Python dev venv / pytest，且 WSL 未启用 Docker。

后续补验建议：

• 在 WSL 下先安装 python3.12-venv，再执行 cd backend && python3 -m venv .venv-linux && .venv-linux/bin/pip install -e ".[dev]" && .venv-linux/bin/python -m pytest -q。
• 或在 Windows PowerShell 下执行 cd backend; .\.venv\Scripts\python.exe -m pytest -q。
• 后端通过后，再运行 docker compose up -d --build、SMOKE_VOICE=1 ./scripts/demo_smoke.sh，并手动走一遍 Voice Studio Alpha 路径。

2026-04-18

补充验证：

• 新增跨故事 Provider analytics 后，backend/.venv/bin/python -m pytest backend/tests -q 通过，83 个测试通过。
• 用户端与管理端 npm run build 均通过；生成轨迹组件已支持未终止任务自动轮询。
• docker compose up -d --build 已再次用当前代码重建本地演示栈。
• ./scripts/demo_smoke.sh 再次通过，并新增断言 GET /api/generations/provider-analytics 可以返回跨故事总调用、成功率、任务数、故事数和 Provider 明细。
• 新增 Week 2-4 总 backlog 后，backend/.venv/bin/python -m pytest backend/tests -q 通过，85 个测试通过。
• 音频缓存治理首版已验证：GET /api/audio/{story_id}/status 查询状态不触发生成，DELETE /api/audio/{story_id}/cache 可清理缓存并让音频重新进入可补全状态。
• 时间线联动已验证：阅读事件会生成更完整的 recent_story 记忆，孩子时间线会展示阅读记录和记忆沉淀。
• ./scripts/demo_smoke.sh 已覆盖音频缓存状态查询。
• Week 4 Demo 包装已完成：新增架构说明、Demo 包装文档、Week 4 sprint review，用户端和管理端绘本阅读器支持阅读位置恢复。
• Week 4 最终回归通过：后端全量测试 85 passed，ruff 通过，用户端/管理端构建通过，docker compose up -d --build 和 ./scripts/demo_smoke.sh 通过。
• 继续优化后再次验证：Provider analytics 已支持时间窗口与能力筛选、失败原因摘要；音频缓存已加入 TTL 配置和后台 prune 任务。
• 新一轮优化验证通过：新增 GET /api/generations/ops-summary，故事库已展示最近失败与卡住任务摘要；生成任务已支持 stale 自动收敛和重复资产任务保护。
• 后端新增 partial_ready、text_status 与迁移 0012_story_text_status 后，backend/.venv/bin/python -m pytest backend/tests -q 通过，82 个测试通过。
• backend/.venv/bin/python -m ruff check backend/app backend/tests backend/alembic/versions/0012_add_story_text_status_and_partial_ready.py 通过。
• 用户端与管理端 npm run build 均通过。
• docker compose up -d --build 已用当前代码重建本地演示栈。
• 当前本地 Docker 数据卷来自早期 create_all，缺少 alembic_version 且旧 stories 表没有 text_status；本轮已为演示库补齐 text_status、回填状态，并 alembic stamp head 到 0012_story_text_status。
• ./scripts/demo_smoke.sh 通过：普通故事以 partial_ready 可读返回，封面补全后仍可读且音频待补；绘本无图时 partial_ready，插图补全后 completed；generation job、story job history 和 provider stats 均可查询。

验证范围：

• 用户前端 Docker 生产构建
• 管理前端 Docker 生产构建
• 用户端与管理端生成/资产状态体验一致性
• 后端 Docker 镜像构建与服务重启
• 后端 lint 与测试
• Pydantic v2 兼容性 warning 清理
• Dockerfile build warning 清理
• 管理后台弱默认密码防护
• Generation job/event 轻量落库
• retryable_assets 标准响应字段
• 后端统一生成接口
• 故事封面资产补全
• 故事音频资产补全
• 绘本文字生成
• 绘本封面和分页插图补全
• 故事列表读取
• Provider capability policy

执行命令：

docker compose build frontend
docker compose build frontend frontend-admin
docker compose build backend backend-admin worker celery-beat
docker compose up -d backend backend-admin worker celery-beat frontend frontend-admin
cd backend && .venv/bin/python -m ruff check app tests
cd backend && .venv/bin/python -m pytest -q
SMOKE_AUDIO=1 ./scripts/demo_smoke.sh

结果：

• vue-tsc 通过。
• 用户端与管理端 vite build 通过。
• Docker 前端镜像 dreamweaver-frontend:dev 构建通过。
• Docker 管理前端镜像 dreamweaver-admin-frontend:dev 构建通过。
• Docker 后端镜像 dreamweaver-backend:dev 构建通过。
• ruff check app tests 通过。
• pytest -q 通过，73 个测试通过，Pydantic v2 deprecation warning 已清零。
• SMOKE_AUDIO=1 ./scripts/demo_smoke.sh 通过。
• smoke 会断言 retryable_assets 在故事、音频、绘本补全前后按预期变化。
• 本地用户端可通过 http://localhost:52080 访问。
• 本地管理端可通过 http://localhost:52888 访问。
• 技术债扫描未发现 class Config、TODO、FIXME、旧 Issue 注释或 Dockerfile FROM ... as。
• 后端不再内置 admin123 管理密码；非 debug 环境开启管理后台时会拒绝空/弱密码。
• 统一生成和资产重试会写入 generation_jobs 与 generation_job_events。
• API 响应返回 retryable_assets，前端按标准字段展示补全/重试入口。

已确认的演示能力：

• 普通故事可以先生成可读正文。
• 封面和音频可以作为资产单独重试。
• 绘本可以生成 6 页文本并补全全部插图。
• 故事列表能看到最新生成结果。
• 时间线中的绘本事件可以直接进入按 ID 恢复的绘本阅读器。

限制：

• 本机浏览器自动化脚本默认寻找标准版 Chrome；当前电脑安装的是 Google Chrome Beta，所以本轮没有生成 CDP 截图。