zcglxt/backend/API_QUICK_REFERENCE.md

资产管理系统API快速参考

版本: v1.0.0 更新时间: 2025-01-24

---

🚀 快速开始

基础URL

开发环境: http://localhost:8000/api/v1

认证方式

Authorization: Bearer {access_token}

---

📦 已发布模块

1. 认证模块 (/auth)

• POST /auth/login - 用户登录
• POST /auth/refresh - 刷新Token
• POST /auth/logout - 用户登出
• PUT /auth/change-password - 修改密码
• GET /auth/captcha - 获取验证码

2. 用户管理 (/users)

• GET /users - 用户列表
• POST /users - 创建用户
• GET /users/{id} - 用户详情
• PUT /users/{id} - 更新用户
• DELETE /users/{id} - 删除用户
• POST /users/{id}/reset-password - 重置密码
• GET /users/me - 当前用户信息

3. 角色权限 (/roles)

• GET /roles - 角色列表
• POST /roles - 创建角色
• GET /roles/{id} - 角色详情
• PUT /roles/{id} - 更新角色
• DELETE /roles/{id} - 删除角色
• GET /permissions/tree - 权限树

4. 设备类型管理 (/device-types)

• GET /device-types - 设备类型列表
• POST /device-types - 创建设备类型
• GET /device-types/{id} - 设备类型详情
• PUT /device-types/{id} - 更新设备类型
• DELETE /device-types/{id} - 删除设备类型
• GET /device-types/{id}/fields - 获取字段配置
• POST /device-types/{id}/fields - 添加字段

5. 机构网点管理 (/organizations)

• GET /organizations/tree - 机构树
• POST /organizations - 创建机构
• GET /organizations/{id} - 机构详情
• PUT /organizations/{id} - 更新机构
• DELETE /organizations/{id} - 删除机构

6. 品牌和供应商管理 (/brands, /suppliers)

• GET /brands - 品牌列表
• POST /brands - 创建品牌
• PUT /brands/{id} - 更新品牌
• DELETE /brands/{id} - 删除品牌
• GET /suppliers - 供应商列表
• POST /suppliers - 创建供应商
• PUT /suppliers/{id} - 更新供应商
• DELETE /suppliers/{id} - 删除供应商

7. 资产管理 (/assets)

• GET /assets - 资产列表
• GET /assets/statistics - 资产统计
• GET /assets/{id} - 资产详情
• GET /assets/scan/{code} - 扫码查询
• POST /assets - 创建资产
• PUT /assets/{id} - 更新资产
• DELETE /assets/{id} - 删除资产
• POST /assets/{id}/status - 变更状态
• GET /assets/{id}/history - 状态历史

8. 资产分配管理 (/allocation-orders) ✨新增

• GET /allocation-orders - 分配单列表
• GET /allocation-orders/statistics - 分配单统计
• GET /allocation-orders/{id} - 分配单详情
• GET /allocation-orders/{id}/items - 分配单明细
• POST /allocation-orders - 创建分配单
• PUT /allocation-orders/{id} - 更新分配单
• POST /allocation-orders/{id}/approve - 审批分配单
• POST /allocation-orders/{id}/execute - 执行分配单
• POST /allocation-orders/{id}/cancel - 取消分配单
• DELETE /allocation-orders/{id} - 删除分配单

9. 维修管理 (/maintenance-records) ✨新增

• GET /maintenance-records - 维修记录列表
• GET /maintenance-records/statistics - 维修统计
• GET /maintenance-records/{id} - 维修记录详情
• POST /maintenance-records - 创建维修记录（报修）
• PUT /maintenance-records/{id} - 更新维修记录
• POST /maintenance-records/{id}/start - 开始维修
• POST /maintenance-records/{id}/complete - 完成维修
• POST /maintenance-records/{id}/cancel - 取消维修
• DELETE /maintenance-records/{id} - 删除维修记录
• GET /maintenance-records/asset/{id} - 资产的维修记录

---

🔑 常用参数

分页参数

page: 页码（默认1）
page_size: 每页数量（默认20，最大100）
skip: 跳过条数（默认0）
limit: 返回条数（默认20）

搜索参数

keyword: 搜索关键词
status: 状态筛选

日期格式

YYYY-MM-DD

---

📊 常用状态码

资产状态

• pending - 待入库
• in_stock - 库存中
• in_use - 使用中
• transferring - 调拨中
• maintenance - 维修中
• pending_scrap - 待报废
• scrapped - 已报废
• lost - 已丢失

分配单审批状态

• pending - 待审批
• approved - 已审批
• rejected - 已拒绝
• cancelled - 已取消

分配单执行状态

• pending - 待执行
• executing - 执行中
• completed - 已完成
• cancelled - 已取消

维修记录状态

• pending - 待处理
• in_progress - 维修中
• completed - 已完成
• cancelled - 已取消

维修类型

• self_repair - 自行维修
• vendor_repair - 外部维修
• warranty - 保修维修

故障类型

• hardware - 硬件故障
• software - 软件故障
• network - 网络故障
• other - 其他故障

---

💡 使用示例

Python示例

import requests

BASE_URL = "http://localhost:8000/api/v1"
TOKEN = "your_access_token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# 获取资产列表
response = requests.get(
    f"{BASE_URL}/assets",
    params={"page": 1, "page_size": 20},
    headers=headers
)
assets = response.json()

# 创建分配单
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()

# 报修
response = requests.post(
    f"{BASE_URL}/maintenance-records",
    json={
        "asset_id": 1,
        "fault_description": "无法开机",
        "fault_type": "hardware",
        "priority": "high"
    },
    headers=headers
)
record = response.json()

---

📖 详细文档

• 资产分配管理API
• 维修管理API
• 开发规范指南
• 完整API参考

---

🧪 测试

运行测试

# 运行所有测试
pytest

# 运行特定模块测试
pytest tests/api/test_assets.py

# 查看测试覆盖率
pytest --cov=app --cov-report=html

---

📝 更新日志

v1.0.0 (2025-01-24)

• ✅ 新增资产分配管理模块（10个API端点）
• ✅ 新增维修管理模块（9个API端点）
• ✅ 完整的审批和执行流程
• ✅ 自动状态管理
• ✅ 统计分析功能

---

最后更新: 2025-01-24 维护者: 后端API扩展组