T1-SD0102-01/2026Technology-Competition
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
lhl
2026-08-09 13:28:38 +08:00
parent 69f04ecda2
commit 1a3c829d4c
6 changed files with 376 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/web-ui-design.md
+220 -91
View File
@@ -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` |