424 lines
21 KiB
Markdown
424 lines
21 KiB
Markdown
# 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）
|
||
|
||
**会话表设计：**
|
||
|
||
```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"
|
||
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 → 显示帮助
|
||
```
|
||
|