Fix API compatibility and add user/role/permission and asset import/export

2026-01-25 23:36:23 +08:00
commit 501d11e14e
371 changed files with 68853 additions and 0 deletions
--- a/backend/TRANSFER_RECOVERY_API.md
+++ b/backend/TRANSFER_RECOVERY_API.md
@@ -0,0 +1,565 @@
+# 资产调拨和回收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`: 失败