# 资产调拨和回收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`: 失败