2026Technology-Competition/docs/web-ui-design.md

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                        │
│                                             │
│  [中途中断]  [查看日志]                     │
│                                             │
│  ┌─ 规则冲突 (浮动卡片) ───────────────────┐   │
│  │  ⚠ 检测到规则冲突（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）

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）

会话表设计：

-- 主模型: 每个用户的会话
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