CDA是XML文档格式标准而非传输协议；需接收并校验符合CDA R2规范的XML文件，重点进行XSD结构校验与templateId、签名、时间等语义检查，避免仅做语法解析。
CDA 不是传输协议，而是 XML 文档格式标准；构建上传服务时，你实际是在「接收并校验一个符合 CDA R2 规范的 XML 文件」，而不是对接某个叫 “CDA 接口” 的东西。
什么是 CDA：别把它当成接口，它是带语义的 XML 文档
CDA（Clinical Document Architecture）本质是一套 XML Schema（CDA.xsd）和配套约束规则（如 Consol.xsd 或 CCD.xsd），定义了临床文档（如出院小结、影像报告）该有哪些头信息（
常见误解是以为“支持 CDA” 就等于“能收 XML”，结果上线后发现对方发来的 XML 虽然能被解析，但缺 templateId 值非法，导致业务系统拒收。这就是没做语义校验，只做了语法解析。
Java 后端接收 CDA 文件：用 DOM + XSD 校验，别只靠 DocumentBuilder
纯用 DocumentBuilderFactory 解析 XML 只能确认它“是 XML”，无法判断它“是不是合法 CDA”。必须叠加 XSD 校验，并检查关键业务约束：
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
-
DocumentBuilderFactory.setValidating(true)不够，它只校验 DTD；得用SchemaFactory加载CDA.xsd和扩展包（如 IHE PCC 的Consol.xsd） - 必须手动验证
root属性是否匹配预期（例如 CCD 要求2.16.840.1.113883.10.20.1），XSD 本身不强制这个 - 签名节点（
XMLSignature验签；若不存在，要确认业务是否允许无签名上传
SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
Schema schema = factory.newSchema(new StreamSource("CDA.xsd"));
Validator validator = schema.newValidator();
validator.validate(new StreamSource(request.getInputStream())); // 抛出 SAXException 表示结构非法
上传服务设计：别暴露原始 CDA XML 给前端，用中间 DTO 封装错误
直接让前端 POST /upload 一个 raw XML，会导致错误反馈极不友好——比如 XSD 校验失败时返回 500 和一堆 SAX 错误栈，前端没法提示用户“第 123 行缺少
- 定义清晰的上传响应 DTO，含
status: "VALID" | "SCHEMA_ERROR" | "SEMANTIC_ERROR"、lineNumber、message字段 - 对常见语义错误预埋检查：患者 ID 是否为空、时间格式是否为
YYYYMMDDHHMMSS、root是否符合 UUID 规范 - 拒绝
Content-Type: text/xml以外的请求，防止用户误传 PDF 或 ZIP
部署时容易忽略的坑：编码、命名空间、时区
CDA 对字符编码、命名空间前缀、时间精度有硬性要求，但开发环境常掩盖问题：
- XML 声明必须是
，用ISO-8859-1会导致中文乱码且校验失败 -
v3或大小写错误都会使 XPath 查找失效 - 所有时间字段（
）必须用 UTC 时间（末尾带Z），本地时区时间（如+0800）不被主流 CDA 工具链接受
真正卡住上线的，往往不是解析逻辑，而是某家医院上传的 CDA 里 extension 带了不可见空格，或用了全角数字——这种细节必须在日志里打印原始字节流才能定位。
