审计查询、导出与留存

本页阅读位置

完成第一轮对话后，按当前业务需求深入。Spring 常规声明优先使用 RegistrationManifest 与注解；本页的底层 register / publish 或直连方法供协议细化与兼容集成参考。

在管理页面追溯操作

打开“审计记录”，填写精确动作、操作人、租户、运行或工具执行标识及时间范围，点击“筛选审计”。留空字段不限制；API/SDK 可用 tenantId="" 精确选择应用共享租户。此工作台属于管理权限；业务 USER 不能使用，应用管理员仅管理当前应用。

每页 25 条，上一页/下一页沿用固定快照，后续新增记录不会插入这份快照。重新筛选建立新快照。记录详情包含 appId、subjectId、tenantId、role、action、target、createdAt、outcome；权限调用增加决策标识和所需权限/参数摘要，工具调用增加 runId/executionId/inputHash/resultHash/revision，资源保存/发布增加 beforeHash/afterHash 与修订。不保存原始 Prompt、业务正文、工具参数、Bearer 或密钥。

旧记录只显示当时实际保存的字段，缺失角色、租户或结果显示“历史未记录”，不按当前账号推断。升级回填可从旧权限 target 和工具目标中提取已有 run/execution 关联，但不改写原始记录正文。V16 为旧记录分配新的位置，位置是升级分配/后续写入顺序，不能当成旧记录原本的精确发生序号；createdAt 保留原时间。

导出完整历史

点击“生成审计导出文件”，下载当前筛选的第一件 JSON 文件；有下一件时继续点击“导出下一件审计文件”，直到提示快照末尾。每件最多 1000 条、记录正文最多 2 MiB，可能因正文较大提前分页。导出不会把所有历史一次装入内存，导出操作自身也记录审计。

文件包含 formatVersion=1.0、items、snapshot、total、limit、nextCursor、exportedAt、sha256。sha256 是 items 规范 JSON 的 SHA-256：对象键排序、数组顺序保留、不额外空格、UTF-8；用于完整性核对，不是平台签名或数据库防篡改保证。JSON 作为数据导入，避免将目标文字当成电子表格公式执行。导出文件属于管理资料，按自己的访问、加密和备份制度保存。

游标必须配合相同应用和过滤，不能作为权限凭据。不手工修改游标；历史清理后 AUDIT_CURSOR_EXPIRED 要求重新开始，避免静默得到残缺历史。旧 GET /v1/apps/{app}/audit 仍返回最近最多 200 条数组，完整历史请使用新接口。

SDK 示例

Java

var query = AuditQuery.builder()
    .action("tool.execute.UNKNOWN")
    .tenant("tenant-a")
    .from(java.time.Instant.parse("2026-10-01T00:00:00Z").toEpochMilli())
    .build();
var page = client.auditRecords(query, null, 50).toCompletableFuture().join();
String cursor = (String) page.get("nextCursor");
if (cursor != null) {
    var next = client.auditRecords(query, cursor, 50).toCompletableFuture().join();
}
var file = client.exportAudit(query, null, 1000).toCompletableFuture().join();
// 安全保存整个 file，并用 file.nextCursor 继续同一 query 的下一件。

Kotlin

val query = auditQuery {
    action("tool.execute.UNKNOWN")
    tenant("tenant-a")
}
val page = client.auditRecordsAwait(query, limit = 50)
val cursor = page["nextCursor"] as String?
val exported = client.exportAuditAwait(query, limit = 1000)

Java 示例说明：

AuditQuery 是不可变精确过滤，支持 action、subject、tenant、run、execution、from、to；时间是非负 epoch 毫秒，不是本地日期字符串。凭据由现有 PlatformClient 提供，SDK 不把管理身份交给浏览器业务会话。

Kotlin 示例说明：

另有 previewAuditRetentionAwait、applyAuditRetentionAwait，与 Java 方法及平台鉴权相同。不要因为清理 API 返回成功就推断业务文件或数据库备份已经保存。

独立留存治理

默认无限期保留，没有后台自动删除。平台管理员在“审计留存清理”中选择至少七天以前的到期时间和本次数量（1–500），点击“预览到期审计”。先验证外部备份、留存义务与数据范围，再填写理由、勾选确认并输入 DELETE_EXPIRED_AUDIT，最后点击“确认清理已预览审计”。选中记录被删除，清理审计在同一事务保存；工具执行幂等账本、Run、业务正文不会随之删除。

预览返回 before、limit、snapshotPosition、epoch、selected、recordsHash、planHash；提交仅把前四项放入 plan。planHash 必须完整匹配；数据或清理纪元变化返回 AUDIT_PLAN_CHANGED，未执行删除，需要重新预览。新插入记录在固定上界之外，不会被误清理。每次最多 500 条，继续清理必须建立新预览。应用管理员不能清理。

long cutoff = java.time.Instant.now().minus(30, java.time.temporal.ChronoUnit.DAYS).toEpochMilli();
var preview = client.previewAuditRetention(cutoff, 100).toCompletableFuture().join();
// 在操作人员验证外部备份和留存义务后，显式提取已预览计划：
var plan = new java.util.LinkedHashMap<String, Object>();
for (String key : java.util.List.of("before", "limit", "snapshotPosition", "epoch")) {
    plan.put(key, preview.get(key));
}
// 确认后才调用，方法会提交完整确认词，理由只以摘要写入清理审计。
var receipt = client.applyAuditRetention(plan, (String) preview.get("planHash"),
    "到期记录已核对备份与留存要求").toCompletableFuture().join();

这是显式删除，不能通过回退 Jar 恢复。外部备份、防篡改存储、组织的法律保留由维护者治理；平台不声称验证了外部备份或提供法律合规保证。需要恢复时先还原至隔离库核对，保留清理证据，不能用恢复备份绕过已撤销身份。

API 与错误处理

前缀 /v1/apps/{app}/audit，所有新接口响应 Cache-Control: no-store。

方法与路径	权限与用途
GET /records	应用/平台管理员；精确筛选，limit=1–100，返回固定快照页
POST /export	应用/平台管理员；body 为过滤与 cursor/limit，limit=1–1000，返回可下载 JSON
POST /retention/preview	平台管理员；before 必填，limit 默认 100，最多 500
POST /retention/apply	平台管理员；plan、planHash、confirmation、reason 必填

实例最多四件同时进行的审计操作；超量 AUDIT_WORKBENCH_BUSY 返回 429，不积累无限数据库等待任务，也不自动重试。游标错误或筛选变化是 INVALID_REQUEST；历史清理为 AUDIT_CURSOR_EXPIRED/410；过时清理计划为 AUDIT_PLAN_CHANGED/409；不可导出的大单条历史记录为 AUDIT_RECORD_TOO_LARGE/413，不静默跳过。身份过期、撤销或跨应用访问仍按当前凭据拒绝。

升级和恢复

升级新增 V16 索引列、位置与清理纪元表，启动按每批 100 条回填旧索引。保留原 body 和时间，不改变旧审计接口。回退旧 Jar 时保留新迁移和默认列，旧程序仍可按原列写入；重新升级会回填回退期间产生的记录。先停止清理并验证备份，保留所有迁移历史。

文档来源与验证记录

字段	内容
状态	已确认
日期	2026-10-01
验收日期	2026-10-02
来源	AuditRecords、Store、V16、业务权限/工具/Registry 审计、Java/Kotlin SDK
责任人	SparkTide 维护者
关联任务	完整产品落地 O02
结论	当前管理身份可筛选全部审计历史，分页导出固定快照；仅平台管理员可预览并明确清理到期记录
证据	平台 clean build 200 项、后台 SDK 实际隔离联调 clean build 102 项全部通过，无跳过；PostgreSQL V15→V16、84 条原正文摘要保持、固定快照 301 条与四件导出 302 条、鉴权/清理保护、重启保留和实际管理页面通过