all-project/docs/业务模块/property-maintenance

物业报修管理模块 - 总览

🎯 模块用途：学校物业维修服务数字化管理，提供从报修申请到维修完成的全流程管理

📋 模块基本信息

模块名称：property-maintenance / 物业报修管理模块
负责人：[待分配]
开发状态：⭕ 待开始
技术栈：Spring Boot 3.4.6 + Vue3 + TypeScript + Warm-Flow + Element Plus
依赖模块：用户管理模块、系统管理模块、文件服务模块
开发周期：[待规划] - [待规划]

🎯 模块概述

业务价值

本模块旨在解决学校物业维修服务的数字化管理问题，实现报修申请、任务分派、维修跟踪、服务评价的全流程线上化处理，提高维修效率，提升用户满意度，建立可追踪的服务质量体系。

核心功能

• 报修申请管理：用户在线提交报修申请，支持图片、视频上传
• 工单分派系统：物业管理员智能分派工单给合适的维修人员
• 维修进度跟踪：实时跟踪维修进度，状态可视化展示
• 服务质量评价：用户对维修服务进行评分和反馈
• 数据统计分析：维修效率、用户满意度等多维度数据分析

技术特点

• 工作流驱动：基于 Warm-Flow 引擎实现标准化业务流程
• 多媒体支持：支持图片、视频等多媒体文件上传和预览
• 权限精细化：基于角色的权限控制，确保数据安全
• 移动端适配：支持 PC 端和移动端操作，方便现场使用

📁 文档结构

property-maintenance/
├── README.md                    # 本文件 - 模块总览
├── 需求分析/
│   ├── 业务需求说明.md           # 详细业务需求
│   ├── 功能需求清单.md           # 功能点清单
│   ├── 非功能需求.md             # 性能、安全要求
│   └── 用户故事.md               # 用户使用场景
├── 技术设计/
│   ├── 数据库设计.md             # 表结构设计
│   ├── API接口设计.md            # 接口定义
│   ├── 架构设计.md               # 模块架构
│   └── 技术选型.md               # 技术决策说明
├── 实现文档/
│   ├── 后端实现说明.md           # 后端代码结构
│   ├── 前端实现说明.md           # 前端代码结构
│   ├── 关键业务逻辑.md           # 核心算法逻辑
│   └── 代码规范.md               # 编码规范
├── 测试文档/
│   ├── 测试计划.md               # 测试策略
│   ├── 测试用例.md               # 具体测试用例
│   └── 测试报告.md               # 测试结果
└── 运维文档/
    ├── 部署指南.md               # 部署步骤
    ├── 监控配置.md               # 监控指标
    └── 故障处理.md               # 常见问题

🏗️ 系统架构

模块架构图

graph TB
    subgraph "前端展示层"
        A1[报修申请页面<br/>用户提交报修]
        A2[工单管理页面<br/>管理员派单]
        A3[维修工作台<br/>维修员操作]
        A4[统计分析页面<br/>数据可视化]
    end

    subgraph "接口服务层"
        B1[报修单Controller<br/>CRUD操作]
        B2[工作流Controller<br/>流程控制]
        B3[文件服务Controller<br/>文件上传]
        B4[统计分析Controller<br/>数据统计]
    end

    subgraph "业务逻辑层"
        C1[报修单Service<br/>业务逻辑处理]
        C2[工作流Service<br/>流程管理]
        C3[通知Service<br/>消息通知]
        C4[统计Service<br/>数据分析]
    end

    subgraph "数据持久层"
        D1[报修单Mapper<br/>数据访问]
        D2[工作流Mapper<br/>流程数据]
        D3[文件Mapper<br/>文件信息]
        D4[MySQL数据库<br/>数据存储]
    end

    subgraph "外部服务"
        E1[文件存储服务<br/>OSS/本地存储]
        E2[消息通知服务<br/>短信/邮件]
        E3[用户权限服务<br/>Sa-Token]
    end

    A1 --> B1
    A2 --> B1
    A2 --> B2
    A3 --> B1
    A3 --> B2
    A4 --> B4

    B1 --> C1
    B2 --> C2
    B3 --> C1
    B4 --> C4

    C1 --> D1
    C2 --> D2
    C3 --> D1
    C4 --> D1

    D1 --> D4
    D2 --> D4
    D3 --> D4

    C1 --> E1
    C3 --> E2
    B1 --> E3

数据流向

sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant C as Controller
    participant S as Service
    participant W as 工作流引擎
    participant M as Mapper
    participant D as Database

    U->>F: 提交报修申请
    F->>C: POST /api/maintenance/repair-order
    C->>S: 创建报修单
    S->>W: 启动维修流程
    W->>M: 保存流程数据
    M->>D: 存储到数据库
    D-->>M: 返回结果
    M-->>S: 返回数据
    S-->>C: 返回报修单ID
    C-->>F: JSON响应
    F-->>U: 显示提交成功

    Note over S,W: 自动通知物业管理员

📊 核心功能模块

1. 报修申请管理

业务描述

用户通过 Web 端或移动端在线提交报修申请，填写报修地点、问题描述、紧急程度等信息，并可上传现场图片或视频作为辅助说明。系统自动生成唯一的报修单号，并启动维修工作流程。

技术实现

• 前端实现：Vue3 + Element Plus + 文件上传组件
• 后端实现：Spring Boot + MyBatis-Plus + OSS 文件服务
• 数据存储：MySQL 存储报修单信息，OSS 存储多媒体文件

关键流程

1. 用户登录认证 → 2. 填写报修信息 → 3. 上传附件文件 → 4. 提交申请 → 5. 系统生成工单 → 6. 进入分派流程

🎯 工单分派系统

业务描述

物业管理员接收用户报修申请后，根据维修类型、紧急程度、维修员专业技能和工作负荷，智能推荐并分派工单给合适的维修员。支持批量分派和分派撤回功能。

技术实现

• 前端实现：工单列表、分派对话框、维修员负荷展示
• 后端实现：工单分配算法、负荷均衡计算
• 数据存储：工单分派记录、维修员工作负荷统计

关键流程

1. 查看待分派工单 → 2. 选择维修员 → 3. 确认分派 → 4. 更新工单状态 → 5. 维修员接收工单

🔧 维修进度跟踪

业务描述

维修员接收工单后，可实时更新维修进度状态（接单、到达现场、开始维修、完成维修等），用户可通过系统实时查看维修进度。支持维修过程照片上传和问题上报。

技术实现

• 前端实现：进度时间轴展示、状态更新界面
• 后端实现：状态机管理、进度同步机制
• 数据存储：维修进度记录、状态变更日志

关键流程

1. 维修员接收工单 → 2. 更新到达状态 → 3. 开始维修 → 4. 上传进度照片 → 5. 完成维修 → 6. 提交报告

⭐ 服务质量评价

业务描述

维修完成后，用户对维修服务进行评分（1-5 星）和文字反馈，包括维修质量、服务态度、响应速度等维度。评价结果作为维修员绩效考核和服务改进的重要依据。

技术实现

• 前端实现：星级评分组件、多维度评价表单
• 后端实现：评价数据统计、满意度计算
• 数据存储：评价记录、统计分析数据

关键流程

1. 维修完成确认 → 2. 用户收到评价邀请 → 3. 多维度评分 → 4. 提交评价 → 5. 工单归档

🔌 API 接口概览

接口分类

报修单管理接口

接口名称	请求方式	路径	功能描述
创建报修单	POST	/api/maintenance/repair-order	用户提交报修申请
查询报修单列表	GET	/api/maintenance/repair-order/list	分页查询报修单列表
查询报修单详情	GET	/api/maintenance/repair-order/{id}	根据 ID 查询报修单详情
更新报修单状态	PUT	/api/maintenance/repair-order/{id}/status	更新报修单处理状态
分派工单	POST	/api/maintenance/repair-order/{id}/assign	管理员分派工单给维修员
完成维修	POST	/api/maintenance/repair-order/{id}/finish	维修员提交维修完成结果

文件管理接口

接口名称	请求方式	路径	功能描述
上传文件	POST	/api/maintenance/file/upload	上传图片、视频文件
删除文件	DELETE	/api/maintenance/file/{id}	删除已上传文件
获取文件信息	GET	/api/maintenance/file/{id}	获取文件详细信息

评价管理接口

接口名称	请求方式	路径	功能描述
提交评价	POST	/api/maintenance/evaluation	用户提交服务评价
查询评价列表	GET	/api/maintenance/evaluation/list	查询评价记录列表
统计满意度	GET	/api/maintenance/evaluation/statistics	统计服务满意度数据

统计分析接口

接口名称	请求方式	路径	功能描述
维修统计概览	GET	/api/maintenance/statistics/overview	获取维修业务概览数据
维修员工作量统计	GET	/api/maintenance/statistics/workload	统计维修员工作负荷
维修类型分析	GET	/api/maintenance/statistics/category	按维修类型统计分析
满意度趋势分析	GET	/api/maintenance/statistics/satisfaction	用户满意度趋势分析

接口规范

• 请求格式：JSON
• 响应格式：统一响应体结构
• 认证方式：JWT Token (Sa-Token)
• 权限控制：基于角色的权限验证
• 文件上传：支持多文件上传，限制文件大小和类型

🗄️ 数据模型

核心实体

报修单表 (hq_pm_repair_order)

字段名	类型	长度	非空	默认值	说明
id	BIGINT	-	Y	-	主键 ID
order_no	VARCHAR	32	Y	-	报修单号
title	VARCHAR	200	Y	-	报修标题
description	TEXT	-	Y	-	问题描述
location	VARCHAR	500	Y	-	报修地点
contact_name	VARCHAR	50	Y	-	联系人姓名
contact_phone	VARCHAR	20	Y	-	联系电话
urgency_level	TINYINT	-	Y	1	紧急程度(1-5)
expected_time	DATETIME	-	N	-	期望完成时间
repair_type	VARCHAR	50	Y	-	维修类型
status	VARCHAR	20	Y	PENDING	状态
assignee_id	BIGINT	-	N	-	分派维修员 ID
assign_time	DATETIME	-	N	-	分派时间
start_time	DATETIME	-	N	-	开始维修时间
finish_time	DATETIME	-	N	-	完成维修时间
repair_result	TEXT	-	N	-	维修结果说明
evaluation_score	DECIMAL(3,2)	-	N	-	评价分数
evaluation_comment	TEXT	-	N	-	评价内容
tenant_id	VARCHAR	20	Y	000000	租户 ID
create_dept	BIGINT	-	Y	-	创建部门
create_by	BIGINT	-	Y	-	创建者
create_time	DATETIME	-	Y	-	创建时间
update_by	BIGINT	-	Y	-	更新者
update_time	DATETIME	-	Y	-	更新时间
deleted	TINYINT	-	Y	0	删除标记

报修附件表 (hq_pm_repair_attachment)

字段名	类型	长度	非空	默认值	说明
id	BIGINT	-	Y	-	主键 ID
repair_order_id	BIGINT	-	Y	-	报修单 ID
file_name	VARCHAR	255	Y	-	文件名
file_path	VARCHAR	500	Y	-	文件路径
file_size	BIGINT	-	Y	-	文件大小
file_type	VARCHAR	50	Y	-	文件类型
attachment_type	VARCHAR	20	Y	-	附件类型
tenant_id	VARCHAR	20	Y	000000	租户 ID
create_by	BIGINT	-	Y	-	创建者
create_time	DATETIME	-	Y	-	创建时间
update_by	BIGINT	-	Y	-	更新者
update_time	DATETIME	-	Y	-	更新时间
deleted	TINYINT	-	Y	0	删除标记

维修进度记录表 (hq_pm_repair_progress)

字段名	类型	长度	非空	默认值	说明
id	BIGINT	-	Y	-	主键 ID
repair_order_id	BIGINT	-	Y	-	报修单 ID
status	VARCHAR	20	Y	-	进度状态
description	TEXT	-	N	-	进度描述
operator_id	BIGINT	-	Y	-	操作人 ID
operator_name	VARCHAR	50	Y	-	操作人姓名
progress_time	DATETIME	-	Y	-	进度更新时间
tenant_id	VARCHAR	20	Y	000000	租户 ID
create_by	BIGINT	-	Y	-	创建者
create_time	DATETIME	-	Y	-	创建时间
deleted	TINYINT	-	Y	0	删除标记

实体关系图

erDiagram
    HQ_PM_REPAIR_ORDER ||--o{ HQ_PM_REPAIR_ATTACHMENT : "一对多"
    HQ_PM_REPAIR_ORDER ||--o{ HQ_PM_REPAIR_PROGRESS : "一对多"
    HQ_PM_REPAIR_ORDER }o--|| SYS_USER : "报修人"
    HQ_PM_REPAIR_ORDER }o--|| SYS_USER : "维修员"

    HQ_PM_REPAIR_ORDER {
        bigint id PK
        varchar order_no UK
        varchar title
        text description
        varchar location
        varchar status
        bigint assignee_id FK
        datetime create_time
    }

    HQ_PM_REPAIR_ATTACHMENT {
        bigint id PK
        bigint repair_order_id FK
        varchar file_name
        varchar file_path
        varchar file_type
    }

    HQ_PM_REPAIR_PROGRESS {
        bigint id PK
        bigint repair_order_id FK
        varchar status
        text description
        bigint operator_id FK
        datetime progress_time
    }

    SYS_USER {
        bigint id PK
        varchar username
        varchar nickname
        varchar phone
    }

🔄 业务流程

主要业务流程

报修申请流程

flowchart TD
    A[用户发起报修] --> B[填写报修信息]
    B --> C{信息完整?}
    C -->|否| B
    C -->|是| D[上传附件]
    D --> E[提交申请]
    E --> F[生成报修单号]
    F --> G[通知物业管理员]
    G --> H[报修单进入待分派状态]

流程说明：

1. 用户在系统中填写报修基本信息，包括报修地点、问题描述等
2. 系统验证信息完整性，要求用户补充必要信息
3. 用户可选择上传现场图片或视频作为补充说明
4. 提交后系统自动生成唯一报修单号
5. 自动通知物业管理员有新的报修申请需要处理

工单分派流程

flowchart TD
    A[管理员查看待分派工单] --> B[选择报修单]
    B --> C[查看报修详情]
    C --> D{是否需要分派?}
    D -->|否| E[标记为无需维修]
    D -->|是| F[选择维修员]
    F --> G[确认分派]
    G --> H[更新工单状态]
    H --> I[通知维修员]
    I --> J[通知报修用户]

流程说明：

1. 物业管理员登录系统查看所有待分派的报修工单
2. 点击查看具体报修单的详细信息和附件
3. 根据维修类型和维修员专长选择合适的维修人员
4. 确认分派后系统更新工单状态为"已分派"
5. 自动通知维修员和报修用户工单分派情况

维修处理流程

flowchart TD
    A[维修员接收工单] --> B[确认接单]
    B --> C[到达现场]
    C --> D[开始维修]
    D --> E[更新维修进度]
    E --> F{维修是否完成?}
    F -->|否| D
    F -->|是| G[提交维修报告]
    G --> H[上传完成照片]
    H --> I[更新工单状态]
    I --> J[通知用户确认]

流程说明：

1. 维修员通过移动端或 PC 端接收分派的工单
2. 确认接单并更新状态为"进行中"
3. 到达维修现场，开始实际维修工作
4. 在维修过程中可随时更新进度状态
5. 维修完成后提交维修报告和现场照片
6. 系统自动通知报修用户确认维修结果

🎨 前端设计

页面结构

报修申请页面 (用户端)

• 功能：用户提交新的报修申请
• 组件：表单组件、文件上传组件、地点选择器、日期选择器
• 交互：填写表单 → 上传附件 → 提交申请 → 查看申请结果
• 数据：报修类型字典、地点选择数据、用户基本信息

工单管理页面 (管理员端)

• 功能：查看、分派和管理所有报修工单
• 组件：数据表格、筛选器、分派对话框、详情抽屉
• 交互：筛选工单 → 查看详情 → 选择维修员 → 确认分派
• 数据：工单列表数据、维修员列表、工单统计数据

维修工作台 (维修员端)

• 功能：维修员查看和处理分配给自己的工单
• 组件：工单卡片、进度更新、文件上传、状态切换
• 交互：接收工单 → 更新进度 → 上传照片 → 完成维修
• 数据：个人工单列表、进度记录、维修结果数据

统计分析页面 (管理员端)

• 功能：查看维修业务的各类统计分析数据
• 组件：图表组件、数据卡片、日期筛选器、导出功能
• 交互：选择时间范围 → 查看统计图表 → 导出报表
• 数据：统计图表数据、趋势分析数据、满意度数据

组件设计

报修申请表单组件 (RepairOrderForm)

// 组件属性接口
interface RepairOrderFormProps {
    modelValue: RepairOrderForm;
    readonly?: boolean;
    showAttachment?: boolean;
}

// 组件事件接口
interface RepairOrderFormEmits {
    'update:modelValue': [value: RepairOrderForm];
    submit: [formData: RepairOrderForm];
    cancel: [];
}

工单分派对话框 (AssignDialog)

// 组件属性接口
interface AssignDialogProps {
    visible: boolean;
    repairOrder: RepairOrderVo;
    maintainerList: MaintainerVo[];
}

// 组件事件接口
interface AssignDialogEmits {
    'update:visible': [visible: boolean];
    confirm: [assignData: AssignFormData];
    cancel: [];
}

📝 开发规范

代码结构

后端代码结构

src/main/java/org/dromara/modules/maintenance/
├── controller/          # 控制器层
│   ├── RepairOrderController.java
│   ├── RepairAttachmentController.java
│   ├── RepairProgressController.java
│   └── MaintenanceStatisticsController.java
├── domain/              # 领域对象层
│   ├── bo/             # 业务对象
│   │   ├── RepairOrderBo.java
│   │   ├── RepairOrderQueryBo.java
│   │   └── AssignRepairOrderBo.java
│   └── vo/             # 视图对象
│       ├── RepairOrderVo.java
│       ├── RepairOrderDetailVo.java
│       └── MaintenanceStatisticsVo.java
├── mapper/              # 数据访问层
│   ├── RepairOrderMapper.java
│   ├── RepairOrderMapper.xml
│   ├── RepairAttachmentMapper.java
│   └── RepairProgressMapper.java
├── service/             # 业务服务层
│   ├── IRepairOrderService.java
│   ├── IRepairAttachmentService.java
│   ├── IMaintenanceStatisticsService.java
│   └── impl/
│       ├── RepairOrderServiceImpl.java
│       ├── RepairAttachmentServiceImpl.java
│       └── MaintenanceStatisticsServiceImpl.java
└── utils/               # 工具类
    └── MaintenanceUtils.java

前端代码结构

src/views/maintenance/
├── repair-order/        # 报修单管理
│   ├── index.vue       # 报修单列表页
│   ├── form.vue        # 报修申请表单
│   └── detail.vue      # 报修单详情
├── work-order/          # 工单管理
│   ├── index.vue       # 工单管理页面
│   └── assign.vue      # 工单分派页面
├── workbench/           # 维修工作台
│   ├── index.vue       # 维修员工作台
│   └── progress.vue    # 进度更新页面
├── statistics/          # 统计分析
│   └── index.vue       # 统计分析页面
├── components/          # 页面组件
│   ├── RepairOrderForm.vue
│   ├── AssignDialog.vue
│   ├── ProgressTimeline.vue
│   └── AttachmentUpload.vue
├── types/               # 类型定义
│   └── index.ts
└── api/                 # API接口
    └── index.ts

命名规范

后端命名规范

• 实体类：RepairOrder、RepairAttachment、RepairProgress
• 服务类：RepairOrderService、MaintenanceStatisticsService
• 控制器：RepairOrderController、MaintenanceStatisticsController
• DTO 类：RepairOrderBo、RepairOrderVo、AssignRepairOrderBo

前端命名规范

• 页面组件：RepairOrderList、WorkOrderManage、MaintenanceWorkbench
• 业务组件：RepairOrderForm、AssignDialog、ProgressTimeline
• API 方法：getRepairOrderList、createRepairOrder、assignRepairOrder
• 类型接口：RepairOrderForm、RepairOrderVo、AssignFormData

数据库命名规范

• 表名：hq_pm_repair_order、hq_pm_repair_attachment、hq_pm_repair_progress
• 字段名：repair_order_id、contact_name、urgency_level
• 索引名：idx_repair_order_status、idx_repair_order_assignee

🧪 测试策略

测试分类

单元测试

• 覆盖范围：Service 层业务逻辑、工具类方法
• 测试框架：JUnit 5 + Mockito + Spring Boot Test
• 覆盖率要求：> 85%
• 重点测试：报修单状态流转、工单分派逻辑、统计计算算法

集成测试

• 覆盖范围：Controller 层 API 接口、数据库操作
• 测试框架：Spring Boot Test + TestContainers
• 测试数据：独立测试数据库
• 重点测试：完整业务流程、文件上传下载、权限控制

前端测试

• 覆盖范围：组件功能、用户交互、表单验证
• 测试框架：Vue Test Utils + Jest + Cypress
• 测试类型：组件单元测试、页面集成测试、E2E 测试

测试用例设计

功能测试用例

• 报修申请测试：正常提交、信息验证、文件上传
• 工单分派测试：分派流程、权限验证、状态更新
• 维修流程测试：接单确认、进度更新、完成提交
• 评价功能测试：评分提交、满意度统计、数据展示

性能测试用例

• 并发提交测试：模拟多用户同时提交报修申请
• 文件上传测试：大文件上传、多文件并发上传
• 数据查询测试：大数据量下的列表查询性能
• 统计分析测试：复杂统计查询的响应时间

🚀 部署运维

部署环境

开发环境

• 部署方式：本地 Docker 容器
• 数据库：MySQL 8.0
• 缓存：Redis 7.0
• 文件存储：本地文件系统
• 配置：application-dev.yml

测试环境

• 部署方式：Docker Compose
• 数据库：MySQL 8.0（测试库）
• 缓存：Redis 7.0
• 文件存储：MinIO 或 阿里云 OSS
• 配置：application-test.yml

生产环境

• 部署方式：Kubernetes
• 数据库：MySQL 8.0（主从集群）
• 缓存：Redis 7.0（集群模式）
• 文件存储：阿里云 OSS
• 负载均衡：Nginx + Ingress
• 配置：application-prod.yml

监控指标

业务指标

• 报修单提交量：每日、每周、每月报修申请数量
• 处理效率：平均处理时长、及时完成率
• 用户满意度：平均评分、满意度趋势
• 维修员工作量：工单分配数量、完成效率

技术指标

• 接口响应时间：各 API 接口的平均响应时间 < 500ms
• 文件上传成功率：文件上传成功率 > 99%
• 系统可用性：服务可用性 > 99.9%
• 错误率：系统错误率 < 0.1%

📅 开发计划

开发阶段

第一阶段：基础框架（预计 2 周）

• 数据库表结构设计和创建
• 基础实体类和 Mapper 开发
• 基础 CRUD 接口开发
• 前端页面框架搭建
• 单元测试编写

第二阶段：核心功能（预计 3 周）

• 报修申请功能开发
• 文件上传功能开发
• 工单分派功能开发
• 维修流程管理开发
• 集成测试编写

第三阶段：高级功能（预计 2 周）

• 服务评价功能开发
• 统计分析功能开发
• 移动端适配优化
• 性能优化

第四阶段：测试部署（预计 1 周）

• 完整功能测试
• 性能压力测试
• 用户验收测试
• 生产环境部署
• 上线运维监控

里程碑

• 里程碑 1：基础框架完成，能够创建和查询报修单
• 里程碑 2：核心流程打通，完整的报修-分派-维修流程
• 里程碑 3：功能完善，包括评价和统计功能
• 里程碑 4：系统上线，正式投入使用

---

📖 相关文档

• 需求分析详细文档：需求分析/业务需求说明.md
• 技术设计详细文档：技术设计/架构设计.md
• API 接口详细文档：技术设计/API 接口设计.md
• 数据库设计详细文档：技术设计/数据库设计.md
• 项目总览文档：../../项目总览/README.md
• 开发规范文档：../../开发文档/README.md

重要说明：

1. 用户权限管理：使用系统自带的用户管理、角色管理和权限管理功能，无需重新开发
2. 通知功能：本模块不包含通知功能，用户通过系统界面查看状态更新和进度变化
3. 集成说明：与现有系统的用户认证、文件存储、工作流引擎进行集成