lhl
a1336f6dd3
- 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% 不回归
555 lines
31 KiB
Markdown
555 lines
31 KiB
Markdown
# Web UI 设计文档
|
||
|
||
> 版本: 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）
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
概要设计书自动生成 Agent 的 Web UI 是用户与系统交互的唯一界面，承担以下功能：
|
||
|
||
- 文件上传（要件定义、模板、做成说明书、规则文档、现系统文件）
|
||
- 各步骤的确认与修正（解析结果、影响调查结果、生成结果）
|
||
- 生成进度实时展示
|
||
- 规则冲突的决策
|
||
- 最终设计书的预览与下载
|
||
- 规则手册管理（更新、版本查看、回退）
|
||
- 会话历史（恢复、删除）
|
||
- 多用户支持（数据隔离）
|
||
|
||
---
|
||
|
||
## 2. 页面结构
|
||
|
||
### 2.1 全局布局
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Genesis [上传] [解析] [影响调查] [生成] [结果] [历史] [设置] │ ← 顶部导航
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─ 对话区域 ──────────────────────────────────────────┐ │
|
||
│ │ 🤖 你好。请上传要件定义的Excel │ │
|
||
│ │ 🧑 [拖放文件] │ │
|
||
│ │ 🤖 解析完成！请确认以下Sheet类型 │ │
|
||
│ │ ┌────────┬──────────┬───────────┐ │ │
|
||
│ │ │ Sheet名 │ 判定结果 │ 修正 │ │ │
|
||
│ │ ├────────┼──────────┼───────────┤ │ │
|
||
│ │ │ 功能一览 │ ✅ FUNCTION │ │ │ │
|
||
│ │ │ 画面一览 │ ❌ 未判定 │ [修正▼] │ │ │
|
||
│ │ └────────┴──────────┴───────────┘ │ │
|
||
│ │ [确认并继续] │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ 组件区域 ──────────────────────────────────────────┐ │
|
||
│ │ (根据当前步骤切换) │ │
|
||
│ └──────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 状态: [📤已上传] [✅完成] [⏳进行中] [⏸未开始] │ ← 底部状态栏
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 导航步骤
|
||
|
||
```
|
||
① 上传 → ② 解析确认 → ③ 影响调查确认 → ④ 生成执行 → ⑤ 结果预览
|
||
(文件选择) (Sheet判定等) (关联・不确定处) (进度/冲突) (设计书浏览/下载)
|
||
```
|
||
|
||
- 每步骤有"确认"按钮，确认后进入下一步
|
||
- 通过顶部导航可跳转到**任意已完成步骤**（状态机允许的回退路径，见 api-design §2.5 rollback 端点）
|
||
- 当前步骤高亮显示
|
||
- **历史页**提供已完成/进行中会话的列表入口与恢复（见 §3.7）
|
||
|
||
---
|
||
|
||
## 3. 各页面详细设计
|
||
|
||
### 3.1 页面1: 文件上传
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 1. 上传文件 │
|
||
├─────────────────────────────────────────────┤
|
||
│ │
|
||
│ 📁 要件定义 (必须) │
|
||
│ ┌─────────────────────────────────────┐ │
|
||
│ │ .xlsx, .xls, .docx, .pptx 拖放即可 │ │
|
||
│ │ 或 [选择文件] │ │
|
||
│ └─────────────────────────────────────┘ │
|
||
│ ⚠ 要件定义推荐使用Excel │
|
||
│ │
|
||
│ 📁 设计书模板 (必须) │
|
||
│ ┌─────────────────────────────────────┐ │
|
||
│ │ .docx (Word) │ │
|
||
│ └─────────────────────────────────────┘ │
|
||
│ │
|
||
│ 📁 概要设计做成说明书 (推荐) │
|
||
│ ┌─────────────────────────────────────┐ │
|
||
│ │ .docx (Word) · 各章作成指引 │ │
|
||
│ └─────────────────────────────────────┘ │
|
||
│ │
|
||
│ 📁 记入规则 (推荐, 可多个) │
|
||
│ ┌─────────────────────────────────────┐ │
|
||
│ │ .docx / .xlsx / .pptx │ │
|
||
│ └─────────────────────────────────────┘ │
|
||
│ │
|
||
│ 📁 图表规则 (推荐) │
|
||
│ ┌─────────────────────────────────────┐ │
|
||
│ │ .docx / .xlsx / .pptx │ │
|
||
│ └─────────────────────────────────────┘ │
|
||
│ │
|
||
│ 📁 现有系统文件 (任意, 追加/改修场景使用) │
|
||
│ ┌─────────────────────────────────────┐ │
|
||
│ │ .java/.xml/.yml 源代码 或 │ │
|
||
│ │ 既有设计书 (.docx/.xlsx) │ │
|
||
│ └─────────────────────────────────────┘ │
|
||
│ │
|
||
│ [更新规则] ← 规则手册再构建按钮 │
|
||
│ │
|
||
│ [上传完成 → 进入解析] │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
**上传规则：**
|
||
- 要件定义文件至少一个
|
||
- 模板文件必须是一个 .docx
|
||
- 做成说明书可零个（系统有内建默认指引时）；上传时以 `write_instruction` 类型标记（api-design §2.2）
|
||
- 规则文档可多个，也可零个（规则手册已存在时）
|
||
- 现系统文件仅在追加/改修场景时需要
|
||
- 文件大小限制：最大 100MB
|
||
- 支持拖拽上传、点击上传、取消上传
|
||
|
||
**对齐**：`POST /api/sessions/{id}/files`（`file_type`：`requirements` / `template` / `write_instruction` / `rules` / `existing_system`）
|
||
|
||
**斜杠命令：** `/upload` 等同于"上传文件区域获得焦点"
|
||
|
||
---
|
||
|
||
### 3.2 页面2: 解析结果确认
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 2. 确认解析结果 │
|
||
├─────────────────────────────────────────────┤
|
||
│ │
|
||
│ ▶ Excel要件定义 - Sheet类型判定 │
|
||
│ ┌────────┬────────────┬────────┬─────────┐ │
|
||
│ │ Sheet名│ 类型判定 │ 修正 │ 行数/列数│ │
|
||
│ ├────────┼────────────┼────────┼─────────┤ │
|
||
│ │ 功能一览 │ ✅ FUNCTION │ [修正]│ 150x5 │ │
|
||
│ │ 画面一览 │ ✅ SCREEN │ [修正]│ 30x4 │ │
|
||
│ │ 账票一览 │ ✅ REPORT │ [修正]│ 12x6 │ │
|
||
│ │ DB定义 │ ✅ DATABASE │ [修正]│ 20x8 │ │
|
||
│ │ 画面对应 │ ⚠ 自由记述型│ [修正]│ 45行 │ │
|
||
│ └────────┴────────────┴────────┴─────────┘ │
|
||
│ ※ 取消线行将从生成对象中排除 │
|
||
│ │
|
||
│ ▶ Word模板 - 章节构成 │
|
||
│ 检测到的章节: │
|
||
│ 1. 目的 │
|
||
│ 2. 功能一览 │
|
||
│ 3. 画面一览 │
|
||
│ 4. DB设计 │
|
||
│ 5. IF定义 │
|
||
│ 6. 账票一览 │
|
||
│ 7. 非功能要件 │
|
||
│ [修改章节] │
|
||
│ │
|
||
│ ▶ 现有系统探索结果 (仅追加/改修场景显示) │
|
||
│ 检测: Controller 5件 / Service 12件 / Entity 8件 │
|
||
│ API端点: 14件 │
|
||
│ DB表: 14件 │
|
||
│ [查看详情] [要修正吗？] │
|
||
│ │
|
||
│ [确认并进入影响调查] │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
**交互说明：**
|
||
- Sheet 类型判定由 AI 自动，但用户可以手动更改
|
||
- 章节构成由模板自动解析，但用户可以追加/删除章节
|
||
- 现有系统信息仅在追加/改修场景显示
|
||
|
||
**对齐原有：** `GET /api/sessions/{id}/parse-result`、`POST /api/sessions/{id}/confirm-parse`、`POST /api/sessions/{id}/reparse`
|
||
|
||
---
|
||
|
||
### 3.3 页面3: 影响调查确认
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 3. 确认影响调查结果 │
|
||
├─────────────────────────────────────────────┤
|
||
│ │
|
||
│ ── 影响调查概要 ── │
|
||
│ 要素数: 45件（功能12/画面10/账票8/DB10/IF3/批处理2）│
|
||
│ 关联数: 128件（高置信度85/中32/低11 │
|
||
│ 不确定处: 2件 │
|
||
│ │
|
||
│ ── 要素一览（可折叠） ── │
|
||
│ ▸ F001 用户注册 (功能) │
|
||
│ 关联: SC001(利用/h) SC002(利用/h) TB001(更新/h) │
|
||
│ [编辑] [删除] │
|
||
│ ▸ F005 月度汇总处理 (功能) │
|
||
│ 关联: ... │
|
||
│ │
|
||
│ ── 未确定项目（2件） ── │
|
||
│ ❓ F004 → TB007 的关联不明 │
|
||
│ 根据: 仅名称相似 │
|
||
│ → [追加] [否决] [修正] │
|
||
│ ❓ 批注「另纸参照」的另纸未找到 │
|
||
│ → [输入回答] [跳过] │
|
||
│ │
|
||
│ ── 质量指标 ── │
|
||
│ ⚠ 孤立要素: F012 与任何要素均无关联 │
|
||
│ ⚠ 风险: 删除 F001 将影响 5 个要素 │
|
||
│ │
|
||
│ [确认完成 → 进入生成] │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
**交互说明：**
|
||
- 一栏显示全部关联（无 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: 生成执行（含规则冲突决策）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 4. 概要设计书生成中... │
|
||
├─────────────────────────────────────────────┤
|
||
│ │
|
||
│ 进度: │
|
||
│ │
|
||
│ ✅ 功能一览 - 完成 (23秒) │
|
||
│ ✅ 画面一览 - 完成 (18秒) │
|
||
│ ⠋ DB设计 - 生成中... │
|
||
│ ⬜ 账票一览 - 等待 │
|
||
│ ⬜ IF定义 - 等待 │
|
||
│ ⬜ 非功能要件 - 等待 │
|
||
│ │
|
||
│ 已过时间: 41秒 / 预计时间: ~3分 │
|
||
│ │
|
||
│ ────────────────────────────────────── │
|
||
│ DB设计章 生成中: │
|
||
│ 关联要素: F001, F003, TB001, TB002 │
|
||
│ 适用规则: 写入规则_v3 │
|
||
│ │
|
||
│ [中途中断] [查看日志] │
|
||
```
|
||
> **串行约束（T10 / I14）**：章节严格按模板顺序**串行**生成，预计时间 = 章数 × 单章
|
||
> ~3-5 分钟（design §6.8.1）。UI 展示「第 N/总章 生成中」与逐章进度，让用户对
|
||
> 串行等待有预期；禁止并发触发多章生成（会造成 WriterState 竞态）。
|
||
│ │
|
||
│ ┌─ 规则冲突 (浮动卡片) ───────────────────┐ │
|
||
│ │ ⚠ 检测到规则冲突（DB设计章） │ │
|
||
│ │ 记入规则 2.3「表头仅加粗」 │ │
|
||
│ │ 图表规则 2.3「表头加粗+下划线」 │ │
|
||
│ │ [采用「记入规则」] [采用「图表规则」] │ │
|
||
│ │ [两规则都标注给人工] │ │
|
||
│ └──────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────┘
|
||
```
|
||
|
||
**交互说明：**
|
||
- 用户可保持此画面打开同时进行其他工作
|
||
- 生成完成时通过浏览器通知（或 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`
|
||
|
||
---
|
||
|
||
### 3.5 页面5: 结果预览与下载
|
||
|
||
```
|
||
┌─────────────────────────────────────────────┐
|
||
│ 5. 生成完成 │
|
||
├─────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─ QA报告 ──────────────────────────┐ │
|
||
│ │ ⏳ QA 校验中… │ │
|
||
│ │ 📊 检查项 7/10 完成 │ │
|
||
│ ├─────────────────────────────────────┤ │
|
||
│ │ (完成后) │ │
|
||
│ │ ✅ 全部10项检查通过 │ │
|
||
│ │ 内容准确性: 通过 │ │
|
||
│ │ 关联一致性: 通过 │ │
|
||
│ │ 规则遵守度: 警告 1件 │ │
|
||
│ │ 警告 1件: →「功能概要应包含影响范围」 │ │
|
||
│ └────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ 预览 ──────────────────────────┐ │
|
||
│ │ (章内容块 → HTML → 浏览器内渲染) │ │
|
||
│ │ 1. 目的 │ │
|
||
│ │ 本系统是... │ │
|
||
│ │ │ │
|
||
│ │ 2. 功能一览 │ │
|
||
│ │ ┌──────┬────────┬───────┐ │ │
|
||
│ │ │功能ID │ 功能名 │ 概要 │ │ │
|
||
│ │ ├──────┼────────┼───────┤ │ │
|
||
│ │ │F001 │用户注册 │... │ │ │
|
||
│ │ └──────┴────────┴───────┘ │ │
|
||
│ │ ... │ │
|
||
│ └────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ 下载区域 ──────────────────────────┐ │
|
||
│ │ 📥 下载设计书 (.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 任务管理与队列抽象（修订 v1.1 + T5 整改）
|
||
|
||
```
|
||
TaskQueue（抽象接口，v1 仅 InMemoryQueue；RedisQueue/ValkeyQueue 为 v2 预留，Scope 缩减裁定）
|
||
├── InMemoryQueue # v1 唯一实现（零依赖）
|
||
# RedisQueue / ValkeyQueue: v2 预留
|
||
|
||
任务队列条目：
|
||
task:generate-chapter-1
|
||
status: completed
|
||
result: {chapter: "章节", html: "...", time_ms: 23000}
|
||
```
|
||
|
||
- v1 队列实现固定为 `task_queue.backend=memory`（InMemoryQueue），详见 `docs/api-design.md` §1 架构决策与 `docs/config-design.md`
|
||
- Web UI 无需关心后端实现，仅消费统一任务状态
|
||
|
||
### 4.2 会话管理（SQLite）
|
||
|
||
**会话表设计：**
|
||
|
||
```sql
|
||
-- 主模型: 每个用户的会话
|
||
CREATE TABLE sessions (
|
||
id TEXT PRIMARY KEY,
|
||
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"
|
||
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 CHECK (step IN ('parse','impact','writer','qa')),
|
||
data BLOB,
|
||
version INTEGER DEFAULT 1,
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
|
||
-- 已上传文件的元数据（文件本体保存在文件系统）
|
||
CREATE TABLE session_files (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
session_id TEXT NOT NULL REFERENCES sessions(id),
|
||
file_type TEXT NOT NULL, -- "requirements" | "template" | "write_instruction" | "rules" | "existing_system"
|
||
file_name TEXT NOT NULL,
|
||
file_path TEXT NOT NULL,
|
||
file_size INTEGER,
|
||
uploaded_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
> 修订说明：`session_files.file_type` 同步扩展 `write_instruction`（对照 api-design §2.2）
|
||
|
||
### 4.3 多用户
|
||
|
||
```
|
||
工作区:
|
||
/data/users/{user_id}/
|
||
├── uploads/ # 用户上传的文件（含要件/模板/做成说明/规则）
|
||
├── outputs/ # 生成的设计书
|
||
└── config/
|
||
└── .env # 用户个别设置
|
||
|
||
共享数据（规则与模板全局共享）:
|
||
/data/shared/
|
||
├── rules-handbook/ # 规则手册版本目录
|
||
│ ├── v1/ v2/ ...
|
||
└── templates/
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 异常处理 UX
|
||
|
||
### 5.1 生成出错时
|
||
|
||
```
|
||
数据库设计 生成过程处理中发生错误
|
||
┌──────────────────────────────────────────┐
|
||
│ ⚠ 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 (影响调查确认)
|
||
・解析结果: ✅ 完成
|
||
・影响调查: ✅ 完成（以已确认版本）
|
||
・生成: 未开始
|
||
|
||
[恢复并继续] [开始新会话]
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 斜杠命令一览
|
||
|
||
```
|
||
/upload → 聚焦到文件上传区域
|
||
/probe → 跳转到解析结果画面
|
||
/impact → 跳转到影响调查画面
|
||
/generate → 跳到生成执行
|
||
/result → 跳转到结果画面
|
||
/history → 跳转到历史会话页
|
||
/settings → 跳转到设置画面
|
||
/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` | |