YG_FT/docs/当前项目开发进度.md

# 当前项目开发进度

> 评估基线：2026-08-19 当前工作区代码、数据库初始化脚本、Docker 部署文件、前端页面和现有设计文档。
>
> 本文以代码实际情况为准。设计文档中已经提出但代码没有形成完整闭环的内容，统一标记为“部分完成”或“未完成”。

## 一、项目定位与总体结论

当前项目是一个面向多用户、多算力节点的模型训练与推理平台，主要链路为：

```text
Vue 前端
    |
FastAPI Backend API
    |-- PostgreSQL：业务元数据、权限、任务状态、小型内容和预览数据
    |-- Redis：会话、限流、短期缓存和任务辅助状态
    |-- MinIO：模型、数据集、报告和大文件的统一对象存储
    |-- Compute API / Agent：训练、推理、评测、模型合并和 GPU 执行
    |
多台算力节点
```

整体判断：

| 范围 | 当前状态 | 结论 |
|---|---|---|
| 平台基础架构 | 基本完成 | 前后端、数据库、Redis、MinIO、Compute Agent 和 Docker 部署均已具备 |
| 核心业务闭环 | 基本可用 | 数据集、数据处理、数据转换、训练、模型、推理、评测均有页面和接口 |
| 多算力节点 | 部分完成 | 节点选择、GPU 分配和缓存准备已经接入，跨节点一致性和失败恢复仍需加强 |
| 权限治理 | 部分完成 | 登录、角色、权限码、ACL、审批、审计已实现，但完整的租户/项目隔离尚未闭环 |
| MinIO 统一存储 | 部分完成 | 大文件和模型已接入，仍存在兼容性的本地路径和部分数据双写/回退路径 |
| 生产可靠性 | 未完成 | 缓存容量治理、对象清理、流式上传、归档重试、备份和高可用尚未完成 |
| 前端体验 | 基本可用，需优化 | 构建问题已持续修复，但页面响应等待、首屏体积和部分错误提示仍需优化 |

## 二、已完成的功能

### 2.1 平台基础与部署

- 已建立 Vue 3 + TypeScript + Vite 前端工程。
- 已建立 FastAPI 后端服务，提供登录、平台管理和模型业务接口。
- 已建立 Compute API / Agent，用于连接算力节点并执行训练、推理、评测和模型处理任务。
- 已使用 PostgreSQL 保存核心业务数据，Redis 提供会话、限流和缓存能力。
- 已增加 MinIO 服务及 Backend 的 MinIO 配置，支持和 Compute Agent 分离部署。
- 已提供 `docker/app`、`docker/compute`、`docker/minio` 和 `docker/offline` 部署目录。
- 已考虑后端、算力服务、MinIO 分布在不同服务器时使用独立网络；Compute 节点访问 MinIO 需要配置所有节点都能访问的固定 IP 或 DNS。
- 离线部署目录已经同步后端、算力相关源码和初始化 SQL 的主要改造内容。

### 2.2 登录、用户和权限基础

- 用户登录、退出、当前用户信息和密码修改接口已经存在。
- 已有 Token 会话、Redis 会话记录和登录限流逻辑。
- 已建立用户、角色、权限码和角色权限关系。
- 已实现管理员、普通用户等基础角色分层。
- 已实现页面路由守卫、菜单过滤和前端按钮级权限的基础能力。
- 已建立资源 ACL 管理页面和相关接口，可对用户或角色授予资源级权限。
- 已建立审批模板、审批实例和审批步骤的基本数据模型与页面。
- 已建立运行日志、审计日志查询页面及审计记录写入机制。
- 已加入软删除相关字段和部分删除逻辑，避免直接物理删除业务资源。

### 2.3 算力节点与 GPU 资源

- 已实现算力节点的新增、编辑、启用、禁用、维护/删除、连通性测试和健康检查。
- 已实现节点列表、节点详情、节点副本/同步状态和 Compute Agent 连接。
- 已实现 GPU 信息发现、GPU 状态查询和队列查询。
- 已建立 `gpu_allocations`、`gpu_assignments`、调度锁等资源分配表。
- 训练任务已经支持选择调度节点和一张或多张 GPU，并在预检阶段校验资源可用性。
- Compute Agent 已支持训练、评测、推理和缓存准备等任务接口。
- 已存在资源副本和同步任务模型，用于记录节点侧资源同步状态。

### 2.4 数据集管理

- 已实现数据集创建、列表、详情、编辑、删除和文件上传。
- 已实现数据集文件下载、预览、记录列表和数据记录编辑入口。
- 已处理 JSON 与 JSONL 的记录数差异：JSON 数组按元素计数，JSONL 按有效行计数，避免把整个 JSON 文件误按行数统计。
- 已提供数据集版本列表、版本详情、创建版本、切换当前激活版本和删除版本接口。
- 已增加数据集文件、版本、数据记录等初始化表结构。
- 已支持数据集文件在数据库小内容和 MinIO 大文件之间按策略存储。
- 已在训练预检中检查数据集文件是否存在、是否可从 MinIO 获取以及是否能准备到目标算力节点。

### 2.5 数据处理与数据转换

- 已提供结构化数据、非结构化数据、外部数据源的处理创建流程。
- 已实现源文件上传、预览、分片/切分、生成、质量检查、去重和结果管理等数据处理流程。
- 已支持处理结果生成数据集或导入数据集版本。
- 已建立数据处理任务、源文件、预览项、结果等数据表。
- 已提供 JSON、JSONL 等数据格式转换页面和后端任务接口。
- 已将数据转换输出接入 MinIO/数据库分层存储：小型文本结果可存数据库，大文件存 MinIO。
- 已处理输出文件下载和转换结果元数据保存问题。

### 2.6 模型训练

- 已实现训练任务创建、配置预检、命令预览、启动、停止、重试和删除。
- 已接入 LLaMA-Factory 等训练适配逻辑。
- 已支持选择训练数据、基座模型、算力节点和 GPU。
- 已实现训练日志获取、训练任务概览、诊断信息、检查点和训练指标查询。
- 前端训练详情已经具备训练曲线解析和展示逻辑，日志轮询间隔已调整为 3 秒。
- 已增加 GPU 详情展示入口，包括显存和利用率等 Compute Agent 上报信息。
- 已支持训练任务的 MinIO 数据准备和目标算力节点缓存准备。

### 2.7 模型管理与权重合并

- 已实现在线模型/基座模型和训练模型的列表、创建、详情、用途修改和删除。
- 已建立模型、训练模型、模型血缘、模型产物和导出任务相关表。
- 已提供权重合并入口，能够根据训练任务准备基座模型和 Adapter，并提交 Compute Agent 执行合并。
- 已增加模型产物和 MinIO 对象关联字段。
- 合并结果能够在任务完成后归档到 MinIO 的设计和主要代码路径已经建立。

### 2.8 模型推理与模型对比

- 已实现推理模型列表、创建、详情和删除入口。
- 已实现模型加载、卸载、服务启动、服务状态查询和对话调用。
- 已实现模型对比任务及多模型聊天相关接口。
- 已增加推理失败重试、停止和资源释放的处理路径。
- 已支持根据页面选择的算力节点准备模型缓存，兼容训练时所选节点优先的业务要求。
- Compute Agent 已提供本地推理会话和模型缓存状态接口。

### 2.9 模型评测

- 已实现评测任务列表、创建、详情和删除。
- 已实现评测维度管理和评测规则配置页面。
- 已建立评测任务、评测维度、对比任务等数据库表。
- 已支持选择模型、数据集、评测维度、算力节点和 GPU 的基础流程。
- 已接入 Compute Agent 执行评测任务，并保存评测结果和报告相关元数据。

### 2.10 数据存储策略

- 已建立 `storage_objects`、`storage_cache_jobs` 等 MinIO 元数据和缓存任务表。
- 已建立 MinIO 对象上传、下载、预签名 URL 和节点缓存准备的主要接口。
- 已采用分层策略：
  - 小型 JSON、JSONL、CSV、任务参数快照、预览数据保留在数据库，降低频繁预览的 MinIO 延迟。
  - 模型权重、训练产物、评测报告和大文件使用 MinIO。
  - 小型 PDF、DOCX、XLSX 仍优先存 MinIO，以保留原始二进制文件内容。
- 已增加 `data_convert_tasks.output_content`，用于保存小型转换结果，避免所有小结果都依赖 MinIO。
- Backend 和离线包中的 `000_full_init.sql` 已同步，当前两份初始化脚本内容一致。

## 三、部分完成、仍需完善的功能

### 3.1 MinIO 统一数据源尚未完全闭环

当前 MinIO 已成为模型、大文件和跨节点资源的主存储方向，但仍保留以下兼容路径：

- Compute Agent 仍有本地文件上传、导入本地模型和扫描本地模型目录的旧接口。
- 部分历史数据仍使用数据库中的 `content` 或 `output_content` 字段，这是当前已确认的小文件性能策略，不是错误，但必须统一记录来源、大小、校验值和版本。
- 大文件在部分代码路径中仍通过 `read()` 或 `put_bytes()` 一次性读入内存，未完成流式或分片上传。
- MinIO 对象和业务资源之间采用多态 `resource_type/resource_id` 关联，数据库没有直接外键，删除和数据一致性需要应用层保证。
- 删除业务资源后，对应 MinIO 对象的延迟清理、失败重试和孤儿对象扫描尚未形成完整闭环。

### 3.2 MinIO 预签名接口的权限边界需要加强

当前预签名接口已经存在，但 PUT 上传场景仍需要重点补强：

- 需要根据资源类型和资源 ID 校验当前用户的写权限，而不应只校验读取权限。
- 需要服务端生成并校验对象 Key，避免客户端任意写入其他用户或其他资源的对象路径。
- 需要增加上传完成确认接口，校验对象实际存在、大小和校验值后再写入业务表。
- 需要限制允许的 Bucket、Content-Type、大小和有效期。
- 需要记录预签名创建、上传完成、失败和过期事件，便于审计。

### 3.3 激活版本和跨节点资源版本仍需加强

数据集已经有 `active_version_id` 和版本表，但以下场景仍需补充：

- 训练、推理和评测必须只使用资源当前激活版本，并在任务创建时固化版本 ID。
- 同一文件名的不同版本不能只依靠文件名同步，应使用资源 ID、版本 ID 和对象 Key 组成唯一定位。
- 已创建任务在后续切换激活版本后，不能被意外切换到新版本。
- 需要为每个准备到算力节点的资源保存版本、对象 ETag/校验值和本地路径清单。
- 历史版本的数据库内容回退和 MinIO 对象回退逻辑还需要补全并增加测试。

### 3.4 权限 2.0 尚未完全落地

已有用户、角色、权限码、ACL、审批和审计基础，但仍存在以下差距：

- 租户、用户、资源、算力节点、模型、数据集之间的隔离规则没有全部在 SQL 查询层统一执行。
- 项目空间设计已经讨论过取消，但数据库中仍保留 `projects`、`project_members` 等历史结构，需要明确兼容策略和最终迁移方式。
- 训练创建的模型、数据集和训练任务之间的联合权限约束还没有完全统一。
- 评测、推理、模型合并、导出、缓存准备等动作需要逐一校验资源读权限和操作权限。
- 前端按钮权限已经有基础实现，但不能替代后端鉴权；仍需要对所有关键动作进行后端默认拒绝校验。
- 审批拦截范围、管理员豁免规则和跨租户资源访问规则需要形成可执行矩阵。

### 3.5 模型合并、导出和评测报告闭环不足

- 权重合并前自动准备 Base Model 和 Adapter 的主要路径已建立，但失败时的清理、重试和幂等性仍需加强。
- 合并结果归档到 MinIO 的逻辑主要依赖任务完成轮询，服务重启或轮询中断时可能需要补偿扫描。
- 模型导出任务目前有查询模型和表结构，但完整的创建、执行、进度、失败重试和下载闭环尚未完成。
- 评测结果和报告字段已经存在，但报告对象归档、报告下载、报告版本和报告与任务的稳定关联仍需验证。
- 评测指标配置和执行器返回指标之间仍需要强类型映射，避免前端显示为通用的 `custom`。

### 3.6 GPU 资源分配需要统一到所有任务类型

- 训练已经有较完整的节点/GPU 选择和预检流程。
- 推理和评测已经出现节点选择、缓存准备和 GPU 选择的接入代码，但还需要确认从页面选择到 Compute Agent 启动参数、进程环境变量和释放逻辑的全链路生效。
- 需要防止同一张 GPU 被多个任务绕过调度锁重复占用。
- 需要处理服务异常退出、Backend 重启、Compute Agent 重启后的分配回收和状态对账。
- 训练详情中的显存使用量、GPU 使用率等指标依赖 Compute Agent 上报，仍需要校验采样时间、单位、空值和任务对应关系。

## 四、尚未完成的功能

以下功能在当前代码中没有形成可验收的完整闭环，或仍处于设计/基础代码阶段：

1. **完整的租户隔离和资源继承模型**：所有列表、详情、下载、缓存、训练、推理、评测和导出接口都需要统一的租户范围过滤。
2. **项目取消后的正式数据迁移方案**：需要决定历史项目数据如何归属到用户或租户，并提供一次性迁移脚本和回滚方案。
3. **预签名上传完成确认和对象校验**：包括 Key 白名单、ACL、大小限制、哈希/ETag 和状态回写。
4. **MinIO 对象生命周期管理**：软删除后的延迟删除、失败重试、孤儿对象扫描、对象引用检查和管理员清理入口。
5. **Compute Agent 缓存治理**：容量上限、LRU/TTL、运行任务保护、磁盘占用监控、缓存清单和版本校验。
6. **统一的资源归档编排器**：训练、合并、评测和推理相关产物需要支持断点恢复、幂等重试和服务重启补偿。
7. **模型导出完整流程**：导出任务创建、格式/量化参数、进度、失败重试、MinIO 归档和下载权限。
8. **流式和分片文件传输**：避免大文件上传、下载和对象复制时将完整内容读入 Backend 或 Compute Agent 内存。
9. **生产级 MinIO 安全和高可用**：默认密钥替换、TLS、网络访问控制、管理员 Console 隔离、容量监控、备份和恢复。
10. **完整的端到端测试和持续集成**：至少覆盖单节点、多节点、多 GPU、跨用户、跨租户、版本切换、MinIO 不可用和服务重启恢复。
11. **统一数据库迁移体系**：当前初始化 SQL 适合新库初始化，但尚未替代正式的版本化迁移工具；已有数据库更新仍需要明确迁移脚本和执行记录。

## 五、需要优化的功能

### 5.1 后端响应性能

- 页面列表接口需要避免每条记录重复查询用户、资源、MinIO 元数据和 Compute 节点状态。
- MinIO 的 Bucket 检查、对象 Head 和预签名生成应使用连接复用、短期缓存和批量查询。
- 训练、推理、评测页面不应通过过短间隔轮询大量详情接口，应按任务状态动态退避，并在完成后停止轮询。
- 对 dashboard、节点健康、GPU 状态等高频数据应区分实时数据和缓存数据。
- 后端日志轮询和健康检查日志需要继续降噪，仅在状态变化、失败或达到较长周期时输出。

### 5.2 前端加载和交互

- 列表页面应区分首屏 loading、刷新 loading、操作 loading，避免整页长时间无反馈。
- 推理、评测、训练详情应使用统一的任务状态刷新策略和超时提示。
- 前端仍有 FontAwesome 在线资源解析警告，应清理对外部网络文件的依赖，保证离线环境打开速度。
- 应继续拆分首屏大体积 chunk，并减少一次性加载不相关页面组件。
- GPU 选择组件需要明确显示空闲、占用、不可达、预留和已分配状态。
- 错误提示应携带资源名称、节点名称、版本和下一步处理建议，减少只显示 500/404 的情况。

### 5.3 训练、推理和评测可靠性

- 所有任务创建前应执行同一套资源权限、版本存在性、MinIO 可用性和 GPU 原子分配校验。
- 任务创建接口应支持幂等键，避免前端重复点击造成重复任务。
- 节点不可达时应快速失败或进入可见的等待状态，不能让页面长时间无反馈。
- 失败重试应区分网络瞬时失败、资源不足、模型文件缺失、参数错误和执行器失败。
- 任务停止后必须释放 GPU 分配、推理端口、缓存锁和临时目录。

### 5.4 数据和模型一致性

- 每个对象都应保存大小、校验值、版本 ID、来源、创建者、租户和引用状态。
- 数据库中的小文件内容和 MinIO 对象不能同时被当作可独立修改的主副本；需要明确唯一写入入口。
- 数据集激活版本变更需要留下审计记录，并影响后续任务创建但不改变已创建任务。
- 模型权重、Adapter、合并结果和导出结果需要形成完整血缘关系。

## 六、数据库和初始化脚本状态

当前 `backend/app/db/sql/000_full_init.sql` 已包含以下主要类别：

- 用户、模型、训练模型、模型血缘、模型产物、模型导出任务。
- 数据集、数据集文件、数据集版本、数据集记录。
- 算力节点、GPU、GPU 分配、调度锁、Compute Job。
- 资源副本、资源同步任务、MinIO 对象、缓存任务。
- 评测任务、评测维度、模型对比任务。
- 租户、项目兼容表、项目成员、角色、会话、ACL。
- 审批模板、审批实例、审批步骤、审计日志、留存策略。
- 数据处理任务、源文件、预览项、处理结果、数据转换任务。

已确认的近期字段包括：

- `model_artifacts.storage_object_id`
- `model_artifacts.storage_backend`
- `dataset_files.storage_object_id`
- `data_convert_tasks.output_content`
- `data_convert_tasks.output_storage_object_id`
- `data_convert_tasks.storage_backend`
- `eval_tasks.report_storage_object_id`

离线包中的 `docker/offline/src/backend/app/db/sql/000_full_init.sql` 应与主工程初始化脚本保持同步。需要注意：

- 初始化 SQL 主要用于新数据库或新数据卷；已有数据库不能仅靠重启容器自动获得全部新字段。
- 生产/测试数据库需要执行可追踪的迁移脚本，并在迁移前备份或生成结构快照。
- `ensure_schema` 类运行时补字段逻辑只能作为兼容兜底，不能替代正式迁移。
- 后续如果正式移除项目设计，需要先完成数据归属迁移，再决定是否删除历史表，不能直接从初始化 SQL 中删除表。

## 七、当前验证结果

已完成的静态和局部验证：

- Backend 和离线 Backend 源码 `compileall` 检查通过。
- MinIO 分层策略冒烟验证通过：小型 JSON/JSONL 可落数据库，小型二进制和超过阈值的内容进入 MinIO。
- 主工程和离线包初始化 SQL 已做同步检查，内容一致。
- 前端此前已完成 `npm run build` 类型错误修复，构建剩余问题主要是非阻断的资源/分包警告。
- 已对训练日志、数据集 JSON/JSONL 统计、MinIO 资源准备等重点链路进行过问题修复。

当前不能据此宣称“全量功能测试通过”：

- 现有部分自动化测试仍保留旧的本地文件或旧 MinIO 行为假设，需要按当前分层存储策略更新。
- WSL Docker 运行时验证受当前环境的 `E_ACCESSDENIED` 影响，不能在本次文档生成时完成全部容器健康、数据库字段和跨节点测试。
- 多节点、多 GPU、MinIO 临时不可用、服务重启恢复和跨用户权限测试仍需要在可用运行环境中执行。

## 八、下一阶段开发计划

### P0：安全与数据正确性

1. 完善 MinIO 预签名 PUT 的资源写权限、对象 Key 白名单、大小/类型限制和上传完成确认。
2. 统一任务创建时的资源版本固化，训练、推理、评测只使用已授权的激活版本快照。
3. 逐一补齐评测、推理、模型合并、模型导出、缓存准备的后端权限校验和审计记录。
4. 完成租户隔离查询范围，清理或兼容历史项目字段，补充数据迁移脚本。

### P1：跨节点可靠性

1. 建立资源清单/manifest，记录 MinIO 对象版本、校验值、目标节点路径和缓存状态。
2. 完善训练、合并、评测和推理的准备、执行、归档、失败重试和服务重启补偿。
3. 完善 GPU 原子分配、异常回收、节点重连对账和任务释放。
4. 增加缓存容量、TTL/LRU、运行任务保护和磁盘占用监控。
5. 增加 MinIO 对象引用清理、孤儿对象扫描和软删除回收任务。

### P2：性能与用户体验

1. 优化页面列表接口和高频轮询，采用批量查询、短期缓存和动态退避。
2. 将大文件上传/下载/复制改为流式或分片传输。
3. 统一前端任务状态组件、loading、超时、重试和错误诊断信息。
4. 处理前端离线资源警告，继续拆分首屏 chunk。
5. 统一 GPU 状态展示及训练指标采样时间、单位和空值处理。

### P3：工程化和上线准备

1. 建立正式数据库版本迁移机制和离线升级脚本。
2. 增加 CI：前端类型检查/构建、Backend 单元测试、Compute Agent 测试、SQL 新库初始化测试。
3. 增加多节点端到端测试和 MinIO 故障注入测试。
4. 完善 MinIO TLS、密钥管理、网络隔离、监控、备份和恢复方案。
5. 建立生产运行手册，包括首次部署、升级、回滚、数据库迁移、对象清理和故障处理。

## 九、阶段验收标准

完成下一阶段后，至少应满足：

- 用户只能看到和操作其所属租户授权的模型、数据集、训练任务、推理服务和评测任务。
- 任何任务创建都能明确记录用户、租户、资源版本、算力节点、GPU 列表和 MinIO 对象版本。
- 同一个节点的同一张 GPU 不能被两个活动任务同时分配。
- MinIO 临时不可用时，任务进入可解释的等待/失败状态，并能按策略重试，页面不会无限等待。
- Backend 或 Compute Agent 重启后，任务、缓存、GPU 分配和归档状态可以对账恢复。
- 训练、合并、评测和推理产物都能在 MinIO 中找到，并且可以通过权限校验后的接口下载或使用。
- 删除资源后不会继续出现在普通列表中，关联对象能够按引用状态延迟清理并留下审计记录。
- 新数据库初始化和已有数据库迁移后，所有业务接口不再因为缺表或缺字段启动失败。
- 离线部署不依赖外部字体、图标或 CDN，前端首屏和核心业务操作在无网络环境下可用。

## 十、相关文件索引

- 平台架构：[platform-architecture-requirements.md](./platform-architecture-requirements.md)
- 权限设计：[permissions-design.md](./permissions-design.md)
- MinIO 与 Compute 缓存方案：[minio-compute-cache-plan.md](./minio-compute-cache-plan.md)
- 平台治理菜单设计：[platform-governance-menu-design.md](./platform-governance-menu-design.md)
- 数据处理设计：[data-process-design.md](./data-process-design.md)
- 数据库初始化脚本：[../backend/app/db/sql/000_full_init.sql](../backend/app/db/sql/000_full_init.sql)
- 离线部署目录：[../docker/offline](../docker/offline)