feat: 1. 完善起草合同页面的逻辑交互，对接minio的接口操作

2025-12-05 20:17:37 +08:00
parent 3d1dbb3f97
commit 91b7518c99
21 changed files with 1249 additions and 1057 deletions
@@ -0,0 +1,776 @@
+# MinIO 存储管理 API 文档
+
+## 概述
+
+MinIO 存储管理模块提供对象存储的完整管理能力，包括存储桶管理和文件操作。
+
+**基础路径**: `/api/v2/storage`
+
+**认证要求**: 当前无需认证（后续可按需添加）
+
+---
+
+## 接口列表
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/buckets` | 创建存储桶 |
+| DELETE | `/buckets` | 删除存储桶 |
+| GET | `/buckets` | 列出所有存储桶 |
+| POST | `/files/copy` | 复制文件 |
+| POST | `/files/move` | 移动/重命名文件 |
+| DELETE | `/files` | 删除单个文件 |
+| POST | `/files/batch-delete` | 批量删除文件 |
+| GET | `/files/download` | 下载文件 |
+| GET | `/files` | 列出目录文件 |
+| GET | `/files/metadata` | 获取文件元数据 |
+| GET | `/files/presigned-url` | 获取预签名URL |
+
+---
+
+## 存储桶管理
+
+### 1. 创建存储桶
+
+**POST** `/api/v2/storage/buckets`
+
+创建新的 MinIO 存储桶。
+
+#### 请求体
+
+```json
+{
+  "bucket_name": "my-new-bucket"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| bucket_name | string | 是 | 存储桶名称（3-63字符，小写字母、数字、连字符） |
+
+#### 响应示例
+
+**成功 (200)**
+```json
+{
+  "success": true,
+  "message": "存储桶创建成功",
+  "bucket_name": "my-new-bucket"
+}
+```
+
+**存储桶已存在 (200)**
+```json
+{
+  "success": false,
+  "message": "存储桶已存在: my-new-bucket",
+  "bucket_name": "my-new-bucket"
+}
+```
+
+#### cURL 示例
+
+```bash
+curl -X POST "http://localhost:8000/api/v2/storage/buckets" \
+  -H "Content-Type: application/json" \
+  -d '{"bucket_name": "my-new-bucket"}'
+```
+
+---
+
+### 2. 删除存储桶
+
+**DELETE** `/api/v2/storage/buckets`
+
+删除 MinIO 存储桶。支持强制删除（会先删除桶内所有文件）。
+
+#### 请求体
+
+```json
+{
+  "bucket_name": "my-bucket",
+  "force": true
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| bucket_name | string | 是 | 存储桶名称 |
+| force | boolean | 否 | 强制删除（默认 false，为 true 时会先删除桶内所有文件） |
+
+#### 响应示例
+
+**成功 (200)**
+```json
+{
+  "success": true,
+  "message": "存储桶删除成功",
+  "bucket_name": "my-bucket",
+  "files_deleted": 15
+}
+```
+
+**存储桶不存在 (200)**
+```json
+{
+  "success": false,
+  "message": "存储桶不存在: my-bucket",
+  "bucket_name": "my-bucket",
+  "files_deleted": 0
+}
+```
+
+#### cURL 示例
+
+```bash
+# 普通删除（桶必须为空）
+curl -X DELETE "http://localhost:8000/api/v2/storage/buckets" \
+  -H "Content-Type: application/json" \
+  -d '{"bucket_name": "my-bucket"}'
+
+# 强制删除（会删除桶内所有文件）
+curl -X DELETE "http://localhost:8000/api/v2/storage/buckets" \
+  -H "Content-Type: application/json" \
+  -d '{"bucket_name": "my-bucket", "force": true}'
+```
+
+---
+
+### 3. 列出存储桶
+
+**GET** `/api/v2/storage/buckets`
+
+列出所有 MinIO 存储桶。
+
+#### 响应示例
+
+```json
+{
+  "success": true,
+  "message": "共 3 个存储桶",
+  "buckets": [
+    {
+      "name": "docauditai",
+      "creation_date": "2024-01-15T08:30:00+00:00"
+    },
+    {
+      "name": "backup",
+      "creation_date": "2024-02-20T10:15:00+00:00"
+    },
+    {
+      "name": "temp",
+      "creation_date": "2024-03-01T14:00:00+00:00"
+    }
+  ]
+}
+```
+
+#### cURL 示例
+
+```bash
+curl -X GET "http://localhost:8000/api/v2/storage/buckets"
+```
+
+---
+
+## 文件操作
+
+### 4. 复制文件
+
+**POST** `/api/v2/storage/files/copy`
+
+在 MinIO 内复制文件。支持跨存储桶复制。
+
+#### 请求体
+
+```json
+{
+  "source_path": "documents/contract.pdf",
+  "destination_path": "backup/contract-2024.pdf",
+  "source_bucket": null,
+  "destination_bucket": null
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| source_path | string | 是 | 源文件路径 |
+| destination_path | string | 是 | 目标文件路径 |
+| source_bucket | string | 否 | 源存储桶（默认使用配置的默认桶） |
+| destination_bucket | string | 否 | 目标存储桶（默认使用配置的默认桶） |
+
+#### 响应示例
+
+```json
+{
+  "success": true,
+  "message": "文件复制成功",
+  "source_path": "docauditai/documents/contract.pdf",
+  "destination_path": "docauditai/backup/contract-2024.pdf"
+}
+```
+
+#### cURL 示例
+
+```bash
+# 同桶内复制
+curl -X POST "http://localhost:8000/api/v2/storage/files/copy" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_path": "documents/contract.pdf",
+    "destination_path": "backup/contract-2024.pdf"
+  }'
+
+# 跨桶复制
+curl -X POST "http://localhost:8000/api/v2/storage/files/copy" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_path": "documents/contract.pdf",
+    "destination_path": "contract.pdf",
+    "source_bucket": "docauditai",
+    "destination_bucket": "backup"
+  }'
+```
+
+---
+
+### 5. 移动/重命名文件
+
+**POST** `/api/v2/storage/files/move`
+
+移动文件（复制后删除源文件）。在同一目录内移动即为重命名。
+
+#### 请求体
+
+```json
+{
+  "source_path": "documents/old-name.pdf",
+  "destination_path": "documents/new-name.pdf"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| source_path | string | 是 | 源文件路径 |
+| destination_path | string | 是 | 目标文件路径 |
+
+#### 响应示例
+
+```json
+{
+  "success": true,
+  "message": "文件移动成功",
+  "source_path": "documents/old-name.pdf",
+  "destination_path": "documents/new-name.pdf"
+}
+```
+
+#### cURL 示例
+
+```bash
+# 重命名文件
+curl -X POST "http://localhost:8000/api/v2/storage/files/move" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_path": "documents/report-v1.pdf",
+    "destination_path": "documents/report-v2.pdf"
+  }'
+
+# 移动到其他目录
+curl -X POST "http://localhost:8000/api/v2/storage/files/move" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source_path": "temp/upload.pdf",
+    "destination_path": "documents/final.pdf"
+  }'
+```
+
+---
+
+### 6. 删除单个文件
+
+**DELETE** `/api/v2/storage/files`
+
+删除 MinIO 中的单个文件。
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file_path | string | 是 | 文件路径 |
+
+#### 响应示例
+
+**成功 (200)**
+```json
+{
+  "success": true,
+  "message": "文件删除成功",
+  "file_path": "documents/old-file.pdf"
+}
+```
+
+**文件不存在 (200)**
+```json
+{
+  "success": false,
+  "message": "文件不存在: documents/old-file.pdf",
+  "file_path": "documents/old-file.pdf"
+}
+```
+
+#### cURL 示例
+
+```bash
+curl -X DELETE "http://localhost:8000/api/v2/storage/files?file_path=documents/old-file.pdf"
+```
+
+---
+
+### 7. 批量删除文件
+
+**POST** `/api/v2/storage/files/batch-delete`
+
+批量删除多个文件。
+
+#### 请求体
+
+```json
+{
+  "file_paths": [
+    "temp/file1.pdf",
+    "temp/file2.pdf",
+    "temp/file3.pdf"
+  ]
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file_paths | string[] | 是 | 文件路径列表（至少1个） |
+
+#### 响应示例
+
+```json
+{
+  "success": true,
+  "message": "删除完成: 成功 3, 失败 0",
+  "deleted_count": 3,
+  "failed_count": 0,
+  "failed_paths": []
+}
+```
+
+**部分失败 (200)**
+```json
+{
+  "success": false,
+  "message": "删除完成: 成功 2, 失败 1",
+  "deleted_count": 2,
+  "failed_count": 1,
+  "failed_paths": ["temp/not-exist.pdf"]
+}
+```
+
+#### cURL 示例
+
+```bash
+curl -X POST "http://localhost:8000/api/v2/storage/files/batch-delete" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "file_paths": [
+      "temp/file1.pdf",
+      "temp/file2.pdf",
+      "temp/file3.pdf"
+    ]
+  }'
+```
+
+---
+
+### 8. 下载文件
+
+**GET** `/api/v2/storage/files/download`
+
+从 MinIO 下载文件。返回文件流。
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file_path | string | 是 | 文件路径 |
+| filename | string | 否 | 下载时显示的文件名 |
+
+#### 响应
+
+返回文件二进制流，包含以下响应头：
+
+```
+Content-Type: application/pdf
+Content-Disposition: attachment; filename="contract.pdf"
+Content-Length: 1234567
+```
+
+#### cURL 示例
+
+```bash
+# 下载文件
+curl -X GET "http://localhost:8000/api/v2/storage/files/download?file_path=documents/contract.pdf" \
+  -o contract.pdf
+
+# 指定下载文件名
+curl -X GET "http://localhost:8000/api/v2/storage/files/download?file_path=documents/contract.pdf&filename=my-contract.pdf" \
+  -o my-contract.pdf
+```
+
+#### 浏览器直接下载
+
+```
+http://localhost:8000/api/v2/storage/files/download?file_path=documents/contract.pdf
+```
+
+---
+
+### 9. 列出目录文件
+
+**GET** `/api/v2/storage/files`
+
+列出指定目录下的文件。
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| directory_path | string | 否 | "" | 目录路径 |
+| recursive | boolean | 否 | false | 是否递归列出子目录 |
+| max_files | int | 否 | 100 | 最大返回数量（1-1000） |
+| marker | string | 否 | null | 分页标记 |
+
+#### 响应示例
+
+```json
+{
+  "success": true,
+  "message": "共 5 个文件",
+  "files": [
+    "documents/contract-001.pdf",
+    "documents/contract-002.pdf",
+    "documents/contract-003.pdf",
+    "documents/report.docx",
+    "documents/summary.xlsx"
+  ],
+  "total_count": 5,
+  "next_marker": null
+}
+```
+
+**分页响应 (200)**
+```json
+{
+  "success": true,
+  "message": "共 100 个文件",
+  "files": ["..."],
+  "total_count": 100,
+  "next_marker": "documents/file-100.pdf"
+}
+```
+
+#### cURL 示例
+
+```bash
+# 列出根目录
+curl -X GET "http://localhost:8000/api/v2/storage/files"
+
+# 列出指定目录
+curl -X GET "http://localhost:8000/api/v2/storage/files?directory_path=documents"
+
+# 递归列出
+curl -X GET "http://localhost:8000/api/v2/storage/files?directory_path=documents&recursive=true"
+
+# 分页查询
+curl -X GET "http://localhost:8000/api/v2/storage/files?directory_path=documents&max_files=50"
+
+# 获取下一页
+curl -X GET "http://localhost:8000/api/v2/storage/files?directory_path=documents&max_files=50&marker=documents/file-50.pdf"
+```
+
+---
+
+### 10. 获取文件元数据
+
+**GET** `/api/v2/storage/files/metadata`
+
+获取文件的详细元数据信息。
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file_path | string | 是 | 文件路径 |
+
+#### 响应示例
+
+```json
+{
+  "success": true,
+  "message": "获取成功",
+  "file_info": {
+    "path": "documents/contract.pdf",
+    "size": 1234567,
+    "content_type": "application/pdf",
+    "created_time": "2024-03-15T10:30:00+00:00",
+    "modified_time": "2024-03-15T10:30:00+00:00",
+    "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
+    "url": "http://minio:9000/docauditai/documents/contract.pdf?X-Amz-..."
+  }
+}
+```
+
+#### cURL 示例
+
+```bash
+curl -X GET "http://localhost:8000/api/v2/storage/files/metadata?file_path=documents/contract.pdf"
+```
+
+---
+
+### 11. 获取预签名URL
+
+**GET** `/api/v2/storage/files/presigned-url`
+
+获取文件的预签名下载URL，可用于临时分享。
+
+#### 请求参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| file_path | string | 是 | - | 文件路径 |
+| expires | int | 否 | 3600 | 过期时间（秒），范围 60-604800（7天） |
+
+#### 响应示例
+
+```json
+{
+  "success": true,
+  "message": "获取成功",
+  "url": "http://minio:9000/docauditai/documents/contract.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
+  "expires_in": 3600
+}
+```
+
+#### cURL 示例
+
+```bash
+# 默认1小时过期
+curl -X GET "http://localhost:8000/api/v2/storage/files/presigned-url?file_path=documents/contract.pdf"
+
+# 自定义过期时间（1天）
+curl -X GET "http://localhost:8000/api/v2/storage/files/presigned-url?file_path=documents/contract.pdf&expires=86400"
+
+# 最长7天
+curl -X GET "http://localhost:8000/api/v2/storage/files/presigned-url?file_path=documents/contract.pdf&expires=604800"
+```
+
+---
+
+## 前端集成示例
+
+### JavaScript/Fetch
+
+```javascript
+const API_BASE = 'http://localhost:8000/api/v2/storage';
+
+// 列出存储桶
+async function listBuckets() {
+  const response = await fetch(`${API_BASE}/buckets`);
+  return response.json();
+}
+
+// 创建存储桶
+async function createBucket(bucketName) {
+  const response = await fetch(`${API_BASE}/buckets`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ bucket_name: bucketName })
+  });
+  return response.json();
+}
+
+// 复制文件
+async function copyFile(sourcePath, destPath) {
+  const response = await fetch(`${API_BASE}/files/copy`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      source_path: sourcePath,
+      destination_path: destPath
+    })
+  });
+  return response.json();
+}
+
+// 重命名文件
+async function renameFile(oldPath, newPath) {
+  const response = await fetch(`${API_BASE}/files/move`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      source_path: oldPath,
+      destination_path: newPath
+    })
+  });
+  return response.json();
+}
+
+// 删除文件
+async function deleteFile(filePath) {
+  const response = await fetch(
+    `${API_BASE}/files?file_path=${encodeURIComponent(filePath)}`,
+    { method: 'DELETE' }
+  );
+  return response.json();
+}
+
+// 下载文件
+function downloadFile(filePath, filename) {
+  const url = `${API_BASE}/files/download?file_path=${encodeURIComponent(filePath)}`;
+  if (filename) {
+    url += `&filename=${encodeURIComponent(filename)}`;
+  }
+  window.open(url, '_blank');
+}
+
+// 获取文件列表
+async function listFiles(directory = '', recursive = false) {
+  const params = new URLSearchParams({
+    directory_path: directory,
+    recursive: recursive.toString()
+  });
+  const response = await fetch(`${API_BASE}/files?${params}`);
+  return response.json();
+}
+
+// 获取预签名URL
+async function getPresignedUrl(filePath, expires = 3600) {
+  const params = new URLSearchParams({
+    file_path: filePath,
+    expires: expires.toString()
+  });
+  const response = await fetch(`${API_BASE}/files/presigned-url?${params}`);
+  return response.json();
+}
+```
+
+### Vue 3 组件示例
+
+```vue
+<template>
+  <div class="file-manager">
+    <div class="file-list">
+      <div v-for="file in files" :key="file" class="file-item">
+        <span>{{ file }}</span>
+        <div class="actions">
+          <button @click="handleDownload(file)">下载</button>
+          <button @click="handleRename(file)">重命名</button>
+          <button @click="handleDelete(file)">删除</button>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue';
+
+const API_BASE = '/api/v2/storage';
+const files = ref([]);
+
+onMounted(async () => {
+  await loadFiles();
+});
+
+async function loadFiles() {
+  const response = await fetch(`${API_BASE}/files?directory_path=documents&recursive=true`);
+  const data = await response.json();
+  if (data.success) {
+    files.value = data.files;
+  }
+}
+
+function handleDownload(filePath) {
+  window.open(`${API_BASE}/files/download?file_path=${encodeURIComponent(filePath)}`);
+}
+
+async function handleRename(filePath) {
+  const newName = prompt('请输入新文件名：');
+  if (!newName) return;
+
+  const directory = filePath.substring(0, filePath.lastIndexOf('/'));
+  const newPath = `${directory}/${newName}`;
+
+  const response = await fetch(`${API_BASE}/files/move`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      source_path: filePath,
+      destination_path: newPath
+    })
+  });
+
+  const data = await response.json();
+  if (data.success) {
+    await loadFiles();
+  } else {
+    alert(data.message);
+  }
+}
+
+async function handleDelete(filePath) {
+  if (!confirm(`确定删除 ${filePath}？`)) return;
+
+  const response = await fetch(
+    `${API_BASE}/files?file_path=${encodeURIComponent(filePath)}`,
+    { method: 'DELETE' }
+  );
+
+  const data = await response.json();
+  if (data.success) {
+    await loadFiles();
+  } else {
+    alert(data.message);
+  }
+}
+</script>
+```
+
+---
+
+## 错误处理
+
+所有接口返回统一格式：
+
+```json
+{
+  "success": false,
+  "message": "错误描述信息"
+}
+```
+
+### 常见错误
+
+| 错误 | 说明 | 解决方案 |
+|------|------|----------|
+| 存储桶不存在 | 操作的存储桶未找到 | 检查桶名是否正确 |
+| 文件不存在 | 操作的文件路径无效 | 检查文件路径 |
+| 存储桶非空 | 删除桶时桶内有文件 | 使用 force=true 强制删除 |
+| 权限不足 | MinIO 访问凭证问题 | 检查配置的 access_key/secret_key |
+
+---
+
+## 测试
+
+使用测试脚本进行完整测试：
+
+```bash
+python scripts/test_minio_api.py --host localhost --port 8000
+```