陆拾贰號从0到1搭建社区医疗挂号病历系统：微信小程序 + Vue管理端 + Python后端的完整实践
最近一个月，我带着小组完整落地了一套面向社区医疗场景的挂号与病历管理系统。技术栈选得比较"杂"：患者端用微信小程序，医院管理端用Vue写的Web后台，接口层用Python做服务端，另外还有一部分运行在Android设备上的辅助模块。整个项目从需求梳理、数据库设计、接口开发到多端联调，踩了不少坑，也沉淀了不少可复用的经验。
这篇文章会把整个项目的来龙去脉、技术选型背后的思考、每个端的关键实现细节、以及联调阶段遇到的真实问题完整写出来。不管是正在做类似毕业设计、练手项目，还是想了解微信小程序 + Vue + Python这种多端组合怎么配合的人，都能从中找到可以直接参考的代码和方案。
先说清楚这个系统解决的核心问题。社区医院的就诊流程和大型三甲医院不太一样，患者往往不需要经过复杂的分诊，但挂号、排队、病历记录这些环节依然依赖纸质流程：窗口排队挂号、医生手写病历、复诊时翻找旧档案。这套系统要把这些环节全部数字化：患者用微信小程序完成挂号、查看排队状态；医生和分诊台通过Vue管理后台维护排班、填写病历、查看当日患者列表；Python后端负责统一处理业务逻辑和患者数据存取；Android端作为补充，主要跑在分诊台平板上，用于处理排队叫号和院内引导。
1. 项目整体架构与数据库设计：先把数据关系理清楚
任何多端系统，第一步不是写代码，而是把业务模型搞清楚。挂号病历系统这个领域，业务边界其实很清晰，核心就两个对象：挂号单和病历。
1.1 表结构设计的核心思路
我从业务抽取出八张核心表：用户表、医生表、科室表、排班表、挂号单表、病历表、处方明细表、院区配置表。其中最关键的是挂号单和病历之间的关系——一次挂号可以对应多次病历记录（比如患者挂了号，医生先开检查单，患者拿着结果回来复诊，医生再写一次病历），但一份病历必须归属于某一次挂号，这样后续统计"某位医生一天接诊了多少人次"才有数据依据。
用户表需要额外说明。微信小程序场景下，用户身份是基于openid建立的，不能用自增ID作为用户唯一标识。我的设计是：用户表主键仍是自增ID，但增加一个openid字段并建立唯一索引；患者首次登录时通过微信授权拿到openid，如果查不到记录就自动创建新用户。这样做的原因是后续可能扩展App登录或公众号登录，openid作为第三方身份标识，和系统内部的用户ID解耦更安全。
排班表是另一个容易设计失误的地方。最初我打算直接把排班信息写进医生表，比如增加"周一上午出诊"之类的字段。后来发现完全行不通：医生请假、临时调班、节假日休诊这些情况太常见，直接把排班耦合在医生表会让状态管理变得非常痛苦。最终拆成独立的排班表，一个医生一天可以有多条排班记录，每条记录包含午别（上午/下午）、科室、号源总数和已预约数。
挂号单表用的是状态机设计。状态字段从0到4分别表示：待支付、已支付待就诊、就诊中、已完成、已取消。所有状态流转都在后端校验，前端只负责展示和触发接口。
完整的建表语句我用的是Python的SQLAlchemy ORM建模，数据库选MySQL 8.0。有个细节值得提一下：所有时间字段统一用DATETIME而不是TIMESTAMP，因为TIMESTAMP有2038年问题，而且MySQL8的TIMESTAMP类型在时区处理上偶尔会让人困惑，社区医疗系统会长期运行，没必要给自己埋这个雷。
1.2 为什么最终选择Python作为服务端语言
这个项目技术组合里，Python承担的职责比较重：既要对接小程序的HTTP请求，还要做JWT鉴权、处理业务事务、对接MySQL。选择Python而非Node.js或Java，主要是三点考虑：
首先，Python的Flask框架上手成本低，对于需要快速交付的系统来说，Flask的灵活性意味着开发效率极高。不需要像Spring那样配置一堆XML，也不需要像Django那样自带一套笨重的ORM约束。一个app.py加几个blueprint就能撑起整个API层。
其次，团队里其他端（小程序和Vue）的人都不太熟悉Java，而Python正好是大家都会的"最大公约数"。
第三，后续如果要做病历文本的自动分析（比如根据病历关键词提示用药禁忌），Python的技术栈迁移最平滑，直接引入jieba分词和简单的规则引擎即可，不需要跨语言调用服务。
生产环境我推荐用gunicorn作为WSGI服务器，不要用Flask自带的开发服务器。一个简单的启动命令：gunicorn -w 4 -b 0.0.0.0:5000 run:app。4个worker可以撑住社区医院一天几百人次的挂号量，完全够用。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 小程序端核心模块：登录、挂号与排队状态查询
微信小程序是整个系统的患者入口，也是用户感知最强的部分。我在开发时重点处理了三个模块：手机号登录、科室/医生选择与挂号支付、排队进度实时查询。
2.1 登录授权与手机号获取的真实做法
微信小程序的登录流程有一个很多人会搞错的地方：wx.login()获取的code只能换一次openid和session_key，这个session_key是会话密钥，但不能直接用来解密手机号。
我在系统里实现的完整登录链是：小程序端调用wx.login()拿到code，发送到后端/api/auth/login接口；后端带着code和appid、appSecret请求微信的jscode2session接口，拿到openid和session_key；随后后端使用session_key结合小程序传来的加密数据encryptedData和iv解密出手机号。解密这一步用的是AES-128-CBC，微信官方提供了WXBizDataCrypt示例代码，Python版可以直接参考。
不过这里有个反直觉的坑：如果只是做一个内部演示系统，其实可以不用实时解密手机号。微信要求调用getPhoneNumber按钮需要企业认证的小程序账号，个人开发者没有这个权限。我在项目演示阶段用的是模拟登录：后端放一个测试开关，开启后前端点击登录按钮直接填入预设手机号，跳过微信解密流程，等部署到正式环境再关闭开关。这个方案让开发进度不受限于账号资质，建议你做类似项目时也保留这个开关。
登录完成后前端存储后端签发的JWT token，后续所有请求都在header里带Authorization: Bearer <token>。小程序端的请求封装在一个独立utils/request.js文件里，统一做token注入、401状态拦截、错误提示，避免每个页面重复写请求逻辑。
javascript复制// utils/request.js 核心代码
const request = (url, method, data) => {
return new Promise((resolve, reject) => {
wx.request({
url: baseUrl + url,
method: method || 'GET',
data: data || {},
header: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + wx.getStorageSync('token')
},
success: (res) => {
if (res.statusCode === 401) {
wx.navigateTo({ url: '/pages/login/login' });
reject(res);
} else {
resolve(res.data);
}
},
fail: (err) => reject(err)
});
});
};
2.2 挂号流程设计：先从科室列表到支付确认
挂号流程我是按四步设计的：科室列表 -> 医生列表 -> 排班时段选择 -> 确认支付。
页面层级多了以后，有一个体验问题必须处理：微信小程序的页面栈默认最多10层，如果患者从首页进科室、再进医生、再进时段确认，连续navigateTo三次，返回时会觉得路径很绕。我最终把"医生列表"和"排班时段选择"合并成同一个页面：医生列表的每一项直接展示当天剩余号源和出诊午别，点击某个医生后弹出一个半屏的ActionSheet，里面显示上午/下午的号源余量和价格，患者确认后直接提交订单。这样既减少了页面跳转，也让关键信息更聚焦。
支付环节，微信小程序里必须用wx.requestPayment调用微信支付。但我这个系统是内部演示环境，没有商户号，所以我把支付做成了"模拟支付"：前端调/api/order/confirm接口，后端校验号源库存后，将订单状态置为"已支付待就诊"。真实接入微信支付时，你需要先调用后端/api/pay/unifiedorder获得wx.requestPayment所需的参数包，前端拿到timeStamp、nonceStr、package等字段后唤起收银台。
这里有一个需要特别注意的事务处理逻辑：确认订单时必须使用数据库行锁防止超卖。我在后端对应接口里使用了SELECT ... FOR UPDATE锁住排班表的对应记录行，再做号源余量判断和扣减。如果你用ORM，注意在with_for_update()方法上调用事务查询，否则并发场景下两个患者同时挂最后一个号，系统会卖出两个号。
2.3 顶部导航栏和排队状态刷新
有搜索热词提到"微信小程序顶部导航栏高度"，这个确实是个容易踩坑的适配点。不同机型下，小程序胶囊按钮（右上角那个胶囊形状的按钮）的位置和状态栏高度不同。不能用固定高度来定位自定义头部。
标准做法是通过wx.getMenuButtonBoundingClientRect()拿到胶囊按钮的信息，再用wx.getSystemInfoSync()拿到状态栏高度，两者联合计算导航栏的自适应高度。
javascript复制const menuButton = wx.getMenuButtonBoundingClientRect();
const systemInfo = wx.getSystemInfoSync();
const navBarHeight = menuButton.bottom + menuButton.top - systemInfo.statusBarHeight - menuButton.height;
排队状态查询模块是另一个要点。患者挂号成功后会看到当前排队序号和前方等待人数。这个页面我用的是定时轮询方案：每15秒调用一次/api/queue/status接口，后端返回当前正在就诊的序号、患者自己的序号、等待人数。轮询间隔不能太短，否则高峰期会把后端打爆，压力测试下15秒是体验和性能的平衡点。如果项目后续并发量变大，可以考虑升级成WebSocket推送，但社区医院场景轮询已经足够。
3. Vue管理后台：医生排班维护与病历编辑效率
管理端是整个系统的中枢，服务对象是分诊台护士、医生和管理员。我选了Vue3 + Element Plus的组合，工程构建用Vite。这一章重点说两个核心模块：排班管理看板和病历编辑器。
3.1 排班可视化：日历表格的组件化方案
排班管理是所有社区医院最频繁的操作。护士每天都要做的就是：把下周的排班表录入系统，临时调班时修改某个医生某一天的值班状态。
最开始我打算用现成的日历组件，找了一圈发现 Element Plus 的日历组件在"一周视图横排显示"这个需求上支持得不好——医院排班通常要看"周一至周日这一周内所有医生的分布"，不是看"某一天所有时段"。最终我决定自己封装一个"周排班表"组件：横向是周一至周日，纵向是医生列表，每个单元格展示当天上午/下午的出诊状态和挂号余量。
表格单元格的交互采用点击后弹出"班次编辑"对话框。对话框里有三个核心字段：午别（上午/下午）、号源总数、停诊原因（可选）。如果勾选了"停诊"，后续小程序端该时段的医生就不会出现在可挂号列表中，这个联动是排班模块最重要的功能。
vue复制<!-- 周排班表格核心骨架 -->
<template>
<el-table :data="scheduleList" border>
<el-table-column label="医生" width="110">
<template #default="scope">{{ scope.row.name }}</template>
</el-table-column>
<el-table-column v-for="day in weekDays" :key="day.date" :label="day.label">
<template #default="scope">
<div v-for="period in periods" :key="period.value"
class="schedule-cell"
@click="openEditDialog(scope.row, day.date, period.value)">
{{ getCellText(scope.row, day.date, period.value) }}
</div>
</template>
</el-table-column>
</el-table>
</template>
对于医生数量不多（20人以内）的社区医院，这个方案在性能和可维护性上都很好。如果医生超过50人，表格会横向滚动，体验下降，届时应改成"医生在左、日期在上"的二维表结构。做这个组件时有一个小经验：把排班数据在进入页面时一次性加载完，不要每次点击单元格时再调接口查询，因为排班数据一天内变化不大，前端缓存一天的量完全没问题。
3.2 病历编辑：富文本与结构化并存
病历是医疗系统里最敏感的数据。我在设计病历编辑页时，没有用简单的textarea，而是用了"结构化表单 + 富文本补充"的组合模式。
结构化部分包括：主诉、现病史、既往史、诊断结果、处理意见等字段。这些字段在后端有对应的独立字段存储，方便后续做数据统计和检索。比如统计"这个月接诊的糖尿病患者人数"，直接对诊断结果字段做LIKE查询即可，不需要去解析大段文本。
富文本部分用来补充一些非结构化的描述，比如医生手写的补充说明、患者的主观感受等。我用的是wangeditor开源编辑器，对中文支持好，体积也不大。富文本内容以HTML形式存入数据库，前端展示时用v-html渲染。
不过v-html直接渲染有一个风险：XSS注入。如果编辑器允许用户粘贴任意内容，恶意脚本可能混入HTML。我做了两层防护：编辑器配置中关闭了所有<script>标签相关的粘贴过滤；后端保存时对富文本做一次白名单清理，只保留允许的标签（p、br、strong、em、ul、ol、li、img）。这是一个必要的安全底线，不要为了省事省略。
病历编辑页面整体采用左右布局：左侧是患者的挂号信息和历史病历列表（便于医生纵向对比），右侧是当前病历的编辑区。编辑完成提交后，后端会生成一条不可修改的病历记录（只做逻辑删除），并在挂号单状态中标记为"已完成"。这样处理的原因很简单：病历是法律证据，不能允许随意修改，如果真的需要更正，应当新增一条更正记录而非覆盖原文。
3.3 Vue项目的环境配置要点
搜热词里频繁出现"vue安装及环境配置"，这里一并说一下。Vue3 + Vite项目对环境的要求很明确：Node.js 16.18以上版本、npm 8以上。我实际工作中被坑过一次：开发机上的Node版本是14.x，运行npm install时Vite4直接报错，提示Node版本不符合要求。升级Node之后一切正常。如果你用的是Windows，建议下载安装包而不是用命令行工具切换版本，安装包会把环境变量一并配好；macOS用户可以用nvm做多版本管理。
npm install慢的问题是国内开发者共同的痛。可靠的处理方案是配置镜像源指向阿里云npm镜像：
bash复制npm config set registry https://registry.npmmirror.com
配置完成后重新npm install，速度会有几十倍的提升。项目提交到Git仓库时，node_modules目录必须加进.gitignore，否则仓库体积会爆炸，也容易引发依赖不一致问题。
4. Python后端：JWT鉴权、API设计与医疗数据校验逻辑
后端是整个系统的心脏。社区医疗系统不像互联网高并发产品那样追求极致的性能，但在数据完整性和权限控制上不能有丝毫放松。
4.1 API的分层设计与JWT会话管理
我用Flask的Blueprint把接口按业务模块拆分：auth模块处理登录和手机号绑定；dept模块处理科室信息；doctor模块处理医生列表和详情；schedule模块处理排班查询；order模块处理挂号订单；medical_record模块处理病历读写。
每个Blueprints注册到主应用的方式统一，模块内通过url_prefix区分路径。比如order模块注册时url_prefix是/api/order，模块内的路由只写/create、/confirm、/cancel这些子路径，最终对外暴露的完整路径是/api/order/create。
JWT鉴权我采用的是flask_jwt_extended库。登录成功后签发有效期30分钟的access token，同时签发7天的refresh token。小程序端每次请求检查token是否过期，过期后自动用refresh token换取新的access token。用户在手机上打开小程序一次，7天内不需要重新登录。
有一个安全性细节必须强调：JWT的SECRET_KEY绝对不允许硬编码在代码里。我在生产环境通过环境变量注入，开发环境用一个独立的config.py配合.env文件管理。项目的.env文件也必须在.gitignore中排除，谁都不想自己的密钥随着代码库推到GitHub上。
4.2 医疗数据结构的严格校验
病历表的字段设计不能马虎。我在模型定义中设置了一些约束：诊断结果字段不能为空，处方明细中的药品数量必须为正整数，挂号单的医生ID必须存在于医生表中。这些约束除了在数据库层通过外键和CHECK约束保证外，后端API层也做了业务校验。
开药剂量校验是个值得展开的细节。社区医院经常有老年患者，医生开药时剂量写错会导致严重后果。我在处方明细表里设计了药品规格字段和单次剂量字段，后端在保存处方前会做一次简单的规则校验：如果单次剂量超过了药品规格表中该药品的最大单次用量，接口直接返回错误信息并阻止保存。
这个校验逻辑用Python实现并不复杂，但它的价值不在代码量，而在拦截了操作风险。实现时我设计了可扩展的校验器模式：
python复制class PrescriptionValidator:
MAX_SINGLE_DOSE_EXCEED = '单次剂量超过药品限量'
@staticmethod
def validate_single_dose(medication, presc_dose):
max_dose = medication.max_single_dose
if not max_dose:
return None
if presc_dose > max_dose:
raise ValidationError(
f'{medication.name} 的单次剂量最高为 {max_dose}，请重新确认'
)
return None
4.3 排队叫号背后的Python逻辑
排队模块的核心逻辑在小程序端看起来只是"查询一个数字"，但在后端涉及一个状态机的有序流转。我的实现方式是：挂号订单表里有一个queue_number字段，记录患者取到的排队序号；同一个医生同一午别下，序号从1递增。医生在管理端点击"叫下一个"时，后端通过/api/queue/next接口把该医生的当前就诊序号加1，并把状态为"已支付待就诊"的最小序号患者更新为"就诊中"。
这个流程对数据库的并发控制有要求。queue_number的递增必须通过UPDATE ... SET queue_number = queue_number + 1 WHERE ...这种原子操作实现，不能先SELECT再UPDATE，否则两个患者同时挂号会拿到相同的序号。
我当时用Python实现时，先写了一个"查最大值再加一"的版本，用并发测试工具压了20个请求后立刻发现了重复序号问题。改成原子递增之后问题消失。这也解释了为什么数据库的原子操作如此重要——在分布式环境里，数据的竞争问题必须通过数据库自身约束解决，多线程加锁在应用层根本挡不住多实例的场景。
5. Android端在项目里的真实角色：跑在平板上的分诊辅助工具
标题中出现了Android，很多人会以为是一个原生的Android App。实际上这个项目里Android端的角色更精准：跑在分诊台Android平板上的辅助应用，用来处理院内叫号和诊区引导。
5.1 为什么村里的小程序项目还需要Android端
微信小程序跑在用户手机上，管理后台跑在浏览器里，那Android端存在的意义是什么？真实场景是这样的：社区医院的诊区里放了几台Android平板，护士需要通过这些平板查看当前叫号情况、管理诊区队列、遇到老年患者时帮他们操作挂号和取号。直接在这些平板上打开小程序或Web页面虽然可行，但受限于浏览器的URL切换、通知推送和系统集成能力，体验并不好。
所以我做了一个Android应用，核心功能有三块：展示当前各诊室的叫号状态（大屏模式）、推送排队到号通知（通过系统通知栏）、提供一个快捷入口跳转到挂号系统的Web管理端。后两个功能用到了Android的系统能力，这是一般的网页做不到的。
5.2 Android与Python后端的交互：一个简化版本
Android端通过Retrofit库访问Python后端提供的/api/queue/board接口，获取各诊室的叫号看板数据。这个接口是专门为Android大屏场景优化过的：每次返回该诊区的所有诊室医生、当前就诊号码、等待人数和预计等待时间。
java复制public interface QueueBoardService {
@GET("api/queue/board")
Call<BoardResponse> getBoard(@Query("department_id") int departmentId);
}
Retrofit的异步回调里更新UI时，记得切回主线程。我刚做时直接在回调里setText，结果崩溃——后来通过runOnUiThread包裹或使用LiveData解决。这是Android新手常见的错误，趁这个机会写出来提醒大家。
5.3 安卓开发环境的一个实用小贴士
热词里出现"android studio怎么设置中文"，这个很多初学者会搜。Android Studio默认界面是英文，如果你希望换成中文界面，不需要额外下载插件，只需要在安装目录的bin文件夹里找到studio64.exe.vmoptions文件（macOS上是studio.vmoptions）加上一行-Duser.language=zh，重启后界面就变中文了。
但我的建议是：尽量保留英文界面。中文界面虽然亲切，但Android开发的学习资料、官方文档、Stack Overflow上九成以上都是英文术语，界面保持英文能帮你更快建立术语映射，后面看报错信息也不会发怵。
6. 联调阶段的高频问题复盘：小程序、Vue与Python之间的协作坑
多端项目最耗时间的阶段一定是联调。单独开发时每个端都能跑通自己的Mock数据，一旦对接真实接口，各种问题蜂拥而至。这一章我把这次项目里最典型、最值得记录的联调问题一次性写清楚。
6.1 小程序10002错误与页面栈导致的"假登录失效"
开发过程中，小程序偶发出现"10002"错误码，这个错误码在小程序官方文档里对应的是"用户登录态无效或过期"。很多人第一时间会去查后端token校验，但我排查后发现10002真正高发的原因是：用户在小程序里停留时间过长，后端签发的JWT过期后，前端请求拿到401，但前端封装的request.js里401后跳转登录页的逻辑在某些页面没有生效。
更隐蔽的问题是：当用户从A页面navigateTo到B页面，再在B页面触发401跳转时，如果B页面用redirectTo而不是navigateTo跳转登录页，返回时A页面的栈还在，但登录状态已经刷新，返回A页面后A页面数据未重新加载，导致看起来"登录失效"。
最终解决方案是：在401拦截处统一使用wx.reLaunch清空页面栈，强制回到登录首页；登录成功后使用wx.reLaunch重新进入首页，避免页面栈混乱。这是一个典型的"错误码在后端，但根因在前端状态管理"的问题。
6.2 用Charles抓包定位小程序请求问题的思路
搜索热词里有"charles使用教程(一)| 使用charles抓包微信小程序"，说明很多开发者联调时都想到了用抓包工具排查请求异常。我在联调阶段也大量使用了Charles。
Charles抓包微信小程序有一个关键设置：先确保手机和电脑在同一局域网，然后手机设置代理指向电脑的IP地址和Charles的默认端口8888。随后在Charles上开启SSL Proxying，添加需要抓包的主机地址，这样才能看到HTTPS请求的具体内容。
实际抓包时我发现一个常见问题：小程序请求报错，但报错信息不具体，比如网络请求失败但后端日志里根本没有对应记录。用Charles抓包后能看到请求根本没发到服务器——是前端请求地址的域名写错了，还是后端服务没有启动，一目了然。Charles还有一个很实用的功能：断点调试。可以在Charles里设置breakpoint，修改请求参数或响应数据再放行，这样可以快速模拟各种极端情况，不需要每次都改DB数据。
6.3 Vue打包后集成到SpringBoot的差异化处理
有个热词是"vue打包放进springboot中"，说明很多项目最终要把前端打包产物交给后端服务托管。虽然我们这个项目Python后端不托管前端文件，但我在多个项目中遇到过类似需求，把通用套路说一下。
Vue项目执行npm run build后会在dist目录生成静态文件。如果要把这些文件放进SpringBoot（或任何Web服务器）的静态资源目录中托管，需要注意两件事：
第一是Vite的base配置。默认base是/，意味着打包后的JS和CSS引用路径是/assets/xxx.js。如果你的应用部署在http://host:8080/根路径，没问题；如果部署在http://host:8080/hospital/子路径下（常见于共享域名场景），就必须把Vite的base配置改为/hospital/，否则页面打开后JS资源404。
第二是Vue Router的history模式问题。createWebHistory()模式的路由在用户刷新页面时会向服务器请求实际的路径URL，而服务器上没有对应的静态文件就会404。如果前后端由同一服务器托管，需要配置服务端将所有路径请求都fallback到index.html。SpringBoot下可以在WebMvcConfigurer里配置一个view-controller，或者简单粗暴地统一改成createWebHashHistory()哈希模式。哈希模式不需要服务端配合，URL形式为/#/admin/...，部署时省心很多，但URL不够优雅，缺点和优点都明显，按项目定位权衡即可。
6.4 Python后端跨域配置与Vue联调的细节
前后端分离开发模式下，本地开发Vue跑在localhost:5173，Python后端跑在localhost:5000，跨域问题必然出现。浏览器会有CORS策略拦截，解决方法是后端配置全源允许。Flask下用flask_cors扩展实现：CORS(app, supports_credentials=True, origins="*")。
实际开发时这里会有一个小坑：supports_credentials=True和origins="*"同时配置时，浏览器会报错。因为带凭证的跨域请求不允许通配符来源。解决方案是明确写出允许的来源列表，比如指定http://localhost:5173，生产环境再换成正式域名。这也算是一个安全上的好习惯：永远不要在上线环境放开全部来源。
7. 项目备份、环境复现与团队协作的经验
多端项目交付前，还有一个容易被忽视但非常关键的工作：让项目在另一台机器上可以一键跑起来。搜热词里反复出现的"python安装教程"、"vue安装及环境配置"、"微信小程序开发者工具插件"等，本质上都是环境复现问题。
7.1 Python虚拟环境与依赖锁定
Python项目保证可复现的第一道保障就是虚拟环境。我要求团队每个人在项目根目录下执行：
bash复制python -m venv venv
source venv/bin/activate # Windows下是 venv\Scripts\activate
pip install -r requirements.txt
requirements.txt通过pip freeze > requirements.txt生成。但要注意：pip freeze会把一些间接依赖也列进去，换环境时版本容易冲突。更稳妥的方式是用pipreqs库扫描项目实际import的包来生成依赖清单，只保留顶层依赖。
bash复制pip install pipreqs
pipreqs ./ --mode local --force
7.2 小程序的微信开发者工具配置
微信开发者工具新建项目时，需要填入小程序的AppID。个人开发可以用测试号，但某些API（比如手机号获取）不开放给个人。团队联调时的建议是：申请一个企业主体的测试小程序，配置好开发者成员，让每个团队成员都用统一的AppID开发，这样体验到的API权限和正式环境最接近。
还有一个容易遗漏的配置：在微信公众平台的"开发设置"中，要把本地开发时后端的IP加入request合法域名列表。微信小程序上线后只能请求HTTPS域名，但开发调试阶段可以在开发者工具中勾选"不校验合法域名"。如果你用的是自定义域名，需要在公众平台配置服务器域名并上传校验文件，这个过程通常需要半天到一天时间，提前准备好。
7.3 Git分支管理与项目交接
多端项目有几个不同代码仓库：小程序一个仓库、Vue一个仓库、Python后端一个仓库、Android辅助应用一个仓库。我强烈建议每个端独立仓库，不要合并到同一个monorepo。原因是各端的技术栈不同，依赖变化频率差异大，独立仓库可以让每个人只关心自己的变更，避免频繁的合并冲突。
团队协作上，我采用master分支保护策略：所有人从master拉取develop分支，每个功能从develop拉新分支，合并请求必须经过至少一人Code Review。对于这个项目，我还要求所有接口字段变更必须先更新在后端的api_docs.md里，再通知其他端修改。这样联调阶段出现的"字段对不上"问题能大幅减少。
文档这块不要偷懒。我在项目根目录创建了一个README，写清楚以下几个问题：环境依赖版本清单、各端启动命令、数据库初始化和迁移方法、测试账号清单、常见错误排查。后续交接给下一任开发者时，这份文档能节省大量时间。
8. 性能优化与后续功能扩展思路
系统上线试运行后，有几处性能问题逐渐显现，做了一些针对性优化。同时也有一些扩展方向，这里一并整理出来。
8.1 排队高频轮询的缓存优化
患者端排队状态页每15秒轮询一次，高峰期系统同时有几十个患者在等待叫号，对后端的查询压力不算小。虽然社区医院规模下MySQL能扛住，但为了更稳妥，我加了一层Redis缓存：排队看板数据每5秒更新一次，患者请求时直接返回缓存结果，而不是每次查询数据库。
python复制board_data = redis.get(f'queue_board_{department_id}')
if not board_data:
board_data = build_board_data(department_id)
redis.setex(f'queue_board_{department_id}', 5, json.dumps(board_data))
这让数据库的查询频率降了两个数量级。后来发现更理想的方式是：前端轮询的15秒间隔和服务端缓存5秒的配合已经非常顺滑，患者看到的等待人数误差在几秒以内，完全不影响体验。
8.2 病历全文检索与标签化管理
病历表的文本字段很多，如果将来要支持"查找所有提到高血压的患者"，用LIKE '%高血压%'在几万条病历里也能跑，但十几万、几十万条时会开始变慢。此时可以考虑引入全文索引或独立搜索服务。不过对于社区医疗系统，我更推荐另一种轻量方案：病历标签化。
即在病历录入时增加一个"标签"字段，医生或系统自动通过关键词匹配打上标签（比如"高血压""糖尿病""复诊"）。查询时先查标签，再结合条件过滤，性能远优于全文检索。我用jieba分词做了自动标签建议：医生写完诊断结果，系统自动提取关键词推荐标签，医生确认后保存。实现简单，但日常使用的体验提升非常明显。
8.3 小程序端视频场景的延伸思考
热词里反复出现"vue播放m3u8免安装"、"vue播放欢乐谷m.3u8"这类音频视频播放需求。虽然本项目没有视频功能，但社区医疗场景下确实存在视频播放需求：比如诊区放置科普视频、医生上传的康复指导视频等。如果未来接入视频，建议采用m3u8的HLS协议播放，Vue端可以用video.js插件，小程序端则使用wx.video配合m3u8的地址。视频文件建议存放在对象存储中，不要放在后端服务器，否则带宽会拖垮接口响应速度。
很多视频播放的"免安装"需求其实是找现成轮子，比如hls.js库，它在Web端播放m3u8流非常成熟，集成到一个Vue组件里只需要几十行代码。小程序端由于官方video组件不支持m3u8直播流，需要自行用WebView组件承载hls.js实现，技术可行但坑也不少，真要做的朋友建议先把hls.js的API文档看透。
我在这个项目里没有接视频模块，原计划排期也没有给这个功能留位置。但它说明了一个趋势：医疗系统数字化越来越立体，文字病历是基础，影像、视频、图表都会逐步进入系统。架构上留下扩展空间很重要，我的API设计从一开始就考虑了文件上传和对象存储的接口位置。
9. 回顾与迭代计划
这个项目从需求确认到多端联调完成，用了大概六周时间。过程中最大的体会是：多端系统的复杂度不在于任何单端的技术难度，而在于三端之间的契约管理。接口字段、状态定义、错误码、数据结构只要有一端理解偏差，联调时就要花数倍时间排查。
几个核心决定回看都是对的：技术选上没有盲目追求微服务或者大前端框架，用小而精的Flask、Vue3、原生小程序和轻量Android应用拼出了完整的业务闭环；数据设计上重点抓了挂号单和病历的状态流转，为后续统计和扩展留了空间；多端身份验证统一走JWT，没有各自另搞一套会话机制，排查问题时少走了很多弯路。
要说遗憾也有。小程序端的自动化测试始终没有做起来，目前主要靠手工回归。如果项目下一步要规模化推广，我会优先补上小程序的自动化测试脚本，用miniprogram-automator跑核心流程冒烟测试，至少把挂号、取消挂号、病历查看这几个高频路径覆盖住。后端的单测倒是写了，主要覆盖了订单并发、状态流转和处方校验三个模块，这些是核心逻辑，不能没有。
预算允许的话，下一步可以接入微信支付正式版和短信通知服务。前者简化患者支付流程，后者让患者能收到挂号成功和排队到号的短信提醒，这比小程序内轮询更主动。Android平板大屏端也可以增加一个扫码签到功能：患者到院后在小程序里展示一个取号二维码，护士用平板扫描后自动标记"已到院"，减少人工确认的沟通成本。
最后说一个对做同类项目很实用的小建议：每做完一个里程碑，就整理一份"联调备忘"。把这段时间遇到的所有问题、定位思路、解决方式记录下来，形成团队的公共知识库。项目开发过程中踩过的坑，如果不记下来，过三个月自己都会忘。而这些记录在写项目文档、做答辩汇报、给新成员培训时，都是最有价值的一手素材。