Add voice analytics filters and metrics

2026-04-26 22:00:34 +08:00
parent 3805c18622
commit 55ca0985eb
25 changed files with 710 additions and 39 deletions
--- a/docs/planning/demo-checklist.md
+++ b/docs/planning/demo-checklist.md
@@ -79,6 +79,8 @@ SMOKE_AUDIO=1 SMOKE_VOICE=1 ./scripts/demo_smoke.sh
 - [ ] `/api/audio/{story_id}/status` 能查询音频缓存状态且不触发生成
 - [ ] 如果启用 `SMOKE_AUDIO=1`，音频 retry 后 `audio_status=ready`
 - [ ] 如果启用 `SMOKE_VOICE=1`，语音共创会话可完成文本 fallback、上传回合、analytics 和 finalize 到 Story
+- [ ] 如果启用 `SMOKE_VOICE=1`，analytics 返回输入构成、语音时长、Provider 分布、ASR/TTS 成功率和低置信度确认率
+- [ ] 如果启用 `SMOKE_VOICE=1`，analytics 支持按 `provider` 和 `session_status` 筛选
 - [ ] 验证结果已记录到 `docs/planning/demo-validation-log.md`

 ---
--- a/docs/planning/demo-validation-log.md
+++ b/docs/planning/demo-validation-log.md
@@ -128,3 +128,158 @@ SMOKE_AUDIO=1 ./scripts/demo_smoke.sh
 限制：

 - 本机浏览器自动化脚本默认寻找标准版 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。
--- a/docs/product/voice-co-creation-mode-incremental-prd.md
+++ b/docs/product/voice-co-creation-mode-incremental-prd.md
@@ -556,6 +556,71 @@ DreamWeaver 的语音共创模式应当成为一种“孩子可以开口参与

 ---

+
+
+## Phase A Alpha 50-Task Execution Backlog（2026-04-24）
+
+> 目标：先把语音共创 Alpha 做到“可演示、可解释、可复验”，再进入 Phase B 实时化。以下 50 项按今天可连续推进的优先级排列；实现时优先选择无需新迁移、风险低、能用测试和 smoke 验证的任务。
+
+| # | Priority | Area | Task | Acceptance |
+| --- | --- | --- | --- | --- |
+| 01 | P0 | PRD | 固化 50 项 Alpha 执行池 | PRD 中能看到任务、优先级、验收口径 |
+| 02 | P0 | Analytics | turn summary 返回用户录音时长 | `GET /turns/{id}` 有 `user_audio_duration_ms` |
+| 03 | P0 | Analytics | turn summary 返回助手音频时长 | `GET /turns/{id}` 有 `assistant_audio_duration_ms` |
+| 04 | P0 | Analytics | voice analytics 返回用户语音总时长 | analytics 有 `total_user_audio_duration_ms` |
+| 05 | P0 | Analytics | voice analytics 返回用户平均语音时长 | analytics 有 `avg_user_audio_duration_ms` |
+| 06 | P0 | Analytics | voice analytics 返回转写 Provider 分布 | analytics 有 `transcription_provider_counts` |
+| 07 | P0 | Analytics | voice analytics 返回低置信度确认率 | analytics 有 `confirmation_request_rate` |
+| 08 | P0 | Frontend | Voice Studio 展示平均用户语音时长 | 观测卡片可见平均秒数 |
+| 09 | P0 | Frontend | Voice Studio 展示转写来源分布 | 观测卡片可见 fallback/demo/openai 次数 |
+| 10 | P0 | Frontend | Voice Studio 展示确认率 | 低置信度卡片显示确认率 |
+| 11 | P0 | Smoke | `SMOKE_VOICE=1` 断言上传回合时长 | smoke 检查 `user_audio_duration_ms` |
+| 12 | P0 | Smoke | `SMOKE_VOICE=1` 断言 Provider 分布 | smoke 检查 demo/fallback 次数 |
+| 13 | P0 | Tests | 增加 analytics 时长测试 | `test_voice_sessions.py` 覆盖新增字段 |
+| 14 | P0 | Tests | 增加 Provider 分布测试 | 测试覆盖 fallback/openai 分布 |
+| 15 | P0 | Tests | 增加确认率测试 | 测试覆盖 `confirmation_request_rate` |
+| 16 | P1 | Analytics | 统计文本 fallback turn 数 | analytics 有 `text_fallback_turns` |
+| 17 | P1 | Analytics | 统计上传音频 turn 数 | analytics 有 `uploaded_audio_turns` |
+| 18 | P1 | Analytics | 统计用户语音 turn 占比 | analytics 有 `user_audio_turn_rate` |
+| 19 | P1 | Analytics | 统计助手音频 ready turn 数 | analytics 有 `assistant_audio_ready_turns` |
+| 20 | P1 | Analytics | 统计助手音频 ready 率 | analytics 有 `assistant_audio_ready_rate` |
+| 21 | P1 | Analytics | 统计 ASR 成功率 | analytics 有 `asr_success_rate` |
+| 22 | P1 | Analytics | 统计 TTS 成功率 | analytics 有 `tts_success_rate` |
+| 23 | P1 | Analytics | 统计平均转写置信度 | analytics 有 `avg_transcript_confidence` |
+| 24 | P1 | Analytics | 统计平均意图置信度 | analytics 有 `avg_intent_confidence` |
+| 25 | P1 | Analytics | 统计安全介入率 | analytics 有 `safety_intervention_rate` |
+| 26 | P1 | Analytics | 统计语音失败事件分布 | analytics 有 `failure_event_counts` |
+| 27 | P1 | Frontend | Voice Studio 展示 fallback/upload turn 数 | 观测卡片可见输入构成 |
+| 28 | P1 | Frontend | Voice Studio 展示助手音频 ready 率 | 观测卡片可见 TTS 产物覆盖 |
+| 29 | P1 | Frontend | Voice Studio 展示 ASR/TTS 成功率 | 观测卡片文案可见成功率 |
+| 30 | P1 | Frontend | Voice Studio 展示平均置信度 | 观测卡片文案可见转写/意图均值 |
+| 31 | P1 | Frontend | Turn 卡片展示用户录音时长 | 单轮卡片可解释录音长度 |
+| 32 | P1 | Frontend | Turn 卡片展示助手音频时长 | 单轮卡片可解释 TTS 产物长度 |
+| 33 | P1 | Smoke | `SMOKE_VOICE=1` 断言输入构成 | smoke 检查 fallback/upload 计数 |
+| 34 | P1 | Smoke | `SMOKE_VOICE=1` 断言成功率字段 | smoke 检查 ASR/TTS/assistant audio 率 |
+| 35 | P1 | Tests | 增加输入构成测试 | 后端测试覆盖 fallback/upload 计数 |
+| 36 | P1 | Tests | 增加音频 ready 率测试 | 后端测试覆盖 assistant audio ready |
+| 37 | P1 | Tests | 增加平均置信度测试 | 后端测试覆盖 confidence 均值 |
+| 38 | P1 | Docs | 更新技术方案 analytics 字段 | tech spec 与接口一致 |
+| 39 | P1 | Docs | 更新 demo checklist 观测项 | checklist 包含语音观测字段 |
+| 40 | P1 | Docs | 更新 validation log | 日志记录命令与结果 |
+| 41 | P2 | Product | 真实儿童表达样本集 | 至少 10 条样本进入验收文档 |
+| 42 | P2 | Product | 低置信度文案 A/B 草案 | 输出两版确认文案 |
+| 43 | P2 | Frontend | 移动端确认卡密度优化 | 小屏按钮不拥挤 |
+| 44 | P2 | Frontend | 会话列表显示观测摘要 | 列表可见需处理原因和输入模式 |
+| 45 | P2 | Backend | 支持 analytics 按 provider 过滤 | query 可筛选 provider |
+| 46 | P2 | Backend | 支持 analytics 按 status 过滤 | query 可筛选会话状态 |
+| 47 | P2 | Ops | ASR Provider 管理端摘要 | admin 侧可见 ASR 调用情况 |
+| 48 | P2 | QA | Docker voice smoke 回归 | Docker 栈下 `SMOKE_VOICE=1` 通过 |
+| 49 | P2 | Review | 自审语音服务复杂度 | 列出可拆分函数和风险点 |
+| 50 | P2 | Review | 自审演示口径一致性 | PRD、tech spec、checklist 口径一致 |
+
+### 今日执行策略
+
+- 先完成 #01-#40 中无需数据库迁移的观测与验收项。
+- #41-#50 作为后续产品化和演示质量任务，不阻塞今天的 Alpha 收束。
+- 每批完成后必须跑后端语音测试、前端 build、ruff，并追加验证日志。
+
 ## Success Metrics

 ### Product Metrics
@@ -600,3 +665,38 @@ DreamWeaver 的语音共创模式应当成为一种“孩子可以开口参与
 4. 复用现有生成主干，新增 voice session 层，而不是另起一套平行系统

 这样既能保持当前 PRD 主线不被打断，也能确保后续做语音共创时，我们是在按计划推进，而不是临时起意。
+
+## Phase A Alpha Child Expression Samples（P2 Seed）
+
+这些样本用于后续补齐真实儿童表达验收，不作为模型提示词硬编码。
+
+| # | Sample | Expected Intent | Review Focus |
+| --- | --- | --- | --- |
+| 01 | 我想听小熊和星星找家的故事 | start_story | 能否抓住主角与目标 |
+| 02 | 不要让小熊害怕，让月亮姐姐帮它 | correct_story | 修正是否接上上一轮 |
+| 03 | 然后小狐狸也来了，它带了饼干 | continue_story | 新角色是否自然进入 |
+| 04 | 我不喜欢黑黑的森林，换成彩虹森林 | correct_story | 负面场景是否温和替换 |
+| 05 | 让恐龙变小一点，不要踩坏花 | correct_story | 安全和教育主题是否保留 |
+| 06 | 再讲一段，它们坐上云朵船 | continue_story | 奇幻想象是否延续 |
+| 07 | 结束吧，我想保存这个故事 | save_story | 是否引导 finalize |
+| 08 | 先停一下，我等会再讲 | end_story | 是否保持会话可恢复 |
+| 09 | 它们可以一起道歉吗 | continue_story | 是否融入教育主题 |
+| 10 | 我刚才说错了，不是兔子，是小猫 | correct_story | 指代修正是否准确 |
+
+## Phase A Alpha Confirmation Copy Options（P2 Seed）
+
+- 版本 A（更温柔）：`我刚才听到的是「{summary}」。如果听对了，我们就按这个继续；如果不对，可以重说一遍或改成文字。`
+- 版本 B（更高效）：`本轮系统理解为「{summary}」。请家长确认：继续、重说，或改成文本输入。`
+
+默认建议继续使用版本 B，因为 Alpha 演示时更短、更容易解释系统状态。
+
+## Phase A Alpha Execution Update（2026-04-25）
+
+本轮继续推进真实开发任务，而不是只维护任务池：
+
+- 已完成 #45：voice analytics 支持 `provider` 查询参数，可按转写来源筛选 turn、事件和会话集合。
+- 已完成 #46：voice analytics 支持 `session_status` 查询参数，可按会话状态筛选统计窗口。
+- 已扩展 Voice Studio 观测卡：支持转写来源和会话状态筛选，便于演示时解释 demo/fallback/真实 ASR 差异。
+- 已扩展 `SMOKE_VOICE=1`：增加 provider/status 过滤断言，避免 analytics 只验证全量路径。
+
+后续仍未完成：#47 ASR Provider 管理端摘要、#48 Docker voice smoke 回归、#49 服务复杂度拆分、#50 演示口径最终复核。
--- a/docs/technical/voice-co-creation-phase-a-tech-spec.md
+++ b/docs/technical/voice-co-creation-phase-a-tech-spec.md
@@ -28,7 +28,7 @@
 - 低置信度确认链路已有后端测试覆盖，可作为下一阶段继续接 ASR 与更细确认交互的基础
 - 已新增用户转写安全检查、assistant 输出柔性改写与 `safety_flags` 事件记录
 - finalize 会生成更稳定的标题/摘要，并在条件允许时自动排队封面补全 job
- 已新增 `voice session analytics` 聚合指标，可跟踪 turn 成功率、ASR/TTS 失败、低置信度触发和 finalize 转化率
+- 已新增 `voice session analytics` 聚合指标，可跟踪 turn 成功率、ASR/TTS 失败、低置信度触发、finalize 转化率、输入构成、语音时长、Provider 分布、确认率和平均置信度，并支持按转写 Provider 与会话状态筛选
 - `voice session finalize` 现在会返回可追踪的 `generation_job_id`，让正式 Story 资产补全重新接回现有 generation trace 主干
 - 语音共创触发的 `asset_generation` job 现在也支持沿用统一 generation job 的取消 / 重试控制