120 lines
7.8 KiB
Markdown
120 lines
7.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；业务义务以上述 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`（获取轮询任务统计）。
|