一、背景
在家政 O2O 服务场景中,"上门签到"是连接线上预约与线下服务的关键环节。它不仅是服务履约的凭证,也是后续计费、评价、纠纷仲裁的重要依据。本文从技术实现角度,拆解上门签到功能的设计思路,包括定位校验、签到流程、异常处理等核心模块。
二、功能模块拆解
上门签到功能可拆分为以下几个子模块:
| 模块 | 职责 |
| 定位采集 | 前端获取服务人员当前 GPS 坐标 |
| 距离校验 | 后端计算服务人员与雇主地址的距离,判断是否在允许范围内 |
| 签到记录 | 写入签到日志,更新订单状态 |
| 异常处理 | 处理定位漂移、GPS 信号弱、用户申诉等边界场景 |
整体流程如下:
服务人员到达 → 打开App点击"签到" → 前端采集GPS → 后端校验距离 → 通过则更新订单状态 → 返回签到成功
三、核心代码示例
1. 地理距离计算工具类
签到校验的核心是判断服务人员当前位置与雇主服务地址之间的距离是否在阈值内(如 500 米)。这里使用 Haversine 公式计算两点间的球面距离:
public class GeoUtils { private static final double EARTH_RADIUS_KM = 6371.0; /** * 计算两个经纬度坐标之间的距离(单位:米) */ public static double distanceInMeters(double lat1, double lng1, double lat2, double lng2) { double dLat = Math.toRadians(lat2 - lat1); double dLng = Math.toRadians(lng2 - lng1); double a = Math.sin(dLat / 2) * Math.sin(dLat / 2) + Math.cos(Math.toRadians(lat1)) * Math.cos(Math.toRadians(lat2)) * Math.sin(dLng / 2) * Math.sin(dLng / 2); double c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a)); return EARTH_RADIUS_KM * c * 1000; } }
2. 签到接口实现
("/checkin") public class CheckInController { private OrderService orderService; private static final double MAX_DISTANCE_METERS = 500.0; ("/arrive") public Result<CheckInVO> arriveCheckIn( CheckInDTO dto) { // 1. 查询订单及雇主服务地址 OrderVO order = orderService.getOrderById(dto.getOrderId()); if (order == null) { return Result.fail("订单不存在"); } // 2. 计算服务人员当前位置与服务地址的距离 double distance = GeoUtils.distanceInMeters( dto.getLatitude(), dto.getLongitude(), order.getServiceLat(), order.getServiceLng()); if (distance > MAX_DISTANCE_METERS) { return Result.fail("当前位置距服务地址" + (int) distance + "米,请到达后再签到"); } // 3. 执行签到:更新订单状态 + 记录签到信息 CheckInVO vo = orderService.executeCheckIn(dto.getOrderId(), dto.getLatitude(), dto.getLongitude(), distance); return Result.success(vo); } }
四、关键设计考量
1. 定位精度与容错
实际场景中,GPS 定位存在漂移问题,尤其在高层住宅或地下车库信号较弱。建议采取以下策略:
- 前端多次采样取中位数:连续采集 3~5 次定位,取中位数作为最终坐标,减少单次漂移影响。
- 动态阈值:根据订单类型调整允许距离。例如保洁上门服务可设 300 米,搬家类大件服务可放宽至 1000 米。
- 辅助校验:结合 Wi-Fi 指纹或基站定位作为补充,提升室内场景的判定准确率。
2. 防作弊机制
签到数据直接影响结算,需要防范虚假签到:
- 服务端校验为主:距离计算必须在后端完成,前端仅负责上报坐标,防止篡改。
- 时间窗口约束:签到时间必须在预约时段的前后 30 分钟内,超出范围需走异常审批流程。
- 设备指纹绑定:签到设备与接单设备需一致,防止远程代签。
3. 异常场景处理
| 场景 | 处理方式 |
| GPS 信号弱无法定位 | 允许使用手动输入地址 + 拍照上传作为补充凭证 |
| 定位偏差过大(如跨城) | 触发人工审核,服务人员提交说明 |
| 雇主临时变更地址 | 支持雇主端发起地址变更,重新计算校验基准 |
| 签到后长时间未开始服务 | 系统定时检测,超时自动提醒或触发工单 |
五、数据库表设计参考
签到记录表的核心字段设计:
CREATE TABLE service_check_in ( id BIGINT PRIMARY KEY AUTO_INCREMENT, order_id BIGINT NOT NULL COMMENT '关联订单ID', staff_id BIGINT NOT NULL COMMENT '服务人员ID', check_in_type TINYINT NOT NULL COMMENT '签到类型:1-到达签到 2-完成签到', latitude DECIMAL(10,7) COMMENT '签到纬度', longitude DECIMAL(10,7) COMMENT '签到经度', distance_meters DOUBLE COMMENT '与服务地址距离(米)', photo_url VARCHAR(512) COMMENT '签到照片(OSS地址)', status TINYINT NOT NULL DEFAULT 1 COMMENT '1-正常 2-异常待审', created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, INDEX idx_order (order_id), INDEX idx_staff_time (staff_id, created_at) ) COMMENT='服务签到记录表';
六、总结
上门签到功能看似简单,但在实际落地中需要综合考虑定位精度、防作弊、异常兜底三个维度的问题。核心原则是:以服务端校验为准,前端采集为辅;正常流程自动化,异常流程可追溯。在技术选型上,如果业务规模较小,直接使用高德/百度地图 SDK 提供的距离计算能力即可;如果有多城市、多场景的复杂需求,建议自建地理计算服务并配合 Redis Geo 做附近人员检索,为后续的实时调度打下基础。