feat: big version, added tasks for backup_database and stock change, added health check api, approve sse (support channel via merchant)

2025-11-26 21:49:42 +08:00
parent 6bf0465d05
commit a9c75a13fa
26 changed files with 7158 additions and 216 deletions
--- a/docs/upload.md
+++ b/docs/upload.md
@@ -0,0 +1,425 @@
+# 文件上传接口文档
+
+## 概述
+
+通用文件上传接口，用于上传无法归类到具体业务的文件。
+
+**基础路径**: `/api/v1/upload/`
+
+**认证要求**: 所有接口都需要 JWT Token 认证
+
+**内容格式**: `multipart/form-data` (上传时) / `application/json` (响应)
+
+**注意事项**:
+- 不支持列表查询（list）
+- 不支持修改操作（PUT/PATCH）
+- 仅支持单个文件查询、上传、删除操作
+
+---
+
+## 数据模型
+
+### UploadedFile
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | integer | 文件ID |
+| path | string | 文件存储路径（随机文件名） |
+| file_url | string | 文件访问URL |
+| owner | integer | 上传者用户ID |
+| owner_username | string | 上传者用户名 |
+| is_deleted | boolean | 是否已删除（软删除标记） |
+| original_filename | string | 原始文件名 |
+| file_size | integer | 文件大小（字节） |
+| content_type | string | MIME类型（如 image/jpeg） |
+| created_at | datetime | 创建时间 |
+| updated_at | datetime | 更新时间 |
+
+---
+
+## 接口列表
+
+### 1. 上传文件
+
+**请求**
+```
+POST /api/v1/upload/
+Content-Type: multipart/form-data
+Authorization: Bearer <token>
+```
+
+**请求参数**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| file | file | 是 | 要上传的文件（最大100MB） |
+
+**请求示例**
+```bash
+curl -X POST http://localhost:8000/api/v1/upload/ \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -F "file=@/path/to/your/file.pdf"
+```
+
+**成功响应** (201 Created)
+```json
+{
+  "id": 1,
+  "path": "uploads/2025/11/17/a1b2c3d4e5f6...hex.pdf",
+  "file_url": "/media/uploads/2025/11/17/a1b2c3d4e5f6...hex.pdf",
+  "owner": 1,
+  "owner_username": "admin",
+  "is_deleted": false,
+  "original_filename": "document.pdf",
+  "file_size": 1048576,
+  "content_type": "application/pdf",
+  "created_at": "2025-11-17T10:30:00Z",
+  "updated_at": "2025-11-17T10:30:00Z"
+}
+```
+
+**错误响应** (400 Bad Request)
+```json
+{
+  "file": ["未上传文件"]
+}
+```
+
+```json
+{
+  "file": ["文件大小不能超过100MB"]
+}
+```
+
+**安全特性**:
+- 文件名使用 UUID 随机化，防止文件名冲突和路径遍历攻击
+- 原始文件名保存在数据库中，不影响存储安全
+- 自动记录上传者信息
+
+---
+
+### 2. 获取文件信息
+
+**请求**
+```
+GET /api/v1/upload/{id}/
+Authorization: Bearer <token>
+```
+
+**路径参数**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | integer | 是 | 文件ID |
+
+**请求示例**
+```bash
+curl -X GET http://localhost:8000/api/v1/upload/1/ \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**成功响应** (200 OK)
+```json
+{
+  "id": 1,
+  "path": "uploads/2025/11/17/a1b2c3d4e5f6...hex.pdf",
+  "file_url": "/media/uploads/2025/11/17/a1b2c3d4e5f6...hex.pdf",
+  "owner": 1,
+  "owner_username": "admin",
+  "is_deleted": false,
+  "original_filename": "document.pdf",
+  "file_size": 1048576,
+  "content_type": "application/pdf",
+  "created_at": "2025-11-17T10:30:00Z",
+  "updated_at": "2025-11-17T10:30:00Z"
+}
+```
+
+**错误响应** (404 Not Found)
+```json
+{
+  "detail": "未找到"
+}
+```
+
+**注意**: 已软删除的文件无法通过此接口查询
+
+---
+
+### 3. 软删除文件
+
+**请求**
+```
+DELETE /api/v1/upload/{id}/
+Authorization: Bearer <token>
+```
+
+**路径参数**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | integer | 是 | 文件ID |
+
+**请求示例**
+```bash
+curl -X DELETE http://localhost:8000/api/v1/upload/1/ \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**成功响应** (200 OK)
+```json
+{
+  "detail": "文件已标记为删除"
+}
+```
+
+**说明**:
+- 软删除不会物理删除文件，只是标记为已删除
+- 软删除后的文件无法通过常规接口查询
+- 可以通过恢复接口恢复文件
+
+---
+
+### 4. 恢复已删除文件
+
+**请求**
+```
+POST /api/v1/upload/{id}/restore/
+Authorization: Bearer <token>
+```
+
+**路径参数**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | integer | 是 | 文件ID |
+
+**请求示例**
+```bash
+curl -X POST http://localhost:8000/api/v1/upload/1/restore/ \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**成功响应** (200 OK)
+```json
+{
+  "detail": "文件已恢复",
+  "data": {
+    "id": 1,
+    "path": "uploads/2025/11/17/a1b2c3d4e5f6...hex.pdf",
+    "file_url": "/media/uploads/2025/11/17/a1b2c3d4e5f6...hex.pdf",
+    "owner": 1,
+    "owner_username": "admin",
+    "is_deleted": false,
+    "original_filename": "document.pdf",
+    "file_size": 1048576,
+    "content_type": "application/pdf",
+    "created_at": "2025-11-17T10:30:00Z",
+    "updated_at": "2025-11-17T10:30:00Z"
+  }
+}
+```
+
+**错误响应** (400 Bad Request)
+```json
+{
+  "detail": "文件未被删除，无需恢复"
+}
+```
+
+---
+
+### 5. 永久删除文件
+
+**请求**
+```
+DELETE /api/v1/upload/{id}/permanent_delete/
+Authorization: Bearer <token>
+```
+
+**路径参数**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | integer | 是 | 文件ID |
+
+**请求示例**
+```bash
+curl -X DELETE http://localhost:8000/api/v1/upload/1/permanent_delete/ \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+**成功响应** (204 No Content)
+```json
+{
+  "detail": "文件已永久删除"
+}
+```
+
+**说明**:
+- 永久删除会物理删除文件和数据库记录
+- 此操作不可恢复，请谨慎使用
+- 建议仅在确认不需要时使用
+
+---
+
+## 使用示例
+
+### Python (requests)
+
+```python
+import requests
+
+# 配置
+BASE_URL = "http://localhost:8000/api/v1"
+TOKEN = "your_jwt_token"
+headers = {"Authorization": f"Bearer {TOKEN}"}
+
+# 1. 上传文件
+with open('document.pdf', 'rb') as f:
+    files = {'file': f}
+    response = requests.post(
+        f"{BASE_URL}/upload/",
+        headers=headers,
+        files=files
+    )
+    file_data = response.json()
+    file_id = file_data['id']
+    print(f"上传成功，文件ID: {file_id}")
+
+# 2. 获取文件信息
+response = requests.get(
+    f"{BASE_URL}/upload/{file_id}/",
+    headers=headers
+)
+print(f"文件信息: {response.json()}")
+
+# 3. 软删除文件
+response = requests.delete(
+    f"{BASE_URL}/upload/{file_id}/",
+    headers=headers
+)
+print(f"软删除: {response.json()}")
+
+# 4. 恢复文件
+response = requests.post(
+    f"{BASE_URL}/upload/{file_id}/restore/",
+    headers=headers
+)
+print(f"恢复文件: {response.json()}")
+
+# 5. 永久删除
+response = requests.delete(
+    f"{BASE_URL}/upload/{file_id}/permanent_delete/",
+    headers=headers
+)
+print(f"永久删除完成")
+```
+
+### JavaScript (Axios)
+
+```javascript
+const axios = require('axios');
+const FormData = require('form-data');
+const fs = require('fs');
+
+const BASE_URL = 'http://localhost:8000/api/v1';
+const TOKEN = 'your_jwt_token';
+const headers = { Authorization: `Bearer ${TOKEN}` };
+
+// 1. 上传文件
+async function uploadFile() {
+  const formData = new FormData();
+  formData.append('file', fs.createReadStream('document.pdf'));
+  
+  const response = await axios.post(
+    `${BASE_URL}/upload/`,
+    formData,
+    { headers: { ...headers, ...formData.getHeaders() } }
+  );
+  
+  console.log('上传成功:', response.data);
+  return response.data.id;
+}
+
+// 2. 获取文件信息
+async function getFileInfo(fileId) {
+  const response = await axios.get(
+    `${BASE_URL}/upload/${fileId}/`,
+    { headers }
+  );
+  console.log('文件信息:', response.data);
+}
+
+// 3. 软删除
+async function softDelete(fileId) {
+  const response = await axios.delete(
+    `${BASE_URL}/upload/${fileId}/`,
+    { headers }
+  );
+  console.log('软删除:', response.data);
+}
+
+// 4. 恢复文件
+async function restore(fileId) {
+  const response = await axios.post(
+    `${BASE_URL}/upload/${fileId}/restore/`,
+    {},
+    { headers }
+  );
+  console.log('恢复:', response.data);
+}
+
+// 5. 永久删除
+async function permanentDelete(fileId) {
+  const response = await axios.delete(
+    `${BASE_URL}/upload/${fileId}/permanent_delete/`,
+    { headers }
+  );
+  console.log('永久删除完成');
+}
+```
+
+---
+
+## 错误码说明
+
+| HTTP状态码 | 说明 |
+|-----------|------|
+| 200 | 成功 |
+| 201 | 创建成功 |
+| 204 | 删除成功（无内容） |
+| 400 | 请求参数错误 |
+| 401 | 未认证或认证失败 |
+| 403 | 无权限 |
+| 404 | 资源不存在 |
+| 413 | 文件过大 |
+| 500 | 服务器内部错误 |
+
+---
+
+## 最佳实践
+
+1. **文件大小限制**: 单文件最大100MB，超过此限制会返回400错误
+2. **文件命名**: 系统自动使用UUID生成随机文件名，原始文件名保存在`original_filename`字段
+3. **软删除策略**: 建议先使用软删除，确认不需要后再使用永久删除
+4. **文件访问**: 使用返回的`file_url`字段访问文件
+5. **权限控制**: 所有接口都需要认证，上传的文件自动关联当前用户
+
+---
+
+## 注意事项
+
+1. **不支持的操作**:
+   - ❌ 列表查询 (`GET /api/v1/upload/`)
+   - ❌ 批量上传
+   - ❌ 修改文件 (`PUT/PATCH /api/v1/upload/{id}/`)
+
+2. **文件存储**:
+   - 文件按日期组织：`uploads/YYYY/MM/DD/`
+   - 文件名使用32位十六进制UUID
+   - 保留原始文件扩展名
+
+3. **查询限制**:
+   - 默认查询会过滤掉已软删除的文件
+   - 要访问已删除文件，需要通过Django Admin或直接数据库查询
+
+4. **安全考虑**:
+   - 所有文件名随机化，防止路径遍历攻击
+   - 需要JWT认证
+   - 自动记录上传者信息