fix: admin of printing module

2025-11-17 12:11:04 +08:00
parent 81e8c8cb84
commit dff9151651
15 changed files with 473 additions and 23 deletions
--- a/stateflow/API.md
+++ b/stateflow/API.md
@@ -14,10 +14,285 @@ Stateflow API 提供了状态节点和流程的 CRUD 操作接口。

 所有 API 都需要 JWT 认证。在请求头中添加：

+# Stateflow API 文档 (v2)
+
+## 概述
+
+Stateflow API 提供了状态节点、流程模板以及流程实例（业务对象）的完整生命周期管理，包括创建、查询、更新、删除以及核心的状态流转操作。
+
+## 基础 URL
+
+所有 Stateflow 相关 API 都在以下基础路径下：
+
+```
+/api/v1/stateflow/
+```
+
+## 认证
+
+所有 API 都需要 JWT 认证。在请求头中添加：
+
 ```
 Authorization: Bearer <access_token>
 ```

+## 分页
+
+列表接口默认使用 `LimitOffset` 分页：
+
+- `limit`: 返回结果数量。
+- `offset`: 偏移量。
+
+---
+
+## 1. State API (状态节点)
+
+**基础路径**: `/api/v1/stateflow/states/`
+
+管理流程中的基础单元：状态。
+
+### 1.1. 列表查询
+
+- **GET** `/api/v1/stateflow/states/`
+- **描述**: 获取状态节点列表。
+- **查询参数**:
+    - `name`: 按名称精确查询。
+    - `search`: 按名称和描述进行模糊搜索。
+    - `ordering`: 排序字段 (`id`, `name`, `created_at`, `updated_at`)。
+
+### 1.2. 详情查询
+
+- **GET** `/api/v1/stateflow/states/{id}/`
+- **描述**: 获取单个状态节点的详细信息，包含其关联的参数模板。
+
+### 1.3. 创建状态
+
+- **POST** `/api/v1/stateflow/states/`
+- **描述**: 创建一个新的状态节点。
+- **请求体**:
+  ```json
+  {
+    "name": "待质检",
+    "description": "等待品质检验",
+    "parameters": [
+      {
+        "key": "inspector",
+        "value": "",
+        "is_required": true,
+        "description": "质检员"
+      }
+    ]
+  }
+  ```
+
+### 1.4. 更新状态
+
+- **PUT/PATCH** `/api/v1/stateflow/states/{id}/`
+- **描述**: 完全或部分更新一个状态节点。`PUT` 请求会替换所有字段，`PATCH` 只更新提供的字段。`parameters` 数组在 `PUT` 时会完全替换。
+
+### 1.5. 删除状态
+
+- **DELETE** `/api/v1/stateflow/states/{id}/`
+- **描述**: 删除一个状态节点。
+
+### 1.6. 获取状态参数
+
+- **GET** `/api/v1/stateflow/states/{id}/parameters/`
+- **描述**: 获取指定状态的参数列表。
+- **查询参数**:
+    - `required_only`: `true` 或 `false`，是否只返回必填参数。
+
+---
+
+## 2. Process API (流程模板)
+
+**基础路径**: `/api/v1/stateflow/processes/`
+
+管理可复用的流程模板。
+
+### 2.1. 列表查询
+
+- **GET** `/api/v1/stateflow/processes/`
+- **描述**: 获取流程模板列表。
+- **查询参数**:
+    - `name`: 按名称精确查询。
+    - `search`: 按名称和描述进行模糊搜索。
+    - `ordering`: 排序字段 (`id`, `name`, `node_count`, `created_at`, `updated_at`)。
+
+### 2.2. 详情查询
+
+- **GET** `/api/v1/stateflow/processes/{id}/`
+- **描述**: 获取单个流程模板的详细信息，包含其所有节点（`nodes`）。
+
+### 2.3. 创建流程
+
+- **POST** `/api/v1/stateflow/processes/`
+- **描述**: 创建一个新的流程模板，并定义其节点顺序。
+- **请求体**:
+  ```json
+  {
+    "name": "生产流程",
+    "description": "从下单到发货的标准流程",
+    "nodes": [
+      { "state_id": 1, "order": 0 },
+      { "state_id": 2, "order": 1 },
+      { "state_id": 5, "order": 2 }
+    ]
+  }
+  ```
+
+### 2.4. 更新流程
+
+- **PUT/PATCH** `/api/v1/stateflow/processes/{id}/`
+- **描述**: 更新流程模板。`nodes` 数组在 `PUT` 时会完全替换。
+
+### 2.5. 删除流程
+
+- **DELETE** `/api/v1/stateflow/processes/{id}/`
+- **描述**: 删除一个流程模板。
+
+---
+
+## 3. Business Object API (流程实例)
+
+**基础路径**: `/api/v1/stateflow/business-objects/`
+
+管理流程的具体实例，这是状态流转的核心。
+
+### 3.1. 列表查询
+
+- **GET** `/api/v1/stateflow/business-objects/`
+- **描述**: 获取流程实例列表。
+- **查询参数**:
+    - `name`: 按名称模糊查询。
+    - `process`: 按流程模板 ID 过滤。
+    - `process_name`: 按流程模板名称模糊查询。
+    - `overall_status`: 按整体状态过滤 (`not_started`, `in_progress`, `completed`)。
+    - `content_type_str`: 按关联的业务模型过滤，格式: `app_label.model` (例如 `printing.plateorder`)。
+    - `has_content_object`: `true` 或 `false`，过滤是否有关联的业务模型。
+    - `search`: 按名称和描述进行模糊搜索。
+    - `ordering`: 排序字段 (`id`, `name`, `created_at`, `updated_at`)。
+
+### 3.2. 详情查询
+
+- **GET** `/api/v1/stateflow/business-objects/{id}/`
+- **描述**: 获取单个流程实例的详细信息，包含当前状态、进度、时间线等。
+
+### 3.3. 创建流程实例
+
+- **POST** `/api/v1/stateflow/business-objects/`
+- **描述**: 创建一个新的流程实例。
+- **请求体**:
+  ```json
+  {
+    "name": "订单 #123 的生产流程",
+    "process": 1,
+    "description": "客户A的加急订单"
+  }
+  ```
+
+### 3.4. 更新流程实例
+
+- **PUT/PATCH** `/api/v1/stateflow/business-objects/{id}/`
+- **描述**: 更新流程实例的基本信息（如名称、描述）。
+
+### 3.5. 删除流程实例
+
+- **DELETE** `/api/v1/stateflow/business-objects/{id}/`
+- **描述**: 删除一个流程实例及其所有相关日志。
+
+### 3.6. 核心流转操作 (Custom Actions)
+
+#### 3.6.1. 推进到下一状态
+
+- **POST** `/api/v1/stateflow/business-objects/{id}/advance/`
+- **描述**: 将流程实例从当前状态推进到下一个状态。
+- **请求体** (可选):
+  ```json
+  {
+    "parameters": {
+      "temperature": "25.5",
+      "humidity": "60%"
+    }
+  }
+  ```
+- **成功响应**: `200 OK`，包含成功信息和更新后的业务对象。
+- **失败响应**: `400 Bad Request`，如果缺少必填参数或流程已完成。
+  ```json
+  {
+    "success": false,
+    "message": "流程已完成，无法继续推进"
+  }
+  ```
+
+#### 3.6.2. 回退一步
+
+- **POST** `/api/v1/stateflow/business-objects/{id}/step_back/`
+- **描述**: 撤销最后一次完成的状态，使流程回退一步。
+- **成功响应**: `200 OK`。
+- **失败响应**: `400 Bad Request`，如果从未开始过。
+  ```json
+  {
+    "success": false,
+    "message": "没有任何状态流转记录，无法回退"
+  }
+  ```
+
+#### 3.6.3. 重置进度
+
+- **POST** `/api/v1/stateflow/business-objects/{id}/reset/`
+- **描述**: 撤销所有已完成的状态，将流程实例重置到未开始状态。
+
+### 3.7. 状态查询接口 (Custom Actions)
+
+#### 3.7.1. 获取状态时间线
+
+- **GET** `/api/v1/stateflow/business-objects/{id}/timeline/`
+- **描述**: 获取一个包含所有节点及其当前状态（`not_started`, `in_progress`, `completed`, `cancelled`）的时间线。
+
+#### 3.7.2. 获取下一个待执行节点
+
+- **GET** `/api/v1/stateflow/business-objects/{id}/next_pending_state/`
+- **描述**: 获取下一个待执行的节点信息。
+- **查询参数**:
+    - `include_parameters`: `true` 或 `false`，是否包含节点的参数模板。
+
+#### 3.7.3. 获取所有待执行节点
+
+- **GET** `/api/v1/stateflow/business-objects/{id}/pending_states/`
+- **描述**: 获取所有未完成的节点列表。
+
+#### 3.7.4. 获取当前状态的参数
+
+- **GET** `/api/v1/stateflow/business-objects/{id}/current_state_parameters/`
+- **描述**: 获取当前待执行节点（`current_state`）的参数模板。
+- **注意**: `current_state` 指的是下一个待执行的节点。如果流程已完成，则返回空。
+
+### 3.8. 参数与日志接口 (Custom Actions)
+
+#### 3.8.1. 为日志补充参数
+
+- **POST** `/api/v1/stateflow/business-objects/{id}/state-logs/{log_id}/add-parameters/`
+- **描述**: 为某一次具体的状态流转记录（`StateFlowRecord`）补充额外的参数。
+- **请求体**:
+  ```json
+  {
+    "parameters": {
+      "inspector_comment": "发现轻微划痕"
+    },
+    "remark": "质检员补充"
+  }
+  ```
+
+#### 3.8.2. 获取日志的参数
+
+- **GET** `/api/v1/stateflow/business-objects/{id}/state-logs/{log_id}/parameters/`
+- **描述**: 获取某一次流转记录的所有参数。
+- **查询参数**:
+    - `key`: 如果提供，则只返回该 `key` 的所有历史值。
+    - `include_cancelled`: `true` 或 `false`，是否包含已撤销的记录。
+
+
 ## 分页

 使用 LimitOffset 分页：