# 训练数据管理 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[查看生成文件]
    
    style A fill:#e1f5fe
    style J fill:#c8e6c9
```

### 流程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[完成]
    
    style A fill:#e1f5fe
    style M fill:#c8e6c9
```

## 响应式设计考虑

### 桌面端（推荐）
- 最小宽度：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应用的最佳实践，支持响应式布局和渐进式功能增强，能够满足不同用户群体的使用需求。 