53 lines
4.3 KiB
Markdown
53 lines
4.3 KiB
Markdown
# 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` |