# 系统功能调整改造说明 ## 1. 背景说明 根据最新数据库设计，以下业务表结构已经调整： - `ai_dataset` - `ai_dataset_sample` - `ai_temp_file` - `ai_annotate_task` - `ai_annotate_task_sample` 其中： - `ai_temp_file` 为新增表 - `ai_dataset`、`ai_annotate_task`、`ai_annotate_task_sample` 发生了表名和字段调整 - `ai_dataset_sample` 发生了字段调整 当前后端代码仍然主要基于旧模型、旧表名和本地文件系统目录进行数据集、样本、标注任务和训练样本处理，尚未与新的 `table.sql` 以及 MinIO 主存储模式完全对齐。因此需要先完成系统功能和代码结构层面的改造设计，再实施模型、接口和业务流程改造。 本说明文档用于梳理： - 新旧表结构差异 - 现有代码现状 - 目标业务逻辑 - 需要调整的模块、接口和流程 - 推荐的实施顺序 --- ## 2. 调整目标 本次改造的核心目标如下： 1. 以 `backend/config/settings/table.sql` 为准，统一后端模型与数据库表结构 2. 引入 `ai_temp_file` 作为临时文件中转表，承接 ZIP、视频、图片、音频等原始文件上传 3. 将上传文件统一存入 MinIO，对象存储成为主文件存储后端 4. `ai_dataset` 只负责数据集主记录管理 5. `ai_dataset_sample` 负责数据集样本记录，支持直接上传和从 `ai_temp_file` 导入 6. 根据数据集类型自动执行 ZIP 解压、视频抽帧等导入规则 7. 保持后续标注、训练准备、模型训练流程可继续使用数据集样本 --- ## 3. 现状分析 ### 3.1 当前数据库模型与 `table.sql` 不一致 当前后端模型定义位于： - `backend/apps/core/models.py` 当前序列化器定义位于： - `backend/apps/common/serializers.py` 当前数据集和样本相关视图位于： - `backend/apps/datasets/views/dataset.py` - `backend/apps/datasets/views/dataset_sample.py` - `backend/apps/datasets/views/annotate_task.py` - `backend/apps/datasets/views/annotate_task_sample.py` 当前 MinIO 通用接口位于： - `backend/apps/common/minio_client.py` - `backend/apps/common/views/minio_storage.py` ### 3.2 当前系统仍以本地文件系统为主 目前数据集主流程依赖本地文件目录 `FILESPACE_ROOT_PATH`： - 创建数据集时创建本地目录 - 上传数据时写入本地目录 - 样本读取时从本地文件读取并转 base64 - 删除样本时直接删除本地文件 - 标注合并时在本地生成 XML/JSON 标注文件 - 训练前样本准备时从本地目录复制样本和标注文件 虽然系统已经集成 MinIO 通用文件接口，但 MinIO 目前仍是旁路能力，尚未成为数据集与训练业务的默认存储主链路。 ### 3.3 当前旧模型与新表结构的主要差异 #### 1. `ai_dataset` `table.sql` 中的目标表为 `ai_dataset`，字段包括： - `id` - `dataset_code` - `dataset_name` - `description` - `dataset_type` - `features` - `original_file_path` - `original_file_name` - `dataset_path` - `dataset_count` - `dataset_labels` - `status` - `creator` - `create_time` - `custom1` - `custom2` - `custom3` 当前代码中实际模型为： - 模型名：`AiDataset` - 表名：`ai_algorithm_dataset` 主要问题： - 表名不一致 - 当前模型多出 `algorithm_id`、`algorithm_name` - 当前业务很多地方基于 `algorithm_id` 生成 `dataset_code` 和目录路径 - 新表 `ai_dataset` 中没有 `algorithm_id` 字段，说明当前“数据集绑定算法”的逻辑需要重新定义 #### 2. `ai_dataset_sample` `table.sql` 中目标表仍为 `ai_dataset_sample`，但字段结构已变化： - `saved_filesize` 长度缩短为 `varchar(10)` - 标注字段拆分为 `rectangle` 与 `polygon` 当前代码中模型仍为： - 模型名：`AiDatasetSample` - 表名：`ai_dataset_sample` 主要问题： - 当前模型使用单一字段 `annotation_content` - 现有标注、审核、合并逻辑均围绕 `annotation_content` 展开 - 新表结构拆成 `rectangle`、`polygon` 后，需要重新设计样本标注存储格式和兼容逻辑 #### 3. `ai_temp_file` `table.sql` 中新增： - 表名：`ai_temp_file` 字段包括： - `id` - `original_path` - `original_name` - `original_type` - `bucket_name` - `object_name` - `object_size` - `content_type` - `status` - `create_time` - `custom1` - `custom2` - `custom3` 当前代码现状： - 无对应 Django 模型 - 无对应序列化器 - 无对应业务接口 - 无与数据集导入流程的集成 也就是说，`ai_temp_file` 目前仅存在于 SQL 设计中，代码层完全缺失。 #### 4. `ai_annotate_task` `table.sql` 中目标表为 `ai_annotate_task`，字段包括： - `id` - `algorithm_id` - `task_name` - `annotate_type` - `description` - `dataset_id` - `task_count` - `task_range` - `task_type` - `region_type` - `labels` - `work_type` - `task_team` - `task_leader` - `status` - `creator` - `create_time` - `custom1` - `custom2` - `custom3` 当前代码中实际模型为： - 模型名：`AiDatasetTask` - 表名：`ai_dataset_task` 主要问题： - 表名不一致 - 当前模型承载的是标注任务业务，语义上与新表一致 - 当前模型仍映射旧表 `ai_dataset_task` - 新表改为 `ai_annotate_task` - `dataset_id` 仍然保留，说明原先“单数据集标注任务”的业务处理逻辑不变 这意味着标注任务主表的核心业务逻辑可以保持不变，主要改造点是表名映射与字段对齐。 - 创建任务时继续保存单一 `dataset_id` - 分配样本时继续按所属数据集筛选样本 - 统计任务样本数时继续按单数据集汇总 #### 5. `ai_annotate_task_sample` `table.sql` 中目标表为 `ai_annotate_task_sample`，字段与当前样本任务表接近，主要变化是表名调整。 当前代码中实际模型为： - 模型名：`AiDatasetTaskSample` - 表名：`ai_dataset_task_sample` 主要问题： - 表名不一致 - 与 `ai_annotate_task` 关联的上游表名也已变化 - 现有接口、序列化器、业务逻辑均使用旧模型名和旧表名 --- ## 4. 新业务逻辑梳理 ### 4.1 `ai_temp_file` 临时文件管理 目标定位： - 作为前端上传 ZIP、视频、图片、音频等原始文件的统一入口 - 所有临时文件先上传到 MinIO 的 `tempfile` 桶 - 上传成功后，在 `ai_temp_file` 表中记录文件元数据 - 数据集导入时，优先从 `ai_temp_file` 选择文件来源 建议的文件类型分类： - `01` 图片 - `02` 视频 - `03` 音频 - `04` ZIP 压缩包 - `05` 文本 - `99` 其他 建议状态值： - `01` 已上传 - `02` 已导入数据集 - `03` 已失效 - `09` 已删除 ### 4.2 `ai_dataset` 数据集主表 目标定位： - 只记录数据集定义信息 - 包括名称、类型、标签、样本数、状态等主数据 - 不直接承担临时文件存储职责 页面能力： - 新增数据集 - 修改数据集 - 删除数据集 - 查询数据集列表 - 查看数据集详情 关键变化： - 当前代码中“创建数据集即创建本地目录”的逻辑需要改造 - 改为 MinIO 主存储，`dataset_path` 适合作为 MinIO 逻辑前缀，而不是本地磁盘目录 ### 4.3 `ai_dataset_sample` 数据集样本表 目标定位： - 记录真正进入数据集的样本文件 - 文件实际存储于 MinIO 的 `dataset` 桶 - 每个样本对应一个 MinIO 对象 样本来源有两类： 1. 页面直接上传图片、视频、音频 2. 从 `ai_temp_file` 中选择文件导入 导入规则： - 如果数据集要求是图片类型，而临时文件是 ZIP，则自动解压 ZIP 中符合类型的文件后逐个导入 - 如果数据集要求是图片类型，而临时文件是视频，则根据抽帧规则提取图片后导入 - 如果数据集要求是视频类型，则视频原文件可以直接进入 `ai_dataset_sample` - 如果数据集要求是音频类型，则只导入音频类文件 ### 4.4 `ai_annotate_task` / `ai_annotate_task_sample` 根据现有代码，当前这两张表实际上承载的是标注任务与标注样本任务。 当前逻辑包括： - 创建标注任务 - 分配样本给执行人 - 自动标注 - 人工标注 - 提交审核 - 审核通过/驳回 - 合并标注结果回主样本表 新的表结构已经明确恢复为原先的标注任务设计，因此任务与数据集的关系保持为单数据集模式： - `ai_annotate_task.dataset_id`：记录本次标注任务所属的数据集 - `ai_annotate_task_sample.sample_id`：记录当前任务样本对应的主样本记录 这样可以继续保持以下业务能力： - 创建任务时按数据集分配样本 - 合并标注结果时定位主数据集样本 - 统计任务所属数据集样本数量 确认采用以下方案调整： 1. `ai_annotate_task.dataset_id` 保存本次标注任务所属数据集 2. `ai_annotate_task_sample.sample_id` 保存当前任务样本对应的主样本 3. 通过 `ai_annotate_task.dataset_id -> ai_dataset.id` 可以明确任务属于哪个数据集 4. 通过 `ai_annotate_task_sample.sample_id -> ai_dataset_sample.id` 可以明确任务样本对应哪条主样本记录 5. 原先“单数据集标注任务”的业务处理逻辑保持不变，主要进行表名和模型映射调整 --- ## 5. 目标功能改造方案 ### 5.1 临时文件模块改造 新增模块名称建议： - 临时文件管理 建议新增模型： - `AiTempFile` 建议新增接口： - 临时文件上传 - 临时文件列表查询 - 临时文件详情读取 - 临时文件修改 - 临时文件删除 - 临时文件下载 - 临时文件预览 建议接口示例： - `POST /server/tempfile/upload/` - `GET /server/tempfile/list/` - `GET /server/tempfile/read/` - `PUT /server/tempfile/update/` - `DELETE /server/tempfile/delete/` - `GET /server/tempfile/download/` - `GET /server/tempfile/preview/` 处理流程建议： 1. 前端上传文件 2. 后端识别文件类型 3. 上传到 MinIO `tempfile` 桶 4. 记录 `ai_temp_file` 5. 返回文件 ID、文件名、桶名、对象名、预览地址 ### 5.2 数据集模块改造 目标接口保留并扩展： - 数据集新增 - 数据集修改 - 数据集删除 - 数据集列表查询 - 数据集详情查询 建议废弃或重构当前接口中的以下逻辑： - 在 `createDataset` 中按算法创建本地目录 - 在 `uploadDatasetFile` 中直接把文件落到本地目录 - 在 `generateDatasetImages` 中依赖本地视频目录做抽帧 建议新增业务接口： - 从临时文件导入到数据集 - 直接上传文件到数据集 建议接口示例： - `POST /server/dataset/importFromTempFile/` - `POST /server/dataset/uploadSamples/` ### 5.3 数据集样本模块改造 建议新增或调整能力： - 样本列表查询 - 样本详情查询 - 样本预览 - 样本删除 - 样本批量导入 - 样本批量抽帧导入 - 样本批量解压导入 #### 样本导入统一规则 建议抽象为统一导入服务： - `TempFileImportService` - `DatasetSampleImportService` 建议流程： 1. 根据 `dataset_id` 读取数据集定义 2. 根据 `temp_file_id` 读取临时文件元数据 3. 按数据集类型与临时文件类型执行对应导入策略 4. 将结果文件上传到 MinIO `dataset` 桶 5. 逐条写入 `ai_dataset_sample` 6. 更新 `ai_dataset.dataset_count` 7. 将 `ai_temp_file.status` 更新为已导入 #### 类型转换规则建议 ##### 规则 A：图片数据集 + ZIP 文件 - 解压 ZIP - 仅提取图片类型文件 - 上传到 `dataset` 桶 - 批量写入 `ai_dataset_sample` ##### 规则 B：图片数据集 + 视频文件 - 根据抽帧规则提取图片 - 上传图片到 `dataset` 桶 - 批量写入 `ai_dataset_sample` ##### 规则 C：视频数据集 + 视频文件 - 视频原文件直接上传到 `dataset` 桶 - 写入 `ai_dataset_sample` ##### 规则 D：音频数据集 + ZIP 文件 - 解压 ZIP - 筛选音频文件 - 上传到 `dataset` 桶 - 批量写入 `ai_dataset_sample` ##### 规则 E：图片数据集 + 直接上传图片 - 文件直接上传到 `dataset` 桶 - 写入 `ai_dataset_sample` ### 5.4 标注任务模块改造 当前标注任务能力本身可以保留，但需进行表结构和字段适配。 建议改造点： - 将 `AiDatasetTask` 调整为映射 `ai_annotate_task` - 将 `AiDatasetTaskSample` 调整为映射 `ai_annotate_task_sample` - 所有任务相关接口、序列化器、统计逻辑同步修改 - 保持当前单 `dataset_id` 的标注任务处理逻辑 - 按新表结构对齐字段顺序和表名，不额外引入新的任务关联复杂度 特别说明： - 创建任务时继续选择单一 `dataset_id` - 分配样本时，继续从该数据集下筛选样本 - 合并标注结果时，继续通过 `sample_id` 回写到主样本 - 任务详情、统计、筛选页面继续按单数据集任务展示 ### 5.5 训练样本准备模块改造 这是本次需求中容易被忽略但必须同步改造的部分。 当前训练准备逻辑默认从本地目录读取图片、标注文件和 mask 文件。如果 `ai_dataset_sample` 的真实文件改存 MinIO，则以下功能都会受到影响： - `prepare_algorithm_train_dataset` - 检测任务生成 YOLO 标签 - 分割任务生成 mask、txt、COCO JSON - 训练前复制样本到 `train/val` 目录 人工核实确认新增一层训练样本读取服务： - 如果样本存本地，则直接读取本地文件 - 如果样本存 MinIO，则先下载到训练工作目录或使用本地缓存目录 建议实现： - `DatasetSampleStorageService` - `TrainingDatasetMaterializeService` --- ## 6. 推荐的数据字段调整建议 ### 6.1 `ai_temp_file.original_type` 建议统一存枚举值，而不是自由文本，便于后续导入规则判断。 ### 6.2 `ai_dataset.dataset_path` 建议定义为 MinIO 逻辑目录前缀，例如： - `datasets/{dataset_id}/` 而不再直接绑定本地绝对目录。 ### 6.3 `ai_dataset_sample.saved_path` 当前字段语义是服务器磁盘路径，改造后建议定义为： - MinIO 对象逻辑前缀 - 或对象完整目录前缀 例如： - `datasets/{dataset_id}/images` ### 6.4 `ai_dataset_sample.saved_filename` 建议保留，作为对象文件名。 ### 6.5 `ai_dataset_sample.rectangle` / `polygon` 由于 `table.sql` 已将标注内容拆分为两个字段，建议后续按标注类型分别存储： - 目标检测标注写入 `rectangle` - 多边形标注写入 `polygon` 如果仍需兼容当前前端和自动标注逻辑，可以在服务层临时做统一转换，避免前端一次性改动过大。 --- ## 7. 受影响模块清单 ### 7.1 数据模型层 需要调整或新增： - `backend/apps/core/models.py` - 新增 `AiTempFile` - 调整 `AiDataset` 映射 - 调整 `AiDatasetSample` 字段 - 调整 `AiDatasetTask` 映射 - 调整 `AiDatasetTaskSample` 映射 - 将 `AiDatasetTask` 的表映射从旧表调整到 `ai_annotate_task` - 将 `AiDatasetTaskSample` 的表映射从旧表调整到 `ai_annotate_task_sample` ### 7.2 序列化器层 需要调整： - `backend/apps/common/serializers.py` 建议不要继续全部使用 `fields = "__all__"`，应增加： - 字段级校验 - 类型校验 - 只读字段控制 - 导入规则参数校验 ### 7.3 视图层 重点受影响文件： - `backend/apps/datasets/views/dataset.py` - `backend/apps/datasets/views/dataset_sample.py` - `backend/apps/datasets/views/annotate_task.py` - `backend/apps/datasets/views/annotate_task_sample.py` - `backend/apps/training/views/algorithm_trainrecords.py` ### 7.4 MinIO 能力层 现有通用能力可复用： - 单文件上传 - 批量上传 - ZIP 解压入库 - 视频抽帧入库 - 下载 - 预览 - 预签名地址 但应注意： - 现有 MinIO 接口是通用文件接口 - 业务层仍需新增“文件上传后写业务表”的封装接口 --- ## 8. 推荐接口改造清单 ### 8.1 临时文件接口 - `POST /server/tempfile/upload/` - `GET /server/tempfile/list/` - `GET /server/tempfile/read/` - `PUT /server/tempfile/update/` - `DELETE /server/tempfile/delete/` - `GET /server/tempfile/download/` - `GET /server/tempfile/preview/` ### 8.2 数据集接口 - `POST /server/dataset/create/` - `PUT /server/dataset/update/` - `DELETE /server/dataset/delete/` - `GET /server/dataset/list/` - `GET /server/dataset/read/` - `POST /server/dataset/uploadSamples/` - `POST /server/dataset/importFromTempFile/` ### 8.3 数据集样本接口 - `GET /server/dataset/sample/list/` - `GET /server/dataset/sample/read/` - `DELETE /server/dataset/sample/delete/` - `GET /server/dataset/sample/preview/` - `GET /server/dataset/sample/download/` ### 8.4 任务接口 - `POST /server/annotateTask/create/` - `GET /server/annotateTask/list/` - `GET /server/annotateTask/read/` - `PUT /server/annotateTask/update/` - `DELETE /server/annotateTask/delete/` - `POST /server/annotateTask/assignSamples/` - `POST /server/annotateTask/autoAnnotate/` - `POST /server/annotateTask/submitAudit/` - `POST /server/annotateTask/audit/` - `POST /server/annotateTask/mergeToDataset/` 任务接口改造时需要特别支持： - 创建任务时提交单一 `dataset_id` - 查询任务详情时返回所属数据集信息 - 任务样本列表继续按任务和样本状态过滤，无需额外支持跨数据集来源拆分 --- ## 9. 推荐实施顺序 ### 第一阶段：表结构对齐 目标： - 按 `table.sql` 调整模型和迁移脚本 - 补齐 `AiTempFile` - 完成序列化器基础适配 ### 第二阶段：临时文件模块落地 目标： - 完成 `ai_temp_file` CRUD、下载、预览 - 文件统一上传到 MinIO `tempfile` 桶 ### 第三阶段：数据集导入流程改造 目标： - 支持直接上传到数据集 - 支持从 `ai_temp_file` 导入到 `ai_dataset_sample` - 支持 ZIP 解压导入 - 支持视频抽帧导入 ### 第四阶段：标注任务适配 目标： - 适配 `ai_annotate_task` / `ai_annotate_task_sample` - 调整样本分配、审核、合并逻辑 - 兼容 `rectangle` / `polygon` ### 第五阶段：训练准备适配 目标： - 训练前样本准备流程改为支持 MinIO 数据源 - 保证现有训练功能不因文件存储切换而失效 --- ## 10. 风险与注意事项 ### 10.1 最大风险：表结构变了，但业务主流程仍基于旧字段 尤其是以下两个点影响最大： - `ai_dataset` 不再包含 `algorithm_id` - 标注任务表从旧表名切换为 `ai_annotate_task` 如果不先明确新的业务关联关系，直接改模型会导致： - 数据集创建逻辑失效 - 标注任务创建与样本分配逻辑失效 - 标注合并逻辑失效 ### 10.2 标注任务表名切换带来的兼容风险 标注任务相关模型、接口和统计逻辑当前都绑定旧表名，切换到新表后需要同步适配： - 创建任务时的数据写入表 - 任务样本分配与读取 - 审核状态统计 - 标注结果合并回主样本 - 前端页面的任务详情与列表查询 ### 10.3 文件存储切换后，训练模块必须同步改造 如果只改上传链路，不改训练样本准备链路，会导致： - 数据集页面可正常上传 - 但训练启动时找不到样本文件 ### 10.4 标注字段拆分后，前端与自动标注逻辑也要同步 当前系统大量逻辑直接读写 `annotation_content`，而新表结构改为： - `rectangle` - `polygon` 需要提前定义兼容策略，避免标注页面与自动标注接口全部失效。 --- ## 11. 最终结论 本次需求不是简单新增几个接口，而是一次涉及以下四个层面的系统级改造： - 数据库表结构重构 - 文件存储模式切换为 MinIO 主存储 - 数据集导入链路重构 - 标注与训练链路适配 - 标注任务表结构与命名对齐 建议按“表结构对齐 -> 临时文件模块 -> 数据集导入 -> 标注任务适配 -> 训练准备适配”的顺序分阶段实施。 本次修正确认后，标注任务链路的关系已经清晰： 1. `ai_annotate_task.dataset_id` 记录本次标注任务所属数据集 2. `ai_annotate_task_sample.sample_id` 记录对应的主样本记录 3. 标注任务仍然按单数据集业务逻辑处理 这样可以保持原先标注任务、样本分配、审核和合并回库逻辑不变。 当前最优先要做的事情有三项： 1. 明确 `ai_dataset` 是否还需要与算法关联 2. 将标注任务模型和接口从旧表映射调整到 `ai_annotate_task` 与 `ai_annotate_task_sample` 3. 将 `ai_temp_file` 模块先落地，作为后续所有导入能力的统一入口 只有在这三个基础点明确后，后续 ZIP 解压导入、视频抽帧导入、样本入库、标注任务、训练任务才能稳定衔接。