# 物业报修管理 API

## 📋 文档说明

本文档记录物业报修管理相关 API 接口，包括维修分类管理、报修工单管理、工单进度跟踪等功能。

**依赖文档**: 请先阅读 [API 文档基础规范.md](./API文档基础规范.md) 了解通用规范。

---

## 🔧 维修分类管理

### 查询维修分类列表

**接口地址**: `GET /hq/pm/repairCategory/list`

**接口描述**: 分页查询维修分类列表，支持权限过滤

**权限要求**: `pm:category:list`

**请求参数**:

| 参数名       | 类型   | 必填 | 说明                  |
| ------------ | ------ | ---- | --------------------- |
| pageNum      | int    | 否   | 页码，默认 1          |
| pageSize     | int    | 否   | 页大小，默认 10       |
| categoryName | string | 否   | 分类名称              |
| categoryCode | string | 否   | 分类编码              |
| parentId     | long   | 否   | 父级分类 ID           |
| skillLevel   | string | 否   | 技能等级要求          |
| status       | string | 否   | 状态（0-停用，1-正常) |

**响应示例**:

```json
{
    "total": 6,
    "rows": [
        {
            "id": 1,
            "categoryName": "电路维修",
            "categoryCode": "ELECTRIC",
            "categoryDescription": "电路、照明、开关、插座等电气设备维修",
            "parentId": 0,
            "ancestorIds": "0",
            "levelDepth": 1,
            "childrenCount": 0,
            "requiredSkills": "电工技能、安全操作",
            "skillLevel": "2",
            "estimatedDuration": 120,
            "standardCost": 200.0,
            "iconUrl": null,
            "colorCode": "#FF6B35",
            "sortOrder": 1,
            "status": "1",
            "usageCount": 0,
            "lastUsedTime": null,
            "remark": null,
            "createTime": "2025-01-23 14:30:00"
        }
    ],
    "code": 200,
    "msg": "查询成功"
}
```

### 获取维修分类树形结构

**接口地址**: `GET /hq/pm/repairCategory/tree`

**接口描述**: 获取维修分类的树形结构数据

**权限要求**: `pm:category:tree`

**请求参数**: 无

**响应示例**:

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "id": 1,
            "categoryName": "电路维修",
            "categoryCode": "ELECTRIC",
            "categoryDescription": "电路、照明、开关、插座等电气设备维修",
            "parentId": 0,
            "children": []
        }
    ]
}
```

### 获取维修分类下拉选项

**接口地址**: `GET /hq/pm/repairCategory/options`

**接口描述**: 获取维修分类的下拉选项数据，用于表单选择器

**权限要求**: `pm:category:list`

**请求参数**: 无

**响应示例**:

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "value": 1,
            "label": "电路维修"
        },
        {
            "value": 2,
            "label": "水管维修"
        },
        {
            "value": 3,
            "label": "门窗维修"
        }
    ]
}
```

**数据格式说明**:

-   **value**: 分类 ID，用于表单提交
-   **label**: 分类名称，用于显示
-   **扁平化处理**: 将树形结构扁平化，便于下拉选择

**使用场景**:

-   报修工单创建时选择维修类型
-   表单编辑时的分类选择
-   搜索条件中的分类筛选

### 获取维修分类详情

**接口地址**: `GET /hq/pm/repairCategory/{id}`

**接口描述**: 根据 ID 获取维修分类详细信息

**权限要求**: `pm:category:query`

**路径参数**:

| 参数名 | 类型 | 必填 | 说明    |
| ------ | ---- | ---- | ------- |
| id     | long | 是   | 分类 ID |

### 新增维修分类

**接口地址**: `POST /hq/pm/repairCategory`

**接口描述**: 创建新的维修分类

**权限要求**: `pm:category:add`

**请求参数**:

```json
{
    "categoryName": "测试维修类型",
    "categoryCode": "TEST_REPAIR",
    "categoryDescription": "这是一个测试的维修类型",
    "parentId": 0,
    "skillLevel": "1",
    "estimatedDuration": 60,
    "standardCost": 100.0,
    "colorCode": "#1890FF",
    "sortOrder": 99,
    "status": "1",
    "remark": "测试数据"
}
```

---

## 🛠️ 报修工单管理

### 查询报修工单列表

**接口地址**: `GET /hq/pm/repairOrder/list`

**接口描述**: 分页查询报修工单列表，支持多种条件筛选，根据用户角色进行数据权限过滤

**权限要求**: `pm:repairOrder:list`

**数据权限说明**:

-   **超级管理员**: 可查看所有报修工单
-   **物业维修管理员** (role_key: property_maintenance_admin): 可查看所有报修工单
-   **维修人员** (role_key: maintenance_worker): 只能查看自己创建的工单和分配给自己的工单
-   **普通用户**: 只能查看自己创建的工单

**请求参数**:

| 参数名          | 类型   | 必填 | 说明            |
| --------------- | ------ | ---- | --------------- |
| pageNum         | int    | 否   | 页码，默认 1    |
| pageSize        | int    | 否   | 页大小，默认 10 |
| orderNo         | string | 否   | 工单编号        |
| title           | string | 否   | 报修标题        |
| repairLocation  | string | 否   | 报修地点        |
| categoryId      | long   | 否   | 维修类型 ID     |
| priorityLevel   | int    | 否   | 紧急程度        |
| reporterName    | string | 否   | 报修人姓名      |
| reporterPhone   | string | 否   | 报修人电话      |
| orderStatus     | string | 否   | 工单状态        |
| assigneeId      | long   | 否   | 分派维修员 ID   |
| assigneeName    | string | 否   | 分派维修员姓名  |
| createTimeRange | array  | 否   | 创建时间范围    |
| finishTimeRange | array  | 否   | 完成时间范围    |

**响应示例**:

```json
{
    "total": 1,
    "rows": [
        {
            "id": "1939510596285673473",
            "tenantId": "000000",
            "orderNo": "RO202506300002",
            "title": "详细测试工单 - 会议室投影仪故障",
            "description": "会议室投影仪无法正常启动，显示器黑屏，影响会议正常进行。设备型号：EPSON EB-U05，购买时间：2023年6月。",
            "repairLocation": "行政楼三楼305会议室",
            "categoryId": 1,
            "categoryName": "电路维修",
            "priorityLevel": 2,
            "expectedFinishTime": "2025-07-02 02:25:34",
            "reporterId": 1,
            "reporterName": "测试用户",
            "reporterPhone": "13900139001",
            "reporterDept": "信息技术部",
            "orderStatus": "1",
            "assignTime": null,
            "assigneeId": null,
            "assigneeName": null,
            "assignRemark": null,
            "startTime": null,
            "finishTime": null,
            "totalDuration": null,
            "repairResult": null,
            "usedMaterials": null,
            "followSuggestions": null,
            "evaluationScore": null,
            "evaluationTime": null,
            "attachmentCount": 0,
            "progressCount": 1,
            "cancelReason": null,
            "remark": "设备在保修期内，请联系厂家技术支持",
            "createTime": "2025-06-30 02:25:34",
            "updateTime": "2025-06-30 02:25:34"
        }
    ],
    "code": 200,
    "msg": "查询成功"
}
```

### 生成工单编号

**接口地址**: `GET /hq/pm/repairOrder/generateOrderNo`

**接口描述**: 自动生成报修工单编号

**权限要求**: 无需特殊权限

**请求参数**: 无

**响应示例**:

```json
{
    "code": 200,
    "msg": "RO202506300002",
    "data": null
}
```

**说明**: 工单编号格式为`RO + 年月日 + 序号`，如`RO202506300002`

### 获取报修统计数据

**接口地址**: `GET /hq/pm/repairOrder/statistics`

**接口描述**: 获取报修工单的统计数据，用于仪表板展示

**权限要求**: `pm:repairOrder:statistics`

**访问权限说明**:

-   **超级管理员**: 可以访问统计数据
-   **物业维修管理员** (role_key: property_maintenance_admin): 可以访问统计数据
-   **维修人员** (role_key: maintenance_worker): **无权限访问**
-   **普通用户**: **无权限访问**

**请求参数**: 无

**响应示例**:

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "totalOrders": 156,
        "pendingAssign": 23,
        "inProgress": 45,
        "completed": 88,
        "cancelled": 0,
        "avgProcessTime": 2.5,
        "avgEvaluationScore": 4.3,
        "monthlyNewOrders": 67,
        "monthlyCompletedOrders": 52,
        "statusDistribution": [
            {
                "status": "待分派",
                "count": 23,
                "percentage": 14.7
            },
            {
                "status": "进行中",
                "count": 45,
                "percentage": 28.8
            },
            {
                "status": "已完成",
                "count": 88,
                "percentage": 56.4
            }
        ],
        "categoryDistribution": [
            {
                "categoryName": "电路维修",
                "count": 45,
                "percentage": 28.8
            },
            {
                "categoryName": "水管维修",
                "count": 38,
                "percentage": 24.4
            }
        ],
        "priorityDistribution": [
            {
                "priorityLevel": 1,
                "count": 12,
                "percentage": 7.7
            },
            {
                "priorityLevel": 2,
                "count": 34,
                "percentage": 21.8
            }
        ]
    }
}
```

**统计字段说明**:

| 字段名                 | 类型  | 说明                   |
| ---------------------- | ----- | ---------------------- |
| totalOrders            | int   | 总工单数量             |
| pendingAssign          | int   | 待分派工单数           |
| inProgress             | int   | 进行中工单数           |
| completed              | int   | 已完成工单数           |
| cancelled              | int   | 已取消工单数           |
| avgProcessTime         | float | 平均处理时长（小时）   |
| avgEvaluationScore     | float | 平均评价得分（1-5 分） |
| monthlyNewOrders       | int   | 本月新增工单数         |
| monthlyCompletedOrders | int   | 本月完成工单数         |
| statusDistribution     | array | 各状态分布统计         |
| categoryDistribution   | array | 各类型分布统计         |
| priorityDistribution   | array | 紧急程度分布统计       |

### 分派工单

**接口地址**: `PUT /hq/pm/repairOrder/{orderId}/assign`

**接口描述**: 分派工单给维修员

**权限要求**: `pm:repairOrder:assign`

**路径参数**:

| 参数名  | 类型 | 必填 | 说明    | 示例值 |
| ------- | ---- | ---- | ------- | ------ |
| orderId | Long | 是   | 工单 ID | 1      |

**请求参数**:

| 参数名       | 类型   | 必填 | 说明      | 示例值     |
| ------------ | ------ | ---- | --------- | ---------- |
| assigneeId   | Long   | 是   | 维修员 ID | 2          |
| assignRemark | String | 否   | 分派备注  | "紧急处理" |

**响应示例**:

```json
{
    "code": 200,
    "msg": "分派成功",
    "data": null
}
```

**错误码**:

| 错误码 | 说明               | 解决方案      |
| ------ | ------------------ | ------------- |
| 400001 | 工单不存在         | 检查工单 ID   |
| 400002 | 维修员不存在       | 检查维修员 ID |
| 400003 | 工单状态不允许分派 | 检查工单状态  |

### 获取工单进度列表

**接口地址**: `GET /hq/pm/repairOrder/{orderId}/progress`

**接口描述**: 获取指定工单的进度记录列表

**权限要求**: `pm:repairOrder:progress`

**路径参数**:

| 参数名  | 类型 | 必填 | 说明    | 示例值 |
| ------- | ---- | ---- | ------- | ------ |
| orderId | Long | 是   | 工单 ID | 1      |

**响应示例**:

```json
{
    "code": 200,
    "msg": "查询成功",
    "data": [
        {
            "id": 1,
            "orderId": 1,
            "progressType": "5",
            "progressStatus": "正在维修",
            "progressDetail": "已到达现场，开始检查设备",
            "operatorId": 2,
            "operatorName": "张维修",
            "operatorRole": "worker",
            "locationInfo": "教学楼A座301",
            "estimatedDuration": 60,
            "operationTime": "2025-06-30 14:30:00",
            "nextStep": "更换零件",
            "issuesEncountered": "发现零件老化",
            "materialsNeeded": "电路板x1",
            "remark": "需要采购新零件"
        }
    ]
}
```

### 更新维修进度

**接口地址**: `POST /hq/pm/repairOrder/progress`

**接口描述**: 添加工单维修进度记录

**权限要求**: `pm:repairOrder:updateProgress`

**请求参数**:

| 参数名            | 类型    | 必填 | 说明                                                                                                             | 示例值                     |
| ----------------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------- | -------------------------- |
| orderId           | Long    | 是   | 工单 ID                                                                                                          | 1                          |
| progressType      | String  | 是   | 进度类型：1-工单分派，2-接收确认，3-到达现场，4-开始维修，5-进度更新，6-完成维修，7-用户评价，8-工单归档，9-其他 | "5"                        |
| progressStatus    | String  | 是   | 进度状态描述                                                                                                     | "正在维修"                 |
| progressDetail    | String  | 是   | 进度详细描述                                                                                                     | "已到达现场，开始检查设备" |
| locationInfo      | String  | 否   | 操作位置信息                                                                                                     | "教学楼 A 座 301"          |
| estimatedDuration | Integer | 否   | 预计耗时（分钟）                                                                                                 | 60                         |
| nextStep          | String  | 否   | 下一步计划                                                                                                       | "更换零件"                 |
| issuesEncountered | String  | 否   | 遇到的问题                                                                                                       | "发现零件老化"             |
| materialsNeeded   | String  | 否   | 需要的材料                                                                                                       | "电路板 x1"                |
| remark            | String  | 否   | 备注信息                                                                                                         | "需要采购新零件"           |

**响应示例**:

```json
{
    "code": 200,
    "msg": "进度更新成功",
    "data": null
}
```

### 完成工单

**接口地址**: `PUT /hq/pm/repairOrder/{orderId}/finish`

**接口描述**: 完成工单维修，填写维修结果

**权限要求**: `pm:repairOrder:complete`

**路径参数**:

| 参数名  | 类型 | 必填 | 说明    | 示例值 |
| ------- | ---- | ---- | ------- | ------ |
| orderId | Long | 是   | 工单 ID | 1      |

**请求参数**:

| 参数名            | 类型   | 必填 | 说明         | 示例值                           |
| ----------------- | ------ | ---- | ------------ | -------------------------------- |
| repairResult      | String | 是   | 维修结果描述 | "已更换故障电路板，设备恢复正常" |
| usedMaterials     | String | 否   | 使用材料清单 | "电路板 x1, 螺丝 x4"             |
| followSuggestions | String | 否   | 后续建议     | "建议定期检查电路板状态"         |

**响应示例**:

```json
{
    "code": 200,
    "msg": "工单完成成功",
    "data": null
}
```

---

## ⭐ 服务评价管理

### 创建服务评价

**接口地址**: `POST /hq/pm/repairOrder/evaluation`

**接口描述**: 创建工单服务评价

**权限要求**: `pm:repairOrder:evaluate`

**请求参数**:

| 参数名                 | 类型    | 必填 | 说明                                                           | 示例值                       |
| ---------------------- | ------- | ---- | -------------------------------------------------------------- | ---------------------------- |
| orderId                | Long    | 是   | 工单 ID                                                        | 1                            |
| evaluatedWorkerId      | Long    | 是   | 被评价维修员 ID                                                | 2                            |
| overallScore           | Number  | 是   | 综合评价得分（1.0-5.0）                                        | 4.5                          |
| qualityScore           | Number  | 是   | 维修质量得分（1.0-5.0）                                        | 4.8                          |
| attitudeScore          | Number  | 是   | 服务态度得分（1.0-5.0）                                        | 4.5                          |
| responseSpeedScore     | Number  | 是   | 响应速度得分（1.0-5.0）                                        | 4.2                          |
| communicationScore     | Number  | 是   | 沟通效果得分（1.0-5.0）                                        | 4.6                          |
| evaluationContent      | String  | 是   | 文字评价内容                                                   | "维修师傅技术过硬，态度很好" |
| satisfactionLevel      | String  | 是   | 满意度等级：1-非常满意，2-满意，3-一般，4-不满意，5-非常不满意 | "1"                          |
| isAnonymous            | Integer | 否   | 是否匿名评价：0-否，1-是                                       | 0                            |
| isPublic               | Integer | 否   | 是否公开显示：0-否，1-是                                       | 1                            |
| positiveTags           | String  | 否   | 正面标签                                                       | "技术专业,态度友好"          |
| negativeTags           | String  | 否   | 负面标签                                                       | ""                           |
| improvementSuggestions | String  | 否   | 改进建议                                                       | "希望能提前通知到达时间"     |
| remark                 | String  | 否   | 备注信息                                                       | ""                           |

**响应示例**:

```json
{
    "code": 200,
    "msg": "评价提交成功",
    "data": null
}
```

### 获取工单评价

**接口地址**: `GET /hq/pm/repairOrder/{orderId}/evaluation`

**接口描述**: 获取指定工单的服务评价信息

**权限要求**: `pm:repairOrder:query`

**路径参数**:

| 参数名  | 类型 | 必填 | 说明    | 示例值 |
| ------- | ---- | ---- | ------- | ------ |
| orderId | Long | 是   | 工单 ID | 1      |

**响应示例**:

```json
{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "id": 1,
        "orderId": 1,
        "evaluatorId": 3,
        "evaluatorName": "张老师",
        "evaluatedWorkerId": 2,
        "evaluatedWorkerName": "张维修",
        "overallScore": 4.5,
        "qualityScore": 4.8,
        "attitudeScore": 4.5,
        "responseSpeedScore": 4.2,
        "communicationScore": 4.6,
        "evaluationContent": "维修师傅技术过硬，态度很好",
        "satisfactionLevel": "1",
        "isAnonymous": 0,
        "isPublic": 1,
        "positiveTags": "技术专业,态度友好",
        "improvementSuggestions": "希望能提前通知到达时间",
        "evaluationTime": "2025-06-30 16:30:00"
    }
}
```

---

## 📊 数据字典

### 工单状态

| 值  | 说明   | 备注         |
| --- | ------ | ------------ |
| 1   | 待分派 | 已创建待分派 |
| 2   | 进行中 | 已分派进行中 |
| 3   | 已完成 | 维修完成     |
| 4   | 已取消 | 工单取消     |

### 紧急程度

| 值  | 说明 | 备注         |
| --- | ---- | ------------ |
| 1   | 低   | 一般维修     |
| 2   | 中   | 较重要维修   |
| 3   | 高   | 紧急维修     |
| 4   | 紧急 | 非常紧急维修 |

### 进度类型

| 值  | 说明     | 备注           |
| --- | -------- | -------------- |
| 1   | 工单分派 | 分派给维修员   |
| 2   | 接收确认 | 维修员确认接收 |
| 3   | 到达现场 | 到达维修现场   |
| 4   | 开始维修 | 开始进行维修   |
| 5   | 进度更新 | 维修进度更新   |
| 6   | 完成维修 | 维修工作完成   |
| 7   | 用户评价 | 用户评价完成   |
| 8   | 工单归档 | 工单归档完成   |
| 9   | 其他     | 其他操作       |

### 满意度等级

| 值  | 说明       | 备注 |
| --- | ---------- | ---- |
| 1   | 非常满意   | 5 分 |
| 2   | 满意       | 4 分 |
| 3   | 一般       | 3 分 |
| 4   | 不满意     | 2 分 |
| 5   | 非常不满意 | 1 分 |

---

## 📞 联系方式

如有物业报修相关问题，请联系开发团队或查看项目仓库的 Issues。

---

**📝 维护**: 物业报修管理 API 文档  
**🔄 更新**: 2025-07-01  
**�� 文件**: 物业报修管理 API.md