# 文件管理 API 接口文档

**Base URL:** `/api/v1/file-manager`

---

## 1. 列出目录内容

**GET** `/api/v1/file-manager/list`

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| path | string | query | 否 | 相对路径，空字符串返回根目录（projects/prompt） |
| recursive | bool | query | 否 | 是否递归列出子目录，默认 false |

```bash
curl -X GET "/api/v1/file-manager/list?path=projects&recursive=false"
```

响应示例：
```json
{
  "success": true,
  "path": "projects",
  "items": [
    {
      "name": "report.pdf",
      "path": "projects/report.pdf",
      "type": "file",
      "size": 102400,
      "modified": 1700000000.0,
      "created": 1699000000.0
    }
  ],
  "total": 1
}
```

---

## 2. 上传文件

**POST** `/api/v1/file-manager/upload`

请求方式：表单数据上传（multipart/form-data）

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| file | file | form | 是 | 上传的文件 |
| path | string | form | 否 | 目标目录路径，默认 `projects` |

```bash
curl -X POST "/api/v1/file-manager/upload" \
  -F "file=@document.pdf" \
  -F "path=projects/dataset"
```

响应示例：
```json
{
  "success": true,
  "message": "文件上传成功",
  "filename": "document.pdf",
  "original_filename": "document.pdf",
  "path": "projects/dataset/document.pdf",
  "size": 102400
}
```

> 注：文件名中的空格会自动替换为下划线。

---

## 3. 下载文件

**GET** `/api/v1/file-manager/download/{file_path}`

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| file_path | string | path | 是 | 文件相对路径 |

```bash
curl -X GET "/api/v1/file-manager/download/projects/report.pdf" -o report.pdf
```

响应：文件二进制流，`Content-Type` 根据文件类型自动推断。

---

## 4. 删除文件或目录

**DELETE** `/api/v1/file-manager/delete`

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| path | string | query | 是 | 要删除的路径 |

```bash
curl -X DELETE "/api/v1/file-manager/delete?path=projects/report.pdf"
```

响应示例：
```json
{
  "success": true,
  "message": "文件删除成功",
  "path": "projects/report.pdf"
}
```

---

## 5. 创建文件夹

**POST** `/api/v1/file-manager/create-folder`

请求方式：JSON

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| path | string | body | 否 | 父目录路径，默认 `projects` |
| name | string | body | 是 | 文件夹名称 |

```bash
curl -X POST "/api/v1/file-manager/create-folder" \
  -H "Content-Type: application/json" \
  -d '{"path": "projects", "name": "new-folder"}'
```

响应示例：
```json
{
  "success": true,
  "message": "文件夹创建成功",
  "path": "projects/new-folder"
}
```

---

## 6. 重命名文件或文件夹

**POST** `/api/v1/file-manager/rename`

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| old_path | string | query | 是 | 原路径 |
| new_name | string | query | 是 | 新名称 |

```bash
curl -X POST "/api/v1/file-manager/rename?old_path=projects/old-name.pdf&new_name=new-name.pdf"
```

响应示例：
```json
{
  "success": true,
  "message": "重命名成功",
  "old_path": "projects/old-name.pdf",
  "new_path": "projects/new-name.pdf"
}
```

---

## 7. 移动文件或文件夹

**POST** `/api/v1/file-manager/move`

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| source_path | string | query | 是 | 源路径 |
| target_path | string | query | 是 | 目标路径 |

```bash
curl -X POST "/api/v1/file-manager/move?source_path=projects/a.pdf&target_path=projects/sub/a.pdf"
```

响应示例：
```json
{
  "success": true,
  "message": "移动成功",
  "source_path": "projects/a.pdf",
  "target_path": "projects/sub/a.pdf"
}
```

---

## 8. 复制文件或文件夹

**POST** `/api/v1/file-manager/copy`

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| source_path | string | query | 是 | 源路径 |
| target_path | string | query | 是 | 目标路径 |

```bash
curl -X POST "/api/v1/file-manager/copy?source_path=projects/a.pdf&target_path=projects/a-copy.pdf"
```

响应示例：
```json
{
  "success": true,
  "message": "复制成功",
  "source_path": "projects/a.pdf",
  "target_path": "projects/a-copy.pdf"
}
```

---

## 9. 搜索文件

**GET** `/api/v1/file-manager/search`

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| query | string | query | 是 | 搜索关键词（匹配文件名） |
| path | string | query | 否 | 搜索路径，为空则搜索所有支持目录 |
| file_type | string | query | 否 | 文件类型过滤（如 `.pdf`） |

```bash
curl -X GET "/api/v1/file-manager/search?query=report&path=projects&file_type=.pdf"
```

响应示例：
```json
{
  "success": true,
  "query": "report",
  "path": "projects",
  "results": [
    {
      "name": "report.pdf",
      "path": "projects/report.pdf",
      "type": "file"
    }
  ],
  "total": 1
}
```

---

## 10. 读取文件内容

**GET** `/api/v1/file-manager/read`

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| path | string | query | 是 | 文件相对路径 |

```bash
curl -X GET "/api/v1/file-manager/read?path=projects/config.json"
```

响应示例：
```json
{
  "success": true,
  "content": "{\"key\": \"value\"}",
  "path": "projects/config.json",
  "size": 16,
  "modified": 1700000000.0,
  "encoding": "utf-8",
  "mime_type": "application/json"
}
```

> 限制：最大 10MB。自动尝试 utf-8 / gbk / gb2312 / latin-1 编码。

---

## 11. 保存文件内容

**POST** `/api/v1/file-manager/save`

请求方式：JSON

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| path | string | body | 是 | 文件相对路径 |
| content | string | body | 是 | 文件内容 |

```bash
curl -X POST "/api/v1/file-manager/save" \
  -H "Content-Type: application/json" \
  -d '{"path": "projects/config.json", "content": "{\"key\": \"new-value\"}"}'
```

响应示例：
```json
{
  "success": true,
  "message": "文件保存成功",
  "path": "projects/config.json",
  "size": 20,
  "modified": 1700000000.0,
  "encoding": "utf-8"
}
```

> 限制：最大 5MB。保存前自动创建备份，写入失败时自动回滚。

---

## 12. 获取文件/文件夹详细信息

**GET** `/api/v1/file-manager/info/{file_path}`

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| file_path | string | path | 是 | 文件或文件夹路径 |

```bash
curl -X GET "/api/v1/file-manager/info/projects/report.pdf"
```

响应示例：
```json
{
  "success": true,
  "info": {
    "name": "report.pdf",
    "path": "projects/report.pdf",
    "type": "file",
    "size": 102400,
    "modified": 1700000000.0,
    "created": 1699000000.0,
    "permissions": "644",
    "mime_type": "application/pdf",
    "preview": "文件前1000字符预览..."
  }
}
```

> 小于 1MB 的文本文件会包含 `preview` 字段。

---

## 13. 下载文件夹为 ZIP

**POST** `/api/v1/file-manager/download-folder-zip`

请求方式：JSON

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| path | string | body | 是 | 文件夹路径 |

```bash
curl -X POST "/api/v1/file-manager/download-folder-zip" \
  -H "Content-Type: application/json" \
  -d '{"path": "projects/dataset"}' -o dataset.zip
```

响应：ZIP 文件二进制流（`application/zip`）。

> 限制：最大 500MB，最多 10000 个文件。

---

## 14. 批量下载为 ZIP

**POST** `/api/v1/file-manager/download-multiple-zip`

请求方式：JSON

| 参数 | 类型 | 位置 | 必填 | 说明 |
|------|------|------|------|------|
| paths | string[] | body | 是 | 文件/文件夹路径数组 |
| filename | string | body | 否 | ZIP 文件名，默认 `batch_download.zip` |

```bash
curl -X POST "/api/v1/file-manager/download-multiple-zip" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["projects/a.pdf", "projects/sub"], "filename": "export.zip"}' \
  -o export.zip
```

响应：ZIP 文件二进制流（`application/zip`）。

> 限制：最大 500MB，最多 10000 个文件。

---

## 15. 批量操作

**POST** `/api/v1/file-manager/batch-operation`

请求方式：JSON（操作数组）

支持操作类型：`delete` / `move` / `copy`

```bash
curl -X POST "/api/v1/file-manager/batch-operation" \
  -H "Content-Type: application/json" \
  -d '[
    {"type": "delete", "path": "projects/old.pdf"},
    {"type": "move", "source_path": "projects/a.pdf", "target_path": "projects/archive/a.pdf"},
    {"type": "copy", "source_path": "projects/b.pdf", "target_path": "projects/backup/b.pdf"}
  ]'
```

响应示例：
```json
{
  "success": true,
  "results": [
    {"type": "delete", "success": true, "message": "删除成功"},
    {"type": "move", "success": true, "message": "移动成功"},
    {"type": "copy", "success": true, "message": "复制成功"}
  ],
  "total": 3,
  "successful": 3
}
```

---

## 通用说明

- **路径约束**：所有路径必须以 `projects` 或 `prompt` 开头，否则返回 400
- **安全机制**：路径经过规范化处理，防止目录遍历攻击
- **隐藏文件**：以 `.` 开头的文件/目录在列出和搜索时自动跳过
- **错误响应格式**：
```json
{
  "detail": "错误描述信息"
}
```