# 文件 API（工作区内，仅 user_upload）

文件读写是**工作区级**的：上传/列目录/下载都发生在指定 workspace 的 `project/user_upload/` 下。

鉴权：所有接口均需要 `Authorization: Bearer <TOKEN>`

---

## 1) 上传文件

### POST `/api/v1/workspaces/{workspace_id}/files/upload`

说明：

- 不指定“任意路径上传”，只能上传到该 workspace 的 `user_upload` 目录（以及其子目录）。

请求（multipart/form-data）：

- Headers：
  - `Authorization: Bearer <TOKEN>`
- Form：
  - `file`：文件本体（必填）
  - `filename`：可选，自定义文件名（服务端会清洗）
  - `dir`：可选，user_upload 下子目录（如 `inputs` / `a/b`）

成功响应（200）：

```json
{
  "success": true,
  "workspace_id": "ws1",
  "path": "inputs/hello.txt",
  "filename": "hello.txt",
  "size": 16,
  "sha256": "0f5bd6..."
}
```

---

## 2) 列出目录内容

### GET `/api/v1/workspaces/{workspace_id}/files?path=<dir>`

说明：

- `path` 是 `user_upload` 下的相对路径；不传或传空则表示根目录。

成功响应（200）：

```json
{
  "success": true,
  "workspace_id": "ws1",
  "base": "inputs",
  "items": [
    { "name": "hello.txt", "is_dir": false, "size": 16, "modified_at": 1769182550.59, "path": "inputs/hello.txt" },
    { "name": "images", "is_dir": true, "size": 64, "modified_at": 1769182552.01, "path": "inputs/images" }
  ]
}
```

常见错误：

- `404`：路径不存在
- `400`：path 指向文件（不是目录）或非法路径

---

## 3) 下载文件或目录

### GET `/api/v1/workspaces/{workspace_id}/files/download?path=<file_or_dir>`

说明：

- `path` 是 `user_upload` 下相对路径
- 若 `path` 是文件：直接下载该文件
- 若 `path` 是目录：服务端打包为 zip 返回

成功响应：

- 文件：`Content-Type: application/octet-stream`
- 目录：`Content-Type: application/zip`

---

## curl 示例

上传到 `ws1/user_upload/inputs/hello.txt`：

```bash
curl -sS -X POST \
  -H "Authorization: Bearer <TOKEN>" \
  -F "file=@hello.txt" \
  -F "dir=inputs" \
  http://localhost:8091/api/v1/workspaces/ws1/files/upload
```

列出 `ws1/user_upload/inputs`：

```bash
curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  "http://localhost:8091/api/v1/workspaces/ws1/files?path=inputs"
```

下载目录 `ws1/user_upload/inputs`：

```bash
curl -L -o inputs.zip \
  -H "Authorization: Bearer <TOKEN>" \
  "http://localhost:8091/api/v1/workspaces/ws1/files/download?path=inputs"
```