Files
go-sms-V2/memory-bank/systemPatterns.md
T

5.4 KiB

系统架构与技术模式

服务拓扑(cmd/ 下多入口,共享 internal/)

服务 入口 职责
gateway cmd/gateway 主服务:HTTP API(:8081 dev)+ CMPP Server(下家接入)+ Web 静态代理;含长短信聚合/挂起维护(reaper)、调度唤醒扫描
consumer cmd/consumer Kafka 消费:Deferred 事件补全(拦截/落库/审核/路由/分发)、回执(report)消费配对
scheduler cmd/scheduler 定时任务调度(与 gateway 的 5s ZSet 扫描协同)
business cmd/business 业务服务(独立部署形态)
migrate cmd/migrate 迁移执行器(gormigrate v1~v19;seed-admin 引导超管,密码仅打印一次)
reconcile cmd/reconcile 对账补偿
探针/工具 authprobe cmppbench longsmsprobe probe smppsmoke 真机验收探针(验收后多数即删,如 probe_longsms)

分层架构(internal/)

internal/
├── api/http/v1/     # HTTP handler(REST /api/v1/*;命名 <域>_handler.go + <域>_dayNN_test.go)
├── app/             # 应用装配骨架
├── config/          # 配置结构体;viper 加载,GOSMS_ 前缀环境变量覆盖
├── middleware/      # gin 中间件(鉴权/限流含动态账号桶/审计/CORS…)
├── model/entity/    # GORM 实体(雪花主键 SnowflakeModel 公共结构)
├── pkg/             # 内部共享:logger(zap)/metrics(prometheus)/queue(Kafka producer)/cache(freecache)/lock
├── protocol/        # 协议实现:cmpp(客户端+服务端+池)/smpp/sgip/httpadapter
├── repository/      # 数据访问(mysql;migrations.go 集中迁移定义 v1~v19)
├── router/          # 四步路由引擎(账号级 steer 绑定快照)
├── service/         # 业务域:access(cmpp 接入+长短信聚合)/account/audit/auth/balance/channel/interceptor/openapi/report/router/send/template/uplink
└── util/            # SmsLength/SmsLengthUCS2 计费口径等纯函数

核心数据流

下行主链(受理→下发→回执)

  1. 受理快路径 send.SubmitFast(Day 63):Validate(内存)→ holdFastLua Redis 哨兵预扣(欠费=唯一同步拒)→ DetailID 雪花预生成 → EmitSubmit 投 Deferred Kafka 事件(task.ID=0,零 DB 写)。
  2. 消费侧补全 send/consumer.handleDeferred:拦截链判定(命中→明细终态 5+退费)→ task INSERT 补建(uk_task_no 冲突=重投,已分流 audit≠0 跳过 Route)→ 明细落库+拦截回执桥 → 全拦任务终态 → 审核 Route → claim/dispatch。
  3. 下发:ChannelDispatcher(router 选路)→ protocol/cmpp 池连接 SubmitViaLink 真链路;MsgID 口径=DetailID 雪花(与回执 Deliver msg_id 同口径)。
  4. 回执 report 域:Kafka 消费回执 → pair(配对)→ 明细终态 → 退费/统计;UNKNOWN 挂起窗 72h;compensator 补偿。

入向长短信(Day 71 挂起制,当前语义)

  • 片聚合:组 ID=首片雪花,N 片 Resp 复用;完整性优先——72h 窗内不齐=不提交/不推终态/不扣费;到期不齐=reaper 建失败终态(task LP+组ID uk 幂等/detail id=组ID status=3 fee=0 LSM:NOTCMPL)+UNDELIV 经 Kafka cmpp-deliver 回环推下家。
  • 持久化:迁移 v19 longsms_pending 表(一行一未齐组,首片 INSERT/续片 UPDATE/到齐 DELETE);启动 restore 回内存;reaper 1min 扫描每轮≤500 行;组上限 16384 超限拒绝。

计费口径(Day 70 根修)

  • fee≡上游真实拆分片数;分流优先级 FeeSegments>0 直接采信 > UCS2 编码按 SmsLengthUCS2 > 默认 SmsLength(GBK);CMPP MsgFmt 透传至受理计费点。

关键技术模式

  • 幂等三锚:task_no uk / detail pk(雪花) / OnConflict DoNothing——重复扫描、重投、并发路径至多一次生效。
  • 雪花生成的 MsgID/DetailID 全链统一,回执配对键跨重启一致。
  • 每分区 worker 池(Day 65):WorkersPerPartition+连续前缀有序 Mark,at-least-once 等价;done 容量≥2w+2。
  • 延迟关联三段式查询(Day 64):窄 Count → 窄列分页 Pluck id → id IN 回表全宽 JOIN(明细页 82s→645ms);无 start_time 缺省 5 天窗。
  • 配置注入:SystemLimits(grouper.window 等)注入 service 构造函数,测试可直接调;config.dev.yaml 默认,环境变量 GOSMS_(层级 _ 连接)覆盖任意键。
  • 迁移:gormigrate 集中于 repository/mysql/migrations.go(末块 v19);不走 entity tag 加索引(SnowflakeModel 公共结构避免波及全部雪花表)。
  • 降级策略:DB 写失败 Warn 降级继续内存聚合;Redis 故障 DB 直查降级;producer 降级时 push=nil 只落失败记录。
  • 前端模式:Vue3 setup + pinia + vue-router;msw Mock/real 双模式(VITE_API_MODE,.env.development.local gitignore 持久化 real);样式三件套 tokens/ep-theme/shell(token 化禁原子类);ProTable 组件(骨架/空态/密度/列显隐/分页)。
  • 测试模式:单测用 sqlite(glebarez)或 miniredis;<域>_dayNN_test.go 按验收日命名;集成测试 go test -tags=integration ./test/integration/...(真实中间件);e2e Playwright(web/tests)。

命名与代码约定

  • 后端 handler:internal/api/http/v1/<域>_handler.go;错误码 ISC-xxx(ISC_CN 字典前端 tooltip)。
  • 前端视图:web/src/views/<域>/<页>/index.vue;语义类前缀(sc-/rec-/audit-/ce- 等)替代原子类;tailwind 已移除。
  • 日志:结构化字段(如 cmpp_longsms_expire_fail/cmpp_deliver_pushed),trace_id 贯穿(runbook SOP 定位入口)。