fix: 修复多个关键问题
- 修复前端路由守卫：未登录时不显示提示，直接跳转登录页 - 修复API拦截器：401错误不显示提示，直接跳转 - 增强验证码显示：图片尺寸从120x40增加到200x80 - 增大验证码字体：从28号增加到48号 - 优化验证码字符：排除易混淆的0和1 - 减少干扰线：从5条减少到3条，添加背景色优化 - 增强登录API日志：添加详细的调试日志 - 增强验证码生成和验证日志 - 优化异常处理和错误追踪 影响文件： - src/router/index.ts - src/api/request.ts - app/services/auth_service.py - app/api/v1/auth.py - app/schemas/user.py 测试状态： - 前端构建通过 - 后端语法检查通过 - 验证码显示效果优化完成 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude
370
MAINTENANCE_API.md
Normal file
370
MAINTENANCE_API.md
Normal file
@@ -0,0 +1,370 @@
|
||||
# 维修管理API使用说明
|
||||
|
||||
> **版本**: v1.0.0
|
||||
> **作者**: 后端API扩展组
|
||||
> **创建时间**: 2025-01-24
|
||||
|
||||
---
|
||||
|
||||
## 📋 目录
|
||||
|
||||
1. [概述](#概述)
|
||||
2. [故障类型说明](#故障类型说明)
|
||||
3. [维修类型说明](#维修类型说明)
|
||||
4. [API端点](#api端点)
|
||||
5. [业务流程](#业务流程)
|
||||
6. [状态说明](#状态说明)
|
||||
7. [错误码](#错误码)
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
维修管理API提供资产报修、维修、维修完成等全流程管理功能。支持自行维修、外部维修和保修维修三种维修类型。
|
||||
|
||||
---
|
||||
|
||||
## 故障类型说明
|
||||
|
||||
| 类型 | 代码 | 说明 |
|
||||
|------|------|------|
|
||||
| 硬件故障 | hardware | 硬件相关故障 |
|
||||
| 软件故障 | software | 软件相关故障 |
|
||||
| 网络故障 | network | 网络相关故障 |
|
||||
| 其他故障 | other | 其他类型故障 |
|
||||
|
||||
---
|
||||
|
||||
## 维修类型说明
|
||||
|
||||
| 类型 | 代码 | 说明 |
|
||||
|------|------|------|
|
||||
| 自行维修 | self_repair | 内部人员自行维修 |
|
||||
| 外部维修 | vendor_repair | 委托供应商维修 |
|
||||
| 保修维修 | warranty | 厂商保修维修 |
|
||||
|
||||
---
|
||||
|
||||
## API端点
|
||||
|
||||
### 1. 获取维修记录列表
|
||||
|
||||
**接口**: `GET /api/v1/maintenance-records`
|
||||
|
||||
**查询参数**:
|
||||
```
|
||||
skip: 跳过条数（默认0）
|
||||
limit: 返回条数（默认20，最大100）
|
||||
asset_id: 资产ID筛选
|
||||
status: 状态筛选
|
||||
fault_type: 故障类型筛选
|
||||
priority: 优先级筛选
|
||||
maintenance_type: 维修类型筛选
|
||||
keyword: 搜索关键词
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"record_code": "MT202501240001",
|
||||
"asset": {
|
||||
"id": 1,
|
||||
"asset_code": "ASSET-20250124-0001",
|
||||
"asset_name": "联想台式机"
|
||||
},
|
||||
"fault_description": "无法开机",
|
||||
"fault_type": "hardware",
|
||||
"priority": "high",
|
||||
"status": "pending",
|
||||
"report_user": {
|
||||
"id": 1,
|
||||
"real_name": "张三"
|
||||
},
|
||||
"report_time": "2025-01-24T10:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 创建维修记录（报修）
|
||||
|
||||
**接口**: `POST /api/v1/maintenance-records`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"asset_id": 1,
|
||||
"fault_description": "无法开机，电源指示灯不亮",
|
||||
"fault_type": "hardware",
|
||||
"priority": "high",
|
||||
"maintenance_type": "vendor_repair",
|
||||
"vendor_id": 1,
|
||||
"remark": "可能是电源故障"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
- `asset_id`: 资产ID（必填）
|
||||
- `fault_description`: 故障描述（必填）
|
||||
- `fault_type`: 故障类型（可选）
|
||||
- `priority`: 优先级（low/normal/high/urgent，默认normal）
|
||||
- `maintenance_type`: 维修类型（可选）
|
||||
- `vendor_id`: 维修供应商ID（外部维修时必填）
|
||||
- `maintenance_cost`: 维修费用（可选）
|
||||
- `maintenance_result`: 维修结果描述（可选）
|
||||
- `replaced_parts`: 更换的配件（可选）
|
||||
- `images`: 维修图片URL（可选，多个逗号分隔）
|
||||
- `remark`: 备注（可选）
|
||||
|
||||
**业务逻辑**:
|
||||
- 自动生成维修单号
|
||||
- 自动将资产状态设置为"维修中"
|
||||
|
||||
---
|
||||
|
||||
### 3. 开始维修
|
||||
|
||||
**接口**: `POST /api/v1/maintenance-records/{record_id}/start`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"maintenance_type": "vendor_repair",
|
||||
"vendor_id": 1,
|
||||
"remark": "送往供应商维修"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
- `maintenance_type`: 维修类型（必填）
|
||||
- `vendor_id`: 维修供应商ID（外部维修时必填）
|
||||
- `remark`: 备注（可选）
|
||||
|
||||
**状态要求**: 只有"待处理"状态的维修记录可以开始维修
|
||||
|
||||
---
|
||||
|
||||
### 4. 完成维修
|
||||
|
||||
**接口**: `POST /api/v1/maintenance-records/{record_id}/complete`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"maintenance_result": "更换电源后正常",
|
||||
"maintenance_cost": 200.00,
|
||||
"replaced_parts": "电源模块",
|
||||
"images": "https://example.com/image1.jpg,https://example.com/image2.jpg",
|
||||
"asset_status": "in_stock"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明**:
|
||||
- `maintenance_result`: 维修结果描述（必填）
|
||||
- `maintenance_cost`: 维修费用（可选）
|
||||
- `replaced_parts`: 更换的配件（可选）
|
||||
- `images`: 维修图片URL（可选）
|
||||
- `asset_status`: 资产维修后状态（in_stock/in_use，默认in_stock）
|
||||
|
||||
**业务逻辑**:
|
||||
- 更新维修记录状态为"已完成"
|
||||
- 自动恢复资产状态（默认恢复为"库存中"）
|
||||
|
||||
---
|
||||
|
||||
### 5. 取消维修
|
||||
|
||||
**接口**: `POST /api/v1/maintenance-records/{record_id}/cancel`
|
||||
|
||||
**说明**: 取消维修记录
|
||||
|
||||
**状态要求**: 已完成的维修记录不能取消
|
||||
|
||||
---
|
||||
|
||||
### 6. 获取维修统计
|
||||
|
||||
**接口**: `GET /api/v1/maintenance-records/statistics`
|
||||
|
||||
**查询参数**:
|
||||
```
|
||||
asset_id: 资产ID（可选）
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"total": 100,
|
||||
"pending": 10,
|
||||
"in_progress": 20,
|
||||
"completed": 65,
|
||||
"cancelled": 5,
|
||||
"total_cost": 15000.00
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. 获取资产的维修记录
|
||||
|
||||
**接口**: `GET /api/v1/maintenance-records/asset/{asset_id}`
|
||||
|
||||
**查询参数**:
|
||||
```
|
||||
skip: 跳过条数（默认0）
|
||||
limit: 返回条数（默认50）
|
||||
```
|
||||
|
||||
**说明**: 获取指定资产的所有维修记录
|
||||
|
||||
---
|
||||
|
||||
## 业务流程
|
||||
|
||||
### 报修流程
|
||||
|
||||
```
|
||||
1. 创建维修记录（pending）
|
||||
↓
|
||||
2. 开始维修（in_progress）
|
||||
↓
|
||||
3. 完成维修（completed）
|
||||
↓
|
||||
4. 恢复资产状态
|
||||
```
|
||||
|
||||
### 自行维修流程
|
||||
|
||||
```
|
||||
报修 → 开始维修(self_repair) → 完成维修 → 资产恢复
|
||||
```
|
||||
|
||||
### 外部维修流程
|
||||
|
||||
```
|
||||
报修 → 开始维修(vendor_repair + vendor_id) → 送修
|
||||
→ 维修完成 → 完成维修记录 → 资产恢复
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 状态说明
|
||||
|
||||
### 维修记录状态 (status)
|
||||
|
||||
| 状态 | 说明 | 可执行操作 |
|
||||
|------|------|------------|
|
||||
| pending | 待处理 | 开始维修、取消 |
|
||||
| in_progress | 维修中 | 完成维修、取消 |
|
||||
| completed | 已完成 | 无 |
|
||||
| cancelled | 已取消 | 无 |
|
||||
|
||||
### 优先级 (priority)
|
||||
|
||||
| 级别 | 代码 | 说明 |
|
||||
|------|------|------|
|
||||
| 低 | low | 普通问题，不紧急 |
|
||||
| 正常 | normal | 常规维修 |
|
||||
| 高 | high | 影响使用，优先处理 |
|
||||
| 紧急 | urgent | 严重故障，立即处理 |
|
||||
|
||||
---
|
||||
|
||||
## 错误码
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| 404 | 维修记录不存在 |
|
||||
| 400 | 资产不存在 |
|
||||
| 400 | 只有待处理状态可以开始维修 |
|
||||
| 400 | 只有维修中状态可以完成 |
|
||||
| 400 | 已完成不能更新或取消 |
|
||||
| 400 | 外部维修必须指定供应商 |
|
||||
| 403 | 权限不足 |
|
||||
|
||||
---
|
||||
|
||||
## 使用示例
|
||||
|
||||
### Python示例
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
BASE_URL = "http://localhost:8000/api/v1"
|
||||
TOKEN = "your_access_token"
|
||||
|
||||
headers = {
|
||||
"Authorization": f"Bearer {TOKEN}",
|
||||
"Content-Type": "application/json"
|
||||
}
|
||||
|
||||
# 1. 报修
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/maintenance-records",
|
||||
json={
|
||||
"asset_id": 1,
|
||||
"fault_description": "无法开机",
|
||||
"fault_type": "hardware",
|
||||
"priority": "high"
|
||||
},
|
||||
headers=headers
|
||||
)
|
||||
record = response.json()
|
||||
|
||||
# 2. 开始维修
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/maintenance-records/{record['id']}/start",
|
||||
json={
|
||||
"maintenance_type": "self_repair"
|
||||
},
|
||||
headers=headers
|
||||
)
|
||||
|
||||
# 3. 完成维修
|
||||
response = requests.post(
|
||||
f"{BASE_URL}/maintenance-records/{record['id']}/complete",
|
||||
json={
|
||||
"maintenance_result": "更换电源后正常",
|
||||
"maintenance_cost": 200.00,
|
||||
"replaced_parts": "电源模块",
|
||||
"asset_status": "in_stock"
|
||||
},
|
||||
headers=headers
|
||||
)
|
||||
|
||||
# 4. 获取维修统计
|
||||
response = requests.get(
|
||||
f"{BASE_URL}/maintenance-records/statistics",
|
||||
headers=headers
|
||||
)
|
||||
stats = response.json()
|
||||
print(f"总维修费用: {stats['total_cost']}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **资产状态**: 创建维修记录会自动将资产状态设置为"维修中"
|
||||
2. **状态恢复**: 完成维修会自动恢复资产状态（默认恢复为"库存中"）
|
||||
3. **外部维修**: 外部维修必须指定维修供应商
|
||||
4. **费用记录**: 维修费用在完成维修时记录
|
||||
5. **图片上传**: 支持多张图片，URL用逗号分隔
|
||||
6. **历史记录**: 资产的所有维修记录都会保留，可追溯
|
||||
|
||||
---
|
||||
|
||||
## 开发建议
|
||||
|
||||
1. **图片上传**: 配合文件上传API使用，上传维修前后照片
|
||||
2. **消息通知**: 维修状态变更时发送通知给相关人员
|
||||
3. **费用统计**: 定期统计维修费用，分析维修成本
|
||||
4. **故障分析**: 根据故障类型和维修记录，分析资产质量问题
|
||||
|
||||
---
|
||||
|
||||
**开发完成日期**: 2025-01-24
|
||||
Reference in New Issue
Block a user