305 lines
5.9 KiB
Markdown
305 lines
5.9 KiB
Markdown
# 资产分配管理API使用说明
|
||
|
||
> **版本**: v1.0.0
|
||
> **作者**: 后端API扩展组
|
||
> **创建时间**: 2025-01-24
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
1. [概述](#概述)
|
||
2. [单据类型说明](#单据类型说明)
|
||
3. [API端点](#api端点)
|
||
4. [业务流程](#业务流程)
|
||
5. [状态说明](#状态说明)
|
||
6. [错误码](#错误码)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
资产分配管理API提供资产分配、调拨、回收、维修分配和报废分配等功能。支持完整的审批流程和执行流程。
|
||
|
||
---
|
||
|
||
## 单据类型说明
|
||
|
||
| 类型 | 代码 | 说明 |
|
||
|------|------|------|
|
||
| 资产分配 | allocation | 从仓库分配资产给网点 |
|
||
| 资产调拨 | transfer | 网点间资产调拨 |
|
||
| 资产回收 | recovery | 从使用中回收资产 |
|
||
| 维修分配 | maintenance | 分配资产进行维修 |
|
||
| 报废分配 | scrap | 分配资产进行报废 |
|
||
|
||
---
|
||
|
||
## API端点
|
||
|
||
### 1. 获取分配单列表
|
||
|
||
**接口**: `GET /api/v1/allocation-orders`
|
||
|
||
**查询参数**:
|
||
```
|
||
skip: 跳过条数（默认0）
|
||
limit: 返回条数（默认20，最大100）
|
||
order_type: 单据类型
|
||
approval_status: 审批状态
|
||
execute_status: 执行状态
|
||
applicant_id: 申请人ID
|
||
target_organization_id: 目标网点ID
|
||
keyword: 搜索关键词
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
[
|
||
{
|
||
"id": 1,
|
||
"order_code": "AL202501240001",
|
||
"order_type": "allocation",
|
||
"title": "天河网点资产分配",
|
||
"approval_status": "pending",
|
||
"execute_status": "pending",
|
||
"target_organization": {
|
||
"id": 3,
|
||
"org_name": "天河网点"
|
||
},
|
||
"applicant": {
|
||
"id": 1,
|
||
"real_name": "张三"
|
||
},
|
||
"items": [
|
||
{
|
||
"asset_code": "ASSET-20250124-0001",
|
||
"asset_name": "联想台式机",
|
||
"execute_status": "pending"
|
||
}
|
||
],
|
||
"created_at": "2025-01-24T10:00:00Z"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 创建分配单
|
||
|
||
**接口**: `POST /api/v1/allocation-orders`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"order_type": "allocation",
|
||
"title": "天河网点资产分配",
|
||
"target_organization_id": 3,
|
||
"asset_ids": [1, 2, 3, 4, 5],
|
||
"expect_execute_date": "2025-01-25",
|
||
"remark": "业务需要"
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `order_type`: 单据类型（必填）
|
||
- `title`: 标题（必填）
|
||
- `source_organization_id`: 调出网点ID（调拨时必填）
|
||
- `target_organization_id`: 调入网点ID（必填）
|
||
- `asset_ids`: 资产ID列表（必填，至少1个）
|
||
- `expect_execute_date`: 预计执行日期（可选）
|
||
- `remark`: 备注（可选）
|
||
|
||
**响应**: 返回创建的分配单详情
|
||
|
||
---
|
||
|
||
### 3. 审批分配单
|
||
|
||
**接口**: `POST /api/v1/allocation-orders/{order_id}/approve`
|
||
|
||
**请求体**:
|
||
```json
|
||
{
|
||
"approval_status": "approved",
|
||
"approval_remark": "同意"
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `approval_status`: 审批状态（approved/rejected）
|
||
- `approval_remark`: 审批备注（可选）
|
||
|
||
**业务逻辑**:
|
||
- 审批通过后自动执行资产分配逻辑
|
||
- 更新资产状态
|
||
- 记录状态变更历史
|
||
|
||
---
|
||
|
||
### 4. 执行分配单
|
||
|
||
**接口**: `POST /api/v1/allocation-orders/{order_id}/execute`
|
||
|
||
**说明**: 手动执行已审批通过的分配单
|
||
|
||
---
|
||
|
||
### 5. 取消分配单
|
||
|
||
**接口**: `POST /api/v1/allocation-orders/{order_id}/cancel`
|
||
|
||
**说明**: 取消分配单（已完成的无法取消）
|
||
|
||
---
|
||
|
||
### 6. 获取分配单统计
|
||
|
||
**接口**: `GET /api/v1/allocation-orders/statistics`
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"total": 100,
|
||
"pending": 10,
|
||
"approved": 50,
|
||
"rejected": 20,
|
||
"executing": 15,
|
||
"completed": 5
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 业务流程
|
||
|
||
### 资产分配流程
|
||
|
||
```
|
||
1. 创建分配单（pending）
|
||
↓
|
||
2. 审批分配单（approved/rejected）
|
||
↓ (审批通过)
|
||
3. 执行分配逻辑（executing）
|
||
↓
|
||
4. 更新资产状态（completed）
|
||
```
|
||
|
||
### 资产调拨流程
|
||
|
||
```
|
||
1. 创建调拨单（指定调出和调入网点）
|
||
↓
|
||
2. 审批调拨单
|
||
↓
|
||
3. 执行调拨（更新资产所属网点）
|
||
↓
|
||
4. 完成调拨
|
||
```
|
||
|
||
---
|
||
|
||
## 状态说明
|
||
|
||
### 审批状态 (approval_status)
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| pending | 待审批 |
|
||
| approved | 已审批 |
|
||
| rejected | 已拒绝 |
|
||
| cancelled | 已取消 |
|
||
|
||
### 执行状态 (execute_status)
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| pending | 待执行 |
|
||
| executing | 执行中 |
|
||
| completed | 已完成 |
|
||
| cancelled | 已取消 |
|
||
|
||
### 明细执行状态 (execute_status)
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| pending | 待执行 |
|
||
| executing | 执行中 |
|
||
| completed | 已完成 |
|
||
| failed | 执行失败 |
|
||
|
||
---
|
||
|
||
## 错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 404 | 分配单不存在 |
|
||
| 400 | 资产状态不允许分配 |
|
||
| 400 | 重复审批 |
|
||
| 400 | 已完成无法取消 |
|
||
| 403 | 权限不足 |
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### Python示例
|
||
|
||
```python
|
||
import requests
|
||
|
||
BASE_URL = "http://localhost:8000/api/v1"
|
||
TOKEN = "your_access_token"
|
||
|
||
headers = {
|
||
"Authorization": f"Bearer {TOKEN}",
|
||
"Content-Type": "application/json"
|
||
}
|
||
|
||
# 1. 创建分配单
|
||
response = requests.post(
|
||
f"{BASE_URL}/allocation-orders",
|
||
json={
|
||
"order_type": "allocation",
|
||
"title": "天河网点资产分配",
|
||
"target_organization_id": 3,
|
||
"asset_ids": [1, 2, 3]
|
||
},
|
||
headers=headers
|
||
)
|
||
order = response.json()
|
||
|
||
# 2. 审批分配单
|
||
response = requests.post(
|
||
f"{BASE_URL}/allocation-orders/{order['id']}/approve",
|
||
json={
|
||
"approval_status": "approved",
|
||
"approval_remark": "同意"
|
||
},
|
||
headers=headers
|
||
)
|
||
|
||
# 3. 获取分配单列表
|
||
response = requests.get(
|
||
f"{BASE_URL}/allocation-orders",
|
||
params={"approval_status": "pending"},
|
||
headers=headers
|
||
)
|
||
orders = response.json()
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **资产状态验证**: 只有"库存中"或"使用中"的资产可以分配
|
||
2. **单据状态**: 只有"待审批"状态的分配单可以更新
|
||
3. **删除限制**: 只能删除草稿、已拒绝或已取消的分配单
|
||
4. **自动执行**: 审批通过后会自动执行资产分配逻辑
|
||
5. **状态历史**: 所有状态变更都会记录在资产状态历史表中
|
||
|
||
---
|
||
|
||
**开发完成日期**: 2025-01-24
|