docs: 补充轮询开关、停机被拒视图、单卡轮询状态、监控与导出场景的接口说明

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/routes/asset.go

@@ -139,7 +139,7 @@ func registerAssetRoutes(router fiber.Router, handler *admin.AssetHandler, walle
 
 	Register(assets, doc, groupPath, "PATCH", "/:identifier/polling-status", handler.UpdatePollingStatus, RouteSpec{
 		Summary:     "更新资产轮询状态",
-		Description: "启用或禁用指定资产（IoT卡或设备）的定期状态轮询。",
+		Description: "启用或禁用指定资产（IoT卡或设备）的定期状态轮询；同事务写不轮询清单（来源单资产接口）与审计。网关扩展状态为风险停机或已销户的卡不能开启轮询，返回 403。设备开关级联到设备下各卡（开启时跳过风险停机、已销户的卡）。影响说明见 GET /polling-status/impact。",
 		Tags:        []string{"资产管理"},
 		Input:       new(dto.UpdateAssetPollingStatusRequest),
 		Output:      new(dto.UpdateAssetPollingStatusResponse),

internal/routes/carrier_scheduler.go

@@ -44,7 +44,10 @@ func registerCarrierSchedulerRoutes(router fiber.Router, handler *admin.CarrierS
 	alerts := router.Group("/polling-failure-alerts")
 	alertsPath := basePath + "/polling-failure-alerts"
 	Register(alerts, doc, alertsPath, "GET", "", handler.ListAlerts, RouteSpec{
-		Summary: "查询卡轮询失败告警列表", Tags: tags, Input: new(dto.PollingFailureAlertListRequest), Output: new(dto.PollingFailureAlertPageResult), Auth: true,
+		Summary: "查询卡轮询失败告警列表",
+		Description: "view=stop_refused 为停机被拒视图：停复机方向为停机，且错误类型为终态或业务错误、或停机失败次数达到停复机告警阈值；该视图只按 carrier_id、status、iccid、start_time、end_time 筛选（忽略 check_type、error_category、alert_level），" +
+			"并额外返回 device_id、network_status、stop_reason、enable_polling、has_package、handled_by_name。导出使用统一导出任务，场景 polling_stop_refused_alert。",
+		Tags: tags, Input: new(dto.PollingFailureAlertListRequest), Output: new(dto.PollingFailureAlertPageResult), Auth: true,
 	})
 	Register(alerts, doc, alertsPath, "GET", "/summary", handler.AlertSummary, RouteSpec{
 		Summary: "未处理卡轮询失败告警按运营商账户与错误类别汇总", Tags: tags, Input: nil, Output: new([]dto.PollingFailureAlertSummaryItem), Auth: true,
@@ -58,11 +61,11 @@ func registerCarrierSchedulerRoutes(router fiber.Router, handler *admin.CarrierS
 	})
 
 	Register(router, doc, basePath, "GET", "/iot-cards/:id/polling-state", handler.CardState, RouteSpec{
-		Summary: "查询单卡轮询状态", Description: "各检查类型下次到期、最近成功、连续失败与最近错误、是否执行中；只读。", Tags: tags,
+		Summary: "查询单卡轮询状态", Description: "各检查类型下次到期、最近成功、连续失败与最近错误、是否执行中；停复机出口开关、当前停复机指令（动作、原因、场景、版本、失败次数、待确认、下次可执行时间）与最近一次停复机调用时间；只读。", Tags: tags,
 		Input: new(dto.CardPollingStatePath), Output: new(dto.CardPollingStateResponse), Auth: true,
 	})
 	Register(router, doc, basePath, "GET", "/polling-stats/carrier-queues", handler.CarrierStats, RouteSpec{
-		Summary: "按运营商账户的轮询队列与执行监控", Description: "按运营商账户调度的各账户队列长度、已到期数、执行中、上一分钟 QPS、限流等待与拒绝、处理中标记到期、未处理告警。", Tags: tags,
+		Summary: "按运营商账户的轮询队列与执行监控", Description: "按运营商账户调度的各账户队列长度、已到期数、执行中、上一分钟 QPS、限流等待与拒绝、处理中标记到期、未处理告警；停复机指令队列长度、已到期、执行中、待确认，近 1 小时停复机成功、失败、重试、结果未知数。", Tags: tags,
 		Input: nil, Output: new(dto.CarrierPollingStatsResponse), Auth: true,
 	})
 }

internal/routes/export_task.go

@@ -13,12 +13,14 @@ func registerExportTaskRoutes(router fiber.Router, handler *admin.ExportTaskHand
 	groupPath := basePath + "/export-tasks"
 
 	Register(exportTasks, doc, groupPath, "POST", "", handler.Create, RouteSpec{
-		Summary:     "创建导出任务",
-		Description: "创建统一导出任务，支持场景 scene=device/iot_card/order/package/agent_wallet_transaction/agent_recharge/refund/exchange/commission_record/package_traffic_alert/expiring_asset 和格式 format=xlsx/csv。受影响场景的时间筛选固定为 query.filters.start_time 与 query.filters.end_time，取值必须为带显式时区的 RFC3339 秒级时间，创建时规范化为 UTC 秒级字符串后冻结。",
-		Tags:        []string{"导出任务"},
-		Input:       new(dto.CreateExportTaskRequest),
-		Output:      new(dto.CreateExportTaskResponse),
-		Auth:        true,
+		Summary: "创建导出任务",
+		Description: "创建统一导出任务，支持场景 scene=device/iot_card/order/package/agent_wallet_transaction/agent_recharge/refund/exchange/commission_record/package_traffic_alert/expiring_asset/operations_activation/operations_renewal/stop_resume_rule_dry_run/polling_pause/polling_stop_refused_alert 和格式 format=xlsx/csv。" +
+			"polling_pause 的 query.filters 同 GET /card-polling-pauses（asset_type、carrier_id、source、status、identifier、operator_id、start_time、end_time）；polling_stop_refused_alert 的 query.filters 为 carrier_id、status、iccid、start_time、end_time；两者仅超级管理员与平台账号可导出。device、iot_card 场景支持 enable_polling 筛选，导出最后一列为「是否轮询」。" +
+			"受影响场景的时间筛选固定为 query.filters.start_time 与 query.filters.end_time，取值必须为带显式时区的 RFC3339 秒级时间，创建时规范化为 UTC 秒级字符串后冻结。",
+		Tags:   []string{"导出任务"},
+		Input:  new(dto.CreateExportTaskRequest),
+		Output: new(dto.CreateExportTaskResponse),
+		Auth:   true,
 	})
 
 	Register(exportTasks, doc, groupPath, "GET", "", handler.List, RouteSpec{