# 资产管理系统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扩展组