OpenMed 非洲参考演示的合成 Fixture 边界:用全虚构数据构建 OpenMRS 到 DHIS2 的离线隐私验证
OpenMed 非洲参考演示的合成 Fixture 边界:用全虚构数据构建 OpenMRS 到 DHIS2 的离线隐私验证
这篇指南以 OpenMed 仓库中 examples/africa-openmrs-dhis2 参考演示的 fixture 边界说明文档为主体,解读其核心设计:一条完全虚构、确定性生成、只服务于设施侧测试边界的合成数据链路。读完本文,你能理解该 fixture 生成器的每个参数与产出物、loopback 回放服务器的实现方式,以及它如何支撑"数据不出院"的脱敏验证流程,并掌握在本地复现、检验该边界的完整方法。
1. Fixture 边界要解决的问题
边界说明文档开篇即定义了这条演示链路的安全姿态:
The fixture demo generates a deterministic, fictional OpenMRS FHIR2 recording in memory and serves it only on an ephemeral
127.0.0.1port. The committed organisation-unit snapshot represents one fictional country, province, district, and three facilities. No Java service, internet access, credentials, or real patient corpus is used.
翻译成设计约束,就是四条硬性边界:
- 确定性虚构:数据在内存中生成,同一个种子永远产出同一份"录像"(recording),便于逐字节比对与回归测试;
- 仅回环:HTTP 服务只绑定
127.0.0.1的临时端口(ephemeral port),任何外部主机都无法访问; - 虚构地理层级:提交的机构单位快照只包含一个虚构国家、一个省、一个区、三家具虚构设施,不指向任何真实行政单元;
- 零外部依赖:不需要 Java 服务(真实 OpenMRS)、不需要互联网、不需要凭据、不需要任何真实患者语料。
这个边界存在的意义,是让演示能"证明隐私闸门有效":数据生成器故意植入必须在设施边界被剥离的识别信息(姓名、手机号、国号 ID、GPS),如果这些值出现在任何出域工件里,闸门就应该失败。整个设计的可信度依赖"输入是已知全集合的虚构数据"这一前提。
2. 重新生成一份可检视的录像
文档给出的核心操作是从仓库根目录运行生成器:
python examples/africa-openmrs-dhis2/synthetic_data.py \
--seed 875 \
--patient-count 50 \
--output /tmp/openmed-africa-recording.json
对照 synthetic_data.py 的 CLI 定义(L337-L346),三个参数的语义如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
--seed |
875(DEFAULT_SEED) |
随机种子,决定诊断抽取与 GPS 抖动等所有随机量 |
--patient-count |
50(DEFAULT_PATIENT_COUNT) |
虚构患者数量,必须大于 0,否则抛 ValueError |
--output |
无(必填) | 输出 JSON 路径,父目录不存在时会自动 mkdir -p |
main()(L349-L364)将 dataset.recording() 以 indent=2, sort_keys=True, ensure_ascii=False 序列化落盘——键排序 + 固定缩进是"同一 seed 两次运行字节相同"这一可复现性保证的一半,另一半来自 run_demo.py 中统一的 _canonical_json 写盘函数(L419-L428)。
输出录像的顶层结构由 recording()(L139-L148)定义:
{
"fixture": "fictional-mtoni-district",
"seed": 875,
"districtOrgUnit": "ouDistrictMtoni",
"fhir2": { "Patient": [...], "Encounter": [...], "Observation": [...] },
"rest": { "patient": [...], "encounter": [...], "obs": [...] }
}
注意它同时生成 FHIR2(R4)资源与 OpenMRS 传统 REST 资源两套"录像"。这不是冗余:演示流程要分别走 pull_fhir 与 pull_rest 两条适配器路径,两套数据同源同种子,保证两条路径面对的是同一批虚构患者。
3. 合成数据长什么样:故意留出的 PHI
生成器(generate_dataset,L151-L197)构建一个虚构区"fictional-mtoni-district",固定包含三家具名设施:
ouFacilityKijani— Kijani Health Centre(-0.31230, 32.58120)ouFacilityMawingu— Mawingu District Clinic(-0.28710, 32.60640)ouFacilityTumaini— Tumaini Community Hospital(-0.33580, 32.62510)
患者按 offset % 3 轮流分配到三家具设施,每位患者携带一组故意可识别的字段:
- 姓名:从 12 个固定名池(Amina、Amara、Chidi……)取名字,姓氏统一为
Fiction{index:03d},如Fiction042; - MSISDN 手机号:
+256 700 {index//1000:03d} {index%1000:03d}; - 国家 ID:
CF-{seed:04d}-{index:06d}; - GPS 坐标:在所属设施坐标基础上做
±0.008度的确定性抖动; - 诊断:在三条 ICD-11 MMS 编码(
1A00霍乱、5A112 型糖尿病、BA00原发性高血压,来自http://id.who.int/icd/release/11/mms命名空间)中按种子随机抽取; - 就诊日期:从 2026-01-05 起逐日递增。
最关键的细节在 Observation 资源里(L277-L280):valueString 会把姓名、电话、国家 ID、GPS 拼进一条自由文本。也就是说 PHI 不只出现在结构化的 name/telecom/extension 字段,还散落在自由文本里——脱敏器必须处理"结构字段 + 自由文本"两种载体,这比只打平结构字段的演示更能检验隐私策略的召回能力。REST 侧同样如此:encounterNotes 与 obs.comment 里都嵌了联系方式与坐标(L312-L333)。
泄漏闸门用的 PHI 映射表
SyntheticDataset.phi_mapping()(L95-L109)为每位患者产出一组"替换令牌 → 原始值"映射:
[FULL_NAME_004] → "Imani Fiction004"
[GIVEN_NAME_004] → "Imani"
[FAMILY_NAME_004] → "Fiction004"
[MSISDN_004] → "+256 700 000 004"
[NATIONAL_ID_004] → "CF-0875-000004"
[GPS_004] → "-0.30432, 32.58711"
[LATITUDE_004] / [LONGITUDE_004] → 拆分后的单项坐标
每个患者 8 个令牌,50 名患者即 400 个可检查的"必须被剥离"的值。这份映射是后续所有 assert_redacted 扫描(见第 6 节)的判据:只要任何一个原始值出现在出域工件里,验证就失败。
4. 只在回环上服务的内存回放服务器
演示并不启动真实 OpenMRS。fixture_server.py 用一个 ThreadingHTTPServer 把录像"回放"成 HTTP 服务,关键实现在 openmrs_fixture_server 上下文管理器(L18-L47):
server = ThreadingHTTPServer(("127.0.0.1", 0), handler) # 端口 0 = 临时端口
...
yield f"http://{host}:{port}/openmrs"
finally:
server.shutdown()
server.server_close()
thread.join(timeout=5)
port=0 让操作系统分配一个空闲端口,进程间不会冲突;finally 保证退出上下文时服务器一定被关停。它暴露两类端点,前缀与真实 OpenMRS 对齐(L59-L78):
- FHIR2 搜索:
/openmrs/ws/fhir2/R4/{Patient|Encounter|Observation}。返回标准searchsetBundle,支持_count/page分页参数,未翻完时附加next链接(L81-L125)。未登记的资源类型返回 404unsupported_resource。 - 传统 REST 搜索:
/openmrs/ws/rest/v1/{patient|encounter|obs}。返回{results, startIndex}结构,支持limit/startIndex分页(L127-L144)。
分页不是摆设:run_demo.py 的 --page-size 参数(默认 17,L93-L98)专门用来迫使客户端跨多页抓取 50 条记录,验证 OpenMRS 适配器的分页逻辑——而测试还证明改 page size 不影响产物字节(见第 6 节)。
5. 已提交的机构单位快照
organisation_units.json 就是文档所说的"一个虚构国家、省、区 + 三家具设施":
{
"organisationUnits": [
{ "id": "ouCountryFiction", "level": 1 },
{ "id": "ouProvinceLake", "level": 2, "parent": { "id": "ouCountryFiction" } },
{ "id": "ouDistrictMtoni", "level": 3, "parent": { "id": "ouProvinceLake" } },
{ "id": "ouFacilityKijani", "level": 4, "parent": { "id": "ouDistrictMtoni" } },
{ "id": "ouFacilityMawingu","level": 4, "parent": { "id": "ouDistrictMtoni" } },
{ "id": "ouFacilityTumaini","level": 4, "parent": { "id": "ouDistrictMtoni" } }
]
}
这份快照是 DHIS2 导出器的"地理策略依据":导出时按 generalization_level=3 向上卷到区县级,因此只有 ouDistrictMtoni 允许出现在最终 payload 中,三个 level-4 设施 UID 属于必须在出域前消失的值。区县 UID 常量 ouDistrictMtoni 在生成器中定义为 DISTRICT_ORG_UNIT(L20),与快照文件互相咬合。
6. 边界如何在完整演示中被强制执行
run_demo.py 把 fixture 边界串成完整流水线:
generate_dataset生成数据集,ExactSyntheticRedactor(L50-L68)拿到phi_mapping(),按"先长后短"的顺序做全量字符串替换——生产部署中它会换成经过评审的 OpenMed 隐私策略;openmrs_fixture_server在临时回环端口上启动,OpenMRSClient先拉取未脱敏原始资源(存为01-raw-openmrs.json,留在设施边界内),再经OpenMRSAdapter拉取脱敏后的 FHIR2 与 REST 记录;- 每条脱敏记录先过
assert_redacted,再校验 FHIR transaction Bundle 形状(150 条 entry、全部POST); export_dhis2以DHIS2ExportConfig(generalization_level=3, small_cell_threshold=5, date_mode="coarsen", period_granularity="month")生成聚合与 Tracker payload(L170-L175);_assert_district_only(L392-L402)做"只许区县级"终检:任何设施 UID、"geometry"、"latitude"、"longitude"残留,或orgUnit取值不等于{ouDistrictMtoni},都直接raise ValueError使演示失败。
输出的 7 个阶段工件中,除 01-raw-openmrs.json 外全部再扫描一遍 phi_mapping,连控制台输出都要过 assert_redacted(L234-L247)——这就是文档标题"Synthetic fixture boundary"的完整含义:原始合成 PHI 只存在于第 1 阶段与设施侧内存里,其余一切产物都被证明不含任何种子值。
测试套件 test_africa_reference_demo.py 把这些约束固化为可回归的检查:从 01-raw-openmrs.json 反向提取 ≥250 个种子识别值(L119);断言 orgUnit 集合只含区县 UID、序列化文本中无 geometry/latitude/longitude(L147-L157);并用 page_size=7 与 page_size=19 跑两次全流程,断言所有工件逐字节相同(L167-L175),验证"确定性"承诺。
7. 边界红线:不要把录像带出院
回到 fixtures/README.md 的收尾警告,它划定了两条使用红线:
- 生成的录像故意包含合成 PHI(真实格式的姓名、MSISDN、国家 ID、GPS),"must remain inside the facility-side test boundary"——它只能停留在设施侧测试边界内,作为隐私闸门的输入对照;
- 它不是 DHIS2 导出工件——真正的 DHIS2 交付物是经过区县级泛化与 PHI 闸门后的
04-dhis2-aggregate.json/05-dhis2-tracker.json,而不是这份原始录像。
配套文档 africa-reference-deployment.md 进一步强调:01-raw-openmrs.json 的存在目的仅是让实施者检视"隐私边界之前的输入",严禁以真实患者数据替换,严禁把原始阶段移入国家报告系统;并给出面向 KenyaEMR/UgandaEMR 风格部署的落地映射(确认 FHIR2 模块、在设施机运行适配器、用评审过的隐私策略替换精确合成脱敏器、映射真实的 ICD-11/DHIS2 元数据)。
8. 可选:live 容器剖析(不属于 fixture 路径)
docker-compose.yml 携带一个 live 剖析,提供 demo 级的 OpenMRS Reference Application(3.7.1)与 DHIS2 Core(2.43.0.1)容器,用于隔离实验室里做真实 API 往返测试:
docker compose \
-f examples/africa-openmrs-dhis2/docker-compose.yml \
--profile live \
up -d
注意三条限制,均有测试背书(test_optional_live_compose_profile_is_explicit_and_loopback_only,L194-L204):所有服务必须显式声明 profiles: [live](CI 永不启动该剖析);所有端口必须绑定 127.0.0.1:;容器使用本地示例口令,是 demo 级配置而非加固部署,且该命令不向任何服务上传任何内容。
9. 小结
examples/africa-openmrs-dhis2/fixtures/README.md 用不到二十行文字定义了一个可审计的隐私工程实践:用可复现的虚构数据、回环内存服务、已知全集合的 PHI 令牌表,把"脱敏是否有效"从经验问题变成可断言的测试问题。生成器、回放服务器、区县快照、演示流水线与回归测试五者共同构成这条边界——任何一环(种子、page size、网络可达性)变化都能被字节级比对或闸门断言立刻发现。如果你的场景中也需要在数据离域前证明隐私策略的召回能力,这套"合成录像 + 已知 PHI 全集 + 只许泛化值出域"的模式是值得直接借鉴的工程范式。