# 轮询运营当前行为

## 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；业务义务以上述 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`（获取轮询任务统计）。