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+ 个