归档

openspec/specs/polling-status-constants/spec.md

@@ -0,0 +1,44 @@
+# 轮询触发日志状态常量规范
+
+## ADDED Requirements
+
+### Requirement: 轮询手动触发日志状态常量
+
+系统应在 `pkg/constants/polling.go` 中定义轮询手动触发日志的四种状态常量，避免硬编码字符串。
+
+**常量定义**：
+- `PollingManualTriggerStatusPending = "pending"`
+- `PollingManualTriggerStatusProcessing = "processing"`
+- `PollingManualTriggerStatusCompleted = "completed"`
+- `PollingManualTriggerStatusCancelled = "cancelled"`
+
+#### Scenario: 轮询触发日志记录使用常量
+
+- **WHEN** 系统记录轮询手动触发日志（插入、更新状态）
+- **THEN** 系统使用 `constants.PollingManualTriggerStatusPending` 等常量，而不是直接写字符串 `"pending"`
+
+#### Scenario: 轮询触发日志查询使用常量
+
+- **WHEN** 系统查询轮询日志（按状态筛选、状态转移判断等）
+- **THEN** 系统使用常量进行比较，而不是硬编码 `status == "pending"`
+
+#### Scenario: 常量修改时自动重构
+
+- **WHEN** 业务要求修改某个状态值（如 `"pending"` → `"awaiting"`）
+- **THEN** 开发者修改 `pkg/constants/polling.go` 中的常量定义
+- **THEN** IDE 自动检测所有使用该常量的代码，支持一键重构替换
+- **THEN** 无需手动搜索和替换散落在各文件中的硬编码字符串
+
+### Requirement: 轮询触发日志字段描述
+
+轮询手动触发日志模型（`tb_polling_manual_trigger_log`）应包含 `status` 字段，并在 DTO 中加入 `status_name` 文字字段。
+
+#### Scenario: 查询轮询触发日志返回状态文本
+
+- **WHEN** API 返回轮询手动触发日志列表（`GET /api/admin/polling/manual-triggers`）
+- **THEN** 响应中的 `status` 字段（int）对应状态常量值
+- **THEN** 响应中的 `status_name` 字段（string）显示该状态的中文描述
+  - `"pending"` → `"待处理"`
+  - `"processing"` → `"处理中"`
+  - `"completed"` → `"已完成"`
+  - `"cancelled"` → `"已取消"`