feat(轮询优先队列): AUG26-016 卡轮询优先队列、人工入队与读侧接口，归档并同步主 Spec 与证据矩阵

新增 000228 成对迁移 tb_polling_priority_item：卡、任务类型、状态、触发类型、来源订单/套餐使用记录、
触发次数与来源集合、尝试次数、失败原因、人工原因与操作者、店铺快照与各时间列；以活动项部分唯一索引
uq_polling_priority_item_active（仅 deleted_at IS NULL AND status IN ('pending','processing') 占键位）
表达「同卡同任务类型至多一条活动项」，另有状态/时间索引与全列注释；down 守卫在存在活动项或未终态行时
拒绝回滚并给出中文原因。

新增优先轮询请求可靠事件 polling.priority.requested（载荷版本 v1、事件键前缀 prio:）与消费者：只在原
业务事务内追加、幂等键稳定；消费者按卡 × 纳入任务类型（realname/carddata/card_status/package）逐条
建项并在提交后下发执行提示，重复投递只合并触发次数、来源集合与最近触发时间，不新建行也不重复调用。
触发点为四类自动场景 purchase_activated / renewal_activated（按同载体更早套餐使用记录判定）/
queue_activated / addon_activated 与「无有效套餐」no_valid_package（仅在普通套餐轮询来源且存在待生效
套餐使用记录时追加；事件通道显式拒绝 manual_trigger）；入队对象恒为卡，绑定设备资产在触发事务内冻结
在用卡快照逐卡建项，不使用设备当前卡槽口径。

轮询共享基类新增认领接缝：四个 Handler（realname/carddata/card_status/package）在并发信号量之后、调用
上游之前探测活动项——待执行条件认领、执行中且 90 秒租约未到期则跳过并延后、无活动项时行为与既有完全
等价；超租约允许相邻执行接管，尝试次数只在真正发起执行后累加，未达上限（3）回到活动态按既有间隔重排，
达上限或业务校验类失败进入失败终态并保留可安全展示原因；执行前校验卡自身与绑定设备的轮询开关。未引入
通用卡级锁与 Redis 活动标记，分片队列的出队、入队与移除路径未改动。

提示通道按任务类型独立键（polling:priority:{taskType}），与既有手动触发队列分离；调度器在同一周期内先
排空优先提示、再排空手动触发队列，提示排空不受分片背压跳过影响；未新建调度设施或异步任务类型。

新增人工优先入队与只读查询三条路由 POST /api/admin/polling-priority-items、
GET /api/admin/polling-priority-items、GET /api/admin/polling-priority-items/:id：人工入队复用既有轮询
权限判定（抽取为同包共享函数），原因必填，不受每日 500 次上限与 24 小时去重约束，重复抑制由活动项合并
承担；读侧按店铺快照下推数据范围，越权与不存在不可区分，不提供优先级分级、有效期或人工重触发入口。
新增 7 个审计动作（enqueue/claim/fail/retry/complete/dequeue/manual_denied）与资源
polling_priority_item，并按（操作者类型，来源）注册，人工侧与 Worker 侧均通过来源校验。

同步 OpenAPI 文档装配三处与路由注册；归档 Change 至
openspec/changes/archive/2026-09-17-add-priority-polling-queue/ 并同步主 Spec（新增
priority-polling-queue、polling-operations 追加单次执行互斥 Requirement 与三条路由索引）与上下文健康
证据（requirement-evidence 150 行、入口矩阵 http 403 / async 56）。

本机验证：junhong_cmp_test 与隔离 Redis DB 15，未连生产、未启动 Worker/API、未调用运营商上游；迁移
up/down/up 与 down 守卫实测（含 dirty=true 记账口径与 force 恢复），A–F 批 94 PASS、接缝 63 PASS、
提示通道 12 PASS、清理零残留 20 PASS。成功路径 Complete、真并发互斥、尝试上限第 3 次判定、HTTP 层权限
矩阵、通道阈值持锁复机边界与三类生效触发点生产集成留待测试部署验证（见
docs/verification/add-priority-polling-queue-verification.md 第 4 节）。自动化测试按项目决策为 N/A，
未新增 *_test.go。

pkg/constants/audit.go

@@ -594,6 +594,20 @@ const (
 	AuditActionPollingManualTriggerByCondition = "polling_manual_trigger.trigger_by_condition"
 	// AuditActionPollingManualCancelled 表示人工取消轮询任务。
 	AuditActionPollingManualCancelled = "polling_manual_trigger.cancel_trigger"
+	// AuditActionPollingPriorityEnqueued 表示建立或合并卡轮询优先项（自动触发与人工入队共用）。
+	AuditActionPollingPriorityEnqueued = "polling_priority.enqueue"
+	// AuditActionPollingPriorityClaimed 表示轮询执行领取卡轮询优先项。
+	AuditActionPollingPriorityClaimed = "polling_priority.claim"
+	// AuditActionPollingPriorityFailed 表示一次卡轮询优先执行失败。
+	AuditActionPollingPriorityFailed = "polling_priority.fail"
+	// AuditActionPollingPriorityRetried 表示未达尝试上限的失败退回活动态重新排期。
+	AuditActionPollingPriorityRetried = "polling_priority.retry"
+	// AuditActionPollingPriorityCompleted 表示卡轮询优先项执行完成并出队。
+	AuditActionPollingPriorityCompleted = "polling_priority.complete"
+	// AuditActionPollingPriorityDequeued 表示达到尝试上限的卡轮询优先项失败出队。
+	AuditActionPollingPriorityDequeued = "polling_priority.dequeue"
+	// AuditActionPollingPriorityManualDenied 表示拒绝一次人工优先入队。
+	AuditActionPollingPriorityManualDenied = "polling_priority.manual_denied"
 	// AuditActionWeComCredentialsRead 表示读取企业微信应用明文凭据。
 	AuditActionWeComCredentialsRead = "wecom.application.credentials_read"
 	// AuditActionRoleCreated 表示创建角色。
@@ -731,6 +745,8 @@ const (
 	AuditResourcePollingAlertRule = "polling_alert"
 	// AuditResourcePollingManualTrigger 表示手动轮询任务资源。
 	AuditResourcePollingManualTrigger = "polling_manual_trigger"
+	// AuditResourcePollingPriorityItem 表示卡轮询优先项资源。
+	AuditResourcePollingPriorityItem = "polling_priority_item"
 	// AuditResourceDevice 表示设备资源。
 	AuditResourceDevice = "device"
 	// AuditResourceIotCard 表示 IoT 卡资源。

pkg/constants/polling.go

@@ -39,3 +39,145 @@ const (
 	// 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 "未知"
+	}
+}

pkg/constants/redis.go

@@ -308,6 +308,15 @@ func RedisPollingManualDedupeKey(taskType string) string {
 	return fmt.Sprintf("polling:manual:dedupe:%s", taskType)
 }
 
+// RedisPollingPriorityQueueKey 生成优先轮询提示通道的 Redis 键
+// 用途：List 存储需要优先执行的卡 ID；与手动触发队列（polling:manual:{taskType}）分离，
+// 使调度器在同一调度周期内先排空优先提示、再排空手动触发队列。
+// 提示通道不是权威：丢失时库内活动优先项仍在，后续普通轮询执行按条件认领仍会执行。
+// 过期时间：无（临时队列）
+func RedisPollingPriorityQueueKey(taskType string) string {
+	return fmt.Sprintf("polling:priority:%s", taskType)
+}
+
 // RedisPollingStatsKey 生成监控统计的 Redis 键
 // 用途：Hash 存储监控指标（成功数、失败数、总耗时等）
 // 过期时间：无（持久化统计）

pkg/openapi/handlers.go

@@ -68,6 +68,7 @@ func BuildDocHandlers() *bootstrap.Handlers {
 		PollingAlert:                admin.NewPollingAlertHandler(nil),
 		PollingCleanup:              admin.NewPollingCleanupHandler(nil),
 		PollingManualTrigger:        admin.NewPollingManualTriggerHandler(nil),
+		PollingPriority:             admin.NewPriorityPollingHandler(nil, nil, nil),
 		Asset:                       admin.NewAssetHandler(nil, nil, nil, nil, nil, nil, nil),
 		AssetLifecycle:              admin.NewAssetLifecycleHandler(nil),
 		AssetWallet:                 admin.NewAssetWalletHandler(nil),

pkg/queue/handler.go

@@ -377,6 +377,7 @@ func (h *Handler) registerAutoPurchaseHandler() {
 		h.asynqClient,
 		h.logger,
 		h.workerResult.Services.ObservationSeriesEvents,
+		h.workerResult.Services.PriorityEvents,
 		audit.NewWriter(audit.NewRegistry(), nil),
 	)
 	h.mux.HandleFunc(constants.TaskTypeAutoPurchaseAfterRecharge, autoPurchaseHandler.ProcessTask)

pkg/queue/types.go

@@ -6,6 +6,7 @@ import (
 	agentrechargeApp "github.com/break/junhong_cmp_fiber/internal/application/agentrecharge"
 	cardObservationApp "github.com/break/junhong_cmp_fiber/internal/application/cardobservation"
 	carrierthresholdApp "github.com/break/junhong_cmp_fiber/internal/application/carrierthreshold"
+	priorityapp "github.com/break/junhong_cmp_fiber/internal/application/prioritypolling"
 	"github.com/break/junhong_cmp_fiber/internal/service/commission_calculation"
 	"github.com/break/junhong_cmp_fiber/internal/service/commission_stats"
 	packagepkg "github.com/break/junhong_cmp_fiber/internal/service/package"
@@ -66,6 +67,7 @@ type WorkerServices struct {
 	CardObservation         *cardObservationApp.Service
 	CardObservationSeries   *cardObservationApp.SeriesAttemptService
 	ObservationSeriesEvents cardObservationApp.SeriesEventWriter
+	PriorityEvents          priorityapp.PriorityEventWriter
 	CommissionCalculation   *commission_calculation.Service
 	CommissionStats         *commission_stats.Service
 	UsageService            *packagepkg.UsageService