junhong_cmp_fiber/pkg/constants/polling.go

package constants

// PollingShardCount 轮询队列默认分片数
// 千万级规模下，16 分片可将单队列深度控制在 ~60 万以内
const PollingShardCount = 16

// PollingBackpressureThreshold 单分片队列背压阈值
// 超过此深度时，Scheduler 跳过该分片本轮出队，防止 Asynq 积压过载
// 默认 50 万，可根据 Asynq Worker 处理速度调整
const PollingBackpressureThreshold = 500_000

// PollingDequeueMaxBatchSize Lua 脚本单次出队上限
// 受 Lua unpack() 的 LUAI_MAXCSTACK 约 8000 限制，保守取 7000
const PollingDequeueMaxBatchSize = 7000

// PollingDefaultMaxConcurrency 并发信号量默认上限
// 读取 Redis 配置 key 失败时使用，作为安全兜底值
// 300：支撑 10M 卡、2小时 carddata 间隔（Gateway 200ms → 300并发 = 1500任务/秒/类型）
const PollingDefaultMaxConcurrency = 300

// PollingDefaultTotalMaxConcurrency 全部轮询任务共享的默认总并发上限。
const PollingDefaultTotalMaxConcurrency = 100

// PollingMaxConcurrencyLimit 轮询并发配置的代码安全上限。
const PollingMaxConcurrencyLimit = 1000

// PollingConcurrencyKeyTTL 并发计数 key 的过期时间（秒）
// 保证 Worker 意外崩溃（defer Decr 未执行）时计数器在此时间内自动归零
const PollingConcurrencyKeyTTL = 600 // 10 分钟

// 轮询手动触发日志状态常量
const (
	// PollingManualTriggerStatusPending 轮询手动触发日志状态-待处理
	PollingManualTriggerStatusPending = "pending"
	// PollingManualTriggerStatusProcessing 轮询手动触发日志状态-处理中
	PollingManualTriggerStatusProcessing = "processing"
	// PollingManualTriggerStatusCompleted 轮询手动触发日志状态-已完成
	PollingManualTriggerStatusCompleted = "completed"
	// PollingManualTriggerStatusCancelled 轮询手动触发日志状态-已取消
	PollingManualTriggerStatusCancelled = "cancelled"
)

// PollingPriorityMaxAttempts 优先轮询项固定的最大尝试次数。
// 尝试次数只在真正发起执行后累加；达到上限记录失败终态并出队。
// 本值不是可维护配置项，也不改变普通轮询的无限重试策略。
const PollingPriorityMaxAttempts = 3

// PollingPriorityClaimLease 优先轮询项的认领租约（秒）。
// 必须长于既有轮询任务超时 60 秒，为执行收尾与重新入队留出余量；
// 执行中且超过租约仍未被更新的优先项允许相邻执行接管领取。
const PollingPriorityClaimLease = 90

// 轮询优先队列状态常量
const (
	// PollingPriorityStatusPending 优先轮询项状态-待执行（活动项）
	PollingPriorityStatusPending = "pending"
	// PollingPriorityStatusProcessing 优先轮询项状态-执行中（活动项，受认领租约保护）
	PollingPriorityStatusProcessing = "processing"
	// PollingPriorityStatusCompleted 优先轮询项状态-已完成（终态，已出队）
	PollingPriorityStatusCompleted = "completed"
	// PollingPriorityStatusFailed 优先轮询项状态-失败出队（终态）
	PollingPriorityStatusFailed = "failed"
)

// 轮询优先项触发类型常量
const (
	// PollingPriorityTriggerPurchaseActivated 主套餐购买后立即生效
	PollingPriorityTriggerPurchaseActivated = "purchase_activated"
	// PollingPriorityTriggerRenewalActivated 同载体在本次生效前已存在更早套餐使用记录
	PollingPriorityTriggerRenewalActivated = "renewal_activated"
	// PollingPriorityTriggerQueueActivated 排队主套餐顺延生效
	PollingPriorityTriggerQueueActivated = "queue_activated"
	// PollingPriorityTriggerAddonActivated 加油包生效
	PollingPriorityTriggerAddonActivated = "addon_activated"
	// PollingPriorityTriggerNoValidPackage 资产无有效套餐且存在待生效套餐使用记录
	PollingPriorityTriggerNoValidPackage = "no_valid_package"
	// PollingPriorityTriggerManual 具备既有人工触发权限的账号人工入队
	PollingPriorityTriggerManual = "manual_trigger"
)

// PollingPriorityManualReasonMaxLength 是人工优先入队原因的长度上限，与事实表 manual_reason 列一致。
const PollingPriorityManualReasonMaxLength = 500

// 轮询优先项执行结果常量
const (
	// PollingPriorityResultSuccess 优先轮询项执行成功
	PollingPriorityResultSuccess = "success"
	// PollingPriorityResultFailed 优先轮询项执行失败
	PollingPriorityResultFailed = "failed"
)

// 轮询优先项请求可靠事件常量
const (
	// OutboxEventTypePollingPriorityRequested 表示业务成功事实请求为该资源的卡建立优先轮询项。
	// 载荷中的卡快照在业务事务内冻结，消费者据此逐卡建项并下发执行提示。
	OutboxEventTypePollingPriorityRequested = "polling.priority.requested"
	// PollingPriorityRequestedPayloadVersionV1 是优先轮询请求事件载荷版本。
	PollingPriorityRequestedPayloadVersionV1 = 1
	// PollingPriorityEventKeyPrefix 是优先轮询请求事件的 event_id 命名空间前缀。
	// 必须与既有 card-observation: 前缀分离：公共 Outbox 的 event_id 是全局幂等键，
	// 复用既有前缀会被 OnConflict DoNothing 静默去重，导致加急永不生效且无任何报错。
	//
	// 长度预算：Outbox 的 event_id 列为 varchar(64)，前缀与后缀共同保证生成的 ID 明显低于上限
	// （当前最长形式为 prio:nvp:{载体检字}:{载体ID}:{秒级时间戳}，不超过 43 字符）。
	// 前缀与后缀都不得再加长；新增场景必须按同一预算核算。
	PollingPriorityEventKeyPrefix = "prio:"
)

// PollingPriorityTaskTypes 返回纳入优先轮询的既有轮询任务类型。
// 一次优先需求对应这些任务类型各执行一次；保护期一致性检查不在集合内。
// 返回新切片，调用方修改不会影响其它调用方。
func PollingPriorityTaskTypes() []string {
	return []string{
		TaskTypePollingRealname,
		TaskTypePollingCarddata,
		TaskTypePollingPackage,
		TaskTypePollingCardStatus,
	}
}

// PollingPriorityStatusName 返回优先轮询项状态的中文名称。
func PollingPriorityStatusName(status string) string {
	switch status {
	case PollingPriorityStatusPending:
		return "待执行"
	case PollingPriorityStatusProcessing:
		return "执行中"
	case PollingPriorityStatusCompleted:
		return "已完成"
	case PollingPriorityStatusFailed:
		return "失败出队"
	default:
		return "未知"
	}
}

// PollingPriorityTriggerName 返回优先轮询项触发类型的中文名称。
func PollingPriorityTriggerName(triggerType string) string {
	switch triggerType {
	case PollingPriorityTriggerPurchaseActivated:
		return "主套餐购买后立即生效"
	case PollingPriorityTriggerRenewalActivated:
		return "续购套餐生效"
	case PollingPriorityTriggerQueueActivated:
		return "排队主套餐顺延生效"
	case PollingPriorityTriggerAddonActivated:
		return "加油包生效"
	case PollingPriorityTriggerNoValidPackage:
		return "资产无有效套餐"
	case PollingPriorityTriggerManual:
		return "人工入队"
	default:
		return "未知"
	}
}

// PollingPriorityResultName 返回优先轮询项执行结果的中文名称。
func PollingPriorityResultName(result string) string {
	switch result {
	case PollingPriorityResultSuccess:
		return "成功"
	case PollingPriorityResultFailed:
		return "失败"
	default:
		return "未出结果"
	}
}

// PollingPriorityTaskTypeName 返回优先轮询任务类型的中文名称。
func PollingPriorityTaskTypeName(taskType string) string {
	switch taskType {
	case TaskTypePollingRealname:
		return "实名检查"
	case TaskTypePollingCarddata:
		return "流量检查"
	case TaskTypePollingPackage:
		return "套餐检查"
	case TaskTypePollingCardStatus:
		return "卡状态检查"
	default:
		return "未知"
	}
}