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

删除多余的md文档

Browse Source
This commit is contained in:
zlwu committed 2025-08-26 14:41:10 +08:00
1 parent 7c08e1b567
commit e4eb5e316e
1 file changed
-811
Download Patch File Download Diff File Expand all files Collapse all files
docs/开发文档/API/物业报修管理API.md
-811
View File
@@ -1,811 +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
## 📊 统计分析接口
**详细信息参考**: `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"） |
#### 响应参数
```json
{
"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角色：可查看所有申请
- 自动排除已通过状态的申请
#### 使用示例
**前端调用**:
```typescript
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示例**:
```bash
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**:
```java
@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` - 后端开发规范