21 KiB
21 KiB
Web UI 设计文档
版本: v1.0 | 日期: 2026-07-21 | 状态: 初版
1. 概述
概要设计书自动生成 Agent 的 Web UI 是用户与系统交互的唯一界面，承担以下功能：
- 文件上传（要件定义、模板、规则文档、现系统文件）
- 各步骤的确认与修正（解析结果、影响调查结果、生成结果）
- 生成进度实时展示
- 最终设计书的预览与下载
- 规则手册管理（更新、版本查看）
- 多用户支持（数据隔离）
2. 页面结构
2.1 全局布局
┌─────────────────────────────────────────────────────────────┐
│ Genesis [上传] [解析] [影响调查] [生成] [结果] [设置] │ ← 顶部导航
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─ 对话区域 ──────────────────────────────────────────┐ │
│ │ 🤖 你好。请上传要件定义的Excel │ │
│ │ 🧑 [拖放文件] │ │
│ │ 🤖 解析完成！请确认以下Sheet类型 │ │
│ │ ┌────────┬──────────┬───────────┐ │ │
│ │ │ Sheet名 │ 判定结果 │ 修正 │ │ │
│ │ ├────────┼──────────┼───────────┤ │ │
│ │ │ 功能一览 │ ✅ FUNCTION │ │ │ │
│ │ │ 画面一览 │ ❌ 未判定 │ [修正▼] │ │ │
│ │ └────────┴──────────┴───────────┘ │ │
│ │ [确认并继续] │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 组件区域 ──────────────────────────────────────────┐ │
│ │ (根据当前步骤切换) │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ 状态: [📤已上传] [✅完成] [⏳进行中] [⏸未开始] │ ← 底部状态栏
└─────────────────────────────────────────────────────────────┘
2.2 导航步骤
① 上传 → ② 解析确认 → ③ 影响调查确认 → ④ 生成执行 → ⑤ 结果预览
(文件选择) (Sheet判定等) (关联・不确定处) (进度显示) (设计书浏览/下载)
- 每步骤有"确认"按钮，确认后进入下一步
- 可通过左侧导航跳转到任意已完成的步骤（支持回退）
- 当前步骤高亮显示
3. 各页面详细设计
3.1 页面1: 文件上传
┌─────────────────────────────────────────────┐
│ 1. 上传文件 │
├─────────────────────────────────────────────┤
│ │
│ 📁 要件定义 (必须) │
│ ┌─────────────────────────────────────┐ │
│ │ .xlsx, .xls, .docx, .pptx 拖放即可 │ │
│ │ 或 [选择文件] │ │
│ └─────────────────────────────────────┘ │
│ ⚠ 要件定义推荐使用Excel │
│ │
│ 📁 设计书模板 (必须) │
│ ┌─────────────────────────────────────┐ │
│ │ .docx (Word) │ │
│ └─────────────────────────────────────┘ │
│ │
│ 📁 记录规则文档 (推荐) │
│ ┌─────────────────────────────────────┐ │
│ │ .docx / .xlsx / .pptx (可多个) │ │
│ └─────────────────────────────────────┘ │
│ │
│ 📁 图表规则 (推荐) │
│ ┌─────────────────────────────────────┐ │
│ │ .docx / .xlsx / .pptx │ │
│ └─────────────────────────────────────┘ │
│ │
│ 📁 现有系统文件 (任意, 追加/改修场景使用) │
│ ┌─────────────────────────────────────┐ │
│ │ .java/.xml/.yml 源代码 或 │ │
│ │ 既有设计书 (.docx/.xlsx) │ │
│ └─────────────────────────────────────┘ │
│ │
│ [更新规则] ← 规则手册再构建按钮 │
│ │
│ [上传完成 → 进入解析] │
└─────────────────────────────────────────────┘
上传规则：
- 要件定义文件至少一个
- 模板文件必须是一个 .docx
- 规则文档可多个，也可零个（规则手册已存在时）
- 现系统文件仅在追加/改修场景时需要
- 文件大小限制：最大100MB
- 支持拖拽上传、点击上传、取消上传
斜杠命令： /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 自动，但用户可以点击"修正"手动更改
- 章节构成由模板自动解析，但用户可以追加/删除章节
- 现有系统信息仅在追加/改修场景显示
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）
- 仅高亮关注未确定项目
- 各关联的追加/删除/种类变更/证据修正是个别交互
- 修正履历显示在画面底部
3.4 页面4: 生成执行
┌─────────────────────────────────────────────┐
│ 4. 概要设计书生成中... │
├─────────────────────────────────────────────┤
│ │
│ 进度: │
│ │
│ ✅ 功能一览 - 完成 (23秒) │
│ ✅ 画面一览 - 完成 (18秒) │
│ ⠋ DB设计 - 生成中... │
│ ⬜ 账票一览 - 等待 │
│ ⬜ IF定义 - 等待 │
│ ⬜ 非功能要件 - 等待 │
│ │
│ 已过时间: 41秒 / 预计时间: ~3分 │
│ │
│ ────────────────────────────────────── │
│ DB设计章 生成中: │
│ 关联要素: F001, F003, TB001, TB002 │
│ 适用规则: 写入规则_v3 │
│ │
│ ────────────────────────────────────── │
│ │
│ [中途中断] [查看日志] │
└─────────────────────────────────────────────┘
交互说明：
- 用户可保持此画面打开同时进行其他工作
- 生成完成时通过浏览器通知（或 WebSocket 推送）告知
- 选择中断时，已完成的章节保留，其余作为未完成保存
- 中断后恢复时，从已完成的章节继续生成
3.5 页面5: 结果预览与下载
┌─────────────────────────────────────────────┐
│ 5. 生成完成 │
├─────────────────────────────────────────────┤
│ │
│ ┌─ QA报告 ──────────────────────────┐ │
│ │ ✅ 全部10项检查通过 │ │
│ │ 内容准确性: 通过 │ │
│ │ 关联一致性: 通过 │ │
│ │ 规则遵守度: 警告 1件 │ │
│ │ → 「功能概要应包含影响范围」 │ │
│ └────────────────────────────────────────┘ │
│ │
│ ┌─ 预览 ──────────────────────────┐ │
│ │ (docx → HTML → 浏览器内渲染) │ │
│ │ 1. 目的 │ │
│ │ 本系统是... │ │
│ │ │ │
│ │ 2. 功能一览 │ │
│ │ ┌──────┬────────┬───────┐ │ │
│ │ │功能ID │ 功能名 │ 概要 │ │ │
│ │ ├──────┼────────┼───────┤ │ │
│ │ │F001 │用户 │... │ │ │
│ │ └──────┴────────┴───────┘ │ │
│ │ ... │ │
│ └────────────────────────────────────────┘ │
│ │
│ ┌─ 下载区域 ──────────────────────────┐ │
│ │ 📥 下载设计书 (.docx) │ │
│ │ 📥 下载QA报告 (.json) │ │
│ │ 📥 下载影响调查书 (.json) │ │
│ └────────────────────────────────────────┘ │
│ │
│ [修正后重新生成] [进行新生成] │
└─────────────────────────────────────────────┘
4. 技术设计
4.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
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"
current_step TEXT,
metadata JSON -- 会话的摘要
);
-- 中间成果物的快照
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, -- 修正时的版本管理
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" | "rules" | "existing_system"
file_name 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 也容易（表定义兼容性高）
4.3 多用户
工作区:
/data/users/{user_id}/
├── uploads/ # 用户上传的文件
│ ├── session_001/
│ │ ├── requirements.xlsx
│ │ └── template.docx
│ └── session_002/
├── outputs/ # 生成的设计书
│ ├── session_001.docx
│ └── session_002.docx
└── config/
└── .env # 用户个别设置（API Key 等共享）
共享数据（所有用户通用）:
/data/shared/
├── rules-handbook/
│ ├── v1/
│ └── v2/ # 规则更新版本
└── templates/
5. 异常处理UX
5.1 生成出错时
DB设计 生成过程中发生错误
┌─────────────────────────────────────────┐
│ ⚠ DB设计章生成时发生错误 │
│ 错误详情: LLM API调用失败 │
│ 错误码: LLM_TIMEOUT │
│ │
│ [重试] [跳过并继续] [中断] │
└─────────────────────────────────────────┘
- 重试: 重新生成同一章（重试 LLM 调用）
- 跳过: 跳过此章并进入下一章
- 中断: 全部中断，保存迄今为止的已完成章节
5.2 会话恢复
浏览器关闭后再次打开时：
「要恢复上次的会话吗？」
上次的状态: Step 3 (影响调查确认)
・解析结果: ✅ 完成
・影响调查: ✅ 完成（以上述v2确认）
・Writer: 未开始
[恢复并继续] [开始新会话]
6. 斜杠命令一览
/upload → 聚焦到文件上传区域
/probe → 跳转到解析结果画面
/impact → 跳转到影响调查画面
/generate → 跳转到生成执行画面
/result → 跳转到结果画面
/settings → 跳转到设置画面
/status → 显示当前生成任务的状态
/cancel → 取消当前生成
/help → 显示帮助