Files
junhong_cmp_fiber/internal/domain/cardobservation/traffic.go
邹进 94cbf2adab feat: 采集记录成功失败分表并保存网关原始数据,到期归档 csv.gz,新增记录分页查询接口
- 网关客户端新增原始数据收集器,记录最后一次尝试的明文请求、HTTP 状态、响应体与 code/msg/trace_id
- tb_card_traffic_collection 只写成功读数,新增 carrier_id 与原始数据列;新增 tb_card_traffic_collection_failure,失败不判断有无套餐并带错误详情
- 采集记录在线保留当月加最近 2 个整月,到期分区摘出、导出 csv.gz、校验行数与 SHA-256 后删除,本地保留 3 个月
- 新增采集成功/失败、卡日流量、套餐日流量详单、冲正流水、退款后处理尝试列表接口:可查单个也可查全部,分页与条件筛选
- 停复机记录支持资产标识、场景、原因、指令号筛选;单卡历史支持动作、结果、来源筛选
- 单卡采集记录支持筛选与合并失败记录;套餐日流量详单支持分页;退款列表支持后处理状态筛选
- 测试环境 api、worker 日志分目录,保留 40 个压缩备份;worker 挂载 archive 目录
- 迁移 000272、000273 需维护者在测试库执行后再部署

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 18:47:00 +09:00

93 lines
3.6 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 cardobservation
import (
"math"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// TrafficObservation 是领域层接收的标准运营商流量读数。
type TrafficObservation struct {
CardID uint
GatewayReadingMB float64
// ReadingResult 是读数结果(constants.TrafficCollectionResult*);为空表示运营商给出了读数,
// 是否有效(有限且 ≥ 0)由观测用例判断。非 ok 的观测只写采集记录,不入队、不写快照。
ReadingResult string
ResetDay int
Metadata ObservationMetadata
// Raw 是本次网关调用的原始请求与响应,未收集时为 nil。
Raw *GatewayRaw
// Failure 是读数结果非 ok 时的失败详情,未提供时为 nil。
Failure *CollectionFailure
}
// GatewayRaw 是一次网关调用的原始数据(最后一次 HTTP 尝试),只含明文业务请求与网关响应。
type GatewayRaw struct {
Request []byte
HTTPStatus int
Response []byte
GatewayCode *int
GatewayMsg string
TraceID string
Attempts int
}
// CollectionFailure 是一次采集失败的错误详情。
type CollectionFailure struct {
ErrorCategory string
ProviderCode string
ProviderMessage string
DurationMS int
}
// TrafficDecision 描述一次流量观测的处理结果。
type TrafficDecision struct {
// IncrementMB 是本次写入流量事件的增量,0 表示没有写事件。
IncrementMB float64
// ReadingAccepted 为 true 表示本次读数通过采集队列判断并写入了日快照。
ReadingAccepted bool
// Decision 是写入判断(constants.TrafficDecision*);读数无效时为空。
Decision string
// Result 是读数结果(constants.TrafficCollectionResult*)。
Result string
// ReadingMB 是本次运营商读数,没有给值时为 nil。
ReadingMB *float64
// CrossMonth 为 true 表示本次写入使卡表本月用量跨入新的自然月。
CrossMonth bool
// CurrentMonthUsageMB 是写入后的本月最大快照(未写入时为卡表原值)。
CurrentMonthUsageMB float64
// LastGatewayReadingMB 保留卡表原值,卡表基线算法已下线,不再更新。
LastGatewayReadingMB float64
}
// ValidateTrafficObservation 校验观测元数据与读数结果;给出读数时读数必须是数字(有效性由用例判断)。
func ValidateTrafficObservation(observation TrafficObservation) error {
if err := validateObservationMetadata(observation.CardID, observation.Metadata); err != nil {
return err
}
switch observation.ReadingResult {
case "", constants.TrafficCollectionResultOK, constants.TrafficCollectionResultFailed, constants.TrafficCollectionResultRateLimited,
constants.TrafficCollectionResultInvalidPayload, constants.TrafficCollectionResultNoReading, constants.TrafficCollectionResultInvalidReading:
return nil
default:
return errors.New(errors.CodeInvalidParam, "流量观测读数结果无效")
}
}
// ResolveReadingResult 返回观测的最终读数结果:给出了读数但不是有限且 ≥ 0 的数时为读数无效。
func ResolveReadingResult(observation TrafficObservation) string {
if observation.ReadingResult != "" && observation.ReadingResult != constants.TrafficCollectionResultOK {
return observation.ReadingResult
}
reading := observation.GatewayReadingMB
if math.IsNaN(reading) || math.IsInf(reading, 0) || reading < 0 {
return constants.TrafficCollectionResultInvalidReading
}
return constants.TrafficCollectionResultOK
}
func validateObservationMetadata(cardID uint, metadata ObservationMetadata) error {
return validateObservation(RealnameObservation{CardID: cardID, Verified: true, Metadata: metadata})
}