通过 Connect 进行批量标准检查

概览

本范例在一次调用中，按一项或多项具名策略检查多个 PDF。它通过 Connect 传输使用批量合规工具。此工具属于 Enterprise 级：通过 class_exists() 探测发现，并且仅在 nextpdf/premium 与服务器一同安装时才注册。系统会按请求中的每一项策略检查每个文档，响应则是一份汇总报告，按文档和策略列出结果。

与单个文档检查一样，每项策略的「通过」结果只是工具基于其已实现规则得出的自检结果；它并非独立的符合性认证。符合性判定由验证器做出。

安装

composer require nextpdf/server

调用一次 tools/list，确认 Enterprise 批量工具存在。请参阅 /connect/tool-catalog/。

概念总览

标准对每个文档提出要求，检查器则根据这些要求逐个文档进行评估（PDF/A-4 §6.2.3）。符合性是根据要求判定的，而不是由生产者声称的（PDF/A-4 §6.7.3）。对于签名相关策略，PAdES 基线级别彼此不同，而 B-LT/B-LTA 级别（验证材料、归档时间戳）是仅限 Enterprise 的能力（ETSI EN 319 142-2 §5.5）。批量结果只是将同一个狭义语义汇总到整个文档集：「没有任何已实现规则失败」。

API 接口

使用 tools/list 对照正在运行的注册表验证工具名称。权威目录为 /connect/tool-catalog/。本范例不重述工具数量。

代码示例 — 快速上手

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "batch_compliance_check",
    "arguments": {
      "sources": ["/data/q1.pdf", "/data/q2.pdf"],
      "policies": ["pdfa-4"]
    }
  }
}

代码示例 — 生产环境

curl -sS -X POST https://connect.example.com/v1/tools/batch_compliance_check \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"sources":["/data/q1.pdf","/data/q2.pdf"],"policies":["pdfa-4"]}' \
  -o /tmp/batch.json -w '%{http_code}' > /tmp/batch-status || {
    echo "transport failure invoking batch_compliance_check" >&2; exit 1; }

响应会包含一个批次 id、汇总后的 pass/fail 计数，以及按文档列出的 checks 数组；数组中包含每项策略的结果和失败原因。筛选失败项并修正，然后只重新提交受影响的文档。

边缘情况与陷阱

空的 sources 或 policies 属于无效参数错误。
缺失的文件会作为单条结果中的错误返回，而不会导致整个批次失败。请检查每一条结果是否包含 error 字段。
超出批量大小上限会产生明确的错误。请拆分为较小的批次。
未知的策略 id 会产生未知标准错误，并列出可识别的标识符。引用 B-LT/B-LTA 的签名策略，只有在能够产生该材料的 Enterprise 部署上才有意义。
**工具不存在。**若未安装 nextpdf/premium，Enterprise 批量工具便不会注册；该调用会以未知工具错误失败。

性能

front-matter 中的预算是文档层面的上限。此工具在服务器端处理文档，每个文档占用的工作内存都不小。请根据主机内存确定批次大小，而不是调高全局超时。

安全注意事项

请勿在会对外暴露的日志级别记录源路径或完整报告。仅记录批次 id 与汇总后的 pass/fail 计数。每项策略的「通过」只描述已实现的规则集，并非安全或法律层面的保证。

符合性

声明	条款	reference_id
标准提出要求；检查器则评估每个文档	PDF/A-4 §6.2.3
符合性是根据要求判定的，而非由生产者声称	PDF/A-4 §6.7.3
B-LT/B-LTA 会加入验证材料；二者是彼此独立、仅限 Enterprise 的级别	ETSI EN 319 142-2 §5.5

支持批量标准检查并不等于符合性认证。由独立验证器逐个文档做出符合性判定。

商业场景

批量合规工具属于 Enterprise 级，并且仅在 nextpdf/premium 与服务器一同安装时才注册。

Connect 相关细节

传输可用性（MCP / REST / gRPC）

此工具通过共享工具执行器调用，在 MCP tools/call、REST 工具端点与 gRPC 服务中的调用方式相同。

HITL 风险层级

批量检查是只读操作，默认并非 approval_required。操作者的覆盖设置只会提高其风险级别。详情请参阅 /connect/hitl-risk-tiers/。

确认关卡 JSON 信封

除非操作者覆盖将其提升为 approval_required，否则此工具不会触发该关卡。信封和一次性令牌的契约位于 /connect/hitl-risk-tiers/。

另请参阅

/cookbook/connect/compliance-check/ — 单个文档的标准检查。
/cookbook/connect/ai-ready-certification/ — 范围更广的 AI 就绪度检查。
/connect/tool-catalog/ — 按层级计算工具集。
/connect/hitl-risk-tiers/ — 风险模型与该确认关卡。