smartClean/docs/requirements.md

# 智慧清洁 SaaS 平台 - 业务需求全景文档

> 基于后端 xiaoqu-intellectual-web 和 xiaoqu-intellectual-task 两个项目的代码分析整理

---

## 一、系统概述

智慧清洁 SaaS 平台面向物业/市政清洁行业，提供从计划排班、任务调度、打卡考勤、IoT设备管理到绩效分析的全链路数字化管理能力。

**系统架构**：
- **Web 服务**（端口 8095）：提供 REST API，支撑后台管理 SPA
- **Task 服务**（端口 8097）：定时任务调度 + MQTT 设备通信 + 消息推送

---

## 二、业务模块清单

### 模块 1：登录与认证

| 功能 | 端点 | 说明 |
|------|------|------|
| 短信验证码登录 | `POST /login` | 手机号+验证码登录，生成UUID（30天有效期） |
| 用户退出 | `GET /logOut` | 清除Redis登录态 |
| 发送验证码 | `GET /sms/sendCode` | 短信平台发送验证码 |

**业务规则**：
- 单点登录控制，防止多终端同时登录
- 请求签名机制：UUID + 时间戳 + 手机号 MD5签名
- 签名有效期10秒窗口
- 登录日志记录（IP、登录类型）

---

### 模块 2：权限管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 设置权限组人员 | `POST /authority/setAuthorityUser` | 批量添加用户到权限组 |
| 查询权限组成员 | `POST /authority/getAuthorityUserList` | 支持分页查询 |

**动态权限体系**：
- **字段级权限**：按权限组控制表格列的显示/隐藏
- **按钮级权限**：按权限组控制操作按钮的可见性
- 权限链路：权限组 → 用户 → 页面 → 字段/按钮

---

### 模块 3：用户与组织管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 用户分页查询 | `POST /userCenter/pageList` | 按服务区域、事项、技能、标签筛选 |
| 新增/修改用户 | `POST /userCenter/addOrUpdateUser` | |
| 删除用户 | `POST /userCenter/deleteUser` | |
| 用户导出 | `POST /userCenter/export` | Excel导出 |
| 用户菜单树 | `POST /userCenter/getUserMenuTree` | |
| 用户下拉选择 | `POST /userCenter/selectUsers` | |

**用户属性**：
- 工作状态：作业(0) / 转场(1) / 空闲(2) / 休息(3)
- 关联：班组、技能标签、事项标签、服务区域、考勤设置

---

### 模块 4：班组管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 班组分页查询 | `POST /workGroup/pageList` | |
| 新增/修改班组 | `POST /workGroup/addOrUpdate` | |
| 删除班组 | `POST /workGroup/deleteWorkGroup` | |
| 班组导出 | `POST /workGroup/export` | |
| 设置班组负责人 | `POST /workGroup/setWorkGroupPrincipal` | |
| 设置班组成员 | `POST /workGroup/setWorkGroupMember` | |
| 获取班组成员 | `POST /workGroup/getWorkGroupMember` | |

---

### 模块 5：标签与技能管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 标签分页查询 | `POST /label/pageList` | |
| 新增/修改标签 | `POST /label/addOrUpdate` | |
| 删除标签 | `POST /label/delete` | |
| 获取所有标签 | `POST /label/allLabels` | |
| 技能分页查询 | `POST /skill/pageList` | |
| 新增/修改技能 | `POST /skill/addOrUpdate` | |
| 删除技能 | `POST /skill/delete` | |
| 获取所有技能 | `POST /skill/allSkills` | |

---

### 模块 6：基础数据管理

#### 6.1 网格管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 网格查询 | `POST /grid/pageList` | 建筑/楼层/多级网格 |
| 新增/修改网格 | `POST /grid/addOrUpdateGrid` | |
| 删除网格 | `POST /grid/deleteGrid` | |
| 批量导入网格 | `POST /grid/importGrid` | |
| 网格负责人列表 | `POST /grid/gridPrincipalList` | |

**网格级别**：建筑(1) → 楼层(2) → 多级网格(3)

#### 6.2 场景管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 场景查询 | `POST /scenes/pageList` | 厕所、楼道等特定场景 |
| 新增/修改场景 | `POST /scenes/addOrUpdateScenes` | |
| 删除场景 | `POST /scenes/deleteScenes` | |
| 批量导入场景 | `POST /scenes/batchInsertScenes` | |
| 导入场景模板 | `POST /scenes/importScenes` | |

**场景级别**：一级场景(1，如卫生间) → 二级场景(2，如楼层卫生间)

#### 6.3 场景对象关联

| 功能 | 端点 | 说明 |
|------|------|------|
| 场景对象查询 | `POST /sceneObject/sceneObjectPageList` | |
| 关联对象到场景 | `POST /sceneObject/addOrUpdateSceneObject` | |

#### 6.4 对象管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 对象分页查询 | `POST /object/objectPageList` | 支持树查询 |
| 新增/修改对象 | `POST /object/addOrUpdateObject` | |
| 删除对象 | `POST /object/deleteObject` | |
| 批量导入对象 | `POST /object/importObject` | |

#### 6.5 事项管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 事项分页查询 | `POST /matter/matterPageList` | |
| 批量添加事项 | `POST /matter/addMatter` | |
| 修改事项 | `POST /matter/updateMatter` | |
| 删除事项 | `POST /matter/deleteMatter` | |

#### 6.6 作业管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 作业分页查询 | `POST /operation/oprationPageList` | 含工具关联 |
| 新增作业 | `POST /operation/addOperation` | |
| 修改作业 | `POST /operation/updateOperation` | |
| 删除作业 | `POST /operation/deleteOperation` | |
| 作业导出 | `POST /operation/export` | |

#### 6.7 工具管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 工具分页查询 | `POST /tools/toolsPageList` | |
| 新增/修改工具 | `POST /tools/addOrUpdateTools` | |
| 删除工具 | `POST /tools/deleteTools` | |

**层级关系**：对象(Object) → 事项(Matter) → 作业(Operation) + 工具(Tools)

---

### 模块 7：计划管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 计划分页查询 | `POST /plan/planPageList` | 按场景、对象、作业筛选 |
| 新增/修改计划 | `POST /plan/addOrUpdatePlan` | |
| 删除计划 | `POST /plan/deletePlan` | |
| 启用计划 | `POST /plan/enablePlan` | |
| 禁用计划 | `POST /plan/disablePlan` | |
| 计划导出 | `POST /plan/export` | 保洁/巡检/设备维护三类 |
| 执行计划 | `POST /plan/executePlan` | 立即生成任务 |
| 复制计划 | `POST /plan/copyPlan` | |
| 计划选择列表 | `POST /plan/selectPlanList` | |
| 计划详情 | `POST /plan/getPlanDetail` | |

**计划类型**：
- 保洁计划（appointment）
- 巡检计划（inspect）
- 设备维护计划（devOps）

**周期规则**：
- 周期类型：天(0) / 周(1，指定周几) / 月(2，指定日期)
- 周期模式：不重复(0) / 周期重复(1) / 间隔重复(2)
- 支持节假日跳过或强制执行
- 支持人次触发（按规定人数完成后自动生成下一轮）

**计划关联**：
- 计划对象（PlanObject）- 清洁对象清单
- 计划作业（PlanOperation）- 作业步骤
- 计划场景（PlanScenes）- 执行范围
- 计划用户（PlanUser）- 分配人员
- 计划班组（PlanWorkGroup）- 分配班组

---

### 模块 8：任务管理

#### 8.1 清洁/保洁任务

| 功能 | 端点 | 说明 |
|------|------|------|
| 任务分页查询 | `POST /task/pageList` | 按网格/场景、状态、时间筛选 |
| 任务明细导出 | `POST /task/export` | Excel |
| 人工取消任务 | `POST /task/cancel` | |
| 查看任务详情 | `POST /task/look` | 含对象、作业、进度、积分 |
| 设置任务优先级 | `POST /task/setTaskTaskOrder` | |

#### 8.2 巡检任务

| 功能 | 端点 | 说明 |
|------|------|------|
| 巡检任务列表 | `POST /taskInspect/pageList` | |
| 巡检任务导出 | `POST /taskInspect/export` | |
| 巡检任务详情 | `POST /taskInspect/look` | |
| 上传巡检照片 | `POST /taskInspect/updateInspectPic` | |

#### 8.3 用户上报任务

| 功能 | 端点 | 说明 |
|------|------|------|
| 上报任务列表 | `POST /taskUserUpload/pageList` | |
| 上报任务详情 | `POST /taskUserUpload/look` | |
| 人工设置时薪 | `POST /taskUserUpload/setWageByManual` | |

**任务状态流转**：
```
已生成(0) → 已匹配(1) → 待抢单(2) → 已接单(3) → 作业中(4) → 按时完成(5) / 超时完成(6)
                                                              ↘ 人工取消(7) / 系统取消(8) / 未完成(9)
```

**任务类型**：
- 0/1/2 = 保洁任务
- 3/4 = 用户上报任务
- 5 = 巡检任务

---

### 模块 9：打卡与考勤

| 功能 | 端点 | 说明 |
|------|------|------|
| 打卡记录查询 | `POST /punchRecord/pageList` | 按网格/场景、时间筛选 |
| 打卡记录导出 | `POST /punchRecord/export` | |
| 考勤记录查询 | `POST /attendance/pageList` | |
| 考勤记录导出 | `POST /attendance/export` | |
| 日打卡统计查询 | `POST /punchRecordDayStatis/pageList` | 按用户分组 |
| 日打卡统计导出 | `POST /punchRecordDayStatis/export` | |

---

### 模块 10：效率与绩效分析

| 功能 | 端点 | 说明 |
|------|------|------|
| 任务人效查询 | `POST /efficiency/taskEfficiencyPageList` | 按员工统计 |
| 人效数据导出 | `POST /efficiency/export` | |
| 时薪分页查询 | `POST /wage/wagePageList` | |
| 新增/修改时薪 | `POST /wage/addOrUpdateWage` | |
| 删除时薪 | `POST /wage/deleteWage` | |
| 积分换算时薪 | `POST /wage/getAmount` | |

**计价逻辑**：任务完成 → 获得积分(point) → 根据时薪表(Wage)换算金额

---

### 模块 11：用户上报管理

| 功能 | 端点 | 说明 |
|------|------|------|
| 上报用户列表 | `POST /escalationUser/pageList` | |
| 添加/修改上报用户 | `POST /escalationUser/addOrUpdate` | |
| 导出 | `POST /escalationUser/export` | |

---

### 模块 12：系统参数配置

| 功能 | 端点 | 说明 |
|------|------|------|
| 站点参数查询 | `POST /taskDistrictParam/taskDistrictParamPageList` | |
| 修改站点参数 | `POST /taskDistrictParam/updateTaskDistrictParam` | 紧急/特殊任务限制数 |

---

## 三、Task 服务 - 定时任务与后台处理

### 模块 13：任务自动调度引擎（XXL-Job）

| 任务 | 触发方式 | 说明 |
|------|----------|------|
| planCreateTask | XXL-Job 动态创建 | 根据计划规则自动生成清洁/巡检/维护任务 |
| planDisableTask | XXL-Job 动态创建 | 按时间段禁用/启用任务生成 |
| InitWatch | XXL-Job 调度 | 手表设备初始化（震动/语音/蓝牙参数） |
| userRestStartTask | XXL-Job 调度 | 员工开始休息（记录、状态变更、蓝牙关闭） |
| userRestEndTask | XXL-Job 调度 | 员工结束休息（恢复状态） |
| restCountDown | XXL-Job 调度 | 休息倒计时监控，超时自动恢复 |

### 模块 14：任务处理队列（Spring @Scheduled）

| 任务 | 频率 | 说明 |
|------|------|------|
| 任务人员派单 | 每秒 | 根据计划分配任务给清洁员 |
| 任务过期处理 | 每秒 | 超时任务自动标记超期 |
| 任务完成处理 | 每秒 | 完成后计算工资、评分 |
| 任务重派发 | 每秒 | 失败/拒绝后重新分配 |
| 巡检任务派单 | 每秒 | 巡检任务分配 |
| 上报任务派单 | 每秒 | 用户上报维修任务分配 |
| 设备维护自动完成 | 每秒 | 部分设备维护任务自动标记完成 |
| 设备告警任务生成 | 每秒 | 监听设备告警，自动创建维护任务 |

---

### 模块 15：消息推送系统

| 任务 | 频率 | 说明 |
|------|------|------|
| 个推推送 | 每秒 | 通过个推SDK推送APP通知 |
| MQTT任务状态推送 | 每2秒 | 推送任务状态变更到手机端 |
| 任务动态消息生成 | 每2秒 | 生成任务动态并存储 |

**推送类型**：
- 新任务提醒（status=1）
- 抢单池任务（status=2）
- 已接单通知（status=3）
- 任务取消通知（status=7/8）
- 厕所保养提醒（status=-1）

**推送方式**：
- 在线推送：NotificationTemplate，立即推送
- 离线推送：TransmissionTemplate，24小时内推送，支持厂商通道

---

### 模块 16：IoT 设备通信（MQTT）

| 任务 | 频率 | 说明 |
|------|------|------|
| 手表连接状态监听 | 每秒 | 监测上下线，维护设备状态 |
| 手表震动语音参数下发 | 每秒 | 实时调整手表配置 |
| 手表参数初始化 | 每2秒 | 初始化手表配置 |
| 手表绑定/解绑消息 | 每2秒 | 下发绑定/解绑指令 |
| 手表任务消息推送 | 每2秒 | 下发新任务到手表 |
| 任务-用户关联处理 | 每2秒 | 将任务消息转换为手表格式 |
| 考勤状态消息 | 每秒 | 下班提醒，关闭手表蓝牙 |
| 放大镜监控消息 | 每秒 | 实时位置追踪提醒 |
| 心跳保活 | 每20秒/298秒 | 保持手表连接 |

---

### 模块 17：蓝牙定位与轨迹追踪

| 任务 | 频率 | 说明 |
|------|------|------|
| 蓝牙信标定位 | 每秒 | 根据RSSI信号强度计算员工位置 |
| 下班定位关闭 | 每秒 | 结束进行中的轨迹记录 |

**定位逻辑**：
- 手表扫描周围蓝牙信标 → 上报信标MAC+RSSI → 服务端计算位置
- RSSI ≥ 阈值 → 进入信标范围 → 记录驻留时间
- 同一位置停留 ≥ 5秒保存轨迹
- 生成员工轨迹记录（UserTrajectory）

---

### 模块 18：员工休息管理

**完整流程**：
1. 员工点击休息 → 创建休息记录 → 更新状态为"休息中"
2. 存入Redis倒计时（默认60分钟）
3. 发送蓝牙关闭消息到手表
4. 倒计时结束 → 自动生成休息完成记录 → 恢复员工状态

---

### 模块 19：节假日同步

| 任务 | 频率 | 说明 |
|------|------|------|
| 节假日同步 | 每年12月28日 06:06:06 | 调用外部API同步下一年节假日 |

**节假日类型**：工作日(0) / 法定节假日(1) / 调休日(2) / 周末(3)

---

## 四、核心业务流程

### 流程 1：清洁任务全生命周期

```
创建计划(Plan)
  ↓
定义：对象 + 作业 + 场景范围 + 人员/班组
  ↓
启用计划 → XXL-Job 定时触发 planCreateTask
  ↓
生成 TaskInfo → 推入 PlanTaskQueue
  ↓
TaskCorrelationSetTask 派单（匹配人员）
  ↓
推送通知：个推(APP) + MQTT(手表)
  ↓
员工接单 → 开始作业 → 完成作业
  ↓
核算积分 → 换算时薪 → 绩效统计
```

### 流程 2：设备告警 → 维护任务

```
设备传感器告警（如纸巾不足、空气质量异常）
  ↓
告警推入 taskCommand 队列
  ↓
TaskCreateQueue 处理：去重检查 + 创建 TaskInfo
  ↓
分配维护员 → 推送通知
  ↓
维护员完成维护 → 标记完成
```

### 流程 3：员工实时定位

```
手表持续扫描蓝牙信标
  ↓
上报信标数据 → BleutoothLocationQueue
  ↓
计算位置 → 保存 UserLocation
  ↓
生成驻留轨迹 → UserTrajectory
  ↓
支撑人效分析报表
```

---

## 五、核心数据模型

| 实体 | 说明 | 所属库 |
|------|------|--------|
| TaskInfo | 任务主表 | db2 |
| Plan | 清洁/巡检/维护计划 | db2 |
| PlanObject | 计划对象清单 | db2 |
| PlanOperation | 计划作业 | db2 |
| PlanScenes | 计划执行范围 | db2 |
| TaskUser | 任务分配人员 | db2 |
| TaskScenes | 任务场景 | db2 |
| Operation | 作业定义 | db2 |
| Object | 清洁对象 | db2 |
| Matter | 事项 | db2 |
| Tools | 工具 | db2 |
| Wage | 时薪 | db2 |
| Authority | 权限组 | db2 |
| WorkGroup | 班组 | db2 |
| PunchRecord | 打卡记录 | db2 |
| AttendanceRecord | 考勤记录 | db2 |
| UserLocation | 实时定位 | db2 |
| UserTrajectory | 员工轨迹 | db2 |
| Watch | 手表设备 | db1 |
| WatchOffLog | 手表上下线日志 | db1 |
| Hardware | 硬件设备 | db1 |
| Beacon | 蓝牙信标 | db1 |
| Holiday | 节假日 | db2 |
| PushLog | 推送日志 | db2 |
| TodayDynamic | 任务动态消息 | db2 |

---

## 六、关键 Redis 数据结构

| Key | 类型 | 用途 |
|-----|------|------|
| `PlanTaskQueue` | List | 待生成的计划任务队列 |
| `taskCommand` | List | 设备告警命令队列 |
| `taskPushQueue` | List | 待推送的通知消息队列 |
| `IntellectualTaskIdList` | List | 待处理的任务ID队列 |
| `MqttWatchTaskMessage` | List | 待推送给手表的任务消息 |
| `WatchTaskUserList` | List | 待处理的任务-用户关联 |
| `WatchConnectList` | List | 手表连接/断开事件 |
| `BleutoothLocationQueue` | List | 蓝牙定位数据队列 |
| `CleaningRestLastTime` | ZSet | 员工休息倒计时（score=截止时间戳） |
| `MQTTTOPIC` | Set | 活跃手表设备集合 |
| `Location:userId` | String | 员工最新位置 |
| `Disable:d/t/p:id:taskTypeId` | String | 任务生成禁用标记 |

---

## 七、数据库详细分析

### 7.1 数据库架构

系统使用 **两个 MySQL 数据库**，通过 MyBatis-Plus 多数据源配置：

| 数据库 | 名称 | 说明 |
|--------|------|------|
| DB1 | xiaoqu_comples_d | 基础信息库：组织、用户、硬件、设备、定位数据 |
| DB2 | xiaoqu_intellectual_d | 业务数据库：任务、计划、权限、考勤、日志 |

**连接配置**：Druid 连接池，最大连接数100，初始10，最小空闲5

### 7.2 DB1 实体表清单（51张）

#### 组织架构

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| agent | Agent | 代理商 | name, type(0区域主管/1代理/2物业), level(0总部/1一级/2二级), channel_no, parents_id |
| properyt | Properyt | 物业公司 | name, agent_id, serialnumber, district_on_count, hard_on_count, user_count |
| district | District | 区域站/站点 | district_name, property_id, agent_id, address, buildCount, punch_flag, online_state |
| building | Building | 一级网格(楼座) | name, district_id, longitude, latitude, grid_level, orderby |
| floor | Floor | 二级网格(楼层) | name, building_id, man, woman, man_floorpic, woman_floorpic, grid_level |
| multistage_grid | MultistageGrid | 多级网格 | 支持更细粒度的网格划分 |
| grid_to_principal | GridToPrincipal | 网格-负责人关联 | grid_id, principal_id |
| positions | Positions | 位置/岗位 | 厕所内具体位置（男厕、女厕等） |

**组织层级**：Agent(代理) → Properyt(物业) → District(站点) → Building(楼座) → Floor(楼层) → MultistageGrid(多级网格)

#### 用户管理

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| user | User | 用户表 | mobile, name, idcard, sex, role_type, work_status, work_at_status, district_id, property_id, agent_id, authority_id |
| user_detail | UserDetail | 用户详情 | 扩展用户信息 |
| user_proper | UserProper | 用户-物业关联 | user_id, proper_id |
| user_toilet | UserToilet | 用户-卫生间关联 | user_id, toilet_id |
| user_district_attendance | UserDistrictAttendance | 用户站点考勤 | user_id, district_id, status, workAtStatus |
| user_rest | UserRest | 用户休息记录 | user_id, rest_time |
| user_location | UserLocation | 用户实时位置 | user_id, longitude, latitude, beacon_mac, rssi |
| user_trajectory | UserTrajectory | 用户轨迹 | user_id, location_id, stay_time, status |
| user_menu_district | UserMenuDistrict | 用户菜单-站点 | user_id, menu_id, district_id |
| proper_user_district | ProperUserDistrict | 物业用户-站点关联 | user_id, district_id |

**User 核心字段**：
- 工作状态：work_status, work_at_status(0作业/1转场/2空闲/3休息)
- 组织关联：district_id, property_id, agent_id
- 权限：role_id, authority_id, property_authority_id
- 认证：weixin_openid, registration_id

#### 硬件设备

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| hardware | Hardware | 硬件设备 | sn_code, type, status, district_id |
| hardware_var | HardwareVar | 硬件变量 | hardware_id, var_name, var_value |
| watch | Watch | 手表设备 | imei, user_id, bind_status, online_status, shock_state, voice_state |
| watch_set_params | WatchSetParams | 手表参数设置 | watch_id, param_name, param_value |
| watch_bind_log | WatchBindLog | 手表绑定日志 | watch_id, user_id, bind_time |
| watch_off_log | WatchOffLog | 手表上下线日志 | watch_id, status(0离线/1在线), connected_at, disconnected_at |
| watch_test_log | WatchTestLog | 手表测试日志 | 测试数据 |
| toilet | Toilet | 卫生间/场景设备 | name, district_id, building_id, floor_id |
| toilet_airquality | ToiletAirquality | 空气质量传感器 | sn_code, toilet_id |
| heyi_dev | HeyiDev | 合一设备 | 第三方设备集成 |
| heyi_group | HeyiGroup | 合一设备分组 | 设备分组管理 |
| equipment_repair_recording | EquipmentRepairRecording | 设备维修记录 | equipment_id, repair_time, status |

#### 蓝牙信标与定位

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| beacon | Beacon | 蓝牙信标 | mac, name, district_id, rssi_threshold |
| beacon_log | BeaconLog | 信标日志 | beacon_id, event_type |
| beacon_area_pic | BeaconAreaPic | 场景区域图 | area_id, pic_url |
| beacon_area_position | BeaconAreaPosition | 图层管理 | area_id, position_x, position_y |
| beacon_point_manage | BeaconPointManage | 点位管理 | beacon_id, point_name |
| bluetooth_communication | BluetoothCommunication | 蓝牙通信日志 | 通信记录 |
| bluetooth_connect | BluetoothConnect | 蓝牙连接数据 | 连接状态 |
| bluetooth_location | BluetoothLocation | 蓝牙定位数据 | mac, rssi, user_id |
| rfid_info | RfidInfo | RFID信息 | rfid标签数据 |

#### 菜单与统计

| 表名 | 实体 | 说明 |
|------|------|------|
| app_menu | AppMenu | 物业APP菜单权限 |
| my_menu | MyMenu | 自定义菜单 |
| my_user_menu | MyUserMenu | 用户菜单 |
| district_strategy | DistrictStrategy | 区域策略 |
| monthly_statistics | MonthlyStatistics | 月度统计 |
| statistics_month_log | StatisticsMonthLog | 月度统计日志 |
| switch_day_data | SwitchDayData | 日数据统计 |
| switch_hour_data | SwitchHourData | 小时数据统计 |
| switch_month_data | SwitchMonthData | 月数据统计 |
| switch_year_data | SwitchYearData | 年数据统计 |
| airqualitylevelgrade | Airqualitylevelgrade | 分润管理明细 |
| xinbiao_record | XinbiaoRecord | 新表记录 |

### 7.3 DB2 实体表清单（61张）

#### 任务管理

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| task_info | TaskInfo | 任务主表 | name, no, task_type, status, plan_id, district_id, point, wage_hour |
| task_type | TaskType | 任务类型 | name, code |
| task_user | TaskUser | 任务-用户关联 | task_id, user_id, status |
| task_accept_user | TaskAcceptUser | 接单人员 | task_id, user_id |
| task_distributi_user | TaskDistributiUser | 派发人员 | task_id, user_id |
| task_pic | TaskPic | 任务照片 | task_id, pic_url, type |
| task_scenes | TaskScenes | 任务场景 | task_id, grid_level, scenes_level, building_id, floor_id |
| task_task_scenes | TaskTaskScenes | 任务-场景关联 | task_id, scenes_id |
| task_status_log | TaskStatusLog | 任务状态日志 | task_id, old_status, new_status, change_time |
| task_district_param | TaskDistrictParam | 站点任务参数 | district_id, rest_time, beacon_no |

**TaskInfo 核心字段**：
- 状态流转：status(0已生成→1匹配→2待抢→3已接→4作业中→5按时完成/6超时/7人工取消/8系统取消/9未完成)
- 时间跟踪：create_time, send_time, confirm_time, action_time, finish_time, expire_time
- 时长统计：confirm_timing(响应), timing(作业), over_timing(超时), transfer_timing(转场)
- 绩效：point(积分), wage_hour(工时), wage_id, salary
- 巡检：should_inspect(应巡), actual_inspect(实巡), not_inspect(未巡)

#### 计划管理

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| plan | Plan | 任务计划 | task_name, type(0例行/2指派/5巡检), circle_status, circle_type(0天/1周/2月), status |
| plan_object | PlanObject | 计划-对象关联 | plan_id, object_id |
| plan_operation | PlanOperation | 计划-作业关联 | plan_id, operation_id |
| plan_scenes | PlanScenes | 计划-场景关联 | plan_id, building_id, floor_id, multistage_grid_id, scenes_id |
| plan_user | PlanUser | 计划-用户关联 | plan_id, user_id |
| plan_work_group | PlanWorkGroup | 计划-班组关联 | plan_id, work_group_id |
| plan_logic_label | PlanLogicLabel | 计划-标签关联 | plan_id, label_id |

**Plan 核心字段**：
- 周期配置：circle_status(0不重复/1周期/2间隔), circle_type(0天/1周/2月), circle_no
- 执行时段：action_start_time, action_end_time
- 过期设置：expire_type(0不过期/1次日/2指定), expire_timing
- 时长参数：working_timing(标准工时), transition_timing(转场), ready_timing(准备), redundance_timing(冗余)
- 跳过配置：eliminate_type(0不跳/1节假日/2自定义)

#### 考勤打卡

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| punch_record | PunchRecord | 打卡记录 | user_id, punch_time, longitude, latitude, address, punch_type, pic_url |
| punch_record_day_statis | PunchRecordDayStatis | 打卡日统计 | user_id, date, punch_count |
| rest_record | RestRecord | 休息记录 | user_id, punch_type(0休息/1恢复), rest_duration |
| attendance_record | AttendanceRecord | 考勤记录 | user_id, date, status |

#### 权限管理

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| authority | Authority | 权限组 | name, type |
| webpage | Webpage | 页面 | name, url, parent_id |
| webpage_authority | WebpageAuthority | 页面权限 | webpage_id, authority_id |
| page_field | PageField | 页面字段 | webpage_id, field_name, field_label |
| field_webpage_authority | FieldWebpageAuthority | 字段-权限关联 | field_id, webpage_id, authority_id |
| button | Button | 按钮 | webpage_id, name, code |
| button_field | ButtonField | 按钮字段 | button_id, field_name |
| button_webpage_authority | ButtonWebpageAuthority | 按钮-权限关联 | button_id, webpage_id, authority_id |

**权限链路**：Authority(权限组) → WebpageAuthority(页面) → FieldWebpageAuthority(字段) + ButtonWebpageAuthority(按钮)

#### 基础数据

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| object | Object | 清洁对象 | name, parent_id, level, type |
| object_type | ObjectType | 对象类型 | name |
| matter | Matter | 事项 | object_id, name, type |
| matter_type | MatterType | 事项类型 | name |
| operation | Operation | 作业 | name, type, tool_ids |
| tools | Tools | 工具 | name, district_id, status |
| scene_object | SceneObject | 场景-对象关联 | scene_id, object_id |
| inspect_scenes | InspectScenes | 巡检场景 | name, district_id |
| inspect_pic | InspectPic | 巡检照片 | inspect_id, pic_url |

#### 人员管理

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| work_group | WorkGroup | 班组 | work_group_name, district_id |
| work_group_to_principal | WorkGroupToPrincipal | 班组-负责人 | work_group_id, principal_id |
| skill_manage | SkillManage | 技能 | name |
| user_to_skill | UserToSkill | 用户-技能 | user_id, skill_id |
| label_manage | LabelManage | 标签 | name |
| user_to_label | UserToLabel | 用户-标签 | user_id, label_id |
| user_to_matter | UserToMatter | 用户-事项 | user_id, matter_id |
| user_to_service_area | UserToServiceArea | 用户-服务区域 | user_id, area_id |
| escalation_user | EscalationUser | 上报用户 | user_id |
| escalation_service_area | EscalationServiceArea | 上报服务区域 | escalation_id, area_id |

#### 绩效与薪资

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| wage | Wage | 时薪配置 | type, point, amount |
| efficiency_recording | EfficiencyRecording | 人效录入 | user_id, date |
| efficiency_detail | EfficiencyDetail | 人效详情 | recording_id, metric, value |

#### 日志与通知

| 表名 | 实体 | 说明 | 关键字段 |
|------|------|------|----------|
| login_log | LoginLog | 登录日志 | user_id, login_time, ip, type(0登录/1退出) |
| change_log | ChangeLog | 变更日志 | entity, operation, old_value, new_value |
| modify_log | ModifyLog | 修改日志 | 记录数据修改历史 |
| push_log | PushLog | 推送日志 | client_id, user_id, title, content, status |
| sms_send_record | SmsSendRecord | 短信发送记录 | mobile, content, status |
| user_push | UserPush | 用户推送映射 | user_id, client_id |
| today_dynamic | TodayDynamic | 今日动态消息 | task_id, user_id, message, type |

#### 其他

| 表名 | 实体 | 说明 |
|------|------|------|
| holiday | Holiday | 节假日(0工作日/1法定/2调休/3周末) |
| app_version | AppVersion | APP版本管理 |
| type_source | TypeSource | 类型来源 |

### 7.4 通用字段规范

所有实体均包含以下标准字段：
- `id` (Long) - 自增主键
- `create_id` (Long) - 创建人ID
- `create_time` (Date) - 创建时间
- `modify_id` (Long) - 修改人ID
- `modify_time` (Date) - 修改时间
- `soft_delete` (Integer) - 软删除标记(0正常/1已删除)

### 7.5 核心关系映射

```
组织层级:
  Agent(代理) → Properyt(物业) → District(站点) → Building(楼座) → Floor(楼层) → MultistageGrid(多级网格)

用户关系:
  User ←→ Authority(权限组)
  User ←→ WorkGroup(班组)
  User ←→ SkillManage(技能)
  User ←→ LabelManage(标签)
  User ←→ District(站点)
  User ←→ Watch(手表)

任务流程:
  Plan(计划) → TaskInfo(任务) → TaskUser(执行人)
  Plan → PlanObject(对象) + PlanOperation(作业) + PlanScenes(场景)
  TaskInfo → TaskScenes(场景) + TaskPic(照片) + TaskStatusLog(状态日志)

基础数据:
  Object(对象) → Matter(事项) → Operation(作业) + Tools(工具)
  District → Beacon(信标) → UserLocation(定位) → UserTrajectory(轨迹)
```

---

## 八、Redis 详细分析

### 8.1 Redis 架构配置

| 配置项 | 值 |
|--------|-----|
| 连接驱动 | Lettuce (Spring Data Redis) |
| 数据库数量 | 2 个独立 DB (DB4 和 DB5) |
| 连接池最大连接数 | 200 |
| 最大空闲连接 | 8 |
| 最小空闲连接 | 1 |
| 序列化方式 | StringRedisSerializer (Key + Value 均为字符串) |

**数据库分工**：
| 数据库 | 用途 |
|--------|------|
| DB 4 | 消息队列、状态标志、计数器、分布式锁 |
| DB 5 | 实体缓存、设备命令队列、字典配置、时间序列 |

### 8.2 Redis 操作工具

**RedisService4 / RedisService5** - 封装以下数据类型操作：

| 数据类型 | 操作方法 |
|---------|---------|
| String | set, get, remove, exists |
| List | lPush, rPush, leftPop, rightPop, lRange, lRangeAll |
| Set | add, setRemove, isMember, setMembers, setPop |
| Hash | hmSet, hmGet |
| ZSet | zAdd, zRemove, rangeByScore |

**RedisDistributedLock** - 分布式锁：
- 锁前缀：`redis_lock_`
- 默认过期：30秒
- 自旋重试：最多10次，间隔50ms

### 8.3 DB4 Key 详细映射

#### 任务消息队列

| Key | 类型 | 内容 | 写入方 | 消费方 |
|-----|------|------|--------|--------|
| `taskUserQueue` | List | 保洁派单消息 (TaskPlanEntity JSON) | TaskCorrelationSetTask, TaskCreateQueue | TaskCorrelationSetTask |
| `taskPushQueue` | List | APP推送消息 (TaskPushInfo JSON) | TaskCorrelationSetTask, TaskCreateQueue | TaskPushMessage |
| `taskReportQueue` | List | 上报任务派单 (TaskPlanEntity JSON) | TaskCorrelationSetTask | TaskCorrelationSetTask |
| `inspectTaskUserQueue` | List | 巡检任务派单 (TaskPlanEntity JSON) | TaskCorrelationSetTask | TaskCorrelationSetTask |
| `IntellectualTaskIdList` | List | 待处理任务ID | TaskCorrelationSetTask | ScheduledTask |
| `PlanTaskQueue` | List | 待生成的计划ID | PlanTimeTask | 任务处理系统 |

#### 手表/MQTT 消息队列

| Key | 类型 | 内容 | 写入方 | 消费方 |
|-----|------|------|--------|--------|
| `WatchTaskUserList` | List | 手表任务-用户ID | TaskCorrelationSetTask | ScheduledTask |
| `MqttWatchTaskMessage` | List | 手表任务消息 (JSON) | ScheduledTask | ScheduledTask (MQTT发送) |
| `MqttTaskStateMessage` | List | 任务状态变更消息 (JSON) | ScheduledTask | ScheduledTask (MQTT发送) |
| `AttendanceStatusMessage` | List | 考勤状态消息 (JSON) | UserRestTask | ScheduledTask |
| `TaskMagnifierMessage` | List | 放大镜监控消息 (JSON) | 业务系统 | ScheduledTask |
| `WatchConnectList` | List | 手表连接/断开事件 (JSON) | PushCallback | ScheduledTask |
| `WatchShockAndVoiceMessage` | List | 手表震动/语音参数 (JSON) | 业务系统 | ScheduledTask |

#### 蓝牙定位队列

| Key | 类型 | 内容 | 写入方 | 消费方 |
|-----|------|------|--------|--------|
| `BleutoothLocationQueue` | List | 蓝牙定位数据 (JSON) | 设备上报 | LocationTask |
| `OffDutyBleutoothLocationQueue` | List | 下班定位数据 (JSON) | 设备上报 | LocationTask |

#### 任务禁用/启用标志

| Key 模式 | 类型 | 值 | 说明 |
|---------|------|-----|------|
| `Disable:d:<districtId>:<taskTypeId>` | String | "0"/"1" | 站点级任务禁用 |
| `Disable:t:<toiletId>:<taskTypeId>` | String | "0"/"1" | 场景级任务禁用 |
| `Disable:p:<positionId>:<taskTypeId>` | String | "0"/"1" | 位置级任务禁用 |
| `DevTaskFlag:<districtId>` | String | "0"/"1" | 设备维护任务开关 |
| `workingTimeing:d:<districtId>:<taskTypeId>` | String | 数字 | 站点级工作时长 |
| `workingTimeing:t:<scenesId>:<taskTypeId>` | String | 数字 | 场景级工作时长 |
| `workingTimeing:p:<scenesId>:<taskTypeId>` | String | 数字 | 位置级工作时长 |

#### 计划/计数器

| Key 模式 | 类型 | 值 | 说明 |
|---------|------|-----|------|
| `Plan:<planType>:<planId>` | String | 任务ID | 计划关联的XXL-Job任务ID |
| `UserCount:p:<scenesId>` | Set | 计划ID集合 | 位置级计划集合 |
| `UserCount:p:<scenesId>:<planId>` | String | 数字 | 人次触发剩余次数 |
| `PoolOrderCount:<orderType>:<districtId>` | String | 数字 | 订单计数 |

#### MQTT 主题管理

| Key | 类型 | 值 | 说明 |
|-----|------|-----|------|
| `MQTTTOPIC` | Set | MQTT Topic 集合 | 活跃手表设备(旧) |
| `MQTTTOPICNEW` | Set | MQTT Topic 集合 | 活跃手表设备(新) |

#### 分布式锁

| Key 模式 | 类型 | TTL | 说明 |
|---------|------|-----|------|
| `redis_lock_<endpoint>` | String | 30秒 | 防重复提交 |
| `HolidayLock` | String | 1800秒 | 节假日同步锁 |

#### 其他

| Key 模式 | 类型 | 说明 |
|---------|------|------|
| `AuthorityWebpage:<authorityId>` | String | 权限页面缓存 |
| `mobileLimit:<mobile>` | String | 手机号限制标志 |
| `ToiletToUser:<toiletId>` | String | 厕所-用户映射 |
| `CleaningRestLastTime` | ZSet | 员工休息倒计时(score=截止时间戳) |

### 8.4 DB5 Key 详细映射

#### 设备命令队列

| Key | 类型 | 内容 | 写入方 | 消费方 |
|-----|------|------|--------|--------|
| `taskCommand` | List | 设备告警命令 (TaskCommandInfo JSON) | PlanTimeTask | TaskCreateQueue |
| `taskFinishCommand` | List | 任务完成命令 (TaskCommandInfo JSON) | 业务系统 | TaskCorrelationSetTask |
| `FinishTaskQueue` | List | 已完成任务ID | TaskCorrelationSetTask | TaskCorrelationSetTask |
| `ConfirmTaskQueue` | List | 已确认任务ID | 业务系统 | TaskCorrelationSetTask |
| `WatchSetParamsInit` | List | 手表初始化参数 (JSON) | 业务系统 | ScheduledTask |
| `WatchShockSetParamsInit` | List | 手表震动初始化参数 (JSON) | 业务系统 | ScheduledTask |
| `RepeatTaskQueue` | Set | 重派发任务集合 | TaskCorrelationSetTask | TaskCorrelationSetTask |
| `DistrictBeaconNoChange` | List | 信标号更新队列 | 业务系统 | BeaconTask |

#### 实体缓存

| Key 模式 | 类型 | 内容 | TTL |
|---------|------|------|-----|
| `entity:UserDistrictAttendance:<userId>_<districtId>` | String | 用户站点考勤 JSON | 无 |
| `entity:Hardware:<snCode>` | String | 硬件设备信息 JSON | 无 |
| `entity:ToiletAirQualityAirMac:<snCode>` | String | 空气质量传感器 JSON | 无 |
| `entity:TaskTypeNearFlag:<typeId>:<districtId>` | String | 任务类型临期标志 | 无 |

#### 名称缓存

| Key 模式 | 类型 | 内容 |
|---------|------|------|
| `name:Agent:<agentId>` | String | 代理商名称 |
| `name:Properyt:<propertyId>` | String | 物业名称 |
| `name:District:<districtId>` | String | 站点名称 |
| `name:PropertyAuthority:<authorityId>` | String | 权限组名称 |

#### 字典配置 (Hash)

| Key | Hash 字段 | 值 | 说明 |
|-----|----------|-----|------|
| `Dictionary` | `UserAppointFlag` | "0"/"1" | 用户预约标志 |
| `Dictionary` | `UserAreaFlag` | "0"/"1" | 用户服务区域标志 |
| `Dictionary` | `UserDutyFlag` | "0"/"1" | 用户职责标志 |
| `Dictionary` | `LogicFlag` | "0"/"1" | 逻辑标志 |
| `Dictionary` | `TaskNearFlag` | "0"/"1" | 任务临期标志 |
| `Dictionary` | `OperateAssignmentTypes` | 类型列表 | 操作分配类型 |
| `Dictionary` | `AutoOffWorkTime` | 数字 | 自动下班时间 |
| `Dictionary` | `ScenesType` | 场景类型列表 | 场景类型 |

#### 定位与状态

| Key 模式 | 类型 | 内容 |
|---------|------|------|
| `Location:<userId>` | String | 最新位置(格式: 时间_场景_楼栋_楼层) |
| `DistrictBeaconNo:<districtId>` | String | 站点信标编号 |
| `disinfect:p:<scenesId>` | String | 位置消毒状态("0"/"1") |
| `CleaningUpWorkAtStatus:<mobile>` | String | 员工原始工作状态 |

#### 时间序列

| Key | 类型 | Score | 说明 |
|-----|------|-------|------|
| `ImpendingTime` | ZSet | 过期时间戳(ms) | 临期任务队列 |
| `TaskExprieQueue` | ZSet | 过期时间戳(ms) | 任务过期队列 |

### 8.5 Redis 数据流转图

```
[计划调度]
  PlanTimeTask → PlanTaskQueue(DB4) → 任务生成
  PlanTimeTask → taskCommand(DB5) → TaskCreateQueue → taskPushQueue(DB4)

[任务派单]
  TaskCorrelationSetTask ←→ taskUserQueue(DB4)
  TaskCorrelationSetTask ←→ inspectTaskUserQueue(DB4)
  TaskCorrelationSetTask ←→ taskReportQueue(DB4)
  TaskCorrelationSetTask → WatchTaskUserList(DB4) → ScheduledTask → MqttWatchTaskMessage(DB4) → MQTT

[消息推送]
  taskPushQueue(DB4) → TaskPushMessage → 个推SDK → APP
  IntellectualTaskIdList(DB4) → ScheduledTask → MqttTaskStateMessage(DB4) → MQTT → 手机端

[设备通信]
  WatchConnectList(DB4) → ScheduledTask → 更新Watch表
  BleutoothLocationQueue(DB4) → LocationTask → UserLocation/UserTrajectory

[员工休息]
  UserRestTask → AttendanceStatusMessage(DB4) → ScheduledTask → MQTT
  CleaningRestLastTime(DB4, ZSet) → restCountDown → 自动恢复
```

---

## 九、统计汇总

| 维度 | 数量 |
|------|------|
| Controller 数量 | 27 个 |
| REST API 端点 | 约 150+ 个 |
| XXL-Job 定时任务 | 6 个 |
| Spring @Scheduled 任务 | 20+ 个 |
| 业务模块 | 19 个 |
| DB1 数据表 | 51 张 |
| DB2 数据表 | 61 张 |
| 数据表总计 | 112 张 |
| Redis DB4 Key 类型 | 30+ 种 |
| Redis DB5 Key 类型 | 25+ 种 |
| Redis 消息队列 | 15+ 个 |