diff --git a/CHANGELOG.md b/CHANGELOG.md index 05251dc2..3067a409 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,14 @@ > 本仓 CHANGELOG 自重建起记(POC 明细见归档仓 /data/poc-archive/repos/go-sms.git 的 CHANGELOG.md,已冻结)。 +## 2026-11-14(傍晚)· S2-D2 消耗日汇总引擎(settle 域首批业务代码) + +- **settle/consume.go**:AggregateDay 账号×业务→billing_consume_log、通道→stats_channel_daily(GROUP BY+SUM(status=N)+[lo,hi) 半开窗双方言、OnConflict 复合 uk UPSERT、cost_total 不写守 R1)+ListConsume(时间窗按天归一修复:零点行不被带时刻参数误滤)。 +- **滚动重刷模型(D1 计划关键修正)**:单日 T+1 落账在 72h 回执窗内会失真(UNKNOWN→成功迁移)→ 周期(1h)重刷近 4 天幂等收敛+启动回补 7 天;月结建议 T+4 后生成。job.go 照 StartStatsRefresher 模式(失败 Warn 自愈+errors 计数器)。 +- **两端点**:GET /billing/consume(customer/group 强制收窄自身,越权带参覆盖)/POST /ops/settle/aggregate(settle:write 手动回补);Deps.Settle 装配+config.Settle 段+metrics 两件(go_sms_settle_aggregate_rows_total/errors_total)。 +- **测试 6 件**(sqlite):正确性/幂等+跨天边界/**UNKNOWN 迁移收敛**/过滤分页/customer 收窄/手动回补+坏日期。 +- **门禁**:vet 0/**-race 39 包零 FAIL**/lint 0;**真 MySQL 实机闭环**:种 3 条明细→启动回补落账逐列正确→UPDATE status 重启重刷收敛(success 1→2/unknown 1→0)→清理+三轮重驻 md5 一致。验收单 `docs/acceptance/s2-d2.md`。 + ## 2026-11-14(18:02)· 24h 稳定性门槛期满核验终判通过(S1 最后一项挂账清偿) - **终判 ✅**:核验三项全绿——①dmesg 崩溃计数(segfault/sigill/error 25)=0(11-13 21:33 宿主重启清零后全窗零新增);②九中间件 Up 20 hours 全 healthy(自愈拉起后观察窗零重启);③gateway 同 PID 53153 驻留 19h47m+/health ok+md5 比对一致(ecf71db6…)。期内唯一事件=11-13 21:33 宿主内核升级主动有序重启(用户裁决:已知事件如实记录不判失败)。 diff --git a/cmd/gateway/main.go b/cmd/gateway/main.go index a5c62a93..59c8e840 100644 --- a/cmd/gateway/main.go +++ b/cmd/gateway/main.go @@ -31,6 +31,7 @@ import ( "go-sms/internal/service/report" "go-sms/internal/service/router" "go-sms/internal/service/send" + "go-sms/internal/service/settle" "go-sms/internal/service/template" "go-sms/internal/service/uplink" "go-sms/internal/util" @@ -233,10 +234,15 @@ func main() { CMPPCfg: &cfg.Server.CMPP, // 阶段5收尾(D28):/record/repush 域四端点 Pair: pairSvc, + // S2:结算域(D2=消耗日汇总;充值审核/月结/阶梯/利润随 D3~D5 追加) + Settle: settle.NewService(db), }) // Day68:运营总览汇总刷新(回补 30 天+60s ticker 增量 UPSERT stats_daily; // 幂等多实例无害,详见 stats_handler.go StartStatsRefresher)。 v1.StartStatsRefresher(db, a.Lg()) + // S2-D2:消耗日汇总滚动重刷(回补 7 天+1h ticker 重刷近 4 天;72h 回执 + // 窗内 UNKNOWN 会迁移,幂等 UPSERT 收敛;详见 service/settle/job.go)。 + v1.StartSettleAggregateJob(db, cfg.Settle, a.Lg()) // Day 46:外部 HTTP API 提交(SMS_HTTP_1.6;/sms/api 独立协议域,MD5 验签+ // 双桶限流:全局 IP 桶(静态配置)+账号桶(动态 speed_limit); diff --git a/configs/config.dev.yaml b/configs/config.dev.yaml index b606a0c9..c14a8ed2 100644 --- a/configs/config.dev.yaml +++ b/configs/config.dev.yaml @@ -101,3 +101,8 @@ rate_limit: # Redis 令牌桶分布式限流(Day 9) balance: # 资金预扣模式(Day54 R1,评审 docs/review/r1-balance.md) mode: redis # P1 压测(09-27):mysql→redis——行锁扣款(HDD 单行串行 ~140ms)把受理锁死在 30/s(实测 20:41-20:45);SubmitFast 快路径设计前提=Redis Lua(112μs);对账覆写 5min 兜底 reconcile_interval: 5m # 对账周期(评审约束 ≤5min;MySQL 流水重算覆写 Redis) + +settle: # S2 结算域:消耗日汇总滚动重刷(72h 回执窗内 UNKNOWN 会迁移,昨日行非终值须滚动收敛;月结建议 T+4 后生成) + refresh_every: 1h # 重刷周期 + refresh_days: 4 # 每轮重刷窗口天数(today-3..today) + backfill_days: 7 # 启动回补天数(明细热窗 5 天内余量) diff --git a/docs/acceptance/s2-d2.md b/docs/acceptance/s2-d2.md new file mode 100644 index 00000000..5cca0785 --- /dev/null +++ b/docs/acceptance/s2-d2.md @@ -0,0 +1,42 @@ +# S2-D2 消耗日汇总引擎 人工验收单(2026-11-14) + +> 前置:s2-d1.md(表设计+v20+契约)。本单覆盖 D2:settle 域首批业务代码—— +> 消耗日汇总引擎(结算域事实源)+ 两端点 + 后台滚动重刷 job。 + +## 一、交付物 + +| # | 任务 | 结果 | 证据 | +|---|---|---|---| +| 1 | **settle/consume.go**(聚合引擎) | ✅ | `AggregateDay`:账号×业务→billing_consume_log、通道→stats_channel_daily,一条 GROUP BY(计 SUM(status=N) 计数+Σfee 条)+OnConflict UPSERT(复合 uk 覆盖更新);`[lo,hi)` 半开窗规避 date() 方言差;cost_total 不写(R1);`ListConsume` 分页/过滤/时间窗按天归一(零点行不被带时刻参数误滤) | +| 2 | **settle/job.go**(滚动重刷 job) | ✅ | **对 D1 计划的关键修正**:单日 T+1 落账会在 72h 回执窗内失真(UNKNOWN→成功迁移),改为**周期重刷近 4 天**滚动收敛;启动回补 7 天;配置零值兜底(1h/4/7);失败 Warn 不中断+errors 计数器,幂等下轮自愈 | +| 3 | **settle_handler.go**(两端点) | ✅ | `GET /billing/consume`(JWT+customer/group 强制收窄自身,越权带参覆盖不报错)+ `POST /ops/settle/aggregate`(settle:write 手动回补);D3~D5 端点随任务在本文件追加 | +| 4 | **装配** | ✅ | Deps.Settle 字段+registerSettleRoutes;`v1.StartSettleAggregateJob`(照 StartStatsRefresher v1 层包装模式);gateway main 挂载于 StatsRefresher 之后;config.Settle 段(1h/4/7)+config.dev.yaml 注释口径;metrics 两件(`go_sms_settle_aggregate_rows_total{kind}`/`errors_total`) | +| 5 | **单测** | ✅ | consume_test.go 4 件(正确性多账号×双业务×五状态逐行断言/幂等+跨天边界/**UNKNOWN 状态迁移重刷收敛**/查询过滤分页)+ settle_handler_test.go 2 件(admin 全量 vs customer 收窄带参越权/手动回补落账+坏日期 4xx) | + +## 二、门禁(七件套后端件) + +| 项 | 结果 | +|---|---| +| go vet ./... | ✅ RC=0 | +| go test -race ./...(全量) | ✅ **39 包 ok 零 FAIL**(新增 settle 包) | +| golangci-lint v2.1.6 | ✅ 0 issues | +| 集成 | ✅ 沿用 schema/casbin(D1 已过;D2 无新集成面,真库验证见 §三) | + +## 三、dev 实机验证(真 MySQL,2026-11-14) + +1. **部署串行铁律**:make gw-stop→gw-start 三轮(重驻/状态迁移验证/清理后),每轮 /health ok+**md5 比对一致**(8fd2dfbc…)。 +2. **端到端落账**:SQL 直插 3 条今日明细(账号 1×2:成功+未知/账号 100×1 成功,通道 1)→启动回补自动聚合 → billing_consume_log 2 行(1:sms 2/1/0/1/fee3.0;100:sms 1/1/0/0/fee2.5)+ stats_channel_daily 1 行(3/2/1/cost_total=0)——**逐列与 sqlite 单测期望一致**;metrics rows{account}=2/{channel}=1。 +3. **滚动收敛实证**:UPDATE 明细 status 4→2 → 重启重刷 → 账号 1 行 **success 1→2/unknown 1→0**——72h 回执窗迁移收敛语义在真库闭环。 +4. **指标暴露**:/metrics 出现 go_sms_settle_aggregate_errors_total=0(HELP/TYPE 正常)。 +5. **清理**:测试明细 3 条+两表当日行全删(避免僵尸汇总行——热窗内明细不删的边界已文档化),最终干净重驻。 + +## 四、口径与边界留痕 + +- **滚动重刷窗 4 天**=72h 回执窗+当天增量;月结建议 T+4 后生成(D4 文档化;generate 幂等重算兜底); +- 汇总行不随明细删除回退(热窗内明细不删;S4 分区清退后历史行冻结); +- 通道维度不含 business/Σfee(通道价格体系不分业务;上家账单按 billing_mode 条数口径); +- job 为 ticker 型(照 StatsRefresher),cronx 保留给已有 alarm/健康巡检用途。 + +## 五、验收结论 + +**S2-D2 通过。** D3(充值审核流)开工前置=本单归档+CHANGELOG+回填+提交。 diff --git a/internal/api/http/v1/account.go b/internal/api/http/v1/account.go index 00250648..6deaec08 100644 --- a/internal/api/http/v1/account.go +++ b/internal/api/http/v1/account.go @@ -29,6 +29,7 @@ import ( "go-sms/internal/service/report" "go-sms/internal/service/router" "go-sms/internal/service/send" + "go-sms/internal/service/settle" "go-sms/internal/service/template" ) @@ -64,6 +65,9 @@ type Deps struct { // CMPPCfg Day 62:CMPP 服务端配置(系统默认配额+端口;GET api-config 的 // cmpp_access 块数据源;nil=CMPP 未启用,响应不带该块)。 CMPPCfg *config.CMPPServer + // Settle S2:结算域(消耗日汇总查询/手动回补;充值订单/月结/阶梯/利润 + // 随 D3~D5 追加;nil=不注册,前端 404 优于半可用)。 + Settle *settle.Service } // Register 注册 v1 路由组。 @@ -189,6 +193,10 @@ func Register(rg *gin.RouterGroup, deps Deps) { if deps.DB != nil { registerStatsRoutes(protected, deps.DB) } + // S2:结算域(D2 消耗日汇总两端点;D3~D5 端点随任务追加,见 settle_handler.go)。 + if deps.Settle != nil { + registerSettleRoutes(protected, deps) + } // 阶段5收尾(D28):回执重推域四端点(回执分页/重推受理/挂起明细/手动配对; // 服务依赖 Billing/PushSink,装配见 cmd/gateway)。 if deps.Pair != nil { diff --git a/internal/api/http/v1/settle_handler.go b/internal/api/http/v1/settle_handler.go new file mode 100644 index 00000000..96fe7651 --- /dev/null +++ b/internal/api/http/v1/settle_handler.go @@ -0,0 +1,114 @@ +// settle_handler.go S2:结算域端点。D2 先挂两件——消耗日汇总查询(/billing/ +// consume)与手动回补(/ops/settle/aggregate);D3(充值订单审核族)/D4(月结 +// 单/阶梯/导出)/D5(利润/对账)随任务推进在本文件追加,契约见 openapi v1.3.0。 +package v1 + +import ( + "strconv" + "time" + + "github.com/gin-gonic/gin" + "go.uber.org/zap" + "gorm.io/gorm" + + "go-sms/internal/config" + "go-sms/internal/middleware" + errs "go-sms/internal/pkg/errors" + "go-sms/internal/pkg/response" + "go-sms/internal/service/settle" +) + +// settleConsumeDefaultDays 消耗查询缺省窗口(近 7 天,对齐 stats trend 口径)。 +const settleConsumeDefaultDays = 7 + +func registerSettleRoutes(protected *gin.RouterGroup, deps Deps) { + h := &settleHandler{svc: deps.Settle} + // 消耗日汇总查询:JWT 即可(admin/ops/service 全量;group/customer 仅自己, + // scope 收窄在 handler 内做——与 stats 域同口径,casbin customer settle:read + // 策略为 v20 所种,细分资源门按需后挂)。 + protected.GET("/billing/consume", h.consumeList) + // 手动触发回补(运维口径;settle:write)。 + protected.POST("/ops/settle/aggregate", + middleware.RequirePermission(deps.Perm, "settle", "write"), h.aggregate) +} + +// StartSettleAggregateJob v1 层装配入口(照 StartStatsRefresher 模式,仅 +// gateway 调用;测试/迁移工具不启)。 +func StartSettleAggregateJob(db *gorm.DB, cfg config.Settle, log *zap.Logger) { + settle.StartAggregateJob(db, cfg.RefreshEvery, cfg.RefreshDays, cfg.BackfillDays, log) +} + +type settleHandler struct{ svc *settle.Service } + +// consumeList GET /billing/consume:账号×业务×天 消耗事实源查询。 +func (h *settleHandler) consumeList(c *gin.Context) { + claims := statsClaims(c) // protected 组内恒在;复用 stats 域提取器 + q := settle.ConsumeQuery{Page: 1, PageSize: 20} + if v, err := strconv.ParseInt(c.Query("account_id"), 10, 64); err == nil && v > 0 { + q.AccountID = v + } + q.Business = c.Query("business") + now := time.Now() + q.To = now + q.From = now.AddDate(0, 0, -(settleConsumeDefaultDays - 1)) + if s := c.Query("date_from"); s != "" { + d, err := time.ParseInLocation("2006-01-02", s, time.Local) + if err != nil { + response.Error(c, errs.InvalidParam.WithMsg("date_from 须为 YYYY-MM-DD")) + return + } + q.From = d + } + if s := c.Query("date_to"); s != "" { + d, err := time.ParseInLocation("2006-01-02", s, time.Local) + if err != nil { + response.Error(c, errs.InvalidParam.WithMsg("date_to 须为 YYYY-MM-DD")) + return + } + q.To = d + } + if v, err := strconv.Atoi(c.Query("page")); err == nil && v > 0 { + q.Page = v + } + if v, err := strconv.Atoi(c.Query("page_size")); err == nil && v > 0 { + q.PageSize = v + } + // 非平台角色强制收窄到自身账号(带参越权请求直接覆盖,不报错——stats 同口径)。 + if claims != nil && !statsIsPlatform(c) { + q.AccountID = claims.AccountID + } + list, total, err := h.svc.ListConsume(c.Request.Context(), q) + if err != nil { + bizResp(c, err) + return + } + response.Success(c, gin.H{"total": total, "list": list}) +} + +// aggregate POST /ops/settle/aggregate:date 缺省=昨日;幂等 UPSERT 可重入, +// 返回两表落账行数(只回补单日——历史区间回补走重启 job 的 backfill 或逐日调用)。 +func (h *settleHandler) aggregate(c *gin.Context) { + var req struct { + Date string `json:"date"` + } + _ = c.ShouldBindJSON(&req) + day := time.Now().AddDate(0, 0, -1) + if req.Date != "" { + d, err := time.ParseInLocation("2006-01-02", req.Date, time.Local) + if err != nil { + response.Error(c, errs.InvalidParam.WithMsg("date 须为 YYYY-MM-DD")) + return + } + day = d + } + accountRows, channelRows, err := h.svc.AggregateDay(c.Request.Context(), day) + if err != nil { + bizResp(c, err) + return + } + response.Success(c, gin.H{ + "day": day.Format("2006-01-02"), + "account_rows": accountRows, + "channel_rows": channelRows, + }) +} diff --git a/internal/api/http/v1/settle_handler_test.go b/internal/api/http/v1/settle_handler_test.go new file mode 100644 index 00000000..15cc10cf --- /dev/null +++ b/internal/api/http/v1/settle_handler_test.go @@ -0,0 +1,157 @@ +package v1 + +// settle_handler_test.go S2-D2:消耗日汇总两端点——customer scope 强制收窄 +// (带参越权请求覆盖不报错,stats 同口径)+手动回补落账断言。 +// gin TestMode + sqlite;claims 由中间件注入模拟(stats_handler_test 同款)。 + +import ( + "encoding/json" + "net/http" + "net/http/httptest" + "strings" + "testing" + "time" + + "github.com/gin-gonic/gin" + "github.com/glebarez/sqlite" + "gorm.io/gorm" + + "go-sms/internal/middleware" + "go-sms/internal/model/entity" + "go-sms/internal/service/settle" +) + +// newSettleRouter 种子:账号 1/100 今日各 1 条成功明细(通道 1);返回注入器。 +func newSettleRouter(t *testing.T) (*gin.Engine, *gorm.DB, func(*middleware.Claims)) { + t.Helper() + gin.SetMode(gin.TestMode) + db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) + if err != nil { + t.Fatal(err) + } + if s, e := db.DB(); e == nil { + s.SetMaxOpenConns(1) + } + if err := db.AutoMigrate(&entity.MessageDetail{}, &entity.BillingConsumeLog{}, + &entity.StatsChannelDaily{}); err != nil { + t.Fatal(err) + } + now := time.Now() + details := []entity.MessageDetail{ + {SnowflakeModel: entity.SnowflakeModel{ID: 9100000001, CreatedAt: now}, + TaskID: 800001, AccountID: 1, ChannelID: 1, Mobile: "13000000001", + Content: "t", Status: 2, Business: "sms", Fee: 1.5}, + {SnowflakeModel: entity.SnowflakeModel{ID: 9100000002, CreatedAt: now}, + TaskID: 800002, AccountID: 100, ChannelID: 1, Mobile: "13000000002", + Content: "t", Status: 2, Business: "sms", Fee: 2.5}, + } + if err := db.Create(&details).Error; err != nil { + t.Fatal(err) + } + rg := gin.New() + api := rg.Group("/api/v1") + var claims *middleware.Claims + api.Use(func(c *gin.Context) { + if claims != nil { + c.Set(middleware.ContextKeyClaims, claims) + } + }) + registerSettleRoutes(api, Deps{Settle: settle.NewService(db)}) + return rg, db, func(cl *middleware.Claims) { claims = cl } +} + +// TestSettleConsume_AdminSeesAll admin 全量;customer 强制收窄(带参越权覆盖)。 +func TestSettleConsume_Scope(t *testing.T) { + rg, db, setClaims := newSettleRouter(t) + // 预落账(查询读事实源,不直查明细)。 + svc := settle.NewService(db) + if _, _, err := svc.AggregateDay(t.Context(), time.Now()); err != nil { + t.Fatal(err) + } + + setClaims(&middleware.Claims{AccountID: 1, Username: "admin", Roles: []string{"admin"}}) + w := httptest.NewRecorder() + rg.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/api/v1/billing/consume", nil)) + if w.Code != 200 { + t.Fatalf("admin status=%d body=%s", w.Code, w.Body.String()) + } + var res struct { + Data struct { + Total int64 `json:"total"` + List []entity.BillingConsumeLog `json:"list"` + } `json:"data"` + } + if err := json.Unmarshal(w.Body.Bytes(), &res); err != nil { + t.Fatal(err) + } + if res.Data.Total != 2 { + t.Fatalf("admin 应见全量 2 行,got %d", res.Data.Total) + } + + // customer 带参越权(account_id=1):应被覆盖为自身 100。 + setClaims(&middleware.Claims{AccountID: 100, Username: "cust", Roles: []string{"customer"}}) + w = httptest.NewRecorder() + req := httptest.NewRequest(http.MethodGet, "/api/v1/billing/consume?account_id=1", nil) + rg.ServeHTTP(w, req) + if w.Code != 200 { + t.Fatalf("customer status=%d body=%s", w.Code, w.Body.String()) + } + if err := json.Unmarshal(w.Body.Bytes(), &res); err != nil { + t.Fatal(err) + } + if res.Data.Total != 1 || len(res.Data.List) != 1 || res.Data.List[0].AccountID != 100 { + t.Fatalf("customer 应强制收窄到自身 100: total=%d list=%v", res.Data.Total, res.Data.List) + } +} + +// TestSettleAggregate_Manual 手动回补:返回行数+落库断言;坏日期 4xx。 +func TestSettleAggregate_Manual(t *testing.T) { + rg, db, setClaims := newSettleRouter(t) + setClaims(&middleware.Claims{AccountID: 1, Username: "admin", Roles: []string{"admin"}}) + + w := httptest.NewRecorder() + rg.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/api/v1/ops/settle/aggregate", nil)) + if w.Code != 200 { + t.Fatalf("status=%d body=%s", w.Code, w.Body.String()) + } + var res struct { + Data struct { + Day string `json:"day"` + AccountRows int64 `json:"account_rows"` + ChannelRows int64 `json:"channel_rows"` + } `json:"data"` + } + if err := json.Unmarshal(w.Body.Bytes(), &res); err != nil { + t.Fatal(err) + } + // 缺省=昨日:种子明细是今天 → 0 行也合法;显式补今天断言 2/1。 + w = httptest.NewRecorder() + req := httptest.NewRequest(http.MethodPost, "/api/v1/ops/settle/aggregate", + strings.NewReader(`{"date":"`+time.Now().Format("2006-01-02")+`"}`)) + req.Header.Set("Content-Type", "application/json") + rg.ServeHTTP(w, req) + if w.Code != 200 { + t.Fatalf("status=%d body=%s", w.Code, w.Body.String()) + } + if err := json.Unmarshal(w.Body.Bytes(), &res); err != nil { + t.Fatal(err) + } + if res.Data.AccountRows != 2 || res.Data.ChannelRows != 1 { + t.Fatalf("今日回补应 account_rows=2/channel_rows=1: %+v", res.Data) + } + var n int64 + db.Model(&entity.BillingConsumeLog{}).Count(&n) + if n != 2 { + t.Fatalf("billing_consume_log 落账=%d 期望 2", n) + } + + // 坏日期参数。 + w = httptest.NewRecorder() + req = httptest.NewRequest(http.MethodPost, "/api/v1/ops/settle/aggregate", + strings.NewReader(`{"date":"2026/11/14"}`)) + req.Header.Set("Content-Type", "application/json") + rg.ServeHTTP(w, req) + if w.Code == 200 { + t.Fatalf("坏日期应 4xx,got %d body=%s", w.Code, w.Body.String()) + } +} diff --git a/internal/config/config.go b/internal/config/config.go index 99a7e4b7..5986d1f9 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -25,6 +25,16 @@ type Config struct { RateLimit RateLimit `mapstructure:"rate_limit"` HotReload HotReload `mapstructure:"hot_reload"` Balance Balance `mapstructure:"balance"` + Settle Settle `mapstructure:"settle"` +} + +// Settle 结算域配置(S2):消耗日汇总滚动重刷模型——周期重刷近 N 天 +// (默认 4 天:72h 回执窗内明细状态会迁移 UNKNOWN→成功/失败,昨日行非终值, +// 须滚动收敛;月结建议 T+4 后生成)。零值兜底见 service/settle/job.go。 +type Settle struct { + RefreshEvery time.Duration `mapstructure:"refresh_every"` // 重刷周期(默认 1h) + RefreshDays int `mapstructure:"refresh_days"` // 每轮重刷天数窗(默认 4=today-3..today) + BackfillDays int `mapstructure:"backfill_days"` // 启动回补天数(默认 7,明细热窗 5 天内余量) } // Balance 资金预扣模式(Day54 R1,评审 docs/review/r1-balance.md): diff --git a/internal/pkg/metrics/prometheus.go b/internal/pkg/metrics/prometheus.go index c8c110fc..43ea0719 100644 --- a/internal/pkg/metrics/prometheus.go +++ b/internal/pkg/metrics/prometheus.go @@ -75,6 +75,14 @@ var ( // ReportRecheckTotal pending 后新事务复查结果({result}: finalized=补刀 // 终态/still_pending=真未到齐;双盲竞态健康度=finalized 占比)。 ReportRecheckTotal *prometheus.CounterVec + + // SettleAggregateRows 结算域消耗日汇总落账行数(scope: account=billing_ + // consume_log / channel=stats_channel_daily;幂等 UPSERT 重刷亦计入, + // 单调累计供观测 job 活性,S5 基线期再评估是否细化)。 + SettleAggregateRows *prometheus.CounterVec + // SettleAggregateErrors 消耗日汇总执行失败次数(失败 Warn 不中断, + // 幂等下轮自愈;持续增长=真故障信号)。 + SettleAggregateErrors prometheus.Counter ) var registry = prometheus.NewRegistry() @@ -171,6 +179,16 @@ func init() { Help: "pending 后新事务复查结果(result: finalized=补刀终态/still_pending=真未到齐)", }, []string{LabelKind}) + SettleAggregateRows = prometheus.NewCounterVec(prometheus.CounterOpts{ + Name: "go_sms_settle_aggregate_rows_total", + Help: "结算域消耗日汇总落账行数(scope: account/channel;UPSERT 重刷亦计入,S2)", + }, []string{LabelKind}) + + SettleAggregateErrors = prometheus.NewCounter(prometheus.CounterOpts{ + Name: "go_sms_settle_aggregate_errors_total", + Help: "消耗日汇总执行失败次数(幂等下轮自愈,持续增长=真故障,S2)", + }) + registry.MustRegister( HTTPRequestsTotal, HTTPRequestDuration, HTTPRequestsInFlight, SMSSubmitTotal, SMSReportTotal, KafkaProducerMessages, @@ -179,6 +197,7 @@ func init() { LongSmsMergedTotal, LongSmsDegradeTotal, LongSmsDupFragTotal, LongSmsExpireFailTotal, ReportPendingTotal, ReportRecheckTotal, ReportRequeueTotal, + SettleAggregateRows, SettleAggregateErrors, ) // Go 运行时与进程指标 registry.MustRegister( diff --git a/internal/service/doc.go b/internal/service/doc.go index 4ed9fcc8..04dfd320 100644 --- a/internal/service/doc.go +++ b/internal/service/doc.go @@ -1,3 +1,3 @@ // Package service 业务服务实现层(账号/通道/发送/路由/审核/计费/统计/结算等)。 -// 阶段 2 起逐步填充。 +// 阶段 2 起逐步填充;S2 起新增 settle 域(消耗日汇总/充值审核/月结/阶梯/利润/对账)。 package service diff --git a/internal/service/settle/consume.go b/internal/service/settle/consume.go new file mode 100644 index 00000000..a46f2080 --- /dev/null +++ b/internal/service/settle/consume.go @@ -0,0 +1,180 @@ +// consume.go S2-D2:消耗日汇总引擎——结算域事实源(T+1 思路的滚动重刷修正版)。 +// +// 模型(评审 docs/review/s2-settle-table-review.md §三 + D2 修正): +// - 明细热窗仅 5 天,月结绝不能扫明细——billing_consume_log(账号×业务×天) +// 与 stats_channel_daily(通道×天)是结算域唯一消耗事实源(R2); +// - 72h 回执窗内明细状态会迁移(UNKNOWN→成功/失败,Day69/71),昨日行非 +// 终值——单日一次性落账会失真,改为周期滚动重刷近 N 天幂等 UPSERT 收敛; +// - 口径:submit=COUNT(*) 全部;success/fail/unknown=SUM(status=N); +// fee_total=Σfee(条,Day70 片数口径);cost_total/est_balance 不写 +// (R1:金额出账时刻推导,单一事实源纪律)。 +// - 边界:某账号当日明细为 0 则不产生行(热窗内明细不删,无脏残留场景); +// 数据清退(S4 分区)后的历史行冻结,重刷窗不覆盖即可。 +package settle + +import ( + "context" + "time" + + "gorm.io/gorm" + "gorm.io/gorm/clause" + + "go-sms/internal/model/entity" +) + +// Service 结算域服务(D2 消耗日汇总;D3~D5 逐步扩展充值审核/出账/利润/对账)。 +type Service struct{ db *gorm.DB } + +// NewService 构造(仅 db 依赖,照 account.Service 极简口径)。 +func NewService(db *gorm.DB) *Service { return &Service{db: db} } + +// accountAggRow 账号维度聚合扫描 DTO(COUNT/SUM 扫 int64 再转实体 int)。 +type accountAggRow struct { + AccountID int64 + Business string + SubmitCount int64 + SuccessCount int64 + FailCount int64 + UnknownCount int64 + FeeTotal float64 +} + +// channelAggRow 通道维度聚合扫描 DTO(无 Σfee——R1 出账按条数×价推导, +// 通道侧无需费用列,cost_total 保持 0)。 +type channelAggRow struct { + ChannelID int64 + SubmitCount int64 + SuccessCount int64 + FailCount int64 + UnknownCount int64 +} + +// AggregateDay 单日消耗汇总(幂等 UPSERT,滚动重刷安全): +// 账号×业务 → billing_consume_log(uk account_id+business+stat_date 覆盖更新); +// 通道 → stats_channel_daily(uk channel_id+stat_date)。 +// [lo,hi) 半开时间窗规避 date() 方言差;SUM(status=N) MySQL/SQLite 双方言 +// 布尔求和(stats_handler 同款)。返回两表落账行数(供指标/手动回补响应)。 +func (s *Service) AggregateDay(ctx context.Context, day time.Time) (accountRows, channelRows int64, err error) { + lo := time.Date(day.Year(), day.Month(), day.Day(), 0, 0, 0, 0, day.Location()) + hi := lo.AddDate(0, 0, 1) + + // ① 账号×业务维度(GROUP BY 聚合一条 SQL;日汇总 job 一天数次, + // 非请求路径——性能三律约束的是业务查询页,此处窗口扫描可接受, + // S5 压测后如需再优化为覆盖索引三 COUNT)。 + var accountAggs []accountAggRow + if err = s.db.WithContext(ctx).Table("message_detail"). + Select("account_id, business, COUNT(*) AS submit_count, "+ + "COALESCE(SUM(status = 2), 0) AS success_count, "+ + "COALESCE(SUM(status = 3), 0) AS fail_count, "+ + "COALESCE(SUM(status = 4), 0) AS unknown_count, "+ + "COALESCE(SUM(fee), 0) AS fee_total"). + Where("created_at >= ? AND created_at < ?", lo, hi). + Group("account_id, business"). + Scan(&accountAggs).Error; err != nil { + return 0, 0, err + } + for _, r := range accountAggs { + row := entity.BillingConsumeLog{ + AccountID: r.AccountID, + Business: r.Business, + StatDate: lo, + SubmitCount: int(r.SubmitCount), + SuccessCount: int(r.SuccessCount), + FailCount: int(r.FailCount), + UnknownCount: int(r.UnknownCount), + FeeTotal: r.FeeTotal, + } + if err = s.db.WithContext(ctx).Clauses(clause.OnConflict{ + Columns: []clause.Column{ + {Name: "account_id"}, {Name: "business"}, {Name: "stat_date"}, + }, + DoUpdates: clause.AssignmentColumns([]string{ + "submit_count", "success_count", "fail_count", + "unknown_count", "fee_total", "updated_at", + }), + }).Create(&row).Error; err != nil { + return accountRows, channelRows, err + } + accountRows++ + } + + // ② 通道维度(grain=通道×天,不加 business——通道价格体系不分业务,R2 评审; + // 不聚合 Σfee——上家账单按 billing_mode 条数口径,cost_total 保持 0,R1)。 + var channelAggs []channelAggRow + if err = s.db.WithContext(ctx).Table("message_detail"). + Select("channel_id, COUNT(*) AS submit_count, "+ + "COALESCE(SUM(status = 2), 0) AS success_count, "+ + "COALESCE(SUM(status = 3), 0) AS fail_count, "+ + "COALESCE(SUM(status = 4), 0) AS unknown_count"). + Where("created_at >= ? AND created_at < ?", lo, hi). + Group("channel_id"). + Scan(&channelAggs).Error; err != nil { + return accountRows, channelRows, err + } + for _, r := range channelAggs { + row := entity.StatsChannelDaily{ + ChannelID: r.ChannelID, + StatDate: lo, + SubmitCount: int(r.SubmitCount), + SuccessCount: int(r.SuccessCount), + FailCount: int(r.FailCount), + UnknownCount: int(r.UnknownCount), + } + if err = s.db.WithContext(ctx).Clauses(clause.OnConflict{ + Columns: []clause.Column{{Name: "channel_id"}, {Name: "stat_date"}}, + DoUpdates: clause.AssignmentColumns([]string{ + "submit_count", "success_count", "fail_count", + "unknown_count", "updated_at", + }), + }).Create(&row).Error; err != nil { + return accountRows, channelRows, err + } + channelRows++ + } + return accountRows, channelRows, nil +} + +// ConsumeQuery 消耗日汇总查询条件(To 按天闭区间,service 内转半开窗)。 +type ConsumeQuery struct { + AccountID int64 // 0=全部;customer scope 由 handler 强制注入 + Business string // ""=全部 + From time.Time // 闭区间起(零值=不限) + To time.Time // 闭区间止(零值=不限) + Page int // 1 起 + PageSize int // 默认 20,上限 100(handler 兜底) +} + +// ListConsume 分页查询消耗日汇总(按 stat_date 倒序,新数据在前)。 +func (s *Service) ListConsume(ctx context.Context, q ConsumeQuery) ([]entity.BillingConsumeLog, int64, error) { + db := s.db.WithContext(ctx).Model(&entity.BillingConsumeLog{}) + if q.AccountID > 0 { + db = db.Where("account_id = ?", q.AccountID) + } + if q.Business != "" { + db = db.Where("business = ?", q.Business) + } + if !q.From.IsZero() { + // 按天归一(stat_date 恒为当日零点,带时刻参数会把今天的行误滤)。 + f := time.Date(q.From.Year(), q.From.Month(), q.From.Day(), 0, 0, 0, 0, q.From.Location()) + db = db.Where("stat_date >= ?", f) + } + if !q.To.IsZero() { + t := time.Date(q.To.Year(), q.To.Month(), q.To.Day(), 0, 0, 0, 0, q.To.Location()) + db = db.Where("stat_date < ?", t.AddDate(0, 0, 1)) // 闭区间转半开(按天) + } + var total int64 + if err := db.Count(&total).Error; err != nil { + return nil, 0, err + } + if q.Page <= 0 { + q.Page = 1 + } + if q.PageSize <= 0 || q.PageSize > 100 { + q.PageSize = 20 + } + var list []entity.BillingConsumeLog + err := db.Order("stat_date DESC, account_id, business"). + Limit(q.PageSize).Offset((q.Page - 1) * q.PageSize). + Find(&list).Error + return list, total, err +} diff --git a/internal/service/settle/consume_test.go b/internal/service/settle/consume_test.go new file mode 100644 index 00000000..8a1f8583 --- /dev/null +++ b/internal/service/settle/consume_test.go @@ -0,0 +1,219 @@ +package settle + +// consume_test.go S2-D2:消耗日汇总引擎单测(sqlite,glebarez)——聚合正确性/ +// 幂等重跑/跨天边界/UNKNOWN 状态迁移重刷收敛(滚动重刷核心语义)/查询过滤。 +// handler 端点(customer scope 收窄+手动回补)在 api 层 settle_handler_test.go。 + +import ( + "context" + "math" + "testing" + "time" + + "github.com/glebarez/sqlite" + "gorm.io/gorm" + + "go-sms/internal/model/entity" +) + +// newConsumeDB 内存库 + message_detail/billing_consume_log/stats_channel_daily。 +func newConsumeDB(t *testing.T) *gorm.DB { + t.Helper() + db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) + if err != nil { + t.Fatal(err) + } + if s, e := db.DB(); e == nil { + s.SetMaxOpenConns(1) // sqlite :memory: 多连接=多个空库 + } + if err := db.AutoMigrate(&entity.MessageDetail{}, &entity.BillingConsumeLog{}, + &entity.StatsChannelDaily{}); err != nil { + t.Fatal(err) + } + return db +} + +// mkDetail 种一条明细(id 雪花由调用方递增保证唯一)。 +func mkDetail(id, accountID, channelID int64, business string, status int8, fee float64, created time.Time) entity.MessageDetail { + return entity.MessageDetail{ + SnowflakeModel: entity.SnowflakeModel{ID: id, CreatedAt: created}, + TaskID: 800000 + id, AccountID: accountID, ChannelID: channelID, + Mobile: "13000001111", Content: "t", Status: status, Business: business, Fee: fee, + } +} + +func feq(a, b float64) bool { return math.Abs(a-b) < 1e-9 } + +func TestAggregateDay_Correctness(t *testing.T) { + db := newConsumeDB(t) + now := time.Now() + details := []entity.MessageDetail{ + // 账号 1 · sms:2 成功(fee 1.5×2)+1 失败+1 未知+1 拦截 → submit5/succ2/fail1/unk1/fee 6.5 + mkDetail(1, 1, 1, "sms", 2, 1.5, now), mkDetail(2, 1, 1, "sms", 2, 1.5, now), + mkDetail(3, 1, 1, "sms", 3, 1.0, now), mkDetail(4, 1, 1, "sms", 4, 1.0, now), + mkDetail(5, 1, 1, "sms", 5, 1.5, now), + // 账号 1 · video:1 成功 → submit1/succ1/fee 2.0 + mkDetail(6, 1, 2, "video", 2, 2.0, now), + // 账号 100 · sms:1 成功 → submit1/succ1/fee 3.0 + mkDetail(7, 100, 2, "sms", 2, 3.0, now), + } + if err := db.Create(&details).Error; err != nil { + t.Fatal(err) + } + svc := NewService(db) + a, ch, err := svc.AggregateDay(context.Background(), now) + if err != nil { + t.Fatal(err) + } + if a != 3 || ch != 2 { + t.Fatalf("落账行数 account=%d(期望3) channel=%d(期望2)", a, ch) + } + var logs []entity.BillingConsumeLog + if err := db.Order("account_id, business").Find(&logs).Error; err != nil { + t.Fatal(err) + } + if len(logs) != 3 { + t.Fatalf("billing_consume_log 行数=%d 期望 3", len(logs)) + } + check := func(l entity.BillingConsumeLog, accountID int64, business string, submit, succ, fail, unknown int, fee float64) { + t.Helper() + if l.AccountID != accountID || l.Business != business { + t.Fatalf("行归属错: got account=%d business=%s", l.AccountID, l.Business) + } + if l.SubmitCount != submit || l.SuccessCount != succ || l.FailCount != fail || l.UnknownCount != unknown { + t.Fatalf("账号 %d %s 计数错: submit=%d succ=%d fail=%d unk=%d (期望 %d/%d/%d/%d)", + accountID, business, l.SubmitCount, l.SuccessCount, l.FailCount, l.UnknownCount, submit, succ, fail, unknown) + } + if !feq(l.FeeTotal, fee) { + t.Fatalf("账号 %d %s fee_total=%v 期望 %v", accountID, business, l.FeeTotal, fee) + } + } + check(logs[0], 1, "sms", 5, 2, 1, 1, 6.5) + check(logs[1], 1, "video", 1, 1, 0, 0, 2.0) + check(logs[2], 100, "sms", 1, 1, 0, 0, 3.0) + + var chans []entity.StatsChannelDaily + if err := db.Order("channel_id").Find(&chans).Error; err != nil || len(chans) != 2 { + t.Fatalf("stats_channel_daily 行数=%d err=%v 期望 2", len(chans), err) + } + if chans[0].ChannelID != 1 || chans[0].SubmitCount != 5 || chans[0].SuccessCount != 2 || + chans[0].FailCount != 1 || chans[0].UnknownCount != 1 { + t.Fatalf("通道 1 计数错: %+v", chans[0]) + } + if chans[1].ChannelID != 2 || chans[1].SubmitCount != 2 || chans[1].SuccessCount != 2 { + t.Fatalf("通道 2 计数错: %+v", chans[1]) + } + if chans[0].CostTotal != 0 { + t.Fatalf("cost_total 应保持 0(R1 出账计价),got %v", chans[0].CostTotal) + } +} + +func TestAggregateDay_IdempotentAndBoundary(t *testing.T) { + db := newConsumeDB(t) + now := time.Now() + yesterday := now.AddDate(0, 0, -1) + details := []entity.MessageDetail{ + mkDetail(1, 1, 1, "sms", 2, 2.0, now), + mkDetail(2, 1, 1, "sms", 3, 2.0, now), + mkDetail(3, 1, 1, "sms", 2, 2.0, yesterday), // 次日窗口外 + } + if err := db.Create(&details).Error; err != nil { + t.Fatal(err) + } + svc := NewService(db) + for i := 0; i < 2; i++ { // 两遍幂等 + a, ch, err := svc.AggregateDay(context.Background(), now) + if err != nil { + t.Fatal(err) + } + if a != 1 || ch != 1 { + t.Fatalf("第 %d 遍落账 account=%d channel=%d 期望 1/1", i+1, a, ch) + } + } + var n int64 + db.Model(&entity.BillingConsumeLog{}).Count(&n) + if n != 1 { + t.Fatalf("幂等重跑后行数=%d 期望 1", n) + } + var l entity.BillingConsumeLog + db.First(&l) + if l.SubmitCount != 2 || l.SuccessCount != 1 || l.FailCount != 1 { + t.Fatalf("跨天边界泄漏(应只含今天): %+v", l) + } + if !feq(l.FeeTotal, 4.0) { + t.Fatalf("fee_total=%v 期望 4.0", l.FeeTotal) + } +} + +func TestAggregateDay_StateMigration(t *testing.T) { + // 滚动重刷核心语义:72h 回执窗内 UNKNOWN→成功迁移后,重跑即覆盖收敛。 + db := newConsumeDB(t) + now := time.Now() + if err := db.Create(&[]entity.MessageDetail{ + mkDetail(1, 1, 1, "sms", 4, 1.0, now), // 先 UNKNOWN + }).Error; err != nil { + t.Fatal(err) + } + svc := NewService(db) + if _, _, err := svc.AggregateDay(context.Background(), now); err != nil { + t.Fatal(err) + } + var l entity.BillingConsumeLog + db.First(&l) + if l.UnknownCount != 1 || l.SuccessCount != 0 { + t.Fatalf("首跑应 unknown=1: %+v", l) + } + // 回执到达:状态迁移为成功,重刷收敛。 + if err := db.Model(&entity.MessageDetail{}).Where("id = ?", int64(1)). + Update("status", 2).Error; err != nil { + t.Fatal(err) + } + if _, _, err := svc.AggregateDay(context.Background(), now); err != nil { + t.Fatal(err) + } + db.First(&l) + if l.UnknownCount != 0 || l.SuccessCount != 1 { + t.Fatalf("重刷后应 success=1/unknown=0: %+v", l) + } +} + +func TestListConsume_Filters(t *testing.T) { + db := newConsumeDB(t) + now := time.Now() + if err := db.Create(&[]entity.BillingConsumeLog{ + {AccountID: 1, Business: "sms", StatDate: now, SubmitCount: 5, SuccessCount: 5}, + {AccountID: 1, Business: "video", StatDate: now, SubmitCount: 1, SuccessCount: 1}, + {AccountID: 100, Business: "sms", StatDate: now.AddDate(0, 0, -3), SubmitCount: 2, SuccessCount: 2}, + {AccountID: 100, Business: "sms", StatDate: now.AddDate(0, 0, -10), SubmitCount: 9, SuccessCount: 9}, + }).Error; err != nil { + t.Fatal(err) + } + svc := NewService(db) + // 全量(默认排序 stat_date DESC)。 + list, total, err := svc.ListConsume(context.Background(), ConsumeQuery{}) + if err != nil || total != 4 || len(list) != 4 { + t.Fatalf("全量 total=%d len=%d err=%v", total, len(list), err) + } + // 账号过滤。 + _, total, err = svc.ListConsume(context.Background(), ConsumeQuery{AccountID: 1}) + if err != nil || total != 2 { + t.Fatalf("账号过滤 total=%d err=%v", total, err) + } + // 业务过滤。 + _, total, err = svc.ListConsume(context.Background(), ConsumeQuery{Business: "video"}) + if err != nil || total != 1 { + t.Fatalf("业务过滤 total=%d err=%v", total, err) + } + // 时间窗(近 7 天闭区间:今 2 行+3 天前 1 行;零点归一语义)。 + _, total, err = svc.ListConsume(context.Background(), ConsumeQuery{ + From: now.AddDate(0, 0, -6), To: now, + }) + if err != nil || total != 3 { + t.Fatalf("时间窗 total=%d err=%v(期望 3)", total, err) + } + // 分页。 + list, total, err = svc.ListConsume(context.Background(), ConsumeQuery{Page: 2, PageSize: 3}) + if err != nil || total != 4 || len(list) != 1 { + t.Fatalf("分页 total=%d len=%d err=%v", total, len(list), err) + } +} diff --git a/internal/service/settle/job.go b/internal/service/settle/job.go new file mode 100644 index 00000000..2159ac4f --- /dev/null +++ b/internal/service/settle/job.go @@ -0,0 +1,65 @@ +// job.go S2-D2:消耗日汇总后台 job(照 StartStatsRefresher 幂等模式;仅 gateway +// 装配调用,测试/迁移工具不启)。 +// +// 滚动重刷模型(D2 对 D1 计划的修正,理由见 consume.go 头注):启动回补 +// BackfillDays 天(不阻塞启动)→ 周期 RefreshEvery 重刷近 RefreshDays 天 +// (默认 4 天=72h 回执窗+当天增量,UNKNOWN 状态迁移靠重刷收敛)。幂等 +// UPSERT——多实例/重复跑无害;失败 Warn 不中断,下轮自愈。 +package settle + +import ( + "context" + "time" + + "go.uber.org/zap" + "gorm.io/gorm" + + "go-sms/internal/pkg/metrics" +) + +// StartAggregateJob 启动消耗日汇总 job(goroutine 内自兜底配置零值; +// cfg 三参<=0 时分别取 1h / 4 天 / 7 天,见 config.Settle 注释)。 +func StartAggregateJob(db *gorm.DB, refreshEvery time.Duration, refreshDays, backfillDays int, log *zap.Logger) { + if refreshEvery <= 0 { + refreshEvery = time.Hour + } + if refreshDays <= 0 { + refreshDays = 4 + } + if backfillDays <= 0 { + backfillDays = 7 + } + svc := NewService(db) + go func() { + for i := backfillDays - 1; i >= 0; i-- { + aggregateOneDay(svc, time.Now().AddDate(0, 0, -i), log) + } + if log != nil { + log.Info("settle_backfill_done", zap.Int("days", backfillDays)) + } + ticker := time.NewTicker(refreshEvery) + defer ticker.Stop() + for range ticker.C { + now := time.Now() + for i := refreshDays - 1; i >= 0; i-- { + aggregateOneDay(svc, now.AddDate(0, 0, -i), log) + } + } + }() +} + +// aggregateOneDay 单日落账 + 指标埋点(失败不返回错误——job 壳内消化, +// 错误计数器持续增长即真故障信号,runbook 口径)。 +func aggregateOneDay(svc *Service, day time.Time, log *zap.Logger) { + accountRows, channelRows, err := svc.AggregateDay(context.Background(), day) + if err != nil { + metrics.SettleAggregateErrors.Inc() + if log != nil { + log.Warn("settle_aggregate_failed", + zap.String("day", day.Format("2006-01-02")), zap.Error(err)) + } + return + } + metrics.SettleAggregateRows.WithLabelValues("account").Add(float64(accountRows)) + metrics.SettleAggregateRows.WithLabelValues("channel").Add(float64(channelRows)) +} diff --git a/memory-bank/activeContext.md b/memory-bank/activeContext.md index c4fbd347..8b294f79 100644 --- a/memory-bank/activeContext.md +++ b/memory-bank/activeContext.md @@ -1,12 +1,12 @@ # 当前工作上下文(最近更新:2026-11-14) -## 当前状态快照(2026-11-14 上午,**S2-D1 收官**) +## 当前状态快照(2026-11-14 傍晚,**S2-D2 收官**) -- **仓库**:main 已推 Gitea(origin=192.168.5.27:24401/Tory/go-sms-V2);S1 全程 28 提交+S3 前置;每日 bundle+push 双轨。 -- **S2 结算域已开工(D 层,5 工作日,出口=结算单测+对账差异 0)**:D1 ✅=六项表设计裁决定稿(`docs/review/s2-settle-table-review.md`)+迁移 **v20_settle_domain**(billing_consume_log 补列/stats_user_daily DROP/settle_ladder 建表/rebate_rate/casbin settle 策略;dev 库 v19→v20 实跑+五项 information_schema 核验过)+**openapi v1.3.0**(+20 结算端点);门禁全绿(vet/-race 38 包/lint 0/迁移单测/集成 AutoMigrate 39 表+Casbin)。验收单 `docs/acceptance/s2-d1.md`。 -- **六项裁决速查**:R1 出账时刻计价(明细 Fee=片数不动,send 域零改动;金额=Σ日成功条数×生效单价,时间线+阶梯在 D4 settle/price.go 单点推导)/R2 消耗事实源=billing_consume_log(账号×业务×天)+stats_channel_daily(通道×天)/R3 充值双通道/R4 rebate_rate 单级返点历史不重算/R5 settle_ladder(owner×tier_from)/R6 条/元换算只在出账引擎。 -- **下一步=S2-D2 消耗日汇总引擎**(整域地基:明细热窗 5 天→月结必须走日汇总):settle/consume.go+job.go(照 StartStatsRefresher 幂等模式,cronx T+1 01:05+回补 7 天)+/billing/consume+/ops/settle/aggregate+Settle 配置段+job 指标;随后 D3 充值审核流/D4 出账+阶梯/D5 利润返点+三方对账。 -- **在途**:~~24h 稳定性门槛~~ → **✅ 终判通过(2026-11-14 18:02 期满核验三项全绿:dmesg 崩溃 0/九容器零重启/gateway 驻留+md5 一致;S5 压测基线前置资格确认,S1 完全闭环)**。 +- **仓库**:main 已推 Gitea(origin=192.168.5.27:24401/Tory/go-sms-V2);每日 bundle+push 双轨。 +- **S2 进度 2/5**:D1 ✅(表设计六裁决+v20+openapi v1.3.0)/ **D2 ✅(消耗日汇总引擎)**——settle/consume.go+job.go+两端点;**滚动重刷模型**(1h 重刷近 4 天,修正单日 T+1 的 72h UNKNOWN 迁移失真;月结建议 T+4 后生成);-race 39 包/lint 0/真 MySQL 端到端+收敛实证(success 1→2/unknown 1→0);gateway 已驻新二进制(md5 一致)。 +- **24h 稳定性门槛 ✅ 终判通过**(18:02 三项全绿;S1 完全闭环,S5 压测前置确认)。 +- **六项裁决速查**:R1 出账时刻计价(明细 Fee=片数不动,send 域零改动;金额=Σ日成功条数×生效单价,时间线+阶梯在 D4 settle/price.go 单点推导)/R2 消耗事实源=billing_consume_log(账号×业务×天)+stats_channel_daily(通道×天,已由 D2 job 落账)/R3 充值双通道/R4 rebate_rate 单级返点历史不重算/R5 settle_ladder(owner×tier_from)/R6 条/元换算只在出账引擎。 +- **下一步=S2-D3 充值审核流**:settle/recharge.go+`/billing/orders` 族四端点(创建 pay_status=0 不动余额/confirm=状态 CAS+余额自增 count+流水 ref_id=order_no 同事务/驳回/列表);R3 双通道语义(即时充值保留);并发 confirm -race 只入账一次为验收点。随后 D4 出账+阶梯(显式验收:阶梯结算单测)/D5 利润返点+三方对账(S2 出口 diff=0)。 - 归档仓(只读):/data/poc-archive/repos/go-sms.git(poc-final=5e09a4cc)。 - **本会话运维教训**:①`pkill/pgrep -f` 自匹配(铁律:`[x]` 括号技巧);②大镜像单窗>体积÷带宽;③du 无 sudo 静默失败误诊;④sed 换行/sed 误伤方法名(重构期优先编辑器工具);⑤Go 工具忽略 `_` 前缀文件;⑥集成测试需 `sg docker` 包裹(docker 组未重登);⑦**Makefile recipe 的 `exit 0` 只退出当前行 shell 不终止目标**(幂等短路须 if/else 递归 `$(MAKE)` 子目标);⑧**管道 `| tail -N` 截首行误导诊断**(gw-start"玄学 NOMATCH"两轮误诊实为 THEN 分支已生效,排查须看全量输出)。 diff --git a/memory-bank/progress.md b/memory-bank/progress.md index b8d79b47..25ffa133 100644 --- a/memory-bank/progress.md +++ b/memory-bank/progress.md @@ -12,7 +12,8 @@ | S1-B B 层搬运 P1 | 12 域+双入口全落位(两阶段等价法);channel P2 拆 pool 完成;lint 27→0;全仓 -race 36 包绿 | ✅ 2026-11-13 | | S1-B 收尾项 | send P2 拆三子包(0550f2a,facade 门面)/dayNN 19 文件改名/storage 归一/文案校准/gofmt 清零 | ✅ 2026-11-13 夜(**S1 泳道收官**) | | S2-D1 表设计+v20+契约 | 六项裁决(R1 出账时刻计价/R2 事实源统一/R3 充值双通道/R4 返点/R5 阶梯表/R6 口径)+v20_settle_domain+openapi v1.3.0(+20 端点)+dev 库实跑 v20 | ✅ 2026-11-14(评审纪要 docs/review/s2-settle-table-review.md;验收单 s2-d1.md) | -| S2-D2~D5 | D2 消耗日汇总引擎(整域地基)/D3 充值审核流/D4 出账+阶梯(显式验收:阶梯结算单测)/D5 利润返点+三方对账(diff=0=S2 出口) | ⬜ 排期中 | +| S2-D2 消耗日汇总引擎 | settle/consume.go+job.go(**滚动重刷模型**:1h 重刷近 4 天,修正单日 T+1 的 72h 失真)+两端点+config/metrics/装配;sqlite 6 测试;真 MySQL 端到端+收敛实证 | ✅ 2026-11-14 傍晚(验收单 s2-d2.md) | +| S2-D3~D5 | D3 充值审核流/D4 出账+阶梯(显式验收:阶梯结算单测)/D5 利润返点+三方对账(diff=0=S2 出口) | ⬜ 排期中 | | 观察项 | 24h 稳定性门槛(11-13 17:55 起计;期内 21:33 宿主主动重启=已知事件不判失败)期满核验 11-14 17:55 | ✅ 2026-11-14 18:02 终判通过(dmesg 0/零重启/驻留+md5 一致;S5 压测前置确认,S1 完全闭环) | | S2~S5 | 结算域/前端收尾/C1C2+冷热/基线与灰度 | ⬜ 见《Go-sms-重建计划.md》 |