break
aab56a6998
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 14m13s
新增 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。
63 lines
3.2 KiB
Go
63 lines
3.2 KiB
Go
// Package prioritypolling 定义卡轮询优先队列的应用层契约。
|
||
//
|
||
// 本包只承载业务事实的形状与执行语义，不依赖 Fiber、GORM、Redis、Asynq 或具体外部 SDK；
|
||
// Outbox 写入、消费者展开与执行接缝适配分别位于基础设施与任务层。
|
||
package prioritypolling
|
||
|
||
import (
|
||
"context"
|
||
"time"
|
||
|
||
"gorm.io/gorm"
|
||
)
|
||
|
||
// PriorityRequestedEvent 是业务成功边界可靠请求「为该资源的卡建立优先轮询项」的事实。
|
||
//
|
||
// 载荷沿用既有业务观测事件的形状（资源类型 / 资源 ID / 资源 ID 列表），并在业务事务内冻结卡快照：
|
||
// 独立卡为自身（ResourceIDs 为空），绑定设备的资产为绑定状态有效的全部在用卡（写入 ResourceIDs）。
|
||
// TriggerType 取值与 pkg/constants.PollingPriorityTrigger* 一致；本轮要逐类型建项的任务类型集合
|
||
// 由代码常量给出（pkg/constants.PollingPriorityTaskTypes），不由事件载荷决定，避免同一决策出现两个权威。
|
||
// 来源订单与来源套餐使用记录只保存 ID，由消费者与读侧显式查询。
|
||
type PriorityRequestedEvent struct {
|
||
EventID string `json:"event_id"`
|
||
ResourceType string `json:"resource_type"`
|
||
ResourceID uint `json:"resource_id"`
|
||
ResourceIDs []uint `json:"resource_ids,omitempty"`
|
||
TriggerType string `json:"trigger_type"`
|
||
SourceOrderID uint `json:"source_order_id,omitempty"`
|
||
SourcePackageUsageID uint `json:"source_package_usage_id,omitempty"`
|
||
OccurredAt time.Time `json:"occurred_at"`
|
||
RequestID string `json:"request_id,omitempty"`
|
||
CorrelationID string `json:"correlation_id,omitempty"`
|
||
}
|
||
|
||
// PromptPublisher 把优先执行提示下发到既有轮询提示通道。
|
||
//
|
||
// 提示通道不是权威：丢失或缓存服务重启时库内活动优先项仍在，后续普通轮询执行按条件认领仍会执行，
|
||
// 只退化为延迟一个普通轮询周期；调用方不得以提示的下发成功作为入队事实成立的条件。
|
||
type PromptPublisher interface {
|
||
EnqueuePriority(ctx context.Context, cardID uint, taskType string) error
|
||
}
|
||
|
||
// PriorityEventWriter 在原业务事务中追加优先轮询请求事件。
|
||
type PriorityEventWriter interface {
|
||
AppendPriorityRequested(ctx context.Context, tx *gorm.DB, event PriorityRequestedEvent) error
|
||
}
|
||
|
||
type pollingPriorityTriggerKey struct{}
|
||
|
||
// WithPollingPriorityTrigger 标记本次业务评估来自普通套餐轮询。
|
||
//
|
||
// 「资产无有效套餐」这一场景在停复机评估内部判定，而该评估入口被观测消费者、手动实名、保护期轮询、
|
||
// 既有兼容入口等多条调用链复用；只有普通套餐轮询来源才允许追加优先轮询请求，
|
||
// 否则会在观测序列、手动实名、保护期与退款等上下文凭空产生加急触发。
|
||
func WithPollingPriorityTrigger(ctx context.Context) context.Context {
|
||
return context.WithValue(ctx, pollingPriorityTriggerKey{}, true)
|
||
}
|
||
|
||
// IsPollingPriorityTrigger 判断当前业务评估是否来自普通套餐轮询。
|
||
func IsPollingPriorityTrigger(ctx context.Context) bool {
|
||
value, _ := ctx.Value(pollingPriorityTriggerKey{}).(bool)
|
||
return value
|
||
}
|