家政预约系统多端开发:预约排班日历组件跨端实现方案
在家政预约场景中,排班日历是用户选择上门日期、时段的核心组件,同时师傅端也需要通过日历查看自己的排班与工单。小程序和H5的渲染机制、日期picker能力、滚动性能存在差异,如果分开开发两套日历,会出现样式、交互逻辑不一致,排期数据打点、时段可选状态判定规则割裂的问题。本文基于UniApp自研日历组件搭配SpringBoot后端排班服务,实现一套代码同时适配小程序、H5,统一日期打点、时段筛选、档期冲突校验逻辑。
一、日历组件跨端开发遇到的痛点
直接使用平台原生日期组件或者第三方日历组件,很容易出现兼容性问题。
小程序原生picker只支持简单日期选择,无法展示日期打点、区分满约/可约/休息日;H5的日历组件在不同浏览器上滚动、样式渲染差异大。家政排班还有业务特殊性:不同师傅、不同服务品类的可预约时段不一样,部分日期设置休息、部分日期名额已满,需要在日历上做标记。
前期项目遇到的问题:H5日历月份切换卡顿、小程序长月日历滚动内存占用高;两端日期禁用规则不一致,H5可以选已经约满的日期,小程序做了拦截;前端硬编码时段规则,后台修改师傅排班后,前端不会同步更新;时区、日期格式化处理不一致,跨端出现日期错位。
单纯前端组件只能解决展示问题,排班的可用性、名额、冲突校验必须交给后端统一计算。
二、整体方案架构设计
采用前端通用日历组件 + 后端排班引擎的架构。
前端基于UniApp封装自研排班日历组件,不依赖原生picker,统一处理月份切换、日期渲染、打点标记、禁用状态;组件对外暴露固定入参和回调,小程序、H5直接引用同一个组件,仅在样式细节做少量适配。
后端排班服务负责计算档期:根据服务ID、师傅ID、月份,查询师傅休息日、已占用工单、剩余可预约名额,返回给前端当月的日期状态。Redis缓存月份排班数据,降低数据库查询压力;用户选中日期后,再二次请求时段列表,同时做时段冲突校验。
所有日期状态、时段配置、名额上限由后端输出,前端只负责渲染,不维护排班业务规则。
三、后端排班查询与冲突校验核心代码
@Service
public class StaffScheduleService {
@Autowired
private StringRedisTemplate redisTemplate;
@Autowired
private StaffScheduleMapper scheduleMapper;
@Autowired
private OrderMapper orderMapper;
private static final String SCHEDULE_MONTH_KEY = "house:schedule:month:";
public ResultDTO<ScheduleMonthVO> getMonthSchedule(Long staffId, String month) {
String cacheKey = SCHEDULE_MONTH_KEY + staffId + ":" + month;
String cacheJson = redisTemplate.opsForValue().get(cacheKey);
if (StringUtils.isNotEmpty(cacheJson)) {
return ResultDTO.success(JSON.parseObject(cacheJson, ScheduleMonthVO.class));
}
// 初始化当月日期状态
ScheduleMonthVO monthVO = new ScheduleMonthVO();
List<ScheduleDayVO> dayList = new ArrayList<>();
LocalDate startDate = LocalDate.parse(month + "-01");
LocalDate endDate = startDate.plusMonths(1).minusDays(1);
// 查询师傅休息日
List<LocalDate> restDayList = scheduleMapper.selectRestDay(staffId, startDate, endDate);
// 查询已经确认的预约工单
List<AppointOrder> orderList = orderMapper.selectConfirmedOrder(staffId, startDate, endDate);
Map<LocalDate, Integer> occupyMap = new HashMap<>();
for (AppointOrder order : orderList) {
LocalDate appointDate = order.getAppointTime().toLocalDate();
occupyMap.put(appointDate, occupyMap.getOrDefault(appointDate, 0) + 1);
}
// 组装每日状态
for (LocalDate d = startDate; !d.isAfter(endDate); d = d.plusDays(1)) {
ScheduleDayVO dayVO = new ScheduleDayVO();
dayVO.setDate(d.toString());
if (restDayList.contains(d)) {
dayVO.setStatus("rest");
} else if (occupyMap.getOrDefault(d, 0) >= scheduleMapper.getDayMaxCount(staffId)) {
dayVO.setStatus("full");
} else {
dayVO.setStatus("available");
}
dayList.add(dayVO);
}
monthVO.setDayList(dayList);
redisTemplate.opsForValue().set(cacheKey, JSON.toJSONString(monthVO), 30, TimeUnit.MINUTES);
return ResultDTO.success(monthVO);
}
}
返回的状态分为available(可预约)、rest(休息)、full(约满),前端日历根据状态渲染不同标记和禁用逻辑。当订单新增、取消、师傅排班变更时,清理对应月份缓存,保证数据实时性。
四、前端跨端日历组件适配策略
组件内部统一处理月份切换逻辑,对两端差异化API做兼容封装:
- 滚动适配:小程序使用scroll-view,H5使用原生滚动,统一监听滚动事件,月份切换时懒加载下个月排班,避免一次性渲染大量日期造成卡顿;
- 样式兼容:使用rpx单位,小程序自动适配,H5通过postcss转换,保证日历格子大小、打点位置视觉一致;
- 日期格式化:统一使用UTC日期转换,避免H5浏览器时区、小程序时区解析不一致,出现日期偏移;
- 事件封装:统一@change回调,选中日期后触发时段接口请求,不再区分渠道。
组件内置状态映射:rest展示灰色标记、full展示红色满约标记、available为可点击,点击日期后加载当日可选时段面板。
五、时段二次校验与预约联动
日历只做初步的日期状态展示,真正提交预约时,后端会再次校验时段冲突。
存在一种场景:日历缓存显示日期可约,在用户选中日期、选择时段的间隙,其他用户完成下单,该时段被占用。所以下单接口必须二次校验库存,不能只依赖日历预加载的数据。
前端日历组件在用户选择时段后,把日期、时段、师傅ID一起传给下单接口,后端通过分布式锁控制时段资源,防止超约,和前面的并发预约方案联动。
六、缓存策略、性能与异常处理
排班数据属于准实时数据,月份缓存设置30分钟过期,订单变更主动删缓存,平衡性能和一致性。
性能优化:一次只请求一个月排班,不一次性加载多个月;日历做虚拟列表优化,可视区域外的日期不渲染DOM,解决H5浏览器和小程序在多月日历下卡顿问题。
异常兜底:排班接口超时,日历组件降级,日期不做标记,只保留基础日期选择,提交预约时后端强校验;接口返回异常时,给用户提示“排班加载失败,请稍后重试”。
监控指标:日历接口响应耗时、月份缓存命中率、跨端渲染异常上报、时段冲突拦截次数。
七、测试验证场景
测试场景:小程序和H5打开同一个师傅的排班日历,可约日期、休息日、满约日期标记完全一致;后台修改师傅休息日,缓存清空后两端日历同步更新;快速切换月份,页面无卡顿、布局不错乱;缓存间隙并发下单,后端二次校验拦截超约;不同时区手机打开,日期不出现错位。

总结
这套排班日历跨端方案,核心是自研统一的UniApp日历组件抹平H5和小程序渲染差异,排班可用性、名额、休息日规则全部收敛在后端排班引擎,前端只负责视图渲染。按月缓存排班数据降低数据库压力,日历预展示状态、下单接口二次校验,兼顾体验和数据安全。该组件可以复用到用户预约下单页、师傅排班管理页,和鉴权、订单同步、并发预约模块组合使用。落地时重点做好日期时区统一、缓存失效机制、虚拟列表渲染优化,保证两端交互和业务规则完全一致。