# Demo 验证记录

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

## 2026-04-28 拉取后回归与 Voice Studio 文案收敛

- 已拉取远端 `main` 到 `55ca098 Add voice analytics filters and metrics` 后完成本地回归。
- 后端复用仓库内 Windows `.venv` 执行全量测试，`118 passed`。
- 后端 `ruff check app/ tests/` 通过。
- 用户端与管理端 `npm run build` 均通过；依赖和文案收敛后再次构建通过，且不再出现 `baseline-browser-mapping` 数据偏旧提示。
- Voice Studio、生成轨迹、故事库和供应商管理页已将用户可见的 `session`、`turn`、`attention`、`fallback`、`Finalize`、`Provider` 等工程词收敛为中文表达，并补充转写来源、语音事件类型和事件状态的中文展示。
- 用户端与管理端执行依赖安全收敛后，`vite` 升至 `6.4.2`，`esbuild` 升至 `0.25.12`，`autoprefixer` 升至 `10.5.0`，`postcss` 升至 `8.5.12`，`baseline-browser-mapping` 升至 `2.10.23`。
- 用户端与管理端完整 `npm audit --registry=https://registry.npmjs.org` 均为 0 vulnerabilities。
- Alembic 当前只有一个 head：`0013_add_voice_sessions_phase_a`；迁移链从 `0012_story_text_status` 到 head 连续。
- `scripts/demo_smoke.sh` shell 语法检查通过，`curl` 与 `jq` 可用。
- 当前 WSL 发行版未启用 Docker Desktop 集成，且本地 `52000/52800/52080` 未监听；本轮无法执行完整 `SMOKE_VOICE=1 ./scripts/demo_smoke.sh`。

验证命令：

```bash
cd backend && .venv/Scripts/python.exe -m pytest
cd backend && .venv/Scripts/python.exe -m ruff check app/ tests/
cd frontend && npm run build
cd admin-frontend && npm run build
cd frontend && npm audit fix --registry=https://registry.npmjs.org
cd admin-frontend && npm audit fix --registry=https://registry.npmjs.org
cd frontend && npm install autoprefixer@latest -D --registry=https://registry.npmjs.org
cd admin-frontend && npm install autoprefixer@latest -D --registry=https://registry.npmjs.org
cd frontend && npm install vite@^6.4.2 -D --registry=https://registry.npmjs.org
cd admin-frontend && npm install vite@^6.4.2 -D --registry=https://registry.npmjs.org
cd frontend && npm audit --omit=dev --registry=https://registry.npmjs.org
cd admin-frontend && npm audit --omit=dev --registry=https://registry.npmjs.org
cd frontend && npm audit --registry=https://registry.npmjs.org
cd admin-frontend && npm audit --registry=https://registry.npmjs.org
cd backend && .venv/Scripts/python.exe -m compileall -q app tests
cd backend && .venv/Scripts/python.exe -m alembic heads
cd backend && .venv/Scripts/python.exe -m alembic history --verbose -r 0012_story_text_status:head
bash -n scripts/demo_smoke.sh
git diff --check
docker compose config --quiet
curl -fsS --max-time 2 http://localhost:52000/health
curl -fsS --max-time 2 http://localhost:52800/health
curl -fsS --max-time 2 http://localhost:52080/health
```

结果：

- `pytest` 通过，118 passed，耗时约 4 分 25 秒。
- 后端 lint、Python compileall、用户端构建、管理端构建均通过；代码/文档 diff 空白检查通过，lockfile 保持仓库既有 CRLF 行尾风格。
- 用户端与管理端构建不再出现 `baseline-browser-mapping` 数据偏旧提示。
- 用户端与管理端完整 audit 均返回 0 vulnerabilities。
- `docker compose config --quiet` 因当前 WSL 找不到 `docker` 命令未执行成功；完整 Docker demo smoke 待启用 Docker Desktop WSL 集成后补跑。

## 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` 通过。

执行命令：

```bash
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

执行命令：

```bash
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 截图。

## 2026-04-24 语音共创 Alpha 观测补强

- 今日优先级：先收束 Phase A Alpha 的可解释性，不进入 Phase B 实时化。
- 后端 `VoiceTurnSummaryResponse` 已返回用户/助手音频时长，便于定位单轮录音质量与 TTS 产物状态。
- 后端 `VoiceSessionAnalyticsResponse` 已新增用户语音总时长、平均时长、助手音频统计、转写 Provider 分布和低置信度确认率。
- 用户端 Voice Studio 观测卡片已展示平均用户语音时长、转写来源分布和确认率。
- `SMOKE_VOICE=1 ./scripts/demo_smoke.sh` 已新增语音时长与转写 Provider 分布断言。

验证命令：

```bash
cd backend && .venv/bin/pytest tests/test_voice_sessions.py -q
cd frontend && npm run build
```

结果：

- `tests/test_voice_sessions.py` 通过，15 passed，保留 1 个 SQLAlchemy/SQLite `datetime.utcnow()` 上游 deprecation warning。
- 用户端 `vue-tsc && vite build` 通过，保留 `baseline-browser-mapping` 数据偏旧提示。

## 2026-04-24 语音共创 Alpha 50 项执行池与 P1 观测扩展

- PRD 已新增 Phase A Alpha 50 项执行 Backlog，明确 P0/P1/P2、验收口径和今日执行策略。
- 后端 voice analytics 已扩展输入构成、上传语音占比、助手语音覆盖率、ASR/TTS 成功率、平均转写/意图置信度、安全介入率和失败事件分布。
- Voice Studio 已展示上传/文本构成、助手语音覆盖、ASR/TTS 成功率、平均置信度、用户/助手平均语音时长，并在单 turn 卡片展示用户/助手语音时长。
- `SMOKE_VOICE=1` smoke 已新增输入构成与 ASR/TTS 成功率断言。
- 技术方案与 demo checklist 已同步语音观测字段。

验证命令：

```bash
cd backend && .venv/bin/pytest tests/test_voice_sessions.py -q
cd backend && .venv/bin/ruff check app/schemas/voice_session_schemas.py app/services/voice_session_service.py tests/test_voice_sessions.py
cd frontend && npm run build
```

结果：

- `tests/test_voice_sessions.py` 通过，15 passed，保留 1 个 SQLAlchemy/SQLite `datetime.utcnow()` 上游 deprecation warning。
- `ruff check` 通过。
- 用户端 `vue-tsc && vite build` 通过，保留 `baseline-browser-mapping` 数据偏旧提示。

## 2026-04-24 语音共创 P2 样本与列表摘要补充

- Voice Studio 最近会话列表已增加轻量状态摘要：待确认、安全介入、最近意图或等待输入。
- PRD 已补 10 条儿童表达样本和 2 版低置信度确认文案草案，用于后续 Alpha 人工验收。
- 代码自审结论：本轮没有新增数据库迁移；新增字段均为响应层兼容扩展；前端使用空值兜底；smoke 断言只在 `SMOKE_VOICE=1` 路径生效，不影响默认演示。

复验命令：

```bash
cd frontend && npm run build
cd backend && .venv/bin/pytest tests/test_voice_sessions.py -q
cd backend && .venv/bin/ruff check app/schemas/voice_session_schemas.py app/services/voice_session_service.py tests/test_voice_sessions.py
```

结果：

- 用户端 `vue-tsc && vite build` 通过。
- `tests/test_voice_sessions.py` 通过，15 passed，保留 1 个 SQLAlchemy/SQLite `datetime.utcnow()` 上游 deprecation warning。
- `ruff check` 通过。

## 2026-04-25 语音 Analytics Provider/Status 过滤开发

- 后端 `GET /api/voice-sessions/analytics` 新增 `provider` 与 `session_status` 查询参数。
- analytics 响应新增当前筛选条件回显：`provider`、`session_status`。
- Voice Studio 观测卡新增转写来源与会话状态筛选控件。
- `SMOKE_VOICE=1` 已新增 provider/status 过滤断言。
- 技术方案、demo checklist、PRD 执行状态已同步。

验证命令：

```bash
cd backend && .venv/bin/pytest tests/test_voice_sessions.py -q
cd backend && .venv/bin/ruff check app/api/voice_sessions.py app/schemas/voice_session_schemas.py app/services/voice_session_service.py tests/test_voice_sessions.py
cd frontend && npm run build
```

结果：

- `tests/test_voice_sessions.py` 通过，15 passed，保留 1 个 SQLAlchemy/SQLite `datetime.utcnow()` 上游 deprecation warning。
- `ruff check` 通过。
- 用户端 `vue-tsc && vite build` 通过，保留 `baseline-browser-mapping` 数据偏旧提示。

## 2026-04-25 Warning 与前端依赖安全收敛

- 后端移除 `datetime.utcnow()`：Provider admin models、cost tracker、provider metrics 已改为 timezone-aware UTC 时间。
- `tests/test_voice_sessions.py` 不再输出 SQLAlchemy/SQLite `datetime.utcnow()` deprecation warning。
- 前端更新 `baseline-browser-mapping`，`npm run build` 不再输出 Baseline 数据过期提示。
- 执行非破坏性 `npm audit fix` 后，用户端生产依赖 `npm audit --omit=dev` 为 0 vulnerabilities。

验证命令：

```bash
cd backend && .venv/bin/pytest tests/test_admin_providers.py tests/test_voice_sessions.py -q
cd backend && .venv/bin/ruff check app/db/admin_models.py app/services/cost_tracker.py app/services/provider_metrics.py app/api/voice_sessions.py app/schemas/voice_session_schemas.py app/services/voice_session_service.py tests/test_voice_sessions.py
cd frontend && npm audit --omit=dev
cd frontend && npm run build
```

结果：

- `tests/test_admin_providers.py tests/test_voice_sessions.py` 通过，17 passed。
- `ruff check` 通过。
- `npm audit --omit=dev` 返回 0 vulnerabilities。
- 用户端 `vue-tsc && vite build` 通过。

## 2026-04-25 行尾噪音收敛与 Admin Analytics 校验

- 已撤回高噪音 CRLF / lockfile 变更，当前 diff 保留在语音 analytics、Voice Studio、测试、smoke、文档和低噪音 admin models 修复范围内。
- 后端 admin provider analytics 的 `capability` 参数已收紧为 `text/image/tts/storybook/asr` 枚举，无效能力返回 `422`。
- 语音 analytics 的 `session_status` 参数已收紧为明确会话状态枚举，无效状态返回 `422`。

验证命令：

```bash
cd backend && .venv/bin/ruff check app/api/admin_providers.py app/api/voice_sessions.py app/db/admin_models.py app/schemas/voice_session_schemas.py app/services/voice_session_service.py tests/test_admin_providers.py tests/test_voice_sessions.py
cd backend && .venv/bin/pytest tests/test_admin_providers.py tests/test_voice_sessions.py -q
cd frontend && npm run build
```

结果：

- `ruff check` 通过。
- `tests/test_admin_providers.py tests/test_voice_sessions.py` 通过，17 passed。
- 用户端 `vue-tsc && vite build` 通过。

## 2026-04-25 Docker Voice Smoke 回归闭环

- Docker 栈已用当前代码重建：backend、backend-admin、worker、celery-beat、frontend、frontend-admin 均可启动。
- 修复 Celery task 注册不完整问题：worker 现在注册 generation workflow、generation maintenance、audio cache、memory、push 和 achievements 任务。
- 修复 worker 冷启动 DB session factory 自锁：数据库锁改为可重入锁。
- 修复 Celery async task 跨 event loop 复用 asyncpg 连接问题：任务结束时 dispose async engine。
- `SMOKE_VOICE=1` smoke 对齐当前 intent/event 命名，并使用非空临时 demo audio 上传样本。

验证命令：

```bash
cd backend && .venv/bin/python -m ruff check app/db/database.py app/core/celery_app.py app/tasks
cd backend && .venv/bin/python -m pytest tests/test_admin_providers.py tests/test_voice_sessions.py -q
cd frontend && npm run build
cd admin-frontend && npm run build
docker compose up -d --build
SMOKE_VOICE=1 ./scripts/demo_smoke.sh
```

结果：

- `ruff check` 通过。
- `tests/test_admin_providers.py tests/test_voice_sessions.py` 通过，17 passed。
- 用户端 `vue-tsc && vite build` 通过。
- 管理端 `vue-tsc && vite build` 通过，仍有 `baseline-browser-mapping` 数据偏旧提示。
- `docker compose up -d --build` 通过，当前本地服务可访问 `http://localhost:52080` 与 `http://localhost:52888`。
- `SMOKE_VOICE=1 ./scripts/demo_smoke.sh` 完整通过，覆盖普通故事、语音共创文本 fallback、上传回合、voice analytics、provider/status 筛选、finalize、绘本、资产重试、provider analytics 与 ops summary。