证据

概览

NextPDF Enterprise 把按文档维度的验证结果汇集成一个封存、不可变的包，具有确定性的 JSON 形式与一个稳定的 SHA-256 摘要，并可选地携带一个 RFC 3161 时间戳令牌。证据采集支持审计工作流程。它不是法律鉴证、审计认证，也不是文档合规的证明。

可用性与授权

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

安装

composer require nextpdf/enterprise:^3

概念总览

EvidencePortal 是入口点。generateEvidence($documentHash, $records, $tsaTimestamp) 把一组 EvidenceRecord 实例汇集进一个 EvidencePackage、计算通过/失败统计、通过一个 EvidenceStoreInterface 持久化该包，并返回封存后的包。一个 EvidenceRecord 捕获一次策略检查：策略名称、通过标志、详情、生成它的验证器版本，以及一个时间戳。

EvidencePackage 一旦构造便不可变。它携带一个包 id、被验证文档的 SHA-256、各记录、聚合计数、一个生成时间，以及一个可选的 RFC 3161 时间戳令牌。allPassed() 与 passRate() 对其进行汇总。它的不可变性使一个包适合写一次读多次（WORM）存储。

EvidenceExporter 把一个包序列化为一个确定性的 JSON 字符串——固定键顺序、可复现——因此 exportHash() 返回一个用于完整性核验的稳定 64 字符 SHA-256 摘要。同一个包始终产生同一个摘要，与它在何时何地被计算无关。

ContinuousMonitor 重新验证一份文档，并按失败的策略名称把当前证据与已存储的先前证据做差异比对，将问题归类为新增、已解决或未变，并暴露一项排程检查（isDue() / MonitorSchedule / MonitorFrequency）。这支持随时间的漂移检测；它报告发生了什么变化，但它不在任何时点断言法律地位。

此处“evidence”意味着什么

本模块为审计工作流程打包并加盖验证结果的时间戳。它不为任何事做认证。

• 一个 RFC 3161 时间戳令牌把包数据绑定到一个时间值：它提供数据在该时间之前已存在的证据。它不是法律鉴证，也不断言被加盖时间戳的内容是合规或有效的。
• 一个 allPassed() === true 的封存包记录了所包含的检查对照其所实现的规则通过了。它不是一项审计认证。
• 确定性摘要证明包字节的完整性。它不证明文档的监管充分性。

证据采集支持审计工作流程；它不是法律鉴证，也不是审计认证。有效性与符合性仍然是最终文件加上一个验证器所具有的属性。

层级边界

证据打包是一个仅限 Enterprise 的接口。Core 与 Pro 生产结果与报告；Enterprise Evidence 把那些结果封存进一个不可变、确定性、可选地加盖时间戳的包，并跟踪回归。它依赖在别处（Validation 或 Compliance 接口）生产的结果；它本身不执行符合性检查。

它为何这样运作

只有当证据事后无法被悄悄改写时它才有用，因此 EvidencePackage 是一个封存的 readonly 值，没有任何修改器——对写一次读多次存储是安全的。导出器的 toJson() 输出遵循固定的键插入顺序，而非运行时排序，因此同一个包始终序列化为完全相同的字节。这种字节稳定性让一个已存储的 exportHash() 能在日后核验完整性：对包的任何改动都会改变摘要。RFC 3161 令牌被保留为时间的内嵌证据，而绝非一个裁决，因此一个包证明的是检查何时运行，而不断言文档合规。回归跟踪随后按失败的策略名称与先前的包做差异比对，从而漂移检测独立于检查的顺序或数量。

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

API 接口

类	职责
EvidencePortal	汇集、持久化并检索证据包。
EvidencePackage	带聚合统计的、不可变的封存记录束。
EvidenceRecord	一次带验证器版本与时间戳的策略检查结果。
EvidenceExporter	确定性 JSON 序列化；稳定的 SHA-256 摘要。
EvidenceStoreInterface	持久化契约。
InMemoryEvidenceStore	参考的内存存储实现。
ContinuousMonitor	重新验证并与先前证据做差异比对。
MonitorResult	新增 / 已解决 / 未变的问题归类。
MonitorSchedule / MonitorFrequency	基于排程的轮询。

代码示例 — 快速开始

$package = $portal->generateEvidence($documentHash, $records);
$digest  = $exporter->exportHash($package); // 64-char SHA-256

代码示例 — 生产

$package = $portal->generateEvidence($documentHash, $records, $tsaToken);
$logger->info('evidence.sealed', [
    'package'   => $package->packageId,
    'digest'    => $exporter->exportHash($package),
    'pass_rate' => $package->passRate(),
]);

$delta = $monitor->check($package, $documentHash);
if ($delta->newIssues !== []) {
    $logger->warning('evidence.regression', ['count' => count($delta->newIssues)]);
}
// The package is audit-supporting evidence, not an attestation of compliance.

边界情况与注意事项

• 当没有任何结果时 passRate() 返回 0.0；一个空包不是一次通过。
• 导出只有通过 EvidenceExporter 才是确定性的；对任意序列化做哈希会破坏稳定摘要保证。
• 一个没有 TSA 令牌的包仍然是有效的证据；该令牌增加的是一个时间绑定，而非一个裁决。

性能

打包与确定性序列化随记录数量线性增长。摘要计算是对序列化后的 JSON 做单次 SHA-256 遍历。

安全说明

包摘要为包字节提供防篡改。可选的 RFC 3161 令牌必须来自一个受信任的 TSA；本模块内嵌该令牌，它并不为 TSA 背书。请把记录详情当作可能敏感的（见下文）。

数据驻留与个人信息缓解

证据记录与文档哈希可能引用受监管内容。打包在进程内进行；持久化被委托给你的 EvidenceStoreInterface 实现，因此驻留遵循你的存储。请对已存储的包施加留存与最小化控制。

安全遥测与日志清洗

包元数据（id、摘要、计数）可以安全地记录。记录详情可能回显包含从文档中提取字符串的结果消息；在转发到共享接收端之前请先脱敏。

符合性

行为	引用	状态
时间戳令牌把数据绑定到一个时间	IETF RFC 3161 §2	令牌已内嵌（由 TSA 提供）
DSS / 长期验证背景	ISO 32000-2:2020 §12.8	引用（在此被消费，而非生产）

本表记录本模块所对照构建的规范。一个时间戳令牌是时间的证据，而非认证或法律鉴证。

FIPS 模式行为

本模块对包字节计算 SHA-256，并内嵌一个由调用方提供的 RFC 3161 令牌。它不执行签名，也不进行密钥保管；密码学运算与 FIPS 模式行为由 Security 与 Signature 模块处理。

威胁模型

输入是各结果与一个可选的 TSA 令牌。缓解措施：不可变的包、带稳定完整性摘要的确定性序列化，以及被委托的持久化，从而由存储来强制执行 WORM 与访问控制。

行为契约

• 门户把各结果汇集进一个不可变、封存的包，带一个包 id、被验证文档的 SHA-256、各记录、聚合计数、生成时间，以及一个可选的 RFC 3161 时间戳令牌。
• 导出器把一个包序列化为一个带固定键顺序的确定性 JSON 字符串，因此摘要是一个稳定的 64 字符 SHA-256，无论它在何时何地被计算都相同。
• 持续监控器重新验证，并按失败的策略名称把当前证据与已存储的先前证据做差异比对，将问题归类为新增、已解决或未变。
• 当没有任何结果时 passRate() 返回 0.0——一个空包不是一次通过；一个没有 TSA 令牌的包仍然是有效的证据。
• 一个时间戳令牌是数据在某个时间之前已存在的证据；它不是法律鉴证，且不就内容的合规性或有效性作任何主张。

发布边界

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

Core 回退

Core 与 Pro 生产结果与报告；把那些结果封存进一个不可变、确定性、可选地加盖时间戳并带回归跟踪的包，在 Core 层级没有等价物。Enterprise 接口依赖在别处生产的结果；它本身不执行符合性检查。

Pro 回退

Pro 回退——无；此能力在 Pro 层级没有等价物。封存的证据包、确定性的导出器，以及持续监控器，仅随 nextpdf/enterprise 包发行；该接口消费来自 Validation 或 Compliance 接口的结果。

Enterprise 边界说明

门户、包、导出器与监控器在行为层面进行描述。参考的内存存储有文档说明；持久化由宿主提供，任何内部存储的内部机制都不属于公开接口范围。本模块内嵌一个由调用方提供的 TSA 令牌；它并不为 TSA 背书。

部署边界

打包与序列化在进程内进行。操作方提供一个持久化的存储实现、负责 WORM 强制与访问控制，并提供一个来自受信任 TSA 的 TSA 令牌。证据记录与文档哈希可能引用受监管内容；驻留遵循操作方的存储，留存与最小化控制是操作方的责任。

法务合规边界

证据采集支持审计工作流程；它不是法律鉴证，也不是审计认证，而有效性与符合性仍然是最终文件加上一个验证器所具有的属性。本文档不是法律意见；请咨询你自己的合规与法务顾问。

另请参阅

• Validation —— 生产此处所打包的结果。
• Compliance —— 外部验证器结果。
• AST 审计轨迹 —— 仅追加的变更历史。
• Specifications: PAdES —— 长期验证背景。
• Evidence — 深度参考 —— 完整的类级 API 参考。