# 资产分配管理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