break
5ed6b39deb
Some checks failed
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Has been cancelled
- 新增六对成对迁移 000232–000237：H5 弹窗类型、退款结算标识与申请人备注、优先轮询事实字段与两个新终态、通道阈值命中留痕、手机号最近解绑人、提现资格校验留痕 - 退款：原因必填与申请人备注、来源支付与渠道流水冻结、线下处理流水号补录审计、按订单查询可选退款方式、企微审批材料补齐且新增字段缺失映射即明确失败 - 优先轮询：人工关闭、有效期到期独立周期任务、失败与过期人工重触发、事实字段与异常重试查询、资产解析端点只读投影 - 通道阈值：命中事实同事务留痕与命中记录查询；员工账单：列表筛选与详情投影；商户池：列表投影与统计周期语义；H5：弹窗类型与类别排序 - 手机号：有效关联数量与最近解绑人、短信验证码失败次数限制；导出：佣金明细十五列与报表序号列 - 时间筛选：三处新增筛选纳入统一严格解析契约，员工账单产生时间参数改名 - 同步 12 份主 Spec 需求、两端点与异步任务证据链，门禁 context-health 与 OpenSpec 校验通过
148 lines
9.8 KiB
Markdown
148 lines
9.8 KiB
Markdown
# 轮询运营当前行为
|
||
|
||
## Purpose
|
||
|
||
描述轮询配置、人工触发、并发控制、监控、告警与数据清理的当前可观察行为。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 异步任务可观察
|
||
|
||
系统 SHALL 允许授权运营者查询轮询和清理任务的状态，并对重复手工触发执行当前防重规则。
|
||
|
||
#### Scenario: 异步任务可观察
|
||
|
||
- **GIVEN** 同类任务正在运行
|
||
- **WHEN** 再次手工触发
|
||
- **THEN** 系统拒绝、复用或排队，而不静默并发执行同一任务
|
||
|
||
### Requirement: 手工轮询任务状态
|
||
|
||
系统 SHALL 将手工轮询任务保持为待处理、处理中、已完成或已取消，并对相同运行中任务执行当前防重与并发限制；取消会立即写入已取消，但当前批量执行结束会无条件写入已完成，因此取消与后台处理竞态时已取消状态可能被覆盖，此缺陷在基线中保留。
|
||
|
||
#### Scenario: 取消运行中轮询任务
|
||
|
||
- **GIVEN** 手工轮询任务仍处于待处理或处理中
|
||
- **WHEN** 授权操作者取消任务
|
||
- **THEN** 系统先记录已取消；若后台批量处理随后结束，当前实现可能把同一任务覆盖为已完成
|
||
|
||
### Requirement: 轮询并发计数可观测
|
||
|
||
系统 SHALL 在轮询并发配置列表和详情中返回与实际限流器相同任务类型的当前计数、可用并发和使用率；重置操作 MUST 重置该同一计数。当前计数、可用并发与使用率 MUST 不因释放过期或已重置的计数而呈现负值。
|
||
|
||
#### Scenario: 查询运行中的任务计数
|
||
- **WHEN** 某轮询任务正在占用并发配额
|
||
- **THEN** 查询该任务类型的并发状态返回非零当前计数，并据此计算可用并发和使用率
|
||
|
||
#### Scenario: 重置任务计数
|
||
- **WHEN** 授权操作者重置某轮询任务类型的并发计数
|
||
- **THEN** 后续状态查询返回该任务类型的当前计数为零，且不影响其他任务类型的计数
|
||
|
||
#### Scenario: 重置后的任务完成
|
||
- **WHEN** 某任务在其并发计数已重置或过期后完成
|
||
- **THEN** 该任务类型的当前计数保持为零而不变为负数
|
||
|
||
### Requirement: 轮询并发配置覆盖实际任务
|
||
|
||
系统 SHALL 为 `realname`、`carddata`、`package`、`protect` 与 `card_status` 五类实际轮询任务各维护一项可查询、可更新的并发配置；`stop_start` 不得作为轮询并发配置返回或接受维护。新增的 `protect` 与 `card_status` 初始最大并发数 MUST 为 300。
|
||
|
||
#### Scenario: 查询完整配置集合
|
||
- **WHEN** 授权操作者查询轮询并发配置列表
|
||
- **THEN** 返回上述五类任务且不含 `stop_start`
|
||
|
||
#### Scenario: 维护高于一千的既有并发配置
|
||
- **WHEN** 授权操作者为已配置轮询任务提交大于 1000 的正整数最大并发数
|
||
- **THEN** 系统保存该值并使后续轮询限流读取该值
|
||
|
||
### Requirement: 轮询任务类型名称可读
|
||
|
||
系统 SHALL 在轮询并发状态中返回与任务类型一致的中文名称：实名检查、流量检查、套餐检查、保护期检查或卡状态检查。
|
||
|
||
#### Scenario: 查询卡状态并发配置
|
||
- **WHEN** 授权操作者查询 `card_status` 的并发状态
|
||
- **THEN** 返回的 `task_type_name` 为“卡状态检查”
|
||
|
||
### Requirement: 停复机遵循实际生效实名策略
|
||
|
||
系统 SHALL 在自动停机、自动复机、设备批量复机和手动停复机的实名门槛中放行行业卡、已实名卡及实际生效策略为 `none` 的卡。独立卡或无有效设备绑定的卡使用卡策略，有有效设备绑定的非独立卡使用设备策略。系统 MUST 保留真实实名状态，不得以豁免伪造已实名事实。其他策略的未实名普通卡 MUST 保持实名限制；套餐、流量、风险、保护期及非轮询停机不自动复机等既有限制保持不变。
|
||
|
||
#### Scenario: 免实名独立卡有生效套餐
|
||
- **WHEN** 未实名普通独立卡配置 `none`，存在生效套餐且流量未耗尽，当前网络在线
|
||
- **THEN** 系统不因未实名向上游请求停机
|
||
|
||
#### Scenario: 免实名卡从轮询停机恢复
|
||
- **WHEN** 上述卡当前因 `not_realname` 停机，满足其他自动复机条件
|
||
- **THEN** 系统不因未实名阻止自动复机
|
||
|
||
#### Scenario: 设备策略优先
|
||
- **WHEN** 未实名普通卡有效绑定设备，卡与设备的实名策略不同
|
||
- **THEN** 系统以设备策略判定实名豁免，卡自身的 `none` 不得覆盖设备的实名要求
|
||
|
||
#### Scenario: 行业卡与已实名卡兼容
|
||
- **WHEN** 行业卡未实名或普通卡已实名
|
||
- **THEN** 系统保留已有实名门槛放行行为
|
||
|
||
#### Scenario: 无套餐和流量耗尽不豁免
|
||
- **WHEN** 免实名卡没有生效套餐或流量已经耗尽
|
||
- **THEN** 系统仍按对应业务原因执行停机判断
|
||
|
||
#### Scenario: 策略读取失败
|
||
- **WHEN** 未实名普通卡的有效设备绑定或设备策略查询失败
|
||
- **THEN** 系统报告错误且不对该卡发起本次停复机命令，不按卡策略回退放行
|
||
|
||
### Requirement: 优先轮询项与普通轮询的单次执行互斥
|
||
|
||
系统 SHALL 在同一卡同一轮询任务类型存在优先轮询项时，只允许一个执行轮次对该卡该任务类型发起上游调用：待执行优先项由本轮执行认领并作为优先执行完成该轮轮询，MUST NOT 另外产生第二次调用；执行中且认领租约未到期的优先项使本轮执行跳过该轮次并延后，MUST NOT 发起上游调用。不存在活动优先项时，普通轮询的入队、出队、移除与延后行为 MUST 与当前行为一致。优先项存在 MUST NOT 使该卡被移出普通轮询，MUST NOT 改变其它轮询任务类型的执行。
|
||
|
||
#### Scenario: 待执行优先项遇到本轮执行
|
||
|
||
- **WHEN** 该卡该轮询任务类型存在待执行优先项，且该任务类型的执行轮次到达
|
||
- **THEN** 系统认领该项并完成本轮轮询，不产生额外的第二次上游调用
|
||
|
||
#### Scenario: 已领取优先项遇到本轮的另一次执行
|
||
|
||
- **WHEN** 该卡该轮询任务类型存在执行中且认领租约未到期的优先项，该任务类型又到达一次执行
|
||
- **THEN** 系统跳过该轮次并按既有间隔延后，不发起上游调用
|
||
|
||
#### Scenario: 不存在活动优先项
|
||
|
||
- **WHEN** 该卡该轮询任务类型不存在活动优先项
|
||
- **THEN** 轮询执行的排队、入队、出队与移除行为与当前行为一致
|
||
|
||
#### Scenario: 优先项结束后的普通轮询
|
||
|
||
- **WHEN** 该卡该轮询任务类型的优先项已完成或失败出队
|
||
- **THEN** 该卡继续按普通轮询间隔执行，仍存在于普通轮询中
|
||
|
||
## 可达操作索引
|
||
|
||
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
|
||
|
||
### 轮询配置管理
|
||
|
||
`GET /api/admin/polling-configs`（获取轮询配置列表）；`POST /api/admin/polling-configs`（创建轮询配置）；`DELETE /api/admin/polling-configs/{id}`（删除轮询配置）；`GET /api/admin/polling-configs/{id}`（获取轮询配置详情）；`PUT /api/admin/polling-configs/{id}`（更新轮询配置）；`PUT /api/admin/polling-configs/{id}/status`（更新轮询配置状态）；`GET /api/admin/polling-configs/enabled`（获取所有启用的配置）。
|
||
|
||
### 轮询管理-告警
|
||
|
||
`GET /api/admin/polling-alert-history/polling-alert-history`（获取轮询告警历史）；`GET /api/admin/polling-alert-rules`（获取轮询告警规则列表）；`POST /api/admin/polling-alert-rules`（创建轮询告警规则）；`DELETE /api/admin/polling-alert-rules/{id}`（删除轮询告警规则）；`GET /api/admin/polling-alert-rules/{id}`（获取轮询告警规则详情）；`PUT /api/admin/polling-alert-rules/{id}`（更新轮询告警规则）。
|
||
|
||
### 轮询管理-并发控制
|
||
|
||
`GET /api/admin/polling-concurrency`（获取轮询并发配置列表）；`GET /api/admin/polling-concurrency/{task_type}`（获取指定任务类型的并发配置）；`PUT /api/admin/polling-concurrency/{task_type}`（更新轮询并发配置）；`POST /api/admin/polling-concurrency/reset`（重置轮询并发计数）。
|
||
|
||
### 轮询管理-手动触发
|
||
|
||
`POST /api/admin/polling-manual-trigger/batch`（批量手动触发）；`POST /api/admin/polling-manual-trigger/by-condition`（条件筛选触发）；`POST /api/admin/polling-manual-trigger/cancel`（取消手动触发任务）；`GET /api/admin/polling-manual-trigger/history`（获取手动触发历史）；`POST /api/admin/polling-manual-trigger/single`（单卡手动触发）；`GET /api/admin/polling-manual-trigger/status`（获取手动触发状态）。
|
||
|
||
### 轮询管理-数据清理
|
||
|
||
`GET /api/admin/data-cleanup-configs`（获取数据清理配置列表）；`POST /api/admin/data-cleanup-configs`（创建数据清理配置）；`DELETE /api/admin/data-cleanup-configs/{id}`（删除数据清理配置）；`GET /api/admin/data-cleanup-configs/{id}`（获取数据清理配置详情）；`PUT /api/admin/data-cleanup-configs/{id}`（更新数据清理配置）；`GET /api/admin/data-cleanup-logs`（获取数据清理日志列表）；`GET /api/admin/data-cleanup/preview`（预览待清理数据）；`GET /api/admin/data-cleanup/progress`（获取数据清理进度）；`POST /api/admin/data-cleanup/trigger`（手动触发数据清理）。
|
||
|
||
### 轮询管理-监控
|
||
|
||
`GET /api/admin/polling-stats`（获取轮询总览统计）；`GET /api/admin/polling-stats/init-progress`（获取轮询初始化进度）；`GET /api/admin/polling-stats/queues`（获取轮询队列状态）；`GET /api/admin/polling-stats/tasks`（获取轮询任务统计）。
|
||
|
||
### 轮询管理-优先队列
|
||
|
||
`POST /api/admin/polling-priority-items`（人工优先入队）；`GET /api/admin/polling-priority-items`（查询优先轮询项列表）；`GET /api/admin/polling-priority-items/{id}`（查询优先轮询项详情）；`POST /api/admin/polling-priority-items/{id}/close`（人工关闭优先轮询项）；`POST /api/admin/polling-priority-items/{id}/retrigger`（人工重触发优先轮询项）。
|