# 文件接口（上传 / 列目录 / 下载）

API v1 只提供最小化的文件能力，用于把外部输入文件放入工作区，并下载产物。

核心限制：

- **上传只能落在 `project/user_upload/` 目录及其子目录**；
- 列目录/下载也只允许访问 `user_upload` 内部路径（路径穿越会被拒绝）。

> 目录结构见 `auth.md`。

## 1) 上传文件

### POST `/api/v1/files/upload`

#### 请求

- Headers：`Authorization: Bearer <TOKEN>`
- Content-Type：`multipart/form-data`
- Form 字段：
  - `file`：必填，上传的文件对象
  - `filename`：可选，覆盖原文件名（会做安全清洗）
  - `dir`：可选，`user_upload` 下的子目录（例如 `docs/`）；不传则落在 `user_upload/` 根目录

> 如果你希望“完全不允许指定目录”，客户端请不要传 `dir`，统一上传到根目录即可。

#### 响应

成功（200）：

```json
{
  "success": true,
  "path": "docs/spec.pdf",
  "filename": "spec.pdf",
  "size": 12345,
  "sha256": "..."
}
```

字段说明：

- `path`：相对 `user_upload` 的路径（用于 list/download）
- `sha256`：服务端计算的文件哈希（便于客户端校验/去重）

可能错误：

- `400`：缺少 file / 文件名非法 / 目录非法
- `401`：缺少或无效 token
- `503`：系统未初始化
- `500`：保存失败（例如写入异常、扫描/隔离异常等）

#### curl 示例

上传到根目录：

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

上传到子目录：

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

## 2) 列出目录内容

### GET `/api/v1/files?path=<dir>`

#### 请求

- Headers：`Authorization: Bearer <TOKEN>`
- Query：
  - `path`：可选，相对 `user_upload` 的目录路径；不传表示根目录

#### 响应

成功（200）：

```json
{
  "success": true,
  "base": "inputs",
  "items": [
    {
      "name": "hello.txt",
      "is_dir": false,
      "size": 16,
      "modified_at": 1769182550.594278,
      "path": "inputs/hello.txt"
    }
  ]
}
```

字段说明：

- `base`：你请求的目录（相对 `user_upload`），根目录时为 `.`
- `items[].path`：相对 `user_upload` 的路径（用于下载或继续列目录）
- `modified_at`：文件 mtime（UNIX 秒）

可能错误：

- `400`：path 不是目录或 path 非法
- `401`：缺少或无效 token
- `404`：目录不存在
- `503`：系统未初始化

#### curl 示例

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

## 3) 下载文件/目录

### GET `/api/v1/files/download?path=<file_or_dir>`

#### 请求

- Headers：`Authorization: Bearer <TOKEN>`
- Query：
  - `path`：必填，相对 `user_upload` 的文件或目录路径

#### 响应

1) 若 `path` 指向文件：返回文件二进制流（`Content-Disposition: attachment`）。  
2) 若 `path` 指向目录：服务端会把目录打包成 zip 后返回（`application/zip`）。

可能错误：

- `400`：缺少 path 或 path 非法
- `401`：缺少或无效 token
- `404`：文件/目录不存在
- `503`：系统未初始化

#### curl 示例

下载文件：

```bash
curl -L -o out.txt \
  -H "Authorization: Bearer <TOKEN>" \
  "http://localhost:8091/api/v1/files/download?path=hello.txt"
```

下载目录（zip）：

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

> zip 内的路径目前是相对 `project/` 的（因此通常会包含 `user_upload/` 前缀）。