perf(mkh-bom): 页面不再每次打开都等分钟级冷查(订单走独立连接 / 缓存 SWR / 后台预热) #99

Merged
yanhui merged 1 commits from yanhui-mkh-perf-1117 into main 2026-11-17 10:31:26 +08:00
Collaborator

MKH-BOM 页面性能:把订单全表扫挪出请求路径(5 项)

目的与范围

反馈:「MKH-BOM 资料每次打开或刷新页面需要的时间很长,导出明细功能也很卡」。

2026-11-17 在生产容器内实测(cangku-backend → JSReportReplica):

操作 耗时
rpt.jst_Orders 光 COUNT(*) 152.8s(158 万行,≈1 万行/秒)
loadOrderIndex() 单独跑 408.5s,最后 jst_qmcust_orderlist 读失败降级
首屏冷查(live=1&fresh=1) 126.9s,待发SKU=0、订单驱动=0、pendingOrderDegraded=true
立刻再请求一次(缓存命中) 4.2s
导出产品清单(缓存命中) 27.3s(4428 行)
导出配件明细 101.3s(51233 行)

结论:代码不笨,是缓存一直被打穿。四个原因叠加——

  1. 订单 SQL 里的 skus LIKE '%MKH%' 是前导通配,索引完全用不上 → 必然全表扫;而这个副本实例慢到 1 万行/秒。
  2. 代码传 { requestTimeout: 180000 } 想给 3 分钟,但 query() 只把它写到 request.timeout(请求级),mssql 12.x 上不生效 → 实际按共享池的池级 60s 掐断 → 每次加载都降级。
  3. 降级缓存 PENDING_ORDER_DEGRADED_TTL_MS = 60s,等于「刚失败就重打一次 60~130s 的全表扫」——自残循环。
  4. 前端首屏 / F5 / 每 2 分钟轮询都带 fresh=1 → 后端清缓存 → 必冷查。

本 PR 按这四条逐项修(对应需求里的 5 条),范围只限 MKH-BOM 链路:

# 改动 落地位置
1 订单两表 + 出库校验查询改走独立连接(freshConnection: true)+ 300s 超时 + 不重试 mkhBomService.js · cloudDatabase.js
2 降级缓存 60s → 5 分钟 PENDING_ORDER_DEGRADED_TTL_MS
3 订单索引缓存 10 → 30 分钟,新增 jobs/mkhBomPrewarmJob.js:启动后 + 每 20 分钟后台预热 mkhBomService.js · mkhBomPrewarmJob.js · index.js
4 首屏 / 轮询不再发 fresh=1,只有「同步最新数据 / 刷新数据」按钮强制重读 frontend/src/pages/MkhBomData/index.jsx
5 待发货分支补 order_date >= 近 180 天 下界 loadOrderIndex() SQL

另外两处配套(不改变业务口径):

  • loadOrderIndex 改成 stale-while-revalidate:缓存过期后先返回旧快照、后台补新值。否则「过期那一刻」的第一位用户还是要为冷查买单。
  • 后台刷新失败时保留旧索引(60 秒内不再重试),不再把缓存清成 null —— 空索引会让页面把待发货量显示成 0,比旧数据危险得多。

同步与兼容性

  • 无接口变更:/api/mkh-bom/* 的入参出参不变,freshDataContractVersion 仍为 1。
  • fresh=1 语义不变:/sync 与 ?fresh=1 仍然是「清运营缓存 + 强制重读」,只是页面不再自动发它。
  • query() 新增可选参数 freshConnection:不传时行为与之前完全一致(走共享池)。传 true 才委派给已有的 queryWithFreshConnection()(WLE 的 querySlow 用的同一条路径,已在生产验证)。
  • 新增的环境变量(都不填就用默认值,不需要改生产配置):
    • CANGKU_MKH_ORDER_QUERY_TIMEOUT_MS(默认 300000)
    • MKH_BOM_PREWARM_INTERVAL_MINUTES(默认 20,限 5~59)
    • MKH_BOM_PREWARM_DISABLED=true 可关闭预热(本地开发 / 排查用)
  • 口径影���需要业务知情(只有第 5 条):待发货订单现在只统计下单日期在近 180 天内的单。聚水潭里超过半年仍未发货的单基本都已人工作废,但如果业务认为存在「半年以上的真实待发单」,这个值就要调大(改 PENDING_ORDER_MAX_AGE_DAYS 一行)。order_date 为空的单照旧纳入,避免漏算。

验证

  • backend npm run syntax:197 个文件通过。
  • backend npm test:526 tests / 524 pass / 2 fail,两个失败都是既有环境问题、与本次改动无关:
    • 负缓存带 TTL:需要 13333 生产隧道(本机未启动)
    • secret backup survives ... owner-only permissions:Windows 下 chmod 0600 → 0666
  • test/mkhBomService.test.js:61/61 通过,其中新增 5 条针对性用例:
    1. 订单查询必须 freshConnection: true + connectRequestTimeoutMs >= 300000 + maxAttempts: 1,且不再出现 requestTimeout;
    2. 待发货 SQL 必须把 order_date 下界与 send_date IS NULL 绑在一起(180 天来自常量);
    3. 源失败时降级 TTL 必须是 5 分钟,且有效期内不重复扫表;
    4. 缓存过期后立刻返回旧快照(<1s)并真的发起后台刷新;
    5. 预热:有效期过半不重查,过期则强制刷新订单索引。
  • frontend npx eslint src/pages/MkhBomData/index.jsx:无告警。
  • frontend npm run build:通过(含 verify-router-lazy / verify-planning-entry)。
  • 冒烟:query(sql, {}, { freshConnection: true }) 实测走到了连接阶段(Failed to connect to 218.93.9.21:1433,本机无隧道),证明委派生效而不是被静默忽略。

部署后待实测(代码侧已尽力,真实收益取决于库):页面首屏、F5、导出产品清单 / 配件明细各自的耗时,以及 pendingOrderDegraded 是否变回 false、待发SKU 是否恢复。

风险与回退

  1. stale-while-revalidate 会让订单数据最多「晚 30 分钟 + 一次刷新时长」。这是本 PR 主动选择的取舍:优先保证打开页面不卡。要最新数据点「同步最新数据」。
  2. 「同步最新数据」按钮仍会冷查(clearMkhBomCache() 会清掉订单索引),冷查可能 2~5 分钟。若反代超时先返回错误,缓存仍会在后台填好,再点一次即命中。若这条体验不可接受,后续可让 sync 只清库存类缓存、保留订单索引。
  3. 第 5 条是口径变化(180 天),见上。合前请业务确认一次。
  4. 预热任务每 20 分钟打一次订单全表扫(单次可能 2~8 分钟),对本来就慢的副本库是额外固定负载。若发现挤压其它系统,把 MKH_BOM_PREWARM_INTERVAL_MINUTES 调大或 MKH_BOM_PREWARM_DISABLED=true 止损(不用发版)。
  5. 治本仍在数据侧(本 PR 做不到,需催 IT):副本实例 IO 只有 1 万行/秒;jst_Orders.skus 需要全文索引或抽一张「含 MKH 的窄表」,否则每次都要扫 158 万行。
  6. 回退:单文件级回退,直接 revert 本 PR 即可 —— 没有数据写入、没有迁移、没有改表;自动任务在 index.js 一行注册,回退后立即消失。
# MKH-BOM 页面性能:把订单全表扫挪出请求路径(5 项) ## 目的与范围 反馈:「MKH-BOM 资料每次打开或刷新页面需要的时间很长,导出明细功能也很卡」。 2026-11-17 在生产容器内实测(`cangku-backend` → `JSReportReplica`): | 操作 | 耗时 | |---|---| | `rpt.jst_Orders` **光 `COUNT(*)`** | **152.8s**(158 万行,≈1 万行/秒) | | `loadOrderIndex()` 单独跑 | **408.5s**,最后 `jst_qmcust_orderlist` 读失败降级 | | 首屏冷查(`live=1&fresh=1`) | **126.9s**,`待发SKU=0`、`订单驱动=0`、`pendingOrderDegraded=true` | | 立刻再请求一次(缓存命中) | **4.2s** | | 导出产品清单(缓存命中) | 27.3s(4428 行) | | 导出配件明细 | 101.3s(51233 行) | 结论:**代码不笨,是缓存一直被打穿**。四个原因叠加—— 1. 订单 SQL 里的 `skus LIKE '%MKH%'` 是前导通配,索引完全用不上 → 必然全表扫;而这个副本实例慢到 1 万行/秒。 2. 代码传 `{ requestTimeout: 180000 }` 想给 3 分钟,但 `query()` 只把它写到 `request.timeout`(**请求级**),mssql 12.x 上不生效 → 实际按共享池的池级 60s 掐断 → 每次加载都降级。 3. 降级缓存 `PENDING_ORDER_DEGRADED_TTL_MS = 60s`,等于「刚失败就重打一次 60~130s 的全表扫」——自残循环。 4. 前端首屏 / F5 / 每 2 分钟轮询都带 `fresh=1` → 后端清缓存 → **必冷查**。 本 PR 按这四条逐项修(对应需求里的 5 条),范围只限 MKH-BOM 链路: | # | 改动 | 落地位置 | |---|---|---| | 1 | 订单两表 + 出库校验查询改走**独立连接**(`freshConnection: true`)+ 300s 超时 + 不重试 | `mkhBomService.js` · `cloudDatabase.js` | | 2 | 降级缓存 60s → **5 分钟** | `PENDING_ORDER_DEGRADED_TTL_MS` | | 3 | 订单索引缓存 10 → **30 分钟**,新增 `jobs/mkhBomPrewarmJob.js`:启动后 + **每 20 分钟**后台预热 | `mkhBomService.js` · `mkhBomPrewarmJob.js` · `index.js` | | 4 | 首屏 / 轮询**不再发 `fresh=1`**,只有「同步最新数据 / 刷新数据」按钮强制重读 | `frontend/src/pages/MkhBomData/index.jsx` | | 5 | 待发货分支补 `order_date >= 近 180 天` 下界 | `loadOrderIndex()` SQL | 另外两处配套(不改变业务口径): - `loadOrderIndex` 改成 **stale-while-revalidate**:缓存过期后**先返回旧快照**、后台补新值。否则「过期那一刻」的第一位用户还是要为冷查买单。 - 后台刷新失败时**保留旧索引**(60 秒内不再重试),不再把缓存清成 `null` —— 空索引会让页面把待发货量显示成 0,比旧数据危险得多。 ## 同步与兼容性 - **无接口变更**:`/api/mkh-bom/*` 的入参出参不变,`freshDataContractVersion` 仍为 1。 - **`fresh=1` 语义不变**:`/sync` 与 `?fresh=1` 仍然是「清运营缓存 + 强制重读」,只是页面不再自动发它。 - **`query()` 新增可选参数 `freshConnection`**:不传时行为与之前**完全一致**(走共享池)。传 `true` 才委派给已有的 `queryWithFreshConnection()`(WLE 的 `querySlow` 用的同一条路径,已在生产验证)。 - **新增的环境变量**(都不填就用默认值,不需要改生产配置): - `CANGKU_MKH_ORDER_QUERY_TIMEOUT_MS`(默认 300000) - `MKH_BOM_PREWARM_INTERVAL_MINUTES`(默认 20,限 5~59) - `MKH_BOM_PREWARM_DISABLED=true` 可关闭预热(本地开发 / 排查用) - **口径影���需要业务知情(只有第 5 条)**:待发货订单现在只统计**下单日期在近 180 天内**的单。聚水潭里超过半年仍未发货的单基本都已人工作废,但如果业务认为存在「半年以上的真实待发单」,这个值就要调大(改 `PENDING_ORDER_MAX_AGE_DAYS` 一行)。`order_date` 为空的单**照旧纳入**,避免漏算。 ## 验证 - `backend npm run syntax`:197 个文件通过。 - `backend npm test`:**526 tests / 524 pass / 2 fail**,两个失败都是既有环境问题、与本次改动无关: - `负缓存带 TTL`:需要 13333 生产隧道(本机未启动) - `secret backup survives ... owner-only permissions`:Windows 下 chmod 0600 → 0666 - `test/mkhBomService.test.js`:**61/61 通过**,其中新增 5 条针对性用例: 1. 订单查询必须 `freshConnection: true` + `connectRequestTimeoutMs >= 300000` + `maxAttempts: 1`,且**不再出现** `requestTimeout`; 2. 待发货 SQL 必须把 `order_date` 下界与 `send_date IS NULL` 绑在一起(180 天来自常量); 3. 源失败时降级 TTL 必须是 5 分钟,且有效期内不重复扫表; 4. 缓存过期后**立刻返回旧快照**(<1s)并真的发起后台刷新; 5. 预热:有效期过半不重查,过期则强制刷新订单索引。 - `frontend npx eslint src/pages/MkhBomData/index.jsx`:无告警。 - `frontend npm run build`:通过(含 `verify-router-lazy` / `verify-planning-entry`)。 - 冒烟:`query(sql, {}, { freshConnection: true })` 实测走到了连接阶段(`Failed to connect to 218.93.9.21:1433`,本机无隧道),证明委派生效而不是被静默忽略。 **部署后待实测**(代码侧已尽力,真实收益取决于库):页面首屏、F5、导出产品清单 / 配件明细各自的耗时,以及 `pendingOrderDegraded` 是否变回 `false`、`待发SKU` 是否恢复。 ## 风险与回退 1. **`stale-while-revalidate` 会让订单数据最多「晚 30 分钟 + 一次刷新时长」**。这是本 PR 主动选择的取舍:优先保证打开页面不卡。要最新数据点「同步最新数据」。 2. **「同步最新数据」按钮仍会冷查**(`clearMkhBomCache()` 会清掉订单索引),冷查可能 2~5 分钟。若反代超时先返回错误,缓存仍会在后台填好,再点一次即命中。若这条体验不可接受,后续可让 sync 只清库存类缓存、保留订单索引。 3. **第 5 条是口径变化**(180 天),见上。合前请业务确认一次。 4. **预热任务每 20 分钟打一次订单全表扫**(单次可能 2~8 分钟),对本来就慢的副本库是额外固定负载。若发现挤压其它系统,把 `MKH_BOM_PREWARM_INTERVAL_MINUTES` 调大或 `MKH_BOM_PREWARM_DISABLED=true` 止损(不用发版)。 5. **治本仍在数据侧**(本 PR 做不到,需催 IT):副本实例 IO 只有 1 万行/秒;`jst_Orders.skus` 需要全文索引或抽一张「含 MKH 的窄表」,否则每次都要扫 158 万行。 6. **回退**:单文件级回退,直接 revert 本 PR 即可 —— 没有数据写入、没有迁移、没有改表;自动任务在 `index.js` 一行注册,回退后立即消失。
yanhui added 1 commit 2026-11-17 10:25:56 +08:00
现象:MKH-BOM 每次打开 / F5 / 每 2 分钟轮询都要等 2 分钟以上,导出明细也卡,
且页面长期处于 pendingOrderDegraded(待发 SKU = 0、订单驱动预警 = 0)。

2026-11-17 生产容器实测:rpt.jst_Orders 158 万行光 COUNT(*) 需 152.8s(≈1 万行/秒),
loadOrderIndex 单跑 408.5s 后降级;首屏冷查 126.9s,而缓存命中只要 4.2s。

四处根因与对应修复:

1) `{ requestTimeout: 180000 }` 在 query() 上不生效(只写请求级 request.timeout,
   mssql 12.x 无效)→ 实际按共享池 60s 掐断 → 每次加载都降级。
   cloudDatabase.query 新增 `freshConnection: true`:委派到既有 queryWithFreshConnection
   (独立连接,池级超时随 connectRequestTimeoutMs 放大);不传时行为不变。
   订单两表 + 出库校验改走该路径,分别 300s / 180s,maxAttempts 1(慢库重试只是把等待翻倍)。
2) 降级缓存 60s → 5 分钟:降级态每次重试都是一次全表扫,60s 等于「刚失败就重打」的自残循环。
3) 订单索引 TTL 10 → 30 分钟,并改为 stale-while-revalidate:过期后先返回旧快照、
   后台补新值(后台失败则保留旧索引并压 60 秒再试,不再把缓存清成 null 让待发货量显示 0)。
   新增 jobs/mkhBomPrewarmJob:启动 20s 后 + 每 20 分钟后台预热(间隔可用环境变量调)。
4) 前端首屏 / 轮询不再发 fresh=1(它会让后端清缓存 → 必冷查);
   强制重读只保留「同步最新数据 / 刷新数据」按钮一个入口。
5) 待发货分支补 order_date >= 近 180 天下界,不再让历史僵尸单参与扫描与累计
   (order_date 为空照旧纳入,宁可多算不漏算)。

验证:backend syntax 197 文件通过;backend test 526/524 pass(2 个既有环境失败:
13333 隧道未起、Windows chmod);mkhBomService 61/61,含新增 5 条针对本次改动的用例;
frontend eslint 无告警、npm run build 通过。

口径提示:第 5 条会改变「待发货订单量」的统计范围(只算近 180 天下单),需业务确认;
若半年以上确有待发单,改 PENDING_ORDER_MAX_AGE_DAYS 一行即可。
yanhui merged commit 2c49df3ff7 into main 2026-11-17 10:31:26 +08:00
Sign in to join this conversation.
No Reviewers
No Label
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: lunanting/cangku#99
No description provided.