erpnew/stateflow/BusinessObject_API.md

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

---

重要说明

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

---

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