物业人员管理系统 API 接口文档

基础信息

• 基础路径: http://{host}:{port}/app/
• 请求方式: 统一使用 POST（遵循项目 Cmd 模式）
• 数据格式: JSON
• 统一返回格式:

{
  "code": 0,
  "msg": "success",
  "data": {}
}

---

一、用户绑定接口

1.1 用户绑定工种

服务编码: property.userBind 请求路径: /app/property.userBind 功能描述: 用户绑定工种和设备信息

请求参数:

参数名	类型	必填	说明
userId	String	是	用户ID
workType	String	是	工种: CLEANING(保洁)/SECURITY(保安)/ENGINEERING(工程维修)
role	String	否	角色: ADMIN(管理员)/STAFF(员工)，默认STAFF
deviceId	String	否	绑定设备ID

请求示例:

{
  "userId": "302021122401234567",
  "workType": "SECURITY",
  "role": "STAFF",
  "deviceId": "DEVICE_ABC123"
}

返回示例:

{
  "code": 0,
  "msg": "success"
}

---

二、定位接口

2.1 实时定位上报

服务编码: property.locationReport 请求路径: /app/property.locationReport 功能描述: 接收安卓端每3秒上报的经纬度，自动去重存储

请求参数:

参数名	类型	必填	说明
userId	String	是	用户ID
longitude	BigDecimal	是	经度(-180~180)
latitude	BigDecimal	是	纬度(-90~90)
bindRelation	String	否	绑定关系(工单ID/巡更ID等)

请求示例:

{
  "userId": "302021122401234567",
  "longitude": 116.397428,
  "latitude": 39.909230
}

返回示例:

{
  "code": 0,
  "msg": "success"
}

2.2 轨迹查询

服务编码: property.queryLocationTracks 请求路径: /app/property.queryLocationTracks 功能描述: 按用户ID/时间范围查询历史轨迹坐标

请求参数:

参数名	类型	必填	说明
userId	String	是	用户ID
startTime	String	否	开始时间(yyyy-MM-dd HHss)
endTime	String	否	结束时间(yyyy-MM-dd HHss)
page	int	否	页码(从1开始)
row	int	否	每页条数(默认20)

请求示例:

{
  "userId": "302021122401234567",
  "startTime": "2026-05-11 08:00:00",
  "endTime": "2026-05-11 18:00:00",
  "page": 1,
  "row": 50
}

返回示例:

{
  "code": 0,
  "msg": "success",
  "data": {
    "data": [
      {
        "id": 1001,
        "user_id": "302021122401234567",
        "user_name": "张三",
        "work_type": "SECURITY",
        "longitude": 116.397428,
        "latitude": 39.909230,
        "report_time": "2026-05-11 09:00:05",
        "loc_status": "NORMAL"
      }
    ],
    "total": 150
  }
}

---

三、打卡接口

3.1 上下班打卡

服务编码: property.attendancePunch 请求路径: /app/property.attendancePunch 功能描述: 记录打卡时间、地点、坐标，校验当天重复打卡 业务规则: 打卡必须关联定位坐标，无定位不允许打卡

请求参数:

参数名	类型	必填	说明
userId	String	是	用户ID
userName	String	否	用户姓名
workType	String	否	工种
punchType	String	是	打卡类型: ON(上班)/OFF(下班)
longitude	BigDecimal	是	打卡经度
latitude	BigDecimal	是	打卡纬度
punchAddress	String	否	打卡地点描述

请求示例:

{
  "userId": "302021122401234567",
  "userName": "张三",
  "workType": "SECURITY",
  "punchType": "ON",
  "longitude": 116.397428,
  "latitude": 39.909230,
  "punchAddress": "北京市朝阳区xxx小区南门"
}

返回示例:

{
  "code": 0,
  "msg": "success"
}

3.2 打卡记录查询

服务编码: property.queryAttendanceRecords 请求路径: /app/property.queryAttendanceRecords 功能描述: 按工种/时间/人员查询打卡数据

请求参数:

参数名	类型	必填	说明
userId	String	否	用户ID
workType	String	否	工种: CLEANING/SECURITY/ENGINEERING
punchType	String	否	打卡类型: ON/OFF
startTime	String	否	开始时间
endTime	String	否	结束时间
page	int	否	页码
row	int	否	每页条数

请求示例:

{
  "workType": "SECURITY",
  "startTime": "2026-05-01 00:00:00",
  "endTime": "2026-05-11 23:59:59",
  "page": 1,
  "row": 20
}

返回示例:

{
  "code": 0,
  "msg": "success",
  "data": {
    "data": [
      {
        "id": "10xxxxx",
        "user_id": "302021122401234567",
        "user_name": "张三",
        "work_type": "SECURITY",
        "punch_type": "ON",
        "punch_time": "2026-05-11 08:00:00",
        "punch_address": "北京市朝阳区xxx小区南门",
        "longitude": 116.397428,
        "latitude": 39.909230
      }
    ],
    "total": 22
  }
}

---

四、保安巡更接口

4.1 巡更上报

服务编码: property.patrolReport 请求路径: /app/property.patrolReport 功能描述: 保安人员上报巡更数据，关联人员+位置

请求参数:

参数名	类型	必填	说明
userId	String	是	巡更人ID
userName	String	否	巡更人姓名
patrolLocation	String	是	巡更地点
patrolContent	String	否	巡更内容
longitude	BigDecimal	是	巡更经度
latitude	BigDecimal	是	巡更纬度
images	String	否	图片URL列表(JSON数组)
remark	String	否	备注

请求示例:

{
  "userId": "302021122401234567",
  "userName": "张三",
  "patrolLocation": "A栋-B栋连廊",
  "patrolContent": "检查消防设施完好，通道畅通",
  "longitude": 116.397428,
  "latitude": 39.909230,
  "images": "[\"https://img.example.com/patrol1.jpg\"]",
  "remark": "一切正常"
}

4.2 巡更记录查询

服务编码: property.queryPatrolRecords 请求路径: /app/property.queryPatrolRecords

---

五、保洁作业接口

5.1 作业上报

服务编码: property.cleaningReport 请求路径: /app/property.cleaningReport

请求参数:

参数名	类型	必填	说明
userId	String	是	作业人ID
userName	String	否	作业人姓名
workArea	String	是	作业区域
workContent	String	否	作业内容
longitude	BigDecimal	是	作业经度
latitude	BigDecimal	是	作业纬度
images	String	否	图片URL列表(JSON数组)
remark	String	否	备注

5.2 保洁记录查询

服务编码: property.queryCleaningRecords 请求路径: /app/property.queryCleaningRecords

---

六、维修工单接口

6.1 提交工单

服务编码: property.submitRepairOrder 请求路径: /app/property.submitRepairOrder 功能描述: 所有人可提交工单，自动分配给工程维修人员

请求参数:

参数名	类型	必填	说明
submitterId	String	是	提交人ID
submitterName	String	否	提交人姓名
title	String	是	工单标题
description	String	否	工单描述
repairLocation	String	是	报修位置
longitude	BigDecimal	是	报修经度
latitude	BigDecimal	是	报修纬度
images	String	否	报修图片(JSON数组)

请求示例:

{
  "submitterId": "302021122401234567",
  "submitterName": "李四",
  "title": "3栋2单元电梯故障",
  "description": "电梯门无法正常关闭，存在安全隐患",
  "repairLocation": "3栋2单元电梯间",
  "longitude": 116.397428,
  "latitude": 39.909230,
  "images": "[\"https://img.example.com/repair1.jpg\"]"
}

返回示例:

{
  "code": 0,
  "msg": "success",
  "data": "20xxxxx"
}

data 为工单ID

6.2 更新工单状态

服务编码: property.updateRepairStatus 请求路径: /app/property.updateRepairStatus 功能描述: 接单/开始维修/完成/取消 业务规则: 工单状态变更自动通知提交人

请求参数:

参数名	类型	必填	说明
id	String	是	工单ID
status	String	是	状态: PENDING/REPAIRING/COMPLETED/CANCELLED
repairerId	String	否	维修人ID(接单时)
repairResult	String	否	维修结果(完成时)
resultImages	String	否	维修结果图片(完成时)

工单状态流转:

PENDING(待接单) → REPAIRING(维修中) → COMPLETED(已完成)
                 → CANCELLED(已取消)

6.3 工单查询

服务编码: property.queryRepairOrders 请求路径: /app/property.queryRepairOrders

请求参数:

参数名	类型	必填	说明
submitterId	String	否	提交人ID
repairerId	String	否	维修人ID
status	String	否	工单状态
startTime	String	否	开始时间
endTime	String	否	结束时间
page	int	否	页码
row	int	否	每页条数

---

七、消息通知接口

7.1 查询通知

服务编码: property.queryMessages 请求路径: /app/property.queryMessages

参数名	类型	必填	说明
userId	String	否	接收人ID
isRead	String	否	是否已读: 0/1
msgType	String	否	类型: REPAIR_STATUS/REPAIR_NEW

7.2 标记已读

服务编码: property.readMessage 请求路径: /app/property.readMessage

参数名	类型	必填	说明
id	String	是	消息ID

---

八、人员查询接口

8.1 人员列表

服务编码: property.queryUsers 请求路径: /app/property.queryUsers

参数名	类型	必填	说明
workType	String	否	工种筛选: CLEANING/SECURITY/ENGINEERING
status	String	否	状态: ON(在职)/OFF(离职)
name	String	否	姓名模糊搜索
page	int	否	页码
row	int	否	每页条数

---

附录

A. 工种枚举值

值	说明
CLEANING	保洁
SECURITY	保安
ENGINEERING	工程维修

B. 工单状态枚举值

值	说明	触发动作
PENDING	待接单	自动通知维修人员
REPAIRING	维修中	记录接单时间
COMPLETED	已完成	记录完成时间，通知提交人
CANCELLED	已取消	通知提交人

C. 错误码

code	说明
0	成功
非0	失败，msg字段包含具体错误信息

D. 前后端字段对照表

数据库字段	Java PO字段	JSON字段	说明
user_id	userId	userId	用户ID
work_type	workType	workType	工种
report_time	reportTime	reportTime	上报时间
punch_type	punchType	punchType	打卡类型
longitude	longitude	longitude	经度
latitude	latitude	latitude	纬度
loc_status	locStatus	locStatus	定位状态
patrol_location	patrolLocation	patrolLocation	巡更地点
patrol_content	patrolContent	patrolContent	巡更内容
work_area	workArea	workArea	作业区域
submitter_id	submitterId	submitterId	提交人ID
repairer_id	repairerId	repairerId	维修人ID
repair_result	repairResult	repairResult	维修结果