# MVP v2.5 开发/部署/验收标准

本文件定义 v2.5 的“可验证闭环”，确保每个里程碑可验收。

---

## 1. 开发交付物（Deliverables）

### 1.1 代码交付（建议）

- API Server 增强：user management + task 关联 user_id + 鉴权隔离
- SQLite schema 迁移：新增 users/tokens，tasks 增加 user_id
- Ray Head service discovery：head.json 写入与心跳刷新
- Worker bootstrap + watchdog：
  - dev：以脚本方式提供（docker compose 场景）
  - prod：以容器 command/entrypoint 方式可注入

### 1.2 文档交付

- 目录结构与 GPFS 路径约定
- API 文档（含用户与多租户隔离）
- 运维 SOP：head 重启、worker 自愈、如何排障 head.json

---

## 2. 部署流程（Dev 环境可验证）

### 2.1 启动顺序（推荐）

1) 启动 head（包含 API server + Ray head）
2) head 写入 `/private/ray/discovery/<cluster_name>/head.json`
3) 启动若干 worker（无须指定 head 地址）
4) worker 自动读取 head.json 并加入集群
5) 通过 API 创建用户并获取 token
6) 使用 user token 提交 PPO/GRPO/SFT

---

## 3. 验收标准（Acceptance Criteria）

### 3.1 Stateless Ray Node Pool

- A1：在 worker 启动时不传 head 地址，worker 能在 `T<=60s` 内加入集群（ray status 可见）
- A2：head 容器重启（IP 变化或 Ray 重启）后：
  - head.json 更新
  - worker watchdog 在 `T<=60s` 内自动重连
- A3：head 设置 `--num-gpus=0 --num-cpus=0`，训练 driver 不会跑到 head（可通过 Ray dashboard/日志验证）

### 3.2 User Management

- U1：admin 可创建用户并签发 token（token 仅返回一次）
- U2：用户 A 提交的 task，用户 B 无法查询/取消/获取日志（API 返回 404 或 403，按设计约定）
- U3：仅隔离 jobs 输出：任务输出落在 `/private/users/<user_id>/jobs/<ray_submission_id>/...`，不同用户互不覆盖
- U4：训练输入（verl 代码、HF cache、datasets）统一使用 `/private/common/...`（v2.5 不做输入隔离）

### 3.3 Task Flow（继承 v2.0）

- T1：PPO/GRPO/SFT 三种 workload 都能成功提交并跑通（dev 规模可用 epoch=1/steps=10）
- T2：资源不足时任务不会“直接失败不可恢复”，而是进入 `PENDING_RESOURCES` 并按间隔重试（与 v2.0 同逻辑）

---

## 4. 回归用例（最小集合）

1) 创建用户 alice/bob，分别提交 sft，验证隔离与输出目录
2) 启动 head + 2 workers，提交 ppo/grpo，验证 driver 落 worker
3) 重启 head（或修改 head.json 指向新 IP），验证 worker watchdog 自动重连