docs: Writer 串行约束写回(T10 架构审查整改,I14)

- design.md §6.8.1 新增串行生成约束:理由(章间引用依赖前章 WriterState /
  并行收益低复杂度高 / Token 友好)+ 落地点(编排层严格顺序串行、UI 预估
  总时长与逐章进度、禁止并发多章)
- api-design §4.3 补串行消费说明(对应 §6.8.1)
- web-ui-design 进度 UI 补串行语义(预计=章数×单章 3-5 分)
- 纯文档,无代码变更;全量 248 passed / 100.00% 不回归
This commit is contained in:
lhl
2026-08-12 23:11:14 +08:00
parent 3ae1f5f38f
commit a1336f6dd3
4 changed files with 31 additions and 1 deletions
+7 -1
View File
@@ -191,9 +191,15 @@ WS /api/ws/sessions/{id}
### 4.3 进程内调用 vs 队列
```
默认(InMemoryQueue:
默认(InMemoryQueue):
Orchestrator 进程内 asyncio 任务池消费队列
状态与任务结果共享内存(FastAPI 进程内)
```
> **串行生成约束(T10 文档化,对应 design.md §6.8.1 / I14**:同一会话的逐章生成
> 任务**严格按模板章节顺序串行消费**。`POST /generate` 投递后不并发执行多章——
> 后章依赖前章 `WriterState` 摘要(design §6.9),并行会造成竞态。单章失败可独立
> `regenerate-chapter` 重试,不影响其余章。
v2 预留)RedisQueue/ValkeyQueue:
Orchestrator 投递 → Redis/Valkey Stream
+19
View File
@@ -918,6 +918,25 @@ style_map:
└──────────────────────────────────────────────────────────┘
```
#### 6.8.1 串行生成约束(T10 文档化,I14)
> 架构审查 I14 裁定:**Writer 各章必须串行生成,不得并行**。本约束为设计基线,
> 而非实现细节,需在编排层与 UI 显式体现。
**理由**
1. **章间引用依赖**:后章(如「3.2 画面一覧」)需引用前章(「2. 機能一覧」)的
表结构与摘要,串行保证前章 `WriterState` 已就绪(§6.9),避免竞态或空引用
2. **并行收益低、复杂度高**:单章生成 3-5 分钟,并行需解决状态回写锁与
跨章引用一致性,复杂度远超收益(编审查 OV 一致结论)
3. **Token 友好**:前章摘要注入后章 prompt 的方式(§6.9)天然要求前章先完成
**约束落地点**
- 编排层:`POST /generate` 投递任务后,同一会话的逐章任务**严格按模板章节顺序串行消费**
(共享 orchestrator/,状态机 `writing` 态内顺序推进;单章失败可独立 retry,不影响其他章)
- UI:生成按钮触发后展示**预估总时长**(章数 × 单章 ~3-5 分钟)与逐章进度
(「第 3/12 章生成中」),让用户对串行等待有预期
- 实现反模式(禁止):同一会话并发投递多章生成任务、跳过 WriterState 直接全量重载
### 6.9 章间引用机制(WriterState
```
+4
View File
@@ -252,6 +252,10 @@
│ 适用规则: 写入规则_v3 │
│ │
│ [中途中断] [查看日志] │
```
> **串行约束(T10 / I14**:章节严格按模板顺序**串行**生成,预计时间 = 章数 × 单章
> ~3-5 分钟(design §6.8.1)。UI 展示「第 N/总章 生成中」与逐章进度,让用户对
> 串行等待有预期;禁止并发触发多章生成(会造成 WriterState 竞态)。
│ │
│ ┌─ 规则冲突 (浮动卡片) ───────────────────┐ │
│ │ ⚠ 检测到规则冲突(DB设计章) │ │