docs: package week 4 demo and architecture
This commit is contained in:
66
docs/planning/demo-package.md
Normal file
66
docs/planning/demo-package.md
Normal file
@@ -0,0 +1,66 @@
|
||||
# DreamWeaver 求职版 Demo 包装
|
||||
|
||||
这份文档用于演示前 5 分钟快速准备，也可以作为面试官追问时的项目导航。
|
||||
|
||||
---
|
||||
|
||||
## 1. 一句话定位
|
||||
|
||||
DreamWeaver 是面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲述产品。它把孩子档案、故事宇宙、故事生成、绘本插图、语音缓存、阅读事件和成长记忆串成一个可恢复的阅读闭环。
|
||||
|
||||
---
|
||||
|
||||
## 2. 演示前检查
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
./scripts/demo_smoke.sh
|
||||
```
|
||||
|
||||
需要验证语音链路时：
|
||||
|
||||
```bash
|
||||
SMOKE_AUDIO=1 ./scripts/demo_smoke.sh
|
||||
```
|
||||
|
||||
演示入口：
|
||||
|
||||
- 用户端：`http://localhost:52080`
|
||||
- 本地登录：`http://localhost:52080/auth/dev/signin`
|
||||
- 管理端：`http://localhost:52888`
|
||||
- 后端健康：`http://localhost:52000/health`
|
||||
|
||||
---
|
||||
|
||||
## 3. 主演示路径
|
||||
|
||||
1. 使用本地登录进入用户端。
|
||||
2. 创建普通故事，说明主内容优先可读。
|
||||
3. 打开故事详情页，展示 `partial_ready`、封面补全、音频缓存状态和生成轨迹。
|
||||
4. 补全封面或音频，说明资产失败不会覆盖正文。
|
||||
5. 创建绘本，进入绘本阅读器。
|
||||
6. 刷新页面或重新进入绘本，说明按 ID 恢复和阅读位置恢复。
|
||||
7. 回到故事库，展示跨故事 Provider 运营摘要。
|
||||
8. 打开孩子时间线，展示阅读事件和记忆沉淀。
|
||||
|
||||
---
|
||||
|
||||
## 4. 面试讲解锚点
|
||||
|
||||
- **产品判断**：求职版不追求功能越多，而是围绕亲子阅读闭环收敛。
|
||||
- **AI 不确定性处理**：主内容和资产拆开，图片/音频失败不阻塞阅读。
|
||||
- **Provider 产品化**：用户看到稳定能力，系统内部用 Capability / Provider / Adapter / Routing Policy 管供应链。
|
||||
- **可观测性**：generation job/event 让生成过程、失败恢复和 Provider 成本可解释。
|
||||
- **可继续生产化**：前端已有轮询形态，后端已有任务事件模型，下一步可以迁移到 worker。
|
||||
|
||||
---
|
||||
|
||||
## 5. 失败预案
|
||||
|
||||
| 风险 | 现场处理 |
|
||||
| --- | --- |
|
||||
| TTS 网络失败 | 说明音频是可恢复资产，展示缓存状态或跳过语音 |
|
||||
| 图片生成失败 | 展示 `degraded_completed` 与资源重试 |
|
||||
| Docker 冷启动慢 | 演示前先跑 smoke 并保持容器运行 |
|
||||
| Provider 追问过深 | 回到 Capability / Provider / Adapter / Routing Policy 四层解释 |
|
||||
| 生产化追问 | 说明下一步是 worker 化、监控告警、密钥治理和 Provider analytics 扩展 |
|
||||
@@ -14,6 +14,8 @@
|
||||
- 音频缓存治理首版已验证：`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` 通过。
|
||||
- 后端新增 `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` 均通过。
|
||||
|
||||
@@ -61,11 +61,11 @@ Week 2 已完成演示闭环、统一生成工作流、generation job/event、
|
||||
|
||||
| ID | Workstream | Task | Output | Priority | Status |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| W4-01 | Frontend | 结果页与阅读页体验收尾 | 故事详情、绘本阅读、故事库状态一致 | P0 | Pending |
|
||||
| W4-02 | Docs | 架构图与系统说明 | `docs/technical/architecture.md` 或 Mermaid 图 | P0 | Pending |
|
||||
| W4-03 | Demo | 求职版 Demo 包装 | 演示路径、风险预案、检查命令一页化 | P0 | Pending |
|
||||
| W4-04 | QA | 全量回归与验证记录 | pytest、ruff、前端 build、Docker smoke | P0 | Pending |
|
||||
| W4-05 | Product | 项目复盘与下一阶段路线 | Week 4 review + production backlog | P1 | Pending |
|
||||
| W4-01 | Frontend | 结果页与阅读页体验收尾 | 故事详情音频缓存、绘本阅读位置恢复、故事库状态一致 | P0 | Done |
|
||||
| W4-02 | Docs | 架构图与系统说明 | `docs/technical/architecture.md` | P0 | Done |
|
||||
| W4-03 | Demo | 求职版 Demo 包装 | `docs/planning/demo-package.md` | P0 | Done |
|
||||
| W4-04 | QA | 全量回归与验证记录 | pytest、ruff、前端 build、Docker smoke | P0 | Done |
|
||||
| W4-05 | Product | 项目复盘与下一阶段路线 | `docs/planning/week-4-sprint-review.md` | P1 | Done |
|
||||
|
||||
---
|
||||
|
||||
|
||||
69
docs/planning/week-4-sprint-review.md
Normal file
69
docs/planning/week-4-sprint-review.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# DreamWeaver Week 4 Sprint Review
|
||||
|
||||
**Date**: 2026-04-18
|
||||
**Theme**: 求职版 Demo 包装、结果体验收尾与生产化路线
|
||||
|
||||
---
|
||||
|
||||
## 1. 本阶段完成
|
||||
|
||||
- Week 2-4 总 backlog 已固化，Week 2 全部完成。
|
||||
- Week 3 已补齐音频缓存治理首版：
|
||||
- 音频缓存状态查询
|
||||
- 音频缓存清理
|
||||
- 故事详情页展示缓存大小和更新时间
|
||||
- Week 3 已补齐时间线与记忆联动：
|
||||
- 阅读事件进入孩子成长时间线
|
||||
- 阅读事件生成的 `recent_story` 记忆带上故事模式、封面、阅读时长和来源
|
||||
- 时间线能展示阅读记录与记忆沉淀
|
||||
- Week 4 已补齐绘本阅读位置恢复。
|
||||
- Week 4 已输出架构说明和 Demo 包装文档。
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前项目状态
|
||||
|
||||
DreamWeaver 已经具备求职演示所需的完整闭环：
|
||||
|
||||
`孩子档案 -> 输入主题 -> 生成故事/绘本 -> 资产补全 -> 语音缓存 -> 阅读记录 -> 记忆沉淀 -> 成长时间线 -> 复用上下文生成新故事`
|
||||
|
||||
同时具备可解释的系统设计：
|
||||
|
||||
- 统一生成入口
|
||||
- 统一状态模型
|
||||
- generation job/event
|
||||
- Provider failover 和聚合指标
|
||||
- 跨故事 Provider analytics
|
||||
- 前端生成轨迹和自动轮询形态
|
||||
|
||||
---
|
||||
|
||||
## 3. 验证状态
|
||||
|
||||
最近一轮验证包括：
|
||||
|
||||
- 后端全量测试：85 passed
|
||||
- 后端 ruff：通过
|
||||
- 用户端生产构建：通过
|
||||
- 管理端生产构建：通过
|
||||
- Docker 全栈重建：通过
|
||||
- demo smoke：通过
|
||||
|
||||
---
|
||||
|
||||
## 4. 生产化 Backlog
|
||||
|
||||
| Priority | Task | Why |
|
||||
| --- | --- | --- |
|
||||
| P0 | 将同步生成迁移到 Celery worker | 支持真实长任务、断点恢复和后台进度 |
|
||||
| P0 | Provider analytics 加入时间窗口和失败原因 | 让运营分析可用于成本与稳定性决策 |
|
||||
| P1 | 音频缓存过期策略与后台清理 | 控制磁盘占用和缓存生命周期 |
|
||||
| P1 | 生成任务取消与重试队列 | 防止重复任务和用户误触造成浪费 |
|
||||
| P1 | 监控告警与结构化 dashboard | 上线前需要可观测性闭环 |
|
||||
| P2 | 更细粒度叙事风格与音色策略 | 扩展体验，但不影响当前求职版主线 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 面试表达
|
||||
|
||||
这个项目最重要的不是“接了几个 AI API”，而是把模型的不确定性变成了可恢复、可解释、可追踪的产品体验。主内容优先保存，资产独立补全，状态明确可读，Provider 调用可观测，阅读行为还能反哺记忆和下一次生成。
|
||||
Reference in New Issue
Block a user