📚 课程目录第3章医疗场景下的分布式追踪数据模型

3. 医疗场景下的分布式追踪数据模型

在医疗微服务体系中，一次“患者完成一次检验申请到报告回传”的业务动作，往往横跨挂号、医嘱、计费、检验、报告、消息推送等多个服务。分布式追踪要回答的核心问题不是“哪个服务慢”，而是“这次就诊中，哪个环节让患者等待、让临床决策延迟、让数据不一致”。因此，追踪数据模型必须同时承载技术调用链与医疗业务语义。

Trace 与 Span：技术链路的最小骨架

Trace 表示一次完整业务请求的全局轨迹，由全局唯一的 traceId 标识。Span 表示 Trace 中的一个工作单元，例如一次 HTTP 调用、一次数据库查询、一次消息消费。每个 Span 至少包含：spanId、parentSpanId、traceId、服务名、操作名、开始时间、持续时长、状态码与标签集合。

在医疗场景中，Span 的粒度需要谨慎设计。以“检验申请提交”为例，若把挂号、开单、计费、标本采集全部塞进一个 Span，排障时无法定位；若把每次 SQL 都单独建 Span，又会造成链路爆炸。推荐做法是：以业务动作作为主 Span，以关键外部依赖作为子 Span。例如主 Span 为 lab.order.submit，子 Span 包括 mysql.insert.order、mq.publish.order.created、his.charge.confirm。

上下文传播：跨进程、跨协议、跨信任域

上下文传播解决的是“traceId 和 spanId 如何从上游带到下游”。在 HTTP 场景中，通常通过 traceparent 头传递；在消息队列中，需要把上下文写入消息属性；在 gRPC 中通过 metadata 传递。医疗系统常见异构协议并存，例如 HL7 v2、DICOM、FHIR、私有 TCP 协议，因此传播策略必须按协议适配。

一个容易被忽略的问题是信任域边界。医院内部服务与第三方支付、医保接口、区域检验平台之间，不应无条件透传内部 traceId。推荐在边界网关处执行“上下文重写”：保留内部 traceId 作为 internal.trace_id 标签，同时生成新的对外 traceId，避免内部拓扑与患者标识泄露。

医疗事件语义标注：让 Span 说“业务语言”

仅有 service.name 和 http.status_code 不足以支撑医疗排障。我们需要在 Span 上附加医疗事件语义标签，使链路可被业务维度检索。推荐在关键 Span 上统一标注以下属性：

event.type：业务事件类型，如 lab.order.submit、report.publish、prescription.audit。
dept.code：发生科室编码，用于按科室聚合延迟。
priority：优先级，如 urgent、routine，用于区分急诊与普通链路。
patient.visit.id：就诊标识，用于把同一患者多次操作串起来。
data.category：数据类别，如 lab、imaging、medication。

标注时需注意基数控制。像 patient.id 这种高基数标签，不应直接作为指标维度，而应作为 Trace 检索字段。否则会导致时序数据库标签爆炸。推荐做法是：高基数标识写入 Span 属性，低基数枚举写入指标标签。

患者就诊标识映射：从技术链路到临床视角

医疗追踪最难的一步是“把 traceId 映射到患者就诊”。因为一次就诊可能产生多个 trace：挂号一个、开单一个、检验一个、报告一个。我们需要一个稳定的业务关联键，把分散的 trace 聚合成“就诊事件链”。

推荐使用三层映射：

患者主索引：patient.id，院内唯一，但属于敏感信息，进入追踪系统前应做哈希脱敏，例如 sha256(patient.id + salt)。
就诊流水号：visit.id，一次挂号到离院的核心关联键，作为 Trace 的 baggage 跨服务传播。
业务单据号：order.id、specimen.id、report.id，作为 Span 级锚点，用于精确回溯。

实际落地时，可以在网关层统一注入 visit.id 到 baggage，下游服务自动继承。这样即使跨消息队列、跨异构协议，也能通过 visit.id 把同一就诊的多个 trace 关联起来。查询时，先按 visit.id 找到所有 traceId，再按时间排序还原就诊全流程。

实践建议：在检验、影像、药房三条高频链路中，优先落地 event.type 与 visit.id 两个标签。它们能以最小成本支撑“按就诊查链路”和“按事件类型统计耗时”两类最高频排障场景。

合规提醒：患者标识进入追踪系统前必须脱敏或哈希，禁止在 Span 属性、日志、URL 参数中明文存储姓名、身份证号、手机号。追踪系统的访问权限应与临床数据权限对齐，并保留审计日志。

一个可参考的 Span 属性样例

{
  "traceId": "7f3a9c21e8b04d5a",
  "spanId": "a1b2c3d4",
  "parentSpanId": "00000000",
  "name": "lab.order.submit",
  "service.name": "order-svc",
  "event.type": "lab.order.submit",
  "dept.code": "0301",
  "priority": "urgent",
  "visit.id": "V2025031800231",
  "patient.hash": "9f2c...e81a",
  "order.id": "LAB2025031800876",
  "data.category": "lab",
  "duration.ms": 342,
  "status": "OK"
}

该样例中，visit.id 用于跨 trace 聚合，order.id 用于单据级回溯，patient.hash 用于合规关联，event.type 与 dept.code 用于业务维度统计。四者配合，才能让分布式追踪从“技术调用链”升级为“医疗业务可观测链路”。