lislgosms/docs/report-generation-reliability-20260908.md

日报生成超时修复

维护日期：2026-09-08。适用于对账单、利润报表、发送质量报表的共同生成任务。本文补充需求 5.19.1的执行与失败恢复机制，不改变收入、成本、计费条数、质量维度及 T+1 / T-4～T-1 业务口径。实施结果见测试进度。

证据与影响

预生产版本 633ba597754c1b89943ea3a819f45042f41b019a 在 2026-09-08 16:40～16:51 只读核验时，三类报表最新日期均为 9 月 2 日，9 月 3～7 日有短信却缺报表。保留日志有 93 次生成失败，最近 16:12 的错误为 Prisma 事务上限 5000ms、实际已耗时 7510ms。应用利润成本 CTE 未限定原短信日期；9 月 4 日只有 2492 条短信，却扫描 103450 条 accepted 提交。仅执行原 SELECT 的实际计划耗时 9090.976ms；添加原短信日期范围的只读候选耗时 90.515ms。单次对照可能受缓存影响，不代表完整任务提速比例或已经上线。

同日期三类报表共用事务，应用利润耗时使事务过期，在下一条通道利润语句处报错，已插入的对账单也回滚。原滚动任务遇到一个日期失败即退出，阻止后续日期执行。

最小修复设计

1. 应用利润的成本 CTE 在关联 SmsMessageRecord 后限定 message.queuedAt >= startAt AND message.queuedAt < endAt，继续累计这些短信的全部 accepted 提交，包括跨日补发。分片审计优先、无分片审计才兼容明确成功的历史回执；不按当前通道价格倒算，不改通道维度的实际提交日归属。
2. 每个日期仍在一个独立事务内原子重建对账、应用/通道利润及四个质量维度；任何失败都保留该日期旧报表，不能先删后在事务外插入。
3. 报表专用事务默认上限 30000ms、获取连接最长等待 5000ms。REPORT_REFRESH_TRANSACTION_TIMEOUT_MS 可设正整数毫秒，非法值回退默认，上限 120000ms；不修改其他业务事务的全局设置。事务内设置同上限的 PostgreSQL statement_timeout，避免单条异常 SQL 无界运行。
4. 同日期使用 PostgreSQL 事务级 advisory lock（固定报表命名空间 + YYYYMMDD）。取锁失败视为该日期未完成，不删除报表；事务结束自动释放锁，下一调度周期可重试。日锁同时保护不同 API 实例和同进程手动服务调用。
5. T-4～T-1 逐日执行；记录每个失败日期及错误后继续其他日期，最后汇总失败并向调用者抛错。只有四天全部成功，调度器才记录本日刷新完成；部分失败保持下个小时重试资格，不静默报告成功。启动 15 秒后的首次执行和默认每小时检查保持；销毁服务同时清除启动与周期定时器。
6. 本轮不新增迁移、持久化任务表、API 写入口或自动历史回算。T-5 及更早报表不被日常任务改写；已发现的历史缺口须在修复部署后按明确授权、日期清单单独补齐。进程重启仍按现有四日窗口执行，不能声称历史缺口永久恢复机制已实现。

验收与交付边界

• 定向回归覆盖日期边界、成本扫描范围、部分失败继续后续日期、失败重试/成功去重、并发、原子回滚和生命周期停止；真实 PostgreSQL 验证跨日尝试、部分分片成功及历史回执兼容、三类报表及重复生成一致性。
• 真实 SQL 性能与结果对照在预生产只允许 SELECT、限时和只读事务，不调用生成服务或写业务表。完整生成测试使用本机独立 PostgreSQL 测试库，不能以 mock 通过代替真实数据库证据。
• 执行 API 全量、类型/生产构建及现有相关质量门禁。没有前端改动，不改变页面、权限、查询 API、端口或租户过滤。
• 本轮授权修改代码并本地提交；不推送、不部署两环境、不补跑预生产报表、不发送短信或修改业务配置。测试数据仅在隔离本地测试库构造，结果与未验证项记入进度。