Files
junhong_cmp_fiber/internal/routes/asset.go
邹进 9c3c258f16
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m27s
feat: 卡流量读数先过采集队列再入账,扣减按采集时刻确定套餐
- 每卡 Redis 采集队列(默认 N=3、跨天清空、回退容差 1 MB),攒满且不下降才写最后一个点
- 测试环境全量切换日快照计量,下线灰度名单、切换水位与卡表基线扣费;全部卡置待建起点
- 读数区分没给值与 0;有套餐的卡读数 0 也写快照与日用量 0 行;重置日比较基准为 0 照常防旧值
- 新增采集记录(按月分区保留 90 天)、人工冲正流水与后台接口、采集告警
- 扣减按采集时刻有效套餐查找,只对生效中套餐做状态迁移,查不到套餐按成功跳过
- 换货新卡(新设备下的卡)打待建起点;采集间隔上限只校验启用中的轮询配置

Change: add-card-traffic-queue-and-observed-deduction

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

194 lines
10 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package 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 registerAssetRoutes(router fiber.Router, handler *admin.AssetHandler, walletHandler *admin.AssetWalletHandler, doc *openapi.Generator, basePath string) {
assets := router.Group("/assets")
groupPath := basePath + "/assets"
Register(assets, doc, groupPath, "GET", "/resolve/:identifier", handler.Resolve, RouteSpec{
Summary: "解析资产",
Description: "通过虚拟号/ICCID/IMEI/SN/MSISDN 解析设备或卡的完整详情。exchange_trace 始终存在,previous_asset/next_asset 无关系时为 null;关联项仅在 can_view=true 且 asset_id 非空时允许跳转。企业账号禁止调用。企业账号只能解析当前授权给本企业的卡或设备,未授权与不存在同样返回未找到;/assets/:identifier/* 下其余接口同此范围。",
Tags: []string{"资产管理"},
Input: new(dto.AssetResolveRequest),
Output: new(dto.AssetResolveResponse),
Auth: true,
})
Register(assets, doc, groupPath, "GET", "/:identifier/realtime-status", handler.RealtimeStatus, RouteSpec{
Summary: "资产实时状态",
Description: "查询资产实时状态。卡类型:读取 DB/Redis 持久化状态;设备类型:实时调用 Gateway sync-info 接口获取最新数据,Gateway 失败不阻断主流程(DeviceRealtime.gateway_msg 返回失败原因)。",
Tags: []string{"资产管理"},
Input: new(dto.AssetIdentifierRequest),
Output: new(dto.AssetRealtimeStatusResponse),
Auth: true,
})
Register(assets, doc, groupPath, "POST", "/:identifier/refresh", handler.Refresh, RouteSpec{
Summary: "刷新资产状态",
Description: "主动调网关同步最新状态。设备有30秒冷却期。",
Tags: []string{"资产管理"},
Input: new(dto.AssetIdentifierRequest),
Output: new(dto.AssetRealtimeStatusResponse),
Auth: true,
})
Register(assets, doc, groupPath, "GET", "/:identifier/packages", handler.Packages, RouteSpec{
Summary: "资产套餐历史",
Description: "查询该资产全部世代的套餐历史层级。每个主套餐及其关联加油包占一个分页名额,total 为筛选后的顶层项数量;支持 status 按同一使用记录筛选。关联主套餐物理缺失返回异常独立项,存在但不可展示的关联主套餐返回统一读取错误。",
Tags: []string{"资产管理"},
Input: new(dto.AssetPackagesRequest),
Output: new(dto.AssetPackagesResult),
Auth: true,
})
Register(assets, doc, groupPath, "GET", "/:identifier/current-package", handler.CurrentPackage, RouteSpec{
Summary: "当前生效套餐",
Tags: []string{"资产管理"},
Input: new(dto.AssetIdentifierRequest),
Output: new(dto.AssetPackageResponse),
Auth: true,
})
Register(assets, doc, groupPath, "PATCH", "/:identifier/packages/:package_usage_id/expires-at", handler.UpdatePackageExpiresAt, RouteSpec{
Summary: "修改资产套餐过期时间",
Description: "修改指定资产下某条套餐使用记录的过期时间。仅允许已认证账号调用,并保留资产与套餐记录归属校验。企业账号无权调用。",
Tags: []string{"资产管理"},
Input: new(dto.UpdateAssetPackageExpiresAtRequest),
Output: new(dto.AssetPackageResponse),
Auth: true,
})
Register(assets, doc, groupPath, "PATCH", "/:identifier/packages/:package_usage_id/used-data", handler.UpdatePackageUsage, RouteSpec{
Summary: "修改资产套餐已用量",
Description: "修改指定资产下某条套餐使用记录的真实已用量(MB):按与当前已用量的差额写一条人工冲正流水(原因记为后台修改资产套餐已用量),提交后走停复机判断。仅允许已认证账号调用,并保留资产与套餐记录归属校验。企业账号无权调用。",
Tags: []string{"资产管理"},
Input: new(dto.UpdateAssetPackageUsageRequest),
Output: new(dto.AssetPackageResponse),
Auth: true,
})
Register(assets, doc, groupPath, "POST", "/:identifier/packages/:package_usage_id/traffic-adjustments", handler.AdjustPackageTraffic, RouteSpec{
Summary: "人工冲正套餐流量",
Description: "按调整量冲正套餐已用量(正数补扣、负数退回),原因必填;锁套餐行按当前值加减,退回后不得小于 0,同事务写冲正流水与审计,提交后走停复机判断,不直接复机。不修改卡日快照。企业账号无权调用。",
Tags: []string{"资产管理"},
Input: new(dto.AdjustAssetPackageTrafficRequest),
Output: new(dto.PackageTrafficAdjustmentItem),
Auth: true,
})
Register(assets, doc, groupPath, "GET", "/:identifier/packages/:package_usage_id/traffic-adjustments", handler.ListPackageTrafficAdjustments, RouteSpec{
Summary: "查询套餐冲正流水",
Description: "分页查询指定套餐使用记录的人工冲正流水,按时间倒序。企业账号无权调用。",
Tags: []string{"资产管理"},
Input: new(dto.PackageTrafficAdjustmentListRequest),
Output: new(dto.PackageTrafficAdjustmentListResponse),
Auth: true,
})
Register(assets, doc, groupPath, "GET", "/:identifier/traffic-collections", handler.ListTrafficCollections, RouteSpec{
Summary: "查询卡流量采集记录",
Description: "按卡与采集时间范围分页查询流量采集记录(仅采集时刻有套餐的卡有记录,保留 90 天),含原始读数、队列与写入判断,按采集时间倒序;单次跨度不超过 31 天。企业账号无权调用。",
Tags: []string{"资产管理"},
Input: new(dto.CardTrafficCollectionListRequest),
Output: new(dto.CardTrafficCollectionListResponse),
Auth: true,
})
Register(assets, doc, groupPath, "POST", "/:identifier/stop", handler.Stop, RouteSpec{
Summary: "停机",
Description: "设备批量停机设备下所有已实名卡;单卡手动停机。",
Tags: []string{"资产管理"},
Input: new(dto.AssetIdentifierRequest),
Output: nil,
Auth: true,
})
Register(assets, doc, groupPath, "POST", "/:identifier/start", handler.Start, RouteSpec{
Summary: "复机",
Description: "设备批量复机;单卡手动复机。",
Tags: []string{"资产管理"},
Input: new(dto.AssetIdentifierRequest),
Output: nil,
Auth: true,
})
Register(assets, doc, groupPath, "PATCH", "/:identifier/deactivate", handler.Deactivate, RouteSpec{
Summary: "停用资产",
Description: "将资产状态设置为停用(不可逆)。仅支持库存中或已售出的资产。企业账号无权调用。",
Tags: []string{"资产管理"},
Input: new(dto.AssetIdentifierRequest),
Output: nil,
Auth: true,
})
Register(assets, doc, groupPath, "GET", "/:identifier/wallet", walletHandler.GetWallet, RouteSpec{
Summary: "资产钱包概况",
Description: "查询指定卡或设备的钱包余额概况。企业账号禁止调用。",
Tags: []string{"资产管理"},
Input: new(dto.AssetIdentifierRequest),
Output: new(dto.AssetWalletResponse),
Auth: true,
})
Register(assets, doc, groupPath, "GET", "/:identifier/wallet/transactions", walletHandler.ListTransactions, RouteSpec{
Summary: "资产钱包流水列表",
Description: "分页查询指定资产的钱包收支流水,含充值/扣款来源编号。企业账号禁止调用。",
Tags: []string{"资产管理"},
Input: new(dto.AssetWalletTransactionListRequest),
Output: new(dto.AssetWalletTransactionListResponse),
Auth: true,
})
Register(assets, doc, groupPath, "GET", "/:identifier/orders", handler.Orders, RouteSpec{
Summary: "资产历史订单",
Description: "查询资产本代历史订单,支持 include_previous=true 参数通过换货链追溯前代订单(最多10代)。",
Tags: []string{"资产管理"},
Input: new(dto.AssetOrdersRequest),
Output: new(dto.AssetOrdersResponse),
Auth: true,
})
Register(assets, doc, groupPath, "GET", "/:identifier/operation-logs", handler.OperationLogs, RouteSpec{
Summary: "查询平台旧资产操作日志",
Description: "仅超级管理员和平台账号可查询切换前旧资产日志;代理和企业必须使用独立资源活动接口。旧记录不接入统一审计时间线。",
Tags: []string{"资产管理"},
Input: new(dto.AssetOperationLogListRequest),
Output: new(dto.AssetOperationLogListResponse),
Auth: true,
})
Register(assets, doc, groupPath, "PATCH", "/:identifier/polling-status", handler.UpdatePollingStatus, RouteSpec{
Summary: "更新资产轮询状态",
Description: "启用或禁用指定资产(IoT卡或设备)的定期状态轮询;同事务写不轮询清单(来源单资产接口)与审计。网关扩展状态为风险停机或已销户的卡不能开启轮询,返回 403。设备开关级联到设备下各卡(开启时跳过风险停机、已销户的卡)。影响说明见 GET /polling-status/impact。企业账号无权调用。",
Tags: []string{"资产管理"},
Input: new(dto.UpdateAssetPollingStatusRequest),
Output: new(dto.UpdateAssetPollingStatusResponse),
Auth: true,
})
Register(assets, doc, groupPath, "PATCH", "/:identifier/realname-mode", handler.UpdateRealnamePolicy, RouteSpec{
Summary: "更新资产实名认证策略",
Description: "更新指定资产(IoT卡或设备)的实名认证策略,支持 none/before_order/after_order 三种模式。",
Tags: []string{"资产管理"},
Input: new(dto.UpdateAssetRealnamePolicyRequest),
Output: new(dto.UpdateAssetRealnamePolicyResponse),
Auth: true,
})
Register(assets, doc, groupPath, "PATCH", "/:identifier/realname-status", handler.UpdateRealnameStatus, RouteSpec{
Summary: "手动更新卡实名状态",
Description: "手动将指定卡资产标记为已实名或未实名。状态更新后会触发停复机评估,并在标记为已实名时触发待实名套餐激活。企业账号无权调用。",
Tags: []string{"资产管理"},
Input: new(dto.UpdateAssetRealnameStatusRequest),
Output: new(dto.UpdateAssetRealnameStatusResponse),
Auth: true,
})
}