YG_FT/docs/team-development-plan.md

多人并行开发分工计划

本文基于 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 治理闭环	审批、审计、留存、导出、部署文档完善	高风险动作审批，审计可检索，应用/算力分离部署可复现