outbox

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

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

type DLQAlertHandler interface {
	// Alert 发送告警
	// ctx: 上下文
	// event: 失败的事件
	// 返回：发送失败时返回错误
	Alert(ctx context.Context, event *OutboxEvent) error
}

type DLQAlertHandlerFunc func(ctx context.Context, event *OutboxEvent) error

type DLQHandler interface {
	// Handle 处理死信事件
	// ctx: 上下文
	// event: 失败的事件
	// 返回：处理失败时返回错误
	Handle(ctx context.Context, event *OutboxEvent) error
}

type DLQHandlerFunc func(ctx context.Context, event *OutboxEvent) error

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

type Envelope struct {
	// EventID 事件唯一ID（必填，用于 Outbox 模式）
	EventID string `json:"event_id"`
	// AggregateID 聚合根ID
	AggregateID string `json:"aggregate_id"`
	// EventType 事件类型
	EventType string `json:"event_type"`
	// EventVersion 事件版本
	EventVersion int64 `json:"event_version"`
	// Payload 事件负载
	Payload []byte `json:"payload"`
	// Timestamp 事件时间戳
	Timestamp time.Time `json:"timestamp"`
	// TraceID 链路追踪ID（可选）
	TraceID string `json:"trace_id,omitempty"`
	// CorrelationID 关联ID（可选）
	CorrelationID string `json:"correlation_id,omitempty"`
	// TenantID 租户ID（多租户支持，用于Outbox ACK路由）
	TenantID int `json:"tenant_id,omitempty"`
}

type EventPublisher interface {
	// PublishEnvelope 发布 Envelope 消息（推荐）
	// ✅ 支持 Outbox 模式：通过 GetPublishResultChannel() 获取 ACK 结果
	// ✅ 可靠投递：不容许丢失的领域事件必须使用此方法
	//
	// 参数：
	//   ctx: 上下文（可能包含租户信息、追踪信息等）
	//   topic: 目标 topic（由 TopicMapper 提供）
	//   envelope: Envelope 消息（包含 EventID、AggregateID、EventType 等元数据）
	//
	// 返回：
	//   error: 提交失败时返回错误（返回时机取决于实现，详见下方"注意"）
	//
	// 注意：
	//   - 此方法 MAY 是同步或异步的，取决于实现：
	//     - 同步发布器（如 InProcessEventPublisher）：handlers 执行完毕后才返回，
	//       返回 nil 即表示发布实际已完成。实现 SyncSemanticsPublisher 标记接口
	//       以便 OutboxPublisher 同步标记事件为 Published。
	//     - 异步发布器（如 Kafka/NATS EventBusAdapter）：提交到 broker 后立即返回，
	//       ACK 通过 GetPublishResultChannel() 异步通知。不要实现 SyncSemanticsPublisher。
	//   - OutboxPublisher 通过 SyncSemanticsPublisher 标记区分两种语义，决定是否
	//     在 PublishBatch 成功后同步调用 MarkBatchAsPublished。
	//   - 实现者应该记录日志、处理超时。
	PublishEnvelope(ctx context.Context, topic string, envelope *Envelope) error

	// GetPublishResultChannel 获取异步发布结果通道
	// ⚠️ 仅 PublishEnvelope() 发送 ACK 结果到此通道
	// 用于 Outbox Processor 监听发布结果并更新 Outbox 状态
	//
	// 返回：
	//   <-chan *PublishResult: 只读的发布结果通道
	GetPublishResultChannel() <-chan *PublishResult
}

type EventStatus string

type FuncTopicMapper func(aggregateType string) string

type InMemoryMetricsCollector struct {

	// 计数器
	PublishedCount int64
	FailedCount    int64
	RetryCount     int64
	DLQCount       int64

	// 按租户统计
	PendingByTenant map[int]int64
	FailedByTenant  map[int]int64
	DLQByTenant     map[int]int64

	// 按事件类型统计
	PublishedByType map[string]int64
	FailedByType    map[string]int64

	// 耗时统计
	TotalDuration time.Duration
	AvgDuration   time.Duration
	MaxDuration   time.Duration
	MinDuration   time.Duration
	DurationCount int64
	// contains filtered or unexported fields
}

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

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

type MetricsCollector interface {
	// RecordPublished 记录事件发布成功
	RecordPublished(tenantID int, aggregateType, eventType string)

	// RecordFailed 记录事件发布失败
	RecordFailed(tenantID int, aggregateType, eventType string, err error)

	// RecordRetry 记录事件重试
	RecordRetry(tenantID int, aggregateType, eventType string)

	// RecordDLQ 记录事件进入死信队列
	RecordDLQ(tenantID int, aggregateType, eventType string)

	// RecordPublishDuration 记录发布耗时
	RecordPublishDuration(tenantID int, aggregateType, eventType string, duration time.Duration)

	// SetPendingCount 设置待发布事件数量
	SetPendingCount(tenantID int, count int64)

	// SetFailedCount 设置失败事件数量
	SetFailedCount(tenantID int, count int64)

	// SetDLQCount 设置死信队列事件数量
	SetDLQCount(tenantID int, count int64)
}

type NoOpDLQAlertHandler struct{}

type NoOpDLQHandler struct{}

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

type NoOpMetricsCollector struct{}

type OutboxEvent struct {
	// ID 事件唯一标识（UUID）
	ID string

	// TenantID 租户 ID（多租户支持）
	TenantID int

	// AggregateID 聚合根 ID
	AggregateID string

	// AggregateType 聚合根类型（用于 Topic 映射）
	// 例如："Archive", "Media", "User"
	AggregateType string

	// EventType 事件类型
	// 例如："ArchiveCreated", "MediaUploaded", "UserRegistered"
	EventType string

	// Payload 事件负载（JSON 格式）
	Payload jxtjson.RawMessage

	// Status 事件状态
	Status EventStatus

	// RetryCount 重试次数
	RetryCount int

	// MaxRetries 最大重试次数
	MaxRetries int

	// LastError 最后一次错误信息
	LastError string

	// CreatedAt 创建时间
	CreatedAt time.Time

	// UpdatedAt 更新时间
	UpdatedAt time.Time

	// PublishedAt 发布时间
	PublishedAt *time.Time

	// ScheduledAt 计划发布时间（延迟发布）
	ScheduledAt *time.Time

	// LastRetryAt 最后重试时间
	LastRetryAt *time.Time

	// Version 事件版本（用于事件演化）
	Version int64

	// TraceID 链路追踪ID（用于分布式追踪）
	// 用于追踪事件在多个微服务之间的流转
	TraceID string

	// CorrelationID 关联ID（用于关联相关事件）
	// 用于关联同一业务流程中的多个事件（例如：Saga 模式）
	CorrelationID string

	// IdempotencyKey 幂等性键（用于防止重复发布）
	// 格式建议：{TenantID}:{AggregateType}:{AggregateID}:{EventType}:{Timestamp}
	// 或者使用业务自定义的唯一标识
	// 用于在发布前检查是否已经发布过相同的事件
	IdempotencyKey string
}

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

type OutboxRepository interface {
	// Save 保存事件（在事务中）
	// ctx: 上下文（可能包含事务信息）
	// event: 要保存的事件
	Save(ctx context.Context, event *OutboxEvent) error

	// SaveBatch 批量保存事件（在事务中）
	// ctx: 上下文（可能包含事务信息）
	// events: 要保存的事件列表
	SaveBatch(ctx context.Context, events []*OutboxEvent) error

	// FindPendingEvents 查找待发布的事件
	// ctx: 上下文
	// limit: 最大返回数量
	// tenantID: 租户 ID（可选，0 表示查询所有租户）
	FindPendingEvents(ctx context.Context, limit int, tenantID int) ([]*OutboxEvent, error)

	// FindPendingEventsWithDelay 查找创建时间超过指定延迟的待发布事件
	// 用于调度器避让机制，防止与立即发布产生竞态
	// ctx: 上下文
	// tenantID: 租户 ID（可选）
	// delaySeconds: 延迟秒数（只查询创建时间超过此延迟的事件）
	// limit: 最大返回数量
	FindPendingEventsWithDelay(ctx context.Context, tenantID int, delaySeconds int, limit int) ([]*OutboxEvent, error)

	// FindEventsForRetry 查找需要重试的失败事件
	// ctx: 上下文
	// maxRetries: 最大重试次数（只查询重试次数小于此值的事件）
	// limit: 最大返回数量
	FindEventsForRetry(ctx context.Context, maxRetries int, limit int) ([]*OutboxEvent, error)

	// FindByAggregateType 根据聚合类型查找待发布事件
	// ctx: 上下文
	// aggregateType: 聚合类型
	// limit: 最大返回数量
	FindByAggregateType(ctx context.Context, aggregateType string, limit int) ([]*OutboxEvent, error)

	// FindByID 根据 ID 查找事件
	// ctx: 上下文
	// id: 事件 ID
	FindByID(ctx context.Context, id string) (*OutboxEvent, error)

	// FindByAggregateID 根据聚合根 ID 查找事件
	// ctx: 上下文
	// aggregateID: 聚合根 ID
	// tenantID: 租户 ID（可选）
	FindByAggregateID(ctx context.Context, aggregateID string, tenantID int) ([]*OutboxEvent, error)

	// Update 更新事件
	// ctx: 上下文
	// event: 要更新的事件
	Update(ctx context.Context, event *OutboxEvent) error

	// MarkAsPublished 标记事件为已发布
	// ctx: 上下文
	// id: 事件 ID
	MarkAsPublished(ctx context.Context, id string) error

	// MarkAsFailed 标记事件为失败
	// ctx: 上下文
	// id: 事件 ID
	// err: 错误信息
	MarkAsFailed(ctx context.Context, id string, err error) error

	// IncrementRetry 增加重试次数（同时更新错误信息和最后重试时间）
	// ctx: 上下文
	// id: 事件 ID
	// errorMsg: 错误信息
	IncrementRetry(ctx context.Context, id string, errorMsg string) error

	// MarkAsMaxRetry 标记事件为超过最大重试次数
	// ctx: 上下文
	// id: 事件 ID
	// errorMsg: 错误信息
	MarkAsMaxRetry(ctx context.Context, id string, errorMsg string) error

	// IncrementRetryCount 增加重试次数（已废弃，使用 IncrementRetry 代替）
	// ctx: 上下文
	// id: 事件 ID
	// Deprecated: 使用 IncrementRetry 代替
	IncrementRetryCount(ctx context.Context, id string) error

	// Delete 删除事件
	// ctx: 上下文
	// id: 事件 ID
	Delete(ctx context.Context, id string) error

	// DeleteBatch 批量删除事件
	// ctx: 上下文
	// ids: 事件 ID 列表
	DeleteBatch(ctx context.Context, ids []string) error

	// DeletePublishedBefore 删除指定时间之前已发布的事件
	// ctx: 上下文
	// before: 时间阈值
	// tenantID: 租户 ID（可选）
	DeletePublishedBefore(ctx context.Context, before time.Time, tenantID int) (int64, error)

	// DeleteFailedBefore 删除指定时间之前失败的事件
	// ctx: 上下文
	// before: 时间阈值
	// tenantID: 租户 ID（可选）
	DeleteFailedBefore(ctx context.Context, before time.Time, tenantID int) (int64, error)

	// Count 统计事件数量
	// ctx: 上下文
	// status: 事件状态（可选，空字符串表示所有状态）
	// tenantID: 租户 ID（可选）
	Count(ctx context.Context, status EventStatus, tenantID int) (int64, error)

	// CountByStatus 按状态统计事件数量
	// ctx: 上下文
	// tenantID: 租户 ID（可选）
	// 返回：map[EventStatus]int64
	CountByStatus(ctx context.Context, tenantID int) (map[EventStatus]int64, error)

	// FindByIdempotencyKey 根据幂等性键查找事件
	// ctx: 上下文
	// idempotencyKey: 幂等性键
	// 返回：事件对象（如果不存在返回 nil）
	FindByIdempotencyKey(ctx context.Context, idempotencyKey string) (*OutboxEvent, error)

	// ExistsByIdempotencyKey 检查幂等性键是否已存在
	// ctx: 上下文
	// idempotencyKey: 幂等性键
	// 返回：true 表示已存在，false 表示不存在
	ExistsByIdempotencyKey(ctx context.Context, idempotencyKey string) (bool, error)

	// FindPublishedByIdempotencyKeys returns the subset of `keys` that are already
	// marked as Published. Used by publisher.filterPublishedEvents to perform a
	// single batched idempotency check instead of N individual FindByIdempotencyKey
	// queries.
	//
	// Keys not present in the returned set are safe to publish (either no event
	// with that key exists, or it's still Pending).
	//
	// Implementations must handle empty input gracefully (return empty map, no error).
	FindPublishedByIdempotencyKeys(ctx context.Context, keys []string) (map[string]struct{}, error)

	// FindMaxRetryEvents 查找超过最大重试次数的事件
	// ctx: 上下文
	// limit: 最大返回数量
	// tenantID: 租户 ID（可选）
	// 返回：事件列表
	FindMaxRetryEvents(ctx context.Context, limit int, tenantID int) ([]*OutboxEvent, error)

	// MarkBatchAsPublished transitions a batch of events from Pending to Published
	// using a single UPDATE statement (status='published', published_at=now,
	// updated_at=now WHERE id IN (?) AND status='pending').
	//
	// Intended for use by sync-semantics publishers (InProcess) where
	// PublishEnvelope's nil return means the publish has effectively completed.
	// Async-semantics publishers (Kafka/NATS) must rely on the ACK listener
	// for marking instead — they do NOT call this method synchronously.
	//
	// The method is idempotent: events already in a non-Pending state are
	// skipped by the WHERE clause.
	MarkBatchAsPublished(ctx context.Context, events []*OutboxEvent) error
}

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

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

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

type PublishResult struct {
	// EventID 事件ID（来自 Envelope.EventID）
	EventID string
	// Topic 主题
	Topic string
	// Success 是否成功
	Success bool
	// Error 错误信息（失败时）
	Error error
	// Timestamp 发布时间戳
	Timestamp time.Time
	// AggregateID 聚合ID（可选，来自 Envelope）
	AggregateID string
	// EventType 事件类型（可选，来自 Envelope）
	EventType string
	// TenantID 租户ID（多租户支持，用于Outbox ACK路由）
	TenantID int
}

type PublisherConfig struct {
	// MaxRetries 最大重试次数
	MaxRetries int

	// RetryDelay 重试延迟
	RetryDelay time.Duration

	// PublishTimeout 发布超时时间
	PublishTimeout time.Duration

	// EnableMetrics 是否启用指标收集
	EnableMetrics bool

	// MetricsCollector 指标收集器（可选）
	// 用于集成 Prometheus、StatsD 等监控系统
	MetricsCollector MetricsCollector

	// ErrorHandler 错误处理器（可选）。
	// event 可能为 nil：单事件路径（PublishEvent）传非 nil event；
	// batch/ACK 级错误（MarkBatchAsPublished 失败、ACK listener 标记失败、NACK）无法关联单个事件，传 nil。
	// 实现者不应假设 event 永远非 nil。
	ErrorHandler func(event *OutboxEvent, err error)

	// ConcurrentPublish 是否启用并发发布（默认 false）
	ConcurrentPublish bool

	// PublishConcurrency 并发发布的并发数（默认 10）
	// 只有当 ConcurrentPublish = true 时生效
	PublishConcurrency int

	// ACKBatchSize 攒批成功 ACK 标记的最大条数；满则立即 flush 一次 MarkBatchAsPublished。
	// 0 = 禁用攥批（回退逐条 MarkAsPublished）。默认 50。
	ACKBatchSize int

	// ACKBatchFlushInterval 攒批 flush 间隔（ACKBatchSize>0 时生效）。
	// 0 或未设 = 使用默认 200ms（newAckMarkerBatcher 对 <=0 钳为 200ms，故 0 不是"永不定时 flush"，F-New-2）。
	ACKBatchFlushInterval time.Duration

	// ACKBatchFailureThreshold 连续 flush 失败的告警阈值；达阈值（及倍数）经 ErrorHandler 告警。
	// 0 = 每次失败都告警。默认 5。
	ACKBatchFailureThreshold int
}

type PublisherMetrics struct {
	// PublishedCount 已发布事件数量
	PublishedCount int64

	// FailedCount 失败事件数量
	FailedCount int64

	// ErrorCount 错误事件数量（批量发布时使用）
	ErrorCount int64

	// RetryCount 重试次数
	RetryCount int64

	// LastPublishTime 最后发布时间
	LastPublishTime time.Time

	// LastError 最后错误
	LastError error
}

type RepositoryStats struct {
	// PendingCount 待发布事件数量
	PendingCount int64

	// PublishedCount 已发布事件数量
	PublishedCount int64

	// FailedCount 失败事件数量
	FailedCount int64

	// TotalCount 总事件数量
	TotalCount int64

	// OldestPendingAge 最老的待发布事件年龄
	OldestPendingAge time.Duration

	// TenantID 租户 ID
	TenantID int
}

type RepositoryStatsProvider interface {
	// GetStats 获取统计信息
	// ctx: 上下文
	// tenantID: 租户 ID（可选）
	GetStats(ctx context.Context, tenantID int) (*RepositoryStats, error)
}

type SchedulerConfig struct {
	// PollInterval 轮询间隔
	PollInterval time.Duration

	// BatchSize 每次处理的事件数量
	BatchSize int

	// TenantID 租户 ID（可选，0 表示处理所有租户）
	TenantID int

	// CleanupInterval 清理间隔
	CleanupInterval time.Duration

	// CleanupRetention 清理保留时间（已发布事件保留多久）
	CleanupRetention time.Duration

	// HealthCheckInterval 健康检查间隔
	HealthCheckInterval time.Duration

	// EnableHealthCheck 是否启用健康检查
	EnableHealthCheck bool

	// EnableCleanup 是否启用自动清理
	EnableCleanup bool

	// EnableMetrics 是否启用指标收集
	EnableMetrics bool

	// EnableRetry 是否启用失败重试
	EnableRetry bool

	// RetryInterval 重试间隔
	RetryInterval time.Duration

	// MaxRetries 最大重试次数
	MaxRetries int

	// EnableDLQ 是否启用死信队列
	EnableDLQ bool

	// DLQInterval 死信队列处理间隔
	DLQInterval time.Duration

	// DLQHandler 死信队列处理器（可选）
	// 用于处理超过最大重试次数的失败事件
	DLQHandler DLQHandler

	// DLQAlertHandler 死信队列告警处理器（可选）
	// 用于发送告警通知
	DLQAlertHandler DLQAlertHandler

	// MetricsCollector 指标收集器（可选）
	// 用于集成 Prometheus、StatsD 等监控系统
	MetricsCollector MetricsCollector

	// ShutdownTimeout 优雅关闭超时时间
	// 调度器停止时等待正在处理的任务完成的最大时间
	// 默认：30 秒
	ShutdownTimeout time.Duration
}

type SchedulerMetrics struct {
	// PollCount 轮询次数（原子操作）
	PollCount atomic.Int64

	// ProcessedCount 处理的事件数量（原子操作）
	ProcessedCount atomic.Int64

	// ErrorCount 错误次数（原子操作）
	ErrorCount atomic.Int64

	// LastPollTime 最后轮询时间（原子操作）
	LastPollTime atomic.Value // time.Time

	// LastCleanupTime 最后清理时间（原子操作）
	LastCleanupTime atomic.Value // time.Time

	// RetryCount 重试次数（原子操作）
	RetryCount atomic.Int64

	// RetriedCount 重试成功的事件数量（原子操作）
	RetriedCount atomic.Int64

	// LastRetryTime 最后重试时间（原子操作）
	LastRetryTime atomic.Value // time.Time

	// LastError 最后错误（原子操作）
	LastError atomic.Value // error
}

type SchedulerMetricsSnapshot struct {
	PollCount       int64
	ProcessedCount  int64
	ErrorCount      int64
	LastPollTime    time.Time
	LastCleanupTime time.Time
	RetryCount      int64
	RetriedCount    int64
	LastRetryTime   time.Time
	LastError       error
}

type SchedulerOption func(*schedulerOptions)

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

type SyncSemanticsPublisher interface {
	EventPublisher

	// IsSyncSemantics is a marker method with no implementation. Its presence
	// on an EventPublisher type signals sync semantics to the publisher.
	IsSyncSemantics()
}

type TopicMapper interface {
	// GetTopic 根据聚合类型获取 Topic
	//
	// 参数：
	//   aggregateType: 聚合类型（例如："Archive", "Media", "User"）
	//
	// 返回：
	//   string: Topic 名称（例如："archive-events", "media-events"）
	//
	// 注意：
	//   - 如果聚合类型未映射，应该返回默认 Topic 或错误
	//   - Topic 名称应该符合 EventBus 的命名规范
	GetTopic(aggregateType string) string
}

type TransactionalRepository interface {
	OutboxRepository

	// SaveInTx 在事务中保存事件
	// ctx: 上下文
	// tx: 事务对象（具体类型由实现决定，例如 *gorm.DB）
	// event: 要保存的事件
	SaveInTx(ctx context.Context, tx interface{}, event *OutboxEvent) error

	// BeginTx 开始事务
	// ctx: 上下文
	// 返回：事务对象
	BeginTx(ctx context.Context) (interface{}, error)

	// CommitTx 提交事务
	// tx: 事务对象
	CommitTx(tx interface{}) error

	// RollbackTx 回滚事务
	// tx: 事务对象
	RollbackTx(tx interface{}) error
}