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

## 基础信息

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

```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 |

**请求示例**:
```json
{
  "userId": "302021122401234567",
  "workType": "SECURITY",
  "role": "STAFF",
  "deviceId": "DEVICE_ABC123"
}
```

**返回示例**:
```json
{
  "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等) |

**请求示例**:
```json
{
  "userId": "302021122401234567",
  "longitude": 116.397428,
  "latitude": 39.909230
}
```

**返回示例**:
```json
{
  "code": 0,
  "msg": "success"
}
```

### 2.2 轨迹查询

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

**请求参数**:

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

**请求示例**:
```json
{
  "userId": "302021122401234567",
  "startTime": "2026-05-11 08:00:00",
  "endTime": "2026-05-11 18:00:00",
  "page": 1,
  "row": 50
}
```

**返回示例**:
```json
{
  "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 | 否 | 打卡地点描述 |

**请求示例**:
```json
{
  "userId": "302021122401234567",
  "userName": "张三",
  "workType": "SECURITY",
  "punchType": "ON",
  "longitude": 116.397428,
  "latitude": 39.909230,
  "punchAddress": "北京市朝阳区xxx项目南门"
}
```

**返回示例**:
```json
{
  "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 | 否 | 每页条数 |

**请求示例**:
```json
{
  "workType": "SECURITY",
  "startTime": "2026-05-01 00:00:00",
  "endTime": "2026-05-11 23:59:59",
  "page": 1,
  "row": 20
}
```

**返回示例**:
```json
{
  "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 | 否 | 备注 |

**请求示例**:
```json
{
  "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数组) |

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

**返回示例**:
```json
{
  "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 | 维修结果 |