From 2a6a66fbd39ef657ca9827b9130a5da9c2602e58 Mon Sep 17 00:00:00 2001 From: Tory Date: Fri, 13 Nov 2026 15:14:59 +0800 Subject: [PATCH] =?UTF-8?q?=E5=9C=B0=E5=9F=BA:=20=E4=BB=93=E5=BA=93?= =?UTF-8?q?=E5=88=9D=E5=A7=8B=E5=8C=96=E2=80=94=E2=80=94memory-bank=20?= =?UTF-8?q?=E5=85=A8=E6=96=87=E5=BA=93(=E5=85=AD=E6=A0=B8=E5=BF=83+docs)+.?= =?UTF-8?q?clinerules+README+.gitignore(=E8=87=AA=20poc-final=205e09a4cc)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .clinerules/memory-bank.md | 35 + .gitignore | 38 + README.md | 6 + memory-bank/activeContext.md | 55 + memory-bank/docs/Go-sms-前端开发计划.md | 155 +++ memory-bank/docs/Go-sms-实施计划.md | 423 +++++++ memory-bank/docs/Go-sms-开发日历.md | 347 ++++++ memory-bank/docs/Go-sms-开发计划.md | 212 ++++ memory-bank/docs/Go-sms-技术方案.md | 1350 +++++++++++++++++++++++ memory-bank/docs/Go-sms-重建搬运清单.md | 46 + memory-bank/docs/Go-sms-重建计划.md | 43 + memory-bank/docs/Go-sms-重建设计规范.md | 45 + memory-bank/docs/Go-sms-需求分析.md | 323 ++++++ memory-bank/productContext.md | 31 + memory-bank/progress.md | 54 + memory-bank/projectbrief.md | 42 + memory-bank/systemPatterns.md | 63 ++ memory-bank/techContext.md | 106 ++ 18 files changed, 3374 insertions(+) create mode 100644 .clinerules/memory-bank.md create mode 100644 .gitignore create mode 100644 README.md create mode 100644 memory-bank/activeContext.md create mode 100644 memory-bank/docs/Go-sms-前端开发计划.md create mode 100644 memory-bank/docs/Go-sms-实施计划.md create mode 100644 memory-bank/docs/Go-sms-开发日历.md create mode 100644 memory-bank/docs/Go-sms-开发计划.md create mode 100644 memory-bank/docs/Go-sms-技术方案.md create mode 100644 memory-bank/docs/Go-sms-重建搬运清单.md create mode 100644 memory-bank/docs/Go-sms-重建计划.md create mode 100644 memory-bank/docs/Go-sms-重建设计规范.md create mode 100644 memory-bank/docs/Go-sms-需求分析.md create mode 100644 memory-bank/productContext.md create mode 100644 memory-bank/progress.md create mode 100644 memory-bank/projectbrief.md create mode 100644 memory-bank/systemPatterns.md create mode 100644 memory-bank/techContext.md diff --git a/.clinerules/memory-bank.md b/.clinerules/memory-bank.md new file mode 100644 index 00000000..30d5729d --- /dev/null +++ b/.clinerules/memory-bank.md @@ -0,0 +1,35 @@ +# Memory Bank(记忆库) + +> 本文件为记忆库索引。每次会话开始时按以下顺序阅读记忆库文件,获取项目上下文。 + +## 核心文件(按需阅读,projectbrief 必读) + +| 顺序 | 文件 | 用途 | +|---|---|---| +| 1 | `memory-bank/projectbrief.md` | 项目简报:定位/目标/关键文档索引(必读) | +| 2 | `memory-bank/activeContext.md` | **当前工作焦点**(每次会话必读,变更最频繁) | +| 3 | `memory-bank/progress.md` | 进度状态:阶段总览/待办池/遗留问题 | +| 4 | `memory-bank/systemPatterns.md` | 系统架构与服务/数据流/代码模式 | +| 5 | `memory-bank/techContext.md` | 技术栈/命令/环境变量/部署铁律 | +| 6 | `memory-bank/productContext.md` | 产品背景:用户/角色/体验目标 | + +## 维护规则 + +- **activeContext.md 与 progress.md**:每个工作日/每项任务完成时更新(当前状态快照、下一步、决策记录)。 +- **其余四文件**:仅在架构/技术栈/需求发生实质变化时更新。 +- 进度事实源仍为《memory-bank/docs/Go-sms-开发日历.md》+ `CHANGELOG.md`——记忆库是其摘要与导航,更新时须与二者对账。 + +## 项目速览(一行版) + +Go-sms:汇网短信运营平台 Go 重建(上游通道↔路由/合规/计费/审核↔下家 CMPP/SMPP/HTTP/Web);Go1.25+gin+gorm+Kafka+Redis / Vue3+EP;80 工作日计划推进至 Day 71(2026-09-29);质量门七件套;分支 rebuild-ui。 + + + +## 附:全文文档库(memory-bank/docs/,2026-11-12 自仓库根目录归拢) + +| 文档 | 状态 | +|---|---| +| Go-sms-需求分析.md / Go-sms-技术方案.md | ✅ 重建基线(横幅标注口径) | +| Go-sms-重建计划.md / 重建搬运清单.md / 重建设计规范.md | 🔄 重建三文档(生效) | +| Go-sms-开发日历.md | 🔒 POC 进度事实源(Day71 定稿) | +| Go-sms-实施计划.md / 开发计划.md / 前端开发计划.md | ⛔ 已废止,历史归档 | diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..71f27d5e --- /dev/null +++ b/.gitignore @@ -0,0 +1,38 @@ +# ---- 构建产物 ---- +bin/ +dist/ +*.exe +*.test +*.out +coverage.out +coverage.html + +# ---- 依赖 ---- +vendor/ + +# ---- IDE / 编辑器 ---- +.idea/ +.vscode/* +!.vscode/settings.json +*.swp +*.swo + +# ---- 系统文件 ---- +.DS_Store +Thumbs.db + +# ---- 本地环境(不入库) ---- +*.local.yaml +.env + +# ---- 日志 ---- +*.log +logs/ + +# 前端(web/) +node_modules/ +web/node_modules/ +web/.vite/ +web/dist/ +web/*.local +frontend/ diff --git a/README.md b/README.md new file mode 100644 index 00000000..fc8b7a0a --- /dev/null +++ b/README.md @@ -0,0 +1,6 @@ +# go-sms-v2(重建主仓) + +> 2026-11-13 创建。POC 归档库(只读参考):/data/poc-archive/repos/go-sms.git(tag poc-final=5e09a4cc) +> - 一期口径:核心先行(P0+P1+结算域+压测灰度)—— 重建计划/搬运清单/设计规范见 memory-bank/docs/ +> - S1 首动作:git init 新历史 + A 层资产搬运(协议四栈/pkg/middleware/util/openapi/迁移链/监控/工具)+ docker/Go 安装与编译循环终验 +> - 环境注意:CPU 画像=编译禁 -march=native(VEX 即 SIGILL;Go 无影响) diff --git a/memory-bank/activeContext.md b/memory-bank/activeContext.md new file mode 100644 index 00000000..8fc04004 --- /dev/null +++ b/memory-bank/activeContext.md @@ -0,0 +1,55 @@ +# 当前工作上下文(最近更新:2026-11-12) + +## 当前状态快照 + +- **分支**:`rebuild-ui`;工作树干净(Day 67-71 已全部入 git)。 +- **最近提交**:80d067e5(2026-09-29)Day67-71 补账——入向长短信全链路/计费根修+清偿/72h 挂起制+明细单表化+运营总览后端,62 文件 +3177/−213(含 CHANGELOG 条目归位/验收单 day67~71/日历回填/aggregator -race 补修)。 +- **已完成日**:开发日推进至 **Day 71**(2026-09-29);前端 UI 重构 W1-W6 全收官(独立于日历编号)。 +- **质量基线**(2026-09-29 补账门禁实测):后端 build+vet+`go test -race -cover` **35 包全绿**(修 aggregator 计数器竞态后);前端 lint 0 / vue-tsc 0 / vitest 138 / build ✓ / verify-layout 18/18。 +- **项目定性变更(2026-11-12 用户裁决)**:本项目为**测试可用性(POC)**,使命完成,决定**全部重建**——新 SSD 环境(121.46.230.53)+ 新仓 `go-sms-v2`;本仓冻结为归档(tag `poc-final`,全量 bundle 交付摆渡)。 +- **重建环境三项裁决(2026-11-12)**:①开发形态=本地 VS Code + Remote-SSH(服务器只跑 vscode-server,Cline 在 server 端);②服务器重装纯命令行 Debian 13(xrdp/Xfce/VS Code GUI 弃用);③不装 Gitea——服务器本地仓为中心,备份=定期 bundle 拉回本地。 +- **新机 S0 就绪(2026-11-13)**:debian13-smsDev(1822/user 免密 + sudo NOPASSWD + DNS ✓);磁盘=顺序 662MB/s + **4K 随机读 76.3k IOPS**(HDD 500 倍级);CPU 画像=CPUID 无 AVX + VEX 执行即 SIGILL(dispatch 类免疫/编译禁 -march=native,Go 无影响);fio/git/curl 就位,归档仓 mirror 落位 /data/poc-archive/repos/go-sms.git;**用户连 Remote-SSH 即开 S1**(docker/Go 安装+编译循环终验为 S1 首动作)。 + +## 重建启动(2026-11-12 裁决 / 盘点 / 迁移方案) + +- **盘点结论(A/B/C/D 四层)**:A 直接保留=协议四栈(cmpp/smpp/sgip/httpadapter)+pkg 标准件+计费纯函数(util)+middleware+openapi.yaml+监控三件+运维资产+v1~v19 迁移链终态 DDL;B 改造保留=send 主链(13 文件拆包/去 dayNN 命名)/access 长短信(72h 挂起制最终语义)/report(补 C1 回调推送)/router(空壳目录归位)/channel/account/balance/interceptor/前端整包(31 页+三件套样式+ProTable,FE-6 收尾);C 结论保留=明细单表化+按页相关子查询(禁 JOIN 计数)/幂等三锚/MsgID=DetailID 雪花全链/削峰(受理-下发解耦)/部署串行铁律/-race 全量门禁;D 新做=结算域(0%)/C1 回调引擎+C2 拉黑/ClickHouse 冷热/通知域/明细按天分区热 5 天。 +- **迁移方式**:git bundle 摆渡(老 IPv6 ↔ 新 IPv4 仅 FC 慢速中转;一次性 ~35M;node_modules/bin/logs 全不迁)。新机依赖大头=Docker 镜像(3-5G)+Go mod cache+pnpm store+Playwright(共 5-8G),按外网连通性决定下载/介质摆渡;vscode-server 首装亦需出网(update.code.visualstudio.com),不通则按 commit hash 离线装。 +- **CPU 缺陷对策(实体机约束,不可换宿主/微码)**:纯 CLI 影响非零(压测基线可信度>编译偶发>Node);缓解=GLIBC_TUNABLES 关 AVX 派发+开荒第一步 stress-ng(avx2/memcpy)+20 轮编译循环实测复现率(≈0 接受/频发建议换整机)+压测基线前置 24h 稳定性门槛。 +- **SSD 基线重标定(重建首个性能工作项)**:workers:4/消费顶 55/s 是 HDD 数字不可沿用;buffer_pool 16-24G/io_capacity 2000/10000/Kafka flush 放宽;就绪验收=七件套全绿+watch_1m.sh --once 首份 SSD 基线快照。 + +## 刚完成(2026-11-12:服务器 121.46.230.53 VS Code「必须 --no-sandbox」排查 ✅,环境运维非开发日) + +根因=**宿主 CPU 指令执行缺陷**(dmesg 实锤:code 确定性 SEGV `error 25` 跨 socket 0/4/8/12 + extensionHost SIGILL + evolution-alarm libatomic invalid opcode 系统级旁证;Xeon 8173M 虚拟化 AVX 全掩/BMI1-2 保留),软件侧无根治;AppArmor userns profile / SUID chrome-sandbox / `--disable-gpu` / `FC_FONTATIONS=0` 逐一实测排除。**实测裸 `code`(无 --no-sandbox)可正常打开**(真实配置冷启动,renderer 闪崩 1 次后自动 reload;`--no-sandbox` 下同样偶崩=沙箱开关非决定因素)。已做变更仅 `/etc/apparmor.d/code` 幂等重载;测试进程与 /tmp 残留已清。遗留:报云厂商换宿主/升级微码。详见 techContext「远程服务器」小节。 + +## 刚完成(2026-09-29:Day67-71 补账提交 80d067e5) + +报障驱动五日(09-28~29)全部入 git 并完成文档对账(CHANGELOG 五条目归档+验收单 day67~71 补账归档+日历 Day67-71 状态列回填);提交门禁补修 `internal/service/send/aggregator.go` 三计数器数据竞争(-race 必现的 Day 47 遗留,int64 裸写→`atomic.Int64`)——教训:**门禁必须 -race 全量,裸跑 go test 掩盖竞争**。事故工具 `cmd/reconcile/refund_lost`(宿主机休眠丢件对账退款)一并留档。 + +## 下一步(重建,2026-11-12 起) + +- **老环境侧(本提交)**:归档三件套=bench 入档+poc-final tag+全量 bundle(/data/go-sms-poc.bundle);老 Gitea 推送 develop(快进 2)+rebuild-ui(首推 11 提交,W1-W6+Day67-71+memory-bank 此前仅存本地);main 不动。 +- **新环境侧(121.46.230.53,重装纯 CLI Debian 13 后)**:SSH 加固(仅密钥/fail2ban)/NTP/Docker → 开荒第一步 stress-ng+编译循环实测 CPU 复现率 → 本地 VS Code+Remote-SSH+Cline → bundle 过桥 → clone 本地归档仓 /data/poc-archive + git init /data/go-sms-v2(A 层搬运)→ compose 七中间件(SSD 参数基线)→ 七件套复跑 → watch_1m.sh --once SSD 首份基线快照(前置 24h 稳定性门槛)。 +- 原「阶段 6/7 重排三选一」裁决已被全部重建取代;日历 Day72-80 原计划转入重建造价。 +- 观察项(随重建转移):16384 长短信组上限(watchdog expf);LP/LSM:NOTCMPL 文案映射待运营反馈。 + +## 活跃的架构决策记录(近期) + +| 决策 | 内容 | +|---|---| +| 长短信语义(Day 71) | 完整性优先:72h 不齐=失败终态(LSM:NOTCMPL/零费/UNDELIV),废除「超时退化逐片直发」 | +| 计费口径(Day 70) | fee≡上游真实拆分片数;`FeeSegments>0`(客户端 pk_total=运营商计费依据)优先于重算 | +| MsgID 口径(Day 63) | CMPP Submit_Resp MsgID=DetailID 雪花,与回执同口径 | +| 消费并发(Day 65) | 每分区 worker 池(workers:4,HDD 顶 55/s);生产换 SSD 是解锁项 | +| UNKNOWN 终态(Day 69/71) | 出向回执挂起 72h 后保持 UNKNOWN(部分段事实送达,不标失败) | + +## 常踩的坑(防复发) + +1. `.env.development.local`(gitignore)会把 vite 钉在 real 模式——切 mock 前必查。 +2. build 与 kill 并行=旧 inode 进程(Day 70);部署必须串行+md5 比对。 +3. 持久化-还原键字段必须成对审计(Day 71 ref 字段漏存教训)。 +4. 迁移版本号字典序坑(v10 **【文档状态】⛔ 已废止**(FE-1~FE-5 + UI 重构 W1-W6 已完成;FE-6 未竟部分转入《Go-sms-重建计划.md》一期) + +> 编制日期:2026-09-03 · 依据:《需求分析》(18 模块/94 页面,P0~P2 分级)、《技术方案》(前端栈空缺,本计划补齐)、《实施计划》(阶段 0-7)、《开发计划》(前端 2 人,阶段 2~6) +> 配置:前端工程师 2 名(FE-A 主架构/权限/业务流;FE-B 组件库/列表页/图表),共 40 个工作日 × 2 人,与后端 Day 21-70 窗口并行 +> 代码位置:本仓库 `web/` 子目录(monorepo,共享 CI 与 CHANGELOG) + +--- + +## 一、现状与依据分析 + +### 1.1 后端进度(硬依赖) + +| 后端阶段 | 状态 | 提供的前端依赖 | +|---|---|---| +| 阶段 0 环境与 CI(Day 1-10) | ✅ 完成 | make up 中间件、CI 流水线、/health、/metrics | +| 阶段 1 数据模型与组件(Day 11-20) | ✅ 完成 | 36 表模型、ISC:xxx 错误码、统一响应 {code,msg,data}、JWT、Casbin RBAC、迁移工具 | +| 阶段 2 账号与权限(Day 21-30) | 🔜 当前 | 登录/账号 CRUD/配置/充值/角色权限 API | +| 阶段 3 通道与路由(Day 31-40) | 待开始 | 通道/上家/通道组/策略 API | +| 阶段 4 消息发送(Day 41-50) | 待开始 | 发送/模板/审核 API | +| 阶段 5 回执与记录(Day 51-60) | 待开始 | 记录查询/回执/上行 API | +| 阶段 6 统计结算(Day 61-70) | 待开始 | 统计/结算/工作台 API | + +### 1.2 关键决策 + +1. **技术栈**(补齐技术方案空缺):Vue 3.4+ / TypeScript 5 / Vite 5 / Element Plus 2.x / Pinia / Vue Router 4 / Axios / ECharts 5 / Vitest + Playwright。理由:管理后台表格表单生态最成熟、团队招聘与上手成本最低、ECharts 对齐开发计划 Day 63 的既有表述。 +2. **契约先行 + Mock 并行**:后端 API 未就绪前,前端依据 `api/openapi.yaml`(后端 Day 30 交付物)或本地 Mock(msw/json-server)开发,后端阶段验收周切换联调,**前端永不被后端阻塞**。 +3. **P0→P1 优先,业务线 P2 后置**:视频/CSP/空号/短链四条增值业务线(需求文档已建议后置)不占本期 40 天,列入迭代二。 +4. **统一对接既有规范**:请求层对接后端统一响应 `{code,msg,data}` 与 `ISC:xxx` 错误码(401→登录页/403→提示/500→人工核查提示),trace_id 透传 `X-Trace-Id`。 + +--- + +## 二、总体节奏:六个前端阶段(对齐后端) + +| 前端阶段 | 工作日 | 对齐后端 | 主题 | 页面覆盖(需求模块) | +|---|---|---|---|---| +| FE-0 工程与骨架 | Day 1-5 | 阶段 2 前半 | 脚手架/布局/登录鉴权 | (全局壳) | +| FE-1 账号与权限 | Day 6-10 | 阶段 2(Day 21-30) | 帐号管理 8 页 | ③帐号管理 | +| FE-2 通道与路由 | Day 11-16 | 阶段 3(Day 31-40) | 通道/策略 12 页 | ⑩通道配置 ⑪规则策略 | +| FE-3 发送与审核 | Day 17-23 | 阶段 4(Day 41-50) | 发送/模板/审核 10 页 | ④业务审核 ⑤短信业务 | +| FE-4 记录与回执 | Day 24-29 | 阶段 5(Day 51-60) | 记录/工具 8 页 | ⑤短信业务(记录)/下载中心 | +| FE-5 统计结算与运营 | Day 30-36 | 阶段 6(Day 61-70) | 图表/结算/配置 12 页 | ①主页 ⑬用户统计 ⑭通道统计 ⑮结算 ⑯日志报表 ⑰系统配置 ⑫通讯录 | +| FE-6 联调加固上线 | Day 37-40 | 阶段 7(Day 71-80) | 全量回归/性能/CI | 全部走查 | + +> 页面合计约 50 页(P0 全量 + P1 主体),P2 业务线(视频/CSP/空号/短链/大屏/主题)为迭代二。 + +--- + +## 三、按天开发明细(产出物 + 验收标准) + +### FE-0 工程与骨架(Day 1-5) + +| 工作日 | 任务(FE-A / FE-B) | 产出物 | 验收标准 | +|---|---|---|---| +| D1 | A:Vite+Vue3+TS 脚手架、ESLint+Prettier+git hooks;B:目录规范(api/components/composables/stores/views/router)、环境变量(.env.dev/.test) | web/ 工程骨架、README | `pnpm i && pnpm dev` 一键起;`pnpm lint` 0 error 0 warning | +| D2 | A:Axios 封装(拦截器:ISC 码分流/token 注入/X-Trace-Id);B:统一响应类型 + Mock 服务(msw) | request.ts、api/types.ts、mocks/ | Mock 登录接口返回 ISC:000;401 拦截跳登录(单测) | +| D3 | A:主布局(侧边栏 18 模块导航/顶栏/面包屑/多标签页);B:主题与全局样式(样式变量/暗色预留) | layouts/、styles/ | 导航与需求模块地图一致;路由与菜单联动刷新不丢标签 | +| D4 | A:登录页(表单校验/验证码占位)+ token 存取;B:Pinia 用户态 + 路由守卫(白名单/重定向) | views/login、stores/user、router/guard | 登录→工作台→登出闭环(Mock);未登录访问任意页重定向 /login | +| D5 | A:动态路由与权限指令 v-permission、按钮级权限;B:错误页(403/404/500 对接 ISC 码) | directive/permission、views/error | 隐藏无权菜单与按钮(Mock admin/customer 两角色实测);阶段走查 FE-0 验收单 | + +### FE-1 账号与权限(Day 6-10,联调后端阶段 2) + +| 工作日 | 任务 | 产出物 | 验收标准 | +|---|---|---|---| +| D6 | 账号列表:搜索(用户名/角色/状态/日期)、分页表格、批量启停/标星;导出(admin) | views/account/list | 与后端 /api/v1/accounts 分页排序联调一致;列 12+;空态/加载态 | +| D7 | 开户表单:多业务线勾选(国内/国际/视频/空号/CSP)、四接入协议、单价时间线、授信/IP 绑定/审核模式 | views/account/create | 分步表单校验(手机号 util 同规则);提交后列表可见(联调) | +| D8 | 账号详情+配置页:基础信息、业务配置矩阵、签名限制、推送地址;切换上级(多级代理) | views/account/detail | 只读/可编辑分区清晰;保存后二次进入回显正确 | +| D9 | 充值与余额:单个/批量充值(二级权限按钮)、余额变动日志、预警设置 | views/account/recharge | 余额变动流水与后端 balance_log 一致;无权限按钮隐藏(v-permission) | +| D10 | 角色权限管理(角色列表/权限树勾选/Casbin 策略展示)、登录审计查询 | views/account/roles、views/audit/login | 权限树勾选→菜单/按钮实时生效;审计表可按账号/IP/日期检索;**FE-1 验收=A-2.x 联调通过** | + +### FE-2 通道与路由(Day 11-16,联调阶段 3) + +| 工作日 | 任务 | 产出物 | 验收标准 | +|---|---|---|---| +| D11 | 上家管理(CRUD/分类/联系人) | views/channel/upstream | CRUD 联调通过;删除二次确认 | +| D12 | 通道列表:协议/状态筛选、启停、连接测试按钮、通道号截断/夜间管控等 20+ 字段 | views/channel/list | 筛选组合联调;测试连接结果 Toast 回显 | +| D13 | 通道新建/编辑:CMPP/HTTP/SGIP/SMPP 参数分区、拦截配置(频次/黑关键字/屏蔽地区)、模板 ID 模式 | views/channel/edit | 四协议表单动态切换;必填校验与后端 ISC:400 对齐提示 | +| D14 | 通道组与四步路由配置器:条件过滤→优先通道(省网/关键字)→权重→兜底,拖拽排序 | views/channel/group | 四步配置保存/回显一致;权重可视化条形展示 | +| D15 | 策略中心:黑白名单(导入导出)、黑白关键字、频次策略、白名单、屏蔽码号 | views/policy/* 5 页 | 各策略 CRUD+批量导入模板下载;命中预演(调后端校验接口) | +| D16 | 导流策略 + 签名/码号报备页;阶段走查 | views/policy/route、views/channel/report | 规则优先级排序正确;**FE-2 验收=A-3.x 联调通过** | + +### FE-3 发送与审核(Day 17-23,联调阶段 4) + +| 工作日 | 任务 | 产出物 | 验收标准 | +|---|---|---|---| +| D17 | 发送工作台-群发:号码输入/文件导入(TXT/CSV/XLSX 预览)、内容输入(计费条数实时展示,规则同后端 util) | views/sms/batch | 文件预览前 50 行;条数/拆分提示与后端 SmsLength 一致 | +| D18 | 个性短信(变量表格编辑)+ 拆分短信;模板选择联动 | views/sms/personal | 变量校验({name} 规则);模板套用预览 | +| D19 | 定时发送(日期时间选择/批量重置)、发送记录摘要卡 | views/sms/timer | 定时任务列表可取消/改期(联调) | +| D20 | 模板管理:列表/报备/批量审核通过拒绝、变量限制提示 | views/sms/template | 模板状态流转(待审/通过/拒绝)实时刷新 | +| D21 | 审核中心:待审聚合(短信/模板/签名/集团/短链 Tab)、批量通过/拒绝(填原因)、48h 超时标红 | views/audit/center | Tab 计数徽标;批量操作后列表与计数联动;超时项样式区分 | +| D22 | 发送结果即时反馈:提交返回 task_no、失败明细(ISC 错误码中文表内嵌)下载 | views/sms/result | ISC 码→中文映射表(内置前端字典与后端 47 码同步) | +| D23 | 短信业务聚合页(发送/记录/模板三入口)+ 移动端适配走查;阶段走查 | views/sms/home | **FE-3 验收=A-4.x 联调:四种发送方式可提交,审核流可闭环** | + +### FE-4 记录与回执(Day 24-29,联调阶段 5) + +| 工作日 | 任务 | 产出物 | 验收标准 | +|---|---|---|---| +| D24 | 下行记录(批次):状态/账号/时间筛选、批次进度(成功/失败/未知占比)、拦截失败号码下载 | views/record/down | 大数据量表格(分页 100/页)流畅;进度条与后端计数一致 | +| D25 | 下行明细(号码级,5 天热数据):CMPP/通道日志钻入、错误码筛选 | views/record/detail | 明细与批次钻取链路正确;ISC 码筛选联调 | +| D26 | 历史记录/明细(全量,>5 天):时间范围查询、异步导出 | views/record/history | 查询响应 <3s(后端 ClickHouse);导出去下载中心 | +| D27 | 上行记录:码号/手机号查询、导出(权限控制) | views/record/uplink | 15 天窗口提示;无权限导出按钮隐藏 | +| D28 | 回执重推工具(选用户+时间窗)与手动配对(四种方式) | views/record/repush | 30 天窗口校验;任务提交反馈;配对结果回写列表 | +| D29 | 下载中心:任务列表/进度/文件下载;定时记录管理;阶段走查 | views/record/download | 异步任务状态轮询;**FE-4 验收=A-5.x 联调:记录四页+两工具可用** | + +### FE-5 统计结算与运营(Day 30-36,联调阶段 6) + +| 工作日 | 任务 | 产出物 | 验收标准 | +|---|---|---|---| +| D30 | 图表基座:ECharts 封装(主题/自适应/loading)+ 通用过滤栏(时间/账号/通道/运营商) | components/charts | 图表空态/加载态统一;切换过滤无内存泄漏(路由切换销毁) | +| D31 | 用户统计:量级/成功率/回执速率趋势、7 维度下钻(时间/地区/签名/状态码…) | views/stats/user | 图表数据与明细核对一致(抽 3 日);导出 XLS | +| D32 | 通道统计:成功率/耗时/量级、估算余额、通道告警配置页 | views/stats/channel | 趋势与后端 stats_channel_daily 一致;告警阈值保存生效 | +| D33 | 结算-下家:月度账单/明细/确认;结算-上家:账单/结账记录/单价追加 | views/settle/* 4 页 | 账单金额=成功条数×单价(抽样对账);状态流转清晰 | +| D34 | 利润分析(用户/通道两视角)+ 消耗/充值日志页 | views/settle/profit | 利润曲线与手工核算一致;日志可追溯操作人 | +| D35 | 主页工作台:今日用量/待办(待审核数)/余额预警/公告;系统配置(参数/初始化/错误码表维护/备份);日志报表(操作日志) | views/home、views/system/* 4 页 | 工作台 5s 内加载;错误码表与后端种子一致(可维护) | +| D36 | 通讯录+常用短语+常用号码(P2 顺带,轻量);预警公告管理;阶段走查 | views/tools/* 3 页 | **FE-5 验收=A-6.x 联调:统计/结算/工作台可用** | + +### FE-6 联调加固与上线(Day 37-40,配合阶段 7) + +| 工作日 | 任务 | 产出物 | 验收标准 | +|---|---|---|---| +| D37 | 全站权限矩阵走查(admin/运维/客服/集团/客户 五角色 × 全菜单);Mock 全部下线切换真实 API | 权限矩阵走查表 | 五角色各走查一遍并截图归档;无越权入口 | +| D38 | 性能与体验:路由懒加载/打包分析/首屏优化;表格大数据虚拟滚动抽检;暗坑修复 | 性能报告(web-vitals) | 首屏 LCP < 2s(内网);chunk 单包 < 500KB | +| D39 | CI 集成:web 构建加入 make ci-local 与 .gitlab-ci(test→build);镜像多阶段构建(node→nginx) | CI 配置、web/Dockerfile、nginx.conf | CI 绿;容器化部署 kind Dev 通过(NodePort 30081) | +| D40 | Playwright 冒烟(登录→发送→审核→记录→结算 主链 10 用例);前端验收会议;文档归档 | e2e/ 10 用例、docs/frontend-review.md | 冒烟全绿;**FE 总验收:50 页走查表全过,零 P0 缺陷** | + +--- + +## 四、交付物清单(累计) + +1. `web/` 工程:源码 + 单测(Vitest 核心工具函数/请求层)+ E2E(Playwright 10 用例) +2. 组件资产:布局/搜索表格套件(ProTable)/分步表单/图表基座/导入导出组件/权限指令 +3. 页面 50+(覆盖 P0 全量 + P1 主体,18 模块中 12 个) +4. `docs/frontend-review.md` 前端验收报告 + 权限矩阵走查表 +5. CI/CD:lint→test→build→镜像→kind Dev 部署链路 + +## 五、Mock 与联调策略 + +- 契约源:后端 `api/openapi.yaml`(Day 30 起维护);阶段 2 之前由前端按本计划接口约定建 Mock 契约,后端实现时对齐 +- 切换:`.env` 的 `VITE_API_MODE=mock|real`,联调周统一切 real;Mock 数据含错误分支(401/403/ISC:500)保证异常态开发 +- 联调窗口:每阶段最后 1 天为固定联调日(与后端阶段验收同周),问题当周清零 + +## 六、风险与依赖 + +| 风险 | 应对 | +|---|---| +| 后端阶段 2 接口延期 | FE-1 前 2 天用 Mock,后端就绪即切换;计划已在缓冲 | +| ISC 错误码双端不一致 | 前端字典从 `internal/pkg/errors` 生成脚本(D39 前完成 codegen) | +| 大表渲染卡顿(明细页) | ProTable 内置虚拟滚动;分页 100;导出走下载中心 | +| 四步路由配置器复杂度高 | D14 预留 1.5 天;必要时降级为分步向导交互 | +| P2 业务线(视频/CSP/空号/短链/大屏) | 明确列入迭代二,本期仅保留菜单占位与路由 404 引导页 | + +--- + +> 执行规范与主干一致:分支 `feature/fe-*` 从 `develop` 拉出,按 FE 阶段合并;每次推送更新 CHANGELOG.md;提交信息含自测报告。 diff --git a/memory-bank/docs/Go-sms-实施计划.md b/memory-bank/docs/Go-sms-实施计划.md new file mode 100644 index 00000000..9bb6b6ed --- /dev/null +++ b/memory-bank/docs/Go-sms-实施计划.md @@ -0,0 +1,423 @@ +# go-sms 分阶段落地实施计划 + +> **【文档状态】⛔ 已废止**(2026-09 被 80 工作日日历取代;10 人团队资源假设与单人现实脱节) +> 仅作历史归档;阶段门禁思想由七件套门禁协议继承。 + +## 实施总体原则 + +- **环环相扣**:每个阶段的输出是下个阶段的输入,验收不通过则阻塞后续开发 +- **MVP优先**:P0功能优先落地,确保核心链路可运行 +- **每日站会**:15分钟同步进度与阻塞 +- **每周迭代评审**:展示可工作软件,收集反馈 +- **自动化测试**:单元测试覆盖率≥80%,集成测试覆盖核心链路 + +--- + +## 第0阶段:基础环境准备(第1-2周) + +> **目标**:完成开发、测试、预发布三套环境搭建,所有基础设施就绪 + +### 任务清单 + +| 序号 | 任务 | 责任人 | 工时 | 依赖 | +|------|------|--------|------|------| +| 0.1 | 申请云资源(或物理机):计算节点、存储、网络 | 运维 | 2天 | 无 | +| 0.2 | 部署Kubernetes集群(3主节点+5工作节点) | 运维 | 2天 | 0.1 | +| 0.3 | 部署MySQL 8.0 MGR集群(1主2从) | DBA | 1天 | 0.2 | +| 0.4 | 部署Redis Cluster(6节点,3主3从) | DBA | 1天 | 0.2 | +| 0.5 | 部署Kafka 3节点集群 + 创建核心Topic | 运维 | 1天 | 0.2 | +| 0.6 | 部署ClickHouse集群(2分片×2副本) | DBA | 1天 | 0.2 | +| 0.7 | 部署ETCD 3节点集群 | 运维 | 1天 | 0.2 | +| 0.8 | 部署MinIO对象存储 | 运维 | 0.5天 | 0.2 | +| 0.9 | 部署Prometheus + Grafana监控体系 | 运维 | 1天 | 0.2 | +| 0.10 | 部署ELK/EFK日志平台 | 运维 | 1天 | 0.2 | +| 0.11 | 搭建GitLab CI/CD流水线基础 | 运维 | 1天 | 0.2 | +| 0.12 | 初始化项目代码仓库 + 分支策略设定 | 后端TL | 0.5天 | 无 | +| 0.13 | 编写docker-compose本地开发环境 | 后端TL | 1天 | 无 | + +### 验收标准 + +| 编号 | 验收项 | 验收方法 | 通过条件 | +|------|--------|----------|----------| +| A-0.1 | 所有中间件健康运行 | `kubectl get pods -n middleware` 全部Running | 所有Pod状态为Running,无重启 | +| A-0.2 | MySQL主从同步正常 | 执行 `SHOW SLAVE STATUS` | Seconds_Behind_Master < 1s | +| A-0.3 | Redis集群节点全部在线 | `redis-cli cluster nodes` | 所有节点状态为connected | +| A-0.4 | Kafka Topic创建成功 | `kafka-topics.sh --list` | 包含 `sms-submit` `sms-report` `sms-up` `stats` 四个Topic | +| A-0.5 | ClickHouse表创建成功 | 执行 `SHOW TABLES` | 返回 `sms_down_details` 和 `sms_up_records` | +| A-0.6 | 监控面板可访问 | 浏览器访问Grafana | 显示基础系统指标(CPU/内存/磁盘) | +| A-0.7 | 日志可正常采集 | 查询ES索引 | 有系统日志写入 | +| A-0.8 | CI/CD Pipeline可执行 | 触发一次空跑Pipeline | 绿色通过 | +| A-0.9 | 本地开发环境可启动 | `docker-compose up` | 所有容器正常启动无报错 | +| A-0.10 | 代码结构规范 | 执行 `go mod tidy && go build ./...` | 编译通过无错误 | + +### 阶段输出物 +- [ ] 基础设施架构图 +- [ ] 网络拓扑图 +- [ ] 中间件部署配置清单 +- [ ] K8s资源清单(YAML文件) +- [ ] CI/CD配置文件(.gitlab-ci.yml) +- [ ] 本地开发环境docker-compose.yaml +- [ ] 项目代码骨架(cmd/internal/pkg目录结构) + +### 阻塞条件 +- 任一中间件无法正常启动 → **阻塞** +- CI/CD Pipeline无法运行 → **阻塞** +- 本地开发环境无法一键启动 → **阻塞** + +--- + +## 第1阶段:核心数据模型与公共组件(第3-4周) + +> **目标**:完成所有数据模型定义、公共组件库、配置管理、日志/监控埋点,为业务开发奠定基础 + +### 任务清单 + +| 序号 | 任务 | 责任人 | 工时 | 依赖 | +|------|------|--------|------|------| +| 1.1 | 设计并实现MySQL全部表结构(账号/通道/路由/余额/结算等36张表) | 后端高级 | 3天 | 0.2 | +| 1.2 | 编写GORM Entity模型 + 基础DAO层 | 后端高级 | 2天 | 1.1 | +| 1.3 | 实现Viper配置管理(支持YAML+环境变量+ETCD热加载) | 后端中级 | 2天 | 0.2 | +| 1.4 | 实现Zap结构化日志 + Lumberjack切割 | 后端中级 | 1天 | 1.3 | +| 1.5 | 实现Prometheus指标埋点(Counter/Gauge/Histogram) | 后端中级 | 1.5天 | 1.3 | +| 1.6 | 实现OpenTelemetry链路追踪中间件 | 后端高级 | 2天 | 1.3 | +| 1.7 | 实现Redis缓存客户端封装(支持单机/集群/哨兵) | 后端中级 | 1.5天 | 0.4 | +| 1.8 | 实现Kafka生产者/消费者封装(Sarama + 重试/死信) | 后端高级 | 2天 | 0.5 | +| 1.9 | 实现雪花ID生成器(支持多Worker自动注册) | 后端中级 | 1天 | 0.7 | +| 1.10 | 实现Redis分布式锁(Lua脚本 + 自动续期) | 后端中级 | 1.5天 | 0.4 | +| 1.11 | 实现Gin统一响应封装 + 错误码体系(UT:xxxx) | 后端中级 | 1天 | 1.3 | +| 1.12 | 实现JWT鉴权中间件 + 权限校验(Casbin集成) | 后端高级 | 2天 | 1.1 | +| 1.13 | 实现参数校验器(go-playground/validator + 自定义校验) | 后端中级 | 1天 | 1.3 | +| 1.14 | 实现数据库迁移工具(gormigrate + 版本管理) | 后端中级 | 1天 | 1.1 | +| 1.15 | 编写公共工具函数库(加密/脱敏/手机号校验/内容过滤) | 后端中级 | 2天 | 1.3 | + +### 验收标准 + +| 编号 | 验收项 | 验收方法 | 通过条件 | +|------|--------|----------|----------| +| A-1.1 | 所有表结构创建成功 | 连接MySQL执行 `SHOW TABLES` | 返回36张表 | +| A-1.2 | GORM AutoMigrate正常运行 | 执行 `go run cmd/migrate/main.go` | 无报错,表结构符合设计 | +| A-1.3 | 配置支持从ETCD热加载 | 修改ETCD配置 → 观察应用日志 | 10秒内日志显示配置已更新 | +| A-1.4 | 日志输出符合规范(JSON格式) | 查看日志文件 | 每行均为有效JSON,包含timestamp/level/msg/fields | +| A-1.5 | Prometheus指标暴露正常 | 访问 `/metrics` 端点 | 返回有效的Prometheus格式指标 | +| A-1.6 | 链路追踪正常上报Jaeger | 发起测试请求 → 查看Jaeger UI | 可查看到完整Trace链条 | +| A-1.7 | Redis缓存读写正常 | 执行单元测试 `go test ./pkg/cache/...` | 全部通过 | +| A-1.8 | Kafka生产消费正常 | 执行单元测试 `go test ./pkg/queue/...` | 全部通过,可生产消费消息 | +| A-1.9 | ID生成器无碰撞 | 并发生成100万ID | 无重复ID | +| A-1.10 | 分布式锁可正常获取释放 | 执行单元测试 `go test ./pkg/lock/...` | 全部通过,无死锁 | +| A-1.11 | 所有错误码有对应中文描述 | 调用 `GetErrorDesc("UT:0006")` | 返回"黑名单" | +| A-1.12 | JWT鉴权正常 | 携带有效/无效Token访问受保护接口 | 有效Token通过,无效返回401 | +| A-1.13 | 参数校验生效 | 提交非法参数(如空手机号) | 返回明确的校验错误 | +| A-1.14 | 数据库迁移可升级/回滚 | 执行 `migrate up` 和 `migrate down` | 版本号正确变更 | +| A-1.15 | 工具函数单元测试覆盖率≥90% | `go test -cover ./pkg/util/...` | 覆盖率≥90% | + +### 阶段输出物 +- [ ] 完整SQL建表脚本(`scripts/init.sql`) +- [ ] GORM Entity代码(`internal/model/entity/`) +- [ ] 配置管理代码(`internal/config/`) +- [ ] 日志/监控/追踪封装(`internal/pkg/logger/`, `internal/pkg/metrics/`) +- [ ] 缓存/队列/锁封装(`internal/pkg/cache/`, `internal/pkg/queue/`, `internal/pkg/lock/`) +- [ ] 鉴权中间件(`internal/middleware/auth/`) +- [ ] 公共工具库(`internal/util/`) +- [ ] 数据库迁移脚本 +- [ ] 单元测试报告 + +### 阻塞条件 +- 任何基础组件(Redis/Kafka/MySQL)连接失败 → **阻塞** +- 配置热加载不生效 → **阻塞** +- 分布式锁存在死锁风险 → **阻塞** +- 单元测试覆盖率<80% → **阻塞** + +--- + +## 第2阶段:账号与权限体系(第5-6周) + +> **目标**:完成多级账号开户、权限管理、充值与余额管理,建立完整的用户身份体系 + +### 任务清单 + +| 序号 | 任务 | 责任人 | 工时 | 依赖 | +|------|------|--------|------|------| +| 2.1 | 账号CRUD接口(创建/查询/修改/启用禁用/删除) | 后端中级 | 2天 | 1.1 | +| 2.2 | 账号多协议接入配置(CMPP/SMPP/HTTP/Web) | 后端高级 | 2天 | 2.1 | +| 2.3 | 账号多业务开通(国内短信/国际短信/视频/CSP/空号/短链) | 后端中级 | 1.5天 | 2.1 | +| 2.4 | IP白名单绑定与校验 | 后端中级 | 1天 | 2.1 | +| 2.5 | 账号审核模式配置(免审/手动/自动) | 后端中级 | 1天 | 2.1 | +| 2.6 | 角色权限管理(RBAC + 页面级 + 二级权限) | 后端高级 | 3天 | 1.12 | +| 2.7 | 用户登录/登出(密码加密bcrypt + JWT) | 后端中级 | 1.5天 | 1.12 | +| 2.8 | 余额查询与充值接口(单个/批量) | 后端中级 | 2天 | 1.1 | +| 2.9 | 余额预警配置(阈值+微信/短信通知) | 后端高级 | 2天 | 2.8 | +| 2.10 | 账号切换上级/批量配置/标星功能 | 后端中级 | 1.5天 | 2.1 | +| 2.11 | 账号导出(仅admin) | 后端中级 | 1天 | 2.1 | +| 2.12 | 实名认证信息记录与审核 | 后端中级 | 1.5天 | 2.1 | +| 2.13 | 账号服务团队绑定 | 后端初级 | 1天 | 2.1 | +| 2.14 | 统一登录审计日志记录 | 后端中级 | 1.5天 | 1.15 | + +### 验收标准 + +| 编号 | 验收项 | 验收方法 | 通过条件 | +|------|--------|----------|----------| +| A-2.1 | 可正常创建各类账号 | API调用创建HTTP/CMPP/SMPP/Web账号 | 4种协议账号均创建成功 | +| A-2.2 | 开通业务线准确 | 为账号开通短信/视频/CSP/空号/短链 | 各业务线独立生效 | +| A-2.3 | IP白名单生效 | 非白名单IP调用接口 | 返回403拒绝访问 | +| A-2.4 | 审核模式切换生效 | 切换账号审核模式后提交短信 | 按模式执行对应审核策略 | +| A-2.5 | 角色权限正确隔离 | 客服角色无法访问大屏 | 返回403 | +| A-2.6 | 二级权限控制生效 | 无充值权限账号尝试充值 | 返回权限错误 | +| A-2.7 | 登录流程正常 | 正确密码登录返回JWT,错误密码锁定 | JWT有效且含正确claims | +| A-2.8 | 充值后余额正确增加 | 充值100元,查询余额 | 余额增加100元 | +| A-2.9 | 余额预警正常触发 | 余额低于阈值 | 微信/短信通知发送成功 | +| A-2.10 | 账号删除条件限制 | 尝试删除有发送记录的账号 | 返回错误提示"账号有发送记录,不可删除" | +| A-2.11 | 导出账号仅admin | admin可导出,非admin无法导出 | 权限校验生效 | +| A-2.12 | 实名认证审核流程完整 | 提交实名 → 审核通过 → 账号状态更新 | 状态流转正确 | +| A-2.13 | 登录审计记录完整 | 查询审计日志 | 包含登录账号/IP/时间/结果 | + +### 阶段输出物 +- [ ] 账号管理API文档(Swagger/OpenAPI) +- [ ] 账号管理前端页面(开户表单/列表/详情) +- [ ] 充值页面 + 余额展示组件 +- [ ] 权限管理页面(角色配置/权限分配) +- [ ] 账号管理单元测试 + 集成测试 +- [ ] 登录审计日志查询接口 + +### 阻塞条件 +- 任何账号创建失败 → **阻塞** +- 权限校验绕过漏洞 → **阻塞** +- 充值后余额计算错误 → **阻塞** + +--- + +## 第3阶段:通道管理与路由引擎(第7-8周) + +> **目标**:完成通道接入(CMPP/HTTP/SGIP/SMPP)、通道组管理、四步路由引擎 + +### 任务清单 + +| 序号 | 任务 | 责任人 | 工时 | 依赖 | +|------|------|--------|------|------| +| 3.1 | CMPP协议栈实现(连接/登录/提交/Deliver/ActiveTest) | 后端高级 | 4天 | 1.1 | +| 3.2 | HTTP通道适配器(调用上游HTTP API) | 后端中级 | 2天 | 3.1 | +| 3.3 | SGIP协议栈实现 | 后端高级 | 3天 | 3.1 | +| 3.4 | SMPP协议栈实现(Bind/Submit/Deliver/EnquireLink) | 后端高级 | 3天 | 3.1 | +| 3.5 | 通道连接池管理(连接复用/心跳/断线重连) | 后端高级 | 2天 | 3.1 | +| 3.6 | 通道CRUD接口 + 通道测试工具 | 后端中级 | 2天 | 3.1 | +| 3.7 | 通道拦截配置(频次/日限/夜间管控/地区/黑关键字/签名) | 后端高级 | 2天 | 3.6 | +| 3.8 | 通道组管理(创建/启停/绑定通道) | 后端中级 | 1.5天 | 3.6 | +| 3.9 | 四步路由引擎实现 | 后端高级 | 4天 | 3.8 | +| 3.10 | 导流策略(关键字/账号维度指定通道) | 后端高级 | 2天 | 3.9 | +| 3.11 | 通道价格时间线管理(分时单价) | 后端中级 | 2天 | 3.6 | +| 3.12 | 通道估算余额计算(校正余额-成功数-未知数,2小时刷新) | 后端中级 | 1.5天 | 3.11 | +| 3.13 | 通道告警配置(异常检测/微信推送) | 后端中级 | 2天 | 3.6 | +| 3.14 | 通道通讯实时监控(2秒刷新) | 后端高级 | 2天 | 3.6 | +| 3.15 | 通道日志记录(CMPP用户/通道日志,5天内) | 后端中级 | 1.5天 | 3.1 | + +### 验收标准 + +| 编号 | 验收项 | 验收方法 | 通过条件 | +|------|--------|----------|----------| +| A-3.1 | CMPP连接建立成功 | 连接模拟运营商CMPP服务端 | 登录成功,心跳正常 | +| A-3.2 | CMPP消息提交成功 | 通过CMPP提交一条短信 | 收到Submit_Resp,MsgID非空 | +| A-3.3 | HTTP通道调用成功 | 配置HTTP通道,发送请求 | 收到200响应,返回上游MsgID | +| A-3.4 | SGIP/SMPP通道正常 | 同CMPP测试 | 绑定成功,消息收发正常 | +| A-3.5 | 连接池断线重连 | 手动断开通道连接 | 30秒内自动重连成功 | +| A-3.6 | 通道测试工具通过 | 使用测试工具发送测试短信 | 通道返回成功 | +| A-3.7 | 日限拦截生效 | 配置日限10条,发送第11条 | 返回UT:0023(发送限制) | +| A-3.8 | 通道组权重分发正确 | 配置A:B=7:3,发送100条 | A≈70条,B≈30条,误差<5 | +| A-3.9 | 优先通道命中 | 配置关键字"测试"走优先通道 | 含"测试"内容走指定通道 | +| A-3.10 | 分时单价生效 | 配置8:00-18:00单价0.05,其他0.06 | 不同时间扣费正确 | +| A-3.11 | 通道估算余额准确 | 连续发送后查询估算余额 | 估算余额≈实际可用余额 | +| A-3.12 | 通道告警触发 | 模拟通道异常 | 微信告警通知发送成功 | +| A-3.13 | 实时通讯曲线刷新 | 访问监控页面 | 每2秒数据更新 | +| A-3.14 | 通道日志完整 | 查询某通道日志 | 包含连接/提交/回执完整记录 | + +### 阶段输出物 +- [ ] CMPP/HTTP/SGIP/SMPP协议实现代码 +- [ ] 通道管理后台(通道列表/配置/测试/监控) +- [ ] 通道组配置界面 +- [ ] 路由规则配置界面 +- [ ] 路由引擎单元测试(覆盖所有路由场景) +- [ ] 通道API文档 + +### 阻塞条件 +- CMPP协议无法正常通信 → **阻塞**(核心通道) +- 路由引擎分发逻辑错误 → **阻塞** +- 通道连接池存在泄漏 → **阻塞** + +--- + +## 第4阶段:消息发送主链路(第9-10周) + +> **目标**:完成群发/个性/定时/文件短信发送全流程,含审核、拦截、路由、提交通道 + +### 任务清单 + +| 序号 | 任务 | 责任人 | 工时 | 依赖 | +|------|------|--------|------|------| +| 4.1 | 发送接口统一模型设计(SubmitRequest/Response) | 后端高级 | 1天 | 2.1 | +| 4.2 | 模板体系实现(模板CRUD + 变量匹配 + 占位符替换) | 后端高级 | 2天 | 4.1 | +| 4.3 | 黑名单三级检测(本地/API/第三方通道) | 后端高级 | 2天 | 3.9 | +| 4.4 | 黑白关键字/频次/签名/退订/地区/时间管控拦截器 | 后端高级 | 3天 | 3.9 | +| 4.5 | 审核工作流(免审/手动/自动 + 48h超时失败) | 后端高级 | 3天 | 2.5 | +| 4.6 | 群发短信业务逻辑(同内容批量) | 后端中级 | 2天 | 4.1 | +| 4.7 | 个性短信业务逻辑(号码+内容变量逐条) | 后端中级 | 2天 | 4.1 | +| 4.8 | 定时短信(定时任务管理 + 批量重置) | 后端中级 | 2天 | 4.6 | +| 4.9 | 文件短信(TXT/Excel/CSV解析 + 异步发送) | 后端中级 | 2天 | 4.6 | +| 4.10 | HTTP API提交接口(含签名校验/回执绑定/上行绑定) | 后端中级 | 2天 | 4.1 | +| 4.11 | CMPP客户接入提交(企业代码/扩展码/通道号校验) | 后端高级 | 2天 | 4.1 | +| 4.12 | CMPP合包发送(聚合提交降低HTTP通道压力) | 后端高级 | 2天 | 4.11 | +| 4.13 | 上行码号分配(精确/前缀匹配 + 账号归属) | 后端中级 | 1.5天 | 4.1 | +| 4.14 | 发送批次记录生成 + 批次状态统计 | 后端中级 | 2天 | 4.6 | +| 4.15 | Kafka生产者写入(消息入队) | 后端中级 | 1天 | 1.8 | + +### 验收标准 + +| 编号 | 验收项 | 验收方法 | 通过条件 | +|------|--------|----------|----------| +| A-4.1 | 群发短信正常提交 | 通过API提交100条短信 | 返回批次ID,全部进入审核/发送流程 | +| A-4.2 | 个性短信逐条内容 | 提交3条不同内容个性短信 | 每条内容与提交一致 | +| A-4.3 | 模板匹配生效 | 使用报备模板发送 | 自动匹配模板,免审通过 | +| A-4.4 | 模板变量替换正确 | 模板`{%姓名%}`替换为实际值 | 替换后内容正确 | +| A-4.5 | 黑名单拦截命中 | 手机号在黑名单中 | 返回UT:0006 | +| A-4.6 | 频次拦截命中 | 同号码1分钟内发送2条(配置1条/分钟) | 第2条返回UT:0016 | +| A-4.7 | 签名校验生效 | 内容无签名 | 返回UT:0013 | +| A-4.8 | 退订标识校验 | 内容无"拒收请回复R" | 返回UT:0014 | +| A-4.9 | 地区拦截生效 | 手机号属于屏蔽省份 | 返回UT:0009 | +| A-4.10 | 营销时间管控生效 | 非营销时间段提交 | 返回时间管控失败 | +| A-4.11 | 自动审核通过 | 提交内容无敏感词 | 状态为审核通过,进入路由 | +| A-4.12 | 手动审核 | 提交敏感内容 | 状态为待审核,管理员可见 | +| A-4.13 | 48h超时审核自动失败 | 待审核消息48小时未处理 | 状态变为审核失败 | +| A-4.14 | 定时短信定时发送 | 设置2小时后发送 | 2小时后准确发送 | +| A-4.15 | 文件短信解析正确 | 上传含1000条号码的Excel | 全部解析成功,逐条发送 | +| A-4.16 | CMPP客户提交通道号校验 | 提交通道号不匹配 | 返回UT:0012 | +| A-4.17 | CMPP合包生效 | 大批量提交触发合包 | 有效减少HTTP调用次数 | +| A-4.18 | 上行码号分配正确 | 回复码号匹配账号 | 上行记录归属正确账号 | +| A-4.19 | Kafka消息入队成功 | 发送后检查Topic | 消息存在于`sms-submit` Topic | +| A-4.20 | 入口吞吐达标 | 5000 TPS持续5min压测(Day50) | P99<50ms;超限请求返回429;MySQL无同步写入 | +| A-4.21 | 下发限速零超速 | 满载下发对照通道speed=3000 | 峰值≥3000 TPS且无超速拒绝;零失败零断链(对照Day39基线:256窗口均值2263/峰值3203) | +| A-4.22 | 背压三级水位联动 | 5000入/3000出打5min | lag>10万触发L1告警;L2入口收紧至Σ(通道speed);停止打压后lag收敛 | + +### 阶段输出物 +- [ ] 发送API文档(HTTP/CMPP/SMPP) +- [ ] 网页发送界面(群发/个性/定时/文件) +- [ ] 模板管理界面 +- [ ] 审核工作台(待审核列表/通过/拒绝) +- [ ] 发送批次记录查询 +- [ ] 发送单元测试 + 集成测试 +- [ ] 拦截器链性能测试报告 + +### 阻塞条件 +- 任何发送方式(群发/个性/定时)无法正常提交 → **阻塞** +- 模板匹配不准确 → **阻塞** +- 审核流程状态流转错误 → **阻塞** +- Kafka消息未正确入队 → **阻塞** + +--- + +## 第5阶段:回执/上行与记录查询(第11-12周) + +> **目标**:完成回执接收处理、上行消息处理、下行记录/明细/历史查询 + +### 任务清单 + +| 序号 | 任务 | 责任人 | 工时 | 依赖 | +|------|------|--------|------|------| +| 5.1 | Kafka消费者服务(消费回执/上行消息) | 后端高级 | 2天 | 4.15 | +| 5.2 | 回执处理引擎(状态归一化 DELIVRD/FAILURE/UNKNOWN) | 后端高级 | 2天 | 5.1 | +| 5.3 | 计费确认/退款逻辑(预扣→实扣/回退) | 后端高级 | 3天 | 2.8, 5.2 | +| 5.4 | 回执重推机制(支持30天内手动重推) | 后端中级 | 2天 | 5.2 | +| 5.5 | 手动配对状态(4种方式处理3h外无状态短信) | 后端高级 | 2天 | 5.2 | +| 5.6 | 上行消息处理(接收/匹配/归属分配) | 后端中级 | 2天 | 5.1 | +| 5.7 | 上行自动拉黑(回复"拒收"等规则可配) | 后端中级 | 1.5天 | 5.6 | +| 5.8 | HTTP回调推送(回执绑定地址+上行绑定地址) | 后端中级 | 2天 | 5.2, 5.6 | +| 5.9 | CMPP回执推送(Deliver) | 后端高级 | 2天 | 5.2 | +| 5.10 | 下行记录(批次级,5天热数据) | 后端中级 | 2天 | 4.14 | +| 5.11 | 下行明细(号码级,5天热数据) | 后端中级 | 2天 | 5.10 | +| 5.12 | 历史记录/明细(全量查询,ClickHouse) | 后端高级 | 3天 | 0.6 | +| 5.13 | 上行记录(15天匹配窗口) | 后端中级 | 2天 | 5.6 | +| 5.14 | 定时记录管理(定时任务取消/重置时间) | 后端中级 | 1.5天 | 4.8 | +| 5.15 | 明细异步下载(下载中心 + 权限控制) | 后端中级 | 2天 | 5.12 | +| 5.16 | 视频记录体系(下行/明细/上行/定时,同短信模型) | 后端中级 | 2天 | 5.10 | + +### 验收标准 + +| 编号 | 验收项 | 验收方法 | 通过条件 | +|------|--------|----------|----------| +| A-5.1 | 回执消费正常 | 模拟通道发送回执到Kafka | 消费者正确处理,状态更新 | +| A-5.2 | DELIVRD计费确认 | 回执为DELIVRD | 预扣金额转为实扣,余额正确减少 | +| A-5.3 | FAILURE退款 | 回执为FAILURE | 预扣金额退回,余额恢复 | +| A-5.4 | UNKNOWN状态处理 | 72小时无回执 | 状态变为UNKNOWN,冻结释放 | +| A-5.5 | 回执重推成功 | 手动触发30天内回执重推 | 客户收到重推回执 | +| A-5.6 | 手动配对生效 | 对3h外无状态短信执行配对 | 状态更新为指定状态 | +| A-5.7 | 上行消息归属正确 | 上行码号匹配到账号 | 上行记录归属正确账号 | +| A-5.8 | 上行"拒收"自动拉黑 | 回复"拒收R" | 手机号加入黑名单 | +| A-5.9 | HTTP回调正常 | 配置回执回调地址 | 回调接口收到回执JSON | +| A-5.10 | CMPP Deliver推送 | 客户为CMPP协议 | 通过CMPP连接推送Deliver | +| A-5.11 | 下行记录5天内可查 | 查询今日发送批次 | 返回正确批次列表 | +| A-5.12 | 历史数据可查 | 查询90天前发送记录 | 从ClickHouse返回正确数据 | +| A-5.13 | 上行15天匹配 | 上行匹配15天内发送数据 | 匹配成功或归admin | +| A-5.14 | 定时任务取消 | 取消待发送定时任务 | 任务不再执行 | +| A-5.15 | 明细异步下载 | 发起下载任务 → 下载文件 | 文件内容与查询结果一致 | +| A-5.16 | 视频记录独立 | 查询视频短信记录 | 与短信记录隔离正确 | + +### 阶段输出物 +- [ ] 回执处理服务 +- [ ] 上行处理服务 +- [ ] 记录查询API + 前端页面(下行记录/明细/历史/上行) +- [ ] 手动配对工具 +- [ ] 回执重推管理页面 +- [ ] 定时任务管理页面 +- [ ] 明细下载中心 + +### 阻塞条件 +- 回执无法正常匹配消息ID → **阻塞** +- 计费确认/退款计算错误 → **阻塞**(资金安全) +- 历史数据查询超时(>3秒)→ **阻塞** + +--- + +## 第6阶段:统计与计费结算(第13-14周) + +> **目标**:完成多维统计、上下家结算、利润分析、充值/消耗日志 + +### 任务清单 + +| 序号 | 任务 | 责任人 | 工时 | 依赖 | +|------|------|--------|------|------| +| 6.1 | 统计事件消费者(消费Kafka统计事件 → 写入ClickHouse) | 后端高级 | 2天 | 0.6 | +| 6.2 | 多维统计(时间/用户/地区/运营商/签名/状态码/回执速率) | 后端高级 | 3天 | 6.1 | +| 6.3 | 统计定时补算(偶数整点刷新/昨日7/13/17点补算) | 后端中级 | 2天 | 6.2 | +| 6.4 | 用户使用统计API + 前端图表 | 后端中级 | 2天 | 6.3 | +| 6.5 | 通道使用统计API + 前端图表 | 后端中级 | 2天 | 6.3 | +| 6.6 | 下家结算(月度账单/明细导出) | 后端高级 | 2.5天 | 5.3 | +| 6.7 | 上家结算(账单/明细/结账记录/单价追加) | 后端高级 | 2.5天 | 5.3 | +| 6.8 | 利润分析(用户利润+下级利润+通道利润) | 后端高级 | 2天 | 6.6, 6.7 | +| 6.9 | 消耗日志(按账号/业务/天记录) | 后端中级 | 1.5天 | 5.3 | +| 6.10 | 充值日志(充值记录+付款审核确认) | 后端中级 | 1.5天 | 2.8 | +| 6.11 | 结算报表导出(XLS格式) | 后端中级 | 1天 | 6.6 | +| 6.12 | 主页工作台(今日用量/发送类型/数据分析) | 后端高级 | 2天 | 6.3 | + +### 验收标准 + +| 编号 | 验收项 | 验收方法 | 通过条件 | +|------|--------|----------|----------| +| A-6.1 | 统计事件实时写入 | 发送消息后查看ClickHouse | 5秒内在统计表可见新数据 | +| A-6.2 | 时间维度统计准确 | 查询今日/本月/自定义时间范围 | 数据与发送记录一致 | +| A-6.3 | 用户维度统计准确 | 查询指定账号发送量 | 数据准确 | +| A-6.4 | 地区/运营商统计准确 | 查询某省/某运营商发送量 | 与号码库匹配 | +| A-6.5 | 偶数整点刷新生效 | 14:00查看统计 | 数据更新到最新 | +| A-6.6 | 昨日补算生效 | 7:00查看昨日统计 | 数据完整 | +| A-6.7 | 下家账单金额正确 | 生成某客户月度账单 | 金额=成功条数×单价 | +| A-6.8 | 上家结算金额正确 | 生成上家对账单 | 金额=成功条数×通道成本单价 | +| A-6.9 | 利润计算正确 | 查询某时间段利润 | 利润=下家收入-上家成本 | +| A-6.10 | 消耗日志完整 | 查询某账号某天消耗 | 包含所有发送消耗 | +| A-6.11 | 充值日志可追溯 | 查询充值记录 | 包含充值时间/金额/操作人 | +| A-6.12 | 主页工作台数据实时 | 访问主页 | 今日用量/图表正常显示 | + +### 阶段输出物 +- [ ] 统计服务API + 前端报表页面 +- [ ] 结算管理页面(下家/上家账单) +- [ ] 利润分析面板 +- [ ] 消耗/充值日志查询页面 +- [ ] 主页工作台 +- [ ] 统计准确性测试报告 + +### 阻塞条件 +- 统计数据与 \ No newline at end of file diff --git a/memory-bank/docs/Go-sms-开发日历.md b/memory-bank/docs/Go-sms-开发日历.md new file mode 100644 index 00000000..718137bf --- /dev/null +++ b/memory-bank/docs/Go-sms-开发日历.md @@ -0,0 +1,347 @@ +# go-Sms 全栈协同开发日历(第 1~80 工作日) + +> **【文档状态】🔒 POC 进度事实源·已定稿**(Day 71 止,2026-09-29) +> 逐日任务/验收/commit 证据链=重建「为什么这么做」知识库;Day 72-80 各行为未执行死计划,作重建排期原始参考,不作承诺。 + +> **文档定位**:本日历由《memory-bank/docs/Go-sms-开发计划.md》(后端,Day 1-80)与《memory-bank/docs/Go-sms-前端开发计划.md》(前端,FE D1-40)合并而成,是全栈双轨并行的**统一进度事实来源**——包含每工作日任务、验收标准、验收日期、完成状态与更新明细(提交号)。 +> 原两份计划保留为详细任务拆解参考;本日历按周对齐双轨,每周五行,后端/前端并排。 +> **编制**:2026-09-04 · 依据两份计划 + git 提交历史 + docs/phase1-review.md + CHANGELOG.md + +## 图例 + +| 标记 | 含义 | +|---|---| +| ✅ | 已完成且已合入 `develop`(或已在验收分支通过验收)——验收标准 100% 逐条通过 | +| 🔶 | 已完成、已推送,等待合并(联调窗口统一合并) | +| 🔄 | 进行中 | +| ⬜ | 未开始 | +| 🚧 | 阶段验收门禁(承上启下检查点) | +| ❌ | **验收未通过(阻塞中)**——下一任务冻结,修复复验通过后回填 ✅ | + +**验收日期规则**:已完成项取实际提交/合并时间(git 历史);未完成项以工作日序号排期,自然日历日期待定(执行节奏以阶段门禁为准,不锁死日历日)。 + +--- + +## 零例外进度门禁协议(2026-09-04 增补 · 执行宪法) + +> **总纲:任何任务(后端 Day N / 前端 D N)验收标准未 100% 通过,下一个任务不得开工。** +> 本节优先级高于一切排期——排期可以顺延,质量门禁不可豁免;日历中每个任务都必须先定义「产出物 + 验收标准」,再动手开发。 + +### 1. 三层门禁模型 + +| 层级 | 粒度 | 通过判据(全部满足才 ✅) | 未过后果 | +|---|---|---|---| +| **L1 每日门禁** | 单个任务(后端 Day N / 前端 D N) | ①验收标准逐条通过 ②质量基线全绿 ③提交推送 ④CHANGELOG 增补 ⑤本日历状态列更新 | 标记 ❌;**次日冻结新任务,修复最高优先级**;修复后完整复验,通过才解锁下一任务 | +| **L2 阶段门禁** | 阶段(后端 8 个 / 前端 7 个) | 阶段内**所有任务 ✅**(无 ❌/⬜ 遗留)+ A-x.x 验收单全过 + 联调项通过 | 下一阶段所有任务不得开工;进入修复循环,顺延排期 | +| **L3 双轨门禁** | 前后端联调项(🚧 联调日) | 前端页面切真实 API 与后端行为一致(替换 Mock);ISC 码/分页/权限三态对齐 | 前端该页保持 🔶* 标注,联调窗口补验;**不阻塞后端推进**(Mock 策略保障前端不被后端卡死) | + +### 1.5 日闭环拉齐与人工验收(v2 增补 2026-09-10,Day 41 起生效) + +> 阶段 4 起联调从「阶段末集中」改为「每日垂直切片」:后端 Day N 完成 → 当日前端拉齐 → 人工逐项验收,当日问题当日发现。v1 五件套对历史任务(Day 1-40)仍有效。 + +- **节奏**:后端 Day N 交付(L1 五件套)→ 当日前端拉齐(对应 D N 页面切真实 API + lint/typecheck/build 三件套)→ AI 产出人工验收单(`docs/acceptance/dayNN.md`,依 `_template.md`,≤10 项 ≤20 分钟)→ **人工逐项走查** → 全过标 `✅A` 解锁 Day N+1;未过标 `❌` **严格冻结**(沿用零例外总纲)。 +- **L1 判据增补第 ⑥ 项**:人工验收单全过并归档 `docs/acceptance/`(Day 41 起生效)。 +- **验收形态**:页面日(D41-47)=真实浏览器操作走查;纯后端日(D48-50)=日志/数据/压测报告走查,不硬造页面操作。 +- **兜底规则**:后端 API 当日未就绪 → 前端按 openapi 契约 Mock 出页 🔶* 标注,次日首件事补联调;等待人工走查期间 AI 只做不依赖验收结论的工作(次日契约/DTO 草案),不空转。 +- **状态标记**:`✅`=自动化+L1 过(v1 口径);`✅A`=人工验收单全过归档(阶段 4 起每任务必须达到);`❌`=冻结中;`⏳W`=自动化+验收单 #1~#10 过但**前端人工走查(用户本人)未签**(v3 起过渡态,走查过即转 ✅A)。 +- **协议 v3(2026-09-11 增补,Day 43 起生效)**:所有任务的 D N 前端页面,**必须由用户本人在浏览器逐项操作走查**(验收单「二·五」节,AI 不得以 vitest/e2e mock 测试替代);W 节未签名不得标 ✅A、不得解锁 Day N+1。纯后端日不硬造页面操作(沿用 v2 口径)。 +- **周表载体**:第 9/10 周起,周表「验收日期 / 更新明细」列即人工验收记录(✅A/❌ + 验收人),验收单原文归档 `docs/acceptance/`。 +- **协议 v4(2026-09-12 增补,Day 48 收官起生效)——分支治理与文档单一事实源**: + - **三活分支模型**:仓库仅保留 `main`(已验收归档线:代码+验收单+日历)/`develop`(集成线)/`feature/*`(当前任务段唯一活跃分支);其余分支(阶段遗留 feature/release 旧支)在并入 develop 后**当周删除**(本地+远程),僵尸分支(已合未删)清零。 + - **feature 生命周期 ≤ 一个任务段**:Day N 人工验收 ✅A 当日即合并 develop 并删除 feature 分支;不允许 feature 分支跨任务段长期存活(消除日历/验收单多分支分叉窗口——2026-09-12 前 feature/phase4-send 曾领先 develop 21 提交,根治此况)。 + - **main 同步节奏**:每 Day ✅A 收官或每阶段门禁通过后,develop → main `--no-ff` 合并推送;`docs/acceptance/`、开发日历、CHANGELOG 以 **main 为权威查找源**(索引见 docs/acceptance/README.md)。 + - **文档不产生分叉窗口**:验收单/日历/CHANGELOG 的当日更新随当日任务提交进 feature→当日合 develop;严禁在 main 上直接修改文档绕过 develop。 + +### 2. 每日验收 DoD(完成定义五件套,缺一即 ❌) + +**后端任务**(每个 Day N 收工前自查): + +| # | 项 | 判据 | +|---|---|---| +| 1 | 代码 | 实现完整 + go doc 注释;`go build ./...` 0 错误 | +| 2 | 测试 | `go test ./...`(-race 阶段回归)全绿;新增逻辑覆盖率 ≥80%(核心服务);集成测试(若有)通过 | +| 3 | 规范 | `golangci-lint run ./...` 0 issue | +| 4 | 提交 | 推送 feature 分支;提交信息含验收结论(场景×结果) | +| 5 | 文档 | CHANGELOG 增补当日条目;本日历状态列改 ✅ 并填提交号 | + +**前端任务**(每个 D N 收工前自查): + +| # | 项 | 判据 | +|---|---|---| +| 1 | 代码 | 页面/组件实现;对接统一响应 `{code,msg,data}` 与 ISC 码(401→登录/403→提示/500→人工核查) | +| 2 | 测试 | `pnpm test`(Vitest)全绿;新增页面附对应用例 | +| 3 | 规范 | `pnpm lint` 0 error 0 warning;`pnpm build` 通过 | +| 4 | 提交 | 推送 `feature/fe-*` 分支;提交信息含自测报告 | +| 5 | 文档 | CHANGELOG 增补;本日历状态列改 ✅ | + +### 3. 「100% 通过」判定与例外处理 + +- **逐条对照**:验收标准每条都要有证据(命令输出/响应体/截图/测试名),一条不满足即整任务 ❌,不存在"基本完成"。 +- **修复优先**:❌ 任务次日为最高优先级;修复后**完整复验全部标准**(不是只测改动点),通过才回填 ✅ 并解锁后续任务。 +- **升级机制**:同一任务连续 2 天 ❌ → 上报 TL 评审,可裁剪范围(须同步修订验收标准并留痕,**不得降低已通过项的标准**)。 +- **环境阻塞**:第三方/运维类阻塞登记到「横切事项」,可并行开发下一任务中不受阻的部分,但受阻任务本身不得标 ✅。 +- **双轨串行**:后端 Day N 未 ✅ 不得开 Day N+1;前端 D N 未 ✅ 不得开 D N+1;前后端互不阻塞(L3 除外,联调项双端都未过则 FE 阶段验收 🔶* 顺延)。 + +--- + + +## 双轨总览(截至 2026-09-13) + +| 轨道 | 阶段 | 工作日窗口 | 状态 | 验收日期 | 更新明细 | +|---|---|---|---|---|---| +| 后端 | 阶段 0 环境与 CI | Day 1-10 | ✅ 完成(合入 develop `7b46b312`) | 2026-09-03 | Day1-2 `0e609c8b` ~ Day10 `eb56a32e` 共 9 提交;A-0.x 全过 | +| 后端 | 阶段 1 数据模型与组件 | Day 11-20 | ✅ 完成(合入 develop `b75fbe26`) | 2026-09-03 | Day11 `12194c61` ~ Day19-20 `de0eb314` 共 9 提交;A-1.1~A-1.15 全过(docs/phase1-review.md) | +| 后端 | 阶段 2 账号与权限 | Day 21-30 | ✅ 完成(验收全过,合入 develop) | 2026-09-04 | Day21 `6748d20d` … Day29 `deb75560` · Day30 `e35ec818`;A-2.1~13 全过(docs/phase2-review.md) | +| 后端 | 阶段 3 通道与路由 | Day 31-40 | ✅ **10/10 天(Day 40 收官)+7 增补日**;A-3.x 全过(A-3.10/11 计费侧注记顺延阶段 4),验收单 docs/phase3-review.md | 实际 2026-09-10 | Day37 路由 Step1 `085a3474` · Day38 导流+分时价 `b101c9cf` · Day39 CMPP 中文/UDH/回执闭环 `8c65225f`+根因两层修复 `d1f64275`/`c0ab7d57`(真网 DELIVRD 双闭环) · Day39.5 压测工具+10 万条基线 `a95b7ff8` · Day39.6 5000/3000 性能规划 `44225a51` · Day31 追加×5(真网联调 `8479d985`/Web real×3/链路单测 `e8b33240`) · Day40 收官 `4ca16173`(告警/WS 监控/channel_log v7/断线重连演练/1000QPS 压测 p99 中位 7.9~8.8ms) | +| 后端 | 阶段 4 消息发送 | Day 41-50 | ✅ 完成(Day41-50 逐日 ✅A 收官,合入 develop `9a42a437`;**A-4.20 满载性能欠账转 Day51-55 专项**——Day51 R3 已 ✅A) | 2026-09-12 | Day41 ~ Day50 `b0f28521`;Day47/48 `031fa3f8`;Day49 `8e50baf9`;详见 day41~50 验收单 | +| 后端 | 阶段 5 回执与记录 | Day 51-64(Day51-54 R1~R3 性能债专项+Day55 复测;验收 Day64,Day50 压测后排期变更) | 🔄 | 2026-09-15 | Day51-58 逐日 ✅A;**Day59/60 计划任务(回调推送引擎/record API+FE-4 联调)未执行**;Day61-65 连续 5 日生产救火(CMPP Deliver 下发/密码与连接可配/拦截终态回执/SubmitFast 异步化/明细查询超时/消费并发 worker 池,各 ✅A 补账提交);**A-5.x 验收未关门,待阶段 5 收尾批次(2026-09-15 复盘裁决)** | +| 后端 | 阶段 6 统计结算 | Day 65-74(随阶段 5 顺延 +4 日) | ⬜ | — | — | +| 后端 | 阶段 7 上线切换 | Day 75-84(80 日框架 +4 日,灰度段缓冲吸收/阶段 6 验收复盘) | ⬜ | — | — | +| 前端 | FE-0 工程与骨架 | D1-5 | ✅ 完成(合入 develop `36701945`) | 2026-09-03 | `26ba2895` + 修复 `d63a6eb8`/`8e56b960`/`b38a637c` | +| 前端 | FE-1 账号与权限 | D6-10 | ✅ 完成(随 FE-0 合并) | 2026-09-03 | `11a30594`(6 页,22/22 测试) | +| 前端 | FE-2 通道与路由 | D11-16 | ✅ 完成(验收通过,**已合并 develop** `5a91cb86`) | 2026-09-04 | `6fb12ece` + D11 验收 `49b18383` + D12-D16 验收 `5ad64a12`;31/31 测试;D13 V2.0 六折叠面板迭代 `b35087da`(fe-tailwind) | +| 前端 | FE-3 发送与审核 | D17-23 | ✅ 完成(D17-23 逐日验收,随阶段 4 波次合入 develop;发送四方式/审核中心/结果反馈/聚合页) | 2026-09-12 | 详见 CHANGELOG Day44~47(D22/D23 双 ✅A 走查三轮闭环) | +| 前端 | FE-4 记录与回执 | D24-29 | 🔄 进行中(D24 ✅A 2026-09-13/D26 ✅A 09-13/D27 ✅A 09-14/D28 ✅A 09-14;方案 A 逐日顺延:Day57=D28…Day58=D29 页面收官,Day60 接 record API 联调=FE-4 验收 A-5.x) | — | **策略拍板 2026-09-13(用户裁决):按原计划逐日完成 D24-29,FE-4 全部完成后再单独立项规划重构;开发期不做中途重构**;**排期落位方案 A 2026-09-13(用户裁决,日历第 11/12 周 FE 列重排)** | +| 前端 | FE-5 统计结算运营 | D30-36 | ⬜ | — | — | +| 前端 | FE-6 联调加固上线 | D37-40 | ⬜ | — | — | + +**累计进度(2026-09-15 复盘更新)**:后端名义 65/80 天(实际推进=Day1-58 计划内+Day61-65 生产救火 5 日,Day59/60 计划任务未执行)· 前端 29/40 天(D24-28 ✅A,D29+record API 联调未收官)· 阶段门禁 4/7(阶段 0-4 ✅;阶段 5 🔄 待 A-5.x 关门;阶段 6/7 ⬜ 且顺延预算已透支,重排待裁决)· 页面 27+/50 +**门禁合规**:截至 2026-09-13 无 ❌ 遗留;每个已完成任务均满足 L1 五件套(证据见各周明细与 CHANGELOG)。 +**门禁合规(2026-09-15 复盘注记)**:Day59-65 连续 7 个工作日未提交未归档(L1 五件套③④⑤破窗,81 文件);当日已完成补账分批提交 develop+补录 day61/65 验收单+本日历状态回填。**教训固化:救火日同样执行五件套,报障不得豁免提交纪律(破窗 1 天未纠即惯性延续)。** +**横切债务**:~~①FE typecheck ②openapi 字典 codegen ③/channels/upstreams API ④fe-tailwind 分支~~ **四项已全部清零(2026-09-10 Day41 开工首动作;详见 CHANGELOG Day 41)**。~~新挂账:TestSGIP_Client -count=3 偶发 bind 超时~~(Day42 已修:Timeout 2s→5s);现存偶发:TestClient_LoginOK 全量并发偶发超时(Day51 单跑 3 次过,环境性,观察中)。 + +## 阶段门禁(承上启下检查清单) + +| 门禁 | 入口条件(必须满足) | 出口交付(必须完成) | 状态 | +|---|---|---|---| +| 🚧 阶段 1 启动 | 阶段 0 A-0.x 全过;CI/CD 能部署 main | 公共组件单测覆盖 ≥80%;迁移工具可用 | ✅ 2026-09-03 | +| 🚧 阶段 2 启动 | 阶段 1 A-1.x 全过;ETCD 热加载验证通过 | 账号 CRUD+JWT+RBAC 完整;审计日志有记录 | ✅ 2026-09-03 | +| 🚧 阶段 3 启动 | 阶段 2 A-2.x 全过;权限模型已验证 | CMPP/HTTP/SMPP 通道可接入;路由引擎单测通过 | ✅ 2026-09-04(A-2.1~13 全过,docs/phase2-review.md) | +| 🚧 阶段 4 启动 | 阶段 3 A-3.x 全过;通道测试工具发测试短信成功 | 四种发送方式可提交;Kafka 入队成功 | ✅ 2026-09-10(A-3.1~14 全过,docs/phase3-review.md;A-3.10/11 计费侧注记顺延——扣费链路阶段 4 上线后回补) | +| 🚧 阶段 5 启动 | 阶段 4 A-4.x 全过;submit Topic 有消费 | 回执正确计费;上行归属准确;历史查询 <1s | ⬜(Day51 起实质启动:性能债专项 R3 ✅/R2·R1·复测 Day52-55;A-4.20 补账后转正) | +| 🚧 阶段 6 启动 | 阶段 5 A-5.x 全过;计费/退款无差额 | 报表与明细一致;账单无误差;工作台可用 | ⬜ | +| 🚧 阶段 7 启动 | 阶段 6 A-6.x 全过;全量回归 PASS | 预发性能达标;灰度成功;生产割接完成 | ⬜ | + +--- +## 第 1 周(Day 1-5 · 前端未启动) + +| 工作日 | 后端任务 | 产出物 | 验收标准(100% 逐条过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---| +| Day 1-2 | Dockerfile 多阶段构建;docker-compose 六中间件;Makefile;go.mod 骨架;config loader(Viper+env) | Dockerfile · docker-compose.dev.yaml · Makefile · go.mod/go.sum · configs/*.yaml · internal/config/loader.go | make up 六容器全 healthy;make down 清理干净;go build ./... 通过 | ✅ | 2026-09-02 · `0e609c8b` | +| Day 3 | K8s 清单(deployment/service/configmap)+ kind Dev 集群 | deployments/base/*.yaml · kind 配置 | kubectl apply 后 Pod Running | ✅ | 2026-09-02 · `a7c3c583` | +| Day 4 | .gitlab-ci.yml(test→build→deploy-dev);/health 端点 | .gitlab-ci.yml · health 路由与中间件 | Push 触发 CI 全绿;/health 返回 200 | ✅ | 2026-09-03 · `1349eea6` | +| Day 5 | zap+lumberjack 结构化日志;请求日志中间件(trace_id) | internal/pkg/logger · middleware/logger.go(双端 JSON,含 trace_id/latency/status) | 测试请求双端输出结构化 JSON 且含 trace_id | ✅ | 2026-09-03 · `e50423a7` | + +## 第 2 周(Day 6-10 · 🚧 阶段 0 验收) + +| 工作日 | 后端任务 | 产出物 | 验收标准(100% 逐条过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---| +| Day 6 | Redis 客户端(single/cluster/sentinel)+ 分布式锁(Lua+续期) | internal/pkg/redis(client/lock)+ miniredis 单测 | miniredis 单测通过;Lock/Unlock/续期正常 | ✅ | 2026-09-03 · `036381fd` | +| Day 7 | Kafka 生产者(重试+死信)/消费者组(手动 offset);Topic 常量 | internal/pkg/queue(producer/consumer)+ Topic 常量 | 收发正常;无 ErrOutOfBrokers | ✅ | 2026-09-03 · `0f9f6a59` | +| Day 8 | 雪花 ID / 校验器(手机号/模板变量/长度)/ AES-GCM | internal/util(snowflake/validator/crypto) | util 覆盖率 ≥90%;并发无 ID 冲突 | ✅ | 2026-09-03 · `9ecd19af` | +| Day 9 | 分布式限流(Redis 令牌桶)/ JWT 中间件 / OTLP 追踪 | middleware(ratelimit/auth/tracer) | 超阈值 429;无效 Token 401;Jaeger 见 Trace | ✅ | 2026-09-03 · `ce975ded` | +| Day 10 | 🚧 阶段 0 全链路回归 + README + 验收评审 | README · scripts/init_mysql.sql · 阶段 0 交付清单 | A-0.x 全过;阻塞条件无遗留 | ✅ | 2026-09-03 · `eb56a32e`,合入 develop `7b46b312` | + +## 第 3 周(Day 11-15 · 前端未启动) + +| 工作日 | 后端任务 | 产出物 | 验收标准(100% 逐条过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---| +| Day 11 | 36 表 DDL + GORM Entity + 泛型 BaseDAO(软删) | model/entity/*.go · repository/basedao.go | AutoMigrate 生成表结构;软删/恢复可用 | ✅ | 2026-09-03 · `12194c61` | +| Day 12 | ETCD 热更新 watcher + app 启动器 + 优雅停机 | internal/app · internal/config/watcher | 10s 内 config reloaded;SIGTERM 排空退出 | ✅ | 2026-09-03 · `63110ea4` | +| Day 13 | Prometheus 指标中心 + HTTP 埋点 + /metrics | internal/pkg/metrics + 埋点中间件 | 指标族可见;P99 分桶对齐 | ✅ | 2026-09-03 · `beddd612` | +| Day 14 | gormigrate 迁移工具(up/down/version/status)+ ClickHouse 批插 | internal/pkg/migrate · pkg/clickhouse | 版本写入 schema_migrations;CH 批插核对一致 | ✅ | 2026-09-03 · `75878f21` | +| Day 15 | ISC 错误码体系 + 统一响应 + 全局 Recovery | pkg/errors(权威 48 码表)+ response + recovery | response.Error 输出 {code,msg};panic → 500 | ✅ | 2026-09-03 · `a4d700b1` → 三位化 `67b60b85` → 权威码表 `426c7c22`(48 码) | + +## 第 4 周(Day 16-20 · 🚧 阶段 1 验收) + +| 工作日 | 后端任务 | 产出物 | 验收标准(100% 逐条过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---| +| Day 16 | ConsumerGroup(暂停/恢复/死信)+ 多级缓存(freecache+Redis) | internal/pkg/queue 扩展 · internal/pkg/cache(L1/L2) | 失败入死信;Get 优先本地命中 | ✅ | 2026-09-03 · `8fc3e24c` | +| Day 17 | JWT 包(claims)+ Casbin(MySQL 持久化)+ init_rbac | pkg/jwt · internal/pkg/casbin · scripts/init_rbac | Token 可解析;Enforce 判定正确 | ✅ | 2026-09-03 · `aa7bd527` | +| Day 18 | go doc 全量注释 + pkg/README + util 拆分 + lint 清零 | 全包注释 · pkg/README.md | golangci-lint 0 warning | ✅ | 2026-09-03 · `b09b031e` | +| Day 19 | 集成测试(testcontainers:MySQL/Redis/Kafka 全链路) | test/integration(*_test.go,-tags=integration) | -tags=integration 全 PASS | ✅ | 2026-09-03 · `de0eb314` | +| Day 20 | 🚧 阶段 1 代码评审 + 验收会议 | docs/phase1-review.md(A-1.1~15 证据映射) | A-1.1~A-1.15 全过;覆盖率 ≥80% | ✅ | 2026-09-03 · `de0eb314`,合入 develop `b75fbe26` | + +## 第 5 周(Day 21-25 ↔ FE D1-5 · FE-0) + +> 双轨表列:任务 · 产出物 → 验收标准(须 100% 逐条通过才可标 ✅) + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day21 开户接口:业务位掩码+bcrypt+事务(账号+配置行+授信流水)
▸ api/v1/account.go · service/account · entity/account | 开户三表同事务落库;密码 bcrypt(cost≥10);业务位掩码还原正确;重复用户名返业务码 | ✅ | D1 Vite+Vue3+TS 脚手架/ESLint/目录规范/.env
▸ web/ 工程骨架+README | pnpm dev 一键起;pnpm lint 0/0 | ✅ | 后端 09-03 `6748d20d` · 前端 09-03 `26ba2895` | +| 2 | Day22 账号 CRUD 全量+禁用即 Token 失效
▸ api/v1/account.go · service/service.go | 过滤分页/详情/启停/删除守卫正确;禁用账号存量 Token 立即 401 | ✅ | D2 Axios 封装+msw Mock
▸ utils/request.ts · api/types.ts · mocks/ | Mock 登录返 ISC:000;401 拦截跳登录(单测) | ✅ | 后端 09-03 `29416feb` · 前端 09-03 `26ba2895` | +| 3 | Day23 IP 白名单(JSON/CIDR)+审核模式(0/1/2)+业务开关
▸ service/config_service.go | 白名单命中/未命中三态正确;审核模式切换生效;开关硬删防唯一冲突 | ✅ | D3 主布局(18 模块导航/顶栏/面包屑/多标签)+主题
▸ layouts/ · styles/ | 导航与需求模块地图一致;刷新不丢标签 | ✅ | 后端 09-04 `73e112da` · 前端 09-03 `26ba2895` | +| 4 | Day24 认证:登录 5 次锁 15 分/登出黑名单/刷新轮换
▸ service/auth/* · pkg/jwt(Sign 加 jti) | 正确密码返 Token;错 5 次锁 15 分;登出即失效;刷新轮换不互伤 | ✅ | D4 登录页+Pinia+路由守卫
▸ views/login · stores/user · router/guard | 登录→工作台→登出闭环(Mock);未登录重定向 /login | ✅ | 后端 09-04 `b645ce6f` · 前端 09-03 `26ba2895` | +| 5 | Day25 Casbin 策略同步+权限中间件+二级权限
▸ middleware/permission.go · casbin 扩展 · /accounts/export | customer 导出 403 ISC:403;admin 200 CSV;授予 export 即时放行/撤销收回;改角重绑 | ✅ | D5 动态路由+v-permission+错误页
▸ directive/permission · views/error | admin/customer 两角色实测隐藏无权菜单与按钮 | ✅ | 后端 09-04 `8a0322ed` · 前端 09-03 `26ba2895`;FE-0 合并 develop `36701945` | + +## 第 6 周(Day 26-30 ↔ FE D6-10 · FE-1,🚧 阶段 2 验收) + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day26 充值接口:单笔/CSV 批量/余额查询
▸ api/v1/account.go · service/recharge.go · balance_log | 充值即余额+流水一致(事务);批量 CSV 行级报错定位;无 recharge 二级权限 403 | ✅ | D6 账号列表(搜索/分页 12+ 列/批量启停标星/导出)
▸ views/account/list | 与 /api/v1/accounts 分页排序一致;空态/加载态完整 | ✅ | 后端 09-04 `899d5c6a` · 前端 09-03 `11a30594` | +| 2 | Day27 余额预警定时任务(cron+企微/钉钉 webhook)
▸ pkg/cronx · pkg/notify · service/warning.go | 余额低于阈值触发通知;同账号冷却期内不重复;定时器可停启 | ✅ | D7 开户表单(多业务线/四协议/单价时间线/授信/IP/审核模式)
▸ views/account/create | 分步校验与后端 util 同规则;提交后列表可见 | ✅ | 后端 09-04 `66b1fbbe` · 前端 09-03 `11a30594` | +| 3 | Day28 上级切换(级联路径)/标星/服务团队/实名审核流转
▸ service/hierarchy.go · service/profile.go | 切换上级后级联路径正确(无环);审核流转状态机合法 | ✅ | D8 账号详情+配置(业务矩阵/签名限制/推送地址/切换上级)
▸ views/account/detail | 只读/编辑分区清晰;保存后二次进入回显正确 | ✅ | 后端 09-04 `1507d20e` · 前端 09-03 `11a30594` | +| 4 | Day29 审计日志拦截器+查询接口+account 单测 ≥85%
▸ middleware/audit.go · service/audit · api/audit_handler.go | 写操作 100% 留痕(who/what/when);按账号/IP/时间检索;覆盖率达标 | ✅ | D9 充值与余额(单笔/批量/流水/预警)
▸ views/account/recharge | 流水与 balance_log 一致;无权限按钮隐藏(v-permission) | ✅ | 后端 09-04 `deb75560` · 前端 09-03 `11a30594` | +| 5 | Day30 🚧 阶段 2 验收:Postman 全量回归+联调+openapi.yaml
▸ api/openapi.yaml · 阶段 2 验收单 | A-2.x 全过;前端 FE-1 切真实 API 联调一致;openapi.yaml 与实现零偏差 | ✅ | D10 角色权限(权限树/Casbin)+登录审计;🚧 FE-1 验收=A-2.x 联调
▸ views/account/roles · views/audit/login | 权限树勾选→菜单/按钮实时生效;审计可按账号/IP/日期检索 | ✅* | 后端 09-04 `e35ec818`(A-2 全过;联调契约已备,FE 切换待联调窗口) · 前端 09-03 `11a30594`(*Mock 联调) | + +## 第 7 周(Day 31-35 ↔ FE D11-15 · FE-2) + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day31 CMPP 协议:连接/Login/心跳
▸ internal/protocol/cmpp(header/body/client) | 与模拟网关握手成功;心跳超时断连重试 | ✅ | D11 上家管理(CRUD/分类/联系人)
▸ views/channel/provider | CRUD 联调一致;表单校验完整 | ✅* | 后端 09-04 `ec1e75e0` · 前端 09-04 `49b18383`(D11 验收:Mock 契约+编辑/校验补齐;lint 0/0+27/27+build;真实 API 待后端 /channels/upstreams) | +| 2 | Day32 CMPP Submit/Deliver 解析/连接池
▸ protocol/cmpp(submit.go · readLoop · pool.go) | Submit 返 msg_id;Deliver 解析回执/上行;池化复用无泄漏 | ✅ | D12 通道列表(协议/状态筛选/启停/连接测试/20+ 字段)
▸ views/channel/list | 筛选/启停/连接测试(Mock)可用;列 20+ | ✅* | 后端 09-04 `e3191241` · 前端 09-04 `5ad64a12`(列 9→21;Mock 通道 7 端点+测试) | +| 3 | Day33 HTTP 通道适配器+SGIP 基础
▸ protocol/httpadapter · protocol/sgip | 可配置鉴权(appkey/签名)命中;SGIP bind/submit 打通模拟端 | ✅ | D13 通道新建/编辑(四协议分区/拦截配置/模板 ID 模式)
▸ views/channel/form | 四协议动态表单;保存回显正确 | ✅* | 后端 09-04 `dec172fb` · 前端 09-04 `5ad64a12`(回显改单查 get;协议类型修复) · 09-05 V2.0 迭代:后端实体 16 字段+测试工具 sp_id 映射 `728d4298`;前端六折叠面板/模板预填/sp_id≤6B 校验/新字段回显(Mock 契约 8 新用例,39/39) `fe-tailwind` | +| 4 | Day34 SMPP 协议(Bind/Submit/Deliver/EnquireLink)+连接池流控
▸ protocol/smpp(pdu/bind/client) | Bind 成功;流控窗口限速生效;链路探测保活 | ✅ | D14 通道组+四步路由配置器(拖拽排序/权重可视化)
▸ views/channel/group | 拖拽排序持久化;权重和=100% 校验 | ✅* | 后端 09-04 `41362c07` · 前端 09-04 `5ad64a12`(权重和实时显示+超 100 拒;优先级上下移排序持久化——拖拽以移位降级,已留痕) | +| 5 | Day35 通道 CRUD+测试工具+拦截配置(夜发/日限/屏蔽地区)
▸ service/channel · api/channel_handler.go | CRUD 全量;测试工具发测试短信成功;拦截三配置生效 | ✅ | D15 策略中心 5 页(黑白名单/关键字/频次/白名单/码号)
▸ views/policy/* | 5 页 CRUD+批量导入可用;列表筛选正确 | ✅* | 后端 09-04 `bce59e3f` · 前端 09-04 `5ad64a12`(五 Tab+批量导入+频次/码号 CRUD;策略 Mock 全套) | + +## 第 8 周(Day 36-40 ↔ FE D16 · FE-2 收尾,🚧 阶段 3 验收) + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day36 通道组+权重路由(7:3 偏差 <5%)+优先匹配+默认兜底
▸ service/router(SWRR) · service/channel/group.go | 1000 条分配偏差 <5%;无匹配走兜底通道 | ✅ | D16 导流策略+签名/码号报备;🚧 FE-2 验收=A-3.x 联调
▸ views/policy/traffic · views/policy/report | 报备流转状态正确;FE-2 六页联调(阶段 3 窗口) | ✅* | 后端 09-04 `7c65bd94` · 前端 09-04 `5ad64a12`(Report.vue 新建:提报→审核→驳回重提状态机+路由注册) | +| 2 | Day37 四步路由引擎(过滤→优先→权重→兜底)
▸ service/router/engine.go | 全分支单测覆盖;全链路 <10ms | ✅ | —(FE-3 未启动) | — | ⬜ | 后端 09-10 `085a3474`(Step1 条件过滤:黑关键字/地区/运营商/频次/签名;engine 单测全分支;叠 Day36 SWRR+兜底构成四步全链) | +| 3 | Day38 导流策略+价格时间线 API+估算余额定时器(2h)
▸ service/policy · cron/estimate | 导流命中规则正确;时间线取价按生效区间;估算误差可接受 | ✅* | — | — | ⬜ | 后端 09-10 `b101c9cf`(Step0 steer:account/keyword 规则 CRUD+引擎消费+路由 REST;price_timelines 分时价 API;估算定时器;A-3.10/11 的计费侧验证顺延阶段 4——扣费链路未上线) | +| 4 | ~~Day39 通道告警+WS 监控+通道日志~~→**实际:CMPP 中文编码+UDH 分片+回执复核 WEB 闭环**
▸ protocol/cmpp(split/EncodeContent) · 回执复核页 | (原任务移入 Day 40 补位)GB 之外中文编码正确;长短信 UDH 分片可合并;回执复核 WEB 可查 | ✅ | — | — | ⬜ | 后端 09-10 `8c65225f`+根因两层修复 `d1f64275`/`c0ab7d57`(Msg_Length 4B→1B 纯 2.0;真网 3 条 DELIVRD 双闭环)+`a95b7ff8` 压测 10 万条零失败+`44225a51` 5000/3000 规划——Day 39 让位真网质量问题,更高优先级 | +| 5 | Day40 阶段 3 收官:**补位 A-3.12 告警(notify webhook 复用)+A-3.13 WS 实时监控(2s)+A-3.14 通道日志(channel_log 建表)** + A-3.5 真网断线重连演练 + 1000 条/秒路由压测
▸ 阶段 3 验收单(docs/phase3-review.md) | A-3.1~A-3.14 全过(A-3.10/11 计费侧注记顺延);1000 条/秒压测稳定;通道测试工具发测试短信成功;fe-tailwind 分支理顺合并 develop | ✅ | — | — | ⬜ | 后端 09-10 `4ca16173`:告警 link_down/fail_rate(cron 30s+断连事件即时,冷却去重)·WS 2s Hub(gorilla v1.5.3;静态段先于 :id 注册坑)+HTTP 快照·ChannelLog v7 真库迁移(连接逐条/提交回执 10s 窗口聚合)·A-3.5 可杀网关演练秒级重连留痕·压测 3 轮中位 p99 7.9~8.8ms<10ms 吞吐 1806/s·BootstrapLinks 装配补缺;验收单 phase3-review.md;26 包全绿 | + +## 第 9 周(Day 41-45 ↔ FE D17-21 · FE-3) + +> 📋 **v2 人工验收**:本表「验收日期 / 更新明细」列=人工验收记录(✅A/❌+验收人);每任务收官产出 `docs/acceptance/dayNN.md`,走查通过才解锁下一任务(协议 1.5 节)。 + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day41 Submit DTO+发送校验器+模板 CRUD+占位符解析
▸ service/send(SubmitReq+Validate+Estimate) · service/template(CRUD/状态机/Render) · /templates+//send/estimate
另:开工三债清零(typecheck 9→0/openapi 字典 codegen 48 码/upstreams API) | 长度拆分与前端一致;变量/签名校验拒绝路径正确;模板状态机合法 | ✅A | D17 群发工作台(号码/TXT 导入预览前 50 行/本地+服务端双预估)
▸ views/sms/batch | 文件预览前 50 行;条数/拆分与后端 SmsLength 一致 | ✅A | 2026-09-10 **✅A 收官**(验收单 #1~#10+R1~R3 全过);首走揭真缺陷 2:v8 迁移缺列(#6 模板 500)、#2/#3 计费口径未含签名→需求两变:①签名并入计费 ②去独立签名框(sign 可选,内容=签名+正文一体);FE 51 tests;commit `3ba34ee7`→`12fd5bbc` | +| 2 | Day42 拦截器链:黑名单三级/频次滑动窗口/签名/退订/地区
▸ service/interceptor/*(+SendBlockLog v9 落库+/send/precheck 真入口;另修 P1④⑤ flaky:SGIP 超时 5s/QPS 线 12.5ms 余量) | 五类拦截各有单测;命中顺序符合配置;拦截原因落库 | ✅A | D18 个性短信(变量表格)+拆分短信+模板联动
▸ views/sms/personal | 变量校验({name} 规则);模板套用预览 | ✅A | 2026-09-10 **✅A 收官**(验收单 #1~#10+R1~R3 全过;interceptor 13 测+API 集成 1 测;/policies 查明为 D15 纯 FE mock,造数走库直插;+ISC:036 codegen 49;FE 57 tests;29 包全绿 EXIT=0) | +| 3 | Day43 审核服务:免审/手动/自动+48h 超时扫描回退余额
▸ service/audit | 三模式分流正确;超时自动回退余额且幂等 | ✅A | D19 定时发送(批量重置/可取消改期)
▸ views/sms/timer | 定时任务列表可取消/改期(联调) | ✅A | 2026-09-11 **✅A 收官**(协议 v3 首单:#1~#10+R1~R3 过;一轮 W1/W4 ✅、W2/W3 ❌→修复循环方案 B:vite proxy 8081→8080+最小提交链 POST /send/submit 提前落地+batch 提交按钮,二轮 W2/W3/W5/W6 全 ✅ 签名;+submit_test 5 例;码表 51;FE 60 tests;29 包全绿 EXIT=0;Day44 范围调「文件入口+个性精检」) | +| 4 | Day44 群发(批次 batch_id)/个性短信/文件解析(TXT/CSV/Excel→MinIO)
▸ service/send/* · util/fileparse | 批次进度可查;个性变量一一对应;文件解析行数一致 | ✅A | D20 模板管理(报备/批量审核/状态流转)
▸ views/sms/template | 模板状态流转(待审/通过/拒绝)实时刷新 | ✅A | 2026-09-11 **✅A 收官**(范围调「文件入口+个性精检」之文件入口:POST /files/numbers/import 三格式解析→归一去重→MinIO 落对象+PUT /templates/batch-review;+excelize/minio-go 依赖;pkg/storage+util/fileparse+fileimport 新模块;30 包 0 FAIL;D20 模板管理页+batch 导入升级,FE 67 tests;真环境三格式/批量审核/MinIO 对象全通;W1~W5 一轮+W6 二轮(修复:导入入口信息标签)走查全 ✅ 签名 Tory) | +| 5 | Day45 定时短信(Redis ZSet+5s 扫描)+批量重置
▸ service/send/timer.go | 到点 5s 内发出;重置批量生效;重复扫描幂等 | ✅A | D21 审核中心(五类 Tab 聚合/批量通过拒绝/48h 标红)
▸ views/audit/center | Tab 计数徽标;批量操作后列表与计数联动;超时样式区分 | ✅A | — | + +## 第 10 周(Day 46-50 ↔ FE D22-23 · FE-3 收尾,🚧 阶段 4 验收) + +> 📋 **v2 人工验收**:同第 9 周注记;Day 48-50 无新页面,验收形态=数据/日志/压测报告走查。 + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day46 HTTP API 提交接口(api_sign 签名)+callback/up 绑定+扩展码
▸ service/openapi · /sms/api 协议域 | api_sign 防重放/防篡改;错误签名 401;扩展码透传 | ✅A | D22 发送结果反馈(task_no/失败明细/ISC 中文表)
▸ views/sms/result | 提交返 task_no;ISC 码→中文映射与后端 48 码同步 | ✅A | 2026-09-11 · day46.md #1~#12+W1~W6 三轮走查闭环全 ✅(签名 Tory) | +| 2 | Day47 CMPP/SMPP 客户接入+合包聚合器(5s/1000 条)
▸ service/access + protocol server | 协议接入鉴权通过;聚合窗口触发正确 | ✅A | D23 短信聚合页+移动端走查;✅A FE-3 验收=A-4.x 联调
▸ views/sms/home | 四种发送方式可提交;审核流可闭环;移动端走查表 | ✅A | 2026-09-11 · day47.md #1~#9 机器项全 ✅(CMPP/SMPP 真机冒烟+聚合单测 99.9% 削减+门禁全绿);W1~W5 用户走查一轮全过(「全部验收通过」)→ 双 ✅A 收官,解锁 Day48;调度器④⑤挪 Day48(用户裁决) | +| 3 | Day48 发送全流程串联(API→预扣→审核→拦截→路由→Kafka)+submit 消费者
▸ service/send/pipeline · consumer/submit | 全流程状态机单测;Kafka 入队成功;失败各环节回退余额 | ✅A | — | — | ⬜ | 2026-09-11 · day48.md #1~#12 机器项全 ✅(状态机 7 例[预扣/拦截退费/全拦终态/拒绝退费/落库对冲/定时不投/个性同构]+消费者 6 例[认领幂等/域过滤/回滚/**ReclaimScanner 修复审核通过即发**]+调度④⑤ 6 例[令牌桶/窗口 256/p50 降速/PaceBudget]+背压+批量 writer 6 例;真机四链路:task33 成功路径[**channel_log submit=1 合包+deliver=2 上游回执**]/task32 频次拦截退费[余额扣3退3]/task35 审核拒绝退费[refund+1]/背压水位键 bp:level=0;**附带修复**:router 空组降级默认通道[原 404]+queue MaxRetry=0 死信 panic;cmd/consumer 新进程+Makefile run-consumer;openapi.emit 移除防双投;go 32 包 0 FAIL/vet 0,FE 79/79 无回归;冒烟数据已还原);**用户走查确认 2026-09-12,✅A 闭环,解锁 Day49** | +| 4 | Day49 上行码号分配(精确>前缀)+上行 Kafka+视频短信
▸ service/uplink | 上行按码号精确/前缀两级匹配;视频短信 biz_type 路由 | ✅A | — | — | ⬜ | — | 2026-09-12 · day49.md #1~#12 机器项全 ✅(码号两级匹配 6 断言[精确优先>最长前缀>兜底 admin=1]+Ingest 落库投递 sms-up+消费者 15 天窗口回填 match_task_id[幂等]+通道 MO 接线[报告不派发/读循环零阻塞]+video 校验/开通/落库/事件 11 断言;**迁移 v11**[uplink_code 表+task.business;dev 库实证 v9→v11 连升并补 v10 缺失 call_data];真机三链路:上行三级匹配[精确/前缀/兜底归属逐条核对]+Kafka 全链[consumer 回填 match_task_id=33]+视频短信[未开通 ISC:403 余额不动→开通受理 business=video 预扣 1 条,附带 video 任务经 consumer 下发完成=与 sms 链路完全兼容];go 33 包 0 FAIL/vet 0,FE 79/79 无回归;冒烟数据全还原);**2026-09-13 语义走查补签**:用户三裁决(①admin 兜底全量不加开关 ②窗口外落库存档 ③video 人工开通)为判定基准,S1~S6 全 ✅ 无缺陷(归属仅由 dest_code 决定与下行解耦/dest_code 存通道原码号=Day59 推送基准/15 天窗口含端点+雪花 ID 排序等价时序/Day52 上行解码衔接实证);8 用例当日回放全 PASS,详见 day49.md 走查记录段 | +| 5 | Day50 🚧 阶段 4 验收:100 并发压测
▸ 压测报告+阶段 4 验收单 | P99 <50ms;成功率 >99.9%;A-4.x 全过 | ⬜ | — | — | ⬜ | — | + +## 第 11 周(Day 51-55 ↔ FE D24-26 实做·方案 A 顺延 2 日 · FE-4) + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day51 🚀R3 拦截器请求级缓存+批量 IN(Day50 性能债专项 1/4)
▸ interceptor/scope.go 请求级快照(策略/签名一次加载跨号复用+白名单/黑名单 IN 批查+Redis SMIsMember 批量) | 100 号 SQL 2 次而非 200(SQL 计数断言);批量 P50 915ms→<200ms | ✅A | D24 下行批次记录(筛选/进度占比/拦截号码下载)→**未动,顺延 Day53**(方案 A)
▸ views/record/down | 分页 100/页流畅;进度条与后端计数一致 | ⬜ | 2026-09-12 **✅A 收官**(后端;scope_test 3 例:SQL 实测 **3 vs 旧路径 400**(Day50 口径×2 系漏计,旧路径实为每号 4 查)/语义回归零漂移/签名 1 次 vs 101 次;500TPS×2 轮 P50 211/190.8ms 达标<200ms,基线 915ms 降 79.1%,100% 成功,59000 明细全终态;坑:限流 env 全称 RATE_PER_SEC/孤儿压测进程→day51.md 三;FE D24 未动) | +| 2 | Day52 🚀R2 明细移 consumer 批量落库(专项 2/4;入口零明细写,回归方案 10.4.3 原文)
▸ send/submit 事务瘦身(仅落 task)+SubmitEvent 载明细(雪花 ID 入口预生成)+consumer 批量 INSERT 幂等 | 入口 P50<50ms;5min 压测明细数=任务计数(最终一致);回执配对零丢失;**Σtask.fee_total=loadtest billed_total** | ✅A(功能)/⚠️P50 | D25 下行明细(号码级/CMPP 钻入/ISC 筛选)→**未动,顺延 Day54**(方案 A)
▸ views/record/detail | 明细与批次钻取链路正确;ISC 码筛选联调 | ⬜ | 2026-09-13 **✅A 功能收官**:入口零明细写+Details 随事件(雪花 ID 预生成/拦截终态行)+消费侧 500/批 OnConflict 幂等(**先于 claim=回执配对键先于 submit 存在**);投递语义反转——定时/全拦亦投(claim 三重域保证不误发);Kafka 故障降级同步落明细;真机三轮(1960/1260/350 号)**明细数=任务计数全终态+三表对平**(11480/5880/1610=billed);**顺带修 4 存量缺陷**:Dispatch 无 status 过滤(拦截号重复下发)/聚合器丢错误码/loadtest 字节索引(**前置日「成功」实为 GBK 全灭假阴性——终态≠成功,验收必须核错误码**)/空跑防御(ErrDetailsNotReady 回滚重扫,420 悬置实证收敛);**首核项定论**:submit 聚合量纲=合包后 CMPP 包数≠计费片数(4706 vs 11480,比值=合包率),负载核算以计费条数为准;⚠️P50 dev 未达标(724~2055ms,宿主盘 w_await 25ms/%util 47%+回执/channel_log 写风暴+fsync 串行;代码路径三重佐证无退化)→Day55 复测先核盘 IO 基线;**午后:压测乱码根因=MsgFmtGBK 0x15 笔误(应 0x0F=15,Day39 引入)修复+上行 MO 按 Msg_Fmt 解码补齐+协议数值独立断言(上游日志 msgFmt=15/正常中文/msgLength=30 三重实证)**;→day52.md | +| 3 | Day53 🚀R1 资金一致性评审(预扣 Redis 化)+runbook P0 告警通道(顺延自 Day50 验收段)
▸ 评审纪要 · alertmanager+前端错误上报 | 过会三点:Redis/MySQL 双写窗口/AOF everysec 丢 1s 容忍/流水为唯一事实源余额可重算;告警通道通(R1 对账差额告警前置) | ✅A | **D24 下行批次记录**(方案 A 开工;Day60 record API 前契约先行 mock)
▸ views/record/down | 分页 100/页流畅;进度条与后端计数一致 | ✅A | 2026-09-13 **双 ✅A 收官**:①评审三点全过(docs/review/r1-balance.md:双写窗口=Redis 防超扣权威/MySQL 最终账务权威,偏小=少发不超扣;AOF everysec 丢 1s 容忍附三前置(生产 AOF/对账≤5min/flag 回退);流水为唯一事实源 balance(t)=Σamount 可重算+差额走 runbook §3 订正)+**Day54 约束 8 条固化**(Lua 原子/GOSMS_BALANCE_MODE flag/差额 gauge go_sms_balance_reconcile_diff/告警规则前置已挂/流水批写不丢/dev 开 AOF/Lua P99<5ms);②§6.2 Alertmanager 通道真机验通——compose 监控栈(prometheus 19090+alertmanager 19093)+规则三条(5xx 突增 P0/P99 P1/**BalanceReconcileDiff P0 接入位**;Kafka lag+通道速率指标未导出注记挂账 Day55/56)+AM webhook→gateway POST /alerts/sink(P0=Error/P1=Warn/resolved=Info 分级留痕;注入 P0/P1 各一条 firing→网关日志 alerts_sink_alert_received 2 条实证);③§6.4 前端错误上报——后端 POST /fe-errors(public 恒 200 尽力而为+截断+kind 归一)+v12_fe_error_log 迁移(**顺带补齐 dev 库 v10/v11 欠账,v9→v12**)+GET 排障端点;FE error-reporter(window error/unhandledrejection/VueHandler 三路+keepalive+60s 去重+防递归)+request.ts 拦截器 5xx/网络层上报带 X-Trace-Id;真机 curl→fe_error_log 落库;④**D24 开工**✅:api/record.ts 契约+fe4-handlers(种子 12 批次+拦截明细+**五段聚合自证**)+views/record/down(五段堆叠进度条/拦截 CSV 下载/分页 100)+记录中心路由分组;契约 7/7+guard 28 菜单;坑:jsdom XHR+blob 与 msw 不兼容(同 fe2 multipart 坑,fetch 直取);nohup 网关随会话被杀→setsid 保活;AM 注入须带未来 endsAt;→day53.md | +| 4 | Day54 🚀R1 预扣 Redis Lua+异步对账+故障回退(专项 4/4)
▸ send/refund.go Lua 化(balance:{account} check-and-decrement)+对账任务+feature flag | 50 并发×100 号零超扣零少扣(对账差额=0);Lua 路径 P99<5ms;kill Redis 回退 MySQL 原路径可用 | ✅A | **D25 下行明细**(号码级/CMPP 钻入/ISC 筛选;mock 先行)
▸ views/record/detail | 明细与批次钻取链路正确;ISC 码筛选联调 | ✅A | 2026-09-13 **双 ✅A 收官**;R1=balance 三件套(Store 接口/MySQLStore 平移+Fallback 业务错透传·基建错回退计数/RedisStore Lua check-and-decrement+key 缺失快照冷启+异步流水批写 4096/200/300ms 雪花预生成 OnConflict 幂等=无 DLQ 组件达 DLQ 语义/Reconciler FlushPending→Σ流水重算→diff gauge 覆写前采样→覆写 Redis→订正快照)+send 六处收口+gateway 装配(5m 对账/15s 热切/优雅排空)+config/metrics 四指标;**8 约束逐条真机验证**:50 并发零超扣零少扣/kill Redis 回退 3 发+fallback=3/5m 对账 diff=3→覆写+gauge 归零/AOF everysec 显式+重启余额保留实证/Lua P99=965µs(串行口径;8 并发 11837QPS;50 并发尾延迟=单线程排队数学必然注记)/流水幂等重投;**FlushPending 竞态三轮修复终局=flusher 纯 tick+锁内循环排空**(取出写入全程持锁,数学无窗口);**种子语义**:初始余额须带 recharge 流水(流水唯一事实源,否则对账「正确地」覆写);D25=record-progress.ts 拆分(修 mock 连带 axios/router 初始化致 vi.mock hoist 失效)+ISC 码字典联动+CMPP timeline 钻入;go 34 包(-race+count=3)+FE 93/93+tsc 零错;→day54.md | +| 5 | Day55 🚀性能债复测归档(上午:_bench 重建 tmpfs 正式场 5min,A-4.20 补账)+回执消费者+状态归一化起步(下午)
▸ docs/acceptance/day51-54.md · consumer/report | 批量 P50<30ms/受理 ≥4000TPS(单副本;5000 需按方案扩 2~3 副本);A-4.20 补账归档;**内容口径=loadtest 随机模式(【盈讯网络】长短信 1~9 条,均条≈5 ⇒ submit 负载×5,通道 speed/在途窗口/费用余量按此重核算,与 Day50/51 基线对比须注记口径变更)** | ✅A(吞吐+归档)/⚠️P50 | **D26 历史记录**(>5 天 ClickHouse <3s/异步导出;mock 先行)
▸ views/record/history | 查询 <3s;导出去下载中心 | ✅A | 2026-09-13 **✅A 收官**:①tmpfs 正式场复刻(day50 备份+R1 生效模式)——**受理 3960/4000TPS 满载 11880 请求 100% 成功零 429**(对照 Day50 硬顶 1600=**容量+150%**),billed 595.92 万条均条 5.01 口径自证,R1 余额 Redis=MySQL 列=Σ流水**三处一元 2038056**(首轮 400 万 t≈204s 耗尽即正确拦截——**压测余额预算=TPS×时长×均条×2**);②⚠️P50 未达(满载 504/空载 91ms/百号)——**非三债回归**(空载证明 R1/R2/R3 全生效),**第四瓶颈定位**:批内逐号串行 3 次 Redis RT(频次 INCR×2+预扣 Lua)≈0.9ms/号+容量贴线排队→立项合批 Lua/并行分片(阶段 5 后性能批次),A-4.20=吞吐✅延迟❌双判定诚实归档 day51-54.md;③**kafka_lag 挂账清偿**:go_sms_kafka_lag{topic}+KafkaLagHigh P1(>10 万 for 2m)+gateway LagReader 15s 采样——**新坑备案:sarama NextOffset 对 coordinator fetch 失败静默-1 与未起步组不可区分**(压测期 gauge 冻结假值 20125,明细增速交叉证伪),根治 OffsetFetchRequest 直连挂账 Day56;④回执归一化**起步**:report/normalize.go 三态(SUCCESS/FAILURE/UNKNOWN 挂起=资损安全)表驱动 12 断言——Day56 地基;⑤坑:pkill -f 匹配 run_commands 自身命令行整链夭折→`[b]in/xxx` 正则规避;tmpfs 备份库流水(Σ=-1232)与快照(400 万)不自洽→启动对账轮「正确地」覆写 -1232→**补 adjust 调差流水三平**(runbook §3 姿势);FE D26 全套(契约/mock 状态机/页面/6 测)99/99+tsc 零错;→day55.md | + +## 第 12 周(Day 56-60 ↔ FE D27-D29+Day60 联调收口 · FE-4 收尾;阶段 5 验收顺延 Day64 见第 13 周注记) + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day56 回执消费者+状态归一化(SUCCESS/FAILURE/UNKNOWN)+错误码维护接口完成;并入回执持久化挂账(环形缓冲→channel_log)+**长短信段级回执配对**(1~9 片 UDH 每段独立 msg_id,按 detail 聚合段数判终态——09-13 小跑实证 detail 状态已闭环,但 channel_log 聚合量纲 450 vs 520 待核)
▸ consumer/report · 错误码表 API | 三态归一正确;错误码可维护(增改停用);重启后回执可查(持久化);长短信 9 片段回执聚合终态正确 | ✅ | **D27 上行记录**(码号/手机号查询/权限导出;15 天匹配后端 Day49 已交付)
▸ views/record/uplink | 15 天窗口提示;无权限导出按钮隐藏 | ✅ | 2026-09-14 **✅A 收官**:①回执链路全程贯通——handleDeliver 状态报告 goroutine 派发 ReportSink→sms-report→`-report` 独立消费组(三态归一化+**段级配对**[v13 message_report_seg:msg_id+mobile 唯一,提交侧单发/合包「包×片」逐段登记]→按 detail 聚合判终态[任一 FAILURE→3/全 SUCCESS 到齐→2/其余挂起]+message_report 落库[uk_detail 冲突忽略]);②**9 片段聚合 9 用例**(8 片挂起→到齐成功/任一片失败整条失败/UNKNOWN 中间态/首到终态锁定[乱序异态不翻转]/无配对挂起不重试/合包多号独立置态);③错误码维护 `/system/error-codes` 增改停用(system:write,与归一化词表解耦);④回执持久化=receipts 改读 seg+uplink(**重启后回执可查**),内存环形降级;⑤**lag 根治**:OffsetFetchRequest V1 直连 coordinator(ErrAlreadyConnected 语义坑:client 连接池 broker 二次 Open 属正常,errors.Is 修正),真机 gauge 18569 正常;⑥**端到端真机闭环**:sarama 直投 sms-report→消费→detail 1→2+report 落库(冒烟数据已清);⑦合包失败回退只重发未确认号(修复 Day47 全量回退重复计费风险);FE D27 上行记录(15 天窗口提示/码号尾号匹配态筛选/uplink:export 权限导出)106/106+tsc 0;→day56.md | | +| 2 | Day57 计费确认:预扣转实扣/失败退款/msg_id 幂等
▸ consumer/billing(**基于 Day54 R1 Redis 预扣新口径**) | 预扣=实扣+退款(零差额);msg_id 重复回执幂等 | ✅A 09-14 | **D28 回执重推工具+手动配对页**(mock 先行)
▸ views/record/repush | 30 天窗口校验;任务提交反馈;配对结果回写列表 | ✅A 09-14 | — | +| 3 | Day58 回执重推(30 天窗)+手动配对(四方式)+异步任务
▸ service/repush | 30 天窗口校验;四方式配对结果正确;任务状态可查 | ⬜ | **D29 下载中心**(任务/进度/下载)+定时记录管理;🚧 FE-4 页面开发收官
▸ views/record/download | 异步任务状态轮询;记录四页+两工具可用 | ⬜ | — | +| 4 | Day59 回复"拒收"自动拉黑(上行消费者+15 天匹配 **Day49 已交付**仅剩拉黑)+回调推送引擎(指数退避重试)+CMPP Deliver 推送
▸ consumer/uplink · service/callback | 拒收关键词命中即拉黑;推送失败退避重试;最终失败落死信可查 | ⬜ | FE-4 自查收口(契约用例补齐+MSW 回归;真实联调待 Day60 API) | 契约用例全绿 | ⬜ | — | +| 5 | Day60 下行批次/明细 API(5 天热数据 Redis 缓存)+状态聚合
▸ api/v1/record.go · cache 层 | 热数据命中缓存;状态聚合计数准确 | ⬜ | 🚧 FE-4 联调+验收=A-5.x(D24-D26 mock 页面接真实 API:批次/明细/历史) | 记录四页+两工具联调可用 | ⬜ | — | + +> **⚠️ Day50 排期变更(2026-09-12,压测后裁决)**:R1~R3 性能债专项占 Day51-54+Day55 上午(4.5 日,详见 Day50 验收单三),阶段 5 主线顺延——**阶段 5 余量落位 Day61-64**(Day61 历史查询 ClickHouse+冷热切换 / Day62 异步下载 MinIO+export 权限+定时管理 / Day63 视频记录体系 biz_type 路由+记录单测 / **Day64 🚧 阶段 5 验收**,验收标准同原 Day60 行:A-5.x 全过;回执计费零差额;上行归属准确;历史查询 <1s)。**下方第 13 周起后端任务整体后移 4 日**:本表 5 行实际落位 Day65-69(统计消费者 Day65/七维统计 Day66/看板接口 Day67/下家结算 Day68/上家结算 Day69);第 14 周→Day70-74(阶段 6 验收 Day74);第 15/16 周→Day75-84(80 日框架 +4 日,由阶段 7 灰度段缓冲压缩吸收,不可吸收则在阶段 6 验收时复盘)。**2026-09-15 复盘修正:Day65 被消费并发修复(生产救火)占用,阶段 6 本表 5 行再落位 Day66-70 起、第 14 周→Day71-75——+4 日弹性已透支 1 日,「不可吸收则复盘」条款触发,阶段 6/7 重排方案(压缩/延期/救火缓冲制度化三选一)待用户裁决,裁决前阶段 6 不开工。****2026-09-16 用户裁决:先做阶段 5 收尾(P0 流程止血→C1 回调推送引擎/C2 拉黑/C3 D28 回执重推+手动配对后端/C4 record API 联调+A-5.x 关门),阶段 6/7 重排待收尾实际耗时后再定。2026-09-24 进展:P0 止血+Day61-65 补账归档已毕(develop→main v4);C3 完成(Day66:四端点+终态链单一实现+实机验收 ✅A,含实机发现的 ctx 断开丢回写/逐条慢两 P1 修复,详见 day66.md)——阶段 6 起点再顺延,重排裁决时点=收尾 C1/C2/C4 毕。****FE 轨道(D30 起)不受后端顺延影响**(msw mock 并行开发,联调窗口随后端 API 后移),故下方 FE↔后端周对齐自第 13 周起错位 4 日,表内 FE 列维持原节奏。 + +## 第 13 周(Day 61-65 ↔ FE D30-34 · FE-5) + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day61 统计消费者(stats_minute 预聚合入 ClickHouse)
▸ consumer/stats | 预聚合值=明细手工汇总;乱序/重复消费幂等 | ⬜ | D30 图表基座(ECharts 封装/过滤栏/自适应)
▸ components/charts | 空/加载态统一;路由切换无内存泄漏 | ⬜ | — | +| 2 | Day62 七维统计查询+Redis 缓存(TTL 1h)+补算定时器
▸ api/v1/stats.go · service/stats | 七维下钻数据正确;缓存命中;补算可指定日期 | ⬜ | D31 用户统计(趋势/七维下钻/XLS 导出)
▸ views/stats/user | 图表与明细抽 3 日核对一致;导出 XLS | ⬜ | — | +| 3 | Day63 用户/通道统计看板接口+ECharts 适配
▸ api/v1/stats 扩展 | 与 stats_channel_daily 一致;估算余额计算正确 | ⬜ | D32 通道统计(成功率/耗时/估算余额/告警配置)
▸ views/stats/channel | 趋势与后端一致;告警阈值保存生效 | ⬜ | — | +| 4 | Day64 下家结算:月度账单(成功条数×单价)+XLS 导出+确认付款
▸ service/settle/bill | 账单=成功条数×单价(抽样对账零差);确认付款状态流转 | ⬜ | D33 结算 4 页(下家账单/上家账单/结账/单价追加)
▸ views/settle/* | 账单金额与后端一致;状态流转清晰 | ⬜ | — | +| 5 | Day65 上家结算:对账单+单价追加锁定+上家切换归档
▸ service/settle/provider | 单价追加后旧数据锁定;切换归档不可逆操作留痕 | ⬜ | D34 利润分析(双视角)+消耗/充值日志
▸ views/settle/profit | 利润曲线与手工核算一致;日志可追溯操作人 | ⬜ | — | + +## 第 14 周(Day 66-70 ↔ FE D35-36 · FE-5 收尾,🚧 阶段 6 验收) + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day66 利润分析引擎(用户级含代理返点/通道级/趋势)
▸ service/settle/profit | 利润与手动核算一致;下级代理分成正确 | ⬜(阶段 6 未开工,2026-09-16 裁决收尾优先;Day66 实际=阶段5收尾 C3:D28 回执重推/手动配对后端 ✅A 09-24,见 day66.md;本行任务随阶段 6 重排落位) | D35 主页工作台+系统配置 4 页+日志报表
▸ views/home · views/system/* | 工作台 5s 内加载;错误码表与后端种子一致 | ⬜ | — | +| 2 | Day67 消耗日志日汇总+充值日志/审核流程
▸ cron/usage · service/recharge_audit | 消耗汇总与余额变动匹配;充值审核通过余额实时增加 | ⬜(阶段 6 未开工,重排待裁决;Day67 实际=明细查询单表化根治 Count 29.5s→亚秒+派生表 JOIN 改相关子查询 ✅A 09-28,见 day67.md;本行任务随阶段 6 重排落位) | D36 通讯录/短语/常用号码+预警公告;🚧 FE-5 验收=A-6.x
▸ views/tools/* | 三工具页可用;FE-5 全阶段页面联调通过 | ⬜ | — | +| 3 | Day68 工作台聚合接口(今日量/余额/待审数/7 日趋势)
▸ api/v1/dashboard | 主页 5s 内加载;待审数与审核表一致 | ⬜(阶段 6 未开工,重排待裁决;Day68 实际=运营总览 /home 真实数据后端 stats_daily 汇总表+/stats/summary·trend ✅A 09-28,见 day68.md;本行任务随阶段 6 重排落位) | — | — | ⬜ | — | +| 4 | Day69 结算单测(阶梯/退款冲正)+三方对账+操作手册
▸ 结算测试集 · docs/settle-manual | 对账差异率=0;覆盖率 ≥80% | ⬜(阶段 6 未开工,重排待裁决;Day69 实际=入向长短信 UDH 全链路支持+回执并发竞态三轮根修+unpaired 重投自愈+百万级压测监测就绪 ✅A 09-28,见 day69.md;本行任务随阶段 6 重排落位) | — | — | ⬜ | — | +| 5 | Day70 🚧 阶段 6 验收:全量回归(阶段 0-6)
▸ 阶段 6 验收单 | A-6.x 全过;全量回归无异常 | ⬜(阶段 6 未开工,重排待裁决;Day70 实际=长短信计费少计根修(fee≡上游真实片数)+存量 21837 条清偿 ✅A 09-28,见 day70.md;阶段 6 验收随重排落位) | — | — | ⬜ | — | + +## 第 15 周(Day 71-75 ↔ FE D37-39 · FE-6) + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day71 Staging 搭建(1:1 减半)+迁移+脱敏数据(10 万账号/50 通道)
▸ Staging 部署清单 | Pod 全启;/health 200;数据量达标 | ⬜(阶段 7 未启动,重排待裁决;Day71 实际=入向长短信挂起制 72h「不齐不发,到期失败」终态制(v19/restore/reaper) ✅A 09-29,见 day71.md;Staging 搭建随阶段 6/7 重排落位) | D37 全站权限矩阵走查(五角色×全菜单)+Mock 下线
▸ 权限矩阵走查表 | 五角色走查截图归档;无越权入口 | ⬜ | — | +| 2 | Day72 全量冒烟+压测(200 QPS×30min)记录性能基线
▸ 性能测试报告 | P99 <50ms;CPU <70%;无 OOM;GC <10ms | ⬜ | D38 性能优化(懒加载/首屏 LCP <2s/单包 <500KB)
▸ 性能报告(web-vitals) | 首屏 LCP <2s(内网);chunk 单包 <500KB | ⬜ | — | +| 3 | Day73 生产环境就绪(36 表/Topic 分区/Redis Cluster LRU)
▸ 生产就绪检查单 | show tables 36 张;Kafka 连通;Redis 策略生效 | ⬜ | D39 CI 集成(test→build)+镜像(nginx)+kind 部署
▸ CI 配置 · web/Dockerfile · nginx.conf | CI 绿;容器化部署 kind Dev 通过(NodePort 30081) | ⬜ | — | +| 4 | Day74 灰度发布(Ingress Header 5% 分流)+监控
▸ 灰度发布配置 | canary Header 进灰度 Pod;错误率与基线差 <1% | ⬜ | — | — | ⬜ | — | +| 5 | Day75 灰度 20%+回滚演练
▸ 灰度验证记录 | 20% 流量指标正常;回滚演练成功 | ⬜ | — | — | ⬜ | — | + +## 第 16 周(Day 76-80 ↔ FE D40 · 🚧 生产总验收) + +| # | 后端任务 · 产出物 | 后端验收标准(100% 过) | 状态 | 前端任务 · 产出物 | 前端验收标准(100% 过) | 状态 | 验收日期 / 更新明细 | +|---|---|---|---|---|---|---|---| +| 1 | Day76 灰度 50%(成功率 >99%/结算无误差)
▸ 中流量验证记录 | 50% 流量成功率 >99%;结算零误差 | ⬜ | D40 Playwright 冒烟 10 用例+验收会议+文档归档;🚧 FE 总验收
▸ e2e/ 10 用例 · docs/frontend-review.md | 冒烟全绿;50 页走查表全过,零 P0 缺陷 | ⬜ | — | +| 2 | Day77 全量切换(旧系统只读+双写比对)
▸ 切换记录 | 全量稳定 2h;新旧系统数据完全一致 | ⬜ | — | — | ⬜ | — | +| 3 | Day78 旧系统下线+历史数据迁移 ClickHouse+定时任务全开
▸ 下线与迁移记录 | 旧系统零流量;迁移完成;定时任务正常 | ⬜ | — | — | ⬜ | — | +| 4 | Day79 混沌工程(Kill Pod/网络延迟,RTO <30s)+上线总结
▸ 混沌测试报告+上线总结 | 自动恢复 RTO <30s;Kafka 重平衡无丢失 | ⬜ | — | — | ⬜ | — | +| 5 | Day80 🚧 生产验收评审+交付文档归档+KT 会议
▸ 最终交付清单 | 所有验收项通过;交付物完整;KT 完成 | ⬜ | — | — | ⬜ | — | + +--- + +## 已完成验收档案(证据索引) + +| 验收项 | 日期 | 结论与证据 | +|---|---|---| +| A-0.x 阶段 0 | 2026-09-03 | 全链路回归通过;合并 develop `7b46b312`;详见 CHANGELOG 阶段 0 段 | +| A-1.1~A-1.15 阶段 1 | 2026-09-03 | 评审报告 docs/phase1-review.md 逐项证据映射;13 包 -race 全绿;lint 0;合并 develop `b75fbe26` | +| A-2.7 登录流程(Day 24) | 2026-09-04 | 正确密码返 Token;错误 5 次锁 15 分;登出即失效;auth 包覆盖 90.4%(`b645ce6f`) | +| A-2.5/A-2.6 权限引擎(Day 25) | 2026-09-04 | customer 导出 403 ISC:403 / admin 200 CSV;二级权限授撤即时生效;17 包全绿+lint 0;casbin 覆盖 80.8%(`8a0322ed`) | +| Day 26 充值(Day 26) | 2026-09-04 | customer 充值 403/admin 200 余额落账;批量行级定位(4 行 2 成 2 败);并发 10×100 无丢失;越权查余额 403(`899d5c6a`) | +| Day 27 余额预警 | 2026-09-04 | 阈值触发单轮通知;冷却去重(3 轮 0 重复);失败下轮重试;授信计入可用额度;调度器可停启;API 越权 403(`66b1fbbe`) | +| Day 28 账号辅助能力 | 2026-09-04 | b 切挂 root 子孙路径级联重写/旁支不变;防环 400 路径零改动;标星列表置顶;实名状态机(驳回可重提/通过终态 400);越权 403(`1507d20e`) | +| Day 29 审计日志 | 2026-09-04 | 充值留痕 who/what/when 全字段;GET/400/401 不记而 export 记;登录成败各 1 条;查询五过滤+分页;customer 403;account 覆盖 87.0%(`deb75560`) | +| A-2.1~A-2.13 阶段 2 验收(Day 30) | 2026-09-04 | TestPhase2E2E 全链路(真登录/四协议/业务线/白名单/审核模式/角色隔离/二级权限/充值/预警/删除守卫/导出/实名/登录审计)全过;openapi.yaml 27p/35op 与实现一致;无阻塞项(`e35ec818`) | +| Day 31 CMPP 基础协议 | 2026-09-04 | 模拟网关握手 status=0;密钥错→ErrLoginRejected;心跳往返计数一致;静默→超时断连→恢复自动重连二次登录;21 包全绿;cmpp 覆盖 81.6%(`ec1e75e0`) | +| Day 32 CMPP 完整协议 | 2026-09-04 | Submit 返 msg_id(Result 0/1);状态报告全字段+上行原样解析;Deliver_Resp 自动回×2;池 2 连接并发 10 提交全成功;修复 ParseDeliver 偏移错位;cmpp 覆盖 85.9%(`e3191241`) | +| Day 33 HTTP+SGIP | 2026-09-04 | HTTP 三鉴权(appkey/sign/none)命中与拒绝全分支+message_id 解析;SGIP bind/submit Result=0、Report 全字段解析+自动回应答;httpadapter 90.6%/sgip 83.0%(`dec172fb`) | +| Day 34 SMPP+流控 | 2026-09-04 | Bind OK/错密码拒;窗口 2×慢网关 80ms 并发 8:在途峰值=2 全成功;窗口满→ErrWindowFull;enquire 保活 ≥2 次;回执/上行解析+自动回 resp×2;smpp 83.9%(`41362c07`) | +| Day 35 通道管理 | 2026-09-04 | CRUD 六断言全过;四协议测试工具连通拿 MsgID(777/up-88/up-35);夜发 -1/地区前缀 -2/日限计满 -3;customer 403;25 包全绿;channel 86.0%(`bce59e3f`) | +| Day 36 路由基础 | 2026-09-04 | SWRR 7:3×100 条=70/30 偏差 0(<5%);1100 条 770/330;关键字/省份/运营商命中+双命中取高优先;组内→全局兜底→ErrNoChannel;组五类校验+双守卫;router 96.0%(`7c65bd94`) | +| Day 37 路由引擎 Step1 | 2026-09-10 | 黑关键字/地区/运营商/频次/签名五类过滤全分支单测;过滤→SWRR→兜底全链 <10ms;engine 叠加 Day36 构成四步闭环(`085a3474`) | +| Day 38 导流+分时价 | 2026-09-10 | steer 规则 CRUD(类型白名单/account 须 account_id/keyword 须 config/通道存在性/停用跳过取次优)+REST 四端点(channel:write);price_timelines 分时区间取价;估算余额 2h 定时(`b101c9cf`) | +| Day 39 CMPP 编码+回执闭环 | 2026-09-10 | EncodeContent GBK/ASCII+UCS2 占位;UDH 长短信分片拆合;回执复核 WEB 页闭环(`8c65225f`) | +| 空内容根因双闭环(Day 39 修复链) | 2026-09-10 | 第一层删 3.0 独有 type 字段 `d1f64275`(通道方复测仍空);第二层 Msg_Length 4B→1B(2.0 Octet String) `c0ab7d57`——1B 宽度模型唯一解释两次空内容;黄金 dump @138=0x22/193B;真网 3 条 DELIVRD 全 ~3s 内精确匹配 msg_id(A-3.2+A-3.4 双闭环);26 包 -race ok | +| Day 39.5 压测基线 | 2026-09-10 | cmppbench 工具(~310 行:随机号/限速/CSV/JSON 摘要);10 万条 6 轮零失败零断链:8×4=266/16×8=490/32×16=861/64×16=1178/160=2573/256=3203 峰值 TPS;建议限流:连接 ≤16、在途 ≤64、常态 ≤720 TPS(`a95b7ff8`) | +| Day 39.6 性能规划合并 | 2026-09-10 | 5000 入/3000 出一收一发规划并入三文档:技术方案 10.4(实测基线表/数据流/各层容量/背压三级水位)+开发计划 Day46/47/48/50 硬数字+A-4.20~22;256 窗口实测持续 ~2263(3000=峰值口径);CHANGELOG NUL 字节治理(`44225a51`) | +| FE-0 验收 | 2026-09-03 | Mock 登录闭环/守卫/权限指令;22/22 测试;合并 develop `36701945` | +| FE-1 验收 | 2026-09-03 | 账号 6 页(Mock 联调);22/22 测试(`11a30594`) | +| FE-2 验收 | 2026-09-03 | 通道/策略 6 页;22/22 测试;**待合并 develop**(`6fb12ece`) | +| D11 上家管理验收 | 2026-09-04 | 修复后通过:补编辑入口(CRUD 之 U)+el-form rules(必填/电话格式)+Mock 契约 4 端点+测试 5 例;lint 0/0、Vitest 27/27、build 17s;登记 FE 存量 typecheck 债务 7 处(D39 前清零)(`49b18383`) | +| D12-D16 通道与策略验收 | 2026-09-04 | 修复后通过:Mock 15→51 端点(通道/组/策略/报备全契约);D12 列 9→21;D13 回显单查+类型修复;D14 权重和校验+排序持久化(拖拽降级移位,留痕);D15 批量导入+频次/码号 CRUD;D16 Report.vue 新建(报备状态机);lint 0/0、Vitest 31/31、build 17.52s(`5ad64a12`) | +| Day 40 阶段 3 收官 | 2026-09-10 | **A-3.x 全过**(`4ca16173`+phase3-review.md):A-3.12 告警 link_down/fail_rate(cron 30s+断连即时,冷却去重/失败重试)·A-3.13 WS 2s 快照帧(60s 滑窗 tps/fail_rate/latency_p50;gorilla v1.5.3)+轮询兜底·A-3.14 channel_log v7 真库迁移(连接逐条/提交回执 10s 窗口聚合——3000 TPS 防打爆,队列满丢弃不阻塞)·A-3.5 可杀网关演练秒级重连(<30s 线)+disconnect 留痕·1000QPS 3 轮 p99 中位 7.9~8.8ms<10ms·吞吐 1806/s·BootstrapLinks 装配补缺·26 包全绿(-race 抽查 ok);A-3.10/11 计费侧顺延阶段 4(扣费链路未上线) | +| Day 31 真实网关联调 | 2026-09-06 | **全链路打通**:CMPP 鉴权两轮修正(9×0x00 + Connect 包体 27B/4B 大端 Timestamp + 鉴权串 ts 十位 ASCII——authprobe 八变体实测命中 status=0);A-3.1 握手 66ms ✔/A-3.2 Submit 连续 6+ 条 result=0 返回真实 MsgID 27-32ms ✔/心跳 30s 周期应答 ✔/HTTP 测试工具 79ms ✔/Web real 全链路(5173→8081→MySQL)✔;工具:seed-admin 首启引导/v6 差量补列/cmd/probe 长连接探针/cmd/authprobe;提交链 `8479d985`;⏳ Deliver 回执长连接观察中、A-3.5 断线重连待网关侧配合演练 | +| FE-2 线上交付缺口修复 | 2026-09-04 | 线上实测仅 FE-0/FE-1:根因=FE-2 验收后未执行 L2 合并,phase3-channel 工作区无 channel/policy 页面且路由指向 ComingSoon 占位。修复:fe-channel→develop(`5a91cb86` 干净合并)→ 同步 phase3(`f3920f3a`);合并后三件套全过(lint 0/31/31/build 17.5s);线上重启实测 9 页面组件全 200(account×2/channel×4/policy×3)。教训:**L2 门禁"验收通过"必须当日内完成合并,验收≠交付** | +| D14/D15/D16 菜单不可见修复 | 2026-09-04 | 复核确认:D11/D14/D16 四路由(channel/upstream、channel/group、policy/route、policy/report)缺 menu:true 被侧边栏过滤;main.ts 未注册 icons(菜单图标空白)。修复:四路由补 menu+icon、icons 全局注册、guard 断言 18→22+四入口包含;31/31+build;线上 22 菜单/四路由 200(`ea5426ab`,cherry-pick develop `b79bd654`) | + +## 当前位置与下一步(2026-09-11 · Day 46 ✅A 收官,Day 47 解锁) + +- **🎉 Day 46 双 ✅A 收官**(外部 HTTP API 提交+D22 结果反馈页;走查**三轮闭环**全 ✅ 签名 Tory:一轮 ❌ env 模式覆盖坑→修复;二轮 W1/W2/W4 ✅+W5/W6 ❌→修复循环;三轮 W3②/W5/W6 全 ✅):**后端**——`service/openapi` 新包(SMS_HTTP_1.6 十八码表/MD5 验签 sign=MD5(user+ts+MD5(secret)) ±5min 常数时间比对/验签序:存在性不泄露→禁用→未开通→IP 白名单→时间戳→签名;SendMass 群发定时(sendTime 秒级,过去/超 15 天拒)+SendOne 个性(phone×content 等长≤1000),**复用 send.Submit/SubmitPersonal 全链**(余额/审核分流/雪花明细),extCode/callData rune 截断透传落库;sms-submit 事件经 queue.Producer 投递(失败仅日志,Day45 调度器 DB 认领兜底))+`/sms/api` 独立协议域(全局 IP 桶→验签 401→**账号桶动态容量**(middleware.RateLimitDynamic,speed_limit 请求期取,500/100 兜底))+GET/PUT /accounts/:id/api-config(reset_secret 重发 32hex 明文仅一次,库存 MD5;查看只回指纹前 8)+GET /send/tasks/:id/details(D22 数据源)+迁移 v10(**并修 CurrentMigrationVersion 字典序坑 v1016 连接);②UCS2(0x08)编码兜底;③回执持久化(Day56 并入回执消费者任务);~~④TestSGIP_Client 偶发~~(Day42 已修:Timeout 5s);~~⑤TestPick1000QPS 压测线无余量~~(Day42 已修:默认 12.5ms+STRICT 开关);~~⑥/data/sms 未提交改动~~(已丢弃 2026-09-10);~~⑦TestSMPP_BindAndSubmit 并发竞态~~(Day42 已修:轮询断言) +- **质量基线**:后端 go test ./... 29 包全绿 EXIT=0 · vet 0;前端 lint 0/0 · 60/60 测试 · typecheck 0 错 · build 通过 +- **门禁执行**:自 Day 26 起 L1 五件套自查;**Day 41 起升格六件套(+人工验收单全过归档,协议 v2);Day 43 起升格七件套(+前端用户本人走查,协议 v3)**;Day 39 例外已留痕 + +> 执行规范:分支 `feature/phase2-*`(后端)/`feature/fe-*`(前端)从 develop 拉出,按阶段合并;每次推送更新 CHANGELOG.md;本日历随每个工作日完成同步更新状态列;**任一任务验收未 100% 通过时,下一任务不得开工(见门禁协议)**。 diff --git a/memory-bank/docs/Go-sms-开发计划.md b/memory-bank/docs/Go-sms-开发计划.md new file mode 100644 index 00000000..d4622181 --- /dev/null +++ b/memory-bank/docs/Go-sms-开发计划.md @@ -0,0 +1,212 @@ +# Go-sms 开发计划 + +> **【文档状态】⛔ 已废止**(实际推进 Day 1-71,2026-09-29 终止;10 人团队假设同实施计划) +> 仅作历史归档;承上启下门禁清单思想由七件套继承。 + +> 本计划基于《分阶段落地实施计划》逐层拆解,**按工作日(人天)精确到天**,为每位Go开发工程师提供清晰的每日行动指南。 +> **核心原则**:每项任务产出必须可独立验证,**前序任务验收不通过,后续任务不得启动**,确保“环环相扣,承上启下”。 + +--- + +## 一、总体开发纪律与规范 + +| 规范项 | 具体要求 | +|--------|----------| +| **代码分支** | `main`(生产)← `release`(预发布)← `develop`(开发主分支)← `feature/xxx`(功能分支) | +| **Merge Request** | 必须包含:自测报告截图、接口变更说明、数据库变更脚本;至少1名Senior Approve | +| **单元测试** | 核心业务逻辑覆盖率 ≥ **80%**;`go test -race -cover` 必须全部通过 | +| **集成测试** | 每阶段结束后执行全链路集成测试(Postman/Newman或Go tests with `-tags=integration`) | +| **代码规范** | 严格执行 `go fmt`、`go vet`、`golangci-lint`(配置`revive`规则集) | +| **每日站会** | 9:30准时开始,每人1分钟:昨天完成 + 今天计划 + 阻塞点 | + +--- + +## 二、第0阶段:基础环境准备(第1~2周,共10个工作日) + +> **目标**:所有基础设施就绪,CI/CD跑通,本地一键启动开发环境。 + +### 第1周(Day 1 ~ Day 5) + +| 工作日 | 开发任务(Go程序员视角) | 产出物 | 验收标准 | +|--------|--------------------------|--------|----------| +| **Day 1** | ① 编写`Dockerfile`(基于`golang:1.22-alpine`,多阶段构建)
② 编写`docker-compose.dev.yaml`(包含:MySQL 8.0、Redis 7.0、Kafka(KRaft)、ETCD、MinIO、ClickHouse)
③ 编写`Makefile`(`make up` / `make down` / `make logs`) | `Dockerfile`,`docker-compose.dev.yaml`,`Makefile` | 执行`make up`后,6个容器全部`healthy`;`make down`完全清理 | +| **Day 2** | ① 初始化`go.mod`(`module hwsms`)
② 创建标准项目骨架:`cmd/`、`internal/`、`pkg/`、`api/`、`configs/`、`scripts/`、`deployments/`
③ 编写`configs/config.dev.yaml`(数据库、Redis、Kafka等DSN占位)
④ 实现`internal/config/loader.go`(Viper加载YAML + 环境变量覆盖) | 项目完整骨架,`go.mod`/`go.sum`,`config.dev.yaml` | `go mod tidy`无报错;`go build ./...`编译通过 | +| **Day 3** | ① 对接运维,获取K8s Namespace(`hwsms-dev`/`hwsms-prod`)
② 编写`deployments/base/deployment.yaml`(通用模板)
③ 编写`deployments/base/service.yaml`(ClusterIP + NodePort)
④ 编写`deployments/base/configmap.yaml`(环境变量注入) | K8s资源YAML文件 | 在Dev环境执行`kubectl apply -f deployments/base/`,Pod能Running(哪怕业务未完成,基础镜像起得来) | +| **Day 4** | ① 编写`.gitlab-ci.yml`(Stage:test → build → deploy-dev)
② 在`cmd/server/main.go`中写入健康检查`/health`端点(Gin框架最小实现)
③ 实现`internal/middleware/health.go`(返回`{"status":"ok"}`) | CI/CD流水线配置,健康检查路由 | Push代码触发CI,`test`阶段运行`go test ./...`通过,`build`阶段生成镜像,`deploy-dev`成功更新Pod;访问`/health`返回200 | +| **Day 5** | ① 实现`internal/pkg/logger/logger.go`(基于`zap` + `lumberjack`,JSON格式)
② 实现`internal/middleware/logger.go`(Gin请求日志,记录`trace_id`、`latency`、`status`)
③ 集成`go.uber.org/zap`,并写入`/var/log/hwsms/app.log` | 日志组件 | 发起测试请求,控制台和文件均输出结构化JSON日志;包含`trace_id`字段 | + +### 第2周(Day 6 ~ Day 10) + +| 工作日 | 开发任务(Go程序员视角) | 产出物 | 验收标准 | +|--------|--------------------------|--------|----------| +| **Day 6** | ① 实现`internal/pkg/redis/client.go`(`go-redis/v9`,支持Cluster模式)
② 实现`internal/pkg/redis/lock.go`(分布式锁,Lua脚本 + 自动续期`watchdog`)
③ 编写单元测试`redis_test.go`(使用`miniredis`模拟) | Redis客户端封装、分布式锁 | 单元测试通过;在开发环境执行`set/get`和`Lock/Unlock`成功 | +| **Day 7** | ① 实现`internal/pkg/queue/producer.go`(`Sarama`异步生产者,重试+死信)
② 实现`internal/pkg/queue/consumer.go`(消费者组,手动提交offset)
③ 定义Topic常量:`TopicSubmit`、`TopicReport`、`TopicUp`、`TopicStats` | Kafka封装 | 生产者发送消息成功;消费者接收并打印消息;无`ErrOutOfBrokers` | +| **Day 8** | ① 实现`internal/util/snowflake.go`(基于`sony/sonyflake`或自研,WorkerID从ETCD获取)
② 实现`internal/util/validator.go`(手机号、模板变量、内容长度校验)
③ 实现`internal/util/crypto.go`(AES-GCM加密/解密,用于API密钥) | 工具函数库 | `go test -cover ./internal/util/...` 覆盖率≥ **90%**;Snowflake并发测试无ID冲突 | +| **Day 9** | ① 实现`internal/middleware/ratelimit.go`(基于Redis + 令牌桶的分布式限流)
② 实现`internal/middleware/auth.go`(JWT解析 + Casbin权限校验接口预留)
③ 实现`internal/middleware/tracer.go`(OpenTelemetry + Jaeger上报) | 全套Gin中间件 | 限流中间件在触发阈值时返回`429`;Auth中间件对无效Token返回`401`;Jaeger UI能查看到Trace | +| **Day 10** | ① **阶段0全链路回归**:重启全部容器,执行`go test -tags=integration ./test/e2e/...`
② 完善`README.md`(含环境变量清单、本地启动步骤)
③ 编写`scripts/init_mysql.sql`(基础库表暂空,仅创建database)
④ **阶段0验收评审** | 阶段0交付物清单 | 所有A-0.x验收项全部通过;**阻塞条件**无遗留 | + +> **⚠️ 阻塞规则**:若Day 10 E2E测试失败,**全体暂停**,优先排查基础设施连接问题,直至通过方可进入第1阶段。 + +--- + +## 三、第1阶段:核心数据模型与公共组件(第3~4周,共10个工作日) + +### 第3周(Day 11 ~ Day 15) + +| 工作日 | 开发任务(Go程序员视角) | 产出物 | 验收标准 | +|--------|--------------------------|--------|----------| +| **Day 11** | ① 编写完整`scripts/init_schema.sql`(36张表DDL,含索引、外键约束)
② 生成GORM Entity:`internal/model/entity/account.go`、`channel.go`、`route_rule.go`、`message.go`等
③ 实现基础DAO接口:`Create`、`Update`、`GetByID`、`List`、`Delete`(软删除) | SQL脚本,Entity代码,BaseDAO | 在测试库执行SQL无语法错误;`AutoMigrate`能生成表结构 | +| **Day 12** | ① 实现`internal/config/etcd_watcher.go`(监听`/config/hwsms/*`,变更触发Viper热更新)
② 实现`internal/app/app.go`(启动器:加载配置→连接DB/Redis/Kafka→注册路由→启动HTTP Server)
③ 优雅停机实现(`http.Server.Shutdown` + 清理Kafka producer) | 配置热更新、应用启动器 | 修改ETCD配置,10s内应用日志输出"config reloaded";`kill -SIGTERM`后等待现有请求完成再退出 | +| **Day 13** | ① 实现`internal/pkg/metrics/prometheus.go`(注册`Counter`、`Gauge`、`HistogramVec`)
② 实现`internal/middleware/metrics.go`(请求数、耗时、错误率埋点)
③ 暴露`/metrics`端点 | 监控指标 | 访问`/metrics`,能看到`http_requests_total`、`http_request_duration_seconds`等指标 | +| **Day 14** | ① 编写数据库迁移工具:`cmd/migrate/main.go`(基于`gormigrate`,初始版本`v0`)
② 实现`internal/repository/mysql/mysql.go`(连接池配置:`MaxOpenConns=100`,`MaxIdleConns=20`)
③ 实现`internal/repository/clickhouse/clickhouse.go`(批量插入接口) | 迁移工具、存储层初始化 | 执行`go run cmd/migrate/main.go up`,表结构版本号写入`schema_migrations`表 | +| **Day 15** | ① 完善错误码定义:`internal/pkg/errors/codes.go`(映射UT:xxxx所有错误码及中英文描述)
② 实现统一响应封装:`internal/pkg/response/response.go`(`Success`、`Error`、`Page`)
③ 实现全局Recovery中间件(捕获panic,返回500,记录堆栈) | 错误码、响应封装 | 调用`response.Error(c, codes.Blacklist)`,返回JSON`{"code":"UT:0006","msg":"黑名单"}` | + +### 第4周(Day 16 ~ Day 20) + +| 工作日 | 开发任务(Go程序员视角) | 产出物 | 验收标准 | +|--------|--------------------------|--------|----------| +| **Day 16** | ① 编写`internal/pkg/queue/consumer_group.go`(优雅消费循环,支持暂停/恢复)
② 实现死信队列处理(消费失败3次后写入`*-dlq` topic)
③ 编写`internal/pkg/cache/multi_level.go`(本地缓存`freecache` + Redis,优先本地) | 高级队列、多级缓存 | 消费失败消息进入死信;缓存Get优先命中本地,Miss时查Redis | +| **Day 17** | ① 实现JWT生成/解析:`internal/pkg/jwt/jwt.go`(含`account_id`、`roles`、`permissions` claims)
② 实现Casbin适配器:`internal/pkg/casbin/enforcer.go`(策略存储在MySQL)
③ 编写`scripts/init_rbac.sql`(基础角色:admin/客户运维/客服/集团) | JWT、RBAC引擎 | 生成Token可正确解析;Casbin能校验`account_id`是否拥有`resource:action` | +| **Day 18** | ① 为所有公共组件编写`go doc`注释
② 编写`internal/pkg/README.md`(各组件使用示例)
③ 重构`internal/util`,拆分出`phone.go`、`content.go`、`template.go` | 文档、代码优化 | `golangci-lint run ./...` 0 warning;`go doc`能显示完整注释 | +| **Day 19** | ① **集成测试**:编写`test/integration/base_test.go`(启动testcontainer模拟MySQL/Redis/Kafka)
② 验证配置加载→DB连接→缓存读写→消息生产消费全链路 | 集成测试框架 | `go test -tags=integration ./test/integration/... -count=1` 全部PASS | +| **Day 20** | ① **阶段1代码评审**(全员CR)
② 修复Review问题,更新`CHANGELOG.md`
③ **阶段1验收会议** | 阶段1交付物 | A-1.1 ~ A-1.15 **全部通过**;单元覆盖率≥80%;**阻塞条件**无遗留 | + +--- + +## 四、第2阶段:账号与权限体系(第5~6周,共10个工作日) + +| 工作日 | 开发任务(Go程序员视角) | 产出物 | 验收标准(启动前确保阶段1完成) | +|--------|--------------------------|--------|--------| +| **Day 21** | ① 实现`internal/service/account/service.go`:CreateAccount(支持`protocol`、`business`位掩码)
② 实现`internal/api/http/v1/account.go`:POST `/api/v1/accounts`
③ 编写Account DAO扩展(根据协议/业务动态字段) | 账号创建接口 | 调用API创建HTTP/CMPP账号,数据库记录正确,密码自动bcrypt加密 | +| **Day 22** | ① 实现账号查询/列表(支持按`username`、`protocol`、`status`过滤)
② 实现账号更新(PUT `/api/v1/accounts/{id}`)
③ 实现账号状态切换(启用/禁用)
④ 实现账号删除逻辑(检查`last_send_time`,沉默或>60天可删) | 账号CRUD全量 | 禁用后Token失效;删除有发送记录账号返回业务错误;列表接口分页正常 | +| **Day 23** | ① 实现IP白名单绑定与校验(存储为JSON数组)
② 实现账号审核模式配置(`audit_mode`字段)
③ 实现多业务开通开关(`business`字段按位操作) | 账号配置扩展 | IP校验中间件生效;开启/关闭业务线,对应功能权限即时变更 | +| **Day 24** | ① 实现登录接口:POST `/api/v1/auth/login`(返回JWT)
② 实现登出接口(JWT加入Redis黑名单,TTL=剩余有效期)
③ 实现刷新Token接口 | 认证模块 | 正确密码返回Token;错误密码5次锁定15分钟;登出后Token立即失效 | +| **Day 25** | ① 实现Casbin策略同步(账号创建/角色变更时自动写入`casbin_rule`表)
② 实现权限中间件`internal/middleware/permission.go`(从Token获取Roles,调用`enforcer.Enforce`)
③ 实现二级权限标记(`recharge`、`proxy_send`、`export`等) | 权限引擎集成 | 普通账号访问`/api/v1/accounts/export`返回403;admin可正常导出 | +| **Day 26** | ① 实现充值接口:POST `/api/v1/accounts/{id}/recharge`(记录充值日志,需二级权限校验)
② 实现批量充值(CSV导入)
③ 实现余额查询接口 | 充值模块 | 充值后`balance_transactions`表生成记录,余额正确累加;无权限用户充值被拦截 | +| **Day 27** | ① 实现余额预警后台定时任务(`cron`每分钟扫描,低于阈值触发微信/短信)
② 实现预警配置接口(阈值/通知方式/接收人)
③ 集成企微/钉钉webhook推送 | 预警模块 | 将账号余额调至阈值以下,1分钟内收到webhook告警消息 | +| **Day 28** | ① 实现账号上级切换(`parent_id`更新,需级联更新下级路径)
② 实现账号标星(`is_starred`)
③ 实现服务团队绑定(`service_team`)
④ 实现实名认证信息存储与审核状态流转 | 辅助功能 | 切换上级后,权限继承正确;标星账号列表置顶;实名审核通过后账户状态变更 | +| **Day 29** | ① 实现审计日志拦截器(记录所有敏感操作:登录/充值/删除/导出)
② 实现审计日志查询接口(按账号/IP/时间范围)
③ 编写`test/unit/account_test.go`(覆盖所有业务逻辑) | 审计、单元测试 | 敏感操作均在`audit_logs`表有记录;`go test -cover ./internal/service/account/...` ≥ 85% | +| **Day 30** | ① **阶段2验收**:Postman集合全量回归
② 前端联调(如已准备)
③ 修复Bug,更新OpenAPI文档(`api/openapi.yaml`) | 阶段2交付 | A-2.1 ~ A-2.13全部通过;**无阻塞项**;接口文档与实现一致 | + +--- + +## 五、第3阶段:通道管理与路由引擎(第7~8周,共10个工作日) + +| 工作日 | 开发任务(Go程序员视角) | 产出物 | 验收标准 | +|--------|--------------------------|--------|----------| +| **Day 31** | ① 设计CMPP协议包结构:`internal/protocol/cmpp/header.go`、`body.go`
② 实现CMPP连接建立(TCP Dial + Login请求)
③ 实现心跳处理(ActiveTest/ActiveTestResp) | CMPP基础协议 | 可连接模拟器(如`cmpp-sim`),Login返回`status=0` | +| **Day 32** | ① 实现CMPP Submit(短消息提交)及Submit_Resp处理
② 实现CMPP Deliver(回执/上行)接收解析
③ 实现CMPP连接池:`internal/protocol/cmpp/pool.go`(含心跳协程) | CMPP完整协议 | 发送消息能收到Submit_Resp;模拟通道返回Deliver,解析正确 | +| **Day 33** | ① 实现HTTP通道适配器:`internal/protocol/http/adapter.go`(调用上游API,支持GET/POST,可配置鉴权方式)
② 实现SGIP协议基础(Submit/Report) | HTTP/SGIP适配 | 配置HTTP通道,成功调用上游发送接口并解析返回值;SGIP连接正常 | +| **Day 34** | ① 实现SMPP协议:`internal/protocol/smpp/`(Bind_Transceiver/Submit_SM/Deliver_SM/EnquireLink)
② 实现SMPP连接池及流量控制(Window Size) | SMPP协议 | 连接SMPP模拟器,提交消息成功,收到Deliver_SM | +| **Day 35** | ① 实现通道CRUD API:`internal/service/channel/service.go`
② 实现通道测试工具(发送单条测试短信验证通道连通性)
③ 实现通道拦截配置(`night_limit`、`day_limit`、`forbidden_regions`) | 通道管理 | 通道配置保存成功;测试工具发送通道返回正确MsgID;日限生效,超出返回-3错误 | +| **Day 36** | ① 实现通道组(Channel Group)实体及API
② 实现权重路由算法(加权轮询)
③ 实现优先通道匹配(关键字/省份/运营商)
④ 实现默认兜底通道 | 路由基础组件 | 通道组内权重7:3分发,发送100条偏差<5%;关键字匹配准确命中指定通道 | +| **Day 37** | ① 实现四步路由引擎Chain:`internal/router/engine.go`
② Step1过滤(频次/黑关键字/签名/地区/运营商)
③ Step2优先通道
④ Step3权重分发
⑤ Step4兜底 | 路由引擎 | 全链路路由选择能在10ms内完成;所有过滤条件命中对应错误码 | +| **Day 38** | ① 实现导流策略(按账号维度/内容维度配置)
② 实现通道价格时间线API(`price_timelines`表 CRUD)
③ 实现通道估算余额计算器(定时任务,2小时刷新) | 价格与导流 | 导流策略生效,特定账号走指定通道;价格时间线按当前时间返回正确单价 | +| **Day 39** | ① 实现通道告警规则配置及检测协程
② 实现通道通讯实时监控WebSocket推送(2秒刷新)
③ 实现通道日志记录(连接/断开/发送/回执) | 监控告警 | 手动断开通道,30s内触发告警并推送;WebSocket推送正常,页面2秒更新 | +| **Day 40** | ① 编写路由引擎单元测试(覆盖所有分支)
② 压力测试(模拟1000条/秒路由决策)
③ **阶段3验收** | 阶段3交付 | 路由引擎P99延迟<10ms;所有A-3.x通过;**阻塞条件**无 | + +--- + +## 六、第4阶段:消息发送主链路(第9~10周,共10个工作日) + +| 工作日 | 开发任务(Go程序员视角) | 产出物 | 验收标准 | +|--------|--------------------------|--------|----------| +| **Day 41** | ① 定义Submit DTO:`internal/model/dto/submit.go`
② 实现`internal/service/send/validator.go`(长度/模板变量/签名校验)
③ 实现模板CRUD及变量占位符解析(`{%var%}`) | 发送模型、模板引擎 | 模板匹配准确率100%;变量替换内容正确;超长内容自动拆分 | +| **Day 42** | ① 实现拦截器接口:`internal/service/send/interceptor.go`
② 实现黑名单三级检测(本地Redis Set + API调用 + 第三方通道)
③ 实现频次拦截(滑动窗口,支持自然日/24h)
④ 实现签名/退订/地区拦截 | 拦截器链 | 黑名单手机号返回UT:0006;频次超限返回UT:0016;地区屏蔽返回UT:0009 | +| **Day 43** | ① 实现审核服务:`internal/service/audit/service.go`
② 实现免审/手动/自动三种策略
③ 实现审核任务入队及48小时超时扫描器 | 审核工作流 | 免审直接通过;手动审进入`pending`;48h后自动设为失败并回退余额 | +| **Day 44** | ① 实现群发逻辑:单批次生成N条Message记录,共享`batch_id`
② 实现个性短信:每条独立内容,批量入库
③ 实现文件解析器(TXT/CSV/Excel),上传MinIO后异步解析 | 群发/个性/文件 | 群发10000条,批次记录完整;个性短信逐条内容不同;文件解析进度可查 | +| **Day 45** | ① 实现定时短信:`internal/service/send/timer.go`(基于Redis ZSet存储定时任务)
② 实现定时扫描器(每5秒扫描一次到期任务)
③ 实现批量重置定时时间 | 定时发送 | 设置定时2小时后发送,任务准确触发;批量重置成功取消原定时 | +| **Day 46** | ① 实现HTTP API提交接口:`POST /api/v1/sms/send`(含签名校验`api_sign`)
② 支持`callback_url`(回执绑定)和`up_url`(上行绑定)
③ 实现随机/固定扩展码分配
④ **入口双桶限流**:全局令牌桶(5000/s)+账号桶(`account.speed_limit`),Redis Lua 原子(技术方案10.4.3)
⑤ **同步链路禁令**:入口只做鉴权/校验/预扣/写Kafka,**严禁MySQL直写**(5000 TPS单条INSERT会打爆InnoDB) | HTTP API | 接口鉴权通过;回执和上行地址存储正确;扩展码分配正确;**5000 TPS下P99<50ms;超限返回429** | +| **Day 47** | ① 实现CMPP客户接入:验证企业代码+通道号前缀(`UT:0012`)
② 实现CMPP合包聚合器(每5秒或1000条聚合提交,降低HTTP通道压力)
③ 实现SMPP客户接入
④ **per-channel下发调度器**:令牌桶=`channel.speed`(默认3000)+在途窗口256(16连接×16,Day39实测背书见技术方案10.4.1);p50>50ms持续30s自动降速10%
⑤ **群发匀速投放器**:按下游预算逐秒投放(每秒min(剩余,Σ通道speed−在途余量)),防瞬时打满队列 | CMPP/SMPP接入 | CMPP提交通道号不匹配返回错误;合包后HTTP调用次数减少80%以上;**3000 TPS峰值零超速零失败** | +| **Day 48** | ① 实现发送全流程串联(API → 预扣费 → 审核 → 拦截 → 路由 → Kafka入队)
② 实现Kafka生产者写入`submit` Topic
③ 实现`cmd/worker/submit_consumer.go`(消费submit,执行实际通道下发)
④ **批量落库writer**:明细攒批500条/批×10并发writer(扛5000 TPS INSERT,技术方案10.4.3);Kafka key=`channel_id`(submit)/`detail_id`(report)保证通道顺序与回执配对
⑤ **背压三级水位**:lag>10万告警/>100万入口限流收紧至Σ(通道speed)/>500万暂停低优先级任务(技术方案10.4.4) | 完整提交链路 | 提交接口返回`batch_id`和`msg_ids`;消费者取出消息后调用通道Adapter下发成功;**MySQL批量写入不阻塞消费(lag不因落库增长)** | +| **Day 49** | ① 实现上行码号分配算法(精确匹配 > 前缀匹配,归属账号)
② 实现上行Kafka生产者及消费者
③ 实现视频短信发送(复用短信流程,内容含视频URL合帧) | 上行处理、视频发送 | 回复码号精确匹配归属正确账号;视频短信提交成功,通道收到合帧内容 | +| **Day 50** | ① 全链路压测:**入口5000 TPS持续5min**(JMeter/Gatling 100并发×N轮)+ **下发满载复验**(cmppbench 256窗口,对照Day39基线)
② **背压联动演练**:5000入/3000出打5min,验证lag收敛、L1~L3水位动作、限流429正确
③ 监控发送延迟(入口/下发分层统计)和成功率
④ **阶段4验收** | 阶段4交付 | **入口P99<50ms@5000TPS;下发均值≥2200/峰值≥3000 TPS零超速;背压三级水位联动正确;成功率>99.9%;所有A-4.x通过** | + +--- + +## 七、第5阶段:回执/上行与记录查询(第11~12周,共10个工作日) + +| 工作日 | 开发任务(Go程序员视角) | 产出物 | 验收标准 | +|--------|--------------------------|--------|----------| +| **Day 51** | ① 实现回执消费者:`cmd/worker/report_consumer.go`(消费`report` Topic)
② 实现状态归一化映射(运营商不同状态码 → 内部`SUCCESS`/`FAILURE`/`UNKNOWN`)
③ 实现错误码表维护接口 | 回执消费基础 | 收到`DELIVRD`映射为SUCCESS;`EXPIRED`映射为FAILURE;未知映射UNKNOWN | +| **Day 52** | ① 实现计费确认服务:`internal/service/balance/confirm.go`
② SUCCESS → 预扣转实扣(插入实扣流水)
③ FAILURE/UNKNOWN → 退还预扣金额
④ 实现幂等控制(基于`msg_id`防重) | 实扣/退款 | 回执处理后余额变化正确;重复回执不重复扣费;流水表记录完整 | +| **Day 53** | ① 实现回执重推服务(支持按`account_id` + `time_range`筛选,30天内)
② 实现手动配对状态(上传状态文件/直接指定状态/提取通道日志匹配)
③ 实现配对任务异步处理 | 回执重推、配对 | 重推后客户收到补发回执;配对上传文件后3h外无状态短信状态更新 | +| **Day 54** | ① 实现上行消费者:`cmd/worker/up_consumer.go`
② 实现上行匹配逻辑(15天内发送数据匹配,失败归admin)
③ 实现上行自动拉黑规则(回复"拒收R" → 加入黑名单,页面隐藏) | 上行处理 | 上行回复匹配成功归属账号;回复拒收后手机号进入黑名单,但上行记录仍推送 | +| **Day 55** | ① 实现HTTP回调推送引擎(带重试队列,指数退避)
② 实现CMPP Deliver推送(通过客户绑定连接)
③ 实现推送失败重试及日志 | 回调推送 | 客户回调地址收到标准JSON回执;CMPP客户收到Deliver包;推送失败进入重试队列 | +| **Day 56** | ① 实现下行批次记录API(5天热数据,Redis缓存)
② 实现下行明细API(号码级,5天热数据)
③ 实现批次状态统计聚合(成功/失败/未知/发送中) | 记录查询 | 查询今日批次返回完整统计;明细列表支持按状态/手机号过滤 | +| **Day 57** | ① 实现历史记录查询(ClickHouse,全量)
② 实现历史明细查询(支持大时间范围)
③ 实现路由层根据时间自动切换数据源(热数据查MySQL,历史查ClickHouse) | 历史数据 | 查询90天前数据,响应时间<1s(ClickHouse);5天内数据走MySQL | +| **Day 58** | ① 实现明细异步下载(提交下载任务→写入MinIO→生成下载链接)
② 实现下载权限控制(非admin需开启`export`二级权限)
③ 实现定时记录管理(取消/重置时间) | 下载中心、定时管理 | 下载任务异步生成,文件内容与查询结果一致;取消定时任务后不再触发 | +| **Day 59** | ① 实现视频记录体系(复用短信Record Service,仅`biz_type`区分)
② 统一记录查询路由(根据`biz_type`路由至不同表或同一表分区)
③ 编写记录查询单元测试 | 视频记录 | 视频短信记录独立查询正常,不影响短信记录 | +| **Day 60** | ① **阶段5集成测试**:模拟全流程(提交→回执→计费→查询→重推)
② 验证数据最终一致性(MySQL事务 + ClickHouse最终一致)
③ **阶段5验收** | 阶段5交付 | 所有A-5.x通过;数据一致性校验(抽样比对)无误;**阻塞条件**无 | + +--- + +## 八、第6阶段:统计与计费结算(第13~14周,共10个工作日) + +| 工作日 | 开发任务(Go程序员视角) | 产出物 | 验收标准 | +|--------|--------------------------|--------|----------| +| **Day 61** | ① 实现统计事件消费者:`cmd/worker/stats_consumer.go`
② 定义统计事件Schema(包含:account_id, channel_id, phone, province, operator, status, fee, report_time等)
③ 批量写入ClickHouse统计表(`stats_minute`预聚合) | 统计消费者 | 发送消息后,ClickHouse `stats_minute`表在5秒内出现聚合数据 | +| **Day 62** | ① 实现多维统计查询API(7维度:时间/用户/地区/运营商/签名/状态码/回执速率)
② 实现统计缓存(Redis,Key包含查询条件Hash,TTL=1小时)
③ 实现统计补算定时器(偶数整点刷新;昨日7/13/17补算) | 统计查询 | 按日/月查询统计,数据准确;缓存命中后响应<20ms;补算后数据修正 | +| **Day 63** | ① 实现用户统计看板接口(今日/昨日/近7天对比)
② 实现通道统计看板接口(成功率、耗时、量级)
③ 前端ECharts数据适配 | 用户/通道统计 | 看板数据与原始明细核对一致;通道成功率趋势图正确 | +| **Day 64** | ① 实现下家结算模型:`internal/service/settlement/client_settlement.go`
② 生成月度账单(聚合成功条数 × 用户单价)
③ 实现账单明细导出(XLS)
④ 实现账单确认/付款状态管理 | 下家结算 | 客户月度账单金额=SUM(success)*price;导出XLS格式正确打开 | +| **Day 65** | ① 实现上家结算模型:`internal/service/settlement/channel_settlement.go`
② 生成上家对账单(成功条数 × 通道成本单价)
③ 实现单价追加(历史账单锁定,新增单价不影响已结算账单)
④ 实现上家切换(旧通道关停,数据归档) | 上家结算 | 通道对账单金额正确;切换上家后新发送走新通道,旧记录仍可查 | +| **Day 66** | ① 实现利润分析引擎(下家总收入 - 上家总成本 - 运营成本)
② 实现用户级利润(含下级代理返点)
③ 实现通道级利润分析
④ 实现利润趋势图 | 利润分析 | 某时间段利润与手动核算一致;下级代理利润分成正确 | +| **Day 67** | ① 实现消耗日志定时汇总(每天凌晨2点汇总前一天按账号/业务的消耗)
② 实现充值日志查询(关联付款审核确认状态)
③ 实现充值审核流程(提交→审核→到账) | 日志查询 | 消耗日志表按日生成,与实时余额变动匹配;充值审核通过后余额实时增加 | +| **Day 68** | ① 实现主页工作台聚合接口(今日发送量/成功量/余额/待审核数)
② 实现发送类型占比(群发/个性/定时/文件)
③ 实现消息量趋势图(近7日) | 工作台 | 主页数据5秒内加载完成;待审核数与审核表一致;趋势图数据与统计表一致 | +| **Day 69** | ① 结算模块单元测试(覆盖阶梯价格、退款冲正场景)
② 执行结算数据对账(业务表 ↔ 统计表 ↔ 结算表)
③ 编写结算操作手册 | 测试、文档 | 对账差异率=0;单元测试覆盖率≥80% | +| **Day 70** | ① **阶段6集成验收**
② 执行全量回归测试(第0~6阶段所有核心流程)
③ **阶段6验收会议** | 阶段6交付 | A-6.1 ~ A-6.12全部通过;全量回归无异常;**阻塞条件**无 | + +--- + +## 九、第7阶段:生产上线与全网切换(第15~16周,共10个工作日) + +> **目标**:预发布环境验证 → 灰度发布 → 全量割接,保障平滑上线。 + +| 工作日 | 开发任务(Go程序员视角) | 产出物 | 验收标准 | +|--------|--------------------------|--------|----------| +| **Day 71** | ① 搭建预发布(Staging)环境,配置与生产1:1(规格减半)
② 执行数据库迁移(`migrate up`至最新版本)
③ 导入脱敏测试数据(模拟10万账号、50通道) | Staging环境 | 所有Pod启动成功;Staging数据库连接正常;`/health`返回200 | +| **Day 72** | ① 执行全量冒烟测试(所有P0/P1接口 Postman Collection)
② 执行压力测试(200 QPS持续30分钟,观察资源水位)
③ 记录性能基线(P99延迟、CPU/Memory、GC耗时) | 性能测试报告 | P99 < 50ms;CPU < 70%;无OOM;GC暂停 < 10ms | +| **Day 73** | ① 准备生产环境数据库(初始Schema + 基础配置数据)
② 配置生产Kafka Topic(分区数=节点数×3)
③ 配置生产Redis Cluster(maxmemory-policy allkeys-lru) | 生产环境就绪 | 生产数据库`show tables`返回36张表;Kafka producer/consumer连通性测试通过 | +| **Day 74** | ① 实现灰度发布策略(K8s Ingress按Header(`version: canary`)分流5%流量)
② 部署灰度版本(`v1.0.0-canary`)
③ 监控灰度版本日志和错误率 | 灰度环境 | 携带`version: canary` Header的请求进入灰度Pod;错误率与基线无显著差异(<1%) | +| **Day 75** | ① 扩大灰度比例至20%,持续观察2小时
② 验收灰度数据(数据库写入正确,无脏数据)
③ 若异常则立即回滚(`kubectl rollout undo`) | 灰度验证 | 20%流量下业务指标正常;无数据一致性问题;回滚演练成功 | +| **Day 76** | ① 灰度比例扩大至50%,观察4小时
② 监控上游通道状态,确认路由正确
③ 监控结算统计准确性(与预发布环境比对) | 中流量验证 | 50%流量下发送成功率>99%;结算统计无误差 | +| **Day 77** | ① 全量切换(100%流量指向新系统)
② 旧系统(汇网V6)配置为只读模式
③ 双写验证(新系统写入后对比旧系统查询结果) | 全量切换 | 全量流量下系统稳定运行2小时;新旧系统数据完全一致 | +| **Day 78** | ① 旧系统下线(关闭接入层)
② 迁移历史数据至ClickHouse(全量)
③ 开启生产环境所有定时任务(补算/预警/清理) | 旧系统下线 | 旧系统无流量进入;历史数据迁移完成;定时任务执行正常 | +| **Day 79** | ① 执行混沌工程测试(随机Kill Pod/网络延迟注入)
② 验证自动恢复能力(预期RTO<30s)
③ 编写上线总结报告(含性能对比、问题清单) | 混沌测试 | K8s自动重启Pod;Redis哨兵切换无感知;Kafka重平衡无数据丢失 | +| **Day 80** | ① **生产验收评审**
② 项目交付文档归档(架构文档/API文档/运维手册/操作手册)
③ 团队内部知识转移(KT)会议 | 最终交付 | 所有验收项全部通过;交付物完整;团队完成技能交接 | + +--- + +## 十、各阶段“承上启下”检查清单(阻塞门禁) + +> 在进入下一阶段之前,**必须完成**上一阶段的所有检查项,否则下一阶段不得开工。 + +| 阶段 | 入口门禁(必须满足) | 出口门禁(必须交付) | +|------|----------------------|----------------------| +| **阶段1启动** | 阶段0 A-0.x 全部通过,CI/CD能部署`main`分支 | 公共组件库单元覆盖率≥80%,数据库迁移工具可用 | +| **阶段2启动** | 阶段1 A-1.x 全部通过,ETCD配置热加载验证通过 | 账号CRUD+JWT+RBAC完整可用,审计日志有记录 | +| **阶段3启动** | 阶段2 A-2.x 全部通过,权限模型已验证 | CMPP/HTTP/SMPP通道可接入,路由引擎单元测试通过 | +| **阶段4启动** | 阶段3 A-3.x 全部通过,通道测试工具成功发送测试短信 | 群发/个性/定时/文件四种发送方式均可提交,Kafka入队成功 | +| **阶段5启动** | 阶段4 A-4.x 全部通过,Kafka `submit` Topic有消费 | 回执消费并正确计费,上行匹配归属性准确,历史查询<1s | +| **阶段6启动** | 阶段5 A-5.x 全部通过,计费确认/退款无差额 | 统计报表与业务明细一致,结算账单无误差,主页工作台可用 | +| **阶段7启动** | 阶段6 A-6.x 全部通过,全量回归测试PASS | 预发布环境性能测试达标,灰度切换成功,生产割接完成 | + +--- + +## 十一、开发资源分配建议(10人团队) + +| 角色 | 人数 | 负责阶段 | 关键职责 | +|------|------|----------|----------| +| **后端TL(架构师)** | 1 | 全阶段 | 技术方案决策、代码Review把关、阻塞问题攻坚、阶段验收主持 | +| **高级Go工程师A** | 1 | 阶段3/4/5 | 协议栈(CMPP/SMPP)、路由引擎、通道池、回执消费 | +| **高级Go工程师B** | 1 | 阶段1/2/6 | 公共组件、账号权限、统计结算、工作台 | +| **中级Go工程师C** | 1 | 阶段2/4 | 账号CRUD、发送API、审核工作流、模板管理 | +| **中级Go工程师D** | 1 | 阶段3/5 | 通道管理、记录查询、上行处理、重推配对 | +| **中级Go工程师E** | 1 | 阶段4/6 | 定时任务、文件处理、下载中心、消费者编写 | +| **初级Go工程师F** | 1 | 阶段0/1 | 协助环境搭建、编写单元测试、编写文档、Docker/K8s资源配置 | +| **前端工程师** | 2 | 阶段2~6 | 管理后台页面开发(与后端接口联调) | +| **测试工程师** | 1 | 全阶段 | 编写集成测试用例、执行全量回归、性能压测、验收协助 | + +--- + +> **最终交付承诺**:严格按照本计划执行,**每阶段结束时**均产出可部署、可演示的增量版本,80个工作日后具备完整生产上线能力。每日站会同步进度,每周五进行阶段里程碑Review,确保**环环相扣、零偏差**。 \ No newline at end of file diff --git a/memory-bank/docs/Go-sms-技术方案.md b/memory-bank/docs/Go-sms-技术方案.md new file mode 100644 index 00000000..0c3ffc3e --- /dev/null +++ b/memory-bank/docs/Go-sms-技术方案.md @@ -0,0 +1,1350 @@ +Go-sms 技术方案 + +> **【文档状态】✅ 重建架构基线**(判定 2026-11-12) +> §1-10 设计经 POC 实测修订后有效;**§11 项目结构以 POC 实际演化结构为准**(35 包 -race 全绿验证),差异裁决与强制结论见《Go-sms-重建设计规范.md》。 + +## 1. 总体架构设计 + +### 1.1 架构原则 + +| 原则 | 说明 | +|------|------| +| **高可用** | 多机房/多可用区部署,故障自动切换,降级熔断,数据多副本 | +| **低延时** | 本地缓存+Redis,连接池复用,异步非阻塞I/O,P99 < 50ms | +| **高并发** | 水平扩展,消息队列削峰,协程池管控,单机支撑10万QPS | + +### 1.2 整体架构图 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 接入层 (Ingress) │ +│ Nginx + LVS + Keepalived (四层/七层) │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 网关层 (Gateway) │ +│ Go Gateway (HTTP/CMPP/SMPP协议适配,限流/鉴权) │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 业务层 (Business) │ +│ ┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐ │ +│ │ 用户服务 │ 通道服务 │ 发送服务 │ 审核服务 │ 路由服务 │ 计费服务 │ │ +│ ├──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤ │ +│ │ 统计服务 │ 结算服务 │ 告警服务 │ 短链服务 │ 空号服务 │ CSP服务 │ │ +│ └──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘ │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 中间件层 (Middleware) │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ │ +│ │ Redis │ │ Kafka │ │ ETCD │ │ ES │ │ ClickHouse│ │ Prometheus│ +│ │(缓存/锁)│ │(消息队列)│ │(配置/服务发现)│ │(日志检索)│ │(历史统计)│ │(监控) │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └────────┘ │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 数据层 (Storage) │ +│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ +│ │ MySQL Cluster │ │ TiDB (历史数据) │ │ OSS/S3 (文件存储) │ │ +│ │ (业务主库+读写分离) │ │ (全量历史明细) │ │ (号码文件/报表) │ │ +│ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 上游通道层 (Upstream) │ +│ CMPP/HTTP/SGIP/SMPP 运营商直连 & 第三方通道 │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. 技术栈选型 + +### 2.1 核心框架与库 + +| 层级 | 技术选型 | 版本 | 选型理由 | +|------|----------|------|----------| +| Web框架 | **Gin** | v1.10+ | 高性能HTTP路由,中间件生态丰富 | +| 微服务框架 | **Go-kratos** 或 **Go-zero** | v2.7+ | 服务治理、可观测性、代码生成 | +| ORM | **GORM** + 自定义DAO | v1.25+ | 开发效率高,支持连接池和钩子 | +| 缓存客户端 | **go-redis/v9** | v9.5+ | 高性能Redis客户端,支持集群/哨兵 | +| 消息队列 | **Sarama** (Kafka) | v1.43+ | 高吞吐,支持Exactly-Once语义 | +| 服务发现/配置 | **ETCD** (clientv3) | v3.5+ | 强一致性,支持Watch和Lease | +| RPC框架 | **gRPC** | v1.64+ | 高性能二进制协议,多语言支持 | +| 日志 | **Zap** + **Lumberjack** | v1.27+ | 高性能结构化日志,自动切割 | +| 监控指标 | **Prometheus** client | v1.19+ | 标准指标采集,与Grafana集成 | +| 链路追踪 | **Jaeger** (OpenTelemetry) | v1.24+ | 分布式追踪,定位慢请求 | +| 并发控制 | **ants** (协程池) | v2.10+ | 控制协程数量,防止资源耗尽 | +| 配置管理 | **Viper** | v1.18+ | 多配置源支持,热加载 | +| 参数校验 | **go-playground/validator** | v10.20+ | 结构体标签校验,灵活扩展 | +| 限流器 | **uber-go/ratelimit** + 令牌桶 | - | 毫秒级限流,支持动态调整 | +| 熔断器 | **gobreaker** / **hystrix-go** | - | 故障隔离,快速失败 | + +### 2.2 存储与中间件 + +| 组件 | 用途 | 部署模式 | +|------|------|----------| +| **MySQL 8.0** | 用户、通道、配置、余额、结算等事务性数据 | 主从+读写分离,MGR高可用 | +| **Redis Cluster** | 缓存、分布式锁、实时计数、会话、限流令牌 | 集群模式,6节点+哨兵 | +| **Kafka** | 发送任务、回执、上行、统计事件、日志 | 3节点集群,分区副本≥2 | +| **ClickHouse** | 下行明细、上行记录、统计报表(历史+实时) | 分布式集群,多分片 | +| **Elasticsearch** | 操作日志、审计日志、查询检索 | 3节点集群 | +| **ETCD** | 服务注册发现、配置下发、分布式协调 | 3节点集群 | +| **MinIO/OSS** | 号码文件、报表文件、检测结果存储 | 分布式对象存储 | +| **Prometheus+Grafana** | 指标采集与可视化 | 单机/集群 | +| **SkyWalking/Jaeger** | APM与链路追踪 | 独立部署 | + +--- + +## 3. 模块详细设计 + +### 3.1 接入网关层 (Gateway) + +#### 3.1.1 多协议适配 + +```go +// 协议适配器接口 +type ProtocolAdapter interface { + ListenAndServe() error + HandleRequest(ctx context.Context, req interface{}) (resp interface{}, err error) + Shutdown(ctx context.Context) error +} + +// 实现:HTTPAdapter, CMPPAdapter, SMPPAdapter, SGIPAdapter +``` + +| 协议 | 实现方式 | 关键点 | +|------|----------|--------| +| HTTP | Gin路由,统一API前缀 `/api/v1/*` | 限流(令牌桶)、鉴权(JWT)、参数校验 | +| CMPP | 自定义TCP Server (v2.0/v3.0) | 连接池管理、心跳保活、窗口流控 | +| SMPP | 标准SMPP 3.4协议 | 长连接、收发分离、ESME绑定 | +| SGIP | 标准SGIP 1.2协议 | 短连接池、消息序列化 | + +#### 3.1.2 连接与并发控制 + +```yaml +gateway: + http: + max_connections: 10000 + read_timeout: 30s + write_timeout: 30s + cmpp: + max_connections_per_account: 50 + idle_timeout: 60s + window_size: 32 + smpp: + max_connections: 1000 + enquire_link_interval: 30s +``` + +#### 3.1.3 限流设计 + +```go +// 多维度限流 +type RateLimiter interface { + Allow(key string) bool // 全局限流 + AllowUser(userID string) bool // 用户级限流 + AllowChannel(channelID string) bool // 通道级限流 + AllowIP(ip string) bool // IP级限流 +} + +// 实现:Redis + 令牌桶 (Lua脚本原子操作) +// 前缀:rate_limit:{key}:timestamp, 窗口滑动 +``` + +### 3.2 路由与策略引擎 + +#### 3.2.1 四步路由实现 + +```go +// 路由链模式 +type RoutingChain struct { + Filters []Filter + Priority *PriorityRouter + Weighted *WeightedRouter + Fallback *FallbackRouter +} + +type Filter interface { + Apply(ctx *RouteContext) bool // true=过滤,跳过 +} + +// 四步路由 +// Step1: 条件过滤 (黑名单/黑关键字/签名/地区/运营商/频次) +// Step2: 优先通道 (省网分流/关键字匹配) +// Step3: 权重比例分发 (加权轮询) +// Step4: 默认通道兜底 +``` + +#### 3.2.2 规则存储与热加载 + +``` +规则存储结构 (MySQL): +┌──────────────────────────────────────────────┐ +│ route_rules (id, account_id, channel_id, │ +│ rule_type, rule_config, priority, status) │ +└──────────────────────────────────────────────┘ + ↓ (Watch) +┌──────────────────────────────────────────────┐ +│ ETCD: /config/routes/ {account_id} │ +│ 规则变更 → 监听 → 本地缓存更新 (10s内生效) │ +└──────────────────────────────────────────────┘ +``` + +### 3.3 消息发送核心 + +#### 3.3.1 异步发送流水线 + +``` +┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ +│ API接收 │ -> │ 提交预扣 │ -> │ 审核过滤 │ -> │ 路由匹配 │ +└─────────┘ └─────────┘ └─────────┘ └─────────┘ + │ +┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ +│ 状态回执 │ <- │ 通道发送 │ <- │ 消息队列 │ <- │ 消息组装 │ +└─────────┘ └─────────┘ └─────────┘ └─────────┘ + │ │ │ │ + ▼ ▼ ▼ ▼ + 计费确认 通道限速 削峰填谷 模板填充 +``` + +#### 3.3.2 消息结构与状态机 + +```go +// 消息实体 +type Message struct { + ID string `json:"id"` // 全局唯一ID (雪花算法) + AccountID string `json:"account_id"` + Business string `json:"business"` // sms/video/csp/empty + Phone string `json:"phone"` + Content string `json:"content"` + TemplateID string `json:"template_id"` + ChannelID string `json:"channel_id"` + Status MsgStatus `json:"status"` + SendTime time.Time `json:"send_time"` + SubmitTime time.Time `json:"submit_time"` + Fee int64 `json:"fee"` // 计费条数 + Price int64 `json:"price"` // 单价(毫) + ErrorCode string `json:"error_code"` + RetryCount int `json:"retry_count"` + Ext map[string]interface{} `json:"ext"` +} + +// 状态枚举 +const ( + Pending MsgStatus = 0 // 待提交 + Submitted MsgStatus = 1 // 已提交通道 + Succeed MsgStatus = 2 // 成功 + Failed MsgStatus = 3 // 失败 + Unknown MsgStatus = 4 // 未知(超时) +) +``` + +#### 3.3.3 发送流程伪代码 + +```go +func (s *SendService) Submit(ctx context.Context, req *SubmitRequest) error { + // 1. 参数校验 (手机号格式、内容长度、模板变量) + if err := s.validate(req); err != nil { return err } + + // 2. 预扣费 (Redis Lua原子操作) + if err := s.balanceService.PreDeduct(ctx, req.AccountID, req.EstimatedFee); err != nil { + return err + } + + // 3. 审核 (免审/自动/手动) + auditResult, err := s.auditService.Check(ctx, req) + if err != nil || !auditResult.Pass { + // 退回预扣费 + s.balanceService.Rollback(ctx, req.AccountID, req.EstimatedFee) + return auditResult.Error + } + + // 4. 频次/黑名单/地区检测 (拦截器链) + if blocked := s.interceptorChain.Process(ctx, req); blocked { + s.balanceService.Rollback(ctx, req.AccountID, req.EstimatedFee) + return ErrBlocked + } + + // 5. 路由选择 + routeResult, err := s.routeService.Select(ctx, req) + if err != nil { + s.balanceService.Rollback(ctx, req.AccountID, req.EstimatedFee) + return err + } + + // 6. 生成消息并写入Kafka (发送队列) + msg := s.buildMessage(req, routeResult) + if err := s.producer.Send(ctx, msg); err != nil { + s.balanceService.Rollback(ctx, req.AccountID, req.EstimatedFee) + return err + } + + // 7. 写入热数据 (Redis预写) + s.cache.Set(ctx, msg.ID, msg, 5*24*time.Hour) + + // 8. 写入ClickHouse异步 + s.asyncWrite.ClickHouse(ctx, msg) + + return nil +} +``` + +### 3.4 计费与结算 + +#### 3.4.1 预扣费+实扣费设计 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Redis Lua脚本 (原子操作) │ +│ 1. 读取账号余额 balance:account:{id} │ +│ 2. 检查余额 + 授信余额 >= 预估费用 │ +│ 3. 冻结预扣金额 (临时冻结) │ +│ 4. 返回预扣成功/失败 │ +└─────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ 回执到达 → 实扣 (异步) │ +│ 成功: 冻结金额 → 实扣记录 (SUCCESS) │ +│ 失败: 冻结金额 → 回退余额 (FAILURE) │ +│ 未知: 72h后超时释放 (UNKNOWN) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +#### 3.4.2 分时计价实现 + +```go +// 价格时间线存储 +type PriceTimeline struct { + AccountID string + Business string + Prices []PricePoint +} + +type PricePoint struct { + Price int64 `json:"price"` + StartTime time.Time `json:"start_time"` + EndTime time.Time `json:"end_time"` +} + +// 查询当前生效价格 +func (s *PriceService) GetCurrentPrice(ctx context.Context, accountID, business string) int64 { + key := fmt.Sprintf("price:%s:%s", accountID, business) + // 1. 本地缓存 (1分钟TTL) + if val, ok := s.localCache.Get(key); ok { return val.(int64) } + // 2. Redis缓存 (5分钟TTL) + // 3. MySQL查询 +} +``` + +### 3.5 审核工作流 + +```go +// 审核状态机 +type AuditStatus int +const ( + AuditPending AuditStatus = 0 // 待审核 + AuditPass AuditStatus = 1 // 通过 + AuditReject AuditStatus = 2 // 拒绝 + AuditAutoPass AuditStatus = 3 // 免审自动通过 + AuditTimeout AuditStatus = 4 // 超时失败 +) + +// 审核策略 +type AuditStrategy interface { + ShouldAudit(ctx context.Context, req *SubmitRequest) (bool, error) +} + +// 实现: NoAuditStrategy (免审), ManualAuditStrategy (人工审), AutoAuditStrategy (自动审) +``` + +**定时清理任务**: +```go +// 48小时超时审核自动失败 +func (s *AuditService) TimeoutCleaner(ctx context.Context) { + ticker := time.NewTicker(1 * time.Hour) + for { + select { + case <-ticker.C: + // 查询待审核>48h的记录,标记为失败,回退预扣费 + s.processTimeoutAudits(ctx) + } + } +} +``` + +### 3.6 通道管理 + +#### 3.6.1 通道连接池 + +```go +// 通道连接池 (CMPP) +type ChannelPool struct { + mu sync.RWMutex + conns map[string]*ChannelConnection + maxSize int + factory ConnectionFactory +} + +type ChannelConnection struct { + Conn net.Conn + Reader *bufio.Reader + Writer *bufio.Writer + SeqID uint32 + Mutex sync.Mutex + LastUsed time.Time + Status ConnStatus +} +``` + +#### 3.6.2 限速实现 + +```go +// 通道级别限速器 (滑动窗口计数) +type ChannelRateLimiter struct { + channelID string + rateLimit int64 // 条数/秒 + windowSize time.Duration + store RateStore // Redis实现 +} + +func (r *ChannelRateLimiter) Allow(ctx context.Context) bool { + key := fmt.Sprintf("channel_rate:%s:%d", r.channelID, time.Now().Unix()) + // INCR + EXPIRE 实现滑动窗口 + count, err := r.store.Incr(ctx, key, r.windowSize) + if err != nil { return false } + return count <= r.rateLimit +} +``` + +### 3.7 状态回执与上行 + +#### 3.7.1 回执处理 + +```go +func (s *ReportService) HandleReport(ctx context.Context, report *Report) error { + // 1. 校验消息ID + msg, err := s.msgStore.Get(ctx, report.MsgID) + if err != nil { + return ErrMsgNotFound + } + + // 2. 更新消息状态 + oldStatus := msg.Status + msg.Status = report.Status + msg.ReportTime = report.Time + + // 3. 计费处理 + if report.Status == Succeed { + s.balanceService.Confirm(ctx, msg) + } else { + s.balanceService.Refund(ctx, msg) + } + + // 4. 更新ClickHouse (状态变更) + s.asyncWrite.UpdateStatus(ctx, msg) + + // 5. 推送回调 (HTTP/CMPP/SMPP) + s.callbackService.Push(ctx, msg) + + // 6. 统计增量 (Redis原子累加) + s.statsService.Incr(ctx, msg) + + return nil +} +``` + +#### 3.7.2 推送可靠性 + +```go +// 推送重试机制 (指数退避) +type CallbackRetry struct { + MaxRetries int + Backoff []time.Duration // [1s, 2s, 4s, 8s, 16s] +} + +// 回执重推任务 (支持30天内) +type ReportRetryTask struct { + AccountID string + StartTime time.Time + EndTime time.Time + Status string +} +``` + +--- + +## 4. 数据存储设计 + +### 4.1 MySQL 核心表结构 + +#### 4.1.1 用户表 +```sql +CREATE TABLE `accounts` ( + `id` VARCHAR(32) PRIMARY KEY, + `username` VARCHAR(64) UNIQUE NOT NULL, + `password` VARCHAR(128) NOT NULL, + `role` TINYINT NOT NULL COMMENT '1-admin 2-客户 3-运维 4-客服', + `business` SET('sms','video','csp','empty','shorturl') NOT NULL, + `protocol` SET('http','cmpp','smpp','web') NOT NULL, + `ip_whitelist` JSON DEFAULT NULL, + `credit_balance` BIGINT DEFAULT 0 COMMENT '授信余额(分)', + `balance` BIGINT DEFAULT 0 COMMENT '可用余额(分)', + `unit_price` INT DEFAULT 0 COMMENT '单价(毫)', + `audit_mode` TINYINT DEFAULT 0 COMMENT '0免审 1手动 2自动', + `send_time_start` TIME DEFAULT NULL, + `send_time_end` TIME DEFAULT NULL, + `status` TINYINT DEFAULT 1 COMMENT '0禁用 1启用', + `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP, + `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + `deleted_at` DATETIME DEFAULT NULL, + INDEX idx_status_created (`status`, `created_at`), + INDEX idx_username (`username`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; +``` + +#### 4.1.2 通道表 +```sql +CREATE TABLE `channels` ( + `id` VARCHAR(32) PRIMARY KEY, + `name` VARCHAR(128) NOT NULL, + `protocol` VARCHAR(16) NOT NULL COMMENT 'cmpp/http/smpp/sgip', + `host` VARCHAR(64) NOT NULL, + `port` INT NOT NULL, + `username` VARCHAR(64) DEFAULT NULL, + `password` VARCHAR(128) DEFAULT NULL, + `enterprise_code` VARCHAR(32) DEFAULT NULL, + `access_code` VARCHAR(32) DEFAULT NULL, + `rate_limit` INT DEFAULT 0 COMMENT '条/秒,0不限', + `day_limit` INT DEFAULT 0 COMMENT '日限,0不限', + `night_limit` INT DEFAULT 0 COMMENT '夜间限速,条/秒/链', + `status` TINYINT DEFAULT 1, + `weight` INT DEFAULT 100, + `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP, + `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + INDEX idx_status_weight (`status`, `weight`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; +``` + +#### 4.1.3 路由规则表 +```sql +CREATE TABLE `route_rules` ( + `id` VARCHAR(32) PRIMARY KEY, + `account_id` VARCHAR(32) DEFAULT NULL COMMENT 'NULL=全局', + `channel_id` VARCHAR(32) NOT NULL, + `rule_type` TINYINT NOT NULL COMMENT '1-关键字 2-省份 3-运营商 4-地区', + `rule_value` VARCHAR(512) NOT NULL, + `priority` INT DEFAULT 0, + `weight` INT DEFAULT 100, + `status` TINYINT DEFAULT 1, + `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP, + INDEX idx_account_type (`account_id`, `rule_type`), + INDEX idx_channel (`channel_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; +``` + +#### 4.1.4 余额变动表 +```sql +CREATE TABLE `balance_transactions` ( + `id` VARCHAR(32) PRIMARY KEY, + `account_id` VARCHAR(32) NOT NULL, + `biz_id` VARCHAR(64) NOT NULL COMMENT '业务单号/消息ID', + `biz_type` TINYINT NOT NULL COMMENT '1-充值 2-预扣 3-确认 4-退款', + `amount` BIGINT NOT NULL COMMENT '变动金额(分)', + `before_balance` BIGINT NOT NULL, + `after_balance` BIGINT NOT NULL, + `remark` VARCHAR(256) DEFAULT NULL, + `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP, + INDEX idx_account_created (`account_id`, `created_at`), + INDEX idx_biz_id (`biz_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; +``` + +### 4.2 ClickHouse 明细表 + +```sql +-- 下行明细 (按天分区) +CREATE TABLE sms_down_details ON CLUSTER ck_cluster ( + `msg_id` String, + `account_id` String, + `channel_id` String, + `phone` String, + `content` String, + `template_id` String, + `status` UInt8, + `error_code` String, + `send_time` DateTime, + `report_time` DateTime, + `fee` UInt16, + `price` UInt32, + `province` String, + `operator` String, + `signature` String, + `batch_id` String, + `ext` String +) ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/sms_down_details', '{replica}') +PARTITION BY toYYYYMMDD(send_time) +ORDER BY (account_id, send_time, msg_id) +TTL send_time + INTERVAL 180 DAY +SETTINGS index_granularity = 8192; + +-- 上行记录 +CREATE TABLE sms_up_records ON CLUSTER ck_cluster ( + `msg_id` String, + `account_id` String, + `phone` String, + `content` String, + `receive_time` DateTime, + `matched_msg_id` String, + `channel_id` String, + `ext` String +) ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/sms_up_records', '{replica}') +PARTITION BY toYYYYMMDD(receive_time) +ORDER BY (account_id, receive_time) +TTL receive_time + INTERVAL 180 DAY; +``` + +### 4.3 Redis 数据结构 + +| Key模式 | 类型 | 用途 | TTL | +|---------|------|------|-----| +| `balance:{account_id}` | String | 实时余额 | 持久 | +| `frozen:{account_id}` | String | 冻结金额 | 持久 | +| `msg:{msg_id}` | Hash | 消息热数据 | 5天 | +| `user_msg_count:{account_id}:{date}` | String | 日发送计数 | 30天 | +| `channel_rate:{channel_id}:{ts}` | String | 通道限流计数 | 10s | +| `freq:{phone}:{window}` | String | 频次计数 | 24h | +| `blacklist:local` | Set | 本地黑名单 | 持久 | +| `whitelist:local` | Set | 白名单 | 持久 | +| `lock:balance:{account_id}` | String | 余额操作锁 | 5s | +| `session:{token}` | String | 用户会话 | 2h | +| `route:cache:{account_id}` | Hash | 路由规则缓存 | 10min | +| `price:cache:{account_id}:{biz}` | String | 价格缓存 | 5min | + +--- + +## 5. 高可用与弹性设计 + +### 5.1 部署架构 + +``` +┌────────────────────────────────────────────────────────────────────────┐ +│ 负载均衡层 (LVS + Nginx) │ +│ VIP: 10.0.0.100 (主备+健康检查) │ +└────────────────────────────────────────────────────────────────────────┘ + │ + ┌───────────────────────┼───────────────────────┐ + │ │ │ + ┌───────▼────────┐ ┌───────▼────────┐ ┌───────▼────────┐ + │ AZ-A (主) │ │ AZ-B (备) │ │ AZ-C (备) │ + │ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │ + │ │ Gateway x3 │ │ │ │ Gateway x3 │ │ │ │ Gateway x3 │ │ + │ │ Business x5│ │ │ │ Business x5│ │ │ │ Business x5│ │ + │ │ Kafka x3 │ │ │ │ Kafka x3 │ │ │ │ Kafka x3 │ │ + │ │ MySQL主 │ │ │ │ MySQL从 │ │ │ │ MySQL从 │ │ + │ │ Redis主 │ │ │ │ Redis从 │ │ │ │ Redis从 │ │ + │ │ CK x2 │ │ │ │ CK x2 │ │ │ │ CK x2 │ │ + │ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │ + └─────────────────┘ └─────────────────┘ └─────────────────┘ +``` + +### 5.2 故障恢复策略 + +| 故障场景 | 恢复策略 | RTO | RPO | +|----------|----------|-----|-----| +| 单实例宕机 | K8s自动重启 + 服务发现剔除 | <30s | 0 | +| AZ故障 | DNS切流 + Kafka/MySQL主从切换 | <5min | <1s | +| MySQL主库故障 | MGR自动选主 + 从库提升 | <60s | <1s | +| Redis集群故障 | 哨兵自动切换 | <30s | <1s | +| Kafka分区故障 | 副本自动恢复 | <60s | 0 | +| 消息积压 | 动态扩消费者 + 限流降级 | <5min | 0 | +| 通道不可用 | 路由自动切换 + 熔断 | <3s | 0 | + +### 5.3 熔断与降级 + +```go +// 熔断器配置 +type CircuitBreakerConfig struct { + Name string + MaxRequests uint32 // 半开状态最大请求数 + Interval time.Duration // 统计窗口 + Timeout time.Duration // 超时时间 + FailureRate float64 // 失败率阈值 (0-1) + RequestVolume uint32 // 最小请求量 +} + +// 降级策略 +type DegradeStrategy interface { + ShouldDegrade(ctx context.Context) bool + Fallback(ctx context.Context, req interface{}) (interface{}, error) +} + +// 实现: BalanceDegrade (余额降级-只读), RouteDegrade (路由降级-默认通道) +``` + +--- + +## 6. 性能优化设计 + +### 6.1 并发模型 + +```go +// 协程池配置 (基于ants) +type PoolConfig struct { + WorkerSize int // 工作协程数: CPU核心数 * 2 + MaxBlocking int // 最大阻塞任务数: 10000 + NonBlocking bool // 非阻塞模式 + ExpiryDuration time.Duration // 空闲回收: 10s +} + +// 业务隔离: 不同业务使用独立协程池 +// 1. 发送池: 高优先级, 大容量 +// 2. 回执池: 中优先级 +// 3. 统计池: 低优先级, 批量处理 +// 4. 审计池: 低优先级, 异步写 +``` + +### 6.2 缓存策略 + +```yaml +cache_strategy: + # 本地缓存 (LRU) + local: + capacity: 10000 + ttl: 60s + items: + - price:price_* # 价格缓存 + - account:account_* # 账号信息 + - channel:channel_* # 通道信息 + - route:route_* # 路由规则 + + # Redis缓存 (多级) + redis: + # 热数据 (5天) + hot_data: + ttl: 5d + max_keys: 10000000 + # 计数 (滑动窗口) + counter: + ttl: 24h + # 分布式锁 + lock: + ttl: 5s + retry: 3 +``` + +### 6.3 批量处理优化 + +```go +// 批量聚合写入 ClickHouse +type BatchWriter struct { + buffer []*Message + size int // 10000条 + interval time.Duration // 5秒 + mu sync.Mutex + cond *sync.Cond +} + +// CMPP 合包发送 (聚合提交) +type CMPPSubmitAggregator struct { + buffer map[string]*CMPPSubmitReq // 按通道聚合 + size int // 1000包/批次 + interval time.Duration // 5秒 +} +``` + +### 6.4 数据库连接池 + +```yaml +database: + mysql: + max_open_conns: 100 + max_idle_conns: 20 + conn_max_lifetime: 3600s + conn_max_idle_time: 600s + clickhouse: + max_open_conns: 50 + max_idle_conns: 10 + conn_max_lifetime: 1800s +``` + +--- + +## 7. 监控与可观测性 + +### 7.1 关键指标 + +| 类别 | 指标 | 采集方式 | 告警阈值 | +|------|------|----------|----------| +| **业务** | 发送成功率 | 回执统计 | <95% | +| | 发送量QPS | 网关计数 | >20000 | +| | 通道不可用率 | 心跳检测 | >5% | +| | 余额预警 | 定时检查 | 低于阈值 | +| | 审核积压 | 定时统计 | >1000条 | +| **系统** | API响应P99 | Prometheus | >100ms | +| | CPU利用率 | Node Exporter | >80% | +| | 内存利用率 | Node Exporter | >85% | +| | GC暂停时间 | Go Runtime | >10ms | +| | Goroutine数量 | Go Runtime | >100000 | +| | 协程池利用率 | 业务埋点 | >90% | +| **中间件** | Redis命中率 | Redis Info | <90% | +| | Kafka消费Lag | Kafka Metrics | >10000 | +| | MySQL慢查询 | MySQL Slow Log | >100ms | +| | ClickHouse写入延迟 | 业务埋点 | >100ms | + +### 7.2 日志体系 + +```go +// 结构化日志 (Zap) +logger.Info("message submitted", + zap.String("msg_id", msgID), + zap.String("account_id", accountID), + zap.String("phone", phone), + zap.Int64("fee", fee), + zap.Duration("latency", time.Since(start)), +) + +// 日志分类 +// 1. access.log - 访问日志 (ELK) +// 2. app.log - 应用日志 (ELK) +// 3. error.log - 错误日志 (ELK + 钉钉告警) +// 4. audit.log - 审计日志 (ES, 保留180天) +// 5. slow.log - 慢请求日志 (>100ms) +``` + +### 7.3 分布式追踪 + +```go +// OpenTelemetry集成 +func TracingMiddleware() gin.HandlerFunc { + return func(c *gin.Context) { + tracer := otel.Tracer("gateway") + ctx, span := tracer.Start(c.Request.Context(), c.Request.URL.Path) + defer span.End() + + // 注入TraceID到日志 + logger := logger.With( + zap.String("trace_id", span.SpanContext().TraceID().String()), + ) + c.Set("logger", logger) + c.Set("ctx", ctx) + c.Next() + } +} +``` + +--- + +## 8. 安全设计 + +### 8.1 鉴权与授权 + +```go +// JWT Token +type Claims struct { + AccountID string `json:"aid"` + Username string `json:"un"` + Roles []string `json:"roles"` + Permissions []string `json:"perms"` + jwt.RegisteredClaims +} + +// 权限中间件 (Casbin) +func (s *SecurityService) Authorize(ctx context.Context, accountID, resource, action string) bool { + // 1. 获取用户角色 + roles := s.GetRoles(ctx, accountID) + // 2. Casbin策略检查 + // 3. 二级权限检查 (充值/代发/导出) + return s.enforcer.Enforce(roles, resource, action) +} +``` + +### 8.2 数据安全 + +| 安全措施 | 实现方式 | +|----------|----------| +| 传输加密 | TLS 1.3 + 证书自动轮换 | +| 敏感数据加密 | AES-256 (账号密码/API密钥) | +| SQL注入防护 | GORM参数化查询 + 预编译 | +| XSS防护 | Gin模板自动转义 | +| 审计日志 | 记录所有敏感操作 (登录/充值/删除) | +| IP白名单 | 接口客户强制校验 | +| 权限最小化 | RBAC + 二级权限控制 | + +--- + +## 9. 部署与运维 + +### 9.1 容器化部署 + +```dockerfile +# Dockerfile +FROM golang:1.22-alpine AS builder +WORKDIR /app +COPY go.mod go.sum ./ +RUN go mod download +COPY . . +RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o gateway ./cmd/server + +FROM alpine:latest +RUN apk --no-cache add ca-certificates tzdata +COPY --from=builder /app/gateway /app/gateway +COPY --from=builder /app/configs /app/configs +WORKDIR /app +EXPOSE 8080 +ENTRYPOINT ["./gateway"] +``` + +### 9.2 Kubernetes资源配置 + +```yaml +# deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: go-sms-gateway + namespace: go-sms +spec: + replicas: 3 + selector: + matchLabels: + app: hwsms-gateway + template: + metadata: + labels: + app: hwsms-gateway + spec: + containers: + - name: gateway + image: hwsms/gateway:latest + ports: + - containerPort: 8080 + resources: + requests: + memory: "512Mi" + cpu: "500m" + limits: + memory: "2Gi" + cpu: "2" + env: + - name: POD_IP + valueFrom: + fieldRef: + fieldPath: status.podIP + livenessProbe: + httpGet: + path: /health + port: 8080 + initialDelaySeconds: 30 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /ready + port: 8080 + initialDelaySeconds: 10 + periodSeconds: 5 +--- +apiVersion: v1 +kind: Service +metadata: + name: hwsms-gateway +spec: + selector: + app: hwsms-gateway + ports: + - name: http + port: 8080 + targetPort: 8080 + - name: cmpp + port: 7890 + targetPort: 7890 + type: ClusterIP +--- +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: + name: hwsms-gateway-hpa +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: hwsms-gateway + minReplicas: 3 + maxReplicas: 20 + metrics: + - type: Resource + resource: + name: cpu + target: + type: Utilization + averageUtilization: 70 + - type: Resource + resource: + name: memory + target: + type: Utilization + averageUtilization: 80 +``` + +### 9.3 CI/CD流水线 + +```yaml +# .gitlab-ci.yml +stages: + - test + - build + - deploy + +test: + stage: test + script: + - go test -v -race -cover ./... + - go vet ./... + +build: + stage: build + script: + - docker build -t $CI_REGISTRY/hwsms/gateway:$CI_COMMIT_SHA . + - docker push $CI_REGISTRY/hwsms/gateway:$CI_COMMIT_SHA + +deploy-dev: + stage: deploy + script: + - kubectl set image deployment/hwsms-gateway gateway=$CI_REGISTRY/hwsms/gateway:$CI_COMMIT_SHA -n hwsms-dev + - kubectl rollout status deployment/hwsms-gateway -n hwsms-dev + environment: dev + +deploy-prod: + stage: deploy + script: + - kubectl set image deployment/hwsms-gateway gateway=$CI_REGISTRY/hwsms/gateway:$CI_COMMIT_SHA -n hwsms-prod + - kubectl rollout status deployment/hwsms-gateway -n hwsms-prod + environment: prod + when: manual +``` + +--- + +## 10. 容量规划 + +### 10.1 估算基准 + +| 场景 | 日均量 | 峰值QPS | 数据增长/天 | +|------|--------|---------|-------------| +| 短信发送 | 5000万条 | 20000 | 5000万行 | +| 上行记录 | 500万条 | 2000 | 500万行 | +| 回执处理 | 5000万条 | 20000 | 5000万行 | +| 用户数 | 5000个 | - | - | +| 通道数 | 200个 | - | - | + +### 10.2 存储估算 + +| 数据类型 | 单条大小 | 日增量 | 180天总量 | 存储方案 | +|----------|----------|--------|-----------|----------| +| 下行明细 | 200字节 | 10GB | 1.8TB | ClickHouse (压缩后~600GB) | +| 上行记录 | 150字节 | 750MB | 135GB | ClickHouse | +| 业务数据 | - | 10MB | 1.8GB | MySQL | +| 日志数据 | - | 20GB | 3.6TB | ES (30天) | +| 文件存储 | - | 5GB | 900GB | MinIO/OSS | + +### 10.3 资源规划 + +| 组件 | 节点数 | 规格 | 总资源 | +|------|--------|------|--------| +| Gateway | 3-20 (HPA) | 4C 8G | 动态 | +| Business | 5-30 (HPA) | 4C 8G | 动态 | +| MySQL | 1主2从 | 16C 64G | 96C 192G | +| Redis | 6节点 (3主3从) | 8C 32G | 48C 192G | +| Kafka | 3节点 | 8C 32G + 2TB SSD | 24C 96G | +| ClickHouse | 2分片×2副本 | 16C 64G + 4TB SSD | 64C 256G | +| ES | 3节点 | 8C 32G + 2TB SSD | 24C 96G | + +### 10.4 通道吞吐规划(当前部署口径:下家接收 5000 TPS / 上家下发 3000 TPS) + +> 远期口径见 10.1(日 5000 万、峰值 2 万);本节为**当前单通道部署**的工程落地口径,数字均有 Day39 真网实测背书(`logs/bench-day39/`,累计 10 万条零失败零断链)。 + +#### 10.4.1 下发能力实测基线(CMPP 2.0,16 连接) + +| 在途窗口 | 均值 TPS | 峰值 TPS | p50 | p90 | p99 | 边际产出 | +|---|---|---|---|---|---|---| +| 64(4/连接) | 1023 | 1178 | 40.1ms | 116ms | 375ms | 18.4 TPS/窗口 | +| 160(10/连接) | 1836 | 2573 | 46.1ms | 194ms | 510ms | 11.5 TPS/窗口 | +| 256(16/连接) | 2263 | **3203** | 52.2ms | 301ms | 510ms | 8.8 TPS/窗口 | + +**结论**:上家宣称 3000 TPS 为**峰值口径**(实测峰值 3203 ✓);**持续吞吐 ≈2200~2300**(256 窗口均值),边际递减明显。**p50 上升(28→40→52ms)是下游饱和拐点信号**。若业务需均值 3000 持续,须与通道方确认提高连接配额(>16)或服务端扩容(P1 待办)。 + +#### 10.4.2 一收一发容量数据流 + +``` +客户(下家) ──5000 TPS──▶ gateway×2~3(HPA) ──▶ Redis(鉴权/预扣Lua/双桶限流) + (接收能力) │ 同步链路≤5ms,严禁 MySQL 直写 + ▼ + Kafka sms-submit (16分区, key=channel_id) + │ ← 削峰缓冲:净积压 2000/s×5min=60万条≈600MB + ▼ + consumer worker ──▶ MySQL 批量落库(异步,500条/批) + ▼ + per-channel dispatcher: 令牌桶=channel.speed(默认3000) + + 在途窗口 256 (16连接×16, 10.4.1 实测背书) + ▼ ──3000 TPS(峰值)──▶ 上家 CMPP Pool +``` + +#### 10.4.3 各层容量要点 + +| 层 | 目标 | 设计 | 推算依据 | +|---|---|---|---| +| 入口(HTTP/CMPP 接入) | 5000 TPS | gateway 2~3 副本 4C8G + HPA(CPU 70%);同步链路=Redis 鉴权 0.5ms+校验内存级+预扣 Lua 1ms+Kafka acks=1 约 1ms | 3~5ms/条 → 单副本 2000~4000 TPS | +| 中间件(Kafka) | 缓冲 5000 入/3000 出 | `sms-submit` 16 分区(312 TPS/分区) key=channel_id;`sms-report` 16 分区 key=detail_id;副本 2、幂等 producer、重试+DLQ | 单分区顺序写 ~1000 TPS 安全;key 保证通道级顺序与回执配对 | +| 中间件(Redis) | 限流/预扣/黑名单 | 双桶令牌桶(全局 5000+账号 `speed_limit`)、预扣 Lua 原子、滑动窗口频次 | 全部 O(1) 命令,单集群 10 万+ ops/s | +| 数据层(MySQL) | 5000 行/s 写 | 明细**只走 consumer 批量** INSERT(500 条/批 × 10 并发 writer=10 批/s);回执按 detail_id 批量 `UPDATE ... IN (500)`;`message_detail` 按天分区、热 5 天 | 批量写使 InnoDB redo/索引压力降 2 个数量级;单条直写 5000/s 必死 | +| 数据层(ClickHouse) | 明细归档 | 批量 1 万行/flush;5 天后从 MySQL 迁出 | 技术方案 10.2 既有口径 | +| 下发(dispatcher) | 峰值 3000 | 令牌桶=`channel.speed` + 窗口 256;**p50>50ms 持续 30s 自动降速 10%** | 10.4.1;压测证实 p50 上升=饱和 | + +#### 10.4.4 背压分级(5000 入 − 3000 出 = 净积压 2000/s) + +| 水位 | 触发条件 | 动作 | +|---|---|---| +| L1 告警 | submit lag > 10 万(满速积压 ~50s) | 告警通知,投放器降速 | +| L2 收紧 | lag > 100 万 或持续 10 分钟净增 | 入口全局限流收紧至 Σ(通道 speed),超额返回 429/流控错误码 | +| L3 降级 | lag > 500 万 或通道熔断 | 暂停低优先级群发任务,仅保验证/通知类;客户公告 | + +群发大任务由**匀速投放器**按下游预算逐秒投放(每秒 min(剩余, Σ通道speed−在途余量)),不瞬时打满队列。 + +--- + +## 11. 项目结构 + +``` +hwsms/ +├── cmd/ +│ ├── gateway/ # 网关服务 +│ │ └── main.go +│ ├── business/ # 业务服务 +│ │ └── main.go +│ ├── scheduler/ # 调度服务 +│ │ └── main.go +│ └── consumer/ # 消费者服务 +│ └── main.go +├── internal/ +│ ├── api/ # API定义 +│ │ ├── gateway/ # 网关API +│ │ ├── business/ # 业务API +│ │ └── proto/ # gRPC Proto +│ ├── service/ # 业务服务实现 +│ │ ├── account/ +│ │ ├── channel/ +│ │ ├── send/ +│ │ ├── route/ +│ │ ├── audit/ +│ │ ├── balance/ +│ │ ├── report/ +│ │ ├── stats/ +│ │ ├── settlement/ +│ │ └── notification/ +│ ├── repository/ # 数据访问层 +│ │ ├── mysql/ +│ │ ├── redis/ +│ │ ├── clickhouse/ +│ │ └── es/ +│ ├── model/ # 数据模型 +│ │ ├── entity/ +│ │ ├── dto/ +│ │ └── vo/ +│ ├── middleware/ # 中间件 +│ │ ├── auth/ +│ │ ├── ratelimit/ +│ │ ├── logger/ +│ │ ├── tracer/ +│ │ └── recovery/ +│ ├── protocol/ # 协议实现 +│ │ ├── cmpp/ +│ │ ├── smpp/ +│ │ ├── sgip/ +│ │ └── http/ +│ ├── router/ # 路由引擎 +│ ├── config/ # 配置管理 +│ ├── util/ # 工具函数 +│ │ ├── id.go # 雪花ID +│ │ ├── crypto.go # 加密解密 +│ │ └── validator.go # 校验器 +│ └── pkg/ # 内部共享包 +│ ├── logger/ +│ ├── metrics/ +│ ├── queue/ # 消息队列封装 +│ ├── cache/ # 缓存封装 +│ └── lock/ # 分布式锁 +├── configs/ # 配置文件 +│ ├── dev/ +│ ├── staging/ +│ └── prod/ +├── scripts/ # 脚本 +│ ├── init.sql +│ ├── migration/ +│ └── deploy/ +├── deployments/ # K8s配置 +│ ├── base/ +│ └── overlays/ +├── test/ # 测试 +│ ├── unit/ +│ ├── integration/ +│ └── e2e/ +├── docs/ # 文档 +├── go.mod +├── go.sum +├── Makefile +└── README.md +``` + +--- + +## 12. 关键代码示例 + +### 12.1 雪花ID生成器 + +```go +package util + +import ( + "sync" + "time" +) + +type Snowflake struct { + mu sync.Mutex + timestamp int64 + workerID int64 + sequence int64 + epoch int64 +} + +func NewSnowflake(workerID int64) *Snowflake { + return &Snowflake{ + workerID: workerID, + epoch: 1640995200000, // 2022-01-01 + sequence: 0, + } +} + +func (s *Snowflake) NextID() int64 { + s.mu.Lock() + defer s.mu.Unlock() + + now := time.Now().UnixMilli() + if now == s.timestamp { + s.sequence = (s.sequence + 1) & 4095 + if s.sequence == 0 { + for now <= s.timestamp { + now = time.Now().UnixMilli() + } + } + } else { + s.sequence = 0 + } + s.timestamp = now + + return ((now - s.epoch) << 22) | (s.workerID << 12) | s.sequence +} +``` + +### 12.2 分布式锁 (Redis) + +```go +package lock + +import ( + "context" + "time" + "github.com/go-redis/redis/v9" +) + +type RedisLock struct { + client *redis.Client + key string + value string + ttl time.Duration +} + +func (l *RedisLock) Lock(ctx context.Context) (bool, error) { + return l.client.SetNX(ctx, l.key, l.value, l.ttl).Result() +} + +func (l *RedisLock) Unlock(ctx context.Context) error { + script := ` + if redis.call("get", KEYS[1]) == ARGV[1] then + return redis.call("del", KEYS[1]) + else + return 0 + end + ` + _, err := l.client.Eval(ctx, script, []string{l.key}, l.value).Result() + return err +} +``` + +### 12.4 限流器 (令牌桶) + +```go +package ratelimit + +import ( + "context" + "sync" + "time" +) + +type TokenBucket struct { + mu sync.Mutex + rate float64 // 令牌填充速率 + capacity float64 // 桶容量 + tokens float64 + lastTime time.Time +} + +func (tb *TokenBucket) Allow() bool { + tb.mu.Lock() + defer tb.mu.Unlock() + + now := time.Now() + elapsed := now.Sub(tb.lastTime).Seconds() + tb.tokens += elapsed * tb.rate + if tb.tokens > tb.capacity { + tb.tokens = tb.capacity + } + tb.lastTime = now + + if tb.tokens >= 1 { + tb.tokens-- + return true + } + return false +} +``` + +--- + +## 13. 总结 + +本技术方案基于Go语言构建,核心设计要点: + +1. **高可用**:多AZ部署、故障自动切换、数据多副本、熔断降级 +2. **低延时**:多级缓存(Caffeine+Redis)、连接池复用、非阻塞I/O、P99<50ms +3. **高并发**:协程池管控、Kafka削峰填谷、水平弹性扩展、10万QPS支撑 +4. **可观测**:Prometheus监控、Jaeger链路追踪、ELK日志聚合 +5. **可扩展**:微服务架构、配置热加载、插件化路由引擎 + +**关键风险与应对**: +- **MySQL热数据压力** → 5天热窗口 + Redis缓存 + 读写分离 +- **回执风暴** → Kafka分区扩容 + 批量聚合写入ClickHouse +- **通道故障** → 路由自动切换 + 熔断隔离 +- **数据一致性** → 分布式事务(Saga模式) + 幂等设计 +- **大文件处理** → MinIO异步存储 + 任务队列 + +**建议实施路径**: +1. 第1-2月:基础架构搭建 + 核心P0功能 +2. 第3-4月:路由引擎 + 计费系统 +3. 第5-6月:通道接入 + 回执系统 +4. 第7-8月:P1运营支撑功能 +5. 第9-10月:P2增值业务 + 性能调优 +6. 第11-12月:全面测试 + 灰度发布 + 上线 \ No newline at end of file diff --git a/memory-bank/docs/Go-sms-重建搬运清单.md b/memory-bank/docs/Go-sms-重建搬运清单.md new file mode 100644 index 00000000..2adba0ad --- /dev/null +++ b/memory-bank/docs/Go-sms-重建搬运清单.md @@ -0,0 +1,46 @@ +# Go-sms 重建搬运清单(A/B/C/D 四层) + +> **【文档状态】🔄 生效**(2026-11-12)——v2 搬运执行清单;源 = POC 归档仓(`poc-final`),目标 = go-sms-v2。 + +## A 层·直接保留(整包搬运,S0 完成) + +| 资产 | 源位置 | 说明 | +|---|---|---| +| 协议四栈 | `internal/protocol/{cmpp,smpp,sgip,httpadapter}` | 真网验证(DELIVRD 双闭环/UDH/窗口流控),最高价值 | +| pkg 标准件 | `internal/pkg/*`(14 件) | queue/cache/lock/metrics/logger/jwt/casbin/errors/response/cronx/storage/notify | +| 计费纯函数 | `internal/util` | SmsLength/SmsLengthUCS2;fee≡上游片数口径 | +| middleware | `internal/middleware` | 鉴权 / 动态账号桶限流 / 审计 / CORS | +| HTTP 契约 | `api/openapi.yaml` | 前后端共同语言 | +| 迁移链终态 | `repository/mysql/migrations.go`(v1~v19)+ `scripts/init_schema.sql` | 建表一步到位(含 v17 单表化 / v18 stats_daily / v19 longsms_pending) | +| 监控三件 | `deploy/monitoring/*` + `scripts/watch_1m.sh` | 7 业务 counter + 告警规则 | +| 运维资产 | `docs/runbook` + compose/kind/CI 三套/Makefile + `cmd/reconcile` | 事故 SOP / 对账退款工具 | +| 集成测试 | `test/integration` | 真实中间件(schema/kafka/dlq/casbin/cache_lock) | +| 工具与种子 | `tools/gen-dict` + `scripts/init_rbac.sql`/`init_mysql.sql` + `cspell.json` | 字典生成 / RBAC 种子 | +| 压测工具 | `_bench/loadtest.go` + `cmd/cmppbench` | SSD 基线重标定用 | +| 前端基建 | `web/src/{styles 三件套, components/ProTable, api, mocks(msw 51 端点), tests, shots}` | UI 重构 W1-W6 新资产(09-24 收官) | +| 全文文档库 | `memory-bank/`(六核心+docs 全文库) | 随 bundle 进入新环境 | + +## B 层·改造保留(搬核心,调结构) + +| 资产 | 改造点 | +|---|---| +| `service/send`(13 文件) | 拆子包(受理/消费/下发);`*_dayNN_test.go` 改语义命名 | +| `service/access`(长短信) | 语义全留(72h 挂起制/组ID=首片雪花);持久化-还原键成对审计入测试模板 | +| `service/report` | 语义全留(UNKNOWN 72h / compensator / C3 重推);C1 引擎补于 S4 | +| `service/router` | 逻辑全留;`internal/router` 空壳目录归位消除 | +| `service/channel` | 拆 pool/limiter 子包 | +| account/auth/balance/interceptor/template/uplink | 全留;audit_mode=2 文案校准 | +| 前端 31 页 | FE-6 收尾(S3);结算页族新做 | +| `cmd/gateway` 装配 | 大单体拆分(CMPP server/reaper/调度扫描)评估放 S5 基线期,搬运期不强拆 | + +## C 层·结论强制继承(不搬代码,详见《Go-sms-重建设计规范.md》) + +性能三律 / 幂等三锚 / MsgID=DetailID 雪花全链 / 削峰架构 / 长短信 72h 语义 / 计费口径 / UNKNOWN 窗口 / 部署铁律 / -race 全量门禁。 + +## D 层·重建新做(S2-S4) + +结算域全量(利润/代理返点/消耗日汇总/充值审核/阶梯结算单测/三方对账)/ C1 回调推送引擎(指数退避+死信可查)/ C2 拉黑 / ClickHouse 冷热切换 / 通知域 / 明细按天分区热 5 天。 + +## 不搬运清单 + +`web/node_modules`(重装)/ `bin/`(重编)/ `logs/`(运行产物)/ 340 万压测明细数据 / 探针 cmd(authprobe 等,验收后即删性质)。 diff --git a/memory-bank/docs/Go-sms-重建计划.md b/memory-bank/docs/Go-sms-重建计划.md new file mode 100644 index 00000000..13b6b138 --- /dev/null +++ b/memory-bank/docs/Go-sms-重建计划.md @@ -0,0 +1,43 @@ +# Go-sms 重建计划(一期:核心先行) + +> **【文档状态】🔄 生效**(2026-11-12 起草,范围终局裁决=口径 B)——go-sms-v2 一期排期与出口定义;二期另行立项。 + +## 一、终局裁决(2026-11-12) + +- **口径 B·核心先行**:一期 = P0+P1 全部页面 + 结算域 + 压测灰度,出口 = **go-sms-v2 替换 POC 系统承接现网试运营流量**; +- **二期独立立项**(外部依赖隔离):汇网旧平台全量切换/双写比对/下线/历史数据 ClickHouse 迁移/混沌工程/总验收;立项时点 = 一期灰度稳定运行 2 周后; +- **重建定义**:结构重组式重建(新仓新历史 + A/B/C/D 资产搬运),非从零重写; +- **为什么不选 A/C**:全量切换汇网依赖外部协调(客户/旧平台/通道窗口),塞进刚性排期=重蹈 POC 80 日透支覆辙;不上灰度的温室重建丢掉 POC 最大教训(真流量才暴露真问题——长短信语义两轮反转/计费根修/明细三轮优化全部来自真机)。 + +## 二、一期范围 + +| 域 | 内容 | 来源 | +|---|---|---| +| 结构重组 | 新仓骨架(POC 实际结构为准,见设计规范)+ A 层整包搬运 | 盘点 A 层 | +| B 层改造 | send 拆包/去 dayNN 命名、router 归位、report 补 C1、前端 FE-6 收尾 | 盘点 B 层 | +| D 层新做 | 结算域(利润引擎/代理返点/消耗日汇总/充值审核/阶梯结算单测/三方对账)+ C1 回调推送引擎 + C2 拉黑 + CH 冷热切换 + 明细按天分区 | 原阶段 6 遗留 | +| 质量与基线 | 七件套全绿 + SSD 基线重标定(压测前置 24h 稳定性门槛) | CPU 缺陷约束 | +| 灰度接管 | 新系统承接 POC 试运营流量;POC 降级冷备 | 一期出口 | + +## 三、一期排期(27 计划日 + 5 缓冲日;5+1 救火缓冲制) + +| 泳道 | 工作日 | 内容 | 验收 | +|---|---|---|---| +| S0 环境与仓库 | 2 | 纯 CLI Debian13 开荒(stress-ng CPU 实测为第一步)→ Remote-SSH → bundle 校验 → 归档仓 clone → v2 初始化 + A 层搬运 | 七容器 healthy;A 层全量跑测绿 | +| S1 主链搬运 | 5 | B 层逐域搬运改造(send/access/report/router/channel/account/balance/interceptor)+ 迁移链 v1~v19 落地 | 全包等价 -race 绿 | +| S2 结算域 | 5 | D 层结算域后端全量 | 结算单测 + 对账差异 = 0 | +| S3 前端收尾 | 4 | FE-6(权限矩阵走查/Mock 下线/性能/CI 镜像化)+ 结算页面族 | LCP<2s / 单包<500KB / 走查归档 | +| S4 C1/C2+冷热 | 3 | 回调推送引擎 / 拉黑 / CH 冷热切换 | 死信可查 / 拒收即拉黑 / 冷查 <1s | +| S5 基线与灰度 | 8 | 24h 稳定性 → 压测基线(200QPS×30min)→ 消费参数重标定 → 灰度接管现网流量 | 基线报告入档 / 接管零事故 | +| 缓冲 | 5 | 救火专用(救火日七件套不豁免) | — | + +## 四、一期出口验收(全过 = 一期完成) + +1. 七件套全绿(build / vet / -race / lint / 前端四件 / 人工验收单); +2. P0+P1+结算域功能全过(需求页面覆盖对照矩阵全勾); +3. SSD 基线报告入档(压测 + 消费参数重标定); +4. 现网试运营流量由 v2 承载 ≥1 周零 P0 事故;POC 系统转冷备。 + +## 五、二期立项预告(不在一期排期内) + +汇网全量切换(双写比对)/ 旧平台下线 / ClickHouse 历史迁移 / 混沌工程(RTO<30s)/ 生产总验收 + KT。 diff --git a/memory-bank/docs/Go-sms-重建设计规范.md b/memory-bank/docs/Go-sms-重建设计规范.md new file mode 100644 index 00000000..b43ca0c2 --- /dev/null +++ b/memory-bank/docs/Go-sms-重建设计规范.md @@ -0,0 +1,45 @@ +# Go-sms 重建设计规范(强制) + +> **【文档状态】🔄 生效**(2026-11-12)——C 层踩坑结论的结构化沉淀;**任何 v2 设计/评审与本文冲突时,以本文为准**(除非有 POC 验收单级的新证据推翻并留痕)。 + +## 一、结构裁决 + +1. **以 POC 实际演化结构为基础**,不照搬技术方案 §11 纸面结构(35 包 -race 全绿的实测结构 > 纸面设计); +2. 修正项:`internal/router` 空壳归位;send 按受理/消费/下发拆子包;测试命名去 dayNN 改语义;`message_detail` 建表即单表化(v17 口径)+ **按天分区热 5 天**; +3. 服务边界:gateway 大单体拆分评估放 S5 基线期(性能数据齐后裁决),搬运期不强拆。 + +## 二、性能三律(Day64/67 三轮优化 82s→1.0s 的代价换来的) + +1. **筛选列随查询下沉明细表**:业务筛选禁止依赖 JOIN task(单表化冗余列); +2. **聚合 JOIN 一律改按页 id 的相关子查询**:派生表全表物化会随业务量静默劣化(每页请求都付全表聚合代价); +3. 延迟关联三段式只救宽行排序,救不了 JOIN 计数随机回表。 + +## 三、语义与口径(不可妥协) + +- **计费**:fee≡上游真实拆分片数;`FeeSegments>0` 直接采信 > UCS2 按 SmsLengthUCS2 > GBK 默认; +- **MsgID** = DetailID 雪花,全链统一(受理 Resp / 回执配对 / 跨重启一致); +- **长短信**:完整性优先,72h 不齐 = 失败终态(LSM:NOTCMPL / 零费 / UNDELIV);组 ID=首片雪花;**持久化-还原键字段必须成对审计**(Day71 ref 字段教训); +- **UNKNOWN**:出向回执 72h 窗后保持 UNKNOWN(部分段事实送达,不标失败); +- **幂等三锚**:task_no uk / detail pk / OnConflict DoNothing——重复扫描/重投/并发至多一次生效。 + +## 四、门禁纪律 + +- 七件套:go vet+test(**-race 必须全量**,aggregator 教训)→ lint → 前端四件 → 人工验收单归档 → 本人走查 → CHANGELOG → 日历/进度回填; +- 救火日七件套不豁免(Day59-65 破窗教训);救火缓冲 5+1; +- 部署串行:build→kill→确认退出→nohup→`md5sum /proc/PID/exe` 比对(并行 build+kill=旧 inode 幽灵进程)。 + +## 五、SSD 环境基线 + +buffer_pool 16~24G(按 64G 内存)/ `innodb_io_capacity=2000, io_capacity_max=10000` / redo≥1G / Kafka flush 放宽靠副本兜底;**workers:4 与消费顶 55/s 是 HDD 数字,S5 必须重标定**;正式基线前置 **24h 稳定性门槛**(dmesg 零新增 + 进程零重启)。 + +## 六、CPU 缺陷基线 Plan B(决策树) + +S0 开荒实测(stress-ng avx2/memcpy/vm + 20 轮编译循环): +- 复现率 = 0 → 正常推进; +- 0 < 复现 < 1 次/天 → 开发容忍(「偶发 SEGV 先查 dmesg 再重试」入 runbook);**压测基线外置**(借健康机器)或带脚注; +- ≥ 1 次/天 → 基线必须外置;建议机房换整机(重建 30+ 工作日不值概率性地基)。 + +## 七、备份与安全 + +- cron 每日 `git bundle create /data/backup/v2-$(date +%F).bundle --all` + rsync 拉回本地(单人纪律不可靠,自动化); +- 凭证/密钥永不入库;公网机器仅密钥登录 + fail2ban + 最小端口面。 diff --git a/memory-bank/docs/Go-sms-需求分析.md b/memory-bank/docs/Go-sms-需求分析.md new file mode 100644 index 00000000..188e8788 --- /dev/null +++ b/memory-bank/docs/Go-sms-需求分析.md @@ -0,0 +1,323 @@ +# 汇网综合业务支撑平台(go-sms)功能需求分析 + +> **【文档状态】✅ 重建需求基线**(判定 2026-11-12) +> 重建范围裁决=核心先行:P0+P1 全做+结算域;P2(§4 增值业务线)不排期。页面覆盖对照与排期见《Go-sms-重建计划.md》。 + +> **来源**:[汇网科技综合业务平台使用文档 V6](https://doc.huiwwl.com/document_new/)(doc.huiwwl.com,共 18 个功能模块 / 94 个功能页面,已全量抓取分析) +> **分析日期**:2026-08-29 +> **优先级定义**: +> - **P0**:平台价值主线的必需功能,缺失则平台无法营业(收发主链路、开户、路由、合规、回执) +> - **P1**:重要支撑功能,影响运营效率与商业闭环(统计、结算、审计、运维告警) +> - **P2**:增强型 / 增值业务,可后置到后续迭代(大屏、增值业务线、便利工具) + +--- + +## 1. 平台概览 + +### 1.1 平台定位 + +多业务线消息综合支撑平台,作为**上游通道资源**与**下游客户**之间的中间运营平台: + +``` +上游(运营商直连 / 第三方通道) ──► 本平台(路由·合规·计费·审核·统计) ──► 下游客户(HTTP API / CMPP / SMPP / 网页客户端) +``` + +### 1.2 业务线 + +| 业务线 | 说明 | 状态判断 | +|---|---|---| +| 国内短信 | 核心业务,CMPP/HTTP 通道,群发/个性/文件/定时 | 成熟,核心 | +| 国际短信 | SMPP 通道,按国家配置单价与通道 | 成熟 | +| 视频短信 | 仅国内,模板+审核体系与短信平行 | 成熟 | +| CSP 5G消息 | 移动/电信/联通 CSP、Chatbot、非直签、阅信单点登录 | 较新 | +| 空号过滤 | 实号/空号/风险号/沉默号检测 | 增值 | +| 短链 | 短链生成、报备、访问统计 | 增值 | + +### 1.3 核心业务流程(快速入门明确给出) + +``` +创建通道(接上游) ──► 开通客户账号+账号配置 ──► 充值 ──► 发送(网页/API) + ──► 回执/上行处理 ──► 记录查询 ──► 统计报表 ──► 上下家结算 +``` + +### 1.4 功能模块地图(18 模块) + +主页 · 预警公告 · 帐号管理 · 业务审核 · 短信业务 · 视频业务 · CSP业务 · 空号业务 · 短链业务 · 通道配置 · 规则策略 · 通讯录 · 用户统计 · 通道统计 · 结算管理 · 日志报表 · 系统配置 · 常见问题 + +--- + +## 2. 核心功能 + +### 2.1 账号与权限体系 + +| 功能 | 需求要点 | 优先级 | +|---|---|---| +| 用户管理-开户 | 一站式开通国内/国际短信、视频、空号、CSP 业务;支持 CMPP/SMPP/HTTP(API)/网页客户端四种接入形态开户 | **P0** | +| 用户配置-基础 | IP 绑定、单价(时间线分时计价)、授信余额、短信类别、进账类型、状态开放、失败返还 | **P0** | +| 审核模式 | 免审 / 手动审核(不符模板入人工审)/ 自动审核(不符直接拒绝);集团审核独立前置 | **P0** | +| 角色权限 | 多级账号体系(admin/客户运维/客服/集团…),页面级角色权限 + 账号二级权限(充值、代发、导出、下载等按权限开放) | **P0** | +| 余额与充值 | 单个/批量充值、余额预警(预警时间可配)、充值需二级权限 | **P0** | +| 账号生命周期 | 启用/禁用、批量切换配置、切换上级(多级代理)、标星、删除(仅沉默账号或 60 天未发送可删)、导出用户(仅 admin) | **P0** | +| 实名认证 | 实名认证限制与审核、签名实名制信息记录 | P1 | +| 服务团队 | 账号维度绑定服务团队展示 | P2 | + +### 2.2 通道接入与管理 + +| 功能 | 需求要点 | 优先级 | +|---|---|---| +| 短信通道-CMPP | CMPP 通道对接与测试;企业代码、通道号(接入码)、扩展码 | **P0** | +| 短信通道-HTTP/SGIP | HTTP API 通道、SGIP 通道对接与测试 | **P0** | +| 通道拦截机制 | 频次拦截、发送限制(不限/日限/限制)、夜间管控(直接失败/限速 4条/s·链)、通道黑关键字、通道签名限制、屏蔽地区 | **P0** | +| 通道号截断/优先发送 | 通道号截断 1~21 位可配;优先发送关键字命中走优先通道 | **P0** | +| 通道组路由 | 四步路由:条件过滤(频次/黑关键字/签名/地区/运营商)→ 优先通道(省网分流)→ 权重比例分发 → 默认通道兜底 | **P0** | +| 上家管理 | 上家(通道方)档案、通道分类、通道与上家单个/批量绑定 | P1 | +| 短信码号报备 | 联通/移动福建/浙江广东电信 签名码号实名报备、子端口强关联 | P1 | +| 签名管理 | 签名→扩展码映射导入(覆盖/追加/删除),配合"无匹配直接失败/自动生成扩展"两种模式 | P1 | +| 屏蔽码号 | 按通道+码号直接拦截(返回"已屏蔽的子端口号") | P1 | +| 配置ID短信通道 | 上游"模板ID+变量"模式(移动 MAS、CSP 中转),变量占位符 `{%xxx%}` | P1 | +| SMPP 通道接入 | 国际 SMPP 通道 | P1 | +| 通道价格时间线 | 分时单价记录、估算余额(=校正余额-成功数-未知数,2 小时刷新) | P1 | +| 视频通道 | 视频通道创建/启停/拦截配置(同短信模型) | P1 | +| 黑名单/空号通道 | 第三方黑名单检测通道、空号检测通道接入 | P2 | +| 携号转网通道统计/投诉查询 | 第三方携转通道统计、投诉记录查询 | P2 | + +### 2.3 消息发送 + +| 功能 | 需求要点 | 优先级 | +|---|---|---| +| 群发短信 | 网页批量提交,同内容群发,每成功 1 条扣减 1 条余额 | **P0** | +| 个性短信 | 号码+内容逐条不同的变量发送 | **P0** | +| HTTP API 提交 | HTTP 接口密码、回执绑定地址、上行绑定地址(回调推送)、随机/固定扩展码 | **P0** | +| CMPP/SMPP 客户接入 | 企业代码、CMPP 扩展码、通道号校验(UT:0012)、速度=最大提交速度×连接数、CMPP 合包(聚合提交降低 HTTP 通道压力) | **P0** | +| 模板体系 | 精确模板报备/导入(仅创建者可用)、模板匹配自动放行、模板变量限制 | **P0** | +| 定时短信 | 定时发送、批量重置定时时间 | **P0** | +| 文件短信 | TXT/EXCEL/CSV 号码文件直接发送(A 列号码 B 列内容,TXT 逗号/制表符分隔) | P1 | +| 拆分短信 | 同模板按变量拆分多批(如 100 号码按联系人名拆分) | P1 | +| 网页提交拆包 | 客户端群发批次拆包配置 | P1 | +| 视频短信发送 | 视频+文字合帧发送,支持优先合帧 | P1 | +| 上行码号分配 | 按上行码号(精确/前缀匹配)将上行回复分配给指定账号;优先 CMPP 推送,无对接则 HTTP 推送/自取 | P1 | +| CSP 发送 | CSP 群发/个性发送(TXT 一行一个、XLSX 一格一个)、CSP 模板 | P2 | +| 空号过滤发送 | 号码文件导入检测,导出 .csv,分类:实号/空号/风险号/沉默号 | P2 | + +### 2.4 路由、合规与风控 + +| 功能 | 需求要点 | 优先级 | +|---|---|---| +| 导流策略 | 按内容关键字/账号维度指定通道(如"张三"走 A 通道、"李四"走 B 通道) | **P0** | +| 黑名单机制 | 本地黑名单库(UT:0006)、汇网 API 黑名单、第三方黑名单通道(UT:0026)三级检测 | **P0** | +| 黑/白关键字 | 一级黑关键字(直接失败 UT:0023)、二级黑关键字(免审模式专用,失败/入审 UT:0010)、白关键字(免审直接通过) | **P0** | +| 频次策略 | 同号码/同内容时间窗发送次数限制(UT:0016),自然日/24 小时两种单位 | **P0** | +| 白名单库 | 忽略频次与黑名单限制 | **P0** | +| 签名限制 | 内容签名校验(缺签名 UT:0013、非指定签名拦截)、退订限制(末尾"拒收请回复R",UT:0014) | **P0** | +| 营销时间管控 | 全局/单账号营销发送时间、超时直接失败、全天发送豁免、夜间频繁拦截 | **P0** | +| 屏蔽地区 | 按地区拦截(UT:0009) | **P0** | +| 审核工作流 | 发送短信审核(48 小时未审自动失败)、待审核内容聚合展示、模板审核(批量通过/拒绝/删除)、集团短信审核(仅 HTTP 生效)、报备签名审核(通过后自动填充到账号签名限制)、短链地址审核 | **P0** | +| 失败重发策略 | 按失败状态码配置自动补发,仅补发一次 | P1 | +| 国际短信规则 | 按国家配置单价与通道(客户扣费单价与通道成本分离) | P1 | +| 上行自动拉黑 | 回复"拒收"等上行自动入黑名单(规则可配、页面隐藏不影响接口推送) | P1 | + +### 2.5 回执、上行与记录查询 + +| 功能 | 需求要点 | 优先级 | +|---|---|---| +| 状态回执 | DELIVRD/FAILURE/未知状态归一,错误代码表可维护 | **P0** | +| 下行记录 | 批次级记录(近 5 天热数据),拦截失败/通道失败号码下载、批次状态统计(客服+)、定时标红 | **P0** | +| 下行明细 | 号码级明细(近 5 天),CMPP 用户/通道日志追溯(5 天内) | **P0** | +| 历史记录 | 全量历史记录/明细按时间查询 | **P0** | +| 上行记录 | 上行接收、匹配失败归 admin、指定用户、导出(非 admin 需权限)、只匹配 15 天内发送数据 | **P0** | +| 定时记录 | 定时任务管理、批量重置发送时间、取消发送 | P1 | +| 回执重推 | 回执/上行手动重推任务(选用户+时间),30 天内可重推 | P1 | +| 手动配对状态 | 直接失败/指定状态/上传状态文件/提取通道回执日志匹配 4 种方式处理 3 小时外无状态短信 | P1 | +| 下载明细 | 全量明细异步下载(非 admin 需单独开权限),按发送时间筛选 | P1 | +| 视频记录体系 | 视频下行记录/明细/上行/定时(模型同短信,5 天热数据) | P1 | + +### 2.6 计费与结算 + +| 功能 | 需求要点 | 优先级 | +|---|---|---| +| 预扣费/按条计费 | 提交预扣、成功计费、失败返还("状态开放"才返还条数) | **P0** | +| 授信余额 | 授信额度下发,允许负余额发送 | **P0** | +| 分时单价 | 用户/通道单价按时间线生效,与结算联动 | **P0** | +| 下家结算 | 按客户月度结算、账单/明细 | P1 | +| 上家结算 | 上家账单/明细导出、结账记录、单价追加、上家切换 | P1 | +| 消耗日志 | 按账号/业务/天记录消耗 | P1 | +| 充值日志 | 充值记录、付款审核确认 | P1 | +| 利润分析 | 用户利润(含下级)、通道利润按时间段分析 | P1 | + + + +--- + +## 3. 辅助功能 + +### 3.1 监控与告警 + +| 功能 | 需求要点 | 优先级 | +|---|---|---| +| 余额预警 | 用户级预警设置 + 初始化预警时间,微信推送/短信通道告警 | P1 | +| 通道告警 | 通道维度异常告警配置 | P1 | +| 用户/通道通讯日志 | 当天通讯实时曲线,**每 2 秒刷新** | P1 | +| 系统信息监控 | MySQL/Redis 空间监控,容量 80% 需扩容/清理 | P1 | +| 系统公告 | 主页公告/底部公告、详情跳转 | P2 | +| 可视化大屏 | 用户监控大屏+通道监控大屏(今日在线/活跃、正常/活跃通道),仅客户运维及以上角色,F11 全屏 | P2 | + +### 3.2 效率工具 + +| 功能 | 需求要点 | 优先级 | +|---|---|---| +| 通讯录 | 分组树(子节点/重命名/删除)、节点全选、批量导入(.xls/.xlsx,日期 yyyy-mm-dd)、导出/删除、一键跳转发短信 | P2 | +| 任务提醒 | 通讯录客户变量短信自动提醒 | P2 | +| 常用短语 | 树形管理、发送页快捷调用 | P2 | +| 常用号码 | 号码组管理、批量导入自动去重、导出 txt | P2 | +| 在线接口文档 | HTTP 短信/视频/空号接口规范查询 | P1 | +| 错误代码表 | 错误码/失败原因/转义值查询与维护(UT:xxxx 体系) | P1 | +| 签名实名制 | 签名信息记录(仅记录,与发送无关联) | P2 | +| 投诉查询 | 投诉记录查询 | P2 | + +### 3.3 系统运维 + +| 功能 | 需求要点 | 优先级 | +|---|---|---| +| 系统参数配置 | 服务协议弹窗、默认查询天数、频繁发送日单位(自然日/24h)、全局营销时间、黑名单收集(第三方黑自动入本地库)、模板变量限制 | P1 | +| 初始化配置 | 用户开户/短信/视频/空号/短链业务开户默认参数、登录手机验证码通道与内容 | P1 | +| 备份与恢复 | 数据备份清理(仅 admin) | P1 | +| 系统日志 | 登录审计(账号/IP/日期检索) | P1 | +| 主页工作台 | 账号身份、公告、系统信息、已激活产品今日用量、发送类型/数据分析 | P1 | +| 更换主题 | 按钮与菜单颜色自定义 | P2 | + +--- + +## 4. 未来规划(增值业务线,P2) + +| 功能 | 需求要点 | 优先级 | +|---|---|---| +| CSP 5G消息全栈 | 移动/电信/联通 CSP 对接、非直签客户配置(运营商平台批量导入)、Chatbot 配置、阅信单点登录、CSP 代理统计 | P2 | +| 短链业务 | 短链域名配置、客户报备链接审核、短链任务记录、访问详情统计(点击分析) | P2 | +| 空号过滤业务 | 空号通道、过滤记录(实号/空号/风险号/沉默号,标称准确率 100% 误差 5%)、空号用户配置与统计 | P2 | +| 视频短信业务线 | 视频模板/审核/发送/记录全链路(国内) | P2 | +| 国际短信业务线 | SMPP 通道、按国家单价/通道规则 | P2 | +| 黑名单通道增值 | 第三方黑名单检测通道 + 检测统计 | P2 | +| 携号转网增强 | 第三方携转库接入、携转通道统计、号段库远程同步 | P2 | +| 可视化大屏 | 见 3.1,依赖实时统计能力 | P2 | + +> 说明:文档中视频/国际短信已是成熟功能,但对新平台建设而言属于"第二条业务线",建议在短信主链路(P0)稳定后实施,故整体归入 P2 规划;其单页面内的通用能力(记录、审核、统计模型)已随 P0/P1 的通用平台能力一并实现。 + +--- + +## 5. 技术约束与依赖 + +### 5.1 协议与对接约束 + +| 约束项 | 内容 | +|---|---| +| 下游接入协议 | HTTP API、CMPP(企业代码/扩展码/通道号校验/连接数×速度)、SMPP(system ID)、网页客户端 | +| 上游通道协议 | CMPP、HTTP API、SGIP、SMPP;上游"模板 ID+变量"模式(`{%变量%}` 占位符) | +| 回执/上行推送 | HTTP 客户:回执绑定 + 上行绑定地址(推荐填写不强制);CMPP 客户:优先 CMPP 推送;支持 HTTP 自取 | +| 合包约束 | CMPP 提交 + HTTP 通道场景需按时间窗合包(如 5 秒)降低通道压力 | +| 限速模型 | 平台总速度 = 最大提交速度 × 连接数;夜间管控单链路 4 条/s(N 链路 = N×4) | + +### 5.2 存储与数据保留约束 + +| 约束项 | 内容 | +|---|---| +| 存储组件 | MySQL(业务数据+记录,需手动配置监控)、Redis(空间监控);容量 80% 触发扩容/清理动作 | +| 热数据窗口 | 下行记录/明细仅保留 **5 天**,更早数据进"历史记录/历史明细"全量库 | +| 上行匹配窗口 | 上行只匹配 **15 天**内的发送数据 | +| 回执重推窗口 | **30 天**内允许回执/上行重推 | +| 状态回补 | 提交失败次日返回;通道失败状态 **72 小时后**凌晨返回;3 小时外无状态走手动配对 | +| 日志窗口 | CMPP 用户/通道日志仅可查 5 天内当天日志 | +| 删除约束 | 账号/通道仅在"从未发送(沉默)"或"60 天以上未发送"时可删除 | +| 明细下载 | 只要数据库未清理即可下载(下载中心模式,非 admin 需授权) | + +### 5.3 统计与调度约束 + +| 约束项 | 内容 | +|---|---| +| 统计刷新 | 用户/通道使用统计**逢偶数整点**更新;昨日统计 7/13/17 点补算;前 2-3 天凌晨 2 点补算 | +| 多维统计 | 时间、用户、地区、运营商、签名、状态码、回执速率 7 个维度 | +| 通道估算余额 | = 校正余额 - 成功数 - 未知数,**每 2 小时**刷新,偶数点刷新,空值不参与统计 | +| 实时监控 | 用户/通道通讯日志 **2 秒**刷新 | +| 审核时效 | 待审核短信/视频 **48 小时**未审核自动失败 | + +### 5.4 计费模型约束 + +- 按条计费:提交预扣、回执成功确认、失败按"状态开放+失败返还"规则返还条数。 +- 单价双线:客户扣费单价(用户侧)与通道成本单价(上家侧)分离,均支持时间线动态调价。 +- 授信机制:授信余额支持透支发送;充值需二级权限,非 admin 充值需显式授权。 +- 错误码体系(UT:xxxx):0006 黑名单、0009 屏蔽地区、0010 二级黑关键字/通道黑关键字、0012 通道号错误、0013 签名、0014 退订、0015 审核、0016 频繁、0021 参数不符、0023 一级黑关键字、0026 第三方黑、0027 空号;通道侧:通道拒收 -1(屏蔽码号)/-3(发送限制)、提交失败 -3。 + +### 5.5 合规与运营商约束 + +- 营销短信时间窗管控(全局+单账号)、夜间管控、超时直接失败。 +- 签名体系:【签名】前后置识别、签名报备审核自动化(审核通过自动写入账号签名限制)、签名实名制记录。 +- 码号报备:联通、移动福建、浙江/广东电信的签名码号实名报备与子端口强关联。 +- 退订合规:内容末尾必须含"拒收请回复R"类退订标识(可配)。 +- 上行拒收自动拉黑规则。 + +### 5.6 外部依赖 + +| 依赖 | 用途 | +|---|---| +| 微信推送 | 余额/通道告警推送 | +| 汇网 API 黑名单库 | 二级黑名单数据源 | +| 第三方黑名单通道 | 发送前实时检测 | +| 第三方携号转网通道 | 携转识别 | +| 汇网号码库/号段库 | 号码归属地、号段分类远程同步 | +| 运营商 CSP 平台 | 移动/电信/联通 CSP、阅信单点登录 | +| 上游通道方 | 短信/视频/空号/黑名单通道资源 | + +### 5.7 安全约束 + +- IP 绑定(接口客户)、登录手机验证码(可配通道与内容)、服务协议弹窗。 +- 分级授权:admin 专属(导出用户、备份恢复、全局配置);二级权限控制充值/代发/导出上行/下载明细;页面级 RBAC 角色(客户运维及以上才可访问大屏)。 +- 数据安全:仅 admin 可导出全量用户数据。 + +### 5.8 文件处理约束 + +- 号码文件:TXT(逗号/制表符分隔)、EXCEL、CSV(A 列号码 B 列内容)。 +- 通讯录:.xls/.xlsx,出生日期格式 yyyy-mm-dd 或 yyyy/mm/dd。 +- 检测结果导出:.csv;号码组导出:.txt;报表导出:.xls。 +- 大文件异步处理:文件短信、批量导入、明细下载均为任务化流程。 + +--- + +## 6. 优先级总览 + +### 6.1 P0(主链路必需,共 ~30 项) + +开户(多协议多业务)· 用户配置(单价/授信/IP/审核模式)· 角色权限与二级权限 · 充值与余额预警 · 通道创建(CMPP/HTTP/SGIP)· 通道拦截机制 · 通道组四步路由 · 导流策略 · 黑白名单/黑白关键字/频次/签名/退订/地区拦截 · 营销时间管控 · 审核工作流(发送/集团/模板/签名)· 群发/个性/定时发送 · HTTP/CMPP/SMPP 提交 · 模板体系 · 状态回执 · 上行接收推送 · 下行记录/明细(含历史库)· 上行记录 · 预扣费/失败返还 · 分时单价 · 号码归属地/号段/携转库 + +### 6.2 P1(运营支撑,共 ~25 项) + +文件短信/拆分短信 · 上行码号分配 · 视频通道与视频记录体系 · 上家管理/码号报备/签名管理/屏蔽码号/配置ID通道/SMPP 通道/价格时间线 · 失败重发 · 国际短信规则 · 上行自动拉黑 · 定时记录 · 回执重推 · 手动配对状态 · 下载明细 · 下家/上家结算 · 充值/消耗日志 · 利润分析 · 多维使用统计 · 余额/通道告警 · 通讯日志 · 系统监控 · 接口文档/错误代码 · 系统参数/初始化配置 · 备份恢复 · 登录审计 · 主页工作台 + +### 6.3 P2(增值与规划,共 ~20 项) + +CSP 5G消息全栈 · 短链业务 · 空号过滤业务 · 视频短信业务线 · 国际短信业务线(SMPP 客户接入)· 黑名单通道 · 携转增强 · 可视化大屏 · 系统公告 · 通讯录/常用短语/常用号码/任务提醒 · 签名实名制 · 投诉查询 · 更换主题 · 服务团队 + +--- + +## 附录 A:错误代码体系(发送链路依赖) + +| 错误码 | 含义 | 触发场景 | +|---|---|---| +| UT:0006 | 黑名单 | 本地/API 黑名单命中 | +| UT:0009 | 屏蔽地区 | 地区拦截 | +| UT:0010 | 黑关键字 | 二级黑关键字/通道黑关键字 | +| UT:0012 | 通道号错误 | CMPP 提交通道号前置不匹配 | +| UT:0013 | 签名错误 | 缺签名/非指定签名 | +| UT:0014 | 退订错误 | 缺退订标识 | +| UT:0015 | 审核拒绝 | 手动/自动审核不通过 | +| UT:0016 | 频繁发送 | 频次策略命中 | +| UT:0021 | 参数不符 | 变量限制触发 | +| UT:0023 | 一级黑关键字 | 强制失败关键字 | +| UT:0026 | 第三方黑名单 | 黑名单检测通道命中 | +| UT:0027 | 空号 | 空号通道检测命中 | +| 通道拒收 -1 | 已屏蔽子端口号 | 屏蔽码号命中 | +| 通道拒收/提交失败 -3 | 发送限制 | 通道日限/限制模式 | +| DELIVRD / FAILURE | 回执状态 | 成功/失败 | + +## 附录 B:数据来源 + +- 文档首页:`https://doc.huiwwl.com/document_new/`(iframe 框架结构,菜单 `/document_new/page/sy`,正文 `/document_new/page/right?cont_id={id}`) +- 全量抓取 94 个功能页面(cont_id 见正文各表),关键字快速入门(1713)、用户管理(19)、短信用户配置(33)、短信通道(84)、通道组(100)、系统参数配置(111)等为需求密度最高的页面。 diff --git a/memory-bank/productContext.md b/memory-bank/productContext.md new file mode 100644 index 00000000..9640d318 --- /dev/null +++ b/memory-bank/productContext.md @@ -0,0 +1,31 @@ +# 产品背景 + +## 为什么存在这个项目 + +旧「汇网综合业务支撑平台」需要用 Go 语言重建:旧平台承载短信代运营业务(上游买通道、下游卖给客户赚差价),但技术栈老化。本项目以 80 工作日计划重建为现代化 Go 平台,保留业务语义并补齐性能/可观测性短板。 + +## 解决的问题 + +1. **多协议互通**:下家用 CMPP/SMPP/HTTP API 提交;平台经四步路由选上家通道(CMPP/SMPP/SGIP/HTTP)下发——协议翻译与统一计费是核心价值。 +2. **资金安全**:余额预扣(holdFastLua 哨兵)、计费口径 fee≡上游真实拆分片数(Day 70 根修)、退费闭环(拦截/失败/全拦)、对账补偿(report compensator)。 +3. **合规风控**:黑白名单/关键字/频次/码号校验拦截链、审核流转(免审/人工/自动)、实名状态机、签名/码号报备审核。 +4. **削峰解耦**:受理速率(SubmitFast p50 14ms / TPS 4279)与下发速率(HDD 物理顶 ~55/s)天然不对齐,Kafka Deferred 事件做中间缓存。 + +## 用户与角色 + +- **运营方(admin/超管)**:管账号(开户/充值/切挂)、通道(上家/通道配置/通道组路由)、策略(黑白名单/关键字/导流)、审核(模板/签名/码号/发送任务)、报表统计、监控告警。 +- **下家客户**:Web 管理台(群发/个性/定时/模板/通讯录/明细查询/回执)、HTTP API(appkey 签名三鉴权)、CMPP/SMPP 长连接接入。 +- **五角色权限矩阵**:RBAC(casbin)+ 二级权限授撤,按钮级权限(customer 受限角色验证口径)。 +- **代理体系**:账号树(root→子账号)路径级联切挂、代理返点分成(结算域,阶段 6 待开工)。 + +## 用户体验目标(Web 管理台) + +- 94 页面需求,现 ~50 页已落地(FE-1~FE-5)。 +- UI 已按 `docs/design/demo-c-aurora.html` 基准全站重构(W1-W6,2026-09-24 收官):暗/亮双主题 token 化、玻璃面卡片、teal 主色调、表格无线化纯 hover。 +- 质量门:eslint 0 / vue-tsc 0 / vitest 137 用例 / build ✓ / verify-layout 18 项 / 双主题截图矩阵。 + +## 运营环境现实约束(影响决策) + +- **宿主机单块 HDD**(w_await ~80ms):消费吞吐、明细回表、Kafka fsync 均受制;生产建议 SSD(运维侧事项)。 +- **端口 8080 被宿主旧进程占用**:网关固定 `GW_PORT=8081`(可覆盖)。 +- 接入账号 tcmpp 为 bcrypt 口令,压测需真实口令(不可暴力试探)。 diff --git a/memory-bank/progress.md b/memory-bank/progress.md new file mode 100644 index 00000000..dc3b6045 --- /dev/null +++ b/memory-bank/progress.md @@ -0,0 +1,54 @@ +# 项目进度(截至 2026-09-29 / Day 71;Day67-71 已入 git `80d067e5`) +> **2026-11-12 终态**:POC 冻结(用户裁决:全部重建)。归档 tag `poc-final` + 全量 bundle(/data/go-sms-poc.bundle)交付摆渡;下方「未完成/待办池」**整体转入重建仓 go-sms-v2 排期**,不在本仓继续开发。重建盘点(A/B/C/D 四层)/迁移方案/环境三项裁决(Remote-SSH/纯CLI/不装 Gitea)见 `activeContext.md` 与 `techContext.md`。 + + +## 阶段总览(8 阶段 / 80 工作日) + +| 阶段 | 内容 | 状态 | +|---|---|---| +| 阶段 0(Day 1-10) | 工程地基:compose/配置/日志/队列/K8s CI | ✅ 2026-09-03(合并 develop `7b46b312`) | +| 阶段 1(Day 11-20) | 数据层:36 表/仓储/迁移 | ✅ 2026-09-03(`b75fbe26`) | +| 阶段 2(Day 21-30) | 账号/权限/余额/审计:E2E 全链 | ✅ 2026-09-04(`e35ec818`) | +| 阶段 3(Day 31-40) | 协议:CMPP/SMPP/SGIP/HTTP 适配 | ✅ 2026-09-08 前后(单日验收连续通过) | +| 阶段 4(Day 41-50) | 发送主链:提交/审核/定时/HTTP API/全链 | ✅(Day 43-50 逐日 ✅A 归档) | +| 阶段 5(Day 51-65) | 运营闭环:回执/重推/对账/消费并发 | ✅ 含收尾 C3(Day66=09-24)与补账(Day59-66) | +| 阶段 6(Day 66-69 原计划) | 结算域:利润/消耗汇总/结算单测 | ⬜ **未开工**(2026-09-16 裁决收尾优先,待重排) | +| 阶段 7(Day 71-80) | 上线:Staging/压测/灰度/切换/验收 | 🔄 部分透支(Day 71 实际=长短信挂起制,非 Staging) | +| 前端 FE-1~FE-5 | 账号→通道→策略→审核→群发/明细 ~50 页 | ✅(FE-6 权限走查/Mock 下线未做) | +| 前端 UI 重构 W1-W6 | demo-c-aurora 基准全站重构 | ✅ 2026-09-24(rebuild-ui 分支 6 commit) | + +## 近期完成明细(Day 63-71,报障驱动修复期) + +| 日 | 主题 | 关键成果 | +|---|---|---| +| Day 71(09-29) | 入向长短信挂起制 72h | v19 持久化/restore/reaper/失败终态制;✅A 真机六步 | +| Day 70(09-28) | 长短信计费少计根修 | fee≡上游片数;UCS2 口径;探针 longsmsprobe;存量 21837 条清偿 | +| Day 69(09-28) | 入向长短信 UDH 全链路 | ParseUDH+聚合器(组ID 三口径同源);回执并发竞态三轮根修(recheckPending 新事务重判)+unpaired 重投自愈;压测监测 7 指标+3 告警+watch_1m.sh | +| Day 68(09-28) | 运营总览真实数据后端 | v18 stats_daily+/stats/summary·trend(60~73ms/15.5ms);60s UPSERT;角色双口径 | +| Day 67(09-28) | 明细查询单表化根治 | v17 business/source 下沉+派生表改按页相关子查询;端到端 29.5s→1.0~1.2s;buffer_pool 6G | +| Day 66(09-24) | 阶段 5 收尾 C3 | D28 回执重推/手动配对四端点 | +| Day 65(09-16) | 消费并发 worker 池 | workers:4 消化 0→55/s;生产级死锁两连修 | +| Day 64(09-15) | 明细查询超时修复 | v16 双索引+延迟关联三段式 82s→645ms;buffer_pool 4G | +| Day 63(09-15) | SubmitFast 快路径 | 受理 p50 1.7s→14ms / TPS 45→4279;MsgID 口径统一 | + +## 未完成 / 待办池 + +1. **阶段 6 结算域**(settle:利润分析/消耗日汇总/充值审核流程/阶梯结算单测/三方对账)——整域未开工,需重排落位。 +2. **Day 72-80 上线序列**:压测基线(200 QPS×30min)→生产就绪检查→灰度 5%→20%→50%→全量切换→旧系统下线+ClickHouse 迁移→混沌工程→总验收。 +3. **FE-6(D37-39)**:全站权限矩阵走查(五角色×全菜单)+Mock 下线;前端性能(LCP<2s/单包<500KB);CI 集成+web 镜像化(nginx+kind NodePort 30081)。 +4. **运维缺口**(2026-09-11 立项,6 工作日):告警通道 Alertmanager 联通(规则已有);Loki 日志聚合;release 回滚流水线。 +5. **P1 挂账**:通道方连接配额确认(3000 TPS 需 >16 连接);生产换 SSD(明细回表/消费吞吐解锁项)。 +6. **小项**:前端 LP/LSM:NOTCMPL 错误码文案映射(待运营反馈);个性逐号精检(待办池择机);账号 audit_mode=2 文案校准。 +7. **观察项**:长短信组上限 16384(watchdog expf);`web/.env.development.local` 当前=real(联调期,切 mock 前必查)。 + +## 已知问题(修复史与遗留) + +- go-sms-kafka 容器曾 DNS 故障重启循环(1217 次,Day 46 观察;网关实连 hwsms-kafka 正常)——非代码问题。 +- 回执偶发双推容忍(72h 末端 reaper 与到齐路径毫秒级窗口,概率趋零)。 +- cmppbench 接入账号口令未知(tcmpp 为 bcrypt)——压测受限非阻塞。 + +## 验收档案索引 + +- 单日验收单:`docs/acceptance/day41~day71.md`(Day 41 起强制,协议 v2→v3;day67~71 为 2026-09-29 补账归档,证据取自 CHANGELOG 各日条目)。 +- 阶段评审:`docs/phase1/2/3-review.md`;资金评审 `docs/review/r1-balance.md`;前端审计 `docs/review/fe-design-audit.md`(W 阶段一~十三全链登记)。 +- 完成验收映射表:开发日历文末「已完成验收档案」(逐项含 commit 证据)。 diff --git a/memory-bank/projectbrief.md b/memory-bank/projectbrief.md new file mode 100644 index 00000000..74b1ebdc --- /dev/null +++ b/memory-bank/projectbrief.md @@ -0,0 +1,42 @@ +# 项目简报 + +> **双阶段**:POC 已终态冻结(2026-09-29,Day 71);重建进行中(2026-11-12 裁决,核心先行口径)。 + +## 一句话定位 + +Go-sms 是「汇网综合业务支撑平台」的 Go 语言重建版本:短信中间运营平台,连接 **上游通道资源 ↔ 中间运营平台(路由/合规/计费/审核/统计)↔ 下游客户(HTTP API / CMPP / SMPP / 网页客户端)**。 + +## 核心目标(两阶段通用) + +1. **多协议接入**:下家客户经 CMPP / SMPP / HTTP API / Web 管理台提交短信;上家通道经 CMPP / SMPP / SGIP / HTTP 对接运营商/服务商。 +2. **运营中枢**:四步路由引擎、黑白名单/关键字/频次等合规拦截、余额预扣计费、审核流转、统计报表、结算与利润分析。 +3. **高性能削峰**:受理(SubmitFast 零 DB 写快路径)与下发(Kafka 异步消费)速率解耦,平台即中间削峰缓存。 +4. **生产级可观测**:Prometheus 指标、OTel tracing、结构化日志(zap+lumberjack)、告警规则。 + +## 项目阶段 + +| 阶段 | 状态 | 说明 | +|---|---|---| +| **POC(测试可用性验证)** | 🔒 已冻结 2026-09-29 | Day 1-71(f1f8e66d/poc-final):阶段 0-5 完成+11 天报障淬炼;质量基线 35 包 -race 全绿。定位=技术可行性验证,使命完成 | +| **重建(go-sms-v2)** | 🔄 2026-11-12 裁决启动 | **结构重组式重建**(新仓新历史+A/B/C/D 资产搬运,非从零重写);一期口径=核心先行(P0+P1+结算域+压测灰度,出口=替换 POC 承接试运营流量);二期独立立项(汇网全量切换/下线/CH 迁移) | + +## 关键文档索引(memory-bank/docs/ 全文库) + +| 文档 | 状态与说明 | +|---|---| +| `memory-bank/docs/Go-sms-需求分析.md` | ✅ 重建需求基线(18 模块/94 页,P0/P1/P2) | +| `memory-bank/docs/Go-sms-技术方案.md` | ✅ 架构基线(§11 结构以 POC 实际为准) | +| `memory-bank/docs/Go-sms-重建计划.md` | 🔄 一期排期/范围/出口定义(B 口径) | +| `memory-bank/docs/Go-sms-重建搬运清单.md` | 🔄 A/B/C/D 资产搬运清单 | +| `memory-bank/docs/Go-sms-重建设计规范.md` | 🔄 强制结论+结构裁决+CPU 基线 Plan B | +| `memory-bank/docs/Go-sms-开发日历.md` | 🔒 POC 进度事实源(Day71 定稿) | +| `memory-bank/docs/Go-sms-实施计划.md` `开发计划.md` `前端开发计划.md` | ⛔ 已废止,历史归档 | +| `CHANGELOG.md` | POC 逐日更新明细(冻结) | +| `docs/acceptance/day41~71.md` | POC 人工验收单(回归用例库) | +| `docs/runbook/incident-response.md` | 运维手册 v1.0 | +| `api/openapi.yaml` | HTTP API 契约(A 层资产) | + +## 项目性质与团队约定 + +- **重建项目**:POC 验证完成后结构重组式重建;终局=替换汇网旧平台(二期独立立项)。 +- **单人全栈 + 评审制**;**强门禁文化**(七件套,任一任务验收未 100% 通过下一任务不得开工);救火缓冲制度(每 5 计划日 +1 缓冲日,救火日七件套不豁免)。 diff --git a/memory-bank/systemPatterns.md b/memory-bank/systemPatterns.md new file mode 100644 index 00000000..c32b1c0e --- /dev/null +++ b/memory-bank/systemPatterns.md @@ -0,0 +1,63 @@ +# 系统架构与技术模式 + +## 服务拓扑(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 定位入口)。 diff --git a/memory-bank/techContext.md b/memory-bank/techContext.md new file mode 100644 index 00000000..b941521c --- /dev/null +++ b/memory-bank/techContext.md @@ -0,0 +1,106 @@ +# 技术上下文 + +## 后端技术栈(Go 1.25,module `go-sms`) + +| 类别 | 选型 | +|---|---| +| Web 框架 | gin v1.10 | +| ORM | gorm v1.30 + gormigrate v2(迁移 v1~v19);驱动 mysql / glebarez sqlite(单测) | +| 消息队列 | Kafka(IBM/sarama v1.43)——四核心 Topic:submit/report 等,16 分区 | +| 缓存/锁 | redis/go-redis v9(single/cluster)、freecache(本地)、etcd client v3 | +| 鉴权 | golang-jwt/v5 + casbin v2(gorm-adapter,RBAC+二级权限) | +| 可观测 | prometheus/client_golang、OTel(otlptracehttp)、zap + lumberjack 日志轮转 | +| 存储 | MySQL 8.0(36 表主库)、ClickHouse 24.3(历史归档规划)、MinIO(文件/号码导入) | +| 其他 | excelize(XLSX)、miniredis(测试)、websocket | + +## 前端技术栈(web/,package name `hwsms-web`) + +| 类别 | 选型 | +|---|---| +| 框架 | Vue 3.4 + TypeScript 5.4(setup 语法) | +| UI | Element Plus 2.7 + @element-plus/icons-vue | +| 状态/路由 | pinia 2 / vue-router 4 | +| 构建 | vite 5;`make web-dev`(:5173)必须 vite dev——preview 不加载 msw | +| 测试 | vitest(137 用例)+ @vue/test-utils + jsdom;Playwright 1.63(截图矩阵+e2e) | +| 质量 | eslint(max-warnings 0)/ vue-tsc / prettier / verify-layout 脚本(18 项断言) | +| Mock | msw 2.3 浏览器拦截 `/api/v1/*`(51 端点);`VITE_API_MODE=mock\|real` | +| 包管理 | pnpm workspace(近期切;package-lock 与 pnpm-lock 并存) | + +## 开发环境(docker-compose.dev.yaml,7 中间件) + +| 中间件 | 宿主端口 | 说明 | +|---|---|---| +| MySQL 8.0 | 13306 | root/root123,库 gosms;buffer_pool 已调 4G | +| Redis 7 | 16379 | single 模式 | +| Kafka 3.7 KRaft | 19092 | Topic 预创建:`make init-topics` | +| ETCD 3.5 | 12379 | | +| ClickHouse 24.3 | 18123(HTTP)/19000(Native) | | +| MinIO | 19010/19011(API/Console) | | +| Prometheus+Alertmanager | — | 规则 `deploy/monitoring/alert_rules.yml` | + +网关 dev 固定 **:8081**(`GW_PORT`,8080 被宿主旧进程占用);Web :5173;K8s NodePort 30080/30081。 + +## 常用命令 + +```bash +# 中间件与初始化 +make up && make init-topics && make init-mysql && make init-schema +# 质量门(后端) +make vet && make test # go test -race -cover ./... +make lint # golangci-lint v2.1.6 +# 运行 +make run # bin/gateway +make run-consumer # bin/consumer +make seed-admin # 首启迁移+超管(密码仅打印一次) +make dev / make dev-stop # 一键全栈(scripts/dev_up.sh 幂等) +make web-dev / web-real / web-test / web-stop +make svc-status # gateway/web/mysql 健康一览 +# 集成测试(真实中间件) +go test -tags=integration ./test/integration/... +# K8s(kind) +make ci-local SERVICE=gateway VERSION=dev +``` + +## 环境变量规则 + +- 前缀 `GOSMS_`,层级以 `_` 连接:`mysql.dsn → GOSMS_MYSQL_DSN`;切片逗号分隔。 +- 高频:`GOSMS_CONFIG` / `GOSMS_SERVER_HTTP_ADDR` / `GOSMS_KAFKA_BROKERS` / `GOSMS_BALANCE_MODE=redis`(消费侧必设)/ `GOSMS_LOG_FILE_PATH`(不可写自动降级 stdout)。 +- 集成测试:`GOSMS_TEST_REDIS_ADDR` / `GOSMS_TEST_KAFKA_ADDR` / `GOSMS_TEST_ETCD_ADDR`。 + +## 工具链版本 + +- Go 1.25.0;golangci-lint v2.1.6(`GOTOOLCHAIN=go1.25.0 go install ...@v2.1.6`)。 +- Node/pnpm(web/node_modules 已就位);字典生成 `go run ./tools/gen-dict`(`npm run gen:dict`)。 +- kind + kubectl(本地 K8s `go-sms-dev` 集群,scripts/kind-dev.yaml)。 + +## 技术约束 +- **重建期代码托管(2026-11-12 裁决)**:新环境**不装 Gitea**——单人+Remote-SSH 下服务器本地仓即中心(/data/go-sms-v2);备份=定期 `git bundle create --all` 至 /data/backup 并拉回本地;需协作/CI 时再补 Gitea(单二进制+SQLite,5 分钟)。 + +- **宿主单块 HDD**:写吞吐物理顶 ~55/s(w_await 80ms),压测结论「代码杠杆已用尽,生产换 SSD」。 +- 36 表 DDL 幂等(scripts/init_schema.sql);生产 Kafka/Redis Cluster 由运维托管。 +- CI 三套同语义:`.gitlab-ci.yml` / `.gitea/workflows/ci.yml` / `make ci-local`(当前验收路径)。 +- 镜像基线:`go-sms-:dev`;CI 用 `kubectl set image` 滚动,**勿 apply 覆盖运行中镜像标签**。 + +## 远程开发机(121.46.230.53,2026-11-13 重装后 = 重建主战场) + +- **SSH**:`ssh -p 1822 user@121.46.230.53`(公网 1822→VM 内 22 NAT;公钥免密,老机 `id_ed25519_510` 已授权实测 SSH_OK);hostname=`debian13-smsDev`;Debian 13.7 / 内核 6.12.116,纯 CLI。 +- **规格**:8C(Xeon 8173M,VMware 虚机,宿主为托管实体机)/ 31G 内存 / sda 400G 虚拟盘(ROTA=0):`/` 92G + `/data` 272G 独立分区(root 所有)。 +- **S0 评估结论(2026-11-13)**:① **CPUID 无 AVX + VEX 编码执行即 SIGILL(2026-11-13 stress-ng 实测定画像)**——dispatch 类软件(glibc/Node/libatomic 类,旧 VM 崩源)免疫(CPUID 干净不选 AVX 路径);但**含 VEX/EVEX 编码的二进制执行即崩**:stress-ng cpu/stream stressor 0 秒 SIGILL(ILL_ILLOPN@VEX 指令),memcpy(SSE2 实现)正常,git/fio/apt/python 实测全正常。**对策:新机编译禁用 `-march=native`/AVX 选项(Go 工具链无影响,CGO/自编 C 注意);Go 编译循环终验待 Go 安装**;② 磁盘实测:顺序写 662MB/s(home dd)+ **fio 4K 随机读 76.3k IOPS(312MB/s)/写 25.5k IOPS**(QD32·75/25 混合,/data 实测)——HDD 老机 ~100 IOPS 的 **500 倍级**,消费吞吐/明细回表瓶颈彻底解锁;③ **外网通畅(2026-11-13 二次探测修正)**:IP 层 ping 223.5.5.5 rtt 4.6ms、TCP 443/53 直连 OK——首测「无外网」为**误报**(dhcpcd 生成的 resolv.conf 无 nameserver,域名全解析失败);修正动作=dhcpcd.conf 加 `domain_name_servers=192.168.5.1 223.5.5.5`(待 root);DNS 恢复后 apt/Go module/vscode-server 全在线,介质摆渡降为备用通道;④ NTP 未同步(无外网,待 open-vm-tools 宿主对时或 root 处理);⑤ 工具链就位(2026-11-13 apt,阿里云镜像):fio/git/curl ✓,stress-ng SSE2 类 stressor 可用(VEX 类崩,见①),docker 待装;⑥ **归档仓 mirror 落位 `/data/poc-archive/repos/go-sms.git`**(HEAD=9c1ed52d,develop/main/rebuild-ui/poc-final 四 ref 全);⑦ DNS 用户已配(114.114.114.114/8.8.8.8,出网正常);user 已入 sudo 组 + NOPASSWD(sudoers.d/user)已配;评估全程 dmesg 零崩溃。 +- **连接故障根修三连留痕(2026-11-13,已解决)**:① root 会话曾把 authorized_keys 权限改成 664(组可写)→ sshd StrictModes 拒绝公钥(表现为:新连接 Permission denied 而旧 ControlMaster 通道存活)——修复 `chmod 600`;② 老机 ssh config 对该 Host `IdentitiesOnly id_ed25519` 单钥匙 + 对端被换钥匙 = 必败——已补回 inscom2ai-image-deploy 公钥(用户本地 Pd-debian12 钥匙保留共存);③ 老机 ControlMaster(30m 复用)会让会话携带**旧的组信息**(usermod 后验证 sudo/组必须 `-o ControlMaster=no -o ControlPath=none` 绕过或 `-O exit` 杀 master)。 +- 过桥:bundle(42M)已落位 `/data/poc-archive`(sha256 `bfca93fa` 一致;ssh cat 管道传输——新机无 rsync,链路实测 ~1.5MB/s);归档仓 mirror 已落位 /data/poc-archive/repos/go-sms.git。 + +### 重装前历史(2026-11-12 VS Code 排查期,旧 VM,已被重装取代) + +- Debian 13 (trixie) / 内核 6.12 / Xfce + **xrdp 远程桌面**(display :10.0);VS Code 1.146 官方 deb(`/usr/share/code`);suer 在 sudo 组。 +- **重装计划(2026-11-12 裁决)**:纯命令行 Debian 13——Xfce/xrdp/VS Code GUI 全弃用(公网攻击面收敛,xrdp 为头号爆破目标);开发形态=本地 VS Code + Remote-SSH,服务器仅 vscode-server(纯 Node,首连自动装,断线自动重连);Cline 扩展装在 server 端。 +- **宿主 CPU 指令执行缺陷(2026-11-12 实锤,系统级)**:Xeon 8173M(Skylake-SP,二手渠道整机特征;2026-11-12 用户澄清=**托管机房实体机,非云虚机,微码/宿主不可更换**,「报云厂商换宿主/升微码」路径作废),AVX 系全掩/BMI1-2 保留,微码/掩码不一致 → 任意进程可确定性 SIGSEGV/SIGILL(dmesg:code 进程 `segfault error 25` 固定崩点跨 socket 0/4/8/12;extensionHost SIGILL;**evolution-alarm 在 libatomic invalid opcode = 非 VS Code 进程同样中招**)。**在该机排查任何「软件崩溃 bug」前先看 `sudo dmesg`,勿误判为代码问题**;根治需云厂商换宿主/升级微码。 +- **CPU 缺陷对纯 CLI 的影响与缓解(2026-11-12 评估)**:非零——压测基线可信度>go build/test 偶发假红(项目纯 Go/SSE2 基线,面小)>Node(vscode-server 自动重连兜底)。缓解:①`/etc/environment` 加 `GLIBC_TUNABLES=glibc.cpu.hwcaps=-AVX2,-AVX512F,-AVX`(glibc 2.41 支持,libatomic/字符串函数回落 SSE2);②重装后开荒第一步=stress-ng(avx2/memcpy/vm)+20 轮编译循环实测复现率,≈0 则接受(「偶发 SEGV 先查 dmesg、重试」入 runbook),频发则建议机房换整机;③压测基线前置 24h 稳定性门槛(dmesg 零新增+进程零重启)。 +- VS Code 使用:裸 `code`(不带 --no-sandbox)**可正常打开**——冷启动 renderer 闪崩 1 次后自动 reload;`--no-sandbox` 非必需(关沙箱有安全代价)。 +- AppArmor:Debian 13 非特权 userns 限制存在,`/etc/apparmor.d/code`(vscode, userns, unconfined)profile 正常加载中(2026-11-12 已重载确认)。 +- SSH 免交互登录(本机无 sshpass/expect/paramiko):OpenSSH≥8.4 用 `SSH_ASKPASS_REQUIRE=force`+setsid,或 python3 标准库 pty 驱动(已验证模板);清理远程进程勿用 `pkill -f`(匹配 bash -c 自杀),用 `pkill -x` 按进程名。 + +## 部署铁律(教训留痕) + + +- **串行部署**:build 完成→kill→确认退出→nohup→`md5sum /proc/PID/exe` 比对(并行 build+kill 会致旧 inode 进程跑旧代码,Day 70 教训)。 +- `pgrep -f` 会匹配 bash 壳须排除(watchdog 同款坑)。