项目做完了趁着热乎劲把整个过程好好梳理一下。事情得从一阵子前的对接说起。某水上执法部门的巡逻艇出勤执法人员要靠纸质台账抄船舶信息、拍照片回单位再把资料一点点敲进系统。江面风大船一晃笔迹就歪恶劣天气连字都看不清。当时负责对接的负责人就问了一句能不能用微信小程序把这套流程直接搬到手机上来于是就有了这个“基于微信小程序的水上警务通小程序设计与实现”的项目。这篇文章会把从功能拆解、技术选型到实操落地、踩坑修复的完整过程写出来给正在做移动执法、外勤作业类小程序的团队做个参考。内容偏工程落地不是理论悬浮的那种每一步都有实际场景支撑你抄作业也能抄得明白。1. 为什么是微信小程序场景痛点与选型取舍1.1 水上执法工作流的真实痛点做这类项目第一步不是想技术而是先把业务场景摸透。我跟着一线人员出了几趟船发现水上执法和陆地执法完全是两种节奏。首先网络环境非常不稳定。船在航道中间、锚地、桥区附近手机经常只有一两格信号4G时有时无。而执法记录、船舶核查又恰恰需要联网查数据库。这就决定了系统不能做成纯在线依赖型的必须考虑离线优先的架构。其次工作场景是在船上。甲板湿滑、屏幕沾水、手套操作输入框不宜太多按钮必须够大。很多执法人员年龄偏大打字速度慢能点选的绝不让手输能用语音的绝不靠键盘。再就是数据一致性要求极高。执法记录属于证据性质的材料一条检查记录生成之后不能随意删改后端必须保存完整操作日志。这在设计数据库和接口时就要提前想清楚不是上线之后再打的补丁。还有一点容易被忽略人员的手机型号参差不齐。有的用安卓千元机有的是老款苹果屏幕大小、性能差异很大。小程序的跨端兼容性在这里是实打实的优势一套代码多端跑省掉了很多“机型适配地狱”的麻烦。1.2 几种技术方案的取舍对比当时备选方案有三个原生App、H5网页和微信小程序。我们做了个简单对比基本把选型逻辑说明白了。维度原生AppH5网页微信小程序使用门槛需安装、需更新版本管理麻烦打开即用无安装打开即用免安装扫码直达开发成本高需要iOS、安卓双端相对低但原生能力弱中等一套代码跨平台更新机制应用商店审核周期长随时发布审核较快可灰度发布相机/定位能力强弱浏览器限制多强API完善弱网处理可深度定制受限于浏览器有离线缓存API、网络状态监听账号体系需自建需自建微信生态自带openid体系最终选了微信小程序核心原因有三个。第一执法部门内部已经有微信使用习惯人员不需要额外学习成本。小程序码一发群里面扫一下就能用。第二小程序的API对移动端能力的封装非常完善拍照、录音、定位、地图组件都是现成的比在浏览器上做H5舒服太多。第三更新迭代快改个bug提审发布一天内基本能搞定App动不动就等一周的审核周期在快速迭代期完全不能接受。1.3 微信生态带来的额外优势小程序还有一个隐藏优势是很多人忽略的微信的订阅消息体系。水上执法的任务往往有很强的时效性比如某条船预计几点靠泊、某个锚地需要突击检查。以前用电话通知容易漏、容易忘。用小程序的话任务下发后能通过微信订阅消息推送到执法人员微信上。虽然微信的订阅消息现在被拆成了订阅一次推送一次局限性不小但做内部工具场景基本够用。另外“添加到我的小程序”“浮窗”这类轻量入口也很实用。执法人员常用的功能可以从微信下拉菜单一键调出不需要在手机桌面上找半天图标。当然小程序也不是没有限制。最典型的就是包体积限制。主包不能超过2MB分包总大小限制也卡得比较死所以图片资源必须尽量放云端不要堆在本地。这个问题在后面做技术方案时重点处理。2. 功能设计一线需求如何翻译成模块2.1 核心功能模块清单整个小程序的角色逻辑比较简单就是管理员、普通执法人员和系统后台三类。核心功能模块如下模块面向角色核心能力工作台所有人今日任务、待办数量、快捷入口船舶核查普通执法人员OCR识别船名、按船名查询、历史记录现场检查普通执法人员检查表填写、拍照取证、定位水印、草稿箱任务协同管理员任务下发、状态流转、订阅消息提醒轨迹与签到所有人位置上报、巡逻轨迹记录统计后台管理员按时间/区域统计、报表导出功能听起来不复杂但每个模块背后的细节非常多。下面挑几个重点展开讲讲。2.2 船舶核查模块不只是“输入船名查一下”这个模块看似简单实际上花了不少心思。执法人员在船艇上核查一艘船首要任务就是确认这艘船的身份信息是否真实、证书是否有效。传统方式是拿个本子记船名回单位再查。现在要做到现场实时核查。第一步是识别。船名一般刷在船身两侧字样大小、颜色、底色各不相同。考虑到执法人员可能穿着手套、戴着护目镜让手输船名不现实就做了一个OCR识别功能拍照自动识别船名识别成功后自动发起查询。识别不成功的话再退化为手工输入。我们用的OCR服务是后端接的通用图像识别接口主要是在请求前做预处理——压缩图片、增强对比度船身上的反光对识别率影响很大这是个关键细节。第二步是查询。根据船名或者船舶识别号调用后端接口获取船舶登记信息包括船籍港、船舶类型、所有人、证书有效期、是否在锚地/在航状态等。这些字段是给执法人员快速判断用的最关键的是证书是否过期、船舶是否被布控。所以记录里特别做了“重点检查原因”的打标功能。第三步是历史记录。同一个执法人员对同一艘船可能做过多次检查历史核查记录要能一键带出。这样例行检查时不用重复填写船舶基础信息新人上手也快得多。2.3 现场检查模块表单设计的逻辑现场检查是整个系统里最核心的数据生产模块。执法人员到了现场要把检查结果录入系统。这个模块有两条设计原则非常重要。第一能用选项的绝不用输入框。执法检查表里的字段是有规范枚举值的比如船舶类型、证书状态、违规类别。如果开放手输几个人填出来的格式可能完全不一样后面统计分析就废了。所以全部设计成下拉选项或者复选框输入框只保留了数量、金额、备注这类自由格式字段。第二照片必须现场拍摄不允许从相册选择。这是执法取证的基本要求。用wx.chooseMedia时把source限定为camera照片自动带上时间水印和经纬度水印。水印不是在拍照时加上去的而是在上传前用canvas在客户端合成。这个细节后面在技术章节详细说。检查记录还支持存草稿。为什么要草稿因为江面网络不稳定现场填了一半发现断网了如果直接清空表单执法人员心态就崩了。草稿存在本地 storage 里网络恢复后一键提报体验会好很多。2.4 任务协同与轨迹闭环任务协同这块主要是管理员的日常工作。以前派任务靠电话和对讲机现在系统里直接下发任务单。任务的状态流转设计了几个节点未接收、待执行、执行中、已完成、复核中。每个节点变更都会记录操作人和时间方便后期追溯。订阅消息提醒这里踩过一个细节坑微信的订阅消息是“一次性订阅”用户不主动点“允许”就收不到下一次。所以我们在任务下发的页面里专门做了一个授权引导弹窗提示“订阅一次接收一条通知”虽然体验上有点绕但这是微信平台的规则只能顺着它来。轨迹模块的定位是解决巡逻监管问题的。以前领导不知道巡逻船去哪儿了、去了多久只能靠对讲机汇报。现在小程序可以在后台记录位置上报点形成一个巡逻轨迹。这里有一个取舍持续后台定位会非常耗电所以并没有做成实时上报而是每30秒一次前台定位上报离开页面自动停止。够用且不给手机续航添麻烦。3. 技术架构与实现细节3.1 前后端整体架构选型技术栈这块我直接说结论小程序端用的是原生框架配合Vant Weapp组件库。后端用的是微信云开发云函数 云数据库 云存储。如果团队没接触过云开发这块要稍微解释一下。原生框架的理由是可控性强。小程序本身的WXML/WXSS/JS体系已经够成熟加上原生支持分包、自定义组件做复杂表单页面不至于被框架束缚。第三方框架比如uni-app或者Taro虽然能多端复用但这个场景只需要微信端引入框架反而多一层性能损耗和调试成本。云开发的选择就要多权衡一下。云开发的云函数本质是Node.js环境可以独立部署、独立鉴权不需要自己买服务器、搭Nginx、配HTTPS部署效率非常惊人。对于这种内部应用效率就是生命线。数据库用的JSON文档模型存检查表单这种结构化数据非常顺手。存储就用来放照片、执法录像。但要特别强调一点如果项目涉及敏感执法数据部署环境必须符合所在单位的安全管理规定。我们在设计时预留了接口层后续如果要切换到内部自建服务器只需要替换云函数的实现前端调用层几乎不用动。3.2 数据库设计与权限规则数据库集合我们设计了六个核心集合集合名称主要字段用途usersopenid, 警号, 姓名, 角色, 单位用户身份与权限ships船名, 船舶识别号, 类型, 所有人, 证书状态船舶底档数据missions类型, 对象id, 指派给, 状态, 截止时间任务下发与跟踪records船舶id, 检查类型, 表单内容json, 照片列表, 定位现场检查记录photo_filesfileID, 大小, 上传时间, 关联记录id照片资料归档audit_logs操作人, 操作时间, 操作内容, ip审计日志数据库权限规则这里要重点讲一下。微信云数据库默认的权限模板是“仅创建者可读写”但我们的业务场景是多人共享数据。比如执法人员A提交的检查记录管理员B必须能查看甚至复核。所以不能直接用前端的权限声明来控制而是规定所有集合默认关闭前端直接读写权限统一通过云函数去操作数据。云函数运行在服务端权限不依赖前端用户身份校验逻辑可以自己写。每个云函数里先验证调用者的openid再查users集合确认角色最后才放行。这个模型虽然多写几行代码但安全性裸奔的坑算是彻底避开了。3.3 离线缓存与弱网同步核心难点这个模块是整个项目里我最想展开讲的。水上场景网络不稳定意味着系统必须具备离线可用能力。方案用的是“本地优先 队列同步”的模式。核心思路是三步。第一步写请求之前先检查网络状态。用wx.getNetworkType判断网络类型如果完全无网络直接把记录写入本地待同步队列。如果网络正常不直接发请求而是把记录写入本地队列然后由同步器统一上报。这个设计的本质是所有写操作都先落本地不会因为网络瞬间抖动就丢数据。第二步网络恢复自动触发同步。小程序有wx.onNetworkStatusChange监听网络切换事件一旦网络恢复立刻调用同步器把待同步队列里的数据逐个上报。上报成功的记录从队列移除失败的重试次数加一超过三次标记为“同步失败”并保留在队列里等下次网络变化再试。第三步上传要做幂等设计。弱网环境下最容易出现的问题是请求超时后重试服务端已经处理了但客户端以为失败又发一次导致重复数据。解决办法是在记录生成时就生成一个32位的唯一 messageId服务端用来查重。收到请求先从日志表查这个messageId是否存在存在就直接返回成功不存在才落库。图片的离线处理比结构化数据更麻烦。我的做法是现场拍完照片立刻在本地做压缩生成一个宽度1080的缩略图然后立即把照片原始文件和缩略图都存进本地临时目录。同步的时候优先传缩略图保证记录可用原图走后台慢慢传。这样即使原图因为网络传不上来检查记录的正文内容已经完整了原图可以等网络好再补传。3.4 地图定位与照片水印的处理定位模块有两个技术点很容易踩坑。第一个是坐标系问题。微信小程序的wx.getLocation返回的是GCJ02坐标系而很多后端GIS系统用的是WGS84坐标系两套坐标之间有几米到几十米的偏差。你在水上漂着看可能觉得无所谓但做轨迹回放和数据入库时汇总到地图上就会发现轨迹整体偏移到岸上去了。所以后端接口要统一约定如果是外部地图底图直接存GCJ02如果是内部GIS必须在云函数里做一次坐标转换。第二个是水上定位漂移问题。GPS在水域受到反射和遮挡概率更高单次定位点经常跳来跳去。我们做了一个简单但好用的滤波逻辑连续采集5个定位点去掉最大和最小偏差的点取剩下的中间三个点的平均值作为上报的坐标。实测下来轨迹平滑度提升明显。水印照片是合规要求。实现方式是拍照后用canvas把原始图片画到底图上然后叠加绘制当前时间、经纬度坐标、执法人员工号三行文字最后把canvas导出成临时文件再上传。这个方案的好处是水印直接烧进像素里防止事后修改和抵赖。代码上只需要二十几行canvas绘制逻辑但价值非常大。// 照片水印合成示例 const drawWatermark async (tempFilePath, locationText, officerNo) { const ctx wx.createCanvasContext(watermarkCanvas); const img await getImageInfo(tempFilePath); // 按原图尺寸设置画布 ctx.setCanvasSize(img.width, img.height); ctx.drawImage(tempFilePath, 0, 0, img.width, img.height); // 绘制定位信息水印 ctx.setFillStyle(rgba(255, 255, 255, 0.8)); ctx.setFontSize(14); ctx.fillText(new Date().toLocaleString(), 10, img.height - 60); ctx.fillText(locationText, 10, img.height - 38); ctx.fillText(执法工号 officerNo, 10, img.height - 16); ctx.draw(false, () { wx.canvasToTempFilePath({ canvasId: watermarkCanvas, success: (res) { // res.tempFilePath 即为带水印的图片 } }); }); };4. 从零到上线的全流程实操复盘4.1 项目初始化与环境准备第一步是小程序账号注册。这里有个容易忽略的点如果是内部工具不一定要急着走公开上架流程。我们的做法是先注册一个小程序账号添加“体验成员”和“开发成员”用微信开发者工具生成小程序码内部扫码就能进入“体验版”整个灰度测试期间可以不对外提审发布效率高不少。政务类小程序涉及类目资质要求比较严格正式上架前必须准备好主体资质文件。如果暂时没有体验版阶段完全够用。第二步是代码工程初始化。原生小程序的目录结构我习惯这样组织miniprogram/ pages/ # 页面 components/ # 自定义组件 utils/ # 工具函数 api/ # 接口封装 store/ # 全局状态 cloudfunctions/ # 云函数目录App配置里要把“权限说明”提前写好特别是定位权限的文案。微信要求不能默认申请所有权限只在需要时弹出的用户提示里说明用途。这个文案写得好不好直接关系到审核通过率和用户信任度。{ permission: { scope.userLocation: { desc: 你的位置信息将用于记录执法位置和生成巡逻轨迹 } } }4.2 登录鉴权与身份绑定登录逻辑是这样的打开小程序先wx.login拿到code传给云函数云函数调用微信接口换取openid。换取成功后根据自己的业务表生成一个自定义token存到本地 storage后续所有请求都带上这个token。这里有个比较容易忽视的安全点不能在前端直接使用openid作为身份标识。因为小程序的运行环境可以被逆向分析openid被拿到了就可以伪造数据。正确做法是openid只在云函数内部识别用对外只暴露随机token服务端根据token查users集合判断当前用户身份和权限。身份绑定这块因为是小范围内部使用管理员在后台可以直接把某用户的小程序openid和他的警号做绑定。绑定的前提是上报警号姓名单位管理员审核通过后就激活账号。被拒绝或者未审核的openid调用任何云函数都返回“未授权”。// 云函数登录示例 exports.main async (event, context) { const { code } event; const result await cloud.openapi.auth.code2Session({ code }); const openid result.openid; // 查询用户表 const db cloud.database(); const userRes await db.collection(users).where({ openid }).get(); if (userRes.data.length 0) { return { code: 403, message: 账号未激活请联系管理员 }; } // 生成token并返回 const token generateToken(openid); await db.collection(users).doc(userRes.data[0]._id).update({ data: { lastToken: token, lastLogin: Date.now() } }); return { code: 0, data: { token, userInfo: userRes.data[0] } }; };4.3 核心页面与组件实现首页工作台是工具箱式的布局。最上方是待办任务卡片往下是四个大宫格入口船舶核查、现场检查、任务中心、我的。宫格按钮设计得很大方便执法人员在颠簸的船上准确点击。点击效果要有手指按下时的反馈不能只有颜色变化最好配合震动wx.vibrateShort船上操作时反馈感才明显。表单页面是个重头。现场检查表单的字段非常多全堆在一个页面滚动起来会很累。我们的方案是用分步表单每一步一个卡片顶部有步骤进度条。第一步选船舶第二步选检查类型第三步填具体检查项第四步拍照定位最后预览提交。每一步的填写内容会自动存本地草稿刷新不丢失。这里有个小坑在 iOS 上当键盘弹起时如果页面底部有提交按钮键盘会遮挡按钮导致没法提交。解决办法是把提交按钮做成浮动在键盘上方监听bindkeyboardheightchange动态调整按钮的 bottom 值。这个小细节不处理的话安卓上没问题iOS 上就会被疯狂吐槽。拍照组件没有用默认的相机样式而是自定义了一个全屏拍摄界面提供“拍摄、重拍、确认”三个按钮更加符合执法流程的确定性。拍摄完成后立刻提示是否继续添加下一张连续拍的体验和微信聊天一样顺手。4.4 本地联调与真机测试开发者工具里能调通的不代表真机没问题这个项目里真机测试是必须的。几个重点测试项列一下弱网测试开发者工具的 Network 面板可以模拟网络延迟和断网但只能模拟2G/3G建议实际拿着手机到水上走一圈特别是过桥底、钻进锚地这些信号死角。相机测试模拟器里相机调用经常失败真机上才能完整跑通拍照-水印-压缩-上传链路。定位测试模拟器的定位是固定的真机上才有漂移问题的复现机会。我们在测试时发现很多点是漂到岸上的后来加了均值滤波才好些。微信开发者工具的“真机调试2.0”模式值得推荐调试时手机上直接看页面布局和数据流效率和纯上真机有质的不同。5. 常见问题与排查技巧实录5.1 高频问题排查表现象可能原因处理方法地图组件白屏未配置合法域名 / 坐标系错误确认地图底图服务域名已加到合法域名列表定位不准轨迹飘逸GCJ02和WGS84坐标系混用固定坐标系并在云函数统一转换图片上传失败原图太大导致超时拍照后先本地压缩宽度缩至1080再传同步数据重复客户端重试导致服务端多次插入每条记录生成唯一消息ID服务端执行幂等检查登录失效token过期 / 清理缓存云函数校验token失效前端自动跳登录页审核被拒类目不符 / 隐私协议缺失按政务类目要求补齐主体资质和隐私保护指引订阅消息收不到用户未重新授权每次使用前提醒并引导一次性订阅5.2 几个不太容易想到的坑第一个是 OCR 识别在强光下的反光问题。船身反光严重时照片里船名字迹泛白识别率直线下降。解决办法是在拍照页做了一个“增强”按钮拍完后先把图片做灰度化对比度增强再送识别。这个增强操作在客户端用 canvas 就能做不需要额外服务器开销。第二个是微信隐私协议权限弹窗。小程序在2023年之后强制要求配置“用户隐私保护指引”如果不配置调用相册、定位、麦克风接口会被直接拦截而且报错提示非常隐晦。开发工具里能看到相关日志但真机上可能完全不显示。这个配置在 mp 后台的“设置-服务内容声明-用户隐私保护指引”里提交填完后还要等审核生效建议提测前就配好别等真机测试才开始。第三个是数据同步的重复问题。这个问题排查了很久才定位到是回执机制缺失。客户端上报数据后如果网络突然断开服务端已经处理了但客户端没收到成功回执重试时就产生了重复数据。后来给每条记录加了唯一ID做幂等同时把“上报成功”的判定从“收到响应”改成“收到携带相同ID的成功响应”问题才彻底解决。第四个是内部分享带来的数据外泄风险。执法数据不能随便转发分享。小程序端做的限制有两层第一所有页面开启disableShare: true禁用转发按钮第二涉及船舶详情、检查记录这些敏感数据即使手动截屏外传了水印里的执法工号和定位坐标能让追溯变得很方便。实际使用中这两层加在一起威慑作用挺明显的。5.3 经验沉淀与后续扩展做完整个项目沉淀下来的几条经验比代码本身更有价值。第一接口先行页面后置。这个项目的数据来源涉及多个既有业务系统船舶底档、证书信息、布控名单都有各自的数据源。如果把页面做完了再对接接口字段对不上改起来就是灾难。建议项目一开始就花时间跟各方确认字段定义和返回格式定义好不轻易改页面实现反而是最简单的一步。第二MVP 缩到最小。第一版我们塞了很多想法包括实时轨迹、视频回传、AI识别等等。后来砍到只剩“船舶核查 检查记录 任务协同”三件事上线后使用率反而最高。工具类应用的价值从来不在功能堆砌而在能不能解决那个最痛的点。第三数据合规从第一天就要想。执法数据涉及大量个人信息数据库的权限规则、操作审计日志、传输加密这三点是不可妥协的底线。后续如果要做大范围推广建议把等保合规要求提前纳入规划而不是功能上线后再补。第四给后续的扩展留好“螺丝孔”。目前这套架构可以比较顺畅地扩展一个“远程复核”模块管理员在后台直接查看现场记录和照片打印PDF归档也可以扩展一个“预警订阅”能力当重点船舶识别出来后自动触发系统值班室提醒。这些小点只要在数据库设计阶段留好字段和状态机后面按部就班加功能就行。最后聊一个实际操作中的感受。这类工具项目最容易犯的错误是从后台管理视角倒推设计管理员想看到一堆统计报表但一线人员只想提前干完活早点回家。所以开发过程中一定要拉着真实使用的人一起测收集“不好用”的反馈比收集“能用”的反馈更有价值。我们的很多改进其实都来自巡逻船上的闲聊——比如把按钮做大的起因就是有人抱怨“船晃起来老点不准”。这类细节说明书上永远写不出来只有在一线待过才知道。水上警务通这个项目到目前的版本算是稳定运行了后续的路还有不少。如果你也在做类似的外勤作业类小程序希望这篇复盘能让你少走两步弯路。 
长河君 · 2026/10/11 3:14:53 · 阅读 1.2k 微信小程序水上警务通设计与实现：从需求到弱网同步落地复盘
项目做完了趁着热乎劲把整个过程好好梳理一下。事情得从一阵子前的对接说起。某水上执法部门的巡逻艇出勤执法人员要靠纸质台账抄船舶信息、拍照片回单位再把资料一点点敲进系统。江面风大船一晃笔迹就歪恶劣天气连字都看不清。当时负责对接的负责人就问了一句能不能用微信小程序把这套流程直接搬到手机上来于是就有了这个“基于微信小程序的水上警务通小程序设计与实现”的项目。这篇文章会把从功能拆解、技术选型到实操落地、踩坑修复的完整过程写出来给正在做移动执法、外勤作业类小程序的团队做个参考。内容偏工程落地不是理论悬浮的那种每一步都有实际场景支撑你抄作业也能抄得明白。1. 为什么是微信小程序场景痛点与选型取舍1.1 水上执法工作流的真实痛点做这类项目第一步不是想技术而是先把业务场景摸透。我跟着一线人员出了几趟船发现水上执法和陆地执法完全是两种节奏。首先网络环境非常不稳定。船在航道中间、锚地、桥区附近手机经常只有一两格信号4G时有时无。而执法记录、船舶核查又恰恰需要联网查数据库。这就决定了系统不能做成纯在线依赖型的必须考虑离线优先的架构。其次工作场景是在船上。甲板湿滑、屏幕沾水、手套操作输入框不宜太多按钮必须够大。很多执法人员年龄偏大打字速度慢能点选的绝不让手输能用语音的绝不靠键盘。再就是数据一致性要求极高。执法记录属于证据性质的材料一条检查记录生成之后不能随意删改后端必须保存完整操作日志。这在设计数据库和接口时就要提前想清楚不是上线之后再打的补丁。还有一点容易被忽略人员的手机型号参差不齐。有的用安卓千元机有的是老款苹果屏幕大小、性能差异很大。小程序的跨端兼容性在这里是实打实的优势一套代码多端跑省掉了很多“机型适配地狱”的麻烦。1.2 几种技术方案的取舍对比当时备选方案有三个原生App、H5网页和微信小程序。我们做了个简单对比基本把选型逻辑说明白了。维度原生AppH5网页微信小程序使用门槛需安装、需更新版本管理麻烦打开即用无安装打开即用免安装扫码直达开发成本高需要iOS、安卓双端相对低但原生能力弱中等一套代码跨平台更新机制应用商店审核周期长随时发布审核较快可灰度发布相机/定位能力强弱浏览器限制多强API完善弱网处理可深度定制受限于浏览器有离线缓存API、网络状态监听账号体系需自建需自建微信生态自带openid体系最终选了微信小程序核心原因有三个。第一执法部门内部已经有微信使用习惯人员不需要额外学习成本。小程序码一发群里面扫一下就能用。第二小程序的API对移动端能力的封装非常完善拍照、录音、定位、地图组件都是现成的比在浏览器上做H5舒服太多。第三更新迭代快改个bug提审发布一天内基本能搞定App动不动就等一周的审核周期在快速迭代期完全不能接受。1.3 微信生态带来的额外优势小程序还有一个隐藏优势是很多人忽略的微信的订阅消息体系。水上执法的任务往往有很强的时效性比如某条船预计几点靠泊、某个锚地需要突击检查。以前用电话通知容易漏、容易忘。用小程序的话任务下发后能通过微信订阅消息推送到执法人员微信上。虽然微信的订阅消息现在被拆成了订阅一次推送一次局限性不小但做内部工具场景基本够用。另外“添加到我的小程序”“浮窗”这类轻量入口也很实用。执法人员常用的功能可以从微信下拉菜单一键调出不需要在手机桌面上找半天图标。当然小程序也不是没有限制。最典型的就是包体积限制。主包不能超过2MB分包总大小限制也卡得比较死所以图片资源必须尽量放云端不要堆在本地。这个问题在后面做技术方案时重点处理。2. 功能设计一线需求如何翻译成模块2.1 核心功能模块清单整个小程序的角色逻辑比较简单就是管理员、普通执法人员和系统后台三类。核心功能模块如下模块面向角色核心能力工作台所有人今日任务、待办数量、快捷入口船舶核查普通执法人员OCR识别船名、按船名查询、历史记录现场检查普通执法人员检查表填写、拍照取证、定位水印、草稿箱任务协同管理员任务下发、状态流转、订阅消息提醒轨迹与签到所有人位置上报、巡逻轨迹记录统计后台管理员按时间/区域统计、报表导出功能听起来不复杂但每个模块背后的细节非常多。下面挑几个重点展开讲讲。2.2 船舶核查模块不只是“输入船名查一下”这个模块看似简单实际上花了不少心思。执法人员在船艇上核查一艘船首要任务就是确认这艘船的身份信息是否真实、证书是否有效。传统方式是拿个本子记船名回单位再查。现在要做到现场实时核查。第一步是识别。船名一般刷在船身两侧字样大小、颜色、底色各不相同。考虑到执法人员可能穿着手套、戴着护目镜让手输船名不现实就做了一个OCR识别功能拍照自动识别船名识别成功后自动发起查询。识别不成功的话再退化为手工输入。我们用的OCR服务是后端接的通用图像识别接口主要是在请求前做预处理——压缩图片、增强对比度船身上的反光对识别率影响很大这是个关键细节。第二步是查询。根据船名或者船舶识别号调用后端接口获取船舶登记信息包括船籍港、船舶类型、所有人、证书有效期、是否在锚地/在航状态等。这些字段是给执法人员快速判断用的最关键的是证书是否过期、船舶是否被布控。所以记录里特别做了“重点检查原因”的打标功能。第三步是历史记录。同一个执法人员对同一艘船可能做过多次检查历史核查记录要能一键带出。这样例行检查时不用重复填写船舶基础信息新人上手也快得多。2.3 现场检查模块表单设计的逻辑现场检查是整个系统里最核心的数据生产模块。执法人员到了现场要把检查结果录入系统。这个模块有两条设计原则非常重要。第一能用选项的绝不用输入框。执法检查表里的字段是有规范枚举值的比如船舶类型、证书状态、违规类别。如果开放手输几个人填出来的格式可能完全不一样后面统计分析就废了。所以全部设计成下拉选项或者复选框输入框只保留了数量、金额、备注这类自由格式字段。第二照片必须现场拍摄不允许从相册选择。这是执法取证的基本要求。用wx.chooseMedia时把source限定为camera照片自动带上时间水印和经纬度水印。水印不是在拍照时加上去的而是在上传前用canvas在客户端合成。这个细节后面在技术章节详细说。检查记录还支持存草稿。为什么要草稿因为江面网络不稳定现场填了一半发现断网了如果直接清空表单执法人员心态就崩了。草稿存在本地 storage 里网络恢复后一键提报体验会好很多。2.4 任务协同与轨迹闭环任务协同这块主要是管理员的日常工作。以前派任务靠电话和对讲机现在系统里直接下发任务单。任务的状态流转设计了几个节点未接收、待执行、执行中、已完成、复核中。每个节点变更都会记录操作人和时间方便后期追溯。订阅消息提醒这里踩过一个细节坑微信的订阅消息是“一次性订阅”用户不主动点“允许”就收不到下一次。所以我们在任务下发的页面里专门做了一个授权引导弹窗提示“订阅一次接收一条通知”虽然体验上有点绕但这是微信平台的规则只能顺着它来。轨迹模块的定位是解决巡逻监管问题的。以前领导不知道巡逻船去哪儿了、去了多久只能靠对讲机汇报。现在小程序可以在后台记录位置上报点形成一个巡逻轨迹。这里有一个取舍持续后台定位会非常耗电所以并没有做成实时上报而是每30秒一次前台定位上报离开页面自动停止。够用且不给手机续航添麻烦。3. 技术架构与实现细节3.1 前后端整体架构选型技术栈这块我直接说结论小程序端用的是原生框架配合Vant Weapp组件库。后端用的是微信云开发云函数 云数据库 云存储。如果团队没接触过云开发这块要稍微解释一下。原生框架的理由是可控性强。小程序本身的WXML/WXSS/JS体系已经够成熟加上原生支持分包、自定义组件做复杂表单页面不至于被框架束缚。第三方框架比如uni-app或者Taro虽然能多端复用但这个场景只需要微信端引入框架反而多一层性能损耗和调试成本。云开发的选择就要多权衡一下。云开发的云函数本质是Node.js环境可以独立部署、独立鉴权不需要自己买服务器、搭Nginx、配HTTPS部署效率非常惊人。对于这种内部应用效率就是生命线。数据库用的JSON文档模型存检查表单这种结构化数据非常顺手。存储就用来放照片、执法录像。但要特别强调一点如果项目涉及敏感执法数据部署环境必须符合所在单位的安全管理规定。我们在设计时预留了接口层后续如果要切换到内部自建服务器只需要替换云函数的实现前端调用层几乎不用动。3.2 数据库设计与权限规则数据库集合我们设计了六个核心集合集合名称主要字段用途usersopenid, 警号, 姓名, 角色, 单位用户身份与权限ships船名, 船舶识别号, 类型, 所有人, 证书状态船舶底档数据missions类型, 对象id, 指派给, 状态, 截止时间任务下发与跟踪records船舶id, 检查类型, 表单内容json, 照片列表, 定位现场检查记录photo_filesfileID, 大小, 上传时间, 关联记录id照片资料归档audit_logs操作人, 操作时间, 操作内容, ip审计日志数据库权限规则这里要重点讲一下。微信云数据库默认的权限模板是“仅创建者可读写”但我们的业务场景是多人共享数据。比如执法人员A提交的检查记录管理员B必须能查看甚至复核。所以不能直接用前端的权限声明来控制而是规定所有集合默认关闭前端直接读写权限统一通过云函数去操作数据。云函数运行在服务端权限不依赖前端用户身份校验逻辑可以自己写。每个云函数里先验证调用者的openid再查users集合确认角色最后才放行。这个模型虽然多写几行代码但安全性裸奔的坑算是彻底避开了。3.3 离线缓存与弱网同步核心难点这个模块是整个项目里我最想展开讲的。水上场景网络不稳定意味着系统必须具备离线可用能力。方案用的是“本地优先 队列同步”的模式。核心思路是三步。第一步写请求之前先检查网络状态。用wx.getNetworkType判断网络类型如果完全无网络直接把记录写入本地待同步队列。如果网络正常不直接发请求而是把记录写入本地队列然后由同步器统一上报。这个设计的本质是所有写操作都先落本地不会因为网络瞬间抖动就丢数据。第二步网络恢复自动触发同步。小程序有wx.onNetworkStatusChange监听网络切换事件一旦网络恢复立刻调用同步器把待同步队列里的数据逐个上报。上报成功的记录从队列移除失败的重试次数加一超过三次标记为“同步失败”并保留在队列里等下次网络变化再试。第三步上传要做幂等设计。弱网环境下最容易出现的问题是请求超时后重试服务端已经处理了但客户端以为失败又发一次导致重复数据。解决办法是在记录生成时就生成一个32位的唯一 messageId服务端用来查重。收到请求先从日志表查这个messageId是否存在存在就直接返回成功不存在才落库。图片的离线处理比结构化数据更麻烦。我的做法是现场拍完照片立刻在本地做压缩生成一个宽度1080的缩略图然后立即把照片原始文件和缩略图都存进本地临时目录。同步的时候优先传缩略图保证记录可用原图走后台慢慢传。这样即使原图因为网络传不上来检查记录的正文内容已经完整了原图可以等网络好再补传。3.4 地图定位与照片水印的处理定位模块有两个技术点很容易踩坑。第一个是坐标系问题。微信小程序的wx.getLocation返回的是GCJ02坐标系而很多后端GIS系统用的是WGS84坐标系两套坐标之间有几米到几十米的偏差。你在水上漂着看可能觉得无所谓但做轨迹回放和数据入库时汇总到地图上就会发现轨迹整体偏移到岸上去了。所以后端接口要统一约定如果是外部地图底图直接存GCJ02如果是内部GIS必须在云函数里做一次坐标转换。第二个是水上定位漂移问题。GPS在水域受到反射和遮挡概率更高单次定位点经常跳来跳去。我们做了一个简单但好用的滤波逻辑连续采集5个定位点去掉最大和最小偏差的点取剩下的中间三个点的平均值作为上报的坐标。实测下来轨迹平滑度提升明显。水印照片是合规要求。实现方式是拍照后用canvas把原始图片画到底图上然后叠加绘制当前时间、经纬度坐标、执法人员工号三行文字最后把canvas导出成临时文件再上传。这个方案的好处是水印直接烧进像素里防止事后修改和抵赖。代码上只需要二十几行canvas绘制逻辑但价值非常大。// 照片水印合成示例 const drawWatermark async (tempFilePath, locationText, officerNo) { const ctx wx.createCanvasContext(watermarkCanvas); const img await getImageInfo(tempFilePath); // 按原图尺寸设置画布 ctx.setCanvasSize(img.width, img.height); ctx.drawImage(tempFilePath, 0, 0, img.width, img.height); // 绘制定位信息水印 ctx.setFillStyle(rgba(255, 255, 255, 0.8)); ctx.setFontSize(14); ctx.fillText(new Date().toLocaleString(), 10, img.height - 60); ctx.fillText(locationText, 10, img.height - 38); ctx.fillText(执法工号 officerNo, 10, img.height - 16); ctx.draw(false, () { wx.canvasToTempFilePath({ canvasId: watermarkCanvas, success: (res) { // res.tempFilePath 即为带水印的图片 } }); }); };4. 从零到上线的全流程实操复盘4.1 项目初始化与环境准备第一步是小程序账号注册。这里有个容易忽略的点如果是内部工具不一定要急着走公开上架流程。我们的做法是先注册一个小程序账号添加“体验成员”和“开发成员”用微信开发者工具生成小程序码内部扫码就能进入“体验版”整个灰度测试期间可以不对外提审发布效率高不少。政务类小程序涉及类目资质要求比较严格正式上架前必须准备好主体资质文件。如果暂时没有体验版阶段完全够用。第二步是代码工程初始化。原生小程序的目录结构我习惯这样组织miniprogram/ pages/ # 页面 components/ # 自定义组件 utils/ # 工具函数 api/ # 接口封装 store/ # 全局状态 cloudfunctions/ # 云函数目录App配置里要把“权限说明”提前写好特别是定位权限的文案。微信要求不能默认申请所有权限只在需要时弹出的用户提示里说明用途。这个文案写得好不好直接关系到审核通过率和用户信任度。{ permission: { scope.userLocation: { desc: 你的位置信息将用于记录执法位置和生成巡逻轨迹 } } }4.2 登录鉴权与身份绑定登录逻辑是这样的打开小程序先wx.login拿到code传给云函数云函数调用微信接口换取openid。换取成功后根据自己的业务表生成一个自定义token存到本地 storage后续所有请求都带上这个token。这里有个比较容易忽视的安全点不能在前端直接使用openid作为身份标识。因为小程序的运行环境可以被逆向分析openid被拿到了就可以伪造数据。正确做法是openid只在云函数内部识别用对外只暴露随机token服务端根据token查users集合判断当前用户身份和权限。身份绑定这块因为是小范围内部使用管理员在后台可以直接把某用户的小程序openid和他的警号做绑定。绑定的前提是上报警号姓名单位管理员审核通过后就激活账号。被拒绝或者未审核的openid调用任何云函数都返回“未授权”。// 云函数登录示例 exports.main async (event, context) { const { code } event; const result await cloud.openapi.auth.code2Session({ code }); const openid result.openid; // 查询用户表 const db cloud.database(); const userRes await db.collection(users).where({ openid }).get(); if (userRes.data.length 0) { return { code: 403, message: 账号未激活请联系管理员 }; } // 生成token并返回 const token generateToken(openid); await db.collection(users).doc(userRes.data[0]._id).update({ data: { lastToken: token, lastLogin: Date.now() } }); return { code: 0, data: { token, userInfo: userRes.data[0] } }; };4.3 核心页面与组件实现首页工作台是工具箱式的布局。最上方是待办任务卡片往下是四个大宫格入口船舶核查、现场检查、任务中心、我的。宫格按钮设计得很大方便执法人员在颠簸的船上准确点击。点击效果要有手指按下时的反馈不能只有颜色变化最好配合震动wx.vibrateShort船上操作时反馈感才明显。表单页面是个重头。现场检查表单的字段非常多全堆在一个页面滚动起来会很累。我们的方案是用分步表单每一步一个卡片顶部有步骤进度条。第一步选船舶第二步选检查类型第三步填具体检查项第四步拍照定位最后预览提交。每一步的填写内容会自动存本地草稿刷新不丢失。这里有个小坑在 iOS 上当键盘弹起时如果页面底部有提交按钮键盘会遮挡按钮导致没法提交。解决办法是把提交按钮做成浮动在键盘上方监听bindkeyboardheightchange动态调整按钮的 bottom 值。这个小细节不处理的话安卓上没问题iOS 上就会被疯狂吐槽。拍照组件没有用默认的相机样式而是自定义了一个全屏拍摄界面提供“拍摄、重拍、确认”三个按钮更加符合执法流程的确定性。拍摄完成后立刻提示是否继续添加下一张连续拍的体验和微信聊天一样顺手。4.4 本地联调与真机测试开发者工具里能调通的不代表真机没问题这个项目里真机测试是必须的。几个重点测试项列一下弱网测试开发者工具的 Network 面板可以模拟网络延迟和断网但只能模拟2G/3G建议实际拿着手机到水上走一圈特别是过桥底、钻进锚地这些信号死角。相机测试模拟器里相机调用经常失败真机上才能完整跑通拍照-水印-压缩-上传链路。定位测试模拟器的定位是固定的真机上才有漂移问题的复现机会。我们在测试时发现很多点是漂到岸上的后来加了均值滤波才好些。微信开发者工具的“真机调试2.0”模式值得推荐调试时手机上直接看页面布局和数据流效率和纯上真机有质的不同。5. 常见问题与排查技巧实录5.1 高频问题排查表现象可能原因处理方法地图组件白屏未配置合法域名 / 坐标系错误确认地图底图服务域名已加到合法域名列表定位不准轨迹飘逸GCJ02和WGS84坐标系混用固定坐标系并在云函数统一转换图片上传失败原图太大导致超时拍照后先本地压缩宽度缩至1080再传同步数据重复客户端重试导致服务端多次插入每条记录生成唯一消息ID服务端执行幂等检查登录失效token过期 / 清理缓存云函数校验token失效前端自动跳登录页审核被拒类目不符 / 隐私协议缺失按政务类目要求补齐主体资质和隐私保护指引订阅消息收不到用户未重新授权每次使用前提醒并引导一次性订阅5.2 几个不太容易想到的坑第一个是 OCR 识别在强光下的反光问题。船身反光严重时照片里船名字迹泛白识别率直线下降。解决办法是在拍照页做了一个“增强”按钮拍完后先把图片做灰度化对比度增强再送识别。这个增强操作在客户端用 canvas 就能做不需要额外服务器开销。第二个是微信隐私协议权限弹窗。小程序在2023年之后强制要求配置“用户隐私保护指引”如果不配置调用相册、定位、麦克风接口会被直接拦截而且报错提示非常隐晦。开发工具里能看到相关日志但真机上可能完全不显示。这个配置在 mp 后台的“设置-服务内容声明-用户隐私保护指引”里提交填完后还要等审核生效建议提测前就配好别等真机测试才开始。第三个是数据同步的重复问题。这个问题排查了很久才定位到是回执机制缺失。客户端上报数据后如果网络突然断开服务端已经处理了但客户端没收到成功回执重试时就产生了重复数据。后来给每条记录加了唯一ID做幂等同时把“上报成功”的判定从“收到响应”改成“收到携带相同ID的成功响应”问题才彻底解决。第四个是内部分享带来的数据外泄风险。执法数据不能随便转发分享。小程序端做的限制有两层第一所有页面开启disableShare: true禁用转发按钮第二涉及船舶详情、检查记录这些敏感数据即使手动截屏外传了水印里的执法工号和定位坐标能让追溯变得很方便。实际使用中这两层加在一起威慑作用挺明显的。5.3 经验沉淀与后续扩展做完整个项目沉淀下来的几条经验比代码本身更有价值。第一接口先行页面后置。这个项目的数据来源涉及多个既有业务系统船舶底档、证书信息、布控名单都有各自的数据源。如果把页面做完了再对接接口字段对不上改起来就是灾难。建议项目一开始就花时间跟各方确认字段定义和返回格式定义好不轻易改页面实现反而是最简单的一步。第二MVP 缩到最小。第一版我们塞了很多想法包括实时轨迹、视频回传、AI识别等等。后来砍到只剩“船舶核查 检查记录 任务协同”三件事上线后使用率反而最高。工具类应用的价值从来不在功能堆砌而在能不能解决那个最痛的点。第三数据合规从第一天就要想。执法数据涉及大量个人信息数据库的权限规则、操作审计日志、传输加密这三点是不可妥协的底线。后续如果要做大范围推广建议把等保合规要求提前纳入规划而不是功能上线后再补。第四给后续的扩展留好“螺丝孔”。目前这套架构可以比较顺畅地扩展一个“远程复核”模块管理员在后台直接查看现场记录和照片打印PDF归档也可以扩展一个“预警订阅”能力当重点船舶识别出来后自动触发系统值班室提醒。这些小点只要在数据库设计阶段留好字段和状态机后面按部就班加功能就行。最后聊一个实际操作中的感受。这类工具项目最容易犯的错误是从后台管理视角倒推设计管理员想看到一堆统计报表但一线人员只想提前干完活早点回家。所以开发过程中一定要拉着真实使用的人一起测收集“不好用”的反馈比收集“能用”的反馈更有价值。我们的很多改进其实都来自巡逻船上的闲聊——比如把按钮做大的起因就是有人抱怨“船晃起来老点不准”。这类细节说明书上永远写不出来只有在一线待过才知道。水上警务通这个项目到目前的版本算是稳定运行了后续的路还有不少。如果你也在做类似的外勤作业类小程序希望这篇复盘能让你少走两步弯路。