# 系统架构与技术模式 ## 服务拓扑(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 定位入口)。