cykj/hzdyjs

0 Fork 0

Files

T

weizhong 3dc8cf677a “0826权限已修复”

2025-08-26 13:24:55 +08:00

25 KiB

Raw Blame History

物业报修管理 API

📋 文档说明

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

依赖文档: 请先阅读 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-正常)

响应示例:

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

请求参数: 无

响应示例:

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

获取维修分类下拉选项

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

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

权限要求: pm:category:list

请求参数: 无

响应示例:

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

请求参数:

{
    "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	否	完成时间范围

响应示例:

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

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

权限要求: 无需特殊权限

请求参数: 无

响应示例:

{
    "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): 无权限访问
普通用户: 无权限访问

请求参数: 无

响应示例:

{
    "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	否	分派备注	"紧急处理"

响应示例:

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

错误码:

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

获取工单进度列表

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

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

权限要求: pm:repairOrder:progress

路径参数:

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

响应示例:

{
    "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	否	备注信息	"需要采购新零件"

响应示例:

{
    "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	否	后续建议	"建议定期检查电路板状态"

响应示例:

{
    "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	否	备注信息	""

响应示例:

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

获取工单评价

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

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

权限要求: pm:repairOrder:query

路径参数:

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

响应示例:

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

📊 统计分析接口

详细信息参考: docs/业务模块/物业报修管理/统计分析功能.md

🔧 培训申请待审批接口 (新增 2025-01-03)

查询待审批培训申请列表

接口地址: GET /rs/training/application/pending/list

权限要求: rs:trainingapproval:process

接口说明: 专门为审批人员提供的待审批培训申请列表接口，解决了rs-Approver角色权限问题

请求参数

参数名	类型	必填	说明
pageNum	number	否	页码，默认1
pageSize	number	否	每页数量，默认10
courseName	string	否	课程名称（模糊查询）
location	string	否	培训地点（模糊查询）
status	string	否	申请状态
excludeStatus	string	否	排除状态（默认排除已通过状态"1"）

响应参数

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "applicationId": 1234567890123456789,
      "courseId": 1,
      "courseName": "Spring Boot开发培训",
      "userId": 123,
      "userName": "张三",
      "department": "技术部",
      "position": "开发工程师",
      "reason": "提升技术能力",
      "status": "0",
      "applyTime": "2025-01-03 10:00:00",
      "location": "培训中心A座",
      "duration": 3,
      "startTime": "2025-01-10 09:00:00",
      "endTime": "2025-01-12 17:00:00"
    }
  ],
  "total": 15
}

状态码说明

状态	含义	类型
0	待审核	warning
1	已通过	success
2	已拒绝	danger
3	已取消	info
4	已完成	success

权限控制

接口权限: rs:trainingapproval:process
角色支持: rs-Approver, rs-admin
数据过滤:
- rs-Approver角色：可查看所有待审批申请
- rs-admin角色：可查看所有申请
- 自动排除已通过状态的申请

使用示例

前端调用:

import { listPendingTrainingApplication } from '@/api/rs/training'

// 查询待审批列表
const getPendingList = async () => {
  const params = {
    pageNum: 1,
    pageSize: 10,
    excludeStatus: '1' // 排除已通过状态
  }
  const response = await listPendingTrainingApplication(params)
  return response
}

Curl示例:

curl -X GET "http://localhost:8080/rs/training/application/pending/list?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer your-token" \
  -H "clientid: e5cd7e4891bf95d1d19206ce24a7b32e" \
  -H "referer: http://localhost"

与原接口对比

项目	原接口	新接口
接口地址	`/rs/training/application/list`	`/rs/training/application/pending/list`
权限要求	`rs:trainingapplication:list`	`rs:trainingapproval:process`
角色支持	rs-admin	rs-Approver, rs-admin
设计目的	申请管理	审批处理
权限独立性	❌ 权限混合	✅ 权限分离

技术实现

后端Controller:

@SaCheckPermission("rs:trainingapproval:process")
@GetMapping("/pending/list")
public TableDataInfo<RsTrainingApplication> pendingList(
    RsTrainingApplication application, 
    PageQuery pageQuery) {
    // 设置租户ID和排除状态
    application.setTenantId(LoginHelper.getTenantId());
    application.setExcludeStatus("1"); // 排除已通过状态
    
    return trainingApplicationService.selectPageRsTrainingApplicationList(
        application, pageQuery);
}

权限过滤逻辑:

Service层根据rs-Approver角色自动放开数据权限
Mapper层支持excludeStatus参数过滤
前端调用专门的审批接口，权限控制更精确

接口文档最后更新: 2025-01-03
维护责任人: 系统架构师
相关文档:

docs/开发文档/培训申请权限一致性修复报告.md
.cursor/cursorrules-backend.md - 后端开发规范

25 KiB Raw Blame History Unescape Escape

物业报修管理 API

📋 文档说明

🔧 维修分类管理

查询维修分类列表

获取维修分类树形结构

获取维修分类下拉选项

获取维修分类详情

新增维修分类

🛠️ 报修工单管理

查询报修工单列表

生成工单编号

获取报修统计数据

分派工单

获取工单进度列表

更新维修进度

完成工单

⭐ 服务评价管理

创建服务评价

获取工单评价

📊 数据字典

工单状态

紧急程度

进度类型

满意度等级

📞 联系方式

📊 统计分析接口

🔧 培训申请待审批接口 (新增 2025-01-03)

查询待审批培训申请列表

请求参数

响应参数

状态码说明

权限控制

使用示例

与原接口对比

技术实现

25 KiB

Raw Blame History