docs: Web UI 设计评审修订（v1.0→v1.1，7 项发现全修 + api §2.2 write_instruction）

.superpowers/sdd/progress.md

@@ -20,3 +20,6 @@ M3.1 IE Task 4: complete (commit per git log, review clean; Minor backlog: retry
 M3.1 IE Task 4: complete (commit add7b15, review clean; Minor: 5xx chain message redundancy, test comment mismatch 0.01, un-typed 3xx/malformed-JSON JSONDecodeError passthrough - leave to Task5/engine fold)
 M3.1 IE Task 5: complete (commit 8bc5e5e, review clean 3 deviations all justified; Minor: for-loop var name in failed chat, test import hygiene, raw-template leak known tradeoff, api-design patch +source column slight overreach)
 M3.1 IE final review: base 2fbff07..8bc5e5e -> With fixes; fixed 2 Important (LLMResponseError wrap for malformed 2xx, explicit 2xx check re 3xx); Issue3 chat_structured no model fallback confirmed intentional per plan L1142 (v1 single-model, prod passes explicit model); Minors logged (LLMResponseError now live, truncation in chat_structured, prompt renderer duplicate import, prompts-dir load not v1, no context manager, last-error only)
+RETRO 2026-08-09: snapshot saved (.superpowers/sdd/retro-2026-08-09.json); first recorded for this workspace
+M3.1 backlog clean (cb2deda): chat_structured truncation, engine test import hygiene, client context manager; remaining backlog: [none critical]
+WEB UI REVIEW 2026-08-09 (docs/web-ui-design-review-v1.1.md): v1.0→v1.1, 7 findings all fixed (F1 write_instruction file_type + api §2.2, F2 TaskQueue abstraction, F3 settings page, F4 preview path, F5 conflict card, F6 history page, F7 a11y); synced design.md §8 mirror

_AI_USAGE_LOG.md

@@ -51,3 +51,4 @@
 
 (End of file - total 50 lines)
 | 2026-08-09 10:50 | 反馈迭代 | 里程碑3.1 backlog 清理（retro 3 项）：① chat_structured 增加 token 超限检测（渲染后估算超限→truncate_cb→重渲染，与 chat 流程一致）TDD RED→GREEN 新增 test_chat_structured_truncation_callback_triggered；② 清理 test_inference_engine.py 未用导入（pytest/json/ChatMessage）；③ HttpLLMClient 增加上下文管理器（__enter__/__exit__ 退出时关闭底层 httpx.Client 释放连接）TDD 新增 test_client_context_manager_closes_transport；pytest 全量 119 passed 覆盖 100.00%，fail_under=99 达标；提交见 git log | src/genesis/inference/engine.py, src/genesis/inference/client.py, tests/test_inference_engine.py, tests/test_inference_client.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
+| 2026-08-09 11:20 | 反馈迭代 | Web UI 设计评审（v1.0→v1.1，7 项发现全修）：以大赛手册+api-design 为权威基准审查 web-ui-design.md——F1 上传区补「概要设计做成说明书」独立 write_instruction file_type（api-design §2.2 连带扩展）+ 命名统一；F2 §4.1 任务队列 Redis 写死→抽象 TaskQueue（InMemory 默认/Redis/Valkey 可选）；F3 新增设置页 §3.6；F4 预览路径改 ContentBlock→chapter_html+docx；F5 生成页新增规则冲突浮动卡片（WS conflict_pending→conflicts/{id}/resolve）；F6 新增会话历史页 §3.7；F7 新增 §7 无障碍与设计规范。同步 design.md §8 简版镜像（上传区/预览/队列/导航历史/冲突卡片/设置历史简版//history 命令）；产出评审报告 docs/web-ui-design-review-v1.1.md；docs/design.md、docs/api-design.md 连带修订 | docs/web-ui-design.md, docs/web-ui-design-review-v1.1.md, docs/api-design.md, docs/design.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free |

docs/api-design.md

@@ -55,7 +55,14 @@ FastAPI Orchestrator（单进程，默认）
 
 | Method | Path | 说明 | 请求体 | 响应 | 触发状态转移 |
 |--------|------|------|--------|------|-------------|
-| POST | `/api/sessions/{id}/files` | 上传文件（multipart） | `file` + `file_type`（requirements/template/rules/existing_system） | `{file_id, file_name, size}` | `uploading` 保持 |
+| POST | `/api/sessions/{id}/files` | 上传文件（multipart） | `file` + `file_type`（`requirements`/`template`/`write_instruction`/`rules`/`existing_system`） | `{file_id, file_name, size}` | `uploading` 保持 |
+
+> `file_type` 取值说明（v1.1 修订，随 web-ui-design §3.1 补齐大赛输入资料）：
+> - `requirements` — 要件定义 Excel（核心数据源）
+> - `template` — 概要设计模板 docx（输出结构/样式）
+> - `write_instruction` — 概要设计做成说明书 docx（各章作成指引；RAG 归类 Type A 写入规则，Parser 解析）
+> - `rules` — 记入规则 / 图表规则等规则文档（可多个）
+> - `existing_system` — 现系统源码或既有设计书（追加/改修场景）
 | POST | `/api/sessions/{id}/start-parse` | 开始解析（全部文件上传完成后） | `{}` | `{task_id}`（解析异步执行） | `uploading → parsing` |
 | GET | `/api/sessions/{id}/parse-result` | 获取解析结果 | — | `{structured_summary, sheets, template_sections}` | 只读 |
 

docs/design.md

@@ -1027,7 +1027,7 @@ QA 输出:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  Genesis    [上传] [解析] [影响调查] [生成] [结果]   [设置] │ ← 顶部导航
+│  Genesis    [上传] [解析] [影响调查] [生成] [结果] [历史] [设置] │ ← 顶部导航
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
 │  ┌─ 对话区域 ──────────────────────────────────────────┐   │
@@ -1070,9 +1070,9 @@ QA 输出:
 │  │  .docx (Word)                       │    │
 │  └─────────────────────────────────────┘    │
 │                                             │
-│  📁 写入规则 (推荐, 可多个)                   │
+│  📁 记入规则 (推荐, 可多个)                   │
 │  📁 图表规则 (推荐)                          │
-│  📁 做成说明书 (推荐)                        │
+│  📁 做成说明书 (推荐, 独立类型)                │
 │                                             │
 │  📁 现有系统文件 (任意, 追加/改修场景使用)      │
 │                                             │
@@ -1085,7 +1085,7 @@ QA 输出:
 上传规则：
 - 要件定义文件至少一个
 - 模板文件必须是一个 .docx
-- 规则文档可多个，也可零个（规则手册已存在时）
+- 做成说明书 / 记入规则 / 图表规则 均可多个，也可零个（规则手册已存在时）；做成说明书使用独立 `file_type=write_instruction`（api-design §2.2）
 - 现系统文件仅在追加/改修场景时需要
 - 文件大小限制：最大100MB
 - 支持拖拽上传、点击上传、取消上传
@@ -1181,10 +1181,25 @@ QA 输出:
 │  适用规则: 写入规则_v3                      │
 │                                             │
 │  [中途中断]  [查看日志]                     │
+│                                             │
+│  ┌─ 规则冲突 (浮动卡片) ───────────────────┐   │
+│  │  ⚠ 检测到规则冲突（DB设计章）                  │   │
+│  │  记入规则 2.3「表头仅加粗」                    │   │
+│  │  图表规则 2.3「表头加粗+下划线」                │   │
+│  │  [采用「记入规则」] [采用「图表规则」] [标注]    │   │
+│  └──────────────────────────────────────┘   │
 └─────────────────────────────────────────────┘
 ```
 
-交互说明：用户可保持此画面打开同时进行其他工作。生成完成时通知。选择中断时，已完成的章节保留。
+交互说明：用户可保持此画面打开同时进行其他工作。生成完成时通知。选择中断时，已完成的章节保留。规则冲突由 WS 事件 `conflict_pending` 触发浮动卡片，决策后调用 `/api/rules/conflicts/{id}/resolve` 继续生成。
+
+#### 页面6: 设置
+>
+> 简版：规则手册版本管理（versions / 更新 / 回滚）+ LLM 配置只读摘要（脱敏）。见 `docs/web-ui-design.md` §3.6。
+
+#### 页面7: 会话历史
+>
+> 简版：会话列表（恢复 / 删除 / 新建），对应 `GET /api/sessions`。见 `docs/web-ui-design.md` §3.7。
 
 #### 页面5: 结果预览与下载
 
@@ -1199,7 +1214,7 @@ QA 输出:
 │  └────────────────────────────────────────┘   │
 │                                             │
 │  ┌─ 预览 ──────────────────────────┐   │
-│  │  (docx → HTML → 浏览器内渲染)    │   │
+│  │  (ContentBlock → HTML 渲染)      │   │
 │  │  [章标题]  [段落]  [表]  ...              │   │
 │  └────────────────────────────────────────┘   │
 │                                             │
@@ -1218,7 +1233,7 @@ QA 输出:
 #### 8.4.1 任务管理
 
 ```
-Task Queue (Redis)
+TaskQueue（抽象接口，默认 InMemoryQueue，生产可切 Redis/Valkey）
   ├── task:generate-chapter-1
   │     status: completed
   │     result: {chapter: "功能一览", html: "...", time_ms: 23000}
@@ -1305,6 +1320,7 @@ CREATE TABLE session_files (
 /impact     → 跳转到影响调查画面
 /generate   → 跳转到生成执行画面
 /result     → 跳转到结果画面
+/history    → 跳转到历史会话页
 /settings   → 跳转到设置画面
 /status     → 显示当前生成任务的状态
 /cancel     → 取消当前生成

docs/web-ui-design-review-v1.1.md

@@ -0,0 +1,121 @@
+# Web UI 设计评审报告（v1.0 → v1.1）
+
+> 版本: v1.1 | 日期: 2026-08-09 | 状态: 评审完成 + 修订已完成
+>
+> 评审对象：`docs/web-ui-design.md` v1.0
+> 权威基准：大赛手册（`docs/design.md` §3.3 输入资料清单 / `docs/sample-spec.md`）+ 后端接口（`docs/api-design.md`）+ 编排（`docs/agent-runtime-design.md`）
+> 评审视角：跨文档一致性 + 设计质量（无障碍 / AI-slop / UX）
+> 严重级：**P0=大赛基准缺陷** **P1=接口/设计缺陷** **P2=建议**
+
+---
+
+## 评审结论摘要
+
+| 项 | 发现 | 严重度 | 处置 |
+|----|------|--------|------|
+| F1 | 上传区缺「概要设计做成说明书」+ 与 design.md §8 命名不一致 | P0 | 已修：补充独立 `write_instruction` 类型（web-ui §3.1、design §8、api-design §2.2） |
+| F2 | §4.1 任务队列写死 Redis，与「抽象 TaskQueue + InMemory 默认」决策冲突 | P1 | 已修：改为抽象接口表述 |
+| F3 | 设置页缺失（导航/斜杠命令存在，但无页面设计） | P1 | 已修：新增 §3.6 设置页 |
+| F4 | §3.5 预览路径标注「docx → HTML」，与 ContentBlock 管线不一致 | P1 | 已修：改为 ContentBlock → chapter_html + docx |
+| F5 | 规则冲突决策 UI 缺失（api/WS 有接口但无页面） | P1 | 已修：生成页新增冲突浮动卡片 |
+| F6 | 会话历史入口缺失（api 有 sessions 列表但 UI 无入口） | P1 | 已修：新增 §3.7 历史页 |
+| F7 | 无障碍与设计规范缺失、emoji 无规范说明 | P2 | 已修：新增 §7 |
+
+---
+
+## 二、详细发现
+
+### F1（P0）上传区输入资料不完整 + 命名不一致
+
+**证据**
+- 大赛输入资料（`docs/design.md` §3.3）：要件定义 / 概要设计模板 / **做成说明书** / 记入规则 / 图表规则 / 现系统源码与设计书
+- `docs/sample-spec.md` 样本集含 `概要設計做成説明書.docx`
+- `web-ui-design.md` §3.1 只有「要件定义 / 设计书模板 / 记录规则文档 / 图表规则 / 现有系统文件」——**做成说明书缺失**
+- 命名不一致：web-ui「记录规则文档」vs design.md §8「写入规则 vs 做成说明书」
+
+**修订**
+- `web-ui-design.md` §3.1：上传区补齐「概要设计做成说明书（推荐）」，命名统一为「要件定义 / 设计书模板 / 做成说明书 / 记入规则 / 图表规则 / 现有系统文件」
+- 做成说明书以独立 `file_type=write_instruction` 提交（api-design §2.2 扩展）
+- `design.md` §8 页面1 同步
+
+---
+
+### F2（P1）任务队列写死 Redis
+
+**证据**
+- `web-ui-design.md` §4.1 与 `design.md` §8.4.1 均写作「Task Queue (Redis)」
+- `api-design.md` §1 架构决策（已与用户确认）：抽象 `TaskQueue` + `InMemoryQueue` 默认 + `RedisQueue`/`ValkeyQueue` 可选
+- `design-review.md` P1-1 已于 2026-07-30 修完 runtime 侧，但 web-ui / design §8 漏同步
+
+**修订**
+- 两文档 §4.1 / §8.4.1 改为「抽象 TaskQueue，默认 InMemory，可切 Redis/Valkey」
+
+---
+
+### F3（P1）设置页无设计
+
+**证据**
+- 顶部导航含 [设置]、斜杠命令含 /settings
+- `api-design.md` §2.7 有 `/api/rules/versions`、`/update`、`/rollback`；§2.8 有 `/api/settings`
+- `web-ui-design.md` §3 仅有页面 1-5
+
+**修订**：新增 §3.6 设置页（规则版本管理 + LLM 配置只读摘要脱敏）
+
+---
+
+### F4（P1）预览渲染路径不一致
+
+**证据**
+- `web-ui-design.md` §3.5 与 `design.md` §8 页面5 均写「docx → HTML → 浏览器内渲染」
+- `design.md` §7 决策：LLM 输出 ContentBlock → `chapter_html`（前端预览）+ docx（下载）
+- `api-design.md` §2.6：`GET /result/preview` 返回 `{html}`
+
+**修订**：两处均改为「ContentBlock → HTML 渲染」，下载走 `/result/download`（docx）
+
+---
+
+### F5（P1）规则冲突决策 UI 缺失
+
+**证据**
+- `api-design.md` §2.7 提供 `POST /api/rules/conflicts/{id}/resolve`；§3.2 WS 事件 `conflict_pending {conflict_id, topic, chapter_id}`
+- `agent-runtime-design.md` §3.3 人工介入点包含「规则冲突确认」
+- 但 web-ui 5 页均无冲突决策界面
+
+**修订**：生成执行页（页面4）新增规则冲突浮动卡片（WS 触发；不阻塞；决策后该章继续）
+
+---
+
+### F6（P1）会话历史列表入口缺失
+
+**证据**
+- `api-design.md` §2.1 提供 `GET /api/sessions` 与 `DELETE /api/sessions/{id}`（会话列表/删除）
+- web-ui 仅有 §5.2 会话恢复一句话，无列表页
+
+**修订**：新增 §3.7 会话历史页（列表 / 恢复 / 删除 / 新建）
+
+---
+
+### F7（P2）无障碍 / 规范 / emoji 说明缺失
+
+**证据**：上传全拖拽、表格逐条修正等大量交互；无键盘可达、焦点可见、触控目标、色盲、对比度说明；绘图大量 emoji（🤖📁✅）
+
+**修订**：新增 §7 无障碍与设计规范（键盘可达、focus ring、≥44px、色盲安全、WCAG AA、骨架屏、具体错误文案、emoji 仅线框示意）
+
+---
+
+## 2. 修订文件清单
+
+| 文件 | 变更 |
+|------|------|
+| `docs/web-ui-design.md` | v1.0 → v1.1（F1-F7 全修订；新增设置/历史页、冲突卡片、无障碍章、端点对应表） |
+| `docs/api-design.md` | §2.2 `file_type` 枚举扩展 `write_instruction` + 注释（F1 连带） |
+| `docs/design.md` | §8 简版镜像同步（上传区、预览路径、队列抽象、导航历史、冲突卡片、设置/历史页简版、/history 命令） |
+| `docs/web-ui-design-review-v1.1.md` | 本报告 |
+
+---
+
+## 3. 遗留建议（不阻塞）
+
+- **RAG 层分类确认**：`write_instruction`（做成说明书）在 Parser 归类 Type A 写入规则（rag-layer §1.1）— 已存在对应约定，无额外工作
+- **验收建议**：实现 Phase 6（Web UI）时以上述 v1.1 为唯一依据；后续若做大版本 UI 改版，可再用 design-review 视觉审计（需已运行站点）
+- **历史页「删除」二次确认**：防误伤生成成果（v1.1 §3.7 已标注）

docs/web-ui-design.md

@@ -1,6 +1,15 @@
 # Web UI 设计文档
 
-> 版本: v1.0 | 日期: 2026-07-21 | 状态: 初版
+> 版本: v1.1 | 日期: 2026-08-09 | 状态: 复审修订版
+>
+> 本次修订（v1.0 → v1.1）：按 `docs/web-ui-design-review-v1.1.md` 评审结果修订——
+> ① 上传区补齐「概要设计做成说明书」（独立 `write_instruction` 类型，api-design §2.2 连带扩展）
+> ② 命名统一（记入规则 / 图表规则 / 做成说明书）
+> ③ §4.1 任务队列改为抽象 TaskQueue（InMemory 默认，Redis/Valkey 可选）
+> ④ §3.5 预览路径改为 ContentBlock → chapter_html + docx
+> ⑤ 新增设置页（§3.6）与会话历史页（§3.7）
+> ⑥ 生成页新增规则冲突浮动卡片（WS conflict_pending 触发）
+> ⑦ 新增无障碍与设计规范（§7）
 
 ---
 
@@ -8,11 +17,13 @@
 
 概要设计书自动生成 Agent 的 Web UI 是用户与系统交互的唯一界面，承担以下功能：
 
-- 文件上传（要件定义、模板、规则文档、现系统文件）
+- 文件上传（要件定义、模板、做成说明书、规则文档、现系统文件）
 - 各步骤的确认与修正（解析结果、影响调查结果、生成结果）
 - 生成进度实时展示
+- 规则冲突的决策
 - 最终设计书的预览与下载
-- 规则手册管理（更新、版本查看）
+- 规则手册管理（更新、版本查看、回退）
+- 会话历史（恢复、删除）
 - 多用户支持（数据隔离）
 
 ---
@@ -23,7 +34,7 @@
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  Genesis    [上传] [解析] [影响调查] [生成] [结果]   [设置] │ ← 顶部导航
+│  Genesis    [上传] [解析] [影响调查] [生成] [结果] [历史] [设置] │ ← 顶部导航
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
 │  ┌─ 对话区域 ──────────────────────────────────────────┐   │
@@ -51,12 +62,13 @@
 
 ```
 ① 上传  →  ② 解析确认  →  ③ 影响调查确认  →  ④ 生成执行  →  ⑤ 结果预览
-(文件选择)     (Sheet判定等)    (关联・不确定处)   (进度显示)     (设计书浏览/下载)
+(文件选择)     (Sheet判定等)    (关联・不确定处)   (进度/冲突)    (设计书浏览/下载)
 ```
 
 - 每步骤有"确认"按钮，确认后进入下一步
-- 可通过左侧导航跳转到任意已完成的步骤（支持回退）
+- 通过顶部导航可跳转到**任意已完成步骤**（状态机允许的回退路径，见 api-design §2.5 rollback 端点）
 - 当前步骤高亮显示
+- **历史页**提供已完成/进行中会话的列表入口与恢复（见 §3.7）
 
 ---
 
@@ -78,22 +90,27 @@
 │                                             │
 │  📁 设计书模板 (必须)                          │
 │  ┌─────────────────────────────────────┐    │
-│  │  .docx (Word)                       │    │
+│  │ .docx (Word)                        │    │
 │  └─────────────────────────────────────┘    │
 │                                             │
-│  📁 记录规则文档 (推荐)                        │
+│  📁 概要设计做成说明书 (推荐)                  │
 │  ┌─────────────────────────────────────┐    │
-│  │  .docx / .xlsx / .pptx (可多个)      │    │
+│  │ .docx (Word) · 各章作成指引         │    │
+│  └─────────────────────────────────────┘    │
+│                                             │
+│  📁 记入规则 (推荐, 可多个)                   │
+│  ┌─────────────────────────────────────┐    │
+│  │ .docx / .xlsx / .pptx               │    │
 │  └─────────────────────────────────────┘    │
 │                                             │
 │  📁 图表规则 (推荐)                          │
 │  ┌─────────────────────────────────────┐    │
-│  │  .docx / .xlsx / .pptx              │    │
+│  │ .docx / .xlsx / .pptx               │    │
 │  └─────────────────────────────────────┘    │
 │                                             │
 │  📁 现有系统文件 (任意, 追加/改修场景使用)      │
 │  ┌─────────────────────────────────────┐    │
-│  │  .java/.xml/.yml 源代码 或            │    │
+│  │ .java/.xml/.yml 源代码 或            │    │
 │  │  既有设计书 (.docx/.xlsx)            │    │
 │  └─────────────────────────────────────┘    │
 │                                             │
@@ -106,11 +123,14 @@
 **上传规则：**
 - 要件定义文件至少一个
 - 模板文件必须是一个 .docx
+- 做成说明书可零个（系统有内建默认指引时）；上传时以 `write_instruction` 类型标记（api-design §2.2）
 - 规则文档可多个，也可零个（规则手册已存在时）
 - 现系统文件仅在追加/改修场景时需要
-- 文件大小限制：最大100MB
+- 文件大小限制：最大 100MB
 - 支持拖拽上传、点击上传、取消上传
 
+**对齐**：`POST /api/sessions/{id}/files`（`file_type`：`requirements` / `template` / `write_instruction` / `rules` / `existing_system`）
+
 **斜杠命令：** `/upload` 等同于"上传文件区域获得焦点"
 
 ---
@@ -126,11 +146,11 @@
 │  ┌────────┬────────────┬────────┬─────────┐ │
 │  │ Sheet名│ 类型判定    │ 修正   │ 行数/列数│ │
 │  ├────────┼────────────┼────────┼─────────┤ │
-│  │ 功能一览 │ ✅ FUNCTION │  [修正]│ 150x5   │ │
-│  │ 画面一览 │ ✅ SCREEN   │  [修正]│ 30x4    │ │
-│  │ 账票一览 │ ✅ REPORT   │  [修正]│ 12x6    │ │
-│  │ DB定义  │ ✅ DATABASE │  [修正]│ 20x8    │ │
-│  │ 自由记述 │ ⚠ 自由记述型│  [修正]│ 45行    │ │
+│  │ 功能一览 │ ✅ FUNCTION │  [修正]│ 150x5    │ │
+│  │ 画面一览 │ ✅ SCREEN   │  [修正]│ 30x4     │ │
+│  │ 账票一览 │ ✅ REPORT   │  [修正]│ 12x6     │ │
+│  │ DB定义  │ ✅ DATABASE │  [修正]│ 20x8     │ │
+│  │ 画面对应 │ ⚠ 自由记述型│  [修正]│ 45行     │ │
 │  └────────┴────────────┴────────┴─────────┘ │
 │  ※ 取消线行将从生成对象中排除                    │
 │                                             │
@@ -156,10 +176,12 @@
 ```
 
 **交互说明：**
-- Sheet类型判定由 AI 自动，但用户可以点击"修正"手动更改
+- Sheet 类型判定由 AI 自动，但用户可以手动更改
 - 章节构成由模板自动解析，但用户可以追加/删除章节
 - 现有系统信息仅在追加/改修场景显示
 
+**对齐原有：** `GET /api/sessions/{id}/parse-result`、`POST /api/sessions/{id}/confirm-parse`、`POST /api/sessions/{id}/reparse`
+
 ---
 
 ### 3.3 页面3: 影响调查确认
@@ -186,7 +208,7 @@
 │     根据: 仅名称相似                          │
 │     → [追加] [否决] [修正]                      │
 │  ❓ 批注「另纸参照」的另纸未找到                │
-│     → [输入回答] [跳过]                    │
+│     → [输入回答] [跳过]                        │
 │                                             │
 │  ── 质量指标 ──                                 │
 │  ⚠ 孤立要素: F012 与任何要素均无关联            │
@@ -200,11 +222,13 @@
 - 一栏显示全部关联（无 auto-pass）
 - 仅高亮关注未确定项目
 - 各关联的追加/删除/种类变更/证据修正是个别交互
-- 修正履历显示在画面底部
+- 修正履历显示在画面对应
+
+**对齐原有：** `GET /api/sessions/{id}/impact-result`、`POST /api/sessions/{id}/impact-edits`、`POST /api/sessions/{id}/confirm-impact`、`POST /api/sessions/{id}/reject-impact`
 
 ---
 
-### 3.4 页面4: 生成执行
+### 3.4 页面4: 生成执行（含规则冲突决策）
 
 ```
 ┌─────────────────────────────────────────────┐
@@ -215,9 +239,9 @@
 │                                             │
 │  ✅ 功能一览 - 完成 (23秒)                      │
 │  ✅ 画面一览 - 完成 (18秒)                      │
-│  ⠋ DB设计  - 生成中...                          │
+│  ⠋ DB设计   - 生成中...                          │
 │  ⬜ 账票一览 - 等待                              │
-│  ⬜ IF定义  - 等待                              │
+│  ⬜ IF定义  - 等待                               │
 │  ⬜ 非功能要件 - 等待                           │
 │                                             │
 │  已过时间: 41秒 / 预计时间: ~3分                │
@@ -225,11 +249,17 @@
 │  ──────────────────────────────────────      │
 │  DB设计章 生成中:                              │
 │  关联要素: F001, F003, TB001, TB002        │
-│  适用规则: 写入规则_v3                      │
-│                                             │
-│  ──────────────────────────────────────      │
+│  适用规则: 写入规则_v3                        │
 │                                             │
 │  [中途中断]  [查看日志]                     │
+│                                             │
+│  ┌─ 规则冲突 (浮动卡片) ───────────────────┐   │
+│  │  ⚠ 检测到规则冲突（DB设计章）                  │   │
+│  │  记入规则 2.3「表头仅加粗」                   │   │
+│  │  图表规则 2.3「表头加粗+下划线」                │   │
+│  │  [采用「记入规则」]  [采用「图表规则」]         │   │
+│  │  [两规则都标注给人工]                          │   │
+│  └──────────────────────────────────────┘   │
 └─────────────────────────────────────────────┘
 ```
 
@@ -238,6 +268,9 @@
 - 生成完成时通过浏览器通知（或 WebSocket 推送）告知
 - 选择中断时，已完成的章节保留，其余作为未完成保存
 - 中断后恢复时，从已完成的章节继续生成
+- **规则冲突**：由 WebSocket 事件 `conflict_pending {conflict_id, topic, chapter_id}` 触发浮动卡片（不阻塞其余进度展示）；用户决策后调用 `POST /api/rules/conflicts/{id}/resolve`，该章在决策后才继续（未决策时该章保持 waiting）
+
+**对齐原有：** `POST /api/sessions/{id}/generate`、`GET /api/sessions/{id}/generation-status`、`POST /api/sessions/{id}/regenerate-chapter`、`POST /api/rules/conflicts/{id}/resolve`
 
 ---
 
@@ -249,57 +282,132 @@
 ├─────────────────────────────────────────────┤
 │                                             │
 │  ┌─ QA报告 ──────────────────────────┐   │
+│  │  ⏳ QA 校验中…                        │   │
+│  │  📊 检查项 7/10 完成                     │   │
+│  ├─────────────────────────────────────┤   │
+│  │  (完成后)                              │   │
 │  │  ✅ 全部10项检查通过                    │   │
 │  │  内容准确性: 通过                         │   │
 │  │  关联一致性: 通过                         │   │
 │  │  规则遵守度: 警告 1件                      │   │
-│  │    → 「功能概要应包含影响范围」    │   │
+│  │  警告 1件:  →「功能概要应包含影响范围」     │   │
 │  └────────────────────────────────────────┘   │
 │                                             │
 │  ┌─ 预览 ──────────────────────────┐   │
-│  │  (docx → HTML → 浏览器内渲染)    │   │
-│  │  1. 目的                                    │   │
-│  │  本系统是...                             │   │
+│  │ (章内容块 → HTML → 浏览器内渲染)   │   │
+│  │ 1. 目的                                    │   │
+│  │ 本系统是...                             │   │
 │  │                                             │   │
-│  │  2. 功能一览                                 │   │
+│  │ 2. 功能一览                                 │   │
 │  │  ┌──────┬────────┬───────┐                │   │
 │  │  │功能ID │ 功能名  │ 概要  │                │   │
 │  │  ├──────┼────────┼───────┤                │   │
-│  │  │F001  │用户    │...    │                │   │
+│  │  │F001  │用户注册 │...    │                │   │
 │  │  └──────┴────────┴───────┘                │   │
-│  │  ...                                       │   │
+│  │ ...                                       │   │
 │  └────────────────────────────────────────┘   │
 │                                             │
 │  ┌─ 下载区域 ──────────────────────────┐   │
-│  │  📥 下载设计书 (.docx)         │   │
-│  │  📥 下载QA报告 (.json)      │   │
-│  │  📥 下载影响调查书 (.json)     │   │
+│  │  📥 下载设计书 (.docx)             │   │
+│  │  📥 下载QA报告 (.json)              │   │
+│  │  📥 下载影响调查书 (.json)          │   │
 │  └────────────────────────────────────────┘   │
 │                                             │
 │  [修正后重新生成]  [进行新生成]               │
 └─────────────────────────────────────────────┘
 ```
 
+**交互说明 / 预览路径（修订 v1.1）：**
+- 预览采用 **ContentBlock → chapter_html** 管线（`GET /api/sessions/{id}/chapters/{chapter_id}` 获取内容块；`GET /api/sessions/{id}/result/preview` 获取 HTML），最终下载由 `GET /api/sessions/{id}/result/download` 返回 docx
+- QA 校验完成的事件为 `qa_completed {summary}`，未完成时预览区显示「校验中…」占位
+- 下载项：设计书 docx / QA 报告 json / 影响调查书 json
+
+**对齐原有：** `GET /api/sessions/{id}/result/preview`、`/result/download`、`/result/qa-report`、`/result/impact-report`、`POST /api/sessions/{id}/writer-fix`、`POST /api/sessions/{id}/rollback-to-impact`
+
+---
+
+### 3.6 页面6: 设置
+
+```
+┌─────────────────────────────────────────────┐
+│  6. 设置                                    │
+├─────────────────────────────────────────────┤
+│                                             │
+│  ── 规则手册 ──                                │
+│  [上一个版本]  [当前版本: v3]  [重建手册]      │
+│  版本列表:                                      │
+│  ▸ v3 (active) 2026-08-01  文档: 5件          │
+│     ▸ 记入规则.docx                     │
+│     ▸ 图表规则.xlsx                     │
+│     ▸ 做成说明书.docx                   │
+│  ▸ v2 2026-07-15  文档: 3件   [回滚]          │
+│  ▸ v1 2026-07-01  文档: 2件                  │
+│                                             │
+│  [更新规则]（将当前上传区规则文件重建手册）        │
+│                                             │
+│  ── LLM 状态（只读摘要，脱敏） ──              │
+│  模型: deepseek-chat (主) / deepseek-chat (备用) │
+│  向量库: Chroma (可用)                      │
+│  约束: max_context=32000 / max_output=4096  │
+│  (敏感密钥不显示，见 /api/settings 脱敏)      │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+**对齐原有：** `GET /api/rules/versions`、`POST /api/rules/update`、`POST /api/rules/rollback`、`GET /api/settings`
+
+---
+
+### 3.7 页面7: 会话历史
+
+```
+┌─────────────────────────────────────────────┐
+│  7. 历史会话                                │
+├─────────────────────────────────────────────┤
+│                                             │
+│  [＋ 新会话]                                  │
+│                                             │
+│  ┌─ 会话列表 ────────────────────────────┐  │
+│  │ 会话ID   状态        更新于    操作         │  │
+│  │ s_1009   结果已生成   今天 14:03  [恢复] [删]  │  │
+│  │ s_1008   影响调查确认 今天 13:40  [恢复] [删]  │  │
+│  │ s_1007   解析确认    昨天 17:21  [恢复] [删]  │  │
+│  │ ...                                          │  │
+│  └──────────────────────────────────────────┘  │
+│                                             │
+│  [恢复并继续] 跳到该会话当前步骤              │
+│  (会话状态: uploading / parsing / impact /   │
+│   awaiting_parse_confirm / awaiting_impact_confirm │
+│  / writing / qa / done)                     │
+└─────────────────────────────────────────────┘
+```
+
+**交互说明：**
+- 通过 `GET /api/sessions?user_id=` 拉取会话列表
+- 「恢复」进入该会话当前步骤（若处于 waiting 状态则自动拉取最新进度）
+- 「删除」调用 `DELETE /api/sessions/{id}`（需二次确认，避免误删生成成果）
+
 ---
 
 ## 4. 技术设计
 
-### 4.1 任务管理
+### 4.1 任务管理与队列抽象（修订 v1.1）
 
 ```
-Task Queue (Redis)
-  ├── task:generate-chapter-1
-  │     status: completed
-  │     result: {chapter: "功能一览", html: "...", time_ms: 23000}
-  │
-  ├── task:generate-chapter-2
-  │     status: running
-  │     started_at: 2026-07-21T12:01:00Z
-  │
-  └── task:generate-chapter-3
-        status: pending
+TaskQueue（抽象接口，默认实现 InMemoryQueue）
+  ├── InMemoryQueue     # 开发/测试/演示默认（零依赖）
+  ├── RedisQueue        # 生产可选（redis-py）
+  └── ValkeyQueue       # 生产可选（Valkey，Redis 协议兼容）
+
+任务队列条目：
+  task:generate-chapter-1
+    status: completed
+    result: {chapter: "章节", html: "...", time_ms: 23000}
 ```
 
+- 队列实现由配置 `task_queue.backend` 决定（memory / redis / valkey），详见 `docs/api-design.md` §1 架构决策与 `docs/config-design.md`
+- Web UI 无需关心后端实现，仅消费统一任务状态
+
 ### 4.2 会话管理（SQLite）
 
 **会话表设计：**
@@ -311,18 +419,18 @@ CREATE TABLE sessions (
     user_id     TEXT NOT NULL,
     created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
     updated_at  DATETIME,
-    status      TEXT,                    -- "uploading" | "parsing" | "awaiting_parse_confirm" | "impact_running" | "awaiting_impact_confirm" | "writing" | "qa" | "done"
-    current_step TEXT,
-    metadata    JSON                     -- 会话的摘要
+    status      TEXT,   -- "uploading" | "parsing" | "awaiting_parse_confirm" | "impact_running" | "awaiting_impact_confirm" | "writing" | "qa" | "done"
+    metadata    JSON,   -- 会话的摘要
+    CONSTRAINT fk_user FOREIGN KEY(user_id) REFERENCES users(id)
 );
 
 -- 中间成果物的快照
 CREATE TABLE session_snapshots (
     id          INTEGER PRIMARY KEY AUTOINCREMENT,
     session_id  TEXT NOT NULL REFERENCES sessions(id),
-    step        TEXT NOT NULL,           -- "parse" | "impact" | "writer" | "qa"
-    data        BLOB,                    -- 序列化的中间成果物 (JSON)
-    version     INTEGER DEFAULT 1,       -- 修正时的版本管理
+    step        TEXT NOT NULL CHECK (step IN ('parse','impact','writer','qa')),
+    data        BLOB,
+    version     INTEGER DEFAULT 1,
     created_at  DATETIME DEFAULT CURRENT_TIMESTAMP
 );
 
@@ -330,77 +438,67 @@ CREATE TABLE session_snapshots (
 CREATE TABLE session_files (
     id          INTEGER PRIMARY KEY AUTOINCREMENT,
     session_id  TEXT NOT NULL REFERENCES sessions(id),
-    file_type   TEXT NOT NULL,           -- "requirements" | "template" | "rules" | "existing_system"
+    file_type   TEXT NOT NULL,  -- "requirements" | "template" | "write_instruction" | "rules" | "existing_system"
     file_name   TEXT NOT NULL,
-    file_path   TEXT NOT NULL,           -- 文件系统上的路径
+    file_path   TEXT NOT NULL,
     file_size   INTEGER,
-    mime_type   TEXT,
     uploaded_at DATETIME DEFAULT CURRENT_TIMESTAMP
 );
 ```
 
-**为什么用 SQLite：**
-- 单一文件，无需额外安装
-- 通过 SQL 查询即可轻松搜索会话（如「用户X的未完成会话」）
-- ACID 事务保证数据一致性
-- 进程重启后数据仍保留
-- 迁移到 PostgreSQL 也容易（表定义兼容性高）
+> 修订说明：`session_files.file_type` 同步扩展 `write_instruction`（对照 api-design §2.2）
 
 ### 4.3 多用户
 
 ```
 工作区:
   /data/users/{user_id}/
-  ├── uploads/           # 用户上传的文件
-  │   ├── session_001/
-  │   │   ├── requirements.xlsx
-  │   │   └── template.docx
-  │   └── session_002/
+  ├── uploads/           # 用户上传的文件（含要件/模板/做成说明/规则）
   ├── outputs/           # 生成的设计书
-  │   ├── session_001.docx
-  │   └── session_002.docx
   └── config/
-      └── .env           # 用户个别设置（API Key 等共享）
+      └── .env           # 用户个别设置
 
-共享数据（所有用户通用）:
+共享数据（规则与模板全局共享）:
   /data/shared/
-  ├── rules-handbook/
-  │   ├── v1/
-  │   └── v2/            # 规则更新版本
+  ├── rules-handbook/   # 规则手册版本目录
+  │   ├── v1/ v2/ ...
   └── templates/
 ```
 
 ---
 
-## 5. 异常处理UX
+## 5. 异常处理 UX
 
 ### 5.1 生成出错时
 
 ```
-DB设计 生成过程中发生错误
-┌─────────────────────────────────────────┐
-│  ⚠ DB设计章生成时发生错误                    │
-│  错误详情: LLM API调用失败    │
-│  错误码: LLM_TIMEOUT                 │
+数据库设计 生成过程处理中发生错误
+┌──────────────────────────────────────────┐
+│  ⚠ DB 设计章节生成时发生错误                    │
+│  详情: LLM 调用超时                     │
+│  错误码: LLM_TIMEOUT (502)              │
 │                                           │
-│  [重试]  [跳过并继续]  [中断]     │
-└─────────────────────────────────────────┘
+│  [重试]  [跳过并继续]  [中断]              │
+│                                           │
+│  若 LLM 未配置: 显示「去设置页配置 Key」   │
+└──────────────────────────────────────────┘
 ```
 
 - **重试**: 重新生成同一章（重试 LLM 调用）
 - **跳过**: 跳过此章并进入下一章
-- **中断**: 全部中断，保存迄今为止的已完成章节
+- **中断**: 全部中断，保存已完成的章节
+- 用户选项与 `api-design.md` §7 错误码表的 `options` 列对应；LLM 相关错误（LLM_TIMEOUT / LLM_NETWORK_ERROR / LLM_NOT_CONFIGURED / LLM_PARSE_ERROR）由 engine `error_code` 提供机器可读值（见 `docs/superpowers/specs/2026-08-09-llm-errorcode-alignment-design.md`）
 
 ### 5.2 会话恢复
 
-浏览器关闭后再次打开时：
+浏览器关闭后再次打开时（从历史页或直接访问）：
 
 ```
 「要恢复上次的会话吗？」
-上次的状态: Step 3 (影响调查确认)
- ・解析结果: ✅ 完成
- ・影响调查: ✅ 完成（以上述v2确认）
- ・Writer: 未开始
+上次的状态: step 3 (影响调查确认)
+  ・解析结果: ✅ 完成
+  ・影响调查: ✅ 完成（以已确认版本）
+  ・生成:    未开始
 
 [恢复并继续]  [开始新会话]
 ```
@@ -413,11 +511,42 @@ DB设计 生成过程中发生错误
 /upload     → 聚焦到文件上传区域
 /probe      → 跳转到解析结果画面
 /impact     → 跳转到影响调查画面
-/generate   → 跳转到生成执行画面
+/generate   → 跳到生成执行
 /result     → 跳转到结果画面
+/history    → 跳转到历史会话页
 /settings   → 跳转到设置画面
-/status     → 显示当前生成任务的状态
+/status     → 查看当前任务状态
 /cancel     → 取消当前生成
 /help       → 显示帮助
 ```
 
+---
+
+## 7. 无障碍与设计规范（v1.1 新增）
+
+- **键盘可达**：所有交互（上传、表格修正、确认、冲突决策）可独立用 Tab + Enter/Space 完成
+- **焦点可见**：键盘导航始终显示 focus ring；清除 `:focus-visible` 必须提供替代
+- **触控目标**：可点击目标 ≥ 44×44px
+- **色盲安全**：状态不单用红/绿区分（附加图标/文字，如 ✅/⚠/❌ 应用于状态图标）
+- **对比度**：正文 ≥ 4.5:1，大号文字 ≥ 3:1（WCAG AA）
+- **加载不能为空**：生成/进度用骨架屏或指示器，避免空白闪屏
+- **错误提示语具体**：错误信息给出出错的章节/操作 + 建议操作（如「配置 Key」）
+- **emoji 规范**：本文作为线稿使用 emoji 仅为示意；正式实现用图标库（如 lucide 等）统一
+- **移动与响应式**：不要求手机为主场景，但桌面缩窄到 1024px 时须保持 5 步导航可用
+
+---
+
+## 8. 与后端 API 的端点对应（汇总）
+
+| UI 步骤 | 主要端点（api-design）|
+|---------|----------------------|
+| 上传 | POST `/api/sessions/{id}/files`、POST `/api/sessions/{id}/start-parse` |
+| 解析确认 | GET/confirm-parse/reparse |
+| 影响调查 | start-impact / impact-result / impact-edits / confirm-impact / reject-impact |
+| 生成 | generate / generation-status / regenerate-chapter |
+| 规则冲突 | POST `/api/rules/conflicts/{id}/resolve`（WS conflict_pending 触发）|
+| QA | run-qa / qa-result / writer-fix / rollback-to-impact |
+| 结果下载 | result/preview / download / qa-report / impact-report |
+| 历史 | GET `/api/sessions`、DELETE `/api/sessions/{id}` |
+| 设置 | GET `/api/rules/versions`、POST `/api/rules/update`、POST `/api/rules/rollback`、GET `/api/settings` |
+| 其他 | GET `/api/health`、POST `/api/sessions/{id}/cancel`、GET `/api/sessions/{id}/logs` |