# MVP v2.5 API 设计（User + Task + Queue）

v2.5 在 v2.0 API 基础上，新增 **User Management** 与多租户隔离。

约束：
- 仍使用内部 token（API key）；
- 不引入外部 IAM；
- TaskSpec 仍为 YAML（沿用现有结构化字段）。

---

## 1. Auth

Header：
- `Authorization: Bearer <api_token>`

服务端行为：
- 将 `api_token` 映射到 `user_id`
- 之后的 task 操作默认仅作用于该 `user_id`

Admin token（可选）：
- 支持额外配置 `MVP_ADMIN_TOKEN`（或 user.role=admin）
- admin 可跨用户查询/取消（用于运维）。

---

## 2. User Management

### 2.1 创建用户（admin）

`POST /api/v2/users`

Request（JSON）：
```json
{"user_id":"alice","display_name":"Alice"}
```

Response：
```json
{"user_id":"alice","state":"ACTIVE"}
```

### 2.2 为用户签发 token（admin）

`POST /api/v2/users/{user_id}/tokens`

Response（只返回一次明文 token）：
```json
{"user_id":"alice","token":"mvp_u_..."}
```

### 2.3 禁用用户（admin）

`POST /api/v2/users/{user_id}:disable`

---

## 3. Task Management（多租户）

### 3.1 提交任务

`POST /api/v2/tasks`

Body：
- `Content-Type: application/yaml`
- raw TaskSpec YAML（训练语义字段；不含 user_id）

Response：
```json
{"task_id":"mvp25-ppo-20251225-170001-2a3f","state":"QUEUED"}
```

服务端 side effects：
- 记录 tasks.user_id（由 token 得到）
- 计算输出目录：`/private/users/<uid>/jobs/<ray_submission_id>/...`

### 3.2 查询任务（仅本人）

`GET /api/v2/tasks/{task_id}`

若 task 不属于当前 user：
- 返回 `404`（避免泄露存在性）

### 3.3 取消任务（仅本人）

`POST /api/v2/tasks/{task_id}:cancel`

---

## 4. Queue/Debug

### 4.1 查看队列（本人视角）

`GET /api/v2/queue`

返回该 user 的 pending/running 列表。

### 4.2 管理员查看全局队列（admin）

`GET /api/v2/admin/queue`

---

## 5. Logs

`GET /api/v2/tasks/{task_id}/logs?attempt=latest&tail=2000`

行为与 v2.0 一致：透传 Ray Job logs tail。