# DreamWeaver 求职版架构说明

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

---

## 1. 产品闭环

```mermaid
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. 后端分层

```mermaid
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. 状态模型

```mermaid
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. 可观测性

```mermaid
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. 补跨环境 Provider 汇聚视图，避免每个部署环境各自成孤岛。
2. 基于现有 job 查询和前端轮询继续扩展断点续跑与更细粒度任务控制。
3. 在当前环境 dashboard 基础上继续扩展失败原因、监控告警和结构化观测能力。
4. 继续补充部署与密钥治理策略。