usage

type ErrLogConfig struct {
	QueueSize       int           // 拒绝队列容量（背压面：满 → 丢弃；默认 4096 ≈ 1MB 量级内存）
	ExemptQueueSize int           // 豁免队列容量（双轨行；默认 1024——恒落盘语义，仅自身溢出才丢）
	BatchSize       int           // 每批落盘行数（默认 500；单条 CreateBulk 有界）
	FlushInterval   time.Duration // 批间隔（默认 500ms；DB 写速率上界 = BatchSize/FlushInterval）
}

type ErrLogInserter interface {
	InsertBatch(ctx context.Context, logs []*domain.UsageLog) error
}

type ErrLogWorker struct {
	// contains filtered or unexported fields
}

type ErrLogWorkerStats struct {
	Queued         int   `json:"queued"`           // 两队列积压总条数（恒 ≤ 容量和）
	QueueCap       int   `json:"queue_cap"`        // 拒绝队列容量（风暴采样阈值）
	ExemptQueueCap int   `json:"exempt_queue_cap"` // 豁免队列容量（双轨行）
	DroppedReject  int64 `json:"dropped_reject"`   // 拒绝行采样丢弃累计
	DroppedExempt  int64 `json:"dropped_exempt"`   // 双轨行丢弃累计（>0 即异常态）
	Inserted       int64 `json:"inserted"`         // 成功落盘累计
	WarnedReject   bool  `json:"warned_reject"`    // 拒绝丢弃告警边沿
	WarnedExempt   bool  `json:"warned_exempt"`    // 双轨丢弃告警边沿
}

type LogInserter interface {
	InsertBatch(ctx context.Context, logs []*domain.UsageLog) error
}

type PartitionManager interface {
	EnsureUsageLogPartitions(ctx context.Context, now, until time.Time) error
	DropUsageLogPartitionsBefore(ctx context.Context, cutoff time.Time) (int, error)
	EnsureErrLogPartitions(ctx context.Context, now, until time.Time) error
	DropErrLogPartitionsBefore(ctx context.Context, cutoff time.Time) (int, error)
	EnsureUsageStatsPartitions(ctx context.Context, now, until time.Time) error
	DropUsageStatsPartitionsBefore(ctx context.Context, cutoff time.Time) (int, error)
	EnsureUsageEntityStatsPartitions(ctx context.Context, now, until time.Time) error
	DropUsageEntityStatsPartitionsBefore(ctx context.Context, cutoff time.Time) (int, error)
	DeleteRedemptionUsesBefore(ctx context.Context, cutoff time.Time) (int, error)
}

type QuotaWriter interface {
	AddQuotaUsed(ctx context.Context, deltas map[int64]int64) error
}

type Recorder struct {
	// contains filtered or unexported fields
}

type RecorderStats struct {
	PendingLogs      int64 `json:"pending_logs"`      // 尚未落库的明细条数
	PendingWaterline int64 `json:"pending_waterline"` // 水线（包级 var 直读）
	Warned           bool  `json:"warned"`            // 水线告警边沿是否置位
}

type RetentionConfig struct {
	LogRetentionDays    int           // usage_logs 分区保留天数（config usage.log_retention_days；<= 0 = 不删除）
	ErrLogRetentionDays int           // err_logs 分区保留天数（config usage.errlog_retention_days，默认 7 天短保留——错误审计；<= 0 = 不删除）
	StatsRetentionDays  int           // usage_stats 分区保留天数（config usage.stats_retention_days，默认 180 天——聚合统计长保留；<= 0 = 不删除）
	TickerInterval      time.Duration // 巡检周期（生产 1h；测试注入短周期；<= 0 兜底 1h）
}

type RetentionWorker struct {
	// contains filtered or unexported fields
}

type RetentionWorkerStats struct {
	LastPatrolUnixMs                 int64 `json:"last_patrol_unix_ms"`                  // 最近一次巡检完成时刻（0 = 尚未巡检）
	LastDroppedLogPartitions         int64 `json:"last_dropped_log_partitions"`          // 最近成功轮 usage_logs DROP 分区数（失败轮保留上轮值）
	LastDroppedErrLogPartitions      int64 `json:"last_dropped_errlog_partitions"`       // 最近成功轮 err_logs DROP 分区数（失败轮保留上轮值）
	LastDroppedStatsPartitions       int64 `json:"last_dropped_stats_partitions"`        // 最近成功轮 usage_stats DROP 分区数（失败轮保留上轮值）
	LastDroppedEntityStatsPartitions int64 `json:"last_dropped_entity_stats_partitions"` // 最近成功轮 usage_entity_stats DROP 分区数（与 stats 同 StatsRetentionDays，失败轮保留上轮值）
	LogRetentionDays                 int   `json:"log_retention_days"`
	ErrLogRetentionDays              int   `json:"errlog_retention_days"`
	StatsRetentionDays               int   `json:"stats_retention_days"`
}

type StatsAggConfig struct {
	Interval time.Duration // 聚合周期（config usage.stats_agg_interval，默认 5m；0 = 禁用——Start 直接返回）
	Lag      time.Duration // 读窗口滞后（读窗口 [W, T)，T = now − Lag；watermark 只推进到 T）
}

type StatsAggStore interface {
	// AcquireStatsAggLock 抢占会话级 advisory lock（专用连接持有到 release；
	// 抢锁失败 ok=false——其他实例在聚合，本轮跳过）。
	AcquireStatsAggLock(ctx context.Context) (release func(), ok bool, err error)
	// LoadAggRange 重算范围 [from,to) 双结果集全量重建：cube 两查询 +
	// entity 六查询（含消费明细行数——cube 两查询 count(*) 合计）。
	LoadAggRange(ctx context.Context, from, to time.Time) ([]*domain.StatBucket, []*domain.EntityStatBucket, int64, error)
	// AggregateRange 单事务 DELETE cube [delFrom,delTo) + INSERT cube +
	// DELETE entity [同范围] + INSERT entity + watermark 推进 wmTo（= 读窗口 T，
	// ≠ 重算范围上界——P1-A 两范围分离；双表同一事务原子回滚）。
	AggregateRange(ctx context.Context, delFrom, delTo, wmTo time.Time, cube []*domain.StatBucket, entity []*domain.EntityStatBucket) error
	LoadStatsAggWatermark(ctx context.Context) (time.Time, error)
	InitStatsAggWatermark(ctx context.Context, t time.Time) error
}

type StatsAggWorker struct {
	// contains filtered or unexported fields
}

type StatsAggWorkerStats struct {
	// WatermarkUnixMs watermark 位置（毫秒；0 = 尚未推进——未初始化/首轮未完成）
	WatermarkUnixMs int64 `json:"watermark_unix_ms"`
	// LastBuckets 上轮写入桶数（cube + entity 合计；失败轮保留上轮值）
	LastBuckets int64 `json:"last_buckets"`
	// LastRows 上轮消费明细行数（cube 两查询 count(*) 合计——实体六查询扫的
	// 是同批源行不重复计数；失败轮保留上轮值）
	LastRows int64 `json:"last_rows"`
	// LastDurationMs 上轮耗时（毫秒；失败轮保留上轮值）
	LastDurationMs int64 `json:"last_duration_ms"`
}

type UsageConfig struct {
	BatchSize          int
	FlushInterval      time.Duration
	QuotaFlushInterval time.Duration // quota 增量批量回写 cadence
	Workers            int           // flush 并行 worker 数（0 = 单 worker；O1 模式分片并行）
	// StatsAggInterval 离线聚合周期（spec 2026-08-14；config usage.stats_agg_
	// interval，默认 5m；0 = 禁用聚合——不装配聚合 worker 的等价语义）。
	StatsAggInterval time.Duration
}