去年帮本地一家社区诊所做了一套在线医生预约挂号答疑系统前端用微信小程序后端用 Python 搭。从需求对接到上线前后断断续续做了两个多月中间踩了不少坑微信支付 v3 的回调验签、小程序顶部导航栏在不同机型上的高度适配、软键盘把查询结果顶出屏幕还有上线前域名备案的等待期。今天把整套系统的开发过程完整梳理一遍。如果你也在做医疗预约类的小程序或者想了解微信小程序 Python 这个技术组合怎么从零落地这篇内容应该能帮你省掉不少试错时间。这套系统的核心流程其实很明确患者在小程序里查看医生排班、选择时间段预约、在线支付挂号费就诊后再通过答疑板块向医生提问医生在小程序端或管理后台回复。听起来不复杂但真正动起手来数据模型怎么设计、支付回调怎么验签、消息通知怎么发送、类目审核怎么过每一块都有各自的隐藏坑。下面我就按从设计到上线的完整顺序把关键环节逐个拆开讲。1. 这个项目到底在解决什么预约挂号与在线答疑的真实场景1.1 线下挂号的痛点与线上预约的价值社区诊所的挂号场景和大型三甲医院不完全一样但痛点同样集中患者集中在上午高峰期排队医生分身乏术排班信息贴在墙上患者到了现场才知道当天哪位医生出诊遇到医生临时停诊完全没有通知渠道老人白跑一趟的情况很常见。线上预约解决的不只是排队问题更关键的是把信息不对称抹平了。排班表在线上实时展示号源剩余数量一目了然患者提前几分钟到院就行。医生也能通过后台看到当天预约分布合理安排看诊节奏。对诊所管理者来说预约数据本身就是排班调整的依据哪个时间段患者密集、哪个医生被约得多后台拉个报表就能看出来。1.2 三类用户角色与核心业务流程我把系统用户分成三类患者、医生、管理员。患者通过手机号微信一键登录浏览排班后选择号源预约医生只处理与自己相关的预约记录和答疑问题管理员管理医生信息、审核排班、查看流水和统计报表。三类角色的权限边界从一开始就划清楚后面做接口权限控制会省很多事。核心业务链路是这样的患者打开小程序 → 选择科室和医生 → 看到近一周排班和剩余号源 → 选择具体时间段 → 确认预约并支付挂号费 → 生成预约记录和就诊二维码 → 到院后医生核销 → 就诊完成后可以在答疑区提问。整个过程最核心的数据关系就是医生—排班—预约—问答这条主线。1.3 系统定位答疑不等于在线问诊这里必须泼一盆冷水答疑模块绝对不能做成在线问诊。医疗是强监管领域小程序平台对涉及医疗的类目审核非常严格如果你在小程序里写了在线诊断开药方这类功能大概率过不了审甚至会被限制功能。我当时的做法是把答疑定位成医学科普与预约咨询患者可以描述症状和既往病史但医生回复时只给出建议来院面诊注意休息、观察哪些指标这类非诊断性内容同时在小程序显眼位置放免责声明明确平台不提供线上诊断所有回复不构成医疗建议请以线下面诊为准。这样既满足患者的信息需求也在合规边界内。2. 先想清楚数据模型医生、排班、预约、答疑怎么落库2.1 医生表与排班表怎么存哪天哪段时间能挂号排班是整套系统的基石数据模型设计不好后面全是坑。医生表相对简单存姓名、职称、科室、擅长领域、头像、简介这些基础信息。真正需要花心思的是排班表。我用的排班表结构大概是这样CREATE TABLE t_doctor_schedule ( id BIGINT PRIMARY KEY AUTO_INCREMENT, doctor_id BIGINT NOT NULL, work_date DATE NOT NULL, start_time VARCHAR(10) NOT NULL, end_time VARCHAR(10) NOT NULL, max_booking INT NOT NULL DEFAULT 5, booked_count INT NOT NULL DEFAULT 0, consult_fee INT NOT NULL COMMENT 挂号费单位分, status TINYINT NOT NULL DEFAULT 1 COMMENT 1正常 0停诊, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_schedule (doctor_id, work_date, start_time) );注意这里的唯一索引uk_schedule它保证了同一个医生在同一天同一时间段只有一条排班记录这是从数据库层面堵住重复排班的第一道防线。consult_fee我直接用整数分存储避免浮点数误差。关于时间段的划分我采用的是固定半小时一个号段上午九点到十二点下午两点到五点半每个号段最多放五个号。这个粒度对社区诊所够用也不会让小程序端的日历组件渲染压力太大。status字段用来处理临时停诊停诊当天前端会把前一天已预约的患者做短信或订阅消息提醒同时自动释放号源。2.2 预约表与号源扣减超卖问题怎么防预约表的设计核心是两条一是每个预约单必须有一个业务单号appointment_no二是扣减号源时必须用原子操作不能在应用层先查询后更新。先看预约表CREATE TABLE t_appointment ( id BIGINT PRIMARY KEY AUTO_INCREMENT, appointment_no VARCHAR(32) NOT NULL, schedule_id BIGINT NOT NULL, patient_id BIGINT NOT NULL, patient_name VARCHAR(30) NOT NULL, patient_phone VARCHAR(20) NOT NULL, appoint_dt DATETIME NOT NULL, status TINYINT NOT NULL DEFAULT 0 COMMENT 0已预约 1已就诊 2已取消, pay_status TINYINT NOT NULL DEFAULT 0 COMMENT 0未支付 1已支付 2已退款, pay_amount INT NOT NULL DEFAULT 0, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_appointment_no (appointment_no) );防超卖的代码这样写核心是单条 SQL 原子扣减# 伪代码扣减号源只有更新成功且影响行数为1才允许创建预约 affected db.execute( UPDATE t_doctor_schedule SET booked_count booked_count 1 WHERE id :sid AND status 1 AND booked_count max_booking , {sid: schedule_id} ) if affected 1: # 号源扣减成功插入预约记录 insert_appointment(...) else: return error(该时间段已满请选择其他号源)UPDATE ... WHERE booked_count max_booking这一步是最关键的数据库行级锁保证并发情况下不会有两个请求同时扣减同一个号段的最后一个号。如果先 SELECT 再判断再 UPDATE高并发下超卖是必然的。这个教训是我第一次用自测工具并发跑 100 个预约请求时直接撞出来的后来改成原子更新再也没出现过。2.3 答疑表为什么采用问题—回答而不是聊天流答疑模块我一开始也想做成 IM 聊天室后来发现没必要而且风险高。聊天流需要维护会话、消息状态、未读数还要做敏感词过滤开发成本大。更重要的是聊天内容没法沉淀患者下次找同样问题的答案还得重新问。所以我用了类工单的问题—回答结构CREATE TABLE t_question ( id BIGINT PRIMARY KEY AUTO_INCREMENT, question_no VARCHAR(32) NOT NULL, patient_id BIGINT NOT NULL, doctor_id BIGINT NOT NULL, title VARCHAR(100) NOT NULL, content TEXT NOT NULL, status TINYINT NOT NULL DEFAULT 0 COMMENT 0待回复 1已回复 2已关闭, create_time DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE t_answer ( id BIGINT PRIMARY KEY AUTO_INCREMENT, question_id BIGINT NOT NULL, doctor_id BIGINT NOT NULL, content TEXT NOT NULL, create_time DATETIME DEFAULT CURRENT_TIMESTAMP );这个结构的好处是每个提问和回答都是独立可检索的内容单元后台审核只需要盯着文本内容处理就行。状态流转做成待回复→已回复→已关闭医生端只展示待回复列表处理效率比聊天流高很多。关于合规我在提问页也加了提示请勿提交含个人隐私的敏感信息已有检查报告可线下出示给医生。3. Python 后端落地FastAPI 登录鉴权与预约接口的幂等设计3.1 为什么从 Flask、Django 里选了 FastAPIPython 后端框架三个主流选择Flask、Django、FastAPI。我自己评估下来这个项目用 FastAPI 最合适。维度FlaskDjangoFastAPI开发效率高但自由度过高容易写乱高自带 Admin 后台高自动生成接口文档异步支持需要额外配置3.x 之后逐步完善原生 async/await接口校验手动写手动写Pydantic 自动校验社区生态成熟非常成熟快速增长中适合场景轻量 API后台管理系统前后端分离、高并发 API选择 FastAPI 的核心理由有两个一是原生异步支持虽然预约系统本身不是高并发场景但答疑模块如果要接 WebSocket异步的支持会让代码干净很多二是 Pydantic 的自动请求校验和 OpenAPI 文档小程序端联调时直接看/docs就能拿全部接口的参数定义。但如果你的团队熟悉 Django用 Django REST Framework 一样能做成这套系统Django 自带的 Admin 做医生管理后台其实非常香。技术选型没有标准答案关键是别选一个团队谁都没用过的框架否则后面踩坑没人能帮你。3.2 小程序登录code2Session 与 Token 签发微信小程序的登录机制简单说就是前端wx.login()拿一个临时code后端拿这个code去微信服务器换openid和session_key。openid是用户在你这一个小程序里的唯一标识用它来关联用户表。FastAPI 里的登录接口核心代码app.post(/api/auth/login) async def login(payload: LoginRequest): # payload.code 来自小程序端 wx.login() url https://api.weixin.qq.com/sns/jscode2session params { appid: WX_APPID, secret: WX_SECRET, js_code: payload.code, grant_type: authorization_code, } async with httpx.AsyncClient() as client: resp await client.get(url, paramsparams) data resp.json() if errcode in data: raise HTTPException(status_code400, detaildata.get(errmsg, 登录失败)) openid data[openid] user await get_or_create_user_by_openid(openid) token create_access_token(user.id) return {token: token, user: user}这里有几个细节需要注意。第一code只能用一次5 分钟内有效前端要避免重复调用wx.login()导致第二个 code 失效。第二不建议直接把openid返回给前端当身份凭证因为openid是敏感信息而且小程序端拿到它也没用安全的正规做法是后端签发自己的 token。第三session_key不要存储到数据库它只在需要解密手机号等敏感数据时才用用完即弃。登录之后的鉴权我用的是 JWT把user_id和角色放进 token在 FastAPI 里写一个依赖函数每个接口自动校验请求头里的Authorization: Bearer token。3.3 预约接口的幂等设计和重复提交防护预约接口比登录更容易踩坑因为用户会重复点击确认预约按钮。前端虽然可以加 loading 禁止二次点击但网络超时后用户很可能重试或者小程序在某些低端机型上事件重复触发。接口层必须做幂等。我的做法是前端在进入确认页时先向后端请求一个预约预下单号pre_order_no用户点击确认时带上这个单号提交。后端拿到pre_order_no先查是否已存在预约如果已存在直接返回对应的appointment_no不重复创建。这个思路和微信支付里的商户订单号out_trade_no是一个道理用业务单号做天然幂等键数据库表对appointment_no加唯一索引重复插入直接走异常分支返回上一次的结果。app.post(/api/appointment/create) async def create_appointment(payload: AppointmentCreate, userDepends(get_current_user)): # 幂等检查pre_order_no 已存在则直接返回 existed await get_appointment_by_pre_no(payload.pre_order_no) if existed: return {appointment_no: existed.appointment_no, duplicated: True} affected await deduct_schedule_booked_count(payload.schedule_id) if not affected: raise HTTPException(status_code400, detail该时间段已满) appointment_no gen_appointment_no() await insert_appointment(appointment_no, payload, user.id) return {appointment_no: appointment_no, duplicated: False}有一个顺序问题要注意先扣号源再插入预约记录如果插入失败要回滚号源。实际开发里我用的是同一个数据库事务把这两步包起来SQLAlchemy 的session.begin()包裹插入失败自动回滚。因为pre_order_no幂等检查和号源扣减之间可能有并发极端情况下两个请求同时通过幂等检查其中只有一个能拿到扣减成功的结果另一个走已满分支这样不会出现同一时间段预约人数超过号源数的情况。4. 小程序前端几处容易翻车的细节导航栏、号源选择、软键盘4.1 自定义导航栏胶囊按钮的位置才是一切小程序顶部导航栏如果想做得好看一般会自定义导航栏但自定义之后马上面对一个经典问题顶部状态栏高度和导航栏高度在不同机型上不一样。写死 44px 是最常见的错误iPhone 和安卓的刘海屏、胶囊按钮高度都不同写死的结果就是返回按钮和胶囊按钮重叠或间距诡异。正确的做法是通过wx.getMenuButtonBoundingClientRect()获取右上角胶囊按钮的位置再结合statusBarHeight算出导航栏高度const getNavBarInfo () { const menuButton wx.getMenuButtonBoundingClientRect() const systemInfo wx.getSystemInfoSync() const statusBarHeight systemInfo.statusBarHeight const navBarHeight (menuButton.top - statusBarHeight) * 2 menuButton.height return { statusBarHeight, navBarHeight, menuButtonRight: menuButton.right, menuButtonTop: menuButton.top } }这段代码的思路是胶囊按钮中心点所在位置基本就是导航栏的中心位置所以用胶囊的顶部减去状态栏高度得到一个偏移量再反过来算出导航栏整体高度。当时我拿 iPhone 13、iPhone SE、小米 11、华为 Mate 40 四台机型跑了一遍高度在 80px 到 96px 之间浮动验证了这个计算公式的通用性。自定义导航栏还有个隐藏坑页面根节点的背景色要延伸到状态栏。处理方式是把自定义导航栏组件放在页面最顶部背景色设置成和导航栏相同再用padding-top撑开状态栏的高度否则顶部会留一条白边特别丑。4.2 号源选择的交互日历、单选框与已满禁用预约页的号源选择是整个小程序交互最重的部分。排班是横向滚动的日期栏加下方时间段列表。日期栏我直接用scroll-view横向滚动每个日期渲染成卡片包含周几和几月几日。时间段列表每个选项是时间 剩余号数。这里有两个交互细节影响体验已预约满的时间段要置灰不可选不仅是disabled样式还要把点击事件过滤掉当天已过的时间段也要自动禁用不能让人预约一个已经过去的时间。我是在后端返回排班数据时对每个时段做了计算返回一个can_book字段前端直接根据这个字段渲染状态。单选这个点看着简单但小程序原生radio-group在自定义卡片样式时特别难调。我后来直接放弃原生组件用view>scroll-view scroll-y classpage scroll-into-view{{targetView}} bindkeyboardheightchangeonKeyboardHeightChange !-- 表单内容 -- view idbottom-placeholder styleheight: {{keyboardHeight}}px;/view /scroll-viewonKeyboardHeightChange(e) { this.setData({ keyboardHeight: e.detail.height }) }同时把输入框的adjust-position设为false让键盘不主动顶页面。这样输入框聚焦时通过scroll-into-view滚动到对应区域键盘高度变化时占位 view 会把底部内容从容顶上去不会出现遮挡或者突然跳动的问题。这个方案对textarea尤其重要因为textarea是原生组件层级最高普通的position: fixed元素压不住它。用scroll-view 手动占位的方式可以绕开原生组件的层级问题。5. 微信支付 v3 从预下单到回调验签的完整链路5.1 准备工作商户号、证书、APIv3 密钥预约挂号涉及收费支付功能绕不开。微信支付 v2 和 v3 我现在只建议用 v3v3 的证书体系更清晰接口签名也更规范。准备工作包括申请微信支付商户号、绑定小程序 AppID、下载商户 API 证书apiclient_cert.pem、商户私钥apiclient_key.pem以及在商户平台设置 APIv3 密钥。这里要提醒一句如果小程序主体是个人微信支付商户号基本申请不下来医疗类目更是需要企业或个体户资质。所以做这种项目之前请先确认你的主体能否申请支付能力不然开发完支付功能上线却开不了整个项目卡在资质上非常痛苦。我实际开发中暂时没有拿到正式的支付商户号之前先用的是模拟支付开关后端在支付下单接口里判断当前是否为测试模式测试模式下直接返回一个假的支付成功回调让前端流程能完整走通。等商户号申请下来再切真实支付。这个开关让开发和联调不被证书申请流程阻塞非常建议。下面说的都是真实支付链路的实现。5.2 JSAPI 预下单签名与小程序端 paySign 生成微信支付 v3 的 JSAPI 支付流程分两步后端先调用微信支付接口创建预支付单拿到prepay_id然后后端用自己的商户私钥生成小程序端wx.requestPayment需要的参数返回给前端。第一步后端请求预下单接口def wx_jsapi_prepay(openid, amount, description, out_trade_no): url https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi payload { appid: WX_APPID, mchid: WX_MCHID, description: description, out_trade_no: out_trade_no, notify_url: https://api.example.com/api/pay/notify, amount: {total: amount, currency: CNY}, payer: {openid: openid} } headers build_wx_headers(POST, /v3/pay/transactions/jsapi, json.dumps(payload)) resp requests.post(url, headersheaders, jsonpayload) return resp.json()[prepay_id]这里的build_wx_headers是最容易出错的地方。微信支付 v3 要求每个请求带Authorization头格式是WECHATPAY2-SHA256-RSA2048后面跟着签名信息。签名串由请求方法、请求路径、时间戳、随机串、请求体拼接而成再用商户私钥做 RSA-SHA256 签名。第二步拿到prepay_id后给小程序端生成拉起支付需要的参数def gen_miniapp_pay_params(prepay_id): params { appId: WX_APPID, timeStamp: str(int(time.time())), nonceStr: uuid.uuid4().hex, package: fprepay_id{prepay_id}, signType: RSA, } message f{params[appId]}\n{params[timeStamp]}\n{params[nonceStr]}\n{params[package]}\n params[paySign] sign_with_merchant_key(message) return params注意timeStamp必须是字符串package的值必须带prepay_id前缀。paySign的签名串结尾有一个换行符这个细节很容易被忽略导致前端调起支付时报签名错误。我当时在这个换行符上卡了一下午所有参数都检查了N遍最后对比官方文档才找到问题就是少了末尾的\n。小程序端拿到这些参数后调用wx.requestPayment(params)支付结果由微信的回调通知和后端主动查询共同确认不能只靠前端回调判断支付是否成功因为用户可能支付完就杀掉小程序前端回调根本来不及执行。5.3 回调通知的验签与解密支付成功之后微信会向notify_url发送一个 POST 请求。回调处理是整个支付链路里最不能出错的环节因为如果回调处理逻辑有问题用户付了钱但订单状态没更新后面就得靠人工对账补救。v3 的支付回调结构是这样的外层有event_type、resource_type、resource三个字段resource里面是加密的ciphertext、nonce、associated_data。处理步骤分两步先用平台证书验证回调签名再用 APIv3 密钥解密resource中的内容。解密代码如下def decrypt_resource(api_v3_key, associated_data, nonce, ciphertext): from cryptography.hazmat.primitives.ciphers.aead import AESGCM aesgcm AESGCM(api_v3_key.encode(utf-8)) plaintext aesgcm.decrypt( nonce.encode(utf-8), ciphertext, # base64 解码后的字节 associated_data.encode(utf-8) if associated_data else None ) return json.loads(plaintext)解密之后能拿到out_trade_no、transaction_id、trade_state等字段。这里最核心的幂等逻辑是根据out_trade_no查订单如果订单已经标记为已支付直接返回成功响应不再更新数据库。重复回调是常态微信支付保证至少一次送达不保证只送一次。回调处理完必须给微信返回200 OK和{code: SUCCESS}如果业务逻辑报错也要返回500让微信稍后重试。我当时遇到过一个坑回调里做了发短信提醒用户就诊的操作短信接口超时导致整个回调返回 500微信反复重试数据库里回调日志刷了十几条。后来把所有非核心操作全部改为先更新订单状态、再异步发消息回调只做最核心的订单状态确认。5.4 退款与对账别等到用户投诉才发现问题预约取消的场景必须有退款逻辑。微信支付 v3 退款接口是POST /v3/refund/domestic/refunds退款时需要用到商户证书。如果用户的预约因为医生停诊被取消或者用户提前一天在订单页申请取消后端自动调退款接口全额原路退回。退款接口返回out_refund_no和status需要注意退款也是异步的最终结果通过退款回调通知确认。所以退款表同样需要记录状态并监听退款结果回调。对账是这个项目里很值得说的一环。我加了一个每日凌晨的定时任务拉取微信支付前一天的全部账单和本地订单表做比对重点检查三种情况本地订单已支付但微信账单里没有、微信账单里有但本地订单未支付、金额不一致。这个定时任务上线前跑了差不多一周帮我们发现了开发环境遗留的两笔脏数据。对账不是上线后才要做的事支付系统从第一天就应该有。6. 答疑模块的务实方案订阅消息通知与即时会话的取舍6.1 为什么选异步问答而不是实时聊天答疑模块前面说过用的是问题—回答结构消息通知则依赖小程序订阅消息。这个方案相对于实时聊天最大的好处是医生不需要时刻在线患者提问后可以先忙别的医生空闲时统一回复。社区诊所的医生一天坐诊时间已经很长了你不可能要求他一直盯着手机聊天窗口。对开发来说异步问答避免了 WebSocket 长连接的维护成本也不需要引入消息队列。小程序端只需要两个页面提问列表页和问答详情页后端只需要两个接口创建提问和回复问题。这个方案的稳定性非常高我从上线到现在没在答疑模块出过线上故障。6.2 订阅消息的一次性订阅限制小程序订阅消息最坑的一个点是一次授权只能发送一次订阅消息。也就是说患者提交问题后小程序弹窗让用户授权订阅消息这个授权只能用一次如果患者下次再提问还需要再授权一次。用户对弹窗的容忍度是很低的连续弹两次基本就烦了。我采用的策略是用户点击提交提问按钮时先不直接提交而是弹出一个半屏的引导层上面写明提交后将收到医生回复通知同时主动调用wx.requestSubscribeMessage申请订阅授权。这样申请订阅的动因是明确的用户愿意点授权的比例明显高于进页面就弹窗。后端发送订阅消息的代码逻辑不复杂核心是传入用户的openid、模板 ID 和参数app.post(/api/notify/doctor) async def notify_doctor(question_id: int): ... resp requests.post( https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token access_token, json{ touser: doctor_openid, template_id: TEMPLATE_DOCTOR_NEW_QUESTION, page: fpages/question/detail?id{question_id}, data: { thing1: {value: question.title[:20]}, time2: {value: time_str} } } )这里有个小坑thing类型的字段有字数限制超过 20 个字会被拒绝所以传参前要截断time类型字段要格式化严格按YYYY-MM-DD HH:MM:SS传。订阅消息发送失败时微信会返回错误码43101表示用户拒绝对该模板的订阅注意这只是表示这次没发出去不是系统故障不要把它当成需要告警的异常。6.3 如果一定要做实时会话可以考虑的路线如果需求方坚持要实时聊天那就要重新评估了。自建 WebSocket 用 FastAPI 完全可行from fastapi import WebSocket就能直接管理连接再用 Redis 做在线状态和消息广播。但自建 IM 真正麻烦的不是 WebSocket 连接而是消息可靠性、离线消息存储、会话列表、未读数、图片语音消息处理这些全要自己造轮子会直接把开发周期拉长一倍。更务实的路线是接入专业的即时通讯云服务比如腾讯云 IM、环信它们有小程序 SDK聊天功能、离线消息、消息审核都有现成方案。缺点是引入第三方 SDK 会带来额外的成本和包体积开销。我的建议是明确问需求方一句医生真的有时间实时在线陪聊吗如果答案是没有那就坚持用异步问答方案在项目评审时给需求方算一笔开发成本账大多数时候他们都会接受异步方案。7. 上线前绕不开的合规与运维域名、证书、隐私协议和日志排查7.1 域名备案与小程序合法域名配置小程序所有网络请求都必须走 HTTPS而且请求的域名必须在小程序后台配置为合法域名。很多人第一次做会忽略一个更前置的问题域名需要完成 ICP 备案。ICP 备案的流程周期通常在 7 到 20 天取决于各地管局的处理速度。如果你希望项目在一个月内上线域名备案这件事必须在项目启动的第一天就开始申请不要等开发和联调都结束了才想起来。我当时因为备案等待期反而把本地开发多铺了一轮测试算是把时间利用了起来但确实紧绷。小程序后台需要配置的有三类域名request合法域名普通接口、socket合法域名如果有 WebSocket、uploadFile合法域名图片上传。开发调试阶段可以在微信开发者工具里勾选不校验合法域名但上线预览版和正式版必须走真实域名这点要牢记。7.2 HTTPS 证书与 Nginx 配置HTTPS 证书我用的是云厂商的免费证书有效期一年到期前会有续期提醒个人项目足够用。如果客户端对证书链有严格要求也要注意把中间证书完整配置到 Nginx只放域名证书不配中间证书会导致部分安卓机型请求失败。Nginx 配置里的关键点server { listen 443 ssl http2; server_name api.example.com; ssl_certificate /etc/nginx/cert/example.com.pem; ssl_certificate_key /etc/nginx/cert/example.com.key; # 小程序要求 TLS 1.2 及以上老项目如果默认开着 TLSv1 和 TLSv1.1 建议关掉 ssl_protocols TLSv1.2 TLSv1.3; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }这里ssl_protocols TLSv1.2 TLSv1.3很重要。微信小程序对旧版 TLS 协议支持不友好如果服务器默认开了 TLSv1 和 TLSv1.1某些 Android 版本的小程序会直接报错request:fail或者 SSL 握手失败但同样的代码在 iOS 上却正常非常容易让人怀疑是代码问题。7.3 隐私协议与医疗类目审核小程序在发布前必须在后台填写用户隐私保护指引声明你收集了哪些用户信息。预约系统里会涉及手机号、位置如果用户定位附近医院、头像昵称这些都要在隐私指引里列出来。如果你还要获取用户手机号做快速登录需要在后台申请手机号快速验证组件权限并声明收集目的。医疗类目的审核还要额外注意如果你的小程序涉及医疗健康服务需要选择对应的服务类目并上传相关资质证明比如《医疗机构执业许可证》或合作协议。我不太建议非医疗机构主体硬闯医疗类目很容易被驳回且有账号风险。更稳妥的做法是定位成预约管理工具和健康咨询主体资质不涉及医疗机构但这部分不同时期的平台规则可能会有调整动手前还是要以最新的官方规则为准。7.4 线上问题排查vConsole、后端日志与主动抓包线上出问题最怕的就是不知道请求到底发没发出去、返回了什么。微信开发者工具带有 vConsole 可以直接看小程序端的请求日志、报错堆栈和页面渲染状态。但对于线上正式版vConsole 默认是关闭的我在开发时做了一个调试开关判断当前环境是开发版或体验版时动态将vconsole.min.js注入到页面正式版不注入。这样体验和测试阶段就能直接看线上环境的网络请求非常方便。后端日志也要在项目启动时就规划好。我用的是标准库logging加TimedRotatingFileHandler按天分文件每个接口在入口处记录请求参数和时间消耗在支付回调、订阅消息发送等关键节点额外打点。线上排查问题的链路通常是用户反馈 → 查小程序端 vConsole 确认请求和响应 → 查后端日志确认处理逻辑 → 如果再对不齐才用抓包工具把整个请求链路的参数和返回字段拉出来比对。抓包在开发阶段主要用来排查一些为什么接口在开发者工具里正常、真机上异常的问题比如域名代理、证书链、请求头被吞等能快速定位是前端发出去的请求被环境拦截还是后端返回异常。8. 复盘这一套系统里哪些模块可以抽出来直接复用8.1 值得沉淀的可复用模块做完这个项目回头看有几个模块是完全可以脱离医疗预约这个业务场景复用的。登录鉴权模块稍微改一下就能用在任何需要微信登录的小程序支付模块经过封装后其实和业务解耦比较彻底输入是订单号和金额输出是支付参数任何涉及收费的小程序都能接排班日历组件和号源选择器更是通用工具。我特别建议你在一开始就把这些通用模块抽象出来。比如支付回调的处理不要和具体的订单表耦合用交易单号 交易类型的模式设计这样以后另一个项目要收费时支付模块直接复制过去只要把交易类型对应的业务处理函数注册进去就行。8.2 后续可以扩展的几个方向系统上线后我列的扩展方向有三个。一是医生管理后台目前医生处理答疑是在小程序端查看预约和管理排班是在一个简单的 Web 后台后续可以考虑做成独立的医生工作台集成排班日历、患者列表和答疑处理。二是数据统计把预约量、取消率、医生接诊量、答疑响应时间这些指标做成图表给诊所管理层做决策参考。三是与线下叫号系统打通这是个比较重的活但确实是很多诊所的实际需求。8.3 我做这个项目的一些体会做这套系统最大的体会不是技术难点有多深而是要分清看起来应该做和实际上需要做。答疑模块一开始需求方要求的是聊天室最后落地成了异步问答体验和成本都好了一个档次支付回调一开始想的很简单真正做了才发现签名、解密、幂等、对账每一环都不能偷懒。医疗类项目尤其如此合规边界从第一行代码就要想清楚。如果你接下来也要做类似的项目我给几个直接可用的建议第一数据库唯一索引能解决 90% 的重复数据问题能在数据层兜底的就别只在应用层校验第二支付、消息这类和外部系统对接的功能测试模式开关一定要提前设计好不要让外部资质办理进度卡住你的开发第三上线之前把对账和日志排查机制建好哪怕早期简单粗暴一点也比出了问题两眼一抹黑强。这套项目做完之后我自己最大的收获是把从需求到上线的完整链路跑通了一遍踩过的坑每一个都变成了后续项目的避坑指南。
社区诊所预约挂号答疑系统开发实录：微信小程序+Python从零落地
去年帮本地一家社区诊所做了一套在线医生预约挂号答疑系统前端用微信小程序后端用 Python 搭。从需求对接到上线前后断断续续做了两个多月中间踩了不少坑微信支付 v3 的回调验签、小程序顶部导航栏在不同机型上的高度适配、软键盘把查询结果顶出屏幕还有上线前域名备案的等待期。今天把整套系统的开发过程完整梳理一遍。如果你也在做医疗预约类的小程序或者想了解微信小程序 Python 这个技术组合怎么从零落地这篇内容应该能帮你省掉不少试错时间。这套系统的核心流程其实很明确患者在小程序里查看医生排班、选择时间段预约、在线支付挂号费就诊后再通过答疑板块向医生提问医生在小程序端或管理后台回复。听起来不复杂但真正动起手来数据模型怎么设计、支付回调怎么验签、消息通知怎么发送、类目审核怎么过每一块都有各自的隐藏坑。下面我就按从设计到上线的完整顺序把关键环节逐个拆开讲。1. 这个项目到底在解决什么预约挂号与在线答疑的真实场景1.1 线下挂号的痛点与线上预约的价值社区诊所的挂号场景和大型三甲医院不完全一样但痛点同样集中患者集中在上午高峰期排队医生分身乏术排班信息贴在墙上患者到了现场才知道当天哪位医生出诊遇到医生临时停诊完全没有通知渠道老人白跑一趟的情况很常见。线上预约解决的不只是排队问题更关键的是把信息不对称抹平了。排班表在线上实时展示号源剩余数量一目了然患者提前几分钟到院就行。医生也能通过后台看到当天预约分布合理安排看诊节奏。对诊所管理者来说预约数据本身就是排班调整的依据哪个时间段患者密集、哪个医生被约得多后台拉个报表就能看出来。1.2 三类用户角色与核心业务流程我把系统用户分成三类患者、医生、管理员。患者通过手机号微信一键登录浏览排班后选择号源预约医生只处理与自己相关的预约记录和答疑问题管理员管理医生信息、审核排班、查看流水和统计报表。三类角色的权限边界从一开始就划清楚后面做接口权限控制会省很多事。核心业务链路是这样的患者打开小程序 → 选择科室和医生 → 看到近一周排班和剩余号源 → 选择具体时间段 → 确认预约并支付挂号费 → 生成预约记录和就诊二维码 → 到院后医生核销 → 就诊完成后可以在答疑区提问。整个过程最核心的数据关系就是医生—排班—预约—问答这条主线。1.3 系统定位答疑不等于在线问诊这里必须泼一盆冷水答疑模块绝对不能做成在线问诊。医疗是强监管领域小程序平台对涉及医疗的类目审核非常严格如果你在小程序里写了在线诊断开药方这类功能大概率过不了审甚至会被限制功能。我当时的做法是把答疑定位成医学科普与预约咨询患者可以描述症状和既往病史但医生回复时只给出建议来院面诊注意休息、观察哪些指标这类非诊断性内容同时在小程序显眼位置放免责声明明确平台不提供线上诊断所有回复不构成医疗建议请以线下面诊为准。这样既满足患者的信息需求也在合规边界内。2. 先想清楚数据模型医生、排班、预约、答疑怎么落库2.1 医生表与排班表怎么存哪天哪段时间能挂号排班是整套系统的基石数据模型设计不好后面全是坑。医生表相对简单存姓名、职称、科室、擅长领域、头像、简介这些基础信息。真正需要花心思的是排班表。我用的排班表结构大概是这样CREATE TABLE t_doctor_schedule ( id BIGINT PRIMARY KEY AUTO_INCREMENT, doctor_id BIGINT NOT NULL, work_date DATE NOT NULL, start_time VARCHAR(10) NOT NULL, end_time VARCHAR(10) NOT NULL, max_booking INT NOT NULL DEFAULT 5, booked_count INT NOT NULL DEFAULT 0, consult_fee INT NOT NULL COMMENT 挂号费单位分, status TINYINT NOT NULL DEFAULT 1 COMMENT 1正常 0停诊, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_schedule (doctor_id, work_date, start_time) );注意这里的唯一索引uk_schedule它保证了同一个医生在同一天同一时间段只有一条排班记录这是从数据库层面堵住重复排班的第一道防线。consult_fee我直接用整数分存储避免浮点数误差。关于时间段的划分我采用的是固定半小时一个号段上午九点到十二点下午两点到五点半每个号段最多放五个号。这个粒度对社区诊所够用也不会让小程序端的日历组件渲染压力太大。status字段用来处理临时停诊停诊当天前端会把前一天已预约的患者做短信或订阅消息提醒同时自动释放号源。2.2 预约表与号源扣减超卖问题怎么防预约表的设计核心是两条一是每个预约单必须有一个业务单号appointment_no二是扣减号源时必须用原子操作不能在应用层先查询后更新。先看预约表CREATE TABLE t_appointment ( id BIGINT PRIMARY KEY AUTO_INCREMENT, appointment_no VARCHAR(32) NOT NULL, schedule_id BIGINT NOT NULL, patient_id BIGINT NOT NULL, patient_name VARCHAR(30) NOT NULL, patient_phone VARCHAR(20) NOT NULL, appoint_dt DATETIME NOT NULL, status TINYINT NOT NULL DEFAULT 0 COMMENT 0已预约 1已就诊 2已取消, pay_status TINYINT NOT NULL DEFAULT 0 COMMENT 0未支付 1已支付 2已退款, pay_amount INT NOT NULL DEFAULT 0, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_appointment_no (appointment_no) );防超卖的代码这样写核心是单条 SQL 原子扣减# 伪代码扣减号源只有更新成功且影响行数为1才允许创建预约 affected db.execute( UPDATE t_doctor_schedule SET booked_count booked_count 1 WHERE id :sid AND status 1 AND booked_count max_booking , {sid: schedule_id} ) if affected 1: # 号源扣减成功插入预约记录 insert_appointment(...) else: return error(该时间段已满请选择其他号源)UPDATE ... WHERE booked_count max_booking这一步是最关键的数据库行级锁保证并发情况下不会有两个请求同时扣减同一个号段的最后一个号。如果先 SELECT 再判断再 UPDATE高并发下超卖是必然的。这个教训是我第一次用自测工具并发跑 100 个预约请求时直接撞出来的后来改成原子更新再也没出现过。2.3 答疑表为什么采用问题—回答而不是聊天流答疑模块我一开始也想做成 IM 聊天室后来发现没必要而且风险高。聊天流需要维护会话、消息状态、未读数还要做敏感词过滤开发成本大。更重要的是聊天内容没法沉淀患者下次找同样问题的答案还得重新问。所以我用了类工单的问题—回答结构CREATE TABLE t_question ( id BIGINT PRIMARY KEY AUTO_INCREMENT, question_no VARCHAR(32) NOT NULL, patient_id BIGINT NOT NULL, doctor_id BIGINT NOT NULL, title VARCHAR(100) NOT NULL, content TEXT NOT NULL, status TINYINT NOT NULL DEFAULT 0 COMMENT 0待回复 1已回复 2已关闭, create_time DATETIME DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE t_answer ( id BIGINT PRIMARY KEY AUTO_INCREMENT, question_id BIGINT NOT NULL, doctor_id BIGINT NOT NULL, content TEXT NOT NULL, create_time DATETIME DEFAULT CURRENT_TIMESTAMP );这个结构的好处是每个提问和回答都是独立可检索的内容单元后台审核只需要盯着文本内容处理就行。状态流转做成待回复→已回复→已关闭医生端只展示待回复列表处理效率比聊天流高很多。关于合规我在提问页也加了提示请勿提交含个人隐私的敏感信息已有检查报告可线下出示给医生。3. Python 后端落地FastAPI 登录鉴权与预约接口的幂等设计3.1 为什么从 Flask、Django 里选了 FastAPIPython 后端框架三个主流选择Flask、Django、FastAPI。我自己评估下来这个项目用 FastAPI 最合适。维度FlaskDjangoFastAPI开发效率高但自由度过高容易写乱高自带 Admin 后台高自动生成接口文档异步支持需要额外配置3.x 之后逐步完善原生 async/await接口校验手动写手动写Pydantic 自动校验社区生态成熟非常成熟快速增长中适合场景轻量 API后台管理系统前后端分离、高并发 API选择 FastAPI 的核心理由有两个一是原生异步支持虽然预约系统本身不是高并发场景但答疑模块如果要接 WebSocket异步的支持会让代码干净很多二是 Pydantic 的自动请求校验和 OpenAPI 文档小程序端联调时直接看/docs就能拿全部接口的参数定义。但如果你的团队熟悉 Django用 Django REST Framework 一样能做成这套系统Django 自带的 Admin 做医生管理后台其实非常香。技术选型没有标准答案关键是别选一个团队谁都没用过的框架否则后面踩坑没人能帮你。3.2 小程序登录code2Session 与 Token 签发微信小程序的登录机制简单说就是前端wx.login()拿一个临时code后端拿这个code去微信服务器换openid和session_key。openid是用户在你这一个小程序里的唯一标识用它来关联用户表。FastAPI 里的登录接口核心代码app.post(/api/auth/login) async def login(payload: LoginRequest): # payload.code 来自小程序端 wx.login() url https://api.weixin.qq.com/sns/jscode2session params { appid: WX_APPID, secret: WX_SECRET, js_code: payload.code, grant_type: authorization_code, } async with httpx.AsyncClient() as client: resp await client.get(url, paramsparams) data resp.json() if errcode in data: raise HTTPException(status_code400, detaildata.get(errmsg, 登录失败)) openid data[openid] user await get_or_create_user_by_openid(openid) token create_access_token(user.id) return {token: token, user: user}这里有几个细节需要注意。第一code只能用一次5 分钟内有效前端要避免重复调用wx.login()导致第二个 code 失效。第二不建议直接把openid返回给前端当身份凭证因为openid是敏感信息而且小程序端拿到它也没用安全的正规做法是后端签发自己的 token。第三session_key不要存储到数据库它只在需要解密手机号等敏感数据时才用用完即弃。登录之后的鉴权我用的是 JWT把user_id和角色放进 token在 FastAPI 里写一个依赖函数每个接口自动校验请求头里的Authorization: Bearer token。3.3 预约接口的幂等设计和重复提交防护预约接口比登录更容易踩坑因为用户会重复点击确认预约按钮。前端虽然可以加 loading 禁止二次点击但网络超时后用户很可能重试或者小程序在某些低端机型上事件重复触发。接口层必须做幂等。我的做法是前端在进入确认页时先向后端请求一个预约预下单号pre_order_no用户点击确认时带上这个单号提交。后端拿到pre_order_no先查是否已存在预约如果已存在直接返回对应的appointment_no不重复创建。这个思路和微信支付里的商户订单号out_trade_no是一个道理用业务单号做天然幂等键数据库表对appointment_no加唯一索引重复插入直接走异常分支返回上一次的结果。app.post(/api/appointment/create) async def create_appointment(payload: AppointmentCreate, userDepends(get_current_user)): # 幂等检查pre_order_no 已存在则直接返回 existed await get_appointment_by_pre_no(payload.pre_order_no) if existed: return {appointment_no: existed.appointment_no, duplicated: True} affected await deduct_schedule_booked_count(payload.schedule_id) if not affected: raise HTTPException(status_code400, detail该时间段已满) appointment_no gen_appointment_no() await insert_appointment(appointment_no, payload, user.id) return {appointment_no: appointment_no, duplicated: False}有一个顺序问题要注意先扣号源再插入预约记录如果插入失败要回滚号源。实际开发里我用的是同一个数据库事务把这两步包起来SQLAlchemy 的session.begin()包裹插入失败自动回滚。因为pre_order_no幂等检查和号源扣减之间可能有并发极端情况下两个请求同时通过幂等检查其中只有一个能拿到扣减成功的结果另一个走已满分支这样不会出现同一时间段预约人数超过号源数的情况。4. 小程序前端几处容易翻车的细节导航栏、号源选择、软键盘4.1 自定义导航栏胶囊按钮的位置才是一切小程序顶部导航栏如果想做得好看一般会自定义导航栏但自定义之后马上面对一个经典问题顶部状态栏高度和导航栏高度在不同机型上不一样。写死 44px 是最常见的错误iPhone 和安卓的刘海屏、胶囊按钮高度都不同写死的结果就是返回按钮和胶囊按钮重叠或间距诡异。正确的做法是通过wx.getMenuButtonBoundingClientRect()获取右上角胶囊按钮的位置再结合statusBarHeight算出导航栏高度const getNavBarInfo () { const menuButton wx.getMenuButtonBoundingClientRect() const systemInfo wx.getSystemInfoSync() const statusBarHeight systemInfo.statusBarHeight const navBarHeight (menuButton.top - statusBarHeight) * 2 menuButton.height return { statusBarHeight, navBarHeight, menuButtonRight: menuButton.right, menuButtonTop: menuButton.top } }这段代码的思路是胶囊按钮中心点所在位置基本就是导航栏的中心位置所以用胶囊的顶部减去状态栏高度得到一个偏移量再反过来算出导航栏整体高度。当时我拿 iPhone 13、iPhone SE、小米 11、华为 Mate 40 四台机型跑了一遍高度在 80px 到 96px 之间浮动验证了这个计算公式的通用性。自定义导航栏还有个隐藏坑页面根节点的背景色要延伸到状态栏。处理方式是把自定义导航栏组件放在页面最顶部背景色设置成和导航栏相同再用padding-top撑开状态栏的高度否则顶部会留一条白边特别丑。4.2 号源选择的交互日历、单选框与已满禁用预约页的号源选择是整个小程序交互最重的部分。排班是横向滚动的日期栏加下方时间段列表。日期栏我直接用scroll-view横向滚动每个日期渲染成卡片包含周几和几月几日。时间段列表每个选项是时间 剩余号数。这里有两个交互细节影响体验已预约满的时间段要置灰不可选不仅是disabled样式还要把点击事件过滤掉当天已过的时间段也要自动禁用不能让人预约一个已经过去的时间。我是在后端返回排班数据时对每个时段做了计算返回一个can_book字段前端直接根据这个字段渲染状态。单选这个点看着简单但小程序原生radio-group在自定义卡片样式时特别难调。我后来直接放弃原生组件用view>scroll-view scroll-y classpage scroll-into-view{{targetView}} bindkeyboardheightchangeonKeyboardHeightChange !-- 表单内容 -- view idbottom-placeholder styleheight: {{keyboardHeight}}px;/view /scroll-viewonKeyboardHeightChange(e) { this.setData({ keyboardHeight: e.detail.height }) }同时把输入框的adjust-position设为false让键盘不主动顶页面。这样输入框聚焦时通过scroll-into-view滚动到对应区域键盘高度变化时占位 view 会把底部内容从容顶上去不会出现遮挡或者突然跳动的问题。这个方案对textarea尤其重要因为textarea是原生组件层级最高普通的position: fixed元素压不住它。用scroll-view 手动占位的方式可以绕开原生组件的层级问题。5. 微信支付 v3 从预下单到回调验签的完整链路5.1 准备工作商户号、证书、APIv3 密钥预约挂号涉及收费支付功能绕不开。微信支付 v2 和 v3 我现在只建议用 v3v3 的证书体系更清晰接口签名也更规范。准备工作包括申请微信支付商户号、绑定小程序 AppID、下载商户 API 证书apiclient_cert.pem、商户私钥apiclient_key.pem以及在商户平台设置 APIv3 密钥。这里要提醒一句如果小程序主体是个人微信支付商户号基本申请不下来医疗类目更是需要企业或个体户资质。所以做这种项目之前请先确认你的主体能否申请支付能力不然开发完支付功能上线却开不了整个项目卡在资质上非常痛苦。我实际开发中暂时没有拿到正式的支付商户号之前先用的是模拟支付开关后端在支付下单接口里判断当前是否为测试模式测试模式下直接返回一个假的支付成功回调让前端流程能完整走通。等商户号申请下来再切真实支付。这个开关让开发和联调不被证书申请流程阻塞非常建议。下面说的都是真实支付链路的实现。5.2 JSAPI 预下单签名与小程序端 paySign 生成微信支付 v3 的 JSAPI 支付流程分两步后端先调用微信支付接口创建预支付单拿到prepay_id然后后端用自己的商户私钥生成小程序端wx.requestPayment需要的参数返回给前端。第一步后端请求预下单接口def wx_jsapi_prepay(openid, amount, description, out_trade_no): url https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi payload { appid: WX_APPID, mchid: WX_MCHID, description: description, out_trade_no: out_trade_no, notify_url: https://api.example.com/api/pay/notify, amount: {total: amount, currency: CNY}, payer: {openid: openid} } headers build_wx_headers(POST, /v3/pay/transactions/jsapi, json.dumps(payload)) resp requests.post(url, headersheaders, jsonpayload) return resp.json()[prepay_id]这里的build_wx_headers是最容易出错的地方。微信支付 v3 要求每个请求带Authorization头格式是WECHATPAY2-SHA256-RSA2048后面跟着签名信息。签名串由请求方法、请求路径、时间戳、随机串、请求体拼接而成再用商户私钥做 RSA-SHA256 签名。第二步拿到prepay_id后给小程序端生成拉起支付需要的参数def gen_miniapp_pay_params(prepay_id): params { appId: WX_APPID, timeStamp: str(int(time.time())), nonceStr: uuid.uuid4().hex, package: fprepay_id{prepay_id}, signType: RSA, } message f{params[appId]}\n{params[timeStamp]}\n{params[nonceStr]}\n{params[package]}\n params[paySign] sign_with_merchant_key(message) return params注意timeStamp必须是字符串package的值必须带prepay_id前缀。paySign的签名串结尾有一个换行符这个细节很容易被忽略导致前端调起支付时报签名错误。我当时在这个换行符上卡了一下午所有参数都检查了N遍最后对比官方文档才找到问题就是少了末尾的\n。小程序端拿到这些参数后调用wx.requestPayment(params)支付结果由微信的回调通知和后端主动查询共同确认不能只靠前端回调判断支付是否成功因为用户可能支付完就杀掉小程序前端回调根本来不及执行。5.3 回调通知的验签与解密支付成功之后微信会向notify_url发送一个 POST 请求。回调处理是整个支付链路里最不能出错的环节因为如果回调处理逻辑有问题用户付了钱但订单状态没更新后面就得靠人工对账补救。v3 的支付回调结构是这样的外层有event_type、resource_type、resource三个字段resource里面是加密的ciphertext、nonce、associated_data。处理步骤分两步先用平台证书验证回调签名再用 APIv3 密钥解密resource中的内容。解密代码如下def decrypt_resource(api_v3_key, associated_data, nonce, ciphertext): from cryptography.hazmat.primitives.ciphers.aead import AESGCM aesgcm AESGCM(api_v3_key.encode(utf-8)) plaintext aesgcm.decrypt( nonce.encode(utf-8), ciphertext, # base64 解码后的字节 associated_data.encode(utf-8) if associated_data else None ) return json.loads(plaintext)解密之后能拿到out_trade_no、transaction_id、trade_state等字段。这里最核心的幂等逻辑是根据out_trade_no查订单如果订单已经标记为已支付直接返回成功响应不再更新数据库。重复回调是常态微信支付保证至少一次送达不保证只送一次。回调处理完必须给微信返回200 OK和{code: SUCCESS}如果业务逻辑报错也要返回500让微信稍后重试。我当时遇到过一个坑回调里做了发短信提醒用户就诊的操作短信接口超时导致整个回调返回 500微信反复重试数据库里回调日志刷了十几条。后来把所有非核心操作全部改为先更新订单状态、再异步发消息回调只做最核心的订单状态确认。5.4 退款与对账别等到用户投诉才发现问题预约取消的场景必须有退款逻辑。微信支付 v3 退款接口是POST /v3/refund/domestic/refunds退款时需要用到商户证书。如果用户的预约因为医生停诊被取消或者用户提前一天在订单页申请取消后端自动调退款接口全额原路退回。退款接口返回out_refund_no和status需要注意退款也是异步的最终结果通过退款回调通知确认。所以退款表同样需要记录状态并监听退款结果回调。对账是这个项目里很值得说的一环。我加了一个每日凌晨的定时任务拉取微信支付前一天的全部账单和本地订单表做比对重点检查三种情况本地订单已支付但微信账单里没有、微信账单里有但本地订单未支付、金额不一致。这个定时任务上线前跑了差不多一周帮我们发现了开发环境遗留的两笔脏数据。对账不是上线后才要做的事支付系统从第一天就应该有。6. 答疑模块的务实方案订阅消息通知与即时会话的取舍6.1 为什么选异步问答而不是实时聊天答疑模块前面说过用的是问题—回答结构消息通知则依赖小程序订阅消息。这个方案相对于实时聊天最大的好处是医生不需要时刻在线患者提问后可以先忙别的医生空闲时统一回复。社区诊所的医生一天坐诊时间已经很长了你不可能要求他一直盯着手机聊天窗口。对开发来说异步问答避免了 WebSocket 长连接的维护成本也不需要引入消息队列。小程序端只需要两个页面提问列表页和问答详情页后端只需要两个接口创建提问和回复问题。这个方案的稳定性非常高我从上线到现在没在答疑模块出过线上故障。6.2 订阅消息的一次性订阅限制小程序订阅消息最坑的一个点是一次授权只能发送一次订阅消息。也就是说患者提交问题后小程序弹窗让用户授权订阅消息这个授权只能用一次如果患者下次再提问还需要再授权一次。用户对弹窗的容忍度是很低的连续弹两次基本就烦了。我采用的策略是用户点击提交提问按钮时先不直接提交而是弹出一个半屏的引导层上面写明提交后将收到医生回复通知同时主动调用wx.requestSubscribeMessage申请订阅授权。这样申请订阅的动因是明确的用户愿意点授权的比例明显高于进页面就弹窗。后端发送订阅消息的代码逻辑不复杂核心是传入用户的openid、模板 ID 和参数app.post(/api/notify/doctor) async def notify_doctor(question_id: int): ... resp requests.post( https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token access_token, json{ touser: doctor_openid, template_id: TEMPLATE_DOCTOR_NEW_QUESTION, page: fpages/question/detail?id{question_id}, data: { thing1: {value: question.title[:20]}, time2: {value: time_str} } } )这里有个小坑thing类型的字段有字数限制超过 20 个字会被拒绝所以传参前要截断time类型字段要格式化严格按YYYY-MM-DD HH:MM:SS传。订阅消息发送失败时微信会返回错误码43101表示用户拒绝对该模板的订阅注意这只是表示这次没发出去不是系统故障不要把它当成需要告警的异常。6.3 如果一定要做实时会话可以考虑的路线如果需求方坚持要实时聊天那就要重新评估了。自建 WebSocket 用 FastAPI 完全可行from fastapi import WebSocket就能直接管理连接再用 Redis 做在线状态和消息广播。但自建 IM 真正麻烦的不是 WebSocket 连接而是消息可靠性、离线消息存储、会话列表、未读数、图片语音消息处理这些全要自己造轮子会直接把开发周期拉长一倍。更务实的路线是接入专业的即时通讯云服务比如腾讯云 IM、环信它们有小程序 SDK聊天功能、离线消息、消息审核都有现成方案。缺点是引入第三方 SDK 会带来额外的成本和包体积开销。我的建议是明确问需求方一句医生真的有时间实时在线陪聊吗如果答案是没有那就坚持用异步问答方案在项目评审时给需求方算一笔开发成本账大多数时候他们都会接受异步方案。7. 上线前绕不开的合规与运维域名、证书、隐私协议和日志排查7.1 域名备案与小程序合法域名配置小程序所有网络请求都必须走 HTTPS而且请求的域名必须在小程序后台配置为合法域名。很多人第一次做会忽略一个更前置的问题域名需要完成 ICP 备案。ICP 备案的流程周期通常在 7 到 20 天取决于各地管局的处理速度。如果你希望项目在一个月内上线域名备案这件事必须在项目启动的第一天就开始申请不要等开发和联调都结束了才想起来。我当时因为备案等待期反而把本地开发多铺了一轮测试算是把时间利用了起来但确实紧绷。小程序后台需要配置的有三类域名request合法域名普通接口、socket合法域名如果有 WebSocket、uploadFile合法域名图片上传。开发调试阶段可以在微信开发者工具里勾选不校验合法域名但上线预览版和正式版必须走真实域名这点要牢记。7.2 HTTPS 证书与 Nginx 配置HTTPS 证书我用的是云厂商的免费证书有效期一年到期前会有续期提醒个人项目足够用。如果客户端对证书链有严格要求也要注意把中间证书完整配置到 Nginx只放域名证书不配中间证书会导致部分安卓机型请求失败。Nginx 配置里的关键点server { listen 443 ssl http2; server_name api.example.com; ssl_certificate /etc/nginx/cert/example.com.pem; ssl_certificate_key /etc/nginx/cert/example.com.key; # 小程序要求 TLS 1.2 及以上老项目如果默认开着 TLSv1 和 TLSv1.1 建议关掉 ssl_protocols TLSv1.2 TLSv1.3; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }这里ssl_protocols TLSv1.2 TLSv1.3很重要。微信小程序对旧版 TLS 协议支持不友好如果服务器默认开了 TLSv1 和 TLSv1.1某些 Android 版本的小程序会直接报错request:fail或者 SSL 握手失败但同样的代码在 iOS 上却正常非常容易让人怀疑是代码问题。7.3 隐私协议与医疗类目审核小程序在发布前必须在后台填写用户隐私保护指引声明你收集了哪些用户信息。预约系统里会涉及手机号、位置如果用户定位附近医院、头像昵称这些都要在隐私指引里列出来。如果你还要获取用户手机号做快速登录需要在后台申请手机号快速验证组件权限并声明收集目的。医疗类目的审核还要额外注意如果你的小程序涉及医疗健康服务需要选择对应的服务类目并上传相关资质证明比如《医疗机构执业许可证》或合作协议。我不太建议非医疗机构主体硬闯医疗类目很容易被驳回且有账号风险。更稳妥的做法是定位成预约管理工具和健康咨询主体资质不涉及医疗机构但这部分不同时期的平台规则可能会有调整动手前还是要以最新的官方规则为准。7.4 线上问题排查vConsole、后端日志与主动抓包线上出问题最怕的就是不知道请求到底发没发出去、返回了什么。微信开发者工具带有 vConsole 可以直接看小程序端的请求日志、报错堆栈和页面渲染状态。但对于线上正式版vConsole 默认是关闭的我在开发时做了一个调试开关判断当前环境是开发版或体验版时动态将vconsole.min.js注入到页面正式版不注入。这样体验和测试阶段就能直接看线上环境的网络请求非常方便。后端日志也要在项目启动时就规划好。我用的是标准库logging加TimedRotatingFileHandler按天分文件每个接口在入口处记录请求参数和时间消耗在支付回调、订阅消息发送等关键节点额外打点。线上排查问题的链路通常是用户反馈 → 查小程序端 vConsole 确认请求和响应 → 查后端日志确认处理逻辑 → 如果再对不齐才用抓包工具把整个请求链路的参数和返回字段拉出来比对。抓包在开发阶段主要用来排查一些为什么接口在开发者工具里正常、真机上异常的问题比如域名代理、证书链、请求头被吞等能快速定位是前端发出去的请求被环境拦截还是后端返回异常。8. 复盘这一套系统里哪些模块可以抽出来直接复用8.1 值得沉淀的可复用模块做完这个项目回头看有几个模块是完全可以脱离医疗预约这个业务场景复用的。登录鉴权模块稍微改一下就能用在任何需要微信登录的小程序支付模块经过封装后其实和业务解耦比较彻底输入是订单号和金额输出是支付参数任何涉及收费的小程序都能接排班日历组件和号源选择器更是通用工具。我特别建议你在一开始就把这些通用模块抽象出来。比如支付回调的处理不要和具体的订单表耦合用交易单号 交易类型的模式设计这样以后另一个项目要收费时支付模块直接复制过去只要把交易类型对应的业务处理函数注册进去就行。8.2 后续可以扩展的几个方向系统上线后我列的扩展方向有三个。一是医生管理后台目前医生处理答疑是在小程序端查看预约和管理排班是在一个简单的 Web 后台后续可以考虑做成独立的医生工作台集成排班日历、患者列表和答疑处理。二是数据统计把预约量、取消率、医生接诊量、答疑响应时间这些指标做成图表给诊所管理层做决策参考。三是与线下叫号系统打通这是个比较重的活但确实是很多诊所的实际需求。8.3 我做这个项目的一些体会做这套系统最大的体会不是技术难点有多深而是要分清看起来应该做和实际上需要做。答疑模块一开始需求方要求的是聊天室最后落地成了异步问答体验和成本都好了一个档次支付回调一开始想的很简单真正做了才发现签名、解密、幂等、对账每一环都不能偷懒。医疗类项目尤其如此合规边界从第一行代码就要想清楚。如果你接下来也要做类似的项目我给几个直接可用的建议第一数据库唯一索引能解决 90% 的重复数据问题能在数据层兜底的就别只在应用层校验第二支付、消息这类和外部系统对接的功能测试模式开关一定要提前设计好不要让外部资质办理进度卡住你的开发第三上线之前把对账和日志排查机制建好哪怕早期简单粗暴一点也比出了问题两眼一抹黑强。这套项目做完之后我自己最大的收获是把从需求到上线的完整链路跑通了一遍踩过的坑每一个都变成了后续项目的避坑指南。
