26 Commits

Author SHA1 Message Date
邹进
46f3a7741b docs: 实名记录与二次实名接口登记到 OpenAPI 文档
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 18m2s
2026-11-08 19:18:16 +09:00
邹进
4967f4df43 feat: 卡实名时间以上游 archiveTime 为准并记录实名时间历史,新增二次实名批次
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled
2026-11-08 19:12:46 +09:00
邹进
94f86ab217 docs: 实名时间以 archiveTime 为准,二次实名按是否返回 archiveTime 判定 2026-11-08 18:47:52 +09:00
邹进
76d0f38b9e docs: 新增实名时间与历史、二次实名及按资产号批量延期提案 2026-11-08 18:44:44 +09:00
邹进
0138a3fb9c feat: 延期资格返回套餐名称、资产、订购时间、到期时间与沉默期截止时间
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 25m44s
2026-11-07 22:50:37 +09:00
邹进
7b13431f36 fix: 微信 H5 下单被明确拒绝时报真实原因并关单,不再显示请求超时
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled
微信 v2 统一下单返回 result_code=FAIL(如 NOAUTH 商户未开通 H5 产品)时订单未创建,
原来一律按结果未知返回"请求超时"、订单挂到支付截止才关。改为验签后按明确失败返回微信原因,
调用方立即关单;用微信配置不可用错误码,不触发商户自动停用。ORDERPAID、OUT_TRADE_NO_USED、SYSTEMERROR 仍按未知处理。
2026-11-07 22:12:42 +09:00
邹进
b2fc74c021 feat: H5 沉默期延期微信支付改为微信内直接拉起(JSAPI)
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled
- H5 下单带 app_type 且选微信、商户为微信直连时,复用套餐购买的 JSAPI 预下单,返回 pay_config
- 调起参数保存在支付单,延期订单详情可继续支付;查单、回调、超时关单、作废沿用原流程
- 后台生成二维码、支付宝、富友商户保持原方式
2026-11-07 21:57:22 +09:00
邹进
8b0a01753d fix: 后台作废延期订单报"延期订单 ID 必须大于 0"
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 35m45s
ID 来自路径参数,请求体里没有;去掉请求体校验里的 ID 必填,路径 ID 由 handler 校验
2026-11-07 21:03:22 +09:00
邹进
d3face6f66 fix: 延期订单超时不关闭、无法继续支付、不能作废
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled
- 支付宝查单把 ACQ.TRADE_NOT_EXIST 当成查单失败,恢复任务永远判为未知,订单停在待支付;
  同一套餐再下单时旧单也关不掉,新单无法创建。改为按"渠道无此订单"处理,过支付截止后关闭
- 延期订单详情对未过期的待支付订单返回 qr_content,后台可展示二维码、H5 可继续支付
- 新增作废待支付订单:后台 POST /orders/:id/close、H5 POST /orders/:id/cancel;作废前先查单,已支付则按支付成功办理
2026-11-07 20:31:45 +09:00
邹进
226a15573a fix: 观测序列与拒绝停机告警读取 ICCID 时显式指定列名
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 1h20m10s
GORM 默认把字段 ICCID 映射成 icc_id:
- 观测序列设备换卡的本地预期判定读不到当前卡 ICCID,永远判不成立,只能靠调网关重试到上限
- 拒绝停机告警列表 ICCID 一直为空
补列名测试防回归。
2026-11-07 17:39:46 +09:00
邹进
eb0d86df4f fix: 记录查询扫描结构显式指定列名,修复 ICCID 一直为空
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled
GORM 默认把字段 ICCID 映射成 icc_id,卡日流量的 c.iccid 和展示字段批量查询都读不到值;
扫描用的匿名结构统一写 gorm column tag。
2026-11-07 17:33:28 +09:00
邹进
3f593b912d feat: 记录查询列表补齐 ICCID、设备号、套餐名称、运营商名称与操作人
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Failing after 4m7s
分页后按当前页 ID 批量查主键补齐展示字段,不在分页查询中关联,也不在记录表冗余:
- 采集成功记录补 ICCID、运营商名称;采集失败、卡日流量补运营商名称
- 套餐日流量详单、冲正流水补套餐名称、ICCID、设备号与 IMEI
- 冲正流水(含资产详情)补操作人用户名;退款后处理尝试记录补设备号与 IMEI
2026-11-07 17:07:27 +09:00
邹进
7d705cf1e8 chore: 测试环境数据库与 Redis 迁到 kt.whcxd.cn(15434 / 16380)
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 29m31s
旧主机 cxd.whcxd.cn 出口带宽约 4.5 Mbit/s,测试环境读写被限速;改用新实例(PostgreSQL 17、Redis 7.2.4)。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 19:03:07 +09:00
邹进
1214181e78 feat: 轮询观测入库异步化,调网关与入库分离,采集记录经消息攒批写入
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 16m2s
- 轮询步骤异步模式下只调网关并发布 card.ingest 入库消息,入库消费者固定并发 30、按采集 ID 去重、可重试错误不限次数退避重投
- 采集记录经 card.collection 攒批写入,失败整批重投,新增 (observation_id, observed_at) 唯一索引
- 网络、实名观测增加乱序保护;轮询读查询走缓存,套餐状态查询各自计时且失败不缓存
- 入库积压告警与反压;系统配置 polling.ingest.mode 默认 sync 可回退;测试环境 nsqd 消息全部落盘

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-06 16:33:29 +09:00
邹进
7e0e37933e fix: 卡日流量查询改用卡日快照 tb_card_flow_day
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 12m2s
tb_card_daily_usage 为已停用旧表(测试库为空,且列名与模型不一致),
卡日流量列表与索引改用采集链路写入的 tb_card_flow_day,当日用量取 settled_mb。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 18:59:30 +09:00
邹进
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
邹进
8eb7d403c4 feat: 退款资产后处理逐次尝试记录与重试上限,停复机指令调用前结束写跳过记录
- 新增 tb_refund_post_process_attempt,每次尝试一条(步骤、触发方式、结果、错误码与信息、耗时)
- 退款单增加 asset_post_status/attempts/last_error/next_at;失败按 2^(n-1) 分钟退避(最长 1 小时),10 次后转人工
- 中间失败只写应用日志,成功或转人工写一条结论审计(带总尝试次数、首次失败时间、最后错误码)
- 补偿扫描跳过需人工处理与未到重试时间的退款单,Outbox 不再无限重投
- 新增 POST /refunds/:id/asset-post-processing/retry 人工重试
- 停复机指令执行前结束(已是目标状态、条件不再满足、需相反动作)写 skipped 停复机记录
- 迁移 000271 需维护者在测试库执行后再部署

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 18:33:32 +09:00
邹进
b7a7430cc3 feat: 审计动作按落库策略分级写入,系统过程动作改写应用日志
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 12m8s
- 审计注册表为可由系统任务、定时任务发起的动作声明落库策略(always/on_success/outcome/log_only/none),未声明按 log_only
- 人工、开放接口、个人客户、外部系统发起的动作始终写审计表
- log_only 写所在服务 app.log(logger=audit),不含快照
- 对接日志不再补写 integration.attempt_started,无上游审计时 audit_event_id 为空
- 新增 audit.persist_overrides 按动作覆盖策略
- 审计覆盖扫描要求机器动作必须声明策略
- 新增 OpenSpec 提案 refactor-audit-log-persistence 与技术方案文档

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 18:27:24 +09:00
邹进
96ff9c1e35 fix: 换货迁移按套餐是否已开始与新资产占位决定主套餐状态
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 12m0s
- 未开始的主套餐(无生效、到期时间且无用量)迁移为待生效,新资产不满足实名条件(行业卡/已实名/无需实名)时标记等实名激活
- 已开始的主套餐在新资产无当前主套餐时原样迁移;新资产已有当前主套餐时改为待生效排队、清空周期与用量
- 迁移后重排新资产主套餐优先级,保证同一载体只有一个当前主套餐
- 换货审计记录套餐状态、优先级、用量的前后值

OpenSpec: fix-exchange-migration-package-state

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 23:25:06 +09:00
邹进
b0a7004cf9 docs: 记录换货迁移导致主套餐双生效的生产数据修正
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 23:24:43 +09:00
邹进
f0b54b8b52 chore: 测试环境 worker 任务并发调到 50、数据库连接池放大
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 11m59s
默认并发 10 时流量扣减事件投递跟不上,白天积压 1 万+、延迟约 2.5 小时。
网关只读开关不变。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 18:16:20 +09:00
邹进
ce2977ce22 fix: C 端设备局域网地址为空时默认 192.168.1.1
网关常不返回设备 lan_ip,H5 点后台管理时提示设备未开机;为空时回落到设备默认网关地址。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 11:21:38 +09:00
邹进
b3f66a01a8 chore: 补充换货原因长度放宽迁移 000270
生产库与测试库已手动执行,迁移重复执行结果不变;回滚不缩短长度,避免截断已有数据。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 11:15:39 +09:00
邹进
afc7e5285e fix: 换货原因长度上限放宽到 500 字
从微信复制的多行换货说明常超过 100 字,创建换货单时报参数验证失败。
请求校验与模型字段长度同步改为 500;生产库已手动执行 ALTER,迁移文件随 Iteration/8-11 编号补充。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 11:15:31 +09:00
邹进
dc816b44d0 fix: 卡或绑定设备关闭轮询时不再自动停复机
关闭轮询的卡/设备已导入其他卡管,去掉套餐到期、退款场景对暂停轮询卡的停机放行,
任何场景都不停机也不复机(单卡判断与设备下逐卡停机同步收口)。
场景判断函数更名为 StopResumeSceneIgnoresNetworkStatus,只保留不看库里开停状态的语义。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 17:01:55 +09:00
邹进
f274f8bb58 feat: 调整验证码短信文案
改为「您的验证码是XXXXXX,请在5分钟内输入验证。如非本人操作,请忽略本短信。」

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 15:56:26 +09:00
185 changed files with 10256 additions and 394 deletions

View File

@@ -50,8 +50,10 @@ jobs:
- name: 部署到测试环境(仅八月迭代分支)
if: github.ref == 'refs/heads/Iteration/8-11'
run: |
# 确保部署目录存在(仅需日志目录,配置已嵌入二进制文件)
mkdir -p ${{ env.DEPLOY_DIR }}/logs
# 确保部署目录存在:api、worker 各自的日志目录与 worker 的采集记录归档目录(配置已嵌入二进制文件)
mkdir -p ${{ env.DEPLOY_DIR }}/api/logs ${{ env.DEPLOY_DIR }}/worker/logs ${{ env.DEPLOY_DIR }}/worker/archive
# 容器以 uid 1000(appuser)运行,新目录需可写;无权限修改属主时保持原样
chown 1000:1000 ${{ env.DEPLOY_DIR }}/api/logs ${{ env.DEPLOY_DIR }}/worker/logs ${{ env.DEPLOY_DIR }}/worker/archive 2>/dev/null || true
umask 077
{

View File

@@ -2,6 +2,7 @@ package main
import (
stdErrors "errors"
auditInfra "github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
"os"
"os/signal"
"reflect"
@@ -146,6 +147,7 @@ func initLogger(cfg *config.Config) *zap.Logger {
appLogger := logger.GetAppLogger()
appLogger.Info("应用程序启动中...", zap.String("address", cfg.Server.Address))
applyAuditPersistOverrides(cfg, appLogger)
return appLogger
}
@@ -472,3 +474,10 @@ func initGateway(cfg *config.Config, db *gorm.DB, appLogger *zap.Logger) *gatewa
return client
}
// applyAuditPersistOverrides 加载审计落库策略的运行时覆盖;非法项忽略并告警。
func applyAuditPersistOverrides(cfg *config.Config, appLogger *zap.Logger) {
if invalid := auditInfra.SetPersistOverrides(cfg.Audit.PersistOverrides); len(invalid) > 0 {
appLogger.Warn("审计落库策略覆盖存在非法项,已忽略", zap.Strings("invalid", invalid))
}
}

View File

@@ -42,9 +42,11 @@ type carrierSchedulerRuntime struct {
srConsumers *nsqbus.ConsumerManager
devConsumers *nsqbus.ConsumerManager
srActive bool
singleton bool
instanceID string
logger *zap.Logger
// ingest 是轮询观测入库消费者与积压监控(add-polling-async-ingest);未配置 nsqd 时为 nil。
ingest *pollingIngestRuntime
singleton bool
instanceID string
logger *zap.Logger
mu sync.Mutex
lastMode string
@@ -104,6 +106,7 @@ func startCarrierScheduler(ctx context.Context, cfg *config.Config, runtime *wor
MsgTimeout: carrierCfg.MsgTimeout, MaxAttempts: carrierCfg.MaxAttempts,
}, constants.NSQChannelWorker, executor.Handle, appLogger)
}
c.ingest = startPollingIngest(ctx, cfg, runtime, c.producer, singleton, c.grace(), appLogger)
c.setupStopResume(carrierCfg, alerts)
var budgets carrierqueue.BudgetProvider
if runtime.gatewayLimit != nil && runtime.gatewayLimit.Limiter != nil {
@@ -302,6 +305,8 @@ func (c *carrierSchedulerRuntime) shutdown() {
}(manager)
}
wg.Wait()
// 卡任务消费者停止后不再产生入库消息,再停入库与采集记录消费者,最后停生产者。
c.ingest.shutdown()
if c.producer != nil {
c.producer.Stop()
}

View File

@@ -151,6 +151,9 @@ func runWorker(cfg *config.Config) {
defer func() {
_ = logger.Sync() // 忽略 sync 错误
}()
if invalid := auditInfra.SetPersistOverrides(cfg.Audit.PersistOverrides); len(invalid) > 0 {
logger.GetAppLogger().Warn("审计落库策略覆盖存在非法项,已忽略", zap.Strings("invalid", invalid))
}
retentionLogger, syncRetentionLogger := logger.NewRetentionLogger(cfg.Logging.Level, logger.LogRotationConfig{
Filename: cfg.Logging.RetentionLog.Filename, MaxSize: cfg.Logging.RetentionLog.MaxSize,
MaxBackups: cfg.Logging.RetentionLog.MaxBackups, MaxAge: cfg.Logging.RetentionLog.MaxAge, Compress: cfg.Logging.RetentionLog.Compress,
@@ -860,10 +863,10 @@ func startOutboxRelay(ctx context.Context, runtime *workerRuntime, instanceName
appLogger.Info("Outbox Relay 已启动", zap.String("lease_owner", owner))
}
// startTrafficCollectionPartitionMaintainer 为 leader/all 维护卡流量采集记录月分区并扫描采集告警:
// 每 12 小时预建本月起 2 个月的分区、删除整月都早于保留期的分区;每天扫描一次前一天的采集告警。
// startTrafficCollectionPartitionMaintainer 为 leader/all 维护卡流量采集记录(成功与失败)月分区并扫描采集告警:
// 每 12 小时预建本月起 2 个月的分区,到期分区导出为 csv.gz、校验后删除;每天扫描一次前一天的采集告警。
func startTrafficCollectionPartitionMaintainer(ctx context.Context, runtime *workerRuntime, appLogger *zap.Logger) {
store := postgres.NewCardTrafficCollectionStore(runtime.db)
archiver := cardObservationInfra.NewCollectionArchiver(runtime.db, constants.TrafficCollectionArchiveDir, constants.TrafficCollectionArchiveKeepFiles, appLogger)
alerts := cardObservationInfra.NewTrafficAlertScanner(runtime.db, appLogger)
go func() {
ticker := time.NewTicker(time.Hour)
@@ -873,7 +876,7 @@ func startTrafficCollectionPartitionMaintainer(ctx context.Context, runtime *wor
for {
now := time.Now()
if now.Sub(lastMaintained) >= 12*time.Hour {
if err := store.MaintainPartitions(ctx, now, 2, constants.TrafficCollectionRetentionDays); err != nil && ctx.Err() == nil {
if err := archiver.Maintain(ctx, now); err != nil && ctx.Err() == nil {
appLogger.Error("维护卡流量采集记录分区失败", zap.Error(err))
} else {
lastMaintained = now

View File

@@ -0,0 +1,160 @@
package main
import (
"context"
"time"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/internal/infrastructure/nsqbus"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/internal/task"
"github.com/break/junhong_cmp_fiber/pkg/config"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// pollingIngestRuntime 是轮询观测入库异步化在 Worker 内的运行组件(add-polling-async-ingest):
// 入库消费者、采集记录批量消费者、活动优先项索引重建与积压监控。入库消费者常驻订阅,
// 使切回同步模式后队列中已有的入库消息仍会被处理完。
type pollingIngestRuntime struct {
runtime *workerRuntime
nsqdAddress string
executor *task.IngestExecutor
collector *task.CollectionBatchConsumer
ingest *nsqbus.ConsumerManager
collection *nsqbus.ConsumerManager
rebuilder *task.PriorityIndexRebuilder
stopCollect context.CancelFunc
grace time.Duration
logger *zap.Logger
}
// startPollingIngest 注入入库发布器并启动入库与采集记录消费者;未配置 nsqd 时返回 nil,轮询保持同步入库。
func startPollingIngest(ctx context.Context, cfg *config.Config, runtime *workerRuntime, producer *nsqbus.Producer,
singleton bool, grace time.Duration, logger *zap.Logger) *pollingIngestRuntime {
carrierCfg := cfg.Polling.Carrier
if producer == nil || carrierCfg.NSQDAddress == "" {
return nil
}
checkIngestConnBudget(cfg, logger)
publisher := task.NewIngestPublisher(producer)
runtime.pollingBase.SetIngest(publisher, func(ctx context.Context) bool {
return runtime.carrierSettings.Current(ctx).IngestAsync()
})
observation := runtime.workerResult.Services.CardObservation
if observation != nil {
observation.SetCollectionSink(publisher)
}
r := &pollingIngestRuntime{
runtime: runtime, nsqdAddress: carrierCfg.NSQDAddress, grace: grace, logger: logger,
executor: task.NewIngestExecutor(runtime.pollingBase, observation, cfg.Polling.Ingest.EffectiveTimeout()),
collector: task.NewCollectionBatchConsumer(runtime.db, cfg.Polling.Collection.EffectiveBatchSize(), logger),
rebuilder: task.NewPriorityIndexRebuilder(postgres.NewPollingPriorityItemStore(runtime.db), runtime.redisClient, logger),
}
collectCtx, stopCollect := context.WithCancel(context.Background())
r.stopCollect = stopCollect
r.collector.Start(collectCtx)
consumerCfg := nsqbus.ConsumerConfig{
NSQDAddress: carrierCfg.NSQDAddress, NSQLookupdAddresses: nsqbus.SplitAddresses(carrierCfg.NSQLookupdAddresses),
MsgTimeout: carrierCfg.MsgTimeout, UnlimitedAttempts: true,
}
r.ingest = nsqbus.NewRetryConsumerManager(consumerCfg, constants.NSQChannelWorker, r.executor.Handle, logger)
r.collection = nsqbus.NewRetryConsumerManager(consumerCfg, constants.NSQChannelWorker, r.collector.Handle, logger)
r.ingest.Sync(map[string]int{constants.NSQCardIngestTopic: cfg.Polling.Ingest.EffectiveConcurrency()})
r.collection.Sync(map[string]int{constants.NSQCardCollectionTopic: constants.PollingCollectionMaxInFlight})
logger.Info("轮询观测入库消费者已启动", zap.Int("ingest_concurrency", cfg.Polling.Ingest.EffectiveConcurrency()),
zap.Duration("ingest_timeout", cfg.Polling.Ingest.EffectiveTimeout()),
zap.Int("collection_batch_size", cfg.Polling.Collection.EffectiveBatchSize()))
if singleton {
go r.loop(ctx)
}
return r
}
// checkIngestConnBudget 启动时检查入库并发与采集记录写并发不超过数据库连接数减去预留,超过只记 ERROR、不阻止启动。
func checkIngestConnBudget(cfg *config.Config, logger *zap.Logger) {
maxOpen := cfg.Database.MaxOpenConns
if maxOpen <= 0 {
maxOpen = constants.DefaultMaxOpenConns
}
need := cfg.Polling.Ingest.EffectiveConcurrency() + constants.PollingIngestCollectionWriters
if budget := maxOpen - constants.PollingIngestConnReserve; need > budget {
logger.Error("入库并发超出数据库连接预算,请调小 polling.ingest.concurrency 或调大数据库连接数",
zap.Int("ingest_concurrency", cfg.Polling.Ingest.EffectiveConcurrency()),
zap.Int("collection_writers", constants.PollingIngestCollectionWriters),
zap.Int("max_open_conns", maxOpen), zap.Int("reserved", constants.PollingIngestConnReserve))
}
}
// loop 在 leader 上定期重建活动优先项索引并检查入库积压。
func (r *pollingIngestRuntime) loop(ctx context.Context) {
r.rebuilder.Rebuild(ctx)
rebuild := time.NewTicker(constants.PollingPriorityIndexRebuildEvery)
monitor := time.NewTicker(constants.PollingIngestMonitorInterval)
defer rebuild.Stop()
defer monitor.Stop()
for {
select {
case <-ctx.Done():
return
case <-rebuild.C:
r.rebuilder.Rebuild(ctx)
case <-monitor.C:
r.checkBacklog(ctx)
}
}
}
// checkBacklog 记录入库与采集记录积压,超过告警阈值或等待过久记 ERROR;入库积压超过反压阈值时暂停派发新卡任务,降到一半以下恢复。
func (r *pollingIngestRuntime) checkBacklog(ctx context.Context) {
defer func() {
if recovered := recover(); recovered != nil {
r.logger.Error("入库积压检查 panic,已恢复", zap.Any("panic", recovered))
}
}()
settings := r.runtime.carrierSettings.Current(ctx)
ingestDepth, ingestErr := nsqbus.TopicBacklog(ctx, r.nsqdAddress, constants.NSQCardIngestTopic)
collectionDepth, collectionErr := nsqbus.TopicBacklog(ctx, r.nsqdAddress, constants.NSQCardCollectionTopic)
if ingestErr != nil || collectionErr != nil {
r.logger.Warn("读取入库积压失败", zap.NamedError("ingest_error", ingestErr), zap.NamedError("collection_error", collectionErr))
return
}
lag := r.executor.LastLag()
fields := []zap.Field{zap.Int64("ingest_backlog", ingestDepth), zap.Int64("collection_backlog", collectionDepth),
zap.Duration("ingest_lag", lag), zap.String("ingest_mode", settings.IngestMode)}
r.logger.Info("轮询入库积压", append(fields, zap.String("metric", "polling.ingest.backlog"))...)
alertDepth := int64(settings.IngestAlertDepth)
if ingestDepth > alertDepth || collectionDepth > alertDepth || lag > constants.PollingIngestLagAlert {
r.logger.Error("轮询入库积压超过告警阈值", append(fields, zap.Int64("alert_depth", alertDepth))...)
}
r.applyBackpressure(ctx, ingestDepth, int64(settings.IngestPauseDepth))
}
// applyBackpressure 按积压置位或清除暂停标记;标记带 TTL,leader 失联时自动解除。
func (r *pollingIngestRuntime) applyBackpressure(ctx context.Context, depth, pauseDepth int64) {
redisClient := r.runtime.redisClient
paused, _ := redisClient.Exists(ctx, constants.RedisPollingIngestPausedKey).Result()
ttl := 3 * constants.PollingIngestMonitorInterval
switch {
case depth > pauseDepth:
redisClient.Set(ctx, constants.RedisPollingIngestPausedKey, depth, ttl)
if paused == 0 {
r.logger.Error("入库积压超过反压阈值,暂停派发新卡任务", zap.Int64("ingest_backlog", depth), zap.Int64("pause_depth", pauseDepth))
}
case paused > 0 && depth > pauseDepth/2:
redisClient.Expire(ctx, constants.RedisPollingIngestPausedKey, ttl)
case paused > 0:
redisClient.Del(ctx, constants.RedisPollingIngestPausedKey)
r.logger.Info("入库积压已降到反压阈值一半以下,恢复派发卡任务", zap.Int64("ingest_backlog", depth), zap.Int64("pause_depth", pauseDepth))
}
}
// shutdown 先停入库消费者(处理中的消息在宽限期内完成),再停采集记录消费者,最后停止攒批循环(写完已缓冲的一批)。
func (r *pollingIngestRuntime) shutdown() {
if r == nil {
return
}
r.ingest.StopAll(r.grace)
r.collection.StopAll(r.grace)
r.stopCollect()
}

View File

@@ -36,15 +36,15 @@ services:
- "3000:3000"
environment:
# 数据库配置(必填)
- JUNHONG_DATABASE_HOST=cxd.whcxd.cn
- JUNHONG_DATABASE_PORT=16159
- JUNHONG_DATABASE_HOST=kt.whcxd.cn
- JUNHONG_DATABASE_PORT=15434
- JUNHONG_DATABASE_USER=erp_pgsql
- JUNHONG_DATABASE_PASSWORD=erp_2025
- JUNHONG_DATABASE_DBNAME=junhong_cmp_test
- JUNHONG_DATABASE_SSLMODE=disable
# Redis 配置(必填)
- JUNHONG_REDIS_ADDRESS=cxd.whcxd.cn
- JUNHONG_REDIS_PORT=16299
- JUNHONG_REDIS_ADDRESS=kt.whcxd.cn
- JUNHONG_REDIS_PORT=16380
- JUNHONG_REDIS_PASSWORD=cpNbWtAaqgo1YJmbMp3h
- JUNHONG_REDIS_DB=6
# JWT 配置(必填)
@@ -54,6 +54,9 @@ services:
# 日志配置
- JUNHONG_LOGGING_LEVEL=info
- JUNHONG_LOGGING_DEVELOPMENT=false
# 应用日志轮换:单文件 100MB(默认),保留 40 个压缩备份,api 与 worker 合计约 1GB
- JUNHONG_LOGGING_APP_LOG_MAX_BACKUPS=40
- JUNHONG_LOGGING_APP_LOG_MAX_AGE=14
# 跨域配置
- JUNHONG_MIDDLEWARE_CORS_ENABLED=true
- JUNHONG_MIDDLEWARE_CORS_ALLOW_ORIGINS=*
@@ -88,7 +91,7 @@ services:
- JUNHONG_MIDDLEWARE_CORS_ALLOW_ORIGINS=https://cmp-admin.boss160.cn,https://cmp-agent.boss160.cn,https://cmp-c.boss160.cn
- JUNHONG_MIDDLEWARE_CORS_ALLOW_CREDENTIALS=true
volumes:
- ./logs:/app/logs
- ./api/logs:/app/logs
networks:
- junhong-network
healthcheck:
@@ -109,19 +112,24 @@ services:
restart: unless-stopped
environment:
# 数据库配置(必填)
- JUNHONG_DATABASE_HOST=cxd.whcxd.cn
- JUNHONG_DATABASE_PORT=16159
- JUNHONG_DATABASE_HOST=kt.whcxd.cn
- JUNHONG_DATABASE_PORT=15434
- JUNHONG_DATABASE_USER=erp_pgsql
- JUNHONG_DATABASE_PASSWORD=erp_2025
- JUNHONG_DATABASE_DBNAME=junhong_cmp_test
- JUNHONG_DATABASE_SSLMODE=disable
# Redis 配置(必填)
- JUNHONG_REDIS_ADDRESS=cxd.whcxd.cn
- JUNHONG_REDIS_PORT=16299
- JUNHONG_REDIS_ADDRESS=kt.whcxd.cn
- JUNHONG_REDIS_PORT=16380
- JUNHONG_REDIS_PASSWORD=cpNbWtAaqgo1YJmbMp3h
- JUNHONG_REDIS_DB=6
# worker 并发轮询与按账户并行分发共用连接池,默认 10 不够
- JUNHONG_REDIS_POOL_SIZE=100
# 任务并发:默认 10 时流量扣减事件投递跟不上(白天积压 1 万+、延迟 2.5 小时),调到 50
- JUNHONG_QUEUE_CONCURRENCY=50
# 数据库连接池随任务并发放大(默认 25/10);测试库 max_connections=200,API 另占 25
- JUNHONG_DATABASE_MAX_OPEN_CONNS=60
- JUNHONG_DATABASE_MAX_IDLE_CONNS=20
# JWT 配置(必填)
- JUNHONG_JWT_SECRET_KEY=dev-secret-key-for-testing-only-32chars!
# 客户端配置(可选,默认 true;false=不强制绑定手机号)
@@ -129,6 +137,9 @@ services:
# 日志配置
- JUNHONG_LOGGING_LEVEL=info
- JUNHONG_LOGGING_DEVELOPMENT=false
# 应用日志轮换:单文件 100MB(默认),保留 40 个压缩备份,api 与 worker 合计约 1GB
- JUNHONG_LOGGING_APP_LOG_MAX_BACKUPS=40
- JUNHONG_LOGGING_APP_LOG_MAX_AGE=14
# 对象存储配置
- JUNHONG_STORAGE_PROVIDER=s3
- JUNHONG_STORAGE_S3_ENDPOINT=https://obs-helf.cucloud.cn
@@ -156,7 +167,9 @@ services:
- JUNHONG_POLLING_CARRIER_NSQD_ADDRESS=${JUNHONG_POLLING_CARRIER_NSQD_ADDRESS:-nsqd:4150}
- JUNHONG_POLLING_CARRIER_NSQLOOKUPD_ADDRESSES=${JUNHONG_POLLING_CARRIER_NSQLOOKUPD_ADDRESSES:-nsqlookupd:4161}
volumes:
- ./logs:/app/logs
- ./worker/logs:/app/logs
# 采集记录到期归档压缩包(archive/traffic-collection),由同步服务器拉走
- ./worker/archive:/app/archive
networks:
- junhong-network
depends_on:
@@ -188,7 +201,7 @@ services:
image: nsqio/nsq:v1.3.0
container_name: junhong-cmp-nsqd
restart: unless-stopped
command: /nsqd --lookupd-tcp-address=nsqlookupd:4160 --broadcast-address=nsqd --data-path=/data --mem-queue-size=10000 --max-msg-timeout=15m
command: /nsqd --lookupd-tcp-address=nsqlookupd:4160 --broadcast-address=nsqd --data-path=/data --mem-queue-size=0 --max-msg-timeout=15m
volumes:
- ./nsq-data:/data
networks:

View File

@@ -0,0 +1,440 @@
# 审计日志写入改造技术方案
> 日期:2026-11-05
> 状态:方案已定,未实施(结论见第 10 节)
> 关联:`openspec/changes/add-audit-integration-write-switches`(全局写入开关,本方案是其后的"按动作分级")
> **范围:本方案基于 `Iteration/8-11` 迭代实施,只部署到测试环境**(推送 8-11 由 `.gitea/workflows/deploy.yaml` 自动部署)。本方案不修改生产环境的代码、配置或服务;第 1 节的生产数据只用来说明问题和估算效果。
## 1. 背景
### 1.1 现状数据(生产近 14 天,只读统计)
| 指标 | 数值 |
|---|---|
| `tb_audit_event` 日均新增 | 约 122 万条(含停机重试风暴);扣掉风暴约 20 万条 |
| 机器发起(`system_task` / `scheduled_job`)占比 | 99% 以上 |
| 人、开放接口、个人客户、外部系统发起 | 约 1,210 条/天 |
| 每条事件含索引 | 约 1.9 KB;每条资源快照约 1.2 KB;平均 2–3 条资源 |
| 日均新增存储 | 约 6 GB(风暴期)/ 约 1 GB(平时) |
| 索引数 | `tb_audit_event` 14 个、`tb_audit_event_resource` 7 个、`tb_integration_log` 13 个 |
测试环境日均约 12.6 万条,几乎全是系统任务:流量同步 5.6 万、扣减 2.6 万、网络状态同步 2.5 万、优先轮询约 1.4 万。
### 1.2 问题
1. **审计表被当成过程日志用。** 每次轮询同步、每次扣减、每次对接调用开始、每次失败重试都写一条事件加 2–3 条资源快照。一次业务动作产生多次写入,而且每次写入要维护 21 个索引。
2. **失败重试没有收敛。** 退款后处理停机失败(`refund.process_asset`)和自动停机失败(`iot_card.auto_stop`),每重试一次就写一条审计。11-05 10:16–11:47,86 张卡产生了 26.1 万次停机失败,一个风暴就占了当天审计量的六成以上。
3. **对接日志顺带写审计。** `integrationlog.Repository.Start` 在没有上游审计事件时,会补写一条 `integration.attempt_started`(`internal/infrastructure/integrationlog/repository.go:119`),这一项每天约 45.6 万条。它与 `tb_integration_log` 本身完全重复。
4. **后果。** 11-03 生产 PostgreSQL IO 打满,轮询停摆约 1.7 天,审计和对接日志的写入与留存扫描是主要 IO 来源之一。
### 1.3 老系统做法(`/home/zoujin/works/golang/kg/qc`,供参考)
- **人工后台操作**:写 `tbl_system_log`。
- **业务过程**:按业务各写一张表,如 `tbl_order_log`、`tbl_card_wallet_auto_renew_log`、`tbl_next_month_log`,以及充值、短信日志。
- **下游代理调用我方接口**:只这一类写 `tbl_agent_pool_api_call_log`。
- **网关调用和轮询**:全部写 log4j 按天滚动的文本日志,不进数据库。
## 2. 目标与原则
**目标**:审计表只回答两个问题:
1. **人(或代表人的外部系统)做了什么**;
2. **钱和套餐、卡的业务状态是怎么变的**。
审计日均降到几千条,一年不到 10 GB,不再依赖归档和清理来扛量。
**原则**:
| 原则 | 说明 |
|---|---|
| 人工操作全留 | 后台账号、个人客户、开放接口、外部系统发起的动作,成功和失败都写审计 |
| 机器动作只留"结果" | 系统任务和定时任务只在资金或业务状态**真正改变**时写审计;无变化、同步、读取不写 |
| 每次失败都可查,审计只记结论 | 自动重试的每一次尝试都完整记在业务尝试记录表里(时间、第几次、错误码、上游返回),可分页查询;审计只记这件事的最终结论:成功,或重试用尽转人工 |
| 过程数据去业务表 | 已有专门记录表的(停复机记录、采集记录、扣减效果、日流量),审计不再重复写 |
| 排查用的走文本日志 | 只用于排查、不需要按业务查询的,写入现有应用日志 `app.log`,沿用现有轮换,由日志同步服务器归集 |
| 不改变业务结果 | 写不写审计,都不影响业务事务成功与否(与现状 `Append` 吞错一致) |
## 3. 数据分层
| 层 | 存储 | 放什么 | 保留 |
|---|---|---|---|
| L1 审计 | `tb_audit_event` + `tb_audit_event_resource` | 人工操作;机器发起的资金、套餐生命周期、停复机成功等状态变化 | 按现有留存策略 |
| L2 业务记录 | 各业务专表 | 停复机调用 `tb_card_stop_resume_record`、流量采集 `tb_card_traffic_collection`、扣减效果与日流量、对接调用 `tb_integration_log`、退款单上的后处理状态 | 按各表策略 |
| L3 文本日志 | 现有应用日志 `app.log`(zap JSON + lumberjack 轮换) | 机器过程类动作的结构化日志,例如停机原因更新、网络状态同步、通知投递、优先轮询、流量重置明细 | 沿用 `logging.app_log` 轮换;长期留存由日志同步服务器负责 |
| L4 不写 | — | 与 L1/L2 完全重复的,例如 `integration.attempt_started` | — |
## 4. 动作去向清单
### 4.1 保留在审计(L1)
**人工及外部发起**(约 1,210 条/天,全部保留):
| 发起方 | 日均 | 主要动作 |
|---|---|---|
| 后台账号 | 约 404 | 手动刷新卡、设备切卡、回收、设 WiFi、手动复机、改套餐到期、设备重启、下单、退款、审批、登录等 |
| 开放接口 | 约 612 | 下单、代理钱包扣款、开放接口复机 |
| 个人客户 | 约 182 | 绑资产、建手机号关联、更新微信身份、绑手机号 |
| 外部系统 | 约 9 | 支付确认、外部回调接收 |
**机器发起但改变资金或业务状态**(方案 A 约 3,510 条/天):
| 动作 | 日均 | 方案 B 去向 |
|---|---|---|
| `iot_card.auto_start` 自动复机 | 1,127 | 移到 L2 停复机记录 |
| `package_usage.reset_traffic` 流量重置 | 1,049 | 移到 L2(套餐自身的重置时间加日流量记录) |
| `iot_card.auto_stop` 自动停机,**仅成功** | 380 | 移到 L2 停复机记录 |
| `commission.calculate` 分佣计算 | 238 | 保留 |
| `package_usage.expire` / `activate` / 退款失效 | 176 / 90 / 6 | 保留 |
| 导入建卡、建设备、设备分配 | 93 / 52 / 44 | 保留 |
| 系统下单、订单套餐失效明细、员工代收账单 | 77 / 74 / 51 | 保留 |
| 外部回调接收、审批同步、退款批准、佣金回溯判定 | 27 / 13 / 6 / 6 | 保留 |
| `refund.process_asset`,**仅成功** | 4 | 保留 |
### 4.2 移出审计
| 动作 | 现在日均(估算) | 去向 | 说明 |
|---|---|---|---|
| `integration.attempt_started` | 约 45.6 万 | L4 不写 | `tb_integration_log` 已有同样内容;`audit_event_id` 留空 |
| `refund.process_asset` 失败 | 约 32.6 万 | L2 退款后处理尝试记录 | 每次尝试一条,记在新表 `tb_refund_post_process_attempt`;退款单上保留当前状态、次数和最后错误;审计只在最终成功或转人工时写一条 |
| `iot_card.auto_stop` 失败 | 约 31.5 万 | L2 停复机记录 | `tb_card_stop_resume_record` 每次实际调用一条,已含错误分类 |
| `iot_card.auto_stop_reason_update` | 约 3.8 万 | L3 文本 | 只改停机原因、不改停复机状态 |
| `iot_card.worker_traffic_sync` | 约 3.1 万(正常时 6–8 万) | L2 采集记录 | `tb_card_traffic_collection` 已经记录每次采集 |
| `iot_card.worker_network_sync` | 约 2.6 万(正常时 6–8 万) | L3 文本 | 结果就是卡上的网络状态字段 |
| `package_usage.deduct_traffic` | 约 2.1 万 | L2 | 采集记录、扣减效果、日流量三张表已经能还原 |
| `notification.deliver`、`polling_priority.*` 等 | 约 0.5 万 | L3 文本 | — |
### 4.3 方案选择
采用**方案 B**。停复机和流量重置都已经有更合适的业务表,审计里只留人工操作和资金、套餐生命周期类动作。
| 方案 | 审计事件/天 | 占现在 | 每天新增存储 |
|---|---|---|---|
| 现在 | 约 122 万 | 100% | 约 6 GB |
| 方案 A:4.1 全留 | 约 4,700 | 0.39% | 约 24 MB |
| **方案 B**:停复机、流量重置移到 L2 | 约 **2,200** | 0.18% | 约 11 MB |
## 5. 技术设计
### 5.1 注册表增加"落库策略"
`internal/infrastructure/audit/registry.go` 的 `ActionDefinition` 新增字段:
```go
// PersistPolicy 决定动作是否写入审计表。
type PersistPolicy string
const (
PersistAlways PersistPolicy = "always" // 成功失败都写(人工动作默认)
PersistOnSuccess PersistPolicy = "on_success" // 只写成功;失败写文本日志
PersistOutcome PersistPolicy = "outcome" // 只写最终结论:成功、或重试用尽转人工;中间失败不写审计(每次尝试在业务尝试记录表)
PersistLogOnly PersistPolicy = "log_only" // 不写表,写 L3 文本日志
PersistNone PersistPolicy = "none" // 什么都不写
)
type ActionDefinition struct {
// ……现有字段
Persist PersistPolicy // 为空时按操作者决定,见 5.2
}
```
动作的策略在注册表中**集中定义**,调用方不改代码。这样一份清单就能看清哪些动作进审计,评审和后续调整也只需改这一处。
### 5.2 默认规则
`Persist` 为空时,按本次写入的操作者类型决定:
| 操作者 `actor_kind` | 默认策略 |
|---|---|
| `account`、`personal_customer`、`openapi`、`external_system` | `always` |
| `system_task`、`scheduled_job` | `log_only` |
因此新增机器动作**默认不进审计**,要进审计必须在注册表显式声明 `always`、`on_success` 或 `outcome`。这能防止后面新增的轮询、同步类动作再次把审计表写满。
同一动作可能同时由人和机器触发,例如 `order.create`、`iot_card.manual_start` 与开放接口复机。策略按"动作 + 操作者"判断:注册表里的 `Persist` 只约束机器操作者,人工操作者始终是 `always`。
### 5.3 Writer 改造
只改 `internal/infrastructure/audit/writer.go` 的 `AppendAndGet`,在注册校验通过后、组装事件前分流:
```go
action, ok := w.registry.Action(input.ActionCode)
// ……现有校验
switch w.persistDecision(ctx, tx, action, input) {
case decisionSkip:
return nil, nil
case decisionLog:
w.machineLog.Info("audit", auditLogFields(action, input)...)
return nil, nil
}
// ……现有写表逻辑
```
要点:
1. **调用方兼容**:`Append` 本来就吞错并返回 nil,调用方不受影响。`AppendAndGet` 有 11 处调用(`refund/clawback.go`、`refund/service.go`、`businessusergroup`、`packagetrafficalert`、`distribution`、`refund_channel`、`integrationlog`),实施时逐一确认能处理返回的 `nil` 事件。这 11 处大多是人工或资金动作,仍然是 `always`,实际不会拿到 nil。
2. **`outcome` 的判定**:由调用方在写审计时标明这次是不是最终结论,`AppendInput` 增加 `Final bool`。
- 中间失败(`Final=false`)不写审计表,只写一行应用日志,日志里带尝试记录 ID 方便对照;
- 最终成功,或重试用尽转人工(`Final=true`)写一条审计,`metadata` 带总尝试次数、首次失败时间、最后错误码;
- 用业务键作 `EventID`(例如 `refund-asset:{refund_id}:outcome`),保证同一件事的结论只有一条。
- **每一次尝试的细节都不丢**,都在业务尝试记录表里(见 5.5),可分页查询(见 5.9)。
3. **文本日志写入现有应用日志**:不新建日志文件,也不新增轮换配置。Writer 直接使用 `logger.GetAppLogger().Named("audit")`,写入现有的 `app.log`,轮换沿用 `logging.app_log`(测试环境配置见 5.8),由日志同步服务器自动归集。`NewWriter` 签名不变,调用方不用改。
- 每行固定 `"logger":"audit"`、`"msg":"audit_event"`,便于在同步端按 logger 名过滤和建索引;
- 字段:`action_code`、`actor_kind`、`actor_id`、`source`、`result`、`resource_type`、`resource_key`、`correlation_id`、`request_id`、`error_code`、`summary`;中间失败额外带 `attempt`(第几次)和尝试记录 ID;
- 级别:成功为 Info,失败为 Warn;
- **不写** before/after 快照与主体数据,避免敏感数据进入文本日志;需要变化值的动作(如流量重置前后用量)只写必要的数值字段。
4. **运行时覆盖**:在 `add-audit-integration-write-switches` 的全局开关之外,增加一个按动作覆盖的配置 `audit.persist_overrides`(动作编码 → 策略)。出问题时不发版就能把某个动作临时降为 `log_only`,或恢复为 `always`。
### 5.4 对接日志不再补写审计
`internal/infrastructure/integrationlog/repository.go` 的 `Start`:
- **删除** `input.AuditEventID == nil` 时补写 `integration.attempt_started` 的逻辑(第 118–120 行)。上游有审计事件时照常关联;没有时 `audit_event_id` 留空。
- 注册表里的 `integration.attempt_started` 设为 `none`,作为兜底。
- `auditEventIDForSeries` 按 `trigger_series` 回查审计的逻辑保留,但需要确认它不会走慢查询(它会查审计表)。
### 5.5 失败重试收敛(与停机风暴止血配套)
审计只记结论之后,排查问题靠的是每一次尝试的记录,同时重试本身要收敛。这两件可以单独开 Change,但**必须先于或同时上线**:
1. **退款后处理**(`internal/service/refund/approval_decision.go` 的 `ProcessAssetPostProcessing`,`stopAsset` → `ManualStopCard`):
- 退款单增加或复用后处理字段:`asset_post_status`、`asset_post_attempts`、`asset_post_last_error`、`asset_post_next_at`,表示当前状态;
- **新增尝试记录表** `tb_refund_post_process_attempt`,每次尝试一条,不修改、不删除。字段:`refund_id`、`step`(停机、套餐失效、钱包回收等)、`asset_type`、`asset_id`、`iccid`、`attempt`、`trigger`(outbox 投递、补偿扫描、人工重试)、`result`、`error_code`、`error_message`、`stop_resume_record_id`(关联到那次停机调用)、`duration_ms`、`created_at`。按月分区。每单最多 10 次,量可控;
- 失败按指数退避,超过 N 次(建议 10 次)标记为"需人工处理",不再自动重试;
- outbox 与 `RecoverRefundPostProcessing` 都按这几个字段判断,不再无限重投。
2. **自动停机**:8-11 上的停机已经走停复机指令队列(`stop-resume-command-queue`),按错误分类处理:终态不可操作不重试,限流按退避处理。退款停机只请求停机评估。本次不改这部分。
- 每次实际调用上游,已经在 `tb_card_stop_resume_record` 记一条,包括第几次、错误类别、上游返回码与信息、耗时。
- 指令在调用上游前就结束的情况(已是目标状态、条件不再满足、卡不允许停复机)现在没有记录。改为在停复机记录里写 `result=skipped`,并写明原因,保证"为什么没停"也能查到。限流推迟后还会再执行,不写记录,沿用现有的分钟计数。
### 5.6 方案 B 的业务表补位
| 移出的动作 | 补位方式 | 现状 |
|---|---|---|
| `iot_card.auto_start` / `auto_stop` 成功 | `tb_card_stop_resume_record`(每次实际调用一条,含来源、场景、原因、结果) | Iteration/8-11 已有 |
| `package_usage.reset_traffic` | 套餐使用记录的 `last_reset_at` / `next_reset_at` 加日流量记录 | 已有;重置前后用量写一行 `app.log`(`logger=audit`)备查 |
| `iot_card.auto_start` / `auto_stop` 的停机原因、触发场景 | `tb_card_stop_resume_record` 的 `source`、`scene`、`reason` | 已有;原审计里的 before/after 卡状态不再保留,卡当前状态以卡表为准 |
后台"卡操作记录"之类的页面如果要看到停复机时间线,查询侧改为合并审计和停复机记录两个来源,不要回头再写审计。
### 5.7 审计覆盖治理
`internal/governance/auditcoverage/scanner.go` 扫描每个入口的 `AuditEvent`、`DomainLedger`、`IntegrationLog` 分类。本次需要做三件事:
- 对移到 L2、L3、L4 的入口,把 `AuditEvent` 分类改为不写,并在 `DomainLedger` 里写明对应的业务表;
- 覆盖扫描增加一条校验:机器操作者的动作必须在注册表显式声明 `Persist`,否则扫描失败;
- 同步更新 `openspec/specs/operations-audit` 和 `external-integration` 中"每个入口都写审计"的要求。
### 5.8 应用日志增量与轮换(测试环境)
测试环境由 `docker-compose.prod.yml` 部署,api、worker 两个容器的现状:
- 日志级别是 `LEVEL=info`、`DEVELOPMENT=false`,即 JSON 格式,可以按 `"logger":"audit"` 过滤;
- 两个容器都把宿主机 `./logs` 挂载到 `/app/logs`,且都**没有设置** `JUNHONG_LOGGING_APP_LOG_FILENAME`,所以都使用默认的 `/app/logs/app.log`;
- 轮换参数也是默认值:100 MB 一个文件、3 个备份、7 天、压缩。
**问题**:api 和 worker 写的是宿主机上**同一个** `/opt/junhong_cmp/logs/app.log`。两个进程各自用 lumberjack 按大小轮换,会互相把对方正在写的文件改名、压缩,导致丢日志和备份错乱。这个问题与审计改造无关,但 L3 日志要落在 `app.log` 里,所以要一并修。
**调整原则**:每个服务写在自己运行目录下的 `logs/`。审计日志不新增路径、不改文件名,跟着所在进程的应用日志走。测试环境的问题只在于两个容器共用了同一个宿主机目录,所以只改挂载:
| 服务 | 挂载(宿主机 → 容器) | 宿主机日志位置 |
|---|---|---|
| api | `./api/logs:/app/logs` | `/opt/junhong_cmp/api/logs/app.log`、`access.log` |
| worker | `./worker/logs:/app/logs` | `/opt/junhong_cmp/worker/logs/app.log` |
- 容器内仍然是默认的 `/app/logs/app.log`,**不设置** `APP_LOG_FILENAME`;目录结构与生产 `/opt/junhong_cmp/api/logs`、`/opt/junhong_cmp/worker/logs` 一致;
- 轮换只加两项:`JUNHONG_LOGGING_APP_LOG_MAX_BACKUPS=40`、`JUNHONG_LOGGING_APP_LOG_MAX_AGE=14`,其余用默认值(100 MB、压缩);
- 容量:两个进程合计约 1 GB,每个进程是 100 MB 当前文件加 40 个压缩备份。每个备份约 10 MB 是估算值,部署后按实际备份大小微调;
- `.gitea/workflows/deploy.yaml` 里 `mkdir -p ${DEPLOY_DIR}/logs` 改为创建 `api/logs`、`worker/logs`;
- 原来的 `/opt/junhong_cmp/logs` 不再写入,旧文件保留不动。
- **新增量**:方案 B 在测试环境移到 L3 的动作,每天约 8 万–10 万行:流量同步改由采集记录承担,不写日志;需要写日志的有网络状态同步约 2.5 万、优先轮询约 1.4 万、停机原因更新与通知若干。按每行约 400 B 计算,每天约 30–40 MB(压缩前),相对单文件 100 MB 没有压力。
文本日志是排查补充。丢几行不影响业务,也不影响审计表。写日志失败时不重试、不报错。
### 5.9 记录查询接口
审计里移出去的数据,要能在后台查得到,否则等于丢了。凡是独立成表的记录,都要提供**分页 + 条件筛选**的查询接口。L3 文本日志不提供接口,由日志同步服务器检索。
**公共约定**(与现有 `ListStopResumeRecords` 一致):
| 项 | 约定 |
|---|---|
| 分页 | `page` 默认 1;`page_size` 默认 20,最大 100(采集记录沿用现有的最大 200);返回 `total`、`page`、`page_size`、`items` |
| 时间范围 | `start_time`、`end_time` 必填,跨度不超过 31 天,按上海时间解析;单卡接口为空时默认取最近 31 天 |
| 卡标识 | `identifier` 支持虚拟号、ICCID、MSISDN,先解析成卡 ID 再查,保证走"卡 ID + 时间"索引;找不到卡时直接返回空页 |
| 排序 | 按记录时间倒序,同一时间按 ID 倒序 |
| 单个与全部 | 每类记录提供一个列表接口,`identifier` 选填:传了就查单卡或单资产,不传就查全部。现有的单卡接口保留给前端兼容,与列表接口共用同一个查询 |
| 筛选 | 按业务排查需要来定,下面逐表列出,不受现有索引限制;为这些筛选新建或重建索引 |
| 时间范围的作用 | 表按月分区,时间范围用于分区裁剪,所以查全部时也只带时间范围、不要求其他条件 |
| 权限 | 平台账号;代理和企业账号是否开放、按归属范围过滤,另行确定 |
**接口清单**:
| 记录 | 表 | 列表接口 | 筛选条件 | 现状 |
|---|---|---|---|---|
| 运营商流量采集记录(成功,失败见 5.10) | `tb_card_traffic_collection` | `GET /traffic-collections` | `identifier`、`carrier_id`(运营商账户)、`decision`(扣减判定)、`source`、`scene`、`has_delta`(是否产生增量)、`stale_guarded` | 只有单卡接口 `GET /assets/:identifier/traffic-collections`,只能按时间分页 |
| 停复机记录 | `tb_card_stop_resume_record` | `GET /card-stop-resume-records` | `identifier`、`carrier_id`、`action`、`source`、`scene`、`reason`、`result`、`error_category`、`command_id` | 已有跨卡接口,但只能用 ICCID 查卡,也不能按场景、原因、指令号筛选;单卡接口没有筛选 |
| 套餐日流量详单 | `tb_package_usage_daily_record` | `GET /package-usage-daily-records` | `identifier`、`package_usage_id`、`package_id`、`carrier_id`、日期范围 | 只有单套餐接口 `GET /package-usages/:id/daily-records`,不分页 |
| 卡日流量 | `tb_card_daily_usage` | `GET /card-daily-usages` | `identifier`、`carrier_id`、日期范围、`min_usage_mb`(用量下限,排查异常大流量) | 无接口 |
| 套餐流量冲正流水 | `tb_package_usage_adjustment` | `GET /package-traffic-adjustments` | `identifier`、`package_usage_id`、操作人、调整方向(补扣或退回)、时间范围 | 只有单套餐接口,没有时间筛选 |
| 对接日志 | `tb_integration_log` | 现有 `GET /audit/integrations` | 现有条件已覆盖 | 不改 |
| 退款后处理尝试记录 | `tb_refund_post_process_attempt`(见 5.5) | `GET /refund-post-process-attempts` | `refund_id`、退款单号、`identifier`、`step`、`result`、`error_code`、`trigger`、时间范围 | 新增。退款列表同时增加 `asset_post_status` 筛选(可查"需人工处理"),列表和详情返回后处理次数、最后错误、下次重试时间 |
**索引**:按上面的筛选设计,需要时新建或重建。分区表的索引建在父表上,会自动应用到各个分区。
| 表 | 索引 |
|---|---|
| `tb_card_traffic_collection` | 保留 `(iot_card_id, observed_at DESC)`;新增冗余列 `carrier_id`,采集时写入;新增 `(observed_at DESC)`、`(carrier_id, observed_at DESC)`、`(decision, observed_at DESC)`;失败表索引见 5.10 |
| `tb_card_stop_resume_record` | 现有 `(card_id, created_at)`、`(carrier_id, created_at)`、`(result, created_at)` 重建为倒序;新增 `(created_at DESC)`、`(scene, created_at DESC)`、`(command_id)` |
| `tb_card_daily_usage` | 现有唯一键 `(iot_card_id, date)`;新增 `(date, usage_mb DESC)`,支撑查全部和按用量下限筛选 |
| `tb_package_usage_daily_record` | 新增 `(package_usage_id, date DESC)`、`(date)` |
| `tb_package_usage_adjustment` | 新增 `(iot_card_id, created_at DESC)`、`(created_at DESC)` |
| `tb_refund_post_process_attempt` | `(refund_id, created_at DESC)`、`(created_at DESC)`、`(result, created_at DESC)`、`(error_code, created_at DESC)` |
其余低选择性的条件,如 `source`、`stale_guarded`、调整方向,和上面的索引组合使用即可,不单独建索引。上线后在测试环境看慢查询日志,按实际情况调整。
**说明**:
- **流量扣减结果**直接从采集记录查:每条采集记录都带 `decision`、`delta_mb`、`month_used_mb`、`event_id`,再结合日流量详单,能还原每次扣了多少。
- **扣减效果表** `tb_card_observation_effect` 不对外提供接口。它只保存 outbox 事件的处理进度,没有卡 ID。排查扣减卡住时,在采集记录里按 `event_id` 关联查。
- 新增接口都要在路由 `RouteSpec` 中声明输入、输出 DTO,并同步生成接口文档。
### 5.10 流量采集记录成功与失败分表
**现状**(测试库近 3 天,只读统计):
| 读数结果 | 扣减判定 | 条数 | 平均行大小 |
|---|---|---|---|
| `ok` | `written`(写入增量) | 104.2 万 | 432 B |
| `ok` | `queue_not_full`(队列未满,暂不判断) | 17.3 万 | 285 B |
| `ok` | `slope_negative`、`baseline`、`settled_existing` | 800 | 约 420 B |
| `failed` | — | 14.5 万 | 136 B |
| `no_reading` | — | 400 | 144 B |
- 成功和失败写在同一张 `tb_card_traffic_collection` 里,失败约占 11%,测试环境每天约 4.8 万条。
- 失败记录只存了失败类型。`polling_carddata_handler` 在调用 `recordUnreadable` 时**丢掉了具体错误**,查不到失败原因,只能再去对接日志里按 `observation_id` 找。
- 失败记录也只给"采集时刻有套餐"的卡写,为此每条失败都要额外查一次有效套餐。
**调整**:
| 表 | 写什么 | 保留 |
|---|---|---|
| `tb_card_traffic_collection`(现有) | 只写成功读数(`result=ok`),包括所有扣减判定;新增原始请求与响应字段 | 在线保留 2 个月,到期月分区导出为压缩包后删除(见下文"到期归档") |
| `tb_card_traffic_collection_failure`(新增) | 只写失败:`failed`、`rate_limited`、`invalid_payload`、`no_reading`、`invalid_reading`;带原始请求与响应 | 与成功表相同:在线 2 个月,到期归档后删除 |
失败表字段:`iot_card_id`、`iccid`、`carrier_id`、`observed_at`、`observation_id`(等于对接日志的 `integration_id`,可直接关联)、`source`、`scene`、`result`(失败类型)、`error_category`(按网关错误分类:超时、限流、上游报错、响应格式错等)、`provider_code`、`provider_message`(截断到 500 字)、`duration_ms`、`created_at`,加上下面的原始数据字段。按 `observed_at` 按月分区,只新增不修改。
**原始数据**:成功表和失败表都保存运营商网关的原始请求与原始响应,有据可查。
| 字段 | 内容 |
|---|---|
| `raw_request` | 加密前的业务请求体(明文 JSON,只有卡号等查询参数),jsonb |
| `http_status` | HTTP 状态码;没拿到响应(超时、连接失败)时为空 |
| `gateway_code`、`gateway_msg`、`gateway_trace_id` | 网关响应外层的 `code`、`msg`、`trace_id` |
| `raw_response` | 网关原始响应体,原样保存。能解析成 JSON 的存 jsonb,不能解析的按文本存在 `raw_response_text`。超过 4 KB 时截断,并标记 `raw_truncated=true` |
| `gateway_attempts` | 网关客户端内部重试次数;保存的是最后一次的请求和响应 |
- **获取方式**:网关客户端(`internal/gateway/client.go` 的 `executeWithRetry`)已经读到了完整响应体和外层的 `code`、`msg`、`trace_id`,但只返回 `data`。新增按请求上下文挂载的原始数据收集器 `gateway.WithRawCapture(ctx)`,调用方挂上后,客户端把最后一次的请求体、状态码、响应体和重试次数写进收集器。没挂收集器的调用不受影响。
- **写入**:`polling_carddata_handler` 调 `QueryFlow` 前挂上收集器,成功读数和各类失败都把收集器内容带进 `TrafficObservation`,写入对应的表。
- **安全**:只存明文业务请求体,不存加密后的报文、签名、`app_id`、密钥和请求头。
- **量的估算**:流量查询响应很小(`iccid`、`used`、`unit` 加外层字段,约 150–250 B),每行增加约 300–400 B。测试环境成功读数每天约 40 万条,每天增加约 120–160 MB;在线保留 2 个月,原始数据部分约 7–10 GB。失败每天约 4.8 万条,2 个月约 1 GB。部署后按实际行大小复核。
**到期归档**:
- **在线保留**:当月加上最近 2 个整月。月分区的月末早于"当前时间减 2 个月"时,判定为到期。例如 2027-01-01 起,2026-10 的分区到期。常量 `TrafficCollectionRetentionDays=90` 改为 `TrafficCollectionRetentionMonths=2`,成功表和失败表共用。
- **执行位置**:沿用 leader worker 现有的分区维护循环 `startTrafficCollectionPartitionMaintainer`,每 12 小时运行一次。原来"到期直接 `DROP TABLE`"的逻辑,改为下面的四步:
1. **摘出分区**:`ALTER TABLE ... DETACH PARTITION`,到期分区不再参与在线查询。
2. **导出压缩包**:用 `COPY (SELECT * FROM 分区 ORDER BY observed_at, id) TO STDOUT WITH (FORMAT csv, HEADER)` 流式读出,边读边 gzip 写到 worker 运行目录下的 `archive/traffic-collection/` 目录,不在内存里攒整个月的数据。文件名为 `tb_card_traffic_collection_202610.csv.gz` 或 `tb_card_traffic_collection_failure_202610.csv.gz`。原始请求与响应以 JSON 文本形式保存在 CSV 列里。
3. **校验**:写完后重新读一遍压缩包,统计行数并与分区 `count(*)` 比对;同时生成同名的 `.manifest.json`,记录表名、月份、行数、最早和最晚采集时间、文件大小、SHA-256 和导出时间。
4. **删除分区**:行数一致后才 `DROP TABLE` 已摘出的分区。导出或校验失败时保留已摘出的表,记 Error 日志,下一轮重试;不会出现"数据删了但没有压缩包"的情况。
- **文件同步**:压缩包和 manifest 由你们的同步服务器拉走。本地只保留最近 3 个月的压缩包,更早的自动删除,个数可配置。先写成 `.tmp`,校验通过后再改名为正式文件名,避免同步到写了一半的文件。
- **测试环境挂载**:worker 容器增加 `./worker/archive:/app/archive`,宿主机目录为 `/opt/junhong_cmp/worker/archive/traffic-collection/`。
- **压缩包大小估算**:测试环境成功表每月约 1,200 万行,CSV 约 8–10 GB,gzip 后约 1–1.5 GB;失败表每月约 150 万行,压缩后约 50 MB。
- **回查**:要查归档月份的数据,解压后用 CSV 工具查看,或者临时 `COPY FROM` 导回一张临时表。线上接口只查在线的 2 个月。
**写入规则**:
- 失败记录**不再判断是否有套餐**,所有轮询到的卡都写,省掉每条失败的有效套餐查询。运营商接口出问题和有没有套餐无关,排查时需要看全量。
- `TrafficObservation` 增加失败详情(错误类别、上游返回码与信息、耗时),由 `polling_carddata_handler` 在网关调用失败时填入,不再丢弃错误。
- 成功表仍在观测事务之外写入,规则不变;写入失败只告警,不影响扣减。
- 成功表已有的失败历史数据保留,到期随分区删除;新数据按新规则分表写入。
**查询接口**(与 5.9 公共约定一致:可查单个也可查全部,分页,时间范围必填):
| 接口 | 筛选条件 | 索引 |
|---|---|---|
| `GET /traffic-collections`(成功) | `identifier`、`carrier_id`、`decision`、`source`、`scene`、`has_delta`、`stale_guarded` | 见 5.9 |
| `GET /traffic-collection-failures`(失败) | `identifier`、`carrier_id`、`result`、`error_category`、`provider_code`、`source`、`scene` | `(iot_card_id, observed_at DESC)`、`(observed_at DESC)`、`(carrier_id, observed_at DESC)`、`(error_category, observed_at DESC)`、`(observation_id)` |
成功表不再有失败数据,所以 5.9 里成功表的 `result` 筛选和 `(result, observed_at DESC)` 索引都去掉。单卡接口 `GET /assets/:identifier/traffic-collections` 增加 `include_failures` 参数,默认不含失败;传了就把两张表合并后按时间倒序返回,方便在一张卡上连起来看。
## 6. 存量数据
- **不删除、不迁移**已有审计数据,由现有留存和归档任务按策略自然过期。
- 如果要尽快释放空间,可以另行评估"按动作编码清理机器过程类历史数据"的一次性任务。本方案不包含它。
## 7. 分支与范围
- 基于 **Iteration/8-11** 实施。该分支已有 `tb_card_stop_resume_record`、采集记录和扣减效果表,方案 B 的补位表都存在。
- **只部署测试环境**:8-11 推送后自动部署到测试环境;不在生产执行任何代码替换、配置修改或服务重启。生产什么时候、以什么方式合入,不在本方案范围内。
- 全局写入开关 `add-audit-integration-write-switches` 已在 8-11 上,本方案与它互不替代:全局开关用于应急**全停**,本方案是常态下的**按动作分级**。
## 8. 实施步骤
| 步骤 | 内容 | 涉及 |
|---|---|---|
| 1 | 注册表增加 `Persist`,补齐全部机器动作的策略,并加上 5.2 的默认规则 | `internal/infrastructure/audit/registry.go`、`pkg/constants/audit.go` |
| 2 | Writer 按策略分流:`outcome` 只写最终结论;`log_only` 写现有应用日志(`logger=audit`) | `internal/infrastructure/audit/writer.go` |
| 3 | 对接日志去掉 `attempt_started` 补写 | `internal/infrastructure/integrationlog/repository.go` |
| 4 | 退款后处理加重试上限和退避,新增尝试记录表;停机业务性失败不重投,调用前被拦截的写 `skipped` 停复机记录 | `internal/service/refund`、`internal/service/iot_card`、`migrations` |
| 5 | 增加 `audit.persist_overrides` 运行时覆盖配置 | `pkg/config` |
| 6 | 审计覆盖扫描和 OpenSpec 规格同步 | `internal/governance/auditcoverage`、`openspec/specs` |
| 7 | 查询侧:卡、设备时间线合并停复机记录(方案 B) | `internal/query/audit` |
| 8 | 测试环境 api、worker 各自挂载自己的 `logs/` 目录,轮换改为 40 个备份(见 5.8) | `docker-compose.prod.yml`、`.gitea/workflows/deploy.yaml` |
| 9 | 记录查询接口:每类记录一个列表接口,可查单个也可查全部;按 5.9 的筛选条件建立或重建索引;采集记录增加 `carrier_id` 冗余列 | `internal/routes`、`internal/handler/admin`、`internal/model/dto`、`internal/store/postgres`、`migrations` |
| 10 | 采集记录成功与失败分表:新增失败表,补全失败详情,失败不再判断有无套餐;两张表保存网关原始请求与响应(网关客户端新增原始数据收集器);提供失败查询接口(见 5.10) | `internal/gateway/client.go`、`internal/application/cardobservation`、`internal/task/polling_carddata_handler.go`、`internal/model`、`internal/store/postgres`、`migrations` |
| 11 | 采集记录到期归档:分区维护改为摘出、导出 `csv.gz`、校验、删除四步;测试环境 worker 挂载 `archive` 目录 | `internal/store/postgres/card_traffic_collection_store.go`、`cmd/worker/main.go`、`pkg/constants`、`docker-compose.prod.yml` |
建议按"1–3 → 4 → 5–11"分三次提交,每次推送 8-11 后在测试环境验证。
## 9. 测试与验证(测试环境)
**测试环境逐项验证**(项目规定自动化测试为 N/A,按 ENG-TEST-001 在测试环境验证,以下各项是验证要点):
- 每种策略在 `account`、`openapi`、`system_task` 下的写入结果;
- `outcome`:中间失败不写审计,尝试记录表每次都有一条;最终成功或转人工写一条审计,带总次数;同一件事重复写结论只保留一条;
- `log_only` 不写表、文本日志有记录且不含快照;
- 覆盖配置能把 `always` 降为 `log_only`,也能反过来恢复。
- 对接调用没有上游审计时,`tb_integration_log.audit_event_id` 为空,审计表无新增;
- 退款后处理失败超过上限后状态为"需人工处理",outbox 不再重投。
- 流量查询成功写成功表、各类失败写失败表,两张表都带原始请求与响应;失败记录有错误类别和上游返回码;无套餐的卡失败也写;
- 网关响应超过 4 KB 时截断并标记;原始请求里没有密钥、签名或加密报文;
- 到期归档:构造一个过期月分区,执行维护后生成 `csv.gz` 和 manifest,行数与 SHA-256 一致后分区被删除;模拟导出失败时,已摘出的表保留,下一轮重试成功;
- 记录查询接口:每个接口都能查单卡、也能查全部,分页总数正确,各筛选条件生效。
**测试环境观察**(部署后 24 小时):
- 审计日增从约 12.6 万降到约 300 条(只读查询走 `created_at` 索引、按小时统计);
- `app.log` 中出现 `logger=audit` 的行,轮换正常,日志同步服务器能收到并按 logger 名过滤;
- 停复机记录、扣减效果写入量没有变化,业务结果没有变化;成功表加失败表的写入量合计,与改造前采集记录的量相当(失败表多出无套餐卡的失败);
- 新接口在测试库数据量下没有慢查询;
- `/opt/junhong_cmp/worker/archive/traffic-collection/` 目录可写,同步服务器能拉到文件。第一次真实归档要等到在线数据满 2 个月之后,在此之前用单元测试和集成测试覆盖。
## 10. 已定事项(2026-11-05)
| 事项 | 结论 |
|---|---|
| 方案 | 方案 B |
| 范围 | 基于 Iteration/8-11,只部署测试环境 |
| L3 文本日志 | 写入所在服务自己运行目录下的 `logs/app.log`,沿用现有轮换,由日志同步服务器归集 |
| 测试环境日志保留 | api、worker 各自的 `logs/` 目录,各保留 40 个压缩备份,合计约 1 GB;部署后按实际备份大小微调 |
| 退款后处理重试上限 | 10 次,指数退避,最长间隔 1 小时;超过后标记"需人工处理" |
| 失败记录 | 每次尝试都记录在业务尝试记录表(退款后处理尝试、停复机记录),可分页查询;审计只记最终结论,不按首次失败去重 |
| 停机业务性失败 | 按网关错误分类判定为不可重试,不再重投 |
| 运行时覆盖 | 提供 `audit.persist_overrides`,可按动作临时调整策略 |
| 存量审计数据 | 不删除、不迁移,按现有留存策略自然过期 |
| 采集记录分表 | 成功写现有表,失败写新表 `tb_card_traffic_collection_failure`,带完整错误详情,所有卡都写;两张表都保存网关原始请求与响应 |
| 采集记录保留 | 两张表在线保留 2 个月(当月加最近 2 个整月);到期月分区先导出为 `csv.gz` 压缩包并校验,再删除;压缩包由同步服务器拉走,本地保留 3 个月 |
| 记录查询 | 所有独立成表的记录都提供分页加条件筛选接口,可查单个也可查全部;筛选条件按排查需要来定,索引随之新建或重建,清单见 5.9;文本日志不提供接口 |
| 页面依赖 | 实施第 7 步(时间线合并停复机记录)前,与前端或运营确认是否有页面依赖机器动作审计 |

View File

@@ -0,0 +1,230 @@
# 轮询入库异步化技术方案
- 日期:2026-11-06
- 分支:`Iteration/8-11`(只部署测试环境,不涉及生产配置与重启)
- 关联:`add-carrier-polling-scheduler`(按运营商账户调度)、`add-card-traffic-queue-and-observed-deduction`(采集队列与按观测扣减)、`refactor-audit-log-persistence`(采集记录分表)
## 1. 背景
### 1.1 测试环境现状(2026-11-06 上午,只读统计)
| 指标 | 数值 |
|---|---|
| worker 报 `context deadline exceeded` 的 SQL | 每分钟 90–220 次,平均约 130 次,即每小时约 8,000 次,部署审计改造前已存在 |
| 慢查询告警(> 500ms) | 每小时约 13.8 万条,占 worker 日志行数 53% |
| 按主键查单行 `tb_iot_card` | 经常 0.7–2.4 秒 |
| worker 日志量 | 每小时约 26 万行,18 分钟写满一个 100MB 文件,40 个备份只能留约 12 小时 |
| 数据库连接 | worker 连接池 `MAX_OPEN_CONNS=60`,测试库上 61 个连接,基本占满;有一次 30 个会话同时等锁 |
| 采集记录丢失 | 写采集成功表/失败表 3 秒超时,约每 16 分钟丢 60 条 |
### 1.2 原因:消费并发没有总量限制
NSQ 只限制了每个运营商账户的并发(保护网关),没有限制全部账户加起来的并发(保护数据库):
| 来源 | 规则 | 理论上限 | 实测 |
|---|---|---|---|
| 卡轮询 `polling.card.<账户>` | 每账户 20(`default_card_max_in_flight`,`tb_carrier_polling_param` 无记录) | 41 × 20 = 820 | 约 310 |
| 停复机 `polling.stop_resume.<账户>` | 每账户 10 | 41 × 10 = 410 | 约 22 |
| 设备评估 `polling.device_eval` | 10 | 10 | 10 |
| 异步任务队列 | `JUNHONG_QUEUE_CONCURRENCY=50` | 50 | — |
| 合计 | | 约 1,290 | 约 380 |
`worker.polling_total_max_concurrency: 100` 只传给旧分片轮询(`cmd/worker/main.go:371`),按账户调度的 NSQ 消费者不受它约束。
每个轮询步骤在**同一个任务里**先调网关、再同步写库,所有写库都在步骤超时内完成。三百多个任务抢 60 个连接,等连接的时间计入超时,数据库稍有抖动就成批超时。
### 1.3 超时分布(按调用栈,约 16 分钟样本)
| 占比 | 位置 | 说明 |
|---|---|---|
| 约 40% | 配置匹配查套餐状态(`TierResolver.Prefill`,`internal/polling/config_manager.go:191`,共用 3 秒) | 绑定设备的卡连查 3 次;失败后把"未知"结果写进缓存 |
| 约 20% | `writeTrafficFailureAudit` | 沿用已超时的上下文再查卡,属连带报错 |
| 约 20% | 写采集成功表、失败表(`collectionRecordTimeout = 3s`) | 记录直接丢失 |
| 其余 | 流量观测事务、网络状态观测、实名缓存失效等 | |
## 2. 目标与原则
1. **调上游与入库分开控制**:调网关按账户并发(保持现有每账户上限),入库单独发消息、由单独的消费者处理。
2. **数据库并发有总上限**:入库消费者的并发是一个固定、可配置的数,与账户数量无关;加账户不会挤爆数据库。
3. **消费慢一点没关系**:消息在 NSQ 里排队,入库按数据库承受的速度处理;不丢、不重复算。
4. **轮询步骤只做"调网关 + 发消息"**:调网关前必要的读查询走缓存,尽量不碰数据库。
5. **可切回**:保留同步入库路径,用系统配置一键切换,异常时可回退。
6. **范围**:只在 `Iteration/8-11` 上实现,只部署测试环境。
## 3. 现状链路(一次流量步骤)
```
NSQ 卡任务 ──► 步骤(15s 超时)
├─ 读:优先轮询项 FindActive(tb_polling_priority_item)
├─ 读:卡(先清缓存再查库 tb_iot_card)
├─ 读:轮询范围校验(tb_carrier、tb_device、tb_device_sim_binding)
├─ 调网关 QueryFlow
├─ 写:ApplyTrafficObservation
│ ├─ Redis 采集队列 Push
│ ├─ 事务:锁卡行、查有效套餐、写日快照、更新卡、写流量事件 outbox、通道阈值评估、审计
│ └─ 写采集成功表/失败表(3s)
├─ 写:对接日志、优先项完成
└─ 返回 TriggeredEvaluation(决定是否跳过本轮套餐步骤)
```
网络状态步骤(`ApplyNetworkObservation`)、实名步骤(`ApplyCardObservation`)结构相同;套餐步骤不调网关,只读写库。
## 4. 技术设计
### 4.1 两段式
```
采集段(按账户并发,现有 NSQ 卡任务) 入库段(固定小并发)
┌────────────────────────────────┐ ┌──────────────────────────────┐
│ 读缓存 → 调网关 → 发入库消息 │──NSQ──► │ card.ingest 消费者(并发 N) │
│ 网关失败 → 发采集失败消息 │ │ Apply*Observation(事务) │
└────────────────────────────────┘ │ → 发采集记录消息 │
└──────────────┬───────────────┘
│NSQ
┌──────────────▼───────────────┐
│ card.collection 消费者 │
│ 攒批写成功表/失败表 │
└──────────────────────────────┘
```
- **采集段**:现有卡任务消费者,并发规则不变(每账户 `card_max_in_flight`)。步骤拿到网关结果后发一条入库消息就结束,步骤结果只反映"网关是否成功"。
- **入库段**:新 topic `card.ingest`,单独消费者,`max_in_flight` = `polling.ingest.concurrency`(默认 30)。
- **采集记录**:新 topic `card.collection`,单独的批量消费者(见 4.5)。
### 4.2 入库消息
topic `card.ingest`,JSON:
| 字段 | 说明 |
|---|---|
| `kind` | `traffic` / `network` / `realname` |
| `card_id`、`carrier_id`、`iccid` | 卡标识 |
| `observation_id` | 现有 `attempt.IntegrationID`,幂等键 |
| `observed_at` | 网关返回时刻(不是入库时刻) |
| `source`、`scene`、`correlation_id` | 现有观测元数据 |
| `payload` | 流量:`reading_mb`、`reading_result`、`reset_day`;网络:`status`、`extend`、`imei`;实名:`verified` |
| `raw`、`failure` | 网关原始数据(截断规则同采集记录) |
| `priority_item_id` | 本轮认领的优先轮询项,入库成功后由入库段完成 |
| `published_at` | 发出时刻,用于积压与延迟统计 |
### 4.3 入库消费者
处理一条消息:
1. 幂等检查:Redis `ingest:done:<observation_id>` 存在则直接 FIN。
2. 按 `kind` 调用现有 `ApplyTrafficObservation` / `ApplyNetworkObservation` / `ApplyCardObservation`,上下文超时 `polling.ingest.timeout`(默认 30s),从拿到消息开始计时。
3. 成功后:写 `ingest:done:<observation_id>`(TTL 48h);流量有变化时写 Redis 标记 `flow_evaluated:<card_id>`(见 4.6)。
- 本轮认领了优先轮询项的观测不走消息,仍在卡任务内同步入库,优先项完成与对接日志沿用原逻辑。
- 网络观测命中风险停机或已销户时,卡任务按网关结果直接停止该卡轮询,入库段写库时关闭轮询开关。
4. 失败:
- 数据库超时、连接错误等可重试错误:NSQ 延迟重投,退避 5s、15s、30s、1m、2m,之后每 5 分钟一次,**不设次数上限、不丢弃**(入库消费者的 NSQ `max_attempts` 设为 0);第 10 次起每次重投记 ERROR,带 `observation_id`、卡号与错误,便于排查。
- 业务性错误(卡不存在、数据校验失败):不重投,记 WARN 后 FIN。
- 本期不做死信表。长时间重试的消息会体现在积压量与最老消息等待时间上(见 4.7)。
### 4.4 顺序与幂等
NSQ 不保证顺序,也可能重投。逐项说明现有逻辑能否承受:
| 风险 | 处理 |
|---|---|
| 同一张卡两条流量消息乱序 | 采集队列按 `observed_at` 插入,"新点在队尾才写"——旧消息后到时不在队尾,不写快照,只记采集记录。现有规则已覆盖 |
| 同一张卡两条消息并发处理 | 事务内 `FOR UPDATE` 锁卡行,串行执行 |
| 同一条消息重投 | ① `ingest:done` 键挡掉已成功的;② 事务提交后、写键前崩溃:日快照取当日最大值、增量按"本月最大 − 已结算"计算,重放得到 0 增量;流量事件 outbox ID 由 `observation_id` 生成,重复写入被唯一键挡掉;③ 采集队列 Push 同一个点需改为按 `observed_at` 去重(Lua 内判断) |
| 网络/实名状态乱序 | 现有 `ApplyNetworkObservation`、`ApplyCardObservation` 需确认按 `observed_at` 比较"更新的才生效";没有的补上 |
| 采集记录重复 | 成功表/失败表按 `(observation_id, observed_at)` 建唯一索引(含分区键),批量写用 `ON CONFLICT DO NOTHING` |
### 4.5 采集记录批量写
- 入库段写完事务后,把采集成功记录发到 `card.collection`;采集段网关失败、无读数时直接把失败记录发到 `card.collection`,不经过入库段。
- `card.collection` 消费者 `max_in_flight` = 500,攒满 `polling.collection.batch_size`(默认 200)或等满 1 秒就批量写一次(多行 INSERT),成功后统一 FIN,失败统一重投。
- 写库并发固定 1–2 个连接。按测试环境每小时约 2.1 万条计算,每秒约 6 条,一次批量写即可。
- 现有 3 秒超时和"写失败只记日志"的逻辑删除,不再丢记录。
### 4.6 采集段剩余读查询
步骤里调网关前的读查询不能异步,改为走缓存:
| 读查询 | 现状 | 改为 |
|---|---|---|
| 卡信息 | 每步先清缓存再查库 | 读 Redis 卡缓存;入库段写完后失效缓存 |
| 优先轮询项 `FindActive` | 每步每类型查一次库 | Redis 维护"有活动优先项的卡"集合,不在集合里不查库 |
| 运营商实名开关、重置日 | 每步查库 | 进程内缓存 1 分钟 |
| 设备轮询开关、绑定关系 | 每步查库 | 并入卡缓存 |
| 套餐状态(配置匹配) | 3 次查询共用 3 秒,失败缓存"未知" | 每次查询各自计时;失败不写缓存,下次重查 |
套餐步骤跳过逻辑:现在根据同一任务里流量步骤的 `TriggeredEvaluation` 跳过。异步后改为读 Redis 标记 `flow_evaluated:<card_id>`(入库段写,TTL = 套餐检查间隔)。
### 4.7 积压与反压
- 监控:每分钟读 nsqd `/stats`,记录 `card.ingest`、`card.collection` 的积压量和最老消息等待时间,写应用日志。
- 告警:积压超过 `polling.ingest.alert_depth`(默认 200,000)或等待超过 10 分钟,记 ERROR(接现有告警通道)。
- 反压:积压超过 `polling.ingest.pause_depth`(默认 500,000,须大于告警阈值)时,调度器暂停发新的卡任务;降到一半以下恢复。账户限流状态不受影响。
### 4.8 NSQ 持久化
nsqd 当前参数 `--mem-queue-size=10000`:消息先放内存,nsqd 意外退出会丢掉内存里的部分。
- 测试环境改为 `--mem-queue-size=0`:所有消息直接落盘(`./nsq-data` 已挂载),按现有量级(每秒几十条)性能没有影响。
- 卡任务 topic 也会一起落盘,对现有调度无行为变化。
- 磁盘占用:入库消息带网关原始数据,单条约 2KB;积压到反压阈值 50 万条约 1GB,测试服务器剩余 32G,足够。
### 4.9 不改的同步路径
以下入口量小、需要立即返回结果,保持同步入库:后台人工刷新、运营商回调(移动/联通/电信实名)、激活前结算、观测序列(series runner)。
### 4.10 配置项
| 配置 | 默认 | 说明 |
|---|---|---|
| `polling.ingest.mode` | `sync` | `sync` 为现在的同步入库;部署确认无误后切 `async` |
| `polling.ingest.concurrency` | 30 | 入库消费者并发 |
| `polling.ingest.timeout` | 30s | 单条入库超时 |
| `polling.collection.batch_size` | 200 | 采集记录批量大小 |
| `polling.ingest.alert_depth` / `pause_depth` | 200,000 / 500,000 | 告警与反压阈值 |
`mode` 与阈值放系统配置(改了几秒内生效),并发放启动配置。启动时检查:入库并发 + 采集记录写并发(2)不超过 `MAX_OPEN_CONNS` − 20(给采集段读查询、异步任务队列与其他查询留出至少 20 个连接),超过记 ERROR。测试环境 `MAX_OPEN_CONNS=60`:入库 30 + 采集记录 2 = 32 ≤ 40,满足。
### 4.11 发布失败兜底
采集段发消息失败(nsqd 不可用)时,降级为当前的同步入库,并记 WARN;不因 nsqd 故障丢观测。
## 5. 影响与代价
- 入库延迟:正常几秒;积压时更长。卡流量、状态在后台的刷新会比现在晚几秒。
- 停复机判断:超量停机、通道阈值停机依赖入库结果,跟着入库段触发,晚几秒。
- 优先轮询(加急):完成时间从"网关返回"推迟到"入库成功"。
- 同一张卡的数据库写入从"一个任务内"变成"跨两个消费者",排查时按 `observation_id` 串联日志。
## 6. 分支与范围
- 基于 `Iteration/8-11`,只部署测试环境;不写生产配置、不涉及生产重启。
- 依赖 `add-carrier-polling-scheduler`、`add-card-traffic-queue-and-observed-deduction` 的现有实现,不改它们的业务规则。
## 7. 实施步骤
1. 采集队列 Push 按 `observed_at` 去重;网络/实名观测补"更新的才生效"判断(如缺)。
2. 采集记录唯一索引迁移;`card.collection` 批量消费者;采集段失败记录改发消息。
3. `card.ingest` 消息、入库消费者、幂等键、不限次数的退避重试。
4. 三个轮询步骤改为发消息;优先项完成、对接日志、`StopPolling`、`flow_evaluated` 移到入库段;发布失败降级。
5. 采集段读查询走缓存;套餐状态查询各自计时、失败不缓存。
6. 积压监控、告警、反压;启动并发检查。
7. 系统配置与回退开关;测试环境 nsqd 改 `--mem-queue-size=0`。
## 8. 测试与验证(测试环境)
| 验证项 | 通过标准 |
|---|---|
| SQL 超时 | `context deadline exceeded` 从每小时约 8,000 次降到个位数 |
| 慢查询 | 每小时告警数明显下降,worker 日志留存能达到 14 天目标的量级 |
| 采集记录完整 | 每小时:入库消息数 = 成功表 + 失败表新增行数(按 `observation_id` 对账) |
| 计量正确 | 抽样卡日快照、套餐扣减与同步模式结果一致;重投、乱序不重复扣减 |
| 积压 | `card.ingest` 等待时间常态 < 30 秒 |
| 回退 | `polling.ingest.mode=sync` 后恢复现有行为 |
| 降级 | 停掉 nsqd 时采集段改为同步入库,不丢观测 |
## 9. 已定事项(2026-11-06)
1. 入库消费者默认并发 30。
2. 测试环境 nsqd 改为 `--mem-queue-size=0`,所有消息直接落盘。
3. 本期不做死信:可重试错误不限次数退避重试,不丢弃;业务性错误记 WARN 后丢弃。
4. 积压告警阈值 200,000 条;反压(暂停派发新卡任务)阈值 500,000 条。

View File

@@ -0,0 +1,133 @@
# 2026-11-04 换货迁移导致卡上两个主套餐同时生效的数据修正
## 现象
卡 `89860624630055040571`(`tb_iot_card.id = 93937`)在后台的预计套餐到期时间显示"数据异常"(`expiry_estimate_status = invalid_data`)。
## 原因
### 1. 换货迁移把老卡的生效中套餐原样挂到了新卡上
2026-11-03 17:42,换货单 `EXC20261103174239616885`(`tb_exchange_order.id = 1094`)完成直接换货:
- 老卡:`89860624630055027198`(`id = 93846`),停机、未实名,从未产生流量。
- 新卡:`89860624630055040571`(`id = 93937`)。
- 选了迁移数据。换货原因是"未实名卡,给老卡续费"。
`internal/service/exchange/migration.go` 的 `migratePackageUsageWithTx` 只把老卡套餐使用记录的 `iot_card_id` 改成新卡,状态原样保留,也不检查新卡是否已有生效中的主套餐。迁移后新卡上同时有两个生效中(`status = 1`)的主套餐:
| 套餐使用记录 | 套餐 | 订单号 | 修正前状态 | 到期时间 |
|---|---|---|---|---|
| 47051 | Mifi-U省内版(12个月省内流量每月3000G),`package_id = 272` | `MIG-89860624630055040571-1` | 生效中 | 2026-12-14 |
| 46981 | 12个月省内流量每月1000G,`package_id = 230` | `MIG-89860624630055027198-1` | 生效中,`activated_at` 为空 | 2027-12-14 |
46981 的到期时间正好是 47051 到期后再加一年,说明运营的本意是"续费,接在现有套餐后面"。
`internal/query/packageexpiry/query.go` 的 `Calculate` 要求一个资产只能有一个生效中或已用完的主套餐。出现两个时返回 `invalid_data`。
### 2. 流量扣到了续费的套餐上
换货后,新卡的流量全部扣到了 46981 上,47051 从 11-03 17:40 起没有再被扣过:
| 日期 | 47051 日用量 | 46981 日用量 |
|---|---|---|
| 11-01 | 941 MB | |
| 11-02 | 255 MB | |
| 11-03 | 5,393 MB | 52 MB |
| 11-04 | | 2,707 MB |
合计 9,348 MB,和新卡 11 月的 `current_month_usage_mb = 9348.33` 一致。老卡本月和上月的用量都是 0,所以 46981 上的用量全部来自新卡。
### 3. 第一次修正后仍显示数据异常:排序问题
46981 改成待生效后,页面仍然显示数据异常。原因是两条记录的 `priority` 都是 1,`created_at` 也完全相同(同一次迁移写入,都是 `2026-09-02 16:40:32.81965`),排序只能按 `id`,46981 就排在了 47051 前面。`Calculate` 不允许待生效套餐排在当前套餐之前,所以仍然判成 `invalid_data`。把 46981 的 `priority` 改成 2 后,它排到了 47051 后面。
## 已执行的修正(生产库,2026-11-04)
两步都在单个事务中执行:先锁行,改完后自动校验,校验不通过就整体回滚。
### 第一步:用量转回 47051,46981 改为待生效
执行前:46981 的 `data_usage_mb = 2759`,47051 的 `data_usage_mb = 112102`。
```sql
BEGIN;
SELECT id, status, data_usage_mb, iot_card_id FROM tb_package_usage WHERE id IN (46981, 47051) ORDER BY id FOR UPDATE;
-- 46981 的已用量转回 47051
UPDATE tb_package_usage a
SET data_usage_mb = a.data_usage_mb + b.data_usage_mb, updated_at = now()
FROM tb_package_usage b
WHERE a.id = 47051 AND b.id = 46981 AND a.status = 1 AND b.status = 1 AND a.iot_card_id = 93937 AND b.iot_card_id = 93937;
-- 日用量记录并到 47051
INSERT INTO tb_package_usage_daily_record (package_usage_id, date, daily_usage_mb, cumulative_usage_mb, created_at, updated_at)
SELECT 47051, d.date, d.daily_usage_mb, 0, now(), now()
FROM tb_package_usage_daily_record d WHERE d.package_usage_id = 46981
ON CONFLICT (package_usage_id, date) DO UPDATE
SET daily_usage_mb = tb_package_usage_daily_record.daily_usage_mb + EXCLUDED.daily_usage_mb, updated_at = now();
-- 以 11-02 的累计值为起点,重算 47051 从 11-03 起的累计用量
UPDATE tb_package_usage_daily_record r SET cumulative_usage_mb = x.cum, updated_at = now()
FROM (
SELECT id,
(SELECT cumulative_usage_mb FROM tb_package_usage_daily_record WHERE package_usage_id = 47051 AND date = '2026-11-02')
+ sum(daily_usage_mb) OVER (ORDER BY date) AS cum
FROM tb_package_usage_daily_record
WHERE package_usage_id = 47051 AND date >= '2026-11-03'
) x
WHERE r.id = x.id;
DELETE FROM tb_package_usage_daily_record WHERE package_usage_id = 46981;
-- 46981 改为待生效,和现有待生效套餐的数据形态一致;激活时不会把已用量清零,所以这里必须清零
UPDATE tb_package_usage
SET status = 0, data_usage_mb = 0, activated_at = NULL, expires_at = NULL,
last_reset_at = NULL, next_reset_at = NULL, updated_at = now()
WHERE id = 46981 AND status = 1 AND iot_card_id = 93937;
-- 校验项:47051 的已用量等于两者之和;46981 是待生效、已用量为 0;
-- 47051 最后一天的累计用量等于它的已用量;46981 已经没有日用量记录
COMMIT;
```
### 第二步:调整排队顺序
```sql
BEGIN;
UPDATE tb_package_usage SET priority = 2, updated_at = now()
WHERE id = 46981 AND status = 0 AND iot_card_id = 93937 AND priority = 1;
COMMIT;
```
## 修正后的状态
| 套餐使用记录 | 状态 | 优先级 | 已用量 | 生效时间 | 到期时间 | 下次重置 |
|---|---|---|---|---|---|---|
| 47051 | 生效中 | 1 | 114,861 MB | 2025-12-14 | 2026-12-14 | 2026-11-09 |
| 46981 | 待生效 | 2 | 0 | 空 | 空 | 空 |
47051 的日用量记录:11-03 为 5,445 MB,累计 112,154 MB;11-04 为 2,707 MB,累计 114,861 MB。
预期效果:
- 后续流量扣到 47051 上。
- 预计到期时间推算为约 2027-12-14:47051 到期后,46981 由排队激活接上 365 天。
## 回滚
一般不需要回滚。如果必须恢复到修正前的状态:
1. 46981 恢复为 `status = 1`、`priority = 1`、`data_usage_mb = 2759`、`expires_at = '2027-12-14 00:00:00'`、`last_reset_at = '2026-10-18 01:23:14.86183'`、`next_reset_at = '2026-11-17 00:00:00'`。
2. 47051 的 `data_usage_mb` 减去 2759。
3. 日用量记录拆回原样:
- 46981:11-03 为 52/52,11-04 为 2707/2759;
- 47051:11-03 为 5393/112102,并删除 47051 的 11-04 记录。
回滚前,要先确认修正之后又扣进 47051 的新用量。
## 遗留问题
- **代码漏洞未修。** 换货迁移不处理新资产已有生效中主套餐的情况,以后同类换货还会再出现两个主套餐同时生效。可选的修法:
- 迁移过来的主套餐改为待生效,排在新资产现有套餐之后(`priority` 递增);
- 或者在换货前检查,直接拒绝,提示运营先处理。
- **同类问题未排查。** 生产中可能还有其他卡或设备同时挂着多个生效中的主套餐,尚未全量排查。

View File

@@ -20,10 +20,11 @@ import (
// RealnameChangedEvent 是卡实名状态变化的可靠领域事实。
type RealnameChangedEvent struct {
EventID string `json:"event_id"`
CardID uint `json:"card_id"`
BeforeStatus int `json:"before_status"`
AfterStatus int `json:"after_status"`
EventID string `json:"event_id"`
CardID uint `json:"card_id"`
BeforeStatus int `json:"before_status"`
AfterStatus int `json:"after_status"`
// FirstVerified 表示需要触发实名激活:首次实名,或二次实名完成(此时 first_realname_at 不变)。
FirstVerified bool `json:"first_verified"`
ObservedAt time.Time `json:"observed_at"`
Source string `json:"source"`
@@ -82,6 +83,18 @@ type Service struct {
logger *zap.Logger
// commandGrace 返回停复机成功后的状态保护窗口;未注入时不保护。
commandGrace func(ctx context.Context) time.Duration
// collectionSink 把采集记录发布到批量写入消息;未注入或发布失败时同步写库。
collectionSink CollectionSink
}
// CollectionSink 发布一条采集记录(成功表或失败表二选一),由批量消费者写库。
type CollectionSink interface {
PublishCollection(ctx context.Context, success *model.CardTrafficCollection, failure *model.CardTrafficCollectionFailure) error
}
// SetCollectionSink 注入采集记录发布器(Worker 启用 card.collection 批量写入时使用)。
func (s *Service) SetCollectionSink(sink CollectionSink) {
s.collectionSink = sink
}
// SetCommandGrace 注入停复机成功后的状态保护窗口(受控系统配置 polling.stop_resume.status_grace_seconds)。
@@ -144,6 +157,7 @@ func (s *Service) ApplyCardObservation(ctx context.Context, observation domain.R
}
var decision domain.RealnameDecision
var auditedCard *model.IotCard
stale := false
err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
var card model.IotCard
if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Where("id = ?", observation.CardID).First(&card).Error; err != nil {
@@ -153,6 +167,36 @@ func (s *Service) ApplyCardObservation(ctx context.Context, observation domain.R
return errors.Wrap(errors.CodeDatabaseError, err, "锁定IoT卡失败")
}
auditedCard = &card
if staleObservation(card.LastRealNameCheckAt, observation.Metadata.ObservedAt) {
// 异步入库可能乱序:早于已应用观测的实名结果不改卡事实,只记录。
s.warnLogger().Info("实名观测早于卡上最近一次已应用的检查,忽略",
zap.Uint("card_id", card.ID), zap.String("observation_id", observation.Metadata.ObservationID),
zap.Time("observed_at", observation.Metadata.ObservedAt), zap.Timep("last_checked_at", card.LastRealNameCheckAt),
zap.String("metric", "card_observation.realname_stale"))
stale = true
return nil
}
realnameRecord, realnameSnapshot, loadErr := loadRealnameTime(ctx, tx, card.ID)
if loadErr != nil {
return loadErr
}
resetGate := domain.EvaluateRealnameResetGate(realnameSnapshot, observation)
if resetGate == domain.RealnameResetGateBlocked {
// 等待二次实名期间读到的仍是旧实名(上游实名时间不晚于清除前时间,或没有上游时间):不改实名状态,只记检查时间。
decision = domain.RealnameDecision{BeforeStatus: card.RealNameStatus, AfterStatus: card.RealNameStatus,
ReversalCount: card.RealnameReversalCount, ReversalStartedAt: card.RealnameReversalStartedAt}
checked := map[string]any{"last_real_name_check_at": observation.Metadata.ObservedAt}
if observation.Metadata.Source != constants.CardObservationSourceManualOverride {
checked["last_sync_time"] = observation.Metadata.ObservedAt
}
if err := tx.Model(&model.IotCard{}).Where("id = ?", card.ID).Updates(checked).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新卡实名检查时间失败")
}
s.warnLogger().Info("等待二次实名的卡读到旧实名,不覆盖",
zap.Uint("card_id", card.ID), zap.String("observation_id", observation.Metadata.ObservationID),
zap.Timep("upstream_realname_at", observation.UpstreamRealnameAt), zap.Timep("baseline_at", realnameSnapshot.ResetBaselineAt))
return nil
}
nextDecision, decisionErr := domain.ApplyRealname(domain.CardRealnameSnapshot{
CardID: card.ID, Status: card.RealNameStatus, FirstRealnameAt: card.FirstRealnameAt,
ReversalCount: card.RealnameReversalCount, ReversalStartedAt: card.RealnameReversalStartedAt,
@@ -185,11 +229,16 @@ func (s *Service) ApplyCardObservation(ctx context.Context, observation domain.R
if result.RowsAffected != 1 {
return errors.New(errors.CodeConflict, "卡实名状态已被其他请求更新")
}
if observation.Verified && decision.AfterStatus == constants.RealNameStatusVerified {
if err := applyRealnameTime(ctx, tx, &card, realnameRecord, observation, resetGate); err != nil {
return err
}
}
if decision.StatusChanged {
eventID := realnameChangedEventID(card.ID, observation.Metadata.ObservationID)
if err := s.eventWriter.AppendRealname(ctx, tx, RealnameChangedEvent{
EventID: eventID, CardID: card.ID, BeforeStatus: card.RealNameStatus, AfterStatus: decision.AfterStatus,
FirstVerified: decision.FirstVerified, ObservedAt: observation.Metadata.ObservedAt,
FirstVerified: decision.FirstVerified || resetGate == domain.RealnameResetGateCompleted, ObservedAt: observation.Metadata.ObservedAt,
Source: observation.Metadata.Source, Scene: observation.Metadata.Scene,
RequestID: observation.Metadata.RequestID, CorrelationID: observation.Metadata.CorrelationID,
}); err != nil {
@@ -275,6 +324,9 @@ func (s *Service) ApplyCardObservation(ctx context.Context, observation domain.R
}
return domain.RealnameDecision{}, err
}
if stale {
return domain.RealnameDecision{}, nil
}
if s.cache != nil {
s.cache.Invalidate(ctx, observation.CardID)
}

View File

@@ -37,6 +37,7 @@ func (s *Service) ApplyNetworkObservation(ctx context.Context, observation domai
}
var decision domain.NetworkDecision
var auditedCard *model.IotCard
stale := false
err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
var card model.IotCard
if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Where("id = ?", observation.CardID).First(&card).Error; err != nil {
@@ -46,6 +47,15 @@ func (s *Service) ApplyNetworkObservation(ctx context.Context, observation domai
return errors.Wrap(errors.CodeDatabaseError, err, "锁定IoT卡网络事实失败")
}
auditedCard = &card
if staleObservation(card.LastCardStatusCheckAt, observation.Metadata.ObservedAt) {
// 异步入库可能乱序:早于已应用观测的网络状态不改卡事实,只记录。
s.warnLogger().Info("网络状态观测早于卡上最近一次已应用的检查,忽略",
zap.Uint("card_id", card.ID), zap.String("observation_id", observation.Metadata.ObservationID),
zap.Time("observed_at", observation.Metadata.ObservedAt), zap.Timep("last_checked_at", card.LastCardStatusCheckAt),
zap.String("metric", "card_observation.network_stale"))
stale = true
return nil
}
nextDecision, decisionErr := domain.ApplyNetwork(domain.CardNetworkSnapshot{
CardID: card.ID, NetworkStatus: card.NetworkStatus, StopReason: card.StopReason,
EnablePolling: card.EnablePolling, StoppedAt: card.StoppedAt, ResumedAt: card.ResumedAt,
@@ -176,8 +186,16 @@ func (s *Service) ApplyNetworkObservation(ctx context.Context, observation domai
}
return domain.NetworkDecision{}, err
}
if stale {
return domain.NetworkDecision{}, nil
}
if s.cache != nil {
s.cache.Invalidate(ctx, observation.CardID)
}
return decision, nil
}
// staleObservation 判断观测时间是否早于卡上最近一次已应用的同类检查时间(异步入库乱序保护)。
func staleObservation(lastChecked *time.Time, observedAt time.Time) bool {
return lastChecked != nil && !observedAt.IsZero() && observedAt.Before(*lastChecked)
}

View File

@@ -0,0 +1,177 @@
package cardobservation
import (
"context"
"strconv"
"time"
domain "github.com/break/junhong_cmp_fiber/internal/domain/cardobservation"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/outboxid"
"gorm.io/gorm"
"gorm.io/gorm/clause"
)
// RealnameResetCommand 描述对一张卡的二次实名清除或撤销。
type RealnameResetCommand struct {
CardID uint
BatchID uint
OperatorID uint
}
// 二次实名不可执行的原因(业务可预期,按行记录,不当作系统错误)。
var (
ErrRealnameResetNotVerified = errors.New(errors.CodeInvalidStatus, "卡未实名,无需二次实名")
ErrRealnameResetNoUpstream = errors.New(errors.CodeInvalidStatus, "上游未返回实名时间,不支持二次实名")
ErrRealnameResetAlreadyReset = errors.New(errors.CodeInvalidStatus, "卡已在等待二次实名")
ErrRealnameResetNotPending = errors.New(errors.CodeInvalidStatus, "卡不在等待二次实名,不能撤销")
)
// ResetRealname 二次实名清除:卡置为未实名、当前实名时间置空,记下清除前的上游实名时间作为新旧判定基准。
// 只支持上游返回过 archiveTime 的卡;已激活套餐不回退,first_realname_at 不修改。
// 状态变化按现有流程写实名变化事件与审计,下游停复机评估与普通未实名卡一致。
func (s *Service) ResetRealname(ctx context.Context, command RealnameResetCommand) error {
return s.changeRealnameForReset(ctx, command, false)
}
// RevertRealnameReset 撤销等待中的二次实名:卡恢复已实名,当前实名时间恢复为清除前时间。
func (s *Service) RevertRealnameReset(ctx context.Context, command RealnameResetCommand) error {
return s.changeRealnameForReset(ctx, command, true)
}
func (s *Service) changeRealnameForReset(ctx context.Context, command RealnameResetCommand, revert bool) error {
if s == nil || s.db == nil || s.eventWriter == nil || s.auditWriter == nil {
return errors.New(errors.CodeInternalError, "卡实名观测能力未完整配置")
}
if command.CardID == 0 {
return errors.New(errors.CodeInvalidParam, "卡 ID 无效")
}
now := time.Now()
err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
var card model.IotCard
if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Where("id = ?", command.CardID).First(&card).Error; err != nil {
if err == gorm.ErrRecordNotFound {
return errors.New(errors.CodeNotFound, "IoT卡不存在")
}
return errors.Wrap(errors.CodeDatabaseError, err, "锁定IoT卡失败")
}
record, snapshot, err := loadRealnameTime(ctx, tx, card.ID)
if err != nil {
return err
}
if revert {
return s.revertResetInTx(ctx, tx, &card, record, snapshot, command, now)
}
return s.resetInTx(ctx, tx, &card, record, snapshot, command, now)
})
if err != nil {
return err
}
if s.cache != nil {
s.cache.Invalidate(ctx, command.CardID)
}
return nil
}
func (s *Service) resetInTx(ctx context.Context, tx *gorm.DB, card *model.IotCard, record *model.IotCardRealname,
snapshot domain.RealnameTimeSnapshot, command RealnameResetCommand, now time.Time) error {
if card.RealNameStatus != constants.RealNameStatusVerified {
return ErrRealnameResetNotVerified
}
if record == nil || record.UpstreamRealnameAt == nil {
return ErrRealnameResetNoUpstream
}
if snapshot.ResetStatus == constants.RealnameResetStatusPending {
return ErrRealnameResetAlreadyReset
}
if err := s.updateCardRealnameStatusInTx(ctx, tx, card, constants.RealNameStatusNotVerified, now, "reset", command.BatchID); err != nil {
return err
}
batchID := command.BatchID
if err := tx.WithContext(ctx).Model(&model.IotCardRealname{}).Where("id = ?", record.ID).Updates(map[string]any{
"realname_at": nil, "reset_status": constants.RealnameResetStatusPending, "reset_at": now,
"reset_baseline_at": *record.UpstreamRealnameAt, "reset_batch_id": batchID, "updated_at": now,
}).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入二次实名等待状态失败")
}
return writeResetHistory(ctx, tx, card, record.RealnameAt, nil, "", constants.RealnameChangeReset, command, now)
}
func (s *Service) revertResetInTx(ctx context.Context, tx *gorm.DB, card *model.IotCard, record *model.IotCardRealname,
snapshot domain.RealnameTimeSnapshot, command RealnameResetCommand, now time.Time) error {
if record == nil || snapshot.ResetStatus != constants.RealnameResetStatusPending {
return ErrRealnameResetNotPending
}
if command.BatchID != 0 && (record.ResetBatchID == nil || *record.ResetBatchID != command.BatchID) {
return ErrRealnameResetNotPending
}
if card.RealNameStatus != constants.RealNameStatusVerified {
if err := s.updateCardRealnameStatusInTx(ctx, tx, card, constants.RealNameStatusVerified, now, "revert", command.BatchID); err != nil {
return err
}
}
restored := record.ResetBaselineAt
if err := tx.WithContext(ctx).Model(&model.IotCardRealname{}).Where("id = ?", record.ID).Updates(map[string]any{
"realname_at": restored, "realname_at_source": constants.RealnameAtSourceUpstream,
"reset_status": constants.RealnameResetStatusNone, "reset_at": nil, "reset_baseline_at": nil, "reset_batch_id": nil,
"updated_at": now,
}).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "撤销二次实名等待状态失败")
}
return writeResetHistory(ctx, tx, card, nil, restored, constants.RealnameAtSourceUpstream, constants.RealnameChangeResetReverted, command, now)
}
// updateCardRealnameStatusInTx 按实名观测的同一口径更新卡实名状态,并写实名变化事件与人工审计。
func (s *Service) updateCardRealnameStatusInTx(ctx context.Context, tx *gorm.DB, card *model.IotCard, after int, now time.Time, kind string, batchID uint) error {
verified := after == constants.RealNameStatusVerified
result := tx.WithContext(ctx).Model(&model.IotCard{}).Where("id = ? AND real_name_status = ?", card.ID, card.RealNameStatus).Updates(map[string]any{
"real_name_status": after,
"realname_reversal_count": 0,
"realname_reversal_started_at": nil,
"activation_status": gorm.Expr(`CASE WHEN network_status = ? AND (card_category = ? OR ?) THEN 1 ELSE 0 END`, constants.NetworkStatusOnline, constants.CardCategoryIndustry, verified),
})
if result.Error != nil {
return errors.Wrap(errors.CodeDatabaseError, result.Error, "更新卡实名状态失败")
}
if result.RowsAffected != 1 {
return errors.New(errors.CodeConflict, "卡实名状态已被其他请求更新")
}
observationID := "realname-" + kind + ":" + strconv.FormatUint(uint64(batchID), 10) + ":" + strconv.FormatInt(now.UnixNano(), 10)
eventID := outboxid.Stable("card-realname:", strconv.FormatUint(uint64(card.ID), 10)+":"+observationID+":changed")
if err := s.eventWriter.AppendRealname(ctx, tx, RealnameChangedEvent{
EventID: eventID, CardID: card.ID, BeforeStatus: card.RealNameStatus, AfterStatus: after,
ObservedAt: now, Source: constants.CardObservationSourceManualOverride, Scene: "realname_" + kind,
CorrelationID: observationID,
}); err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入卡实名 Outbox 事件失败")
}
summary := "二次实名清除:卡实名状态置为未实名"
if verified {
summary = "二次实名撤销:卡恢复已实名"
}
return s.auditWriter.WriteCardStateAudit(ctx, tx, StateAudit{
ActionCode: constants.AuditActionIotCardRealnameStatusUpdated, Summary: summary, Card: card,
BeforeData: map[string]any{"real_name_status": card.RealNameStatus},
AfterData: map[string]any{"real_name_status": after, "realname_reset_batch_id": batchID},
})
}
func writeResetHistory(ctx context.Context, tx *gorm.DB, card *model.IotCard, before, after *time.Time, afterSource, changeType string,
command RealnameResetCommand, now time.Time) error {
var batchID *uint
if command.BatchID != 0 {
value := command.BatchID
batchID = &value
}
history := model.IotCardRealnameHistory{
CardID: card.ID, ICCID: card.ICCID, BeforeAt: before, AfterAt: after, AfterSource: afterSource,
ChangeType: changeType, ObservationSource: constants.CardObservationSourceManualOverride,
ResetBatchID: batchID, OperatorID: command.OperatorID, ObservedAt: now, CreatedAt: now,
}
if err := tx.WithContext(ctx).Create(&history).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入卡实名时间历史失败")
}
return nil
}

View File

@@ -0,0 +1,96 @@
package cardobservation
import (
"context"
"time"
domain "github.com/break/junhong_cmp_fiber/internal/domain/cardobservation"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"gorm.io/gorm"
)
// loadRealnameTime 在调用方事务中读取卡当前实名记录;调用方已锁定卡行,同一张卡的写入因此串行。
func loadRealnameTime(ctx context.Context, tx *gorm.DB, cardID uint) (*model.IotCardRealname, domain.RealnameTimeSnapshot, error) {
var record model.IotCardRealname
err := tx.WithContext(ctx).Where("card_id = ?", cardID).Take(&record).Error
if err == gorm.ErrRecordNotFound {
return nil, domain.RealnameTimeSnapshot{}, nil
}
if err != nil {
return nil, domain.RealnameTimeSnapshot{}, errors.Wrap(errors.CodeDatabaseError, err, "查询卡当前实名记录失败")
}
return &record, realnameTimeSnapshot(&record), nil
}
func realnameTimeSnapshot(record *model.IotCardRealname) domain.RealnameTimeSnapshot {
if record == nil {
return domain.RealnameTimeSnapshot{}
}
return domain.RealnameTimeSnapshot{
Exists: true, RealnameAt: record.RealnameAt, RealnameAtSource: record.RealnameAtSource,
UpstreamRealnameAt: record.UpstreamRealnameAt, FirstObservedAt: record.FirstObservedAt,
ResetStatus: record.ResetStatus, ResetBaselineAt: record.ResetBaselineAt,
}
}
// applyRealnameTime 在卡已被采纳为已实名后更新当前实名记录;只有实名时间变化才写历史。
func applyRealnameTime(ctx context.Context, tx *gorm.DB, card *model.IotCard, record *model.IotCardRealname,
observation domain.RealnameObservation, gate domain.RealnameResetGate) error {
decision := domain.DecideRealnameTime(realnameTimeSnapshot(record), observation, gate)
if !decision.Changed {
return nil
}
now := time.Now()
var resetBatchID *uint
if record != nil {
resetBatchID = record.ResetBatchID
}
if record == nil {
created := model.IotCardRealname{
CardID: card.ID, RealnameAt: decision.RealnameAt, RealnameAtSource: decision.Source,
UpstreamRealnameAt: decision.UpstreamRealnameAt, FirstObservedAt: decision.FirstObservedAt,
ResetStatus: constants.RealnameResetStatusNone, CreatedAt: now, UpdatedAt: now,
}
if err := tx.WithContext(ctx).Create(&created).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "创建卡当前实名记录失败")
}
} else {
updates := map[string]any{
"realname_at": decision.RealnameAt, "realname_at_source": decision.Source,
"upstream_realname_at": decision.UpstreamRealnameAt, "first_observed_at": decision.FirstObservedAt,
"updated_at": now,
}
if decision.ClearReset {
updates["reset_status"] = constants.RealnameResetStatusNone
updates["reset_at"] = nil
updates["reset_baseline_at"] = nil
updates["reset_batch_id"] = nil
}
if err := tx.WithContext(ctx).Model(&model.IotCardRealname{}).Where("id = ?", record.ID).Updates(updates).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新卡当前实名记录失败")
}
}
if decision.ClearReset && resetBatchID != nil {
if err := tx.WithContext(ctx).Model(&model.IotCardRealnameResetBatch{}).Where("id = ?", *resetBatchID).
Updates(map[string]any{"completed_count": gorm.Expr("completed_count + 1"), "updated_at": now}).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新二次实名批次完成数失败")
}
}
if !decision.WriteHistory {
return nil
}
history := model.IotCardRealnameHistory{
CardID: card.ID, ICCID: card.ICCID, BeforeAt: decision.BeforeAt, AfterAt: decision.RealnameAt,
AfterSource: decision.Source, ChangeType: decision.ChangeType, ObservationSource: observation.Metadata.Source,
ObservedAt: observation.Metadata.ObservedAt, CreatedAt: now,
}
if decision.ClearReset {
history.ResetBatchID = resetBatchID
}
if err := tx.WithContext(ctx).Create(&history).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入卡实名时间历史失败")
}
return nil
}

View File

@@ -84,6 +84,7 @@ func (s *Service) ApplyTrafficObservation(ctx context.Context, observation domai
return errors.Wrap(errors.CodeDatabaseError, err, "查询卡采集时刻有效套餐失败")
}
record.HasPackage = len(packages.Packages) > 0
record.CarrierID = card.CarrierID
if judge != cardflow.QueueWrite {
if observation.Metadata.Scene == constants.CardObservationScenePreActivationSettlement {
// 激活前结算没写入:用已有本月最大快照结算,不新写快照。
@@ -230,6 +231,10 @@ func (s *Service) writeTrafficFailureAudit(ctx context.Context, observation doma
if !workerObservationAudited(ctx) || s.auditWriter == nil {
return
}
// 观测失败常因上下文已超时,失败审计改用独立短超时上下文,避免连带报错。
auditCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
defer cancel()
ctx = auditCtx
var card model.IotCard
if loadErr := s.db.WithContext(ctx).Where("id = ?", observation.CardID).First(&card).Error; loadErr != nil {
return

View File

@@ -4,8 +4,10 @@ import (
"context"
"encoding/json"
"time"
"unicode/utf8"
"go.uber.org/zap"
"gorm.io/datatypes"
cardflow "github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
domain "github.com/break/junhong_cmp_fiber/internal/domain/cardobservation"
@@ -14,13 +16,15 @@ import (
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// collectionRecordTimeout 是事务提交后写采集记录的超时;采集记录只用于排查,写失败只告警。
const collectionRecordTimeout = 3 * time.Second
// rawResponseMaxBytes 是原始响应体保存上限,超过时截断并标记。
const rawResponseMaxBytes = 4096
// collectionRecord 是一次采集的留痕内容;HasPackage 在观测事务内判断,读数无效的观测写记录前再查。
// collectionRecord 是一次采集的留痕内容;HasPackage 在观测事务内判断(只对成功读数有意义)。
type collectionRecord struct {
model.CardTrafficCollection
HasPackage bool
failure *domain.CollectionFailure
iccid string
}
func newCollectionRecord(observation domain.TrafficObservation) *collectionRecord {
@@ -28,7 +32,8 @@ func newCollectionRecord(observation domain.TrafficObservation) *collectionRecor
IotCardID: observation.CardID, ObservedAt: observation.Metadata.ObservedAt,
ObservationID: observation.Metadata.ObservationID, Source: observation.Metadata.Source,
Scene: observation.Metadata.Scene, Result: domain.ResolveReadingResult(observation),
}}
CollectionRaw: buildCollectionRaw(observation.Raw), CarrierID: observation.CarrierID,
}, failure: observation.Failure, iccid: observation.ICCID}
if record.Result == constants.TrafficCollectionResultOK {
reading := observation.GatewayReadingMB
record.VendorUsedMB = &reading
@@ -51,24 +56,112 @@ func (r *collectionRecord) applyOutcome(outcome *flowOutcome) {
r.MonthUsedMB, r.DeltaMB, r.StaleGuarded, r.EventID = &monthUsed, &delta, &stale, outcome.EventID
}
// writeCollectionRecord 在观测事务之外为采集时刻有套餐的卡写采集记录;没套餐的卡不写。
func (s *Service) writeCollectionRecord(ctx context.Context, record *collectionRecord, observedAt time.Time) {
writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), collectionRecordTimeout)
defer cancel()
hasPackage := record.HasPackage
// writeCollectionRecord 在观测事务之外写采集记录:成功读数只为采集时刻有套餐的卡写成功表;
// 失败读数不判断有无套餐,写失败表。注入发布器时发布到批量写入消息,由消费者攒批写库并失败重投;
// 未注入或发布失败时同步写库。
func (s *Service) writeCollectionRecord(ctx context.Context, record *collectionRecord, _ time.Time) {
if record.Result != constants.TrafficCollectionResultOK {
packages, err := postgres.FindEffectivePackagesAt(writeCtx, s.db, record.IotCardID, observedAt, false)
if err != nil {
s.logTrafficWarn("查询卡采集时刻有效套餐失败,跳过采集记录", zap.Uint("card_id", record.IotCardID), zap.Error(err))
return
}
hasPackage = len(packages.Packages) > 0
}
if !hasPackage {
s.writeCollectionFailure(ctx, record)
return
}
if err := postgres.NewCardTrafficCollectionStore(s.db).Create(writeCtx, &record.CardTrafficCollection); err != nil {
if !record.HasPackage {
return
}
row := &record.CardTrafficCollection
if s.collectionSink != nil {
err := s.collectionSink.PublishCollection(ctx, row, nil)
if err == nil {
return
}
s.logTrafficWarn("发布卡流量采集记录消息失败,改为同步写库", zap.Uint("card_id", record.IotCardID),
zap.String("observation_id", record.ObservationID), zap.Error(err))
}
writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), constants.PollingIngestSyncCollectionTimeout)
defer cancel()
if err := postgres.NewCardTrafficCollectionStore(s.db).Create(writeCtx, row); err != nil {
s.logTrafficWarn("写卡流量采集记录失败", zap.Uint("card_id", record.IotCardID),
zap.String("observation_id", record.ObservationID), zap.Error(err))
}
}
func (s *Service) writeCollectionFailure(ctx context.Context, record *collectionRecord) {
row := &model.CardTrafficCollectionFailure{
IotCardID: record.IotCardID, ObservedAt: record.ObservedAt, ObservationID: record.ObservationID,
Source: record.Source, Scene: record.Scene, Result: record.Result, CollectionRaw: record.CollectionRaw,
ICCID: record.iccid, CarrierID: record.CarrierID,
}
if failure := record.failure; failure != nil {
row.ErrorCategory, row.ProviderCode = failure.ErrorCategory, failure.ProviderCode
row.ProviderMessage, row.DurationMS = truncateText(failure.ProviderMessage, 500), failure.DurationMS
}
writeCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), constants.PollingIngestSyncCollectionTimeout)
defer cancel()
if row.ICCID == "" || row.CarrierID == 0 {
var card model.IotCard
if err := s.db.WithContext(writeCtx).Unscoped().Select("iccid", "carrier_id").Where("id = ?", record.IotCardID).Take(&card).Error; err == nil {
row.ICCID, row.CarrierID = card.ICCID, card.CarrierID
}
}
if s.collectionSink != nil {
err := s.collectionSink.PublishCollection(ctx, nil, row)
if err == nil {
return
}
s.logTrafficWarn("发布卡流量采集失败记录消息失败,改为同步写库", zap.Uint("card_id", record.IotCardID),
zap.String("observation_id", record.ObservationID), zap.Error(err))
}
if err := postgres.NewCardTrafficCollectionFailureStore(s.db).Create(writeCtx, row); err != nil {
s.logTrafficWarn("写卡流量采集失败记录失败", zap.Uint("card_id", record.IotCardID),
zap.String("observation_id", record.ObservationID), zap.Error(err))
}
}
// buildCollectionRaw 把网关原始数据转为留存字段:响应可解析为 JSON 且不超过 4KB 时存 JSON,否则存文本并按 4KB 截断。
func buildCollectionRaw(raw *domain.GatewayRaw) model.CollectionRaw {
if raw == nil {
return model.CollectionRaw{}
}
out := model.CollectionRaw{
GatewayCode: raw.GatewayCode, GatewayMsg: truncateText(raw.GatewayMsg, 500),
GatewayTraceID: truncateText(raw.TraceID, 128), GatewayAttempts: raw.Attempts,
}
if raw.HTTPStatus > 0 {
status := raw.HTTPStatus
out.HTTPStatus = &status
}
if len(raw.Request) > 0 && json.Valid(raw.Request) {
out.RawRequest = datatypes.JSON(raw.Request)
}
switch {
case len(raw.Response) == 0:
case len(raw.Response) > rawResponseMaxBytes:
out.RawResponseText, out.RawTruncated = validUTF8Prefix(raw.Response, rawResponseMaxBytes), true
case json.Valid(raw.Response):
out.RawResponse = datatypes.JSON(raw.Response)
default:
out.RawResponseText = validUTF8Prefix(raw.Response, rawResponseMaxBytes)
}
return out
}
// validUTF8Prefix 返回不超过 limit 字节且不截断多字节字符的前缀,并替换非法 UTF-8(PostgreSQL text 不接受)。
func validUTF8Prefix(data []byte, limit int) string {
if len(data) > limit {
data = data[:limit]
for len(data) > 0 && !utf8.Valid(data) {
data = data[:len(data)-1]
}
}
if !utf8.Valid(data) {
return string([]rune(string(data)))
}
return string(data)
}
func truncateText(value string, limit int) string {
runes := []rune(value)
if len(runes) <= limit {
return value
}
return string(runes[:limit])
}

View File

@@ -45,6 +45,7 @@ type ExtensionService struct {
runtime *merchantpayment.RuntimeLoader
payments PaymentPorts
refunder refundchannel.Refunder
jsapi JSAPIPayer
logger *zap.Logger
now func() time.Time
}
@@ -269,7 +270,21 @@ func (s *ExtensionService) Eligibility(ctx context.Context, usageID uint, scope
if err != nil {
return nil, err
}
return eligibilityResponse(facts), nil
resp := eligibilityResponse(facts)
// 办理延期时一并展示套餐订购时间、到期时间与沉默期截止时间
resp.PackageName = usage.PackageName
resp.PurchasedAt = usage.SilenceStartAt
if resp.PurchasedAt == nil {
createdAt := usage.CreatedAt
resp.PurchasedAt = &createdAt
}
resp.ActivatedAt = usage.ActivatedAt
resp.ExpiresAt = usage.ExpiresAt
resp.SilenceDeadlineAt = usage.SilenceDeadlineAt
if identifier, idErr := assetIdentifier(ctx, s.db, usage); idErr == nil {
resp.AssetIdentifier = identifier
}
return resp, nil
}
// Quote 按输入天数试算付费延期。

View File

@@ -0,0 +1,64 @@
package packagesilence
import (
"context"
"encoding/json"
"strings"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// jsapiContentPrefix 标记支付单 qr_content 里保存的是微信 JSAPI 调起参数(JSON),而不是二维码 / 支付链接。
const jsapiContentPrefix = "jsapi:"
// JSAPIPayer 为 C 端客户按已冻结商户创建微信 JSAPI 预下单(复用套餐购买的公众号 / 小程序支付)。
type JSAPIPayer interface {
CreateJSAPIPayConfig(ctx context.Context, customerID uint, appType string, config *model.WechatConfig,
paymentNo, description string, amount int64) (*dto.ClientPayConfig, error)
}
// SetJSAPIPayer 注入微信 JSAPI 预下单能力;未注入时 H5 微信延期仍走 H5 支付链接。
func (s *ExtensionService) SetJSAPIPayer(payer JSAPIPayer) { s.jsapi = payer }
// useJSAPI 判断本次下单是否走微信内直接支付:H5 客户、微信支付、带应用类型、商户为微信直连(v3 / v2)。
// 富友商户仍走扫码,避免查单与下单协议不一致。
func (s *ExtensionService) useJSAPI(source string, req dto.SilenceOnlineOrderRequest, config *model.WechatConfig) bool {
return s.jsapi != nil && source == constants.SilenceOrderSourceClient && req.PaymentMethod == model.PaymentByWechat &&
strings.TrimSpace(req.AppType) != "" && config != nil &&
(config.ProviderType == model.ProviderTypeWechat || config.ProviderType == model.ProviderTypeWechatV2)
}
// createJSAPIContent 预下单并把调起参数编码成支付单内容,便于"继续支付"复用(预支付有效期 2 小时,长于支付截止)。
func (s *ExtensionService) createJSAPIContent(ctx context.Context, customerID uint, appType string, config *model.WechatConfig, payment *model.Payment) (string, error) {
payConfig, err := s.jsapi.CreateJSAPIPayConfig(ctx, customerID, appType, config, payment.PaymentNo, "沉默期延期", payment.Amount)
if err != nil {
return "", err
}
if payConfig == nil || strings.TrimSpace(payConfig.PackageVal) == "" {
return "", errors.New(errors.CodeWechatPayFailed, "微信支付未返回调起参数")
}
raw, err := json.Marshal(payConfig)
if err != nil {
return "", errors.Wrap(errors.CodeInternalError, err, "编码微信支付参数失败")
}
return jsapiContentPrefix + string(raw), nil
}
// ApplyPaymentContent 把支付单内容写到响应:JSAPI 参数放 pay_config,其余(二维码 / 支付链接)放 qr_content。
func ApplyPaymentContent(resp *dto.SilenceExtensionOrderResponse, content string) {
if resp == nil || content == "" {
return
}
if strings.HasPrefix(content, jsapiContentPrefix) {
var payConfig dto.ClientPayConfig
if err := json.Unmarshal([]byte(strings.TrimPrefix(content, jsapiContentPrefix)), &payConfig); err == nil {
resp.PayConfig = &payConfig
resp.QRContent = ""
}
return
}
resp.QRContent = content
}

View File

@@ -0,0 +1,57 @@
package packagesilence
import (
"context"
"testing"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
type fakeJSAPIPayer struct{}
func (fakeJSAPIPayer) CreateJSAPIPayConfig(context.Context, uint, string, *model.WechatConfig, string, string, int64) (*dto.ClientPayConfig, error) {
return &dto.ClientPayConfig{PackageVal: "prepay_id=wx1"}, nil
}
func TestUseJSAPI(t *testing.T) {
s := &ExtensionService{jsapi: fakeJSAPIPayer{}}
wechatReq := dto.SilenceOnlineOrderRequest{PaymentMethod: model.PaymentByWechat, AppType: "official_account"}
tests := []struct {
name string
svc *ExtensionService
source string
req dto.SilenceOnlineOrderRequest
config *model.WechatConfig
want bool
}{
{"H5 微信直连 v2", s, constants.SilenceOrderSourceClient, wechatReq, &model.WechatConfig{ProviderType: model.ProviderTypeWechatV2}, true},
{"H5 微信直连 v3", s, constants.SilenceOrderSourceClient, wechatReq, &model.WechatConfig{ProviderType: model.ProviderTypeWechat}, true},
{"富友仍走扫码", s, constants.SilenceOrderSourceClient, wechatReq, &model.WechatConfig{ProviderType: model.ProviderTypeFuiou}, false},
{"后台二维码", s, constants.SilenceOrderSourceAdmin, wechatReq, &model.WechatConfig{ProviderType: model.ProviderTypeWechatV2}, false},
{"未带应用类型", s, constants.SilenceOrderSourceClient, dto.SilenceOnlineOrderRequest{PaymentMethod: model.PaymentByWechat}, &model.WechatConfig{ProviderType: model.ProviderTypeWechatV2}, false},
{"支付宝", s, constants.SilenceOrderSourceClient, dto.SilenceOnlineOrderRequest{PaymentMethod: model.PaymentByAlipay, AppType: "official_account"}, &model.WechatConfig{ProviderType: "alipay"}, false},
{"未注入", &ExtensionService{}, constants.SilenceOrderSourceClient, wechatReq, &model.WechatConfig{ProviderType: model.ProviderTypeWechatV2}, false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := tt.svc.useJSAPI(tt.source, tt.req, tt.config); got != tt.want {
t.Fatalf("useJSAPI() = %v, want %v", got, tt.want)
}
})
}
}
func TestApplyPaymentContent(t *testing.T) {
resp := &dto.SilenceExtensionOrderResponse{}
ApplyPaymentContent(resp, `jsapi:{"app_id":"wxA","package":"prepay_id=wx1","pay_sign":"S"}`)
if resp.PayConfig == nil || resp.PayConfig.PackageVal != "prepay_id=wx1" || resp.PayConfig.AppID != "wxA" || resp.QRContent != "" {
t.Fatalf("jsapi content not mapped: %+v", resp)
}
link := &dto.SilenceExtensionOrderResponse{}
ApplyPaymentContent(link, "https://wx.tenpay.com/checkmweb?x=1")
if link.QRContent != "https://wx.tenpay.com/checkmweb?x=1" || link.PayConfig != nil {
t.Fatalf("link content not mapped: %+v", link)
}
}

View File

@@ -101,6 +101,20 @@ func (s *ExtensionService) CreateOnlineOrder(ctx context.Context, command Online
}
return nil, err
}
if s.useJSAPI(source, req, config) {
// H5 客户在微信内用微信支付:走 JSAPI 直接拉起,不生成 H5 支付链接(H5 链接在微信内无法支付)
content, jsapiErr := s.createJSAPIContent(ctx, command.Scope.CustomerID, req.AppType, config, payment)
if jsapiErr != nil {
_ = s.closeOrder(ctx, order.ID, "微信支付参数生成失败")
return nil, jsapiErr
}
if err := s.db.WithContext(ctx).Model(&model.Payment{}).
Where("id = ? AND status = ? AND (qr_content IS NULL OR qr_content = '')", payment.ID, model.PaymentRecordStatusPending).
Update("qr_content", content).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "保存支付内容失败")
}
return s.orderResponse(ctx, order, true)
}
paymentResult, err := adapter.CreatePaymentURL(ctx, agentrechargeApp.OnlinePaymentRequest{
PaymentID: payment.ID, PaymentNo: payment.PaymentNo, CorrelationID: payment.PaymentNo,
Description: "沉默期延期", Amount: payment.Amount, ExpireAt: *payment.ExpireAt,

View File

@@ -0,0 +1,101 @@
package packagesilence
import (
"context"
"strings"
"gorm.io/gorm"
agentrechargeApp "github.com/break/junhong_cmp_fiber/internal/application/agentrecharge"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// CancelOrderCommand 是作废待支付延期订单的命令:Scope.CustomerID 非 0 为 H5 客户作废自己的订单,为 0 为后台运营作废。
type CancelOrderCommand struct {
OrderID uint
Scope Scope
Reason string
}
// CancelPendingOrder 作废未支付的在线延期订单,作废后同一套餐可以重新下单。
//
// 作废前先按冻结商户查单:渠道已支付则按支付成功处理(照常延期)并拒绝作废;
// 其余情况(未支付、渠道无此订单、查单失败)直接关闭。关闭后才到达的支付会进入异常并由恢复任务原路退款,不会吞款。
func (s *ExtensionService) CancelPendingOrder(ctx context.Context, command CancelOrderCommand) (*dto.SilenceExtensionOrderResponse, error) {
if command.Scope.CustomerID == 0 {
if err := s.requirePermission(ctx, constants.PermissionPackageSilenceExtend); err != nil {
return nil, err
}
}
order, err := postgres.NewPackageSilenceOrderStore(s.db).GetByID(ctx, command.OrderID)
if err != nil {
if err == gorm.ErrRecordNotFound {
return nil, errors.New(errors.CodeNotFound, "延期订单不存在")
}
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询延期订单失败")
}
if command.Scope.CustomerID != 0 && (order.CustomerID == nil || *order.CustomerID != command.Scope.CustomerID) {
return nil, errors.New(errors.CodeNotFound, "延期订单不存在")
}
if order.Status != constants.SilenceOrderStatusPendingPayment {
return nil, errors.New(errors.CodeInvalidStatus, "只有待支付的延期订单可以作废")
}
paid, err := s.confirmIfPaid(ctx, order)
if err != nil {
return nil, err
}
if paid {
return nil, errors.New(errors.CodeInvalidStatus, "该订单已支付,已按支付成功办理延期,不能作废")
}
reason := "手动作废"
if command.Scope.CustomerID != 0 {
reason = "客户作废"
}
if extra := strings.TrimSpace(command.Reason); extra != "" {
reason += ":" + extra
}
if err := s.closeOrder(ctx, order.ID, reason); err != nil {
return nil, err
}
current, err := postgres.NewPackageSilenceOrderStore(s.db).GetByID(ctx, order.ID)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询延期订单失败")
}
return s.orderResponse(ctx, current, false)
}
// confirmIfPaid 查询订单下待支付的支付单;渠道已支付时走支付确认并返回 true。查单失败不阻止作废。
func (s *ExtensionService) confirmIfPaid(ctx context.Context, order *model.PackageSilenceExtensionOrder) (bool, error) {
if order.PaymentMethod == model.PaymentByOffline {
return false, nil
}
var payments []model.Payment
if err := s.db.WithContext(ctx).Where("order_type = ? AND order_id = ? AND status = ?", constants.PaymentOrderTypeSilenceExtension, order.ID, model.PaymentRecordStatusPending).
Order("id DESC").Find(&payments).Error; err != nil {
return false, errors.Wrap(errors.CodeDatabaseError, err, "查询延期支付单失败")
}
for index := range payments {
payment := &payments[index]
state, query, err := s.queryPayment(ctx, payment)
if err != nil || state != agentrechargeApp.OnlinePaymentStatePaid {
continue
}
paidAt := s.now()
if query.PaidAt != nil {
paidAt = *query.PaidAt
}
if err := s.ConfirmPayment(ctx, PaymentConfirmCommand{
PaymentNo: payment.PaymentNo, ThirdPartyTradeNo: query.ThirdPartyTradeNo, Amount: query.Amount, PaidAt: paidAt,
}); err != nil {
return false, err
}
return true, nil
}
return false, nil
}

View File

@@ -67,8 +67,9 @@ func (s *ExtensionService) orderResponse(ctx context.Context, order *model.Packa
resp.ThirdPartyTradeNo = payment.ThirdPartyTradeNo
resp.PaymentNo = payment.PaymentNo
}
if includeQR && order.Status == constants.SilenceOrderStatusPendingPayment && payment.Status == model.PaymentRecordStatusPending && resp.QRContent == "" {
resp.QRContent = payment.QRContent
if includeQR && order.Status == constants.SilenceOrderStatusPendingPayment && payment.Status == model.PaymentRecordStatusPending &&
resp.QRContent == "" && resp.PayConfig == nil {
ApplyPaymentContent(resp, payment.QRContent)
resp.PaymentNo = payment.PaymentNo
}
}

View File

@@ -223,6 +223,10 @@ func (r *Resolver) applyExpire(ctx context.Context, tx *gorm.DB, usage *model.Pa
return ResolveResult{Decision: packagedomain.SilenceDecisionExpire, Changed: true, Status: constants.SilenceStatusExpired}, nil
}
// cardRealnameAtExpr 是卡当前实名时间:取卡当前实名记录的实名时间(上游 archiveTime 优先,见 add-realname-time-history);
// 还没有当前实名记录的卡(上线迁移前后的空窗)回退到 first_realname_at。
const cardRealnameAtExpr = "CASE WHEN r.id IS NULL THEN c.first_realname_at ELSE r.realname_at END"
// realnameFacts 是判定所需的资产实名事实(技术方案 §5.1)。
type realnameFacts struct {
realnamed bool
@@ -239,15 +243,16 @@ type boundCardRow struct {
}
// loadRealnameFacts 读取实名事实:
// - 卡:first_realname_at;已实名但时间为空时视为期内实名并补写。
// - 卡:当前实名时间;已实名但时间为空时视为期内实名并补写。
// - 设备:所有已绑定且已实名卡中 max(卡实名时间, 绑定时间) 的最小值,使截止后才绑定的已实名卡不能倒推为期内实名;
// 卡实名时间为空时按绑定时间计并补写卡的实名时间。
func loadRealnameFacts(ctx context.Context, tx *gorm.DB, usage *model.PackageUsage) (realnameFacts, error) {
if usage.DeviceID > 0 {
var rows []boundCardRow
err := tx.WithContext(ctx).Table("tb_device_sim_binding AS b").
Select("c.id AS card_id, c.real_name_status, c.first_realname_at, b.bind_time, b.created_at AS bind_created_at").
Select("c.id AS card_id, c.real_name_status, "+cardRealnameAtExpr+" AS first_realname_at, b.bind_time, b.created_at AS bind_created_at").
Joins("JOIN tb_iot_card AS c ON c.id = b.iot_card_id AND c.deleted_at IS NULL").
Joins("LEFT JOIN tb_iot_card_realname AS r ON r.card_id = c.id").
Where("b.device_id = ? AND b.bind_status = ? AND b.deleted_at IS NULL", usage.DeviceID, constants.BindStatusBound).
Where("c.real_name_status = ?", constants.RealNameStatusVerified).
Scan(&rows).Error
@@ -277,22 +282,25 @@ func loadRealnameFacts(ctx context.Context, tx *gorm.DB, usage *model.PackageUsa
if usage.IotCardID == 0 {
return realnameFacts{}, nil
}
var card model.IotCard
if err := tx.WithContext(ctx).Select("id", "real_name_status", "first_realname_at").
Where("id = ?", usage.IotCardID).First(&card).Error; err != nil {
if err == gorm.ErrRecordNotFound {
return realnameFacts{}, nil
}
var cards []boundCardRow
if err := tx.WithContext(ctx).Table("tb_iot_card AS c").
Select("c.id AS card_id, c.real_name_status, "+cardRealnameAtExpr+" AS first_realname_at").
Joins("LEFT JOIN tb_iot_card_realname AS r ON r.card_id = c.id").
Where("c.id = ?", usage.IotCardID).Limit(1).Scan(&cards).Error; err != nil {
return realnameFacts{}, errors.Wrap(errors.CodeDatabaseError, err, "查询卡实名事实失败")
}
if len(cards) == 0 {
return realnameFacts{}, nil
}
card := cards[0]
facts := realnameFacts{realnamed: card.RealNameStatus == constants.RealNameStatusVerified, realnameAt: card.FirstRealnameAt}
if facts.realnamed && card.FirstRealnameAt == nil {
facts.backfillCardIDs = []uint{card.ID}
facts.backfillCardIDs = []uint{card.CardID}
}
return facts, nil
}
// backfillRealnameAt 为已实名但实名时间为空的卡补写 first_realname_at(只写为空的,返回补写数量)。
// backfillRealnameAt 为已实名但实名时间为空的卡补写实名时间(first_realname_at 与当前实名记录都只写为空的,返回补写数量)。
func backfillRealnameAt(ctx context.Context, tx *gorm.DB, facts realnameFacts, now time.Time) (int64, error) {
if len(facts.backfillCardIDs) == 0 {
return 0, nil
@@ -303,6 +311,9 @@ func backfillRealnameAt(ctx context.Context, tx *gorm.DB, facts realnameFacts, n
if result.Error != nil {
return 0, errors.Wrap(errors.CodeDatabaseError, result.Error, "补写卡实名时间失败")
}
if err := backfillCurrentRealnameAt(ctx, tx, facts.backfillCardIDs, now); err != nil {
return 0, err
}
return result.RowsAffected, nil
}
@@ -326,3 +337,44 @@ func (r *Resolver) AllowActivationInTx(ctx context.Context, tx *gorm.DB, usage *
}
return !result.Blocked(), nil
}
// backfillCurrentRealnameAt 为已实名但当前实名时间为空的卡写入当前实名记录(来源"首次读到",取判定时间)并记一条首次实名历史。
// 二次实名等待中的卡是未实名状态,不会进入这里。
func backfillCurrentRealnameAt(ctx context.Context, tx *gorm.DB, cardIDs []uint, now time.Time) error {
var rows []struct {
CardID uint `gorm:"column:card_id"`
ICCID string `gorm:"column:iccid"`
RecordID *uint `gorm:"column:record_id"`
Realname *time.Time `gorm:"column:realname_at"`
}
if err := tx.WithContext(ctx).Table("tb_iot_card AS c").
Select("c.id AS card_id, c.iccid, r.id AS record_id, r.realname_at").
Joins("LEFT JOIN tb_iot_card_realname AS r ON r.card_id = c.id").
Where("c.id IN ? AND c.real_name_status = ?", cardIDs, constants.RealNameStatusVerified).
Scan(&rows).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "查询卡当前实名记录失败")
}
for _, row := range rows {
if row.Realname != nil {
continue
}
updates := map[string]any{"realname_at": now, "realname_at_source": constants.RealnameAtSourceFirstObserved, "updated_at": now}
if row.RecordID == nil {
record := model.IotCardRealname{CardID: row.CardID, RealnameAt: &now, RealnameAtSource: constants.RealnameAtSourceFirstObserved,
FirstObservedAt: &now, ResetStatus: constants.RealnameResetStatusNone, CreatedAt: now, UpdatedAt: now}
if err := tx.WithContext(ctx).Create(&record).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "补写卡当前实名记录失败")
}
} else if err := tx.WithContext(ctx).Model(&model.IotCardRealname{}).Where("id = ? AND realname_at IS NULL", *row.RecordID).
Updates(updates).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "补写卡当前实名时间失败")
}
history := model.IotCardRealnameHistory{CardID: row.CardID, ICCID: row.ICCID, AfterAt: &now,
AfterSource: constants.RealnameAtSourceFirstObserved, ChangeType: constants.RealnameChangeFirst,
ObservationSource: "package_silence", ObservedAt: now, CreatedAt: now}
if err := tx.WithContext(ctx).Create(&history).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "写入卡实名时间历史失败")
}
}
return nil
}

View File

@@ -0,0 +1,259 @@
// Package realnamereset 提供二次实名批次的导入与撤销用例。
// 二次实名:清除卡的实名状态与当前实名时间,之后只有上游 archiveTime 晚于清除前时间才算重新实名(见 add-realname-time-history)。
package realnamereset
import (
"context"
"crypto/rand"
"fmt"
"math/big"
"strings"
"time"
"github.com/bytedance/sonic"
"gorm.io/gorm"
cardobservationapp "github.com/break/junhong_cmp_fiber/internal/application/cardobservation"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/middleware"
)
// CardResetter 执行单卡二次实名清除与撤销。
type CardResetter interface {
ResetRealname(ctx context.Context, command cardobservationapp.RealnameResetCommand) error
RevertRealnameReset(ctx context.Context, command cardobservationapp.RealnameResetCommand) error
}
// PermissionChecker 校验后台账号权限点。
type PermissionChecker interface {
CheckPermission(ctx context.Context, userID uint, permCode string, platform string) (bool, error)
}
// Service 是二次实名批次用例。
type Service struct {
db *gorm.DB
resetter CardResetter
perms PermissionChecker
now func() time.Time
}
// NewService 创建二次实名批次用例。
func NewService(db *gorm.DB, resetter CardResetter, perms PermissionChecker) *Service {
return &Service{db: db, resetter: resetter, perms: perms, now: time.Now}
}
// resetTarget 是一行资产号展开出的一张卡。
type resetTarget struct {
CardID uint `gorm:"column:id"`
ICCID string `gorm:"column:iccid"`
}
// Import 导入二次实名名单:逐行展开为卡并逐卡清除,不合格的行记录原因跳过,不影响其他行。
func (s *Service) Import(ctx context.Context, req dto.RealnameResetImportRequest) (*dto.RealnameResetBatchResponse, error) {
operatorID, err := s.authorize(ctx)
if err != nil {
return nil, err
}
identifiers := normalizeIdentifiers(req.Identifiers)
if len(identifiers) == 0 {
return nil, errors.New(errors.CodeInvalidParam, "请导入至少一个资产号")
}
if len(identifiers) > constants.RealnameResetBatchMaxRows {
return nil, errors.New(errors.CodeInvalidParam, fmt.Sprintf("单批最多导入 %d 个资产号", constants.RealnameResetBatchMaxRows))
}
now := s.now()
batch := &model.IotCardRealnameResetBatch{
BatchNo: generateBatchNo(now), ImportFileKey: strings.TrimSpace(req.ImportFileKey), Reason: strings.TrimSpace(req.Reason),
Items: []byte("[]"), OperatorID: operatorID, OperatorName: middleware.GetUsernameFromContext(ctx), CreatedAt: now, UpdatedAt: now,
}
if err := s.db.WithContext(ctx).Create(batch).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "创建二次实名批次失败")
}
items := make([]dto.RealnameResetItem, 0, len(identifiers))
seen := make(map[uint]bool)
succeeded, skipped := 0, 0
for index, identifier := range identifiers {
rowNo := index + 1
targets, resolveErr := s.resolveTargets(ctx, identifier)
if resolveErr != nil {
return nil, resolveErr
}
if len(targets) == 0 {
items = append(items, skippedItem(rowNo, identifier, resetTarget{}, "资产不存在或设备未绑定卡"))
skipped++
continue
}
for _, target := range targets {
if seen[target.CardID] {
items = append(items, skippedItem(rowNo, identifier, target, "同一张卡在名单中重复"))
skipped++
continue
}
seen[target.CardID] = true
resetErr := s.resetter.ResetRealname(ctx, cardobservationapp.RealnameResetCommand{CardID: target.CardID, BatchID: batch.ID, OperatorID: operatorID})
switch {
case resetErr == nil:
items = append(items, dto.RealnameResetItem{RowNo: rowNo, Input: identifier, CardID: target.CardID, ICCID: target.ICCID,
Result: constants.RealnameResetItemPending})
succeeded++
case isExpectedResetError(resetErr):
items = append(items, skippedItem(rowNo, identifier, target, errorMessage(resetErr)))
skipped++
default:
items = append(items, dto.RealnameResetItem{RowNo: rowNo, Input: identifier, CardID: target.CardID, ICCID: target.ICCID,
Result: constants.RealnameResetItemFailed, Reason: errorMessage(resetErr)})
skipped++
}
}
}
encoded, err := sonic.Marshal(items)
if err != nil {
return nil, errors.Wrap(errors.CodeInternalError, err, "编码二次实名批次结果失败")
}
batch.Items, batch.TotalCount, batch.SucceededCount, batch.SkippedCount = encoded, len(items), succeeded, skipped
if err := s.db.WithContext(ctx).Model(&model.IotCardRealnameResetBatch{}).Where("id = ?", batch.ID).Updates(map[string]any{
"items": encoded, "total_count": len(items), "succeeded_count": succeeded, "skipped_count": skipped, "updated_at": s.now(),
}).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "更新二次实名批次结果失败")
}
return &dto.RealnameResetBatchResponse{
ID: batch.ID, BatchNo: batch.BatchNo, Reason: batch.Reason, ImportFileKey: batch.ImportFileKey,
TotalCount: len(items), SucceededCount: succeeded, SkippedCount: skipped, PendingCount: succeeded,
OperatorID: operatorID, OperatorName: batch.OperatorName, CreatedAt: batch.CreatedAt, Items: withResultNames(items),
}, nil
}
// Revert 撤销批次中仍在等待二次实名的卡;card_ids 为空时撤销整批。
func (s *Service) Revert(ctx context.Context, req dto.RealnameResetRevertRequest) (*dto.RealnameResetRevertResponse, error) {
operatorID, err := s.authorize(ctx)
if err != nil {
return nil, err
}
var batch model.IotCardRealnameResetBatch
if err := s.db.WithContext(ctx).Select("id").Where("id = ?", req.ID).Take(&batch).Error; err != nil {
if err == gorm.ErrRecordNotFound {
return nil, errors.New(errors.CodeNotFound, "二次实名批次不存在")
}
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询二次实名批次失败")
}
query := s.db.WithContext(ctx).Model(&model.IotCardRealname{}).
Where("reset_batch_id = ? AND reset_status = ?", batch.ID, constants.RealnameResetStatusPending)
if len(req.CardIDs) > 0 {
query = query.Where("card_id IN ?", req.CardIDs)
}
var cardIDs []uint
if err := query.Pluck("card_id", &cardIDs).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询等待二次实名的卡失败")
}
result := &dto.RealnameResetRevertResponse{}
for _, cardID := range cardIDs {
if err := s.resetter.RevertRealnameReset(ctx, cardobservationapp.RealnameResetCommand{CardID: cardID, BatchID: batch.ID, OperatorID: operatorID}); err != nil {
result.FailedCount++
result.Failures = append(result.Failures, fmt.Sprintf("卡 %d:%s", cardID, errorMessage(err)))
continue
}
result.RevertedCount++
}
if result.RevertedCount > 0 {
if err := s.db.WithContext(ctx).Model(&model.IotCardRealnameResetBatch{}).Where("id = ?", batch.ID).Updates(map[string]any{
"reverted_count": gorm.Expr("reverted_count + ?", result.RevertedCount), "updated_at": s.now(),
}).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "更新二次实名批次撤销数失败")
}
}
return result, nil
}
// authorize 二次实名只允许平台账号,且需要 iot_card:realname_reset 权限(超级管理员不受限)。
func (s *Service) authorize(ctx context.Context) (uint, error) {
operatorID := middleware.GetUserIDFromContext(ctx)
switch middleware.GetUserTypeFromContext(ctx) {
case constants.UserTypeSuperAdmin:
return operatorID, nil
case constants.UserTypePlatform:
default:
return 0, errors.New(errors.CodeForbidden, "仅平台账号可办理二次实名")
}
if s.perms == nil {
return 0, errors.New(errors.CodeForbidden)
}
allowed, err := s.perms.CheckPermission(ctx, operatorID, constants.PermissionIotCardRealnameReset, constants.PlatformWeb)
if err != nil {
return 0, err
}
if !allowed {
return 0, errors.New(errors.CodeForbidden, "无二次实名权限")
}
return operatorID, nil
}
// resolveTargets 把资产号展开为卡:先按卡 ICCID / 虚拟号,再按设备虚拟号 / IMEI 取设备当前全部绑定卡。
func (s *Service) resolveTargets(ctx context.Context, identifier string) ([]resetTarget, error) {
var cards []resetTarget
if err := s.db.WithContext(ctx).Table("tb_iot_card").Select("id, iccid").
Where("deleted_at IS NULL AND (iccid = ? OR virtual_no = ?)", identifier, identifier).
Order("id").Limit(1).Scan(&cards).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "按资产号查询卡失败")
}
if len(cards) > 0 {
return cards, nil
}
if err := s.db.WithContext(ctx).Table("tb_device AS d").Select("c.id, c.iccid").
Joins("JOIN tb_device_sim_binding AS b ON b.device_id = d.id AND b.bind_status = ? AND b.deleted_at IS NULL", constants.BindStatusBound).
Joins("JOIN tb_iot_card AS c ON c.id = b.iot_card_id AND c.deleted_at IS NULL").
Where("d.deleted_at IS NULL AND (d.virtual_no = ? OR d.imei = ?)", identifier, identifier).
Order("c.id").Scan(&cards).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "按资产号查询设备绑定卡失败")
}
return cards, nil
}
func normalizeIdentifiers(raw []string) []string {
result := make([]string, 0, len(raw))
seen := make(map[string]bool, len(raw))
for _, value := range raw {
value = strings.TrimSpace(value)
if value == "" || seen[value] {
continue
}
seen[value] = true
result = append(result, value)
}
return result
}
func isExpectedResetError(err error) bool {
return err == cardobservationapp.ErrRealnameResetNotVerified || err == cardobservationapp.ErrRealnameResetNoUpstream ||
err == cardobservationapp.ErrRealnameResetAlreadyReset
}
func errorMessage(err error) string {
if appErr, ok := err.(*errors.AppError); ok && appErr.Message != "" {
return appErr.Message
}
return err.Error()
}
func skippedItem(rowNo int, input string, target resetTarget, reason string) dto.RealnameResetItem {
return dto.RealnameResetItem{RowNo: rowNo, Input: input, CardID: target.CardID, ICCID: target.ICCID,
Result: constants.RealnameResetItemSkipped, Reason: reason}
}
// withResultNames 补结果中文名。
func withResultNames(items []dto.RealnameResetItem) []dto.RealnameResetItem {
for index := range items {
items[index].ResultName = constants.RealnameResetItemName(items[index].Result)
}
return items
}
func generateBatchNo(now time.Time) string {
suffix, err := rand.Int(rand.Reader, big.NewInt(10000))
if err != nil {
suffix = big.NewInt(now.UnixNano() % 10000)
}
return fmt.Sprintf("%s%s%04d", constants.RealnameResetBatchNoPrefix, now.Format("20060102150405"), suffix.Int64())
}

View File

@@ -11,6 +11,7 @@ import (
notificationApp "github.com/break/junhong_cmp_fiber/internal/application/notification"
packageExpiryApp "github.com/break/junhong_cmp_fiber/internal/application/packageexpiry"
packagesilenceApp "github.com/break/junhong_cmp_fiber/internal/application/packagesilence"
realnameresetApp "github.com/break/junhong_cmp_fiber/internal/application/realnamereset"
roleApp "github.com/break/junhong_cmp_fiber/internal/application/role"
shopApp "github.com/break/junhong_cmp_fiber/internal/application/shop"
systemConfigApp "github.com/break/junhong_cmp_fiber/internal/application/systemconfig"
@@ -37,6 +38,7 @@ import (
assetQuery "github.com/break/junhong_cmp_fiber/internal/query/asset"
auditQuery "github.com/break/junhong_cmp_fiber/internal/query/audit"
businessUserGroupQuery "github.com/break/junhong_cmp_fiber/internal/query/businessusergroup"
cardrealnameQuery "github.com/break/junhong_cmp_fiber/internal/query/cardrealname"
distributionwithdrawalQuery "github.com/break/junhong_cmp_fiber/internal/query/distributionwithdrawal"
employeecollectionQuery "github.com/break/junhong_cmp_fiber/internal/query/employeecollection"
exchangeQuery "github.com/break/junhong_cmp_fiber/internal/query/exchange"
@@ -122,6 +124,10 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
deps.Redis,
deps.Logger,
)
// 沉默期延期的 H5 微信支付复用套餐购买的 JSAPI 预下单(微信内直接拉起支付)
if svc.PackageSilence != nil && svc.PackageSilence.Extensions != nil {
svc.PackageSilence.Extensions.SetJSAPIPayer(clientOrderService)
}
systemConfigRegistry := deps.SystemConfigRegistry
if systemConfigRegistry == nil {
systemConfigRegistry = systemConfigInfra.NewRegistry()
@@ -356,7 +362,9 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
pollingSvcPkg.NewPollingStatusImportService(deps.DB, deps.QueueClient, deps.Logger), validate),
CarrierScheduler: admin.NewCarrierSchedulerHandler(pollingSvcPkg.NewCarrierSchedulerService(deps.DB, deps.Redis,
auditInfra.NewWriter(auditInfra.NewRegistry(), nil), carrierSchedulerConfig()), validate),
PollingMonitoring: admin.NewPollingMonitoringHandler(svc.PollingMonitoring),
PollingMonitoring: admin.NewPollingMonitoringHandler(svc.PollingMonitoring),
CardRealname: admin.NewCardRealnameHandler(realnameresetApp.NewService(deps.DB, svc.CardObservation, svc.Permission),
cardrealnameQuery.NewQuery(deps.DB), validate),
PollingAlert: admin.NewPollingAlertHandler(svc.PollingAlert),
PollingCleanup: admin.NewPollingCleanupHandler(svc.PollingCleanup),
PollingManualTrigger: admin.NewPollingManualTriggerHandler(svc.PollingManualTrigger),

View File

@@ -68,6 +68,7 @@ type Handlers struct {
CarrierScheduler *admin.CarrierSchedulerHandler
PollingPause *admin.PollingPauseHandler
PackageSilence *admin.PackageSilenceHandler
CardRealname *admin.CardRealnameHandler
ClientPackageSilence *app.ClientPackageSilenceHandler
PollingConcurrency *admin.PollingConcurrencyHandler
PollingMonitoring *admin.PollingMonitoringHandler

View File

@@ -28,7 +28,9 @@ type ObservationMetadata struct {
type RealnameObservation struct {
CardID uint
Verified bool
Metadata ObservationMetadata
// UpstreamRealnameAt 是上游返回的实名时间 archiveTime;未返回时为 nil。
UpstreamRealnameAt *time.Time
Metadata ObservationMetadata
}
// CardRealnameSnapshot 是应用层从持久化模型映射出的最小卡实名快照。

View File

@@ -0,0 +1,144 @@
package cardobservation
import (
"time"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// RealnameTimeSnapshot 是卡当前实名记录的最小快照;Exists=false 表示还没有当前实名记录。
type RealnameTimeSnapshot struct {
Exists bool
RealnameAt *time.Time
RealnameAtSource string
UpstreamRealnameAt *time.Time
FirstObservedAt *time.Time
ResetStatus string
ResetBaselineAt *time.Time
}
// RealnameResetGate 描述二次实名等待期间对一次"已实名"观测的处理。
type RealnameResetGate int
const (
// RealnameResetGateNone 卡不在等待二次实名,或本次不是已实名观测。
RealnameResetGateNone RealnameResetGate = iota
// RealnameResetGateBlocked 读到的仍是旧实名(或没有上游实名时间),不得改实名状态。
RealnameResetGateBlocked
// RealnameResetGateCompleted 上游实名时间晚于清除前时间,二次实名完成。
RealnameResetGateCompleted
)
// EvaluateRealnameResetGate 判断等待二次实名的卡本次已实名观测是新实名还是旧实名。
// 以上游 archiveTime 为准:晚于清除前的上游实名时间才算新实名;没有上游时间一律视为旧实名。
// 人工纠偏是运营明确操作,不受拦截。
func EvaluateRealnameResetGate(snapshot RealnameTimeSnapshot, observation RealnameObservation) RealnameResetGate {
if !observation.Verified || snapshot.ResetStatus != constants.RealnameResetStatusPending {
return RealnameResetGateNone
}
if observation.Metadata.Source == constants.CardObservationSourceManualOverride {
return RealnameResetGateCompleted
}
upstream := observation.UpstreamRealnameAt
if upstream == nil || snapshot.ResetBaselineAt == nil || !upstream.After(*snapshot.ResetBaselineAt) {
return RealnameResetGateBlocked
}
return RealnameResetGateCompleted
}
// RealnameTimeDecision 描述一次已实名观测后当前实名记录应如何更新。
type RealnameTimeDecision struct {
// Changed 表示当前实名记录有任何字段需要写入(含不写历史的上游最近时间等)。
Changed bool
// RealnameAt / Source 是写入后的当前实名时间与来源。
RealnameAt *time.Time
Source string
// UpstreamRealnameAt / FirstObservedAt 是写入后的值。
UpstreamRealnameAt *time.Time
FirstObservedAt *time.Time
// ClearReset 表示清除二次实名等待状态。
ClearReset bool
// WriteHistory 仅在当前实名时间变化时为 true。
WriteHistory bool
ChangeType string
BeforeAt *time.Time
}
// DecideRealnameTime 根据已被采纳为"已实名"的观测确定当前实名时间:
// 1. 有上游实名时间 → 以它为准(来源 upstream);
// 2. 否则已有当前实名时间 → 保持不变;
// 3. 否则 → 取本次观测时间(来源 first_observed)。
//
// 只有当前实名时间变化才写历史;相同时间只可能静默更新来源或上游最近返回时间。
// 调用方只应在观测被采纳为已实名(卡最终为已实名、且未被二次实名拦截)时调用。
func DecideRealnameTime(snapshot RealnameTimeSnapshot, observation RealnameObservation, gate RealnameResetGate) RealnameTimeDecision {
decision := RealnameTimeDecision{
RealnameAt: snapshot.RealnameAt, Source: snapshot.RealnameAtSource,
UpstreamRealnameAt: snapshot.UpstreamRealnameAt, FirstObservedAt: snapshot.FirstObservedAt,
BeforeAt: snapshot.RealnameAt,
}
if !snapshot.Exists {
decision.Changed = true
}
observedAt := observation.Metadata.ObservedAt
if decision.FirstObservedAt == nil {
decision.FirstObservedAt = timePtr(observedAt)
decision.Changed = true
}
upstream := observation.UpstreamRealnameAt
if upstream != nil && !sameTime(decision.UpstreamRealnameAt, upstream) {
decision.UpstreamRealnameAt = timePtr(*upstream)
decision.Changed = true
}
var next *time.Time
source := decision.Source
switch {
case upstream != nil:
next, source = timePtr(*upstream), constants.RealnameAtSourceUpstream
case snapshot.RealnameAt != nil:
next = snapshot.RealnameAt
default:
next, source = timePtr(observedAt), constants.RealnameAtSourceFirstObserved
}
if gate == RealnameResetGateCompleted {
decision.ClearReset = true
decision.Changed = true
decision.ChangeType = constants.RealnameChangeResetCompleted
}
if !sameTime(snapshot.RealnameAt, next) {
decision.RealnameAt, decision.Source = next, source
decision.Changed = true
decision.WriteHistory = true
if decision.ChangeType == "" {
if snapshot.RealnameAt == nil {
decision.ChangeType = constants.RealnameChangeFirst
} else {
decision.ChangeType = constants.RealnameChangeUpstreamFix
}
}
return decision
}
if source != decision.Source {
// 时间相同只是来源不同(如迁移时间恰好等于上游时间):静默更正来源,不写历史。
decision.Source = source
decision.Changed = true
}
if gate == RealnameResetGateCompleted {
// 二次实名完成但时间未变(理论上不会发生,上游时间一定晚于基准):仍记一条完成历史。
decision.WriteHistory = true
}
return decision
}
func sameTime(left, right *time.Time) bool {
if left == nil || right == nil {
return left == nil && right == nil
}
return left.Equal(*right)
}
func timePtr(value time.Time) *time.Time {
return &value
}

View File

@@ -0,0 +1,149 @@
package cardobservation
import (
"testing"
"time"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
var cst = time.FixedZone("CST", 8*3600)
func at(value string) *time.Time {
parsed, err := time.ParseInLocation("2006-01-02 15:04:05", value, cst)
if err != nil {
panic(err)
}
return &parsed
}
func verifiedObservation(source string, observedAt, upstream *time.Time) RealnameObservation {
return RealnameObservation{CardID: 1, Verified: true, UpstreamRealnameAt: upstream,
Metadata: ObservationMetadata{ObservationID: "o", Source: source, Scene: "s", ObservedAt: *observedAt}}
}
func TestDecideRealnameTime(t *testing.T) {
polling := constants.CardObservationSourcePolling
cases := []struct {
name string
snapshot RealnameTimeSnapshot
observation RealnameObservation
gate RealnameResetGate
wantAt *time.Time
wantSource string
wantHistory bool
wantChange string
wantChanged bool
wantUpstream *time.Time
}{
{
name: "每次轮询读到相同上游时间不写",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: at("2026-07-16 19:43:39"), RealnameAtSource: constants.RealnameAtSourceUpstream,
UpstreamRealnameAt: at("2026-07-16 19:43:39"), FirstObservedAt: at("2026-07-16 20:03:25")},
observation: verifiedObservation(polling, at("2026-11-08 17:10:51"), at("2026-07-16 19:43:39")),
wantAt: at("2026-07-16 19:43:39"), wantSource: constants.RealnameAtSourceUpstream,
wantUpstream: at("2026-07-16 19:43:39"),
},
{
name: "上游更正迁移时间",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: at("2026-07-16 20:03:25"), RealnameAtSource: constants.RealnameAtSourceMigrated,
FirstObservedAt: at("2026-07-16 20:03:25")},
observation: verifiedObservation(polling, at("2026-11-08 17:10:51"), at("2026-07-16 19:43:39")),
wantAt: at("2026-07-16 19:43:39"), wantSource: constants.RealnameAtSourceUpstream,
wantHistory: true, wantChange: constants.RealnameChangeUpstreamFix, wantChanged: true, wantUpstream: at("2026-07-16 19:43:39"),
},
{
name: "不返回时间的运营商首次实名",
snapshot: RealnameTimeSnapshot{},
observation: verifiedObservation(polling, at("2026-11-08 10:00:00"), nil),
wantAt: at("2026-11-08 10:00:00"), wantSource: constants.RealnameAtSourceFirstObserved,
wantHistory: true, wantChange: constants.RealnameChangeFirst, wantChanged: true,
},
{
name: "不返回时间的运营商再次读到不写",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: at("2026-11-08 10:00:00"), RealnameAtSource: constants.RealnameAtSourceFirstObserved,
FirstObservedAt: at("2026-11-08 10:00:00")},
observation: verifiedObservation(polling, at("2026-11-08 12:00:00"), nil),
wantAt: at("2026-11-08 10:00:00"), wantSource: constants.RealnameAtSourceFirstObserved,
},
{
name: "迁移沿用的时间在无上游时间时保持",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: at("2026-09-01 10:00:00"), RealnameAtSource: constants.RealnameAtSourceMigrated,
FirstObservedAt: at("2026-09-01 10:00:00")},
observation: verifiedObservation(polling, at("2026-11-08 12:00:00"), nil),
wantAt: at("2026-09-01 10:00:00"), wantSource: constants.RealnameAtSourceMigrated,
},
{
name: "已实名但无记录的老卡首次读到上游时间",
snapshot: RealnameTimeSnapshot{},
observation: verifiedObservation(polling, at("2026-11-09 00:10:00"), at("2026-08-01 09:00:00")),
wantAt: at("2026-08-01 09:00:00"), wantSource: constants.RealnameAtSourceUpstream,
wantHistory: true, wantChange: constants.RealnameChangeFirst, wantChanged: true, wantUpstream: at("2026-08-01 09:00:00"),
},
{
name: "二次实名完成",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: nil, RealnameAtSource: "", UpstreamRealnameAt: at("2026-07-16 19:43:39"),
FirstObservedAt: at("2026-07-16 20:03:25"), ResetStatus: constants.RealnameResetStatusPending, ResetBaselineAt: at("2026-07-16 19:43:39")},
observation: verifiedObservation(polling, at("2026-11-09 10:05:00"), at("2026-11-09 10:00:00")),
gate: RealnameResetGateCompleted,
wantAt: at("2026-11-09 10:00:00"), wantSource: constants.RealnameAtSourceUpstream,
wantHistory: true, wantChange: constants.RealnameChangeResetCompleted, wantChanged: true, wantUpstream: at("2026-11-09 10:00:00"),
},
{
name: "时间相同只是来源不同静默更正",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: at("2026-07-16 19:43:39"), RealnameAtSource: constants.RealnameAtSourceMigrated,
FirstObservedAt: at("2026-07-16 19:43:39")},
observation: verifiedObservation(polling, at("2026-11-08 17:10:51"), at("2026-07-16 19:43:39")),
wantAt: at("2026-07-16 19:43:39"), wantSource: constants.RealnameAtSourceUpstream, wantChanged: true,
wantUpstream: at("2026-07-16 19:43:39"),
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got := DecideRealnameTime(tc.snapshot, tc.observation, tc.gate)
if !sameTime(got.RealnameAt, tc.wantAt) || got.Source != tc.wantSource {
t.Fatalf("realname_at=%v source=%s, want %v %s", got.RealnameAt, got.Source, tc.wantAt, tc.wantSource)
}
if got.WriteHistory != tc.wantHistory || got.ChangeType != tc.wantChange {
t.Fatalf("history=%v change=%s, want %v %s", got.WriteHistory, got.ChangeType, tc.wantHistory, tc.wantChange)
}
if got.Changed != tc.wantChanged {
t.Fatalf("changed=%v, want %v", got.Changed, tc.wantChanged)
}
if tc.wantUpstream != nil && !sameTime(got.UpstreamRealnameAt, tc.wantUpstream) {
t.Fatalf("upstream=%v, want %v", got.UpstreamRealnameAt, tc.wantUpstream)
}
if tc.gate == RealnameResetGateCompleted && !got.ClearReset {
t.Fatal("reset completion must clear reset state")
}
})
}
}
func TestEvaluateRealnameResetGate(t *testing.T) {
pending := RealnameTimeSnapshot{Exists: true, ResetStatus: constants.RealnameResetStatusPending, ResetBaselineAt: at("2026-07-16 19:43:39")}
polling := constants.CardObservationSourcePolling
now := at("2026-11-09 10:05:00")
cases := []struct {
name string
snapshot RealnameTimeSnapshot
observation RealnameObservation
want RealnameResetGate
}{
{"不在等待", RealnameTimeSnapshot{Exists: true}, verifiedObservation(polling, now, nil), RealnameResetGateNone},
{"读到旧实名", pending, verifiedObservation(polling, now, at("2026-07-16 19:43:39")), RealnameResetGateBlocked},
{"读到更早实名", pending, verifiedObservation(polling, now, at("2026-07-01 00:00:00")), RealnameResetGateBlocked},
{"没有上游时间", pending, verifiedObservation(polling, now, nil), RealnameResetGateBlocked},
{"回调没有时间", pending, verifiedObservation(constants.CardObservationSourceCarrierCallback, now, nil), RealnameResetGateBlocked},
{"新实名", pending, verifiedObservation(polling, now, at("2026-11-09 10:00:00")), RealnameResetGateCompleted},
{"人工改为已实名", pending, verifiedObservation(constants.CardObservationSourceManualOverride, now, nil), RealnameResetGateCompleted},
{"未实名观测", pending, RealnameObservation{CardID: 1, Metadata: ObservationMetadata{Source: polling, ObservedAt: *now}}, RealnameResetGateNone},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if got := EvaluateRealnameResetGate(tc.snapshot, tc.observation); got != tc.want {
t.Fatalf("got %v, want %v", got, tc.want)
}
})
}
}

View File

@@ -16,6 +16,32 @@ type TrafficObservation struct {
ReadingResult string
ResetDay int
Metadata ObservationMetadata
// Raw 是本次网关调用的原始请求与响应,未收集时为 nil。
Raw *GatewayRaw
// Failure 是读数结果非 ok 时的失败详情,未提供时为 nil。
Failure *CollectionFailure
// ICCID、CarrierID 是调用方已知的卡标识,写采集失败记录时直接使用;为空时由观测用例查库补齐。
ICCID string
CarrierID uint
}
// 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 描述一次流量观测的处理结果。

View File

@@ -61,7 +61,7 @@ func (s *IotCardDataSource) Fetch(ctx context.Context, params ExportParams, offs
COALESCE(d.device_name, '') AS device_name,
c.real_name_status,
c.enable_polling,
c.first_realname_at,
CASE WHEN rn.id IS NULL THEN c.first_realname_at ELSE rn.realname_at END AS first_realname_at,
c.first_purchase_at,
c.network_status,
COALESCE(pkg.package_name, '') AS package_name,
@@ -169,6 +169,7 @@ func (s *IotCardDataSource) baseQuery(ctx context.Context) *gorm.DB {
return s.db.WithContext(ctx).
Table("tb_iot_card AS c").
Joins("LEFT JOIN tb_shop AS sh ON sh.id = c.shop_id").
Joins("LEFT JOIN tb_iot_card_realname AS rn ON rn.card_id = c.id").
Joins(`
LEFT JOIN LATERAL (
SELECT d.device_name

View File

@@ -114,6 +114,10 @@ func (c *Client) doRequest(ctx context.Context, path string, params interface{})
return nil, errors.Wrap(errors.CodeInternalError, err, "序列化业务数据失败")
}
if capture := rawCaptureFrom(ctx); capture != nil {
capture.Request = append(json.RawMessage(nil), dataBytes...)
}
// 加密业务数据(加密结果不变,可在重试间复用)
encryptedData, err := aesEncrypt(dataBytes, c.appSecret)
if err != nil {
@@ -184,8 +188,13 @@ func (c *Client) executeWithRetry(ctx context.Context, path, encryptedData strin
return nil, err
}
}
capture := rawCaptureFrom(ctx)
if capture != nil {
capture.resetResponse()
capture.Attempts = attemptNumber
}
attemptStartedAt := time.Now()
result, retryable, err := c.executeHTTPRequest(ctx, path, encryptedData)
result, retryable, err := c.executeHTTPRequest(ctx, path, encryptedData, capture != nil && logPayload)
attemptDuration := time.Since(attemptStartedAt)
if gwErr, ok := AsGatewayError(err); ok {
gwErr.Duration = attemptDuration
@@ -237,7 +246,12 @@ func (c *Client) executeWithRetry(ctx context.Context, path, encryptedData strin
// executeHTTPRequest 执行单次 HTTP 请求(无重试逻辑)
// 返回值:响应数据、是否可重试、错误
func (c *Client) executeHTTPRequest(ctx context.Context, path string, encryptedData string) (json.RawMessage, bool, error) {
// captureRaw 为 true 时把状态码、响应体与外层字段写入上下文上的原始数据收集器。
func (c *Client) executeHTTPRequest(ctx context.Context, path string, encryptedData string, captureRaw bool) (json.RawMessage, bool, error) {
var capture *RawCapture
if captureRaw {
capture = rawCaptureFrom(ctx)
}
// 每次重试使用新的时间戳和签名
timestamp := time.Now().Unix()
sign := generateSign(c.appID, encryptedData, timestamp, c.appSecret)
@@ -277,6 +291,9 @@ func (c *Client) executeHTTPRequest(ctx context.Context, path string, encryptedD
return nil, true, newGatewayError(constants.GatewayErrorNetwork, errors.Wrap(errors.CodeGatewayError, err, "发送 HTTP 请求失败"))
}
defer resp.Body.Close()
if capture != nil {
capture.HTTPStatus = resp.StatusCode
}
// HTTP 状态码错误 — 不可重试
if resp.StatusCode != http.StatusOK {
@@ -290,10 +307,18 @@ func (c *Client) executeHTTPRequest(ctx context.Context, path string, encryptedD
return nil, false, newGatewayError(constants.GatewayErrorInvalidResponse, errors.Wrap(errors.CodeGatewayInvalidResp, err, "读取响应体失败"))
}
if capture != nil {
capture.Response = body
}
var gatewayResp GatewayResponse
if err := sonic.Unmarshal(body, &gatewayResp); err != nil {
return nil, false, newGatewayError(constants.GatewayErrorInvalidResponse, errors.Wrap(errors.CodeGatewayInvalidResp, err, "解析 Gateway 响应失败"))
}
if capture != nil {
code := gatewayResp.Code
capture.GatewayCode, capture.GatewayMsg, capture.TraceID = &code, gatewayResp.Msg, gatewayResp.TraceID
}
// Gateway 业务错误 — 不可重试
if gatewayResp.Code != gatewaySuccessCode {

View File

@@ -5,6 +5,7 @@ import (
"encoding/json"
"strconv"
"strings"
"time"
)
// FlexBool 灵活布尔类型
@@ -206,8 +207,17 @@ type CardOperationReq struct {
// RealnameStatusResp 是实名认证状态的响应
type RealnameStatusResp struct {
ICCID string `json:"iccid" description:"ICCID"`
RealStatus bool `json:"realStatus" description:"实名状态(true=已实名, false=未实名)"`
ICCID string `json:"iccid" description:"ICCID"`
RealStatus bool `json:"realStatus" description:"实名状态(true=已实名, false=未实名)"`
ArchiveTime *string `json:"archiveTime,omitempty" description:"上游实名时间(YYYY-MM-DD HH:mm:ss,北京时间;部分运营商不返回)"`
}
// UpstreamRealnameAt 返回上游实名时间:仅已实名且 archiveTime 可解析时有值;缺失、空、格式错误或未实名时返回 nil。
func (r *RealnameStatusResp) UpstreamRealnameAt() *time.Time {
if r == nil || !r.RealStatus || r.ArchiveTime == nil {
return nil
}
return parseUpstreamTime(*r.ArchiveTime)
}
// RealnameLinkResp 是实名认证链接的响应

View File

@@ -0,0 +1,44 @@
package gateway
import (
"context"
"encoding/json"
)
// RawCapture 收集一次网关调用的原始数据(最后一次 HTTP 尝试),供业务记录留存。
// 只保存加密前的明文业务请求与网关响应;不含加密报文、签名、应用标识、密钥与请求头。
type RawCapture struct {
// Request 是加密前的明文业务请求({"params": ...});不记录载荷的调用为空。
Request json.RawMessage
// HTTPStatus 是 HTTP 状态码;没拿到响应(超时、连接失败)时为 0。
HTTPStatus int
// Response 是网关原始响应体;没拿到响应体时为空。
Response []byte
// GatewayCode、GatewayMsg、TraceID 是网关响应外层字段;响应无法解析时为空。
GatewayCode *int
GatewayMsg string
TraceID string
// Attempts 是网关客户端内部 HTTP 尝试次数。
Attempts int
}
type rawCaptureKey struct{}
// WithRawCapture 在请求上下文上挂载原始数据收集器;未挂载的调用不收集。
func WithRawCapture(ctx context.Context) (context.Context, *RawCapture) {
capture := &RawCapture{}
return context.WithValue(ctx, rawCaptureKey{}, capture), capture
}
func rawCaptureFrom(ctx context.Context) *RawCapture {
capture, _ := ctx.Value(rawCaptureKey{}).(*RawCapture)
return capture
}
// resetResponse 在每次 HTTP 尝试前清空上一次的响应,保证留存的是最后一次尝试。
func (c *RawCapture) resetResponse() {
if c == nil {
return
}
c.HTTPStatus, c.Response, c.GatewayCode, c.GatewayMsg, c.TraceID = 0, nil, nil, "", ""
}

View File

@@ -0,0 +1,25 @@
package gateway
import (
"strings"
"time"
)
// upstreamLocation 是上游时间字段的时区(北京时间,固定 +08:00,不依赖系统时区数据库)。
var upstreamLocation = time.FixedZone("CST", 8*3600)
var upstreamTimeLayouts = []string{"2006-01-02 15:04:05", "2006-01-02T15:04:05", "2006/01/02 15:04:05"}
// parseUpstreamTime 按北京时间解析上游时间字符串,空或无法解析返回 nil。
func parseUpstreamTime(raw string) *time.Time {
value := strings.TrimSpace(raw)
if value == "" || strings.EqualFold(value, "null") {
return nil
}
for _, layout := range upstreamTimeLayouts {
if parsed, err := time.ParseInLocation(layout, value, upstreamLocation); err == nil {
return &parsed
}
}
return nil
}

View File

@@ -0,0 +1,42 @@
package gateway
import (
"encoding/json"
"testing"
"time"
)
func TestRealnameStatusRespUpstreamRealnameAt(t *testing.T) {
cases := []struct {
name string
body string
want string
}{
{"移动返回实名时间", `{"archiveTime":"2026-07-16 19:43:39","iccid":"89860885192590574640","realStatus":true}`, "2026-07-16T19:43:39+08:00"},
{"电信不返回", `{"iccid":"8986112520903884400","realStatus":true}`, ""},
{"联通 extend 无时间", `{"extend":"已实名","iccid":"89860625750010460562","realStatus":true}`, ""},
{"未实名 null", `{"archiveTime":null,"iccid":"898608851925D1284902","realStatus":false}`, ""},
{"未实名但带时间忽略", `{"archiveTime":"2026-07-16 19:43:39","realStatus":false}`, ""},
{"空串", `{"archiveTime":"","realStatus":true}`, ""},
{"格式错误", `{"archiveTime":"07/16/2026","realStatus":true}`, ""},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
var resp RealnameStatusResp
if err := json.Unmarshal([]byte(tc.body), &resp); err != nil {
t.Fatalf("unmarshal: %v", err)
}
got := resp.UpstreamRealnameAt()
if tc.want == "" {
if got != nil {
t.Fatalf("want nil, got %v", got)
}
return
}
want, _ := time.Parse(time.RFC3339, tc.want)
if got == nil || !got.Equal(want) {
t.Fatalf("want %v, got %v", want, got)
}
})
}
}

View File

@@ -13,6 +13,8 @@ import (
"strings"
"github.com/bytedance/sonic"
auditinfra "github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
)
// Entry 是一个必须经过审计分类的 HTTP、Worker 或定时任务入口。
@@ -46,6 +48,9 @@ type Entry struct {
// Scan 扫描当前仓库中对外 HTTP、Asynq Worker 和定时任务注册入口。
func Scan(root string) ([]Entry, error) {
if missing := auditinfra.NewRegistry().MachineActionsWithoutPolicy(); len(missing) > 0 {
return nil, fmt.Errorf("以下可由系统任务或定时任务发起的审计动作未声明落库策略:%s", strings.Join(missing, ", "))
}
var entries []Entry
files := []string{
"internal/routes", "internal/application", "internal/domain", "internal/service",
@@ -201,7 +206,7 @@ func classifyWorker(file string, line int, taskType, handler string) Entry {
entry := Entry{
Key: fmt.Sprintf("worker:%s:%d:%s", file, line, taskType), Kind: "worker",
CodeEntry: fmt.Sprintf("%s:%d %s", file, line, handler), Owner: owner,
Summary: "处理异步任务 " + taskType, AuditEvent: "按状态变化、人工触发、连续失败或高风险异常决定",
Summary: "处理异步任务 " + taskType, AuditEvent: "按审计注册表落库策略决定:系统任务未声明策略时只写应用日志",
DomainLedger: ledgerDecision(owner), IntegrationLog: workerIntegrationDecision(taskType),
Outbox: "任务来源 Outbox/业务任务事实;消费端按稳定事件或任务 ID 幂等",
ActionCode: actionCode(owner, handler), ActionName: "处理异步任务(" + taskType + ")",

View File

@@ -0,0 +1,128 @@
package admin
import (
"github.com/go-playground/validator/v10"
"github.com/gofiber/fiber/v2"
"github.com/break/junhong_cmp_fiber/internal/application/realnamereset"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/internal/query/cardrealname"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/response"
)
// CardRealnameHandler 处理卡实名记录与二次实名批次。
type CardRealnameHandler struct {
reset *realnamereset.Service
query *cardrealname.Query
validator *validator.Validate
}
// NewCardRealnameHandler 创建卡实名记录处理器。
func NewCardRealnameHandler(reset *realnamereset.Service, query *cardrealname.Query, validate *validator.Validate) *CardRealnameHandler {
if validate == nil {
validate = validator.New()
}
return &CardRealnameHandler{reset: reset, query: query, validator: validate}
}
func (h *CardRealnameHandler) validate(prefix string, req any) error {
if err := h.validator.Struct(req); err != nil {
return errors.New(errors.CodeInvalidParam, validationMessage(prefix, req, err))
}
return nil
}
// CardHistory 查询单卡当前实名时间与实名时间历史。
// GET /api/admin/iot-cards/:id/realname-history
func (h *CardRealnameHandler) CardHistory(c *fiber.Ctx) error {
var req dto.CardRealnameHistoryListRequest
if err := c.QueryParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
id, err := rateLimitPathID(c, "id", "IoT 卡 ID")
if err != nil {
return err
}
req.ID = id
if err := h.validate("实名记录查询参数不合法", &req); err != nil {
return err
}
result, err := h.query.CardHistory(c.UserContext(), req)
if err != nil {
return err
}
return response.Success(c, result)
}
// ImportResetBatch 导入二次实名名单。
// POST /api/admin/realname-reset/batches
func (h *CardRealnameHandler) ImportResetBatch(c *fiber.Ctx) error {
var req dto.RealnameResetImportRequest
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
if err := h.validate("二次实名导入参数不合法", &req); err != nil {
return err
}
result, err := h.reset.Import(c.UserContext(), req)
if err != nil {
return err
}
return response.Success(c, result)
}
// ListResetBatches 分页查询二次实名批次。
// GET /api/admin/realname-reset/batches
func (h *CardRealnameHandler) ListResetBatches(c *fiber.Ctx) error {
var req dto.RealnameResetBatchListRequest
if err := c.QueryParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
if err := h.validate("二次实名批次查询参数不合法", &req); err != nil {
return err
}
list, total, page, size, err := h.query.ListResetBatches(c.UserContext(), req)
if err != nil {
return err
}
return response.SuccessWithPagination(c, list, total, page, size)
}
// GetResetBatch 查询二次实名批次详情。
// GET /api/admin/realname-reset/batches/:id
func (h *CardRealnameHandler) GetResetBatch(c *fiber.Ctx) error {
id, err := rateLimitPathID(c, "id", "批次 ID")
if err != nil {
return err
}
result, err := h.query.GetResetBatch(c.UserContext(), id)
if err != nil {
return err
}
return response.Success(c, result)
}
// RevertResetBatch 撤销批次中仍在等待二次实名的卡。
// POST /api/admin/realname-reset/batches/:id/revert
func (h *CardRealnameHandler) RevertResetBatch(c *fiber.Ctx) error {
var req dto.RealnameResetRevertRequest
if len(c.Body()) > 0 {
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
}
}
id, err := rateLimitPathID(c, "id", "批次 ID")
if err != nil {
return err
}
req.ID = id
if err := h.validate("二次实名撤销参数不合法", &req); err != nil {
return err
}
result, err := h.reset.Revert(c.UserContext(), req)
if err != nil {
return err
}
return response.Success(c, result)
}

View File

@@ -259,6 +259,31 @@ func (h *PackageSilenceHandler) GetOrder(c *fiber.Ctx) error {
return response.Success(c, result)
}
// CloseOrder 作废待支付的延期订单。POST /api/admin/package-silence/orders/:id/close
func (h *PackageSilenceHandler) CloseOrder(c *fiber.Ctx) error {
id, err := silencePathID(c)
if err != nil {
return err
}
var req dto.SilenceOrderCancelRequest
if len(c.Body()) > 0 {
if err := h.bindBody(c, "作废参数不合法", &req); err != nil {
return err
}
}
// 先按数据范围查详情:看不到的订单不能作废
if _, err := h.query.GetOrder(c.UserContext(), id, 0); err != nil {
return err
}
result, err := h.extensions.CancelPendingOrder(c.UserContext(), packagesilenceapp.CancelOrderCommand{
OrderID: id, Reason: req.Reason,
})
if err != nil {
return err
}
return response.Success(c, result)
}
// SubmitSpecial 提交特殊延期(单个 / 批量)。POST /api/admin/package-silence/special
func (h *PackageSilenceHandler) SubmitSpecial(c *fiber.Ctx) error {
var req dto.SilenceSpecialRequest

View File

@@ -37,7 +37,12 @@ func (h *PackageUsageHandler) GetDailyRecords(c *fiber.Ctx) error {
endDate := c.Query("end_date", "")
// 任务 16.4: 调用 DailyRecordService.GetDailyRecords 获取日记录
records, err := h.dailyRecordService.GetDailyRecords(c.UserContext(), uint(id), startDate, endDate)
page := c.QueryInt("page", 0)
pageSize := c.QueryInt("page_size", 0)
if page < 0 || pageSize < 0 || pageSize > 100 {
return errors.New(errors.CodeInvalidParam, "分页参数不合法,page_size 最大 100")
}
records, err := h.dailyRecordService.GetDailyRecords(c.UserContext(), uint(id), startDate, endDate, page, pageSize)
if err != nil {
return err
}

View File

@@ -0,0 +1,94 @@
package admin
import (
"github.com/gofiber/fiber/v2"
"github.com/break/junhong_cmp_fiber/internal/handler/validation"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/response"
)
// parseRecordQuery 解析并校验记录查询参数。
func (h *AssetHandler) parseRecordQuery(c *fiber.Ctx, req any, label string) error {
if err := rejectEnterpriseAssetAdmin(c); err != nil {
return err
}
if err := c.QueryParser(req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数格式不正确")
}
if err := h.validator.Struct(req); err != nil {
return errors.New(errors.CodeInvalidParam, validation.Message(label, req, err))
}
return nil
}
// ListTrafficCollectionRecords 采集成功记录列表
// GET /api/admin/traffic-collections
func (h *AssetHandler) ListTrafficCollectionRecords(c *fiber.Ctx) error {
var req dto.TrafficCollectionListRequest
if err := h.parseRecordQuery(c, &req, "采集成功记录查询参数不合法"); err != nil {
return err
}
result, err := h.assetService.ListTrafficCollectionRecords(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// ListTrafficCollectionFailures 采集失败记录列表
// GET /api/admin/traffic-collection-failures
func (h *AssetHandler) ListTrafficCollectionFailures(c *fiber.Ctx) error {
var req dto.TrafficCollectionFailureListRequest
if err := h.parseRecordQuery(c, &req, "采集失败记录查询参数不合法"); err != nil {
return err
}
result, err := h.assetService.ListTrafficCollectionFailures(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// ListCardDailyUsages 卡日流量列表
// GET /api/admin/card-daily-usages
func (h *AssetHandler) ListCardDailyUsages(c *fiber.Ctx) error {
var req dto.CardDailyUsageListRequest
if err := h.parseRecordQuery(c, &req, "卡日流量查询参数不合法"); err != nil {
return err
}
result, err := h.assetService.ListCardDailyUsages(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// ListPackageUsageDailyRecords 套餐日流量详单列表
// GET /api/admin/package-usage-daily-records
func (h *AssetHandler) ListPackageUsageDailyRecords(c *fiber.Ctx) error {
var req dto.PackageUsageDailyRecordListRequest
if err := h.parseRecordQuery(c, &req, "套餐日流量详单查询参数不合法"); err != nil {
return err
}
result, err := h.assetService.ListPackageUsageDailyRecords(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// ListPackageTrafficAdjustmentRecords 套餐流量冲正流水列表
// GET /api/admin/package-traffic-adjustments
func (h *AssetHandler) ListPackageTrafficAdjustmentRecords(c *fiber.Ctx) error {
var req dto.PackageTrafficAdjustmentQueryRequest
if err := h.parseRecordQuery(c, &req, "冲正流水查询参数不合法"); err != nil {
return err
}
result, err := h.assetService.ListPackageTrafficAdjustmentRecords(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}

View File

@@ -97,6 +97,37 @@ func (h *RefundHandler) RecoverApproval(c *fiber.Ctx) error {
return response.Success(c, result)
}
// RetryAssetPostProcessing 人工重试退款资产后处理
// POST /api/admin/refunds/:id/asset-post-processing/retry
func (h *RefundHandler) RetryAssetPostProcessing(c *fiber.Ctx) error {
id, err := strconv.ParseUint(c.Params("id"), 10, 64)
if err != nil || id == 0 {
return errors.New(errors.CodeInvalidParam, "无效的退款申请ID")
}
result, err := h.service.RetryAssetPostProcessingByAdmin(c.UserContext(), uint(id))
if err != nil {
return err
}
return response.Success(c, result)
}
// ListAssetPostProcessAttempts 退款资产后处理尝试记录列表
// GET /api/admin/refund-post-process-attempts
func (h *RefundHandler) ListAssetPostProcessAttempts(c *fiber.Ctx) error {
var req dto.RefundPostProcessAttemptListRequest
if err := c.QueryParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam, "请求参数格式不正确")
}
if req.StartTime == "" || req.EndTime == "" {
return errors.New(errors.CodeInvalidParam, "开始时间与结束时间必填")
}
result, err := h.service.ListAssetPostProcessAttempts(c.UserContext(), &req)
if err != nil {
return err
}
return response.Success(c, result)
}
// Approve 审批通过退款申请
// POST /api/admin/refunds/:id/approve
func (h *RefundHandler) Approve(c *fiber.Ctx) error {

View File

@@ -801,6 +801,15 @@ func packageStatusName(status int) string {
}
}
// clientDeviceLANIP 网关未返回局域网网关地址(空或仅空白)时使用设备默认网关地址,保证 C 端可进入设备后台。
func clientDeviceLANIP(lanIP *string) *string {
if lanIP != nil && strings.TrimSpace(*lanIP) != "" {
return lanIP
}
defaultIP := constants.DefaultDeviceLANIP
return &defaultIP
}
// mapDeviceGatewayInfoToClientInfo 将 B 端 DeviceGatewayInfo 映射为 C 端 DeviceRealtimeInfo
// B 端和 C 端结构独立,通过映射函数转换(per D-08)
func mapDeviceGatewayInfoToClientInfo(g *dto.DeviceGatewayInfo) *dto.DeviceRealtimeInfo {
@@ -844,7 +853,7 @@ func mapDeviceGatewayInfoToClientInfo(g *dto.DeviceGatewayInfo) *dto.DeviceRealt
info.WifiPassword = g.WifiPassword
info.IPAddress = g.IPAddress
info.WANIP = g.WANIP
info.LANIP = g.LANIP
info.LANIP = clientDeviceLANIP(g.LANIP)
info.MACAddress = g.MACAddress
info.DailyUsage = g.DailyUsage
info.DLStats = g.DLStats

View File

@@ -0,0 +1,39 @@
package app
import (
"testing"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
func TestMapDeviceGatewayInfoToClientInfo_LANIPDefault(t *testing.T) {
strPtr := func(s string) *string { return &s }
cases := []struct {
name string
lanIP *string
want string
}{
{name: "网关未返回", lanIP: nil, want: constants.DefaultDeviceLANIP},
{name: "空字符串", lanIP: strPtr(""), want: constants.DefaultDeviceLANIP},
{name: "仅空白", lanIP: strPtr(" "), want: constants.DefaultDeviceLANIP},
{name: "网关有值", lanIP: strPtr("192.168.0.1"), want: "192.168.0.1"},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
info := mapDeviceGatewayInfoToClientInfo(&dto.DeviceGatewayInfo{LANIP: tc.lanIP})
if info.LANIP == nil || *info.LANIP != tc.want {
t.Fatalf("期望 %q,实际 %v", tc.want, info.LANIP)
}
})
}
}
// 网关调用失败时同样返回默认地址,前端仍可进入设备后台。
func TestMapDeviceGatewayInfoToClientInfo_GatewayFailedStillDefaultLANIP(t *testing.T) {
msg := "网关调用失败"
info := mapDeviceGatewayInfoToClientInfo(&dto.DeviceGatewayInfo{GatewayMsg: &msg})
if info.LANIP == nil || *info.LANIP != constants.DefaultDeviceLANIP {
t.Fatalf("期望默认地址,实际 %v", info.LANIP)
}
}

View File

@@ -145,6 +145,31 @@ func (h *ClientPackageSilenceHandler) GetOrder(c *fiber.Ctx) error {
return response.Success(c, result)
}
// CancelOrder 客户作废自己未支付的延期订单。POST /api/c/v1/package-silence/orders/:id/cancel
func (h *ClientPackageSilenceHandler) CancelOrder(c *fiber.Ctx) error {
id, err := c.ParamsInt("id")
if err != nil || id <= 0 {
return errors.New(errors.CodeInvalidParam)
}
var req dto.SilenceOrderCancelRequest
if len(c.Body()) > 0 {
if err := c.BodyParser(&req); err != nil {
return errors.New(errors.CodeInvalidParam)
}
}
ctx, customerID, err := h.customerContext(c)
if err != nil {
return err
}
result, err := h.extensions.CancelPendingOrder(ctx, packagesilenceapp.CancelOrderCommand{
OrderID: uint(id), Scope: packagesilenceapp.Scope{CustomerID: customerID}, Reason: req.Reason,
})
if err != nil {
return err
}
return response.Success(c, result)
}
// ListRecords 套餐沉默期流水。GET /api/c/v1/package-silence/records
func (h *ClientPackageSilenceHandler) ListRecords(c *fiber.Ctx) error {
var req dto.SilenceRecordListRequest

View File

@@ -0,0 +1,130 @@
package audit
import (
"context"
"strings"
"sync/atomic"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/logger"
"github.com/break/junhong_cmp_fiber/pkg/sanitizer"
)
// persistDecision 是一次审计写入的去向。
type persistDecision int
const (
decisionWrite persistDecision = iota
decisionLog
decisionSkip
)
// auditLoggerName 是应用日志中审计行的固定 logger 名,日志同步端按它过滤。
const auditLoggerName = "audit"
// persistOverrides 是运行时按动作覆盖的落库策略(只作用于系统任务、定时任务操作者)。
var persistOverrides atomic.Pointer[map[string]PersistPolicy]
// SetPersistOverrides 解析并设置运行时覆盖,格式为 "动作编码=策略,动作编码=策略";返回被忽略的非法项。
func SetPersistOverrides(raw string) []string {
overrides := map[string]PersistPolicy{}
var invalid []string
for _, item := range strings.Split(raw, ",") {
item = strings.TrimSpace(item)
if item == "" {
continue
}
code, policy, ok := strings.Cut(item, "=")
code, policy = strings.TrimSpace(code), strings.TrimSpace(policy)
if !ok || code == "" || !validPersistPolicy(PersistPolicy(policy)) {
invalid = append(invalid, item)
continue
}
overrides[code] = PersistPolicy(policy)
}
persistOverrides.Store(&overrides)
return invalid
}
// effectivePolicy 返回机器操作者下动作实际采用的策略:运行时覆盖 > 注册表声明 > 默认只写应用日志。
func effectivePolicy(action ActionDefinition) PersistPolicy {
if overrides := persistOverrides.Load(); overrides != nil {
if policy, ok := (*overrides)[action.Code]; ok {
return policy
}
}
if action.Persist != "" {
return action.Persist
}
return PersistLogOnly
}
// decidePersist 按"动作 × 操作者"决定写表、写应用日志还是跳过;人工与外部操作者始终写表。
func decidePersist(action ActionDefinition, input AppendInput) persistDecision {
if !isMachineActor(input.Actor.Kind) {
return decisionWrite
}
switch effectivePolicy(action) {
case PersistAlways:
return decisionWrite
case PersistOnSuccess:
if input.Result == constants.AuditResultSuccess {
return decisionWrite
}
return decisionLog
case PersistOutcome:
if input.Final {
return decisionWrite
}
return decisionLog
case PersistNone:
return decisionSkip
default:
return decisionLog
}
}
// writeAuditLog 把未落表的审计写成一行应用日志;只含标识类字段,不含快照与主体数据。
func writeAuditLog(ctx context.Context, action ActionDefinition, input AppendInput) {
resourceType, resourceKey := primaryResource(input)
fields := []zap.Field{
zap.String("action_code", action.Code),
zap.String("actor_kind", input.Actor.Kind),
zap.String("actor_id", input.Actor.ID),
zap.String("source", input.Source),
zap.String("result", input.Result),
zap.String("resource_type", resourceType),
zap.String("resource_key", resourceKey),
zap.String("correlation_id", input.CorrelationID),
zap.String("request_id", input.RequestID),
zap.String("error_code", input.ErrorCode),
zap.String("summary", sanitizer.SanitizeText(input.Summary)),
}
if input.Attempt > 0 {
fields = append(fields, zap.Int("attempt", input.Attempt))
}
if input.AttemptRecordID != "" {
fields = append(fields, zap.String("attempt_record_id", input.AttemptRecordID))
}
auditLogger := logger.GetAppLogger().Named(auditLoggerName)
if input.Result == constants.AuditResultSuccess {
auditLogger.Info("audit_event", fields...)
return
}
auditLogger.Warn("audit_event", fields...)
}
// primaryResource 返回主资源的类型与键,没有主资源时取第一条资源。
func primaryResource(input AppendInput) (string, string) {
for _, resource := range input.Resources {
if resource.Relation == constants.AuditResourceRelationPrimary {
return resource.Type, resource.Key
}
}
if len(input.Resources) > 0 {
return input.Resources[0].Type, input.Resources[0].Key
}
return "", ""
}

View File

@@ -0,0 +1,250 @@
package audit
import (
"sort"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// PersistPolicy 决定系统任务、定时任务发起的审计动作是否写入审计表。
// 后台账号、个人客户、开放接口、外部系统发起的动作始终写表,不受该策略约束。
type PersistPolicy string
const (
// PersistAlways 成功、失败都写审计表。
PersistAlways PersistPolicy = "always"
// PersistOnSuccess 只写成功;失败写应用日志。
PersistOnSuccess PersistPolicy = "on_success"
// PersistOutcome 只写最终结论(AppendInput.Final=true);中间失败写应用日志,逐次细节由业务尝试记录保存。
PersistOutcome PersistPolicy = "outcome"
// PersistLogOnly 不写审计表,只写所在服务的应用日志。
PersistLogOnly PersistPolicy = "log_only"
// PersistNone 不写审计表,也不写应用日志。
PersistNone PersistPolicy = "none"
)
// validPersistPolicy 判断策略取值是否合法。
func validPersistPolicy(policy PersistPolicy) bool {
switch policy {
case PersistAlways, PersistOnSuccess, PersistOutcome, PersistLogOnly, PersistNone:
return true
default:
return false
}
}
// machinePersistPolicies 是可由系统任务或定时任务发起的动作的落库策略。
// 只登记资金、套餐生命周期与业务状态变化等需要留在审计表的动作,以及明确不写的动作;
// 未登记的机器动作按 PersistLogOnly 写应用日志(见 docs/2026-11-05-审计日志写入改造技术方案.md 4.1、4.2)。
var machinePersistPolicies = func() map[string]PersistPolicy {
policies := map[string]PersistPolicy{
// 对接调用开始:与 tb_integration_log 完全重复,不写。
constants.AuditActionIntegrationAttemptStarted: PersistNone,
// 退款资产后处理:只写最终结论(成功或转人工),逐次尝试见 tb_refund_post_process_attempt。
"refund.process_asset": PersistOutcome,
}
// 资金、审批、订单、套餐生命周期、导入与资产归属等业务状态变化:留在审计表。
for _, code := range []string{
"agent_distribution.registration_approve",
"agent_distribution.registration_reject",
"agent_recharge.close",
"agent_recharge.create",
"agent_recharge.credit",
"agent_wallet.order_complete",
"agent_wallet.order_debit",
"agent_wallet.order_release",
"agent_wallet.order_reserve",
"approval.recover_submission",
"approval.sync_decision",
"approval.sync_submission",
"asset.first_purchase_ended",
"asset.first_purchase_recorded",
"asset_auto_renewal.failed",
"asset_auto_renewal.renewed",
"asset_package_batch_order_task.complete",
"asset_recharge.auto_purchase",
"audit.retention_cleanup",
"commission.calculate",
"commission.credit",
"commission_withdrawal.anomaly_flag",
"commission_withdrawal.approve",
"commission_withdrawal.attempt_approve",
"commission_withdrawal.attempt_close",
"commission_withdrawal.attempt_reject",
"commission_withdrawal.attempt_submit",
"commission_withdrawal.reject",
"commission_withdrawal.request",
"device.allocate",
"device.allocate_batch",
"device.create",
"device.recall",
"device.recall_batch",
"device.series_binding",
"device.series_binding_batch",
"device.update_polling_status",
"device_import_task.complete",
"employee_collection.application.approve",
"employee_collection.application.reject",
"employee_collection.application.revoke",
"employee_collection.application.submit",
"employee_collection.bill.close",
"employee_collection.bill.create",
"employee_collection.bill.refund_offset",
"integration.inbound_received",
// 自动停复机:系统自动发起的已由 StopResumeService.commandAuditRequired 改写停复机记录,
// 仍写审计的只剩通道阈值、自动续费等豁免链路(gateway-call-observability 要求保留)。
"iot_card.auto_start",
"iot_card.auto_stop",
"iot_card.batch_update_polling_status",
"iot_card.create",
"iot_card.terminal_disable_polling",
"iot_card.update_polling_status",
"iot_card_import_task.complete",
"order.cancel",
"order.create",
"order.expire_close",
"order.online_pay",
"order.wallet_pay",
"order_package_invalidate_task.complete",
"order_package_invalidate_task.item",
"package.silence_default_changed",
"package.silence_switch_changed",
"package_silence_policy.created",
"package_silence_policy.status_changed",
"package_silence_policy.updated",
"package_traffic_alert.trigger",
"package_usage.activate",
"package_usage.adjust_traffic",
"package_usage.expire",
"package_usage.invalidate_asset",
"package_usage.invalidate_refund",
"package_usage.silence_adjust_approved",
"package_usage.silence_adjust_rejected",
"package_usage.silence_adjust_requested",
"package_usage.silence_backfilled",
"package_usage.silence_ended",
"package_usage.silence_expired",
"package_usage.silence_extension_applied",
"package_usage.silence_extension_approved",
"package_usage.silence_extension_exception",
"package_usage.silence_extension_order_changed",
"package_usage.silence_extension_rejected",
"package_usage.silence_extension_requested",
"package_usage.silence_migrated_on_exchange",
"package_usage.silence_set",
"package_usage.update_expires_at",
"payment.confirm",
"payment.create",
"payment.fail",
"phone_asset_association.import_unbind",
"phone_asset_unbind_import_task.complete",
"refund.anomaly_flag",
"refund.approve",
"refund.attempt_approve",
"refund.attempt_close",
"refund.channel_call",
"refund.channel_recover",
"refund.clawback_commission",
"refund.clawback_not_required",
"refund.invalidate_commission",
"refund.reject",
"shop.import_business_owner",
"shop_business_owner_import_task.complete",
"withdrawal_qualification.approve",
"withdrawal_qualification.invalidate",
"withdrawal_qualification.reject",
"withdrawal_qualification.submit",
"withdrawal_qualification.submit_reject",
"withdrawal_qualification.void",
} {
policies[code] = PersistAlways
}
// 过程类动作:写应用日志。采集与扣减见采集记录与日流量,流量重置见套餐重置时间与日流量。
for _, code := range []string{
"device.worker_observation_sync",
"iot_card.auto_stop_reason_update",
"iot_card.worker_network_sync",
"iot_card.worker_realname_sync",
"iot_card.worker_traffic_sync",
"notification.cleanup",
"notification.cleanup_item",
"notification.deliver",
"package_usage.deduct_traffic",
"package_usage.reset_traffic",
"polling_priority.claim",
"polling_priority.complete",
"polling_priority.dequeue",
"polling_priority.enqueue",
"polling_priority.expire",
"polling_priority.fail",
"polling_priority.retry",
} {
policies[code] = PersistLogOnly
}
return policies
}()
// applyPersistPolicies 把机器动作落库策略写入已注册的动作定义。
func applyPersistPolicies(registry *Registry, policies map[string]PersistPolicy) {
for code, policy := range policies {
action, ok := registry.actionsByCode[code]
if !ok {
continue
}
action.Persist = policy
registry.actionsByCode[code] = action
for operation, byOperation := range registry.actionsByOperation {
if byOperation.Code == code {
byOperation.Persist = policy
registry.actionsByOperation[operation] = byOperation
}
}
}
}
// isMachineActor 判断操作者是否为系统任务或定时任务。
func isMachineActor(actorKind string) bool {
return actorKind == constants.AuditActorSystemTask || actorKind == constants.AuditActorScheduledJob
}
// allowsMachineOrigin 判断动作是否允许由系统任务或定时任务发起。
func allowsMachineOrigin(action ActionDefinition) bool {
if isMachineActor(action.AllowedActor) {
return true
}
for _, origin := range action.AllowedOrigins {
if isMachineActor(origin.Actor) {
return true
}
}
return false
}
// MachineActionsWithoutPolicy 返回可由系统任务或定时任务发起、但未声明落库策略的动作编码(审计覆盖扫描使用)。
func (r *Registry) MachineActionsWithoutPolicy() []string {
if r == nil {
return nil
}
var codes []string
for code, action := range r.actionsByCode {
if allowsMachineOrigin(action) && action.Persist == "" {
codes = append(codes, code)
}
}
sort.Strings(codes)
return codes
}
// MachineActions 返回可由系统任务或定时任务发起的全部动作及其声明的策略(空表示未声明)。
func (r *Registry) MachineActions() map[string]PersistPolicy {
if r == nil {
return nil
}
actions := map[string]PersistPolicy{}
for code, action := range r.actionsByCode {
if allowsMachineOrigin(action) {
actions[code] = action.Persist
}
}
return actions
}

View File

@@ -18,6 +18,8 @@ type ActionDefinition struct {
SubjectFields []string
SensitiveRead bool
AllowedOrigins []ActionOrigin
// Persist 是系统任务、定时任务发起时的落库策略,空表示未声明(按 PersistLogOnly 处理)。
Persist PersistPolicy
}
// ActionOrigin 定义动作允许的操作者与入口组合。
@@ -1185,6 +1187,7 @@ func NewRegistry() *Registry {
},
}
registerPackageSilenceAudit(registry)
applyPersistPolicies(registry, machinePersistPolicies)
return registry
}

View File

@@ -812,6 +812,11 @@ type AppendInput struct {
FailCount int
Metadata map[string]any
Resources []ResourceInput
// Final 只对"只写结论"策略生效:true 表示本次是最终结论(成功或重试用尽转人工),写审计表;false 只写应用日志。
Final bool
// Attempt 与 AttemptRecordID 是自动重试类动作的尝试序号与业务尝试记录标识,只写入应用日志。
Attempt int
AttemptRecordID string
}
// Writer 只提供不可变 Audit Event 追加能力。
@@ -956,6 +961,13 @@ func (w *Writer) AppendAndGet(ctx context.Context, tx *gorm.DB, input AppendInpu
if !validResult(input.Result) || len(input.Resources) == 0 {
return nil, pkgerrors.New(pkgerrors.CodeInvalidParam, "审计结果非法或缺少资源")
}
switch decidePersist(action, input) {
case decisionSkip:
return nil, nil
case decisionLog:
writeAuditLog(ctx, action, input)
return nil, nil
}
resources, err := w.buildResources(input.Resources, action)
if err != nil {
return nil, err

View File

@@ -0,0 +1,313 @@
package cardobservation
import (
"compress/gzip"
"context"
"crypto/sha256"
"database/sql"
"encoding/csv"
"encoding/hex"
"encoding/json"
"fmt"
"io"
"os"
"path/filepath"
"sort"
"strings"
"time"
"github.com/jackc/pgx/v5/stdlib"
"go.uber.org/zap"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// collectionArchiveTables 是按月分区、到期归档的采集记录父表。
var collectionArchiveTables = []string{"tb_card_traffic_collection", "tb_card_traffic_collection_failure"}
// CollectionArchiver 维护采集记录月分区:预建未来分区;到期分区按"摘出 → 导出 csv.gz → 校验 → 删除"归档。
// 导出或校验失败时保留已摘出的表,下一轮重试,不会出现数据已删但没有压缩包的情况。
type CollectionArchiver struct {
db *gorm.DB
dir string
keepFiles int
aheadMonth int
logger *zap.Logger
}
// NewCollectionArchiver 创建采集记录归档器;dir 为压缩包目录,keepFiles 为每张表本地保留的压缩包个数。
func NewCollectionArchiver(db *gorm.DB, dir string, keepFiles int, logger *zap.Logger) *CollectionArchiver {
if logger == nil {
logger = zap.NewNop()
}
if keepFiles <= 0 {
keepFiles = constants.TrafficCollectionArchiveKeepFiles
}
return &CollectionArchiver{db: db, dir: dir, keepFiles: keepFiles, aheadMonth: 2, logger: logger}
}
// archiveManifest 是压缩包同名说明文件内容。
type archiveManifest struct {
Table string `json:"table"`
Partition string `json:"partition"`
Month string `json:"month"`
Rows int64 `json:"rows"`
FirstObservedAt *string `json:"first_observed_at"`
LastObservedAt *string `json:"last_observed_at"`
File string `json:"file"`
FileBytes int64 `json:"file_bytes"`
SHA256 string `json:"sha256"`
ExportedAt time.Time `json:"exported_at"`
}
// Maintain 对全部采集记录表执行一轮分区维护;单张表失败不影响其他表,返回第一个错误。
func (a *CollectionArchiver) Maintain(ctx context.Context, now time.Time) error {
var firstErr error
for _, table := range collectionArchiveTables {
if err := a.maintainTable(ctx, table, now); err != nil {
a.logger.Error("维护采集记录分区失败", zap.String("table", table), zap.Error(err))
if firstErr == nil {
firstErr = err
}
}
}
return firstErr
}
func (a *CollectionArchiver) maintainTable(ctx context.Context, table string, now time.Time) error {
monthStart := cardflow.MonthStart(now)
for i := 0; i <= a.aheadMonth; i++ {
from := monthStart.AddDate(0, i, 0)
sqlText := fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s_%s PARTITION OF %s FOR VALUES FROM ('%s') TO ('%s')`,
table, from.Format("200601"), table, from.Format(time.RFC3339), from.AddDate(0, 1, 0).Format(time.RFC3339))
if err := a.db.WithContext(ctx).Exec(sqlText).Error; err != nil {
return fmt.Errorf("预建分区失败: %w", err)
}
}
// 在线保留当月加最近 N 个整月,更早的月分区到期。
cutoff := monthStart.AddDate(0, -constants.TrafficCollectionRetentionMonths, 0)
partitions, err := a.monthPartitions(ctx, table)
if err != nil {
return err
}
for _, partition := range partitions {
if !partition.month.Before(cutoff) {
continue
}
if err := a.archivePartition(ctx, table, partition); err != nil {
return fmt.Errorf("归档分区 %s 失败: %w", partition.name, err)
}
}
a.cleanupLocalFiles(table)
return nil
}
type monthPartition struct {
name string
month time.Time
attached bool
}
// monthPartitions 返回该表全部按月命名的分区(含上一轮已摘出未删除的表),按月份升序。
func (a *CollectionArchiver) monthPartitions(ctx context.Context, table string) ([]monthPartition, error) {
var rows []struct {
Relname string
Attached bool
}
err := a.db.WithContext(ctx).Raw(`
SELECT c.relname, EXISTS (SELECT 1 FROM pg_inherits i JOIN pg_class p ON p.oid = i.inhparent
WHERE i.inhrelid = c.oid AND p.relname = ?) AS attached
FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE n.nspname = current_schema() AND c.relkind IN ('r', 'p') AND c.relname ~ ?`,
table, "^"+table+`_[0-9]{6}$`).Scan(&rows).Error
if err != nil {
return nil, fmt.Errorf("查询分区失败: %w", err)
}
partitions := make([]monthPartition, 0, len(rows))
for _, row := range rows {
month, err := time.ParseInLocation("200601", row.Relname[len(table)+1:], cardflow.MonthStart(time.Now()).Location())
if err != nil {
continue
}
partitions = append(partitions, monthPartition{name: row.Relname, month: month, attached: row.Attached})
}
sort.Slice(partitions, func(i, j int) bool { return partitions[i].month.Before(partitions[j].month) })
return partitions, nil
}
func (a *CollectionArchiver) archivePartition(ctx context.Context, table string, partition monthPartition) error {
if partition.attached {
if err := a.db.WithContext(ctx).Exec(fmt.Sprintf("ALTER TABLE %s DETACH PARTITION %s", table, partition.name)).Error; err != nil {
return fmt.Errorf("摘出分区失败: %w", err)
}
}
if err := os.MkdirAll(a.dir, 0o755); err != nil {
return fmt.Errorf("创建归档目录失败: %w", err)
}
finalPath := filepath.Join(a.dir, partition.name+".csv.gz")
tmpPath := finalPath + ".tmp"
if err := a.exportCSV(ctx, partition.name, tmpPath); err != nil {
_ = os.Remove(tmpPath)
return err
}
manifest, err := a.verify(ctx, table, partition, tmpPath)
if err != nil {
_ = os.Remove(tmpPath)
return err
}
manifest.File = filepath.Base(finalPath)
if err := writeManifest(finalPath+".manifest.json", manifest); err != nil {
_ = os.Remove(tmpPath)
return err
}
if err := os.Rename(tmpPath, finalPath); err != nil {
return fmt.Errorf("压缩包改名失败: %w", err)
}
if err := a.db.WithContext(ctx).Exec("DROP TABLE IF EXISTS " + partition.name).Error; err != nil {
return fmt.Errorf("删除已归档分区失败: %w", err)
}
a.logger.Info("采集记录分区已归档", zap.String("partition", partition.name), zap.Int64("rows", manifest.Rows),
zap.String("file", finalPath), zap.Int64("file_bytes", manifest.FileBytes))
return nil
}
// exportCSV 用 COPY 把分区按采集时间与 ID 排序流式导出为带表头的 CSV,并边写边 gzip。
func (a *CollectionArchiver) exportCSV(ctx context.Context, partition, path string) error {
file, err := os.Create(path)
if err != nil {
return fmt.Errorf("创建压缩包失败: %w", err)
}
defer file.Close()
gz := gzip.NewWriter(file)
sqlDB, err := a.db.DB()
if err != nil {
return fmt.Errorf("获取数据库连接失败: %w", err)
}
conn, err := sqlDB.Conn(ctx)
if err != nil {
return fmt.Errorf("获取数据库连接失败: %w", err)
}
defer conn.Close()
copySQL := fmt.Sprintf("COPY (SELECT * FROM %s ORDER BY observed_at, id) TO STDOUT WITH (FORMAT csv, HEADER)", partition)
if err := rawCopyTo(ctx, conn, gz, copySQL); err != nil {
return fmt.Errorf("导出分区失败: %w", err)
}
if err := gz.Close(); err != nil {
return fmt.Errorf("写压缩包失败: %w", err)
}
if err := file.Sync(); err != nil {
return fmt.Errorf("落盘压缩包失败: %w", err)
}
return nil
}
func rawCopyTo(ctx context.Context, conn *sql.Conn, w io.Writer, copySQL string) error {
return conn.Raw(func(driverConn any) error {
stdConn, ok := driverConn.(*stdlib.Conn)
if !ok {
return fmt.Errorf("数据库驱动不支持 COPY 导出")
}
_, err := stdConn.Conn().PgConn().CopyTo(ctx, w, copySQL)
return err
})
}
// verify 重新读取压缩包统计行数并与分区行数比对,生成说明文件内容。
func (a *CollectionArchiver) verify(ctx context.Context, table string, partition monthPartition, path string) (archiveManifest, error) {
var stats struct {
Rows int64
First *time.Time
Last *time.Time
}
if err := a.db.WithContext(ctx).Raw(fmt.Sprintf(
"SELECT count(*) AS rows, min(observed_at) AS first, max(observed_at) AS last FROM %s", partition.name)).Scan(&stats).Error; err != nil {
return archiveManifest{}, fmt.Errorf("统计分区行数失败: %w", err)
}
fileRows, sum, size, err := countArchiveRows(path)
if err != nil {
return archiveManifest{}, err
}
if fileRows != stats.Rows {
return archiveManifest{}, fmt.Errorf("压缩包行数 %d 与分区行数 %d 不一致", fileRows, stats.Rows)
}
manifest := archiveManifest{
Table: table, Partition: partition.name, Month: partition.month.Format("2006-01"), Rows: stats.Rows,
FileBytes: size, SHA256: sum, ExportedAt: time.Now(),
}
if stats.First != nil {
first, last := stats.First.Format(time.RFC3339), stats.Last.Format(time.RFC3339)
manifest.FirstObservedAt, manifest.LastObservedAt = &first, &last
}
return manifest, nil
}
// countArchiveRows 解压并按 CSV 解析压缩包,返回数据行数(不含表头)、文件 SHA-256 与文件大小。
func countArchiveRows(path string) (int64, string, int64, error) {
file, err := os.Open(path)
if err != nil {
return 0, "", 0, fmt.Errorf("打开压缩包失败: %w", err)
}
defer file.Close()
hash := sha256.New()
gz, err := gzip.NewReader(io.TeeReader(file, hash))
if err != nil {
return 0, "", 0, fmt.Errorf("读取压缩包失败: %w", err)
}
reader := csv.NewReader(gz)
reader.FieldsPerRecord = -1
reader.ReuseRecord = true
var records int64
for {
if _, err := reader.Read(); err == io.EOF {
break
} else if err != nil {
return 0, "", 0, fmt.Errorf("解析压缩包失败: %w", err)
}
records++
}
if _, err := io.Copy(io.Discard, gz); err != nil {
return 0, "", 0, fmt.Errorf("读取压缩包失败: %w", err)
}
info, err := file.Stat()
if err != nil {
return 0, "", 0, fmt.Errorf("读取压缩包大小失败: %w", err)
}
if records > 0 {
records-- // 表头
}
return records, hex.EncodeToString(hash.Sum(nil)), info.Size(), nil
}
func writeManifest(path string, manifest archiveManifest) error {
data, err := json.MarshalIndent(manifest, "", " ")
if err != nil {
return fmt.Errorf("生成说明文件失败: %w", err)
}
tmp := path + ".tmp"
if err := os.WriteFile(tmp, append(data, '\n'), 0o644); err != nil {
return fmt.Errorf("写说明文件失败: %w", err)
}
if err := os.Rename(tmp, path); err != nil {
return fmt.Errorf("说明文件改名失败: %w", err)
}
return nil
}
// cleanupLocalFiles 每张表只保留最近 keepFiles 个月的压缩包与说明文件。
func (a *CollectionArchiver) cleanupLocalFiles(table string) {
matches, err := filepath.Glob(filepath.Join(a.dir, table+"_[0-9][0-9][0-9][0-9][0-9][0-9].csv.gz"))
if err != nil || len(matches) <= a.keepFiles {
return
}
sort.Strings(matches)
for _, path := range matches[:len(matches)-a.keepFiles] {
if err := os.Remove(path); err != nil {
a.logger.Warn("删除过期采集记录压缩包失败", zap.String("file", path), zap.Error(err))
continue
}
_ = os.Remove(path + ".manifest.json")
a.logger.Info("已删除过期采集记录压缩包", zap.String("file", strings.TrimPrefix(path, a.dir+"/")))
}
}

View File

@@ -475,10 +475,11 @@ func (r *SeriesRunner) loadCurrentICCIDs(ctx context.Context, payload cardapp.Se
if err != nil {
return nil, err
}
// 显式列名:GORM 默认把 ICCID 映射成 icc_id,不写 tag 时三个值都读不到,本地预期判定永远不成立。
var current struct {
ICCID string
ICCID19 string
ICCID20 *string
ICCID string `gorm:"column:iccid"`
ICCID19 string `gorm:"column:iccid_19"`
ICCID20 *string `gorm:"column:iccid_20"`
}
err = r.db.WithContext(ctx).Table("tb_device_sim_binding AS binding").
Select("card.iccid, card.iccid_19, card.iccid_20").
@@ -550,7 +551,7 @@ func (r *SeriesRunner) queryAndApply(ctx context.Context, payload cardapp.Series
if err != nil {
return cardapp.RunResult{}, err
}
decision, err := r.observation.ApplyCardObservation(ctx, carddomain.RealnameObservation{CardID: card.ID, Verified: response.RealStatus, Metadata: metadata})
decision, err := r.observation.ApplyCardObservation(ctx, carddomain.RealnameObservation{CardID: card.ID, Verified: response.RealStatus, UpstreamRealnameAt: response.UpstreamRealnameAt(), Metadata: metadata})
return cardapp.RunResult{StateChanged: decision.StatusChanged}, err
case constants.CardObservationSyncTypeTraffic:
response, err := r.gateway.QueryFlow(ctx, &gateway.FlowQueryReq{CardNo: card.ICCID})

View File

@@ -133,14 +133,16 @@ func RecoverRefundPostProcessing(ctx context.Context, db *gorm.DB, repository *o
}
refundStats := RecoveryStats{}
var refunds []model.RefundRequest
if err := db.WithContext(ctx).Where("status = ? AND (commission_deducted = ? OR asset_reset = ?)", model.RefundStatusApproved, false, false).Order("id ASC").Limit(limit).Find(&refunds).Error; err != nil {
// 需人工处理与未到下次重试时间的资产后处理不参与扫描,避免长期失败的退款单占满每轮名额。
if err := db.WithContext(ctx).Where("status = ? AND (commission_deducted = ? OR (asset_reset = ? AND asset_post_status <> ? AND (asset_post_next_at IS NULL OR asset_post_next_at <= ?)))",
model.RefundStatusApproved, false, false, model.RefundAssetPostManualRequired, time.Now()).Order("id ASC").Limit(limit).Find(&refunds).Error; err != nil {
logger.Warn("扫描退款后处理失败", zap.Error(err))
} else {
for _, refund := range refunds {
if !refund.CommissionDeducted {
recoverOne(ctx, db, repository, EventRefundCommissionDeduct, refund.ID, refund.OrderID, &refundStats, logger, true)
}
if !refund.AssetReset {
if !refund.AssetReset && assetPostDue(refund, time.Now()) {
recoverOne(ctx, db, repository, EventRefundAssetProcess, refund.ID, refund.OrderID, &refundStats, logger, true)
}
}
@@ -148,6 +150,14 @@ func RecoverRefundPostProcessing(ctx context.Context, db *gorm.DB, repository *o
return refundStats
}
// assetPostDue 判断退款资产后处理是否到了可自动重试的时间:需人工处理的不重投,未到下次重试时间的不重投。
func assetPostDue(refund model.RefundRequest, now time.Time) bool {
if refund.AssetPostStatus == model.RefundAssetPostManualRequired {
return false
}
return refund.AssetPostNextAt == nil || !refund.AssetPostNextAt.After(now)
}
func recoverOne(ctx context.Context, db *gorm.DB, repository *outbox.Repository, eventType string, aggregateID, orderID uint, stats *RecoveryStats, logger *zap.Logger, retryDelivered bool) {
eventID := outboxid.Stable(eventType+":", strconv.FormatUint(uint64(aggregateID), 10))
var event model.OutboxEvent

View File

@@ -26,6 +26,8 @@ type StopResumeRecordInput struct {
Attempt int
CallErr error
Duration time.Duration
// SkipReason 非空表示指令在调用上游前结束(已是目标状态、条件不再满足等),按"跳过"记录,原因写入 ProviderMessage。
SkipReason string
}
// StopResumeRecorder 把每次停复机上游调用写入停复机记录表;写入失败只记日志与计数,不影响业务回写。
@@ -54,7 +56,11 @@ func (r *StopResumeRecorder) Record(ctx context.Context, input StopResumeRecordI
Attempt: input.Attempt, Result: constants.StopResumeRecordSuccess,
DurationMS: int(input.Duration.Milliseconds()), CreatedAt: time.Now(),
}
if input.CallErr != nil {
if input.SkipReason != "" {
row.Result = constants.StopResumeRecordSkipped
row.ErrorCategory = ""
row.ProviderMessage = input.SkipReason
} else if input.CallErr != nil {
row.Result = constants.StopResumeRecordFailed
if gwErr, ok := gateway.AsGatewayError(input.CallErr); ok {
row.ErrorCategory = gwErr.Category

View File

@@ -115,9 +115,7 @@ func (r *Repository) Start(ctx context.Context, input Attempt) (*model.Integrati
if input.AuditEventID == nil && input.TriggerSeries != nil {
input.AuditEventID = r.auditEventIDForSeries(ctx, *input.TriggerSeries)
}
if input.AuditEventID == nil {
input.AuditEventID = r.recordAuditEvent(ctx, constants.AuditActionIntegrationAttemptStarted, input.IntegrationID, input.Provider, input.Direction, input.Operation, input.ResourceType, input.ResourceID, input.ResourceKey, input.CorrelationID)
}
// 没有上游审计事件时 audit_event_id 留空,不再补写 integration.attempt_started(与本表内容重复)。
autoAttempt := input.Attempt <= 0 && input.TriggerSeries != nil
if input.Attempt <= 0 {
input.Attempt = 1
@@ -321,6 +319,10 @@ func (r *Repository) recordAuditEvent(ctx context.Context, actionCode, integrati
zap.L().Warn("Integration Log 缺少审计关联", zap.String("integration_id", integrationID), zap.Error(err))
return nil
}
if event == nil {
// 落库策略决定不写审计表(只写应用日志或不写)时没有事件可关联。
return nil
}
return &event.ID
}

View File

@@ -47,6 +47,10 @@ func (p *Producer) Stop() {
// Handler 处理一条消息;返回后由管理器 FIN。消息处理期间可调用 touch 延长 NSQ 消息超时。
type Handler func(ctx context.Context, body []byte, touch func())
// RetryHandler 处理一条消息并决定是否重投:返回 0 表示 FIN,返回正数表示按该延迟重投(REQ,不计 NSQ 退避)。
// attempts 是 NSQ 记录的投递次数(含本次,从 1 起)。
type RetryHandler func(ctx context.Context, body []byte, attempts uint16, touch func()) time.Duration
// ConsumerConfig 是消费者参数。
type ConsumerConfig struct {
NSQDAddress string
@@ -55,14 +59,17 @@ type ConsumerConfig struct {
MaxAttempts uint16
// LookupdPollInterval 消费者向 nsqlookupd 查询 nsqd 的间隔;0 表示 15 秒。
LookupdPollInterval time.Duration
// UnlimitedAttempts 为 true 时不限投递次数(忽略 MaxAttempts),用于不允许丢弃的入库消息。
UnlimitedAttempts bool
}
// ConsumerManager 按 topic 动态订阅与取消订阅;每个 topic 一个消费者,max_in_flight 控制本进程对该 topic 的并发。
type ConsumerManager struct {
cfg ConsumerConfig
channel string
handler Handler
logger *zap.Logger
cfg ConsumerConfig
channel string
handler Handler
retryHandler RetryHandler
logger *zap.Logger
mu sync.Mutex
consumers map[string]*subscription
@@ -86,6 +93,13 @@ func NewConsumerManager(cfg ConsumerConfig, channel string, handler Handler, log
consumers: map[string]*subscription{}, ctx: ctx, cancel: cancel}
}
// NewRetryConsumerManager 创建由处理结果决定 FIN 或延迟重投的消费者管理器。
func NewRetryConsumerManager(cfg ConsumerConfig, channel string, handler RetryHandler, logger *zap.Logger) *ConsumerManager {
manager := NewConsumerManager(cfg, channel, nil, logger)
manager.retryHandler = handler
return manager
}
// Sync 使订阅集合与 desired(topic → max_in_flight)一致:新增订阅、取消多余订阅、调整 max_in_flight。
func (m *ConsumerManager) Sync(desired map[string]int) {
m.mu.Lock()
@@ -97,7 +111,7 @@ func (m *ConsumerManager) Sync(desired map[string]int) {
if _, keep := desired[topic]; !keep {
sub.consumer.Stop()
delete(m.consumers, topic)
m.logger.Info("取消订阅卡任务 topic", zap.String("topic", topic))
m.logger.Info("取消订阅 NSQ topic", zap.String("topic", topic))
}
}
for topic, maxInFlight := range desired {
@@ -113,11 +127,11 @@ func (m *ConsumerManager) Sync(desired map[string]int) {
}
consumer, err := m.subscribe(topic, maxInFlight)
if err != nil {
m.logger.Warn("订阅卡任务 topic 失败,下一轮重试", zap.String("topic", topic), zap.Error(err))
m.logger.Warn("订阅 NSQ topic 失败,下一轮重试", zap.String("topic", topic), zap.Error(err))
continue
}
m.consumers[topic] = &subscription{consumer: consumer, maxInFlight: maxInFlight}
m.logger.Info("订阅卡任务 topic", zap.String("topic", topic), zap.Int("max_in_flight", maxInFlight))
m.logger.Info("订阅 NSQ topic", zap.String("topic", topic), zap.Int("max_in_flight", maxInFlight))
}
}
@@ -130,6 +144,9 @@ func (m *ConsumerManager) subscribe(topic string, maxInFlight int) (*nsq.Consume
if m.cfg.MaxAttempts > 0 {
cfg.MaxAttempts = m.cfg.MaxAttempts
}
if m.cfg.UnlimitedAttempts {
cfg.MaxAttempts = 0
}
cfg.LookupdPollInterval = 15 * time.Second
if m.cfg.LookupdPollInterval > 0 {
cfg.LookupdPollInterval = m.cfg.LookupdPollInterval
@@ -146,6 +163,14 @@ func (m *ConsumerManager) subscribe(topic string, maxInFlight int) (*nsq.Consume
message.DisableAutoResponse()
m.inflight.Add(1)
defer m.inflight.Done()
if m.retryHandler != nil {
if delay := m.retryHandler(handlerCtx, message.Body, message.Attempts, message.Touch); delay > 0 {
message.RequeueWithoutBackoff(delay)
return nil
}
message.Finish()
return nil
}
defer message.Finish()
m.handler(handlerCtx, message.Body, message.Touch)
return nil

View File

@@ -0,0 +1,60 @@
package nsqbus
import (
"context"
"encoding/json"
"fmt"
"net/http"
"net/url"
"time"
)
type nsqdStats struct {
Topics []struct {
TopicName string `json:"topic_name"`
Depth int64 `json:"depth"`
Channels []struct {
Depth int64 `json:"depth"`
DeferredCount int64 `json:"deferred_count"`
} `json:"channels"`
} `json:"topics"`
}
// TopicBacklog 读取 nsqd 上某 topic 的积压量:topic 未分发量 + 各 channel 待消费量与延迟重投量(不含处理中)。
// topic 不存在时返回 0。
func TopicBacklog(ctx context.Context, nsqdTCPAddress, topic string) (int64, error) {
httpAddress := nsqdHTTPAddress(nsqdTCPAddress)
if httpAddress == "" {
return 0, fmt.Errorf("nsqd 地址无效:%s", nsqdTCPAddress)
}
requestCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
endpoint := "http://" + httpAddress + "/stats?format=json&topic=" + url.QueryEscape(topic)
request, err := http.NewRequestWithContext(requestCtx, http.MethodGet, endpoint, nil)
if err != nil {
return 0, err
}
response, err := http.DefaultClient.Do(request)
if err != nil {
return 0, err
}
defer response.Body.Close()
if response.StatusCode != http.StatusOK {
return 0, fmt.Errorf("读取 nsqd 统计失败,HTTP %d", response.StatusCode)
}
var stats nsqdStats
if err := json.NewDecoder(response.Body).Decode(&stats); err != nil {
return 0, err
}
var backlog int64
for _, item := range stats.Topics {
if item.TopicName != topic {
continue
}
backlog += item.Depth
for _, channel := range item.Channels {
backlog += channel.Depth + channel.DeferredCount
}
}
return backlog, nil
}

View File

@@ -0,0 +1,31 @@
package payment
import (
"fmt"
"testing"
sdkalipay "github.com/smartwalle/alipay/v3"
)
func TestAlipayTradeNotExist(t *testing.T) {
notExist := sdkalipay.Error{Code: sdkalipay.Code("40004"), SubCode: alipayTradeNotExistCode}
tests := []struct {
name string
response *sdkalipay.TradeQueryRsp
err error
want bool
}{
{name: "失败响应且交易不存在", response: &sdkalipay.TradeQueryRsp{Error: notExist}, want: true},
{name: "SDK 以错误返回交易不存在", err: fmt.Errorf("wrap: %w", &notExist), want: true},
{name: "其他业务失败", response: &sdkalipay.TradeQueryRsp{Error: sdkalipay.Error{Code: sdkalipay.Code("40004"), SubCode: "ACQ.SYSTEM_ERROR"}}, want: false},
{name: "成功响应", response: &sdkalipay.TradeQueryRsp{Error: sdkalipay.Error{Code: sdkalipay.CodeSuccess}, TradeStatus: sdkalipay.TradeStatusWaitBuyerPay}, want: false},
{name: "网络错误", err: fmt.Errorf("dial tcp: timeout"), want: false},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := alipayTradeNotExist(tt.response, tt.err); got != tt.want {
t.Fatalf("alipayTradeNotExist() = %v, want %v", got, tt.want)
}
})
}
}

View File

@@ -2,6 +2,7 @@ package payment
import (
"context"
stderrors "errors"
"strconv"
"time"
@@ -54,6 +55,18 @@ func (a *AlipayWapAdapter) Query(ctx context.Context, request agentrecharge.Onli
}
startedAt := time.Now()
response, callErr := client.TradeQuery(ctx, sdkalipay.TradeQuery{OutTradeNo: request.PaymentNo})
// 客户没打开过支付链接时支付宝侧没有这笔交易(ACQ.TRADE_NOT_EXIST):按"渠道没有这笔订单"返回,
// 恢复任务在过支付截止后据此关闭订单;不能当成查单失败,否则订单永远停在待支付。
if alipayTradeNotExist(response, callErr) {
if _, err = a.integration.Complete(ctx, attempt.IntegrationID, integrationlog.Completion{
Result: constants.IntegrationResultSuccess, ProviderCode: alipayTradeNotExistCode,
ResponseSummary: map[string]any{"state": agentrecharge.OnlinePaymentStateNotFound},
DurationMS: time.Since(startedAt).Milliseconds(),
}); err != nil {
return agentrecharge.OnlinePaymentQueryResult{}, err
}
return agentrecharge.OnlinePaymentQueryResult{State: agentrecharge.OnlinePaymentStateNotFound}, nil
}
if callErr != nil {
return agentrecharge.OnlinePaymentQueryResult{}, a.completeUnknown(ctx, attempt.IntegrationID, startedAt, callErr)
}
@@ -128,6 +141,18 @@ func (a *AlipayWapAdapter) completeUnknown(ctx context.Context, integrationID st
return apperrors.Wrap(apperrors.CodeTimeout, cause, "支付宝支付请求结果未知")
}
// alipayTradeNotExistCode 是支付宝查单"交易不存在"的业务子码。
const alipayTradeNotExistCode = "ACQ.TRADE_NOT_EXIST"
// alipayTradeNotExist 判断查单结果是否为"交易不存在":SDK 可能以失败响应返回,也可能以 *Error 返回。
func alipayTradeNotExist(response *sdkalipay.TradeQueryRsp, callErr error) bool {
if response != nil && response.IsFailure() && response.SubCode == alipayTradeNotExistCode {
return true
}
var sdkErr *sdkalipay.Error
return stderrors.As(callErr, &sdkErr) && sdkErr != nil && sdkErr.SubCode == alipayTradeNotExistCode
}
func mapAlipayTradeState(state sdkalipay.TradeStatus) string {
switch state {
case sdkalipay.TradeStatusSuccess, sdkalipay.TradeStatusFinished:

View File

@@ -47,6 +47,18 @@ func (a *WechatWebAdapter) CreatePaymentURL(ctx context.Context, request agentre
PayerClientIP: request.PayerClientIP,
H5Type: "Wap",
})
// 微信明确拒绝(订单未创建):记失败并返回真实原因,调用方立即关单;
// 用"微信配置不可用"错误码,不触发支付失败自动停用商户(如 H5 产品未开通不影响该商户的公众号支付)。
var bizErr *wechatpay.V2BusinessError
if stderrors.As(callErr, &bizErr) {
if _, err = a.integration.Complete(ctx, attempt.IntegrationID, integrationlog.Completion{
Result: constants.IntegrationResultFailed, ProviderCode: bizErr.Code, ProviderMessage: bizErr.Message,
ResponseSummary: map[string]any{"success": false}, DurationMS: time.Since(startedAt).Milliseconds(),
}); err != nil {
return agentrecharge.OnlinePaymentResult{}, err
}
return agentrecharge.OnlinePaymentResult{}, apperrors.New(apperrors.CodeWechatConfigUnavailable, bizErr.Error())
}
if callErr != nil {
return agentrecharge.OnlinePaymentResult{}, a.completeUnknown(ctx, attempt.IntegrationID, startedAt, callErr)
}

View File

@@ -22,7 +22,9 @@ type CardTrafficCollection struct {
StaleGuarded *bool `gorm:"column:stale_guarded" json:"stale_guarded"`
DeltaMB *float64 `gorm:"column:delta_mb;type:numeric(14,3)" json:"delta_mb"`
EventID string `gorm:"column:event_id;type:varchar(128);not null;default:''" json:"event_id"`
CreatedAt time.Time `gorm:"column:created_at;not null;default:now()" json:"created_at"`
CarrierID uint `gorm:"column:carrier_id;not null;default:0" json:"carrier_id"`
CollectionRaw
CreatedAt time.Time `gorm:"column:created_at;not null;default:now()" json:"created_at"`
}
// TableName 指定表名。
@@ -30,6 +32,43 @@ func (CardTrafficCollection) TableName() string {
return "tb_card_traffic_collection"
}
// CollectionRaw 是采集记录保存的网关原始数据(成功表与失败表共用)。
type CollectionRaw struct {
RawRequest datatypes.JSON `gorm:"column:raw_request;type:jsonb" json:"raw_request"`
HTTPStatus *int `gorm:"column:http_status" json:"http_status"`
GatewayCode *int `gorm:"column:gateway_code" json:"gateway_code"`
GatewayMsg string `gorm:"column:gateway_msg;type:varchar(500);not null;default:''" json:"gateway_msg"`
GatewayTraceID string `gorm:"column:gateway_trace_id;type:varchar(128);not null;default:''" json:"gateway_trace_id"`
RawResponse datatypes.JSON `gorm:"column:raw_response;type:jsonb" json:"raw_response"`
RawResponseText string `gorm:"column:raw_response_text;type:text;not null;default:''" json:"raw_response_text"`
RawTruncated bool `gorm:"column:raw_truncated;not null;default:false" json:"raw_truncated"`
GatewayAttempts int `gorm:"column:gateway_attempts;not null;default:0" json:"gateway_attempts"`
}
// CardTrafficCollectionFailure 卡流量采集失败记录:所有被采集的卡每次失败一条,按月分区,在线保留 2 个月。
type CardTrafficCollectionFailure struct {
ID uint `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
IotCardID uint `gorm:"column:iot_card_id;not null" json:"iot_card_id"`
ICCID string `gorm:"column:iccid;type:varchar(30);not null;default:''" json:"iccid"`
CarrierID uint `gorm:"column:carrier_id;not null;default:0" json:"carrier_id"`
ObservedAt time.Time `gorm:"column:observed_at;primaryKey;not null" json:"observed_at"`
ObservationID string `gorm:"column:observation_id;type:varchar(128);not null;default:''" json:"observation_id"`
Source string `gorm:"column:source;type:varchar(32);not null;default:''" json:"source"`
Scene string `gorm:"column:scene;type:varchar(64);not null;default:''" json:"scene"`
Result string `gorm:"column:result;type:varchar(32);not null" json:"result"`
ErrorCategory string `gorm:"column:error_category;type:varchar(30);not null;default:''" json:"error_category"`
ProviderCode string `gorm:"column:provider_code;type:varchar(30);not null;default:''" json:"provider_code"`
ProviderMessage string `gorm:"column:provider_message;type:varchar(500);not null;default:''" json:"provider_message"`
DurationMS int `gorm:"column:duration_ms;not null;default:0" json:"duration_ms"`
CollectionRaw
CreatedAt time.Time `gorm:"column:created_at;not null;default:now()" json:"created_at"`
}
// TableName 指定表名。
func (CardTrafficCollectionFailure) TableName() string {
return "tb_card_traffic_collection_failure"
}
// PackageUsageAdjustment 套餐流量人工冲正流水:只新增,不修改、不删除。
type PackageUsageAdjustment struct {
ID uint `gorm:"column:id;primaryKey;autoIncrement" json:"id"`

View File

@@ -27,7 +27,9 @@ type AssetResolveResponse struct {
ActivationStatus int `json:"activation_status" description:"激活状态:0未激活 1已激活;设备需有生效中主套餐且任意绑定卡已实名"`
ActivationStatusName string `json:"activation_status_name" description:"激活状态名称(中文)"`
RealNameStatus int `json:"real_name_status" description:"实名状态:0未实名 1已实名"`
RealNameAt *time.Time `json:"real_name_at" description:"最近一次完成实名的时间,未实名时为 null"`
RealNameAt *time.Time `json:"real_name_at" description:"实名时间:上游返回的实名时间优先,否则为首次读到已实名的时间;未实名时为 null"`
RealNameAtSource string `json:"real_name_at_source,omitempty" description:"实名时间来源(卡资产):upstream 上游返回 / first_observed 首次读到 / migrated 迁移沿用"`
RealNameAtSourceName string `json:"real_name_at_source_name,omitempty" description:"实名时间来源中文名"`
RealnamePolicy string `json:"realname_policy" description:"实名认证策略 (none:无需实名, before_order:先实名后充值/购买, after_order:先充值/购买后实名)"`
CurrentPackage string `json:"current_package" description:"当前套餐名称(无套餐时为空)"`
CurrentPackageUsageID *uint `json:"current_package_usage_id" description:"当前主套餐的套餐使用记录ID,无主套餐时为 null"`
@@ -116,7 +118,9 @@ type BoundCardInfo struct {
MSISDN string `json:"msisdn,omitempty" description:"手机号"`
NetworkStatus int `json:"network_status" description:"网络状态:0停机 1开机"`
RealNameStatus int `json:"real_name_status" description:"实名状态:0未实名 1已实名"`
RealNameAt *time.Time `json:"real_name_at" description:"该卡最近一次完成实名的时间,未实名时为 null"`
RealNameAt *time.Time `json:"real_name_at" description:"该卡实名时间:上游返回的实名时间优先,否则为首次读到已实名的时间;未实名时为 null"`
RealNameAtSource string `json:"real_name_at_source,omitempty" description:"实名时间来源:upstream 上游返回 / first_observed 首次读到 / migrated 迁移沿用"`
RealNameAtSourceName string `json:"real_name_at_source_name,omitempty" description:"实名时间来源中文名"`
SlotPosition int `json:"slot_position,omitempty" description:"插槽位置"`
IsCurrent bool `json:"is_current" description:"是否为当前使用的卡"`
CarrierID uint `json:"carrier_id,omitempty" description:"运营商ID"`
@@ -281,6 +285,8 @@ type PackageTrafficAdjustmentListRequest struct {
PackageUsageID uint `path:"package_usage_id" description:"套餐使用记录ID" required:"true"`
Page int `query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码,默认 1"`
PageSize int `query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页条数,默认 20"`
StartTime string `query:"start_time" description:"开始时间(RFC3339 或 2006-01-02 15:04:05,上海时间),选填;与结束时间同时传,跨度不超过 31 天"`
EndTime string `query:"end_time" description:"结束时间(不含),选填"`
}
// PackageTrafficAdjustmentItem 冲正流水。
@@ -296,6 +302,7 @@ type PackageTrafficAdjustmentItem struct {
RefObservationID string `json:"ref_observation_id" description:"关联的采集 ID"`
RefEventID string `json:"ref_event_id" description:"关联的流量事件 ID"`
OperatorID uint `json:"operator_id" description:"操作人账号ID"`
OperatorName string `json:"operator_name" description:"操作人账号用户名"`
CreatedAt time.Time `json:"created_at" description:"冲正时间"`
}
@@ -312,6 +319,11 @@ type CardTrafficCollectionListRequest struct {
EndTime string `query:"end_time" validate:"required" required:"true" description:"结束时间(不含),最长跨度 31 天"`
Page int `query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码,默认 1"`
PageSize int `query:"page_size" validate:"omitempty,min=1,max=200" minimum:"1" maximum:"200" description:"每页条数,默认 50"`
Decision string `query:"decision" validate:"omitempty,max=32" description:"写入判断筛选(只作用于成功记录)"`
Source string `query:"source" validate:"omitempty,max=32" description:"来源筛选"`
Scene string `query:"scene" validate:"omitempty,max=64" description:"场景筛选"`
// IncludeFailures 为 true 时合并采集失败记录,按采集时间倒序返回。
IncludeFailures bool `query:"include_failures" description:"是否包含采集失败记录,默认 false"`
}
// CardTrafficCollectionItem 卡流量采集记录。
@@ -329,6 +341,13 @@ type CardTrafficCollectionItem struct {
StaleGuarded *bool `json:"stale_guarded" description:"写入时是否触发重置日防旧值"`
DeltaMB *float64 `json:"delta_mb" description:"写入时本次增量(MB)"`
EventID string `json:"event_id" description:"流量事件 ID"`
// RecordKind 区分成功表与失败表记录:success/failure。
RecordKind string `json:"record_kind" description:"记录类型:success 采集成功,failure 采集失败"`
ErrorCategory string `json:"error_category,omitempty" description:"错误类别(失败记录)"`
ProviderCode string `json:"provider_code,omitempty" description:"上游返回码(失败记录)"`
ProviderMessage string `json:"provider_message,omitempty" description:"上游返回信息或错误信息(失败记录)"`
DurationMS int `json:"duration_ms,omitempty" description:"调用耗时毫秒(失败记录)"`
GatewayRawItem
}
// CardTrafficCollectionListResponse 卡流量采集记录分页结果。

View File

@@ -0,0 +1,114 @@
package dto
import "time"
// CardRealnameHistoryListRequest 查询单卡实名时间历史。
type CardRealnameHistoryListRequest struct {
ID uint `json:"-" path:"id" description:"IoT卡ID"`
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:"每页数量"`
}
// CardRealnameCurrentResponse 是卡当前实名时间。
type CardRealnameCurrentResponse struct {
CardID uint `json:"card_id" description:"IoT卡ID"`
RealnameAt *time.Time `json:"realname_at" description:"当前实名时间:上游返回的实名时间优先,否则为首次读到已实名的时间"`
RealnameAtSource string `json:"realname_at_source" description:"实名时间来源:upstream 上游返回 / first_observed 首次读到 / migrated 迁移沿用"`
RealnameAtSourceName string `json:"realname_at_source_name" description:"实名时间来源中文名"`
UpstreamRealnameAt *time.Time `json:"upstream_realname_at" description:"上游最近一次返回的实名时间"`
FirstObservedAt *time.Time `json:"first_observed_at" description:"首次读到已实名的时间"`
ResetPending bool `json:"reset_pending" description:"是否等待二次实名(仅后台展示)"`
ResetAt *time.Time `json:"reset_at" description:"二次实名清除时间"`
ResetBaselineAt *time.Time `json:"reset_baseline_at" description:"清除前的上游实名时间(新旧判定基准)"`
ResetBatchID *uint `json:"reset_batch_id" description:"所属二次实名批次 ID"`
}
// CardRealnameHistoryItem 是一条实名时间变化历史。
type CardRealnameHistoryItem struct {
ID uint `json:"id" description:"历史 ID"`
CardID uint `json:"card_id" description:"IoT卡ID"`
ICCID string `json:"iccid" description:"ICCID"`
BeforeAt *time.Time `json:"before_at" description:"原实名时间"`
AfterAt *time.Time `json:"after_at" description:"新实名时间"`
AfterSource string `json:"after_source" description:"新实名时间来源"`
AfterSourceName string `json:"after_source_name" description:"新实名时间来源中文名"`
ChangeType string `json:"change_type" description:"变化类型:first 首次实名 / upstream_fix 上游更正 / reset 二次实名清除 / reset_completed 二次实名完成 / reset_reverted 二次实名撤销 / migrated 迁移补录"`
ChangeTypeName string `json:"change_type_name" description:"变化类型中文名"`
ObservationSource string `json:"observation_source" description:"观测来源:polling 轮询 / manual_sync 手动刷新 / carrier_callback 回调 / business_event 业务观测 / manual_override 人工 / migration 迁移 / package_silence 沉默期判定"`
ObservationSourceName string `json:"observation_source_name" description:"观测来源中文名"`
ResetBatchID *uint `json:"reset_batch_id" description:"关联二次实名批次 ID"`
OperatorID uint `json:"operator_id" description:"操作人账号 ID(人工时)"`
OperatorName string `json:"operator_name" description:"操作人名称"`
ObservedAt time.Time `json:"observed_at" description:"发现时间"`
CreatedAt time.Time `json:"created_at" description:"记录时间"`
}
// CardRealnameHistoryResponse 是单卡实名记录:当前实名时间与历史分页。
type CardRealnameHistoryResponse struct {
Current CardRealnameCurrentResponse `json:"current" description:"当前实名时间"`
Items []CardRealnameHistoryItem `json:"items" description:"实名时间历史(按时间倒序)"`
Total int64 `json:"total" description:"历史总数"`
Page int `json:"page" description:"页码"`
PageSize int `json:"page_size" description:"每页数量"`
}
// RealnameResetImportRequest 导入二次实名名单。
type RealnameResetImportRequest struct {
Identifiers []string `json:"identifiers" validate:"required,min=1,max=1000,dive,required,max=64" required:"true" description:"资产号列表:ICCID / 虚拟号 / IMEI,设备展开为其全部绑定卡,最多 1000 个"`
Reason string `json:"reason" validate:"required,min=1,max=500" required:"true" description:"原因"`
ImportFileKey string `json:"import_file_key" validate:"omitempty,max=500" description:"导入文件对象存储 Key(可选,留档)"`
}
// RealnameResetItem 是二次实名批次的一行结果。
type RealnameResetItem struct {
RowNo int `json:"row_no" description:"行号(从 1 开始)"`
Input string `json:"input" description:"导入的资产号"`
CardID uint `json:"card_id,omitempty" description:"卡 ID"`
ICCID string `json:"iccid,omitempty" description:"ICCID"`
Result string `json:"result" description:"结果:pending 等待二次实名 / completed 已完成 / reverted 已撤销 / skipped 跳过 / failed 失败"`
ResultName string `json:"result_name" description:"结果中文名"`
Reason string `json:"reason,omitempty" description:"跳过或失败原因"`
}
// RealnameResetBatchResponse 是二次实名批次。
type RealnameResetBatchResponse struct {
ID uint `json:"id" description:"批次 ID"`
BatchNo string `json:"batch_no" description:"批次号"`
Reason string `json:"reason" description:"原因"`
ImportFileKey string `json:"import_file_key" description:"导入文件 Key"`
TotalCount int `json:"total_count" description:"处理卡数(含跳过)"`
SucceededCount int `json:"succeeded_count" description:"已清除卡数"`
SkippedCount int `json:"skipped_count" description:"跳过或失败数"`
CompletedCount int `json:"completed_count" description:"已完成二次实名卡数"`
RevertedCount int `json:"reverted_count" description:"已撤销卡数"`
PendingCount int `json:"pending_count" description:"仍在等待二次实名卡数"`
OperatorID uint `json:"operator_id" description:"操作人账号 ID"`
OperatorName string `json:"operator_name" description:"操作人"`
CreatedAt time.Time `json:"created_at" description:"导入时间"`
Items []RealnameResetItem `json:"items,omitempty" description:"逐行结果(详情返回)"`
}
// RealnameResetBatchListRequest 查询二次实名批次。
type RealnameResetBatchListRequest struct {
BatchNo string `json:"batch_no" query:"batch_no" validate:"omitempty,max=40" description:"批次号"`
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:"每页数量"`
}
// RealnameResetBatchIDRequest 是批次路径参数。
type RealnameResetBatchIDRequest struct {
ID uint `json:"-" path:"id" description:"批次 ID"`
}
// RealnameResetRevertRequest 撤销二次实名。
type RealnameResetRevertRequest struct {
ID uint `json:"-" path:"id" description:"批次 ID"`
CardIDs []uint `json:"card_ids" validate:"omitempty,max=1000" description:"只撤销这些卡;为空撤销整批仍在等待的卡"`
}
// RealnameResetRevertResponse 撤销结果。
type RealnameResetRevertResponse struct {
RevertedCount int `json:"reverted_count" description:"撤销成功卡数"`
FailedCount int `json:"failed_count" description:"撤销失败卡数"`
Failures []string `json:"failures,omitempty" description:"失败说明"`
}

View File

@@ -9,7 +9,7 @@ type CreateExchangeRequest struct {
FlowType string `json:"flow_type" validate:"omitempty,oneof=shipping direct" enum:"shipping,direct" description:"换货流程类型 (shipping:物流换货, direct:直接换货)"`
NewIdentifier string `json:"new_identifier" validate:"omitempty,min=1,max=100" minLength:"1" maxLength:"100" description:"新资产输入标识,direct 流程必填;卡支持 ICCID、接入号、虚拟号,设备支持虚拟号、IMEI、SN"`
MigrateData *bool `json:"migrate_data" description:"是否执行全量迁移,direct 流程未传按 false 处理"`
ExchangeReason string `json:"exchange_reason" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"换货原因"`
ExchangeReason string `json:"exchange_reason" validate:"required,min=1,max=500" required:"true" minLength:"1" maxLength:"500" description:"换货原因"`
Remark *string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"备注"`
}

View File

@@ -0,0 +1,34 @@
package dto
import (
"strings"
"testing"
"github.com/go-playground/validator/v10"
)
// 换货原因按字符计数,上限 500:从微信复制的多行说明(含换行)不超过 500 字都应通过校验。
func TestCreateExchangeRequest_ExchangeReasonLength(t *testing.T) {
validate := validator.New()
multiLine := "862639070766110(门店:862639070766110机头,862639070743218后盖)\n\n" +
"862639070743218(厂家:862639070766110后盖,862639070743218机头)\n\n这两台后盖机头窜了。"
cases := []struct {
name string
reason string
wantErr bool
}{
{name: "多行说明124字", reason: multiLine, wantErr: false},
{name: "500个中文字", reason: strings.Repeat("换", 500), wantErr: false},
{name: "501个中文字", reason: strings.Repeat("换", 501), wantErr: true},
{name: "空", reason: "", wantErr: true},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
req := CreateExchangeRequest{OldAssetType: "device", OldIdentifier: "862639070743218", ExchangeReason: tc.reason}
err := validate.Struct(req)
if (err != nil) != tc.wantErr {
t.Fatalf("wantErr=%v, err=%v", tc.wantErr, err)
}
})
}
}

View File

@@ -140,6 +140,10 @@ type StopResumeRecordListRequest 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:"每页数量"`
ICCID string `json:"iccid" query:"iccid" validate:"omitempty,max=30" maxLength:"30" description:"ICCID"`
Identifier string `json:"identifier" query:"identifier" validate:"omitempty,max=50" maxLength:"50" description:"资产标识(虚拟号/ICCID/MSISDN,设备支持虚拟号/IMEI/SN,取其绑定卡)"`
Scene string `json:"scene" query:"scene" validate:"omitempty,max=50" maxLength:"50" description:"场景"`
Reason string `json:"reason" query:"reason" validate:"omitempty,max=50" maxLength:"50" description:"停机原因"`
CommandID string `json:"command_id" query:"command_id" validate:"omitempty,max=64" maxLength:"64" description:"指令号(同一次停复机命令的多次尝试共用)"`
CarrierID *uint `json:"carrier_id" query:"carrier_id" validate:"omitempty" description:"运营商账户ID"`
Action string `json:"action" query:"action" validate:"omitempty,oneof=stop start" description:"动作 (stop:停机, start:复机)"`
Source string `json:"source" query:"source" validate:"omitempty,max=50" maxLength:"50" description:"来源"`
@@ -156,6 +160,9 @@ type CardStopResumeRecordListRequest struct {
PageSize int `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页数量"`
StartTime time.Time `json:"start_time" query:"start_time" description:"开始时间(RFC3339),为空取最近 31 天"`
EndTime time.Time `json:"end_time" query:"end_time" description:"结束时间(RFC3339),为空取当前"`
Action string `json:"action" query:"action" validate:"omitempty,oneof=stop start" description:"动作 (stop:停机, start:复机)"`
Result string `json:"result" query:"result" validate:"omitempty,oneof=success failed unknown already_target skipped" description:"结果 (success:成功, failed:失败, unknown:结果未知, already_target:已是目标状态, skipped:跳过)"`
Source string `json:"source" query:"source" validate:"omitempty,max=50" maxLength:"50" description:"来源"`
}
// StopResumeRecordResponse 停复机记录响应

View File

@@ -194,5 +194,8 @@ type PackageUsageDetailResponse struct {
PackageUsageID uint `json:"package_usage_id" description:"套餐使用记录ID"`
PackageName string `json:"package_name" description:"套餐名称"`
Records []PackageUsageDailyRecordResponse `json:"records" description:"流量日记录列表"`
TotalUsageMB int64 `json:"total_usage_mb" description:"总使用流量(MB)"`
TotalUsageMB int64 `json:"total_usage_mb" description:"总使用流量(MB),为筛选范围内全部记录之和"`
Total int64 `json:"total" description:"筛选范围内记录总数"`
Page int `json:"page" description:"页码;未传 page_size 时为 0,返回全部记录"`
PageSize int `json:"page_size" description:"每页条数;未传时为 0,返回全部记录"`
}

View File

@@ -115,6 +115,12 @@ type SilenceExtensionOption struct {
// SilenceEligibilityResponse 延期资格(技术方案 §12.2),金额与月数全部由后端计算。
type SilenceEligibilityResponse struct {
PackageUsageID uint `json:"package_usage_id" description:"套餐记录 ID"`
PackageName string `json:"package_name,omitempty" description:"套餐名称"`
AssetIdentifier string `json:"asset_identifier,omitempty" description:"资产标识"`
PurchasedAt *time.Time `json:"purchased_at,omitempty" description:"套餐订购时间(购买支付成功时间)"`
ActivatedAt *time.Time `json:"activated_at,omitempty" description:"套餐生效时间(未实名激活时为空)"`
ExpiresAt *time.Time `json:"expires_at,omitempty" description:"套餐到期时间(未实名激活时为空)"`
SilenceDeadlineAt *time.Time `json:"silence_deadline_at,omitempty" description:"沉默期截止时间(截止日 23:59:59)"`
SilenceStatus string `json:"silence_status" description:"沉默期状态(待实名但已到期的先判定为过期)"`
CanExtend bool `json:"can_extend" description:"能否办理付费延期"`
SpecialExtensionAvailable bool `json:"special_extension_available" description:"能否申请特殊延期(只要求套餐已过期)"`
@@ -159,6 +165,7 @@ type SilenceOnlineOrderRequest struct {
PackageUsageID uint `json:"package_usage_id" validate:"required,min=1" required:"true" description:"套餐记录 ID"`
Days int `json:"days" validate:"required,min=1,max=3650" required:"true" description:"输入的延期天数"`
PaymentMethod string `json:"payment_method" validate:"required,oneof=wechat alipay" required:"true" description:"支付方式:wechat / alipay(经商户池路由)"`
AppType string `json:"app_type" validate:"omitempty,oneof=official_account miniapp" description:"H5 微信支付时的应用类型:official_account / miniapp;传入时在微信内直接拉起支付(JSAPI),返回 pay_config"`
RequestID string `json:"request_id" validate:"required,min=1,max=64" required:"true" description:"下单幂等键"`
EvidenceRefs []string `json:"evidence_refs" validate:"omitempty,max=10,dive,max=500" description:"客户申请记录或截图对象存储 Key(后台创建时填写)"`
}
@@ -178,51 +185,52 @@ type SilenceOfflineOrderRequest struct {
// SilenceExtensionOrderResponse 延期订单。
type SilenceExtensionOrderResponse struct {
ID uint `json:"id" description:"订单 ID"`
OrderNo string `json:"order_no" description:"订单号"`
BatchNo string `json:"batch_no,omitempty" description:"批次号"`
PackageUsageID uint `json:"package_usage_id" description:"套餐记录 ID"`
PackageID uint `json:"package_id" description:"套餐 ID"`
PackageName string `json:"package_name" description:"套餐名称快照"`
AssetType string `json:"asset_type" description:"资产类型 iot_card / device"`
AssetID uint `json:"asset_id" description:"资产 ID"`
AssetIdentifier string `json:"asset_identifier" description:"资产标识快照"`
ShopID uint `json:"shop_id" description:"下单时资产所属店铺"`
CustomerID *uint `json:"customer_id,omitempty" description:"H5 下单的客户"`
Source string `json:"source" description:"来源:client / admin / offline"`
SourceName string `json:"source_name" description:"来源名称"`
InputDays int `json:"input_days" description:"输入天数"`
Months int `json:"months" description:"计费月数"`
ExtensionDays int `json:"extension_days" description:"计费 / 延长天数"`
UnitPrice int64 `json:"unit_price" description:"单价(分/月)"`
Amount int64 `json:"amount" description:"应付金额(分)"`
PolicyName string `json:"policy_name" description:"政策名称快照"`
BeforeDeadlineAt time.Time `json:"before_deadline_at" description:"下单时截止时间"`
ExpectedDeadlineAt time.Time `json:"expected_deadline_at" description:"预计新截止时间"`
Status string `json:"status" description:"状态:pending_payment/pending_approval/rejected/paid/completed/closed/exception/refunded"`
StatusName string `json:"status_name" description:"状态名称"`
PaymentMethod string `json:"payment_method" description:"支付方式:wechat/alipay/offline"`
PaymentMerchantName string `json:"payment_merchant_name,omitempty" description:"收款商户名称(取已支付或已退款支付单快照)"`
ThirdPartyTradeNo string `json:"third_party_trade_no,omitempty" description:"交易流水号"`
PaymentNo string `json:"payment_no,omitempty" description:"支付单号"`
QRContent string `json:"qr_content,omitempty" description:"支付内容(待支付时返回,前端渲染为二维码或跳转链接)"`
OfflinePaymentMethodName string `json:"offline_payment_method_name,omitempty" description:"线下收款方式"`
OfflineTradeNo string `json:"offline_trade_no,omitempty" description:"线下交易单号"`
PaymentVoucherKeys []string `json:"payment_voucher_keys,omitempty" description:"线下收款凭证"`
EvidenceRefs []string `json:"evidence_refs,omitempty" description:"申请依据"`
ApprovalRequired bool `json:"approval_required" description:"是否需要审批"`
ApprovalInstanceID *uint `json:"approval_instance_id,omitempty" description:"审批实例 ID"`
PaidAmount *int64 `json:"paid_amount,omitempty" description:"实付金额(分)"`
PaidAt *time.Time `json:"paid_at,omitempty" description:"支付时间"`
ExpireAt *time.Time `json:"expire_at,omitempty" description:"支付截止时间"`
CompletedAt *time.Time `json:"completed_at,omitempty" description:"延期生效时间"`
ExceptionCode string `json:"exception_code,omitempty" description:"异常原因码"`
ExceptionSummary string `json:"exception_summary,omitempty" description:"异常说明"`
RefundNo string `json:"refund_no,omitempty" description:"原路退款单号(仅执行异常)"`
RefundAmount *int64 `json:"refund_amount,omitempty" description:"退款金额"`
RefundedAt *time.Time `json:"refunded_at,omitempty" description:"退款时间"`
CreatedBy *uint `json:"created_by,omitempty" description:"后台创建人"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
ID uint `json:"id" description:"订单 ID"`
OrderNo string `json:"order_no" description:"订单号"`
BatchNo string `json:"batch_no,omitempty" description:"批次号"`
PackageUsageID uint `json:"package_usage_id" description:"套餐记录 ID"`
PackageID uint `json:"package_id" description:"套餐 ID"`
PackageName string `json:"package_name" description:"套餐名称快照"`
AssetType string `json:"asset_type" description:"资产类型 iot_card / device"`
AssetID uint `json:"asset_id" description:"资产 ID"`
AssetIdentifier string `json:"asset_identifier" description:"资产标识快照"`
ShopID uint `json:"shop_id" description:"下单时资产所属店铺"`
CustomerID *uint `json:"customer_id,omitempty" description:"H5 下单的客户"`
Source string `json:"source" description:"来源:client / admin / offline"`
SourceName string `json:"source_name" description:"来源名称"`
InputDays int `json:"input_days" description:"输入天数"`
Months int `json:"months" description:"计费月数"`
ExtensionDays int `json:"extension_days" description:"计费 / 延长天数"`
UnitPrice int64 `json:"unit_price" description:"单价(分/月)"`
Amount int64 `json:"amount" description:"应付金额(分)"`
PolicyName string `json:"policy_name" description:"政策名称快照"`
BeforeDeadlineAt time.Time `json:"before_deadline_at" description:"下单时截止时间"`
ExpectedDeadlineAt time.Time `json:"expected_deadline_at" description:"预计新截止时间"`
Status string `json:"status" description:"状态:pending_payment/pending_approval/rejected/paid/completed/closed/exception/refunded"`
StatusName string `json:"status_name" description:"状态名称"`
PaymentMethod string `json:"payment_method" description:"支付方式:wechat/alipay/offline"`
PaymentMerchantName string `json:"payment_merchant_name,omitempty" description:"收款商户名称(取已支付或已退款支付单快照)"`
ThirdPartyTradeNo string `json:"third_party_trade_no,omitempty" description:"交易流水号"`
PaymentNo string `json:"payment_no,omitempty" description:"支付单号"`
QRContent string `json:"qr_content,omitempty" description:"支付内容(待支付时返回,前端渲染为二维码或跳转链接)"`
PayConfig *ClientPayConfig `json:"pay_config,omitempty" description:"微信内直接支付(JSAPI)参数,H5 带 app_type 下微信单时返回,前端用它拉起支付"`
OfflinePaymentMethodName string `json:"offline_payment_method_name,omitempty" description:"线下收款方式"`
OfflineTradeNo string `json:"offline_trade_no,omitempty" description:"线下交易单号"`
PaymentVoucherKeys []string `json:"payment_voucher_keys,omitempty" description:"线下收款凭证"`
EvidenceRefs []string `json:"evidence_refs,omitempty" description:"申请依据"`
ApprovalRequired bool `json:"approval_required" description:"是否需要审批"`
ApprovalInstanceID *uint `json:"approval_instance_id,omitempty" description:"审批实例 ID"`
PaidAmount *int64 `json:"paid_amount,omitempty" description:"实付金额(分)"`
PaidAt *time.Time `json:"paid_at,omitempty" description:"支付时间"`
ExpireAt *time.Time `json:"expire_at,omitempty" description:"支付截止时间"`
CompletedAt *time.Time `json:"completed_at,omitempty" description:"延期生效时间"`
ExceptionCode string `json:"exception_code,omitempty" description:"异常原因码"`
ExceptionSummary string `json:"exception_summary,omitempty" description:"异常说明"`
RefundNo string `json:"refund_no,omitempty" description:"原路退款单号(仅执行异常)"`
RefundAmount *int64 `json:"refund_amount,omitempty" description:"退款金额"`
RefundedAt *time.Time `json:"refunded_at,omitempty" description:"退款时间"`
CreatedBy *uint `json:"created_by,omitempty" description:"后台创建人"`
CreatedAt time.Time `json:"created_at" description:"创建时间"`
}
// SilenceSpecialItem 特殊延期的一条明细。
@@ -410,6 +418,13 @@ type SilenceIDPath struct {
ID uint `json:"id" params:"id" path:"id" validate:"required,min=1" required:"true" description:"ID"`
}
// SilenceOrderCancelRequest 作废待支付延期订单请求。
type SilenceOrderCancelRequest struct {
// ID 来自路径参数,由 handler 单独校验;这里不加 validate,否则解析请求体时一律报"必须大于 0"
ID uint `json:"-" params:"id" path:"id" required:"true" description:"延期订单 ID"`
Reason string `json:"reason" validate:"omitempty,max=200" maxLength:"200" description:"作废原因(选填)"`
}
// SilenceRecordListRequest 沉默期流水查询请求。
type SilenceRecordListRequest struct {
PackageUsageID uint `json:"package_usage_id" query:"package_usage_id" validate:"required,min=1" required:"true" description:"套餐记录 ID"`

View File

@@ -0,0 +1,233 @@
package dto
import (
"encoding/json"
"time"
)
// RecordRangeQuery 是记录查询的公共条件:资产标识选填(不传查全部),时间范围必填(跨度不超过 31 天),分页。
type RecordRangeQuery struct {
Identifier string `query:"identifier" validate:"omitempty,max=50" maxLength:"50" description:"资产标识(虚拟号/ICCID/MSISDN,设备支持 IMEI/SN);不传查全部"`
StartTime string `query:"start_time" validate:"required" required:"true" description:"开始时间(RFC3339 或 2006-01-02 15:04:05,上海时间)"`
EndTime string `query:"end_time" validate:"required" required:"true" description:"结束时间(不含),跨度不超过 31 天"`
Page int `query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码,默认 1"`
PageSize int `query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页条数,默认 20,最大 100"`
}
// RecordDateRangeQuery 是按日期查询的公共条件:资产标识选填,日期范围必填(含首尾,跨度不超过 31 天),分页。
type RecordDateRangeQuery struct {
Identifier string `query:"identifier" validate:"omitempty,max=50" maxLength:"50" description:"资产标识(虚拟号/ICCID/MSISDN,设备支持 IMEI/SN);不传查全部"`
StartDate string `query:"start_date" validate:"required" required:"true" description:"开始日期(2006-01-02,含)"`
EndDate string `query:"end_date" validate:"required" required:"true" description:"结束日期(2006-01-02,含),跨度不超过 31 天"`
Page int `query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码,默认 1"`
PageSize int `query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页条数,默认 20,最大 100"`
}
// GatewayRawItem 是采集记录保存的网关原始请求与响应。
type GatewayRawItem struct {
RawRequest json.RawMessage `json:"raw_request" description:"网关明文业务请求(加密前),未收集时为 null"`
HTTPStatus *int `json:"http_status" description:"HTTP 状态码,未拿到响应时为 null"`
GatewayCode *int `json:"gateway_code" description:"网关响应 code"`
GatewayMsg string `json:"gateway_msg" description:"网关响应 msg"`
GatewayTraceID string `json:"gateway_trace_id" description:"网关响应 trace_id"`
RawResponse json.RawMessage `json:"raw_response" description:"网关原始响应体(JSON 且不超过 4KB 时)"`
RawResponseText string `json:"raw_response_text" description:"网关原始响应体文本(非 JSON 或超过 4KB 截断时)"`
RawTruncated bool `json:"raw_truncated" description:"原始响应是否被截断"`
GatewayAttempts int `json:"gateway_attempts" description:"网关客户端内部 HTTP 尝试次数(原始数据为最后一次)"`
}
// TrafficCollectionListRequest 采集成功记录列表请求。
type TrafficCollectionListRequest struct {
RecordRangeQuery
CarrierID *uint `query:"carrier_id" validate:"omitempty,min=1" description:"运营商账户ID"`
Decision string `query:"decision" validate:"omitempty,max=32" description:"写入判断:written/baseline/queue_not_full/slope_negative/out_of_order/settled_existing"`
Source string `query:"source" validate:"omitempty,max=32" description:"来源:polling/manual_sync/business_event"`
Scene string `query:"scene" validate:"omitempty,max=64" description:"场景"`
HasDelta *bool `query:"has_delta" description:"是否产生增量:true 只看增量大于 0,false 只看没有增量"`
StaleGuarded *bool `query:"stale_guarded" description:"是否触发重置日防旧值"`
}
// TrafficCollectionRecordItem 采集成功记录。
type TrafficCollectionRecordItem struct {
CardTrafficCollectionItem
IotCardID uint `json:"iot_card_id" description:"卡ID"`
ICCID string `json:"iccid" description:"ICCID"`
CarrierID uint `json:"carrier_id" description:"运营商账户ID(历史记录为 0)"`
CarrierName string `json:"carrier_name" description:"运营商账户名称"`
}
// TrafficCollectionRecordListResponse 采集成功记录分页结果。
type TrafficCollectionRecordListResponse struct {
Items []TrafficCollectionRecordItem `json:"items" description:"采集成功记录"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"页码"`
PageSize int `json:"page_size" description:"每页条数"`
}
// TrafficCollectionFailureListRequest 采集失败记录列表请求。
type TrafficCollectionFailureListRequest struct {
RecordRangeQuery
CarrierID *uint `query:"carrier_id" validate:"omitempty,min=1" description:"运营商账户ID"`
Result string `query:"result" validate:"omitempty,oneof=failed rate_limited invalid_payload no_reading invalid_reading" description:"失败类型:failed/rate_limited/invalid_payload/no_reading/invalid_reading"`
ErrorCategory string `query:"error_category" validate:"omitempty,max=30" description:"错误类别:timeout/network/http/invalid_response/upstream 等"`
ProviderCode string `query:"provider_code" validate:"omitempty,max=30" description:"上游返回码"`
Source string `query:"source" validate:"omitempty,max=32" description:"来源"`
Scene string `query:"scene" validate:"omitempty,max=64" description:"场景"`
}
// TrafficCollectionFailureItem 采集失败记录。
type TrafficCollectionFailureItem struct {
ID uint `json:"id" description:"记录ID"`
IotCardID uint `json:"iot_card_id" description:"卡ID"`
ICCID string `json:"iccid" description:"ICCID"`
CarrierID uint `json:"carrier_id" description:"运营商账户ID"`
CarrierName string `json:"carrier_name" description:"运营商账户名称"`
ObservedAt time.Time `json:"observed_at" description:"采集时间"`
ObservationID string `json:"observation_id" description:"采集 ID(等于对接日志 integration_id)"`
Source string `json:"source" description:"来源"`
Scene string `json:"scene" description:"场景"`
Result string `json:"result" description:"失败类型"`
ErrorCategory string `json:"error_category" description:"错误类别"`
ProviderCode string `json:"provider_code" description:"上游返回码"`
ProviderMessage string `json:"provider_message" description:"上游返回信息或错误信息"`
DurationMS int `json:"duration_ms" description:"调用耗时(毫秒)"`
GatewayRawItem
}
// TrafficCollectionFailureListResponse 采集失败记录分页结果。
type TrafficCollectionFailureListResponse struct {
Items []TrafficCollectionFailureItem `json:"items" description:"采集失败记录"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"页码"`
PageSize int `json:"page_size" description:"每页条数"`
}
// CardDailyUsageListRequest 卡日流量列表请求。
type CardDailyUsageListRequest struct {
RecordDateRangeQuery
CarrierID *uint `query:"carrier_id" validate:"omitempty,min=1" description:"运营商账户ID"`
MinUsageMB *float64 `query:"min_usage_mb" validate:"omitempty,min=0" description:"当日已结算增量下限(MB),用于排查异常大流量"`
}
// CardDailyUsageItem 卡日流量(卡日快照 tb_card_flow_day)。
type CardDailyUsageItem struct {
ID uint `json:"id" description:"记录ID"`
IotCardID uint `json:"iot_card_id" description:"卡ID"`
ICCID string `json:"iccid" description:"ICCID"`
CarrierID uint `json:"carrier_id" description:"运营商账户ID"`
CarrierName string `json:"carrier_name" description:"运营商账户名称"`
Date string `json:"date" description:"日期(上海)"`
SettledMB float64 `json:"settled_mb" description:"当日已结算增量合计(MB),即当日用量"`
MonthUsedMB float64 `json:"month_used_mb" description:"当日结束时的本月自然月累计(MB)"`
VendorUsedMB float64 `json:"vendor_used_mb" description:"当天最后一次写入的运营商原始读数(MB)"`
StaleGuarded bool `json:"stale_guarded" description:"当天是否触发重置日防旧值"`
ObsCount int `json:"obs_count" description:"当天写入次数"`
UpdatedAt time.Time `json:"updated_at" description:"更新时间"`
}
// CardDailyUsageListResponse 卡日流量分页结果。
type CardDailyUsageListResponse struct {
Items []CardDailyUsageItem `json:"items" description:"卡日流量"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"页码"`
PageSize int `json:"page_size" description:"每页条数"`
}
// PackageUsageDailyRecordListRequest 套餐日流量详单列表请求。
type PackageUsageDailyRecordListRequest struct {
RecordDateRangeQuery
PackageUsageID *uint `query:"package_usage_id" validate:"omitempty,min=1" description:"套餐使用记录ID"`
PackageID *uint `query:"package_id" validate:"omitempty,min=1" description:"套餐ID"`
CarrierID *uint `query:"carrier_id" validate:"omitempty,min=1" description:"运营商账户ID(按卡所属账户)"`
}
// PackageUsageDailyRecordItem 套餐日流量详单。
type PackageUsageDailyRecordItem struct {
ID uint `json:"id" description:"记录ID"`
PackageUsageID uint `json:"package_usage_id" description:"套餐使用记录ID"`
PackageID uint `json:"package_id" description:"套餐ID"`
PackageName string `json:"package_name" description:"套餐名称(套餐使用记录快照)"`
IotCardID uint `json:"iot_card_id" description:"卡ID,设备套餐为 0"`
ICCID string `json:"iccid" description:"ICCID(卡套餐)"`
DeviceID uint `json:"device_id" description:"设备ID,卡套餐为 0"`
DeviceVirtualNo string `json:"device_virtual_no" description:"设备号(设备套餐)"`
DeviceIMEI string `json:"device_imei" description:"设备 IMEI(设备套餐)"`
Date string `json:"date" description:"日期"`
DailyUsageMB int `json:"daily_usage_mb" description:"当日流量(MB)"`
CumulativeUsageMB int64 `json:"cumulative_usage_mb" description:"截止当日累计(MB)"`
UpdatedAt time.Time `json:"updated_at" description:"更新时间"`
}
// PackageUsageDailyRecordListResponse 套餐日流量详单分页结果。
type PackageUsageDailyRecordListResponse struct {
Items []PackageUsageDailyRecordItem `json:"items" description:"套餐日流量详单"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"页码"`
PageSize int `json:"page_size" description:"每页条数"`
}
// PackageTrafficAdjustmentQueryRequest 套餐流量冲正流水列表请求。
type PackageTrafficAdjustmentQueryRequest struct {
RecordRangeQuery
PackageUsageID *uint `query:"package_usage_id" validate:"omitempty,min=1" description:"套餐使用记录ID"`
OperatorID *uint `query:"operator_id" validate:"omitempty,min=1" description:"操作人账号ID"`
Direction string `query:"direction" validate:"omitempty,oneof=deduct refund" description:"调整方向:deduct 补扣(增量为正),refund 退回(增量为负)"`
}
// PackageTrafficAdjustmentRecordItem 冲正流水(跨卡列表)。
type PackageTrafficAdjustmentRecordItem struct {
PackageTrafficAdjustmentItem
PackageName string `json:"package_name" description:"套餐名称(套餐使用记录快照)"`
IotCardID uint `json:"iot_card_id" description:"卡ID"`
ICCID string `json:"iccid" description:"ICCID(卡套餐)"`
DeviceID uint `json:"device_id" description:"设备ID"`
DeviceVirtualNo string `json:"device_virtual_no" description:"设备号(设备套餐)"`
DeviceIMEI string `json:"device_imei" description:"设备 IMEI(设备套餐)"`
}
// PackageTrafficAdjustmentRecordListResponse 冲正流水分页结果(跨卡列表)。
type PackageTrafficAdjustmentRecordListResponse struct {
Items []PackageTrafficAdjustmentRecordItem `json:"items" description:"冲正流水"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"页码"`
PageSize int `json:"page_size" description:"每页条数"`
}
// RefundPostProcessAttemptListRequest 退款资产后处理尝试记录列表请求。
type RefundPostProcessAttemptListRequest struct {
RecordRangeQuery
RefundID *uint `query:"refund_id" validate:"omitempty,min=1" description:"退款单ID"`
RefundNo string `query:"refund_no" validate:"omitempty,max=64" description:"退款单号"`
Step string `query:"step" validate:"omitempty,oneof=load invalidate activate check_main stop mark done" description:"处理步骤:load/invalidate/activate/check_main/stop/mark/done"`
Result string `query:"result" validate:"omitempty,oneof=success failed" description:"结果:success/failed"`
ErrorCode string `query:"error_code" validate:"omitempty,max=32" description:"错误码"`
Trigger string `query:"trigger" validate:"omitempty,oneof=outbox manual" description:"触发方式:outbox(含补偿扫描)/manual(人工重试)"`
}
// RefundPostProcessAttemptItem 退款资产后处理尝试记录。
type RefundPostProcessAttemptItem struct {
ID uint `json:"id" description:"记录ID"`
RefundID uint `json:"refund_id" description:"退款单ID"`
RefundNo string `json:"refund_no" description:"退款单号"`
Step string `json:"step" description:"处理步骤(失败时为失败步骤,成功为 done)"`
AssetType string `json:"asset_type" description:"资产类型"`
AssetID uint `json:"asset_id" description:"资产ID"`
ICCID string `json:"iccid" description:"ICCID(单卡资产)"`
DeviceVirtualNo string `json:"device_virtual_no" description:"设备号(设备资产)"`
DeviceIMEI string `json:"device_imei" description:"设备 IMEI(设备资产)"`
Attempt int `json:"attempt" description:"尝试序号"`
Trigger string `json:"trigger" description:"触发方式"`
Result string `json:"result" description:"结果"`
ErrorCode string `json:"error_code" description:"错误码"`
ErrorMessage string `json:"error_message" description:"错误信息"`
DurationMS int `json:"duration_ms" description:"耗时(毫秒)"`
CreatedAt time.Time `json:"created_at" description:"记录时间"`
}
// RefundPostProcessAttemptListResponse 退款资产后处理尝试记录分页结果。
type RefundPostProcessAttemptListResponse struct {
Items []RefundPostProcessAttemptItem `json:"items" description:"尝试记录"`
Total int64 `json:"total" description:"总数"`
Page int `json:"page" description:"页码"`
PageSize int `json:"page_size" description:"每页条数"`
}

View File

@@ -1,5 +1,7 @@
package dto
import "time"
// CreateRefundRequest 创建退款申请请求
type CreateRefundRequest struct {
OrderID uint `json:"order_id" validate:"required" required:"true" description:"关联订单ID"`
@@ -60,6 +62,7 @@ type RefundListRequest struct {
OrderID *uint `json:"order_id" query:"order_id" validate:"omitempty" description:"关联订单ID"`
ShopID *uint `json:"shop_id" query:"shop_id" validate:"omitempty" description:"店铺ID"`
AssetIdentifier string `json:"asset_identifier" query:"asset_identifier" validate:"omitempty,max=100" maxLength:"100" description:"资产标识精确检索(ICCID 或 设备虚拟号,非空时精确匹配)"`
AssetPostStatus *int `json:"asset_post_status" query:"asset_post_status" validate:"omitempty,min=0,max=3" minimum:"0" maximum:"3" description:"资产后处理状态 (0:未开始, 1:待重试, 2:已完成, 3:需人工处理)"`
}
// RefundResponse 退款申请详情响应
@@ -116,6 +119,10 @@ type RefundResponse struct {
Remark string `json:"remark,omitempty" description:"审批备注"`
CommissionDeducted bool `json:"commission_deducted" description:"佣金是否已回扣"`
AssetReset bool `json:"asset_reset" description:"退款后资产处理是否完成"`
AssetPostStatus int `json:"asset_post_status" description:"资产后处理状态 (0:未开始, 1:待重试, 2:已完成, 3:需人工处理)"`
AssetPostAttempts int `json:"asset_post_attempts" description:"资产后处理已尝试次数(自动重试上限 10 次)"`
AssetPostLastError string `json:"asset_post_last_error" description:"资产后处理最后一次错误"`
AssetPostNextAt *time.Time `json:"asset_post_next_at,omitempty" description:"资产后处理下次自动重试时间"`
SubmitterID uint `json:"submitter_id" description:"提交人账号ID"`
SubmitterName string `json:"submitter_name" description:"提交人账号名称"`
ApprovalInstanceID *uint `json:"approval_instance_id,omitempty" description:"通用审批实例ID"`

View File

@@ -56,7 +56,7 @@ type ExchangeOrder struct {
CompletedAt *time.Time `gorm:"column:completed_at;comment:换货完成时间,物流换货和直接换货完成后写入" json:"completed_at,omitempty"`
// 业务信息
ExchangeReason string `gorm:"column:exchange_reason;type:varchar(100);not null;comment:换货原因" json:"exchange_reason"`
ExchangeReason string `gorm:"column:exchange_reason;type:varchar(500);not null;comment:换货原因" json:"exchange_reason"`
Remark *string `gorm:"column:remark;type:text;comment:备注" json:"remark,omitempty"`
Status int `gorm:"column:status;type:int;not null;default:1;index:idx_exchange_order_status;comment:换货状态 1-待填写信息 2-待发货 3-已发货待确认 4-已完成 5-已取消" json:"status"`

View File

@@ -0,0 +1,67 @@
package model
import (
"time"
"gorm.io/datatypes"
)
// IotCardRealname 是卡的当前实名记录(每卡一行)。
// 实名状态 real_name_status 仍在 tb_iot_card;这里只记录实名时间及来源、二次实名状态。
type IotCardRealname struct {
ID uint `gorm:"column:id;primaryKey" json:"id"`
CardID uint `gorm:"column:card_id;not null" json:"card_id"`
RealnameAt *time.Time `gorm:"column:realname_at" json:"realname_at,omitempty"`
RealnameAtSource string `gorm:"column:realname_at_source;type:varchar(20);not null;default:''" json:"realname_at_source"`
UpstreamRealnameAt *time.Time `gorm:"column:upstream_realname_at" json:"upstream_realname_at,omitempty"`
FirstObservedAt *time.Time `gorm:"column:first_observed_at" json:"first_observed_at,omitempty"`
ResetStatus string `gorm:"column:reset_status;type:varchar(20);not null;default:'none'" json:"reset_status"`
ResetAt *time.Time `gorm:"column:reset_at" json:"reset_at,omitempty"`
ResetBaselineAt *time.Time `gorm:"column:reset_baseline_at" json:"reset_baseline_at,omitempty"`
ResetBatchID *uint `gorm:"column:reset_batch_id" json:"reset_batch_id,omitempty"`
CreatedAt time.Time `gorm:"column:created_at;not null;default:CURRENT_TIMESTAMP" json:"created_at"`
UpdatedAt time.Time `gorm:"column:updated_at;not null;default:CURRENT_TIMESTAMP" json:"updated_at"`
}
// TableName 指定表名。
func (IotCardRealname) TableName() string { return "tb_iot_card_realname" }
// IotCardRealnameHistory 是卡实名时间变化历史(只追加)。
type IotCardRealnameHistory struct {
ID uint `gorm:"column:id;primaryKey" json:"id"`
CardID uint `gorm:"column:card_id;not null" json:"card_id"`
ICCID string `gorm:"column:iccid;type:varchar(20);not null;default:''" json:"iccid"`
BeforeAt *time.Time `gorm:"column:before_at" json:"before_at,omitempty"`
AfterAt *time.Time `gorm:"column:after_at" json:"after_at,omitempty"`
AfterSource string `gorm:"column:after_source;type:varchar(20);not null;default:''" json:"after_source"`
ChangeType string `gorm:"column:change_type;type:varchar(30);not null" json:"change_type"`
ObservationSource string `gorm:"column:observation_source;type:varchar(30);not null;default:''" json:"observation_source"`
ResetBatchID *uint `gorm:"column:reset_batch_id" json:"reset_batch_id,omitempty"`
OperatorID uint `gorm:"column:operator_id;not null;default:0" json:"operator_id"`
ObservedAt time.Time `gorm:"column:observed_at;not null" json:"observed_at"`
CreatedAt time.Time `gorm:"column:created_at;not null;default:CURRENT_TIMESTAMP" json:"created_at"`
}
// TableName 指定表名。
func (IotCardRealnameHistory) TableName() string { return "tb_iot_card_realname_history" }
// IotCardRealnameResetBatch 是二次实名导入批次。
type IotCardRealnameResetBatch struct {
ID uint `gorm:"column:id;primaryKey" json:"id"`
BatchNo string `gorm:"column:batch_no;type:varchar(40);not null" json:"batch_no"`
ImportFileKey string `gorm:"column:import_file_key;type:varchar(500);not null;default:''" json:"import_file_key"`
Reason string `gorm:"column:reason;type:varchar(500);not null;default:''" json:"reason"`
TotalCount int `gorm:"column:total_count;not null;default:0" json:"total_count"`
SucceededCount int `gorm:"column:succeeded_count;not null;default:0" json:"succeeded_count"`
SkippedCount int `gorm:"column:skipped_count;not null;default:0" json:"skipped_count"`
RevertedCount int `gorm:"column:reverted_count;not null;default:0" json:"reverted_count"`
CompletedCount int `gorm:"column:completed_count;not null;default:0" json:"completed_count"`
Items datatypes.JSON `gorm:"column:items;type:jsonb;not null;default:'[]'" json:"items"`
OperatorID uint `gorm:"column:operator_id;not null;default:0" json:"operator_id"`
OperatorName string `gorm:"column:operator_name;type:varchar(100);not null;default:''" json:"operator_name"`
CreatedAt time.Time `gorm:"column:created_at;not null;default:CURRENT_TIMESTAMP" json:"created_at"`
UpdatedAt time.Time `gorm:"column:updated_at;not null;default:CURRENT_TIMESTAMP" json:"updated_at"`
}
// TableName 指定表名。
func (IotCardRealnameResetBatch) TableName() string { return "tb_iot_card_realname_reset_batch" }

View File

@@ -77,6 +77,12 @@ type RefundRequest struct {
// 后处理标记
CommissionDeducted bool `gorm:"column:commission_deducted;not null;default:false;comment:佣金是否已回扣" json:"commission_deducted"`
AssetReset bool `gorm:"column:asset_reset;not null;default:false;comment:退款后资产处理是否完成" json:"asset_reset"`
// 资产后处理重试状态(refactor-audit-log-persistence)
AssetPostStatus int `gorm:"column:asset_post_status;type:smallint;not null;default:0;comment:资产后处理状态 0-未开始 1-待重试 2-已完成 3-需人工处理" json:"asset_post_status"`
AssetPostAttempts int `gorm:"column:asset_post_attempts;type:int;not null;default:0;comment:资产后处理已尝试次数" json:"asset_post_attempts"`
AssetPostLastError string `gorm:"column:asset_post_last_error;type:varchar(500);not null;default:'';comment:资产后处理最后一次错误摘要" json:"asset_post_last_error"`
AssetPostNextAt *time.Time `gorm:"column:asset_post_next_at;comment:资产后处理下次自动重试时间" json:"asset_post_next_at,omitempty"`
}
// TableName 指定表名
@@ -136,3 +142,34 @@ func RefundActiveStatuses() []int {
func RefundResubmittableStatuses() []int {
return []int{RefundStatusRejected, RefundStatusReturned, RefundStatusChannelFailed, RefundStatusSubmissionFailed}
}
// 退款资产后处理状态。
const (
RefundAssetPostNotStarted = 0 // 未开始
RefundAssetPostRetryPending = 1 // 待重试
RefundAssetPostCompleted = 2 // 已完成
RefundAssetPostManualRequired = 3 // 需人工处理
)
// RefundPostProcessAttempt 退款资产后处理逐次尝试记录,只新增不修改。
type RefundPostProcessAttempt struct {
ID uint `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
RefundID uint `gorm:"column:refund_id;not null" json:"refund_id"`
RefundNo string `gorm:"column:refund_no;type:varchar(64);not null;default:''" json:"refund_no"`
Step string `gorm:"column:step;type:varchar(32);not null" json:"step"`
AssetType string `gorm:"column:asset_type;type:varchar(16);not null;default:''" json:"asset_type"`
AssetID uint `gorm:"column:asset_id;not null;default:0" json:"asset_id"`
ICCID string `gorm:"column:iccid;type:varchar(30);not null;default:''" json:"iccid"`
Attempt int `gorm:"column:attempt;not null" json:"attempt"`
Trigger string `gorm:"column:trigger;type:varchar(16);not null" json:"trigger"`
Result string `gorm:"column:result;type:varchar(16);not null" json:"result"`
ErrorCode string `gorm:"column:error_code;type:varchar(32);not null;default:''" json:"error_code"`
ErrorMessage string `gorm:"column:error_message;type:varchar(500);not null;default:''" json:"error_message"`
DurationMS int `gorm:"column:duration_ms;not null;default:0" json:"duration_ms"`
CreatedAt time.Time `gorm:"column:created_at;type:timestamptz;not null;autoCreateTime" json:"created_at"`
}
// TableName 指定退款资产后处理尝试记录表名。
func (RefundPostProcessAttempt) TableName() string {
return "tb_refund_post_process_attempt"
}

View File

@@ -110,6 +110,12 @@ func (d *Dispatcher) Ready(ctx context.Context) bool {
return err == nil && state == InitStateDone
}
// ingestPaused 判断入库积压是否已触发反压:置位时暂停领取新卡任务(停复机指令照常分发)。
func (d *Dispatcher) ingestPaused(ctx context.Context) bool {
exists, err := d.store.redis.Exists(ctx, constants.RedisPollingIngestPausedKey).Result()
return err == nil && exists > 0
}
func (d *Dispatcher) tick(ctx context.Context, interval time.Duration) {
defer func() {
if r := recover(); r != nil {
@@ -118,7 +124,7 @@ func (d *Dispatcher) tick(ctx context.Context, interval time.Duration) {
}()
// 停复机指令与设备判断的分发只看停复机出口开关,不受 scheduler_mode 限制;卡任务只在新调度就绪时领取。
stopResumeOn := d.settings.Current(ctx).StopResumeQueueEnabled
cardsReady := d.Ready(ctx)
cardsReady := d.Ready(ctx) && !d.ingestPaused(ctx)
if !stopResumeOn && !cardsReady {
return
}

View File

@@ -27,6 +27,7 @@ func RegisterConfigDefinitions(registry *systemconfig.Registry, logger *zap.Logg
return
}
minZero, minOne, maxSeconds, maxCount := int64(0), int64(1), int64(86400*7), int64(100000)
maxDepth := int64(100000000)
definitions := []systemconfig.Definition{
{Key: constants.SystemConfigPollingSchedulerMode, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeString,
DefaultValue: constants.PollingSchedulerModeLegacy, Description: "卡轮询调度模式:legacy 旧分片调度,carrier 按运营商账户调度(整体切换)",
@@ -61,6 +62,13 @@ func RegisterConfigDefinitions(registry *systemconfig.Registry, logger *zap.Logg
DefaultValue: "5", Description: "停复机连续失败告警阈值", Min: &minOne, Max: &maxCount},
{Key: constants.SystemConfigStopResumeStatusGrace, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeInt,
DefaultValue: "300", Description: "停复机成功后的状态保护窗口(秒):窗口内查卡状态返回操作前的状态视为上游滞后,不回写;0 不保护", Min: &minZero, Max: &maxSeconds},
{Key: constants.SystemConfigPollingIngestMode, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeString,
DefaultValue: constants.PollingIngestModeSync, Description: "轮询观测入库模式:sync 卡任务内同步入库,async 只调网关并发布入库消息",
EnumValues: []string{constants.PollingIngestModeSync, constants.PollingIngestModeAsync}},
{Key: constants.SystemConfigPollingIngestAlertDepth, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeInt,
DefaultValue: strconv.Itoa(constants.PollingIngestDefaultAlertDepth), Description: "入库消息积压告警阈值(条)", Min: &minOne, Max: &maxDepth},
{Key: constants.SystemConfigPollingIngestPauseDepth, Module: constants.SystemConfigModulePolling, ValueType: constants.SystemConfigTypeInt,
DefaultValue: strconv.Itoa(constants.PollingIngestDefaultPauseDepth), Description: "入库消息积压反压阈值(条):超过时暂停派发新卡任务,降到一半以下恢复;须大于告警阈值", Min: &minOne, Max: &maxDepth},
}
for _, definition := range definitions {
if _, exists := registry.Get(definition.Key); exists {
@@ -205,6 +213,16 @@ type Settings struct {
SRBackoff []time.Duration
SRAlertFailCount int
SRStatusGrace time.Duration
// 轮询观测入库(add-polling-async-ingest)。
IngestMode string
IngestAlertDepth int
IngestPauseDepth int
}
// IngestAsync 判断轮询观测是否按异步入库执行。
func (s Settings) IngestAsync() bool {
return s.IngestMode == constants.PollingIngestModeAsync
}
// SRBackoffFor 返回停复机第 n 次连续失败(n 从 1 起)的退避间隔;超过序列长度取最后一项。
@@ -297,6 +315,9 @@ func DefaultSettings() Settings {
SRBackoff: []time.Duration{10 * time.Minute, 15 * time.Minute, 30 * time.Minute, time.Hour},
SRAlertFailCount: 5,
SRStatusGrace: 5 * time.Minute,
IngestMode: constants.PollingIngestModeSync,
IngestAlertDepth: constants.PollingIngestDefaultAlertDepth,
IngestPauseDepth: constants.PollingIngestDefaultPauseDepth,
}
}
@@ -421,6 +442,8 @@ func (p *SettingsProvider) load(ctx context.Context) (Settings, error) {
{constants.SystemConfigStopResumeUnknownAlert, func(v int) { s.SRUnknownAlert = v }},
{constants.SystemConfigStopResumeAlertFailCount, func(v int) { s.SRAlertFailCount = v }},
{constants.SystemConfigStopResumeStatusGrace, func(v int) { s.SRStatusGrace = time.Duration(v) * time.Second }},
{constants.SystemConfigPollingIngestAlertDepth, func(v int) { s.IngestAlertDepth = v }},
{constants.SystemConfigPollingIngestPauseDepth, func(v int) { s.IngestPauseDepth = v }},
}
for _, item := range ints {
raw, err := get(item.key)
@@ -448,6 +471,16 @@ func (p *SettingsProvider) load(ctx context.Context) (Settings, error) {
for _, value := range srBackoff {
s.SRBackoff = append(s.SRBackoff, time.Duration(value)*time.Second)
}
if raw, err = get(constants.SystemConfigPollingIngestMode); err != nil {
return s, err
}
s.IngestMode = raw
if s.IngestPauseDepth <= s.IngestAlertDepth {
// 反压阈值须大于告警阈值:配置不满足时按告警阈值的 2 倍执行并告警,避免还没告警就先停派发。
p.logger.Warn("入库反压阈值不大于告警阈值,按告警阈值的 2 倍执行",
zap.Int("alert_depth", s.IngestAlertDepth), zap.Int("pause_depth", s.IngestPauseDepth))
s.IngestPauseDepth = s.IngestAlertDepth * 2
}
return s, nil
}

View File

@@ -188,9 +188,8 @@ func (m *PollingConfigManager) lazyTierFacts(card *model.IotCard) func() TierFac
return func() TierFacts {
once.Do(func() {
if m.tier != nil {
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
facts = m.tier.Resolve(ctx, card)
// 每次查询在解析器内单独计时,避免一张绑定设备的卡连查多次时共用一个超时。
facts = m.tier.Resolve(context.Background(), card)
}
})
return facts

View File

@@ -156,6 +156,16 @@ func (m *PollingQueueManager) EnqueueManual(ctx context.Context, cardID uint, ta
// 使用 RPUSH 与调度器的 LPopCount 组成先进先出;提示通道不是权威,丢失或缓存服务重启时
// 库内活动优先项仍在,后续普通轮询执行按条件认领仍会执行,只退化为延迟一个普通轮询周期。
func (m *PollingQueueManager) EnqueuePriority(ctx context.Context, cardID uint, taskType string) error {
// 同时登记活动优先项索引(轮询步骤据此跳过无优先项卡的查库);recent 集合供索引重建时并入,避免重建期间漏掉新项。
member := constants.PollingPriorityIndexMember(cardID, taskType)
pipe := m.redis.Pipeline()
pipe.SAdd(ctx, constants.RedisPollingPriorityActiveKey, member)
pipe.SAdd(ctx, constants.RedisPollingPriorityRecentKey, member)
pipe.Expire(ctx, constants.RedisPollingPriorityRecentKey, constants.PollingPriorityIndexRecentTTL)
if _, err := pipe.Exec(ctx); err != nil {
m.logger.Warn("登记活动优先项索引失败,轮询步骤将在索引重建后发现该项", zap.Uint("card_id", cardID),
zap.String("task_type", taskType), zap.Error(err))
}
key := constants.RedisPollingPriorityQueueKey(taskType)
return m.redis.RPush(ctx, key, fmt.Sprintf("%d", cardID)).Err()
}

View File

@@ -76,7 +76,7 @@ func (r *TierResolver) Prefill(ctx context.Context, cards []*model.IotCard) {
}
results := make(map[uint]TierFacts, len(cards))
if len(standaloneIDs) > 0 {
states, err := r.usage.PackageStatesByCarriers(ctx, constants.AssetTypeIotCard, standaloneIDs)
states, err := r.packageStates(ctx, constants.AssetTypeIotCard, standaloneIDs)
if err != nil {
r.logger.Warn("批量查询卡套餐状态失败,相关卡本次不按套餐状态匹配", zap.Error(err))
}
@@ -87,7 +87,9 @@ func (r *TierResolver) Prefill(ctx context.Context, cards []*model.IotCard) {
}
}
if len(boundCardIDs) > 0 && r.bindings != nil {
bindings, err := r.bindings.GetActiveBindingsByCardIDs(ctx, boundCardIDs)
bindCtx, cancel := context.WithTimeout(ctx, constants.PollingTierQueryTimeout)
bindings, err := r.bindings.GetActiveBindingsByCardIDs(bindCtx, boundCardIDs)
cancel()
if err != nil {
r.logger.Warn("批量查询卡绑定设备失败,相关卡本次不按套餐状态匹配", zap.Error(err))
} else {
@@ -97,8 +99,8 @@ func (r *TierResolver) Prefill(ctx context.Context, cards []*model.IotCard) {
deviceOf[binding.IotCardID] = binding.DeviceID
deviceIDs = append(deviceIDs, binding.DeviceID)
}
deviceStates, devErr := r.usage.PackageStatesByCarriers(ctx, constants.AssetTypeDevice, deviceIDs)
cardStates, cardErr := r.usage.PackageStatesByCarriers(ctx, constants.AssetTypeIotCard, boundCardIDs)
deviceStates, devErr := r.packageStates(ctx, constants.AssetTypeDevice, deviceIDs)
cardStates, cardErr := r.packageStates(ctx, constants.AssetTypeIotCard, boundCardIDs)
for _, id := range boundCardIDs {
// 有有效设备绑定按设备计算;绑定已失效的卡按卡自身计算(与 resolvePackageCarrier 口径一致)。
if deviceID, bound := deviceOf[id]; bound {
@@ -111,17 +113,22 @@ func (r *TierResolver) Prefill(ctx context.Context, cards []*model.IotCard) {
}
}
}
// 只缓存查询成功的卡:查询失败的卡本次按未知处理,下次重新查询,不把"未知"留在缓存里。
now := time.Now()
r.mu.Lock()
for _, card := range cards {
if card == nil {
continue
}
r.cache[card.ID] = tierCacheEntry{facts: results[card.ID], loadedAt: now}
for id, facts := range results {
r.cache[id] = tierCacheEntry{facts: facts, loadedAt: now}
}
r.mu.Unlock()
}
// packageStates 以单独的超时查询一批载体的套餐状态,避免多次查询共用一个超时。
func (r *TierResolver) packageStates(ctx context.Context, carrierType string, ids []uint) (map[uint]string, error) {
queryCtx, cancel := context.WithTimeout(ctx, constants.PollingTierQueryTimeout)
defer cancel()
return r.usage.PackageStatesByCarriers(queryCtx, carrierType, ids)
}
// Invalidate 清除某卡的分层事实缓存(套餐变化后可调用,未调用时最迟缓存过期后更新)。
func (r *TierResolver) Invalidate(cardID uint) {
if r == nil {

View File

@@ -0,0 +1,42 @@
// Package cardrealname 提供卡当前实名时间与实名时间历史的只读查询。
package cardrealname
import (
"context"
"time"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"gorm.io/gorm"
)
// Current 是卡当前实名时间及来源。
type Current struct {
RealnameAt *time.Time
Source string
}
// LoadCurrent 批量读取卡当前实名记录;没有记录的卡不在返回结果中。
func LoadCurrent(ctx context.Context, db *gorm.DB, cardIDs []uint) (map[uint]Current, error) {
result := make(map[uint]Current, len(cardIDs))
if db == nil || len(cardIDs) == 0 {
return result, nil
}
var rows []model.IotCardRealname
if err := db.WithContext(ctx).Select("card_id", "realname_at", "realname_at_source").
Where("card_id IN ?", cardIDs).Find(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡当前实名时间失败")
}
for _, row := range rows {
result[row.CardID] = Current{RealnameAt: row.RealnameAt, Source: row.RealnameAtSource}
}
return result, nil
}
// ResolveRealnameAt 返回卡的实名时间:有当前实名记录用记录(可能为空,如等待二次实名),没有记录回退 first_realname_at。
func ResolveRealnameAt(current map[uint]Current, cardID uint, fallback *time.Time) (*time.Time, string) {
if value, ok := current[cardID]; ok {
return value.RealnameAt, value.Source
}
return fallback, ""
}

View File

@@ -0,0 +1,269 @@
package cardrealname
import (
"context"
"github.com/bytedance/sonic"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/middleware"
)
// Query 提供单卡实名记录与二次实名批次查询。
type Query struct {
db *gorm.DB
}
// NewQuery 创建实名记录查询。
func NewQuery(db *gorm.DB) *Query {
return &Query{db: db}
}
// CardHistory 返回单卡当前实名时间与实名时间历史(按时间倒序分页);卡按当前账号数据范围可见。
func (q *Query) CardHistory(ctx context.Context, req dto.CardRealnameHistoryListRequest) (*dto.CardRealnameHistoryResponse, error) {
var card model.IotCard
if err := middleware.ApplyShopFilter(ctx, q.db.WithContext(ctx).Select("id", "first_realname_at").Where("id = ?", req.ID)).
First(&card).Error; err != nil {
if err == gorm.ErrRecordNotFound {
return nil, errors.New(errors.CodeNotFound, "IoT 卡不存在")
}
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询 IoT 卡失败")
}
page, size := normalizePage(req.Page, req.PageSize)
resp := &dto.CardRealnameHistoryResponse{Current: dto.CardRealnameCurrentResponse{CardID: card.ID}, Page: page, PageSize: size}
var record model.IotCardRealname
err := q.db.WithContext(ctx).Where("card_id = ?", card.ID).Take(&record).Error
switch {
case err == nil:
resp.Current = dto.CardRealnameCurrentResponse{
CardID: card.ID, RealnameAt: record.RealnameAt, RealnameAtSource: record.RealnameAtSource,
RealnameAtSourceName: constants.RealnameAtSourceName(record.RealnameAtSource),
UpstreamRealnameAt: record.UpstreamRealnameAt, FirstObservedAt: record.FirstObservedAt,
ResetPending: record.ResetStatus == constants.RealnameResetStatusPending, ResetAt: record.ResetAt,
ResetBaselineAt: record.ResetBaselineAt, ResetBatchID: record.ResetBatchID,
}
case err == gorm.ErrRecordNotFound:
resp.Current.RealnameAt = card.FirstRealnameAt
default:
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡当前实名记录失败")
}
base := q.db.WithContext(ctx).Model(&model.IotCardRealnameHistory{}).Where("card_id = ?", card.ID)
if err := base.Count(&resp.Total).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "统计卡实名时间历史失败")
}
var rows []model.IotCardRealnameHistory
if err := base.Order("id DESC").Offset((page - 1) * size).Limit(size).Find(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡实名时间历史失败")
}
operators, err := q.operatorNames(ctx, rows)
if err != nil {
return nil, err
}
resp.Items = make([]dto.CardRealnameHistoryItem, 0, len(rows))
for _, row := range rows {
resp.Items = append(resp.Items, dto.CardRealnameHistoryItem{
ID: row.ID, CardID: row.CardID, ICCID: row.ICCID, BeforeAt: row.BeforeAt, AfterAt: row.AfterAt,
AfterSource: row.AfterSource, AfterSourceName: constants.RealnameAtSourceName(row.AfterSource),
ChangeType: row.ChangeType, ChangeTypeName: constants.RealnameChangeTypeName(row.ChangeType),
ObservationSource: row.ObservationSource, ObservationSourceName: observationSourceName(row.ObservationSource),
ResetBatchID: row.ResetBatchID, OperatorID: row.OperatorID, OperatorName: operators[row.OperatorID],
ObservedAt: row.ObservedAt, CreatedAt: row.CreatedAt,
})
}
return resp, nil
}
// ListResetBatches 分页查询二次实名批次(不含逐行结果)。
func (q *Query) ListResetBatches(ctx context.Context, req dto.RealnameResetBatchListRequest) ([]dto.RealnameResetBatchResponse, int64, int, int, error) {
if err := requirePlatform(ctx); err != nil {
return nil, 0, 0, 0, err
}
page, size := normalizePage(req.Page, req.PageSize)
base := q.db.WithContext(ctx).Model(&model.IotCardRealnameResetBatch{})
if req.BatchNo != "" {
base = base.Where("batch_no = ?", req.BatchNo)
}
var total int64
if err := base.Count(&total).Error; err != nil {
return nil, 0, 0, 0, errors.Wrap(errors.CodeDatabaseError, err, "统计二次实名批次失败")
}
var rows []model.IotCardRealnameResetBatch
if err := base.Omit("items").Order("id DESC").Offset((page - 1) * size).Limit(size).Find(&rows).Error; err != nil {
return nil, 0, 0, 0, errors.Wrap(errors.CodeDatabaseError, err, "查询二次实名批次失败")
}
pending, err := q.pendingCounts(ctx, batchIDs(rows))
if err != nil {
return nil, 0, 0, 0, err
}
list := make([]dto.RealnameResetBatchResponse, 0, len(rows))
for _, row := range rows {
item := batchResponse(row)
item.PendingCount = pending[row.ID]
list = append(list, item)
}
return list, total, page, size, nil
}
// GetResetBatch 查询二次实名批次详情,逐行结果按卡当前状态刷新为等待 / 已完成 / 已撤销。
func (q *Query) GetResetBatch(ctx context.Context, id uint) (*dto.RealnameResetBatchResponse, error) {
if err := requirePlatform(ctx); err != nil {
return nil, err
}
var row model.IotCardRealnameResetBatch
if err := q.db.WithContext(ctx).Where("id = ?", id).Take(&row).Error; err != nil {
if err == gorm.ErrRecordNotFound {
return nil, errors.New(errors.CodeNotFound, "二次实名批次不存在")
}
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询二次实名批次失败")
}
var items []dto.RealnameResetItem
if len(row.Items) > 0 {
if err := sonic.Unmarshal(row.Items, &items); err != nil {
return nil, errors.Wrap(errors.CodeInternalError, err, "解析二次实名批次结果失败")
}
}
finals, err := q.finalResults(ctx, row.ID)
if err != nil {
return nil, err
}
pending := 0
for index := range items {
if items[index].Result == constants.RealnameResetItemPending {
if final, ok := finals[items[index].CardID]; ok {
items[index].Result = final
} else {
pending++
}
}
items[index].ResultName = constants.RealnameResetItemName(items[index].Result)
}
resp := batchResponse(row)
resp.PendingCount = pending
resp.Items = items
return &resp, nil
}
// finalResults 返回批次内已完成或已撤销的卡(以历史为准,同卡取最新一条)。
func (q *Query) finalResults(ctx context.Context, batchID uint) (map[uint]string, error) {
var rows []model.IotCardRealnameHistory
if err := q.db.WithContext(ctx).Select("card_id", "change_type").
Where("reset_batch_id = ? AND change_type IN ?", batchID,
[]string{constants.RealnameChangeResetCompleted, constants.RealnameChangeResetReverted}).
Order("id").Find(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询二次实名结果失败")
}
result := make(map[uint]string, len(rows))
for _, row := range rows {
if row.ChangeType == constants.RealnameChangeResetCompleted {
result[row.CardID] = constants.RealnameResetItemCompleted
} else {
result[row.CardID] = constants.RealnameResetItemReverted
}
}
return result, nil
}
func (q *Query) pendingCounts(ctx context.Context, ids []uint) (map[uint]int, error) {
result := make(map[uint]int, len(ids))
if len(ids) == 0 {
return result, nil
}
var rows []struct {
BatchID uint `gorm:"column:reset_batch_id"`
Count int `gorm:"column:count"`
}
if err := q.db.WithContext(ctx).Model(&model.IotCardRealname{}).Select("reset_batch_id, COUNT(*) AS count").
Where("reset_batch_id IN ? AND reset_status = ?", ids, constants.RealnameResetStatusPending).
Group("reset_batch_id").Scan(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "统计等待二次实名卡数失败")
}
for _, row := range rows {
result[row.BatchID] = row.Count
}
return result, nil
}
func (q *Query) operatorNames(ctx context.Context, rows []model.IotCardRealnameHistory) (map[uint]string, error) {
ids := make([]uint, 0)
for _, row := range rows {
if row.OperatorID > 0 {
ids = append(ids, row.OperatorID)
}
}
result := make(map[uint]string, len(ids))
if len(ids) == 0 {
return result, nil
}
var accounts []model.Account
if err := q.db.WithContext(ctx).Select("id", "username").Where("id IN ?", ids).Find(&accounts).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询操作人失败")
}
for _, account := range accounts {
result[account.ID] = account.Username
}
return result, nil
}
func batchResponse(row model.IotCardRealnameResetBatch) dto.RealnameResetBatchResponse {
return dto.RealnameResetBatchResponse{
ID: row.ID, BatchNo: row.BatchNo, Reason: row.Reason, ImportFileKey: row.ImportFileKey,
TotalCount: row.TotalCount, SucceededCount: row.SucceededCount, SkippedCount: row.SkippedCount,
CompletedCount: row.CompletedCount, RevertedCount: row.RevertedCount,
OperatorID: row.OperatorID, OperatorName: row.OperatorName, CreatedAt: row.CreatedAt,
}
}
func batchIDs(rows []model.IotCardRealnameResetBatch) []uint {
ids := make([]uint, 0, len(rows))
for _, row := range rows {
ids = append(ids, row.ID)
}
return ids
}
func requirePlatform(ctx context.Context) error {
switch middleware.GetUserTypeFromContext(ctx) {
case constants.UserTypeSuperAdmin, constants.UserTypePlatform:
return nil
default:
return errors.New(errors.CodeForbidden, "仅平台账号可查看二次实名批次")
}
}
func normalizePage(page, size int) (int, int) {
if page < 1 {
page = 1
}
if size < 1 {
size = 20
}
if size > 100 {
size = 100
}
return page, size
}
func observationSourceName(source string) string {
switch source {
case constants.CardObservationSourcePolling:
return "轮询"
case constants.CardObservationSourceManualSync:
return "手动刷新"
case constants.CardObservationSourceManualOverride:
return "人工"
case constants.CardObservationSourceCarrierCallback:
return "运营商回调"
case constants.CardObservationSourceBusinessEvent:
return "业务观测"
case "migration":
return "上线迁移"
case "package_silence":
return "沉默期判定"
default:
return source
}
}

View File

@@ -125,7 +125,22 @@ func (q *Query) GetOrder(ctx context.Context, id uint, customerID uint) (*dto.Si
if err != nil {
return nil, err
}
return items[0], nil
item := items[0]
// 待支付且未过支付截止的订单返回支付内容,前端据此展示二维码 / 继续支付;列表不返回。
if order.Status == constants.SilenceOrderStatusPendingPayment && (order.ExpireAt == nil || time.Now().Before(*order.ExpireAt)) {
var payment model.Payment
err := q.db.WithContext(ctx).Select("payment_no", "qr_content").
Where("order_type = ? AND order_id = ? AND status = ?", constants.PaymentOrderTypeSilenceExtension, order.ID, model.PaymentRecordStatusPending).
Order("id DESC").First(&payment).Error
if err != nil && err != gorm.ErrRecordNotFound {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询延期支付单失败")
}
if err == nil {
packagesilenceapp.ApplyPaymentContent(item, payment.QRContent)
item.PaymentNo = payment.PaymentNo
}
}
return item, nil
}
// OrderItems 批量补齐延期订单的支付单快照与批次号(列表、详情与导出共用)。

View File

@@ -24,7 +24,7 @@ type StopRefusedFilter struct {
type StopRefusedRow struct {
ID uint
CardID uint
ICCID string
ICCID string `gorm:"column:iccid"` // 显式列名:GORM 默认映射成 icc_id
CarrierID uint
CarrierName string
DeviceID uint

View File

@@ -0,0 +1,20 @@
package pollingalert
import (
"sync"
"testing"
"gorm.io/gorm/schema"
)
// GORM 默认把字段 ICCID 映射成 icc_id;查询选的是 a.iccid,必须显式指定列名,否则列表 ICCID 一直为空。
func TestStopRefusedRowICCIDColumn(t *testing.T) {
s, err := schema.Parse(&StopRefusedRow{}, &sync.Map{}, schema.NamingStrategy{})
if err != nil {
t.Fatalf("parse StopRefusedRow: %v", err)
}
field := s.LookUpField("ICCID")
if field == nil || field.DBName != "iccid" {
t.Fatalf("StopRefusedRow.ICCID column = %v, want iccid", field)
}
}

View File

@@ -0,0 +1,29 @@
package recorddisplay
import (
"sync"
"testing"
"gorm.io/gorm/schema"
)
// 防回归:不带 column tag 时 GORM 会把 ICCID 读成 icc_id 列。
func TestDefaultNamingSplitsICCID(t *testing.T) {
type untagged struct{ ICCID string }
type tagged struct {
ICCID string `gorm:"column:iccid"`
}
for _, tc := range []struct {
name string
v any
want string
}{{"untagged", &untagged{}, "icc_id"}, {"tagged", &tagged{}, "iccid"}} {
s, err := schema.Parse(tc.v, &sync.Map{}, schema.NamingStrategy{})
if err != nil {
t.Fatal(err)
}
if got := s.LookUpField("ICCID").DBName; got != tc.want {
t.Fatalf("%s: DBName = %q, want %q", tc.name, got, tc.want)
}
}
}

View File

@@ -0,0 +1,143 @@
// Package recorddisplay 为记录查询列表补齐展示字段(ICCID、设备号、运营商名称、操作人)。
//
// 记录表只存内部 ID;列表先分页,再按当前页出现的 ID 批量查主键补齐,
// 不在分页查询里关联,也不在记录表里冗余这些字段。查到的是当前值。
package recorddisplay
import (
"context"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// Device 是设备展示字段。
type Device struct {
VirtualNo string
IMEI string
}
// Lookup 是当前页的展示字段字典;未找到的 ID 返回零值。
type Lookup struct {
iccids map[uint]string
devices map[uint]Device
carriers map[uint]string
operators map[uint]string
packages map[uint]string
}
// Request 是需要补齐的 ID 集合(可重复、可含 0,内部去重并忽略 0)。
type Request struct {
CardIDs []uint
DeviceIDs []uint
CarrierIDs []uint
OperatorIDs []uint
// PackageUsageIDs 用于取套餐使用记录上的套餐名称快照。
PackageUsageIDs []uint
}
// Load 按 ID 批量查询展示字段:每类最多一条主键查询,已删除的资产同样返回(历史记录仍需显示)。
func Load(ctx context.Context, db *gorm.DB, req Request) (*Lookup, error) {
lookup := &Lookup{
iccids: map[uint]string{}, devices: map[uint]Device{}, carriers: map[uint]string{}, operators: map[uint]string{},
packages: map[uint]string{},
}
session := db.WithContext(ctx).Unscoped()
if ids := distinct(req.CardIDs); len(ids) > 0 {
// 显式列名:GORM 默认把字段 ICCID 映射成 icc_id,不写 tag 会读不到值。
var rows []struct {
ID uint `gorm:"column:id"`
ICCID string `gorm:"column:iccid"`
}
if err := session.Model(&model.IotCard{}).Select("id, iccid").Where("id IN ?", ids).Scan(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡展示信息失败")
}
for _, row := range rows {
lookup.iccids[row.ID] = row.ICCID
}
}
if ids := distinct(req.DeviceIDs); len(ids) > 0 {
var rows []struct {
ID uint `gorm:"column:id"`
VirtualNo string `gorm:"column:virtual_no"`
IMEI string `gorm:"column:imei"`
}
if err := session.Model(&model.Device{}).Select("id, virtual_no, imei").Where("id IN ?", ids).Scan(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询设备展示信息失败")
}
for _, row := range rows {
lookup.devices[row.ID] = Device{VirtualNo: row.VirtualNo, IMEI: row.IMEI}
}
}
if ids := distinct(req.CarrierIDs); len(ids) > 0 {
var rows []struct {
ID uint `gorm:"column:id"`
CarrierName string `gorm:"column:carrier_name"`
}
if err := session.Model(&model.Carrier{}).Select("id, carrier_name").Where("id IN ?", ids).Scan(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询运营商账户展示信息失败")
}
for _, row := range rows {
lookup.carriers[row.ID] = row.CarrierName
}
}
if ids := distinct(req.OperatorIDs); len(ids) > 0 {
var rows []struct {
ID uint `gorm:"column:id"`
Username string `gorm:"column:username"`
}
if err := session.Model(&model.Account{}).Select("id, username").Where("id IN ?", ids).Scan(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询操作人展示信息失败")
}
for _, row := range rows {
lookup.operators[row.ID] = row.Username
}
}
if ids := distinct(req.PackageUsageIDs); len(ids) > 0 {
var rows []struct {
ID uint `gorm:"column:id"`
PackageName string `gorm:"column:package_name"`
}
if err := session.Model(&model.PackageUsage{}).Select("id, package_name").Where("id IN ?", ids).Scan(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询套餐名称失败")
}
for _, row := range rows {
lookup.packages[row.ID] = row.PackageName
}
}
return lookup, nil
}
// ICCID 返回卡 ICCID。
func (l *Lookup) ICCID(cardID uint) string { return l.iccids[cardID] }
// Device 返回设备号与 IMEI。
func (l *Lookup) Device(deviceID uint) Device { return l.devices[deviceID] }
// CarrierName 返回运营商账户名称。
func (l *Lookup) CarrierName(carrierID uint) string { return l.carriers[carrierID] }
// PackageName 返回套餐使用记录上的套餐名称快照。
func (l *Lookup) PackageName(packageUsageID uint) string { return l.packages[packageUsageID] }
// OperatorName 返回操作人账号用户名。
func (l *Lookup) OperatorName(accountID uint) string { return l.operators[accountID] }
func distinct(ids []uint) []uint {
seen := make(map[uint]struct{}, len(ids))
result := make([]uint, 0, len(ids))
for _, id := range ids {
if id == 0 {
continue
}
if _, ok := seen[id]; ok {
continue
}
seen[id] = struct{}{}
result = append(result, id)
}
return result
}

View File

@@ -0,0 +1,50 @@
package recorddisplay
import (
"reflect"
"testing"
)
func TestDistinctSkipsZeroAndDuplicates(t *testing.T) {
tests := []struct {
name string
in []uint
want []uint
}{
{name: "空", in: nil, want: []uint{}},
{name: "只有 0", in: []uint{0, 0}, want: []uint{}},
{name: "去重并保持顺序", in: []uint{3, 0, 1, 3, 2, 1}, want: []uint{3, 1, 2}},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if got := distinct(tt.in); !reflect.DeepEqual(got, tt.want) {
t.Fatalf("distinct(%v) = %v, want %v", tt.in, got, tt.want)
}
})
}
}
func TestLookupMissingIDsReturnZeroValues(t *testing.T) {
lookup := &Lookup{
iccids: map[uint]string{1: "8986001"},
devices: map[uint]Device{2: {VirtualNo: "60003081372", IMEI: "869555083099518"}},
carriers: map[uint]string{},
operators: map[uint]string{},
packages: map[uint]string{},
}
if got := lookup.ICCID(1); got != "8986001" {
t.Fatalf("ICCID(1) = %q", got)
}
if got := lookup.ICCID(9); got != "" {
t.Fatalf("ICCID(9) = %q, want empty", got)
}
if got := lookup.Device(2); got.VirtualNo != "60003081372" || got.IMEI != "869555083099518" {
t.Fatalf("Device(2) = %+v", got)
}
if got := lookup.Device(0); got != (Device{}) {
t.Fatalf("Device(0) = %+v, want zero", got)
}
if lookup.CarrierName(5) != "" || lookup.OperatorName(5) != "" || lookup.PackageName(5) != "" {
t.Fatal("missing IDs must return empty strings")
}
}

View File

@@ -154,6 +154,9 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
if handlers.PollingMonitoring != nil {
registerPollingMonitoringRoutes(authGroup, handlers.PollingMonitoring, doc, basePath)
}
if handlers.CardRealname != nil {
registerCardRealnameRoutes(authGroup, handlers.CardRealname, doc, basePath)
}
if handlers.PollingAlert != nil {
registerPollingAlertRoutes(authGroup, handlers.PollingAlert, doc, basePath)
}
@@ -188,6 +191,9 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
if handlers.Refund != nil {
registerRefundRoutes(authGroup, handlers.Refund, doc, basePath)
}
if handlers.Asset != nil && handlers.Refund != nil {
registerRecordQueryRoutes(authGroup, handlers.Asset, handlers.Refund, doc, basePath)
}
if handlers.OrderPackageInvalidate != nil {
registerOrderPackageInvalidateRoutes(authGroup, handlers.OrderPackageInvalidate, doc, basePath)
}

View File

@@ -0,0 +1,38 @@
package routes
import (
"github.com/gofiber/fiber/v2"
"github.com/break/junhong_cmp_fiber/internal/handler/admin"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/pkg/openapi"
)
func registerCardRealnameRoutes(router fiber.Router, handler *admin.CardRealnameHandler, doc *openapi.Generator, basePath string) {
tags := []string{"卡实名记录"}
Register(router, doc, basePath, "GET", "/iot-cards/:id/realname-history", handler.CardHistory, RouteSpec{
Summary: "查询单卡实名时间与历史",
Description: "current 为当前实名时间:上游返回 archiveTime 时以它为准(来源 upstream),否则为首次读到已实名的时间(first_observed)," +
"上线前已实名的卡沿用库里时间(migrated)。历史只在实名时间变化时记录,按时间倒序分页。卡按当前账号数据范围可见。",
Tags: tags, Input: new(dto.CardRealnameHistoryListRequest), Output: new(dto.CardRealnameHistoryResponse), Auth: true,
})
Register(router, doc, basePath, "POST", "/realname-reset/batches", handler.ImportResetBatch, RouteSpec{
Summary: "导入二次实名名单",
Description: "仅平台账号,需 iot_card:realname_reset 权限。资产号为 ICCID / 虚拟号 / IMEI,设备展开为其全部绑定卡,最多 1000 个。" +
"逐卡清除实名状态与实名时间;未实名、上游从未返回 archiveTime、已在等待的卡跳过并写明原因,不影响其他行。" +
"之后上游 archiveTime 晚于清除前时间才算二次实名完成。C 端按普通未实名展示。",
Tags: tags, Input: new(dto.RealnameResetImportRequest), Output: new(dto.RealnameResetBatchResponse), Auth: true,
})
Register(router, doc, basePath, "GET", "/realname-reset/batches", handler.ListResetBatches, RouteSpec{
Summary: "二次实名批次列表", Description: "仅平台账号,按导入时间倒序分页。",
Tags: tags, Input: new(dto.RealnameResetBatchListRequest), Output: new(dto.RealnameResetBatchResponse), Auth: true,
})
Register(router, doc, basePath, "GET", "/realname-reset/batches/:id", handler.GetResetBatch, RouteSpec{
Summary: "二次实名批次详情", Description: "仅平台账号;逐行结果按卡当前状态显示等待二次实名 / 已完成 / 已撤销 / 跳过 / 失败。",
Tags: tags, Input: new(dto.RealnameResetBatchIDRequest), Output: new(dto.RealnameResetBatchResponse), Auth: true,
})
Register(router, doc, basePath, "POST", "/realname-reset/batches/:id/revert", handler.RevertResetBatch, RouteSpec{
Summary: "撤销二次实名", Description: "仅平台账号,需 iot_card:realname_reset 权限。card_ids 为空时撤销整批仍在等待的卡;卡恢复已实名、实名时间恢复为清除前时间。",
Tags: tags, Input: new(dto.RealnameResetRevertRequest), Output: new(dto.RealnameResetRevertResponse), Auth: true,
})
}

View File

@@ -77,7 +77,14 @@ func registerPackageSilenceRoutes(router fiber.Router, handler *admin.PackageSil
Tags: extTags, Input: new(dto.SilenceOrderListRequest), Output: new(dto.SilenceOrderPageResult), Auth: true,
})
Register(group, doc, path, "GET", "/orders/:id", handler.GetOrder, RouteSpec{
Summary: "延期订单详情", Tags: extTags, Input: new(dto.SilenceIDPath), Output: new(dto.SilenceExtensionOrderResponse), Auth: true,
Summary: "延期订单详情", Description: "待支付且未过支付截止的订单返回 qr_content,可继续扫码支付。",
Tags: extTags, Input: new(dto.SilenceIDPath), Output: new(dto.SilenceExtensionOrderResponse), Auth: true,
})
Register(group, doc, path, "POST", "/orders/:id/close", handler.CloseOrder, RouteSpec{
Summary: "作废待支付延期订单",
Description: "需 package_silence:extend 权限,只能作废数据范围内待支付的在线订单。作废前先查单:渠道已支付则按支付成功办理延期并拒绝作废;" +
"作废后同一套餐可重新下单,作废后才到达的支付进入异常并原路退款。",
Tags: extTags, Input: new(dto.SilenceOrderCancelRequest), Output: new(dto.SilenceExtensionOrderResponse), Auth: true,
})
Register(group, doc, path, "POST", "/special", handler.SubmitSpecial, RouteSpec{
Summary: "提交特殊延期(单个 / 批量)",
@@ -130,7 +137,13 @@ func registerPersonalPackageSilenceRoutes(router fiber.Router, handler *apphandl
Summary: "我的延期订单", Tags: tags, Input: new(dto.SilenceOrderListRequest), Output: new(dto.SilenceOrderPageResult), Auth: true,
})
Register(group, doc, path, "GET", "/orders/:id", handler.GetOrder, RouteSpec{
Summary: "我的延期订单详情", Tags: tags, Input: new(dto.SilenceIDPath), Output: new(dto.SilenceExtensionOrderResponse), Auth: true,
Summary: "我的延期订单详情", Description: "待支付且未过支付截止的订单返回 qr_content,可继续支付。",
Tags: tags, Input: new(dto.SilenceIDPath), Output: new(dto.SilenceExtensionOrderResponse), Auth: true,
})
Register(group, doc, path, "POST", "/orders/:id/cancel", handler.CancelOrder, RouteSpec{
Summary: "作废我的待支付延期订单",
Description: "只能作废自己的待支付订单。作废前先查单:已支付则按支付成功办理延期并拒绝作废;作废后可重新下单。",
Tags: tags, Input: new(dto.SilenceOrderCancelRequest), Output: new(dto.SilenceExtensionOrderResponse), Auth: true,
})
Register(group, doc, path, "GET", "/records", handler.ListRecords, RouteSpec{
Summary: "套餐沉默期流水", Tags: tags, Input: new(dto.SilenceRecordListRequest), Output: new([]dto.SilenceRecordResponse), Auth: true,

View File

@@ -14,10 +14,11 @@ func registerPackageUsageRoutes(router fiber.Router, handler *admin.PackageUsage
groupPath := basePath + "/package-usage"
Register(packageUsage, doc, groupPath, "GET", "/:id/daily-records", handler.GetDailyRecords, RouteSpec{
Summary: "获取套餐流量详单",
Tags: []string{"套餐使用记录"},
Input: new(dto.IDReq),
Output: new(dto.PackageUsageDetailResponse),
Auth: true,
Summary: "获取套餐流量详单",
Description: "查询参数:start_date、end_date(2006-01-02,选填);page、page_size(选填,page_size 最大 100)。传 page_size 时按日期倒序分页并返回 total/page/page_size,不传时按日期正序返回全部(兼容旧调用);total_usage_mb 为筛选范围内全部记录之和。",
Tags: []string{"套餐使用记录"},
Input: new(dto.IDReq),
Output: new(dto.PackageUsageDetailResponse),
Auth: true,
})
}

View File

@@ -0,0 +1,46 @@
package routes
import (
"github.com/gofiber/fiber/v2"
"github.com/break/junhong_cmp_fiber/internal/handler/admin"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/pkg/openapi"
)
// recordQueryDescription 是记录查询接口的公共说明。
const recordQueryDescription = "identifier 选填:传入时只查该卡(设备取其绑定卡),解析不到资产返回空页;不传查全部,仅平台账号。" +
"时间范围必填,跨度不超过 31 天;按记录时间倒序分页,每页默认 20、最大 100。"
func registerRecordQueryRoutes(router fiber.Router, asset *admin.AssetHandler, refund *admin.RefundHandler, doc *openapi.Generator, basePath string) {
Register(router, doc, basePath, "GET", "/traffic-collections", asset.ListTrafficCollectionRecords, RouteSpec{
Summary: "运营商流量采集成功记录",
Description: recordQueryDescription + "只含读数有效的采集,带网关原始请求与响应;在线保留当月加最近 2 个整月。",
Tags: []string{"记录查询"}, Input: new(dto.TrafficCollectionListRequest), Output: new(dto.TrafficCollectionRecordListResponse), Auth: true,
})
Register(router, doc, basePath, "GET", "/traffic-collection-failures", asset.ListTrafficCollectionFailures, RouteSpec{
Summary: "运营商流量采集失败记录",
Description: recordQueryDescription + "含失败、限流、响应无效、无读数、读数无效,带错误类别、上游返回与原始数据;observation_id 等于对接日志 integration_id。",
Tags: []string{"记录查询"}, Input: new(dto.TrafficCollectionFailureListRequest), Output: new(dto.TrafficCollectionFailureListResponse), Auth: true,
})
Register(router, doc, basePath, "GET", "/card-daily-usages", asset.ListCardDailyUsages, RouteSpec{
Summary: "卡日流量记录",
Description: recordQueryDescription + "数据来自卡日快照(每卡每天一条);按日期范围(含首尾)查询;min_usage_mb 按当日已结算增量筛异常大流量。",
Tags: []string{"记录查询"}, Input: new(dto.CardDailyUsageListRequest), Output: new(dto.CardDailyUsageListResponse), Auth: true,
})
Register(router, doc, basePath, "GET", "/package-usage-daily-records", asset.ListPackageUsageDailyRecords, RouteSpec{
Summary: "套餐日流量详单记录",
Description: recordQueryDescription + "按日期范围(含首尾)查询;设备标识同时匹配设备套餐与其绑定卡的套餐。",
Tags: []string{"记录查询"}, Input: new(dto.PackageUsageDailyRecordListRequest), Output: new(dto.PackageUsageDailyRecordListResponse), Auth: true,
})
Register(router, doc, basePath, "GET", "/package-traffic-adjustments", asset.ListPackageTrafficAdjustmentRecords, RouteSpec{
Summary: "套餐流量冲正流水记录",
Description: recordQueryDescription + "direction=deduct 为补扣(增量为正),refund 为退回(增量为负)。",
Tags: []string{"记录查询"}, Input: new(dto.PackageTrafficAdjustmentQueryRequest), Output: new(dto.PackageTrafficAdjustmentRecordListResponse), Auth: true,
})
Register(router, doc, basePath, "GET", "/refund-post-process-attempts", refund.ListAssetPostProcessAttempts, RouteSpec{
Summary: "退款资产后处理尝试记录",
Description: "仅平台账号。可按退款单 ID 或单号、资产标识、步骤、结果、错误码、触发方式筛选,不传条件查全部;时间范围必填,跨度不超过 31 天;按时间倒序分页,每页默认 20、最大 100。",
Tags: []string{"记录查询"}, Input: new(dto.RefundPostProcessAttemptListRequest), Output: new(dto.RefundPostProcessAttemptListResponse), Auth: true,
})
}

View File

@@ -74,6 +74,10 @@ func registerRefundRoutes(router fiber.Router, handler *admin.RefundHandler, doc
Summary: "恢复退款原审批提交", Description: "仅恢复最新退款审批实例的原提交事件,不创建新审批实例,不直接调用企业微信接口;审批提交结果未知时必须先由恢复任务确认。", Tags: []string{"退款管理"}, Input: new(dto.RefundIDRequest), Output: new(dto.RefundResponse), Auth: true,
})
Register(refund, doc, groupPath, "POST", "/:id/asset-post-processing/retry", handler.RetryAssetPostProcessing, RouteSpec{
Summary: "人工重试退款资产后处理", Description: "仅平台账号;仅对资产后处理状态为需人工处理(自动重试已达 10 次)的退款单发起,同步执行一次后处理并写尝试记录,返回最新退款详情;仍失败时返回错误并保留需人工处理状态。", Tags: []string{"退款管理"}, Input: new(dto.RefundIDRequest), Output: new(dto.RefundResponse), Auth: true,
})
Register(refund, doc, groupPath, "POST", "/:id/approve", handler.Approve, RouteSpec{
Summary: "审批通过退款申请",
Tags: []string{"退款管理"},

View File

@@ -0,0 +1,436 @@
package asset
import (
"context"
"encoding/json"
stderrors "errors"
"time"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/internal/query/recorddisplay"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/middleware"
)
const (
recordDefaultPageSize = 20
recordMaxPageSize = 100
recordDateLayout = "2006-01-02"
)
// recordScope 是资产标识解析后的查询范围:all 为 true 表示不按资产过滤。
type recordScope struct {
all bool
cardIDs []uint
deviceID uint
}
func (r recordScope) empty() bool { return !r.all && len(r.cardIDs) == 0 && r.deviceID == 0 }
// resolveRecordScope 把选填的资产标识解析为卡 ID(设备取其绑定卡);不传标识查全部时只允许平台账号。
// 标识解析不到资产时返回空范围,调用方直接返回空页。
func (s *Service) resolveRecordScope(ctx context.Context, identifier string) (recordScope, error) {
if identifier == "" {
userType := middleware.GetUserTypeFromContext(ctx)
if userType != constants.UserTypeSuperAdmin && userType != constants.UserTypePlatform {
return recordScope{}, errors.New(errors.CodeForbidden, "只有平台账号可以不带资产标识查询全部记录")
}
return recordScope{all: true}, nil
}
asset, err := s.Resolve(ctx, identifier, false)
if err != nil {
var appErr *errors.AppError
if stderrors.As(err, &appErr) && appErr.Code == errors.CodeNotFound {
return recordScope{}, nil
}
return recordScope{}, err
}
if asset.AssetType == "card" {
return recordScope{cardIDs: []uint{asset.AssetID}}, nil
}
var cardIDs []uint
if err := s.db.WithContext(ctx).Model(&model.DeviceSimBinding{}).
Where("device_id = ? AND bind_status = ?", asset.AssetID, constants.BindStatusBound).
Pluck("iot_card_id", &cardIDs).Error; err != nil {
return recordScope{}, errors.Wrap(errors.CodeDatabaseError, err, "查询设备绑定卡失败")
}
return recordScope{cardIDs: cardIDs, deviceID: asset.AssetID}, nil
}
// parseRecordTimeRange 解析必填时间范围(结束不含,跨度不超过 31 天)。
func parseRecordTimeRange(start, end string) (time.Time, time.Time, error) {
from, err := parseCollectionTime(start)
if err != nil {
return time.Time{}, time.Time{}, err
}
to, err := parseCollectionTime(end)
if err != nil {
return time.Time{}, time.Time{}, err
}
if !to.After(from) || to.Sub(from) > maxCollectionQuerySpan {
return time.Time{}, time.Time{}, errors.New(errors.CodeInvalidParam, "结束时间必须晚于开始时间,且跨度不超过 31 天")
}
return from, to, nil
}
// parseRecordDateRange 解析必填日期范围(含首尾,跨度不超过 31 天)。
func parseRecordDateRange(start, end string) (time.Time, time.Time, error) {
location := cardflow.ShanghaiDate(time.Now()).Location()
from, err := time.ParseInLocation(recordDateLayout, start, location)
if err != nil {
return time.Time{}, time.Time{}, errors.New(errors.CodeInvalidParam, "开始日期格式无效,应为 2006-01-02")
}
to, err := time.ParseInLocation(recordDateLayout, end, location)
if err != nil {
return time.Time{}, time.Time{}, errors.New(errors.CodeInvalidParam, "结束日期格式无效,应为 2006-01-02")
}
if to.Before(from) || to.Sub(from) > maxCollectionQuerySpan {
return time.Time{}, time.Time{}, errors.New(errors.CodeInvalidParam, "结束日期不能早于开始日期,且跨度不超过 31 天")
}
return from, to, nil
}
func recordPage(page, size, maxSize int) (int, int) {
if page <= 0 {
page = 1
}
if size <= 0 {
size = recordDefaultPageSize
}
if size > maxSize {
size = maxSize
}
return page, size
}
// pageQuery 统计总数后按排序取当前页。
func pageQuery[T any](query *gorm.DB, order string, page, size int) ([]T, int64, error) {
var total int64
if err := query.Count(&total).Error; err != nil {
return nil, 0, err
}
rows := make([]T, 0, size)
if total == 0 {
return rows, 0, nil
}
err := query.Order(order).Offset((page - 1) * size).Limit(size).Find(&rows).Error
return rows, total, err
}
func gatewayRawItem(raw model.CollectionRaw) dto.GatewayRawItem {
return dto.GatewayRawItem{
RawRequest: json.RawMessage(raw.RawRequest), HTTPStatus: raw.HTTPStatus, GatewayCode: raw.GatewayCode,
GatewayMsg: raw.GatewayMsg, GatewayTraceID: raw.GatewayTraceID, RawResponse: json.RawMessage(raw.RawResponse),
RawResponseText: raw.RawResponseText, RawTruncated: raw.RawTruncated, GatewayAttempts: raw.GatewayAttempts,
}
}
func collectionSuccessItem(row model.CardTrafficCollection) dto.CardTrafficCollectionItem {
return dto.CardTrafficCollectionItem{
ID: row.ID, ObservedAt: row.ObservedAt, ObservationID: row.ObservationID, Source: row.Source,
Scene: row.Scene, Result: row.Result, VendorUsedMB: row.VendorUsedMB, QueuePoints: json.RawMessage(row.QueuePoints),
Decision: row.Decision, MonthUsedMB: row.MonthUsedMB, StaleGuarded: row.StaleGuarded,
DeltaMB: row.DeltaMB, EventID: row.EventID, RecordKind: "success", GatewayRawItem: gatewayRawItem(row.CollectionRaw),
}
}
func collectionFailureItem(row model.CardTrafficCollectionFailure) dto.TrafficCollectionFailureItem {
return dto.TrafficCollectionFailureItem{
ID: row.ID, IotCardID: row.IotCardID, ICCID: row.ICCID, CarrierID: row.CarrierID, ObservedAt: row.ObservedAt,
ObservationID: row.ObservationID, Source: row.Source, Scene: row.Scene, Result: row.Result,
ErrorCategory: row.ErrorCategory, ProviderCode: row.ProviderCode, ProviderMessage: row.ProviderMessage,
DurationMS: row.DurationMS, GatewayRawItem: gatewayRawItem(row.CollectionRaw),
}
}
// ListTrafficCollectionRecords 查询采集成功记录(可查单个也可查全部)。
func (s *Service) ListTrafficCollectionRecords(ctx context.Context, req *dto.TrafficCollectionListRequest) (*dto.TrafficCollectionRecordListResponse, error) {
from, to, err := parseRecordTimeRange(req.StartTime, req.EndTime)
if err != nil {
return nil, err
}
page, size := recordPage(req.Page, req.PageSize, recordMaxPageSize)
resp := &dto.TrafficCollectionRecordListResponse{Items: []dto.TrafficCollectionRecordItem{}, Page: page, PageSize: size}
scope, err := s.resolveRecordScope(ctx, req.Identifier)
if err != nil || scope.empty() {
return resp, err
}
query := s.db.WithContext(ctx).Model(&model.CardTrafficCollection{}).
Where("observed_at >= ? AND observed_at < ? AND result = ?", from, to, constants.TrafficCollectionResultOK)
if !scope.all {
query = query.Where("iot_card_id IN ?", scope.cardIDs)
}
if req.CarrierID != nil {
query = query.Where("carrier_id = ?", *req.CarrierID)
}
query = applyStringFilters(query, map[string]string{"decision": req.Decision, "source": req.Source, "scene": req.Scene})
if req.HasDelta != nil {
if *req.HasDelta {
query = query.Where("delta_mb > 0")
} else {
query = query.Where("(delta_mb IS NULL OR delta_mb = 0)")
}
}
if req.StaleGuarded != nil {
query = query.Where("stale_guarded = ?", *req.StaleGuarded)
}
rows, total, err := pageQuery[model.CardTrafficCollection](query, "observed_at DESC, id DESC", page, size)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询采集成功记录失败")
}
successReq := recorddisplay.Request{}
for _, row := range rows {
successReq.CardIDs = append(successReq.CardIDs, row.IotCardID)
successReq.CarrierIDs = append(successReq.CarrierIDs, row.CarrierID)
}
display, err := recorddisplay.Load(ctx, s.db, successReq)
if err != nil {
return nil, err
}
for _, row := range rows {
resp.Items = append(resp.Items, dto.TrafficCollectionRecordItem{
CardTrafficCollectionItem: collectionSuccessItem(row), IotCardID: row.IotCardID, ICCID: display.ICCID(row.IotCardID),
CarrierID: row.CarrierID, CarrierName: display.CarrierName(row.CarrierID),
})
}
resp.Total = total
return resp, nil
}
// ListTrafficCollectionFailures 查询采集失败记录(可查单个也可查全部)。
func (s *Service) ListTrafficCollectionFailures(ctx context.Context, req *dto.TrafficCollectionFailureListRequest) (*dto.TrafficCollectionFailureListResponse, error) {
from, to, err := parseRecordTimeRange(req.StartTime, req.EndTime)
if err != nil {
return nil, err
}
page, size := recordPage(req.Page, req.PageSize, recordMaxPageSize)
resp := &dto.TrafficCollectionFailureListResponse{Items: []dto.TrafficCollectionFailureItem{}, Page: page, PageSize: size}
scope, err := s.resolveRecordScope(ctx, req.Identifier)
if err != nil || scope.empty() {
return resp, err
}
query := s.db.WithContext(ctx).Model(&model.CardTrafficCollectionFailure{}).Where("observed_at >= ? AND observed_at < ?", from, to)
if !scope.all {
query = query.Where("iot_card_id IN ?", scope.cardIDs)
}
if req.CarrierID != nil {
query = query.Where("carrier_id = ?", *req.CarrierID)
}
query = applyStringFilters(query, map[string]string{
"result": req.Result, "error_category": req.ErrorCategory, "provider_code": req.ProviderCode, "source": req.Source, "scene": req.Scene,
})
rows, total, err := pageQuery[model.CardTrafficCollectionFailure](query, "observed_at DESC, id DESC", page, size)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询采集失败记录失败")
}
carrierIDs := make([]uint, 0, len(rows))
for _, row := range rows {
carrierIDs = append(carrierIDs, row.CarrierID)
}
display, err := recorddisplay.Load(ctx, s.db, recorddisplay.Request{CarrierIDs: carrierIDs})
if err != nil {
return nil, err
}
for _, row := range rows {
item := collectionFailureItem(row)
item.CarrierName = display.CarrierName(row.CarrierID)
resp.Items = append(resp.Items, item)
}
resp.Total = total
return resp, nil
}
// ListCardDailyUsages 查询卡日流量(可查单个也可查全部)。
func (s *Service) ListCardDailyUsages(ctx context.Context, req *dto.CardDailyUsageListRequest) (*dto.CardDailyUsageListResponse, error) {
from, to, err := parseRecordDateRange(req.StartDate, req.EndDate)
if err != nil {
return nil, err
}
page, size := recordPage(req.Page, req.PageSize, recordMaxPageSize)
resp := &dto.CardDailyUsageListResponse{Items: []dto.CardDailyUsageItem{}, Page: page, PageSize: size}
scope, err := s.resolveRecordScope(ctx, req.Identifier)
if err != nil || scope.empty() {
return resp, err
}
// 显式列名:GORM 默认把字段 ICCID 映射成 icc_id,不写 tag 时 ICCID 一直为空。
type row struct {
model.CardFlowDay
ICCID string `gorm:"column:iccid"`
CarrierID uint `gorm:"column:carrier_id"`
}
query := s.db.WithContext(ctx).Table("tb_card_flow_day AS u").
Select("u.*, c.iccid, c.carrier_id").Joins("LEFT JOIN tb_iot_card c ON c.id = u.iot_card_id").
Where("u.flow_date >= ? AND u.flow_date <= ?", from.Format(recordDateLayout), to.Format(recordDateLayout))
if !scope.all {
query = query.Where("u.iot_card_id IN ?", scope.cardIDs)
}
if req.CarrierID != nil {
query = query.Where("c.carrier_id = ?", *req.CarrierID)
}
if req.MinUsageMB != nil {
query = query.Where("u.settled_mb >= ?", *req.MinUsageMB)
}
rows, total, err := pageQuery[row](query, "u.flow_date DESC, u.id DESC", page, size)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡日流量失败")
}
carrierIDs := make([]uint, 0, len(rows))
for _, item := range rows {
carrierIDs = append(carrierIDs, item.CarrierID)
}
display, err := recorddisplay.Load(ctx, s.db, recorddisplay.Request{CarrierIDs: carrierIDs})
if err != nil {
return nil, err
}
for _, item := range rows {
resp.Items = append(resp.Items, dto.CardDailyUsageItem{
ID: item.ID, IotCardID: item.IotCardID, ICCID: item.ICCID, CarrierID: item.CarrierID,
CarrierName: display.CarrierName(item.CarrierID),
Date: item.FlowDate.Format(recordDateLayout), SettledMB: item.SettledMB, MonthUsedMB: item.MonthUsedMB,
VendorUsedMB: item.VendorUsedMB, StaleGuarded: item.StaleGuarded, ObsCount: item.ObsCount, UpdatedAt: item.UpdatedAt,
})
}
resp.Total = total
return resp, nil
}
// ListPackageUsageDailyRecords 查询套餐日流量详单(可查单个也可查全部)。
func (s *Service) ListPackageUsageDailyRecords(ctx context.Context, req *dto.PackageUsageDailyRecordListRequest) (*dto.PackageUsageDailyRecordListResponse, error) {
from, to, err := parseRecordDateRange(req.StartDate, req.EndDate)
if err != nil {
return nil, err
}
page, size := recordPage(req.Page, req.PageSize, recordMaxPageSize)
resp := &dto.PackageUsageDailyRecordListResponse{Items: []dto.PackageUsageDailyRecordItem{}, Page: page, PageSize: size}
scope, err := s.resolveRecordScope(ctx, req.Identifier)
if err != nil || scope.empty() {
return resp, err
}
type row struct {
model.PackageUsageDailyRecord
PackageID uint `gorm:"column:package_id"`
PackageName string `gorm:"column:package_name"`
IotCardID uint `gorm:"column:iot_card_id"`
DeviceID uint `gorm:"column:device_id"`
}
query := s.db.WithContext(ctx).Table("tb_package_usage_daily_record AS r").
Select("r.*, pu.package_id, pu.package_name, COALESCE(pu.iot_card_id, 0) AS iot_card_id, COALESCE(pu.device_id, 0) AS device_id").
Joins("JOIN tb_package_usage pu ON pu.id = r.package_usage_id").
Where("r.date >= ? AND r.date <= ?", from.Format(recordDateLayout), to.Format(recordDateLayout))
if !scope.all {
if scope.deviceID > 0 {
query = query.Where("(pu.device_id = ? OR pu.iot_card_id IN ?)", scope.deviceID, append([]uint{0}, scope.cardIDs...))
} else {
query = query.Where("pu.iot_card_id IN ?", scope.cardIDs)
}
}
if req.PackageUsageID != nil {
query = query.Where("r.package_usage_id = ?", *req.PackageUsageID)
}
if req.PackageID != nil {
query = query.Where("pu.package_id = ?", *req.PackageID)
}
if req.CarrierID != nil {
query = query.Where("pu.iot_card_id IN (SELECT id FROM tb_iot_card WHERE carrier_id = ?)", *req.CarrierID)
}
rows, total, err := pageQuery[row](query, "r.date DESC, r.id DESC", page, size)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询套餐日流量详单失败")
}
dailyReq := recorddisplay.Request{}
for _, item := range rows {
dailyReq.CardIDs = append(dailyReq.CardIDs, item.IotCardID)
dailyReq.DeviceIDs = append(dailyReq.DeviceIDs, item.DeviceID)
}
display, err := recorddisplay.Load(ctx, s.db, dailyReq)
if err != nil {
return nil, err
}
for _, item := range rows {
device := display.Device(item.DeviceID)
resp.Items = append(resp.Items, dto.PackageUsageDailyRecordItem{
ID: item.ID, PackageUsageID: item.PackageUsageID, PackageID: item.PackageID, PackageName: item.PackageName,
IotCardID: item.IotCardID, ICCID: display.ICCID(item.IotCardID),
DeviceID: item.DeviceID, DeviceVirtualNo: device.VirtualNo, DeviceIMEI: device.IMEI, Date: item.Date.Format(recordDateLayout), DailyUsageMB: item.DailyUsageMB,
CumulativeUsageMB: item.CumulativeUsageMB, UpdatedAt: item.UpdatedAt,
})
}
resp.Total = total
return resp, nil
}
// ListPackageTrafficAdjustmentRecords 查询套餐流量冲正流水(可查单个也可查全部)。
func (s *Service) ListPackageTrafficAdjustmentRecords(ctx context.Context, req *dto.PackageTrafficAdjustmentQueryRequest) (*dto.PackageTrafficAdjustmentRecordListResponse, error) {
from, to, err := parseRecordTimeRange(req.StartTime, req.EndTime)
if err != nil {
return nil, err
}
page, size := recordPage(req.Page, req.PageSize, recordMaxPageSize)
resp := &dto.PackageTrafficAdjustmentRecordListResponse{Items: []dto.PackageTrafficAdjustmentRecordItem{}, Page: page, PageSize: size}
scope, err := s.resolveRecordScope(ctx, req.Identifier)
if err != nil || scope.empty() {
return resp, err
}
query := s.db.WithContext(ctx).Model(&model.PackageUsageAdjustment{}).Where("created_at >= ? AND created_at < ?", from, to)
if !scope.all {
if scope.deviceID > 0 {
query = query.Where("(device_id = ? OR iot_card_id IN ?)", scope.deviceID, append([]uint{0}, scope.cardIDs...))
} else {
query = query.Where("iot_card_id IN ?", scope.cardIDs)
}
}
if req.PackageUsageID != nil {
query = query.Where("package_usage_id = ?", *req.PackageUsageID)
}
if req.OperatorID != nil {
query = query.Where("operator_id = ?", *req.OperatorID)
}
switch req.Direction {
case "deduct":
query = query.Where("delta_mb > 0")
case "refund":
query = query.Where("delta_mb < 0")
}
rows, total, err := pageQuery[model.PackageUsageAdjustment](query, "created_at DESC, id DESC", page, size)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询套餐流量冲正流水失败")
}
adjReq := recorddisplay.Request{}
for _, row := range rows {
adjReq.CardIDs = append(adjReq.CardIDs, row.IotCardID)
adjReq.DeviceIDs = append(adjReq.DeviceIDs, row.DeviceID)
adjReq.OperatorIDs = append(adjReq.OperatorIDs, row.OperatorID)
adjReq.PackageUsageIDs = append(adjReq.PackageUsageIDs, row.PackageUsageID)
}
display, err := recorddisplay.Load(ctx, s.db, adjReq)
if err != nil {
return nil, err
}
for _, row := range rows {
item := toTrafficAdjustmentItem(row)
item.OperatorName = display.OperatorName(row.OperatorID)
device := display.Device(row.DeviceID)
resp.Items = append(resp.Items, dto.PackageTrafficAdjustmentRecordItem{
PackageTrafficAdjustmentItem: item, PackageName: display.PackageName(row.PackageUsageID),
IotCardID: row.IotCardID, ICCID: display.ICCID(row.IotCardID),
DeviceID: row.DeviceID, DeviceVirtualNo: device.VirtualNo, DeviceIMEI: device.IMEI,
})
}
resp.Total = total
return resp, nil
}
// applyStringFilters 对非空字符串条件追加等值过滤(列名为内部常量,不来自请求)。
func applyStringFilters(query *gorm.DB, filters map[string]string) *gorm.DB {
for column, value := range filters {
if value != "" {
query = query.Where(column+" = ?", value)
}
}
return query
}

View File

@@ -16,6 +16,7 @@ import (
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
assetquery "github.com/break/junhong_cmp_fiber/internal/query/asset"
"github.com/break/junhong_cmp_fiber/internal/query/cardrealname"
packageexpiry "github.com/break/junhong_cmp_fiber/internal/query/packageexpiry"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/constants"
@@ -247,14 +248,21 @@ func (s *Service) buildDeviceResolveResponse(ctx context.Context, device *model.
zap.Uints("card_ids", cardIDs),
zap.Error(err))
}
currentRealname, realnameErr := cardrealname.LoadCurrent(ctx, s.db, cardIDs)
if realnameErr != nil {
return nil, realnameErr
}
for _, c := range cards {
realnameAt, realnameSource := cardrealname.ResolveRealnameAt(currentRealname, c.ID, c.FirstRealnameAt)
resp.Cards = append(resp.Cards, dto.BoundCardInfo{
CardID: c.ID,
ICCID: c.ICCID,
MSISDN: c.MSISDN,
NetworkStatus: c.NetworkStatus,
RealNameStatus: c.RealNameStatus,
RealNameAt: c.FirstRealnameAt,
RealNameAt: realnameAt,
RealNameAtSource: realnameSource,
RealNameAtSourceName: constants.RealnameAtSourceName(realnameSource),
SlotPosition: slotMap[c.ID],
IsCurrent: isCurrentMap[c.ID],
CarrierID: c.CarrierID,
@@ -288,11 +296,12 @@ func (s *Service) buildDeviceResolveResponse(ctx context.Context, device *model.
}
// RealNameAt 取所有绑定卡中最早的实名时间
for _, c := range cards {
if c.FirstRealnameAt == nil {
realnameAt, _ := cardrealname.ResolveRealnameAt(currentRealname, c.ID, c.FirstRealnameAt)
if realnameAt == nil {
continue
}
if resp.RealNameAt == nil || c.FirstRealnameAt.Before(*resp.RealNameAt) {
t := *c.FirstRealnameAt
if resp.RealNameAt == nil || realnameAt.Before(*resp.RealNameAt) {
t := *realnameAt
resp.RealNameAt = &t
}
}
@@ -345,6 +354,11 @@ func (s *Service) resolveAssociatedPhones(ctx context.Context, assetType string,
// buildCardResolveResponse 构建卡类型的资产解析响应
func (s *Service) buildCardResolveResponse(ctx context.Context, card *model.IotCard) (*dto.AssetResolveResponse, error) {
currentRealname, err := cardrealname.LoadCurrent(ctx, s.db, []uint{card.ID})
if err != nil {
return nil, err
}
realnameAt, realnameSource := cardrealname.ResolveRealnameAt(currentRealname, card.ID, card.FirstRealnameAt)
resp := &dto.AssetResolveResponse{
AssetType: "card",
AssetID: card.ID,
@@ -359,7 +373,9 @@ func (s *Service) buildCardResolveResponse(ctx context.Context, card *model.IotC
CreatedAt: card.CreatedAt,
UpdatedAt: card.UpdatedAt,
RealNameStatus: card.RealNameStatus,
RealNameAt: card.FirstRealnameAt,
RealNameAt: realnameAt,
RealNameAtSource: realnameSource,
RealNameAtSourceName: constants.RealnameAtSourceName(realnameSource),
RealnamePolicy: card.RealnamePolicy,
NetworkStatus: card.NetworkStatus,
GatewayExtend: card.GatewayExtend,

View File

@@ -10,6 +10,7 @@ import (
stopresumedomain "github.com/break/junhong_cmp_fiber/internal/domain/stopresume"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/internal/query/recorddisplay"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
@@ -175,6 +176,13 @@ func (s *Service) ListPackageTrafficAdjustments(ctx context.Context, assetType s
size = 20
}
query := s.db.WithContext(ctx).Model(&model.PackageUsageAdjustment{}).Where("package_usage_id = ?", req.PackageUsageID)
if req.StartTime != "" || req.EndTime != "" {
from, to, err := parseRecordTimeRange(req.StartTime, req.EndTime)
if err != nil {
return nil, err
}
query = query.Where("created_at >= ? AND created_at < ?", from, to)
}
var total int64
if err := query.Count(&total).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询冲正流水失败")
@@ -183,9 +191,19 @@ func (s *Service) ListPackageTrafficAdjustments(ctx context.Context, assetType s
if err := query.Order("created_at DESC, id DESC").Offset((page - 1) * size).Limit(size).Find(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询冲正流水失败")
}
operatorIDs := make([]uint, 0, len(rows))
for _, row := range rows {
operatorIDs = append(operatorIDs, row.OperatorID)
}
display, err := recorddisplay.Load(ctx, s.db, recorddisplay.Request{OperatorIDs: operatorIDs})
if err != nil {
return nil, err
}
items := make([]dto.PackageTrafficAdjustmentItem, 0, len(rows))
for _, row := range rows {
items = append(items, toTrafficAdjustmentItem(row))
item := toTrafficAdjustmentItem(row)
item.OperatorName = display.OperatorName(row.OperatorID)
items = append(items, item)
}
return &dto.PackageTrafficAdjustmentListResponse{Items: items, Total: total}, nil
}

View File

@@ -2,12 +2,15 @@ package asset
import (
"context"
"encoding/json"
"sort"
"time"
"gorm.io/gorm"
"github.com/break/junhong_cmp_fiber/internal/domain/cardflow"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/internal/model/dto"
"github.com/break/junhong_cmp_fiber/internal/store/postgres"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
@@ -37,22 +40,72 @@ func (s *Service) ListCardTrafficCollections(ctx context.Context, cardID uint, r
if size <= 0 {
size = 50
}
rows, total, err := postgres.NewCardTrafficCollectionStore(s.db).List(ctx, postgres.CardTrafficCollectionQuery{
CardID: cardID, From: from, To: to, Page: page, PageSize: size,
})
if err != nil {
success := s.db.WithContext(ctx).Model(&model.CardTrafficCollection{}).
Where("iot_card_id = ? AND observed_at >= ? AND observed_at < ? AND result = ?", cardID, from, to, constants.TrafficCollectionResultOK)
success = applyStringFilters(success, map[string]string{"decision": req.Decision, "source": req.Source, "scene": req.Scene})
if !req.IncludeFailures {
rows, total, err := pageQuery[model.CardTrafficCollection](success, "observed_at DESC, id DESC", page, size)
if err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡流量采集记录失败")
}
items := make([]dto.CardTrafficCollectionItem, 0, len(rows))
for _, row := range rows {
items = append(items, collectionSuccessItem(row))
}
return &dto.CardTrafficCollectionListResponse{Items: items, Total: total}, nil
}
return s.listCardCollectionsWithFailures(ctx, success, cardID, from, to, req, page, size)
}
// listCardCollectionsWithFailures 合并单卡的成功与失败记录,按采集时间倒序分页(单卡 31 天内数据量有限,取前 page*size 条归并)。
func (s *Service) listCardCollectionsWithFailures(ctx context.Context, success *gorm.DB, cardID uint, from, to time.Time,
req *dto.CardTrafficCollectionListRequest, page, size int) (*dto.CardTrafficCollectionListResponse, error) {
failure := s.db.WithContext(ctx).Model(&model.CardTrafficCollectionFailure{}).
Where("iot_card_id = ? AND observed_at >= ? AND observed_at < ?", cardID, from, to)
failure = applyStringFilters(failure, map[string]string{"source": req.Source, "scene": req.Scene})
var successTotal, failureTotal int64
if err := success.Count(&successTotal).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡流量采集记录失败")
}
items := make([]dto.CardTrafficCollectionItem, 0, len(rows))
for _, row := range rows {
items = append(items, dto.CardTrafficCollectionItem{
ID: row.ID, ObservedAt: row.ObservedAt, ObservationID: row.ObservationID, Source: row.Source,
Scene: row.Scene, Result: row.Result, VendorUsedMB: row.VendorUsedMB, QueuePoints: json.RawMessage(row.QueuePoints),
Decision: row.Decision, MonthUsedMB: row.MonthUsedMB, StaleGuarded: row.StaleGuarded,
DeltaMB: row.DeltaMB, EventID: row.EventID,
if err := failure.Count(&failureTotal).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡流量采集失败记录失败")
}
window := page * size
var successRows []model.CardTrafficCollection
if err := success.Order("observed_at DESC, id DESC").Limit(window).Find(&successRows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡流量采集记录失败")
}
var failureRows []model.CardTrafficCollectionFailure
if err := failure.Order("observed_at DESC, id DESC").Limit(window).Find(&failureRows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询卡流量采集失败记录失败")
}
merged := make([]dto.CardTrafficCollectionItem, 0, len(successRows)+len(failureRows))
for _, row := range successRows {
merged = append(merged, collectionSuccessItem(row))
}
for _, row := range failureRows {
f := collectionFailureItem(row)
merged = append(merged, dto.CardTrafficCollectionItem{
ID: f.ID, ObservedAt: f.ObservedAt, ObservationID: f.ObservationID, Source: f.Source, Scene: f.Scene,
Result: f.Result, RecordKind: "failure", ErrorCategory: f.ErrorCategory, ProviderCode: f.ProviderCode,
ProviderMessage: f.ProviderMessage, DurationMS: f.DurationMS, GatewayRawItem: f.GatewayRawItem,
})
}
return &dto.CardTrafficCollectionListResponse{Items: items, Total: total}, nil
sort.SliceStable(merged, func(i, j int) bool {
if !merged[i].ObservedAt.Equal(merged[j].ObservedAt) {
return merged[i].ObservedAt.After(merged[j].ObservedAt)
}
return merged[i].ID > merged[j].ID
})
start := (page - 1) * size
if start > len(merged) {
start = len(merged)
}
end := start + size
if end > len(merged) {
end = len(merged)
}
return &dto.CardTrafficCollectionListResponse{Items: merged[start:end], Total: successTotal + failureTotal}, nil
}
func parseCollectionTime(value string) (time.Time, error) {

View File

@@ -182,3 +182,29 @@ func payFirstNonEmpty(values ...string) string {
}
return ""
}
// CreateJSAPIPayConfig 为 C 端客户按已选定(已冻结)的商户配置创建微信 JSAPI 预下单,返回前端调起支付的参数。
// 供套餐以外的 C 端在线支付复用(如沉默期延期):openid 取客户在当前应用(公众号 / 小程序)下的授权。
func (s *Service) CreateJSAPIPayConfig(ctx context.Context, customerID uint, appType string, config *model.WechatConfig,
paymentNo, description string, amount int64) (*dto.ClientPayConfig, error) {
if config == nil {
return nil, errors.New(errors.CodeNoPaymentConfig)
}
_, appID, err := s.loadWechatAuthorization(ctx, appType)
if err != nil {
return nil, err
}
openID, err := s.resolveCustomerOpenID(ctx, customerID, appID)
if err != nil {
return nil, err
}
provider, err := s.newPaymentProvider(config, appID, appType)
if err != nil {
return nil, err
}
result, err := provider.CreateJSAPIPayment(ctx, paymentNo, description, openID, int(amount))
if err != nil {
return nil, err
}
return buildClientPayConfigFromResult(result), nil
}

View File

@@ -216,7 +216,7 @@ func (s *Service) buildCardExchangeCompletionResources(
return nil, err
}
resources = append(resources, transactionResources...)
usageResources, err := loadCardExchangePackageUsageResources(ctx, tx, migration.PackageUsageIDs, oldCard.ID, newCard.ID)
usageResources, err := loadCardExchangePackageUsageResources(ctx, tx, migration.PackageUsageIDs, migration.PackageUsageChanges, oldCard.ID, newCard.ID)
if err != nil {
return nil, err
}
@@ -377,24 +377,46 @@ func loadExchangeTransactionResources(ctx context.Context, tx *gorm.DB, exchange
return resources, nil
}
func loadCardExchangePackageUsageResources(ctx context.Context, tx *gorm.DB, ids []uint, oldCardID, newCardID uint) ([]audit.ResourceInput, error) {
return loadExchangePackageUsageResources(ctx, tx, ids, "iot_card_id", oldCardID, newCardID, constants.AuditResourceRoleCardExchangePackageUsage, "卡")
func loadCardExchangePackageUsageResources(ctx context.Context, tx *gorm.DB, ids []uint, changes map[uint]*packageUsageStateChange, oldCardID, newCardID uint) ([]audit.ResourceInput, error) {
return loadExchangePackageUsageResources(ctx, tx, ids, changes, "iot_card_id", oldCardID, newCardID, constants.AuditResourceRoleCardExchangePackageUsage, "卡")
}
func loadExchangePackageUsageResources(ctx context.Context, tx *gorm.DB, ids []uint, assetIDField string, oldAssetID, newAssetID uint, role, assetName string) ([]audit.ResourceInput, error) {
if len(ids) == 0 {
func loadExchangePackageUsageResources(ctx context.Context, tx *gorm.DB, ids []uint, changes map[uint]*packageUsageStateChange, assetIDField string, oldAssetID, newAssetID uint, role, assetName string) ([]audit.ResourceInput, error) {
migrated := make(map[uint]bool, len(ids))
allIDs := make([]uint, 0, len(ids)+len(changes))
for _, id := range ids {
migrated[id] = true
allIDs = append(allIDs, id)
}
for id := range changes {
if !migrated[id] {
allIDs = append(allIDs, id)
}
}
if len(allIDs) == 0 {
return nil, nil
}
var rows []model.PackageUsage
if err := tx.WithContext(ctx).Where("id IN ?", ids).Order("id ASC").Find(&rows).Error; err != nil {
if err := tx.WithContext(ctx).Where("id IN ?", allIDs).Order("id ASC").Find(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询"+assetName+"换货套餐权益失败")
}
orderIDs := make(map[uint]struct{}, len(rows))
packageIDs := make(map[uint]struct{}, len(rows))
resources := make([]audit.ResourceInput, 0, len(rows)*3)
for _, row := range rows {
resource := audit.PackageUsageResource(&row, constants.AuditResourceRelationAffected, role,
map[string]any{assetIDField: oldAssetID}, map[string]any{assetIDField: newAssetID})
beforeData, afterData := map[string]any{}, map[string]any{}
if migrated[row.ID] {
beforeData[assetIDField], afterData[assetIDField] = oldAssetID, newAssetID
}
if change := changes[row.ID]; change != nil {
for key, value := range change.Before {
beforeData[key] = value
}
for key, value := range change.After {
afterData[key] = value
}
}
resource := audit.PackageUsageResource(&row, constants.AuditResourceRelationAffected, role, beforeData, afterData)
resource.SubjectVisibility = constants.AuditSubjectInternalOnly
resources = append(resources, resource)
orderIDs[row.OrderID] = struct{}{}

View File

@@ -229,7 +229,7 @@ func (s *Service) buildDeviceExchangeCompletionResources(
return nil, err
}
resources = append(resources, transactions...)
usages, err := loadDeviceExchangePackageUsageResources(ctx, tx, migration.PackageUsageIDs, oldDevice.ID, newDevice.ID)
usages, err := loadDeviceExchangePackageUsageResources(ctx, tx, migration.PackageUsageIDs, migration.PackageUsageChanges, oldDevice.ID, newDevice.ID)
if err != nil {
return nil, err
}
@@ -337,8 +337,8 @@ func loadDeviceExchangeTransactionResources(ctx context.Context, tx *gorm.DB, ex
return loadExchangeTransactionResources(ctx, tx, exchangeNo, constants.AuditResourceRoleDeviceExchangeWalletTransaction, "设备")
}
func loadDeviceExchangePackageUsageResources(ctx context.Context, tx *gorm.DB, ids []uint, oldDeviceID, newDeviceID uint) ([]audit.ResourceInput, error) {
return loadExchangePackageUsageResources(ctx, tx, ids, "device_id", oldDeviceID, newDeviceID, constants.AuditResourceRoleDeviceExchangePackageUsage, "设备")
func loadDeviceExchangePackageUsageResources(ctx context.Context, tx *gorm.DB, ids []uint, changes map[uint]*packageUsageStateChange, oldDeviceID, newDeviceID uint) ([]audit.ResourceInput, error) {
return loadExchangePackageUsageResources(ctx, tx, ids, changes, "device_id", oldDeviceID, newDeviceID, constants.AuditResourceRoleDeviceExchangePackageUsage, "设备")
}
func (s *Service) recordExchangeOrderFailure(ctx context.Context, cardActionCode, summary string, order *model.ExchangeOrder, businessErr error) {

View File

@@ -15,6 +15,8 @@ import (
type exchangeMigrationResult struct {
Balance int64
PackageUsageIDs []uint
// PackageUsageChanges 记录因迁移规则改变状态、优先级或用量的套餐使用记录(含新资产原有主套餐)
PackageUsageChanges map[uint]*packageUsageStateChange
}
func (s *Service) executeMigrationWithTx(ctx context.Context, tx *gorm.DB, order *model.ExchangeOrder, oldAsset, newAsset *resolvedExchangeAsset) (*exchangeMigrationResult, error) {
@@ -22,7 +24,7 @@ func (s *Service) executeMigrationWithTx(ctx context.Context, tx *gorm.DB, order
if err != nil {
return nil, errors.Wrap(errors.CodeExchangeMigrationFailed, err, "执行钱包迁移失败")
}
usageIDs, err := s.migratePackageUsageWithTx(ctx, tx, oldAsset, newAsset)
usageIDs, usageChanges, err := s.migratePackageUsageWithTx(ctx, tx, oldAsset, newAsset)
if err != nil {
return nil, errors.Wrap(errors.CodeExchangeMigrationFailed, err, "迁移套餐使用记录失败")
}
@@ -35,7 +37,7 @@ func (s *Service) executeMigrationWithTx(ctx context.Context, tx *gorm.DB, order
if err = markTrafficBaselinePendingWithTx(ctx, tx, newAsset); err != nil {
return nil, errors.Wrap(errors.CodeExchangeMigrationFailed, err, "标记新资产流量待建起点失败")
}
return &exchangeMigrationResult{Balance: migrationBalance, PackageUsageIDs: usageIDs}, nil
return &exchangeMigrationResult{Balance: migrationBalance, PackageUsageIDs: usageIDs, PackageUsageChanges: usageChanges}, nil
}
func (s *Service) transferWalletBalanceWithTx(ctx context.Context, tx *gorm.DB, order *model.ExchangeOrder, oldAsset, newAsset *resolvedExchangeAsset) (int64, error) {
@@ -104,39 +106,79 @@ func (s *Service) transferWalletBalanceWithTx(ctx context.Context, tx *gorm.DB,
return migrationBalance, nil
}
func (s *Service) migratePackageUsageWithTx(ctx context.Context, tx *gorm.DB, oldAsset, newAsset *resolvedExchangeAsset) ([]uint, error) {
query := tx.WithContext(ctx).Model(&model.PackageUsage{}).Where("status IN ?", []int{constants.PackageUsageStatusPending, constants.PackageUsageStatusActive, constants.PackageUsageStatusDepleted})
if oldAsset.AssetType == constants.ExchangeAssetTypeIotCard {
query = query.Where("iot_card_id = ?", oldAsset.AssetID)
} else {
query = query.Where("device_id = ?", oldAsset.AssetID)
// migratePackageUsageWithTx 把旧资产待生效、生效中、已用完的套餐使用记录迁到新资产,
// 并按"是否已开始、新资产实名条件、新资产是否已有当前主套餐"决定主套餐迁移后的状态与排队顺序。
func (s *Service) migratePackageUsageWithTx(ctx context.Context, tx *gorm.DB, oldAsset, newAsset *resolvedExchangeAsset) ([]uint, map[uint]*packageUsageStateChange, error) {
column := carrierColumn(oldAsset.AssetType)
oldUsages, err := lockLiveUsagesWithTx(ctx, tx, column, oldAsset.AssetID, false)
if err != nil {
return nil, nil, err
}
if len(oldUsages) == 0 {
return nil, nil, nil
}
newMains, err := lockLiveUsagesWithTx(ctx, tx, carrierColumn(newAsset.AssetType), newAsset.AssetID, true)
if err != nil {
return nil, nil, err
}
var usageIDs []uint
if err := query.Pluck("id", &usageIDs).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询套餐使用记录失败")
usageIDs := make([]uint, 0, len(oldUsages))
oldMains := make([]*model.PackageUsage, 0, len(oldUsages))
for _, usage := range oldUsages {
usageIDs = append(usageIDs, usage.ID)
if usage.MasterUsageID == nil {
oldMains = append(oldMains, usage)
}
}
if len(usageIDs) == 0 {
if err = tx.WithContext(ctx).Model(&model.PackageUsage{}).Where("id IN ?", usageIDs).
Updates(map[string]any{column: newAsset.AssetID, "updated_at": time.Now()}).Error; err != nil {
return nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "迁移套餐使用记录失败")
}
if err = tx.WithContext(ctx).Model(&model.PackageUsageDailyRecord{}).Where("package_usage_id IN ?", usageIDs).Update("updated_at", gorm.Expr("updated_at")).Error; err != nil {
return nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "迁移套餐日记录失败")
}
changes, err := s.arrangeMigratedMainsWithTx(ctx, tx, oldMains, newMains, newAsset)
if err != nil {
return nil, nil, err
}
return usageIDs, changes, nil
}
// arrangeMigratedMainsWithTx 决定迁入主套餐状态并重排新资产主套餐优先级,保证同一载体最多一个当前主套餐。
func (s *Service) arrangeMigratedMainsWithTx(ctx context.Context, tx *gorm.DB, oldMains, newMains []*model.PackageUsage, newAsset *resolvedExchangeAsset) (map[uint]*packageUsageStateChange, error) {
if len(oldMains) == 0 {
return nil, nil
}
updates := map[string]any{"updated_at": time.Now()}
if oldAsset.AssetType == constants.ExchangeAssetTypeIotCard {
updates["iot_card_id"] = newAsset.AssetID
} else {
updates["device_id"] = newAsset.AssetID
now := time.Now()
dailyRecords, err := loadDailyRecordUsageIDsWithTx(ctx, tx, oldMains)
if err != nil {
return nil, err
}
if err := tx.WithContext(ctx).Model(&model.PackageUsage{}).Where("id IN ?", usageIDs).Updates(updates).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "迁移套餐使用记录失败")
newHasCurrent := false
for _, usage := range newMains {
if isCurrentMainUsage(usage, now) {
newHasCurrent = true
break
}
}
if err := tx.WithContext(ctx).Model(&model.PackageUsageDailyRecord{}).Where("package_usage_id IN ?", usageIDs).Update("updated_at", gorm.Expr("updated_at")).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "迁移套餐日记录失败")
var realnameChecked, realnameOK bool
realnameSatisfied := func() (bool, error) {
if !realnameChecked {
ok, checkErr := newAssetRealnameSatisfiedWithTx(ctx, tx, newAsset)
if checkErr != nil {
return false, checkErr
}
realnameChecked, realnameOK = true, ok
}
return realnameOK, nil
}
return usageIDs, nil
plans, promoted, err := planMigratedMains(oldMains, dailyRecords, newHasCurrent, now, realnameSatisfied)
if err != nil {
return nil, err
}
return applyMigratedMainPlansWithTx(ctx, tx, plans, buildMainQueueOrder(newMains, promoted, plans, now))
}
// markTrafficBaselinePendingWithTx 给换货新卡(设备换货时为新设备当前绑定的每张卡)打"待建起点"标记:

View File

@@ -0,0 +1,289 @@
package exchange
import (
"context"
"time"
"gorm.io/gorm"
"gorm.io/gorm/clause"
"github.com/break/junhong_cmp_fiber/internal/model"
"github.com/break/junhong_cmp_fiber/pkg/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
)
// packageUsageStateChange 记录换货迁移中套餐使用记录状态字段的前后值,供换货审计使用。
type packageUsageStateChange struct {
Before map[string]any
After map[string]any
}
// migratedMainPlan 是旧资产主套餐迁移后的目标状态。
type migratedMainPlan struct {
usage *model.PackageUsage
updates map[string]any // 为空表示状态字段原样保留
pending bool // 迁移后为待生效,参与排队
}
func carrierColumn(assetType string) string {
if assetType == constants.ExchangeAssetTypeIotCard {
return "iot_card_id"
}
return "device_id"
}
func liveUsageStatuses() []int {
return []int{constants.PackageUsageStatusPending, constants.PackageUsageStatusActive, constants.PackageUsageStatusDepleted}
}
// lockLiveUsagesWithTx 锁定载体上待生效、生效中、已用完的套餐使用记录,按优先级、创建时间、标识排序。
func lockLiveUsagesWithTx(ctx context.Context, tx *gorm.DB, column string, assetID uint, mainOnly bool) ([]*model.PackageUsage, error) {
query := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).
Where(column+" = ?", assetID).
Where("status IN ?", liveUsageStatuses())
if mainOnly {
query = query.Where("master_usage_id IS NULL")
}
var rows []*model.PackageUsage
if err := query.Order("priority ASC, created_at ASC, id ASC").Find(&rows).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "锁定套餐使用记录失败")
}
return rows, nil
}
// isCurrentMainUsage 与 FindCurrentMainPackageForQueue 口径一致:生效中或已用完且未到期。
func isCurrentMainUsage(usage *model.PackageUsage, now time.Time) bool {
if usage.Status != constants.PackageUsageStatusActive && usage.Status != constants.PackageUsageStatusDepleted {
return false
}
return usage.ExpiresAt == nil || usage.ExpiresAt.After(now)
}
func isExpiredOccupyingUsage(usage *model.PackageUsage, now time.Time) bool {
return (usage.Status == constants.PackageUsageStatusActive || usage.Status == constants.PackageUsageStatusDepleted) &&
!isCurrentMainUsage(usage, now)
}
// isUsageStarted 判断套餐是否已开始:有生效时间、有到期时间、有用量、有日流量记录或已用完。
// 老系统迁移数据可能只有固定到期时间、没有生效时间,按已开始处理以保留原到期日。
func isUsageStarted(usage *model.PackageUsage, hasDailyRecord bool) bool {
return usage.ActivatedAt != nil || usage.ExpiresAt != nil || usage.DataUsageMB > 0 || hasDailyRecord ||
usage.Status == constants.PackageUsageStatusDepleted
}
func loadDailyRecordUsageIDsWithTx(ctx context.Context, tx *gorm.DB, usages []*model.PackageUsage) (map[uint]bool, error) {
result := make(map[uint]bool)
if len(usages) == 0 {
return result, nil
}
ids := make([]uint, 0, len(usages))
for _, usage := range usages {
ids = append(ids, usage.ID)
}
var withRecords []uint
if err := tx.WithContext(ctx).Model(&model.PackageUsageDailyRecord{}).
Where("package_usage_id IN ?", ids).Distinct().Pluck("package_usage_id", &withRecords).Error; err != nil {
return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询套餐日流量记录失败")
}
for _, id := range withRecords {
result[id] = true
}
return result, nil
}
// resetToPendingUpdates 生成"改为待生效并清空生效周期"的字段更新。
func resetToPendingUpdates(pendingRealname, clearUsage bool) map[string]any {
updates := map[string]any{
"status": constants.PackageUsageStatusPending,
"activated_at": nil,
"expires_at": nil,
"last_reset_at": nil,
"next_reset_at": nil,
"pending_realname_activation": pendingRealname,
}
if clearUsage {
updates["data_usage_mb"] = int64(0)
}
return updates
}
// isCleanPendingUsage 判断记录是否已是目标待生效状态,避免无变化的写入与审计。
func isCleanPendingUsage(usage *model.PackageUsage, pendingRealname bool) bool {
return usage.Status == constants.PackageUsageStatusPending && usage.PendingRealnameActivation == pendingRealname &&
usage.ActivatedAt == nil && usage.ExpiresAt == nil && usage.LastResetAt == nil && usage.NextResetAt == nil
}
// planMigratedMains 按"是否已开始、新资产实名条件、新资产是否已有当前主套餐"决定旧资产主套餐的迁移状态。
// realnameSatisfied 仅在存在未开始的主套餐时被调用。
func planMigratedMains(oldMains []*model.PackageUsage, dailyRecords map[uint]bool, newHasCurrent bool, now time.Time,
realnameSatisfied func() (bool, error)) ([]migratedMainPlan, *model.PackageUsage, error) {
plans := make([]migratedMainPlan, 0, len(oldMains))
var promoted *model.PackageUsage
for _, usage := range oldMains {
if isExpiredOccupyingUsage(usage, now) {
plans = append(plans, migratedMainPlan{usage: usage})
continue
}
if !isUsageStarted(usage, dailyRecords[usage.ID]) {
satisfied, err := realnameSatisfied()
if err != nil {
return nil, nil, err
}
var updates map[string]any
if !isCleanPendingUsage(usage, !satisfied) {
updates = resetToPendingUpdates(!satisfied, false)
}
plans = append(plans, migratedMainPlan{usage: usage, updates: updates, pending: true})
continue
}
if !newHasCurrent && promoted == nil && isCurrentMainUsage(usage, now) {
promoted = usage
plans = append(plans, migratedMainPlan{usage: usage})
continue
}
plans = append(plans, migratedMainPlan{usage: usage, updates: resetToPendingUpdates(false, true), pending: true})
}
return plans, promoted, nil
}
// buildMainQueueOrder 迁移后新资产主套餐顺序:当前主套餐 → 新资产原有待生效 → 迁入的待生效。
func buildMainQueueOrder(newMains []*model.PackageUsage, promoted *model.PackageUsage, plans []migratedMainPlan, now time.Time) []*model.PackageUsage {
ordered := make([]*model.PackageUsage, 0, len(newMains)+len(plans))
for _, usage := range newMains {
if isCurrentMainUsage(usage, now) {
ordered = append(ordered, usage)
}
}
if promoted != nil {
ordered = append(ordered, promoted)
}
for _, usage := range newMains {
if usage.Status == constants.PackageUsageStatusPending {
ordered = append(ordered, usage)
}
}
for _, plan := range plans {
if plan.pending {
ordered = append(ordered, plan.usage)
}
}
return ordered
}
func usageStateSnapshot(usage *model.PackageUsage) map[string]any {
return map[string]any{
"status": usage.Status, "priority": usage.Priority, "data_usage_mb": usage.DataUsageMB,
"activated_at": usage.ActivatedAt, "expires_at": usage.ExpiresAt,
"last_reset_at": usage.LastResetAt, "next_reset_at": usage.NextResetAt,
"pending_realname_activation": usage.PendingRealnameActivation,
}
}
func recordStateChange(changes map[uint]*packageUsageStateChange, usage *model.PackageUsage, updates map[string]any) {
change, ok := changes[usage.ID]
if !ok {
change = &packageUsageStateChange{Before: usageStateSnapshot(usage), After: usageStateSnapshot(usage)}
changes[usage.ID] = change
}
for key, value := range updates {
change.After[key] = value
}
}
func applyUsageUpdatesWithTx(ctx context.Context, tx *gorm.DB, id uint, updates map[string]any) error {
values := make(map[string]any, len(updates)+1)
for key, value := range updates {
values[key] = value
}
values["updated_at"] = time.Now()
if err := tx.WithContext(ctx).Model(&model.PackageUsage{}).Where("id = ?", id).Updates(values).Error; err != nil {
return errors.Wrap(errors.CodeDatabaseError, err, "更新迁移套餐状态失败")
}
return nil
}
// applyMigratedMainPlansWithTx 写入迁移主套餐的目标状态并重排新资产主套餐优先级。
func applyMigratedMainPlansWithTx(ctx context.Context, tx *gorm.DB, plans []migratedMainPlan, ordered []*model.PackageUsage) (map[uint]*packageUsageStateChange, error) {
changes := make(map[uint]*packageUsageStateChange)
pendingUpdates := make(map[uint]map[string]any)
for _, plan := range plans {
if len(plan.updates) > 0 {
pendingUpdates[plan.usage.ID] = plan.updates
recordStateChange(changes, plan.usage, plan.updates)
}
}
for index, usage := range ordered {
priority := index + 1
if usage.Priority == priority {
continue
}
updates := pendingUpdates[usage.ID]
if updates == nil {
updates = make(map[string]any)
pendingUpdates[usage.ID] = updates
}
updates["priority"] = priority
recordStateChange(changes, usage, map[string]any{"priority": priority})
}
for id, updates := range pendingUpdates {
if err := applyUsageUpdatesWithTx(ctx, tx, id, updates); err != nil {
return nil, err
}
}
return changes, nil
}
// newAssetRealnameSatisfiedWithTx 判断新资产是否满足实名条件。
// 口径同 StopResumeService.isRealnameOK:行业卡、已实名、或适用实名策略为无需实名;设备看自身策略与已绑定卡。
func newAssetRealnameSatisfiedWithTx(ctx context.Context, tx *gorm.DB, asset *resolvedExchangeAsset) (bool, error) {
if asset.AssetType == constants.ExchangeAssetTypeIotCard {
return cardRealnameSatisfiedWithTx(ctx, tx, asset.AssetID)
}
return deviceRealnameSatisfiedWithTx(ctx, tx, asset.AssetID)
}
func cardRealnameSatisfiedWithTx(ctx context.Context, tx *gorm.DB, cardID uint) (bool, error) {
var card model.IotCard
if err := tx.WithContext(ctx).Select("id", "card_category", "real_name_status", "realname_policy", "is_standalone").
First(&card, cardID).Error; err != nil {
return false, errors.Wrap(errors.CodeDatabaseError, err, "查询新卡实名条件失败")
}
if card.CardCategory == constants.CardCategoryIndustry || card.RealNameStatus == constants.RealNameStatusVerified {
return true, nil
}
if card.IsStandalone {
return card.RealnamePolicy == constants.RealnamePolicyNone, nil
}
var device model.Device
err := tx.WithContext(ctx).Select("devices.realname_policy").Table("tb_device AS devices").
Joins("JOIN tb_device_sim_binding AS bindings ON bindings.device_id = devices.id").
Where("bindings.iot_card_id = ? AND bindings.bind_status = ? AND bindings.deleted_at IS NULL", cardID, constants.BindStatusBound).
Where("devices.deleted_at IS NULL").
Take(&device).Error
if err == gorm.ErrRecordNotFound {
return card.RealnamePolicy == constants.RealnamePolicyNone, nil
}
if err != nil {
return false, errors.Wrap(errors.CodeDatabaseError, err, "查询新卡绑定设备实名策略失败")
}
return device.RealnamePolicy == constants.RealnamePolicyNone, nil
}
func deviceRealnameSatisfiedWithTx(ctx context.Context, tx *gorm.DB, deviceID uint) (bool, error) {
var device model.Device
if err := tx.WithContext(ctx).Select("id", "realname_policy").First(&device, deviceID).Error; err != nil {
return false, errors.Wrap(errors.CodeDatabaseError, err, "查询新设备实名条件失败")
}
if device.RealnamePolicy == constants.RealnamePolicyNone {
return true, nil
}
var count int64
if err := tx.WithContext(ctx).Model(&model.IotCard{}).
Joins("JOIN tb_device_sim_binding AS bindings ON bindings.iot_card_id = tb_iot_card.id").
Where("bindings.device_id = ? AND bindings.bind_status = ? AND bindings.deleted_at IS NULL", deviceID, constants.BindStatusBound).
Where("tb_iot_card.card_category = ? OR tb_iot_card.real_name_status = ?", constants.CardCategoryIndustry, constants.RealNameStatusVerified).
Count(&count).Error; err != nil {
return false, errors.Wrap(errors.CodeDatabaseError, err, "查询新设备绑定卡实名条件失败")
}
return count > 0, nil
}

View File

@@ -1590,7 +1590,7 @@ func (s *Service) refreshCardDataFromGateway(ctx context.Context, iccid string,
requestID := requestIDFromContext(ctx)
decision, applyErr := s.cardObservation.ApplyCardObservation(ctx, carddomain.RealnameObservation{
CardID: card.ID,
Verified: realnameResp.RealStatus,
Verified: realnameResp.RealStatus, UpstreamRealnameAt: realnameResp.UpstreamRealnameAt(),
Metadata: carddomain.ObservationMetadata{
ObservationID: uuid.NewString(), Source: constants.CardObservationSourceManualSync,
Scene: constants.CardObservationSceneManualRefresh, ObservedAt: syncTime,

Some files were not shown because too many files have changed in this diff Show More