# 训练数据管理 WebUI 设计文档 ## 概述 本文档描述训练数据管理系统的Web用户界面设计方案，旨在为用户提供简洁易用的训练数据集创建、执行和管理功能。整个系统围绕四个核心步骤展开：DDL/MD生成、Question-SQL生成、SQL验证和训练数据加载。 ## 系统设计原则 ### UI设计原则 - **简洁优先**：界面元素精简，减少用户认知负担 - **流程引导**：清晰的步骤指示和进度反馈 - **状态可视**：实时显示任务执行状态和结果 - **操作便捷**：支持快速创建和一键执行 ### 技术原则 - **API驱动**：所有操作基于REST API实现 - **异步处理**：长时间任务采用轮询方式获取状态 - **错误友好**：清晰的错误提示和恢复指导 ## 页面架构设计 ### 整体布局 ``` ┌─────────────────────────────────────────┐ │ 导航栏 │ ├─────────────────────────────────────────┤ │ │ │ 主要内容区 │ │ │ └─────────────────────────────────────────┘ ``` ### 页面结构 - **主页面**：任务创建和列表管理 - **任务详情页**：执行控制和状态监控 - **文件管理页**：查看和下载生成文件 - **日志查看页**：执行日志和错误诊断 ## 核心页面设计 ### 1. 主页面 - 任务管理 #### 功能概述 - 创建新的训练数据任务 - 查看历史任务列表 - 任务状态一览和快速操作 #### 页面布局设计 ```mermaid graph TD A[页面标题: 训练数据管理] --> B[创建任务区域] B --> C[任务列表区域] B --> B1[任务名称输入框] B --> B2[数据库连接配置] B --> B3[业务上下文输入] B --> B4[创建任务按钮] C --> C1[搜索和过滤] C --> C2[任务列表表格] C --> C3[批量操作按钮 - 管理员] C2 --> C2a[任务ID] C2 --> C2b[任务名称] C2 --> C2c[状态] C2 --> C2d[创建时间] C2 --> C2e[操作按钮] ``` #### 控件详细设计 **创建任务表单** - **任务名称**：单行文本输入框，必填，默认"训练数据任务_[时间戳]" - **数据库连接**：单行文本输入框，必填，占位符显示连接串格式 - **业务上下文**：多行文本输入框，必填，描述业务场景用于LLM理解 - **创建按钮**：主要按钮，触发任务创建API **任务列表表格** - **任务ID**：链接，点击进入任务详情页 - **任务名称**：普通文本 - **状态标签**： - 待处理 (pending) - 灰色 - 执行中 (in_progress) - 蓝色 - 已完成 (completed) - 绿色 - 失败 (failed) - 红色 - **创建时间**：格式化显示 - **操作**： - 查看详情（按钮） - 删除（按钮，管理员） #### API集成点 - `POST /api/v0/data_pipeline/tasks` - 创建任务 - `GET /api/v0/data_pipeline/tasks` - 获取任务列表 - `DELETE /api/v0/data_pipeline/tasks` - 删除任务（管理员） ### 2. 任务详情页 - 执行控制 #### 功能概述 - 提供表名列表（在线输入或文件上传） - 选择执行模式（完整/分步） - 监控任务执行状态 - 管理生成的文件 #### 页面布局设计 ```mermaid graph TD A[返回列表 + 任务标题] --> B[任务信息卡片] A --> C[表名配置区域] A --> D[执行控制区域] A --> E[状态监控区域] A --> F[快速导航] C --> C1[表名输入方式选择] C --> C2[在线输入文本域] C --> C3[文件上传组件] C --> C4[表名预览] D --> D1[执行模式选择] D --> D2[开始执行按钮] D --> D3[步骤执行按钮组] E --> E1[整体进度条] E --> E2[步骤状态卡片] E --> E3[当前步骤详情] F --> F1[查看文件按钮] F --> F2[查看日志按钮] ``` #### 控件详细设计 **任务信息卡片** - 任务ID、名称、创建时间 - 数据库连接信息 - 业务上下文描述 **表名配置区域** - **方式选择**：单选按钮组（在线输入/文件上传） - **在线输入**：多行文本域，支持逗号分隔的表名 - **文件上传**：拖拽上传组件，支持.txt文件 - **表名预览**：只读列表，显示解析后的表名 **执行控制区域** - **模式选择**：单选按钮组 - 完整执行：一次性执行四个步骤 - 分步执行：手动控制每个步骤 - **执行按钮**： - 完整模式：单个"开始执行"按钮 - 分步模式：四个步骤按钮（根据依赖关系启用/禁用） **状态监控区域** - **整体进度条**：显示总体完成百分比 - **步骤卡片**：四个卡片，每个显示： - 步骤名称和描述 - 状态图标和文字 - 执行时间 - 错误信息（如有） #### API集成点 - `POST /api/v0/data_pipeline/tasks/{task_id}/table-list` - 提交表名 - `POST /api/v0/data_pipeline/tasks/{task_id}/upload-table-list` - 上传表名文件 - `POST /api/v0/data_pipeline/tasks/{task_id}/execute` - 执行任务 - `GET /api/v0/data_pipeline/tasks/{task_id}` - 获取任务状态（轮询） ### 3. 文件管理页 - 结果查看 #### 功能概述 - 查看任务生成的所有文件 - 下载特定文件 - 上传修改后的文件（管理员） #### 页面布局设计 ```mermaid graph TD A[文件管理标题] --> B[文件概览] A --> C[文件列表] A --> D[上传区域 - 管理员] B --> B1[总文件数] B --> B2[总大小] B --> B3[目录状态] C --> C1[文件表格] C1 --> C1a[文件名] C1 --> C1b[类型] C1 --> C1c[大小] C1 --> C1d[修改时间] C1 --> C1e[操作] D --> D1[拖拽上传组件] D --> D2[覆盖模式选择] ``` #### 控件详细设计 **文件列表表格** - **文件名**：按类型分组显示，支持搜索 - **文件类型**：图标+标签显示（DDL/MD/JSON/LOG等） - **文件大小**：人性化格式显示 - **修改时间**：相对时间+绝对时间 - **操作**：下载按钮 **文件分类显示** - DDL文件：建表语句文件 - MD文档：表结构说明文档 - JSON数据：问答对训练数据 - 日志文件：执行日志和验证报告 #### API集成点 - `GET /api/v0/data_pipeline/tasks/{task_id}/files` - 获取文件列表 - `GET /api/v0/data_pipeline/tasks/{task_id}/files/{file_name}` - 下载文件 - `POST /api/v0/data_pipeline/tasks/{task_id}/files` - 上传文件（管理员） ### 4. 日志查看页 - 执行监控 #### 功能概述 - 实时查看任务执行日志 - 按日志级别过滤 - 错误诊断和排查 #### 页面布局设计 ```mermaid graph TD A[日志查看标题] --> B[过滤控制] A --> C[日志显示区域] A --> D[底部操作] B --> B1[日志级别选择] B --> B2[时间范围选择] B --> B3[关键词搜索] B --> B4[刷新按钮] C --> C1[日志列表] C1 --> C1a[时间戳] C1 --> C1b[级别标签] C1 --> C1c[日志内容] D --> D1[导出日志按钮] D --> D2[清空显示按钮] ``` #### 控件详细设计 **过滤控制栏** - **日志级别**：多选复选框（INFO/WARNING/ERROR） - **时间范围**：快捷选择按钮（最近1小时/今天/全部） - **关键词搜索**：实时搜索输入框 - **自动刷新**：开关按钮，控制是否自动轮询 **日志显示区域** - **虚拟滚动**：支持大量日志的高性能显示 - **级别标识**：不同颜色的标签 - **时间格式**：显示相对时间，hover显示绝对时间 - **内容格式**：支持换行和长文本折叠 #### API集成点 - `GET /api/v0/data_pipeline/tasks/{task_id}/logs` - 获取日志（支持分页和过滤） ## 用户操作流程设计 ### 流程1：快速创建训练数据（推荐） ```mermaid flowchart TD A[打开主页面] --> B[填写任务信息] B --> C[点击创建任务] C --> D[进入任务详情页] D --> E[选择在线输入表名] E --> F[输入表名列表] F --> G[选择完整执行模式] G --> H[点击开始执行] H --> I[等待执行完成] I --> J[查看生成文件] ``` ### 流程2：分步控制执行（高级用户） ```mermaid flowchart TD A[创建任务并配置表名] --> B[选择分步执行模式] B --> C[执行DDL生成] C --> D[查看DDL文件] D --> E{结果满意?} E -->|是| F[执行QA生成] E -->|否| G[重新执行DDL生成] G --> D F --> H[查看QA文件] H --> I{结果满意?} I -->|是| J[执行SQL验证] I -->|否| K[重新执行QA生成] K --> H J --> L[执行训练加载] L --> M[完成] ``` ## 响应式设计考虑 ### 桌面端（推荐） - 最小宽度：1200px - 多列布局，充分利用屏幕空间 - 表格支持水平滚动 ### 平板端 - 适配768px-1199px宽度 - 自适应列布局 - 表格优化显示 ### 手机端（基础支持） - 单列布局 - 卡片式展示替代表格 - 简化操作流程 ## 状态管理设计 ### 页面状态 - **任务创建状态**：表单验证、提交状态 - **执行状态**：各步骤的执行状态和进度 - **文件状态**：文件列表、上传状态 - **日志状态**：过滤条件、自动刷新状态 ### 数据轮询策略 - **任务状态**：每5秒轮询一次 - **日志数据**：自动刷新时每3秒轮询 - **文件列表**：步骤完成后自动刷新 ## 错误处理设计 ### 用户友好的错误提示 - **网络错误**：显示重试按钮 - **权限错误**：显示联系管理员提示 - **数据错误**：显示具体错误信息和修正建议 - **系统错误**：显示错误ID便于技术支持 ### 错误恢复机制 - **自动重试**：网络临时故障自动重试 - **手动重试**：提供重试按钮 - **状态回滚**：失败后恢复到上一个稳定状态 ## 性能优化建议 ### 前端优化 - **懒加载**：文件列表和日志按需加载 - **虚拟滚动**：处理大量日志数据 - **缓存策略**：任务列表和状态信息适度缓存 - **防抖处理**：搜索和过滤操作防抖 ### 用户体验优化 - **加载状态**：所有异步操作显示加载指示器 - **进度反馈**：长时间操作显示进度条 - **操作确认**：危险操作需要用户确认 - **快捷键支持**：常用操作支持键盘快捷键 ## 技术实现建议 ### 前端技术栈 - **框架**：React/Vue.js 等现代前端框架 - **状态管理**：Redux/Vuex 管理复杂状态 - **UI组件库**：Ant Design/Element UI 快速开发 - **HTTP客户端**：Axios 处理API调用 ### 关键技术点 - **WebSocket**：考虑用于实时状态推送（可选） - **文件上传**：支持拖拽和进度显示 - **表格组件**：支持排序、过滤、分页 - **代码高亮**：SQL和JSON内容语法高亮 ## 管理员功能说明 以下功能仅限管理员使用，需在相应UI元素上添加"管理员"标识： ### 主页面管理功能 - **批量删除任务**：选择多个任务进行批量删除 - **任务状态管理**：强制修改任务状态（高级） ### 文件管理功能 - **文件上传**：上传修改后的训练数据文件 - **文件删除**：删除指定文件（危险操作） ### 系统管理功能 - **清理旧任务**：自动清理30天前的任务目录 - **系统状态监控**：查看系统资源使用情况 ## 总结 本设计文档提供了训练数据管理WebUI的完整设计方案，重点关注用户体验和API集成。通过简洁的界面设计、清晰的操作流程和完善的错误处理，用户可以轻松完成训练数据集的创建、执行和管理工作。 设计遵循现代Web应用的最佳实践，支持响应式布局和渐进式功能增强，能够满足不同用户群体的使用需求。