# 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` |