dreamweaver/docs/technical/architecture.md

DreamWeaver 求职版架构说明

这份说明用于面试和复盘场景，帮助快速解释 DreamWeaver 如何把多模型能力收敛成稳定的亲子阅读产品闭环。

---

1. 产品闭环

flowchart LR
  A["孩子档案 / 故事宇宙"] --> B["输入主题或教育目标"]
  B --> C["统一生成入口 /api/generations"]
  C --> D["文本故事或绘本结构"]
  D --> E["主记录保存到 stories"]
  E --> F["封面 / 插图 / 音频资产补全"]
  F --> G["故事详情 / 绘本阅读器"]
  G --> H["阅读事件"]
  H --> I["记忆沉淀与成长时间线"]
  I --> A

核心取舍是主内容优先可读，封面、插图和音频作为可恢复资产补全。这样 AI 资产失败不会摧毁用户已经得到的故事。

---

2. 后端分层

flowchart TB
  FE["Vue 用户端 / 管理端"] --> API["FastAPI API 层"]
  API --> WF["story_service 统一工作流"]
  WF --> JOB["generation_jobs / events"]
  WF --> ST["story_status 状态推导"]
  WF --> MEM["memory_service 记忆上下文"]
  WF --> ROUTER["provider_router"]
  ROUTER --> POLICY["provider_policy"]
  ROUTER --> ADAPTER["text / image / tts / storybook adapters"]
  WF --> DB["PostgreSQL: stories, profiles, universes, reading_events, memory_items"]
  WF --> CACHE["音频文件缓存"]

职责边界：

• API 层负责认证、限流、兼容 header 和响应模型。
• story_service 负责产品工作流：上下文准备、主记录保存、资产补全、状态回写。
• story_status 负责把文本、图片、音频状态推导为统一 generation_status。
• generation_jobs 负责生成任务、事件流、进度摘要和 Provider 聚合。
• provider_router 负责运行时调用、failover、指标和成本记录。
• 前端只消费标准状态和 retryable_assets，不自行猜测重试逻辑。

---

3. 状态模型

stateDiagram-v2
  [*] --> narrative_ready
  narrative_ready --> partial_ready: 主内容可读且资产待补全
  partial_ready --> assets_generating: 发起封面 / 插图 / 音频
  assets_generating --> completed: 所需资产完成
  assets_generating --> degraded_completed: 资产失败但主内容可读
  degraded_completed --> assets_generating: 用户重试失败资产
  completed --> assets_generating: 用户清理或重做资产
  narrative_ready --> failed: 主内容生成失败

关键语义：

• text_status 只表达主文本或绘本结构是否可读。
• partial_ready 表示主内容可读，资产仍可补全。
• degraded_completed 表示主内容可读，但至少一个资产失败。
• retryable_assets 由后端标准返回，前端按字段展示 CTA。

---

4. 可观测性

flowchart LR
  G["生成 / 重试请求"] --> J["generation_jobs"]
  J --> E["generation_job_events"]
  E --> T["任务详情时间线"]
  E --> S["单故事 Provider stats"]
  E --> A["跨故事 Provider analytics"]
  T --> UI["故事详情 / 绘本阅读"]
  S --> UI
  A --> LIB["故事库运营摘要"]

当前已经能说明：

• 某个故事来自哪次生成任务。
• 每次任务执行到哪一步。
• Provider 是否成功、耗时多少、预估成本多少。
• 失败资源是否可以单独重试。

---

5. 当前边界与下一步

当前仍是求职版 MVP，不引入复杂工作流引擎。下一步生产化优先级：

1. 补齐生成任务取消与重新排队能力，减少误触和重复消耗。
2. 基于现有 job 查询和前端轮询继续扩展真实异步进度与任务控制。
3. 扩展 Provider analytics 的时间窗口、失败原因和跨用户维度。
4. 继续补充部署、监控告警和密钥治理策略。