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