AI Points · Specification
/spec/auditvisa-idempotency-v1.0.html
Public Structure Layer

AuditVisa Idempotent Processing Specification v1.0

AuditVisa 幂等处理规范 v1.0

本规范用于定义 AuditVisa 在自动化交付流程中的幂等处理原则，确保在重复触发、网络重试、重复投递与并发到达等情况下，同一有效事件始终指向同一正式结果。

StatusDraft for implementation / public documentation
Versionv1.0
Maintained byAuditVisa / AI Origins related structure
Suggested HostAI Points · Public Structure Layer
定位句：同一事件，只产生一个正式结果；重复到达，只复用，不重做。

1. 目的

本规范用于定义 AuditVisa 在自动化交付流程中的幂等处理原则，以确保在面对重复触发、重复通知、网络重试、外部平台重复投递等情况时，系统能够：

  1. 保证同一业务事件不会被重复执行；
  2. 保证同一交付结果不会被重复生成为多个不一致副本；
  3. 保证重复请求可获得一致、可追溯、可验证的既有结果；
  4. 保证自动化流程在网络不稳定或第三方平台重复推送条件下仍保持稳定与可审计性。

2. 定义

2.1 幂等（Idempotency）

对于同一逻辑事件，无论系统被触发一次还是多次，其最终结果应当保持一致，不因重复执行而产生额外副作用。

在 AuditVisa 语境中，幂等意味着：同一支付事件不会重复生成多个不同出证包；同一交付事件不会重复写入多个冲突性结果；同一通知事件在重复触发时，应优先复用既有结果，而不是重新制造新结果。

2.2 事件（Event）

事件是指由外部系统或内部系统触发的、具有唯一标识的处理单元。例如 Stripe webhook event、内部审核任务完成事件、自动打包完成事件、自动投递通知事件。

evt_XXXXXXXXXXXX

2.3 业务引用（Reference）

业务引用是系统内部用于绑定处理记录的唯一引用标识。例如：

av_evt_1T5pdGGRtItDCjuJ7AJcYMdb

2.4 会话标识（Session ID / SID）

会话标识指与一次支付或业务提交相关联的会话 ID，例如 Stripe Checkout Session：

cs_live_XXXXXXXXXXXX

SID 可用于关联付款上下文，但 不应单独作为幂等主键。

3. 适用原则

  1. 唯一事件唯一结果：对于同一唯一事件，系统只允许存在一个正式处理结果。
  2. 重复触发不重复生产：如事件重复到达，系统不得再次生成新的正式交付包，而应复用既有产物。
  3. 结果优先复用：若既有结果已经存在，重复请求应直接返回既有 HTML、ZIP、JSON 或其索引引用。
  4. 记录必须可追踪：每一个被判定为“已处理”的事件，都必须可追溯到原始事件 ID、内部引用 ID、交付物路径、首次处理时间与处理状态。
  5. 拒绝隐性重复副作用：即便重复请求未重新生成文件，只要造成重复写库、重复通知、重复签名、重复计费、重复发包，也视为违反幂等原则。

4. 幂等判定键

4.1 主幂等键

AuditVisa 应优先使用外部事件唯一 ID 作为主幂等判定键，例如：

evt_1T5pdGGRtItDCjuJ7AJcYMdb

内部可映射为：

av_evt_1T5pdGGRtItDCjuJ7AJcYMdb

4.2 辅助关联键

系统可记录以下辅助键用于关联与校验：

  • session id (cs_live_...)
  • target
  • email
  • product / price id
  • request fingerprint
  • payload hash

4.3 规范要求

当外部平台本身提供全局唯一事件 ID 时，系统不得仅依赖时间戳、用户邮箱、商品名、URL 或金额作为唯一判定依据。

5. 标准处理流程

5.1 接收事件

系统收到事件后，应立即提取：

  • event_id
  • source
  • session_id
  • payload
  • received_at

5.2 生成内部引用

ref = av_evt_<event_id>

5.3 查重

系统在执行正式处理前，必须检查本地或远程幂等记录库，例如：

  • processed.jsonl
  • sqlite
  • kv store
  • append-only log
  • audit ledger

查重结果应至少分为：not_found、processing、processed、failed、orphaned。

5.4 首次处理

  1. 拉取或规范化业务参数；
  2. 执行出证；
  3. 生成 HTML / ZIP / JSON；
  4. 写入交付目录；
  5. 记录结果索引；
  6. 发送通知；
  7. 将状态写为 processed。

5.5 重复处理

  1. 不重复生成新文件；
  2. 不重复生成新签名；
  3. 不重复写入新的正式交付记录；
  4. 返回既有结果链接或结果摘要；
  5. 日志中标记为 duplicate_reused。

5.6 处理中重复到达

若事件状态为 processing，系统应避免开启第二个正式处理流程，可返回处理中状态，或在短时间轮询后返回首次处理结果。

6. 状态模型

  • received：已收到事件，尚未开始正式处理。
  • processing：已进入处理流程，结果尚未确认完成。
  • processed：正式结果已生成，且已建立稳定索引。
  • duplicate_reused：本次触发为重复触发，系统未重新执行，而是复用既有结果。
  • failed：处理失败，且未产生有效正式结果。
  • orphaned：发生部分产物生成但主记录未完整写入的异常状态。

7. 结果复用规则

7.1 可复用结果

  • HTML 报告
  • ZIP 打包文件
  • JSON 元数据
  • 结果索引记录
  • run hash
  • 签名结果
  • 审计摘要

7.2 禁止重复生成的对象

  • 新的交付文件名（除非系统明确采用同名覆盖策略）
  • 新的正式签名
  • 新的正式 run hash
  • 新的正式通知记录
  • 新的收费确认状态

7.3 复用输出建议

Duplicate event detected.
Existing AuditVisa reused.
检测到重复事件，已复用既有 AuditVisa 结果。

8. 存储要求

8.1 幂等记录存储

{
  "event_id": "evt_xxx",
  "ref": "av_evt_xxx",
  "sid": "cs_live_xxx",
  "status": "processed",
  "created_at": "2026-03-01T09:49:14Z",
  "updated_at": "2026-03-01T09:49:20Z",
  "html_url": "https://deliver.evanbei.com/d/xxx.html",
  "zip_url": "https://deliver.evanbei.com/d/xxx.zip",
  "run_hash": "xxx",
  "payload_hash": "xxx"
}

8.2 存储特性

幂等记录存储应尽量满足：原子写入、可追加、可恢复、可审计、易导出、易备份。

8.3 不可仅依赖内存

幂等判定不得仅保存在进程内存中，否则服务重启后将丢失状态，造成重复处理风险。

9. 通知规范

9.1 首次处理通知

首次处理完成后，通知中应包括：处理成功说明、Event ID、Ref、SID（如适用）、HTML URL、ZIP URL。

9.2 重复处理通知

对于重复事件，通知中应标记为 already processed 或 duplicate reused，并明确说明未重新出证，当前链接为既有正式结果。

9.3 禁止制造误导

通知内容不得让使用者误以为系统发生了严重故障；如果实际情况只是重复 webhook 重试，应表达为受控状态、正常幂等拦截、稳定复用既有结果。

10. 并发控制

10.1 单事件串行处理

同一幂等键在任意时刻只允许一个正式处理流程运行。

10.2 推荐机制

  • 文件锁
  • sqlite transaction
  • advisory lock
  • 原子创建标记文件
  • 队列化单消费者处理

10.3 并发冲突处理

若两个进程几乎同时收到同一事件，只有一个进程应成功进入 processing；另一个进程应检测到占用并退出或等待；最终均应指向同一正式结果。

11. 异常恢复

11.1 半完成状态

若系统在文件已生成但记录未写入、记录已写入但通知未发出、HTML 已存在但 ZIP 未完成等阶段中断，则应进入异常恢复流程。

11.2 恢复原则

  1. 检查是否已有可复用正式产物；
  2. 若存在，则补全记录；
  3. 若不存在，则谨慎重新生成；
  4. 整个恢复过程仍应遵守幂等原则。

11.3 人工核验接口

对于 orphaned 或 failed 状态，建议保留人工检查工具，用于核验文件是否完整、hash 是否一致、是否需要补写索引。

12. 审计要求

12.1 最低审计信息

  • event id
  • ref
  • sid
  • payload hash
  • 状态变更时间
  • 输出文件路径
  • run hash
  • 签名状态
  • 通知状态

12.2 审计目标

  1. 该事件是否到达过？
  2. 到达了几次？
  3. 哪次是首次正式处理？
  4. 是否发生过重复触发？
  5. 是否复用了既有结果？
  6. 当前正式结果是什么？
  7. 是否存在不一致副作用？

13. 安全与信任边界

13.1 幂等不是授权

幂等处理只解决“重复执行”问题，不自动等同于来源可信、权限合法、内容真实或业务正确。因此幂等机制必须与 webhook 验签、target policy、参数校验、delivery policy 共同工作。

13.2 幂等不是防伪

幂等能防止重复生产，但不能单独证明交付内容不可伪造。若需更强信任，应配合 run hash、Ed25519 signature、anchor public key、二阶段验证页和多节点签名。

14. 实现建议

14.1 记录文件

/var/lib/auditvisa/processed.jsonl

14.2 交付目录

/var/lib/auditvisa/deliveries/

14.3 核心步骤

  1. 接收 webhook
  2. 验签
  3. 提取 event_id
  4. 查询 processed.jsonl
  5. 未处理则加锁进入处理
  6. 生成结果并写入 delivery
  7. 记录 processed
  8. 发送 Telegram 通知
  9. 重复事件则直接返回既有链接

14.4 推荐日志语义

event_received
event_processing_started
event_processed
event_duplicate_reused
event_failed
event_orphaned
delivery_written
telegram_notified

15. 对外说明建议

AuditVisa implements idempotent event processing to ensure that repeated triggers, retries, or duplicate webhook deliveries do not create inconsistent or duplicated certification artifacts. The same verified event always resolves to the same canonical result.
AuditVisa 实现了幂等事件处理机制，能够在重复触发、网络重试或外部平台重复投递情况下，始终将同一有效事件解析为同一正式结果，从而避免重复出证与不一致副作用。

16. 合规结论

  • 同一事件不会重复出证；
  • 同一事件不会重复生成冲突性交付包；
  • 重复事件可回溯并复用既有正式结果；
  • 状态流转清晰可审计；
  • 网络重试不会破坏系统稳定性。

17. 版本信息

Specification Name: AuditVisa Idempotent Processing Specification

Version: v1.0

Status: Draft for implementation / public documentation

Maintained by: AuditVisa / AI Origins related structure

Language: Chinese primary, English title retained; bilingual expansion optional

18. 一句定位版

同一事件，只产生一个正式结果；重复到达，只复用，不重做。

可直接作为页面摘要、对外说明或产品说明中的一句定位语。