// stats_handler.go Day68:运营总览(/home)真实数据——四指标卡 summary + 近 N 日 // trend 两端点。契约=web/src/api/stats.ts(FE-Design-Audit B1,此前仅 msw mock // 承载);响应形状与 mock ok() 逐字段一致({code,msg,data})。 // // 性能(Day64/67 教训前置):趋势/历史不直查明细(340 万行×7 天=700 万条目扫描, // HDD 5s+/次×60s 自动刷新不可持续)——日汇总表 stats_daily 由后台 60s ticker 增量 // UPSERT(当天行滚动更新+跨天补昨日终值,幂等),API 只读汇总表毫秒级;聚合 SQL // 三条纯覆盖索引 COUNT(总量 idx_detail_created/成败 idx_status_time(status, // created_at))零随机回表。 // // 口径:success_rate=终态成功率 success/(success+failed)(在途0/提交1/未知4/拦截5 // 不计分母,运营语义);today_sent=全部提交含在途。balance_alert_count 同 // service/account/warning.go ScanOnce 口径(启用规则×启用账号×可用额度 // balance+credit_balance<阈值)。pending_audit_count=message_task.audit_status=0。 // // 角色范围:admin/ops/service=全平台(stats_daily);group/customer=仅自己账号 // (明细直查——自有量级小;大客户场景预留账号维度汇总,见 entity.StatsDaily 注)。 package v1 import ( "time" "github.com/gin-gonic/gin" "go.uber.org/zap" "gorm.io/gorm" "gorm.io/gorm/clause" "go-sms/internal/middleware" "go-sms/internal/model/entity" "go-sms/internal/pkg/response" ) const ( // statsRefreshEvery 汇总刷新周期(与前端 Dashboard 60s 自动刷新同频)。 statsRefreshEvery = time.Minute // statsTrendMaxDays 趋势最大天数(防 days 超大;mock 契约默认 7)。 statsTrendMaxDays = 30 // statsRefresherBackfillDays 启动回补天数(趋势窗余量)。 statsRefresherBackfillDays = 30 ) type statsHandler struct{ db *gorm.DB } // registerStatsRoutes 注册 stats 域端点(查询类,JWT 保护即可,不挂 Casbin)。 func registerStatsRoutes(protected *gin.RouterGroup, db *gorm.DB) { h := &statsHandler{db: db} protected.GET("/stats/summary", h.summary) protected.GET("/stats/trend", h.trend) } // statsSummaryDTO 四指标卡(mock 契约逐字段)。 type statsSummaryDTO struct { TodaySent int64 `json:"today_sent"` YesterdaySent int64 `json:"yesterday_sent"` SuccessRate float64 `json:"success_rate"` // 0~1(终态口径) SuccessRateDelta float64 `json:"success_rate_delta"` // 今-昨(pp 差值) BalanceAlertCount int64 `json:"balance_alert_count"` // 余额低于预警线账号数 PendingAuditCount int64 `json:"pending_audit_count"` // 待人工审核条数 } // trendDTO 趋势点(mock 契约:date='MM-DD')。 type trendDTO struct { Date string `json:"date"` Sent int64 `json:"sent"` Success int64 `json:"success"` } // statsClaims 从 gin 上下文取登录 Claims(protected 组内恒在;nil 仅测试场景)。 func statsClaims(c *gin.Context) *middleware.Claims { v, _ := c.Get(middleware.ContextKeyClaims) claims, _ := v.(*middleware.Claims) return claims } // statsIsPlatform 平台口径角色判定(admin/ops/service);其余(group/customer) // 走自己账号范围。 func statsIsPlatform(c *gin.Context) bool { claims := statsClaims(c) if claims == nil { return true } for _, r := range claims.Roles { if r == "admin" || r == "ops" || r == "service" { return true } } return false } // statsRate 终态成功率(分母 0 返回 0)。 func statsRate(succ, fail int64) float64 { if d := succ + fail; d > 0 { return float64(succ) / float64(d) } return 0 } // platformDay 读汇总表单日三元组(无行=0,如启动回补前的首分钟)。 func (h *statsHandler) platformDay(day time.Time) (sub, succ, fail int64) { var row entity.StatsDaily if err := h.db.Where("day = ?", day.Format("2006-01-02")).Take(&row).Error; err != nil { return 0, 0, 0 } return row.Submitted, row.Success, row.Failed } // accountDay 客户口径单日直查(自有量级小,一条聚合可接受;SUM 布尔两库通用)。 func (h *statsHandler) accountDay(accountID int64, day time.Time) (sub, succ, fail int64) { type r struct { Total int64 Succ int64 Fail int64 } var row r if err := h.db.Table("message_detail"). Select("COUNT(*) AS total, COALESCE(SUM(status = 2), 0) AS succ, COALESCE(SUM(status = 3), 0) AS fail"). Where("account_id = ? AND created_at >= ? AND created_at < ?", accountID, day, day.AddDate(0, 0, 1)). Take(&row).Error; err != nil { return 0, 0, 0 } return row.Total, row.Succ, row.Fail } // balanceAlertCount 余额预警计数(平台=全量规则;客户=自己 0/1)。Raw 绕 gorm // 软删过滤需手工 deleted_at IS NULL(与 warning.go Take 自动过滤口径一致)。 func (h *statsHandler) balanceAlertCount(c *gin.Context, platform bool) int64 { if platform { var n int64 h.db.Raw(`SELECT COUNT(*) FROM system_alert_rule r JOIN account_user a ON a.id = r.target_id AND a.status = 1 AND a.deleted_at IS NULL WHERE r.status = 1 AND r.target_type = 'account' AND r.metric = 'balance' AND (a.balance + a.credit_balance) < r.threshold`).Scan(&n) return n } claims := statsClaims(c) if claims == nil { return 0 } var rule entity.SystemAlertRule if err := h.db.Where( "status = 1 AND target_type = ? AND metric = ? AND target_id = ?", "account", "balance", claims.AccountID, ).Take(&rule).Error; err != nil { return 0 // 未配置阈值不计 } var acct entity.AccountUser if err := h.db.Select("balance", "credit_balance").Take(&acct, claims.AccountID).Error; err != nil { return 0 } if float64(acct.Balance+acct.CreditBalance) < rule.Threshold { return 1 } return 0 } // pendingAuditCount 待人工审核计数(audit_status=0;idx_audit 覆盖快扫)。 func (h *statsHandler) pendingAuditCount(c *gin.Context, platform bool) int64 { q := h.db.Table("message_task").Where("audit_status = 0") if !platform { if claims := statsClaims(c); claims != nil { q = q.Where("account_id = ?", claims.AccountID) } } var n int64 q.Count(&n) return n } // summary GET /stats/summary——四指标卡。 func (h *statsHandler) summary(c *gin.Context) { now := time.Now() // 自然日窗口(00:00~24:00):与 statsAggregateDay 聚合口径一致,且避免 // 「行 created_at 与请求时刻同毫秒」的窗口边界竞争。 today := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location()) yesterday := today.AddDate(0, 0, -1) platform := statsIsPlatform(c) var tSub, tSucc, tFail, ySub, ySucc, yFail int64 if platform { tSub, tSucc, tFail = h.platformDay(today) ySub, ySucc, yFail = h.platformDay(yesterday) } else { claims := statsClaims(c) tSub, tSucc, tFail = h.accountDay(claims.AccountID, today) ySub, ySucc, yFail = h.accountDay(claims.AccountID, yesterday) } response.Success(c, statsSummaryDTO{ TodaySent: tSub, YesterdaySent: ySub, SuccessRate: statsRate(tSucc, tFail), SuccessRateDelta: statsRate(tSucc, tFail) - statsRate(ySucc, yFail), BalanceAlertCount: h.balanceAlertCount(c, platform), PendingAuditCount: h.pendingAuditCount(c, platform), }) } // trend GET /stats/trend?days=7——近 N 日趋势(缺日补零;date=MM-DD 同 mock)。 func (h *statsHandler) trend(c *gin.Context) { days := intQuery(c, "days", 7) if days < 1 { days = 7 } if days > statsTrendMaxDays { days = statsTrendMaxDays } now := time.Now() // 自然日起点(与 summary/聚合同口径,避免毫秒级窗口边界竞争)。 start := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location()). AddDate(0, 0, -(days - 1)) byDay := map[string][2]int64{} if statsIsPlatform(c) { var rows []entity.StatsDaily if err := h.db.Where("day >= ?", start.Format("2006-01-02")). Order("day").Find(&rows).Error; err != nil { bizResp(c, err) return } for _, r := range rows { byDay[r.Day] = [2]int64{r.Submitted, r.Success} } } else { claims := statsClaims(c) type row struct { Day string Submitted int64 Success int64 } var rows []row if err := h.db.Table("message_detail"). Select("date(created_at) AS day, COUNT(*) AS submitted, COALESCE(SUM(status = 2), 0) AS success"). Where("account_id = ? AND created_at >= ?", claims.AccountID, start). Group("day").Order("day").Scan(&rows).Error; err != nil { bizResp(c, err) return } for _, r := range rows { byDay[r.Day] = [2]int64{r.Submitted, r.Success} } } list := make([]trendDTO, 0, days) for i := 0; i < days; i++ { day := start.AddDate(0, 0, i) v := byDay[day.Format("2006-01-02")] list = append(list, trendDTO{Date: day.Format("01-02"), Sent: v[0], Success: v[1]}) } response.Success(c, list) } // statsAggregateDay 单日聚合(幂等 UPSERT):三条纯覆盖索引 COUNT——总量走 // idx_detail_created,成功/失败各走 idx_status_time(status,created_at)—— // 零随机回表(Day67 教训:合一条 SUM(status=2) 会让覆盖索引失效退化百万级回表)。 func statsAggregateDay(db *gorm.DB, day time.Time) error { lo := time.Date(day.Year(), day.Month(), day.Day(), 0, 0, 0, 0, day.Location()) hi := lo.AddDate(0, 0, 1) var submitted, success, failed int64 if err := db.Table("message_detail"). Where("created_at >= ? AND created_at < ?", lo, hi). Count(&submitted).Error; err != nil { return err } if err := db.Table("message_detail"). Where("status = ? AND created_at >= ? AND created_at < ?", 2, lo, hi). Count(&success).Error; err != nil { return err } if err := db.Table("message_detail"). Where("status = ? AND created_at >= ? AND created_at < ?", 3, lo, hi). Count(&failed).Error; err != nil { return err } row := entity.StatsDaily{ Day: lo.Format("2006-01-02"), Submitted: submitted, Success: success, Failed: failed, } return db.Clauses(clause.OnConflict{ Columns: []clause.Column{{Name: "day"}}, DoUpdates: clause.AssignmentColumns([]string{"submitted", "success", "failed", "updated_at"}), }).Create(&row).Error } // StartStatsRefresher 后台汇总刷新(仅 gateway 装配调用;测试/迁移工具不启): // 启动即后台回补 30 天(不阻塞启动,HDD 首轮 1~2 分钟),此后 60s ticker 聚合 // 今天+昨天(跨天窗口补昨日终值)。幂等 UPSERT——多实例重复刷新无害。 func StartStatsRefresher(db *gorm.DB, log *zap.Logger) { go func() { for i := statsRefresherBackfillDays - 1; i >= 0; i-- { day := time.Now().AddDate(0, 0, -i) if err := statsAggregateDay(db, day); err != nil && log != nil { log.Warn("stats_backfill_day_failed", zap.String("day", day.Format("2006-01-02")), zap.Error(err)) } } if log != nil { log.Info("stats_backfill_done") } ticker := time.NewTicker(statsRefreshEvery) defer ticker.Stop() for range ticker.C { now := time.Now() for _, d := range []time.Time{now, now.AddDate(0, 0, -1)} { if err := statsAggregateDay(db, d); err != nil && log != nil { log.Warn("stats_refresh_failed", zap.Error(err)) } } } }() }