diff --git a/internal/routes/asset.go b/internal/routes/asset.go index 25db9c6a..5afa3ef9 100644 --- a/internal/routes/asset.go +++ b/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), diff --git a/internal/routes/carrier_scheduler.go b/internal/routes/carrier_scheduler.go index 264647b8..88cc2e95 100644 --- a/internal/routes/carrier_scheduler.go +++ b/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, }) } diff --git a/internal/routes/export_task.go b/internal/routes/export_task.go index 9b5325cb..5178055f 100644 --- a/internal/routes/export_task.go +++ b/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{