# 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):
```json
{
  "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):
```json
{
  "next_state": null,
  "message": "没有待执行节点（未开始或已完成）"
}
```

**示例**:
```bash
# 获取下一个节点及参数
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):
```json
{
  "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):
```json
{
  "parameters": [],
  "message": "尚未完成任何状态"
}
```

**示例**:
```bash
# 获取当前状态的所有参数定义
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):
```json
{
  "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):
```json
{
  "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):
```json
{
  "success": false,
  "message": "状态流转记录不存在"
}
```

**示例**:
```bash
# 获取状态记录的所有参数
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/`

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

**请求体**:
```json
{
  "parameters": {
    "temperature": "25.5",
    "humidity": "60%",
    "operator": "张三"
  }
}
```

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

**成功响应** (200):
```json
{
  "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):
```json
{
  "success": false,
  "message": "缺少必填参数: temperature, operator"
}
```

**其他失败情况** (400):
```json
{
  "success": false,
  "message": "已经完成所有状态"
}
```

**示例**:
```bash
# 推进到下一状态（带参数）
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):
```json
{
  "success": true,
  "message": "已回退到状态: 生产加工",
  "business_object": {
    "id": 123,
    "name": "订单-001",
    "process": {...},
    "overall_status": "in_progress",
    "current_state": {...}
  }
}
```

**失败响应** (400):
```json
{
  "success": false,
  "message": "没有可回退的状态"
}
```

**示例**:
```bash
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/`

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

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

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

**成功响应** (200):
```json
{
  "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):
```json
{
  "success": false,
  "message": "状态流转记录不存在"
}
```

**失败响应 - 参数为空** (400):
```json
{
  "success": false,
  "message": "参数不能为空"
}
```

**示例**:
```bash
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):
```json
[
  {
    "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):
```json
{
  "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):
```json
{
  "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: 推进到下一状态

```bash
# 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: 补充参数

```bash
# 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: 查询参数

```bash
# 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 个测试用例全部通过