566 lines
12 KiB
Markdown
566 lines
12 KiB
Markdown
# 资产调拨和回收API文档
|
||
|
||
## 目录
|
||
- [资产调拨管理](#资产调拨管理)
|
||
- [资产回收管理](#资产回收管理)
|
||
|
||
---
|
||
|
||
## 资产调拨管理
|
||
|
||
### 1. 获取调拨单列表
|
||
**GET** `/api/v1/transfers`
|
||
|
||
**查询参数：**
|
||
- `skip` (int): 跳过条数，默认0
|
||
- `limit` (int): 返回条数，默认20，最大100
|
||
- `transfer_type` (string): 调拨类型（internal=内部调拨/external=跨机构调拨）
|
||
- `approval_status` (string): 审批状态（pending/approved/rejected/cancelled）
|
||
- `execute_status` (string): 执行状态（pending/executing/completed/cancelled）
|
||
- `source_org_id` (int): 调出网点ID
|
||
- `target_org_id` (int): 调入网点ID
|
||
- `keyword` (string): 搜索关键词（单号/标题）
|
||
|
||
**响应示例：**
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"order_code": "TO-20250124-00001",
|
||
"source_org_id": 1,
|
||
"target_org_id": 2,
|
||
"transfer_type": "external",
|
||
"title": "从总部向分公司调拨资产",
|
||
"asset_count": 5,
|
||
"apply_user_id": 1,
|
||
"apply_time": "2025-01-24T10:00:00",
|
||
"approval_status": "pending",
|
||
"execute_status": "pending",
|
||
"created_at": "2025-01-24T10:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 获取调拨单统计
|
||
**GET** `/api/v1/transfers/statistics`
|
||
|
||
**查询参数：**
|
||
- `source_org_id` (int): 调出网点ID（可选）
|
||
- `target_org_id` (int): 调入网点ID（可选）
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"total": 100,
|
||
"pending": 10,
|
||
"approved": 50,
|
||
"rejected": 5,
|
||
"executing": 15,
|
||
"completed": 20
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 获取调拨单详情
|
||
**GET** `/api/v1/transfers/{order_id}`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 调拨单ID
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"order_code": "TO-20250124-00001",
|
||
"source_org_id": 1,
|
||
"target_org_id": 2,
|
||
"transfer_type": "external",
|
||
"title": "从总部向分公司调拨资产",
|
||
"asset_count": 5,
|
||
"apply_user_id": 1,
|
||
"apply_time": "2025-01-24T10:00:00",
|
||
"approval_status": "approved",
|
||
"approval_user_id": 2,
|
||
"approval_time": "2025-01-24T11:00:00",
|
||
"execute_status": "completed",
|
||
"execute_user_id": 3,
|
||
"execute_time": "2025-01-24T12:00:00",
|
||
"remark": "调拨备注",
|
||
"created_at": "2025-01-24T10:00:00",
|
||
"updated_at": "2025-01-24T12:00:00",
|
||
"source_organization": {
|
||
"id": 1,
|
||
"org_name": "总部",
|
||
"org_type": "headquarters"
|
||
},
|
||
"target_organization": {
|
||
"id": 2,
|
||
"org_name": "北京分公司",
|
||
"org_type": "branch"
|
||
},
|
||
"apply_user": {
|
||
"id": 1,
|
||
"real_name": "张三",
|
||
"username": "zhangsan"
|
||
},
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"asset_id": 10,
|
||
"asset_code": "ASSET001",
|
||
"source_organization_id": 1,
|
||
"target_organization_id": 2,
|
||
"transfer_status": "completed"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 获取调拨单明细
|
||
**GET** `/api/v1/transfers/{order_id}/items`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 调拨单ID
|
||
|
||
**响应示例：**
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"order_id": 1,
|
||
"asset_id": 10,
|
||
"asset_code": "ASSET001",
|
||
"source_organization_id": 1,
|
||
"target_organization_id": 2,
|
||
"transfer_status": "completed",
|
||
"created_at": "2025-01-24T10:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 创建调拨单
|
||
**POST** `/api/v1/transfers`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"source_org_id": 1,
|
||
"target_org_id": 2,
|
||
"transfer_type": "external",
|
||
"title": "从总部向分公司调拨资产",
|
||
"asset_ids": [10, 11, 12, 13, 14],
|
||
"remark": "调拨备注"
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
- `source_org_id` (int, 必填): 调出网点ID
|
||
- `target_org_id` (int, 必填): 调入网点ID
|
||
- `transfer_type` (string, 必填): 调拨类型
|
||
- `internal`: 内部调拨
|
||
- `external`: 跨机构调拨
|
||
- `title` (string, 必填): 标题
|
||
- `asset_ids` (array, 必填): 资产ID列表
|
||
- `remark` (string, 可选): 备注
|
||
|
||
**响应：** 返回创建的调拨单详情
|
||
|
||
---
|
||
|
||
### 6. 更新调拨单
|
||
**PUT** `/api/v1/transfers/{order_id}`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 调拨单ID
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"title": "更新后的标题",
|
||
"remark": "更新后的备注"
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
- `title` (string, 可选): 标题
|
||
- `remark` (string, 可选): 备注
|
||
|
||
**响应：** 返回更新后的调拨单详情
|
||
|
||
**限制：** 只有待审批状态的调拨单可以更新
|
||
|
||
---
|
||
|
||
### 7. 审批调拨单
|
||
**POST** `/api/v1/transfers/{order_id}/approve`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 调拨单ID
|
||
|
||
**查询参数：**
|
||
- `approval_status` (string, 必填): 审批状态（approved/rejected）
|
||
- `approval_remark` (string, 可选): 审批备注
|
||
|
||
**响应：** 返回审批后的调拨单详情
|
||
|
||
**限制：**
|
||
- 只有待审批状态的调拨单可以审批
|
||
- 审批通过后可以开始执行调拨
|
||
|
||
---
|
||
|
||
### 8. 开始调拨
|
||
**POST** `/api/v1/transfers/{order_id}/start`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 调拨单ID
|
||
|
||
**响应：** 返回开始执行后的调拨单详情
|
||
|
||
**限制：**
|
||
- 必须已审批通过
|
||
- 不能重复开始
|
||
|
||
---
|
||
|
||
### 9. 完成调拨
|
||
**POST** `/api/v1/transfers/{order_id}/complete`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 调拨单ID
|
||
|
||
**响应：** 返回完成后的调拨单详情
|
||
|
||
**功能：**
|
||
- 自动更新资产所属机构
|
||
- 自动更新资产状态
|
||
- 更新明细状态为完成
|
||
|
||
**限制：** 只有pending或executing状态的调拨单可以完成
|
||
|
||
---
|
||
|
||
### 10. 取消调拨单
|
||
**POST** `/api/v1/transfers/{order_id}/cancel`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 调拨单ID
|
||
|
||
**响应：** 204 No Content
|
||
|
||
**限制：** 已完成的调拨单无法取消
|
||
|
||
---
|
||
|
||
### 11. 删除调拨单
|
||
**DELETE** `/api/v1/transfers/{order_id}`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 调拨单ID
|
||
|
||
**响应：** 204 No Content
|
||
|
||
**限制：** 只能删除已拒绝或已取消的调拨单
|
||
|
||
---
|
||
|
||
## 资产回收管理
|
||
|
||
### 1. 获取回收单列表
|
||
**GET** `/api/v1/recoveries`
|
||
|
||
**查询参数：**
|
||
- `skip` (int): 跳过条数，默认0
|
||
- `limit` (int): 返回条数，默认20，最大100
|
||
- `recovery_type` (string): 回收类型（user=使用人回收/org=机构回收/scrap=报废回收）
|
||
- `approval_status` (string): 审批状态（pending/approved/rejected/cancelled）
|
||
- `execute_status` (string): 执行状态（pending/executing/completed/cancelled）
|
||
- `keyword` (string): 搜索关键词（单号/标题）
|
||
|
||
**响应示例：**
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"order_code": "RO-20250124-00001",
|
||
"recovery_type": "user",
|
||
"title": "回收离职员工资产",
|
||
"asset_count": 3,
|
||
"apply_user_id": 1,
|
||
"apply_time": "2025-01-24T10:00:00",
|
||
"approval_status": "pending",
|
||
"execute_status": "pending",
|
||
"created_at": "2025-01-24T10:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 获取回收单统计
|
||
**GET** `/api/v1/recoveries/statistics`
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"total": 80,
|
||
"pending": 8,
|
||
"approved": 40,
|
||
"rejected": 4,
|
||
"executing": 12,
|
||
"completed": 16
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 获取回收单详情
|
||
**GET** `/api/v1/recoveries/{order_id}`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 回收单ID
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"order_code": "RO-20250124-00001",
|
||
"recovery_type": "user",
|
||
"title": "回收离职员工资产",
|
||
"asset_count": 3,
|
||
"apply_user_id": 1,
|
||
"apply_time": "2025-01-24T10:00:00",
|
||
"approval_status": "approved",
|
||
"approval_user_id": 2,
|
||
"approval_time": "2025-01-24T11:00:00",
|
||
"execute_status": "completed",
|
||
"execute_user_id": 3,
|
||
"execute_time": "2025-01-24T12:00:00",
|
||
"remark": "回收备注",
|
||
"created_at": "2025-01-24T10:00:00",
|
||
"updated_at": "2025-01-24T12:00:00",
|
||
"apply_user": {
|
||
"id": 1,
|
||
"real_name": "张三",
|
||
"username": "zhangsan"
|
||
},
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"asset_id": 10,
|
||
"asset_code": "ASSET001",
|
||
"recovery_status": "completed"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 获取回收单明细
|
||
**GET** `/api/v1/recoveries/{order_id}/items`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 回收单ID
|
||
|
||
**响应示例：**
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"order_id": 1,
|
||
"asset_id": 10,
|
||
"asset_code": "ASSET001",
|
||
"recovery_status": "completed",
|
||
"created_at": "2025-01-24T10:00:00"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 创建回收单
|
||
**POST** `/api/v1/recoveries`
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"recovery_type": "user",
|
||
"title": "回收离职员工资产",
|
||
"asset_ids": [10, 11, 12],
|
||
"remark": "回收备注"
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
- `recovery_type` (string, 必填): 回收类型
|
||
- `user`: 使用人回收（从使用人处回收）
|
||
- `org`: 机构回收（从机构回收）
|
||
- `scrap`: 报废回收（报废资产回收）
|
||
- `title` (string, 必填): 标题
|
||
- `asset_ids` (array, 必填): 资产ID列表
|
||
- `remark` (string, 可选): 备注
|
||
|
||
**响应：** 返回创建的回收单详情
|
||
|
||
---
|
||
|
||
### 6. 更新回收单
|
||
**PUT** `/api/v1/recoveries/{order_id}`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 回收单ID
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"title": "更新后的标题",
|
||
"remark": "更新后的备注"
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
- `title` (string, 可选): 标题
|
||
- `remark` (string, 可选): 备注
|
||
|
||
**响应：** 返回更新后的回收单详情
|
||
|
||
**限制：** 只有待审批状态的回收单可以更新
|
||
|
||
---
|
||
|
||
### 7. 审批回收单
|
||
**POST** `/api/v1/recoveries/{order_id}/approve`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 回收单ID
|
||
|
||
**查询参数：**
|
||
- `approval_status` (string, 必填): 审批状态（approved/rejected）
|
||
- `approval_remark` (string, 可选): 审批备注
|
||
|
||
**响应：** 返回审批后的回收单详情
|
||
|
||
**限制：**
|
||
- 只有待审批状态的回收单可以审批
|
||
- 审批通过后可以开始执行回收
|
||
|
||
---
|
||
|
||
### 8. 开始回收
|
||
**POST** `/api/v1/recoveries/{order_id}/start`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 回收单ID
|
||
|
||
**响应：** 返回开始执行后的回收单详情
|
||
|
||
**限制：**
|
||
- 必须已审批通过
|
||
- 不能重复开始
|
||
|
||
---
|
||
|
||
### 9. 完成回收
|
||
**POST** `/api/v1/recoveries/{order_id}/complete`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 回收单ID
|
||
|
||
**响应：** 返回完成后的回收单详情
|
||
|
||
**功能：**
|
||
- 自动更新资产状态为in_stock（普通回收）或scrapped（报废回收）
|
||
- 自动记录资产状态历史
|
||
- 更新明细状态为完成
|
||
|
||
**限制：** 只有pending或executing状态的回收单可以完成
|
||
|
||
---
|
||
|
||
### 10. 取消回收单
|
||
**POST** `/api/v1/recoveries/{order_id}/cancel`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 回收单ID
|
||
|
||
**响应：** 204 No Content
|
||
|
||
**限制：** 已完成的回收单无法取消
|
||
|
||
---
|
||
|
||
### 11. 删除回收单
|
||
**DELETE** `/api/v1/recoveries/{order_id}`
|
||
|
||
**路径参数：**
|
||
- `order_id` (int): 回收单ID
|
||
|
||
**响应：** 204 No Content
|
||
|
||
**限制：** 只能删除已拒绝或已取消的回收单
|
||
|
||
---
|
||
|
||
## 业务流程说明
|
||
|
||
### 调拨流程
|
||
1. **创建调拨单**：选择调出/调入机构和资产
|
||
2. **审批调拨单**：管理员审批（通过/拒绝）
|
||
3. **开始调拨**：开始执行调拨操作
|
||
4. **完成调拨**：
|
||
- 自动更新资产所属机构
|
||
- 自动更新资产状态
|
||
- 记录状态历史
|
||
|
||
### 回收流程
|
||
1. **创建回收单**：选择回收类型和资产
|
||
2. **审批回收单**：管理员审批（通过/拒绝）
|
||
3. **开始回收**：开始执行回收操作
|
||
4. **完成回收**：
|
||
- 普通回收：资产状态变为in_stock
|
||
- 报废回收：资产状态变为scrapped
|
||
- 记录状态历史
|
||
|
||
### 状态说明
|
||
|
||
#### 调拨类型
|
||
- `internal`: 内部调拨（同一组织内调拨）
|
||
- `external`: 跨机构调拨（不同组织间调拨）
|
||
|
||
#### 回收类型
|
||
- `user`: 使用人回收（从使用人处回收资产）
|
||
- `org`: 机构回收（从机构回收资产）
|
||
- `scrap`: 报废回收（报废并回收资产）
|
||
|
||
#### 审批状态
|
||
- `pending`: 待审批
|
||
- `approved`: 已审批通过
|
||
- `rejected`: 已拒绝
|
||
- `cancelled`: 已取消
|
||
|
||
#### 执行状态
|
||
- `pending`: 待执行
|
||
- `executing`: 执行中
|
||
- `completed`: 已完成
|
||
- `cancelled`: 已取消
|
||
|
||
#### 调拨明细状态
|
||
- `pending`: 待调拨
|
||
- `transferring`: 调拨中
|
||
- `completed`: 已完成
|
||
- `failed`: 失败
|
||
|
||
#### 回收明细状态
|
||
- `pending`: 待回收
|
||
- `recovering`: 回收中
|
||
- `completed`: 已完成
|
||
- `failed`: 失败
|