feat: upload api

2025-11-17 14:34:09 +08:00
parent dff9151651
commit d23db848ec
16 changed files with 1183 additions and 29 deletions
--- a/stateflow/API.md
+++ b/stateflow/API.md
@@ -270,7 +270,52 @@ Authorization: Bearer <access_token>

 ### 3.8. 参数与日志接口 (Custom Actions)

-#### 3.8.1. 为日志补充参数
+#### 3.8.1. 获取状态流转记录列表
+
+- **GET** `/api/v1/stateflow/business-objects/{id}/state-logs/`
+- **描述**: 获取业务对象的所有状态流转记录列表。
+- **查询参数**:
+    - `include_parameters`: `true` 或 `false`，是否包含工艺参数，默认 `true`。
+    - `include_cancelled`: `true` 或 `false`，是否包含已撤销的记录，默认 `true`。
+- **响应示例**:
+  ```json
+  {
+    "count": 2,
+    "state_logs": [
+      {
+        "id": 123,
+        "state": 1,
+        "state_name": "质检",
+        "completed_at": "2025-11-15T10:30:00Z",
+        "completed_by": 5,
+        "completed_by_username": "inspector1",
+        "is_cancelled": false,
+        "cancelled_at": null,
+        "parameters_summary": {
+          "temperature": "25.5",
+          "humidity": "60%"
+        }
+      },
+      {
+        "id": 124,
+        "state": 2,
+        "state_name": "包装",
+        "completed_at": "2025-11-15T14:20:00Z",
+        "completed_by": 6,
+        "completed_by_username": "packer1",
+        "is_cancelled": false,
+        "cancelled_at": null,
+        "parameters_summary": {}
+      }
+    ]
+  }
+  ```
+- **注意**: 
+    - 当 `include_parameters=false` 时，返回的记录不包含 `parameters_summary` 字段。
+    - 当 `include_cancelled=false` 时，只返回未撤销的记录。
+    - 记录按 `completed_at` 时间正序排列。
+
+#### 3.8.2. 为日志补充参数

 - **POST** `/api/v1/stateflow/business-objects/{id}/state-logs/{log_id}/add-parameters/`
 - **描述**: 为某一次具体的状态流转记录（`StateFlowRecord`）补充额外的参数。
@@ -283,14 +328,82 @@ Authorization: Bearer <access_token>
    "remark": "质检员补充"
  }
  ```
+- **成功响应**: `200 OK`
+  ```json
+  {
+    "success": true,
+    "parameter_record": {
+      "id": 456,
+      "parameters": {
+        "inspector_comment": "发现轻微划痕"
+      },
+      "remark": "质检员补充",
+      "created_at": "2025-11-15T15:00:00Z"
+    }
+  }
+  ```
+- **失败响应**: 
+    - `400 Bad Request`: 参数为空
+    - `404 Not Found`: 状态流转记录不存在

-#### 3.8.2. 获取日志的参数
+#### 3.8.3. 获取单个日志的参数

 - **GET** `/api/v1/stateflow/business-objects/{id}/state-logs/{log_id}/parameters/`
- **描述**: 获取某一次流转记录的所有参数。
+- **描述**: 获取某一次流转记录的所有参数记录或指定参数的历史。
 - **查询参数**:
-    - `key`: 如果提供，则只返回该 `key` 的所有历史值。
-    - `include_cancelled`: `true` 或 `false`，是否包含已撤销的记录。
+    - `key`: （可选）如果提供，则只返回该 `key` 的所有历史值。
+    - `include_cancelled`: `true` 或 `false`，是否包含已撤销状态的参数，默认 `false`。
+- **响应示例**（获取所有参数）:
+  ```json
+  {
+    "state_log_id": 123,
+    "is_cancelled": false,
+    "count": 2,
+    "summary": {
+      "temperature": "26.5",
+      "humidity": "60%"
+    },
+    "records": [
+      {
+        "id": 1,
+        "parameters": {
+          "temperature": "25.5",
+          "humidity": "60%"
+        },
+        "remark": "",
+        "created_at": "2025-11-15T10:30:00Z"
+      },
+      {
+        "id": 2,
+        "parameters": {
+          "temperature": "26.5"
+        },
+        "remark": "重新测量",
+        "created_at": "2025-11-15T11:00:00Z"
+      }
+    ]
+  }
+  ```
+- **响应示例**（按 key 查询历史）:
+  ```json
+  {
+    "state_log_id": 123,
+    "key": "temperature",
+    "is_cancelled": false,
+    "history": [
+      {
+        "value": "25.5",
+        "remark": "",
+        "created_at": "2025-11-15T10:30:00Z"
+      },
+      {
+        "value": "26.5",
+        "remark": "重新测量",
+        "created_at": "2025-11-15T11:00:00Z"
+      }
+    ]
+  }
+  ```


 ## 分页