Files
junhong_cmp_fiber/internal/model/dto/carrier_dto.go
邹进 96771a204f
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled
feat: 卡流量改为日快照计量并统一停复机规则
卡流量计量(按名单灰度,默认 off):
- 新增卡日快照与切换水位表(000241),按通道上游流量重置日换算自然月、重置日防旧值
- 已切换的卡按月对账产生增量,无生效中套餐只结算不发事件;第一次切换写水位
- 已切换卡读数有效即判定通道阈值,卡表本月用量用快照覆盖,日流量读快照
- 配置 JUNHONG_TRAFFIC_CALC_MODE/CARDS、JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED

停复机规则(总开关 JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED,默认关闭):
- 复机不看停机原因,持通道阈值锁仍拒绝;暂停轮询的卡不自动停复机
- 通道新增实名管控 realname_control_enabled(000242,默认 0),开启后不区分行业卡与实名策略
- 实名管控从 0 改 1 需确认,修改并入通道更新审计

OpenSpec Change: rebuild-card-traffic-metering-and-stop-resume
2026-10-20 17:49:26 +09:00

151 lines
13 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"
type CreateCarrierRequest struct {
CarrierCode string `json:"carrier_code" validate:"required,min=1,max=50" required:"true" minLength:"1" maxLength:"50" description:"运营商编码"`
CarrierName string `json:"carrier_name" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"运营商名称"`
CarrierType string `json:"carrier_type" validate:"required,oneof=CMCC CUCC CTCC CBN" required:"true" description:"运营商类型 (CMCC:中国移动, CUCC:中国联通, CTCC:中国电信, CBN:中国广电)"`
Description string `json:"description" validate:"omitempty,max=500" maxLength:"500" description:"运营商描述"`
DataResetDay *int `json:"data_reset_day" validate:"omitempty,min=1,max=28" minimum:"1" maximum:"28" description:"上游流量重置日(1-28),运营商每月清零网关计数器的日期,默认1"`
RealnameLinkType *string `json:"realname_link_type" validate:"omitempty,oneof=none template gateway" description:"实名链接类型 none-不支持 template-模板URL gateway-Gateway接口"`
RealnameLinkTemplate *string `json:"realname_link_template" validate:"omitempty,max=500" maxLength:"500" description:"实名链接模板URL,支持 {iccid}/{msisdn}/{virtual_no} 占位符"`
TrafficThresholdEnabled *int `json:"traffic_threshold_enabled" validate:"omitempty,oneof=0 1" description:"通道流量阈值是否启用 (0:禁用, 1:启用),仅超级管理员与平台账号可配置"`
TrafficThresholdValue *float64 `json:"traffic_threshold_value" validate:"omitempty,gt=0" description:"通道流量阈值数值,必须为正数,单位由 traffic_threshold_unit 决定,仅超级管理员与平台账号可配置"`
TrafficThresholdUnit *string `json:"traffic_threshold_unit" validate:"omitempty,oneof=MB GB" description:"通道流量阈值单位 (MB:兆字节, GB:吉字节,1 GB = 1024 MB),仅超级管理员与平台账号可配置"`
RealnameControlEnabled *int `json:"realname_control_enabled" validate:"omitempty,oneof=0 1" description:"通道实名管控 (0:不管控, 1:管控),默认0;只在停复机新规则开启后影响停复机:管控时未实名卡停机、实名后才复机。仅超级管理员与平台账号可配置"`
}
// HasTrafficThresholdFields 判断请求是否携带仅平台账号可配置的通道字段(通道流量阈值、通道实名管控)。
// 非超管、非平台账号提交携带这些字段的请求必须被整体拒绝。
func (r *CreateCarrierRequest) HasTrafficThresholdFields() bool {
if r == nil {
return false
}
return r.TrafficThresholdEnabled != nil || r.TrafficThresholdValue != nil || r.TrafficThresholdUnit != nil ||
r.RealnameControlEnabled != nil
}
type UpdateCarrierRequest struct {
CarrierName *string `json:"carrier_name" validate:"omitempty,min=1,max=100" minLength:"1" maxLength:"100" description:"运营商名称"`
Description *string `json:"description" validate:"omitempty,max=500" maxLength:"500" description:"运营商描述"`
DataResetDay *int `json:"data_reset_day" validate:"omitempty,min=1,max=28" minimum:"1" maximum:"28" description:"上游流量重置日(1-28),运营商每月清零网关计数器的日期"`
RealnameLinkType *string `json:"realname_link_type" validate:"omitempty,oneof=none template gateway" description:"实名链接类型 none-不支持 template-模板URL gateway-Gateway接口"`
RealnameLinkTemplate *string `json:"realname_link_template" validate:"omitempty,max=500" maxLength:"500" description:"实名链接模板URL,支持 {iccid}/{msisdn}/{virtual_no} 占位符"`
TrafficThresholdEnabled *int `json:"traffic_threshold_enabled" validate:"omitempty,oneof=0 1" description:"通道流量阈值是否启用 (0:禁用, 1:启用),仅超级管理员与平台账号可配置"`
TrafficThresholdValue *float64 `json:"traffic_threshold_value" validate:"omitempty,gt=0" description:"通道流量阈值数值,必须为正数,单位由 traffic_threshold_unit 决定,仅超级管理员与平台账号可配置"`
TrafficThresholdUnit *string `json:"traffic_threshold_unit" validate:"omitempty,oneof=MB GB" description:"通道流量阈值单位 (MB:兆字节, GB:吉字节,1 GB = 1024 MB),仅超级管理员与平台账号可配置"`
RealnameControlEnabled *int `json:"realname_control_enabled" validate:"omitempty,oneof=0 1" description:"通道实名管控 (0:不管控, 1:管控),默认0;只在停复机新规则开启后影响停复机:管控时未实名卡停机、实名后才复机。仅超级管理员与平台账号可配置"`
RealnameControlConfirm *bool `json:"realname_control_confirm" description:"把实名管控从 0 改为 1 时必须传 true,确认该通道未实名的开机卡会在下一次评估时被停机"`
}
// HasTrafficThresholdFields 判断请求是否携带仅平台账号可配置的通道字段(通道流量阈值、通道实名管控)。
// 非超管、非平台账号提交携带这些字段的请求必须被整体拒绝。
func (r *UpdateCarrierRequest) HasTrafficThresholdFields() bool {
if r == nil {
return false
}
return r.TrafficThresholdEnabled != nil || r.TrafficThresholdValue != nil || r.TrafficThresholdUnit != nil ||
r.RealnameControlEnabled != nil
}
type CarrierListRequest 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:"每页数量"`
CarrierType *string `json:"carrier_type" query:"carrier_type" validate:"omitempty,oneof=CMCC CUCC CTCC CBN" description:"运营商类型 (CMCC:中国移动, CUCC:中国联通, CTCC:中国电信, CBN:中国广电)"`
CarrierName *string `json:"carrier_name" query:"carrier_name" validate:"omitempty,max=100" maxLength:"100" description:"运营商名称(模糊搜索)"`
Status *int `json:"status" query:"status" validate:"omitempty,oneof=0 1" description:"状态 (1:启用, 0:禁用)"`
}
type UpdateCarrierStatusRequest struct {
Status int `json:"status" validate:"required,oneof=0 1" required:"true" description:"状态 (1:启用, 0:禁用)"`
}
type CarrierResponse struct {
ID uint `json:"id" description:"运营商ID"`
CarrierCode string `json:"carrier_code" description:"运营商编码"`
CarrierName string `json:"carrier_name" description:"运营商名称"`
CarrierType string `json:"carrier_type" description:"运营商类型 (CMCC:中国移动, CUCC:中国联通, CTCC:中国电信, CBN:中国广电)"`
Description string `json:"description" description:"运营商描述"`
DataResetDay int `json:"data_reset_day" description:"上游流量重置日(1-28)"`
RealnameLinkType string `json:"realname_link_type" description:"实名链接类型 none-不支持 template-模板URL gateway-Gateway接口"`
RealnameLinkTemplate string `json:"realname_link_template" description:"实名链接模板URL"`
Status int `json:"status" description:"状态 (1:启用, 0:禁用)"`
// 阈值字段仅对超级管理员与平台账号返回;其他账号响应中不出现这三个字段。
TrafficThresholdEnabled *int `json:"traffic_threshold_enabled,omitempty" description:"通道流量阈值是否启用 (0:禁用, 1:启用),仅超级管理员与平台账号可见"`
TrafficThresholdValue *float64 `json:"traffic_threshold_value,omitempty" description:"通道流量阈值数值,单位由 traffic_threshold_unit 决定,未配置时不返回,仅超级管理员与平台账号可见"`
TrafficThresholdUnit *string `json:"traffic_threshold_unit,omitempty" description:"通道流量阈值单位 (MB:兆字节, GB:吉字节,1 GB = 1024 MB),未配置时不返回,仅超级管理员与平台账号可见"`
RealnameControlEnabled *int `json:"realname_control_enabled,omitempty" description:"通道实名管控 (0:不管控, 1:管控),仅超级管理员与平台账号可见"`
CreatedAt string `json:"created_at" description:"创建时间"`
UpdatedAt string `json:"updated_at" description:"更新时间"`
}
type UpdateCarrierParams struct {
IDReq
UpdateCarrierRequest
}
type UpdateCarrierStatusParams struct {
IDReq
UpdateCarrierStatusRequest
}
type CarrierPageResult struct {
List []*CarrierResponse `json:"items" description:"运营商列表"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"当前页"`
PageSize int `json:"size" description:"每页数量"`
}
// CarrierThresholdHitListRequest 是通道阈值命中记录的查询参数。
//
// 判定时间使用统一时间筛选参数名 start_time/end_time(带显式时区的 RFC3339 秒级,闭区间含两端,
// 开始晚于结束拒绝);计费周期起点用周期起点的瞬时精确匹配,与判定时间共用同一严格解析器。
type CarrierThresholdHitListRequest struct {
Page int `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码,默认1"`
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量,默认20,最大100"`
CarrierID *uint `json:"carrier_id" query:"carrier_id" validate:"omitempty,min=1" minimum:"1" description:"运营商通道ID"`
CardID *uint `json:"card_id" query:"card_id" validate:"omitempty,min=1" minimum:"1" description:"IoT卡ID"`
// PeriodStart 为计费周期起点,取值必须与命中事实记录的周期起点时刻一致(如东八区 2026-09-01T00:00:00+08:00)。
PeriodStart string `json:"period_start" query:"period_start" description:"计费周期起点,带时区的RFC3339秒级时间,精确匹配该计费周期"`
StartTime string `json:"start_time" query:"start_time" description:"判定时间范围开始,带时区的RFC3339秒级时间,闭区间含该时刻"`
EndTime string `json:"end_time" query:"end_time" description:"判定时间范围结束,带时区的RFC3339秒级时间,闭区间含该时刻"`
}
// CarrierThresholdHitItem 是一条通道阈值命中事实。
//
// 累计流量与阈值为命中时冻结的证据:历史行(本次上线前)未记录读数与阈值,按「无」返回空值,
// 不阻断查询;判定时间取既有创建时间。响应不包含任何凭证与上游响应原文。
type CarrierThresholdHitItem struct {
ID uint `json:"id" description:"命中记录ID"`
CarrierID uint `json:"carrier_id" description:"运营商通道ID"`
CardID uint `json:"card_id" description:"IoT卡ID"`
// PeriodStart 是计费周期起点。
PeriodStart time.Time `json:"period_start" description:"计费周期起点"`
// HitTrafficMB 为空表示无(历史行读数不可重建)。
HitTrafficMB *float64 `json:"hit_traffic_mb" description:"命中时该卡当前计费周期的累计流量读数(MB),取与停机判定同一来源的网关累计读数,不使用本地用量或套餐真流量;为空表示无"`
// HitThresholdValue 为空表示无(历史行未记录)。
HitThresholdValue *float64 `json:"hit_threshold_value" description:"本次判定实际生效的通道阈值数值,冻结命中时值,通道阈值变更不改写历史命中;为空表示无"`
// HitThresholdUnit 为空字符串表示无(历史行未记录)。
HitThresholdUnit string `json:"hit_threshold_unit" description:"本次判定阈值单位 MB-兆字节 GB-吉字节;空字符串表示无"`
// TriggerSource 取值与 constants.CardObservationSource* 一致,空字符串表示无。
TriggerSource string `json:"trigger_source" description:"触发本次判定的流量观测来源 polling-周期轮询 manual_sync-手动同步 manual_override-人工纠偏 carrier_callback-运营商回调 business_event-业务成功后的观测;空字符串表示无"`
JudgedAt time.Time `json:"judged_at" description:"判定时间,既有锁行取创建时间"`
Status string `json:"status" description:"锁状态 locked-持锁中 unlocked-已跨期解锁"`
// UnlockedAt 为空表示尚未解锁。
UnlockedAt *time.Time `json:"unlocked_at" description:"周期恢复的解锁时间,未解锁为空"`
// ResumeResult 为空字符串表示未处理或历史行。
ResumeResult string `json:"resume_result" description:"周期恢复的复机结果 resumed-已发起复机 skipped-仅解锁未复机 manual-周期归属不可判定转人工;空字符串表示未处理或历史行"`
// FailureReason 只承载可安全展示的跳过原因或转人工原因,不含内部细节与渠道报文。
FailureReason string `json:"failure_reason" description:"跳过复机或转人工核对的可安全原因,无则为空"`
CreatedAt time.Time `json:"created_at" description:"记录创建时间"`
}
// CarrierThresholdHitPageResult 是通道阈值命中记录的分页结果。
type CarrierThresholdHitPageResult struct {
List []*CarrierThresholdHitItem `json:"items" description:"通道阈值命中记录列表,按判定时间倒序"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"当前页"`
PageSize int `json:"size" description:"每页数量"`
}