AST 审计轨迹

概览

NextPDF Enterprise 把每一次 AST 变更都记录为仅追加、按文档维度的审计轨迹，并为下游管线生成语义有界、带引用锚点的 AST 分块。该轨迹支持审计与可追溯性工作流程。它不是法律鉴证，也不是对文档完整性的认证。

可用性与授权

本能力随 NextPDF Enterprise（nextpdf/enterprise）发行，并通过 Enterprise 层级的授权信封激活。没有该授权的部署不会加载本能力的类。比较各版本并获取授权。

安装

composer require nextpdf/enterprise:^3

概念总览

AstAuditTrailInterface 是记录契约。record($documentSourceHash, $log) 会把来自 Pro AST MutationLog 的每一条记录转换为一个 AstAuditEntry 并追加；用同一个文档哈希重复调用会累积记录。该实现按契约是仅追加的：一旦记录，某条记录便不能被修改或移除。findByDocument($hash) 按插入顺序返回某一文档的记录；count() 返回跨所有文档的总数。InMemoryAstAuditTrail 是参考实现。

AstAuditEntry 是对一次变更的不可变记录：文档源哈希、规范化节点 id、变更类型（updated / inserted / deleted）、从 0 开始的页索引、变更前/后的属性快照，以及该记录被记录下来的 UTC 时间。检索按文档哈希作用域隔离，因此审计历史在各文档之间保持隔离。

AstAwareChunker 以深度优先方式遍历 AST，并发出尊重文档结构的 AstChunk 实例：标题会开启一个新分块，叶子文本会累积直至到达配置的大小，而一个重叠窗口会在切分边界处保留连续性。每个分块都携带其第一个贡献节点的节点 id、页索引、包围盒，以及节点类型，因此下游系统可以引用一个精确的源位置。

本模块断言了什么

本模块记录变更历史并生成结构化分块。它不为完整性背书，也不提供法律鉴证。

• 审计轨迹在所配置的存储内按契约是仅追加的。防篡改与不可否认性是“你在何处、如何持久化并加盖时间戳”所具备的属性（参见 Evidence），而不是本模块自身做出的保证。
• 记录一次变更，是在记载它发生过。它并不验证或授权该改动。
• 分块引用指向源位置；它们是导航辅助，而非符合性主张。

审计轨迹支持审计工作流程；它不是法律鉴证，也不是审计认证。

层级边界

• NextPDF Core / Pro AST 提供 AST 模型与变更日志。
• NextPDF Enterprise AST（本页） 在那些变更之上增加仅追加、按文档维度的审计轨迹，以及带引用锚点的分块器。它消费 Pro 的变更日志；它并不替代 AST 模型。

为何如此设计

关键的设计决策是范围克制。本模块记录一次变更发生过；持久性、防篡改与不可否认性则委托给支撑存储和 Evidence 模块。这让承诺保持诚实：一种面向审计人员的记录保存辅助，而非本模块自身无法佐证的认证。检索以 documentSourceHash 为键，因此一份文档的历史绝不会渗入另一份。分块器把每个分块锚定到其第一个节点，并预先校验 maxChunkChars 与 overlapChars，因此引用保持精确。持久化与驻留仍掌握在操作方手中，因此同一套接口既可服务于 WORM 支撑的证据存储，也可服务于更轻量的管线。

设计背景：可交给审计人员的合规。

API 接口

类 / 接口	职责
AstAuditTrailInterface	仅追加记录与按文档维度检索的契约。
AstAuditEntry	对一次变更的不可变记录，带变更前/后快照。
InMemoryAstAuditTrail	参考的仅追加轨迹实现。
AstAwareChunker	尊重结构、带引用锚点的 AST 分块器。
AstChunk	一个分块，带节点 id、页索引、bbox 与节点类型。

代码示例 — 快速开始

$trail->record($documentSourceHash, $mutationLog);
$entries = $trail->findByDocument($documentSourceHash);

代码示例 — 生产

$trail->record($documentSourceHash, $mutationLog);

foreach ($trail->findByDocument($documentSourceHash) as $entry) {
    $logger->info('ast.audit', [
        'node'     => $entry->nodeId,
        'type'     => $entry->mutationType,
        'page'     => $entry->pageIndex,
        'recorded' => $entry->occurredAt->format(DATE_RFC3339),
    ]);
}
// Persist the trail in a WORM-backed store for tamper-evidence (see Evidence).

边界情况与注意事项

• 对同一个 MutationLog 记录两次会累积记录；如果你需要幂等性，请在上游去重。
• 内存轨迹不具持久性；生产部署应提供一个持久化的 AstAuditTrailInterface。
• 仅追加是存储的契约，而非密码学属性；请与 Evidence 打包搭配使用以实现防篡改。

性能

记录的开销与变更记录数量呈线性关系。分块是一次深度优先的 AST 遍历；成本随节点数量与配置的分块大小而变化。

安全说明

变更前/后快照可能包含文档文本。请把该轨迹在静态存储时当作敏感数据对待。仅追加契约阻止了通过本 API 进行的原地编辑，但持久性与防篡改取决于支撑存储。

数据驻留与个人信息缓解

变更快照可能携带从文档中提取的个人数据。持久化被委托给你的轨迹实现，因此驻留遵循你的存储。请对已记录的快照施加留存与最小化控制。

安全遥测与日志清洗

节点 id、变更类型、页索引与时间戳可以安全地记录。变更前/后快照可能包含文档内容；在转发到共享接收端之前请先脱敏。

符合性

行为	引用	状态
增量更新 / 完整性背景	ISO 32000-2:2020 §12.8	引用（作为防篡改的背景）

本表记录本模块所处的规范背景。审计轨迹是一种记录保存辅助，而非认证或法律鉴证。

FIPS 模式行为

本模块不执行任何密码学运算。用于防篡改的哈希、签名与时间戳由 Evidence、Security 与 Signature 模块处理。

威胁模型

输入是一份变更日志。缓解措施：仅追加记录契约、按文档维度作用域以隔离各历史，以及把持久性与防篡改委托给一个具备 WORM 能力的存储和 Evidence 模块。

行为契约

• 审计轨迹在所配置的存储内按契约是仅追加的：一旦记录，某条记录便不能通过本 API 被修改或移除。
• 每条记录都是对一次变更的不可变记录（文档源哈希、规范化节点 id、变更类型、页索引、变更前/后快照、被记录的 UTC 时间）；检索按文档哈希作用域隔离。
• 对同一份变更日志记录两次会累积记录——如果需要幂等性，请在上游去重。
• 分块器以深度优先方式遍历 AST，并发出尊重结构的分块，携带节点 id、页索引、包围盒与节点类型以便精确的源引用。
• 记录一次变更，是在记载它发生过；它并不验证或授权该改动，分块引用是导航辅助，而非符合性主张。

发布边界

本页仅描述外部可观察的行为与受支持的公开 API 接口。内部命名空间路径、辅助类、机制表、运维手册文件名，以及工单前缀均不在范围之内。

Core 回退

NextPDF Core / Pro AST 提供 AST 模型与变更日志。仅追加、按文档维度的审计轨迹与带引用锚点的分块器在 Core 层级没有等价物；Enterprise 接口消费变更日志，它并不替代 AST 模型。

Pro 回退

NextPDF Pro AST 提供 AST 模型与变更日志，但不提供仅追加、按文档维度的审计轨迹，也不提供带引用锚点的分块器。那些仅随 nextpdf/enterprise 包发行；Enterprise 接口消费 Pro 的变更日志。

Enterprise 边界说明

记录契约、按文档维度的检索，以及分块器，均在行为层面进行描述。参考的内存轨迹有文档说明；持久化由宿主提供，任何内部存储的内部机制都不属于公开接口范围。

部署边界

仅追加是存储的契约，而非密码学属性。操作方提供一个持久化的轨迹实现，并负责把它持久化到一个 WORM 支撑的存储中以实现防篡改；持久性与不可否认性取决于该存储与 Evidence 模块，而不仅仅取决于本模块。变更快照可能携带个人数据；驻留遵循操作方的存储。

法务合规边界

AST 审计轨迹接口不适用任何出口管制限制。审计轨迹支持审计工作流程；它不是法律鉴证，也不是审计认证。本文档不是法律意见；请咨询你自己的合规与法务顾问。

另请参阅

• Evidence —— 封存并加盖时间戳到该轨迹。
• Validation —— 结构性策略检查。
• Core AST —— AST 模型。
• AST 审计轨迹 —— 深度参考 —— 持久化存储的内部机制与完整的公开 API 接口。