简介这是一款专为医疗信息化场景设计的轻量工具旨在生成符合HL7 CDA标准临床文档架构的XML文件面向需要处理电子病历、检验报告等结构化数据的开发与实施人员可显著降低手工编写CDA文档的难度与出错率并提升跨系统共享的效率。资源包共5个文件EXE可执行程序用于生成与解析CDA示例XML展示最小化标准实例XSL样式表可在浏览器中格式化渲染CSV提供LOINC诊断编码映射PDF手册则完整说明部署与使用整体压缩后仅443KB。目前已有545人学习/下载属于即下即用的实用型工具包。通过运行带GUI的EXE、对照最小示例与手册读者既能快速产出合规CDA文档也能拆解文档结构、模板字段和编码映射为院内系统集成或二次开发提供可复用参考。1. 生成 CDA 文件的小程序先搞明白它到底在解决什么问题接到“写一个小程序生成 CDA 文件”这个需求多半是医院在做电子病历共享、互联互通评审或者区域平台要求把出院小结、检验报告上报成标准 XML。CDA 全称 Clinical Document Architecture是 HL7 组织定义的临床文档结构标准落地到工程上就是一个 XML 文件但它的约束比普通 XML 严格得多。某医院报一份出院小结被平台退回来三次一次说 templateId 不匹配一次说时间格式不带时区一次说诊断代码没按 ICD-10 编码。标题里的“小程序”不是微信小程序而是指一个本地命令行小工具读入结构化临床数据输出一份能通过校验的 CDA 文档。适合正在做医院信息集成、区域平台对接、或者被领导安排“把报告转成标准格式”的后端工程师看。2. 写生成器之前先拆 CDA 文档结构和模板 ID很多团队拿到 CDA 需求的第一反应是找个 XML 模板改改结果改出来的文档平台不认。CDA 不是普通 XML它的 Header 部分描述了“这份文档是谁、为谁、记录了什么”Body 部分承载临床内容而整份文档的合法性由模板 ID 和代码系统决定。这章先把结构和选型讲清楚再动手写代码可以少走很多弯路。2.1 CDA 文件的最小骨架Header 里的固定元素与 typeIdCDA R2 的根元素是 ClinicalDocument命名空间是 urn:hl7-org:v3。整个文档分成 Header 和 Body 两段Header 是文档元数据Body 是临床内容。Header 里的元素分必选和可选但实际接入平台时几乎每个项目都会在此基础上叠加自己的模板约束。表CDA Header 常用元素清单元素出现要求取值示例作用typeId必选1 个root2.16.840.1.113883.1.3extensionPOCD_HD000040告诉解析器这是 CDA R2templateId必选1 个或多个按对接平台模板填写告诉解析器套用哪套约束id必选1 个UUID 转字符串文档实例唯一标识code必选1 个LOINC 编码文档类型如出院小结title可选“出院小结”人类可读的标题effectiveTime必选1 个201403081200000800文档生成时间confidentialityCode必选1 个codeN保密级别recordTarget必选1 个包含患者信息记录对象author必选1 个医生或系统文档作者custodian必选1 个医院机构信息保管机构typeId 是固定值root 和 extension 都不能改解析器看到这个值就知道按 CDA R2 处理。templateId 则是接入平台给的模板标识这个值直接决定平台用什么规则校验你的文档。常见错误是以为 templateId 也可以自己随便编一个结果平台返回“模板不匹配”。2.2 Structured Body 与 Non-XML Body两种内容承载方式怎么选CDA Body 有两种形态。Structured Body 是结构化的由多个 section 组成每个 section 里有人类可读的 text 和机器可读的 entry平台能从里面抽出诊断、用药、检验结果等结构化数据。Non-XML Body 则是把 PDF、图片等原始文件用 Base64 编码嵌入 XML平台能看但不能直接抽取数据。实际项目里这两者不是二选一。某区域平台的要求是结构化数据必须放在 Structured Body 里供系统抓取原始报告 PDF 同时以 Non-XML Body 嵌入存档。我一般建议先做 Structured Body因为结构化数据的映射工作量大越早暴露问题越好Non-XML Body 相对简单留到后面处理也不迟。判断用哪种 Body 也看场景。如果只是院内留档、人工查阅Non-XML Body 嵌入 PDF 就够了。如果要做数据上报、互认、统计分析必须做 Structured Body。平台通常会在对接文档里写明要求按对方文档来最稳妥。2.3 两条实现路线XML 模板替换 vs 对象树构建生成 CDA 的主流做法有两种。一是用模板引擎比如 Jinja2 或 FreeMarker把 XML 写成模板用变量替换数据。二是用编程语言直接构建对象树比如 Python 的 lxml 或 Java 的 JAXB先构造元素节点再序列化成 XML。模板路线的优点是上手快结构固定的场景下代码量少缺点是列表循环、条件分支一多模板里全是 if 和 for改起来容易出错。对象树路线的优点是命名空间、属性都通过 API 设置不容易漏数据结构复杂时更好维护缺点是最开始写的代码多一点。我最开始做生成器时直接上了模板引擎结果模板里命名空间写错一个前缀排查了大半天。后来改成用 lxml 构建对象树虽然代码多了几十行但每个节点都清清楚楚。如果你的项目只需要固定一两个模板用模板替换够用如果要做多文档类型、多院区多模板适配建议直接走对象树路线。表两种实现路线对比维度模板引擎方案对象树方案上手速度快稍慢模板数量少时维护简单略繁琐模板数量多、结构复杂时模板容易膨胀易维护逻辑清晰命名空间控制依赖手写模板API 设置不易漏适合场景固定单一模板多模板、多文档类型3. 从零生成一份可校验的 CDA最小可运行代码逐段拆解选定了 lxml 对象树路线这章直接写代码。先构造 Header再往 Structured Body 里填诊断信息最后讲批量生成时命名空间和版本的坑。代码都按可运行的标准写复制到本地改一改就能用。3.1 Python lxml 生成 CDA Header 的最小实现下面的代码生成一份最简 CDA Header包含 typeId、templateId、id、code、effectiveTime、recordTarget 等关键元素。from lxml import etree from uuid import uuid4 from datetime import datetime NSMAP {None: urn:hl7-org:v3} # 默认命名空间 def build_header(): doc etree.Element(ClinicalDocument, nsmapNSMAP) # typeId 固定用于识别 CDAR2 type_id etree.SubElement(doc, typeId) type_id.set(root, 2.16.840.1.113883.1.3) type_id.set(extension, POCD_HD000040) # templateId接入平台给定必须一字不差 tpl etree.SubElement(doc, templateId) tpl.set(root, 2.16.840.1.113883.10.20.22.1.1) # 文档实例 ID每次生成都用 UUID保证唯一 doc_id etree.SubElement(doc, id) doc_id.set(root, str(uuid4())) # 文档类型 code出院小结对应 LOINC 18842-5 code etree.SubElement(doc, code) code.set(code, 18842-5) code.set(codeSystem, 2.16.840.1.113883.6.1) code.set(codeSystemName, LOINC) code.set(displayName, Discharge summary) title etree.SubElement(doc, title) title.text 出院小结 # 文档生成时间必须带时区偏移 eff etree.SubElement(doc, effectiveTime) eff.set(value, datetime.now().strftime(%Y%m%d%H%M%S0800)) conf etree.SubElement(doc, confidentialityCode) conf.set(code, N) conf.set(codeSystem, 2.16.840.1.113883.5.25) # recordTarget患者信息 rt etree.SubElement(doc, recordTarget) pr etree.SubElement(rt, patientRole) pid etree.SubElement(pr, id) pid.set(root, 2.16.840.1.113883.19.5) pid.set(extension, P123456) pn etree.SubElement(pr, patient) name etree.SubElement(pn, name) name.text 张三 gender etree.SubElement(pn, administrativeGenderCode) gender.set(code, M) gender.set(codeSystem, 2.16.840.1.113883.5.1) birth etree.SubElement(pn, birthTime) birth.set(value, 19800215) return doc代码里最需要注意的是 nsmap 的设置{None: urn:hl7-org:v3}让默认命名空间带上 HL7 V3 的 URI子元素不需要加前缀生成出来的 XML 是干净的。typeId 的 root 和 extension 是固定值解析器靠这个识别文档标准。id 用 UUID 字符串是为了保证每份文档实例唯一同样内容的文档重新生成也该换一个新 id。effectiveTime 格式是 HL7 时间戳%Y%m%d%H%M%S0800生成的结果类似 202403081530000800。这里强烈建议把时区写死为 0800不要依赖服务器默认时区后面避坑章节会展开说。administrativeGenderCode 的代码系统 2.16.840.1.113883.5.1 是 HL7 维护的性别编码M 代表男F 代表女不能直接填中文。主程序输出 XML 到文件时要按二进制写xml_bytes etree.tostring( build_header(), xml_declarationTrue, encodingUTF-8, pretty_printTrue ) with open(sample_cda.xml, wb) as f: f.write(xml_bytes)这里用wb二进制模式而不是文本模式是因为 Windows 下文本模式会把 UTF-8 编码重新转成 GBK导致声明和实际字节不一致平台解析时直接乱码。这个写法对跨平台部署尤其重要服务跑在 Linux 上问题不大但本地 Windows 调试时就能避免很多无用功。3.2 往 Structured Body 里写诊断section 与 observation 的层级Header 完成后继续往文档里加 Structured Body。下面代码演示了一个带诊断 section 的结构化 Body。def build_body(doc): sbody etree.SubElement(doc, structuredBody) component etree.SubElement(sbody, component) section etree.SubElement(component, section) # section.code 在对接模板里通常会指定 LOINC sec_code etree.SubElement(section, code) sec_code.set(nullFlavor, NI) # 先用占位接入时换成模板要求值 sec_code.set(codeSystem, 2.16.840.1.113883.6.1) sec_title etree.SubElement(section, title) sec_title.text 诊断 sec_text etree.SubElement(section, text) sec_text.text 社区获得性肺炎左肺下叶 # entry 是机器可读部分observation 表示一条诊断观察 entry etree.SubElement(section, entry) obs etree.SubElement(entry, observation) obs_code etree.SubElement(obs, code) obs_code.set(code, 282825002) obs_code.set(codeSystem, 2.16.840.1.113883.6.96) obs_code.set(displayName, Diagnosis) value etree.SubElement(obs, value) # xsi:type 必须用完整命名空间写法不能用 xsi:type value.set({http://www.w3.org/2001/XMLSchema-instance}type, CD) value.set(code, J18.9) value.set(codeSystem, 2.16.840.1.113883.6.3) value.set(displayName, 肺炎未特指)section 里的 code 我用了 nullFlavorNI 占位这是有意为之。CDA 规范允许 section.code 为空但实际对接模板通常会指定具体 LOINC比如出院诊断可能要求某个固定值接入时把nullFlavor删掉换成code和displayName即可。这里的占位写法保证 XML 合法同时提醒你这里需要按模板参数补全。observation 的 value 元素用了{http://www.w3.org/2001/XMLSchema-instance}type属性来指定值类型为 CD这是 CDA 里很常见也最容易写错的地方。如果写成value.set(xsi:type, CD)lxml 不会自动补命名空间生成出来的 XML 会缺少 xsi 前缀声明Schema 校验直接报 unbound prefix。诊断值用 ICD-10 编码 J18.9代码系统是 2.16.840.1.113883.6.3。医院 HIS 里存的中文诊断和 ICD 编码经常对不上这部分映射工作要在数据进生成器之前完成不要指望 CD 类型里只填 displayName 就能通过校验平台抽数据看的还是 code。3.3 批量生成几十份文档时命名空间前缀与版本号怎么处理lxml 在默认情况下会给无前缀命名空间生成 ns0 前缀比如ns0:ClinicalDocument。语义上没有错Schema 校验也能过但有的平台解析器写得不严谨只认固定的元素名看到 ns0 前缀直接解析失败。解决方式是在创建根元素时指定 nsmap如前面的代码所示把 None 映射到 urn:hl7-org:v3序列化出来就没有前缀。另一个批量生成容易忽略的是版本管理。同一份患者的多份修订文档不应该每次都用新 id而应该用 setId 标识同一文档族versionNumber 递增。做法如下set_id etree.SubElement(doc, setId) set_id.set(root, 2.16.840.1.113883.19.5.8888.123) set_id.set(extension, 20240308) ver etree.SubElement(doc, versionNumber) ver.set(value, 2) # 从业务系统读取上一次版本号 1这样平台能区分修订记录而不是把新文档当成独立文档存两份。 setId 的 root 可以是产品线固定的 OIDextension 可以用日期或者业务主键。versionNumber 是字符串类型直接填数字字符串即可。4. 真实临床数据映射从 HIS 字段到 XML 节点的转换参数代码骨架搭好后真正花时间的是把门诊、住院、检验系统的字段映射到 CDA 节点上。这章给出一份常用映射表和三个最常返工的参数处理方式。4.1 常用 HIS 字段到 CDA 节点的映射表不同医院的 HIS 表结构差异很大但映射关系有共性。我一般会先做一张映射表发给对接方确认确认后再写转换代码。表常见 HIS 字段与 CDA 节点映射HIS 系统字段CDA 节点取值说明处理要点患者编号recordTarget/patientRole/idextensionP123456root 用机构 OID患者姓名patientRole/patient/name张三直接放文本性别administrativeGenderCodecodeM必须映射成 HL7 编码出生日期birthTime19800215格式 YYYYMMDD就诊时间componentOf/encompassingEncounter/effectiveTimelow入院时间high出院时间必须带时区偏移就诊科室serviceProviderOrganization/name呼吸内科有的平台要求放 assignedEntity主治医生author/assignedAuthor/assignedPerson/name李医生没有医生时填系统账号诊断描述section/text中文描述平台可读诊断编码observation/valueICD-10 编码不要只放中文报告 PDFnonXMLBody/textBase64mediaType 要匹配映射表落地时注意两点。一是就诊科室的位置在不同模板里有差异有的放在 componentOf/encompassingEncounter 里有的放在 custodian 相关的组织结构里需要按对接方模板确认。二是医生为空时不要直接跳过 author 元素CDA 规范要求至少有一个 author可以用系统账号或 default value 兜底。4.2 代码系统归一性别、诊断、检验结果三个重灾区CDA 对取值的要求是“代码 代码系统”不接受中文原始值。性别在 HIS 里存的是“男”“女”到 CDA 里要映射成 HL7 的 M、F、U未知。诊断在 HIS 里可能存的是带标点的 ICD-10 描述生成前要清洗成标准编码。检验项目是重灾区LIS 里几乎全是本地码极少有 LOINC。处理检验项目的常见做法是本地码 translation 指向 LOINC。也就是说原始 code 保留 LIS 本地编码codeSystem 用本机构申请的 OID然后加一个 translation 元素表示“这个本地码等价于某个 LOINC 编码”。code.set(code, LIS-BG-001) code.set(codeSystem, 2.16.840.1.113883.19.5.998) code.set(displayName, 白细胞计数) trans etree.SubElement(code, translation) trans.set(code, 58410-2) trans.set(codeSystem, 2.16.840.1.113883.6.1) trans.set(displayName, WBC)这样既保留了原始数据的可追溯性又给平台提供了标准编码入口。如果本地码确实没有对应 LOINC不要硬编一个上去宁可只带本地码让平台那边知道这个项目还没映射完成。编造 LOINC 映射比不映射更糟因为解析方会按 LOINC 去匹配规则匹配错了影响临床决策。4.3 中文 PDF 报告嵌入Non-XML Body 的 Base64 写法有些平台要求原始报告全文嵌入 CDA一般是 PDF。这时候用 nonXMLBodyimport base64 with open(report.pdf, rb) as fp: b64 base64.b64encode(fp.read()).decode(ascii) nxml etree.SubElement(doc, nonXMLBody) text etree.SubElement(nxml, text) text.set(mediaType, application/pdf) text.set(representation, B64) text.text b64mediaType 要用 IANA 注册的标准类型application/pdf、image/jpeg 最常见。representation 固定写 B64说明内容是 Base64 编码。这里有个隐藏问题部分生成器把 Base64 字符串按每 76 个字符插入换行CDA 规范允许换行但有的平台解析时没做换行处理导致解码失败。Python 的 base64.b64encode 默认不换行这是最安全的。嵌入前要先确认平台有没有文件大小限制。常见限制在 10MB 到 20MB 之间如果报告扫描件很大我一般会先用 PDF 压缩工具处理到 2MB 以内再嵌入。还有一点Base64 只能嵌“文件”不能嵌“路径”不要图省事把文件路径塞进去平台不可能从你的服务器路径去读文件。5. CDA 生成中的五个典型翻车现象现象、原因、解决这章写的是生成 CDA 文件时最常见的五类故障每一条都是真实对接过程中被平台打回来的典型案例。按“现象 → 原因 → 解决”的顺序写排错时可以直接对照。5.1 平台反馈 templateId 不匹配或模板缺失现象生成的 XML 用 Schema 校验完全通过但上传到区域平台后被退回报错信息是 templateId 不存在或者与预期模板不匹配。原因CDA 规范本身只要求 templateId 存在但具体值必须由对接平台指定。很多开发者在写生成器时随手填了一个模板 ID或者在网上复制的示例值平台按自己的模板库比对时自然找不到。解决找对接方要“电子病历共享文档模板”或“CDA 模板清单”把 templateId 的 root 和 extension 一字不差填进代码。注意平台可能要求多个 templateId比如一个标识文档总体类型一个标识具体业务的约束模板两个都写上且顺序不能乱。拿到模板后把 templateId 从配置读取不要硬编码在代码里后续平台升级模板时不用改代码。5.2 effectiveTime 与就诊时间相差八小时现象文档里 effectiveTime 写的是 20140308120000平台解析后变成 20140308040000恰好差八小时。原因生成时没有带时区偏移或者写的是 0000平台按 UTC 解析后换算到北京时间就少了八小时。服务器时区和数据库时区如果不一致还会出现生成时间和入库时间两个结果。解决统一在程序入口用固定时区生成时间。from datetime import datetime, timezone, timedelta cst timezone(timedelta(hours8)) now datetime.now(cst).strftime(%Y%m%d%H%M%S0800)这段代码把时区固定为东八区无论服务器实际时区是什么生成的时间字符串都带 0800。不要用datetime.now()直接格式化因为它是服务器本地时间部署到 UTC 的机器上就会出问题。CDA 里凡是时间字段都建议用这个模式处理。5.3 中文内容乱码或解析中断现象XML 声明写的是 UTF-8平台也按 UTF-8 解析但中文显示乱码严重的直接报 parse error。原因文件写入时用了文本模式Windows 环境下 Python 会按 GBK 编码写入虽然 XML 声明写的是 UTF-8实际字节是 GBK解析器按 UTF-8 解码自然出错。另一种情况是 etree.tostring 时没指定 encoding默认生成的是不带 XML 声明的字符串别人拿到手不知道按什么编码读。解决序列化和写文件统一按前面的写法来encodingUTF-8加wb二进制模式。写完文件后随手检查第一行确保是?xml version1.0 encodingUTF-8?再检查字节里有没有乱码。一个小习惯用file sample_cda.xml看一眼编码能避免很多不必要的来回。5.4 CDA 里嵌了 PDF 但平台打不开现象平台能解析 XML但点击预览报告时提示文件损坏或空白。原因最常见的是 Base64 内容中间被插入了换行符解析方解码时没有忽略换行。另一个原因是 mediaType 声明和实际内容不符比如嵌的是 JPEG 扫描件但声明成 application/pdf。解决代码里用base64.b64encode(...).decode(ascii)默认不换行。如果数据经过了别的环节生成前检查一下字符串里有没有\n有就替换掉。嵌入前本地先解码验证一次echo 这里是base64内容 | base64 -d /tmp/check.pdf file /tmp/check.pdffile命令能看出解码后的文件类型是否和 mediaType 一致。不一致就去检查源文件路径是不是拿错了。5.5 文档 id 重复导致平台覆盖历史记录现象同一患者的第二次上报成功后平台里查不到第一次的记录只剩最新一条。原因document id 用了固定值比如用患者 ID 或某个业务单号直接作为 id 的 extension平台按 id 做唯一性判断新文档覆盖旧文档。解决id 每次生成都用 UUID保证全局唯一。setId 用于表示“这是同一业务文档的不同版本”versionNumber 递增。三者配合doc_id.set(root, str(uuid4())) set_id.set(root, 2.16.840.1.113883.19.5.8888.123) set_id.set(extension, 20240308) ver.set(value, 3)这样平台能知道这两份文档是同一份出院小结的第 2 版和第 3 版而不是两份完全独立的文档。6. 生成之后如何验证与批量自检一条命令跑完全部样例CDA 生成器写完验证环节不能省。这章讲我用什么命令做 Schema 校验、怎么批量跑历史样例、以及上线前我必查的三个习惯。6.1 用 xmllint 做 Schema 校验的最小命令本机有 CDA R2 的 schema 文件时校验一条命令xmllint --noout --schema POCD_MT000040.xsd sample_cda.xmlPOCD_MT000040.xsd 是 CDA R2 的根 schema同一目录下要有 datatypes.xsd、vocab.xsd、NarrativeBlock.xsd 等依赖文件缺一不可。报错时看前三条就够了后面的错误大多是前面错误的连锁反应。没有本地 schema 也可以用 Python 的 lxml 做同样校验但 xmllint 的优势是批量快、输出清楚。提一句Schema 校验通过的文档未必能过平台的 Schematron 校验平台还会查 recordTarget 是否存在、时间字段是否带时区等约束这部分靠后续自检脚本兜底。6.2 批量自检脚本一次跑完所有样例项目里通常有几十份或几百份历史样例不可能手动逐份校验。我习惯写一个简单的 bash 脚本批量跑#!/bin/bash for f in samples/*.xml; do if xmllint --noout --schema POCD_MT000040.xsd $f 2/tmp/err; then echo OK $f else echo FAIL $f head -n 5 /tmp/err fi done这个脚本配合定时任务或 CI每次代码改动后自动跑一遍全部样例能防止修改一个参数导致其他文档集体翻车。另外再查一下文档 id 是否重复grep -o id root[^]* samples/*.xml | sort | uniq -d有输出就说明两份文档用了同一个 id按上一章的规则改成 UUID 就好。6.3 上线前我必查的三个习惯第一每换一次模板就用校验脚本重新跑一遍全部历史样例。平台模板升级是常态旧文档可能还是合法的但新文档必须按新模板来。第二把 templateId、codeSystem、OID 这些参数从代码里抽出来放到配置文件里。生成器写死这些值的后果是平台一改模板你得改代码重新部署放配置里的话改一行配置就能适配新模板。第三保留一份“被平台打回”的文档样本。某公司项目里有一份专门存放退回文档的目录每次退回后对着错误信息修正生成器修完再跑一次完整校验。我第一次做 CDA 生成器时因为少了一个 templateId整批报告被退回重新生成后才意识到前置自检的重要性。后来我在生成器里加了一个--check参数先输出校验报告再决定是否提交。希望帮到你。本文还有配套的精品资源点击获取
简介这是一款专为医疗信息化场景设计的轻量工具旨在生成符合HL7 CDA标准临床文档架构的XML文件面向需要处理电子病历、检验报告等结构化数据的开发与实施人员可显著降低手工编写CDA文档的难度与出错率并提升跨系统共享的效率。资源包共5个文件EXE可执行程序用于生成与解析CDA示例XML展示最小化标准实例XSL样式表可在浏览器中格式化渲染CSV提供LOINC诊断编码映射PDF手册则完整说明部署与使用整体压缩后仅443KB。目前已有545人学习/下载属于即下即用的实用型工具包。通过运行带GUI的EXE、对照最小示例与手册读者既能快速产出合规CDA文档也能拆解文档结构、模板字段和编码映射为院内系统集成或二次开发提供可复用参考。1. 生成 CDA 文件的小程序先搞明白它到底在解决什么问题接到“写一个小程序生成 CDA 文件”这个需求多半是医院在做电子病历共享、互联互通评审或者区域平台要求把出院小结、检验报告上报成标准 XML。CDA 全称 Clinical Document Architecture是 HL7 组织定义的临床文档结构标准落地到工程上就是一个 XML 文件但它的约束比普通 XML 严格得多。某医院报一份出院小结被平台退回来三次一次说 templateId 不匹配一次说时间格式不带时区一次说诊断代码没按 ICD-10 编码。标题里的“小程序”不是微信小程序而是指一个本地命令行小工具读入结构化临床数据输出一份能通过校验的 CDA 文档。适合正在做医院信息集成、区域平台对接、或者被领导安排“把报告转成标准格式”的后端工程师看。2. 写生成器之前先拆 CDA 文档结构和模板 ID很多团队拿到 CDA 需求的第一反应是找个 XML 模板改改结果改出来的文档平台不认。CDA 不是普通 XML它的 Header 部分描述了“这份文档是谁、为谁、记录了什么”Body 部分承载临床内容而整份文档的合法性由模板 ID 和代码系统决定。这章先把结构和选型讲清楚再动手写代码可以少走很多弯路。2.1 CDA 文件的最小骨架Header 里的固定元素与 typeIdCDA R2 的根元素是 ClinicalDocument命名空间是 urn:hl7-org:v3。整个文档分成 Header 和 Body 两段Header 是文档元数据Body 是临床内容。Header 里的元素分必选和可选但实际接入平台时几乎每个项目都会在此基础上叠加自己的模板约束。表CDA Header 常用元素清单元素出现要求取值示例作用typeId必选1 个root2.16.840.1.113883.1.3extensionPOCD_HD000040告诉解析器这是 CDA R2templateId必选1 个或多个按对接平台模板填写告诉解析器套用哪套约束id必选1 个UUID 转字符串文档实例唯一标识code必选1 个LOINC 编码文档类型如出院小结title可选“出院小结”人类可读的标题effectiveTime必选1 个201403081200000800文档生成时间confidentialityCode必选1 个codeN保密级别recordTarget必选1 个包含患者信息记录对象author必选1 个医生或系统文档作者custodian必选1 个医院机构信息保管机构typeId 是固定值root 和 extension 都不能改解析器看到这个值就知道按 CDA R2 处理。templateId 则是接入平台给的模板标识这个值直接决定平台用什么规则校验你的文档。常见错误是以为 templateId 也可以自己随便编一个结果平台返回“模板不匹配”。2.2 Structured Body 与 Non-XML Body两种内容承载方式怎么选CDA Body 有两种形态。Structured Body 是结构化的由多个 section 组成每个 section 里有人类可读的 text 和机器可读的 entry平台能从里面抽出诊断、用药、检验结果等结构化数据。Non-XML Body 则是把 PDF、图片等原始文件用 Base64 编码嵌入 XML平台能看但不能直接抽取数据。实际项目里这两者不是二选一。某区域平台的要求是结构化数据必须放在 Structured Body 里供系统抓取原始报告 PDF 同时以 Non-XML Body 嵌入存档。我一般建议先做 Structured Body因为结构化数据的映射工作量大越早暴露问题越好Non-XML Body 相对简单留到后面处理也不迟。判断用哪种 Body 也看场景。如果只是院内留档、人工查阅Non-XML Body 嵌入 PDF 就够了。如果要做数据上报、互认、统计分析必须做 Structured Body。平台通常会在对接文档里写明要求按对方文档来最稳妥。2.3 两条实现路线XML 模板替换 vs 对象树构建生成 CDA 的主流做法有两种。一是用模板引擎比如 Jinja2 或 FreeMarker把 XML 写成模板用变量替换数据。二是用编程语言直接构建对象树比如 Python 的 lxml 或 Java 的 JAXB先构造元素节点再序列化成 XML。模板路线的优点是上手快结构固定的场景下代码量少缺点是列表循环、条件分支一多模板里全是 if 和 for改起来容易出错。对象树路线的优点是命名空间、属性都通过 API 设置不容易漏数据结构复杂时更好维护缺点是最开始写的代码多一点。我最开始做生成器时直接上了模板引擎结果模板里命名空间写错一个前缀排查了大半天。后来改成用 lxml 构建对象树虽然代码多了几十行但每个节点都清清楚楚。如果你的项目只需要固定一两个模板用模板替换够用如果要做多文档类型、多院区多模板适配建议直接走对象树路线。表两种实现路线对比维度模板引擎方案对象树方案上手速度快稍慢模板数量少时维护简单略繁琐模板数量多、结构复杂时模板容易膨胀易维护逻辑清晰命名空间控制依赖手写模板API 设置不易漏适合场景固定单一模板多模板、多文档类型3. 从零生成一份可校验的 CDA最小可运行代码逐段拆解选定了 lxml 对象树路线这章直接写代码。先构造 Header再往 Structured Body 里填诊断信息最后讲批量生成时命名空间和版本的坑。代码都按可运行的标准写复制到本地改一改就能用。3.1 Python lxml 生成 CDA Header 的最小实现下面的代码生成一份最简 CDA Header包含 typeId、templateId、id、code、effectiveTime、recordTarget 等关键元素。from lxml import etree from uuid import uuid4 from datetime import datetime NSMAP {None: urn:hl7-org:v3} # 默认命名空间 def build_header(): doc etree.Element(ClinicalDocument, nsmapNSMAP) # typeId 固定用于识别 CDAR2 type_id etree.SubElement(doc, typeId) type_id.set(root, 2.16.840.1.113883.1.3) type_id.set(extension, POCD_HD000040) # templateId接入平台给定必须一字不差 tpl etree.SubElement(doc, templateId) tpl.set(root, 2.16.840.1.113883.10.20.22.1.1) # 文档实例 ID每次生成都用 UUID保证唯一 doc_id etree.SubElement(doc, id) doc_id.set(root, str(uuid4())) # 文档类型 code出院小结对应 LOINC 18842-5 code etree.SubElement(doc, code) code.set(code, 18842-5) code.set(codeSystem, 2.16.840.1.113883.6.1) code.set(codeSystemName, LOINC) code.set(displayName, Discharge summary) title etree.SubElement(doc, title) title.text 出院小结 # 文档生成时间必须带时区偏移 eff etree.SubElement(doc, effectiveTime) eff.set(value, datetime.now().strftime(%Y%m%d%H%M%S0800)) conf etree.SubElement(doc, confidentialityCode) conf.set(code, N) conf.set(codeSystem, 2.16.840.1.113883.5.25) # recordTarget患者信息 rt etree.SubElement(doc, recordTarget) pr etree.SubElement(rt, patientRole) pid etree.SubElement(pr, id) pid.set(root, 2.16.840.1.113883.19.5) pid.set(extension, P123456) pn etree.SubElement(pr, patient) name etree.SubElement(pn, name) name.text 张三 gender etree.SubElement(pn, administrativeGenderCode) gender.set(code, M) gender.set(codeSystem, 2.16.840.1.113883.5.1) birth etree.SubElement(pn, birthTime) birth.set(value, 19800215) return doc代码里最需要注意的是 nsmap 的设置{None: urn:hl7-org:v3}让默认命名空间带上 HL7 V3 的 URI子元素不需要加前缀生成出来的 XML 是干净的。typeId 的 root 和 extension 是固定值解析器靠这个识别文档标准。id 用 UUID 字符串是为了保证每份文档实例唯一同样内容的文档重新生成也该换一个新 id。effectiveTime 格式是 HL7 时间戳%Y%m%d%H%M%S0800生成的结果类似 202403081530000800。这里强烈建议把时区写死为 0800不要依赖服务器默认时区后面避坑章节会展开说。administrativeGenderCode 的代码系统 2.16.840.1.113883.5.1 是 HL7 维护的性别编码M 代表男F 代表女不能直接填中文。主程序输出 XML 到文件时要按二进制写xml_bytes etree.tostring( build_header(), xml_declarationTrue, encodingUTF-8, pretty_printTrue ) with open(sample_cda.xml, wb) as f: f.write(xml_bytes)这里用wb二进制模式而不是文本模式是因为 Windows 下文本模式会把 UTF-8 编码重新转成 GBK导致声明和实际字节不一致平台解析时直接乱码。这个写法对跨平台部署尤其重要服务跑在 Linux 上问题不大但本地 Windows 调试时就能避免很多无用功。3.2 往 Structured Body 里写诊断section 与 observation 的层级Header 完成后继续往文档里加 Structured Body。下面代码演示了一个带诊断 section 的结构化 Body。def build_body(doc): sbody etree.SubElement(doc, structuredBody) component etree.SubElement(sbody, component) section etree.SubElement(component, section) # section.code 在对接模板里通常会指定 LOINC sec_code etree.SubElement(section, code) sec_code.set(nullFlavor, NI) # 先用占位接入时换成模板要求值 sec_code.set(codeSystem, 2.16.840.1.113883.6.1) sec_title etree.SubElement(section, title) sec_title.text 诊断 sec_text etree.SubElement(section, text) sec_text.text 社区获得性肺炎左肺下叶 # entry 是机器可读部分observation 表示一条诊断观察 entry etree.SubElement(section, entry) obs etree.SubElement(entry, observation) obs_code etree.SubElement(obs, code) obs_code.set(code, 282825002) obs_code.set(codeSystem, 2.16.840.1.113883.6.96) obs_code.set(displayName, Diagnosis) value etree.SubElement(obs, value) # xsi:type 必须用完整命名空间写法不能用 xsi:type value.set({http://www.w3.org/2001/XMLSchema-instance}type, CD) value.set(code, J18.9) value.set(codeSystem, 2.16.840.1.113883.6.3) value.set(displayName, 肺炎未特指)section 里的 code 我用了 nullFlavorNI 占位这是有意为之。CDA 规范允许 section.code 为空但实际对接模板通常会指定具体 LOINC比如出院诊断可能要求某个固定值接入时把nullFlavor删掉换成code和displayName即可。这里的占位写法保证 XML 合法同时提醒你这里需要按模板参数补全。observation 的 value 元素用了{http://www.w3.org/2001/XMLSchema-instance}type属性来指定值类型为 CD这是 CDA 里很常见也最容易写错的地方。如果写成value.set(xsi:type, CD)lxml 不会自动补命名空间生成出来的 XML 会缺少 xsi 前缀声明Schema 校验直接报 unbound prefix。诊断值用 ICD-10 编码 J18.9代码系统是 2.16.840.1.113883.6.3。医院 HIS 里存的中文诊断和 ICD 编码经常对不上这部分映射工作要在数据进生成器之前完成不要指望 CD 类型里只填 displayName 就能通过校验平台抽数据看的还是 code。3.3 批量生成几十份文档时命名空间前缀与版本号怎么处理lxml 在默认情况下会给无前缀命名空间生成 ns0 前缀比如ns0:ClinicalDocument。语义上没有错Schema 校验也能过但有的平台解析器写得不严谨只认固定的元素名看到 ns0 前缀直接解析失败。解决方式是在创建根元素时指定 nsmap如前面的代码所示把 None 映射到 urn:hl7-org:v3序列化出来就没有前缀。另一个批量生成容易忽略的是版本管理。同一份患者的多份修订文档不应该每次都用新 id而应该用 setId 标识同一文档族versionNumber 递增。做法如下set_id etree.SubElement(doc, setId) set_id.set(root, 2.16.840.1.113883.19.5.8888.123) set_id.set(extension, 20240308) ver etree.SubElement(doc, versionNumber) ver.set(value, 2) # 从业务系统读取上一次版本号 1这样平台能区分修订记录而不是把新文档当成独立文档存两份。 setId 的 root 可以是产品线固定的 OIDextension 可以用日期或者业务主键。versionNumber 是字符串类型直接填数字字符串即可。4. 真实临床数据映射从 HIS 字段到 XML 节点的转换参数代码骨架搭好后真正花时间的是把门诊、住院、检验系统的字段映射到 CDA 节点上。这章给出一份常用映射表和三个最常返工的参数处理方式。4.1 常用 HIS 字段到 CDA 节点的映射表不同医院的 HIS 表结构差异很大但映射关系有共性。我一般会先做一张映射表发给对接方确认确认后再写转换代码。表常见 HIS 字段与 CDA 节点映射HIS 系统字段CDA 节点取值说明处理要点患者编号recordTarget/patientRole/idextensionP123456root 用机构 OID患者姓名patientRole/patient/name张三直接放文本性别administrativeGenderCodecodeM必须映射成 HL7 编码出生日期birthTime19800215格式 YYYYMMDD就诊时间componentOf/encompassingEncounter/effectiveTimelow入院时间high出院时间必须带时区偏移就诊科室serviceProviderOrganization/name呼吸内科有的平台要求放 assignedEntity主治医生author/assignedAuthor/assignedPerson/name李医生没有医生时填系统账号诊断描述section/text中文描述平台可读诊断编码observation/valueICD-10 编码不要只放中文报告 PDFnonXMLBody/textBase64mediaType 要匹配映射表落地时注意两点。一是就诊科室的位置在不同模板里有差异有的放在 componentOf/encompassingEncounter 里有的放在 custodian 相关的组织结构里需要按对接方模板确认。二是医生为空时不要直接跳过 author 元素CDA 规范要求至少有一个 author可以用系统账号或 default value 兜底。4.2 代码系统归一性别、诊断、检验结果三个重灾区CDA 对取值的要求是“代码 代码系统”不接受中文原始值。性别在 HIS 里存的是“男”“女”到 CDA 里要映射成 HL7 的 M、F、U未知。诊断在 HIS 里可能存的是带标点的 ICD-10 描述生成前要清洗成标准编码。检验项目是重灾区LIS 里几乎全是本地码极少有 LOINC。处理检验项目的常见做法是本地码 translation 指向 LOINC。也就是说原始 code 保留 LIS 本地编码codeSystem 用本机构申请的 OID然后加一个 translation 元素表示“这个本地码等价于某个 LOINC 编码”。code.set(code, LIS-BG-001) code.set(codeSystem, 2.16.840.1.113883.19.5.998) code.set(displayName, 白细胞计数) trans etree.SubElement(code, translation) trans.set(code, 58410-2) trans.set(codeSystem, 2.16.840.1.113883.6.1) trans.set(displayName, WBC)这样既保留了原始数据的可追溯性又给平台提供了标准编码入口。如果本地码确实没有对应 LOINC不要硬编一个上去宁可只带本地码让平台那边知道这个项目还没映射完成。编造 LOINC 映射比不映射更糟因为解析方会按 LOINC 去匹配规则匹配错了影响临床决策。4.3 中文 PDF 报告嵌入Non-XML Body 的 Base64 写法有些平台要求原始报告全文嵌入 CDA一般是 PDF。这时候用 nonXMLBodyimport base64 with open(report.pdf, rb) as fp: b64 base64.b64encode(fp.read()).decode(ascii) nxml etree.SubElement(doc, nonXMLBody) text etree.SubElement(nxml, text) text.set(mediaType, application/pdf) text.set(representation, B64) text.text b64mediaType 要用 IANA 注册的标准类型application/pdf、image/jpeg 最常见。representation 固定写 B64说明内容是 Base64 编码。这里有个隐藏问题部分生成器把 Base64 字符串按每 76 个字符插入换行CDA 规范允许换行但有的平台解析时没做换行处理导致解码失败。Python 的 base64.b64encode 默认不换行这是最安全的。嵌入前要先确认平台有没有文件大小限制。常见限制在 10MB 到 20MB 之间如果报告扫描件很大我一般会先用 PDF 压缩工具处理到 2MB 以内再嵌入。还有一点Base64 只能嵌“文件”不能嵌“路径”不要图省事把文件路径塞进去平台不可能从你的服务器路径去读文件。5. CDA 生成中的五个典型翻车现象现象、原因、解决这章写的是生成 CDA 文件时最常见的五类故障每一条都是真实对接过程中被平台打回来的典型案例。按“现象 → 原因 → 解决”的顺序写排错时可以直接对照。5.1 平台反馈 templateId 不匹配或模板缺失现象生成的 XML 用 Schema 校验完全通过但上传到区域平台后被退回报错信息是 templateId 不存在或者与预期模板不匹配。原因CDA 规范本身只要求 templateId 存在但具体值必须由对接平台指定。很多开发者在写生成器时随手填了一个模板 ID或者在网上复制的示例值平台按自己的模板库比对时自然找不到。解决找对接方要“电子病历共享文档模板”或“CDA 模板清单”把 templateId 的 root 和 extension 一字不差填进代码。注意平台可能要求多个 templateId比如一个标识文档总体类型一个标识具体业务的约束模板两个都写上且顺序不能乱。拿到模板后把 templateId 从配置读取不要硬编码在代码里后续平台升级模板时不用改代码。5.2 effectiveTime 与就诊时间相差八小时现象文档里 effectiveTime 写的是 20140308120000平台解析后变成 20140308040000恰好差八小时。原因生成时没有带时区偏移或者写的是 0000平台按 UTC 解析后换算到北京时间就少了八小时。服务器时区和数据库时区如果不一致还会出现生成时间和入库时间两个结果。解决统一在程序入口用固定时区生成时间。from datetime import datetime, timezone, timedelta cst timezone(timedelta(hours8)) now datetime.now(cst).strftime(%Y%m%d%H%M%S0800)这段代码把时区固定为东八区无论服务器实际时区是什么生成的时间字符串都带 0800。不要用datetime.now()直接格式化因为它是服务器本地时间部署到 UTC 的机器上就会出问题。CDA 里凡是时间字段都建议用这个模式处理。5.3 中文内容乱码或解析中断现象XML 声明写的是 UTF-8平台也按 UTF-8 解析但中文显示乱码严重的直接报 parse error。原因文件写入时用了文本模式Windows 环境下 Python 会按 GBK 编码写入虽然 XML 声明写的是 UTF-8实际字节是 GBK解析器按 UTF-8 解码自然出错。另一种情况是 etree.tostring 时没指定 encoding默认生成的是不带 XML 声明的字符串别人拿到手不知道按什么编码读。解决序列化和写文件统一按前面的写法来encodingUTF-8加wb二进制模式。写完文件后随手检查第一行确保是?xml version1.0 encodingUTF-8?再检查字节里有没有乱码。一个小习惯用file sample_cda.xml看一眼编码能避免很多不必要的来回。5.4 CDA 里嵌了 PDF 但平台打不开现象平台能解析 XML但点击预览报告时提示文件损坏或空白。原因最常见的是 Base64 内容中间被插入了换行符解析方解码时没有忽略换行。另一个原因是 mediaType 声明和实际内容不符比如嵌的是 JPEG 扫描件但声明成 application/pdf。解决代码里用base64.b64encode(...).decode(ascii)默认不换行。如果数据经过了别的环节生成前检查一下字符串里有没有\n有就替换掉。嵌入前本地先解码验证一次echo 这里是base64内容 | base64 -d /tmp/check.pdf file /tmp/check.pdffile命令能看出解码后的文件类型是否和 mediaType 一致。不一致就去检查源文件路径是不是拿错了。5.5 文档 id 重复导致平台覆盖历史记录现象同一患者的第二次上报成功后平台里查不到第一次的记录只剩最新一条。原因document id 用了固定值比如用患者 ID 或某个业务单号直接作为 id 的 extension平台按 id 做唯一性判断新文档覆盖旧文档。解决id 每次生成都用 UUID保证全局唯一。setId 用于表示“这是同一业务文档的不同版本”versionNumber 递增。三者配合doc_id.set(root, str(uuid4())) set_id.set(root, 2.16.840.1.113883.19.5.8888.123) set_id.set(extension, 20240308) ver.set(value, 3)这样平台能知道这两份文档是同一份出院小结的第 2 版和第 3 版而不是两份完全独立的文档。6. 生成之后如何验证与批量自检一条命令跑完全部样例CDA 生成器写完验证环节不能省。这章讲我用什么命令做 Schema 校验、怎么批量跑历史样例、以及上线前我必查的三个习惯。6.1 用 xmllint 做 Schema 校验的最小命令本机有 CDA R2 的 schema 文件时校验一条命令xmllint --noout --schema POCD_MT000040.xsd sample_cda.xmlPOCD_MT000040.xsd 是 CDA R2 的根 schema同一目录下要有 datatypes.xsd、vocab.xsd、NarrativeBlock.xsd 等依赖文件缺一不可。报错时看前三条就够了后面的错误大多是前面错误的连锁反应。没有本地 schema 也可以用 Python 的 lxml 做同样校验但 xmllint 的优势是批量快、输出清楚。提一句Schema 校验通过的文档未必能过平台的 Schematron 校验平台还会查 recordTarget 是否存在、时间字段是否带时区等约束这部分靠后续自检脚本兜底。6.2 批量自检脚本一次跑完所有样例项目里通常有几十份或几百份历史样例不可能手动逐份校验。我习惯写一个简单的 bash 脚本批量跑#!/bin/bash for f in samples/*.xml; do if xmllint --noout --schema POCD_MT000040.xsd $f 2/tmp/err; then echo OK $f else echo FAIL $f head -n 5 /tmp/err fi done这个脚本配合定时任务或 CI每次代码改动后自动跑一遍全部样例能防止修改一个参数导致其他文档集体翻车。另外再查一下文档 id 是否重复grep -o id root[^]* samples/*.xml | sort | uniq -d有输出就说明两份文档用了同一个 id按上一章的规则改成 UUID 就好。6.3 上线前我必查的三个习惯第一每换一次模板就用校验脚本重新跑一遍全部历史样例。平台模板升级是常态旧文档可能还是合法的但新文档必须按新模板来。第二把 templateId、codeSystem、OID 这些参数从代码里抽出来放到配置文件里。生成器写死这些值的后果是平台一改模板你得改代码重新部署放配置里的话改一行配置就能适配新模板。第三保留一份“被平台打回”的文档样本。某公司项目里有一份专门存放退回文档的目录每次退回后对着错误信息修正生成器修完再跑一次完整校验。我第一次做 CDA 生成器时因为少了一个 templateId整批报告被退回重新生成后才意识到前置自检的重要性。后来我在生成器里加了一个--check参数先输出校验报告再决定是否提交。希望帮到你。本文还有配套的精品资源点击获取
