家政平台多端适配改造:基于源码扩展H5、技师APP端方案
一、改造背景与痛点
很多家政平台早期源码只实现了微信小程序用户端与技师端,业务扩张后,需要支持H5访问、独立技师APP,方便技师在无微信环境下接单、打卡、上传服务凭证。直接新增两套独立前端会带来接口重复开发、订单状态不同步、权限逻辑不一致等问题。本次改造基于现有Java后端源码做扩展,复用原有订单、派单、实名认证核心能力,新增多端识别、权限隔离、原生能力适配模块,低成本完成H5、技师APP接入。
二、整体架构改造思路
后端沿用SpringBoot+MySQL+Redis架构,不改动原有核心业务表,新增终端标识字段、登录适配器;前端采用uni-app一套工程,通过条件编译分别输出H5、技师APP包,共用一套业务组件,针对平台特有能力做差异化处理。
整体分为三层:接入适配层、业务服务层、数据存储层。接入层统一拦截不同终端的请求,做token校验、平台来源识别;业务层复用原有派单、订单、技师服务逻辑;存储层通过扩展字段区分终端来源,保证数据同源。
三、后端接口适配改造
核心改造点是增加终端适配器,区分MP、H5、APP三类终端,处理登录、推送、文件上传差异。原有登录接口只支持小程序code登录,改造后支持H5手机号验证码登录、APP一键登录、小程序静默登录,统一返回相同结构的token,上层业务不需要感知终端类型。
新增技师位置上报接口,APP端支持高频原生定位上报,H5端受浏览器权限限制,降低上报频率,增加节流策略,避免频繁请求。
下面是终端枚举与登录适配的Java示例代码:
/**
* 终端类型枚举
*/
public enum TerminalEnum {
MP("mp", "微信小程序"),
H5("h5", "H5网页端"),
APP_TECH("app_tech", "技师APP端");
private final String code;
private final String desc;
TerminalEnum(String code, String desc) {
this.code = code;
this.desc = desc;
}
// getter省略
}
/**
* 登录适配器入口
*/
@Service
public class TechLoginAdapterService {
@Autowired
private Map<String, TechLoginHandler> loginHandlerMap;
public LoginVO login(TerminalEnum terminal, LoginDTO dto) {
TechLoginHandler handler = loginHandlerMap.get(terminal.getCode());
if(handler == null){
throw new RuntimeException("该终端暂不支持登录");
}
return handler.doLogin(dto);
}
}
同时在拦截器中解析请求头terminal字段,记录每一笔订单、操作的终端来源,用于后续日志排查、风控统计。
四、技师端前端多端兼容处理
前端基于uni-app改造,原有技师小程序页面全部复用,使用条件编译隔离平台差异:
- 登录:小程序用wx.login;H5走短信验证码;APP支持本机号码一键登录;
- 定位与打卡:APP可调用原生高精度定位、地理围栏校验;H5依赖浏览器定位,增加精度提示;
- 图片上传:APP支持相册+相机直接拍摄;H5部分浏览器存在权限限制,增加降级提示;
- 消息推送:APP接入厂商推送通道,H5使用WebSocket在线推送,离线消息存入消息队列,上线后拉取。
样式层面统一使用rpx单位,对安全区、刘海屏、底部操作栏做兼容,H5增加CORS跨域配置,后端配置允许域名白名单,避免跨域报错。
五、数据模型与权限隔离
不修改原有tech_worker、order_info主表,扩展字段:
- order_info:terminal 订单来源终端
- tech_token:terminal、expire_time,区分不同终端登录会话,支持多端同时在线或互踢配置
- worker_auth:增加APP端资质上传记录,和小程序资质数据互通,一套资质多端复用
权限控制上,同一个技师账号,H5、APP、小程序权限保持一致;可在后台配置开关,单独关闭某一端的接单权限,例如临时关闭H5技师接单入口。
六、联调、灰度与兼容性测试
联调优先保证接口返回结构统一,差异字段做兼容判空处理。测试重点覆盖:
- 多端登录互斥/共存逻辑;
- 订单状态跨端同步,APP接单后H5、小程序实时刷新;
- 定位打卡、拍照上传在低端安卓、不同浏览器下的兼容性;
- WebSocket断开重连、离线消息补偿。
上线采用灰度策略,先开放少量技师账号体验APP和H5,观察接口报错、定位失败率,再全量放开。
七、总结
本次家政平台多端适配改造,核心思路是复用原有业务源码,通过适配器模式隔离终端差异,避免重复开发核心派单、订单逻辑。后端只新增适配层、终端标识逻辑,前端基于uni-app实现一套代码编译H5、技师APP,降低维护成本。改造过程中重点需要处理登录方式、定位、推送、文件上传这些平台原生能力差异,同时做好会话管理和跨端数据同步。该方案适合已经有小程序版本、需要快速拓展H5和独立技师APP的家政同城项目,在控制改造成本的同时,丰富技师的接单入口,提升平台覆盖能力。