one-pipe-system/openspec/changes/add-polling-priority-queue/proposal.md

Change: 新增轮询管理 - 优先队列 API 前端对接（列表 + 人工优先入队 + 单项详情）

Why

根据 docs/产品迭代8月份/优先队列.md。后端测试环境（https://cmp-api.boss160.cn，Authorization: Bearer <token>）已提供「轮询管理 - 优先队列」能力：

• 查询优先轮询项列表：GET /api/admin/polling-priority-items
• 人工优先入队：POST /api/admin/polling-priority-items
• 查询优先轮询项详情：GET /api/admin/polling-priority-items/{id}

该能力服务于：

1. 查询优先轮询项：分页查询卡轮询优先项，按创建时间倒序，支持卡 card_id、任务类型 task_type、状态 status、触发类型 trigger_type 筛选；数据范围按卡所属店铺快照下推：代理只能看到自身及下级店铺资产，平台卡不可见。
2. 人工优先入队：为该卡的全部纳入轮询任务类型（实名/流量/套餐/卡状态）建立或合并优先轮询项，原因必填（最长 500 字符）。不受 既有人工触发的每日次数上限与 24 小时去重约束；不修改 调度优先级，也 不绕过 既有并发上限。
3. 查询优先轮询项详情：查询单条卡轮询优先项，越权与不存在返回同一响应，不产生可枚举差异，不提供 优先级分级、有效期与人工重触发入口。

What Changes

• 新增能力 polling-priority-queue，提供：
  • 优先轮询项列表：
    • 分页：GET /api/admin/polling-priority-items，按创建时间倒序；
    • 筛选：卡 card_id、任务类型 task_type、状态 status（pending/processing/completed/failed）、触发类型 trigger_type（含 manual_trigger 人工入队）；
    • 列表项字段：id/card_id/iccid/task_type(_name)/status(_name)/trigger_type(_name)/trigger_types/trigger_count/attempt_count/result(_name)/failure_reason/shop_id_snapshot/source_order_id/source_package_usage_id/manual_operator_id(_name)/manual_reason/claimed_at/last_triggered_at/created_at/updated_at；
  • 人工优先入队：POST /api/admin/polling-priority-items：
    • 请求 {card_id, reason}，reason 必填、最长 500 字符；
    • 语义：为该卡的全部纳入轮询任务类型（实名/流量/套餐/卡状态）建立或合并优先轮询项；
    • 约束：同一卡同一任务类型至多一条活动项，重复入队合并 trigger_count 与来源集合；
    • 边界：不受 既有人工触发的每日次数上限与 24 小时去重约束；
    • 边界：不修改 调度优先级，也 不绕过 既有并发上限；
    • 响应：{card_id, created_count, merged_count, task_types, task_type_names, items[{item_id, task_type(_name), status(_name), trigger_count, created, last_triggered_at}]
  • 优先轮询项详情：GET /api/admin/polling-priority-items/{id}：
    • 越权与不存在返回同一响应，不产生可枚举差异；
    • 不提供 优先级分级、有效期与人工重触发入口。
• 任务类型 task_type：polling:realname 实名检查 / polling:carddata 流量检查 / polling:package 套餐检查 / polling:card_status 卡状态检查。
• 状态 status：pending 待执行 / processing 执行中 / completed 已完成 / failed 失败出队。
• 触发类型 trigger_type：purchase_activated 主套餐购买后立即生效 / renewal_activated 续购套餐生效 / queue_activated 排队主套餐顺延生效 / addon_activated 加油包生效 / no_valid_package 资产无有效套餐 / manual_trigger 人工入队。
• 执行结果 result：success 成功 / failed 失败 / 空值表示未出结果。
• 错误响应：400 请求参数错误 / 401 未认证或认证已过期 / 403 无权访问 / 500 服务器内部错误。

Impact

• Affected specs:
  • polling-priority-queue — 新增能力
• Affected code:
  • src/api/modules/pollingPriorityQueue.ts（新增）
  • src/api/modules/index.ts
  • src/types/api/pollingPriorityQueue.ts（新增）
  • src/types/api/index.ts
  • src/config/constants/augustIteration.ts
  • src/views/polling-management/priority-queue/index.vue（新增）
  • src/router/routesAlias.ts
  • src/router/routes/asyncRoutes.ts
  • src/locales/langs/zh.json
  • src/locales/langs/en.json