Files
junhong_cmp_fiber/internal/model/dto/carrier_polling_dto.go
邹进 934a3a27a1
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled
feat: 停复机指令队列与设备维度判断
自动停复机统一经停复机指令队列执行(全局开关 polling.stop_resume.queue_enabled,默认关闭):
- 统一判断函数 decideCard,新旧路径共用;暂停轮询的卡在套餐到期、退款场景照常停机
- 同卡一条指令、版本号覆盖;领取校验单卡最小重试间隔;先于卡任务领取,不受 scheduler_mode 限制
- 执行器只调用一次网关,按错误分类退避与告警,结果未知在队列内确认
- 设备维度判断合并请求与场景,版本变化再判断,旧路径持设备锁时推后
- 套餐激活、重置、订单、流量扣减、套餐到期、退款、实名管控修改改为请求评估
- 监控增加停复机队列与近 1 小时执行计数,单卡轮询状态返回当前指令
- 迁移 000255 插入开关与告警、退避参数

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 00:36:26 +09:00

214 lines
17 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package dto
import "time"
// CarrierPollingParamItem 运营商账户调度参数(含全局默认合并后的生效值)。
type CarrierPollingParamItem struct {
CarrierID uint `json:"carrier_id" description:"运营商账户ID"`
CarrierName string `json:"carrier_name" description:"运营商账户名称"`
IsDefault bool `json:"is_default" description:"是否未单独配置、全部使用全局默认"`
InflightLimit int `json:"inflight_limit" description:"生效的执行上限(跨 Worker 实例同时执行卡任务数)"`
CardMaxInFlight int `json:"card_max_in_flight" description:"生效的每进程卡任务 max_in_flight"`
PriorityMaxRatio *float64 `json:"priority_max_ratio" description:"优先队列每轮最大占比(0~1),空表示不限"`
StopResumeMaxInFlight *int `json:"stop_resume_max_in_flight" description:"每进程停复机 max_in_flight(停复机指令队列使用),空表示默认"`
SRInflightLimit *int `json:"sr_inflight_limit" description:"停复机执行上限(停复机指令队列使用),空表示默认"`
StopResumeMinInterval *int `json:"stop_resume_min_interval" description:"单卡两次停复机调用最小间隔(秒),空表示默认"`
StopResumeConfirmDelay *int `json:"stop_resume_confirm_delay" description:"停复机结果未知后确认延迟(秒),空表示默认"`
ConfiguredInflight *int `json:"configured_inflight_limit" description:"单独配置的执行上限,空表示使用默认"`
ConfiguredMaxInFlight *int `json:"configured_card_max_in_flight" description:"单独配置的每进程 max_in_flight,空表示使用默认"`
ConsumeCapacity int `json:"consume_capacity" description:"当前订阅进程 max_in_flight 之和(执行上限不应超过该值)"`
}
// CarrierPollingParamListResponse 运营商账户调度参数列表。
type CarrierPollingParamListResponse struct {
Items []CarrierPollingParamItem `json:"items" description:"各运营商账户调度参数"`
SubscriberProcesses int `json:"subscriber_processes" description:"订阅卡任务的 Worker 进程数"`
DefaultInflight int `json:"default_inflight_limit" description:"全局默认执行上限"`
DefaultMaxInFlight int `json:"default_card_max_in_flight" description:"全局默认每进程 max_in_flight"`
}
// CarrierPollingParamPath 运营商账户路径参数。
type CarrierPollingParamPath struct {
CarrierID uint `json:"-" path:"carrier_id" required:"true" description:"运营商账户ID"`
}
// SaveCarrierPollingParamRequest 保存运营商账户调度参数;字段为空表示该项使用全局默认。
type SaveCarrierPollingParamRequest struct {
CarrierID uint `json:"-" path:"carrier_id" required:"true" description:"运营商账户ID"`
InflightLimit *int `json:"inflight_limit" validate:"omitempty,min=1,max=10000" minimum:"1" maximum:"10000" description:"执行上限,空表示默认"`
CardMaxInFlight *int `json:"card_max_in_flight" validate:"omitempty,min=1,max=2000" minimum:"1" maximum:"2000" description:"每进程卡任务 max_in_flight,空表示默认"`
StopResumeMaxInFlight *int `json:"stop_resume_max_in_flight" validate:"omitempty,min=1,max=1000" minimum:"1" maximum:"1000" description:"每进程停复机 max_in_flight,空表示默认"`
SRInflightLimit *int `json:"sr_inflight_limit" validate:"omitempty,min=1,max=10000" minimum:"1" maximum:"10000" description:"停复机执行上限,空表示默认"`
PriorityMaxRatio *float64 `json:"priority_max_ratio" validate:"omitempty,gt=0,lte=1" description:"优先队列每轮最大占比(0~1],空表示不限"`
StopResumeMinInterval *int `json:"stop_resume_min_interval" validate:"omitempty,min=1,max=86400" minimum:"1" maximum:"86400" description:"单卡停复机最小间隔(秒),空表示默认"`
StopResumeConfirmDelay *int `json:"stop_resume_confirm_delay" validate:"omitempty,min=1,max=86400" minimum:"1" maximum:"86400" description:"停复机结果未知确认延迟(秒),空表示默认"`
}
// PollingCheckSceneItem 请求检查场景。
type PollingCheckSceneItem struct {
Scene string `json:"scene" description:"场景编码 (order_paid:订单支付, package_activated:套餐激活, stop_resume_succeeded:停复机成功, device_operation:设备操作, auto_renewal_purchase:自动续费购包, client_asset_detail:C 端资产详情, admin_asset_realtime:后台资产实时状态, realname_link:实名链接)"`
SceneName string `json:"scene_name" description:"场景名称"`
CheckTypes []string `json:"check_types" description:"检查类型 (card_status:卡状态, carddata:流量, realname:实名)"`
ConfirmDelays []int `json:"confirm_delays" description:"延迟确认序列(秒),空表示只立即检查一次"`
Cooldown *int `json:"cooldown" description:"冷却时长(秒),最近一次成功检查未超过该时长则不请求;空表示不冷却"`
UpdatedAt time.Time `json:"updated_at" description:"更新时间"`
}
// UpdatePollingCheckSceneRequest 修改请求检查场景(场景由代码预置,只可改检查类型、确认延迟与冷却)。
type UpdatePollingCheckSceneRequest struct {
Scene string `json:"-" path:"scene" required:"true" description:"场景编码"`
CheckTypes []string `json:"check_types" validate:"required,min=1,max=3,dive,oneof=card_status carddata realname" required:"true" description:"检查类型 (card_status:卡状态, carddata:流量, realname:实名)"`
ConfirmDelays []int `json:"confirm_delays" validate:"omitempty,max=5,dive,min=1,max=86400" description:"延迟确认序列(秒,递增),空表示只立即检查一次"`
Cooldown *int `json:"cooldown" validate:"omitempty,min=1,max=86400" minimum:"1" maximum:"86400" description:"冷却时长(秒),空表示不冷却"`
}
// PollingFailureAlertListRequest 卡轮询失败告警列表请求。
type PollingFailureAlertListRequest struct {
Page int `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码"`
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
CarrierID *uint `json:"carrier_id" query:"carrier_id" validate:"omitempty,min=1" description:"运营商账户ID"`
CheckType string `json:"check_type" query:"check_type" validate:"omitempty,oneof=card_status carddata realname package all" description:"检查类型 (card_status:卡状态, carddata:流量, realname:实名, package:套餐, all:账户级)"`
ErrorCategory string `json:"error_category" query:"error_category" validate:"omitempty,max=50" description:"错误类别"`
Status *int `json:"status" query:"status" validate:"omitempty,oneof=1 2 3 4" description:"状态 (1:未处理, 2:已恢复, 3:已关闭轮询, 4:已处理)"`
AlertLevel string `json:"alert_level" query:"alert_level" validate:"omitempty,oneof=card carrier" description:"告警级别 (card:卡级, carrier:账户级)"`
ICCID string `json:"iccid" query:"iccid" validate:"omitempty,max=30" description:"ICCID(精确)"`
StartTime string `json:"start_time" query:"start_time" description:"最近失败时间起始(带时区的 RFC3339 秒级时间)"`
EndTime string `json:"end_time" query:"end_time" description:"最近失败时间结束(带时区的 RFC3339 秒级时间)"`
}
// PollingFailureAlertItem 卡轮询失败告警。
type PollingFailureAlertItem struct {
ID uint `json:"id" description:"告警ID"`
AlertLevel string `json:"alert_level" description:"告警级别 (card:卡级, carrier:账户级)"`
CardID uint `json:"card_id" description:"卡ID,账户级为 0"`
ICCID string `json:"iccid" description:"ICCID"`
CarrierID uint `json:"carrier_id" description:"运营商账户ID"`
CarrierName string `json:"carrier_name" description:"运营商账户名称"`
CheckType string `json:"check_type" description:"检查类型"`
CheckTypeName string `json:"check_type_name" description:"检查类型名称"`
ErrorCategory string `json:"error_category" description:"最近错误类别"`
FailCount int `json:"fail_count" description:"连续失败次数;账户级为窗口内告警数"`
FirstFailedAt *time.Time `json:"first_failed_at" description:"首次失败时间"`
LastFailedAt *time.Time `json:"last_failed_at" description:"最近失败时间"`
LastError string `json:"last_error" description:"最近错误"`
Status int `json:"status" description:"状态 (1:未处理, 2:已恢复, 3:已关闭轮询, 4:已处理)"`
StatusName string `json:"status_name" description:"状态名称"`
HandledBy uint `json:"handled_by" description:"处理人"`
HandledAt *time.Time `json:"handled_at" description:"处理时间"`
HandleRemark string `json:"handle_remark" description:"处理备注"`
RecoveredAt *time.Time `json:"recovered_at" description:"自动恢复时间"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
}
// PollingFailureAlertPageResult 卡轮询失败告警分页结果。
type PollingFailureAlertPageResult struct {
List []PollingFailureAlertItem `json:"items" description:"告警列表"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"当前页"`
PageSize int `json:"size" description:"每页数量"`
}
// PollingFailureAlertSummaryItem 未处理告警按运营商账户 × 错误类别汇总。
type PollingFailureAlertSummaryItem struct {
CarrierID uint `json:"carrier_id" description:"运营商账户ID"`
CarrierName string `json:"carrier_name" description:"运营商账户名称"`
ErrorCategory string `json:"error_category" description:"错误类别"`
OpenCount int64 `json:"open_count" description:"未处理卡级告警数"`
}
// PollingFailureAlertIDPath 告警路径参数。
type PollingFailureAlertIDPath struct {
ID uint `json:"-" path:"id" required:"true" description:"告警ID"`
}
// HandlePollingFailureAlertRequest 标记告警已处理。
type HandlePollingFailureAlertRequest struct {
ID uint `json:"-" path:"id" required:"true" description:"告警ID"`
Status int `json:"status" validate:"required,oneof=4" required:"true" description:"目标状态 (4:已处理);关闭轮询请使用资产轮询开关接口"`
Remark string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"处理备注"`
}
// CardPollingStatePath 卡ID路径参数。
type CardPollingStatePath struct {
ID uint `json:"-" path:"id" required:"true" description:"卡ID"`
}
// CardPollingTypeState 卡某检查类型的轮询状态。
type CardPollingTypeState struct {
CheckType string `json:"check_type" description:"检查类型"`
CheckTypeName string `json:"check_type_name" description:"检查类型名称"`
NextDueAt *time.Time `json:"next_due_at" description:"下次到期时间"`
LastSuccessAt *time.Time `json:"last_success_at" description:"最近一次成功时间"`
FailCount int `json:"fail_count" description:"连续失败次数"`
FirstFailedAt *time.Time `json:"first_failed_at" description:"首次失败时间"`
LastError string `json:"last_error" description:"最近错误(类别|信息)"`
PendingConfirm []int `json:"pending_confirm" description:"待执行的延迟确认(秒)"`
}
// CardStopResumeCommandState 卡当前停复机指令(停复机指令队列)。
type CardStopResumeCommandState struct {
Action string `json:"action" description:"动作 (stop:停机, start:复机)"`
Reason string `json:"reason" description:"停机原因"`
Scenes []string `json:"scenes" description:"触发场景"`
Source string `json:"source" description:"请求来源"`
Version int64 `json:"version" description:"指令版本"`
FailCount int `json:"fail_count" description:"连续失败次数"`
LastError string `json:"last_error" description:"最近错误(类别|信息)"`
Pending bool `json:"pending" description:"结果未知,待确认"`
Unknown int `json:"unknown" description:"连续结果未知次数"`
WrittenAt *time.Time `json:"written_at" description:"最近写入时间"`
NextAt *time.Time `json:"next_at" description:"下次可执行时间(空表示不在队列中)"`
}
// CardPollingStateResponse 单卡轮询状态(只读)。
type CardPollingStateResponse struct {
CardID uint `json:"card_id" description:"卡ID"`
ICCID string `json:"iccid" description:"ICCID"`
CarrierID uint `json:"carrier_id" description:"运营商账户ID"`
SchedulerMode string `json:"scheduler_mode" description:"当前调度模式 (legacy:旧分片调度, carrier:按运营商账户调度)"`
EnablePolling bool `json:"enable_polling" description:"卡轮询开关"`
Queue string `json:"queue" description:"所在队列 (priority:优先, queue:普通, none:不在轮询中)"`
QueueScoreAt *time.Time `json:"queue_score_at" description:"队列中下次可领取时间"`
Running bool `json:"running" description:"是否执行中"`
ClaimExpireAt *time.Time `json:"claim_expire_at" description:"处理中标记到期时间"`
PriorityMark bool `json:"priority_mark" description:"执行中收到请求检查,收尾后进入优先队列"`
Types []CardPollingTypeState `json:"types" description:"各检查类型状态"`
StopResumeQueueEnabled bool `json:"stop_resume_queue_enabled" description:"停复机出口开关是否开启"`
StopResumeCommand *CardStopResumeCommandState `json:"stop_resume_command" description:"当前停复机指令(无指令为空)"`
LastStopResumeCallAt *time.Time `json:"last_stop_resume_call_at" description:"最近一次停复机网关调用时间(单卡最小重试间隔依据)"`
}
// CarrierPollingStatsItem 按运营商账户的轮询监控。
type CarrierPollingStatsItem struct {
CarrierID uint `json:"carrier_id" description:"运营商账户ID"`
CarrierName string `json:"carrier_name" description:"运营商账户名称"`
PriorityLength int64 `json:"priority_length" description:"优先队列长度"`
QueueLength int64 `json:"queue_length" description:"普通队列长度"`
DueCount int64 `json:"due_count" description:"已到期卡数(优先 + 普通)"`
Running int64 `json:"running" description:"执行中卡任务数"`
InflightLimit int `json:"inflight_limit" description:"执行上限"`
QPSLastMinute float64 `json:"qps_last_minute" description:"上一分钟实际网关调用 QPS(查询类)"`
RateLimitWaits int64 `json:"rate_limit_waits" description:"上一分钟限流等待次数"`
RateLimited int64 `json:"rate_limited" description:"上一分钟限流拒绝或等待超时次数"`
ExpiredClaims1h int64 `json:"expired_claims_1h" description:"近 1 小时处理中标记到期次数(执行崩溃或超时)"`
OpenAlerts int64 `json:"open_alerts" description:"未处理卡级失败告警数"`
OpenAlertsByType map[string]int64 `json:"open_alerts_by_category" description:"未处理卡级失败告警数(按错误类别)"`
StopResumeQueueLength int64 `json:"stop_resume_queue_length" description:"停复机指令队列长度"`
StopResumeDue int64 `json:"stop_resume_due" description:"已到期停复机指令数"`
StopResumeRunning int64 `json:"stop_resume_running" description:"执行中停复机指令数"`
StopResumePending int64 `json:"stop_resume_pending" description:"结果未知待确认的停复机指令数(按队列前 500 条统计)"`
StopResumeSuccess1h int64 `json:"stop_resume_success_1h" description:"近 1 小时停复机成功数"`
StopResumeFailed1h int64 `json:"stop_resume_failed_1h" description:"近 1 小时停复机失败数(计入连续失败或终态)"`
StopResumeRetry1h int64 `json:"stop_resume_retry_1h" description:"近 1 小时停复机推后重试数(限流、频率限制、最小间隔)"`
StopResumeUnknown1h int64 `json:"stop_resume_unknown_1h" description:"近 1 小时停复机结果未知数"`
}
// CarrierPollingStatsResponse 按运营商账户的轮询监控。
type CarrierPollingStatsResponse struct {
SchedulerMode string `json:"scheduler_mode" description:"当前调度模式"`
InitState string `json:"init_state" description:"新结构初始化状态 (running / done,空表示未初始化)"`
Items []CarrierPollingStatsItem `json:"items" description:"各运营商账户监控"`
}