wip: snapshot full local workspace state

.claude/settings.local.json

@@ -38,7 +38,11 @@
       "Bash(npx vue-tsc:*)",
       "Bash(ls:*)",
       "Bash(git init:*)",
-      "Bash(git add:*)"
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git remote add:*)",
+      "Bash(git push:*)",
+      "Bash(git branch:*)"
     ]
   }
 }

AGENTS.md

@@ -0,0 +1,134 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Project Overview
+
+DreamWeaver (梦语织机) - AI-powered children's story generation app for ages 3-8. Features story generation from keywords, story enhancement, AI-generated cover images, and text-to-speech narration.
+
+**Language:** Chinese (Simplified) for UI and comments.
+
+## Tech Stack
+
+- **Backend:** FastAPI + PostgreSQL (Neon) + SQLAlchemy (async) + Celery/Redis | **Python 3.11+**
+- **Frontend:** Vue 3 + TypeScript + Pinia + Tailwind CSS + vue-i18n
+- **Auth:** OAuth 2.0 (GitHub/Google) with JWT in httpOnly cookie
+- **AI Services:** Text generation, image generation, TTS (pluggable adapters)
+
+## Commands
+
+```bash
+# Backend
+cd backend
+pip install -e .                              # Install dependencies
+pip install -e ".[dev]"                       # With dev tools (pytest, ruff)
+uvicorn app.main:app --reload --port 8000     # Start dev server
+
+# Celery worker (requires Redis)
+celery -A app.tasks worker --loglevel=info
+
+# Database migrations
+alembic upgrade head                          # Run migrations
+alembic revision -m "message" --autogenerate  # Generate new migration
+
+# Linting
+ruff check app/                               # Check code
+ruff check app/ --fix                         # Auto-fix
+
+# Testing
+pytest                                        # Run all tests
+pytest tests/test_auth.py -v                  # Single test file
+pytest -k "test_name"                         # Match pattern
+
+# Frontend
+cd frontend
+npm install
+npm run dev                                   # Start dev server (port 5173)
+npm run build                                 # Type-check + build
+```
+
+## Architecture
+
+```
+backend/app/
+├── main.py                    # FastAPI app entry, routes registration
+├── api/
+│   ├── auth.py                # OAuth routes (GitHub/Google)
+│   ├── stories.py             # Story CRUD and AI generation endpoints
+│   ├── profiles.py            # User profile management
+│   ├── universes.py           # Story universe/world management
+│   ├── reading_events.py      # Reading progress tracking
+│   ├── push_configs.py        # Push notification settings
+│   ├── admin_providers.py     # Provider CRUD (admin)
+│   └── admin_reload.py        # Hot-reload providers (admin)
+├── core/
+│   ├── config.py              # Pydantic settings from env
+│   ├── deps.py                # Dependency injection (auth, db session)
+│   ├── security.py            # JWT token create/verify
+│   ├── prompts.py             # AI prompt templates
+│   └── admin_auth.py          # Basic Auth for admin routes
+├── db/
+│   ├── database.py            # SQLAlchemy async engine + session
+│   ├── models.py              # User, Story models
+│   └── admin_models.py        # Provider model
+├── services/
+│   ├── adapters/              # Capability adapters (text, image, tts)
+│   ├── provider_router.py     # Failover routing across providers
+│   ├── provider_cache.py      # In-memory provider config cache
+│   ├── provider_metrics.py    # Provider performance metrics
+│   └── achievement_extractor.py  # Extract achievements from stories
+└── tasks/
+    ├── achievements.py        # Celery task: achievement processing
+    └── push_notifications.py  # Celery task: push notifications
+
+frontend/src/
+├── api/client.ts              # Axios wrapper with auth interceptors
+├── stores/user.ts             # Pinia user state
+├── router.ts                  # Vue Router config
+├── i18n.ts + locales/         # vue-i18n setup
+├── components/                # Reusable Vue components
+└── views/                     # Page components
+```
+
+## Key Patterns
+
+- **Async everywhere:** All database and API calls use async/await
+- **Dependency injection:** FastAPI `Depends()` for auth and db session
+- **JWT auth:** Stored in httpOnly cookie, validated via `get_current_user` dependency
+- **Provider routing:** `provider_router.py` tries providers in order, auto-failover on error
+- **Background tasks:** Celery workers handle achievements and push notifications
+- **Proxy in dev:** Vite proxies `/api`, `/auth`, `/admin` to backend (see `vite.config.ts`)
+
+## Provider System
+
+AI providers are configured via env vars (`TEXT_PROVIDERS`, `IMAGE_PROVIDERS`, `TTS_PROVIDERS`) as JSON arrays. The router tries each in order and fails over automatically.
+
+Admin console (disabled by default): Set `ENABLE_ADMIN_CONSOLE=true` to enable `/admin/providers` CRUD endpoints with Basic Auth (`ADMIN_USERNAME`/`ADMIN_PASSWORD`).
+
+## Environment Variables
+
+See `backend/.env.example` for required variables:
+
+- `DATABASE_URL`, `SECRET_KEY` (required)
+- OAuth: `GITHUB_CLIENT_ID/SECRET`, `GOOGLE_CLIENT_ID/SECRET`
+- AI: `TEXT_API_KEY`, `TTS_API_BASE`, `TTS_API_KEY`, `IMAGE_API_KEY`
+- Providers: `TEXT_PROVIDERS`, `IMAGE_PROVIDERS`, `TTS_PROVIDERS` (JSON arrays)
+- Celery: `CELERY_BROKER_URL`, `CELERY_RESULT_BACKEND` (Redis URLs)
+- Admin: `ENABLE_ADMIN_CONSOLE`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`
+
+## API Endpoints
+
+| Method              | Route                      | Description                 |
+| ------------------- | -------------------------- | --------------------------- |
+| GET                 | `/auth/{provider}/signin`  | OAuth login                 |
+| GET                 | `/auth/session`            | Get current user            |
+| POST                | `/api/generate`            | Generate/enhance story      |
+| POST                | `/api/image/generate/{id}` | Generate cover image        |
+| GET                 | `/api/audio/{id}`          | Get TTS audio               |
+| GET                 | `/api/stories`             | List stories (paginated)    |
+| GET/DELETE          | `/api/stories/{id}`        | Story CRUD                  |
+| CRUD                | `/api/profiles`            | User profiles               |
+| CRUD                | `/api/universes`           | Story universes             |
+| CRUD                | `/api/reading-events`      | Reading progress            |
+| CRUD                | `/api/push-configs`        | Push notification settings  |
+| GET/POST/PUT/DELETE | `/admin/providers`         | Provider management (admin) |

backend/docs/code_review_report.md

@@ -1,14 +0,0 @@
-# Code Review Report (2nd follow-up)
-
-## What¡¯s fixed
-- Provider cache now loads on startup via lifespan (`app/main.py`), so DB providers are honored without manual reload.
-- Providers support DB-stored `api_key` precedence (`provider_router.py:77-104`) and Provider model added `api_key` column (`db/admin_models.py:25`).
-- Frontend uses `/api/generate/full` and propagates image-failure warning to detail via query flag; StoryDetail displays banner when image generation failed.
-- Tests added for full generation, provider failover, config-from-DB, and startup cache load.
-
-## Remaining issue
-1) **Missing DB migration for new Provider.api_key column**
-   - Files updated model (`backend/app/db/admin_models.py:25`) but `backend/alembic/versions/0001_init_providers_and_story_mode.py` lacks this column. Existing databases will not have `api_key`, causing runtime errors when accessing or inserting. Add an Alembic migration to add/drop `api_key` to `providers` table and update sample data if needed.
-
-## Suggested action
-- Create and apply an Alembic migration adding `api_key` (String, nullable) to `providers`. After migration, verify admin CRUD works with the new field.

docs/README.md

@@ -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.

docs/planning/document-status-inventory.md

@@ -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 问题说明项目还没完成最后一轮收尾。
+
+因此，文档已经足够清晰，可以进入下一阶段：按优先级开始改代码，而不是继续扩写更多概念文档。

docs/planning/week-1-execution-backlog.md

@@ -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.*

docs/planning/weekend-handoff-2026-04-17.md

@@ -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` 为准

docs/product/job-search-relaunch-prd.md

@@ -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.*

docs/product/unified-generation-workflow-prd.md

@@ -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.*

frontend/src/components/CreateStoryModal.vue

@@ -157,15 +157,12 @@ async function generateStory() {
       
       storybookStore.setStorybook(response)
       close()
-      router.push('/storybook/view')
+      const storybookPath = response.id ? `/storybook/view/${response.id}` : '/storybook/view'
+      router.push(storybookPath)
     } else {
       const result = await api.post<any>('/api/stories/generate/full', payload)
-      const query: Record<string, string> = {}
-      if (result.errors && Object.keys(result.errors).length > 0) {
-        if (result.errors.image) query.imageError = '1'
-      }
       close()
-      router.push({ path: `/story/${result.id}`, query })
+      router.push(`/story/${result.id}`)
     }
   } catch (e) {
     error.value = e instanceof Error ? e.message : '生成失败'

frontend/src/router.ts

@@ -44,7 +44,7 @@ const router = createRouter({
       component: () => import('./views/StoryDetail.vue'),
     },
     {
-      path: '/storybook/view',
+      path: '/storybook/view/:id?',
       name: 'storybook-viewer',
       component: () => import('./views/StorybookViewer.vue'),
     },