1. 一个停车小程序的边界不是把页面画出来而是把业务闭环跑通花了大半个月把停车自助系统从零到一跑通之后我越来越觉得这类项目特别适合当作微信小程序的练手作品。它不像电商那样有复杂的商品体系但要害流程一个不少车牌绑定、车位状态、计费规则、支付回调、设备联动随便挑一个模块出来都能写出一堆坑。所以我把整个项目的源码、文档和调试过程整理了出来这篇文章就当一次完整交付记录——你拿去能直接改也能看懂我当初为什么这么设计。停车自助系统的名字听起来像是“给停车场做一个在线缴费页面”但真正深入进去之后你会发现问题远不止“页面”这么简单。它本质上是一个涉及人、车、场、钱、设备的五方协作系统。如果不先把边界想清楚代码写再多都只是玩具。1.1 用户、管理员、设备三端的链路拆解先看一个最简单的停车场景车主开车进入停车场摄像头识别车牌后抬杆入场车主停好车办完事回到车上出场时在道闸前扫小程序二维码确认停车时长和费用支付道闸抬杆离场。这一连串动作在小程序端只体现为几个页面但数据流转其实横跨了三个角色。用户端要处理的是微信登录授权、车牌绑定、实时车位查询、预约锁定、支付、历史订单查询。管理端要处理的是车位信息维护、计费规则配置、异常订单处理、设备状态监控。设备端则更特殊它通常是硬件厂商的接口不会直接跑在小程序里但需要和你的后端完成“入场识别、出场识别、抬杆指令、执行结果上报”这四次握手。我在这套系统里把三端的数据入口和出口分得很清楚端角色核心职责典型数据入口典型数据出口用户端小程序自助操作与支付车牌号、车位编号、支付结果预约请求、支付请求、寻车请求管理后台运营与规则配置费率、车位状态、放行名单价格配置、异常退款、掉线设备清单设备端物理世界执行车牌识别结果、地锁状态入场事件、出场事件、抬杆回执如果你只把“页面画出来”不做清楚数据闭环就会发现一个典型问题前端明明显示了“车位已预约”但用户到现场根本没有对应车位。原因就是预约记录只写在本地缓存里没有同步到后端也没有和设备端联动。所以我在项目一开始就要求自己每一个用户操作都必须能说清楚它之后影响哪张表、哪个设备、哪个状态。1.2 必须做的核心功能和容易做进去的伪需求“超全”这两个字往往会诱导人做加法但做加法之前先得守住底线。我当时列了三层清单。第一层是必须有否则线上没法用的登录授权与车牌绑定车位实时状态展示与预约停车计时计费含免费时长、封顶价微信支付闭环预支付单、回调、订单状态回写历史订单与退款入口第二层是容易做但容易做歪的优惠券、积分、分享有礼月卡自动续费场内导航和反向寻车发票开具第三层是看起来很亮但交付时间会失控的大屏可视化驾驶舱多停车场集团化接入和第三方会员系统打通我最后只把第一层做得完整第二层拆出一个“寻车”模块放在系统里第三层全部砍掉。原因很简单这类系统上线后的第一个投诉一定来自计费而不是界面。如果费率算法出了问题用户多付一块钱都会天然觉得系统“黑”后续再补功能也救不回来。所以计费、支付、订单状态这三件事的优先级永远高于一切花哨模块。1.3 判断闭环是否跑通的三条标准我给自己定的验收标准只有三条如果三条都成立才叫闭环跑通。第一用户入场时一定能生成一笔有效订单无论入口是摄像头识别、二维码扫码还是手动输入车牌。第二用户出场时一定能算出正确的金额并且支付成功后订单状态能同步到“已支付”设备端能收到抬杆指令。第三任何一个环节异常时比如设备断网、支付回调丢失、车牌识别错误系统都要有兜底路径让现场人员能在管理端手动处理而不是卡死一个订单。这三条标准恰好对应了源码、文档、调试三件事源码负责把流程写对文档负责告诉别人规则是什么调试负责解决流程中各种“没想到”的边界情况。2. 技术选型与工程骨架为什么用原生小程序加云开发这个项目我一开始就定了两个技术约束第一客户端用微信原生小程序不用 uniapp第二后端用微信云开发不自建服务器。原因不是因为我偷懒而是基于项目形态做过取舍。2.1 不用 uniapp 的三点原因uniapp 确实能跨端前端界面的代码可以复用到 App、H5甚至鸿蒙。但停车自助系统的目标平台很明确就是微信生态。用户扫码即用不需要下载 App也不需要跳转浏览器。在这个前提下uniapp 的跨端优势发挥不出来反而带来三个实际问题。第一是 API 兼容性。微信小程序里的支付、订阅消息、蓝牙、NFC、车牌识别摄像头能力很多都带原生环境依赖。uniapp 虽然做了条件编译但真机调试时有些能力表现和微信原生并不完全一致出了问题反而要多查一层框架源码。第二是组件抽象层。我在项目里需要自定义车牌键盘原生小程序一个 custom component 就能搞定uniapp 里要考虑跨端渲染逻辑代码复杂度和心智负担都会上升。第三是调试成本。uniapp 最终也会编译成小程序等于你在“源码”和“编译产物”之间多了一层映射对新手来说排查问题更痛苦。如果你未来明确要发布 App 和 H5uniapp 是不错的选择。但就这个项目而言原生小程序加云开发是最短路径。2.2 源码目录怎么组织别人拿到手才不会骂人源码结构的合理性直接决定这套系统能不能被别人接手。我最开始的第一版把页面、工具函数、云函数全都堆在根目录结果自己三天后再看都找不到文件。后来重构成了下面的结构miniprogram/ pages/ index/ // 首页 车位总览 parking/ // 车位列表与预约 bind-car/ // 绑定车牌 order/ // 订单确认与支付 my/ // 我的车辆、历史订单 components/ car-license/ // 车牌输入键盘 parking-card/ // 车位卡片组件 empty-state/ // 空状态组件 utils/ fee.js // 计费算法与后端保持同一套规则 format.js // 时间、金额格式化 api/ index.js // 云函数调用统一封装 app.js app.json app.wxss cloudfunctions/ login/ // 获取 openid签发登录态 bindCar/ // 车牌绑定与校验 getParkingStatus/ // 聚合车位实时状态 createOrder/ // 生成预支付单 payCallback/ // 微信支付回调处理 syncDevice/ // 设备侧轮询订单状态 refund/ // 退款 docs/ README.md DEPLOY.md DEV.md USER.md页面目录按业务区分组件独立放云函数按接口语义拆分而不是合并成一个大函数。我一个一个云函数拆开好处有三个冷启动互不影响某一个函数出问题不会拖垮别的接口日志也能单独看权限可以按函数单独控制登录函数和支付回调函数需要的权限完全不同文档也更好写每个函数对应一段说明别人看代码时能迅速定位。2.3 订单状态机与数据库权限这两件事不能含糊停车计费系统的核心不是视图层而是订单状态机。我把订单状态定义为六个状态含义触达方式CREATED订单已创建等待入场确认用户预约或设备识别后生成PARKING车辆已在场内入场设备确认计时开始PAYING支付处理中用户发起支付生成预支付单PAID已支付等待离场支付回调确认CLOSED已完成离场离场设备确认订单关闭EXCEPTION异常订单待人工处理设备断网、支付超时、退款纠纷状态流转必须严格单向推进。用户不可能从 PARKING 直接跳到 CLOSED中间必须经过 PAID。这样设计的价值在于任何时刻你都能回答“这笔订单到哪一步了”设备端和客服端也都能依据状态做一致判断。云开发数据库的权限设置也是同样关键的坑。parking_spaces集合必须设置为“所有用户可读”否则用户端根本查不到车位数据而orders和cars集合必须限制为仅创建者可读写同时让云函数通过后台权限直接操作数据。云开发里云函数天然具备管理端权限可以绕过客户端权限限制这是这套体系的一个核心特性。如果一开始不把权限规则写清楚调试阶段就会反复遇到“数据库请求失败”的报错。3. 关键模块落地笔记车牌、车位、计费、设备联动框架搭好之后最关键的就是把几个硬骨头啃下来。我按难点从高到低排序逐个拆解。3.1 车牌绑定正则校验、OCR 辅助和二次确认车牌输入最大的坑是用户手动输入时容易混淆字符。比如“1”和“I”、“0”和“O”在普通键盘上几乎无法区分。所以我自建了一个车牌专用输入组件只在省份汉字和数字字母间切换并且把容易混淆的 I 和 O 直接排除掉。车牌号对应的正则校验是这样的const platePattern /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼][A-Z][A-HJ-NP-Z0-9]{5}[DF]?$/这里[A-HJ-NP-Z0-9]意味着去掉 I 和 O新能源汽车的车牌有 8 位字符最后多出来一个 D 或 F 表示纯电动或混动正则也要兼容。如果你的停车场还没有新能源车位规则可以先不做 D/F 的区分但正则至少要放开位数否则新能源车主绑定车牌时会直接报错。只靠手动输入还是不够效率所以我加了 OCR 辅助识别。小程序端用 camera 组件截取车头照片把图片传到一个云函数云函数再调用第三方 OCR 接口返回识别结果。但我没有让识别结果直接保存而是回传前端弹窗让用户二次确认。因为实测中 OCR 对汉字识别的准确率大概在九成左右“京”偶尔会被识别成“示”这种错误一旦进库后面计费、匹配设备都会乱套。3.2 车位实时刷新轮询和数据库订阅之间怎么选车位状态的变化频率不高但实时性要求确实存在。停车场里一旦有车进、有车出其他用户希望能较快看到状态更新。技术上可以选两类方案。第一类是云开发的实时数据推送也就是collection.watch()。这个方案体验最好数据变化后会自动推给前端。但它对并发连接数有配额限制每一个在线小程序端都占一条连接。如果停车场门口人多连接数突然上来配额极易被打满反而引起线上故障。第二类是传统轮询前端每隔 5 秒调用一次获取车位状态的云函数。这个方案稳定、实现简单而且 5 秒的延迟对车位状态场景完全够用。最终我选了轮询。原因很简单停车场不是一个高实时场景用户不差这几秒稳定性和成本远比“秒级推送”重要。轮询还有一个优化点前端拿到数据后不要无脑 setData而是先对比上一次的状态如果有变化才更新视图。否则每 5 秒刷新一次列表屏幕会反复跳变视觉上非常不稳定。3.3 计费算法金额计算必须放在云函数防的是篡改计费规则表面上很简单按小时收费加免费时长但如果细化下去需要定义清楚几个关键参数免费分钟数、每小时的单价、按天封顶价格、是否按自然日还是连续 24 小时封顶。我最终给出的计费逻辑是function calcFee({ entryTime, exitTime, feeRule }) { const minutes Math.ceil((exitTime - entryTime) / 60000) if (minutes feeRule.freeMinutes) return 0 const chargeableMinutes minutes - feeRule.freeMinutes const hours Math.ceil(chargeableMinutes / 60) const fee hours * feeRule.hourlyRate return Math.min(fee, feeRule.dailyCap) }这是最简单的模型不足一小时按一小时收费全天有封顶价。看起来没错但这里有几个边界必须注意。第一个是“跨天”。如果入场时间是前一天 23:50出场时间是当天 00:10停车时长 20 分钟已经超过免费 15 分钟需要计费。这里不能用两个自然日分段计算否则会各算一天产生完全错误的费用。解决办法就是统一用时间戳差值不看日期字面值。第二个是“余额精度”。JS 的浮点数计算存在精度问题金额不能用“元”做单位而应该用“分”做整数运算。比如0.1 0.2在 JS 里不等于 0.3放到金额计算中就是事故。我在设计数据库表时就把金额字段全部定义为整数分展示层再做 100 的除法。第三个是“防篡改”。前端显示金额只是给用户预览真正的费用计算必须在云函数里完成。原因很直接前端时间和金额都是可以被修改或伪造的。云函数从数据库读取入场时间和结束时间再用服务器时间计算才能保证公平。3.4 设备联动云函数轮询订单状态避免长连接断线设备端和微信小程序之间的通信最常见做法是让设备端调用后端接口或者后端主动推送。但在真实停车场场景里设备和后端之间通常不具备稳定的长连接条件而且不同厂商的硬件协议差异很大。我在实现时做了一个折中方案。入场设备端的摄像头识别车牌后设备向一个云函数发起 HTTP 请求写入入场事件同时生成一笔 PARKING 状态订单。这个接口可以由硬件厂商主动调用不依赖轮询。出场用户在小程序端支付成功后订单状态变为 PAID。设备端并不需要实时感知这件事而是由一个定时触发的云函数每隔 2 秒查询 PAID 状态且尚未执行抬杆的订单然后向设备端下发抬杆指令。这种方案的好处是即使支付回调晚了几秒或者设备端临时断网轮询也能在恢复后自动补上不会丢单。如果走长连接推送设备一旦掉线指令就丢了还得额外做消息补发复杂度高很多。4. 调试这件“小事”停车系统翻车记录与定位思路如果只谈源码和文档不提调试过程那这篇交付记录就缺了最真实的部分。下面这几个案例是我在开发过程中真实遇到过、也真实花时间排查过的问题它们比代码本身更能体现一个系统的复杂度。4.1 三种调试环境怎么配合别傻乎乎只靠开发者工具微信小程序的调试至少分三层开发者工具本地调试、真机预览调试、线上云函数日志排查。很多新手只会在开发者工具里点“编译”但停车系统的很多问题恰恰只在真机和线上环境里暴露出来。开发工具适合打断点调试前端逻辑尤其是组件交互、页面跳转。云函数也可以在云开发控制台里选择“本地调试”把云函数跑在本地 Node 环境方便观察变量。真机调试适合验证摄像头、支付、定位这类依赖硬件能力和微信客户端的特性。线上排查则必须依赖云开发控制台的日志查询每个云函数调用都有独立的日志流。我在实际开发中养成的一个习惯是在api/index.js统一封装云函数调用每个请求都带上request_id不管成功失败都在云函数侧把request_id和关键参数打印出来。这样后端报错时我只要让用户把页面上的错误码发过来就能在日志里找到对应的链路而不是在几十条日志里大海捞针。4.2 真机白屏一个看似“玄学”但实际上有迹可循的问题最诡异的一个问题开发者工具里一切正常点击编译一切都能显示但手机预览版一进去就是白屏过一会儿偶尔又恢复。排查到这个问题的过程很有代表性。我先怀疑是页面渲染问题把 index 页面里所有数据都改成写死的假数据真机上仍然白屏。然后又怀疑是云开发没初始化成功打开调试器看wx.cloud.init的报错果然看到了env not found。最后定位到原因app.js里的env参数写的是云开发环境名而手机上预览版使用的环境配置和开发者工具不一致导致数据库请求全部超时。页面在拿到不到数据的情况下渲染逻辑又没有做异常兜底于是整页空白。这个经历让我给所有页面加了三条默认逻辑数据初始值必须是空数组而不是 undefined网络请求必须有 try/catch异步抛错时至少要渲染一个“加载失败”的空状态组件而不是直接什么都不显示。4.3 支付成功但订单状态没更新回调链路里最容易漏的三件事停车系统最核心的一条链路就是支付。这里出问题的概率是最高的我第一次联调时就遇到了“用户微信零钱已经扣款但订单显示未支付”的情况。一步步排查后问题出在了三处。第一微信支付的回调地址没有配好。小程序端发起wx.requestPayment之前需要在商户平台配置回调地址让微信支付结果通知发送到云开发暴露的云函数地址。如果这里填错回调根本进不来。第二回调验签不能自己硬写。云开发环境里微信支付回调的验签最好用官方 SDK而不是自己解析报文后拼一个 sign 出来。手写验签很容易漏字段或排序错位轻则验签失败重则极容易被不法请求钻空子。第三更新订单状态时要对订单当前状态做判断。回调可能重复推送也可能乱序到达。我在payCallback云函数里的更新条件是const res await db.collection(orders) .where({ _id: orderId, status: PAYING }) .update({ data: { status: PAID, paidAt: Date.now() } })如果更新条数不是 1说明订单当前不是 PAYING 状态直接返回成功让微信停止重推而不是继续执行后续逻辑。这样才能保证重复回调不会把订单状态改写乱。4.4 计费边界跨天、免费时长和金额精度的实测调试期间我发现计费算法写起来容易但测试时总有喜剧效果因为人会下意识用常规小时数去试而忽略了边缘情况。我后来整理了四类必须测试的边界场景停车时间恰好等于免费时长15 分钟内免费等于 15 分钟时应该返回 0不能直接把写成。停车时间刚超过一小时比如 61 分钟按不足一小时按一小时算的话应该是两小时费用。要确认产品和运营是否接受这种计费方式。跨天订单入场前一天出场当天计算不准用日期字符串差要用时间戳差。金额精度用分存储所有折扣、封顶值都用整数分计算。把这些边界问题都测一遍以后我才敢把费用规则开放给管理后台。否则现场运营人员随便改一个费率参数后端可能直接算出负数或天价订单。5. 源码文档怎么整理才配得上“超全”两个字项目标题里的“超全”一半体现在功能闭环另一半必然体现在文档。如果这文档写出来只是为了应付检查那调试过程中积累的任何经验都会丢失接手的人等于重新踩一遍坑。我的文档整理原则是按读者拆分而不是写一篇又臭又长的说明书。5.1 四段式文档结构README、部署、开发、使用我把文档拆成了四个文件每个文件面向一类人。README.md面向第一次拿到代码的人。里面写清楚项目是什么、有哪些功能、目录结构、如何快速启动。我还会放几张核心页面截图让人在跑起来之前就知道最终效果是什么。DEPLOY.md面向部署者。里面记录云开发环境的创建步骤、云函数逐一部署的操作、数据库集合与权限设置、微信支付商户号的绑定流程、定时触发器的配置方法。这一步最容易漏的是“云函数需要先部署再到控制台配置环境变量”文档里我会把每一步的按钮位置都写清楚。DEV.md面向想改代码的开发者。里面包含数据字典、订单状态机说明、云函数调用关系图、计费算法说明、设备接口对接协议。这个文件的价值在于接手者不需要通读全部源码就能知道改某个功能应该动哪个文件。USER.md面向停车场管理员。里面写的是后台的使用说明如何新增车位、修改费率、处理异常订单、手动抬杆、查看报表。好的用户文档应该像操作手册写到没有任何技术背景的人也能照着完成日常工作。5.2 代码注释怎么写才有用而不是废话踩过几次“注释比代码还难懂”的坑之后我给自己定了一条规矩注释只写“为什么”不写“是什么”。因为代码本身已经说明了它做什么再复述一遍只是噪音。比如订单状态从 PARKING 改为 PAYING 的那行代码好注释应该写“先置成 PAYING 的目的是防止用户在多台设备上同时发起支付生成多个预付单”。这样接手者才能理解这个状态设计的意图而不是只知道“这里改了个状态”。我在源码里也专门保留了几个这样的注释它们都是我调试时真正踩过坑后得出的经验。代码会过时但“为什么这样设计”的理由往往能帮后面的人少走很多弯路。5.3 实用 FAQ 和交付检查清单文档里我还放了一张非常实用的 FAQ 表用来覆盖线上运营时的常见问题问题可能原因快速处理小程序进去白屏或一直 loading云开发环境 ID 配置错误或云函数未部署检查 app.js 中的 env确认云函数已部署支付成功但订单状态没更新回调地址未配置、验签失败、更新条件不匹配检查商户平台回调配置查看云函数日志用户看不到车位状态parking_spaces 集合权限不是“所有用户可读”到云开发控制台调整数据库权限车牌绑定总是失败正则没有兼容新能源车牌或 OCR 识别错误检查正则确认二次确认弹窗是否正常弹出云函数报“找不到 openid”调用端未经过 login或环境未初始化先调用 login 云函数再拉取其他数据最后还有一份交付检查清单至少包括云函数是否全部部署、数据库权限是否符合预期、微信支付回调是否真实可用、定时触发器是否开启、文档里写的步骤有没有和当前代码版本对得上。我每次发新版本之前都会按清单过一遍省掉了很多现场事故。5.4 一点小经验调试、文档不要放到最后一起做最后分享一个我个人的真实体会。第一次写这个系统时我采取的是“功能写完了再统一补调试和文档”结果是调试时发现计费逻辑要重写文档里所有截图全部作废等于做了两遍。第二次我改变策略每完成一个模块就顺手写一个对应的小文档并把调试过程中遇到的关键报错和解决方案记在 DEV.md 里。这样项目结束时文档其实已经积累完成了九五成我只需要做一次格式统一和细节校对就好。停车自助系统这类项目验收的人往往不看页面多华丽而是看你从进场到出场计时计费对不对、支付有没有漏单、异常能不能兜住。源码、文档、调试这三样东西如果把调试和文档只放在最后几天赶工是补不出来的。我踩过这个亏所以这次特意分散到每个模块完成时就顺手写。希望这份交付记录能让你少走几段冤枉路。