第一次提交

docs/team-development-plan.md

@@ -0,0 +1,208 @@
+# 多人并行开发分工计划
+
+> 本文基于 `docs/menu-functional-requirements.md`、`docs/backend-api-design.md`、`docs/postgres-schema.sql`、`docs/system-development-plan.md` 和当前前端路由整理，用于 3-4 人并行开发。开发口径以正式系统演进为准，不以临时演示或静态 Mock 作为交付标准。
+
+## 1. 分工原则
+
+- 每位开发尽量独立负责一组页面、后端模块、数据库表和联调脚本，避免多人同时改同一个业务文件。
+- 公共接口契约先在 `docs/backend-api-design.md` 更新，再进入代码实现。
+- 前端 API 模块按业务域维护：`system.ts`、`model.ts`、`dataset.ts`、`fineTune.ts`、`compute.ts`、`eval.ts`、`log.ts`。
+- 后端业务代码按 `backend/app/modules/<domain>/` 拆分，路由统一挂载 `/modelTF`。
+- 数据库按迁移脚本推进，目标模型以 `docs/postgres-schema.sql` 为准，当前运行库脚本以 `backend/app/db/sql/` 为准。
+- 所有写操作必须预留审计；涉及删除、导出、发布、停止他人任务等高风险动作必须预留审批入口。
+
+## 2. 4 人开发拆分
+
+### A. 平台基础与企业治理
+
+负责人边界：
+
+- 前端目录：`frontend/src/views/login/`、`frontend/src/views/system/`，后续新增 `tenants`、`projects`、`approvals`、`audit` 页面目录。
+- 前端 API：`frontend/src/api/modules/system.ts`、`frontend/src/api/modules/log.ts`。
+- 后端模块：`auth`、`tenant`、`project`、`approval`、`audit`、`retention`、`system`。
+- 数据库表：`users`、`permissions`、`roles`、`role_permissions`、`user_permission_overrides`、`tenants`、`tenant_users`、`projects`、`project_members`、`resource_acl`、`approval_templates`、`approval_instances`、`approval_steps`、`audit_logs`、`retention_policies`。
+
+对应页面和功能：
+
+| 页面/模块 | 路由 | 功能点 | 接口 |
+| --- | --- | --- | --- |
+| 登录 | `/login` | 登录、Token 写入、登录失败提示、会话恢复 | `POST /modelTF/login`、`GET /modelTF/me` |
+| 用户设置 | `/user-settings`、`/user-settings/create`、`/user-settings/:id/permission` | 用户列表、创建、启停、重置密码、页面权限 | `/modelTF/users/*`、`/modelTF/permissions` |
+| 平台性能 | `/hardware` | 系统资源、进程、GPU 摘要 | `/modelTF/system-info`、`/modelTF/compute/gpus` |
+| 查看日志 | `/logs`、`/training-log/:id` | 后端日志、error 日志、训练日志索引和内容 | `/modelTF/log-files`、`/modelTF/log-content`、`/modelTF/training-log-*` |
+| 租户管理 | `/tenants`、`/tenants/:id` | 租户、配额、留存策略 | `/modelTF/tenants/*`、`/modelTF/retention-policies/*` |
+| 项目空间 | `/projects`、`/projects/:id`、`/projects/:id/members` | 项目、成员、项目角色 | `/modelTF/projects/*` |
+| 资源授权 | `/resources/:type/:id/acl` 或弹窗 | 模型/数据集/任务 ACL | `/modelTF/resources/{type}/{id}/acl` |
+| 审批中心 | `/approvals`、`/approval-settings` | 审批待办、审批历史、审批模板 | `/modelTF/approvals/*`、`/modelTF/approval-templates/*` |
+| 审计中心 | `/audit-logs` | 操作审计、登录审计、导出 | `/modelTF/audit-logs` |
+
+开发计划：
+
+| 阶段 | 交付内容 |
+| --- | --- |
+| 第 1 周 | 完成登录、当前用户、用户列表、权限码、日志查询接口；完善当前运行 SQL。 |
+| 第 2 周 | 完成租户、项目、项目成员、资源 ACL 后端和基础页面。 |
+| 第 3 周 | 完成审批实例、审批模板、审计日志查询和导出。 |
+| 第 4 周 | 接入其他模块写操作审计和审批拦截，补充权限测试。 |
+
+验收标准：
+
+- 所有业务列表按租户、项目、资源 ACL 过滤。
+- 普通用户无法访问未授权项目、模型和数据集。
+- 高风险动作有审批或管理员旁路规则。
+- 日志文件和审计日志可按时间、用户、动作、资源筛选。
+
+### B. 模型资产、训练与 LLaMA-Factory 任务
+
+负责人边界：
+
+- 前端目录：`frontend/src/views/model/`、`frontend/src/views/fine-tune/`。
+- 前端 API：`frontend/src/api/modules/model.ts`、`frontend/src/api/modules/fineTune.ts`。
+- 后端模块：`model`、`fine_tune`、`engine_registry`、`compute_gateway` 中的训练编排部分。
+- 数据库表：`models`、`trained_models`、`fine_tune_tasks`、`fine_tune_metrics`、`fine_tune_checkpoints`、`training_engines`、`training_engine_capabilities`、`compute_jobs`、`gpu_allocations`。
+
+对应页面和功能：
+
+| 页面/模块 | 路由 | 功能点 | 接口 |
+| --- | --- | --- | --- |
+| 模型管理 | `/model-manage` | 基座模型、API 模型、训练产物列表、筛选、删除审批入口 | `/modelTF/model-manage`、`/modelTF/model-manage/trained-models` |
+| 添加/编辑模型 | `/model-manage/create`、`/model-manage/:id/edit` | 模型登记、本地路径/API 配置、能力标签 | `/modelTF/model-manage`、`/modelTF/model-manage/{id}` |
+| 合并权重 | `/model-manage/merge` | LoRA/Adapter 合并、产物登记 | `/modelTF/model-manage/merge` |
+| 模型训练 | `/fine-tune` | 训练任务列表、状态、启动、停止、删除审批入口 | `/modelTF/fine-tune`、`/modelTF/fine-tune/{id}/start`、`/stop` |
+| 创建训练任务 | `/fine-tune/create` | 选择模型、数据集、超参、GPU、节点策略 | `/modelTF/fine-tune`、`/modelTF/model-manage`、`/modelTF/dataset-manage`、`/modelTF/compute/*` |
+| 训练日志 | `/training-log/:id` | 实时日志、loss 曲线、checkpoint、产物 | `/modelTF/fine-tune/{id}/progress`、`/metrics`、`/checkpoints`、`/modelTF/training-log-*` |
+
+开发计划：
+
+| 阶段 | 交付内容 |
+| --- | --- |
+| 第 1 周 | 完成模型 CRUD、训练任务 CRUD、训练参数校验和接口联调。 |
+| 第 2 周 | 完成训练启动、停止、状态轮询、日志和指标落库。 |
+| 第 3 周 | 完成 LLaMA-Factory 参数映射、checkpoint 列表、训练产物登记。 |
+| 第 4 周 | 完成权重合并、失败恢复、权限隔离和审计接入。 |
+
+验收标准：
+
+- 训练任务不能绕过项目、模型、数据集权限。
+- 训练任务状态以应用侧轮询 Compute API 为主。
+- 训练命令只能由训练引擎适配层生成，不在页面或应用 API 中拼命令。
+- checkpoint、日志、产物均可追溯到任务、节点、GPU 和项目。
+
+### C. 数据集、数据处理、评测与推理
+
+负责人边界：
+
+- 前端目录：`frontend/src/views/dataset/`、`frontend/src/views/data-process/`、`frontend/src/views/data-convert/`、`frontend/src/views/eval/`、`frontend/src/views/inference/`、`frontend/src/views/compare/`、`frontend/src/views/tools/`。
+- 前端 API：`dataset.ts`、`eval.ts`、`compare.ts`，必要时新增 `dataProcess.ts`、`dataConvert.ts`、`inference.ts`。
+- 后端模块：`dataset`、`data_process`、`eval`、`inference`、`file_gateway` 中的数据资产登记部分。
+- 数据库表：`datasets`、`dataset_files`、`dataset_file_versions`、`dataset_records`、`data_process_tasks`、`data_process_source_files`、`data_process_preview_items`、`data_process_results`、`data_convert_jobs`、`eval_tasks`、`eval_dimensions`、`eval_sample_results`、`inference_tasks`、`chat_sessions`、`chat_messages`、`custom_tools`。
+
+对应页面和功能：
+
+| 页面/模块 | 路由 | 功能点 | 接口 |
+| --- | --- | --- | --- |
+| 数据集管理 | `/dataset` | 数据集列表、搜索、版本、下载、删除审批入口 | `/modelTF/dataset-manage` |
+| 数据集创建/编辑 | `/dataset/create`、`/dataset/:id/edit` | 元数据、文件上传、格式识别、项目归属 | `/modelTF/dataset-manage`、`/upload/{id}` |
+| 数据集预览 | `/dataset/:id/preview` | 分页预览、在线编辑、版本对比 | `/modelTF/dataset-manage/{id}/preview`、`/versions` |
+| 数据处理 | `/data-process`、`/data-process/create`、`/data-process/:id` | 文档上传、切片、脱敏、质量评分、发布数据集 | `/modelTF/data-process/*` |
+| 数据类型转换 | `/data-convert` | JSON/JSONL/Markdown 转换任务 | `/modelTF/data-convert/jobs/*` |
+| 模型评测 | `/model-eval`、`/model-eval/create`、`/model-eval/:id` | 评测任务、维度、样本级结果、人工复核预留 | `/modelTF/model-eval/*`、`/modelTF/dimension/*` |
+| 模型推理/对比 | `/model-inference/*`、`/model-compare/*` | 模型加载、对话、对比、结果沉淀 | `/modelTF/model-chat/*`、`/modelTF/model-compare/*` |
+| 自定义工具 | `/tools`、`/tools/create`、`/tools/:id/edit` | 工具登记、参数 schema、启停 | `/modelTF/tools/*` |
+
+开发计划：
+
+| 阶段 | 交付内容 |
+| --- | --- |
+| 第 1 周 | 完成数据集 CRUD、上传、预览、版本接口和页面联调。 |
+| 第 2 周 | 完成数据处理任务、切片预览、质量评分和发布数据集。 |
+| 第 3 周 | 完成评测任务、评测维度、样本结果查询。 |
+| 第 4 周 | 完成推理会话、模型对比、数据转换、自定义工具基础能力。 |
+
+验收标准：
+
+- 数据文件必须登记存储对象、checksum、版本和项目归属。
+- 数据处理产物发布为数据集时保留来源链路。
+- 评测和推理必须记录使用的模型版本、数据集版本和参数快照。
+- 下载、删除、导出等动作必须接入审计和审批策略。
+
+### D. 算力平台、部署与运维
+
+负责人边界：
+
+- 前端目录：`frontend/src/views/compute/`，协助 `system/HardwareView.vue`。
+- 前端 API：`frontend/src/api/modules/compute.ts`。
+- 后端模块：`compute_gateway`、`engine_registry`、`file_gateway`、`system` 中的资源采集部分。
+- 算力目录：`compute/api/`、`compute/agent/`、`compute/engines/llama_factory/`、`compute/file_gateway/`。
+- 部署目录：`docker/app/`、`docker/compute/`、`docker/README.md`、`docs/deployment-plan.md`。
+- 数据库表：`compute_nodes`、`gpu_devices`、`compute_node_engines`、`compute_jobs`、`gpu_allocations`、`resource_replicas`、`resource_sync_jobs`、`system_metric_snapshots`、`storage_objects`。
+
+对应页面和功能：
+
+| 页面/模块 | 路由 | 功能点 | 接口 |
+| --- | --- | --- | --- |
+| 算力节点 | `/compute`、`/compute?tab=nodes` | 节点地址、File Gateway 地址、权重、标签、启用状态、连接测试 | `/modelTF/compute/nodes/*` |
+| GPU 资源 | `/compute?tab=gpus`、`/hardware` | GPU 显存、利用率、温度、分配状态、节点归属 | `/modelTF/compute/gpus`、`/modelTF/system-info` |
+| 任务队列 | `/compute?tab=queue` | 队列、优先级、占用 GPU、任务状态 | `/modelTF/compute/queue` |
+| 资源副本 | `/compute` 节点详情 | 模型/数据集在算力节点上的同步状态 | `/modelTF/compute/nodes/{id}/replicas` |
+| 文件网关 | 无独立页面，供模型/数据/训练调用 | 上传、下载、离线导入、产物归档 | 应用侧 `/modelTF/*` 编排，算力侧内部 File Gateway API |
+| 部署运维 | 文档和 Compose | 应用/算力分离部署、端口、镜像、日志、健康检查 | Docker Compose、健康检查接口 |
+
+开发计划：
+
+| 阶段 | 交付内容 |
+| --- | --- |
+| 第 1 周 | 完成 Compute API 健康检查、GPU 发现、节点登记和连接测试。 |
+| 第 2 周 | 完成任务状态查询、应用侧轮询、资源副本状态同步。 |
+| 第 3 周 | 完成 LLaMA-Factory 容器/宿主机路径适配、日志采集、训练进程管理。 |
+| 第 4 周 | 完成应用/算力两套 Docker Compose、部署文档、故障排查脚本。 |
+
+验收标准：
+
+- 多算力节点阶段仍按“每台算力服务器 = 单机多 GPU 节点”设计。
+- 每台算力服务器都部署 Compute API、Agent、File Gateway 和 LLaMA-Factory。
+- 应用服务器只需主动访问所有算力节点，不要求算力节点反向访问应用服务器。
+- 节点地址、权重、标签、启用状态必须可动态维护。
+
+## 3. 3 人开发合并方案
+
+如果团队只有 3 人，建议合并为：
+
+| 开发人员 | 合并内容 | 不建议合并的原因 |
+| --- | --- | --- |
+| A | 平台基础与企业治理 | 该部分是所有模块的权限和隔离底座，不宜再叠加训练或数据主链路。 |
+| B | 模型资产、训练与 LLaMA-Factory 任务 | 模型和训练强耦合，适合一人端到端打通。 |
+| C | 数据集、数据处理、评测、推理、算力部署协同 | 数据链路和评测推理使用相同数据/模型资产；算力底层可先由 C 搭骨架，后续扩人拆出 D。 |
+
+若进入真实 GPU 联调阶段，必须优先把 D 独立出来，否则训练问题、部署问题和业务问题会混在一起，排障效率会明显下降。
+
+## 4. 公共契约和协作节奏
+
+公共契约负责人建议由 A 兼任，所有人遵守：
+
+| 契约 | 文件 | 变更规则 |
+| --- | --- | --- |
+| 路由前缀 | `backend/app/core/config.py`、`backend/app/api/v1/router.py`、接口文档 | 统一 `/modelTF`，不得新增 `/api` 前缀 |
+| 响应结构 | `frontend/src/api/request.ts`、后端 schema | 统一 `{ code, message, data }` |
+| 权限码 | `frontend/src/types/index.ts`、`permissions` 表、接口文档 | 新菜单先登记权限码再开发 |
+| 项目隔离 | `project_id`、`tenant_id`、`resource_acl` | 所有模型、数据集、任务必须带项目归属 |
+| 审计动作 | `audit_logs`、后端审计中间件/服务 | 写操作默认审计 |
+| 异步状态 | 任务表、`compute_jobs` | 统一 `pending/running/completed/failed/stopped` |
+| 文件存储 | `storage_objects`、File Gateway | 不暴露宿主机绝对路径给前端 |
+
+建议节奏：
+
+- 每周一上午同步接口契约和数据库迁移计划。
+- 每天下午固定一次跨模块联调窗口，优先处理阻塞其他人的接口。
+- 每个模块 PR 必须包含页面入口、接口说明、SQL/迁移、最小验证步骤。
+- 公共文件如 `frontend/src/types/index.ts`、`backend/app/core/*`、`docs/backend-api-design.md` 由对应 owner 统一合并，其他人通过小 PR 提交变更。
+
+## 5. 里程碑
+
+| 里程碑 | 目标 | 必须完成 |
+| --- | --- | --- |
+| M1 基础可用 | 用户登录、模型/数据集/训练主链路可运行 | A 登录权限，B 模型训练，C 数据集，D 单节点 GPU 状态 |
+| M2 企业隔离 | 多租户、项目、资源 ACL 接入主链路 | 所有资源按租户/项目过滤，审计落库 |
+| M3 训练闭环 | LLaMA-Factory 真实训练、日志、checkpoint、产物登记 | 应用侧轮询 Compute API，训练产物可在模型管理查看 |
+| M4 治理闭环 | 审批、审计、留存、导出、部署文档完善 | 高风险动作审批，审计可检索，应用/算力分离部署可复现 |
+