# MVP v3.0 — API 扩展设计（基于 v2.5）

v3.0 的原则是：**尽量复用 v2.5 API**，只增量增加 “数据闭环” 与 “WebUI 支持” 所需的最小接口。

## 1) 认证与权限

沿用 v2.5：
- Header：`Authorization: Bearer <token>`
- admin token：来自 `MVP_INTERNAL_TOKEN`
- 普通用户 token：由 admin 颁发并持久化在 SQLite

权限规则：
- 非 admin：只能访问自己的 task、自己的数据空间（`/private/users/<user_id>/...`）。
- 跨用户访问返回 404（不泄露存在性）。

## 2) 用户与 SFTPGo 联动（管理员接口）

### 2.1 创建用户（复用 v2.5）
`POST /api/v2/users`
- v3.0 行为：成功后，**可选**联动创建 SFTPGo 用户
  - v3.0 默认启用联动：创建 SFTPGo 用户 + 生成一次性密码（password 认证）
  - v3.0 仅保留该方案（方案 A）：不做外部认证/SSO 集成（留到更后续版本）
  - `data.sftpgo.admin_api_base` 推荐形如：`http://argus-sftpgo:8080/api/v2`（包含 `/api/v2` 前缀）

### 2.2 下发 token（复用 v2.5）
`POST /api/v2/users/{user_id}/tokens`

### 2.3 禁用用户（复用 v2.5）
`POST /api/v2/users/{user_id}:disable`
- v3.0 行为：联动禁用 SFTPGo 用户（可选）

### 2.4 SFTP 凭据管理（新增，管理员或用户自助）
（具体由你确认 v3.0 需要“用户自助”还是“管理员操作”）

#### 重置 SFTP 密码（管理员）
`POST /api/v2/users/{user_id}/sftp:reset_password`
- 返回：一次性密码（只返回一次，服务端不保存明文）
> v3.0 先只做 password 方案；SSH public key 作为后续版本可选增强（不在 v3.0 范围）。

## 3) 用户自助信息（新增）

### 3.1 获取当前用户信息
`GET /api/v2/me`
- 返回示例：
```json
{
  "user_id": "alice",
  "is_admin": false,
  "paths": {
    "home": "/private/users/alice",
    "datasets": "/private/users/alice/datasets",
    "models": "/private/users/alice/models",
    "code": "/private/users/alice/code",
    "jobs": "/private/users/alice/jobs",
    "trash_jobs": "/private/users/alice/trash/jobs"
  },
  "retention": {
    "jobs_trash_after_days": 3,
    "jobs_purge_after_days": 7
  },
  "sftp": {
    "host": "h1.example.internal",
    "port": 2022,
    "username": "alice"
  }
}
```

## 3.2 Jobs Retention 提示（新增）
为了支撑 WebUI 展示与用户预期管理，可在 `/api/v2/me` 或单独接口返回：
- `jobs_trash_after_days`：默认 3
- `jobs_purge_after_days`：默认 7
- `jobs_root`：`/private/users/<me>/jobs`
- `trash_jobs_root`：`/private/users/<me>/trash/jobs`
- `recommendations`：提示用户把需要长期保存的产物移动到 `models/` 或 `datasets/`

## 4) 数据浏览/下载（可选，v3.0 最小化）

说明：上传/下载主通道仍是 SFTP。  
WebUI 如果要提供“快速浏览/查看”，可实现只读接口（避免实现大文件上传/断点等复杂逻辑）。

### 4.1 列目录
`GET /api/v2/files?path=/private/users/alice`
- 权限：path 必须在 `/private/common/` 或 `/private/users/<me>/` 下
- 返回：文件列表（name/type/size/mtime）

### 4.2 下载文件（小文件为主）
`GET /api/v2/files:download?path=/private/users/alice/jobs/.../logs/...`
- 返回：流式下载
- 大文件仍建议走 SFTP

## 5) TaskSpec 路径校验升级（v3.0 关键）

v2.5：仅允许 `/private/common/...`  
v3.0：允许 `/private/common/...` 与 `/private/users/<me>/...`

应用字段（至少）：
- `train_file` / `val_file`
- `code_path`：仍仅允许 `/private/common/...`（v3.0 不支持执行用户 code）
- 本地模型路径字段（如果引入）：允许 `/private/users/<me>/models/...`

## 6) WebUI 路由（新增）

由 API server 托管：
- `GET /ui`：主页面
- `GET /ui/login`：token 登录页
- 静态资源：`/ui/static/...`

WebUI 的所有操作均调用同源 API（不额外开 CORS）。