Fix API compatibility and add user/role/permission and asset import/export
This commit is contained in:
266
backend/API_QUICK_REFERENCE.md
Normal file
266
backend/API_QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# 资产管理系统API快速参考
|
||||
|
||||
> **版本**: v1.0.0
|
||||
> **更新时间**: 2025-01-24
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 基础URL
|
||||
```
|
||||
开发环境: http://localhost:8000/api/v1
|
||||
```
|
||||
|
||||
### 认证方式
|
||||
```http
|
||||
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示例
|
||||
|
||||
```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](./ALLOCATIONS_API.md)
|
||||
- [维修管理API](./MAINTENANCE_API.md)
|
||||
- [开发规范指南](../development_standards_guide.md)
|
||||
- [完整API参考](../complete_api_reference.md)
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试
|
||||
|
||||
### 运行测试
|
||||
```bash
|
||||
# 运行所有测试
|
||||
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扩展组
|
||||
Reference in New Issue
Block a user