docs: add week 2 plan and demo smoke checklist
This commit is contained in:
139
docs/planning/demo-checklist.md
Normal file
139
docs/planning/demo-checklist.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# DreamWeaver 求职演示 Checklist
|
||||
|
||||
**目标**: 演示前用 5-10 分钟确认本地 Docker 环境、核心生成链路和讲解材料处于可展示状态。
|
||||
|
||||
---
|
||||
|
||||
## 1. 演示前准备
|
||||
|
||||
### 环境检查
|
||||
|
||||
- [ ] 已拉取最新 `main`
|
||||
- [ ] `backend/.env` 存在，且不包含需要提交的真实密钥
|
||||
- [ ] `DEBUG=true`
|
||||
- [ ] `ENABLE_DEMO_PROVIDERS=true`
|
||||
- [ ] `SECRET_KEY` 已设置
|
||||
- [ ] Docker Desktop 正常运行
|
||||
|
||||
### 启动命令
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
### 入口
|
||||
|
||||
- 用户端：http://localhost:52080
|
||||
- 本地登录：http://localhost:52080/auth/dev/signin
|
||||
- Admin：http://localhost:52888
|
||||
- 后端健康：http://localhost:52000/health
|
||||
- Admin 后端健康：http://localhost:52800/health
|
||||
|
||||
---
|
||||
|
||||
## 2. 自动 smoke 检查
|
||||
|
||||
默认检查健康、登录、普通故事、绘本、图片补全和 Provider 能力分层：
|
||||
|
||||
```bash
|
||||
./scripts/demo_smoke.sh
|
||||
```
|
||||
|
||||
需要检查 TTS 音频时：
|
||||
|
||||
```bash
|
||||
SMOKE_AUDIO=1 ./scripts/demo_smoke.sh
|
||||
```
|
||||
|
||||
通过标准：
|
||||
|
||||
- [ ] backend health 返回 `ok`
|
||||
- [ ] admin-backend health 返回 `ok`
|
||||
- [ ] dev login 能拿到 session
|
||||
- [ ] `/api/generations` 能生成普通故事
|
||||
- [ ] 普通故事封面 retry 后 `image_status=ready`
|
||||
- [ ] `/api/generations` 能生成绘本
|
||||
- [ ] 绘本图片 retry 后 `image_status=ready`
|
||||
- [ ] `/admin/providers/capabilities` 返回 `text/image/tts/storybook`
|
||||
- [ ] 如果启用 `SMOKE_AUDIO=1`，音频 retry 后 `audio_status=ready`
|
||||
|
||||
---
|
||||
|
||||
## 3. 手动演示路径
|
||||
|
||||
### 路径 A: 普通故事
|
||||
|
||||
1. 打开用户端。
|
||||
2. 使用本地登录。
|
||||
3. 创建普通故事：
|
||||
- 关键词：`月亮船，小狐狸，学会道歉`
|
||||
- 教育主题：`真诚表达`
|
||||
4. 进入故事详情页。
|
||||
5. 展示：
|
||||
- 标题和正文
|
||||
- 封面状态
|
||||
- 音频状态
|
||||
- 资产补全/重试入口
|
||||
6. 点击音频播放，说明音频缓存复用。
|
||||
|
||||
### 路径 B: 绘本
|
||||
|
||||
1. 创建绘本：
|
||||
- 关键词：`彩虹邮局，小刺猬，练习说谢谢`
|
||||
- 教育主题：`感恩表达`
|
||||
2. 进入绘本阅读器。
|
||||
3. 翻页展示多页文本和插图。
|
||||
4. 刷新页面或复制 URL，说明绘本已经支持按 ID 恢复。
|
||||
|
||||
### 路径 C: Admin/Provider
|
||||
|
||||
1. 打开 Admin。
|
||||
2. 说明管理端不是用户主链路，而是产品拥有者维护供应链路的辅助能力。
|
||||
3. 通过接口或页面说明：
|
||||
- Capability: `text/image/tts/storybook`
|
||||
- Provider: 具体供应商配置
|
||||
- Adapter: API 调用实现
|
||||
- Routing Policy: 优先级/成本/延迟/轮询
|
||||
|
||||
---
|
||||
|
||||
## 4. 3 分钟讲解结构
|
||||
|
||||
### 0:00 - 0:40 产品定位
|
||||
|
||||
DreamWeaver 是面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲述产品。它不是只生成一次性故事，而是围绕孩子档案、成长主题和故事宇宙，生成可回看、可补全、可聆听的故事体验。
|
||||
|
||||
### 0:40 - 1:30 用户闭环
|
||||
|
||||
用户选择孩子档案，输入主题或教育目标，生成故事或绘本。主内容先可读，封面、插图、语音作为资产补全。即使图片或音频失败，故事仍然可读，并且可以后续重试。
|
||||
|
||||
### 1:30 - 2:20 系统设计
|
||||
|
||||
系统收敛到统一 Generation Workflow：上下文准备、主记录保存、资产补全、状态回写和后处理。Provider 体系拆成 Capability、Provider、Adapter、Routing Policy，用户不需要理解模型供应商，只感知稳定的产品能力。
|
||||
|
||||
### 2:20 - 3:00 取舍与下一步
|
||||
|
||||
求职版优先稳定闭环和可解释性，不做支付、多租户和复杂监控。下一步会继续打磨前端状态体验、旧 API 兼容策略和 generation job 是否落库。
|
||||
|
||||
---
|
||||
|
||||
## 5. 风险预案
|
||||
|
||||
| 风险 | 现场处理 |
|
||||
| --- | --- |
|
||||
| 网络导致 TTS 失败 | 说明音频是可恢复资产，不阻塞故事阅读；使用已缓存样本或跳过 TTS |
|
||||
| 图片 provider 失败 | 展示 degraded completed 与 retry 机制 |
|
||||
| Docker 冷启动慢 | 演示前提前运行 smoke 脚本并保持容器运行 |
|
||||
| Admin 页面不适合主展示 | 只用 Provider 分层说明辅助讲系统设计 |
|
||||
| 面试官追问生产部署 | 明确当前是求职版 MVP，本轮重点是产品闭环和系统边界 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 演示完成标准
|
||||
|
||||
- [ ] 面试官能在 30 秒内理解产品定位。
|
||||
- [ ] 能现场看到普通故事和绘本结果。
|
||||
- [ ] 能解释失败降级和资产重试。
|
||||
- [ ] 能解释为什么 Provider 分层是产品设计，而不是单纯技术炫技。
|
||||
- [ ] 能说明下一步计划，而不是让项目停在 demo。
|
||||
Reference in New Issue
Block a user