feat: 更新后端平台模块、数据库、Compute引擎及多项配置文档

- 更新 backend 平台 API、platform_store、session 数据库模块 - 新增 backend SQL 初始化脚本 - 更新 compute 引擎适配器及 README - 更新 Docker 部署配置（app/compute） - 更新前端入口、环境类型声明及 README - 新增 docs/menu-functional-requirements.md 菜单功能需求文档 - 更新多项项目文档 Co-Authored-By: Claude <noreply@anthropic.com>
2026-07-21 10:55:44 +08:00
parent bccd3bf448
commit a72b8f1e4b
24 changed files with 571 additions and 630 deletions
--- a/docs/backend-api-design.md
+++ b/docs/backend-api-design.md
@@ -1,6 +1,8 @@
 # 模型微调平台后端接口设计

-> 后端建议使用 FastAPI，统一挂载 `/modelTF` 前缀。本文根据当前 Vue 前端路由、API 模块、mock 数据和页面交互反推接口，并补充完整微调平台必须具备的用户中心、权限控制、审计、异步任务、文件版本与监控能力。
+> 后端建议使用 FastAPI，统一挂载 `/modelTF` 前缀。本文根据当前 Vue 前端路由、API 模块和页面交互契约梳理接口，并补充完整微调平台必须具备的用户中心、权限控制、审计、异步任务、文件版本与监控能力。前端 Mock 仅作为隔离开发辅助，不作为接口设计准则。
+
+菜单、二级路由、规划菜单、接口和数据库的总览映射见 `docs/menu-functional-requirements.md`。后续新增接口时，必须同步标注对应页面/功能模块。

 ## 1. 通用约定

@@ -88,7 +90,7 @@ page=1&page_size=20&keyword=xxx&sort=-created_at
 }
 ```

-说明：前端当前登录接口已经要求返回 `user`，mock 里只返回 token，正式后端必须返回完整用户信息。
+说明：前端当前登录接口已经要求返回 `user`，正式后端必须返回完整用户信息。

 ### 2.2 当前用户

@@ -158,7 +160,7 @@ page=1&page_size=20&keyword=xxx&sort=-created_at
 }
 ```

-说明：首页当前完全使用前端 mock，后端应提供聚合接口，避免前端拼多接口导致加载慢。
+说明：首页需要由后端提供正式聚合接口，避免前端拼多接口导致加载慢。

 ### 3.2 健康指标

@@ -318,7 +320,7 @@ page=1&page_size=20&keyword=xxx&sort=-created_at

 ## 6. 数据处理

-当前数据处理页面为本地模拟，正式后端建议实现以下接口。
+当前数据处理页面需要后端正式承接上传、切片、生成、编辑和发布流程，建议实现以下接口。

 ### 6.1 任务列表与详情

@@ -678,7 +680,7 @@ page=1&page_size=20&keyword=xxx&sort=-created_at
 ## 11. 后端开发需要补齐的关键点

 1. 前端路由已有 `user-settings`、`user-create`、`user-permission`、`permission-denied`，但当前仓库缺少对应 Vue 文件；后端仍应先实现用户中心和权限接口。
-2. 数据处理主流程目前全在浏览器本地模拟，后端需要正式实现上传、切片、LLM 生成、结果编辑、发布数据集。
+2. 数据处理主流程需要后端正式实现上传、切片、LLM 生成、结果编辑、发布数据集。
 3. 训练、评测、数据处理、模型加载都不应同步阻塞 HTTP；建议接 Celery/RQ/Arq 或 FastAPI BackgroundTasks + 独立 worker。
 4. 文件内容不要全部入库；数据库保存元数据、版本、校验和、对象存储路径，内容放本地 NAS/MinIO。
 5. API Key、外部数据源密码必须加密存储，接口只回显脱敏。
--- a/docs/deployment-plan.md
+++ b/docs/deployment-plan.md
@@ -63,7 +63,7 @@

 ### 4.1 适用场景

- PoC、试点环境、演示环境。
+- 开发联调、单机试运行、资源受限的早期上线环境。
 - 小团队共用一台单机多 GPU 服务器。
 - 网络隔离要求不高，部署资源有限。

@@ -272,7 +272,7 @@ compute/engines/openrlhf/
 ```env
 APP_ENV=prod
 MODELTF_ROUTE_PREFIX=/modelTF
-DATABASE_URL=postgresql+asyncpg://yg_ft:***@postgres:5432/yg_ft
+DATABASE_URL=postgresql+psycopg://yg_ft:***@postgres:5432/yg_ft
 REDIS_URL=redis://redis:6379/0
 LOG_DIR=/opt/yg-ft/logs/backend
 COMPUTE_API_BASE_URL=https://compute.internal:19100
@@ -327,7 +327,7 @@ CUDA_VISIBLE_DEVICES=0,1,2,3
 - 后端 `GET /modelTF/health` 正常。
 - Compute API 健康检查正常。
 - Compute Agent 能识别 GPU、显存、CUDA 版本。
- LLaMA-Factory 能在命令行完成最小训练样例。
+- LLaMA-Factory 能在命令行完成最小训练作业。
 - 应用平台能提交训练任务到 Compute API。
 - 任务状态能从算力平台同步回应用平台。
 - 数据集上传、离线导入、产物下载路径权限正确。
--- a/docs/first-version-development-plan.md
+++ b/docs/first-version-development-plan.md
@@ -1,10 +1,10 @@
-# 第一版系统开发计划
+# 当前系统主链路开发计划

-> 说明：本计划虽然以“可演示闭环”为阶段目标，但实现内容按正式系统第一版开发，不在工程模块、配置项、接口标签、数据库对象中使用临时代码命名。初始化数据仅作为样例种子数据，后续可在此基础上继续扩展为生产能力。
+> 说明：本计划描述当前正在开发的系统能力。代码、接口和 SQL 均按后续生产演进基线维护，不以一次性演示、静态 Mock 或样例数据作为开发准则。联调辅助能力必须显式配置启用，并不得成为默认运行路径。

 ## 1. 阶段目标

-第一版系统需要在没有完整生产环境、没有真实 GPU 或没有 LLaMA-Factory 运行环境时，仍然可以跑通模型微调平台的主链路：
+当前阶段需要完成模型微调平台的主链路工程基础：

 ```text
 登录
@@ -12,24 +12,26 @@
 -> 数据集管理
 -> 创建微调任务
 -> 调度算力节点与 GPU
- -> 模拟资源副本检查和同步
+ -> 检查并同步模型/数据集资源
 -> 启动训练任务
- -> 查看任务状态、GPU 占用、训练日志、loss 曲线
+ -> 轮询任务状态、GPU 占用、训练日志、loss 曲线
 -> 训练完成后登记训练产物
 ```

-该阶段不是一次性展示代码，而是后续系统继续开发的基础版本。算力、训练框架、资源同步、任务状态机均按真实平台边界设计，当前仅以 `simulator` 模式补齐无 GPU 环境下的可运行能力。
+该阶段是正式系统的第一批可运行能力，不再初始化业务样例数据。系统只允许初始化内置管理员/运维账号，模型、数据集、算力节点、GPU、训练任务和资源副本必须通过页面、接口、算力 Agent 扫描或正式导入流程产生。

 ## 2. 运行模式

-| 模式 | 说明 | 当前状态 |
+| 模式 | 说明 | 当前要求 |
 | --- | --- | --- |
-| `simulator` | 模拟 GPU、训练进程、日志、指标、checkpoint 和训练产物 | 第一版默认实现 |
-| `real` | 预留真实 `nvidia-smi`、LLaMA-Factory 进程启动、真实日志解析和产物扫描 | 后续接入 |
+| `real` | 面向真实部署，等待 Compute API、Agent、File Gateway 和 LLaMA-Factory 执行器回写状态 | 默认模式 |
+| `simulator` | 仅用于隔离联调，无真实 GPU 时临时推进任务状态、GPU 状态和训练日志 | 必须显式开启，不得用于生产基线 |

-第一版实现必须保留 `real` 模式边界，不允许把训练命令直接写死在应用平台后端。训练相关能力统一沉淀在 `compute/engines/` 适配层。
+后端默认 `COMPUTE_MODE=real`。在该模式下，任务状态不再按时间自动推进，必须由后续真实算力同步逻辑更新。算力服务默认 `COMPUTE_EXECUTION_MODE=real`，真实训练执行器未完成前，创建训练作业会返回明确的未实现错误，避免误认为已经完成生产训练能力。

-## 3. 第一批开发范围
+训练相关能力必须沉淀在 `compute/engines/` 适配层，不允许在应用平台后端直接拼接或执行训练命令。
+
+## 3. 当前开发范围

 ### 3.1 应用平台后端

@@ -38,24 +40,27 @@
 ```text
 backend/app/
  api/v1/endpoints/platform.py
-  db/platform_store.py
-  db/session.py
+  core/
+  db/
 ```

-已覆盖能力：
+已建立能力：
 - 统一 API 响应结构 `{ code, message, data }`。
- 初始化样例用户、模型、数据集、算力节点、GPU 和微调任务。
- 登录、当前用户、用户列表与权限。
- 模型管理、训练产物列表、权重合并任务占位。
+- PostgreSQL 运行表初始化，当前执行脚本位于 `backend/app/db/sql/001_platform_runtime.sql`。
+- 内置管理员账号初始化，业务数据不再自动写入样例记录。
+- 登录、当前用户、用户列表与权限页面接口。
+- 模型管理、训练产物列表、权重合并任务入口。
 - 数据集管理、文件上传、预览、版本管理和下载。
 - 微调任务创建、启动、停止、删除、进度查询、checkpoint 查询。
- 系统健康指标、系统信息、训练日志、系统日志。
+- 系统健康指标、系统信息、训练日志、系统日志接口。
 - 算力节点、GPU、队列、资源副本、资源同步任务接口。

-开发约定：
- 当前本地可运行存储使用 SQLite，配置项为 `LOCAL_DB_PATH`。
- 生产数据库仍以 PostgreSQL 为目标，正式表结构以 `docs/postgres-schema.sql` 为准。
- `backend/app/db/session.py` 已提供 SQLAlchemy session 入口，后续替换正式 ORM 时从此处收口。
+待继续开发：
+- 接入正式 ORM/Repository/Service 分层和 Alembic 迁移。
+- 将任务状态更新改为应用侧定时轮询 Compute API/File Gateway 后落库。
+- 完成项目/模型/数据集级权限隔离校验。
+- 完成审批流、审计留存、配额、资源申请和多租户上下文。
+- 增加正式异常码、接口鉴权、中间件、幂等控制和分页规范。

 ### 3.2 算力平台服务

@@ -64,72 +69,77 @@ backend/app/
 ```text
 compute/
  api/main.py
-  engines/llama_factory/adapter.py
+  agent/
+  engines/llama_factory/
+  file_gateway/
 ```

-已覆盖能力：
+已建立能力：
 - `/modelTF/health` 与 `/modelTF/v1/compute/health` 节点健康检查。
- `/modelTF/compute/resources/gpus` GPU 状态模拟。
- `/modelTF/compute/jobs` 创建、查询、停止训练任务。
- `/modelTF/compute/jobs/{id}/logs` 拉取训练日志与解析指标。
- `/modelTF/compute/files/upload` 与 `/modelTF/compute/files/{id}/download` 文件网关占位。
- LLaMA-Factory 参数校验、命令生成、日志指标解析。
+- LLaMA-Factory 参数校验、命令生成和训练日志指标解析。
+- Compute API 作业、GPU、文件网关接口壳。
+- 显式 `simulator` 模式下的内存状态机，用于隔离联调。

-设计约定：
- 多算力节点阶段，每台单机多 GPU 服务器都部署一套 Compute API、Agent、File Gateway 和训练框架。
- 应用平台通过 `compute_nodes` 中维护的 `api_base_url`、`file_gateway_url` 主动轮询算力节点。
- 算力节点之间默认不互访，资源副本和同步状态由应用平台统一编排。
+待继续开发：
+- 真实 GPU 发现：接入 `nvidia-smi` 或 NVML。
+- GPU 锁定与释放：一张 GPU 同一时间只分配给一个训练或推理任务。
+- LLaMA-Factory 真实执行器：生成 YAML/命令、启动进程、停止进程、采集 PID。
+- 训练日志采集：读取宿主机挂载日志文件，解析 loss、learning rate、epoch 等指标。
+- Checkpoint/adapter/merged model 扫描与产物登记。
+- File Gateway：本地磁盘文件上传、下载、校验、导入和跨节点资源同步。

 ### 3.3 前端页面

 已接入页面：
 - `/login`：登录接口。
- `/model-manage`：模型列表与模型来源。
- `/dataset`、`/dataset/:id/preview`：数据集列表、预览和版本。
+- `/model-manage`：模型列表、模型来源、训练产物。
+- `/dataset`、`/dataset/:id/preview`：数据集列表、预览、版本。
 - `/fine-tune`、`/fine-tune/create`：微调任务创建、启动、状态轮询。
 - `/training-log/:id`：训练日志和 loss 曲线。
 - `/hardware`：平台 GPU 与系统性能。
 - `/compute`：算力节点、GPU、队列、资源副本。

-新增前端能力：
- `frontend/src/api/modules/compute.ts`：算力节点 API 包装。
- `frontend/src/views/compute/ComputeNodesView.vue`：节点、GPU、队列、资源副本四个视图。
- 权限枚举增加 `compute`，菜单增加“算力节点”入口。
+前端 Mock 默认关闭。仅在隔离前端开发时可设置 `VITE_ENABLE_MOCK=true`，真实联调和后续生产演进均以 `/modelTF` 后端接口为准。
+
+待继续开发：
+- 补齐多租户、项目管理、审批中心、审计中心、配额管理页面。
+- 完成算力节点管理表单，包括节点地址、权重、标签、启用状态和健康检查结果。
+- 完成模型/数据集导入页面，支持本地路径扫描和归属项目选择。
+- 推理服务页面需接入真实后端任务接口，移除页面内本地假对话路径。

 ### 3.4 数据库

-第一版运行时使用本地 SQLite 以降低开发环境门槛，但数据库模型仍按 PostgreSQL 正式设计推进。
+当前运行 SQL：

-核心表范围：
- 用户、租户、项目、角色、权限。
- 模型、训练产物、数据集、数据集文件、存储对象。
- 微调任务、训练指标、checkpoint、审计日志。
- 算力节点、GPU 设备、算力任务、GPU 分配。
- 资源副本、资源同步任务。
+```text
+backend/app/db/sql/001_platform_runtime.sql
+```

-优化方向：
- 任务状态、租户/项目隔离字段、资源副本定位字段需要建立索引。
- 审计日志、训练指标、日志归档后续建议按时间分区。
- 大文件只落本地磁盘或对象存储，数据库保存元数据和版本关系。
+架构目标 SQL：
+
+```text
+docs/postgres-schema.sql
+```
+
+当前运行 SQL 用于支持已开发接口落库；架构目标 SQL 包含用户中心、多租户、项目隔离、审批、审计、配额、评测等完整模型。后续需要通过 Alembic 将二者收敛为统一迁移体系，生产升级只走迁移脚本，不依赖手工改表。

 ## 4. 验收标准

-第一版完成后应满足：
- 前端不启用静态 Mock 时，可以通过 FastAPI 获取主要页面数据。
- 登录后可以看到模型、数据集、微调任务和算力节点。
- 创建微调任务后可以启动任务，任务状态自动流转。
- GPU 状态会随任务进入 `syncing`、`queued`、`running` 发生变化。
- 训练日志持续生成，日志详情页能解析 loss、grad norm、learning rate、epoch。
- 任务完成后训练产物出现在模型管理的训练产物列表中。
- 算力节点页面可展示节点地址、权重、标签、启用状态、队列和资源副本。
- 工程命名、配置和接口分组均可作为后续正式开发基础。
+- 启动后端必须连接 PostgreSQL，不允许回退到 SQLite。
+- 后端启动只初始化系统内置账号，不初始化模型、数据集、算力节点、GPU、训练任务等业务样例数据。
+- 前端默认请求真实 `/modelTF` 接口，除非显式设置 `VITE_ENABLE_MOCK=true`。
+- 默认 `real` 模式下任务状态不自动伪造完成，必须等待真实算力同步。
+- 显式 `simulator` 模式只能用于隔离联调，部署文档必须标注不得用于生产。
+- 登录后可以进入主界面，并可通过页面/API 创建真实业务记录。
+- 代码、接口路由、配置项、数据库表名不得使用 `demo` 命名。

 ## 5. 后续开发计划

 | 阶段 | 重点 | 说明 |
 | --- | --- | --- |
-| 第二阶段 | PostgreSQL ORM 与 Alembic | 将 `platform_store.py` 的能力迁移为正式 ORM、迁移脚本和 repository/service 分层 |
-| 第三阶段 | 真实 Compute Agent | 接入 `nvidia-smi`、GPU 锁定、进程管理、训练日志文件采集 |
-| 第四阶段 | LLaMA-Factory 真实训练 | 生成 YAML/命令、启动训练进程、停止任务、扫描 checkpoint 和 adapter |
-| 第五阶段 | 企业治理 | 多租户、项目/模型/数据集隔离、审批流、审计留存、配额和资源申请 |
-| 第六阶段 | 多节点调度 | 基于 `compute_nodes`、资源副本和节点标签实现自动/手动调度策略 |
+| 阶段 1 | 数据库迁移体系 | 将当前运行 SQL 与架构 SQL 收敛到 Alembic 迁移 |
+| 阶段 2 | 后端领域分层 | 拆分用户、模型、数据集、训练、算力、审计等模块 |
+| 阶段 3 | 真实 Compute Agent | GPU 发现、资源锁定、进程管理、日志采集 |
+| 阶段 4 | LLaMA-Factory 训练执行 | YAML/命令生成、进程启动/停止、checkpoint 和 adapter 扫描 |
+| 阶段 5 | 企业治理 | 多租户、项目隔离、审批流、审计留存、配额和资源申请 |
+| 阶段 6 | 多算力节点调度 | 基于 `compute_nodes`、标签、权重、资源副本和节点健康实现调度策略 |
--- a/docs/menu-functional-requirements.md
+++ b/docs/menu-functional-requirements.md
@@ -0,0 +1,98 @@
+# 菜单与功能需求总览
+
+> 本文根据当前前端侧边栏、路由、需求文档、接口文档、部署文档和 SQL 脚本整理。当前代码和 SQL 均按正式系统开发基线维护；Mock、Simulator 只能作为显式联调能力，不作为默认开发准则。
+
+## 1. 菜单分层
+
+### 1.1 当前侧边栏菜单
+
+| 一级分组 | 菜单 | 路由 | 权限码 | 当前状态 | 主要功能 |
+| --- | --- | --- | --- | --- | --- |
+| 服务看板 | 服务看板 | `/dashboard` | `dashboard` | 已有页面，接口需继续完善 | 总览指标、服务状态、训练统计、最近任务、健康入口 |
+| 模型服务 | 模型训练 | `/fine-tune` | `fine-tune` | 已接入主链路 | 训练任务列表、创建训练、启动/停止、进度、训练日志、checkpoint |
+| 模型服务 | 模型评测 | `/model-eval` | `model-eval` | 前端页面已有，后端待完整实现 | 评测任务、评测维度、样本评分、综合结果 |
+| 模型服务 | 模型推理 | `/model-inference` | `model-inference` | 前端页面已有，后端待完整实现 | 推理任务、模型加载、单模型对话、模型对比入口 |
+| 模型服务 | 模型管理 | `/model-manage` | `model-manage` | 已接入主链路 | 基座模型登记、本地/API 模型、训练产物、权重合并、模型导出 |
+| 数据治理 | 数据集管理 | `/dataset` | `dataset` | 已接入主链路 | 数据集列表、上传、预览、在线编辑、版本、下载、删除审批入口 |
+| 数据治理 | 数据处理 | `/data-process` | `data-process` | 前端页面已有，后端待完整实现 | 文档上传、切片预览、LLM 生成、结果编辑、发布数据集 |
+| 其他工具 | 数据类型转换 | `/data-convert` | `data-convert` | 前端页面已有，后端待实现 | JSON/JSONL/Markdown 等格式转换任务 |
+| 算力资源 | 算力节点 | `/compute` | `compute` | 已接入节点管理接口 | 节点地址、权重、标签、启用状态、GPU、队列、资源副本 |
+| 系统设置 | 用户设置 | `/user-settings` | `user-settings` | 已接入基础用户接口 | 用户列表、创建用户、启停、页面权限 |
+| 系统设置 | 平台性能 | `/hardware` | `hardware` | 已有接口，需接真实采集 | CPU、内存、磁盘、GPU、进程、网络监控 |
+| 系统设置 | 查看日志 | `/logs` | `logs` | 已有接口，需接真实日志文件 | 后端日志、error 日志、训练日志索引、日志内容查看 |
+
+### 1.2 当前二级和隐藏路由
+
+| 页面 | 路由 | 归属菜单 | 说明 |
+| --- | --- | --- | --- |
+| 登录 | `/login` | 独立入口 | 登录后进入主界面 |
+| 使用文档 | `/guide` | 独立入口 | 当前系统使用说明 |
+| 创建训练任务 | `/fine-tune/create` | 模型训练 | 训练参数、模型/数据集/GPU 选择 |
+| 训练日志 | `/training-log/:id` | 模型训练 | 日志、指标、checkpoint、任务概览 |
+| 新建评测 | `/model-eval/create` | 模型评测 | 模型、数据集、维度、GPU 选择 |
+| 评测详情 | `/model-eval/:id` | 模型评测 | 维度汇总、样本结果、人工复核预留 |
+| 评测维度创建/编辑 | `/model-eval/dimension/create`、`/model-eval/dimension/:id/edit` | 模型评测 | 评测规则、Prompt、评分器配置 |
+| 新建推理 | `/model-inference/create` | 模型推理 | 推理任务和模型加载配置 |
+| 模型对话 | `/model-inference/chat/:id` | 模型推理 | 单模型对话 |
+| 模型对比 | `/model-compare/chat/:id`、`/model-compare/result` | 模型推理 | 多模型对比和结果页 |
+| 添加/编辑模型 | `/model-manage/create`、`/model-manage/:id/edit` | 模型管理 | 模型登记、用途、来源、路径/API 配置 |
+| 合并权重 | `/model-manage/merge` | 模型管理 | LoRA/Adapter 合并任务 |
+| 数据处理创建/详情 | `/data-process/create`、`/data-process/:id` | 数据处理 | 数据处理向导和任务详情 |
+| 数据集创建/编辑/预览 | `/dataset/create`、`/dataset/:id/edit`、`/dataset/:id/preview` | 数据集管理 | 数据集元数据、文件、版本与内容 |
+| 自定义工具 | `/tools`、`/tools/create`、`/tools/:id/edit` | 规划入口 | 路由存在，当前侧边栏未展示，后续可归入“其他工具” |
+| 算力子页 | `/compute/gpus`、`/compute/queue`、`/compute/nodes` | 算力节点 | 当前可作为页签或深链 |
+| 创建用户/权限设置 | `/user-settings/create`、`/user-settings/:id/permission` | 用户设置 | 用户创建和页面权限 |
+| 无权限页 | `/permission-denied` | 系统页 | 路由守卫无权限跳转 |
+
+### 1.3 企业治理待补菜单
+
+| 建议菜单分组 | 菜单 | 建议路由 | 优先级 | 必要性 |
+| --- | --- | --- | --- | --- |
+| 组织与项目 | 租户管理 | `/tenants`、`/tenants/:id` | P0 | 多租户隔离、配额、留存策略入口 |
+| 组织与项目 | 项目空间 | `/projects`、`/projects/:id`、`/projects/:id/members` | P0 | 项目级模型/数据集/任务隔离 |
+| 组织与项目 | 资源授权 | `/projects/:id/permissions` 或资源详情弹窗 | P0 | 模型/数据集/任务级 ACL |
+| 治理中心 | 审批中心 | `/approvals`、`/approvals/:id` | P0 | 删除、发布、导出、停止他人任务等高风险动作 |
+| 治理中心 | 审批设置 | `/approval-settings` | P1 | 审批模板、审批人规则、超时策略 |
+| 治理中心 | 审计中心 | `/audit-logs`、`/login-logs`、`/download-logs` | P1 | 操作审计、登录审计、下载审计、导出 |
+| 运维中心 | 存储管理 | `/storage` | P1 | 本地磁盘占用、临时文件、checkpoint 清理、留存 |
+| 运维中心 | 训练引擎管理 | `/training-engines` | P2 | LLaMA-Factory 和后续引擎能力 schema、健康检查 |
+| 模型服务 | 模型服务治理 | `/model-services`、`/model-services/:id` | P1 | 测试/生产服务发布、调用统计、下线审批 |
+
+## 2. 菜单对应接口和数据库
+
+| 菜单/模块 | 主要接口 | 当前运行 SQL | 目标 SQL |
+| --- | --- | --- | --- |
+| 登录、用户设置 | `/modelTF/login`、`/modelTF/me`、`/modelTF/users` | `users` | `users`、`login_sessions`、`permissions`、`role_permissions`、`user_permission_overrides` |
+| 服务看板 | `/modelTF/dashboard/overview`、`/modelTF/health` | 复用模型/数据集/任务/算力表 | `system_metric_snapshots`、`web_logs`、各业务表聚合 |
+| 模型管理 | `/modelTF/model-manage`、`/modelTF/model-manage/trained-models`、`/modelTF/model-manage/merge` | `models`、`trained_models` | `models`、`trained_models`、`storage_objects`、`local_import_jobs`、`resource_acl` |
+| 数据集管理 | `/modelTF/dataset-manage`、`/modelTF/dataset-manage/upload/{id}`、`/preview`、`/versions` | `datasets`、`dataset_files` | `datasets`、`dataset_files`、`dataset_file_versions`、`dataset_records`、`storage_objects` |
+| 模型训练 | `/modelTF/fine-tune`、`/start`、`/progress`、`/checkpoints` | `fine_tune_tasks`、`trained_models` | `fine_tune_tasks`、`fine_tune_metrics`、`fine_tune_checkpoints`、`compute_jobs`、`gpu_allocations` |
+| 训练日志 | `/modelTF/training-log-files`、`/modelTF/training-log-content` | 由任务表生成索引 | 日志文件元数据、`fine_tune_metrics`、`audit_logs` |
+| 算力节点 | `/modelTF/compute/nodes`、`/compute/gpus`、`/compute/queue`、`/compute/nodes/{id}/replicas` | `compute_nodes`、`gpus`、`resource_replicas`、`resource_sync_jobs` | `compute_nodes`、`gpu_devices`、`compute_node_engines`、`compute_jobs`、`resource_replicas`、`resource_sync_jobs` |
+| 平台性能 | `/modelTF/system-info`、`/modelTF/compute/gpus` | `gpus`、任务表 | `system_metric_snapshots`、`gpu_devices`、`compute_jobs` |
+| 查看日志 | `/modelTF/log-files`、`/modelTF/log-content`、`/modelTF/web-log` | 文件日志 | `web_logs`、`audit_logs`，大日志进入日志平台 |
+| 模型评测 | `/modelTF/model-eval`、`/modelTF/dimension` | 当前运行 SQL 未覆盖 | `eval_tasks`、`eval_dimensions`、`eval_sample_results`、`eval_dimension_summaries` |
+| 模型推理/对比 | `/modelTF/model-compare`、`/modelTF/model-chat/*` | 当前运行 SQL 未覆盖 | `inference_tasks`、`inference_task_models`、`chat_sessions`、`chat_messages` |
+| 数据处理 | `/modelTF/data-process/*` | 当前运行 SQL 未覆盖 | `data_process_tasks`、`data_process_source_files`、`data_process_preview_items`、`data_process_results` |
+| 数据转换/自定义工具 | `/modelTF/data-convert/jobs`、`/modelTF/tools` | 当前运行 SQL 未覆盖 | `data_convert_jobs`、`custom_tools` |
+| 租户/项目/资源授权 | `/modelTF/tenants`、`/modelTF/projects`、`/modelTF/resources/{type}/{id}/acl` | 当前运行 SQL 未覆盖 | `tenants`、`tenant_users`、`projects`、`project_members`、`resource_acl` |
+| 审批/审计/留存/配额 | `/modelTF/approvals`、`/modelTF/audit-logs`、`/modelTF/retention-policies`、`/modelTF/quotas/usage` | 当前运行 SQL 未覆盖 | `approval_templates`、`approval_instances`、`approval_steps`、`audit_logs`、`retention_policies`、`quotas`、`quota_usage` |
+
+## 3. 文档和脚本检查结论
+
+| 对象 | 当前结论 | 本次补充 |
+| --- | --- | --- |
+| 需求文档 | `docs/platform-architecture-requirements.md` 和 `docs/system-development-plan.md` 已覆盖多租户、项目隔离、审批、审计、多算力节点、应用/算力分离部署；缺少一份按当前菜单组织的总览 | 新增本文作为菜单和功能需求总览 |
+| 接口文档 | `docs/backend-api-design.md` 已统一 `/modelTF`，并已有页面/接口映射；需要明确引用菜单总览，避免开发只看接口不看页面入口 | 在接口文档增加菜单总览引用 |
+| 开发计划 | `docs/system-development-plan.md` 已按工作包列出页面、接口和 DB；需要把本文作为任务认领入口 | 在开发计划增加菜单总览引用 |
+| 部署文档 | `docs/deployment-plan.md`、`docker/README.md` 已覆盖应用/算力分离、单机多 GPU、本地磁盘、真实模式默认、Docker 拆分 | 暂无新增部署配置要求 |
+| 目标 SQL | `docs/postgres-schema.sql` 覆盖完整目标模型，包含用户、权限、多租户、项目、审批、审计、模型、数据集、训练、评测、推理、算力、存储、导入、服务治理 | 暂不需要新增目标表 |
+| 当前运行 SQL | `backend/app/db/sql/001_platform_runtime.sql` 只覆盖已接入运行接口的最小表集 | 后续每实现一个 P0/P1 菜单模块，应同步补运行 SQL 或迁移脚本；不能再以样例数据补功能 |
+
+## 4. 后续补充原则
+
+- 新增侧边栏菜单时，必须同步补齐：路由、权限码、接口文档、DB 表/迁移、审计动作、部署依赖。
+- 新增后端接口时，必须在 `docs/backend-api-design.md` 标注对应页面/功能模块。
+- 新增表结构时，目标模型写入 `docs/postgres-schema.sql`，当前可执行落库写入 `backend/app/db/sql/` 或 Alembic 迁移。
+- 与训练、评测、推理、数据处理相关的异步任务必须落库，不能依赖前端本地状态。
+- 与算力相关的功能默认走真实模式；Simulator 只能显式开启用于隔离联调。
--- a/docs/system-development-plan.md
+++ b/docs/system-development-plan.md
@@ -1038,7 +1038,7 @@ YG_FT/

 ## 16. 页面模块开发工作包

-本节用于多人并行开发时认领任务。每个工作包都标明对应页面、前端内容、后端接口、DB 表和部署/算力依赖。
+本节用于多人并行开发时认领任务。每个工作包都标明对应页面、前端内容、后端接口、DB 表和部署/算力依赖。当前菜单、二级路由、规划菜单和接口/数据库映射总览见 `docs/menu-functional-requirements.md`。

 ### 16.1 基础入口与用户权限