4. 映射需求分析与规格编写

FHIR资源映射项目的失败，很少是因为工程师不会写转换代码，而是因为一开始就没有把“要交换什么、交换到什么程度、先做哪一块”讲清楚。映射需求分析的任务，就是把临床业务场景中的信息交换诉求，翻译成一份可执行、可评审、可验收的映射规格说明书（Mapping Specification）。它既是需求文档，也是后续接口开发、测试用例设计和上线验收的共同基线。

一、从业务场景提取数据交换需求

需求提取的起点不是FHIR资源，而是真实发生的业务事件。以“区域检验结果互认共享”为例，业务场景描述为：某二级医院完成生化检验后，需要把结果共享给区域平台，供三甲医院复诊时调阅。围绕这个场景，我们要追问五个问题：谁发起、谁接收、交换什么、什么时候交换、交换后做什么。答案会直接决定资源选型和字段范围。

把场景拆成可映射的需求条目时，建议采用“业务对象—数据元素—约束条件”的三段式。例如“患者身份”这一业务对象，可拆出姓名、性别、出生日期、身份证号、就诊卡号等数据元素；约束条件则包括：身份证号必须脱敏、就诊卡号仅在本院范围内有效、姓名允许为空但需记录数据来源。这样拆解后，需求条目天然带有可验证性，而不是一句“需要患者基本信息”的模糊表述。

提取过程中要特别区分三类需求：必须交换（如检验结果值、单位、参考范围）、条件交换（如患者过敏史，仅当本次检验涉及相关项目时携带）、可选交换（如检验设备型号，用于质量追溯）。这个分类直接决定后续映射范围与优先级，也是评审时最容易被忽略却最影响工期的地方。

二、定义映射范围与优先级

映射范围要回答“哪些字段进、哪些字段不进”。范围过宽会导致大量字段无源可映射，范围过窄则会在联调阶段反复返工。一个实用的做法是建立“源系统字段—FHIR路径—映射必要性”的三列表，逐条确认。对于源系统中存在但FHIR中无对应元素的字段，应明确处理策略：扩展（Extension）、忽略、或放入文本备注（note）。

优先级划分建议按“业务价值×实现难度”两个维度评估。高价值低难度的条目放入第一期，例如患者标识、检验项目编码、结果值；高价值高难度的条目（如跨院患者主索引匹配）放入第二期并单独设计；低价值条目原则上不纳入首期范围。优先级不是技术排序，而是交付节奏的承诺，必须在规格说明书中写明每期的范围边界。

三、映射规格说明书的模板结构

一份可执行的映射规格说明书，至少应包含以下六个部分，且每部分都要有明确的填写要求，而不是留空等开发人员自行理解。

1. 文档标识与版本：规格编号、适用场景、源系统版本、目标FHIR版本（如R4）、编制人与评审人、生效日期。版本号必须与接口发布版本绑定，避免“文档是V1.2、接口是V1.5”的错位。

2. 范围声明：明确本期覆盖的资源类型（如Patient、Observation、DiagnosticReport）、不覆盖的资源、以及跨期边界。范围声明要具体到资源级别，不能只写“检验相关资源”。

3. 映射明细表：这是规格书的核心。每一行至少包含：源系统字段名、源数据类型与长度、FHIR资源与路径（如Observation.valueQuantity.value）、FHIR数据类型、转换规则、术语绑定（ValueSet/CodeSystem）、是否必填、异常处理策略。转换规则要写到可直接编码的程度，例如“性别代码1→male，2→female，0→unknown，其余→other并记录原始值”。

4. 术语映射表：列出所有需要编码转换的字段，包括本地代码、目标代码系统、映射方向（单向/双向）、未匹配时的处理方式。检验项目编码建议映射到LOINC，结果单位映射到UCUM，这两项是检验场景中最容易出问题的部分。

5. 异常与边界处理：规定空值、超长、非法编码、时间格式不一致时的处理策略。例如源系统出生日期为“不详”时，Patient.birthDate应留空并附加data-absent-reason扩展，而不是填一个默认日期。

6. 验收标准：每条映射规则对应的测试用例编号、预期输出、判定依据。验收标准要可执行，例如“给定源消息A，转换后Observation.code.coding.system为http://loinc.org，code为2345-7，且valueQuantity.unit为mg/dL”。

四、评审要点与常见问题

规格说明书评审不是走形式，重点看四件事。第一，完整性：业务场景中提到的每个数据元素，是否都能在映射明细表中找到对应行；找不到的，是遗漏还是有意排除，必须有结论。第二，可执行性：转换规则是否写到无需口头补充即可编码的程度。评审时可以让未参与编写的工程师试读一条规则，若能直接写出伪代码，说明粒度合格。第三，一致性：同一字段在不同资源中的映射规则是否统一，例如患者标识在Patient和Observation.subject中是否使用同一套标识系统。第四，可验证性：每条规则是否有对应的测试用例和预期结果，验收标准是否可自动断言。

五、一个可填写的映射明细行示例

以下给出一条检验结果值的映射明细行示例，字段和取值均为教学示例，实际项目需按源系统字典和FHIR版本调整。

源字段	FHIR路径	转换规则	术语绑定	必填	异常处理
RESULT_VALUE	Observation.valueQuantity.value	去除首尾空格，转为decimal；若含“<”或“>”，改用valueString并保留符号	—	是	空值→不生成value[x]，附加data-absent-reason
RESULT_UNIT	Observation.valueQuantity.unit / code	本地单位字典→UCUM代码；unit填可读名称，code填UCUM码	UCUM	是	未匹配→code留空，unit保留原文，标记待人工确认
TEST_CODE	Observation.code.coding.code	本地检验项目代码→LOINC代码，一对多时取首选映射	LOINC	是	未匹配→使用本地代码并附加local-code扩展

这张表的价值在于：开发人员可以直接据此编写转换逻辑，测试人员可以直接据此设计断言，业务方可以逐行确认是否符合预期。映射规格说明书的最终目标，就是让这三类人看同一份文档时，对“做什么、做到什么程度、怎么算做完了”没有歧义。