Fix API compatibility and add user/role/permission and asset import/export
This commit is contained in:
304
backend/ALLOCATIONS_API.md
Normal file
304
backend/ALLOCATIONS_API.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# 资产分配管理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
|
||||
Reference in New Issue
Block a user