# 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 → 显示帮助 ```