OpenMed DHIS2 脱敏导出实战:在机构本地完成聚合数据与 Tracker 导入对象的隐私处理
OpenMed DHIS2 脱敏导出实战:在机构本地完成聚合数据与 Tracker 导入对象的隐私处理
导读
本文讲解 OpenMed 提供的 DHIS2 导出器(export_dhis2):它可以在数据离开机构之前,在本地内存中完成 DHIS2 聚合数据值集(data value sets)与 Tracker 导入对象(tracked entities / events)的脱敏转换,输出可供 /api/dataValueSets 与 /api/tracker 导入接口直接消费的确定性 JSON。读完本文,你将掌握机构到区县(facility-to-district)的完整导出流程、DHIS2ExportConfig 全部隐私参数的含义与取值、组织单元层级泛化与日期/小单元格处理的底层原理,以及如何通过清单(manifest)在上传前完成人工审查门禁。
设计原则:无传输的本地导出器
OpenMed 的 DHIS2 导出器刻意保持"传输无关"(transport-free):它从本地 JSON 读取载荷(payload)与组织单元层级快照,在内存中应用隐私策略,返回确定性 JSON。上传凭证、HTTP 请求以及 DHIS2 服务端的实时元数据变更,全部留在 OpenMed 之外——导出器不包含 HTTP 客户端,也绝不会主动联系任何 DHIS2 实例(这一点在源码模块 docstring 中明确声明,见 openmed/clinical/exporters/dhis2.py)。
输出格式遵循 DHIS2 的 /api/dataValueSets 与 /api/tracker 导入结构:
aggregate.json是一个本地集合,其dataValueSets成员是逐个数据值集请求体;tracker.json包含 tracker 导入所接受的trackedEntities与events数组。
项目仓库中的测试夹具给出了这两种载荷的真实形状,可直接作为输入格式参考:tests/unit/clinical/fixtures/dhis2/aggregate_payload.json 与 tests/unit/clinical/fixtures/dhis2/tracker_payload.json。
Facility-to-district 流程
请严格按以下顺序执行:
- 导出到受保护工作区:将机构的聚合(aggregate)与 tracker JSON 导出到受保护的本地工作区。
- 导出组织单元快照:导出本地
/api/organisationUnits快照,其中须包含所有被引用的单元及其祖先,且带id、level、parent.id三个字段。仓库测试夹具 tests/unit/clinical/fixtures/dhis2/organisation_units.json 展示了一个 country(1)/province(2)/district(3)/facility(4) 四级结构的快照样例。 - 运行
export_dhis2:先脱敏自由文本,再移除精确几何信息,将细粒度orgUnit引用替换为配置的祖先层级,然后对日期做平移或粗化,最后抑制小规模聚合单元格。 - 本地检查:在本地检查端点载荷与不含值的清单。
- 再交给上传器:只有通过检查后,才把端点请求体交给机构现有的、已认证的上传程序。
默认目标是 level 3,即 country/province/district/facility 树中的"区县"层级。注意:DHIS2 层级是可配置的,导出前必须确认本地层级编号方式。任何未知单元、断裂的父链接、环(cycle)或缺失目标层级祖先的情况都会失败关闭(fail closed),导出器不会向服务器查询以填补空缺。
组织单元快照的校验逻辑
快照加载与校验由 OrgUnitHierarchy 类完成(源码见 openmed/clinical/exporters/dhis2.py 的 OrgUnitHierarchy.from_snapshot),它执行以下严格检查:
- 快照必须包含
organisationUnits数组,且不能为空; - 每个单元必须有非空
id(兼容uid字段)与正整数level; - 不允许出现重复 id;
parent可以是字符串 id、包含id/uid的对象,或null(顶层单元);- 所有父链接必须指向快照内存在的单元,且父层级必须低于子层级(
parent.level < unit.level); - 沿父链遍历不得成环。
在泛化阶段,generalize() 会沿父链向上查找目标层级祖先;若遇到环、父链断裂或未达到目标层级,均抛出 DHIS2ExportError。测试用例 tests/unit/clinical/test_dhis2_exporter.py 中的 test_snapshot_parent_links_and_levels_are_validated 与 test_unknown_org_unit_fails_closed_without_echoing_the_uid 分别验证了链接校验与"未知单元失败关闭"行为——错误信息只提示"absent from the local snapshot",不会把 UID 回显到错误中,避免敏感标识泄漏。
Python API 使用
以下是官方文档给出的最小可用示例(保持原样,可直接运行):
import json
from pathlib import Path
from openmed.clinical.exporters import DHIS2ExportConfig, export_dhis2
aggregate = json.loads(Path("facility-aggregate.json").read_text())
tracker = json.loads(Path("facility-tracker.json").read_text())
result = export_dhis2(
aggregate,
tracker,
"organisation-units.json",
config=DHIS2ExportConfig(
generalization_level=3,
small_cell_threshold=5,
date_mode="shift",
# Omit this for a deterministic per-record non-zero shift.
date_shift_days=30,
),
)
Path("aggregate.json").write_text(result.aggregate_json() + "\n")
Path("tracker.json").write_text(result.tracker_json() + "\n")
Path("manifest.json").write_text(result.manifest_json() + "\n")
export_dhis2 的完整签名(见 openmed/clinical/exporters/dhis2.py 的 export_dhis2 定义)还支持以关键字参数覆盖 config 中的单个策略项:generalization_level、small_cell_threshold、date_mode、date_shift_days、period_granularity。这些便利参数会通过 dataclasses.replace 与 config 合并,未传的项保持 config 默认值。org_unit_snapshot 是必填项,可传 JSON 数据(dict/list)、本地路径字符串、pathlib.Path 或可读流。
结果对象
export_dhis2 返回 DHIS2ExportResult,提供以下确定性序列化接口:
aggregate_json()/tracker_json()/manifest_json():分别序列化聚合载荷、tracker 载荷与清单;combined_payload:把三个 DHIS2 集合合并到一个传输中立对象(dataValueSets+trackedEntities+events);to_json():把聚合载荷、清单、tracker 载荷打包为单一 JSON。
所有序列化都经过 _canonical_json——sort_keys=True、紧凑分隔符(,、:)、ensure_ascii=False——保证相同输入与配置产出字节级相同的输出。
输入载荷的归一化
导出器对输入形状非常宽容(见 _normalize_aggregate_payload / _normalize_tracker_payload):
- 聚合载荷可以是单个 dataValueSet 对象、对象数组,或带
dataValueSets键的封装(envelope);None视为空集合; - tracker 载荷必须是 JSON 对象且至少含
trackedEntities或events之一;缺失的键会自动补为空数组。
自由文本脱敏与自定义 Redactor
默认情况下,以下敏感字符串字段会经过 OpenMed 的 hipaa_safe_harbor 脱敏流水线:
comment、storedBy、completedBy等文本字段;- tracker 属性(
attributes[].value)与 data-valuevalue字符串; - note 的
value字符串。
这些敏感字段中的非字符串值会失败关闭(抛出 DHIS2ExportError),唯一例外是 null——DHIS2 用 null 来表示删除属性和数据值的操作,因此被原样保留。
默认 redactor 的调用方式在源码 _default_text_redactor 中可以看到:调用 openmed.core.pii.deidentify(value, method="mask", lang=..., policy=...),其中 lang 与 policy 均来自配置。测试 test_default_redactor_uses_existing_local_deidentification_pipeline 验证了这一调用约定。
如果你已经持有预热好的模型或更严格的流水线,可以传入自定义 text_redactor 可调用对象。该 callable 必须返回:
- 一个字符串;或
- 一个带
deidentified_text字符串属性的对象(_redacted_text同时支持 Mapping 与任意对象)。
redactor 抛出的任何异常都会被包装为 DHIS2ExportError,且错误信息不含原始值(raw value omitted)。测试 test_sensitive_text_values_fail_closed_on_non_strings 覆盖了 storedBy、comment、attribute、data_value、note 五种敏感位置的失败关闭行为。
地理、日期与小单元格策略
组织单元泛化(generalization)
generalization_level=3会把每个 level-4 的机构 UID 替换为其 level-3 祖先;已处于 level 3 或以上的引用保持不变。- 泛化只发生在
orgUnit字段;泛化路径、被检查/被泛化的单元数量都会计入清单计数(org_units_examined/org_units_generalized)。 - 导出完成后,
_assert_org_units_permitted会对整个输出递归扫描,确保任何残留引用都不低于配置层级——双重校验保证"泛化遗漏"不可能溜进最终载荷。
精确地理信息移除
geometry、latitude、longitude 三个字段会被删除而非带入脱敏载荷(源码中 _PRECISE_GEOGRAPHY_FIELDS 常量,见 openmed/clinical/exporters/dhis2.py)。即使字段值为 null 也不保留。每次移除都会计数到 precise_locations_removed 并记录到 transformed_paths。测试 test_synthetic_payloads_round_trip_without_phi_or_fine_geography 断言输出事件中不再含这三个键。
日期策略:shift 与 coarsen
date_mode="shift"(默认):使用与表格型准标识符脱敏相同的确定性逐记录偏移派生。不传date_shift_days时,偏移由derive_date_shift_days(见 openmed/multimodal/tabular_csv.py)基于记录的规范 JSON、记录序号与种子材料做 SHA-256 哈希派生,得到-365 ~ 364之间的非零偏移(0 被强制为 1);默认种子为openmed-dhis2-v1(date_shift_seed可改)。设置date_shift_days则复用同一个显式非零偏移。date_mode="coarsen":把事件日期替换为当月或当年第一天(period_granularity="month"或"year"),并同步粗化兼容的 DHIS2 报告期。date_mode="none":日期保持不变(适合仅需文本脱敏与地理/层级处理的场景)。
被识别的日期字段集合(_DATE_FIELDS)包括:completedAt、completedDate、createdAt、createdAtClient、dueDate、enrolledAt、enrollmentDate、eventDate、incidentDate、occurredAt、scheduledAt、updatedAt、updatedAtClient。
日期字符串必须是 ISO YYYY-MM-DD(可带 T 时间与 Z/时区后缀)。平移会保留时区后缀;粗化时若原值带 T 时间,则时间部分被归一为 T00:00:00 并保留时区。非 ISO 或非法日期直接失败关闭,且不把原始值回显到错误信息(test_malformed_datetime_suffix_fails_closed_without_echoing_raw_value 验证)。
报告期粗化
在 coarsen 模式下,聚合载荷中的 period 字段支持以下 DHIS2 周期格式(_coarsen_period 实现):
| 输入格式 | 示例 | month 粒度结果 | year 粒度结果 |
|---|---|---|---|
日周期 YYYYMMDD / YYYY-MM-DD |
20260717 |
202607 |
2026 |
周周期 YYYYWn |
2026W29 |
转为所在月 202607 |
2026 |
月周期 YYYYMM |
202607 |
保持不变 | 2026 |
季度/半年 YYYYQn / YYYYSn |
2026Q3 |
保持不变 | 2026 |
年 YYYY |
2026 |
保持不变 | 2026 |
不支持的周期格式会抛出 DHIS2ExportError。对应行为由测试 test_period_and_event_dates_can_be_coarsened_to_month 验证。
小单元格抑制
small_cell_threshold=5会移除数值在 0 到 4 之间的聚合 data value(判定条件为0 <= value < threshold的有限数值)。- 只有当已批准的策略明确禁用抑制时,才使用
0或构造None的 config 禁用(DHIS2ExportConfig(small_cell_threshold=None))。 - 被抑制的单元格直接从输出中删除,并计入
suppressed_aggregate_values、记录到transformed_paths;布尔值与非数值不会被抑制。
测试 test_none_convenience_threshold_disables_small_cell_suppression 验证了 None 禁用抑制的便利语义。
确定性输出
导出器对所有集合做规范排序,确保相同输入产出相同输出:
- dataValueSets 按
dataSet, period, orgUnit, completeDate排序; - dataValues 按
dataElement, categoryOptionCombo, attributeOptionCombo排序; - trackedEntities 按
trackedEntity, trackedEntityType, orgUnit排序; - events 按
event, program, programStage, occurredAt, orgUnit排序; - attributes 按
attribute排序。
测试 test_payload_collections_are_sorted_for_canonical_output 通过故意反转输入数组来验证排序行为。所有抑制与变换路径都会被记录,但从不记录源值。
清单(Manifest)与上传审查门禁
清单(manifest.json)只包含策略设置、计数与结构路径,不包含评论、属性值、用户名、组织单元 UID 或抑制的单元格值。其结构(见 _ManifestState.to_manifest)包括:
schema_version、exporter(固定为"dhis2");generalization_level、small_cell_threshold;date_policy:mode、fixed_shift_days、keep_year、period_granularity;counts:data_value_sets、aggregate_values_input、aggregate_values_output、suppressed_aggregate_values、tracked_entities、events、org_units_examined、org_units_generalized、precise_locations_removed、text_values_examined、text_values_redacted、dates_examined、dates_transformed、periods_examined、periods_coarsened;transformed_paths:有序(sorted)的结构路径列表。
上传前至少应核对:
counts.org_units_generalized与预期的机构引用数一致;counts.precise_locations_removed与预期的坐标字段数一致;counts.suppressed_aggregate_values与低容量审查结果一致;transformed_paths覆盖所有预期的自由文本与日期字段;- 序列化后的端点载荷通过机构的 no-PHI 门禁与 DHIS2 元数据校验。
仓库测试通过 assert_redacted(来自 openmed.interop)对整个序列化输出(聚合 + tracker + 清单)断言原始 PHI(姓名、电话、ID)不再出现,见 tests/unit/clinical/test_dhis2_exporter.py。
命令行参考
仓库提供了开箱即用的 CLI 示例脚本 examples/dhis2_district_export.py,与文档给出的命令一致:
python examples/dhis2_district_export.py \
--aggregate facility-aggregate.json \
--tracker facility-tracker.json \
--org-units organisation-units.json \
--output-dir deidentified-dhis2
该脚本支持的参数与 DHIS2ExportConfig 一一对应:--generalization-level(默认 3)、--small-cell-threshold(默认 5)、--date-mode(shift/coarsen/none,默认 shift)、--date-shift-days(可选)、--period-granularity(month/year,默认 month)。
运行后会在 --output-dir 下生成三个本地文件:
aggregate.json:脱敏后的聚合端点载荷;tracker.json:脱敏后的 tracker 端点载荷;manifest.json:PHI-free 的变换清单。
该命令只写本地文件,永不执行上传——将载荷交给机构既有上传器之前,必须完成上文清单审查门禁。