接到“基于微信小程序的远程在线诊疗系统”这个项目需求时我的第一反应不是急着打开HBuilderX而是先问自己一个问题这套系统和平时做的商城、点餐小程序到底差在哪里做过之后才彻底明白医疗类小程序的核心不在页面多好看而在状态机、数据安全、支付回调、合规审核这几条隐藏链路。图文问诊、视频问诊、预约挂号、电子处方、在线支付这些模块拆开后任何一个环节按普通CRUD方式处理后期都会翻车。这篇博文就围绕整套系统从需求拆解、技术选型、核心模块实现到上线审核的完整过程来写把可以直接抄作业的方案和踩过的坑一起整理出来。如果你正准备做医疗/健康类小程序或者毕业设计选了同类题目这篇文章应该能帮你少走大半年弯路。1. 项目整体定位远程诊疗小程序到底在解决什么问题1.1 从“挂号两小时”到“线上复诊三分钟”的真实需求做这个项目之前我花了两周时间去线下门诊蹲点观察。发现一个非常现实的问题复诊患者占了门诊量很大比例他们当中很多人只是需要让医生看一眼检查报告、调整一下用药方案却要专门请半天假、排队两小时。另一边医生的碎片时间没有被利用起来门诊结束后大量时间处于空闲状态。远程在线诊疗系统要做的就是把“轻问诊”“复诊随访”“预约挂号”“药品配送”这四类高频需求搬上微信小程序。患者端不需要下载App微信扫码或搜索就能进入医生端可以在手机上利用碎片时间接诊平台端统一管理问诊单、处方、支付和物流状态。它解决的痛点是三端的患者复诊不用反复跑医院图文/视频沟通成本更低药品可以直接配送到家。医生碎片时间自由接诊问诊记录结构化留存避免“上午看完下午就忘”。平台/医院释放线下门诊压力把复诊人群导流到线上沉淀患者健康档案。这里要特别提醒一句如果是课程设计或者演示项目建议把“电子处方”改成“健康建议”。因为真正的在线开处方需要互联网医院资质个人开发者和小型团队根本拿不到。后面我会在合规章节详细展开这条红线千万别踩。1.2 三端角色与业务模块的两层拆分整个系统按“患者端、医生端、管理端”三角色划分对应小程序用户端、医生工作台、PC管理后台三个前端。业务模块我拆成四层问诊层、支付层、药品层、数据层。患者端的核心功能包括微信授权登录、图文问诊、视频问诊、预约挂号、问诊记录查询、药品订单跟踪、健康档案查看。医生端要能设置在线状态、接诊/拒绝问诊、查看患者历史记录、回复图文消息、发起视频通话、填写接诊小结。管理端负责医生资质审核、科室维护、问诊单监控、异常订单退款、数据统计。这四层里最容易做乱的是问诊层和支付层的交叉。一个问诊单既要走“医生接诊状态”又要走“订单支付状态”两条状态线如果没有解耦后面会出现“医生已经开完建议但订单还显示待支付”这种诡异情况。我的做法是把问诊流程状态和资金状态分开存储分别用两个字段控制只有问诊流程走到“待支付药品费”时才去联动资金状态。1.3 一个问诊单的完整生命周期设计核心业务流程我反复画了五版才算理清楚。最完整的链路是这样的患者选择科室和医生确认图文或视频问诊方式创建问诊单并支付咨询费。支付成功后进入“待接诊”池医生端能看到排队列表。医生点击接诊状态变为“问诊中”双方通过IM或视频沟通。沟通结束医生填写问诊小结如果是合规持证机构可以开具电子处方/健康建议状态变为“待患者确认”。患者确认后如果需要用药系统生成药品清单并引导支付药费。支付完成后进入“配药发货”最后完成订单。对应到代码层面我设计了一个问诊单状态枚举public enum ConsultStatus { UNPAID(0, 待支付), WAIT_ACCEPT(1, 待接诊), CONSULTING(2, 问诊中), WAIT_CONFIRM(3, 待患者确认), FINISHED(4, 已完成), CANCELLED(5, 已取消), REFUNDING(6, 退款中); private final int code; private final String desc; ConsultStatus(int code, String desc) { this.code code; this.desc desc; } }这里要注意状态流转一定要校验“当前状态是否合法”。比如只有FINISHED状态的订单才能申请退款只有UNPAID状态才能取消。我见过很多半路出家的代码不校验就直接UPDATE结果线上出现“已取消的订单还能被医生接诊”这种事故。2. 技术选型为什么坚持用uniapp做前端、Java做后端2.1 uniapp与原生小程序、Android/iOS、鸿蒙的对比“微信小程序 vs Android/iOS/鸿蒙”这个问题是我在立项时第一个面对的。最终选择uniapp核心原因不是它跑得最快而是成本结构太划算了。传统方案下如果目标是同时覆盖微信小程序、Android App、iOS App、鸿蒙应用原生开发意味着至少三到四套代码。医疗类项目业务逻辑复杂前端界面其实相对标准化没有特别极致的性能要求。用uniapp的Vue语法写一套代码可以同时编译到微信小程序端、H5端和App端鸿蒙端也有对应的适配方向后期扩展成本明显更低。对比维度可以看这个表维度uniapp微信原生小程序Android/iOS原生跨端能力微信小程序/H5/App多端仅微信小程序仅单端开发效率一套代码多端运行需要独立维护多端各自开发性能常规场景够用最优最优学习门槛会Vue即可需要额外学WXML/WXSS需要学Java/Kotlin/Swift生态uni_modules插件丰富微信生态组件最多原生SDK最强但uniapp有一个坑必须提前说它和原生小程序在部分API上是“同名不同行为”。比如chooseAvatar、getPhoneNumber这些隐私接口在uniapp里需要通过条件编译或者调用uni原生API去适配。我在开发中就遇到过“H5端能拿手机号小程序端死活拿不到”的情况最后定位是API调用方式不对。所以架构设计时要把平台差异封装成一层适配器而不是直接在页面里写平台API。2.2 后端与基础设施选型后端我选的Spring Boot MyBatis-Plus MySQL Redis RabbitMQ WebSocket这套组合。没有上微服务因为项目规模用微服务反而增加部署复杂度。单体应用配合合理的模块划分一套代码走天下够用。Redis在这里不是摆设我用来做三件事一是存微信access_token和定时刷新二是存问诊单的防重提交标记避免用户双击造成重复订单三是缓存科室列表、医生排班等低频变更数据减轻数据库压力。文件存储用的对象存储我用的腾讯云COS病历图片、检查报告、聊天图片都走独立上传接口返回fileId给前端。视频问诊因为微信小程序原生视频能力限制我采用的是H5内嵌方案后面会详细讲。基础设施方面最值得强调的是环境隔离。医疗项目最怕的是“开发环境把测试患者数据发到了生产手机号上”。我强制拆成三套环境开发、测试、生产小程序端通过打包时注入的环境变量切换域名数据库物理隔离账号体系隔离。这个操作虽然前期麻烦一点但上线后省了至少十倍的心力。2.3 6个接口请求封装被问最多的就这一个“微信小程序请求封装”这个话题在开发群里几乎每天都有人问。我封装的request模块核心就三个能力统一注入token、统一处理错误、防止登录过期出现并发风暴。// utils/request.js import { useUserStore } from /stores/user const BASE_URL https://api.example.com const request (options) { return new Promise((resolve, reject) { const userStore useUserStore() uni.request({ url: BASE_URL options.url, method: options.method || GET, data: options.data || {}, header: { Content-Type: application/json, Authorization: Bearer ${userStore.token || } }, success: (res) { // 业务约定code为0成功token过期码为401 if (res.data.code 0) { resolve(res.data) } else if (res.data.code 401) { // 刷新token重放请求 refreshTokenAndRetry(options).then(resolve).catch(reject) } else { uni.showToast({ title: res.data.msg, icon: none }) reject(res.data) } }, fail: (err) { // 网络异常统一提示 uni.showToast({ title: 网络异常请稍后重试, icon: none }) reject(err) } }) }) }这里有个很容易踩的坑如果多个接口同时返回401就会触发多个刷新token的请求造成“token刷新风暴”。我的解决方式是用一个Promise队列做并发合并第一个401触发刷新后续401等待同一个刷新结果let refreshPromise null function refreshTokenAndRetry(options) { if (!refreshPromise) { refreshPromise refreshTokenRequest() .finally(() { refreshPromise null }) } return refreshPromise.then(() request(options)) }这个细节不处理好用户登录状态过期那一刻页面会连续弹十几个错误toast体验非常糟糕。3. 核心功能模块的实操实现3.1 微信登录、手机号授权与隐私声明微信小程序的登录链路和其他App不一样它不是直接输入账号密码而是通过uni.login拿到code传给后端code2Session接口换openid。我封装好的登录逻辑长这样uni.login({ provider: weixin, success: async (res) { const code res.code const loginRes await request({ url: /user/login, method: POST, data: { code } }) userStore.token loginRes.data.token userStore.userInfo loginRes.data.userInfo } })手机号授权这里特别留意。从微信新版基础库开始getPhoneNumber返回的不再是encryptedData和iv而是一个动态令牌code。后端需要拿这个code去调用微信接口换取真实手机号。这意味着前端拿不到任何明文手机号隐私安全性提高了很多。uni.getPhoneNumber({ success: (res) { // res.code 是动态令牌发给后端换取手机号 request({ url: /user/bind-phone, method: POST, data: { phoneCode: res.code } }) } })这种设计带来的问题是如果后端没有正确配置微信开放平台的AppSecret权限换号码会直接失败。还经常遇到chooseAvatar:fail api scope is not declared in the private info这个报错解法是在app.json里声明{ requiredPrivateInfos: [chooseAvatar, chooseLocation, getPhoneNumber] }同时在小程序管理后台的“用户隐私保护指引”里逐项声明收集这些信息的目的。授权弹窗的逻辑也建议用自己的自定义弹窗不要直接用微信默认的因为默认弹窗文案不能自定义用户拒绝的概率会更高。3.2 图文问诊IM消息列表设计与附件上传图文问诊聊天界面是患者感知最直接的模块。实现方式我当时纠结过到底用WebSocket长连接还是用轮询我调研了几套现成IM方案比如腾讯云IM、环信功能很强但对这个项目来说引入一个完整IM系统会让代码复杂度直接翻倍。考虑到问诊场景不是高频实时聊天消息频率远低于普通客服场景我用的是“WebSocket兜底 HTTP拉取历史消息”的混合方案。具体做法是问诊进行中时用WebSocket推送新消息医生回复、系统提示客户端收到推送后刷新消息列表。进入页面时先用HTTP分页拉取最近20条历史消息上滑加载更早记录。文件消息单独处理图片/报告通过上传接口返回fileId消息列表只存fileId展示时再拼CDN地址。聊天数据表设计我放在消息主表和附件表两张表里CREATE TABLE consult_message ( id BIGINT AUTO_INCREMENT PRIMARY KEY, consult_order_id BIGINT NOT NULL, sender_type TINYINT NOT NULL COMMENT 0患者 1医生 2系统, sender_id BIGINT NOT NULL, content_type TINYINT NOT NULL COMMENT 1文本 2图片 3语音 4系统提示, content TEXT, is_read TINYINT DEFAULT 0, create_time DATETIME NOT NULL, KEY idx_order_time (consult_order_id, create_time) ); CREATE TABLE consult_message_attachment ( id BIGINT AUTO_INCREMENT PRIMARY KEY, message_id BIGINT NOT NULL, file_url VARCHAR(500) NOT NULL, file_type TINYINT NOT NULL COMMENT 1图片 2报告文件 );为什么分成两张表因为消息列表页不需要附件字段拉历史消息时JOIN附件表会让简单查询变复杂。分开后主表保持轻量附件通过messageId关联查询逻辑更清晰。3.3 视频问诊微信小程序视频能力边界与H5接入方案微信原生小程序做视频通话是比较尴尬的。小程序的live-pusher和live-player组件能实现直播场景但做一对一实时音视频通话信令控制、音视频编码、弱网切换这些都要自己负责成本非常高。我当时果断选择了“web-view内嵌H5视频问诊”的方案。服务端接入腾讯实时音视频TRTC的Web SDKH5页面负责音视频采集和通话小程序端通过web-view组件加载对应的问诊房间链接。核心流程是医生端点击“开始视频通话”后端创建房间并生成带鉴权的URL患者端收到状态变更通知打开web-view进入房间。这个方案有两个坑要讲清楚。第一个是web-view组件必须配置业务域名意味着你得先在小程序后台把H5所在的域名加到业务域名列表并且校验文件要放在服务器根目录。第二个是iOS上web-view内置浏览器对摄像头授权方式不同首次进入会出现“无法访问摄像头”的弹窗需要在H5里做显式授权引导。如果预算紧张还有更轻量级的过渡方案预约视频时间然后用微信自带的“微信通话”能力小程序里只负责展示预约状态和提醒。对早期项目验证需求来说这个方案成本最低体验也不算差。3.4 微信支付、退款与回调幂等的完整处理支付模块我放在了问诊流程的后半段。用户创建问诊单后先支付咨询费医生回复后如产生药品或报告打印费用再走药品支付环节。小程序端支付用的是微信支付JSAPI先请求后端统一下单接口拿到支付参数后调uni.requestPaymentconst paymentRes await request({ url: /pay/create, method: POST, data: { orderId } }) uni.requestPayment({ provider: wxpay, timeStamp: paymentRes.data.timeStamp, nonceStr: paymentRes.data.nonceStr, package: paymentRes.data.package, signType: RSA, paySign: paymentRes.data.paySign, success: () { console.log(支付成功) }, fail: (err) { console.log(支付失败, err) } })这里最核心的是后端回调处理。微信异步通知可能因为网络原因重复推送同一个回调事件到达多次所以回调接口必须实现“幂等”也就是无论收到多少次通知结果都一样。我的回调处理逻辑是先验签再用微信回调的transaction_id查库如果订单已经处理过就直接返回成功不再重复更新状态只有第一次处理时才修改订单状态、触发后续流程。同时判断回调金额和订单金额是否一致防止篡改。退款我用的微信支付的退款API。这里有个有效提醒退款最好在管理后台走人工触发不要用户点一下就自动发起退款容易产生资损纠纷。人工审核可以确认医生是否已经完成服务、药品是否已发货情况明确后再执行退款操作。3.5 消息订阅通知问诊状态变更的推送实现小程序不能像App一样推送任意通知只能通过订阅消息。我在两个关键节点做了订阅消息引导一是用户支付问诊单后引导订阅“医生接诊通知”和“问诊状态变更通知”用于告知医生已接诊。二是药品支付后引导订阅“订单配送状态通知”用于告知物流节点。wx.requestSubscribeMessage({ tmplIds: [模板ID1, 模板ID2], success: (res) { // res[模板ID1] accept 表示同意订阅 } })订阅消息有个限制一次性订阅消息只能发送一条用户订阅一次就只能收到一次推送。所以在设计上要把通知合并一次订阅尽量触发一次聚合消息比如“您的问诊单已完成医生已出具健康建议点击查看详情”把状态变更和结果一次性推送清楚。3.6 uni-app与地图选点坐标系统的坑如果要做“选择附近药店”或者“填写收货地址”会用到地图选点。uni.chooseLocation在小程序端调用的是腾讯位置服务返回的坐标是GCJ-02坐标系火星坐标系。这个坐标直接用于微信内置地图没有任何问题但如果你在后端接入了高德地图、天地图或自绘地图会存在坐标偏移。有一次多端适配时H5端我用天地图展示药店位置结果小程序端传过去的坐标在地图上偏移了几百米。原因就是天地图用WGS-84坐标系而小程序返回的是GCJ-02。处理方式是在后端或者前端做一次坐标转换转成目标坐标系后再展示function gcj02ToWgs84(lng, lat) { const a 6378245.0 const ee 0.006693421622965943 let dlat transformLat(lng - 105.0, lat - 35.0) let dlng transformLng(lng - 105.0, lat - 35.0) // 具体转换逻辑参考坐标系转换标准算法 // ... return { lng, lat } }这个坑不遇到一次永远不会意识到。做跨端项目时一定要在接口文档里统一标注坐标体系避免前端传一个坐标、后端按另一个坐标系理解最后地图上全是乱飞的点。4. 上线发布与合规避坑医疗类小程序的生死线4.1 类目选择、资质材料与年审微信小程序不是注册完就能上线的医疗健康类目有严格的审核要求。这里是最容易卡住项目的地方很多团队代码写完才发现类目申请不下来整个项目直接泡汤。核心逻辑是这样的如果你的服务涉及在线诊疗、预约挂号、电子处方小程序类目必须对应“医疗”下的相关类目并且需要提供对应的资质文件比如《医疗机构执业许可证》或者互联网医院资质。个人主体小程序不能申请医疗类目必须是企业或机构主体。如果你没有医疗机构资质能申请的是“健康咨询”类目提供服务边界是健康相关咨询服务不能在文案中出现“在线诊断”“开具处方”“治疗疾病”等字眼。我的建议是演示项目或毕业设计全部用“健康咨询建议”代替“电子处方”并明确标注“本服务不构成诊疗行为”。不要为了功能好看去冒这个风险。微信小程序的认证有效期是一年到期前需要年审。同时医疗类资质证书本身也有有效期年审时会校验证照状态。我踩过的坑是资质证书在年审前三天到期导致小程序被暂停服务所以建议在服务器或者手机日历上设置“资质到期前90天”的提醒。4.2 隐私接口、用户协议与数据安全这一块和审核关系很大。新版微信小程序对隐私数据管理非常严格设置路径有两层一是代码里的requiredPrivateInfos声明二是小程序管理后台的“用户隐私保护指引”两者必须一一对应收集手机号、地理位置、存储权限每一项都要写清楚用途。患者上传的病历图片、检查报告属于敏感医疗数据要特别注意两个点存储端文件要设置访问控制不能是什么权限都公开的链接传输过程必须走HTTPS不用HTTP明文流量。我的方案是对象存储开启私有读写后端在需要返回图片URL时生成临时签名链接有效期设置十分钟。这样外部即使拿到链接过期后也访问不了。患者隐私协议文本我建议除了平台通用协议外增加一个医疗数据专项说明明确“用户上传的检查报告、病史信息仅用于本次问诊服务平台不得用于其他商业用途”。虽然多写一段但审核通过概率明显更高也更能让患者信任。4.3 域名、业务域名与H5唤起限制小程序所有网络请求的域名都必须配置在后台的服务器域名白名单里而且必须是HTTPS、经过ICP备案的域名。分三类配置request合法域名接口域名、uploadFile合法域名上传文件域名、downloadFile合法域名下载文件域名。web-view组件使用的H5页面域名要单独配置到“业务域名”里。配置业务域名时需要下载校验文件并放到服务器根目录。这里有一个容易出错的操作校验文件如果放在了子目录而不是域名根目录配置会一直失败而且报错信息很不明确一度让我以为是网络问题。另外如果你想在普通H5网页里直接唤起微信小程序需要先生成URL Link或者URL Scheme并进行用户行为路径配置。没有配置的链接在微信内打开会直接提示“已停止访问该网页”。这是微信平台的安全策略不要试图绕过遵平台规则即可。5. 常见问题排查与实战笔记5.1 iOS端网络请求失败率高报错6001怎么追上线后最让人头疼的事来了。后端日志显示Android端一切正常iOS端的接口失败率却异常升高报错码6001。这个报错不是业务错误而是小程序端网络层错误通常指向安全连接建立失败。排查询问结论是证书链不完整。iOS对证书链校验比Android严格如果HTTPS证书没有在Nginx上正确配置证书链只有叶证书而没有中间证书Android可能不报错iOS直接握手失败。排查方式可以用SSLLabs在线检测也可以直接在iOS Safari打开接口地址看浏览器是否提示证书错误。第二个可能的坑是TLS版本。微信小程序在iOS上要求TLS1.2及以上如果你的Nginx配置还是老旧的TLSv1.0也会出现偶发失败。解决办法是server { listen 443 ssl; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256; }还要留意网络环境差异。iOS设备在IPv6网络下访问只有IPv4的服务器或者反过来都会出现请求失败。排查方法是在不同网络环境反复测试定位是不是特定网络下才触发。5.2 头像选择、位置选择等隐私接口报错排查chooseAvatar:fail api scope is not declared in the private info这个问题我在开发群见到频率很高。原因有两种代码里没有在app.json的requiredPrivateInfos中声明对应接口或者后台“用户隐私保护指引”里没有同步勾选对应权限。这个报错的“药方”已经写在第3.1节了声明私有接口的四件套app.json 里配置 requiredPrivateInfos小程序后台配置用户隐私保护指引启动时弹出隐私授权弹窗用户确认后再调接口云开发项目还要检查有没有使用云调用等价接口另外头像授权还涉及一个认知陷阱现在button组件上的chooseAvatar已经不是权限弹窗而是用户主动点击头像选择器后小程序才会把临时路径回调给前端。它不是像以前那样先弹窗询问“是否允许使用头像”。明白这个交互逻辑调试起来会顺畅很多。5.3 用抓包工具排查接口异常数据的正确姿势开发阶段经常需要查看小程序发出的实际请求内容比如参数格式、返回结构、签名结果是否正确。我做接口联调时通常优先用微信开发者工具自带的Network面板它最直接不需要额外操作。线上问题排查时客户端不好复现我会用Charles或Fiddler这类抓包工具来辅助分析。基本原理是配置本机代理让小程序流量经过抓包工具转发同时在工具里配置HTTPS证书进行解密查看。这里必须提醒抓包工具只能在你自己的开发环境里调试自己的小程序绝对不能用于抓取他人的应用数据也不能依赖抓包绕过或破解任何安全机制。技术工具是用于正常开发的越遵守规则路越宽。5.4 小程序包体积优化与首屏加载速度医疗类小程序功能多页面数轻松可以达到六七十个很容易触碰主包2M、总包20M的限制。我的优化方案一是分主体配置分包。把用户端、医生端、药品商城拆成三个分包主包只保留首页、登录、公共组件和工具库。分包加载是按需加载的用户进入时只加载主包和当前分包加载速度明显提升。二是静态资源全面CDN化。图片、图标、科室背景图不放在本地全部上传到对象存储走CDN链路。本地只保留tabBar图标这类必须的素材。三是对低频页面做分包预下载。用wx.preloadSubpackage对用户大概率会进入的分包进行预加载比如用户在首页浏览医生列表时后台提前把问诊详情分包下载好点进去就没有白屏等待。5.5 自定义顶部导航栏高度的踩坑记录热词里 “微信小程序顶部导航栏高度” 出现频率很高这里也记录一下。如果你要自定义导航栏将navigationStyle改为customiPhoneX以后的机型底部有home indicator顶部有刘海屏安全区不同机型状态栏高度不同如果写死一个固定值测试机上看很正常换几台手机就变形。推荐写法是运行时动态获取uni.getSystemInfo({ success: (res) { const statusBarHeight res.statusBarHeight // 胶囊按钮位置由 res.capsule 提供导航栏高度 胶囊高度 上下间距 const menuButtonHeight res.menuButtonHeight } })然后再根据胶囊按钮的顶部位置计算导航栏的整体高度。这套逻辑后来我抽成了公共样式变量保证所有自定义页面的顶部布局在不同机型上一致。写在最后的一点个人经验回头再看这个项目最值钱的部分不是那些功能页面而是问诊单状态机、支付回调幂等、合规资质这些看不见的底层设计。把这些地基打牢后面加功能其实很快。如果只埋头写页面结果就是demo跑得欢一上线全完蛋。最后再分享一个我自己的体会医疗类项目要想清楚“哪些东西可以简配”。IM聊天我用的是WebSocket加HTTP拉取视频问诊直接内嵌H5没有一开始就上完整IM和音视频SDK。先用简单方案跑通闭环等用户量起来再评估要不要升级重型方案。这个节奏我个人觉得最适合团队不大、资源紧张的医疗类小程序项目。