cpa-plugin/docs/modules/persistence.md

本地持久化模块

1. 定位

持久化模块负责把 数据模块 的事实安全地保存到本地，并提供事务、查询、迁移、备份、归档和重建能力。它不解释 CPA payload、不计算价格、不决定 Key 是否放行，也不包含 UI 逻辑。

第一版采用单文件 SQLite。它符合插件单机、低运维、随 CPA 一起分发的目标，又能提供计费账本需要的事务与唯一约束。不能沿用 cpa-plugin-key-billing 把整个状态写成一个 JSON 文档的方式。

2. 存储分层

2.1 权威事实：不可随意修改

• Request 与 Execution；
• 标准 Usage；
• BillingRecord 与 LedgerEntry；
• 管理员余额调整；
• 请求准入使用的 plan/cycle/price 快照。

事实只允许追加、幂等补全或显式冲正。历史价格变化不能重算并覆盖已经入账金额。

2.2 当前目录与配置事实

• 下游 account、credential、自管 Key public ID/HMAC digest/preview/alias，以及兼容模式的 CPA scope；
• 上游 auth/provider identity；
• Key→plan 与 Key→upstream binding；
• plan、route policy、price catalog/rule；
• plugin settings 和 schema migrations。

同步删除采用 soft delete，历史请求不能因当前 Key 或上游账号被删除而失去解释能力。

2.3 时间点快照

• 上游 quota/subscription snapshot；
• 模型与价格目录版本；
• credential health；
• 同步运行结果。

快照按时间追加，当前值由最新有效快照投影，不覆盖历史。

2.4 可重建派生数据

• 小时/日 overview；
• activity；
• latency 分布；
• identity totals；
• ranking、Top 和 heatmap；
• realtime cache。

这些数据可以删除后从事实表重建，不能作为余额或账本真相。

3. 建议表组

字段细节由数据模块契约决定，持久化初版至少需要以下表组：

表组	建议表	说明
下游身份	accounts、billing_accounts、credentials、credential_secret_versions	用户、金额账户、逻辑 Credential 和可轮换 secret version 分开；只存 public ID、HMAC digest/key ID、preview，不存可恢复明文
上游身份	upstream_identities	auth ID/index、provider、账户展示、状态、订阅元数据
绑定与策略	billing_account_plans、credential_routes	金额套餐属于 BillingAccount，上游账户路由属于 Credential/Account
请求事实	requests、executions、usage_records	一次 Request 可有多个 Execution/Usage
Usage 关联	usage_correlations、usage_observations	response ID→Request/Execution 最小映射、canonical vector/hash/revision 与迟到观察
价格	price_catalogs、price_rules、pricing_snapshots	带版本、来源、有效期和审批状态
计费	billing_records、ledger_entries、billing_cycles	定点整数金额，事务提交
上游配额	quota_snapshots、subscription_snapshots	与下游余额严格分离
同步诊断	ingest_inbox、sync_runs、diagnostic_events	失败重试、来源与处理状态
统一投影流	projection_events	全库单调 event_seq，领域事实/修订对应的确定性统计变化
聚合	overview_hourly、overview_daily、activity_stats、latency_stats、aggregation_checkpoints	可以重建
系统	schema_migrations、app_settings	数据库版本和插件设置；只有引入 sidecar/已认证用户路由后才增加 auth_sessions

billing_records 对 Usage 使用稳定逻辑 ID/revision，ledger_entries.billing_record_id、各 EventID/IdempotencyKey 必须有唯一约束。usage_observations 至少唯一约束 (execution_id, canonical_hash)；相同累计 vector 重放不能产生新 revision。

4. SQLite 运行策略

参考 cpa-usage-keeper/internal/repository/db.go：

• 文件库启用 WAL；
• busy_timeout=5000；
• foreign_keys=ON；
• 单 writer connection，所有写事务串行；
• 独立只读 pool，可允许少量并发查询；
• 内存数据库测试时复用单连接；
• 数据库路径使用插件专属 data directory，不放入动态库目录或当前工作目录猜测位置。

插件在 CPA 进程内，任何数据库操作都不能长期阻塞请求线程。准入 pending 和 response hook 取得的可靠 canonical Usage 必须在回调返回前耐久化；completion 不是 Usage 唯一落库点。使用有界队列时，队列满不能静默丢弃，应同步落库、进入本地 inbox，或对新请求 fail closed。

Go c-shared 内长期 goroutine/timer 的安全性尚未通过验证，MVP 持久化先采用 host callback/管理请求驱动的同步短事务，不自行启动后台 flusher。连接池、WAL checkpoint、聚合和 backup worker 只有通过 dev.md 的双 Go runtime soak gate 后才能开启；否则长期任务移到 sidecar。

5. 原子事务

一次正常结算至少在一个事务内完成：

1. 幂等插入/确认 Request、Execution、Usage；
2. 读取准入时锁定的 cycle 与 pricing snapshot；
3. 插入 BillingRecord；
4. 插入不可变 LedgerEntry；
5. 更新 cycle/account 的缓存余额投影；
6. 在 projection_events 插入可供聚合追赶的单调 event_seq，事务后再发送轻量通知；结算事务不提前推进任何聚合 checkpoint。

唯一约束是最终防线。进程内去重缓存只能提高性能，不能替代数据库幂等。

管理员充值、扣减、重置和冲正同样必须写 LedgerEntry，禁止直接修改 spent 或 balance 而不留原因。

6. 金额、时间和未知值

• 金额统一保存为 int64 micros 和 currency，不使用 float 作为余额或账本字段；
• Token 使用非负 int64；
• 时间保存 UTC 或一个固定的规范化格式，展示时再转时区；
• NULL 表示未知，数值 0 表示确认观察到零；
• bool 若来源可能缺失则使用 nullable；
• 枚举按稳定字符串保存，并由 schema version 管理扩展。

7. Hot、Archive 与保留策略

参考 usage-keeper 的 usage_events / usage_events_archive，但不能直接照搬其单表 INSERT SELECT + DELETE：本项目存在 Request→Execution→Usage→Billing→Ledger 永久审计关系。

MVP 决断：不物理移动或删除 Request/Execution/Usage 最小事实行；只清理原始大响应引用、临时诊断和已过期内存缓存。BillingRecord、LedgerEntry 和管理员调整永久保留。待真实容量达到阈值后再设计统一逻辑 ID + hot/cold view，或只归档大字段/诊断明细；任何方案都不能打断账本引用。

• 最小 usage_correlations 默认随 hot Request 保留至少 90 天；24 小时只表示内存 cache TTL/awaiting 快速扫描窗口，不立即删除 response-ID 映射；
• 超过关联保留期后，只有自带 RequestID/ExecutionID 的迟到事实仍可可靠补记，无 ID 观察不得猜配；
• 小时级高分辨率聚合可以短期保留，日级金额/请求聚合长期保留；
• quota snapshot 可以按策略降采样，保留重置边界和异常快照。

归档不是删除历史。用户要求清除日志时，必须区分“隐藏/清理诊断日志”“删除请求内容引用”和“不可删除的金额账本”。

8. 聚合与 checkpoint

projection_events.event_seq INTEGER PRIMARY KEY AUTOINCREMENT 是全库唯一聚合游标；同一事务还写 event_id UNIQUE、event_kind、fact_id、fact_revision、occurred_at、booked_at、supersedes_event_id 和确定性 delta payload。状态从 unmeasured 变为 measured 时，事件明确携带 unmeasured_count=-1、measured_count=+1、spend_delta=...，不能只追加一个“已结算”状态造成双计数。

每类聚合使用独立 checkpoint：overview、activity、latency、identity、ranking 互不阻塞。checkpoint 保存已处理的最大单调 event_seq，而不是 UUID event_id 或只保存时间；event_id 负责全局身份/幂等，不能拿来比较处理先后。

• 新事件提交后发送轻量通知；
• callback-driven runner、sidecar 或 soak 通过后的后台 runner 批量追赶；
• 启动时检查 lag 并恢复；
• 单个聚合失败只保留自己的旧 checkpoint；
• 聚合 upsert 与 checkpoint 推进处于同一事务；
• 支持从 0 或指定 event_seq 重建；
• UI 能展示各 checkpoint lag 和最后错误。

9. Inbox、崩溃恢复与备份

如果存在 Redis/HTTP 导入或异步采集，应先把原始消息写入 ingest_inbox，再解码为事实，状态至少包含 pending、processed、process_failed、discarded。失败重试必须有次数和最后错误。

原生回调的 Request 临时状态不能完整依赖内存。至少在准入/执行开始处留下轻量 pending 事实，使进程崩溃后可以将未完成请求标记为 abandoned/unknown，而不是永久占用并发或额度预留。

恢复扫描还必须包括：已保存 canonical Usage 但尚未结算的 Execution、awaiting usage、未发布 projection/outbox。即使 completion 永久丢失，Request 可以转为 abandoned/unknown，可靠 Usage 仍必须结算。

备份使用 SQLite online backup API，不能只复制正在 WAL 模式运行的 .db 文件。建议：

• 每日自动备份；
• 默认保留 7～30 天；
• 管理员可立即创建和下载备份；
• 恢复必须校验 schema version、integrity check 和账本一致性；
• SQLite 备份不包含外部 HMAC secret keyring；运维必须分开加密备份、成对恢复，并用非秘密 fingerprint/key ID 验证匹配；缺失或不匹配时认证 fail closed，禁止自动生成替代 secret；
• shutdown 时停止 runner、checkpoint WAL、关闭 reader/writer，且整个过程幂等有超时。

10. 索引原则

索引围绕真实查询建立：

• request/event ID 唯一索引；
• timestamp + ID 游标；
• downstream credential/account + timestamp；
• upstream identity + timestamp；
• model + timestamp；
• outcome/status + timestamp；
• cycle、ledger account + occurred_at；
• archive 只保留主键和必要的少数索引。

不要为 UI 的每个筛选组合创建索引。使用真实数据容量测试查询计划，再调整复合索引。

11. 迁移策略

• 新库可创建当前完整 schema；
• 已存在数据库必须执行有序、带版本的显式 migration；
• migration 在插件开始接收业务请求前完成；
• 破坏性迁移先备份；
• migration 失败时插件进入不可计费/不放行的安全状态，不能打开空数据库继续免费运行；
• 数据契约 schema version 与 SQLite migration version 分开管理。

12. 参考路径与验收

主要参考：

• cpa-usage-keeper/internal/repository/db.go；
• internal/entities/；
• internal/repository/migration/；
• internal/repository/usage_event_archive.go；
• internal/backup/；
• internal/repository/usage*.go。

验收必须覆盖事务回滚、重复事件、并发读写、WAL、数据库锁、崩溃恢复、migration、备份恢复、archive 前 checkpoint 检查、账本金额一致性和 go test -race。