Training Data 文件管理系统 API 设计方案

📋 项目概述

设计目标

为 data_pipeline/training_data/ 目录设计一套完整的文件管理API系统，提供目录浏览、文件操作、安全管理等功能。

应用场景

开发调试: 查看和管理训练数据文件
数据维护: 上传、删除、下载训练文件
目录管理: 浏览项目目录结构
文件监控: 跟踪文件变化和使用情况

设计原则

✅ 安全性: 严格限制在training_data目录范围内
✅ 简洁性: RESTful API设计，易于理解和使用
✅ 完整性: 覆盖文件管理的基本需求
✅ 兼容性: 与现有data_pipeline系统无缝集成

🎯 功能需求分析

1. 目录遍历功能

需求	描述	优先级
递归遍历	支持整个training_data目录的递归遍历	🟢 高
层级控制	可指定遍历深度，避免性能问题	🟡 中
筛选功能	按文件类型、大小、时间等条件筛选	🟡 中
排序功能	按名称、时间、大小等排序	🟡 中

2. 文件列表功能

需求	描述	优先级
基本信息	文件名、大小、类型、修改时间等	🟢 高
详细属性	权限、创建时间、文件哈希等	🟡 中
分页支持	大目录的分页展示	🟡 中
搜索功能	按文件名模糊搜索	🟡 中

3. 文件下载功能

需求	描述	优先级
单文件下载	支持各种文件类型下载	🟢 高
流式下载	大文件的流式传输	🟡 中
批量下载	多文件打包下载	🔴 低
断点续传	大文件下载中断恢复	🔴 低

4. 文件删除功能

需求	描述	优先级
单文件删除	删除指定文件	🟢 高
批量删除	删除多个文件	🟡 中
安全确认	删除前的确认机制	🟢 高
回收站	软删除，可恢复	🔴 低

5. 文件上传功能

需求	描述	优先级
单文件上传	支持各种文件类型上传	🟢 高
同名覆盖	自动覆盖同名文件	🟢 高
分片上传	大文件分片上传	🟡 中
进度跟踪	上传进度实时反馈	🟡 中

🏗️ API 设计方案

API 基础信息

基础路径: /api/v0/training_data/files 认证方式: 继承现有系统认证 响应格式: JSON 错误处理: 标准HTTP状态码 + 详细错误信息

1. 目录遍历 API

1.1 获取目录树结构

GET /api/v0/training_data/files/tree

查询参数:

max_depth: 最大遍历深度 (默认: 3)
include_files: 是否包含文件 (默认: true)
file_types: 筛选文件类型 (如: ddl,md,json)

响应示例:

{
  "success": true,
  "data": {
    "directory": "training_data",
    "path": "./data_pipeline/training_data",
    "children": [
      {
        "name": "vector_bak",
        "type": "directory",
        "path": "./data_pipeline/training_data/vector_bak",
        "file_count": 4,
        "size": "1.6MB",
        "children": [
          {
            "name": "langchain_pg_collection_20250722_132518.csv",
            "type": "file",
            "path": "./data_pipeline/training_data/vector_bak/langchain_pg_collection_20250722_132518.csv",
            "size": "209B",
            "modified_at": "2025-07-22T13:25:18Z",
            "file_type": "csv"
          }
        ]
      }
    ]
  },
  "meta": {
    "total_directories": 15,
    "total_files": 89,
    "total_size": "25.4MB",
    "scan_time": "0.234s"
  }
}

1.2 获取指定目录内容

GET /api/v0/training_data/files/list

查询参数:

path: 相对路径 (默认: ".")
page: 页码 (默认: 1)
page_size: 每页大小 (默认: 50)
sort_by: 排序字段 (name|size|modified_at)
sort_order: 排序方向 (asc|desc)
search: 文件名搜索关键词

响应示例:

{
  "success": true,
  "data": {
    "current_path": "./data_pipeline/training_data/task_20250721_213627",
    "items": [
      {
        "name": "bss_business_day_data.ddl",
        "type": "file",
        "size": 1024,
        "size_formatted": "1.0 KB",
        "modified_at": "2025-07-21T21:36:27Z",
        "created_at": "2025-07-21T21:36:27Z",
        "file_type": "ddl",
        "permissions": "rw-r--r--"
      },
      {
        "name": "vector_bak",
        "type": "directory", 
        "size": 819200,
        "size_formatted": "800 KB",
        "modified_at": "2025-07-22T01:03:18Z",
        "file_count": 4
      }
    ]
  },
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total": 25,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

2. 文件下载 API

2.1 下载单个文件

GET /api/v0/training_data/files/download

查询参数:

path: 文件相对路径 (必需)
inline: 是否内联显示 (默认: false)

响应: 文件流 Headers:

Content-Type: 根据文件类型自动设置
Content-Disposition: attachment; filename="文件名"
Content-Length: 文件大小

2.2 预览文件内容 (文本文件)

GET /api/v0/training_data/files/preview

查询参数:

path: 文件相对路径 (必需)
lines: 预览行数 (默认: 100)
encoding: 文件编码 (默认: utf-8)

响应示例:

{
  "success": true,
  "data": {
    "file_path": "./data_pipeline/training_data/task_xxx/metadata.txt",
    "file_size": 2048,
    "content_preview": "业务日数据表...",
    "total_lines": 45,
    "preview_lines": 100,
    "encoding": "utf-8",
    "is_text_file": true
  }
}

3. 文件删除 API

3.1 删除单个文件

DELETE /api/v0/training_data/files/delete

请求体:

{
  "path": "./data_pipeline/training_data/task_xxx/old_file.json",
  "confirm": true
}

响应示例:

{
  "success": true,
  "message": "文件删除成功",
  "data": {
    "deleted_file": {
      "path": "./data_pipeline/training_data/task_xxx/old_file.json",
      "name": "old_file.json",
      "size": 1024,
      "deleted_at": "2025-07-22T15:30:00Z"
    }
  }
}

3.2 批量删除文件

POST /api/v0/training_data/files/batch_delete

请求体:

{
  "paths": [
    "./data_pipeline/training_data/task_xxx/file1.json",
    "./data_pipeline/training_data/task_xxx/file2.ddl"
  ],
  "confirm": true
}

响应示例:

{
  "success": true,
  "data": {
    "deleted_files": [
      {
        "path": "./data_pipeline/training_data/task_xxx/file1.json",
        "success": true
      }
    ],
    "failed_files": [
      {
        "path": "./data_pipeline/training_data/task_xxx/file2.ddl", 
        "success": false,
        "error": "文件不存在"
      }
    ],
    "summary": {
      "total": 2,
      "success": 1,
      "failed": 1
    }
  }
}

4. 文件上传 API

4.1 上传单个文件

POST /api/v0/training_data/files/upload

请求: multipart/form-data

file: 文件数据 (必需)
path: 目标目录相对路径 (默认: ".")
filename: 自定义文件名 (可选)
overwrite: 是否覆盖同名文件 (默认: true)

响应示例:

{
  "success": true,
  "message": "文件上传成功",
  "data": {
    "uploaded_file": {
      "original_name": "table_list.txt",
      "saved_name": "table_list.txt", 
      "path": "./data_pipeline/training_data/task_xxx/table_list.txt",
      "size": 256,
      "size_formatted": "256 B",
      "uploaded_at": "2025-07-22T15:45:00Z",
      "file_type": "text",
      "overwrite_occurred": true
    },
    "backup_info": {
      "backup_created": true,
      "backup_path": "./data_pipeline/training_data/task_xxx/table_list.txt.bak1",
      "backup_created_at": "2025-07-22T15:45:00Z"
    }
  }
}

4.2 批量上传文件

POST /api/v0/training_data/files/batch_upload

请求: multipart/form-data

files[]: 多个文件 (必需)
path: 目标目录相对路径 (默认: ".")
overwrite: 是否覆盖同名文件 (默认: true)

5. 文件管理 API

5.1 获取目录统计信息

GET /api/v0/training_data/files/stats

查询参数:

path: 目录相对路径 (默认: ".")
recursive: 是否递归统计 (默认: true)

响应示例:

{
  "success": true,
  "data": {
    "directory_stats": {
      "path": "./data_pipeline/training_data",
      "total_directories": 12,
      "total_files": 87,
      "total_size": 26542080,
      "total_size_formatted": "25.3 MB",
      "file_type_breakdown": {
        "ddl": {"count": 18, "size": 45120},
        "md": {"count": 18, "size": 234560}, 
        "json": {"count": 15, "size": 1024000},
        "csv": {"count": 8, "size": 25000000},
        "txt": {"count": 12, "size": 15360},
        "log": {"count": 16, "size": 223040}
      },
      "largest_files": [
        {
          "name": "langchain_pg_embedding_20250722_132518.csv",
          "path": "./data_pipeline/training_data/vector_bak/langchain_pg_embedding_20250722_132518.csv",
          "size": 838860,
          "size_formatted": "819 KB"
        }
      ]
    }
  }
}

5.2 搜索文件

GET /api/v0/training_data/files/search

查询参数:

query: 搜索关键词 (必需)
file_types: 文件类型筛选 (可选)
max_results: 最大结果数 (默认: 50)
search_type: 搜索类型 (name|content) (默认: name)

响应示例:

{
  "success": true,
  "data": {
    "search_query": "business_day",
    "search_type": "name",
    "results": [
      {
        "name": "bss_business_day_data.ddl",
        "path": "./data_pipeline/training_data/task_20250721_213627/bss_business_day_data.ddl",
        "size": 1024,
        "modified_at": "2025-07-21T21:36:27Z",
        "file_type": "ddl",
        "match_score": 0.95
      }
    ],
    "summary": {
      "total_results": 3,
      "search_time": "0.045s"
    }
  }
}

🔒 安全设计

路径安全策略

1. 路径验证

def validate_path(relative_path: str) -> bool:
    """验证路径安全性"""
    # 1. 禁止绝对路径
    if os.path.isabs(relative_path):
        return False
    
    # 2. 禁止路径遍历
    if '..' in relative_path:
        return False
    
    # 3. 解析后验证在允许范围内
    full_path = os.path.join(TRAINING_DATA_ROOT, relative_path)
    real_path = os.path.realpath(full_path)
    return real_path.startswith(os.path.realpath(TRAINING_DATA_ROOT))

2. 文件类型限制

允许的文件类型: .ddl, .sql, .md, .json, .txt, .csv, .log
禁止的文件类型: .exe, .bat, .sh, .py (可执行文件)
大小限制: 单文件最大 100MB

3. 操作权限控制

操作	权限要求	说明
目录浏览	只读	所有用户
文件下载	只读	所有用户
文件上传	读写	需要认证
文件删除	读写	需要认证 + 确认

错误处理策略

标准错误响应格式

{
  "success": false,
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "指定的文件不存在",
    "details": {
      "path": "./data_pipeline/training_data/nonexistent.txt",
      "timestamp": "2025-07-22T15:30:00Z"
    }
  }
}

错误代码定义

错误代码	HTTP状态	说明
`INVALID_PATH`	400	路径格式错误或不安全
`FILE_NOT_FOUND`	404	文件不存在
`DIRECTORY_NOT_FOUND`	404	目录不存在
`PERMISSION_DENIED`	403	权限不足
`FILE_TOO_LARGE`	413	文件超过大小限制
`UNSUPPORTED_FILE_TYPE`	415	不支持的文件类型
`DISK_SPACE_FULL`	507	磁盘空间不足

🚀 实施方案

阶段1: 核心功能实现 (1-2周)

✅ 基础文件管理器类
✅ 目录遍历API
✅ 文件列表API
✅ 文件下载API
✅ 基础安全验证

阶段2: 上传和删除功能 (1周)

✅ 单文件上传API
✅ 单文件删除API
✅ 文件覆盖策略
✅ 错误处理完善

阶段3: 高级功能 (1周)

✅ 批量操作API
✅ 文件搜索功能
✅ 统计信息API
✅ 文件预览功能

阶段4: 优化和完善 (1周)

✅ 性能优化
✅ 缓存策略
✅ 日志记录
✅ 监控告警

📊 技术架构

系统架构图

┌─────────────────────────────────────────────────────────────┐
│                    Training Data File Management API        │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────┐ │
│  │   目录API   │  │   文件API   │  │   上传API   │  │ 统计 │ │
│  │  tree/list  │  │download/del │  │upload/batch │  │ API  │ │
│  └─────────────┘  └─────────────┘  └─────────────┘  └──────┘ │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐ │
│  │           TrainingDataFileManager (核心管理器)            │ │
│  │  • 路径安全验证  • 文件操作封装  • 错误处理  • 日志记录   │ │
│  └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
│  │   路径管理   │  │   文件操作   │  │      安全策略       │ │
│  │ • 路径解析   │  │ • 读写操作   │  │ • 权限验证          │ │
│  │ • 安全检查   │  │ • 元数据     │  │ • 类型检查          │ │
│  │ • 目录遍历   │  │ • 流式处理   │  │ • 大小限制          │ │
│  └──────────────┘  └──────────────┘  └─────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                    现有 data_pipeline 基础设施               │
│           • unified_api.py 路由  • 日志系统  • 配置管理     │
└─────────────────────────────────────────────────────────────┘

核心类设计

TrainingDataFileManager

class TrainingDataFileManager:
    """Training Data 文件管理器"""
    
    def __init__(self, base_path: str = "data_pipeline/training_data"):
        self.base_path = Path(base_path)
        self.logger = get_logger("TrainingDataFileManager")
    
    # 核心方法
    def get_directory_tree(self, max_depth: int = 3) -> Dict
    def list_directory_contents(self, path: str, **kwargs) -> Dict
    def download_file(self, path: str) -> FileResponse
    def upload_file(self, file_data, target_path: str) -> Dict
    def delete_file(self, path: str) -> Dict
    def get_file_stats(self, path: str) -> Dict
    def search_files(self, query: str, **kwargs) -> Dict
    
    # 安全验证
    def validate_path(self, path: str) -> bool
    def check_file_type(self, filename: str) -> bool
    def check_file_size(self, size: int) -> bool

配置管理

新增配置项

# data_pipeline/config.py
TRAINING_DATA_FILE_MANAGEMENT = {
    "enabled": True,
    "max_file_size": 100 * 1024 * 1024,  # 100MB
    "allowed_extensions": [".ddl", ".sql", ".md", ".json", ".txt", ".csv", ".log"],
    "max_tree_depth": 5,
    "max_search_results": 100,
    "cache_enabled": True,
    "cache_ttl": 300,  # 5分钟
    "upload_chunk_size": 1024 * 1024,  # 1MB
}

🔧 使用示例

前端集成示例

JavaScript调用示例

// 获取目录树
const getDirectoryTree = async () => {
    const response = await fetch('/api/v0/training_data/files/tree?max_depth=3');
    const data = await response.json();
    return data;
};

// 上传文件
const uploadFile = async (file, targetPath = '.') => {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('path', targetPath);
    formData.append('overwrite', 'true');
    
    const response = await fetch('/api/v0/training_data/files/upload', {
        method: 'POST',
        body: formData
    });
    return await response.json();
};

// 删除文件
const deleteFile = async (filePath) => {
    const response = await fetch('/api/v0/training_data/files/delete', {
        method: 'DELETE',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ path: filePath, confirm: true })
    });
    return await response.json();
};

命令行工具示例

cURL命令示例

# 获取目录列表
curl "http://localhost:8084/api/v0/training_data/files/list?path=task_20250721_213627"

# 下载文件
curl -O "http://localhost:8084/api/v0/training_data/files/download?path=task_xxx/metadata.txt"

# 上传文件
curl -X POST -F "file=@local_file.txt" -F "path=task_xxx" \
     "http://localhost:8084/api/v0/training_data/files/upload"

# 删除文件
curl -X DELETE -H "Content-Type: application/json" \
     -d '{"path":"task_xxx/old_file.json","confirm":true}' \
     "http://localhost:8084/api/v0/training_data/files/delete"

# 搜索文件
curl "http://localhost:8084/api/v0/training_data/files/search?query=business&file_types=ddl,md"

📝 总结

这个文件管理系统API设计方案提供了：

✅ 核心功能

完整的CRUD操作: 创建、读取、更新、删除文件
目录管理: 递归遍历、层级展示、统计信息
安全保障: 路径验证、权限控制、类型限制
用户友好: RESTful设计、详细响应、错误处理

✅ 技术特色

高性能: 流式处理、分页支持、缓存策略
高可靠: 详细日志、错误恢复、操作确认
易集成: 标准HTTP接口、JSON格式、现有架构兼容
易扩展: 模块化设计、配置驱动、插件机制

✅ 实施价值

提升效率: 简化文件管理操作
降低风险: 严格的安全控制机制
改善体验: 直观的API设计和响应格式
便于维护: 清晰的架构和完善的文档

这个设计方案可以作为后续开发的详细指导，确保实现一个功能完整、安全可靠、易于使用的文件管理系统。

文档版本: v1.0
创建日期: 2025-07-22
作者: AI Assistant
审核状态: 待审核

training_data_file_management_api_design.md 20 KB 永久連結 文件歷史 原始文件

Training Data 文件管理系统 API 设计方案

📋 项目概述

设计目标

应用场景

设计原则

🎯 功能需求分析

1. 目录遍历功能

2. 文件列表功能

3. 文件下载功能

4. 文件删除功能

5. 文件上传功能

🏗️ API 设计方案

API 基础信息

1. 目录遍历 API

1.1 获取目录树结构

1.2 获取指定目录内容

2. 文件下载 API

2.1 下载单个文件

2.2 预览文件内容 (文本文件)

3. 文件删除 API

3.1 删除单个文件

3.2 批量删除文件

4. 文件上传 API

4.1 上传单个文件

4.2 批量上传文件

5. 文件管理 API

5.1 获取目录统计信息

5.2 搜索文件

🔒 安全设计

路径安全策略

1. 路径验证

2. 文件类型限制

3. 操作权限控制

错误处理策略

标准错误响应格式

错误代码定义

🚀 实施方案

阶段1: 核心功能实现 (1-2周)

阶段2: 上传和删除功能 (1周)

阶段3: 高级功能 (1周)

阶段4: 优化和完善 (1周)

📊 技术架构

系统架构图

核心类设计

TrainingDataFileManager

配置管理

新增配置项

🔧 使用示例

前端集成示例

JavaScript调用示例

命令行工具示例

cURL命令示例

📝 总结

✅ 核心功能

✅ 技术特色

✅ 实施价值

training_data_file_management_api_design.md 20 KB

永久連結文件歷史原始文件