DreamWeaver/dreamweaver
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: sync workflow progress and weekend handoff

Browse Source
This commit is contained in:
torin
2026-04-17 18:44:43 +08:00
parent a97a2fe005
commit fea4ef012f
11 changed files with 2712 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
docs/README.md Normal file
View File

@@ -0,0 +1,166 @@
# Documentation Index
This repository now uses a simple documentation taxonomy so you can quickly tell:
- what is current and actionable
- what is product-facing vs. technical
- what is historical and should not be treated as source of truth
---
## Folder Structure
### `docs/product/`
Current product documents. These are the best starting point when you want to understand:
- product positioning
- MVP scope
- feature requirements
- portfolio/presentation story
Files:
- `job-search-relaunch-prd.md`
Status: Active
Type: Product strategy / reboot PRD
Use when: you want the current product direction and prioritization.
- `unified-generation-workflow-prd.md`
Status: Active
Type: Feature-level PRD
Use when: you want the target design for the core generation workflow.
### `docs/planning/`
Execution-oriented documents. These are for sprint planning, backlog breakdown, and short-term delivery.
Files:
- `document-status-inventory.md`
Status: Active
Type: Documentation audit / implementation mapping
Use when: you want to know which docs are current, which capabilities are really implemented, and where coding should restart.
- `week-1-execution-backlog.md`
Status: Active
Type: Sprint / execution planning
Use when: you want to know what to do first and how to break work into tasks.
- `weekend-handoff-2026-04-17.md`
Status: Active
Type: Progress handoff / execution snapshot
Use when: you want to continue work from another machine without reconstructing the latest checkpoint from chat history.
### `docs/technical/`
Technical reference documents. These are implementation-oriented and may include design guidance or development notes.
Files:
- `memory-system-dev.md`
Status: Reference
Type: Technical design / development guide
Use when: you work on the memory system or want to study one style of technical design note.
Note: parts of this document are forward-looking and should be validated against the current codebase before implementation.
### `docs/operations/`
Runbooks and environment/operations documentation.
Files:
- `ha-runbook.md`
Status: Reference
Type: Operations runbook
Use when: you work on Docker-based HA deployment, Redis Sentinel, PostgreSQL replication, or backup verification.
### `docs/archive/`
Historical documents. Keep these for learning or project history, but do not treat them as the current source of truth.
Files:
- `provider-system-legacy.md`
Status: Archived
Type: Historical technical plan
Why archived: partially outdated; references earlier provider architecture and older app entry naming.
- `refactoring-plan-legacy.md`
Status: Archived
Type: Historical implementation plan
Why archived: reflects an earlier refactor phase; some items are completed, some are no longer current priorities.
- `stories-split-analysis-legacy.md`
Status: Archived
Type: Historical code analysis
Why archived: tied to a past `stories.py` split effort and no longer represents the current structure.
---
## Deleted Document
The following document was removed instead of archived:
- `backend/docs/code_review_report.md`
Reason: it was a one-off review artifact, not a durable project document, and its main issue was already resolved by the later `0002_add_api_key_to_providers.py` migration.
---
## Recommended Reading Order
If you want to understand the project as a product manager:
1. `docs/product/job-search-relaunch-prd.md`
2. `docs/product/unified-generation-workflow-prd.md`
3. `docs/planning/document-status-inventory.md`
4. `docs/planning/week-1-execution-backlog.md`
5. `docs/planning/weekend-handoff-2026-04-17.md`
6. `docs/technical/memory-system-dev.md`
7. `docs/operations/ha-runbook.md`
If you want to understand the project as an engineer:
1. `docs/planning/document-status-inventory.md`
2. `docs/product/unified-generation-workflow-prd.md`
3. `docs/technical/memory-system-dev.md`
4. `docs/operations/ha-runbook.md`
5. `docs/archive/*` only when you need historical context
---
## Documentation Rules Going Forward
When adding a new document, place it using these rules:
- Put it in `docs/product/` if it explains what should be built and why.
- Put it in `docs/planning/` if it explains when or in what order work should happen.
- Put it in `docs/technical/` if it explains how something works or should be implemented.
- Put it in `docs/operations/` if it is about deployment, environments, runbooks, or maintenance.
- Put it in `docs/archive/` if it is historically useful but no longer current.
Delete a document only when all three are true:
- it is a one-off artifact
- it is not a reusable reference
- its key information is either obsolete or already captured elsewhere
Archive instead of deleting when:
- the document shows project history
- the document may still help future debugging or learning
- you are not fully sure whether it is still valuable
---
## PM Learning Note
A good documentation system helps you think clearly:
- `product` tells you what problem you are solving
- `planning` tells you what to do next
- `technical` tells you how the system works
- `operations` tells you how to run it
- `archive` tells you what used to be true
That separation is useful not only for this repo, but also as a general PM habit. Many product documents become confusing because they mix all five at once.

246
docs/archive/provider-system-legacy.md Normal file
View File

@@ -0,0 +1,246 @@
# Provider 系统开发文档
## 当前版本功能 (v0.2.0)
### 已完成功能
1. **CQTAI nano 图像适配器** (`app/services/adapters/image/cqtai.py`)
- 异步生成 + 轮询获取结果
- 支持 nano-banana / nano-banana-pro 模型
- 支持多种分辨率和画面比例
- 支持图生图 (filesUrl)
2. **密钥加密存储** (`app/services/secret_service.py`)
- Fernet 对称加密，密钥从 SECRET_KEY 派生
- Provider API Key 自动加密存储
- 密钥管理 API (CRUD)
3. **指标收集系统** (`app/services/provider_metrics.py`)
- 调用成功率、延迟、成本统计
- 时间窗口聚合查询
- 已集成到 provider_router
4. **熔断器功能** (`app/services/provider_metrics.py`)
- 连续失败 3 次触发熔断
- 60 秒后自动恢复尝试
- 健康状态持久化到数据库
5. **管理后台前端** (`app/admin_app.py`)
- 独立端口部署 (8001)
- Vue 3 + Tailwind CSS 单页应用
- Provider CRUD 管理
- 密钥管理界面
- Basic Auth 认证
### 配置说明
```bash
# 启动主应用
uvicorn app.main:app --port 8000
# 启动管理后台 (独立端口)
uvicorn app.admin_app:app --port 8001
```
环境变量:
```
CQTAI_API_KEY=your-cqtai-api-key
ENABLE_ADMIN_CONSOLE=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-secure-password
```
---
## 下一版本优化计划 (v0.3.0)
### 高优先级
#### 1. 智能负载分流 (方案 B)
**目标**: 主渠道压力大时自动分流到后备渠道
**实现方案**:
- 监控指标: 并发数、响应延迟、错误率
- 分流阈值配置:
```python
class LoadBalanceConfig:
max_concurrent: int = 10 # 并发超过此值时分流
max_latency_ms: int = 5000 # 延迟超过此值时分流
max_error_rate: float = 0.1 # 错误率超过 10% 时分流
```
- 分流策略: 加权轮询，根据健康度动态调整权重
**涉及文件**:
- `app/services/provider_router.py` - 添加负载均衡逻辑
- `app/services/provider_metrics.py` - 添加并发计数器
- `app/db/admin_models.py` - 添加 LoadBalanceConfig 模型
#### 2. Storybook 适配器
**目标**: 生成可翻页的分页故事书
**实现方案**:
- 参考 Gemini AI Story Generator 格式
- 输出结构:
```python
class StorybookPage:
page_number: int
text: str
image_prompt: str
image_url: str | None
class Storybook:
title: str
pages: list[StorybookPage]
cover_url: str | None
```
- 集成文本 + 图像生成流水线
**涉及文件**:
- `app/services/adapters/storybook/` - 新建目录
- `app/api/stories.py` - 添加 storybook 生成端点
### 中优先级
#### 3. 成本追踪系统
**目标**: 记录实际消费，支持预算控制
**实现方案**:
- 成本记录表:
```python
class CostRecord:
user_id: str
provider_id: str
capability: str # text/image/tts
estimated_cost: Decimal
actual_cost: Decimal | None
timestamp: datetime
```
- 预算配置:
```python
class BudgetConfig:
user_id: str
daily_limit: Decimal
monthly_limit: Decimal
alert_threshold: float = 0.8 # 80% 时告警
```
- 超预算处理: 拒绝请求 / 降级到低成本 provider
**涉及文件**:
- `app/db/admin_models.py` - 添加 CostRecord, BudgetConfig
- `app/services/cost_tracker.py` - 新建
- `app/api/admin_providers.py` - 添加成本查询 API
#### 4. 指标可视化
**目标**: 管理后台展示供应商指标图表
**实现方案**:
- 添加指标查询 API:
- GET /admin/metrics/summary - 汇总统计
- GET /admin/metrics/timeline - 时间线数据
- GET /admin/metrics/providers/{id} - 单个供应商详情
- 前端使用 Chart.js 或 ECharts 展示
### 低优先级
#### 5. 多租户 Provider 配置
**目标**: 每个租户可配置独立 provider 列表和 API Key
**实现方案**:
- 租户配置表:
```python
class TenantProviderConfig:
tenant_id: str
provider_type: str
provider_ids: list[str] # 按优先级排序
api_key_override: str | None # 加密存储
```
- 路由时优先使用租户配置，回退到全局配置
#### 6. Provider 健康检查调度器
**目标**: 定期主动检查 provider 健康状态
**实现方案**:
- Celery Beat 定时任务
- 每 5 分钟检查一次所有启用的 provider
- 更新 ProviderHealth 表
#### 7. 适配器热加载
**目标**: 支持运行时动态加载新适配器
**实现方案**:
- 适配器插件目录: `app/services/adapters/plugins/`
- 启动时扫描并注册
- 提供 API 触发重新扫描
---
## API 变更记录
### v0.2.0 新增
| Method | Route | Description |
|--------|-------|-------------|
| GET | `/admin/secrets` | 列出所有密钥名称 |
| POST | `/admin/secrets` | 创建/更新密钥 |
| DELETE | `/admin/secrets/{name}` | 删除密钥 |
| GET | `/admin/secrets/{name}/verify` | 验证密钥有效性 |
### 计划中 (v0.3.0)
| Method | Route | Description |
|--------|-------|-------------|
| GET | `/admin/metrics/summary` | 指标汇总 |
| GET | `/admin/metrics/timeline` | 时间线数据 |
| POST | `/api/storybook/generate` | 生成分页故事书 |
| GET | `/admin/costs` | 成本统计 |
| POST | `/admin/budgets` | 设置预算 |
---
## 适配器开发指南
### 添加新适配器
1. 创建适配器文件:
```python
# app/services/adapters/image/new_provider.py
from app.services.adapters.base import AdapterConfig, BaseAdapter
from app.services.adapters.registry import AdapterRegistry
@AdapterRegistry.register("image", "new_provider")
class NewProviderAdapter(BaseAdapter[str]):
adapter_type = "image"
adapter_name = "new_provider"
async def execute(self, prompt: str, **kwargs) -> str:
# 实现生成逻辑
pass
async def health_check(self) -> bool:
# 实现健康检查
pass
@property
def estimated_cost(self) -> float:
return 0.01 # USD
```
2. 在 `__init__.py` 中导入:
```python
# app/services/adapters/__init__.py
from app.services.adapters.image import new_provider as _new_provider # noqa: F401
```
3. 添加配置:
```python
# app/core/config.py
new_provider_api_key: str = ""
# app/services/provider_router.py
API_KEY_MAP["new_provider"] = "new_provider_api_key"
```
4. 更新 `.env.example`:
```
NEW_PROVIDER_API_KEY=
```

109
docs/archive/refactoring-plan-legacy.md Normal file
View File

@@ -0,0 +1,109 @@
# DreamWeaver 重构实施计划
## 1. 概述
本文档基于对当前架构的深入分析，制定了从稳定性、可维护性到可扩展性的分阶段重构计划。
**目标**：
- **短期**：解决单点故障风险，优化开发体验，清理关键技术债。
- **中期**：提升系统高可用能力，增强监控与可观测性。
- **长期**：架构演进，支持大规模并发与复杂业务场景。
---
## 2. 短期优化计划 (1-2周)
**重点**：消除即时风险，提升部署效率。
### 2.1 统一镜像构建 (High Priority)
目前 `backend`, `backend-admin`, `worker`, `celery-beat` 重复构建 4 次，浪费资源且镜像版本可能不一致。
- **Action Items**:
- [x] 修改 `backend/Dockerfile` 为通用基础镜像。
- [x] 更新 `docker-compose.yml`，定义 `backend-base` 服务或使用 `image` 标签共享镜像。
- [x] 确保所有 Python 服务共用同一构建产物，仅启动命令不同。
### 2.2 修复 Provider 缓存与限流 (High Priority)
内存缓存 (`TTLCache`, `_latency_cache`) 在多进程/多实例下失效。
- **Action Items**:
- [x] 引入 Redis 作为共享缓存后端。
- [x] 重构 `_load_provider_cache`，将 Provider 配置缓存至 Redis。
- [x] 重构 `stories.py` 中的限流逻辑，使用 `redis-cell` 或简单的 Redis 计数器替代 `TTLCache`。
### 2.3 拆分 `stories.py` (Medium Priority)
`app/api/stories.py` 超过 600 行，包含 API 定义、业务逻辑、验证逻辑，维护困难。
- **Action Items**:
- [x] 创建 `app/services/story_service.py`，迁移生成、润色、PDF生成等核心逻辑。
- [x] 创建 `app/schemas/story_schemas.py`，迁移 Pydantic 模型（`GenerateRequest`, `StoryResponse` 等）。
- [x] API 层 `stories.py` 仅保留路由定义和依赖注入，调用 Service 层。
---
## 3. 中期优化计划 (1-2月)
**重点**：高可用 (HA) 与系统韧性。
### 3.1 数据库高可用 (Critical)
当前 PostgreSQL 为单点，且 Admin/User 混合使用。
- **Action Items**:
- [ ] 部署 PostgreSQL 主从复制 (Master-Slave)。
- [ ] 配置 `PgBouncer` 或 SQLAlchemy 读写分离，减轻主库压力。
- [ ] 实施数据库自动备份策略 (如 `pg_dump` 定时上传 S3)。
### 3.2 消息队列高可用 (Critical)
Redis 单点故障将导致 Celery 任务全盘停摆。
- **Action Items**:
- [ ] 迁移至 Redis Sentinel 或 Redis Cluster 模式。
- [ ] 更新 Celery 配置以支持 Sentinel/Cluster 连接串。
### 3.3 增强可观测性 (Important)
目前仅有简单的日志，缺乏系统级指标。
- **Action Items**:
- [ ] 集成 Prometheus Client，暴露 `/metrics` 端点。
- [ ] 部署 Grafana + Prometheus，监控 API 延迟、QPS、Celery 队列积压情况。
- [ ] 完善 `ProviderMetrics`，增加可视化大盘，实时监控 AI 供应商的成本与成功率。
### 3.4 Phase 3 最小可执行任务清单 (MVP)
目标：在不大改业务代码的前提下，于一个迭代内完成高可用基础设施闭环。
- [x] PostgreSQL 主从：新增 `docker-compose.ha.yml`，包含 1 主 1 从与健康检查。
- [x] PostgreSQL 备份：新增每日备份任务（`pg_dump`）与 7 天保留策略。
- [x] Redis Sentinel：新增 1 主 2 哨兵最小拓扑，并验证故障切换。
- [x] Celery 连接：更新 Celery broker/result backend 配置，支持 Sentinel 连接串。
- [x] 回归验证：执行一次故事生成 + 异步任务链路（worker/beat）冒烟测试。
- [x] 运行手册：补充故障切换与恢复步骤文档（PostgreSQL/Redis/Celery）。
---
## 4. 长期架构演进 (季度规划)
**重点**：业务解耦与规模化。
### 4.1 统一 API 网关
- **当前**：前端直连后端端口，CORS 配置分散。
- **演进**：引入 Traefik 或 Nginx 作为统一网关，管理路由、SSL、全局限流、统一鉴权。
### 4.2 前端工程合并
- **当前**：User App 和 Admin Console 是完全独立的两个项目，但在组件和工具链上高度重复。
- **演进**：使用一种 Monorepo 策略或基于路由的单一应用策略，共享组件库和类型定义，减少维护成本。
### 4.3 事件驱动架构完善
- **当前**：部分业务逻辑耦合在 API 中。
- **演进**：扩展事件总线，将“阅读记录”、“成就解锁”、“通知推送”等非核心链路完全异步化，通过 Domain Events 解耦。
---
## 5. 实施路线图
| 阶段 | 时间估算 | 关键里程碑 |
| :--- | :--- | :--- |
| **Phase 1: 基础夯实** | Week 1-2 | Docker 构建优化上线，Redis 替代内存缓存。 |
| **Phase 2: 代码重构** | Week 3-4 | `stories.py` 拆分完成，Service 层建立。 |
| **Phase 3: 高可用建设** | Month 2 | 数据库与 Redis 实现主备/集群模式。 |
| **Phase 4: 监控体系** | Month 2 | Grafana 监控大盘上线，关键指标报警配置完毕。 |

52
docs/archive/stories-split-analysis-legacy.md Normal file
View File

@@ -0,0 +1,52 @@
# `stories.py` 拆分分析 (Phase 2 准备)
## 当前职责
`app/api/stories.py` (591 行) 承担了以下职责：
| 职责 | 行数 | 描述 |
|---|---|---|
| Pydantic 模型 | ~50 行 | `GenerateRequest`, `StoryResponse`, `FullStoryResponse` 等 |
| 验证逻辑 | ~40 行 | `_validate_profile_and_universe` |
| 路由 + 业务 | ~300 行 | `generate_story`, `generate_story_full`, `generate_story_stream` |
| 绘本逻辑 | ~170 行 | `generate_storybook_api` (含并行图片生成) |
| 成就查询 | ~30 行 | `get_story_achievements` |
## 缺失端点
测试中引用但 **未实现** 的端点（这些应在拆分时一并补充）：
- `GET /api/stories` — 故事列表 (分页)
- `GET /api/stories/{id}` — 故事详情
- `DELETE /api/stories/{id}` — 故事删除
- `POST /api/image/generate/{id}` — 封面图片生成
- `GET /api/audio/{id}` — 语音朗读
## 建议拆分结构
```
app/
├── schemas/
│ └── story_schemas.py # [NEW] Pydantic 模型
├── services/
│ └── story_service.py # [NEW] 核心业务逻辑
└── api/
├── stories.py # [SLIM] 路由定义 + 依赖注入
└── stories_storybook.py # [NEW] 绘本相关端点 (可选)
```
### `story_schemas.py`
- 迁移所有 Pydantic 模型
- 包括 `GenerateRequest`, `StoryResponse`, `FullStoryResponse`, `StorybookRequest`, `StorybookResponse` 等
### `story_service.py`
- `validate_profile_and_universe()` — 验证逻辑
- `create_story()` — 故事入库
- `generate_and_save_story()` — 生成 + 保存联合操作
- `generate_storybook_with_images()` — 绘本并行图片生成
- 补充: `list_stories()`, `get_story()`, `delete_story()`
### `stories.py` (瘦路由层)
- 仅保留 `@router` 装饰器和依赖注入
- 调用 service 层完成业务逻辑
- 预计 150-200 行

89
docs/operations/ha-runbook.md Normal file
View File

@@ -0,0 +1,89 @@
# HA 部署与验证 Runbook（Phase 3 MVP）
本文档对应 `docker-compose.ha.yml`，用于本地/测试环境验证高可用基础能力。
## 1. 启动方式
```bash
docker compose -f docker-compose.yml -f docker-compose.ha.yml up -d
```
说明：
- 基础业务服务仍来自 `docker-compose.yml`。
- `docker-compose.ha.yml` 覆盖了 `db`、`redis`，并新增 `db-replica`、`postgres-backup`、`redis-replica`、`redis-sentinel-*`。
## 2. 核心环境变量建议
在 `backend/.env`（或 shell 环境）中至少配置：
```env
# PostgreSQL
POSTGRES_USER=dreamweaver
POSTGRES_PASSWORD=dreamweaver_password
POSTGRES_DB=dreamweaver_db
POSTGRES_REPMGR_PASSWORD=repmgr_password
# Redis Sentinel
REDIS_SENTINEL_ENABLED=true
REDIS_SENTINEL_NODES=redis-sentinel-1:26379,redis-sentinel-2:26379,redis-sentinel-3:26379
REDIS_SENTINEL_MASTER_NAME=mymaster
REDIS_SENTINEL_DB=0
REDIS_SENTINEL_SOCKET_TIMEOUT=0.5
# 可选：若 Sentinel/Redis 设置了密码
REDIS_SENTINEL_PASSWORD=
# 备份周期，默认 86400 秒（1 天）
BACKUP_INTERVAL_SECONDS=86400
```
## 3. 健康检查
### 3.1 PostgreSQL 主从
```bash
docker compose -f docker-compose.yml -f docker-compose.ha.yml ps
docker exec -it dreamweaver_db_primary psql -U dreamweaver -d dreamweaver_db -c "select now();"
docker exec -it dreamweaver_db_replica psql -U dreamweaver -d dreamweaver_db -c "select pg_is_in_recovery();"
```
期望：
- 主库可读写；
- 从库 `pg_is_in_recovery()` 返回 `t`。
### 3.2 Redis Sentinel
```bash
docker exec -it dreamweaver_redis_sentinel_1 redis-cli -p 26379 sentinel masters
docker exec -it dreamweaver_redis_sentinel_1 redis-cli -p 26379 sentinel replicas mymaster
```
期望：
- `mymaster` 存在；
- 至少 1 个 replica 被发现。
### 3.3 备份任务
```bash
docker exec -it dreamweaver_postgres_backup sh -c "ls -lh /backups"
```
期望：
- `/backups` 下出现 `.dump` 文件；
- 旧于 7 天的备份会被自动清理。
## 4. 故障切换演练（最小）
```bash
# 模拟 Redis 主节点故障
docker stop dreamweaver_redis_master
# 等待 Sentinel 选主后查看
docker exec -it dreamweaver_redis_sentinel_1 redis-cli -p 26379 sentinel get-master-addr-by-name mymaster
```
提示：应用与 Celery 已支持 Sentinel 配置。若未启用 Sentinel，仍可回退到 `REDIS_URL` / `CELERY_BROKER_URL` / `CELERY_RESULT_BACKEND` 直连模式。
## 5. 当前已知限制（下一步）
- PostgreSQL 侧当前仅完成主从拓扑，读写分离（PgBouncer/路由）待后续迭代。

450
docs/planning/document-status-inventory.md Normal file
View File

@@ -0,0 +1,450 @@
# DreamWeaver 文档状态盘点表
**Version**: 1.0
**Date**: 2026-04-17
**Author**: Sarah (Product Owner) / Codex
**Document Type**: Documentation Audit / Source-of-Truth Inventory
---
## 1. 盘点目的
这份文档不是新的 PRD，也不是新的技术方案，而是一份“项目资产盘点文档”。它解决三个问题：
1. 让团队快速分清楚 `docs/` 里哪些文件是当前有效文档，哪些只是历史材料。
2. 让产品文档与代码现实建立映射，避免“文档看起来很完整，但代码并没有落地”的错觉。
3. 在重新启动项目时，为后续改代码提供明确起点，减少无效重构和重复讨论。
对于求职版 DreamWeaver，这份盘点文档的价值在于：它帮助你把“会写需求文档”进一步提升为“会管理文档体系、会判断 source of truth、会做项目现状诊断”。
---
## 2. 盘点范围与判定口径
### 2.1 盘点范围
本次盘点覆盖以下对象：
- `docs/` 当前全部文档
- 后端核心实现：`backend/app/api/`、`backend/app/services/`、`backend/app/db/`
- 前端关键体验：`frontend/src/components/`、`frontend/src/views/`、`frontend/src/stores/`
- 运维相关配置：`docker-compose.ha.yml`、`backend/app/core/`
- 构建与验证结果：后端测试、后端 lint、主前端构建、管理端构建
### 2.2 文档状态定义
| 文档状态 | 含义 |
| --- | --- |
| Active | 当前有效，应作为近期工作的参考依据 |
| Reference | 有参考价值，但不能直接视为最新实现说明 |
| Archived | 保留历史价值，但不再作为现行 source of truth |
### 2.3 代码落地状态定义
| 落地状态 | 含义 |
| --- | --- |
| 非实现类文档 | 文档本身是产品/规划/治理文档，不直接对应“已实现/未实现” |
| 已实现 | 文档描述的主体能力已在代码中形成闭环，且验证结果基本通过 |
| 部分实现 | 已有主干能力，但关键路径、恢复能力、状态模型或工程质量仍未闭环 |
| 未实现 | 文档描述的主体仍是目标态，当前代码尚未形成有效落地 |
| 历史文档 | 文档描述对应的是过去的设计/阶段，部分内容已落地，但已不适合作为现行依据 |
### 2.4 本次验证快照
截至 2026-04-17 evening，本次盘点同步得到以下验证结果：
- 后端测试通过：`backend/` 下 `pytest -q` 结果为 `53 passed`
- 主前端类型检查通过：`frontend/` 下 `vue-tsc --noEmit` 成功
- 主前端完整构建在当前环境受 Rollup 可选原生包缺失影响，属于环境依赖问题，不是本轮状态模型改动直接引起
- 管理端范围仍未明确，不适合作为当前求职版稳定演示链路
- 后端 lint 仍有历史债务，尚未完成最后一轮收尾
这意味着：项目并不是“不能运行”，而是“核心主链路可用，但工程完备度和演示稳定性还没到求职成品状态”。
---
## 3. 文档状态总表
| 文档 | 分类 | 文档状态 | 代码落地状态 | 盘点结论 | 建议动作 |
| --- | --- | --- | --- | --- | --- |
| `docs/README.md` | 文档治理 | Active | 非实现类文档 | 当前 docs 分类规则清晰，已成为文档入口页 | 保留并持续维护 |
| `docs/product/job-search-relaunch-prd.md` | 产品 PRD | Active | 非实现类文档 | 是当前“求职版产品重启”的核心 source of truth | 保留，作为产品总纲 |
| `docs/product/unified-generation-workflow-prd.md` | 功能 PRD | Active | 部分实现 | 目标方向明确，但“统一工作流”目标态尚未真正落地 | 保留，作为改代码主依据 |
| `docs/planning/week-1-execution-backlog.md` | 执行规划 | Active | 非实现类文档 | 是执行计划，不应用它判断是否“已经做完” | 保留，并按完成情况更新 |
| `docs/planning/document-status-inventory.md` | 项目盘点 | Active | 非实现类文档 | 当前文档体系与代码现实的映射表 | 保留，后续按阶段更新 |
| `docs/technical/memory-system-dev.md` | 技术设计 | Reference | 部分实现 | 记忆系统主干已存在，但文档中不少内容仍是增强设计 | 保留，开发前逐条核验 |
| `docs/operations/ha-runbook.md` | 运维 Runbook | Reference | 部分实现 | Docker HA、Redis Sentinel、备份与 Celery Sentinel 支持已存在，但仍属基础版 | 保留，按真实环境演练继续校正 |
| `docs/archive/provider-system-legacy.md` | 历史技术文档 | Archived | 历史文档 | 部分设计已落地，但命名与架构描述已过时 | 继续归档，不再扩写 |
| `docs/archive/refactoring-plan-legacy.md` | 历史实施计划 | Archived | 历史文档 | 反映旧阶段重构过程，部分 checklist 已完成 | 继续归档，仅供回溯 |
| `docs/archive/stories-split-analysis-legacy.md` | 历史分析 | Archived | 历史文档 | 拆分分析对应的主要重构已发生 | 继续归档，仅供理解演进过程 |
---
## 4. 逐份文档判定说明
### 4.1 `docs/README.md`
**判定**
当前有效，属于“文档治理入口”。
**证据**
- 已明确区分 `product / planning / technical / operations / archive`
- 已写清删除与归档规则
- 已能帮助团队快速识别 source of truth
**结论**
这份文档不是实现说明，但它已经承担“文档信息架构”角色，应继续保留并作为 docs 首页。
### 4.2 `docs/product/job-search-relaunch-prd.md`
**判定**
当前有效，属于产品总纲文档。
**证据**
- 文档明确提出求职版产品定位、成功指标、P0/P1/P2 取舍
- 文档中的问题诊断与当前代码现实一致，包括：
- Storybook 恢复能力不足
- Provider 体系职责混杂
- Admin 构建问题影响演示
- 前端状态设计薄弱
**结论**
这份 PRD 不用于判断“是否已实现”，而用于回答“现在应该把项目做成什么样”。它是当前最重要的产品 source of truth。
### 4.3 `docs/product/unified-generation-workflow-prd.md`
**判定**
当前有效，但对应能力仅部分实现。
**证据**
- 当前后端仍保留多条生成路径：
- `POST /api/stories/generate`
- `POST /api/stories/generate/full`
- `POST /api/storybook/generate`
- 相关实现仍分别落在 `backend/app/api/stories.py` 与 `backend/app/services/story_service.py`
- 当前 `Story` 模型已具备统一主记录的基础字段：
- `story_text`
- `pages`
- `cover_prompt`
- `image_url`
- `mode`
- 当前已经落地的统一状态模型包括：
- `generation_status`
- `image_status`
- `audio_status`
- `last_error`
- `degraded_completed`
- 但更完整的工作流目标仍未完全实现，例如：
- `partial_ready`
- `retryable_assets`
- 统一资产重试入口
- 单一 generation service workflow
**结论**
这份文档对应的是“当前核心改造主线”。它已经不再只是方向性文档，因为统一状态模型和恢复能力已经开始落地；但它仍不是“已完成实现说明”，因为统一工作流入口和统一资产补全过程还未真正收束。
### 4.4 `docs/planning/week-1-execution-backlog.md`
**判定**
当前有效，属于执行计划文档。
**证据**
- 文档将工作拆成产品聚焦、工作流定义、Storybook 恢复、Admin 处理、Provider 边界梳理等任务
- 这些任务与盘点出的真实缺口一致
- 但多数事项仍未被代码完成，因此不能把这份文档当作“实现说明”
**结论**
这是一份“该做什么”的文档，不是“已经做了什么”的文档。后续应在每个任务完成后更新状态，而不是继续长期停留在初始 backlog。
### 4.5 `docs/technical/memory-system-dev.md`
**判定**
技术参考文档，部分实现。
**已落地部分证据**
- `backend/app/db/models.py` 中存在 `MemoryItem`、`ChildProfile`、`StoryUniverse`
- `backend/app/services/memory_service.py` 中已实现：
- 记忆类型定义
- 时效衰减评分
- Prompt 注入格式化
- TTL 清理
- recent story / favorite character / scary element 创建
- `backend/app/api/memories.py` 已提供记忆查询、创建、删除相关接口
- `backend/app/api/profiles.py` 已提供 `GET /profiles/{profile_id}/timeline`
- `backend/app/tasks/memory.py` 和 `backend/app/core/celery_app.py` 已接入每日清理任务
**未完全落地部分**
- 文档规划的反馈接口 `POST /api/memories/{id}/feedback` 当前不存在
- 更复杂的“长期印象总结”“通知机制”“更丰富的结构化 schema”尚未形成闭环
- 时间线目前主要由档案创建、故事记录、宇宙成就拼装而成，还不是完整的成长操作系统
**结论**
记忆系统不是“没做”，而是“已经有主干，但还停在可用原型阶段”。这份文档应该被保留为技术参考，但开发时必须逐条核验，不可直接按文档默认其已落地。
### 4.6 `docs/operations/ha-runbook.md`
**判定**
运维参考文档，部分实现。
**已落地部分证据**
- `docker-compose.ha.yml` 已提供：
- PostgreSQL 主库
- PostgreSQL 从库
- 定时备份容器
- Redis 主从
- 3 个 Sentinel 节点
- `backend/app/core/config.py` 已支持 Sentinel 相关配置解析
- `backend/app/core/redis.py` 已支持通过 Sentinel 获取 Redis master
- `backend/app/core/celery_app.py` 已支持 Celery broker/result backend 走 Sentinel
**未完全落地部分**
- 仍停留在 Docker Compose 层的基础 HA 演练，不是成熟生产级方案
- 尚未看到读写分离、连接池代理、监控告警等更完整设施
- 这份 runbook 更适合作为“基础 HA 实验手册”，而不是正式生产运维规范
**结论**
该文档不应删除，因为它对应的基础设施确实存在；但也不能对外表述成“完整 HA 能力已成熟上线”。
### 4.7 `docs/archive/provider-system-legacy.md`
**判定**
历史文档，部分内容已落地，但整体已过时。
**证据**
- 文档提到的 provider failover、metrics、secret management、admin console 等能力，在代码中能找到对应实现：
- `backend/app/services/provider_router.py`
- `backend/app/services/provider_metrics.py`
- `backend/app/services/secret_service.py`
- `backend/app/api/admin_providers.py`
- 但文档中的部分命名与现状不一致，例如仍提到 `app/admin_app.py`，而当前入口为 `backend/app/admin_main.py`
- 当前 provider router 同时承担默认配置、凭据映射、路由策略、熔断、成本记录等多项职责，说明体系已继续演化，不再等同于这份旧文档
**结论**
这份文档值得保留用于理解历史，但不能作为现行 provider 体系说明书。
### 4.8 `docs/archive/refactoring-plan-legacy.md`
**判定**
历史计划文档，部分任务已完成。
**证据**
- 文档中提到的 `stories.py` 拆分，目前已经有明显落地：
- `backend/app/services/story_service.py`
- `backend/app/schemas/story_schemas.py`
- `backend/app/api/stories.py`
- 文档中提到的 Redis / HA 方向也已有基础实现
- 但它描述的是更早阶段的改造路线，与当前“求职版重启”的产品目标已不是同一语境
**结论**
保留在 `archive/` 是合理的。它是“项目曾经怎么想”的材料，不是“现在应该怎么做”的材料。
### 4.9 `docs/archive/stories-split-analysis-legacy.md`
**判定**
历史分析文档，核心分析目的已经完成。
**证据**
- 文档聚焦 `stories.py` 过重的问题
- 当前已形成更合理的拆分：
- API 层保留路由
- schema 独立
- service 独立
- 说明它的主要使命已经完成
**结论**
应继续归档，用于未来解释“为什么会有现在的结构”，但不再参与当前需求决策。
---
## 5. 当前已落地的核心能力
以下能力已经具备“代码存在且主链路可验证”的基础：
### 5.1 内容生成基础能力
- 普通故事生成、完整故事生成、绘本生成均存在可调用接口
- `Story` 模型已能同时承载文本故事与分页绘本
- 封面图生成与成就提取已接入后处理链路
### 5.2 个性化上下文基础能力
- 孩子档案、故事宇宙、记忆系统、成长时间线均已有基础模型和接口
- Prompt 侧已接入记忆上下文构建
- 成就可回写到 `StoryUniverse.achievements`
### 5.3 Provider 管理基础能力
- Provider Router 已支持 failover
- Provider 管理、密钥管理、成本汇总等管理 API 已存在
- 默认 provider 列表与数据库 provider 配置可共存
### 5.4 运维与异步基础能力
- Celery + Redis 已接入
- Redis Sentinel 与 Celery Sentinel 配置已实现
- PostgreSQL 主从与备份的 Compose 级实验环境已存在
### 5.5 工程可运行性
- 后端测试通过：`53 passed`
- 主前端构建通过
---
## 6. 当前“部分实现 / 未实现”的关键缺口
这些缺口正是接下来改代码最应该优先处理的地方。
### 6.1 统一生成工作流尚未真正落地
虽然 PRD 已经明确目标，但当前系统仍是多入口、多响应模型、多处理路径并存。它们共享了一些底层能力，但还没有收束为统一 workflow。
### 6.2 Storybook 恢复能力不完整
当前前端仍依赖 `frontend/src/stores/storybook.ts` 暂存数据，`frontend/src/views/StorybookViewer.vue` 在刷新或直接访问时无法按 ID 恢复。这是最明显的“演示链路不稳”问题之一。
### 6.3 音频体验未形成闭环
当前 `GET /api/audio/{id}` 会在请求时即时生成音频，但没有持久化缓存与复用策略，既影响用户体验，也影响成本控制。
### 6.4 Provider 体系职责边界仍然混杂
当前 `provider_router.py` 既负责默认 provider、凭据映射、策略排序，又承担 metrics、熔断、成本记录等职责。功能虽强，但不利于后续持续演进，也不利于你在面试中清晰讲解。
### 6.5 管理端尚未达到“可展示成品”标准
`admin-frontend` 当前构建失败，说明管理端虽然概念上存在，但还不适合作为稳定演示链路的一部分。
### 6.6 工程质量信号还不统一
后端测试是加分项，但 lint 未通过会削弱成熟度观感。对于求职版项目，测试通过但 lint 大量报错，会让项目显得“能跑，但还没收尾”。
---
## 7. 推荐下一步编码切入点
如果目标是“尽快把项目恢复到可演示、可讲清、可继续迭代”的状态，建议按以下顺序推进。
### 7.1 第一优先级：补齐 Storybook 按 ID 恢复
**为什么先做**
- 改动范围相对可控
- 用户价值直观
- 修完后演示稳定性立刻提升
- 很适合作为“重新启动项目后的第一场胜仗”
**目标**
- `StorybookViewer` 不再只依赖 Pinia
- 支持通过 `story_id` 拉取 `Story.pages`
- 刷新页面后仍能继续阅读
### 7.2 第二优先级：抽出统一生成状态模型
**为什么第二个做**
- 这是“统一工作流”真正开始落地的最小切口
- 它能先统一语言，再统一代码
- 前端状态设计、后端任务编排、部分完成/降级完成，都会以它为中心展开
**目标**
- 先在服务层定义统一状态
- 再决定是否扩展数据库字段
- 让故事、绘本、图片、音频都能共享一套状态表达
### 7.3 第三优先级：清理 Provider 边界并决定 Admin 范围
**为什么第三个做**
- 这是系统长期可解释性的关键
- 但它比 Storybook 恢复和状态模型更抽象，适合在主链路稳定后推进
**目标**
- 先梳理 Capability / Provider / Routing Policy 三层概念
- 再判断管理端是修复、降级，还是缩小到只保留必要接口
---
## 8. 建议保留、更新、删除动作汇总
### 8.1 建议保留
- `docs/README.md`
- `docs/product/job-search-relaunch-prd.md`
- `docs/product/unified-generation-workflow-prd.md`
- `docs/planning/week-1-execution-backlog.md`
- `docs/technical/memory-system-dev.md`
- `docs/operations/ha-runbook.md`
- `docs/archive/*`
### 8.2 建议更新
- `docs/planning/week-1-execution-backlog.md`
- 需要随着任务推进更新完成状态，不应长期停留在纯规划状态
- `docs/technical/memory-system-dev.md`
- 后续开发时应补充“已实现”和“待实现”标记，减少误读
- `docs/operations/ha-runbook.md`
- 后续若做真实演练，应把演练结果写回文档
### 8.3 当前不建议再删除
本轮分类整理后，`docs/` 目录中没有新的“应该直接删除”的文档。剩余历史文件都具备学习价值或项目演进价值，适合继续保留在 `archive/`。
---
## 9. PM 学习笔记：为什么要写这种盘点文档
很多初级产品文档只会写“要做什么”，但不会回答：
- 现在手里的文档哪些是真的有效
- 哪些是目标态，哪些是现状
- 哪些能力已经能演示，哪些只是概念
- 哪些问题适合现在改，哪些问题应该晚一点改
“文档状态盘点表”就是用来解决这些问题的。它本质上是产品管理中的三项能力训练：
1. **Source of Truth 管理**
你要知道团队现在到底该信哪份文档。
2. **现状诊断能力**
你要把 PRD、代码、构建结果、运维配置放在一起看，而不是只看其中一边。
3. **优先级判断能力**
你要判断什么是“现在最值得做的第一件事”。
以后你在写自己的项目盘点时，可以直接复用这套结构：
1. 盘点目的
2. 判定口径
3. 状态总表
4. 逐项证据
5. 已落地能力
6. 关键缺口
7. 下一步建议
---
## 10. 本次盘点结论
DreamWeaver 当前不是“半成品废案”，而是“有明显实现基础、但还缺一轮产品收束与关键链路补完”的项目。
更准确地说：
- 产品层面，方向已经比以前清楚，现有 PRD 可以继续作为重启依据。
- 技术层面，后端主能力、记忆系统、Provider 管理、异步任务和基础 HA 都不是空白。
- 体验层面，Storybook 恢复、音频闭环、前端状态设计已明显推进，但统一工作流与统一重试入口仍是关键缺口。
- 工程层面，主前端与后端可用，但 admin-frontend 与 lint 问题说明项目还没完成最后一轮收尾。
因此，文档已经足够清晰，可以进入下一阶段：按优先级开始改代码，而不是继续扩写更多概念文档。

344
docs/planning/week-1-execution-backlog.md Normal file
View File

@@ -0,0 +1,344 @@
# DreamWeaver 求职版重启：Week 1 执行 Backlog
**Version**: 1.0
**Date**: 2026-04-17
**Author**: Sarah (Product Owner)
**Sprint Length**: 5 个工作日
**Sprint Theme**: 产品聚焦与核心生成链路收敛
---
## 1. Sprint Executive Summary
本周的核心任务不是“继续加功能”，而是为 DreamWeaver 的求职版重启建立一个稳定、可解释、可执行的基础版本。Week 1 的目标是完成三件事：
1. 明确 DreamWeaver 求职版的核心产品主线。
2. 明确统一生成工作流的目标状态与系统边界。
3. 识别并解决阻碍演示与后续开发的关键基础问题。
这意味着本周的重点是“收敛、抽象、对齐”，而不是“冲刺做完所有体验”。如果 Week 1 做得对，Week 2 的前端状态、音频体验和闭环演示才会顺。
---
## 2. Sprint Goal
### Sprint Goal
在 5 个工作日内，将 DreamWeaver 从“功能分散的 AI 项目”推进为“围绕个性化亲子故事体验的清晰产品方案”，并完成统一生成工作流的设计对齐与关键技术阻塞清单。
### Sprint Success Definition
本周结束时，团队应满足以下状态：
- 已统一项目对外叙事：DreamWeaver 是“个性化 AI 绘本与陪伴式讲述产品”。
- 已形成统一生成工作流的需求说明、状态模型和系统边界。
- 已确认 admin 端、Storybook 恢复能力、Provider 重构边界的处理方案。
- 已产出 Week 2 可直接进入开发的任务清单。
## 2.1 Current Progress Snapshot
**Updated**: 2026-04-17 evening
### What Has Been Completed
- 已完成求职版产品方向收敛，并形成 `docs/product/job-search-relaunch-prd.md` 与 `docs/product/unified-generation-workflow-prd.md`
- 已在代码中补齐 Storybook 按 ID 恢复，不再只依赖前端内存态
- 已在后端和前端落地统一状态字段与状态文案：
- `generation_status`
- `image_status`
- `audio_status`
- `last_error`
- 已补齐故事列表、故事详情、绘本阅读页的状态展示
- 已为故事音频增加首次生成后落盘缓存与后续复用
- 已新增数据库迁移：
- `0009_add_story_generation_statuses.py`
- `0010_add_story_audio_cache_path.py`
- 已完成一轮后端回归验证：`backend/` 下 `pytest -q` 结果为 `53 passed`
### What Is In Progress
- 统一状态模型已落地，但统一 service workflow 仍未真正收束成单一路径
- 普通故事、完整生成、绘本生成仍存在多条 service / API 路径
- 资产补全虽然已经支持图片与音频状态，但“统一重试入口”尚未实现
### What Is Still Pending
- admin-frontend 的处理决策与演示范围收敛
- Provider 的 Capability / Provider / Routing Policy 边界整理
- Week 2 可直接执行的开发任务表
- 演示 checklist 与最终收尾策略
### Remote Checkpoint Scope
当前远端已同步一个阶段性 checkpoint：
- Commit: `a97a2fe`
- Message: `feat: persist story generation states and cache audio`
这个 checkpoint **不是今天下午所有本地修改的全集**。它只覆盖以下主线：
- 统一生成状态模型
- Storybook 按 ID 恢复
- 故事列表/详情/绘本页状态展示
- 音频缓存与状态语义修正
当前工作区里仍存在其他未提交、本机独有的改动，周末换电脑后不会自动带过去。
---
## 3. Scope
### In Scope
- 产品主线收敛
- 统一生成工作流的需求定义
- Provider 概念重构边界梳理
- Storybook 恢复路径方案确认
- Admin 前端处理策略确认
- Week 2 开发前准备
### Out of Scope
- 大规模前端视觉重构
- 新增更多 AI 供应商
- 复杂监控大盘与成本后台
- 多租户、商业化支付、会员系统
- 全量高可用部署优化
---
## 4. Sprint Priorities
| Priority | Item | Why It Matters |
|------|------|------|
| P0 | 收敛产品定位 | 决定后续所有产品与技术选择 |
| P0 | 统一生成工作流定义 | 决定故事、绘本、音频、封面如何整合 |
| P0 | Storybook 恢复方案 | 当前是演示稳定性的关键缺口 |
| P0 | Admin 端处理决策 | 当前会影响完整构建与部署 |
| P1 | Provider 分层整理 | 为后续系统重构和面试讲解打底 |
| P1 | Week 2 任务准备 | 保证下周可直接进入执行 |
---
## 5. Week 1 User Stories
### Story A: 明确求职版产品主线
**As a** 项目拥有者
**I want to** 明确 DreamWeaver 求职版只讲一个清晰的产品故事
**So that** 我在面试和开发中都能聚焦重点
**Acceptance Criteria**
- [ ] 输出一句话产品定位
- [ ] 输出 3 条核心价值主张
- [ ] 明确哪些功能是本轮保留，哪些是延后
### Story B: 明确统一生成工作流
**As a** 产品负责人
**I want to** 用统一工作流来定义故事、绘本、封面和语音生成
**So that** 系统可以持续演进，而不是继续分裂
**Acceptance Criteria**
- [x] 定义统一状态模型
- [x] 明确故事与绘本的共同链路和差异
- [ ] 明确失败降级与重试原则
### Story C: 识别并拆解关键阻塞项
**As a** 求职项目维护者
**I want to** 找出影响演示和开发推进的关键阻塞
**So that** 后续投入能集中在最高价值项上
**Acceptance Criteria**
- [ ] 明确 admin-frontend 的处理方案
- [x] 明确 Storybook 恢复方案
- [ ] 明确 Provider 重构边界
---
## 6. Task Backlog
| ID | Workstream | Task | Output | Priority | Estimate | Status |
|------|------|------|------|------|------|------|
| W1-01 | Product | 确认求职版产品定位与展示口径 | 一句话定位 + 3 条价值主张 | P0 | 0.5d | Done |
| W1-02 | Product | 梳理本轮 In Scope / Out of Scope | 范围清单 | P0 | 0.5d | Done |
| W1-03 | Product / System | 盘点现有生成路径：普通故事、完整生成、绘本生成 | 现状流程图或对照表 | P0 | 0.5d | Done |
| W1-04 | Product / System | 定义统一 Generation Workflow 状态模型 | 状态流转说明 | P0 | 1.0d | Done |
| W1-05 | Product / Backend | 定义统一工作流下的 API / 数据结构影响 | 接口与模型变更清单 | P0 | 0.5d | In Progress |
| W1-06 | Product / Backend | 梳理 Provider 概念层：Capability / Provider / Routing Policy | 分层图与术语表 | P1 | 0.5d | Pending |
| W1-07 | Product / Frontend | 梳理 Storybook 当前问题与恢复方案 | 恢复方案说明 | P0 | 0.5d | Done |
| W1-08 | Product / Frontend | 确认 admin 前端是修复、裁剪还是暂时降级 | 决策记录 | P0 | 0.5d | Pending |
| W1-09 | Planning | 产出 Week 2 开发任务清单 | 下周 backlog | P1 | 0.5d | In Progress |
| W1-10 | Review | 形成求职演示版检查清单 | 演示清单 | P1 | 0.5d | Pending |
---
## 7. Recommended Execution Sequence
### Day 1: 产品聚焦
- 完成求职版产品定位
- 确认本轮保留功能与延后功能
- 输出一句话产品口径和核心价值主张
**Expected Output**
- 产品定位 statement
- MVP 范围清单
- 非本轮范围说明
### Day 2: 现状拆解
- 盘点当前三类生成路径
- 对比普通故事、完整故事、绘本生成的共同点与差异
- 找出重复步骤与缺失状态
**Expected Output**
- 现状流程对照表
- 问题清单
- 工作流统一方向初稿
### Day 3: 统一工作流定义
- 确定 Generation Workflow 的状态模型
- 明确文本、封面、语音、绘本页的生成关系
- 明确哪些步骤同步、哪些异步
**Expected Output**
- 统一工作流草案
- 状态流转图
- 失败降级规则
### Day 4: 关键阻塞项决策
- 明确 Storybook 恢复方案
- 明确 admin 端处理策略
- 明确 Provider 重构边界和迁移原则
**Expected Output**
- 技术决策记录
- Week 2 实施前置条件
### Day 5: Sprint Wrap-up
- 整理 Week 2 可执行任务
- 形成演示清单与风险清单
- 输出周总结
**Expected Output**
- Week 2 backlog
- 演示 checklist
- Sprint review summary
---
## 8. Deliverables
本周必须交付的成果如下：
1. 求职版产品定位文档
2. 统一生成工作流功能级 PRD
3. Storybook 恢复方案说明
4. Admin 端处理决策
5. Week 2 开发 Backlog
6. 演示检查清单
## 8.1 Weekend Handoff Guidance
如果周末在另一台电脑继续推进，建议按以下顺序接手：
1. 先拉取远端 `main`，确认已经包含 commit `a97a2fe`
2. 先阅读：
- `docs/product/job-search-relaunch-prd.md`
- `docs/product/unified-generation-workflow-prd.md`
- 当前这份 backlog
3. 运行数据库迁移：`alembic upgrade head`
4. 从“统一资产补全”和“统一 service workflow”继续，而不是重新发散到新功能
建议周末接续时的第一优先级：
- 抽出图片/音频统一资产补全过程
- 设计并实现统一的重试入口
- 继续收敛普通故事、完整生成、绘本生成三条路径
---
## 9. Definition of Done
只有满足以下条件，Week 1 才视为完成：
- [ ] 产品定位能用 30 秒讲清楚
- [ ] 统一生成工作流的状态模型已明确
- [ ] 关键阻塞项均有明确处理方案，不处于“再看看”
- [ ] Week 2 有可直接执行的任务表
- [ ] 所有本周产出都已沉淀为书面文档
---
## 10. Risks
| Risk | Likelihood | Impact | Mitigation |
|------|------|------|------|
| 本周又回到“继续加功能” | High | High | 每天检查任务是否服务于核心闭环 |
| Provider 讨论过深，脱离产品目标 | Medium | High | 保持“求职版可解释性”优先，不做过度设计 |
| 前端细节打断主线梳理 | High | Medium | Week 1 不做大量视觉细化，只做策略与任务定义 |
| Storybook 恢复方案定义不清 | Medium | High | 必须把“按 ID 恢复”作为明确目标，不接受模糊状态 |
---
## 11. Dependencies
- 已有 PRD: `docs/product/job-search-relaunch-prd.md`
- 当前生成接口与数据结构
- Storybook Viewer 与 Store 实现
- Provider Router 当前实现
---
## 12. Suggested Daily Rituals
为了帮助你模仿真实产品经理工作方式，建议你在执行本周任务时保持以下节奏：
- **每日开始前**：先写今天要解决的 1 个核心问题。
- **每日结束时**：用 3 句话回答：
- 今天明确了什么？
- 还有什么不确定？
- 明天最重要的一件事是什么？
这会帮助你从“想到什么做什么”转向“围绕目标做判断”。
---
## 13. How to Reuse This Format
以后你自己写 Sprint Backlog 或执行计划时，可以直接套用这套结构：
1. Executive Summary
2. Sprint Goal
3. Scope
4. Priorities
5. User Stories
6. Task Backlog
7. Recommended Execution Sequence
8. Deliverables
9. Definition of Done
10. Risks / Dependencies
和 PRD 不同，Backlog 文档更偏执行，不需要写太多业务背景，但一定要写清楚：
- 这周为什么做
- 这周不做什么
- 每天要推进什么
- 什么状态算完成
---
*This document is intended as a PM-style execution backlog for Week 1 of the DreamWeaver portfolio relaunch.*

125
docs/planning/weekend-handoff-2026-04-17.md Normal file
View File

@@ -0,0 +1,125 @@
# DreamWeaver Weekend Handoff - 2026-04-17
## Purpose
这份文档用于周末在另一台电脑上继续推进 DreamWeaver 时快速接手，不需要先重新阅读大量聊天记录或从工作区猜测上下文。
---
## What Is Already On Remote
当前远端已经包含一个阶段性 checkpoint：
- Commit: `a97a2fe`
- Message: `feat: persist story generation states and cache audio`
这个 checkpoint 覆盖的主线如下：
- 新增并落地统一生成状态字段：
- `generation_status`
- `image_status`
- `audio_status`
- `last_error`
- Storybook 阅读页支持按 ID 恢复
- 故事列表页、故事详情页、绘本阅读页接入统一状态展示
- 音频首次生成后缓存落盘并可复用
- 统一状态语义中 `degraded_completed` 已和错误展示保持一致
---
## What Is Not Yet On Remote
当前这台机器的工作区里仍存在大量未提交改动，它们 **不属于上面的 checkpoint**，也不会自动出现在另一台电脑上。
因此，周末接手时应该默认：
- 远端 `main` 只包含“统一状态模型 + Storybook 恢复 + 音频缓存”这一条主线
- 其他本机未提交内容需要后续再整理，不应假设它们已经同步
---
## Recommended Reading Order
周末继续前，建议先阅读：
1. `docs/product/job-search-relaunch-prd.md`
2. `docs/product/unified-generation-workflow-prd.md`
3. `docs/planning/week-1-execution-backlog.md`
4. `docs/planning/document-status-inventory.md`
---
## Environment Setup On The Next Machine
建议接手后先完成以下动作：
1. `git pull`
2. `cd backend && alembic upgrade head`
3. `cd backend && ./.venv/Scripts/python.exe -m pytest -q`
4. `cd frontend && npm install`
5. `cd frontend && ./node_modules/.bin/vue-tsc --noEmit`
如果主前端完整构建失败，优先检查 Rollup 可选原生包是否正常安装，而不是先怀疑本轮代码逻辑。
---
## Current Product / Engineering Position
当前阶段不是“继续加功能”，而是把 DreamWeaver 收敛成可讲述、可演示、可恢复的求职版产品。
已经完成的关键支点：
- 状态模型已落地，不再只是文档概念
- Storybook 恢复能力已补上
- 音频体验开始形成闭环
还没完成的关键工作：
- 普通故事、完整生成、绘本生成仍是多条 service 路径
- 缺少统一资产重试入口
- 缺少更清晰的统一 workflow 编排边界
- admin-frontend 范围和 Provider 边界仍未收束
---
## Best Next Step
周末最值得继续做的第一优先级：
### P0: 统一资产补全过程
目标：
- 抽出封面生成和音频生成的共同步骤
- 让图片 / 音频共享一套资产状态回写逻辑
- 为后续“统一重试入口”打基础
为什么先做：
- 它直接承接已经落地的状态模型
- 它比继续加页面更能体现系统设计能力
- 它能把当前三条生成路径往统一 workflow 再推近一步
### P1: 统一重试入口
目标：
- 至少设计出一个清晰的 retry API 方向
- 即使不一次性重命名为 `/api/generations/...`，也先做到内部统一
### P1: 收敛 service workflow
目标：
- 梳理普通故事 / 完整生成 / 绘本生成的共同步骤
- 把“验证上下文 -> 生成主内容 -> 保存主记录 -> 补全资产 -> 状态回写”整理成更明确的共享流程
---
## Important Reminder
如果周末是在另一台电脑上继续，不要默认“今天下午所有本地修改”都已经上远端。当前最可靠的 source of truth 是：
- 远端代码：以 commit `a97a2fe` 为准
- 产品目标：以 `docs/product/job-search-relaunch-prd.md` 为准
- 当前执行主线：以 `docs/product/unified-generation-workflow-prd.md` 与 `docs/planning/week-1-execution-backlog.md` 为准

474
docs/product/job-search-relaunch-prd.md Normal file
View File

@@ -0,0 +1,474 @@
# Product Requirements Document: DreamWeaver 求职版产品重启与重构
**Version**: 1.0
**Date**: 2026-04-17
**Author**: Sarah (Product Owner)
**Quality Score**: 91/100
---
## Executive Summary
DreamWeaver 当前已经具备一个 AI 儿童故事产品的基础能力，包括故事生成、绘本生成、封面图生成、语音合成、孩子档案、故事宇宙、记忆系统与供应商路由能力。从“功能数量”上看，这个项目并不空，但从“产品完成度”上看，当前版本的核心问题是价值主线分散、工作流不统一、供应商体系复杂度过高，导致产品体验不够聚焦，项目故事也不够适合面试场景快速讲清楚。
本次重启不以“继续堆功能”为目标，而以“构建一个求职可展示、逻辑可讲述、体验可闭环的 AI 产品版本”为目标。求职版 DreamWeaver 将聚焦为一个“面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲述产品”，突出三个核心价值：个性化连续性、稳定的生成工作流、可感知的声音体验。
本 PRD 旨在为后续 2 周至 4 周的产品重构提供明确的目标、范围、优先级与阶段计划。文档同时兼具两个用途：一是作为当前项目的重启执行依据；二是作为转型 AI 产品经理时可模仿的标准化产品文档样本。
---
## Problem Statement
**Current Situation**
DreamWeaver 目前存在以下产品层与系统层问题：
1. 产品主线不清晰。系统同时在讲“儿童故事产品”“成长记忆产品”“多供应商 AI 编排平台”三个故事，但没有一个故事被打磨到足够完整。
2. 关键工作流分裂。普通故事生成、完整生成、绘本生成分别走不同实现，验证、上下文、保存、资产生成与后处理逻辑重复，难以稳定演进。
3. 供应商体系职责混杂。Provider 路由层同时承担默认配置、Key 映射、路由策略、熔断、成本统计、执行入口等多项职责，维护成本高，后续扩展风险大。
4. 演示链路不够稳。Storybook 阅读器依赖内存状态，刷新后无法恢复；音频未做缓存；管理端构建失败会阻碍全量部署。
5. 工程观感不统一。后端测试可通过，但 lint 历史债务较多，前后端重复代码较多，项目成熟度展示受影响。
**Proposed Solution**
将项目收敛为“求职版 DreamWeaver MVP”，围绕一个可讲清楚的核心闭环进行重构：
`选择孩子档案 -> 输入主题/教育目标 -> 生成故事或绘本 -> 生成封面/语音 -> 保存进入故事库与成长时间线`
系统层同步推进两项重构：
1. 将故事/绘本/资产生成统一到一套 Generation Workflow 中。
2. 将供应商体系重构为清晰的 Capability / Provider / Routing Policy 分层结构。
**Business Impact**
本轮重构完成后，项目在求职场景中的价值将从“会调用多个模型的功能集合”提升为“有明确价值主张、闭环体验和系统设计取舍的 AI 产品案例”，更适合作为 AI 产品经理岗位的核心项目展示。
---
## Current Product Diagnosis
| 诊断项 | 当前表现 | 对产品的影响 | 判断 |
|------|------|------|------|
| 核心价值主张 | 功能较多，但主线分散 | 面试官难以快速理解产品价值 | P0 问题 |
| 生成工作流 | 故事、完整生成、绘本三套路径并存 | 需求扩展成本高，失败处理不一致 | P0 问题 |
| Provider 架构 | 路由、配置、凭证、监控耦合 | 后续优化与说明成本过高 | P0 问题 |
| Storybook 体验 | 依赖前端内存状态，无法按 ID 恢复 | 阅读体验中断，演示不稳 | P0 问题 |
| 音频体验 | 支持实时生成，但无缓存与复用 | 性能与成本不可控 | P1 问题 |
| Admin 前端 | 构建失败，影响完整部署链路 | 一键启动和展示受阻 | P0 问题 |
| 代码质量信号 | 后端测试通过，但 lint 债务明显 | 降低项目成熟度感知 | P1 问题 |
| 前端表现力 | 可用但较轻，缺少状态设计与产品表达 | 难以承载“生成中/失败/降级成功”等体验 | P1 问题 |
---
## Product Positioning
### 产品定位
DreamWeaver 是一款面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲述产品，通过孩子档案、成长主题和故事宇宙上下文，为家庭生成连续、可回看、可聆听的儿童故事体验。
### 求职版定位
求职版 DreamWeaver 不是“最全功能版本”，而是“最能体现产品思考与系统设计能力的版本”。
该版本重点体现以下能力：
- 能围绕明确用户价值做产品收敛，而不是单纯堆功能。
- 能把多模型、多供应商能力整理成稳定、可解释的 AI 工作流。
- 能把声音体验、个性化连续性和失败降级机制变成真正的产品能力。
### 核心价值主张
1. **个性化连续性**：故事不是一次性生成，而是围绕孩子档案与世界观不断积累。
2. **陪伴式体验**：文本、绘本和语音不是孤立能力，而是一套完整的亲子阅读体验。
3. **生成稳定性**：用户不需要理解底层模型，只需要感受到“能稳定出结果，失败也可恢复”。
---
## Success Metrics
**Primary KPIs**
- **故事生成成功率**：核心生成链路成功完成率 >= 90%
测量方式：生成请求中完成文本输出并成功保存主记录的比例。
- **首个结果可见时长**：用户发起生成后，首个可见结果出现时间 <= 15 秒
测量方式：文本结果或“部分完成”状态首次返回时间。
- **完整体验完成率**：文本、封面、语音至少完成其二的比例 >= 80%
测量方式：故事生成后资产完成状态统计。
- **个性化命中率**：在内部评审样本中，>= 80% 的故事能明显体现孩子档案/宇宙上下文
测量方式：人工评估打分表。
- **演示可用率**：求职演示关键链路 10 次连续演示成功率 = 100%
测量方式：内部演示脚本回归。
**Validation**
- 第 1 阶段验证：以“是否能完成端到端故事闭环”为准。
- 第 2 阶段验证：以“是否能稳定支持绘本与语音回放体验”为准。
- 对外验证：以面试演示反馈和项目讲解清晰度为准。
---
## User Personas
### Primary Persona: 家长 / 监护人
- **Role**: 3-8 岁儿童的家长或监护人
- **Goals**:
- 为孩子快速生成有趣、温暖、可教育的故事
- 让孩子成为故事主角，形成陪伴感
- 在睡前、亲子共读等场景中使用语音或绘本
- **Pain Points**:
- 一次性生成内容容易同质化
- 缺少与孩子长期成长相关的连续性
- 语音与插图往往不是同一套体验的一部分
- **Technical Level**: 初中级
### Secondary Persona: 产品拥有者 / 运营管理员
- **Role**: 产品负责人、创作者或系统维护者
- **Goals**:
- 稳定控制模型调用效果、成本和失败降级
- 保持产品演示链路稳定
- 对系统结构有解释力，便于招聘场景展示
- **Pain Points**:
- Provider 配置复杂，难以讲清楚
- 多条工作流重复演化，维护成本高
- 工程质量与展示价值不匹配
- **Technical Level**: 中高级
---
## User Stories & Acceptance Criteria
### Story 1: 快速生成个性化故事
**As a** 家长
**I want to** 基于孩子档案和教育主题生成一个故事
**So that** 我能快速得到适合孩子的阅读内容
**Acceptance Criteria**
- [ ] 用户可以选择孩子档案并输入主题或教育目标
- [ ] 系统能结合档案与宇宙上下文生成故事文本
- [ ] 故事保存后可在故事库中查看
- [ ] 当图片或语音生成失败时，故事文本仍可正常保留并查看
### Story 2: 生成并阅读绘本
**As a** 家长
**I want to** 生成一个多页绘本并在前端顺畅阅读
**So that** 我能获得更强的陪伴和共读体验
**Acceptance Criteria**
- [ ] 系统支持多页绘本生成
- [ ] 绘本可通过唯一 ID 被再次打开，而不是只依赖前端内存状态
- [ ] 页面刷新或重新进入时，绘本内容仍能恢复
- [ ] 若部分页面插图失败，文本页仍可正常展示
### Story 3: 听故事
**As a** 家长
**I want to** 播放故事语音
**So that** 我可以在睡前或陪伴场景下使用
**Acceptance Criteria**
- [ ] 故事详情页支持加载和播放语音
- [ ] 同一故事音频应支持缓存或复用，避免重复生成
- [ ] 音频生成失败时，页面应给出明确状态与重试方式
### Story 4: 管理模型供应与成本风险
**As a** 产品拥有者
**I want to** 以清晰的方式管理不同能力对应的供应商
**So that** 我能解释系统架构，并稳定控制成本与故障
**Acceptance Criteria**
- [ ] Provider 配置以能力、供应商、模型配置的方式组织
- [ ] 路由策略与凭证管理职责分离
- [ ] 系统能清楚展示失败降级逻辑
- [ ] 管理端或配置文档能说明当前有效供应链路
---
## Functional Requirements
### Core Feature 1: 统一的生成工作流
- **Description**: 将普通故事、完整故事、绘本生成统一到一套生成任务模型中。
- **User Flow**:
1. 用户发起生成
2. 系统校验档案与宇宙关系
3. 系统构建 memory/context
4. 系统生成文本或绘本结构
5. 系统保存主记录
6. 系统异步生成封面与语音
7. 系统回写状态
- **Edge Cases**:
- 用户未选择孩子档案
- 故事宇宙与孩子档案不匹配
- 部分资产生成失败
- **Error Handling**:
- 文本失败：返回明确错误，不保存空故事
- 图片失败：标记为部分完成，可后续重试
- 音频失败：不阻塞文本阅读
### Core Feature 2: 个性化上下文注入
- **Description**: 将孩子档案、成长主题、故事宇宙和记忆系统统一视为内容上下文，而不是附属配置。
- **User Flow**:
1. 用户选择档案
2. 系统聚合角色、兴趣、成长主题、宇宙设定、记忆
3. 生成结果体现上下文
- **Edge Cases**:
- 没有档案时，允许通用生成
- 没有宇宙时，允许使用基础档案
- **Error Handling**:
- 某类上下文缺失不应阻塞生成，只进行降级
### Core Feature 3: 绘本与语音的可恢复体验
- **Description**: 阅读器和音频播放应支持重新进入、状态恢复与降级处理。
- **User Flow**:
1. 用户打开故事详情或绘本详情
2. 系统按 ID 拉取内容
3. 页面展示当前已完成资产
4. 用户按需触发图片或音频补全
- **Edge Cases**:
- 页面刷新
- 资产未生成完成
- 资产生成失败
- **Error Handling**:
- 以状态展示替代“空白失败”
- 保留重试入口
### Core Feature 4: 简化后的 Provider Orchestration
- **Description**: 供应商系统应服务于“稳定生成”，而不是暴露为产品主角。
- **User Flow**:
1. 系统根据能力类型加载 provider 列表
2. 根据 routing policy 选择执行顺序
3. 调用成功即返回结果，失败则自动切换
4. 记录成本、耗时与错误
- **Edge Cases**:
- 没有可用 provider
- provider 凭证缺失
- 同类 provider 全部失败
- **Error Handling**:
- 返回聚合错误
- 支持 degraded completion
### Core Feature 5: 演示级前端关键体验
- **Description**: 前端优先完成关键状态设计，而不是先追求大规模视觉升级。
- **Required States**:
- 初始化
- 生成中
- 文本已完成、资产处理中
- 部分完成
- 全部完成
- 失败与重试
- **UI Principles**:
- 用户始终知道系统当前在做什么
- 用户始终知道下一步能做什么
- 页面刷新后体验不中断
### Out of Scope
- 新增大量供应商类型或复杂负载均衡策略
- 多租户 Provider 管理
- 复杂高可用部署优化作为本轮核心目标
- 高保真商业化支付、会员与订阅系统
- 花大量时间做纯视觉层重做
---
## Technical Constraints
### Performance
- 文本生成应在 15 秒内给出首个可用结果或明确状态
- 图片/语音资产生成可异步完成，但前端必须有可见状态
- 绘本详情和故事详情需支持按 ID 快速恢复
### Security
- 继续使用现有 JWT + httpOnly Cookie 认证方案
- Provider 密钥应保持加密管理，不在前端暴露
- 管理端仅保留必要入口，默认不作为求职版核心展示对象
### Integration
- **Text Providers**: Gemini / OpenAI 作为文本能力候选
- **Image Providers**: CQTAI / Antigravity 作为图片能力候选
- **TTS Providers**: MiniMax / ElevenLabs / Edge TTS 作为语音能力候选
- **Background Jobs**: Celery + Redis 负责后处理与异步任务
### Technology Stack
- **Backend**: FastAPI + SQLAlchemy Async + PostgreSQL + Celery/Redis
- **Frontend**: Vue 3 + TypeScript + Pinia + Tailwind CSS
- **Design Principle**: 先完成状态与流程设计，再做界面强化
---
## MVP Scope & Phasing
### Phase 1: MVP (2 周)
**目标**: 做出一个求职可演示、逻辑清晰、体验闭环的 AI 故事产品版本
**MVP Scope**
- 统一故事 / 完整生成 / 绘本生成的工作流抽象
- 将 Storybook 页面改为支持按 ID 恢复
- 修复管理端构建问题，或明确降级为非核心链路
- 清理 Provider 概念层，去掉历史别名与混杂职责
- 为图片/音频生成增加明确状态与重试入口
- 清理关键 lint 与工程观感问题
**MVP Definition**
用户可以稳定完成一次“选择孩子档案 -> 生成故事/绘本 -> 获取封面/语音 -> 回看或继续阅读”的完整体验，且系统结构可以被清晰讲述。
### Phase 2: Enhancements (4 周)
- 音频缓存与复用
- 记忆系统与时间线联动优化
- Provider 健康状态与成本摘要
- 演示级前端优化，包括结果页、状态页和阅读页体验
- 补齐缺失测试，提升工程可信度
### Future Considerations
- 更细粒度的叙事风格与音色策略
- 睡前模式 / 陪伴模式
- 教师场景或课程场景扩展
- 更复杂的成本路由与多租户配置
---
## Prioritization Matrix
| Priority | 事项 | 目标 | 原因 |
|------|------|------|------|
| P0 | 收敛产品主线 | 明确“个性化 AI 绘本与陪伴讲述”定位 | 决定后续所有范围 |
| P0 | 统一生成工作流 | 消除故事/绘本/资产生成的分裂实现 | 是系统稳定性的核心 |
| P0 | Provider 概念重构 | 拆清 Capability / Provider / Routing Policy | 是系统可解释性的核心 |
| P0 | Storybook 可恢复体验 | 支持按 ID 加载与刷新恢复 | 是演示稳定性的核心 |
| P0 | 修复 admin-frontend 构建或明确降级 | 保证一键启动或明确非核心范围 | 避免部署阻塞 |
| P1 | 音频缓存与重试 | 强化声音体验和成本控制 | 与你的背景强相关 |
| P1 | 前端状态设计 | 让生成中、失败、部分完成可感知 | 提升产品成熟度 |
| P1 | 补测试与 lint 清理 | 提升工程可信度 | 有助于面试展示 |
| P2 | 增加更多 Provider | 扩展覆盖面 | 当前不是关键短板 |
| P2 | 管理后台复杂可视化 | 增强运维能力 | 不是求职版核心 |
| P2 | 大规模视觉升级 | 提升表层观感 | 应晚于闭环与稳定性 |
---
## Delivery Plan
### 第 1 阶段：2 周执行清单
#### Week 1
- 完成产品主线和展示口径收敛
- 定义统一的 Generation Job 状态模型
- 拆分 Provider 层职责，输出新概念模型
- 决定 admin 端保留范围
- 修复 Storybook 依赖内存状态的问题
#### Week 2
- 将前端关键页面补齐状态与重试
- 打通故事生成与绘本生成的统一流程
- 输出一版稳定演示脚本
- 清理关键 lint 问题
- 完成一轮端到端回归测试
### 第 2 阶段：4 周执行清单
#### Week 3
- 上线音频缓存与复用
- 让时间线、记忆、故事结果之间形成更清晰关联
- 增加失败降级与资产补全机制
#### Week 4
- 完善前端结果体验与语音体验
- 补齐缺失测试
- 输出项目说明文档、架构图和演示话术
- 完成求职版 Demo 包装
---
## Risk Assessment
| Risk | Probability | Impact | Mitigation Strategy |
|------|------------|--------|---------------------|
| 重构范围失控 | High | High | 严格限制本轮只服务一个核心闭环，不新增大功能 |
| Provider 重构导致兼容性问题 | Medium | High | 先保留兼容层，再逐步迁移配置 |
| Storybook/音频链路改动引入回归 | Medium | High | 补关键回归测试与演示脚本 |
| 前端优化挤占后端重构时间 | High | Medium | 前端只做状态和关键体验，不做全量视觉翻新 |
| 求职展示与真实产品目标冲突 | Medium | Medium | 将“求职版”定义为独立阶段目标，不追求商业化全量能力 |
---
## Dependencies & Blockers
**Dependencies**
- 现有后端数据库模型和迁移能力
- 现有 Provider Adapter 体系
- Vue 前端页面与 Pinia 状态管理
- 可用的测试与构建环境
**Known Blockers**
- 管理端前端当前构建失败
- Storybook 阅读器缺少按 ID 恢复能力
- 音频未缓存，体验和成本不可控
- Provider Router 耦合度高，任何修改都容易牵动多处逻辑
---
## Appendix
### Assumptions
- 本轮目标以求职展示为第一优先级，而非商业化上线。
- 目标用户仍然是 3-8 岁儿童家庭场景。
- 当前技术栈保持不变，不进行大规模框架迁移。
- 管理后台是辅助能力，不作为本轮展示主角。
### Glossary
- **Generation Workflow**: 从用户输入到文本、图片、语音完成的一整套生成流程。
- **Capability**: 底层 AI 能力分类，如文本、图片、语音。
- **Provider**: 具体供应商，如 Gemini、OpenAI、MiniMax。
- **Routing Policy**: 供应商选择与降级策略。
- **Degraded Completion**: 资产部分失败但主结果可用的完成状态。
### 如何模仿本类文档
当你以后写自己的 PRD 或产品方案时，可以复用这套骨架：
1. 先写 Executive Summary，说明产品现在为什么要做这件事。
2. 再写 Problem Statement，拆清当前问题、方案与业务影响。
3. 给出 Success Metrics，避免文档只有想法没有验证标准。
4. 用 Persona 和 User Story 把“用户价值”写实，而不是只写功能点。
5. 在 Functional Requirements 里同时写 happy path、edge case 和 error handling。
6. 用明确的 Out of Scope 防止范围不断膨胀。
7. 用 P0/P1/P2 或阶段计划体现产品判断，而不是罗列任务。
8. 最后补风险、依赖和假设，让文档更像真正可执行的产品方案。
### References
- `backend/app/services/provider_router.py`
- `backend/app/services/story_service.py`
- `frontend/src/views/StorybookViewer.vue`
- `frontend/src/stores/storybook.ts`
- `backend/tests/`
---
*This PRD was created as a job-search-oriented product reboot plan, with emphasis on product focus, AI workflow clarity, and portfolio-ready execution quality.*

510
docs/product/unified-generation-workflow-prd.md Normal file
View File

@@ -0,0 +1,510 @@
# Product Requirements Document: 统一生成工作流
**Version**: 1.0
**Date**: 2026-04-17
**Author**: Sarah (Product Owner)
**Quality Score**: 93/100
---
## Executive Summary
DreamWeaver 当前同时支持普通故事生成、完整故事生成和绘本生成，但这三类能力在系统中以不同接口、不同服务路径和不同前端消费方式存在，已经开始阻碍产品迭代。当前实现能工作，但不利于功能演化，也不利于在求职场景中讲清楚产品系统逻辑。
统一生成工作流的目标，是将“文本生成、封面生成、语音生成、绘本页生成、后处理（记忆/成就）”纳入一套统一的产品与系统模型中。对于用户，统一工作流意味着结果更稳定、失败更可解释、页面状态更清晰；对于产品和工程，统一工作流意味着需求不会在多个分叉路径中重复实现。
本 PRD 面向 DreamWeaver 求职版 MVP，重点定义统一生成工作流的目标用户、状态模型、功能边界、数据结构演进方向、前后端行为以及发布优先级。
## Implementation Snapshot
**Updated**: 2026-04-17 evening
当前代码已经从“纯目标态设计”进入“部分落地”阶段，主要进展如下：
### Already Landed
- `Story` 主记录已持久化以下统一状态相关字段：
- `generation_status`
- `image_status`
- `audio_status`
- `last_error`
- `audio_path`
- Storybook 阅读器已支持按 ID 恢复，不再只依赖 Pinia 内存态
- 故事列表页、故事详情页、绘本阅读页已接入统一状态展示
- 故事音频已支持首次生成后缓存复用
- `degraded_completed` 已在服务层和前端语义中落地
### Still Missing
- 统一的 `POST /api/generations` 风格入口尚未建立
- 普通故事、完整生成、绘本生成仍通过多条 service 路径实现
- “统一资产重试入口”尚未落地
- `partial_ready`、`retryable_assets` 等更细粒度状态仍停留在目标态
### What This Means
这份 PRD 仍然是目标态文档，但它对应的主干方向已经不是纸面方案。当前最适合的继续方式，不是重写文档，而是继续把 service workflow 和资产补全过程收拢成统一实现。
---
## Problem Statement
**Current Situation**
DreamWeaver 当前存在以下工作流层面问题：
1. **生成入口不统一**
普通故事走 `/api/stories/generate`，完整故事走 `/api/stories/generate/full`，绘本走 `/api/storybook/generate`，前端对结果的处理也不同。
2. **保存与资产补全过程不统一**
有的流程先存文本再补图，有的流程只返回绘本对象并依赖前端 store，有的流程不考虑音频状态。
3. **状态表达不统一**
系统缺少标准的“生成中、部分完成、已完成、失败、可重试”等状态定义，导致前端难以做出成熟体验。
4. **失败处理策略不统一**
图片、音频、绘本页生成失败时，系统没有统一的降级定义，用户体验和技术行为都不够稳定。
5. **恢复能力不足**
尤其是绘本路径，依赖前端内存态，页面刷新或重进后无法恢复。
**Proposed Solution**
引入统一的 Generation Workflow，将不同内容模式视为同一工作流下的不同配置，而不是完全不同的产品流程。系统将围绕一个统一对象进行组织：
- 请求输入
- 上下文准备
- 文本或绘本结构生成
- 主记录保存
- 资产异步补全
- 状态回写
- 后处理任务
**Business Impact**
统一生成工作流将带来以下影响：
- 用户更容易理解生成过程与失败反馈
- 前端可构建成熟状态体验
- 后续扩展语音缓存、绘本恢复、记忆提取等能力更顺畅
- 面试场景中可清楚展示 AI 产品的工作流设计能力
---
## Success Metrics
**Primary KPIs**
- **工作流覆盖率**：普通故事、完整故事、绘本生成全部迁移到统一工作流 >= 100%
- **部分完成可用率**：当图片或音频失败时，文本仍能可读的比例 >= 95%
- **可恢复率**：绘本和故事结果按 ID 重新打开成功率 >= 100%
- **前端状态完整度**：关键生成状态在前端均有可见反馈 >= 100%
- **新增需求复用率**：新生成能力接入时复用统一工作流步骤的比例 >= 80%
**Validation**
- 技术验证：端到端测试与手动演示
- 产品验证：能否用一张流程图清楚说明 DreamWeaver 的生成机制
---
## User Personas
### Primary Persona: 家长 / 监护人
- **Role**: 使用 DreamWeaver 为孩子生成故事内容的人
- **Goals**:
- 快速得到稳定的故事或绘本结果
- 看到清晰的生成状态
- 即使部分资产失败，仍能继续阅读
- **Pain Points**:
- 不知道系统是否仍在生成中
- 结果部分丢失后体验中断
- 页面刷新后无法找回内容
- **Technical Level**: 初中级
### Secondary Persona: 产品负责人 / 开发者
- **Role**: 维护 DreamWeaver 的产品与系统设计者
- **Goals**:
- 降低流程分裂造成的重复实现
- 统一失败处理与状态管理
- 能向他人清楚解释系统设计
- **Pain Points**:
- 同一需求在多个生成路径里改动
- 状态定义不清，难以推进前端体验
- 架构复杂度高，影响项目表达
- **Technical Level**: 中高级
---
## User Stories & Acceptance Criteria
### Story 1: 统一发起生成
**As a** 家长
**I want to** 从一个统一的创建入口发起普通故事或绘本生成
**So that** 我不需要理解系统内部差异
**Acceptance Criteria**
- [ ] 创建入口支持选择输出类型：普通故事或绘本
- [ ] 系统能根据输入类型走统一流程，而不是完全独立逻辑
- [ ] 用户提交后立即看到生成状态
### Story 2: 获得可用结果
**As a** 家长
**I want to** 在生成过程中尽快看到第一个可用结果
**So that** 我不会因等待过久而中断使用
**Acceptance Criteria**
- [ ] 文本生成完成后，主记录应被保存
- [ ] 图片、音频、绘本页可后续补全
- [ ] 即使部分资产失败，用户仍可查看文本结果
### Story 3: 恢复历史结果
**As a** 家长
**I want to** 通过故事或绘本 ID 再次打开内容
**So that** 我可以回看、继续阅读或重新播放
**Acceptance Criteria**
- [ ] 故事详情页支持按 ID 加载
- [ ] 绘本阅读器支持按 ID 加载
- [ ] 刷新页面不会导致内容丢失
### Story 4: 理解系统状态
**As a** 家长
**I want to** 知道系统目前是在生成文本、生成图片还是失败可重试
**So that** 我不会困惑或误以为系统卡住
**Acceptance Criteria**
- [ ] 前端展示统一状态模型
- [ ] 失败原因对用户可解释
- [ ] 可补全资产应有独立重试入口
### Story 5: 以统一方式扩展能力
**As a** 产品负责人
**I want to** 未来新增音频缓存、更多绘本模式或新资产时复用统一工作流
**So that** 系统能持续扩展而不继续分叉
**Acceptance Criteria**
- [ ] 工作流步骤具备清晰边界
- [x] 新能力接入时能挂入现有状态模型
- [ ] 不需要再新增完全平行的一套生成接口
---
## Functional Requirements
### Feature 1: 统一工作流模型
**Description**
所有内容生成行为必须映射到同一套工作流中，不再按“故事模式/绘本模式”分别设计完全独立的业务流程。
**Standard Workflow Steps**
1. Request Accepted
2. Context Prepared
3. Narrative Generated
4. Story Saved
5. Assets Generating
6. Partial Ready / Completed
7. Post-processing Completed
**Requirements**
- 系统需定义统一工作流状态
- 故事与绘本共享前四步
- 资产生成与后处理作为后续步骤处理
### Feature 2: 状态模型
**Description**
系统必须拥有统一且可面向前端呈现的状态模型。
**Proposed Status Set**
- `pending`
- `context_ready`
- `narrative_ready`
- `assets_generating`
- `partial_ready`
- `completed`
- `failed`
- `degraded_completed`
**Requirements**
- 每个状态必须有明确进入条件
- 前端可根据状态做 UI 展示
- `degraded_completed` 必须代表“主结果可用，部分资产失败”
### Feature 3: 统一主记录保存
**Description**
不论输出为普通故事还是绘本，系统都应有统一的主记录保存策略。
**Requirements**
- 文本或绘本结构生成完成后，应立即保存主记录
- 主记录至少保存：
- 用户 ID
- 档案 ID
- 宇宙 ID
- 标题
- 模式
- 文本或分页结构
- 封面 prompt
- 资产状态
- 保存后即可供前端按 ID 加载
### Feature 4: 资产异步补全
**Description**
图片、音频等资产不应阻塞主结果可用性。
**Requirements**
- 封面、绘本页插图、音频均支持异步补全
- 各资产需独立记录状态
- 资产失败不应导致主故事记录失效
- 用户应可单独重试未完成资产
### Feature 5: 恢复与回看能力
**Description**
结果页与绘本页应按持久化数据恢复，而不是仅依赖 Pinia 内存状态。
**Requirements**
- 故事详情页支持按 ID 读取主记录
- 绘本阅读器支持按 ID 读取 `pages`
- 前端 store 可以作为缓存层，但不是唯一数据来源
### Feature 6: 统一后处理钩子
**Description**
成就提取、记忆提取、阅读时间线更新等能力应挂在统一后处理节点中。
**Requirements**
- 后处理任务应在主记录保存后触发
- 后处理失败不应影响主内容可读
- 后处理可被日志和状态观测
### Out of Scope
- 引入复杂工作流引擎
- 设计多租户任务编排
- 在本轮中彻底重做数据库结构
- 把所有历史接口一次性废弃
---
## UX Requirements
### Core UX Principles
- 用户始终知道当前生成到哪一步
- 用户始终能在部分成功时继续阅读
- 用户始终能在失败后看到下一步动作
### Required UI States
- 提交中
- 正在分析输入
- 正在生成文本
- 文本已完成，图片/音频处理中
- 部分完成
- 全部完成
- 失败
- 可重试
### Recovery UX
- 刷新页面后，故事结果应直接恢复
- 绘本页刷新后，应恢复到默认首页或上次阅读位置
- 若某资产失败，应明确显示“稍后重试”而非空白区域
---
## Technical Constraints
### Backend Constraints
- 现有后端基于 FastAPI + SQLAlchemy Async + Celery
- 应优先在当前架构内重组服务边界，而非大规模重写
- 现有 `Story` 表已支持 `story_text`、`pages`、`image_url` 等字段，可作为统一主记录基础
### Frontend Constraints
- 当前前端使用 Vue 3 + Pinia
- 已有创建弹窗、故事详情页、绘本阅读页
- 需尽量在现有组件结构内推进，不做过度重写
### Integration Constraints
- 文本、图片、语音能力由 Provider Router 提供
- 工作流应与 Provider 路由解耦，避免把模型策略写进业务流程
---
## Proposed Data Model Evolution
### Existing Base
当前 `Story` 模型已经可承载：
- `story_text`
- `pages`
- `cover_prompt`
- `image_url`
- `mode`
### Recommended Additions
建议新增以下字段或概念层（可为数据库字段，也可先为服务层状态）：
- `generation_status`
- `text_status`
- `image_status`
- `audio_status`
- `last_error`
- `retryable_assets`
### Why This Matters
这些字段可以帮助：
- 前端显示精确状态
- 后端区分主结果和资产结果
- 支持“部分完成”和“可重试”能力
---
## API Impact
### Current APIs
- `POST /api/stories/generate`
- `POST /api/stories/generate/full`
- `POST /api/storybook/generate`
- `GET /api/stories/{id}`
- `GET /api/audio/{id}`
### Recommended Direction
第一阶段不必强行一次性废弃旧接口，但建议向统一入口演进。
**Recommended Target**
- `POST /api/generations`
- `GET /api/generations/{id}`
- `POST /api/generations/{id}/retry-assets`
如果短期不改 API 命名，也至少应做到：
- 内部统一走同一个 service workflow
- 外部不同接口只是兼容层
---
## MVP Scope & Phasing
### Phase 1: MVP
- 统一 service 层生成流程
- 支持统一状态模型
- 支持故事和绘本按 ID 恢复
- 支持部分完成与失败降级
- 支持图片和音频独立重试入口
### Phase 2: Enhancements
- 更进一步的音频缓存策略（如过期、清理与复用治理）
- 更细粒度资产状态
- 阅读位置恢复
- 工作流相关日志与监控
### Future Considerations
- 长任务通知
- 流式生成 UI
- 多阶段生成策略
- 高级 narrative plan
---
## Risk Assessment
| Risk | Probability | Impact | Mitigation Strategy |
|------|------------|--------|---------------------|
| 工作流抽象过度 | Medium | High | 先围绕现有故事/绘本/音频场景做最小抽象 |
| 历史接口兼容性问题 | Medium | Medium | 保留兼容入口，内部统一服务实现 |
| 前后端状态模型理解不一致 | High | High | 先写清统一状态表，再进入实现 |
| Storybook 恢复实现不彻底 | Medium | High | 把“按 ID 加载”作为硬性验收项 |
| 资产状态字段新增引发迁移成本 | Medium | Medium | 允许先在服务层实现，再视需要落库 |
---
## Dependencies & Blockers
**Dependencies**
- 现有 `Story` 数据模型
- 现有 `story_service.py` 能力
- 现有前端创建入口与详情页
- Provider Router 可继续提供文本、图片、音频能力
**Known Blockers**
- 统一入口尚未建立
- 多条生成链路重复实现
---
## Appendix
### Recommended State Definition Table
| State | Meaning | User-facing Message |
|------|------|------|
| `pending` | 请求已提交 | 正在准备生成 |
| `context_ready` | 上下文已完成 | 正在分析孩子档案和主题 |
| `narrative_ready` | 文本或绘本结构已生成 | 故事已生成，正在补充插图/语音 |
| `assets_generating` | 资产处理中 | 正在绘制封面或生成语音 |
| `partial_ready` | 主结果可用，资产未全部完成 | 可以先阅读，稍后补全更多内容 |
| `completed` | 全部核心资产完成 | 故事已准备完成 |
| `failed` | 主流程失败 | 生成失败，请重试 |
| `degraded_completed` | 主流程成功但部分资产失败 | 故事已可阅读，部分内容稍后重试 |
### How to Learn from This PRD
如果你想模仿写功能级 PRD，可以重点学习这几个动作：
1. 不要直接写功能，要先写“为什么当前方式有问题”。
2. 一定要把“当前实现”和“目标实现”分开写。
3. 用状态模型、边界和恢复能力来体现你对 AI 产品的不确定性理解。
4. 用户故事不要只写 happy path，要覆盖失败、降级和恢复。
5. 对系统型需求，要写清 API 影响和数据模型影响。
### References
- `backend/app/services/story_service.py`
- `backend/app/api/stories.py`
- `backend/app/schemas/story_schemas.py`
- `backend/app/db/models.py`
- `frontend/src/components/CreateStoryModal.vue`
- `frontend/src/views/StorybookViewer.vue`
---
*This PRD defines the target-state product and system behavior for unifying DreamWeaver's content generation workflow.*

147
docs/technical/memory-system-dev.md Normal file
View File

@@ -0,0 +1,147 @@
# 记忆系统开发指南 (Development Guide)
本文档详细说明了 PRD 中定义的记忆系统的技术实现细节。
## 1. 数据库架构变更 (Schema Changes)
目前的 `MemoryItem` 表结构尚可，但需要增强字段以支持丰富的情感和元数据。
### 1.1 `MemoryItem` 表优化
建议使用 Alembic 进行迁移，增加以下字段或在 `value` JSON 中规范化以下结构：
```python
# 建议在 models.py 中明确这些字段，或者严格定义 value 字段的 Schema
class MemoryItem(Base):
# ... 现有字段 ...
# 新增/规范化字段建议
# value 字段的 JSON 结构规范：
# {
# "content": "小兔子战胜了大灰狼", # 记忆的核心文本
# "keywords": ["勇敢", "森林"], # 用于检索的关键词
# "emotion": "positive", # 情感倾向: positive/negative/neutral
# "source_story_id": 123, # 来源故事 ID
# "confidence": 0.85 # 记忆置信度 (如果是 AI 自动提取)
# }
```
### 1.2 `StoryUniverse` 表优化 (成就系统)
目前的成就存储在 `achievements` JSON 字段中。为了支持更复杂的查询（如"获得勇气勋章的所有用户"），建议将其重构为独立关联表，或保持 JSON 但规范化结构。
**当前 JSON 结构规范**:
```json
[
{
"id": "badge_courage_01",
"type": "勇气",
"name": "小小勇士",
"description": "第一次在故事中独自面对困难",
"icon_url": "badges/courage.png",
"obtained_at": "2023-10-27T10:00:00Z",
"source_story_id": 45
}
]
```
---
## 2. 核心逻辑实现
### 2.1 记忆注入逻辑 (Prompt Engineering)
修改 `backend/app/api/stories.py` 中的 `_build_memory_context` 函数。
**目标**: 生成一段自然的、不仅是罗列数据的 Prompt。
**伪代码逻辑**:
```python
def format_memory_for_prompt(memories: list[MemoryItem]) -> str:
"""
将记忆项转换为自然语言 Prompt 片段。
"""
context_parts = []
# 1. 角色记忆
chars = [m for m in memories if m.type == 'favorite_character']
if chars:
names = ", ".join([c.value['name'] for c in chars])
context_parts.append(f"孩子特别喜欢的角色有：{names}。请尝试让他们客串出场。")
# 2. 近期情节
recent_stories = [m for m in memories if m.type == 'recent_story'][:2]
if recent_stories:
for story in recent_stories:
context_parts.append(f"最近发生过：{story.value['summary']}。可以在对话中不经意地提及此事。")
# 3. 避雷区 (负面记忆)
scary = [m for m in memories if m.type == 'scary_element']
if scary:
items = ", ".join([s.value['keyword'] for s in scary])
context_parts.append(f"【绝对禁止】不要出现以下让孩子害怕的元素：{items}。")
return "\n".join(context_parts)
```
### 2.2 成就提取与通知流程
当前流程在 `app/tasks/achievements.py`。需要完善闭环。
**改进后的流程**:
1. **Story Generation**: 故事生成成功，存入数据库。
2. **Async Task**: 触发 Celery 任务 `extract_story_achievements`。
3. **LLM Analysis**: 调用 Gemini 分析故事，提取成就。
4. **Update DB**: 更新 `StoryUniverse.achievements`。
5. **Notification (新增)**:
* 创建一个 `Notification` 或 `UserMessage` 记录（需要新建表或使用 Redis Pub/Sub）。
* 前端轮询或通过 SSE (Server-Sent Events) 接收通知："🎉 恭喜！在这个故事里，小明获得了[诚实勋章]！"
### 2.3 记忆清理与衰减 (Maintenance)
需要一个后台定时任务（Cron Job），清理无效记忆，避免 Prompt 过长。
* **频率**: 每天一次。
* **逻辑**:
* 删除 `ttl_days` 已过期的记录。
* 对 `recent_story` 类型的 `base_weight` 进行每日衰减 update（或者只在读取时计算，数据库存静态值，推荐读取时动态计算以减少写操作）。
* 当 `MemoryItem` 总数超过 100 条时，触发"记忆总结"任务，将多条旧记忆合并为一条"长期印象" (Long-term Impression)。
---
## 3. API 接口规划
### 3.1 获取成长时间轴
`GET /api/profiles/{id}/timeline`
**Response**:
```json
{
"events": [
{
"date": "2023-10-01",
"type": "milestone",
"title": "初次相遇",
"description": "创建了角色 [小明]"
},
{
"date": "2023-10-05",
"type": "story",
"title": "小明与魔法树",
"image_url": "..."
},
{
"date": "2023-10-05",
"type": "achievement",
"badge": {
"name": "好奇宝宝",
"icon": "..."
}
}
]
}
```
### 3.2 记忆反馈 (人工干预)
`POST /api/memories/{id}/feedback`
允许家长手动删除或修正错误的记忆。
* **Action**: `delete` | `reinforce` (强化，增加权重)