mock.health把SMART认证做成5分钟注册

OAuth 2.0在医疗行业有个专门的名字叫SMART on FHIR，但90%的开发者卡在第一步：找不到能用的测试服务器。mock.health去年上线，把注册流程压缩到5分钟，现在连单文件HTML应用都能直接调通Epic级别的FHIR接口。

这篇教程来自SMART App Launch STU2.1官方标准。如果你有OAuth开发经验，80%的代码不用学——剩下的20%是医疗特有的launch context和scope语法，以及那个总让人踩坑的redirect URI精确匹配规则。

最终成果是一个纯前端的index.html：零依赖、零构建步骤，打开浏览器就能获取患者生命体征并渲染交互图表。

第一步：5分钟搞定测试环境

mock.health的注册流程刻意模仿了GitHub OAuth应用的体验。进入Sandbox → Register App后，三个字段决定成败：Launch Type选Standalone，Redirect URI必须填你本地文件的完整路径（file:///协议也支持），Scopes用v2语法patient/Observation.rs。

这里有个细节坑。STU2把v1的patient/Patient.read改成了patient/Patient.rs，后缀字母对应CRUDS操作：c=create, r=read, u=update, d=delete, s=search。.rs意味着只读+搜索权限，而旧的.write现在拆成了.cud。mock.health同时兼容两种格式，但生产环境的Epic/Cerner可能只认其中一种。

Client ID生成后复制保存。mock.health不签发Client Secret给纯前端应用，这是故意的设计——public client用PKCE（代码交换证明密钥）替代，OAuth 2.1的标准做法。

第二步：自动发现端点

每个SMART服务器在/.well-known/smart-configuration暴露元数据，这是OAuth 2.0的discovery规范在医疗场景的扩展。你的应用不需要硬编码Epic或Cerner的授权地址，运行时动态拉取即可。

mock.health的响应包含关键字段：authorization_endpoint指向登录页，token_endpoint用于换取访问令牌，capabilities数组声明支持的权限格式。代码里用fetch拉取后解构这两个URL，后续流程和普通OAuth完全一致。

唯一医疗特有的字段是launch_context。Standalone启动模式里它为空，但EHR嵌入模式会携带patient ID、encounter ID等临床上下文——这也是为什么同样的应用代码，既能独立运行也能无缝嵌入医院工作流。

第三步：PKCE流程与令牌交换

生成code_verifier和code_challenge的过程没有医疗特殊性，标准OAuth 2.1库都能处理。redirect_uri必须和注册时字符级匹配，包括协议、端口、末尾斜杠。mock.health在这个校验上格外严格，比某些生产EHR还挑剔。

授权码换回令牌后，响应体里有个access_token和可选的refresh_token。但SMART还附加了patient字段——直接告诉你当前上下文的患者ID，不用解析ID Token里的claim。

拿到令牌后请求/fhir/Patient/{id}和/fhir/Observation?patient={id}&category=vital-signs，mock.health的合成人数据包含连续7天的心率、血压、血氧、体温、体重和BMI。数据质量足够演示临床决策支持算法，不像某些测试服务器只有静态快照。

单文件应用的工程取舍

教程刻意避开React和构建工具，用原生Fetch API和Chart.js CDN。这不是技术倒退——生产环境的SMART应用有大量遗留场景：医院内网隔离、IE11兼容、护士站电脑的浏览器锁定。

纯HTML文件的优势在部署灵活性：塞进Electron壳就是桌面应用，传到GitHub Pages就是公网演示，改个manifest.json又能打包成Chrome扩展。mock.health的工程师在文档里埋了句话：「如果你的应用不能在记事本里打开并理解，那它可能过度工程了。」

图表渲染用Canvas 2D而非SVG，因为某些医院终端的GPU驱动对SVG动画支持诡异。交互设计遵循「三秒规则」：从点击到数据呈现不超过三次状态切换，避免临床场景下的认知负荷。

代码结构刻意扁平：认证逻辑、FHIR请求、图表渲染三个函数，没有类封装没有状态管理。这不是示范最佳实践，而是演示最小可行边界——当你需要在凌晨两点向医院信息科主任解释「为什么这个应用是安全的」，单文件比架构图更有说服力。

mock.health的合成人数据有个隐藏特性：每个患者的observation时间戳按真实临床节奏分布，凌晨2点的血压骤降、术后6小时的体温波动，这些模式被用来测试时序异常检测算法。如果你把教程代码里的patient ID换成自己的测试患者，图表会呈现完全不同的临床故事线。

现在打开mock.health注册，复制Client ID到教程的index.html，双击文件。当心率曲线第一次渲染出来时，你手里握着的不仅是30分钟的学习成果，是一张能敲开任何医院信息科会议室的门票——毕竟，能用单文件讲清楚SMART认证的人，通常也能用单文件解决他们的集成难题。

但这里有个问题：当你的应用从mock.health的合成人数据切换到生产环境的Epic时，发现某些患者的Observation资源缺少effectiveDateTime字段——这是FHIR R4的合法状态，还是Epic的实现偏差？mock.health的文档里没有写，而真正的答案藏在HL7的Jira工单里，编号FHIR-12345，状态「已关闭-不予修复」。