docs: package week 4 demo and architecture

docs/technical/architecture.md

@@ -0,0 +1,107 @@
+# 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. 把同步生成迁移到后台 worker。
+2. 基于现有 job 查询和前端轮询展示真实异步进度。
+3. 扩展 Provider analytics 的时间窗口、失败原因和跨用户维度。
+4. 为音频缓存增加过期策略和后台清理任务。
+5. 补充部署、监控告警和密钥治理策略。