伦斯特去年年底我接了一个代号“weixin066”的家政项目小程序开发，甲方需求文档只有一句话：做一个能预约阿姨上门保洁的小程序。但真做起来才发现，家政这个品类远比普通电商复杂——它牵扯到服务人员排期、上门地址、时长计费、状态流转，还有用户端之外的阿姨端和管理后台。这篇博文就把我从零到一落地这个项目的完整过程写出来，包括业务模型设计、技术选型、核心功能实现、调试排查，以及上线前后那些容易被忽略的坑。
如果你正打算做家政、维修、上门保养这类“服务型小程序”，或者已经在开发微信小程序但被订单状态、分包体积、导航栏适配这些细节卡住，这篇文章应该能帮你少走不少弯路。
1. 家政业务模型设计：先定状态机，再写代码
很多团队做家政小程序的第一反应是先画页面、先写接口，结果做到订单流转那一步就卡住了。原因很简单：家政订单和商城订单完全是两种生物。商城订单的流程是“付款→发货→收货→评价”，但家政订单包含服务时间、服务人员、上门地址、服务时长，甚至可能包含耗材费用，状态链路长得多。所以我的第一步不是搭工程，而是把业务模型和订单状态机先定下来。
1.1 用户、阿姨、门店、平台：四方角色的边界
家政小程序虽然用户量最大的是C端顾客，但整个系统至少需要四类角色：
- 顾客（用户端小程序）：搜索服务、下单预约、支付、评价、查看历史订单。
- 阿姨/服务人员（阿姨端小程序或独立分包）：接收派单、确认接单、上报完工、查看收入。
- 门店/站点（管理后台）：处理订单分配、排班管理、处理客诉。
- 平台管理员（总后台）：审核服务人员资质、配置服务项目、运营位管理、财务对账。
这四类角色不能共用一套接口权限。比较稳妥的做法是：用户端用微信登录换取普通用户Token；阿姨端单独走一套身份认证，增加人脸识别和工牌校验；管理后台走账号密码加二次验证。要是图省事把所有接口都放在同一套鉴权下，后面出现越权问题的概率极高。
1.2 服务单模型：为什么不能直接套用商品订单
家政项目里最核心的表不是“订单表”，而是“服务单表”。一张服务单记录的不只是价格，还有预约的日期时段、服务地址、下单备注、指派阿姨、完工照片、耗材费用这些维度的信息。
我当时设计的核心字段大致如下：
| 字段 | 说明 |
|---|---|
| service_no | 服务单编号，用户可见，类似“JZ20251208001” |
| user_id / address_id | 下单用户和服务地址 |
| category_id / product_id | 服务品类和SKU，例如“日常保洁-2小时” |
| appoint_date / appoint_slot | 预约日期和时段，时段是固定档位而非任意时间 |
| worker_id | 被指派的阿姨，平台派单模式下创建时为空 |
| order_status | 订单状态，见下方状态机 |
| charge_type | 计费类型：一口价、按时计费、按面积计费 |
| total_amount / pay_amount | 原始金额、实付金额 |
| coupon_id | 优惠券ID，划分平台补贴还是门店承担 |
这里有个容易踩的坑：不要把服务明细塞进一个Json字段里面图省事。比如用户选了“2小时日常保洁+加1小时擦玻璃”，如果只在备注里写，后面结算、对账、分析服务质量时都会崩溃。宁可多建两张子表，把增值服务做成正式子项。
1.3 订单状态机：把“混乱”变成有限状态
家政订单的状态一定不能用死板的数字+不知道含义的status字段，而是要把每个状态、每个动作、操作人、时间都记录下来。我最终定义了一组状态流转：
- 待支付（已创建未支付）
- 待派单（支付成功，等待运营/系统派单）
- 已派单（阿姨已接单，展示阿姨信息给用户）
- 服务中（阿姨开始上门服务，打卡签到）
- 待完成（阿姨上报完工，等待用户验收）
- 已完成（用户确认或系统自动确认，进入结算）
- 已取消（用户取消、平台取消、超时未支付自动关闭）
- 售后中（用户发起客诉或退款请求）
每一种状态变化都要有操作日志。状态机确定之后，前端页面、后端接口、订阅消息的触发时机都跟着这个状态走，后期基本不用返工。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技术选型与工程初始化：uniapp还是原生，我为什么这样选
项目代号“weixin066”，一听就知道是微信生态为主。但选型的时候我还是纠结了一阵子：微信原生小程序、uni-app、Taro三者都有各自的使用场景。最后我选了uni-app，理由是这型项目的目标不只是微信端，后续可能要出支付宝小程序、H5甚至独立App，哪怕现在只做微信端，用uni-app也不亏。事实也证明，后期甲方要求加一个H5版的预约入口，uni-app直接编译就能用，省了不少事。
2.1 uni-app开发微信小程序的基本链路
开发环境我用的是HBuilder X + 微信开发者工具，一套代码同时负责三端预览。需要注意的版本兼容问题不少：uni-app编译器版本、基础库版本、Vue版本（写Vue2还是Vue3），这些在项目一开始就要定死，否则写到一半升级框架能折磨死人。
工程目录方面我的组织习惯是：
/pages用户端主包页面/pagesWorker阿姨端分包/components公共组件/api接口请求模块/storePinia/Vuex状态管理（我们项目用的Vue3 + Pinia）/utils工具函数/static图片和静态资源
2.2 环境配置里最容易踩的坑
第一个坑：AppID。开发时要用真实的小程序AppID，不要用测试号。测试号虽然能跑，但微信支付、订阅消息、获取手机号这些能力全都没有，等做到支付环节再切AppID，整个环境和缓存都要重新弄一遍。
第二个坑：域名校验。开发期在微信开发者工具里勾选“不校验合法域名”，联调很爽，但2024年以后微信对未配置域名请求做了更严格的限制，我自己就见过同行上线时忘了关闭这个开关，真机上面所有接口直接失败。所以项目初始化之后，第一步就应把request合法域名配好。
第三个坑：AppSecret绝对不能出现在前端代码或仓库里。所有需要AppSecret的操作都要放到后端服务完成，小程序端用code换session_key，再通过后端换取自定义登录态Token。
2.3 微信支付、订阅消息、登录支付的接入顺序
接入微信生态能力时我建议严格按照下面的顺序来：
- 先搞定微信登录（wx.login + code2session），这是后续一切用户身份的基础。
- 再接入微信支付（统一下单、支付回调、订单查询），支付成功才能触发后续派单逻辑。
- 最后接入订阅消息（下单成功后可申请一次性订阅授权，用于发送服务开始提醒、完工提醒、优惠活动触达）。
一个教训：订阅消息的模板ID要提前在微信公众平台申请并审核通过，开发半路上才去申请模板，会导致联调时拿模板ID测试只能用一次性订阅，体验很糟糕。而且2023年之后微信对订阅消息的使用场景审查更严格，家政这类垂直服务，最好把模板消息触发时机做成用户主动订阅后才发放，避免被判定为骚扰用户。
3. 用户端核心模块落地：从首页到订单中心
选型完成后进入实际编码阶段。家政小程序用户端的主要模块包括首页、服务列表、服务详情、预约下单、订单中心、个人中心。下面我按实现顺序逐个说，每个模块都附上我认为值得关注的实现细节和踩坑经验。
3.1 首页：信息层级与动态配置
首页是一个家政App的脸面，信息层级我是这样排的：
- 顶部搜索栏：支持服务搜索和门店搜索
- 金刚区：日常保洁、深度保洁、家电清洗、收纳整理、老人陪护等入口
- 限时活动/轮播图：新客立减、首单优惠
- 今日推荐服务：运营后台配置，客户端按接口返回渲染
- 附近门店入口：根据当前定位展示附近门店和服务阿姨
这里需要注意，首页的轮播图、金刚区、推荐位不要写死在代码里，而应做成配置化。运营同学在后台改图片、改跳转链接，小程序端发布一次就全部生效。我见过不少项目把首页硬编码，运营每调整一次活动都要发版审核，一等就是两三天，这种体验用户早就跑了。
对了，首页的接口并发请求一定要做“Preload 预请求”。微信小程序启动时首屏渲染特别看重网络耗时，可以在首页onLoad阶段并行请求配置、金刚区、推荐位、附近门店这四类数据，每多一个串行请求，用户看到首屏的时间就会肉眼可见地变长。
3.2 服务列表与详情：SKU与价格展示逻辑
家政服务的价格模式比商品复杂，有的是固定一口价（比如空调清洗一台199元），有的是按时长计费（日常保洁每小时59元，2小时起约），还有的是按面积或者按房间数计费。前端在服务详情页要展示清晰的价格模型，不能就写一个“¥59起”，用户看不明白就不敢下单。
我的做法是：服务详情接口返回完整的SKU列表，包含时长档位、价格、优惠价、是否可加购增值服务。前端对“按时计费”的服务做一个“选择时长”组件，时长变化时实时计算总价，页面下方固定栏展示动态总价和“立即预约”按钮。
服务详情页还需要展示服务标准化流程和真实评价。家政消费者下单决策的关键影响因素主要是两点，一个是能不能约到合适的时间，另一个是服务人员靠不靠谱。所以详情页一定要放“服务保障”（比如迟到赔付、不满意重做）和“阿姨资质展示”模块。
3.3 预约下单：时间片冲突校验的思路
预约流程是家政项目核心中的核心。用户在选定服务后进入预约页，选择上门地址、预约日期、时间段，然后提交订单。
时间段不能做成随便选的自由时间，通常按上午/下午/晚间或者固定小时段（比如9:00-11:00、14:00-16:00）来切。后台阿姨的排班也以这些时间段为最小单位。
这里的关键是时间片冲突校验。当用户提交一个预约单时，后端必须校验目标时段内，该门店可用的阿姨数量是否充足；同时，阿姨端被派单时也要二次校验，防止出现“同一时间两单”的情况。
我在后端实现了一个简单的可预约数量校验逻辑：
- 对每个门店，按日期+时段建立服务能力表（capacity表）。
- 已接单数+进行中订单数要小于该时段可服务阿姨数。
- 用户同时只能有一个服务中/待服务的家政订单，避免恶意下单。
- 阿姨端点击接单时，使用数据库唯一约束或Redis分布式锁防止并发重复派单。
只靠前端判断“这个时段已满”完全不够，后端必须做硬校验，否则活动大促时并发一高就会出现超卖（超派）问题。
3.4 订单中心与状态展示
订单中心需要一个分组列表：待支付、待服务、进行中、待评价、已完成、已取消/售后。不同状态下显示的操作按钮不一样：
- 待支付：显示”去支付“按钮，带倒计时关闭逻辑
- 待派单：显示“催单”按钮，其实会发一条通知给运营
- 已派单：显示阿姨联系方式、头像、预计上门时间
- 服务中：显示“联系阿姨”、“查看服务进度”
- 待完成：显示“确认完成”、“发起客诉”
- 已完成：显示“评价”、“再来一单”
状态文案在小程序端要和订阅消息文案保持一致，否则用户会糊涂。比如小程序里写着“待派单”，订阅消息推过来却是“订单已确认”，用户就会疑惑。家政项目里，让用户对服务状态看得明明白白，比多做一个功能还重要。
4. 前端体验细节：导航栏、标题、缓存与分包
这个章节可能是很多小程序团队容易忽略的部分，但恰恰是真正决定体验感的地方。家政项目上线后用户反馈最集中的问题，就是首页慢、页面卡、在iPhone上顶部按钮被刘海屏挡住——这些全都属于前端基本功，却直接影响留存。
4.1 自定义导航栏与顶部安全区适配
家政首页因为有搜索框、城市定位、顶部轮播，用默认导航栏会很丑，所以我把首页和部分二级页面设置成了自定义导航栏。全局配置里navigationStyle改成custom，然后在页面里计算并预留状态栏高度。这里有一个贴代码的要点：
javascript复制const sysInfo = uni.getSystemInfoSync()
const statusBarHeight = sysInfo.statusBarHeight || 44
const navBarHeight = 44 // 胶囊按钮区域高度一般近似44
const totalHeight = statusBarHeight + navBarHeight
用这个计算值给占位视图设置height，再在页面里写自己的标题栏。不要想着用固定高度适配所有机型，安卓和iOS的状态栏高度不一样，iPhone Pro系列的灵动岛区域也不一样，用getSystemInfoSync动态计算是兼容性最稳的做法。
4.2 页面标题和分享标题
页面标题这块，我单独拿出来说，是因为搜索热词里大量出现“小程序头部标题”、“动态设置标题”、“小程序动态设置标题”这类问题，说明很多新手被这块卡住过。
微信小程序的默认标题写死在pages.json里的navigationBarTitleText。但家政项目里，服务详情页、订单详情页的标题要动态变化，比如从“日常保洁”详情页跳到“深度保洁”详情页，标题还都叫“服务详情”就比较low。
动态标题的正确写法是通过uni.setNavigationBarTitle在onLoad或onShow里根据页面参数设置：
javascript复制uni.setNavigationBarTitle({
title: `预约-${serviceName}`
})
分享标题则要用onShareAppMessage返回值控制，分享卡片 title 不要默认为小程序名称，应带上服务信息和优惠信息，比如“一键预约上门日常保洁，新客立减20元”，转化率会高得多。
4.3 缓存策略：什么数据该缓存，缓存多久
微信小程序设置缓存时间这个问题，搜索结果里也有不少人问。我的原则很简单：高频、非敏感的配置数据缓存，用户私有数据和订单数据尽量不缓存。
具体来说，我当时做了这样的缓存策略：
| 数据 | 缓存时间 | 说明 |
|---|---|---|
| 首页运营配置（轮播图、金刚区等） | 1小时 | 是不常变化但运营又要调整的数据 |
| 服务分类列表 | 24小时 | 家政分类很少变 |
| 用户定位城市和区域ID | 7天 | 但用户手动切换时要立即覆盖 |
| 用户基础信息（头像昵称） | 5分钟 | 避免长期不更新 |
| 订单列表 | 不缓存 | 每次进入都请求最新状态 |
缓存的key命名要规范，加版本后缀，比如home_config_v3。这样后面改数据结构、version递增就能自动让旧缓存失效，不至于出现线上用户看到一个月前首页配置的情况。
4.4 分包加载与独立分包：把包体积压到1.5M以内
微信小程序主包有2M限制，家政项目如果用户端、阿姨端全塞在主包，肯定超。我的处理方案：
- 主包只放首页、公共组件、请求库、工具库。
- 服务列表、服务详情、预约页面、订单中心、个人中心全部放进分包。
- 阿姨端单独做一个独立分包，和用户端完全隔离，阿姨点击进入时直接从独立分包启动，互不影响。
- 第三方图片资源尽量用CDN，不要把大图放static目录。
分包配置在pages.json的subPackages字段里写。这样一个主包控制在一百多KB，全部分包加一起也就两个多MB，启动速度、审核通过率都很健康。
4.5 H5唤醒小程序与页面跳转链接
项目后期甲方提出一个需求：在公众号文章、短信、外部H5页面里放小程序入口。这个场景涉及微信的URL Link与URL Scheme能力。很多人用“weixin://dl/business/?t=xxx”格式的链接来跳转，但这类链接通常是从微信支付或特定业务能力生成的，不具备通用性，不能拿来直接使用。
现在正规的做法是在微信公众平台申请微信小程序URL Link或URL Scheme，把生成的链接放在H5页面跳转按钮上。用户点击后如果打开的是微信内浏览器，可以直接拉起小程序；如果是外部浏览器，会先打开一个中间H5页面，提示用户“打开微信小程序”。要注意URL Link的生成有每日数量限制，且微信对链接的有效期做了时间限制（30天/7天可配置），过期后要服务端调用接口重新生成。
5. 接口联调、抓包分析与常见问题排查
家政小程序和其他小程序一样，最耗时间的其实是联调和排查问题环节。特别是微信生态里，登录态、支付回调、订阅消息这三个环节，坑多且隐蔽，值得单独写一节。
5.1 合规联调工具：开发者工具的Network面板与代理抓包
想排查小程序请求问题，第一步是在微信开发者工具里打开“调试器”的Network面板，可以看到每个请求的完整URL、Method、请求头、响应体。这个面板已经能解决绝大多数接口查询问题。
有些时候真机上复现的接口问题（比如某些手机网络环境下超时、DNS解析异常），开发者工具里看不出来，这时候需要借助代理工具分析流量。业界常用的有Charles或Fiddler，连接方式是：
- PC和手机处于同一局域网
- 手机设置手动代理，指向PC的IP和代理端口
- 安装并信任抓包工具的SSL证书
- 然后在小程序真机上操作，代理工具会展示完整的HTTP/HTTPS请求内容
需要强调的是，代理抓包的作用范围应限定在调试自己开发的小程序、排查自有业务接口，这属于正常开发流程。对他人生产环境的小程序做未授权流量分析、绕过SSL校验、注入操作，既不合规也违反了微信平台的规则。微信小程序代码本身也做了多层保护和合规要求，开发者根本不需要去研究“反编译”一类的灰色手段，遵循官方开发调试流程才是最快、最安全的路。
5.2 登录态失效与“开发版小程序已过期”处理
开发阶段最常见的报错是“开发版小程序已过期，请在开发者工具重新扫码”。这是因为微信对开发版/体验版小程序设置了一个有效期（通常为30天左右），超过期限后必须重新编译上传并扫码登录微信开发者工具。解决办法很直接：在微信开发者工具里点“重新编译”，然后打开“清缓存→清除全部缓存”，再用手机微信重新扫码加载开发版。
另一个高频问题是登录态（Token）失效。小程序静默登录的逻辑是：wx.login拿code → 后端用code换openid和session_key → 后端生成自定义Token → 小程序端存储Token并携带请求。如果Token过期，接口返回401，这时前端要统一处理：
- 拦截401响应，弹出登录提示
- 静默wx.login重新获取code
- 后端refresh接口换新Token
- 重放之前失败的请求
比较好用的做法是封装一个request.js，请求前判断Token是否存在，响应错误时统一做401拦截重放，避免每个页面都处理一遍登录逻辑。
5.3 真机适配中容易出现的差异
家政项目的用户群体里中老年用户占比不低，用的手机大多是中低端安卓机。开发时在开发者工具模拟器上一套效果，真机上一跑就发现问题。我遇到过的典型差异包括：
- iOS底部安全区：iPhone上“立即预约”按钮被Home指示条挡住，解决办法是给底部按钮做safe-area-inset-bottom适配。
- 安卓WebView字体缩放：部分安卓手机系统字体调大了之后，小程序页面文字错位。需要在样式里对关键布局使用rpx与固定高度混合，避免文字撑破容器。
- 单选框的原生样式在两端差异大，如果搜索词里有“微信小程序单选框”相关需求，建议不自带样式，而是用自定义标签模拟选中态，体验更统一。
- 日期时间选择器：微信原生picker组件的mode=date在iOS和安卓的视觉形式不一致，但功能上都能用。如果对美观度有要求，就自己封装一个日历弹窗组件。
运行时间一长，我强烈建议给关键接口加上请求耗时统计，用uni.report或自己埋点。家政项目中“服务列表接口慢”这类问题虽然小，但反馈到用户端就是“页面一直转圈”，影响下单率。
6. 发布上线、年审与长期运营
一个项目开发完成只是开始，上线和后期维护才是家政小程序真正受考验的环节。这里结合实操经验，讲一下从提审到稳定运营的几个关键节点。
6.1 提审前要过一遍的资质与服务类目
微信小程序审核对家政服务类目有明确要求。需要用主体资质去微信公众平台开通“生活服务 > 家政服务”类目，并上传相关资质文件。如果你只在类目里选“生活服务”，没有细分类目，审核很可能被驳回。
另外，小程序名称不能用“微信”、“小程序”等误导性词，像“weixin066”这种项目代号也需要注意命名规范。我在提审前会把以下材料先准备好：营业执照、对应服务类目资质、若涉及收费或预付费服务还需要提供相关协议说明。
开发中用到的第三方服务（如OCR身份证识别用于阿姨实名认证），建议采用腾讯云或微信官方服务商提供的能力，购买后履行相关个人信息保护与授权告知，避免审核时被询问数据来源。
6.2 小程序年审：别让有效期拖垮业务
微信小程序认证（也就是原来的“微信认证”）每年需要年审，年审费用与首次认证相同。认证有效期过期之后，小程序相关能力会被限制，比如无法使用微信支付、无法使用部分插件接口能力、无法获得新的订阅消息模板。很多运营团队只关注开发，忽略了年审，等到线上支付突然挂掉、后台才发现认证过期，那真是手忙脚乱的时刻。
我的建议是把认证到期时间提前两个月加到运营日历里，到期前一个月就启动年审流程，不要卡在最后一周。年审期间如果材料不齐，也有可能延误，甚至影响既定营销活动排期。
6.3 体验版、灰度发布与线上监控
小程序上线建议走一套“开发版→体验版→审核→灰度发布→全量发布”的流程。
开发版面向开发者自己；体验版可以生成二维码，发给产品、运营、测试同学验证；提审通过后，先在公众平台设置“分阶段发布”，灰度比例先放10%或20%，观察接口错误率和用户反馈，确认无问题再全量放量。
上线之后重点盯这些指标：
- 下单转化率：从浏览服务详情到提交订单的比例
- 支付成功率：订单创建后实际完成支付的比例
- 接口耗时与错误率：尤其关注首页聚合接口和订单列表接口
- 客诉率：服务完成后用户投诉占比，家政行业的客诉率直接影响平台口碑
6.4 阿姨端冷启动与用户增长建议
家政项目是一个双边平台，光有C端用户不够，还得有阿姨供给。如果阿姨端的服务体验不好，接单麻烦、提现难，阿姨流失很快。我的经验是阿姨端的操作按钮要放大、流程要缩短，界面文字尽量通俗，因为阿姨群体中很多人手机操作不太熟练。
冷启动阶段可以在一个城市或小区做试点，先积累一个“社区阿姨”团队，通过社区团购群、物业合作、业主群推广等方式拉来首批用户。首单优惠、邀请有礼这类手段相比砸广告来说，对家政用户更有效，因为家政消费天然是邻里口碑传播的生意。
7. 一些实际的体会
做完这个家政项目小程序，我最大的感受是：家政小程序的难点不在开发本身，而在业务模型设计和细节的打磨。预约时间片、订单状态机这些设计一旦定型，代码实现不过是一两周的工作量；而真正决定用户留不留下来的是导航栏有没有挡住按钮、标题有没有显示对、缓存有没有让页面秒开、阿姨能不能顺利接单。
另外提醒一句，这类小程序项目一定要做好“变更管理”。家政业务的运营规则一直在变——今天要加一个服务品类，明天要改一波定价策略，后天运营要上新活动。客户端这边所有运营位都做成配置化，服务项目列表和价格做成后端动态下发，这样业务调整时才不用三天两头提审发版。
如果你现在正准备开发家政小程序，我建议按照这个顺序来定方案：先画清楚角色和状态机，再定技术栈，然后依次做登录、用户端首页、预约下单、支付、订单中心、阿姨端。不要一上来就写代码，至少花两三天把业务模型理清楚。这个过程在前期多花一点时间，后面整个研发周期都能省回来。