# 公共 API 与解释契约 v1

> 0.5.0发行源码新增查询/质量/计划/Native SDK及固定字典Implicit VR LE；本页旧阶段记录保留其原版本，当前增量见[数据处理指南](DATA_PROCESSING.zh-CN.md)。

C1 新增公开 SDK 集合入口（已纳入 0.3.0 快照；发布状态须回读核验）：`api/validation.convert_collection(inputs, policy, uid_seed, date_offsets)`。仅通过 `api/dicom`、`api/policy`、`api/validation` 即可构造、读取、转换并复核影像，无需导入内部 Context。详见[完整消费者](CONSUMER.zh-CN.md)。

该入口要求严格封闭集合，先检查 1–256 个对象、每对象至多 64 MiB、合计至多 128 MiB，再解析/验证所有输入、核对关联、准备单作业身份、逐对象转换并核对全部输出的关系。失败不返回部分结果，也不写文件。`ConvertedCollection.length()`、`private_bytes(index)` 保持输入顺序；索引错误返回类型化异常。`public_report()` 只包含数量、受限决定和 `release_authorized:false`。UID seed/每患者非零偏移必须由宿主显式提供；此可移植接口没有随机源（Native 目录接口另取 OS 熵），也不替代跨作业身份库、审核或事务性文件交付。旧 `convert(ValidatedObject, Context)` 继续兼容。

W0 建立公共门面，旧 `src/` 导入和已有命令继续可用。所有类型状态表示工厂在指定时刻完成过相应核验，不自动授予以后一次文件操作的许可。

| 导入路径（模块前缀 `001-Elsa/medseal/`） | 用途与边界 |
| --- | --- |
| `api/dicom` | 读取 Explicit VR LE / 固定字典 Implicit VR LE，写出规范化为 Explicit VR LE；单独解析不代表 IOD 合格或允许交付 |
| `api/dicom_json` | C3a 已纳入 0.3.0：25种VR的私有 JSON 编解码及 Part 10 重建；保留十进制 token、有界拒绝、pydicom 双向检查；不是公开报告/脱敏，详见[DICOM JSON](DICOM_JSON.zh-CN.md) |
| `api/policy` | 严格策略编译、规范摘要；身份、日期、结构字段不能被描述字段规则覆盖 |
| `api/validation` | `plan_collection` / `ConversionOptions.for_patients` 增加命名日期和不可变快照，预算只下调；`validate(Bytes)` 创建不受调用方数组修改影响的 `ValidatedObject`；`convert` 使用已准备的严格 Context，重新验证输出和写回值，返回 `ConvertedObject` |
| `api/explain` | 配置／对象／当前集合关系的公开解释，及版本化 `ValidationIssue`；原值、原 UID／日期、输入摘要、本机路径、偏移、替换内容与管理员规则 ID 不进入公开出口 |
| `api/authorization` | Native 受信任提供方；重新核验当前审核门禁或 Ed25519 包，创建 `ReviewEvidence`／`AuthorizedPackage`；输入 JSON 中的 true 不能创建这些状态 |
| `api/query` | `lookup/values/scalar/integer`、`select/project/group_counts/summary`；表格的 `private_csv/private_jsonl` 含私有原值，匿名清单只有计数 |
| `api/quality` | `check` 检查完整字节，`check_datasets` 检查元数据；`required_fields`、匿名问题及四类状态；`ready` 不授权 |
| `api/native` | Native 异步 `scan_directory/quality_directory/plan_directory` 与 `DatasetJob.execute`；无 Python、每作业身份、全新目录与边界取消 |

九个公共包的签名以各包 `pkg.generated.mbti` 为准。查询/质量/计划及 Native 的不同预算、报告 Schema、私有数据和取消边界见[数据处理指南](DATA_PROCESSING.zh-CN.md)。`api/validation` 是内存快照，`api/native` 计划会重新核对磁盘源字节，两者不能混同。

`private_dataset`、`private_bytes` 返回私有内容，只可用于受控处理和交付。解释类型没有这些内容的序列化出口。Bytes 在当前工具链不可变；每次读取 Dataset 都重新解析成独立数组。状态类型构造器为包内私有，没有“已审核=true”工厂，也没有未经核验的反序列化工厂。

Native Verifier 由受信任管理员配置，固定解释器和完整的八文件已审计运行时闭包的指纹，每次调用前后检查，并使用参数数组执行。它复用原审核门禁和独立签名验证器，合成上下文必须显式选择 `SyntheticTest`。这不防御恶意管理员、被替换的系统解释器依赖或本机存储管理员。审核、签名、发布与接收的实际操作仍在执行前重新检查；先前创建的类型实例不能跳过这些门禁。

新增入口：`medseal explain-object INPUT [--policy POLICY]`。它在内存中复用严格转换决定并输出 `explanation-v1.schema.json` 对应 JSON，不写入交付影像，不产生放行。读取、策略编译与验证错误也使用同一公开错误边界。旧 inspect、validate、explain 的诊断接口保留原私有语义，分享时使用新的公共接口和报告。

条件为 `met`、`not-met`、`unknown`，支持 Kleene 合取／析取。缺失的完整对象字段可判不成立；不完整对象中的缺失字段为 Unknown。SOP 缺失或不可解释为 Unknown。`require_condition` 对 Unknown 阻断，生产 SOP 模块分支调用此求值。现有模块必需性仍为部分集合，W3 已实现限定经典 CT 矩阵与独立接收验证；仍未覆盖所有 SOP 的完整 Type 1C/2C，不能从三值求值推出所有条件均已实现。

Rulebook 固定 DICOM 2025e：120 个属性的 VR/VM 已逐项比对官方 PS3.6 与固定 pydicom 字典；PS3.15 仅保留选定属性的参考链接与来源摘要，批量动作表摘录已移除；MedSeal 选择的保留／替换／平移动作有独立策略说明。21 项现有约束另行列出，必需字段类型、SOP 分支、文件头身份和时间精度不混入属性字典。141 个索引项均有实现与正反例入口。属性用例证明 VR/VM 分类接口；它们不是完整去标识动作、IOD 或 Annex E 的证据，独立预期由 W1 固定质量实验室验证；限定 CT 的体素/HU/几何由 W3 验证，均未扩张为完整 IOD。

四个[合成解释案例](examples/rule-explanation/condition-met.html)提供 JSON、无外部资源的 HTML 和 SVG。报告渲染器只读取结构路径、已登记规则和动作，丢弃其他输入；不显示患者假名或映射 UID，也不把所有诊断字段原样转成 HTML。

## 兼容与迁移

W0 把已有严格拒绝转为 `RuleViolation`，公开错误码为 `MEDSEAL-E530`；旧异常类型仍存在，异常消息不应当作稳定 API。Sequence 执行事件由含糊的 keep 改为 recurse，影像内容不因此改变。新增 `(0012,0063)` 方法标记的字典事实供输出重新验证；原有重复处理拒绝继续生效。

字典、规则与程序指纹变化会使旧运行计划、审核与缓存失效。这是预期行为。需要恢复旧作业时使用其原固定运行包；重新转换时从封存的原输入建立新作业，不能把已处理影像再次平移日期，也不能把旧审核改成当前摘要。

核验：`tools/verify_rulebook.py` 校验规则索引、生成漂移、Schema、实际解释、原值金丝雀和 Native 证据工厂；四后端测试覆盖规则条件及生产字段检查。结果记录代码范围的内容指纹和程序／规则指纹，提交前的运行明确记为 source_base_commit；远端 CI 制品由 GitHub 运行绑定提交 SHA。

> 文档核对：本文说明已与当前维护代码和实际入口核对；不扩大医疗/生产保证。见[文档账本](DOCUMENTATION_STATUS.zh-CN.md)；正式申报由韩桢本人完成。