feat(套餐真流量预警): AUG26-004 真流量预警规则、达量扫描通知与导出

新增 000228 迁移:规则表 tb_package_traffic_alert_rule(每套餐商品至多一条,无软删除,package_id
非部分唯一约束)、达量预警快照表 tb_package_traffic_alert(以主套餐使用记录 + 阈值快照为唯一键,
触发时冻结用量、额度、比例、阈值、到期时间、归属与资产快照),并为 tb_package_usage 新增扫描
范围部分索引 idx_package_usage_alert_scope;down 在预警表存在数据时阻断回滚。

新增规则维护接口 GET/POST/PUT /api/admin/package-traffic-alert-rules(仅超级管理员与平台账号):
创建校验套餐存在且真流量额度大于零,阈值为 1%~100% 的两位小数;修改只影响后续扫描,不回填也
不改写既有预警快照;全部写操作记录操作者、前后值与时间。

新增每日 06:00(Asia/Shanghai)扫描任务 package:traffic:alert:scan,与套餐临期扫描共用 data_cleanup
队列:按资产汇总当前有效套餐的真流量,分子取使用记录真已用量、分母取使用记录真总量快照,命中
主套餐规则阈值时在同一事务创建预警与可靠通知事件;重复执行以唯一冲突视为已处理,不重复投递,
不建停机锁、不调用运营商。

新增预警列表、详情与异步导出 GET /api/admin/package-traffic-alerts、GET /api/admin/package-traffic-alerts/:id、
POST /api/admin/package-traffic-alerts/export,列表与详情一律读冻结快照;新增通知类型
package.traffic.alert 与受控目标 package_traffic_alert_detail,目标解析仅对超级管理员与平台账号
返回可跳转,越权与不存在统一按资源不可见处理。

同步 OpenAPI(cmd/gendocs、cmd/api/docs.go、pkg/openapi/handlers.go)、审计动作与资源注册、上下文
健康检查证据;归档变更并同步 package-traffic-alert 主 Spec。
This commit is contained in:
2026-09-16 17:05:55 +08:00
parent ef4d3696d4
commit d5bcda94fe
46 changed files with 3679 additions and 100 deletions

View File

@@ -103,6 +103,9 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
if handlers.PackageUsage != nil {
registerPackageUsageRoutes(authGroup, handlers.PackageUsage, doc, basePath)
}
if handlers.PackageTrafficAlert != nil {
registerPackageTrafficAlertRoutes(authGroup, handlers.PackageTrafficAlert, doc, basePath)
}
if handlers.ShopPackageBatchAllocation != nil {
registerShopPackageBatchAllocationRoutes(authGroup, handlers.ShopPackageBatchAllocation, doc, basePath)
}

View File

@@ -0,0 +1,84 @@
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/constants"
"github.com/break/junhong_cmp_fiber/pkg/errors"
"github.com/break/junhong_cmp_fiber/pkg/middleware"
"github.com/break/junhong_cmp_fiber/pkg/openapi"
)
// registerPackageTrafficAlertRoutes 注册套餐真流量预警规则与达量预警路由。
// 沿用超管/平台路由组级 gate 先例:代理、企业与个人客户账号一律 403。
func registerPackageTrafficAlertRoutes(router fiber.Router, handler *admin.PackageTrafficAlertHandler, doc *openapi.Generator, basePath string) {
group := router.Group("", func(c *fiber.Ctx) error {
userType := middleware.GetUserTypeFromContext(c.UserContext())
if userType != constants.UserTypeSuperAdmin && userType != constants.UserTypePlatform {
return errors.New(errors.CodeForbidden, constants.PlatformManagementForbiddenMessage)
}
return c.Next()
})
ruleGroup := group.Group("/package-traffic-alert-rules")
rulePath := basePath + "/package-traffic-alert-rules"
Register(ruleGroup, doc, rulePath, "GET", "", handler.ListRules, RouteSpec{
Summary: "查询套餐真流量预警规则列表",
Description: "返回套餐、商品当前真流量额度、阈值、启用状态、备注与更新时间;仅超级管理员与平台账号可访问",
Tags: []string{"套餐管理"},
Input: new(dto.ListPackageTrafficAlertRuleRequest),
Output: new(dto.PackageTrafficAlertRuleListResponse),
Auth: true,
})
Register(ruleGroup, doc, rulePath, "POST", "", handler.CreateRule, RouteSpec{
Summary: "创建套餐真流量预警规则",
Description: "每个套餐商品至多一条当前规则;创建时校验套餐存在且商品真流量额度大于零,阈值为 1%100% 的小数百分比",
Tags: []string{"套餐管理"},
Body: new(dto.CreatePackageTrafficAlertRuleRequest),
Output: new(dto.PackageTrafficAlertRuleItem),
Auth: true,
})
Register(ruleGroup, doc, rulePath, "PUT", "/:id", handler.UpdateRule, RouteSpec{
Summary: "修改套餐真流量预警规则",
Description: "允许修改阈值、启停与备注;修改不影响既有预警快照,停用后扫描不再创建新预警",
Tags: []string{"套餐管理"},
Input: new(dto.UpdatePackageTrafficAlertRuleParams),
Output: new(dto.PackageTrafficAlertRuleItem),
Auth: true,
})
alertGroup := group.Group("/package-traffic-alerts")
alertPath := basePath + "/package-traffic-alerts"
Register(alertGroup, doc, alertPath, "GET", "", handler.ListAlerts, RouteSpec{
Summary: "查询套餐真流量达量预警列表",
Description: "先应用既有资产数据范围;资产、套餐、用量、阈值、到期时间与触发时归属均为触发快照,支持按触发时间闭区间与通知投递结果筛选",
Tags: []string{"套餐流量预警"},
Input: new(dto.ListPackageTrafficAlertRequest),
Output: new(dto.PackageTrafficAlertListResponse),
Auth: true,
})
Register(alertGroup, doc, alertPath, "GET", "/:id", handler.GetAlert, RouteSpec{
Summary: "查询套餐真流量达量预警详情",
Description: "越权与不存在统一按资源不可见处理;返回冻结快照、通知投递结果与通知已读展示期",
Tags: []string{"套餐流量预警"},
Input: new(dto.IDReq),
Output: new(dto.PackageTrafficAlertDetailResponse),
Auth: true,
})
Register(alertGroup, doc, alertPath, "POST", "/export", handler.ExportAlerts, RouteSpec{
Summary: "导出套餐真流量达量预警",
Description: "复用既有异步导出任务,创建时冻结操作者、筛选、时间范围与可见资产范围;归属列按执行时当前归属补充",
Tags: []string{"套餐流量预警"},
Body: new(dto.ExportPackageTrafficAlertRequest),
Output: new(dto.CreateExportTaskResponse),
Auth: true,
})
}