zcglxt/backend_new/MAINTENANCE_API.md

维修管理API使用说明

版本: v1.0.0 作者: 后端API扩展组 创建时间: 2025-01-24

---

📋 目录

1. 概述
2. 故障类型说明
3. 维修类型说明
4. 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: 搜索关键词

响应示例:

[
  {
    "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

请求体:

{
  "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

请求体:

{
  "maintenance_type": "vendor_repair",
  "vendor_id": 1,
  "remark": "送往供应商维修"
}

字段说明:

• maintenance_type: 维修类型（必填）
• vendor_id: 维修供应商ID（外部维修时必填）
• remark: 备注（可选）

状态要求: 只有"待处理"状态的维修记录可以开始维修

---

4. 完成维修

接口: POST /api/v1/maintenance-records/{record_id}/complete

请求体:

{
  "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（可选）

响应示例:

{
  "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示例

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