zcglxt/MAINTENANCE_API.md

# 维修管理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