docs: 更新后端api文档

doc/project/02-设计文档/backend-api.md

@@ -325,42 +325,145 @@
   "configs": [
     {
       "perturbation_configs_id": 1,
+      "perturbation_code": "aspl",
+      "perturbation_name": "ASPL算法",
+      "description": "Advanced Semantic Protection Layer for Enhanced Privacy Defense"
+    },
+    {
+      "perturbation_configs_id": 2,
       "perturbation_code": "simac",
       "perturbation_name": "SimAC算法",
-      "description": "Simple Anti-Customization Method"
+      "description": "Simple Anti-Customization Method for Protecting Face Privacy"
     },
     {
-      "perturbation_configs_id": 2,
+      "perturbation_configs_id": 3,
       "perturbation_code": "caat",
       "perturbation_name": "CAAT算法",
-      "description": "Perturbing Attention..."
+      "description": "Perturbing Attention Gives You More Bang for the Buck"
+    },
+    {
+      "perturbation_configs_id": 4,
+      "perturbation_code": "caat_pro",
+      "perturbation_name": "CAAT Pro算法",
+      "description": "CAAT with Prior Preservation - Enhanced version with class data preservation"
+    },
+    {
+      "perturbation_configs_id": 5,
+      "perturbation_code": "pid",
+      "perturbation_name": "PID算法",
+      "description": "Prompt-Independent Data Protection Against Latent Diffusion Models"
+    },
+    {
+      "perturbation_configs_id": 6,
+      "perturbation_code": "glaze",
+      "perturbation_name": "Glaze算法",
+      "description": "Protecting Artists from Style Mimicry by Text-to-Image Models"
+    },
+    {
+      "perturbation_configs_id": 7,
+      "perturbation_code": "anti_customize",
+      "perturbation_name": "防定制生成",
+      "description": "Anti-Customization Generation - 专门防止人脸定制化生成"
+    },
+    {
+      "perturbation_configs_id": 8,
+      "perturbation_code": "anti_face_edit",
+      "perturbation_name": "防人脸编辑",
+      "description": "Anti-Face-Editing - 专门防止人脸图像被编辑"
+    },
+    {
+      "perturbation_configs_id": 9,
+      "perturbation_code": "style_protection",
+      "perturbation_name": "风格迁移防护",
+      "description": "Style Transfer Protection - 保护艺术作品免受风格模仿"
     }
   ]
 }
 ```
+**说明**：
+- `perturbation_configs_id=7,8` 仅适用于人脸数据集（`data_type_id=1`）
+- `perturbation_configs_id=9` 仅适用于艺术作品数据集（`data_type_id=2`）且**必须**指定 `target_style` 参数
+
 **错误响应**：
 - `401 {"error": "无效的用户身份标识"}`
 - `500 Internal Server Error`
 
+##### GET `/api/task/perturbation/style-presets`
+**功能**：获取风格迁移防护算法的预设风格列表（仅用于 `style_protection` 算法）。
+**认证**：是  
+**成功响应** `200 OK`：
+```json
+{
+  "presets": [
+    {
+      "style_code": "van_gogh",
+      "name": "梵高印象派",
+      "prompt": "impressionism painting by van gogh",
+      "description": "模仿梵高的印象派绘画风格"
+    },
+    {
+      "style_code": "kandinsky",
+      "name": "康定斯基抽象派",
+      "prompt": "abstract art by kandinsky",
+      "description": "模仿康定斯基的抽象艺术风格"
+    },
+    {
+      "style_code": "picasso",
+      "name": "毕加索立体派",
+      "prompt": "cubist painting by picasso",
+      "description": "模仿毕加索的立体主义风格"
+    },
+    {
+      "style_code": "baroque",
+      "name": "巴洛克风格",
+      "prompt": "baroque style painting",
+      "description": "经典巴洛克艺术风格"
+    }
+  ]
+}
+```
+**错误响应**：
+- `401 {"error": "无效的用户身份标识"}`
+
 ##### POST `/api/task/perturbation`
 **功能**：基于指定数据集与配置创建加噪任务，并支持图片文件一并上传。
 **请求格式**：`multipart/form-data`，字段：
-- `data_type_id`（数字，必填）
-- `perturbation_configs_id`（数字，必填）
-- `perturbation_intensity`（数字，必填）
-- `perturbation_name`（字符串，可选）
-- `description`（字符串，可选）
-- `flow_id`（数字，可选）
-- `files`（一个或多个图片文件，可选）
+- `data_type_id`（数字，必填）- 数据集类型ID，1=人脸，2=艺术作品
+- `perturbation_configs_id`（数字，必填）- 算法配置ID，参考上方配置列表
+- `perturbation_intensity`（数字，必填）- 扰动强度（epsilon值）
+- `target_style`（字符串，条件必填）- **仅当使用 `style_protection` 算法时必填**，可选值：`van_gogh`、`kandinsky`、`picasso`、`baroque`
+- `perturbation_name`（字符串，可选）- 任务自定义名称
+- `description`（字符串，可选）- 任务描述
+- `flow_id`（数字，可选）- 流程ID，若不指定则自动生成
+- `files`（文件数组，必填）- 一个或多个图片文件（jpg/jpeg/png/bmp/gif/webp/tiff）
 
 **成功响应** `201 Created`：
 ```json
 {
   "message": "加噪任务已创建并已启动",
-  "task": { ... },
-  "job_id": "pert_901"
+  "task": {
+    "task_id": 123,
+    "flow_id": 1734700000000,
+    "task_type": "perturbation",
+    "status": "waiting",
+    "user_id": 1,
+    "description": null,
+    "created_at": "2025-12-20T10:00:00",
+    "started_at": null,
+    "finished_at": null,
+    "error_message": null,
+    "perturbation": {
+      "data_type_id": 2,
+      "perturbation_configs_id": 9,
+      "perturbation_intensity": 0.04,
+      "perturbation_name": "梵高风格保护",
+      "target_style": "van_gogh"
+    }
+  },
+  "job_id": "pert_123"
 }
 ```
+
 **错误响应**：
 - `401 {"error": "无效的用户身份标识"}`
 - `400 {"error": "缺少必要的任务参数"}`
@@ -368,27 +471,76 @@
 - `400 {"error": "数据集类型不存在"}`
 - `403 {"error": "普通用户仅可使用人脸数据集"}`
 - `400 {"error": "加噪配置不存在"}`
+- `400 {"error": "风格迁移防护算法必须指定target_style参数"}`
+- `400 {"error": "无效的风格代码: xxx。请使用 /api/task/perturbation/style-presets 查看可用风格"}`
+- `400 {"error": "请上传至少一张图片"}`
+- `400 {"error": "不支持的文件格式: xxx。仅支持图片格式。"}`
 - `400 {"error": "非法的 flow_id 参数"}`
 - `500 {"error": "Task status 'waiting' is not configured"}` / `{...}`
 - `500 {"error": "创建任务失败: ..."}`
 
+**特殊说明**：
+1. **算法与数据集类型限制**：
+   - `anti_customize`（防定制生成，ID=7）和 `anti_face_edit`（防人脸编辑，ID=8）仅适用于人脸数据集（`data_type_id=1`）
+   - `style_protection`（风格迁移防护，ID=9）仅适用于艺术作品数据集（`data_type_id=2`）
+   
+2. **风格选择**：
+   - 使用 `style_protection` 算法时，**必须**通过 `target_style` 参数指定预设风格
+   - 可用风格代码：`van_gogh`、`kandinsky`、`picasso`、`baroque`
+   - 使用 `GET /api/task/perturbation/style-presets` 查看完整风格列表
+   
+3. **扰动强度**：
+   - 不同算法的 `perturbation_intensity` 取值范围不同
+   - 大部分算法：0.01-0.1（浮点数）
+   - 部分算法（如SimAC系列）：整数值（如16）
+
 ##### PATCH `/api/task/perturbation/<task_id>`
 **功能**：调整已有加噪任务的参数或描述。
-**请求体**：可选字段 同创建接口。  
+**请求体**（JSON格式，所有字段可选）：
+```json
+{
+  "data_type_id": 2,
+  "perturbation_configs_id": 9,
+  "perturbation_intensity": 0.05,
+  "perturbation_name": "更新后的任务名",
+  "target_style": "picasso",
+  "description": "更新后的描述"
+}
+```
+
 **成功响应** `200 OK`：
 ```json
 {
   "message": "任务已更新",
-  "task": { ... 同 `serialize_task` 输出 ... }
+  "task": {
+    "task_id": 123,
+    "flow_id": 1734700000000,
+    "task_type": "perturbation",
+    "status": "waiting",
+    "perturbation": {
+      "data_type_id": 2,
+      "perturbation_configs_id": 9,
+      "perturbation_intensity": 0.05,
+      "perturbation_name": "更新后的任务名",
+      "target_style": "picasso"
+    }
+  }
 }
 ```
+
 **错误响应**：
 - `401 {"error": "无效的用户身份标识"}`
 - `404 {"error": "任务不存在或无权限"}`
+- `404 {"error": "任务配置不存在"}`
 - `400 {"error": "数据集类型不存在"}`
 - `400 {"error": "加噪配置不存在"}`
+- `400 {"error": "无效的风格代码: xxx"}`
 - `500 {"error": "更新任务失败: ..."}`（数据库提交失败或参数类型转换异常）
 
+**说明**：
+- 仅可更新未执行或执行失败的任务
+- 更新 `target_style` 时会自动验证风格代码有效性
+
 ##### POST `/api/task/perturbation/<task_id>/start`
 **功能**：向异步队列提交该加噪任务，并将任务状态重置为 `waiting`。
 **成功响应** `200 OK`：
@@ -406,15 +558,43 @@
 **错误响应**：
 - `401 {"error": "无效的用户身份标识"}`
 - `500 {"error": "Task type 'perturbation' is not configured"}`（数据库缺少任务类型配置时触发）
-##### GET `/api/task/perturbation/<task_id>`
-返回单个任务结构。
 
+##### GET `/api/task/perturbation/<task_id>`
 **功能**：查看指定加噪任务的完整信息。
 
+**成功响应** `200 OK`：
+```json
+{
+  "task": {
+    "task_id": 123,
+    "flow_id": 1734700000000,
+    "task_type": "perturbation",
+    "status": "completed",
+    "user_id": 1,
+    "description": "艺术作品保护",
+    "created_at": "2025-12-20T10:00:00",
+    "started_at": "2025-12-20T10:01:00",
+    "finished_at": "2025-12-20T10:15:00",
+    "error_message": null,
+    "perturbation": {
+      "data_type_id": 2,
+      "perturbation_configs_id": 9,
+      "perturbation_intensity": 0.04,
+      "perturbation_name": "梵高风格保护",
+      "target_style": "van_gogh"
+    }
+  }
+}
+```
+
 **错误响应**：
 - `401 {"error": "无效的用户身份标识"}`
 - `404 {"error": "任务不存在或无权限"}`
 
+**说明**：
+- `target_style` 字段仅在使用 `style_protection` 算法时有值
+- 其他算法该字段为 `null`
+
 #### 热力图任务相关
 
 ##### POST `/api/task/heatmap`
@@ -1700,6 +1880,14 @@ Authorization: Bearer <token>
 
 ## 文档更新记录
 
+### 2025-12-20 风格迁移防护功能更新
+- [GET /api/task/perturbation/configs](#get-apitaskperturbationconfigs)：更新算法配置列表，新增9种算法的完整信息及适用范围说明。
+- [GET /api/task/perturbation/style-presets](#get-apitaskperturbationstyle-presets)：**新增接口**，用于获取风格迁移防护算法的4种预设风格（梵高/康定斯基/毕加索/巴洛克）。
+- [POST /api/task/perturbation](#post-apitaskperturbation)：新增 `target_style` 参数（风格迁移防护算法必填），完善请求示例和错误处理，新增算法与数据集类型限制说明。
+- [PATCH /api/task/perturbation/<task_id>](#patch-apitaskperturbationtask_id)：新增 `target_style` 参数支持，完善请求响应示例。
+- [GET /api/task/perturbation/<task_id>](#get-apitaskperturbationtask_id)：更新响应示例，包含 `target_style` 字段说明。
+
+### 历史更新
 - [POST /api/task/finetune/from-perturbation](#post-apitaskfinetunefrom-perturbation)：新增 `custom_prompt` 参数。
 - [POST /api/task/finetune/from-upload](#post-apitaskfinetunefrom-upload)：新增 `custom_prompt` 参数。
 - [GET /api/task/finetune/<task_id>/coords](#get-apitaskfinetunetask_idcoords)：完善3D可视化坐标数据接口文档，新增详细的请求响应格式说明和错误处理。