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。
6.1 KiB
6.1 KiB
1. 迁移与模型存储
- 1.1 新增成对迁移
000228_add_polling_priority_queue：优先项表（卡、任务类型、状态、触发类型、来源订单/套餐使用记录、触发次数、来源集合、尝试次数、失败原因、人工原因与操作者、店铺快照、各时间列、软删列）、活动项部分唯一索引(card_id, task_type)（仅覆盖待执行/执行中且未软删）、状态与时间索引、全列注释 - 1.2 down 迁移守卫：存在活动项或未终态行时拒绝回滚并给出中文原因；与 up 严格成对
- 1.3 新增优先项模型与状态/触发类型取值常量，字段长度、可空与迁移一致；不新增外键与关联标签
- 1.4 新增存储层：合并插入（显式插入 + 唯一冲突识别，不用 OnConflict 打部分唯一索引）、条件认领、超租约接管、终态更新、按卡批量活动项查询、列表筛选与分页
- 1.5 新增常量：触发类型枚举、状态枚举、最大尝试次数（3）、认领租约（90 秒）、优先提示通道键生成函数
2. 触发事件与 Worker 注册
- 2.1 新增优先轮询请求事件类型与载荷版本常量；载荷含资源类型、资源 ID、冻结卡快照、触发类型、来源订单、来源套餐使用记录
- 2.2 新增事件 Writer：只在原业务事务内追加、幂等键稳定；观测结果驱动的业务评估上下文下短路不写
- 2.3 新增事件消费者：逐卡建立优先项（含合并语义）并下发执行提示；重复投递只合并
- 2.4 在 Worker 组装处注册该事件类型的消费者，保持事件类型唯一注册
3. 生效触发点接入
- 3.1 主套餐购买后立即生效路径：仅在生效状态分支追加事件；新购/续购按同载体更早套餐使用记录的存在性判定触发类型
- 3.2 排队主套餐顺延生效路径：条件更新命中一行后追加事件（触发类型
queue_activated） - 3.3 加油包生效路径：以生效状态提交后追加事件（触发类型
addon_activated） - 3.4 在 API 与 Worker 两个组装入口注入事件 Writer
- 3.5 确认支付失败、已取消与未支付到账路径不追加事件
4. 无有效套餐触发
- 4.1 在套餐轮询评估命中「无有效套餐」处增加判定：该载体存在待生效套餐使用记录时追加事件（触发类型
no_valid_package），否则不追加 - 4.2 该场景按资产解析绑定状态有效的全部在用卡（独立卡为自身），在触发事务内冻结快照，不使用当前卡槽口径
5. 互斥接缝与执行前校验
- 5.1 轮询共享基类新增认领接缝：活动项索引探测 → 待执行条件认领 / 执行中跳过并延后 / 无活动项时完全等价既有行为
- 5.2 四个纳入集合的轮询 Handler 接入接缝（取并发信号量之后、调用上游之前），成功、失败、跳过分支统一收口
- 5.3 实现认领租约与崩溃接管：执行中且超过 90 秒租约的项允许相邻执行接管
- 5.4 执行前轮询范围校验（卡自身与绑定设备的轮询开关），不满足时失败终态且不发起上游调用
- 5.5 尝试次数只在真正发起执行后累加；未达上限回活动态并按既有间隔重排；达上限失败终态并保留安全原因；业务校验类失败不重试
- 5.6 确认未引入通用卡级锁与 Redis 活动标记，且分片队列的出队、入队与移除路径未被改动
6. 提示通道与调度先排空
- 6.1 队列管理新增优先提示下发：每任务类型独立键，不复用手动触发队列键
- 6.2 调度器在同一周期内先排空优先提示、再排空手动触发队列；提示排空不受分片背压跳过影响
- 6.3 确认未新建调度设施、未新增异步任务类型或队列
7. 人工入队、读侧接口与路由装配
- 7.1 抽取既有人工触发权限判定为同包共享函数（超管/平台放行、代理限自身与下级、平台卡不可见、企业拒绝），判定语义不变
- 7.2 人工优先入队用例：解析资产标识、权限校验、原因必填、写事实并合并、下发提示、写审计；不受每日次数上限与 24 小时去重约束
- 7.3 读侧列表与详情用例：筛选、分页、按数据范围下推，越权与不存在响应不可区分
- 7.4 Handler 与路由注册（RouteSpec 摘要、标签、入参与出参类型），仅挂在既有后台认证中间件下
- 7.5 同步文档装配三处：文档工厂、API 组装与文档生成入口
- 7.6 事实表冗余卡所属店铺快照，供数据范围下推使用
8. 审计常量与注册
- 8.1 新增轮询优先队列审计动作与资源常量（入队、领取、失败、重试、完成、失败出队、人工拒绝）
- 8.2 按（操作者类型，来源）注册动作定义，人工侧与 Worker 侧均能通过来源校验
- 8.3 接入写入点：人工侧复用既有轮询审计输入与失败短事务模式；系统侧复用既有 Worker 审计上下文
9. 验证
- 9.1 在受控隔离环境执行迁移 up/down/up；确认 down 守卫在有活动项时拒绝回滚
- 9.2 验证三种生效触发、无有效套餐（含无待同步业务不入队）、支付失败与取消不入队、重复回调与事件重放幂等
- 9.3 验证合并（人工 + 自动）、同卡不同任务类型互不干扰、普通轮询互斥不产生第二次上游调用
- 9.4 验证认领租约接管、提示通道丢失兜底、执行前轮询范围校验、尝试上限与终态出队
- 9.5 验证权限矩阵：超管/平台全量、代理限自身与下级、范围外与平台卡不可见、企业拒绝
- 9.6 验证触发类型枚举：新购/续购判定、加油包、排队顺延、无有效套餐、人工
- 9.7 验证通道阈值边界：持锁卡的优先执行不复机且保留既有拒绝事实
- 9.8 运行
gofmt -w、go build ./cmd/api ./cmd/worker、go run cmd/gendocs/main.go、openspec validate add-priority-polling-queue --strict、openspec doctor --json、./scripts/context-health.sh；自动化测试按项目决策为 N/A