feat: add retention policy and stability verification

internal/retention/archive.go

@@ -0,0 +1,43 @@
+package retention
+
+import (
+	"context"
+	"time"
+
+	"git.yuntuo.hk/k2safe/orbit/platform/auth"
+)
+
+// ArchiveInput 选择一类历史快照；每批最多100条根记录，游标绑定类别和策略版本。
+type ArchiveInput struct {
+	Kind             string `json:"kind" required:"true"`                     // Kind tasks、workflows、events、audit、deliveries、inbox 或 idempotency。
+	Limit            int    `json:"limit"`                                    // Limit 根记录数量，默认20，最大100。
+	Cursor           string `json:"cursor"`                                   // Cursor 上一批返回的继续位置，空表示从最早记录开始。
+	ExpectedRevision uint64 `json:"expected_revision,string" required:"true"` // ExpectedRevision 防止使用页面未确认的保留窗口导出。
+}
+
+// ArchiveSnapshot 是一个只读归档批次；SourceRetained始终为true，禁止把导出当作数据库清理。
+type ArchiveSnapshot struct {
+	FormatVersion int    `json:"format_version"` // FormatVersion 归档信封格式版本。
+	SHA256        string `json:"sha256"`         // SHA256 对Content原始UTF-8字节的摘要，校验传输和文件完整性。
+	Content       string `json:"content"`        // Content 是原始 JSON 文本；下载时按 UTF-8 原样保存再核验 SHA256，不重新序列化。
+}
+
+// CandidatePage 描述按策略筛选的一批根记录，不宣称它们可以删除。
+type CandidatePage struct {
+	Kind   string    `json:"kind"`   // Kind 历史类型。
+	Cutoff time.Time `json:"cutoff"` // Cutoff 当前策略的UTC排除边界。
+	Count  int       `json:"count"`  // Count 本批候选数量，不是全库数量。
+	More   bool      `json:"more"`   // More 后面还有候选根记录。
+}
+
+// Preview 返回按各类保留窗口读取的有限候选数量，不加载业务正文。
+type Preview struct {
+	Policy      Policy          `json:"policy"`       // Policy 实际读取的版本和窗口。
+	SampleLimit int             `json:"sample_limit"` // SampleLimit 每类候选的取样上限。
+	Items       []CandidatePage `json:"items"`        // Items 固定类别的候选样本。
+}
+
+type ArchiveStore interface {
+	PreviewRetention(context.Context, auth.Token) (Preview, error)
+	ExportRetention(context.Context, auth.Token, ArchiveInput) (ArchiveSnapshot, error)
+}