cykj/hzdyjs
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'master' of http://47.99.164.66:3000/hzdyjs-xg/all-project

Browse Source
This commit is contained in:
李旭明 committed 2025-08-27 10:16:50 +08:00
2 parents 73ffd576bc 1c878d994a
commit 6c90a8e173
44 files changed
+1088 -1077
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/开发文档/API/物业报修管理API.md
-670
View File
@@ -1,670 +0,0 @@
# 物业报修管理 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