归档: add-polling-card-status-with-verbose-log，同步主规范

change 目录归档至 openspec/changes/archive/2026-04-15-add-polling-card-status-with-verbose-log/
新建主规范 openspec/specs/polling-card-status-task/spec.md（6个需求）
追加 verbose log 需求至 openspec/specs/polling-task-handlers/spec.md（4个新需求）
protect handler 规范更新字段名：network_status → network_status_at_check + action_taken

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

openspec/specs/polling-task-handlers/spec.md

@@ -265,3 +265,85 @@ func NewPollingProtectHandler(
 - **GIVEN** 卡 `is_standalone=true`（未绑定设备）
 - **WHEN** `HandleProtectConsistencyCheck` 执行
 - **THEN** 检测到独立卡，直接 requeue（设备保护期与独立卡无关）
+
+---
+
+### Requirement: PollingBase 支持 verboseLog 标志
+`PollingBase` 结构体 SHALL 新增 `verboseLog bool` 字段，`NewPollingBase` 函数 SHALL 接受 `verboseLog bool` 参数并赋值。`cmd/worker/main.go` SHALL 从 `cfg.Polling.VerboseLog` 读取并传入。
+
+#### Scenario: verboseLog 为 true 时详细日志启用
+- **WHEN** `cfg.Polling.VerboseLog = true` 且 Worker 启动
+- **THEN** `PollingBase.verboseLog = true`，所有 handler 在成功查询上游时输出 Info 日志
+
+#### Scenario: verboseLog 为 false 时详细日志不输出
+- **WHEN** `cfg.Polling.VerboseLog = false`（默认）
+- **THEN** 成功查询上游时不输出额外日志，行为与修改前相同
+
+---
+
+### Requirement: 配置文件包含 polling.verbose_log 字段
+`pkg/config/config.go` SHALL 新增 `PollingConfig struct` 含 `VerboseLog bool`，并加入 `Config` 结构体。`pkg/config/defaults/config.yaml` SHALL 包含 `polling.verbose_log: false`。
+
+#### Scenario: 默认配置 verbose_log 为 false
+- **WHEN** 未设置 `JUNHONG_POLLING_VERBOSE_LOG` 环境变量
+- **THEN** `cfg.Polling.VerboseLog = false`
+
+#### Scenario: 环境变量覆盖开启 verbose_log
+- **WHEN** 设置 `JUNHONG_POLLING_VERBOSE_LOG=true`
+- **THEN** `cfg.Polling.VerboseLog = true`
+
+---
+
+### Requirement: realname handler 成功查询后输出 verbose 日志
+`PollingRealnameHandler.Handle` SHALL 在 `gateway.QueryRealnameStatus` 成功返回后，当 `h.base.verboseLog` 为 true 时，以 `Info` 级别记录日志，包含：`card_id`、`iccid`、`real_status`（bool）、`new_status`（int）、`changed`（bool）。
+
+#### Scenario: verboseLog 开启时实名查询成功输出日志
+- **WHEN** `verboseLog = true` 且 `QueryRealnameStatus` 成功返回
+- **THEN** 输出包含 iccid + real_status + new_status + changed 的 Info 日志
+
+#### Scenario: verboseLog 关闭时实名查询成功不输出额外日志
+- **WHEN** `verboseLog = false` 且 `QueryRealnameStatus` 成功返回（状态未变）
+- **THEN** 不输出 verbose 日志
+
+---
+
+### Requirement: carddata handler 成功查询后输出 verbose 日志
+`PollingCarddataHandler.Handle` SHALL 在 `gateway.QueryFlow` 成功返回后，当 `h.base.verboseLog` 为 true 时，以 `Info` 级别记录日志，包含：`card_id`、`iccid`、`gateway_flow_mb`（float64）、`increment_mb`（float64）、`is_cross_month`（bool）。
+
+#### Scenario: verboseLog 开启时流量查询成功输出日志
+- **WHEN** `verboseLog = true` 且 `QueryFlow` 成功返回
+- **THEN** 输出包含 iccid + gateway_flow_mb + increment_mb + is_cross_month 的 Info 日志
+
+#### Scenario: verboseLog 关闭时流量查询成功不输出额外日志
+- **WHEN** `verboseLog = false` 且 `QueryFlow` 成功返回（流量无增量）
+- **THEN** 不输出 verbose 日志
+
+---
+
+### Requirement: package handler 成功加载卡信息后输出 verbose 日志
+`PollingPackageHandler.Handle` SHALL 在 `GetByID` 成功返回 `freshCard` 后、调用 `EvaluateAndAct` 之前，当 `h.base.verboseLog` 为 true 时，以 `Info` 级别记录日志，包含：`card_id`、`iccid`、`network_status`（int）、`stop_reason`（string）。
+
+> 注：package handler 不查询 Gateway，verbose log 记录的是本次评估时读取到的本地卡状态，便于排查"停复机评估为何结果不符预期"类问题。
+
+#### Scenario: verboseLog 开启时套餐检查加载卡成功输出日志
+- **WHEN** `verboseLog = true` 且 `iotCardStore.GetByID` 成功返回 `freshCard`
+- **THEN** 输出包含 iccid + network_status + stop_reason 的 Info 日志
+
+#### Scenario: verboseLog 关闭时套餐检查不输出额外日志
+- **WHEN** `verboseLog = false`
+- **THEN** 不输出 verbose 日志（现有 "套餐检查：执行停复机评估" Info 日志保持不变）
+
+---
+
+### Requirement: protect handler 成功执行保护期检查后输出 verbose 日志
+`PollingProtectHandler.Handle` SHALL 在 switch 块执行完毕、调用 `UpdateFields(last_protect_check_at)` 之前，当 `h.base.verboseLog` 为 true 时，以 `Info` 级别记录日志，包含：`card_id`、`iccid`、`stop_protect`（bool）、`start_protect`（bool）、`network_status_at_check`（int）、`action_taken`（string）。
+
+> 注：该日志在 switch 的所有分支（强制停机、强制复机、EvaluateAndAct、无操作）均成功执行后输出；若某分支因 Gateway 失败提前 return，则不输出（已有 Error 日志覆盖）。`network_status_at_check` 反映检查时的卡状态（触发动作的原因），`action_taken` 反映实际执行了什么（forced_stop / forced_resume / evaluate / no_action）。
+
+#### Scenario: verboseLog 开启时保护期检查成功输出日志
+- **WHEN** `verboseLog = true` 且 switch 块各分支均执行成功（未提前 return）
+- **THEN** 输出包含 iccid + stop_protect + start_protect + network_status_at_check + action_taken 的 Info 日志
+
+#### Scenario: verboseLog 关闭时保护期检查不输出额外日志
+- **WHEN** `verboseLog = false`
+- **THEN** 不输出 verbose 日志