Merge pull request 'fix(wle): 正文写明物流快照是否覆盖核验时刻 / 是否过旧' (#97)

backend/src/jobs/warehouseLogisticsExceptionNotifyJob.js

@@ -22,6 +22,9 @@
  *      关键词一般是「异常」，缺了会被拒（errcode 310000）。
  *   ④ 一天只推一次：状态存 system_config，按「推送日（北京时间）」去重，
  *      服务重启不会重复轰炸；手动「立即推送」才强制重发。
+ *   ⑤ 数据新鲜度必须进正文（2026-11-11 加）：只要算出异常，就要说明物流快照
+ *      是否覆盖本轮核验时刻、是否过旧 —— 否则「990 单 100% 异常」到底是真异常
+ *      还是镜像表停在昨天，群里看不出来。见 `buildFreshnessWarning`。
  *
  * 时区：生产容器是 UTC，核验批次和「到点没有」全部用 Asia/Shanghai 判断。
  */
@@ -296,6 +299,51 @@ function buildTypeLine(data = {}) {
     .join(' · ');
 }
 
+/**
+ * 快照时刻的展示形式：`2026-11-11 09:05:00` → `09:05`；**跨天则带 `MM-DD`**。
+ * ⚠️ 只显示 HH:mm 会把「昨天 11:53」读成「今天 11:53」。11-11 那批的 `snapshotAt`
+ *    其实是前一天的（镜像表停在 11-10 11:53），群里看到「快照最新只到 11:53」会误以为
+ *    当天上午的数据很新鲜 —— 与 WST「历史单审核时间必须带 MM-DD」是同一个坑。
+ */
+function formatSnapshotMoment(value, referenceDate = '') {
+  const text = String(value || '').trim();
+  if (text.length < 16) return text;
+  const datePart = text.slice(0, 10);
+  const timePart = text.slice(11, 16);
+  const refDate = String(referenceDate || '').trim().slice(0, 10);
+  if (refDate && datePart === refDate) return timePart;
+  return `${datePart.slice(5)} ${timePart}`;
+}
+
+/**
+ * 快照新鲜度告警 —— **有异常数据时才用**（0 单的情形由 `buildNotifyText` 里的 emptyWindow 分支处理）。
+ *
+ * 🔥 2026-11-11 实况：物流镜像表停在 11-10 11:53，09:10 那批算出 990 单**全部异常**，
+ *    正文却只有一句「异常 990 个（100%）」。群里没法分辨这是真异常还是数据没更新，
+ *    而这恰恰决定当天要不要去催快递。所以「没覆盖核验时刻」「快照过旧」必须写进正文，
+ *    不能只留在页面 hint 里 —— 群里干活的人看不到页面。
+ */
+function buildFreshnessWarning(freshness = {}, batch = {}) {
+  const info = freshness && typeof freshness === 'object' ? freshness : {};
+  const snapshotAt = formatSnapshotMoment(info.snapshotAt, batch.verifyDate);
+
+  if (info.coversDeadline === false) {
+    const deadline = formatSnapshotMoment(batch.deadline, batch.verifyDate);
+    return `⚠️ 数据未覆盖核验时刻：物流快照最新只到 ${snapshotAt || '未知'}`
+      + `${deadline ? `，本轮核验 ${deadline}` : ''} —— 之后的揽收/中转轨迹没进库，异常量会偏大。`
+      + '请以聚水潭实时物流为准，别按这个数去催快递。';
+  }
+  if (info.stale === true) {
+    const ageMinutes = Number(info.ageMinutes);
+    const hours = Number.isFinite(ageMinutes) && ageMinutes > 0
+      ? `（已 ${Math.round((ageMinutes / 60) * 10) / 10} 小时未刷新）`
+      : '';
+    return `⚠️ 物流快照偏旧：最新只到 ${snapshotAt || '未知'}${hours} —— 状态可能滞后，`
+      + '异常量仅供参考，请以聚水潭实时物流为准。';
+  }
+  return '';
+}
+
 function buildPageLink(pageUrl, verifyDate) {
   const base = String(pageUrl || DEFAULT_PAGE_URL);
   if (!verifyDate) return base;
@@ -333,10 +381,15 @@ function buildNotifyText(data = {}, options = {}) {
   const typeLine = buildTypeLine(data);
   if (typeLine) head.push(`类型：${typeLine}`);
 
+  // 快照新鲜度告警：只对「算出了异常」的批次有意义 —— 11-11 那批 990 单全部异常，
+  // 正文却完全看不出数据停在昨天，业务只能凭印象判断要不要催快递。
+  const freshness = data.freshness || {};
+  const freshnessWarning = totalPackages > 0 ? buildFreshnessWarning(freshness, batch) : '';
+  if (freshnessWarning) head.push(freshnessWarning);
+
   // 🔥 2026-11-02 修：0 单有两种完全不同的含义，不能都写「全部正常」——
   //   ① 数据源没同步（镜像表窗口 0 行）→ 0 单是假的，写「全部正常」等于给群里发假绿；
   //   ② 当天确实没发货 → 0 单是真的，那也不叫「正常」，叫「无发货可核」。
-  const freshness = data.freshness || {};
   if (totalPackages === 0) {
     if (freshness.emptyWindow && freshness.sourceStale) {
       const hours = Number(freshness.sourceAgeMinutes) > 0
@@ -635,6 +688,7 @@ module.exports = {
   TIMEZONE,
   buildCenterLines,
   buildDetailLine,
+  buildFreshnessWarning,
   buildNotifyText,
   buildTypeLine,
   chinaDateKey,

backend/test/warehouseLogisticsExceptionNotify.test.js

@@ -541,6 +541,71 @@ test('数据源正常但当天 0 条记录 → 说明是「库里没有记录」
   assert.match(built.text, /请到聚水潭核对/);
   assert.ok(!built.text.includes('物流数据未同步'), '表是新的，不能谎报停更');
   assert.ok(!built.text.includes('全部正常'), '0 条不能糊成「全部正常」');
+  assert.ok(!built.text.includes('数据未覆盖核验时刻'), '0 单已有专门告警，别再叠一条快照告警');
+});
+
+// ── ⑥ 有异常时的快照新鲜度也必须进正文（2026-11-11）──────────────────
+// 实况：镜像表停在 11-10 11:53，09:10 那批算出 990 单全部异常，正文只有一句
+// 「异常 990 个（100%）」。群里没法分辨「真异常」和「数据停在昨天」，
+// 而这恰恰决定当天要不要催快递。下面把两种降级（未覆盖核验时刻 / 快照过旧）钉死。
+test('快照没覆盖核验时刻 → 正文点名「未覆盖」，并把前一天的日期带上（不能只写 11:53）', () => {
+  const data = sampleData({
+    freshness: {
+      snapshotAt: '2026-10-21 11:53:00',
+      ageMinutes: 1270,
+      stale: true,
+      coversDeadline: false,
+      emptyWindow: false,
+    },
+  });
+  const built = job.buildNotifyText(data, { maxDetailRows: 30 });
+
+  assert.match(built.text, /数据未覆盖核验时刻/);
+  assert.match(built.text, /最新只到 10-21 11:53/, '跨天必须带 MM-DD，否则会被读成当天 11:53');
+  assert.match(built.text, /本轮核验 09:00/, '同一天的时刻不带日期');
+  assert.match(built.text, /别按这个数去催快递/);
+  // 抬头仍要带「异常」关键词，否则钉钉自定义关键词会拒收
+  assert.match(built.text, /【仓储物流转运异常】/);
+});
+
+test('快照同日但没过核验时刻 → 只写时分，不啰嗦日期', () => {
+  const data = sampleData({
+    freshness: { snapshotAt: '2026-10-22 08:30:00', ageMinutes: 30, stale: false, coversDeadline: false },
+  });
+  const built = job.buildNotifyText(data, { maxDetailRows: 30 });
+  assert.match(built.text, /最新只到 08:30/);
+  assert.ok(!built.text.includes('10-22 08:30'), '同一天不重复写日期');
+});
+
+test('快照过旧（stale）→ 正文写「偏旧」+ 未刷新时长，异常量标注仅供参考', () => {
+  const data = sampleData({
+    freshness: { snapshotAt: '2026-10-22 09:05:00', ageMinutes: 200, stale: true, coversDeadline: true },
+  });
+  const built = job.buildNotifyText(data, { maxDetailRows: 30 });
+  assert.match(built.text, /物流快照偏旧/);
+  assert.match(built.text, /09:05/);
+  assert.match(built.text, /已 3\.3 小时未刷新/);
+  assert.match(built.text, /仅供参考/);
+});
+
+test('快照正常 → 正文不出现任何新鲜度告警（别把正常批次也刷成黄色）', () => {
+  const data = sampleData({
+    freshness: { snapshotAt: '2026-10-22 09:05:00', ageMinutes: 3, stale: false, coversDeadline: true },
+  });
+  const built = job.buildNotifyText(data, { maxDetailRows: 30 });
+  assert.ok(!built.text.includes('数据未覆盖核验时刻'));
+  assert.ok(!built.text.includes('物流快照偏旧'));
+  assert.match(built.text, /异常 144 个包裹/);
+});
+
+test('快照字段缺失（老缓存 / 接口未返回）→ 不能崩，也不能瞎报警', () => {
+  const data = sampleData({ freshness: undefined });
+  const built = job.buildNotifyText(data, { maxDetailRows: 30 });
+  assert.match(built.text, /异常 144 个包裹/);
+  assert.ok(!built.text.includes('⚠️ 数据未覆盖'));
+
+  assert.equal(job.buildFreshnessWarning(undefined, {}), '');
+  assert.equal(job.buildFreshnessWarning({ coversDeadline: null }, {}), '');
 });
 
 // ── ⑥ 推送失败要重试，不能「一天只有一次机会」（2026-11-11）──────────────