zcglxt/backend_new/ALLOCATIONS_API.md

资产分配管理API使用说明

版本: v1.0.0 作者: 后端API扩展组 创建时间: 2025-01-24

---

📋 目录

1. 概述
2. 单据类型说明
3. 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: 搜索关键词

响应示例:

[
  {
    "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

请求体:

{
  "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

请求体:

{
  "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

响应示例:

{
  "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示例

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