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

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-18 evening

当前代码已经从“纯目标态设计”进入“部分落地”阶段，主要进展如下：

Already Landed

• Story 主记录已持久化以下统一状态相关字段：
  • generation_status
  • text_status
  • image_status
  • audio_status
  • last_error
  • audio_path
• partial_ready 已在服务层、迁移、API schema、用户端与管理端状态展示中落地，用于表达“主内容可读，但仍有封面、插图或音频可补全”
• 已新增轻量可查询的生成过程记录：
  • generation_jobs
  • generation_job_events
• Storybook 阅读器已支持按 ID 恢复，不再只依赖 Pinia 内存态
• 故事列表页、故事详情页、绘本阅读页已接入统一状态展示
• API 响应已统一返回 retryable_assets，前端不再各自推断可补全资产
• 故事音频已支持首次生成后缓存复用
• degraded_completed 已在服务层和前端语义中落地
• 已新增首版统一资产重试入口：POST /api/stories/{story_id}/assets/retry
• 已新增目标态统一生成 API：
  • POST /api/generations
  • GET /api/generations/{story_id}
  • POST /api/generations/{story_id}/retry-assets
  • GET /api/generations/jobs/{job_id}
  • GET /api/generations/{story_id}/jobs
  • GET /api/generations/{story_id}/provider-stats
• 用户前端与 admin 前端创建弹窗已切换到 POST /api/generations
• service 内部已开始收束统一工作流步骤：
  • 上下文准备：档案/宇宙校验 + memory context 构建
  • 主记录保存：文本故事与绘本统一持久化入口
  • 资产补全：普通故事封面、绘本缺失插图、故事音频缓存/生成统一封装
• 已引入首版服务层 AssetCompletionResult，用于表达资产补全类型、状态、结果值、错误信息和是否阻塞主结果
• generation_job_events 已从首版请求/完成事件扩展到关键 workflow 节点：
  • context_prepared
  • narrative_generated
  • story_saved
  • 普通故事封面开始/成功/失败
  • 绘本封面与逐页插图成功/失败
  • 音频缓存命中、生成开始、成功和失败
• Provider failover 已记录到 job event，包含 capability、adapter、strategy、latency 和 estimated cost
• Provider 调用已可按故事聚合为成功率、平均耗时、预估成本和 adapter 明细
• generation job 响应已提供 progress_percent、progress_label 和 is_terminal，前端可直接用于进度条和轮询
• 已新增跨故事 Provider 运营摘要 GET /api/generations/provider-analytics，故事库可展示总调用、成功率、平均耗时、预估成本和任务/故事覆盖数
• 跨故事 Provider 运营摘要已支持按时间窗口和 capability 筛选，并聚合失败原因
• 已新增任务运行概览 GET /api/generations/ops-summary，故事库可展示最近失败、运行中任务和超时待收敛任务
• 重复资产任务已加入保护：同一故事存在运行中 job 时，不再重复触发封面、音频或统一资产重试
• Celery beat 已支持定时收敛卡住的 generation job，避免任务长期停在 running
• 用户端与管理端生成轨迹组件会在任务未终止时自动轮询，为后续后台 worker 进度流保留前端形态
• POST /api/generations 响应已返回 generation_job_id，smoke 脚本会验证 job 查询与 story job history
• 用户端与管理端的故事详情页、绘本阅读页已接入生成轨迹，展示生成/重试任务、关键事件、Provider 调用结果和聚合指标
• 故事详情页封面补全已切换到统一资产重试入口
• 管理端前端构建阻塞已修复，主前端与 admin 前端均可完成生产构建

Remaining Production Work

• 普通故事、完整生成、绘本生成已有统一外部入口，内部 workflow 仍可继续减少兼容层分支
• 统一资产重试入口已覆盖普通故事封面、绘本缺失插图和故事音频，后续可继续扩展更细的资产级审计
• 后台异步 worker 执行、断点续跑、跨用户/跨环境 Provider 分析，以及真正的取消/重试队列仍属于后续生产化增强

What This Means

这份 PRD 仍然保留目标态设计，但主干能力已经可在当前代码中演示。当前最适合的继续方式，是继续把同步请求迁移到后台 worker，并把当前首版运营摘要扩展为可筛选、可对比的分析视角，而不是继续扩大功能范围。

---

Problem Statement

Current Situation

DreamWeaver 当前存在以下工作流层面问题：

1. 生成入口已建立，内部路径正在收束 当前前端已切到 /api/generations，旧的 /api/stories/generate、/api/stories/generate/full、/api/storybook/generate 仍作为兼容入口保留。service 内部已抽取上下文准备、主记录保存、封面补全、绘本插图补全和音频补全 helper，并用 AssetCompletionResult 表达资产补全结果。generation job/event 已落库并可查询，Provider 调用轨迹、单故事聚合指标和跨故事运营摘要也已进入用户端与管理端展示。下一步重点是为后台异步 worker 复用这些事件。

2. 保存与资产补全过程正在统一 文本故事和绘本已拥有更清晰的主记录保存 helper；普通故事封面、绘本缺失插图、故事音频生成/缓存已共用各自的 asset completion helper。服务层已经能表达资产任务结果，并会把统一入口、资产重试、绘本逐页插图和音频生成的关键节点写入 job event。

3. 状态表达已基本统一，仍需生产化扩展 当前已经能用 generation_status、text_status、image_status、audio_status 和 retryable_assets 表达生成中、部分可读、完成、降级完成、失败和可重试。后续重点是让后台 worker、运营分析和通知系统复用同一套状态语义。

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

• 工作流步骤具备清晰边界
• 新能力接入时能挂入现有状态模型
• 不需要再新增完全平行的一套生成接口

---

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 必须代表“主结果可用，部分资产失败”
• partial_ready 必须代表“主结果可读，资产尚未全部完成但没有失败”
• text_status 必须只表达主文本或绘本结构是否可读，不被图片、音频状态覆盖

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	保留兼容入口，内部统一服务实现
前后端状态模型理解不一致	Medium	High	通过共享状态 helper、API schema 和回归测试保持一致
Storybook 恢复实现不彻底	Medium	High	把“按 ID 加载”作为硬性验收项
资产状态字段新增引发迁移成本	Medium	Medium	允许先在服务层实现，再视需要落库

---

Dependencies & Blockers

Dependencies

• 现有 Story 数据模型
• 现有 story_service.py 能力
• 现有前端创建入口与详情页
• Provider Router 可继续提供文本、图片、音频能力

Known Blockers

• 当前没有阻塞 MVP 演示的已知问题；后续生产化主要受后台异步化与运营分析范围影响
• 多条生成链路重复实现

---

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.