zuowei/erpnew

Fork 0

forked from erp-dev/erp

Files

colaftc 9c38e2ac09 feat: stateflow v2 (params required)

2025-11-15 19:39:15 +08:00

12 KiB

Raw Blame History

Stateflow 业务对象 API 文档

概述

业务对象（BusinessObject）是流程的实例，支持状态流转、参数管理和进度控制。

基础路径: /api/v1/stateflow/business-objects/

1. 查询下一步节点（可选带参数）

获取下一个待执行节点

接口: GET /api/v1/stateflow/business-objects/{id}/next_pending_state/

描述: 获取业务对象的下一个待执行状态节点，默认包含该状态的参数定义列表。

查询参数:

include_parameters (可选): 是否包含参数列表，默认 true
- true: 返回参数定义列表
- false: 只返回状态信息

成功响应 (200):

{
  "state": {
    "id": 5,
    "name": "质量检验",
    "description": "对产品进行质量检查"
  },
  "order": 3,
  "parameters": [
    {
      "id": 1,
      "name": "temperature",
      "display_name": "温度",
      "is_required": true,
      "is_image_path": false
    },
    {
      "id": 2,
      "name": "humidity",
      "display_name": "湿度",
      "is_required": false,
      "is_image_path": false
    }
  ]
}

无待执行节点 (200):

{
  "next_state": null,
  "message": "没有待执行节点（未开始或已完成）"
}

示例:

# 获取下一个节点及参数
GET /api/v1/stateflow/business-objects/123/next_pending_state/

# 只获取下一个节点，不要参数
GET /api/v1/stateflow/business-objects/123/next_pending_state/?include_parameters=false

2. 查询已存在的参数（可选仅包括必填）

2.1 获取当前状态的参数定义

接口: GET /api/v1/stateflow/business-objects/{id}/current_state_parameters/

描述: 获取当前状态（最后完成的状态）的参数定义列表。

查询参数:

required_only (可选): 是否只返回必填参数，默认 false
- true: 只返回必填参数
- false: 返回所有参数

成功响应 (200):

{
  "state": {
    "id": 4,
    "name": "生产加工",
    "description": "进行生产加工"
  },
  "parameters": [
    {
      "id": 3,
      "name": "machine_number",
      "display_name": "机器编号",
      "is_required": true,
      "is_image_path": false
    },
    {
      "id": 4,
      "name": "operator",
      "display_name": "操作员",
      "is_required": true,
      "is_image_path": false
    }
  ],
  "count": 2
}

未完成任何状态 (200):

{
  "parameters": [],
  "message": "尚未完成任何状态"
}

示例:

# 获取当前状态的所有参数定义
GET /api/v1/stateflow/business-objects/123/current_state_parameters/

# 只获取必填参数
GET /api/v1/stateflow/business-objects/123/current_state_parameters/?required_only=true

2.2 获取状态记录的实际参数值

接口: GET /api/v1/stateflow/business-objects/{id}/state-logs/{log_id}/parameters/

描述: 获取指定状态流转记录的实际参数值（用户填写的数据）。

查询参数:

key (可选): 指定参数键，返回该参数的历史记录
include_cancelled (可选): 是否包含已撤销状态的参数，默认 false

成功响应 - 所有参数 (200):

{
  "state_log_id": 456,
  "is_cancelled": false,
  "count": 2,
  "summary": {
    "temperature": "25.5",
    "humidity": "60%",
    "operator": "张三"
  },
  "records": [
    {
      "id": 1,
      "state_log": 456,
      "parameters": {
        "temperature": "25.5",
        "humidity": "60%"
      },
      "remark": "",
      "created_at": "2025-11-15T10:30:00Z",
      "created_by": 1
    },
    {
      "id": 2,
      "state_log": 456,
      "parameters": {
        "operator": "张三"
      },
      "remark": "补充操作员信息",
      "created_at": "2025-11-15T11:00:00Z",
      "created_by": 2
    }
  ]
}

成功响应 - 指定参数历史 (200):

{
  "state_log_id": 456,
  "key": "temperature",
  "is_cancelled": false,
  "history": [
    {
      "value": "25.5",
      "created_at": "2025-11-15T10:30:00Z",
      "created_by": 1,
      "remark": ""
    }
  ]
}

状态记录不存在 (404):

{
  "success": false,
  "message": "状态流转记录不存在"
}

示例:

# 获取状态记录的所有参数
GET /api/v1/stateflow/business-objects/123/state-logs/456/parameters/

# 获取特定参数的历史
GET /api/v1/stateflow/business-objects/123/state-logs/456/parameters/?key=temperature

# 包含已撤销状态的参数
GET /api/v1/stateflow/business-objects/123/state-logs/456/parameters/?include_cancelled=true

3. 推进到下一步（校验必填参数）

接口: POST /api/v1/stateflow/business-objects/{id}/advance/

描述: 推进业务对象到下一个状态，自动校验必填参数。

请求体:

{
  "parameters": {
    "temperature": "25.5",
    "humidity": "60%",
    "operator": "张三"
  }
}

参数说明:

parameters (可选): 参数字典
- 如果下一个状态有必填参数，则必须提供所有必填参数
- 可以包含可选参数
- 参数值以字符串形式存储

成功响应 (200):

{
  "success": true,
  "message": "已推进到状态: 质量检验",
  "state_log": {
    "id": 456,
    "state": {
      "id": 5,
      "name": "质量检验"
    },
    "completed_at": "2025-11-15T10:30:00Z",
    "completed_by": {
      "id": 1,
      "username": "zhangsan"
    },
    "is_cancelled": false,
    "parameters_summary": {
      "temperature": "25.5",
      "humidity": "60%"
    }
  },
  "business_object": {
    "id": 123,
    "name": "订单-001",
    "process": {...},
    "overall_status": "in_progress",
    "current_state": {...}
  }
}

校验失败 - 缺少必填参数 (400):

{
  "success": false,
  "message": "缺少必填参数: temperature, operator"
}

其他失败情况 (400):

{
  "success": false,
  "message": "已经完成所有状态"
}

示例:

# 推进到下一状态（带参数）
curl -X POST /api/v1/stateflow/business-objects/123/advance/ \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"temperature": "25.5", "humidity": "60%"}}'

# 推进到下一状态（无参数）
curl -X POST /api/v1/stateflow/business-objects/123/advance/ \
  -H "Content-Type: application/json" \
  -d '{}'

4. 回退

接口: POST /api/v1/stateflow/business-objects/{id}/step_back/

描述: 回退一步，撤销最后一次完成的状态（标记为已撤销，不删除记录）。

请求体: 无需请求体

成功响应 (200):

{
  "success": true,
  "message": "已回退到状态: 生产加工",
  "business_object": {
    "id": 123,
    "name": "订单-001",
    "process": {...},
    "overall_status": "in_progress",
    "current_state": {...}
  }
}

失败响应 (400):

{
  "success": false,
  "message": "没有可回退的状态"
}

示例:

curl -X POST /api/v1/stateflow/business-objects/123/step_back/

5. 针对已完成的状态节点添加新的参数集

接口: POST /api/v1/stateflow/business-objects/{id}/state-logs/{log_id}/add-parameters/

描述: 为已完成的状态流转记录补充参数（追加新的参数记录）。

请求体:

{
  "parameters": {
    "additional_note": "发现轻微瑕疵",
    "inspector": "李四"
  },
  "remark": "质检员补充信息"
}

参数说明:

parameters (必填): 参数字典，不能为空
remark (可选): 备注说明

成功响应 (200):

{
  "success": true,
  "parameter_record": {
    "id": 789,
    "state_log": 456,
    "parameters": {
      "additional_note": "发现轻微瑕疵",
      "inspector": "李四"
    },
    "remark": "质检员补充信息",
    "created_at": "2025-11-15T14:30:00Z",
    "created_by": 2
  }
}

失败响应 - 状态记录不存在 (404):

{
  "success": false,
  "message": "状态流转记录不存在"
}

失败响应 - 参数为空 (400):

{
  "success": false,
  "message": "参数不能为空"
}

示例:

curl -X POST /api/v1/stateflow/business-objects/123/state-logs/456/add-parameters/ \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "additional_note": "发现轻微瑕疵",
      "inspector": "李四"
    },
    "remark": "质检员补充信息"
  }'

6. 其他相关接口

6.1 获取状态时间线

接口: GET /api/v1/stateflow/business-objects/{id}/timeline/

描述: 获取业务对象的完整状态时间线。

成功响应 (200):

[
  {
    "state": {
      "id": 1,
      "name": "接单"
    },
    "status": "completed",
    "order": 1,
    "completed_at": "2025-11-15T09:00:00Z",
    "completed_by": "zhangsan",
    "cancelled_at": null,
    "is_cancelled": false
  },
  {
    "state": {
      "id": 2,
      "name": "生产加工"
    },
    "status": "completed",
    "order": 2,
    "completed_at": "2025-11-15T10:00:00Z",
    "completed_by": "lisi",
    "cancelled_at": null,
    "is_cancelled": false
  },
  {
    "state": {
      "id": 3,
      "name": "质量检验"
    },
    "status": "pending",
    "order": 3,
    "completed_at": null,
    "completed_by": null,
    "cancelled_at": null,
    "is_cancelled": false
  }
]

6.2 获取所有待执行节点

接口: GET /api/v1/stateflow/business-objects/{id}/pending_states/

描述: 获取所有待执行的状态节点列表（不包含参数）。

成功响应 (200):

{
  "count": 2,
  "pending_states": [
    {
      "state": {
        "id": 3,
        "name": "质量检验"
      },
      "order": 3
    },
    {
      "state": {
        "id": 4,
        "name": "打包发货"
      },
      "order": 4
    }
  ]
}

6.3 重置进度

接口: POST /api/v1/stateflow/business-objects/{id}/reset/

描述: 重置业务对象的进度（删除所有状态记录）。

成功响应 (200):

{
  "success": true,
  "message": "进度已重置",
  "business_object": {...}
}

完整性检查清单

根据您的需求，所有接口都已齐全：

✅ 查询下一步节点（可选带参数）: GET next_pending_state/ (支持 include_parameters 参数)
✅ 查询已存在的参数（可选仅包括必填）:
- GET current_state_parameters/ (支持 required_only 参数) - 参数定义
- GET state-logs/{log_id}/parameters/ - 实际参数值
✅ 回退: POST step_back/
✅ 推进到下一步（校验必填参数）: POST advance/ (自动校验必填参数)
✅ 针对已完成的状态节点添加新的参数集: POST state-logs/{log_id}/add-parameters/

典型使用流程

场景 1: 推进到下一状态

# 1. 查询下一个待执行节点及参数要求
GET /api/v1/stateflow/business-objects/123/next_pending_state/

# 响应显示需要 temperature (必填) 和 humidity (可选)

# 2. 推进到下一状态（提供必填参数）
POST /api/v1/stateflow/business-objects/123/advance/
{
  "parameters": {
    "temperature": "25.5",
    "humidity": "60%"
  }
}

场景 2: 补充参数

# 1. 从时间线获取已完成状态的 state_log_id
GET /api/v1/stateflow/business-objects/123/timeline/

# 2. 为指定状态记录补充参数
POST /api/v1/stateflow/business-objects/123/state-logs/456/add-parameters/
{
  "parameters": {
    "inspector": "李四",
    "note": "补充检验员信息"
  },
  "remark": "质检后补充"
}

场景 3: 查询参数

# 1. 查询当前状态的必填参数定义
GET /api/v1/stateflow/business-objects/123/current_state_parameters/?required_only=true

# 2. 查询某个状态记录的实际参数值
GET /api/v1/stateflow/business-objects/123/state-logs/456/parameters/

# 3. 查询某个参数的修改历史
GET /api/v1/stateflow/business-objects/123/state-logs/456/parameters/?key=temperature

重要说明

参数存储: 所有参数值以字符串形式存储在 JSONField 中，支持灵活的数据结构
参数校验: 仅校验必填参数是否提供，不校验参数值的格式或类型
撤销状态: 回退操作不删除记录，而是标记为已撤销（is_cancelled=True）
参数可见性: 默认情况下，已撤销状态的参数不会返回，需要显式传递 include_cancelled=true
参数追加: 可以多次为同一个状态记录添加参数，所有记录都会保留
参数历史: 支持查询单个参数的修改历史，按时间顺序返回

文档版本: 2025-11-15
测试覆盖: 55 个测试用例全部通过

12 KiB Raw Blame History Unescape Escape

Stateflow 业务对象 API 文档

概述

1. 查询下一步节点（可选带参数）

获取下一个待执行节点

2. 查询已存在的参数（可选仅包括必填）

2.1 获取当前状态的参数定义

2.2 获取状态记录的实际参数值

3. 推进到下一步（校验必填参数）

4. 回退

5. 针对已完成的状态节点添加新的参数集

6. 其他相关接口

6.1 获取状态时间线

6.2 获取所有待执行节点

6.3 重置进度

完整性检查清单

典型使用流程

场景 1: 推进到下一状态

场景 2: 补充参数

场景 3: 查询参数

重要说明

12 KiB

Raw Blame History