fix: close receipt delivery workflows

2026-07-24 14:40:57 +08:00
parent 2ee39056eb
commit 91f04f5288
22 changed files with 829 additions and 48 deletions
@@ -1620,6 +1620,8 @@
 - 最终入账前必须调用真实后端预检并重复展示企业名称、编码、唯一ID、操作方向、当前现金余额、本次变动、预计现金余额和备注；余额以PostgreSQL账户读取结果为准，不能用前端静态计算冒充资格检查。
 - 人工充值请求必须使用当前会话操作者、8至128位幂等键和账户`updatedAt`版本。相同幂等键同一请求返回原订单/操作单和`replayed=true`；不同范围复用键或账户版本变化必须返回冲突并要求重新核对。
 - RechargeOrder、TenantAccount余额增量、AccountTransaction和OperationLog必须在同一Serializable事务内原子完成；审计记录需包含前余额、变动金额、后余额、订单号、原因和幂等键。正数为充值，负数为冲正，金额精确到小数点后4位且不得为0。
+- 运营端充值记录必须提供可截图的账户充值回执。回执只能使用真实充值订单、企业和关联账务流水数据，展示系统真实Logo、入账状态、企业名称与编码、订单号、入账时间、前后余额、入账方式和备注；不得使用前端临时数据补齐缺失字段。
+- 回执的“本次充值金额”按实际精度显示：整数金额不显示小数部分，存在小数时仅保留有效小数位；前后余额继续遵循平台统一的四位金额精度。

 ## 2026-07-22 UI/UX A7公共Dialog契约

@@ -1672,3 +1674,6 @@
 5. 通讯日志写入不能阻塞短信主链路，默认批量异步写入，缓冲区应有上限和溢出告警；热数据默认保留30天，保留期允许通过环境变量配置。
 6. 通讯日志方向固定使用“企业应用 → 平台、平台 → 供应商通道、供应商通道 → 平台、平台 → 企业应用”。供应商长短信每个真实 `SUBMIT` 和 `SUBMIT_RESP` 分片各记一条，企业应用每个真实 `SUBMIT_RESP` 也必须记录；内部 `submit-result` 聚合回调不是协议报文，不得重复生成通讯日志。
 7. 供应商长短信回执必须先写入对应 `SmsMessageSegmentAudit`。仅当同一提交尝试的全部分片均为 `delivered` 时，主记录才转 `delivered` 并向企业应用投递一次最终回执；任一分片明确失败可进入最终失败/补发状态，分片尚未齐全时主记录保持 `submitted`，不得由首片成功提前聚合。
+8. 长短信任一分片返回非成功终态时，系统必须通过该分片审计关联的提交记录识别当前发送尝试，不得仅以主记录保存的首片上游消息号判断；确认属于当前尝试后，整条短信立即进入失败/补发或退款终态，无需等待其余分片回执。
+9. 回执和上行投递方式不得由运营人员选择。企业应用开通CMPP接口即按CMPP投递，开通HTTP接口且对应Webhook地址非空即按HTTP投递，两者同时满足时双投；任一地址为空时只跳过该类HTTP事件。运营端企业应用HTTP参数页必须始终可编辑回执和上行Webhook地址，不因HTTP接口开关关闭而隐藏。
+10. Gateway向企业应用发送真实 `CMPP_DELIVER` 以及收到企业应用真实 `CMPP_DELIVER_RESP` 时，都必须各写一条通讯交互日志，分别使用“平台→企业应用”和“企业应用→平台”方向；下游投递记录继续承担排队、重试和ACK业务状态，不得以通讯日志替代。
@@ -3408,6 +3408,7 @@ npm run verify:phase8
 | TC-BILLING-011 | 分别准备 `余额+授信` 为正数、0 和负数的账户，使用相同短信费用发起发送。 | 和为正数时允许发送；和为 0 或负数时提示余额不足。判断公式为 `balanceCents + creditCents > 0`，与本次费用和套餐无关。 |
 | TC-BILLING-012 | 已扣费短信收到最终失败回执；另一个消息在提交前失败并释放冻结；另准备一笔任务冻结转扣费时的批次级释放。 | 最终失败只生成一条 `refunded` 并计入“今日返还”，重复回执不重复退款；提交前失败生成 `released + relatedType=sms_message_record` 并计入“今日返还”；冻结转扣费的 `released + relatedType=sms_batch_task` 属于内部转换，不计入“今日返还”；客户端和运营端当日金额一致且保留三位小数。 |
 | TC-BILLING-013 | 准备已提交扣费但 72 小时完全无回执的 `submitted` 短信，以及有 `UNKNOWN` 回执且超过 72 小时的短信；启动 API 定时扫描并模拟重复扫描。 | 两类短信都转为 timeout 并退款；任务进度刷新；同一短信只退款一次；定时扫描默认启用且每 5 分钟执行。 |
+| TC-BILLING-014 | 在运营端充值记录中分别打开整数金额、含1至4位有效小数、负数冲正以及缺少可追溯余额的真实订单回执。 | 每行提供“查看回执”；弹窗左上只使用系统真实Logo；企业、订单号、时间、备注与数据库订单一致；可追溯订单的入账前余额等于入账后余额减本次变动；无快照时前后余额不得伪造；主金额整数不显示小数，非整数仅显示有效小数，余额仍显示四位精度；正数显示已入账，负数显示已冲正。 |
 | TC-SEC-006 | 安装 API 生产依赖并执行 `npm audit`；使用缺文件、多文件、超大文件、超量字段和正常单文件调用认证后的 multipart 上传接口。 | NestJS/Multer/Hono 已升级或锁定到修复版本，生产依赖 audit 为 0；接口只接受一个不超过 20MB 的文件，并限制字段、part、字段名、字段值和 header pair 数量；异常请求返回受控 4xx，正常文件仍写入真实 MinIO 和 `FileObject`。 |

 ### 17.5.1 报表对账细化
@@ -3797,3 +3798,7 @@ npm run verify:phase8
 - `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`聚合回调不得额外落协议日志。
+- `TC-RECEIPT-LONG-013`：两分片长短信主记录保存首片上游消息号，第二片返回`YL:1014`等任意非成功状态且首片未回执；系统通过第二片审计识别当前提交尝试，整条短信进入失败/补发或退款终态并只投递一次最终失败回执，不再卡在`submitted`。
+- `TC-DELIVERY-AUTO-014`：分别配置仅CMPP、仅HTTP、CMPP+HTTP、两者均关闭四种应用状态；回执与上行分别只产生CMPP下游记录、HTTP Webhook事件、两者各一条、均不产生。修改历史手工投递模式不得改变自动计算结果。
+- `TC-HTTP-WEBHOOK-015`：运营端关闭HTTP接口后，回执和上行Webhook地址输入框仍显示且可保存；任一地址保存为空时删除对应有效端点，后续不推送该类HTTP事件，另一非空地址不受影响。
+- `TC-PROTOCOL-LOG-016`：在线企业应用收到回执或上行 `CMPP_DELIVER` 并返回 `CMPP_DELIVER_RESP`；通讯日志各出现一条“平台→企业应用/DELIVER”和“企业应用→平台/DELIVER_RESP”，结果、消息号、序列号和投递记录一致，下游投递记录仍独立展示发送、ACK和重试状态。
@@ -2372,3 +2372,22 @@ git diff --check
 - Gateway重启后5条活动供应商通道有4条立即在线，“富泷物业-联通”首次鉴权失败并按数据库`nextReconnectAt=2026-07-24 12:59:31+08`自动慢重试；到13:00只读复核时5/5均为`connected/currentConnections=1/desiredConnections=1`，最近心跳持续刷新、`nextReconnectAt`与`lastError`清空。
 - 公网首页、运营登录、客户端登录和API health均HTTP 200，公网CMPP 17890 TCP连接成功。真实浏览器加载运营端登录页，标题正确、页面无横向溢出、控制台0条业务error/warn；因图形验证码保护，本轮未绕过登录，登录后通讯日志页面仍需下一次人工登录结合真实短信复测。
 - 发布后API/Gateway日志未出现panic、fatal、unhandled、exception、通讯遥测失败或`SMS message record not found`。本次未发送真实短信、未修改或回填`13127620092`历史业务数据；跨连接真实供应商回执和长短信两片最终聚合仍需下一次授权测试短信或自然业务回执验证。
+
+## 2026-07-24 运营端账户充值回执（本地未提交、未部署）
+
+- 运营端充值记录每行新增“查看回执”操作，弹窗直接使用真实`RechargeOrder`、企业信息及订单关联的`balanceAfterCents`，据此计算入账前余额；历史记录缺少可追溯余额时显示`-`，不使用当前账户余额或前端假数据补齐。
+- 回执左上只展示系统现有`/logo/logo1.png`真实Logo；展示入账状态、本次金额、企业名称和编码、订单号、入账时间、前后余额、入账方式与备注，适合客户截图留存。
+- “本次充值金额”采用实际精度：整数不显示小数，存在小数时移除末尾无效零；前后余额继续显示平台统一四位精度。正数显示“已入账”，负数冲正显示“已冲正”。
+- 金额边界验证结果：`10000.0000 → 10,000`、`10000.2500 → 10,000.25`、`10000.0001 → 10,000.0001`、负数冲正`-123.4500 → 123.45`，符合主金额按实际精度展示口径。
+- 使用Node.js v24.14.0执行前端TypeScript和Vite生产构建通过，保留既有约1.93MB单chunk/579.51KB gzip警告；`git diff --check`通过。首次由系统旧Node执行时Vite不支持`??=`且错误返回0，已明确排除，未将其计为通过。
+- 浏览器加载真实本地前端/API后进入运营登录页，页面标题正确、控制台0条error/warn；由于当前浏览器无有效会话且存在图形验证码，本轮未绕过验证码，登录后的“查看回执”点击与视觉验收仍需人工登录后补测。
+- 本轮按要求保持未提交、未推送、未部署；预发布仍运行既有版本，不包含充值回执功能。
+
+## 2026-07-24 长短信失败终态、自动双通道投递与企业侧通讯日志（发布前）
+
+- 预发布只读复核号码`18821203795`的消息`MSG-e4ded553-8f08-4f7d-85ae-06a30b163e86`：主记录保存首片上游消息号`736078096474128384`，第二片`736078096490905600`收到`undelivered/YL:1014`，首片无回执。原逻辑只按主记录首片消息号查提交记录，导致第二片虽写入分片审计，但被误判为非当前尝试，主记录卡在`submitted`且未建立最终下游投递。
+- 修复为优先通过`SmsMessageSegmentAudit.gatewayMessageId`取得该分片所属`submitRecordId/submitId/channelId`，再执行当前尝试判断。长短信任一分片明确失败即可沿既有补发、退款和最终回执链路使整条短信终态化，不等待缺失分片；供应商原始非成功码（包括`YL:1014`）保持原样，不增加码表。
+- HTTP和CMPP投递改为按接口能力自动派生：CMPP开通即建CMPP下游投递，HTTP开通且对应Webhook地址有效即建HTTP事件，两者同时开通时双投。运营端不再提供回执/上行投递方式选择，HTTP关闭时仍显示并允许维护两个Webhook地址，保存空地址会删除对应端点并停止该类HTTP推送。
+- Gateway补充企业侧真实`CMPP_DELIVER`发送成功/失败以及`CMPP_DELIVER_RESP`接收结果通讯日志，API白名单允许`platform_to_client + deliver_receipt/deliver_uplink`和`client_to_platform + deliver_resp`。通讯日志只描述真实协议报文；`CmppDownstreamDelivery`继续保存排队、发送、ACK、失败和重试业务状态，两者不合并。
+- 新增migration`20260724143000_derive_application_delivery_modes`，按当前CMPP/HTTP开通状态回填历史配置的派生模式，避免旧人工模式继续影响展示或参数复制。
+- 已完成定向回归：OpenAPI、短信配置和Gateway事件3 suites/67项通过；SendChain新增长短信非首片失败、仅HTTP投递和CMPP关闭3项通过；Gateway inbound全量通过并覆盖企业侧DELIVER/DELIVER_RESP日志。另一个会话的运营端账户充值回执源码和文档已一并纳入本发布分支，原工作区未覆盖。