fix: reconcile shared-channel receipts and protocol logs
This commit is contained in:
hectorzhao
@@ -1564,7 +1564,7 @@
|
||||
|
||||
## 2026-07-20 回执、报表、安全与公开 HTTP 接口收口要求
|
||||
|
||||
1. 上游回执按内部消息 ID，或 `channelId + gatewayMessageId + DestTerminalId` 对提交记录作唯一匹配；同账号多通道不得互相认领。每个回执事件必须有数据库唯一键，并发或重复事件不得重复生成记录、退款、计费或下游投递。
|
||||
1. 供应商回执优先按内部消息 ID，或 `channelId + gatewayMessageId + DestTerminalId` 对提交记录/长短信分片审计作唯一匹配。若同一供应商账号配置了多个物理通道连接，回执可能从非原提交连接返回，此时仅允许在“账号、Gateway 主机、端口、协议及 CMPP 版本全部一致，且 `gatewayMessageId + DestTerminalId` 只有一个候选提交/分片”时跨连接认领，并仍归属原提交的逻辑通道；任一字段不同或候选不唯一必须拒绝自动匹配。每个回执事件必须以逻辑通道生成数据库唯一键，并发或重复事件不得重复生成记录、退款、计费或企业应用投递。
|
||||
2. 成功回执统一更新短信主记录状态、回执状态、到达时间、真实通道、通道消息号、原始回执码和文本；失败、超时和未知回执保留可解释状态，最终失败只退款一次。
|
||||
3. 对账、利润和质量报表统一以短信记录计费条数为发送量，以唯一主记录终态统计成功/失败；收入取扣费流水，返还取退款流水，成本取真实提交通道单价，利润等于收入减成本。到达时长按提交至成功回执计算，延迟回执由 T+1 和 T-4 至 T-1 重算覆盖；查询、页面和 CSV 共用同一聚合表。
|
||||
4. 运营端与客户端用户接口使用各自安全 DTO，禁止输出密码散列、会话版本、登录失败内部计数和密钥字段。后端禁止自删除/自停用、禁止删除或降权最后一个平台管理员及企业管理员，并强制校验跨租户操作；唯一冲突返回 HTTP 409 和明确字段。
|
||||
@@ -1666,7 +1666,9 @@
|
||||
## 2026-07-24 CMPP/HTTP 通讯交互日志要求
|
||||
|
||||
1. 运营端“系统日志”必须将人员操作审计与协议通讯日志分成两个独立页签。通讯日志至少支持协议、交互方向、事件类型、结果、关键字和时间范围过滤，并展示平台消息号、上游消息号或HTTP请求号、脱敏对象、结果码、耗时和安全详情。
|
||||
2. CMPP应覆盖客户登录/Submit、供应商SubmitResp、状态报告Deliver、上行Deliver及平台下游投递；HTTP应覆盖客户发送请求和平台回执/上行Webhook。日志状态至少区分已收到、已受理、成功、重试和失败，不能只记录最终成功。
|
||||
3. Gateway收到状态报告或上行后，必须对解包/解码失败及转发NestJS失败输出结构化安全日志；NestJS入口应分别记录到达和业务处理结果，以便区分“上游未发”“Gateway未收到”“Gateway转发失败”和“API落库失败”。
|
||||
2. CMPP应覆盖客户登录/Submit、供应商SubmitResp、状态报告Deliver、上行Deliver及平台下游投递；HTTP应覆盖客户发送请求和平台回执/上行Webhook。数据库中一条记录必须对应一个真实业务报文，不得把同一报文的“入口收到”和“处理成功”拆成两条记录；处理结果、结果码和耗时写在该报文同一条记录中，失败、重试等后续真实交互另行记录。
|
||||
3. Gateway收到状态报告或上行后，必须对解包/解码失败及转发NestJS失败输出结构化安全日志；NestJS入口把业务处理结果合并回同一报文记录，以便区分“上游未发”“Gateway未收到”“Gateway转发失败”和“API落库失败”。一条正常短短信的供应商侧完整成功闭环应依次展示四个真实报文：平台→通道 `CMPP_SUBMIT`、通道→平台 `CMPP_SUBMIT_RESP`、通道→平台 `CMPP_DELIVER`、平台→通道 `CMPP_DELIVER_RESP`；箭头只表达报文实际传输方向。
|
||||
4. 通讯日志不得保存短信正文、密码、密钥、Token、签名鉴权值或完整HTTP请求体；手机号只保存脱敏值。CMPP心跳不得逐包写入数据库，连接健康仍使用连接状态和聚合指标。
|
||||
5. 通讯日志写入不能阻塞短信主链路，默认批量异步写入，缓冲区应有上限和溢出告警；热数据默认保留30天，保留期允许通过环境变量配置。
|
||||
6. 通讯日志方向固定使用“企业应用 → 平台、平台 → 供应商通道、供应商通道 → 平台、平台 → 企业应用”。供应商长短信每个真实 `SUBMIT` 和 `SUBMIT_RESP` 分片各记一条，企业应用每个真实 `SUBMIT_RESP` 也必须记录；内部 `submit-result` 聚合回调不是协议报文，不得重复生成通讯日志。
|
||||
7. 供应商长短信回执必须先写入对应 `SmsMessageSegmentAudit`。仅当同一提交尝试的全部分片均为 `delivered` 时，主记录才转 `delivered` 并向企业应用投递一次最终回执；任一分片明确失败可进入最终失败/补发状态，分片尚未齐全时主记录保持 `submitted`，不得由首片成功提前聚合。
|
||||
|
||||
@@ -3786,9 +3786,14 @@ npm run verify:phase8
|
||||
## 2026-07-24 CMPP/HTTP 通讯交互日志用例
|
||||
|
||||
- `TC-PROTOCOL-LOG-001`：向Gateway客户认证入口提交不存在的CMPP账号；真实接口返回业务4xx，通讯日志分别出现`received`和`failed`事件，账号可检索、耗时和安全错误可见，数据库无短信业务记录。
|
||||
- `TC-PROTOCOL-LOG-002`：真实CMPP Submit获得供应商SubmitResp；通讯日志可按CMPP、通道到平台、SubmitResp及平台消息号筛选，展示上游消息号和结果码，不包含短信正文或通道密码。
|
||||
- `TC-PROTOCOL-LOG-003`：供应商发送DELIVER状态报告；Gateway结构化日志出现收到事件，NestJS通讯日志依次出现入口收到和落库成功。构造解包失败或API拒绝时必须出现对应失败证据，不能静默返回。
|
||||
- `TC-PROTOCOL-LOG-002`：真实CMPP Submit获得供应商SubmitResp；通讯日志可按CMPP、通道到平台、SubmitResp及平台消息号筛选，展示上游消息号和结果码，不包含短信正文或通道密码；同一个SubmitResp只能落一条最终处理结果，不得同时出现`received`和`success`重复行。
|
||||
- `TC-PROTOCOL-LOG-003`：供应商发送DELIVER状态报告；Gateway结构化日志出现收到事件，NestJS通讯日志以一条记录展示该报文及最终处理结果。构造解包失败或API拒绝时必须出现对应失败证据，不能静默返回。
|
||||
- `TC-PROTOCOL-LOG-004`：通过公开HTTP API提交合法和非法请求；通讯日志展示客户到平台的受理或失败状态、请求号、脱敏手机号、业务码和耗时，鉴权头、密钥和正文不得入库。
|
||||
- `TC-PROTOCOL-LOG-005`：平台向客户投递回执或上行Webhook并触发成功、网络失败和重试；通讯日志展示事件ID、HTTP状态或网络错误、耗时、尝试次数及最终状态，真实`HttpWebhookAttempt`状态一致。
|
||||
- `TC-PROTOCOL-LOG-006`：连续运行CMPP心跳；`ProtocolInteractionLog`行数不随每个ACTIVE_TEST增长，连接状态中的最近心跳仍更新。超过配置保留期的数据被清理，业务表及操作审计不受影响。
|
||||
- `TC-PROTOCOL-LOG-007`：运营端真实登录后打开系统日志，键盘切换“系统与操作日志/通讯交互日志”，筛选、分页、详情及固定操作列可用；桌面和平板/手机不产生页面级横向溢出，宽表允许容器内滚动，控制台无error/warn。
|
||||
- `TC-PROTOCOL-LOG-008`：一条真实短短信取得成功状态报告后，按同一平台消息号查询应恰好看到四个供应商侧真实业务报文：`平台→通道/CMPP_SUBMIT`、`通道→平台/CMPP_SUBMIT_RESP`、`通道→平台/CMPP_DELIVER`、`平台→通道/CMPP_DELIVER_RESP`；每个报文只出现一条，箭头与抓包传输方向一致，长短信则按实际分片分别记录Submit/SubmitResp。
|
||||
- `TC-PROTOCOL-LOG-009`：企业应用提交短信时，入站Submit显示“企业应用→平台”，每个实际返回的SubmitResp显示“平台→企业应用”；供应商侧统一显示“平台→供应商通道/供应商通道→平台”，不得再使用含义模糊的客户/通道箭头。
|
||||
- `TC-RECEIPT-SHARED-010`：供应商账号、Gateway主机、端口、协议和CMPP版本均相同的两个物理通道连接中，回执从副连接进入、原连接存在唯一`gatewayMessageId + DestTerminalId`分片候选时，应写入原提交逻辑通道；账号或端点任一不同、或候选超过一条时不得自动匹配。
|
||||
- `TC-RECEIPT-LONG-011`：两分片长短信仅收到第一片`DELIVRD`时，`SmsMessageRecord`保持`submitted`且不创建企业应用最终回执；第二片到达后两条分片审计均为`delivered`，主记录只聚合一次为`delivered`，重复回执不得重复投递、扣费或退款。
|
||||
- `TC-PROTOCOL-LOG-012`：供应商长短信每个真实分片分别产生一条`平台→供应商通道/CMPP_SUBMIT`和一条`供应商通道→平台/CMPP_SUBMIT_RESP`；内部`submit-result`聚合回调不得额外落协议日志。
|
||||
|
||||
@@ -2341,3 +2341,23 @@ git diff --check
|
||||
- Gateway重启后5条启用上游通道中3条立即连接，“富泷物业-联通/电信”共享账号`C59748`首次被供应商返回`auth failed`；自动重连按`nextReconnectAt=11:00:58`执行后两条均恢复。最终5/5通道全部`connected/currentConnections=1/desiredConnections=1`，最近心跳持续刷新，`lastError`和`nextReconnectAt`清空。
|
||||
- 公网首页、运营登录、客户端登录和API health均HTTP 200，公网CMPP 17890 TCP连接成功。真实运营账号通过算术验证码登录，在“系统日志→通讯交互日志”看到预发布CMPP连接的`received/success`事件、耗时和固定详情列；浏览器控制台0条error/warn。
|
||||
- 发布后API/Gateway日志未出现panic、fatal、unhandled、exception、通讯日志批量写入失败、回执解包失败或API转发失败；Nginx无error/crit/emerg。未发送真实短信、未充值、未审核、未删除或修改业务对象。
|
||||
|
||||
## 2026-07-24 通讯日志方向与重复记录修正（本地未提交、未部署）
|
||||
|
||||
- 复核预发布号码`18821203795`对应消息`MSG-TEST-1784863949078-b28e828d`确认：原页面四条记录全部显示“通道→平台”，不是四个完整协议报文，而是仅采集了Gateway转入NestJS的`CMPP_SUBMIT_RESP`和`CMPP_DELIVER`，并把每个报文各拆成`received/success`两行；真实下行`CMPP_SUBMIT`与`CMPP_DELIVER_RESP`此前未采集，因此箭头虽符合现有事件入口方向，但不足以表达完整交互并造成重复观感。
|
||||
- 改为“一条数据库记录对应一个真实业务报文”：NestJS不再为同一入站报文分别写`received`和`success`，只落最终成功或失败结果；Go Gateway在真实`SendReqPkt(CMPP_SUBMIT)`及`SendRspPkt(CMPP_DELIVER_RESP)`写包完成后异步上报平台→通道事件。正常短短信完整成功闭环将显示`CMPP_SUBMIT → CMPP_SUBMIT_RESP → CMPP_DELIVER → CMPP_DELIVER_RESP`四条真实报文及实际传输方向；历史`received`行保留并标记为历史，不修改既有预发布数据。
|
||||
- Gateway遥测使用独立goroutine和既有HTTP超时，不阻塞发送/回执读循环；API仅接受`cmpp + platform_to_channel + submit/deliver_resp + success/failed`白名单事件，不接收正文、密码或密钥。
|
||||
- 本地使用真实NestJS API、真实算术验证码管理员会话和真实PostgreSQL写入两条安全的合成出站协议事件（未发送短信），再从运营端查询`MSG-DIRECTION-SMOKE`，页面正确显示“平台→通道 / CMPP_SUBMIT / 已发送”和“平台→通道 / CMPP_DELIVER_RESP / 已发送”；浏览器控制台0条error/warn。
|
||||
- 自动化验证：新增Controller单元测试覆盖入站单报文单记录和Gateway白名单，新增Go测试覆盖出站遥测payload；API全量、API/前端构建、Prisma validate、Gateway全量测试及`git diff --check`结果见本次会话最终记录。
|
||||
- 当前修改保持未提交、未推送、未部署；预发布仍运行`0bfeb0839ee6b67611e13796f46c19fc05b88de9`，发布前不得把本地验证结果误认为预发布已生效。
|
||||
|
||||
## 2026-07-24 跨连接回执、长短信聚合与通讯日志闭环修复（发布前）
|
||||
|
||||
- 对号码`13127620092`的预发布只读证据确认：两分片均已由供应商受理，第二片回执从同账号复制通道连接返回。Gateway内存映射按物理连接隔离，未找到原提交后上报了`receipt-736070230367350788`和当前连接通道；NestJS又要求`channelId + gatewayMessageId`严格一致，最终通讯日志显示`SMS message record not found`。首片`DELIVRD`同时提前把主记录改成`delivered`，没有等待第二片，是独立的长短信聚合缺陷。
|
||||
- 回执匹配增加分片审计路径，并把“同供应商”固定为账号、Gateway主机、端口、协议和CMPP版本全部一致。只有`gatewayMessageId + DestTerminalId`在该供应商范围内唯一时才允许跨物理连接认领；回执、幂等键和主记录仍归属原提交逻辑通道。不同供应商或候选不唯一继续拒绝，避免串单。
|
||||
- 长短信每片回执先写`SmsMessageSegmentAudit`。部分成功时主记录保持`submitted`且不向企业应用投递最终回执；全部分片成功后才聚合为`delivered`并投递一次。任一明确失败进入既有最终失败/补发路径，重复回执继续由逻辑通道回执键幂等。
|
||||
- 通讯日志改为一条真实业务报文一条记录：供应商长短信每片真实`SUBMIT/SUBMIT_RESP`分别采集，内部`submit-result`聚合回调不重复落协议日志；Gateway补充供应商`SUBMIT`、`SUBMIT_RESP`、`DELIVER_RESP`和企业应用`SUBMIT_RESP`出入方向。运营端方向名称统一为“企业应用→平台、平台→供应商通道、供应商通道→平台、平台→企业应用”，回执成功处理后用真实主消息ID替换临时`receipt-*`标识。
|
||||
- 新增回归覆盖：同供应商副连接唯一匹配、不同供应商拒绝、两分片未齐不提前送达、全部到齐一次聚合、内部回调不重复记录、入站服务真实SubmitResp遥测及安全白名单。API定向2 suites/90项、API全量26 suites/313项、Gateway全量`go test ./...`和`go vet ./...`、API/前端build、Prisma generate/validate/status（本地67条migration最新）、`git diff --check`均通过。
|
||||
- 使用当前构建启动独立本地NestJS API，连接真实PostgreSQL和Redis执行`tools/smoke/receipt-cross-connection-smoke.mjs`：第二片从副连接进入后回执行的逻辑通道为原通道、主记录保持`submitted`；第一片补齐后主记录为`delivered`，恰好2条回执和2个已送达分片，脚本最终清理全部合成业务数据。
|
||||
- `verify:phase8`首次使用共享Redis且本机已有API争用时为373.05 TPS，低于500阈值，明确记为失败；改用独立临时Redis完整重跑为764.69 TPS并通过，临时Redis随后停止。前端仅保留既有约1.93MB单chunk警告。
|
||||
- 本次不新增Prisma模型或migration。发布后仍需只读确认服务、67条migration、Redis Stream、5条供应商通道重连、通讯日志新方向和近期错误；未经单独授权不发送真实短信，也不改写`13127620092`历史业务记录。
|
||||
|
||||
Reference in New Issue
Block a user