junhong_cmp_fiber/openspec/specs/polling-operations/spec.md

轮询运营当前行为

Purpose

描述轮询配置、人工触发、并发控制、监控、告警与数据清理的当前可观察行为。

Requirements

Requirement: 异步任务可观察

系统 SHALL 允许授权运营者查询轮询和清理任务的状态，并对重复手工触发执行当前防重规则。

Scenario: 异步任务可观察

• GIVEN 同类任务正在运行
• WHEN 再次手工触发
• THEN 系统拒绝、复用或排队，而不静默并发执行同一任务

Requirement: 手工轮询任务状态

系统 SHALL 将手工轮询任务保持为待处理、处理中、已完成或已取消，并对相同运行中任务执行当前防重与并发限制；取消会立即写入已取消，但当前批量执行结束会无条件写入已完成，因此取消与后台处理竞态时已取消状态可能被覆盖，此缺陷在基线中保留。

Scenario: 取消运行中轮询任务

• GIVEN 手工轮询任务仍处于待处理或处理中
• WHEN 授权操作者取消任务
• THEN 系统先记录已取消；若后台批量处理随后结束，当前实现可能把同一任务覆盖为已完成

Requirement: 轮询并发计数可观测

系统 SHALL 在轮询并发配置列表和详情中返回与实际限流器相同任务类型的当前计数、可用并发和使用率；重置操作 MUST 重置该同一计数。

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（获取轮询任务统计）。