Merge pull request 'feat: 新增「仓储中心24小时发货时效」侧栏（11 个主仓 · 12:00/16:00 双轮核验）' (#68) from codex/warehouse-ship-timeliness-1020 into main

需求（yanhui 2026-10-20）：在 MKH-BOM 列表左侧加一栏「仓储中心24小时发货时效」，
下列 11 个主仓（横林二仓、横林三仓、横林二仓品牌仓、崔桥工厂仓、崔桥工厂品牌仓、
崔桥工厂半成品仓、新苏北仓、睢宁仓、山东青岗集仓、山东品牌仓、河南洛宁仓），
从系统库存抓取已发货/未发货订单，按订单创建时间判定发货是否及时：
· 每天 12:00 核验「当天创建时间 7:00 之前」的订单是否已完成发货
· 每天 16:00 核验「当天创建时间 16:00 之前」的订单是否已完成发货

已确认的三条设计决策：
1. 子仓归属 → 连子仓一起算（京东云仓/自营仓/运营C专用仓/唯品仓等并入主仓）
2. 崔桥工厂半成品仓 → 系统无同名仓，先留空占位（不映射到配件仓 15718196）
3. 展示结构 → 只显示超时未发

实现要点
- 仓库归属用「关键词最长匹配」（不写死 wms_co_id），新增子仓只要名字含主仓关键词
  就自动归入，缓存 1h。实测 28 个子仓全部正确归入 11 个主仓，132 个代发仓零误并。
- 12:00 之前**不做核验**：resolveActiveRound 返回 null，服务层直接返回 notStarted，
  既不查订单表（接口 165ms）也不回填昨天的数据。前端显示「未到核验时间」+
  「12:00 开始首轮核验（核验当日 07:00 前创建的订单）」，11 个仓结构保留、数字显示「—」。
- 订单取数：两张表店铺互斥（jst_Orders = 京东/拼多多/抖音/得物/唯品会，
  jst_qmcust_orderlist = 天猫/淘宝/1688），并行分开查 + Node 侧按 o_id 去重合并，
  用 Promise.allSettled 保证单表失败时另一表数据仍可用（detailDegraded 标记）。
- 三态判定 pending / shippedLate / onTime：send_date 与出库表 io_date 取先到的发货痕迹，
  避免上游 send_date 回写滞后导致「已发的被判成没发」。
- 状态过滤：排除 Cancelled / Merged / **Split**（拆单父单永不发货，不排除会捞出一年前
  1.3 万条历史单），Question 仍计入待发。
- freshness 字段如实报告出库表最新 io_date，前端「发货数据可能滞后」告警，
  不拿一份可能滞后的数据去考核仓库。

排除的两次错误优化（均在代码注释里留了实测数据与复测脚本路径）
1. 用 created 替代 order_date 做窗口过滤（快 10 倍）—— 已证伪：2581 行里完全相等的只有 4 行，
   差 >1h 的 412 行，198 行跨日；典型形态 order_date=10-18 23:58 而 created=10-19 04:00:08
   （上游凌晨 4 点批量补录，created 是灌库时间不是下单时间）。业务口径是「订单创建时间」，
   只有 order_date 正确。
2. 「UNION ALL 一条 SQL 慢 5~8 倍」—— 被后续实测推翻（46.3s vs 并行 48.2s，基本持平）。

验证
- 新增 backend/test/warehouseShipTimeliness.test.js，10 条用例全绿，覆盖：
  最长匹配不误并、子仓命名、山东/河南高频前缀不误并、占位仓、12:00 前返回 null、
  12:00 轮窗口 00:00~07:00、16:00 轮窗口 00:00~16:00、状态排除表、三态分桶互斥、
  跨表重复 o_id 去重、round.windowEnd 必须带出（否则前端渲染成「核验 前」）。
- check-syntax 185 文件通过；全量 node --test 415 项 / 413 过 / 2 fail，
  两条失败均为已知环境因素（负缓存带 TTL 因 .env 有 CLOUD_DB_* 短路；
  resilientSecretStore 的 Windows 权限断言，基线恒失败）。
- 真渲染验收（组件级沙盒 + 真实接口数据）：两态均 0 控制台错误；
  已核验态 358 单超时未发、8 个仓有数字、点仓切换选中/再点取消均正常；
  多分辨率验证 1920/1600 侧栏 208px、1440/1366 收窄 176px、列表始终竖向。

.gitignore

@@ -54,5 +54,16 @@ tmall-board-speed-check.json
 **/.env.*
 !**/.env.example
 **/uploads/
+.remote-access/
+.remote-access.backup-*/
 .workbuddy/
 **/node_modules
+
+# Local verification artifacts
+/outputs/
+.git-status.txt
+
+# 本地一次性探查/调试产物（不进仓库）
+_probe_*.json
+_probe_*.js
+_work-scratch-*/

AGENTS.md

@@ -0,0 +1,15 @@
+# AI 开发协作入口
+
+开始修改、提交、推送或合并前，必须阅读并遵守 [仓库提交与合并规范](./仓库提交与合并规范.md)。准备更新生产服务器时，还必须阅读并遵守 [服务器部署规范](./服务器部署规范.md)。这些文件是本仓库多人协作的具体流程，不可仅凭本摘要跳过全文。
+
+- 每个任务使用独立目录和唯一任务分支，默认前缀 `codex/`；不得共享目录并行编辑。
+- 保留他人的未提交修改和已有提交，仅暂存本任务内容；不得清理或覆盖未知工作。
+- 推送前同步远端，逐项检查最终差异并验证；被拒绝后先查明并合并更新，禁止任何形式的强推。
+- 不改写已发布历史，不批量选择冲突的某一方；不明确的行为取舍需要负责人确认。
+- 所有变更通过 PR 进入 `main`，不得直接推送主分支；默认由非提交者审核。仓库所有者或管理员明确授权某个 PR 合并时，该书面授权可以代替独立审核，但仍必须同步最新主分支、验证最终提交并保留授权记录。
+- 不提交凭据、私钥、环境秘密或真实业务数据；不把合并授权当成生产部署授权。
+- 新建或修改数据表、映射表、查询和同步任务时，必须按实际过滤、关联、排序和唯一性设计索引，用执行计划和有代表性数据验证负载；禁止无边界全表扫描、无节制并发和重复全量同步。
+- 开发机器使用中央系统数据库和公网 TLS Redis，无需安装本地数据库；生产部署必须先将代码通过 PR 合入 `main`，并在 `/opt/cangku/deploy.lock` 锁内从服务器 Git 工作区快进拉取和验证。
+- 最终交付报告实际分支、提交 SHA、验证结果及 PR 状态，不能将“已推送”报告为“已合并”。
+
+这些文档不代表服务端保护已启用。任何 AI 工具无法自动读取规则时，由使用它的开发者主动提供全文。

README.md

@@ -2,33 +2,23 @@
 
 公开的拼多多业务精简版。欢迎所有人克隆、修改、分发代码并提交 Pull Request，代码按 MIT 许可证开放。
 
-保留商品监控、仪表盘、激励看板、营销活动、推广、商品分析、店铺体检、客服质检、上架测算、AI 买家秀和客户端管理等现有模块。部分菜单仍沿用原项目的占位页面。
+保留商品监控、仪表盘、激励看板、营销活动、推广、商品分析、工单以及在线客户端与执行任务等现有模块。部分菜单仍沿用原项目的占位页面。
 
-已删除市场数据整组页面、Claw 对话、skills 管理、平台切换与其他平台演示页，以及对应路由、页面资源、专属配置接口和权限项。首页为仪表盘。保留业务仍使用的模型配置、商品数据查询和自动上架公共服务继续可用；Claw 补全与图搜备用通道已经移除，缺失资料需使用业务接口或手工补充。
+已删除市场数据、店铺管理和运营工具整组页面、Claw 对话、skills 管理、平台切换与其他平台演示页，以及对应路由、页面资源、专属配置接口和权限项。首页为仪表盘。保留业务仍使用的模型配置、商品数据查询、桌面会话和自动上架公共服务继续可用；Claw 补全与图搜备用通道已经移除，缺失资料需使用业务接口或手工补充。
 
 ## 本地启动
 
-需要 Node.js 22、MySQL 系统库，以及业务实际使用的数据库和外部服务。仓库不包含生产环境配置、密钥、业务数据或原仓库历史。
+需要 Node.js 22。团队开发机器无需安装或初始化 MySQL、Redis 及第三方数据库；使用管理员发放的部署 Key，一次注册后自动连接中央系统数据库、公网 TLS Redis 和第三方数据库。完整步骤及安全边界见 [远程系统数据库部署](./remote-access/README.md)。
 
 ```bash
 npm --prefix backend ci
 npm --prefix frontend ci
-cp backend/.env.example backend/.env
+npm run remote:dev
 ```
 
-填写 `backend/.env` 中的连接信息与密钥，分别在两个终端启动：
+首次启动时填写配置请求地址和部署 Key，系统自动写入被 Git 忽略的本机配置并重启后端。保存一次性显示的管理员账号和密码后直接登录，不需要在本地创建数据库或继续执行设置向导。前端默认访问 http://localhost:5173，API 默认代理到本地后端。
 
-```bash
-cd backend
-npm run dev
-```
-
-```bash
-cd frontend
-npm run dev
-```
-
-前端默认访问 http://localhost:5173，API 默认代理到 http://localhost:4001，可用 `VITE_API_PROXY_TARGET` 覆盖。首次启动按照安装与设置向导初始化系统。
+拉取主仓库更新后必须停止旧的 `npm run remote:dev` 进程并重新启动，保证前后端使用同一版本。MKH 页的强制刷新带有版本协议校验；如果新前端仍代理到未重启的旧后端，页面会停止展示可能过期的库存并明确提示重启，不再将旧值冒充为“最新数据”。
 
 ## 验证与构建
 
@@ -39,8 +29,10 @@ npm --prefix frontend run check
 
 前端构建输出位于 `frontend/dist`。部署时需为单页应用配置路由回退，并代理 `/api` 与 `/cubejs-api` 到后端。
 
-启动时会迁移旧侧栏配置，并删除已退役页面的权限和专属设置；业务数据及历史聊天记录不作数据库删表操作。迁移仅作用于实际配置给此实例的系统数据库。
+启动时会迁移旧侧栏配置，并删除已退役页面的权限、专属设置和专用数据表。上架测算旧偏好表中的商品分析阈值会先迁移到商品分析专用表；其他保留模块的数据不受影响。迁移仅作用于实际配置给此实例的系统数据库。
 
 ## 参与修改
 
+开始开发前请阅读 [仓库提交与合并规范（多用户与 AI 开发必读）](./仓库提交与合并规范.md)。准备更新生产服务器时必须继续阅读 [服务器部署规范（开发者与 AI 必读）](./服务器部署规范.md)。AI 工具的规则入口为 [AGENTS.md](./AGENTS.md)。每个任务使用独立目录和分支，通过 PR、同步验证和独立审核合并，禁止强推或覆盖其他开发者的工作。
+
 所有用户均可 Fork 仓库、创建分支并提交 Pull Request。直接推送本仓库需要仓库所有者授予协作者写权限。提交时请说明修改和验证结果，勿提交 `.env`、密码、令牌、数据库备份或真实业务数据。

backend/.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+.env
+npm-debug.log*
+coverage
+runtime

backend/.env.example

@@ -116,8 +116,11 @@ S3_SECRET_ACCESS_KEY=your-secret-key
 # 两套系统库 Redis 都不可用时，才使用下面的 .env 配置兜底。
 REDIS_HOST=
 REDIS_PORT=6379
+REDIS_USERNAME=
 REDIS_PASSWORD=
 REDIS_DB=0
+REDIS_TLS=false
+REDIS_TLS_SERVER_NAME=
 # 默认 stored 表示自动选择系统库 Redis；也可临时指定 default/changzhou/env。
 REDIS_RUNTIME_PROFILE=stored
 CHANGZHOU_REDIS_SERVER_IPS=192.168.150.234

backend/Dockerfile.production

@@ -0,0 +1,21 @@
+FROM node:22-bookworm-slim
+
+ENV NODE_ENV=production
+WORKDIR /app
+
+# 每日进销存定时截图需要 Chromium 与中文字体：
+#   · fonts-noto-cjk —— 否则截图里所有中文都会变成方块
+#   · playwright install --with-deps chromium —— 默认镜像不带浏览器
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates fonts-noto-cjk \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev --no-audit --no-fund \
+    && npx playwright install --with-deps chromium \
+    && rm -rf /var/lib/apt/lists/* /root/.npm/_cacache
+
+COPY . .
+
+EXPOSE 4090
+CMD ["node", "src/index.js"]

backend/package-lock.json

@@ -28,6 +28,7 @@
         "multer": "^2.1.1",
         "mysql2": "^3.6.5",
         "node-cron": "^3.0.3",
+        "pg": "8.17.2",
         "playwright": "^1.60.0",
         "sharp": "^0.33.5",
         "uuid": "^9.0.1",

backend/package.json

@@ -10,6 +10,7 @@
     "test": "node --test test/*.test.js",
     "check": "npm run syntax && npm test",
     "alert:check": "node src/services/alertChecker.js",
+    "inventory:import-official": "node scripts/importDailyInventoryOfficial.js",
     "product-analysis:sync-replica": "node scripts/sync_jian_sun_product_analysis_tables.js"
   },
   "dependencies": {
@@ -32,6 +33,7 @@
     "multer": "^2.1.1",
     "mysql2": "^3.6.5",
     "node-cron": "^3.0.3",
+    "pg": "8.17.2",
     "playwright": "^1.60.0",
     "sharp": "^0.33.5",
     "uuid": "^9.0.1",

backend/scripts/importDailyInventoryOfficial.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * 导入聚水潭「进销存按仓导出」到每日进销存校正表
+ *
+ * 用法：
+ *   node scripts/importDailyInventoryOfficial.js <业务日期> <xlsx 路径>
+ *   node scripts/importDailyInventoryOfficial.js 2026-09-26 ./进销存_按仓_20260926.xlsx
+ *
+ * 作用：
+ *   1) 解析导出文件，校验「期初 + Σ流水 = 期末」逐仓闭合
+ *   2) 写入本地表 daily_inventory_official（同一业务日整体覆盖）
+ *   3) 回写本地快照：官方期初 → 上一业务日期末、官方期末 → 该业务日期末
+ *
+ * 页面右上角「导入聚水潭进销存」走的是同一个后端接口（POST /api/daily-inventory/official-import）。
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseWorkbook, importOfficial, checkBalance } = require('../src/services/dailyInventoryOfficial');
+const snapshotDb = require('../src/config/dailyInventorySnapshotDb');
+const { DAILY_INVENTORY_BASELINE } = require('../src/config/dailyInventoryBaseline');
+
+function prevDay(bizDate) {
+  const d = new Date(`${bizDate}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() - 1);
+  return d.toISOString().slice(0, 10);
+}
+
+async function main() {
+  const [bizDate, file] = process.argv.slice(2);
+  if (!bizDate || !/^\d{4}-\d{2}-\d{2}$/.test(bizDate)) {
+    console.error('用法: node scripts/importDailyInventoryOfficial.js <业务日期 YYYY-MM-DD> <xlsx 路径>');
+    process.exit(1);
+  }
+  if (!file || !fs.existsSync(file)) {
+    console.error(`文件不存在: ${file}`);
+    process.exit(1);
+  }
+
+  const { rows, warnings, sheetName } = parseWorkbook(fs.readFileSync(file));
+  console.log(`解析 ${path.basename(file)} [${sheetName}]：${rows.length} 行，提示：${warnings.join('；') || '无'}`);
+  if (!rows.length) {
+    console.error('未解析到仓库行，已中止');
+    process.exit(1);
+  }
+
+  const mismatches = checkBalance(rows);
+  if (mismatches.length) {
+    console.warn(`⚠ 以下 ${mismatches.length} 个仓「期初 + 流水 ≠ 期末」：`);
+    mismatches.forEach((m) => console.warn(`   ${m.warehouse}: 差 ${m.diff}`));
+  } else {
+    console.log('恒等式校验：期初 + 流水 = 期末，逐仓闭合 ✓');
+  }
+
+  const result = await importOfficial(bizDate, rows);
+  console.log(`写入 official：${result.imported} 行（${bizDate}）`);
+  if (result.unknownWarehouses.length) {
+    console.warn(`⚠ 未匹配到仓库 ID（仅按仓库名存档）：${result.unknownWarehouses.join('、')}`);
+  }
+  if (result.missingWarehouses.length) {
+    console.warn(`⚠ 清单中未出现在导出里的仓库：${result.missingWarehouses.join('、')}`);
+  }
+
+  const byId = new Map(DAILY_INVENTORY_BASELINE.map((b) => [String(b.wmsCoId), b]));
+  const known = rows.filter((r) => r.wmsCoId != null);
+  const prevDate = prevDay(bizDate);
+  const prev = await snapshotDb.fetchSnapshot(prevDate);
+  const prevCount = await snapshotDb.upsertSnapshot(prevDate, known
+    .filter((r) => r.openingQty != null)
+    .map((r) => ({
+      wmsCoId: r.wmsCoId,
+      warehouse: r.warehouse,
+      dbWarehouse: byId.get(String(r.wmsCoId))?.dbWarehouse || null,
+      closingQty: Number(r.openingQty),
+      skuCount: Number(prev.get(String(r.wmsCoId))?.skuCount || 0),
+      takenAt: null,
+    })));
+  const current = await snapshotDb.fetchSnapshot(bizDate);
+  const currentCount = await snapshotDb.upsertSnapshot(bizDate, known
+    .filter((r) => r.closingQty != null)
+    .map((r) => ({
+      wmsCoId: r.wmsCoId,
+      warehouse: r.warehouse,
+      dbWarehouse: byId.get(String(r.wmsCoId))?.dbWarehouse || null,
+      closingQty: Number(r.closingQty),
+      skuCount: Number(current.get(String(r.wmsCoId))?.skuCount || 0),
+      takenAt: null,
+    })));
+  console.log(`快照回写：${prevDate}（官方期初 → 期末）${prevCount} 行，${bizDate}（官方期末）${currentCount} 行`);
+  process.exit(0);
+}
+
+main().catch((e) => {
+  console.error('导入失败:', e.message);
+  process.exit(1);
+});

backend/scripts/sync-daily-inventory-snapshot.cjs

@@ -0,0 +1,25 @@
+/**
+ * 手动同步一次每日库存快照
+ *
+ * 用途：补跑 / 排障 / 挂到系统计划任务（Windows 任务计划程序、Linux crontab）。
+ *      业务库没有按天的历史库存结存表，本脚本把 26 仓实时库存落一份到本地快照表，
+ *      使「今日期初 = 上一业务日期末」能够自动滚动。
+ *
+ * 运行：node scripts/sync-daily-inventory-snapshot.cjs
+ *      业务日自动取库存快照库 rpt.pm_stockMonitor 的最新日期（T-1）。
+ *
+ * 生产环境下后端每日 01:30 的定时任务（src/jobs/dailyInventorySnapshotJob.js）会自动执行，
+ * 本脚本仅作为兜底与手动补跑手段。
+ */
+process.env.CANGKU_SKIP_BOOTSTRAP = '1';
+
+const { syncOnce } = require('../src/jobs/dailyInventorySnapshotJob');
+
+syncOnce('manual')
+  .then((result) => {
+    console.log('[快照同步] 结果:', JSON.stringify(result));
+  })
+  .catch((error) => {
+    console.error('[快照同步] 失败:', error.message);
+  })
+  .finally(() => process.exit(0));

backend/scripts/validateDailyInventoryFromBiz.js

@@ -0,0 +1,153 @@
+'use strict';
+/**
+ * 用业务库（JSReportReplica）反算流水，校验已导入的聚水潭官方进销存数据。
+ * 用法（先起隧道）: cd backend && node scripts/validateDailyInventoryFromBiz.js 2026-10-06
+ *
+ * 注意：业务库 jst_inventoryInfo 是 T-1 同步快照，只能精确校验「昨天」的期末；
+ *      更早的历史日会带自然变动（实测 10-05 差 0.1%~1.2%），属正常。
+ */
+const mysql = require('mysql2/promise');
+const sql = require('mssql');
+
+const BIZ_DATE = process.argv[2] || '2026-10-06';
+
+const SYS = {
+  host: '127.0.0.1',
+  port: 13307,
+  user: 'cangku_67c48c6660be787f',
+  password: 'wIJugzi26RQHF4J4BgnwxCxxecp157goR93M_IXEhqc',
+  database: 'shujuku2_system',
+};
+
+// 业务库能还原的 4 个流水列（与 dailyInventoryFlows.js 口径一致，这里加单日上界）
+const FLOWS = [
+  {
+    field: 'purchase_in',
+    label: '采购进仓',
+    sql: `SELECT p.wms_co_id AS wmsCoId, SUM(CAST(ISNULL(pi.qty,0) AS DECIMAL(18,2))) AS qty
+            FROM rpt.jst_purchase p JOIN rpt.jst_purchaseItem pi ON pi.po_id = p.po_id
+           WHERE p.wms_co_id IN (%W%) AND p.po_date >= @from AND p.po_date < @to
+             AND ISNULL(p.status,'') IN ('Confirmed','Finished') GROUP BY p.wms_co_id`,
+  },
+  {
+    field: 'purchase_return',
+    label: '采购退货',
+    sql: `SELECT o.wms_co_id AS wmsCoId, SUM(CAST(ISNULL(oi.qty,0) AS DECIMAL(18,2))) AS qty
+            FROM rpt.jst_purchaseout o JOIN rpt.jst_purchaseoutItem oi ON oi.io_id = o.io_id
+           WHERE o.wms_co_id IN (%W%) AND o.io_date >= @from AND o.io_date < @to
+           GROUP BY o.wms_co_id`,
+  },
+  {
+    field: 'sales_out',
+    label: '销售出仓',
+    sql: `SELECT o.wms_co_id AS wmsCoId, SUM(CAST(ISNULL(oi.qty,0) AS DECIMAL(18,2))) AS qty
+            FROM rpt.jst_Orders o JOIN rpt.jst_OrderItem oi ON oi.o_id = o.o_id
+           WHERE o.wms_co_id IN (%W%) AND o.send_date >= @from AND o.send_date < @to
+             AND ISNULL(o.status,'') NOT IN ('Delete','Cancelled') GROUP BY o.wms_co_id`,
+  },
+  {
+    field: 'sales_return',
+    label: '销售退货',
+    sql: `SELECT r.wms_co_id AS wmsCoId, SUM(CAST(ISNULL(ri.r_qty,0) AS DECIMAL(18,2))) AS qty
+            FROM rpt.jst_returnAndRefundInfo r JOIN rpt.jst_returnAndRefundItem ri ON ri.as_id = r.as_id
+           WHERE r.wms_co_id IN (%W%) AND r.as_date >= @from AND r.as_date < @to
+             AND ISNULL(r.type,'') IN (N'普通退货',N'拒收退货',N'换货',N'维修') GROUP BY r.wms_co_id`,
+  },
+];
+
+(async () => {
+  const sys = await mysql.createConnection(SYS);
+  const [official] = await sys.query(
+    'SELECT wms_co_id, warehouse, opening_qty, closing_qty, purchase_in, purchase_return, sales_out, sales_return FROM daily_inventory_official WHERE DATE(biz_date)=? ORDER BY closing_qty DESC',
+    [BIZ_DATE]
+  );
+  if (!official.length) {
+    console.log('官方表无 ' + BIZ_DATE + ' 数据');
+    await sys.end();
+    return;
+  }
+  const ids = official.map((r) => String(r.wms_co_id)).filter(Boolean);
+  const clause = ids.map((_, i) => '@w' + i).join(',');
+  const wparams = {};
+  ids.forEach((v, i) => (wparams['w' + i] = v));
+
+  // 业务库凭据从系统库 database_configs 现取（不落盘）
+  const [cfgRows] = await sys.query(
+    "SELECT host, port, database_name, username, password FROM database_configs WHERE name='cloud_database_public' LIMIT 1"
+  );
+  const biz = cfgRows[0];
+  await sql.connect({
+    server: biz.host,
+    port: Number(biz.port),
+    database: biz.database_name,
+    user: biz.username,
+    password: biz.password,
+    options: { encrypt: false, trustServerCertificate: true },
+    connectionTimeout: 20000,
+    requestTimeout: 180000,
+  });
+
+  const from = BIZ_DATE + ' 00:00:00';
+  const d = new Date(BIZ_DATE + 'T00:00:00Z');
+  d.setUTCDate(d.getUTCDate() + 1);
+  const to = d.toISOString().slice(0, 10) + ' 00:00:00';
+
+  const computed = {};
+  for (const f of FLOWS) {
+    const req = new sql.Request();
+    req.input('from', sql.DateTime, new Date(from));
+    req.input('to', sql.DateTime, new Date(to));
+    ids.forEach((v, i) => req.input('w' + i, sql.NVarChar, v));
+    const r = await req.query(f.sql.replace('%W%', clause));
+    r.recordset.forEach((row) => {
+      computed[String(row.wmsCoId)] = computed[String(row.wmsCoId)] || {};
+      computed[String(row.wmsCoId)][f.field] = Number(row.qty) || 0;
+    });
+  }
+
+  console.log('业务库口径反算 vs 聚水潭官方导出 —— ' + BIZ_DATE);
+  console.log('（业务库仅能还原 4/12 列；采购退货/销售出仓为流出，官方值取绝对值比较）\n');
+  const pad = (s, n) => String(s).padEnd(n);
+  console.log(
+    pad('仓库', 26) + pad('采购进仓 官方/业务库', 26) + pad('采购退货 官方/业务库', 26) + pad('销售出仓 官方/业务库', 26) + '销售退货 官方/业务库'
+  );
+  let diffs = { purchase_in: 0, sales_out: 0, purchase_return: 0, sales_return: 0 };
+  for (const o of official) {
+    const c = computed[String(o.wms_co_id)] || {};
+    const cells = ['purchase_in', 'purchase_return', 'sales_out', 'sales_return'].map((k) => {
+      const ov = Math.abs(Number(o[k]) || 0);
+      const cv = Math.abs(Number(c[k]) || 0);
+      if (Math.abs(ov - cv) > 0.005) diffs[k]++;
+      return pad(ov + ' / ' + cv, 26);
+    });
+    console.log(pad(o.warehouse, 26) + cells.join(''));
+  }
+  console.log('\n不一致仓数：' + JSON.stringify(diffs) + ' / 共 ' + official.length + ' 仓');
+
+  // 期末 vs 业务库实时库存（仅作量级参考，业务库只有实时库存）
+  const req2 = new sql.Request();
+  ids.forEach((v, i) => req2.input('w' + i, sql.NVarChar, v));
+  const inv = await req2.query(
+    `SELECT wms_co_id AS wmsCoId, SUM(CAST(ISNULL(qty,0) AS DECIMAL(18,2))) AS qty
+       FROM rpt.jst_inventoryInfo WHERE wms_co_id IN (${clause}) GROUP BY wms_co_id`
+  );
+  const invMap = {};
+  inv.recordset.forEach((r) => (invMap[String(r.wmsCoId)] = Number(r.qty) || 0));
+  console.log('\n【参考】官方' + BIZ_DATE + '期末 vs 业务库实时库存（业务库无历史快照，仅看量级）');
+  official
+    .slice()
+    .sort((a, b) => Number(b.closing_qty) - Number(a.closing_qty))
+    .slice(0, 8)
+    .forEach((o) => {
+      const live = invMap[String(o.wms_co_id)] || 0;
+      const off = Number(o.closing_qty) || 0;
+      const pct = off ? (((live - off) / off) * 100).toFixed(1) : '-';
+      console.log(pad(o.warehouse, 26) + '期末 ' + off + ' | 实时 ' + live + ' | 差 ' + pct + '%');
+    });
+
+  await sql.close();
+  await sys.end();
+})().catch((e) => {
+  console.log('FAIL', e.message);
+  process.exit(1);
+});

backend/src/api/admin.js

@@ -1,14 +1,14 @@
-const { isRetiredSystemConfigKey, pruneRetiredSidebarConfig } = require('../services/retiredFeatures');
+const {
+  isRetiredDatabaseConfigName,
+  isRetiredSystemConfigKey,
+  pruneRetiredSidebarConfig,
+} = require('../services/retiredFeatures');
 // 管理员 API
 const express = require('express');
 const router = express.Router();
 const bcrypt = require('bcryptjs');
-const crypto = require('crypto');
 const dayjs = require('dayjs');
-const fs = require('fs');
 const multer = require('multer');
-const os = require('os');
-const path = require('path');
 const { v4: uuidv4 } = require('uuid');
 const { requireRole } = require('../middleware/auth');
 const database = require('../config/database');
@@ -25,17 +25,7 @@ const {
   normalizeStorageClass,
   testObjectStorageConnection,
   uploadBase64ImageToDefaultS3,
-  uploadFileToDefaultS3,
 } = require('../services/objectStorage');
-const {
-  compareVersions,
-  getLatestDesktopRelease,
-  listDesktopReleases,
-  normalizeArchitecture,
-  normalizePlatform,
-  publishDesktopRelease,
-  validateVersion,
-} = require('../services/desktopReleaseService');
 const { listOnlineDesktopUsers } = require('../services/desktopPresenceService');
 const {
   getSystemDbConfig,
@@ -108,10 +98,6 @@ const {
   testSelectionFissionAiConfig,
 } = require('../services/selectionFissionAiSettings');
 const { testSelectionImageGenerationConfig } = require('../services/selectionImageGenerationService');
-const {
-  getProductTagConfig,
-  saveProductTagConfig,
-} = require('../services/productTagConfigService');
 
 const backfillJobs = new Map();
 const productCodeImportUpload = multer({
@@ -129,44 +115,6 @@ const productCodeImportUpload = multer({
   },
 });
 
-const desktopReleaseTempDir = path.join(os.tmpdir(), 'maixiang-desktop-releases');
-fs.mkdirSync(desktopReleaseTempDir, { recursive: true });
-const desktopReleaseUpload = multer({
-  dest: desktopReleaseTempDir,
-  limits: {
-    fileSize: 300 * 1024 * 1024,
-    files: 1,
-  },
-  fileFilter: (_req, file, callback) => {
-    if (/\.(exe|dmg)$/i.test(String(file.originalname || ''))) {
-      callback(null, true);
-      return;
-    }
-    callback(new Error('仅支持上传 Windows（.exe）或 macOS（.dmg）安装包'));
-  },
-});
-
-const uploadDesktopReleaseInstaller = (req, res, next) => {
-  desktopReleaseUpload.single('installer')(req, res, (error) => {
-    if (!error) return next();
-    if (error.code === 'LIMIT_FILE_SIZE') {
-      return res.status(413).json({ success: false, error: '安装包不能超过 300 MB' });
-    }
-    return res.status(400).json({ success: false, error: error.message || '安装包上传失败' });
-  });
-};
-
-async function sha256File(filePath) {
-  const hash = crypto.createHash('sha256');
-  await new Promise((resolve, reject) => {
-    const stream = fs.createReadStream(filePath);
-    stream.on('data', (chunk) => hash.update(chunk));
-    stream.on('error', reject);
-    stream.on('end', resolve);
-  });
-  return hash.digest('hex');
-}
-
 const runBackfill = async (job) => {
   try {
     const totalStepsPerDay = 21;
@@ -208,93 +156,6 @@ router.get('/desktop-presence', async (_req, res) => {
   }
 });
 
-router.get('/desktop-releases', async (req, res) => {
-  try {
-    const releases = await listDesktopReleases(req.query.limit);
-    res.json({
-      success: true,
-      data: releases.map((release) => ({
-        ...release,
-        downloadUrl: `/api/desktop-client/releases/${release.id}/download`,
-      })),
-    });
-  } catch (error) {
-    console.error('获取桌面客户端发布记录失败:', error);
-    res.status(500).json({ success: false, error: '获取桌面客户端发布记录失败' });
-  }
-});
-
-router.post('/desktop-releases', uploadDesktopReleaseInstaller, async (req, res) => {
-  const tempFilePath = req.file?.path;
-  try {
-    if (!req.file) {
-      return res.status(400).json({ success: false, error: '请选择需要发布的桌面客户端安装包' });
-    }
-    const version = validateVersion(req.body?.version);
-    const originalName = String(req.file.originalname || '');
-    const platform = normalizePlatform(req.body?.platform, originalName);
-    const architecture = normalizeArchitecture(req.body?.architecture, originalName, platform);
-    const expectedExtension = platform === 'darwin' ? '.dmg' : '.exe';
-    if (!originalName.toLowerCase().endsWith(expectedExtension)) {
-      return res.status(400).json({
-        success: false,
-        error: platform === 'darwin' ? 'macOS 安装包必须为 .dmg 格式' : 'Windows 安装包必须为 .exe 格式',
-      });
-    }
-    const latest = await getLatestDesktopRelease(platform, architecture);
-    if (latest && compareVersions(version, latest.version) < 0) {
-      return res.status(409).json({
-        success: false,
-        error: `发布版本 v${version} 低于当前平台最新版本 v${latest.version}`,
-      });
-    }
-
-    const fileName = platform === 'darwin'
-      ? `pdd-auto-sale-${version}-${architecture}.dmg`
-      : `pdd-auto-sale-${version}-setup.exe`;
-    const objectKey = `desktop-client/${platform}/${version}/${Date.now()}-${fileName}`;
-    const mimeType = platform === 'darwin'
-      ? 'application/x-apple-diskimage'
-      : 'application/vnd.microsoft.portable-executable';
-    const [sha256, uploadResult] = await Promise.all([
-      sha256File(tempFilePath),
-      uploadFileToDefaultS3(tempFilePath, {
-        key: objectKey,
-        mimeType,
-      }),
-    ]);
-    const release = await publishDesktopRelease({
-      version,
-      platform,
-      architecture,
-      releaseNotes: String(req.body?.releaseNotes || '').trim(),
-      objectKey: uploadResult.key,
-      fileName,
-      fileSize: req.file.size,
-      sha256,
-      publishedByUserId: Number(req.user?.sub || req.user?.id || 0) || null,
-      publishedByName: req.user?.name || req.user?.username || req.user?.email || '',
-    });
-
-    res.status(201).json({
-      success: true,
-      message: `${platform === 'darwin' ? 'macOS' : 'Windows'} 客户端 v${version} 已发布`,
-      data: {
-        ...release,
-        downloadUrl: `/api/desktop-client/releases/${release.id}/download`,
-      },
-    });
-  } catch (error) {
-    console.error('发布桌面客户端失败:', error);
-    const status = /版本号格式/.test(error.message) ? 400 : 500;
-    res.status(status).json({ success: false, error: error.message || '发布桌面客户端失败' });
-  } finally {
-    if (tempFilePath) {
-      await fs.promises.unlink(tempFilePath).catch(() => {});
-    }
-  }
-});
-
 router.get('/cache-performance', async (_req, res) => {
   const dataPayloadStats = getStatsSnapshot();
   res.json({
@@ -1350,40 +1211,6 @@ router.post('/selection-fission-ai-settings/image-generation/test', async (_req,
 
 
 
-// ==================== 商品标签配置（规模标签 / 利润标签 / SABC 映射） ====================
-
-router.get('/product-tag-config', async (_req, res) => {
-  try {
-    res.json({ success: true, data: await getProductTagConfig() });
-  } catch (error) {
-    console.error('获取商品标签配置失败:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || '获取商品标签配置失败',
-    });
-  }
-});
-
-router.put('/product-tag-config', async (req, res) => {
-  try {
-    const result = await saveProductTagConfig(req.body || {});
-    const config = await getProductTagConfig();
-    res.json({
-      success: true,
-      message: '商品标签配置已保存到系统数据库',
-      data: { ...config, saved: result },
-    });
-  } catch (error) {
-    console.error('保存商品标签配置失败:', error);
-    // 校验类错误回 400，方便前端直接展示原因
-    const status = /行|重复|不能为空|取值非法|必须小于/.test(error.message || '') ? 400 : (error.statusCode || error.status || 500);
-    res.status(status).json({
-      success: false,
-      error: error.message || '保存商品标签配置失败',
-    });
-  }
-});
-
 // ==================== 1688 专用以图搜图 ====================
 
 
@@ -1622,12 +1449,10 @@ router.post('/work-order-config/test', async (req, res) => {
 const DEFAULT_DATABASE_CONFIG_NAME = 'cloud_database';
 const CLOUD_DATABASE_PUBLIC_CONFIG_NAME = 'cloud_database_public';
 const PLANNING_DATABASE_CONFIG_NAME = 'planning_database';
-const AI_BUYER_SHOW_DATABASE_CONFIG_NAME = 'ai_buyer_show_database';
 const PROTECTED_DATABASE_CONFIG_NAMES = new Set([
   DEFAULT_DATABASE_CONFIG_NAME,
   CLOUD_DATABASE_PUBLIC_CONFIG_NAME,
   PLANNING_DATABASE_CONFIG_NAME,
-  AI_BUYER_SHOW_DATABASE_CONFIG_NAME,
 ]);
 
 function normalizeDatabaseConfigName(rawName) {
@@ -1640,6 +1465,11 @@ function normalizeDatabaseConfigName(rawName) {
     error.statusCode = 400;
     throw error;
   }
+  if (isRetiredDatabaseConfigName(configName)) {
+    const error = new Error('该功能已下线，不能创建对应数据库配置');
+    error.statusCode = 410;
+    throw error;
+  }
   return configName;
 }
 
@@ -1649,6 +1479,13 @@ function getDefaultPortByDriver(driver) {
   return 3306;
 }
 
+function normalizeDatabaseDriver(driver) {
+  const normalized = String(driver || '').trim().toLowerCase();
+  if (normalized === 'postgresql' || normalized === 'postgres') return 'postgres';
+  if (normalized === 'mssql') return 'mssql';
+  return 'mysql';
+}
+
 async function getStoredDatabaseConfig(configName) {
   const normalizedName = normalizeDatabaseConfigName(configName);
   let configs = await database.local.query(
@@ -1787,7 +1624,9 @@ router.put('/database', async (req, res) => {
     }
 
     // 根据数据库类型设置默认端口
-    const resolvedDriver = driver || existingConfig?.driver || (useEnvConfig ? envSummary.driver : 'mysql');
+    const resolvedDriver = normalizeDatabaseDriver(
+      driver || existingConfig?.driver || (useEnvConfig ? envSummary.driver : 'mysql')
+    );
     const defaultPort = getDefaultPortByDriver(resolvedDriver);
     
     const configData = {
@@ -1881,6 +1720,8 @@ router.post('/database/test', async (req, res) => {
       return res.status(400).json({ success: false, error: '请完整填写数据库连接信息' });
     }
     
+    driver = normalizeDatabaseDriver(driver);
+
     if (driver === 'mssql') {
       // SQL Server 连接测试
       const sql = require('mssql');
@@ -1900,6 +1741,26 @@ router.post('/database/test', async (req, res) => {
       const pool = await sql.connect(config);
       await pool.request().query('SELECT 1 as test');
       await pool.close();
+    } else if (driver === 'postgres') {
+      const { Client } = require('pg');
+      const client = new Client({
+        host,
+        port: port || 5432,
+        database: dbName,
+        user: username,
+        password,
+        ssl: ssl ? { rejectUnauthorized: false } : false,
+        connectionTimeoutMillis: 10000,
+        query_timeout: 10000,
+        statement_timeout: 10000,
+      });
+
+      try {
+        await client.connect();
+        await client.query('SELECT 1 AS test');
+      } finally {
+        await client.end().catch(() => {});
+      }
     } else {
       // MySQL 连接测试
       const mysql = require('mysql2/promise');

backend/src/api/aiBuyerShow.js

@@ -1,397 +0,0 @@
-const express = require('express');
-const multer = require('multer');
-const axios = require('axios');
-const {
-  buildDefaultPrompt,
-  createAiBuyerShowJob,
-  generateAiBuyerShowReviews,
-  getAiBuyerShowHistoryDetail,
-  getAiBuyerShowJob,
-  getQueueStats,
-  getWorkerRuntimeStatus,
-  listAiBuyerShowHistory,
-  listAiBuyerShowJobs,
-  testAiBuyerShowDatabase,
-} = require('../services/aiBuyerShowService');
-const { buildBuyerShowPrompt } = require('../services/aiBuyerShowReviewService');
-const {
-  createSeedPack,
-  deleteSeedPack,
-  getSeedPackDownload,
-  listSeedPacks,
-  MAX_SEED_PACK_FILE_BYTES,
-} = require('../services/aiBuyerShowSeedPackService');
-
-const router = express.Router();
-
-const upload = multer({
-  storage: multer.memoryStorage(),
-  limits: {
-    fileSize: 20 * 1024 * 1024,
-    files: 10,
-  },
-  fileFilter: (_req, file, callback) => {
-    if (String(file.mimetype || '').startsWith('image/')) {
-      callback(null, true);
-      return;
-    }
-    callback(new Error('仅支持上传图片文件'));
-  },
-});
-
-const uploadFields = upload.fields([
-  { name: 'productImages', maxCount: 5 },
-  { name: 'sceneReferenceImages', maxCount: 4 },
-]);
-
-function runUpload(req, res, next) {
-  uploadFields(req, res, (error) => {
-    if (!error) {
-      next();
-      return;
-    }
-    if (error instanceof multer.MulterError && error.code === 'LIMIT_FILE_SIZE') {
-      res.status(413).json({ success: false, error: '图片不能超过 20MB' });
-      return;
-    }
-    res.status(400).json({ success: false, error: error.message || '图片上传失败' });
-  });
-}
-
-const seedPackUpload = multer({
-  storage: multer.memoryStorage(),
-  limits: {
-    fileSize: MAX_SEED_PACK_FILE_BYTES,
-    files: 1,
-  },
-  fileFilter: (_req, file, callback) => {
-    const isZip = String(file.mimetype || '') === 'application/zip'
-      || String(file.mimetype || '') === 'application/x-zip-compressed'
-      || /\.zip$/i.test(String(file.originalname || ''));
-    if (isZip) {
-      callback(null, true);
-      return;
-    }
-    callback(new Error('种菜资源包仅支持上传 ZIP 文件'));
-  },
-}).single('file');
-
-function runSeedPackUpload(req, res, next) {
-  seedPackUpload(req, res, (error) => {
-    if (!error) {
-      next();
-      return;
-    }
-    if (error instanceof multer.MulterError && error.code === 'LIMIT_FILE_SIZE') {
-      res.status(413).json({ success: false, error: '种菜资源包 ZIP 不能超过 200MB' });
-      return;
-    }
-    res.status(400).json({ success: false, error: error.message || '种菜资源包上传失败' });
-  });
-}
-
-function normalizeList(value) {
-  const raw = Array.isArray(value) ? value : String(value || '').split(/[\n,，]+/);
-  return Array.from(new Set(raw.map((item) => String(item || '').trim()).filter(Boolean)));
-}
-
-function isAllowedImageUrl(value) {
-  try {
-    const parsed = new URL(String(value || ''));
-    return ['http:', 'https:'].includes(parsed.protocol) && (
-      parsed.hostname.endsWith('aliyuncs.com')
-      || parsed.hostname.endsWith('volces.com')
-      || parsed.hostname.endsWith('jiansuntuzhi.cn')
-      || parsed.hostname.endsWith('yydd.ai')
-      || parsed.hostname.endsWith('jiansun.vip')
-    );
-  } catch (_) {
-    return false;
-  }
-}
-
-router.get('/runtime', async (_req, res) => {
-  try {
-    const databaseStatus = await testAiBuyerShowDatabase();
-    const queue = databaseStatus.ok ? await getQueueStats() : null;
-    const worker = databaseStatus.ok ? await getWorkerRuntimeStatus(queue || {}) : {
-      enabled: false,
-      hasApiKey: false,
-      status: 'database_unavailable',
-      source: 'job-table-observation',
-      lastActivityAt: null,
-      lastError: '',
-    };
-    res.json({
-      success: true,
-      data: {
-        database: databaseStatus,
-        queue,
-        worker,
-      },
-    });
-  } catch (error) {
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || 'AI买家秀运行状态查询失败',
-      data: {
-        database: {
-          ok: false,
-          missingTables: [],
-        },
-      },
-    });
-  }
-});
-
-router.post('/prompt-preview', express.json({ limit: '1mb' }), async (req, res) => {
-  try {
-    const body = req.body || {};
-    res.json({
-      success: true,
-      data: {
-        prompt: body.review
-          ? buildBuyerShowPrompt({
-            review: body.review,
-            analysis: body.analysis || {},
-            style: body.buyerShowStyle,
-          })
-          : buildDefaultPrompt(body),
-      },
-    });
-  } catch (error) {
-    res.status(500).json({ success: false, error: error.message || '提示词预览失败' });
-  }
-});
-
-router.post('/reviews', runUpload, async (req, res) => {
-  try {
-    const body = req.body || {};
-    const result = await generateAiBuyerShowReviews({
-      productName: body.productName || body.spu,
-      spu: body.spu || body.productName,
-      scene: body.scene,
-      userType: body.userType,
-      sellingPoints: body.sellingPoints,
-      useEmoji: body.useEmoji,
-      reviewTotal: body.reviewTotal,
-      productImageFiles: req.files?.productImages || [],
-    }, req.user || {});
-    res.json({ success: true, data: result });
-  } catch (error) {
-    console.error('[ai-buyer-show] generate reviews failed:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || '攻心评价生成失败',
-    });
-  }
-});
-
-router.post('/jobs', runUpload, async (req, res) => {
-  try {
-    const body = req.body || {};
-    const result = await createAiBuyerShowJob({
-      productName: body.productName || body.spu,
-      spu: body.spu || body.productName,
-      scene: body.scene,
-      userType: body.userType,
-      sellingPoints: body.sellingPoints,
-      reviewText: body.reviewText,
-      generationId: body.generationId,
-      reviewRecordId: body.reviewRecordId,
-      prompt: body.prompt,
-      negativePrompt: body.negativePrompt,
-      buyerShowStyle: body.buyerShowStyle,
-      imageCount: 5,
-      aspectRatio: body.aspectRatio,
-      imageSize: body.imageSize,
-      productImageUrls: normalizeList(body.productImageUrls),
-      sceneReferenceImageUrls: normalizeList(body.sceneReferenceImageUrls),
-      productImageFiles: req.files?.productImages || [],
-      sceneReferenceImageFiles: req.files?.sceneReferenceImages || [],
-    }, req.user || {});
-
-    res.json({ success: true, data: result });
-  } catch (error) {
-    console.error('[ai-buyer-show] create job failed:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || 'AI买家秀任务创建失败',
-    });
-  }
-});
-
-router.get('/jobs', async (req, res) => {
-  try {
-    const result = await listAiBuyerShowJobs({
-      page: req.query.page,
-      pageSize: req.query.pageSize,
-      spu: req.query.spu,
-      includeTotal: req.query.includeTotal !== '0',
-    });
-    res.json({ success: true, data: result });
-  } catch (error) {
-    console.error('[ai-buyer-show] list jobs failed:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || 'AI买家秀任务列表查询失败',
-    });
-  }
-});
-
-router.get('/history', async (req, res) => {
-  try {
-    const data = await listAiBuyerShowHistory({
-      page: req.query.page,
-      pageSize: req.query.pageSize,
-      keyword: req.query.keyword,
-    });
-    res.set('Cache-Control', 'private, no-store');
-    res.json({ success: true, data });
-  } catch (error) {
-    console.error('[ai-buyer-show] list history failed:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || '历史生成记录加载失败',
-    });
-  }
-});
-
-router.get('/history/:id', async (req, res) => {
-  try {
-    const data = await getAiBuyerShowHistoryDetail(req.params.id);
-    if (!data) {
-      res.status(404).json({ success: false, error: '历史生成记录不存在' });
-      return;
-    }
-    res.set('Cache-Control', 'private, no-store');
-    res.json({ success: true, data });
-  } catch (error) {
-    console.error('[ai-buyer-show] get history failed:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || '历史生成详情加载失败',
-    });
-  }
-});
-
-router.get('/image-proxy', async (req, res) => {
-  const imageUrl = String(req.query.url || '').trim();
-  if (!isAllowedImageUrl(imageUrl)) {
-    res.status(400).json({ success: false, error: '不支持的图片地址' });
-    return;
-  }
-
-  try {
-    const response = await axios.get(imageUrl, {
-      responseType: 'stream',
-      timeout: 120000,
-      maxContentLength: 30 * 1024 * 1024,
-      headers: { 'User-Agent': 'Mozilla/5.0' },
-    });
-    res.set('Content-Type', response.headers['content-type'] || 'application/octet-stream');
-    res.set('Cache-Control', 'private, max-age=300');
-    response.data.pipe(res);
-  } catch (error) {
-    res.status(error.response?.status || 502).json({
-      success: false,
-      error: error.message || '图片下载失败',
-    });
-  }
-});
-
-router.get('/jobs/:jobId', async (req, res) => {
-  try {
-    const job = await getAiBuyerShowJob(req.params.jobId);
-    if (!job) {
-      res.status(404).json({ success: false, error: '任务不存在' });
-      return;
-    }
-    res.json({ success: true, data: job });
-  } catch (error) {
-    console.error('[ai-buyer-show] get job failed:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || 'AI买家秀任务查询失败',
-    });
-  }
-});
-
-router.get('/queue-stats', async (req, res) => {
-  try {
-    const data = await getQueueStats(req.query.jobId || '');
-    res.json({ success: true, data });
-  } catch (error) {
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || 'AI买家秀队列统计查询失败',
-    });
-  }
-});
-
-router.post('/seed-packs', runSeedPackUpload, async (req, res) => {
-  try {
-    const body = req.body || {};
-    const data = await createSeedPack({
-      shopName: body.shopName,
-      productId: body.productId,
-      skuName: body.skuName,
-      fileName: body.fileName || req.file?.originalname,
-      reviewCount: body.reviewCount,
-      file: req.file,
-    }, req.user || {});
-    res.json({ success: true, data });
-  } catch (error) {
-    console.error('[ai-buyer-show] create seed pack failed:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || '种菜资源包上传失败',
-    });
-  }
-});
-
-router.get('/seed-packs', async (req, res) => {
-  try {
-    const data = await listSeedPacks({
-      page: req.query.page,
-      pageSize: req.query.pageSize,
-      keyword: req.query.keyword,
-    });
-    res.set('Cache-Control', 'private, no-store');
-    res.json({ success: true, data });
-  } catch (error) {
-    console.error('[ai-buyer-show] list seed packs failed:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || '种菜资源包列表查询失败',
-    });
-  }
-});
-
-router.get('/seed-packs/:id/download', async (req, res) => {
-  try {
-    const data = await getSeedPackDownload(req.params.id);
-    res.json({ success: true, data });
-  } catch (error) {
-    console.error('[ai-buyer-show] get seed pack download failed:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || '种菜资源包下载信息获取失败',
-    });
-  }
-});
-
-router.delete('/seed-packs/:id', async (req, res) => {
-  try {
-    const data = await deleteSeedPack(req.params.id);
-    res.json({ success: true, data });
-  } catch (error) {
-    console.error('[ai-buyer-show] delete seed pack failed:', error);
-    res.status(error.statusCode || error.status || 500).json({
-      success: false,
-      error: error.message || '种菜资源包删除失败',
-    });
-  }
-});
-
-module.exports = router;

backend/src/api/csQuality.js

@@ -1,93 +0,0 @@
-'use strict';
-
-const express = require('express');
-const {
-  getGoods,
-  getChatDataMeta,
-  getCustomers,
-  getMessages,
-  getProductProfile,
-  startAnalysisJob,
-  getAnalysisJob,
-  runAnalysis,
-  listHistory,
-  getHistoryDetail,
-} = require('../services/csQualityService');
-
-const router = express.Router();
-
-function sendError(res, error, fallback = '客服质检请求失败') {
-  const status = Number(error?.statusCode) || (error?.message?.includes('不能超过30天') ? 400 : 500);
-  console.error('[CsQuality]', {
-    message: error?.message || fallback,
-    code: error?.code || null,
-    status,
-    stack: error?.stack || null,
-  });
-  res.status(status).json({ success: false, error: error.message || fallback });
-}
-
-router.get('/goods', async (req, res) => {
-  try {
-    res.json({ success: true, data: await getGoods(req.query) });
-  } catch (error) { sendError(res, error, '加载商品聊天列表失败'); }
-});
-
-router.get('/data-meta', async (_req, res) => {
-  try {
-    res.json({ success: true, data: await getChatDataMeta() });
-  } catch (error) { sendError(res, error, '加载聊天数据日期范围失败'); }
-});
-
-router.get('/goods/:goodsId/profile', async (req, res) => {
-  try {
-    res.json({ success: true, data: await getProductProfile({ ...req.query, goodsId: req.params.goodsId }) });
-  } catch (error) { sendError(res, error, '加载商品表现失败'); }
-});
-
-router.get('/customers', async (req, res) => {
-  try {
-    res.json({ success: true, data: await getCustomers(req.query) });
-  } catch (error) { sendError(res, error, '加载客户列表失败'); }
-});
-
-router.get('/messages', async (req, res) => {
-  try {
-    res.json({ success: true, data: await getMessages(req.query) });
-  } catch (error) { sendError(res, error, '加载聊天内容失败'); }
-});
-
-router.post('/analysis', async (req, res) => {
-  try {
-    res.json({ success: true, data: await runAnalysis(req.body || {}, req.user || {}) });
-  } catch (error) { sendError(res, error, 'AI质检失败'); }
-});
-
-router.post('/analysis-jobs', async (req, res) => {
-  try {
-    const data = await startAnalysisJob(req.body || {}, req.user || {});
-    res.status(202).json({ success: true, data });
-  } catch (error) { sendError(res, error, '创建AI质检任务失败'); }
-});
-
-router.get('/analysis-jobs/:analysisId', async (req, res) => {
-  try {
-    res.json({ success: true, data: await getAnalysisJob(req.params.analysisId) });
-  } catch (error) { sendError(res, error, '查询AI质检进度失败'); }
-});
-
-router.get('/analysis-history', async (req, res) => {
-  try {
-    res.json({ success: true, data: await listHistory(req.query) });
-  } catch (error) { sendError(res, error, '加载AI质检历史失败'); }
-});
-
-router.get('/analysis-history/:id', async (req, res) => {
-  try {
-    const data = await getHistoryDetail(req.params.id);
-    if (!data) return res.status(404).json({ success: false, error: '历史质检记录不存在' });
-    return res.json({ success: true, data });
-  } catch (error) { return sendError(res, error, '加载AI质检历史详情失败'); }
-});
-
-module.exports = router;

backend/src/api/dailyInventory.js

@@ -0,0 +1,563 @@
+const express = require('express');
+const multer = require('multer');
+const cloudDb = require('../config/cloudDatabase');
+const snapshotDb = require('../config/dailyInventorySnapshotDb');
+const officialDb = require('../config/dailyInventoryOfficialDb');
+const {
+  DAILY_INVENTORY_BASELINE,
+  FLOW_COLUMNS,
+} = require('../config/dailyInventoryBaseline');
+const { fetchFlows, AVAILABLE_FLOW_FIELDS } = require('../services/dailyInventoryFlows');
+const { deriveAndStoreOpeningSnapshot } = require('../services/dailyInventoryOpening');
+const {
+  parseWorkbook,
+  normalizeRecords,
+  checkBalance,
+  importOfficial,
+} = require('../services/dailyInventoryOfficial');
+
+const router = express.Router();
+const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: 20 * 1024 * 1024 } });
+
+/** 库存衡量基准时刻：快照日次日 01:00（报表库每日凌晨 1 点跑批，标注 T-1） */
+const AS_OF_TIME = '01:00';
+
+/**
+ * 「月度」发货窗口天数：滚动 30 天。
+ * 库龄阈值：3 个月 = 90 天、12 个月 = 365 天（按日历天折算）。
+ */
+const SHIP_WINDOW_DAYS = 30;
+const AGE_3M_DAYS = 90;
+const AGE_12M_DAYS = 365;
+
+/** 结果缓存：单次查询要扫订单明细 + 库存明细两张大表，避免连续刷新重复打库 */
+const RESULT_CACHE_TTL_MS = 5 * 60 * 1000;
+let cachedResult = null;
+let cachedResultAt = 0;
+
+const toNumber = (v) => {
+  if (v == null) return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+/** 快照日 + 次日 01:00 作为统一的库龄/分级基准 */
+function nextDayAsOf(bizDate) {
+  if (!bizDate || !/^\d{4}-\d{2}-\d{2}$/.test(bizDate)) return null;
+  const d = new Date(`${bizDate}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + 1);
+  return `${d.toISOString().slice(0, 10)} ${AS_OF_TIME}`;
+}
+
+/** 发货窗口：[asOf - 30 天, asOf)，滚动一个月 */
+function shipWindow(asOf) {
+  const to = new Date(`${asOf.slice(0, 10)}T${AS_OF_TIME}:00Z`);
+  const from = new Date(to.getTime() - SHIP_WINDOW_DAYS * 86400000);
+  const fmt = (dt) => dt.toISOString().slice(0, 19).replace('T', ' ');
+  return { shipFrom: fmt(from), shipTo: fmt(to) };
+}
+
+async function fetchLatestBizDate() {
+  const rows = await cloudDb.query(
+    `SELECT MAX(CONVERT(VARCHAR(10), date, 23)) AS d FROM rpt.pm_stockMonitor`
+  );
+  return rows[0]?.d || null;
+}
+
+/** 上一自然日（日历天，用于取「期初 = 昨日结存」） */
+function prevDay(bizDate) {
+  if (!bizDate || !/^\d{4}-\d{2}-\d{2}$/.test(bizDate)) return null;
+  const d = new Date(`${bizDate}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() - 1);
+  return d.toISOString().slice(0, 10);
+}
+
+/** mssql 不支持数组参数，按位展开成 @p0,@p1... */
+function buildInClause(values, prefix) {
+  const params = {};
+  const clause = values
+    .map((v, i) => {
+      const key = `${prefix}${i}`;
+      params[key] = v;
+      return `@${key}`;
+    })
+    .join(',');
+  return { clause, params };
+}
+
+/**
+ * 分级规则（库龄 + 周转率双维度），口径与业务给定一致：
+ *   库龄 < 3 个月 且 周转率 30%~199%      → 滞销预警
+ *   库龄 < 3 个月 且 周转率 ≥ 200%        → 商品慢流
+ *   库龄 > 3 个月 且 周转率 30%~99%       → 商品慢流
+ *   库龄 3~12 个月 且 周转率 ≥ 100%       → 商品呆滞
+ *   库龄 > 12 个月 且 周转率 100%~199%    → 商品呆滞
+ *   库龄 > 12 个月 且 周转率 ≥ 200%       → 商品僵尸
+ * 边界：库龄正好 90 天不计入「慢流」（业务描述为 > 3 个月），正好 365 天仍属「3~12 个月」。
+ */
+function buildLevelExpr() {
+  const t = 'b.turnoverPct';
+  return `
+      CASE
+        WHEN b.stockQty <= 0 OR ${t} IS NULL OR b.ageDays IS NULL THEN NULL
+        WHEN b.ageDays < ${AGE_3M_DAYS} AND ${t} >= 30 AND ${t} < 200 THEN 'warn'
+        WHEN b.ageDays < ${AGE_3M_DAYS} AND ${t} >= 200 THEN 'slow'
+        WHEN b.ageDays > ${AGE_3M_DAYS} AND ${t} >= 30 AND ${t} < 100 THEN 'slow'
+        WHEN b.ageDays >= ${AGE_3M_DAYS} AND b.ageDays <= ${AGE_12M_DAYS} AND ${t} >= 100 THEN 'stale'
+        WHEN b.ageDays > ${AGE_12M_DAYS} AND ${t} >= 100 AND ${t} < 200 THEN 'stale'
+        WHEN b.ageDays > ${AGE_12M_DAYS} AND ${t} >= 200 THEN 'zombie'
+        ELSE NULL
+      END`;
+}
+
+/**
+ * 每个仓库的周转率与四级库存量（一次查询覆盖全部仓库）。
+ *
+ * 口径：
+ *   库存周转天数（周转率）= 月度发货总件数 / 月度日均库存件数 × 100%
+ *     · 月度发货总件数 = 该仓近 30 天已发货订单件数（jst_OrderItem × jst_Orders，按 send_date，排除 Delete/Cancelled）
+ *     · 月度日均库存件数 = 该仓聚水潭库存 jst_inventoryInfo（无历史结存表，以当日库存近似月度日均）
+ *   库龄(天) = DATEDIFF(基准时刻, SKU 建档时间 created)
+ *
+ * SKU 关联链路：jst_inventoryInfo.sku_id = jst_OrderItem.sku_id = pm_stockMonitor.sku_id（实测崔桥 1852/1852 命中）
+ */
+async function fetchGradeMetrics(wmsCoIds, bizDate, asOf) {
+  if (!wmsCoIds.length || !bizDate || !asOf) return new Map();
+  const invIn = buildInClause(wmsCoIds, 'w');
+  const shipIn = buildInClause(wmsCoIds, 'v');
+  const { shipFrom, shipTo } = shipWindow(asOf);
+  const level = buildLevelExpr();
+
+  const sqlText = `
+    WITH inv AS (
+      SELECT i.wms_co_id AS wmsCoId,
+             i.sku_id    AS skuId,
+             SUM(CAST(ISNULL(i.qty, 0) AS DECIMAL(18, 2))) AS stockQty
+        FROM rpt.jst_inventoryInfo i
+       WHERE i.wms_co_id IN (${invIn.clause})
+       GROUP BY i.wms_co_id, i.sku_id
+    ),
+    created AS (
+      SELECT m.sku_id AS skuId, MIN(m.created) AS created
+        FROM rpt.pm_stockMonitor m
+       WHERE CONVERT(VARCHAR(10), m.date, 23) = @bizDate
+       GROUP BY m.sku_id
+    ),
+    ship AS (
+      SELECT o.wms_co_id AS wmsCoId,
+             oi.sku_id   AS skuId,
+             SUM(CAST(ISNULL(oi.qty, 0) AS DECIMAL(18, 2))) AS shipQty
+        FROM rpt.jst_OrderItem oi
+        JOIN rpt.jst_Orders o ON o.o_id = oi.o_id
+       WHERE o.wms_co_id IN (${shipIn.clause})
+         AND o.send_date >= @shipFrom
+         AND o.send_date < @shipTo
+         AND ISNULL(o.status, '') NOT IN ('Delete', 'Cancelled')
+       GROUP BY o.wms_co_id, oi.sku_id
+    ),
+    base AS (
+      SELECT v.wmsCoId,
+             v.skuId,
+             v.stockQty,
+             ISNULL(s.shipQty, 0) AS shipQty,
+             DATEDIFF(DAY, c.created, @asOf) AS ageDays,
+             CASE WHEN v.stockQty <= 0 THEN NULL
+                  ELSE ISNULL(s.shipQty, 0) * 100.0 / v.stockQty END AS turnoverPct
+        FROM inv v
+        LEFT JOIN ship s ON s.wmsCoId = v.wmsCoId AND s.skuId = v.skuId
+        LEFT JOIN created c ON c.skuId = v.skuId
+    )
+    SELECT b.wmsCoId,
+           SUM(CASE WHEN ABS(b.stockQty) > 0.0001 THEN 1 ELSE 0 END) AS skuCount,
+           SUM(b.stockQty) AS totalStock,
+           SUM(b.shipQty) AS totalShip,
+           SUM(CASE WHEN b.ageDays IS NULL OR b.turnoverPct IS NULL OR b.stockQty <= 0 THEN 1 ELSE 0 END) AS ungradedSku,
+           CASE WHEN SUM(b.stockQty) > 0
+                THEN CAST(SUM(b.shipQty) * 100.0 / SUM(b.stockQty) AS DECIMAL(18, 2))
+                ELSE NULL END AS turnoverPct,
+           SUM(CASE WHEN ${level} = 'warn' THEN b.stockQty ELSE 0 END) AS warnLevel,
+           SUM(CASE WHEN ${level} = 'slow' THEN b.stockQty ELSE 0 END) AS slowLevel,
+           SUM(CASE WHEN ${level} = 'stale' THEN b.stockQty ELSE 0 END) AS staleLevel,
+           SUM(CASE WHEN ${level} = 'zombie' THEN b.stockQty ELSE 0 END) AS zombieLevel
+      FROM base b
+     GROUP BY b.wmsCoId`;
+
+  const rows = await cloudDb.query(sqlText, {
+    ...invIn.params,
+    ...shipIn.params,
+    bizDate,
+    asOf,
+    shipFrom,
+    shipTo,
+  }, { requestTimeout: 120000 });
+
+  const map = new Map();
+  rows.forEach((r) => {
+    map.set(String(r.wmsCoId), {
+      skuCount: toNumber(r.skuCount) || 0,
+      gradeStock: toNumber(r.totalStock) || 0,
+      shipQty: toNumber(r.totalShip) || 0,
+      turnoverDays: toNumber(r.turnoverPct),
+      warnLevel: toNumber(r.warnLevel) || 0,
+      slowLevel: toNumber(r.slowLevel) || 0,
+      staleLevel: toNumber(r.staleLevel) || 0,
+      zombieLevel: toNumber(r.zombieLevel) || 0,
+      ungradedSku: toNumber(r.ungradedSku) || 0,
+    });
+  });
+  return map;
+}
+
+/** 实时库存表的数据时效（一次取全局即可） */
+async function fetchInventoryTakenAt() {
+  const rows = await cloudDb.query(
+    `SELECT MAX(modified) AS takenAt FROM rpt.jst_inventoryInfo`
+  );
+  return rows[0]?.takenAt || null;
+}
+
+/**
+ * GET /api/daily-inventory
+ * 每日进销存：26 个仓库 ×（期初 / 期末 / 周转率 / 四级库存量）
+ *
+ * 数据源分工（全部来自数据库，无硬编码业务数值）：
+ *   - 期初数量：本地快照表 daily_inventory_snapshot 中「上一业务日」的期末结存；
+ *     快照缺失时按 pm_stockMonitor（精确）/ 实时库存扣流水（近似）推导并补写
+ *   - 期末数量：jst_inventoryInfo 实时库存（按 wms_co_id 单仓）
+ *   - 库存周转天数 / 四级库存量：近 30 天发货 × 实时库存 × SKU 建档日期
+ *   - 12 个流水列：4 列可从业务库单据表还原（采购进仓/采购退货/销售出仓/销售退货，
+ *     见 services/dailyInventoryFlows.js），其余 8 列业务库无单据表，返回 null（前端显示「—」）
+ */
+router.get('/', async (req, res) => {
+  try {
+    const force = String(req.query?.refresh || '') === '1';
+    const requestedDate = typeof req.query?.date === 'string'
+      && /^\d{4}-\d{2}-\d{2}$/.test(req.query.date) ? req.query.date : null;
+    const systemBizDate = await fetchLatestBizDate().catch(() => null);
+    const latestBizDate = requestedDate || systemBizDate;
+    // 查看历史业务日时，业务库只有「当前」的实时库存与流水，不能当成该日的期末/发生额
+    const staleMetrics = Boolean(requestedDate && systemBizDate && requestedDate !== systemBizDate);
+    const cacheKey = `${latestBizDate}|${staleMetrics ? 'hist' : 'live'}`;
+    if (!force && cachedResult && cachedResult.latestBizDate === cacheKey
+      && Date.now() - cachedResultAt < RESULT_CACHE_TTL_MS) {
+      return res.json({ success: true, data: cachedResult, cached: true });
+    }
+
+    const asOf = nextDayAsOf(latestBizDate);
+    const openingDate = prevDay(latestBizDate);
+    const wmsCoIds = DAILY_INVENTORY_BASELINE
+      .map((b) => b.wmsCoId)
+      .filter((v) => v != null);
+
+    const [gradeMap, takenAt, officialMap, officialDates] = await Promise.all([
+      fetchGradeMetrics(wmsCoIds, latestBizDate, asOf).catch((e) => {
+        console.error('[daily-inventory] 分级计算失败:', e.message);
+        return new Map();
+      }),
+      fetchInventoryTakenAt().catch(() => null),
+      officialDb.fetchOfficial(latestBizDate).catch(() => new Map()),
+      officialDb.listOfficialDates(30).catch(() => []),
+    ]);
+
+    // 期初 = 上一业务日的期末快照；若定时任务漏跑，顺手把当前业务日的快照补齐
+    let openingMap = await snapshotDb.fetchSnapshot(openingDate).catch(() => new Map());
+    const todayMap = await snapshotDb.fetchSnapshot(latestBizDate).catch(() => new Map());
+    const missing = DAILY_INVENTORY_BASELINE
+      .filter((b) => b.wmsCoId != null && !todayMap.has(String(b.wmsCoId)))
+      .map((b) => {
+        const g = gradeMap.get(String(b.wmsCoId));
+        return {
+          wmsCoId: b.wmsCoId,
+          warehouse: b.warehouse,
+          dbWarehouse: b.dbWarehouse,
+          closingQty: Number(g?.gradeStock ?? 0),
+          skuCount: Number(g?.skuCount ?? 0),
+          takenAt: takenAt ? new Date(takenAt) : null,
+        };
+      });
+    if (missing.length) {
+      await snapshotDb.upsertSnapshot(latestBizDate, missing).catch((e) => {
+        console.error('[daily-inventory] 快照补写失败:', e.message);
+      });
+    }
+
+    // 期初快照也缺失时，用 pm_stockMonitor（精确）/ 实时库存扣流水（近似）推导并补写
+    if (openingDate && !openingMap.size) {
+      await deriveAndStoreOpeningSnapshot({
+        cloudDb,
+        snapshotDb,
+        baseline: DAILY_INVENTORY_BASELINE,
+        openingDate,
+        latestBizDate,
+        takenAt,
+      }).catch((e) => {
+        console.error('[daily-inventory] 期初快照推导失败:', e.message);
+      });
+      openingMap = await snapshotDb.fetchSnapshot(openingDate).catch(() => new Map());
+    }
+
+    // 流水列：自期初时刻（最新业务日 01:00）以来的单据合计（带符号，流出为负）
+    let flowMap = new Map();
+    if (openingDate) {
+      flowMap = await fetchFlows(cloudDb, wmsCoIds, `${latestBizDate} 01:00:00`).catch((e) => {
+        console.error('[daily-inventory] 流水取数失败:', e.message);
+        return new Map();
+      });
+    }
+
+    const items = DAILY_INVENTORY_BASELINE.map((base) => {
+      const official = officialMap.get(base.warehouse) || null;
+      const grade = base.wmsCoId != null ? gradeMap.get(String(base.wmsCoId)) : null;
+      const opening = base.wmsCoId != null ? openingMap.get(String(base.wmsCoId)) : null;
+      const itemFlows = base.wmsCoId != null ? flowMap.get(String(base.wmsCoId)) : null;
+
+      // 12 个流水列：聚水潭官方导出优先，缺失时回退业务库推算（历史业务日不做回退）
+      const flows = {};
+      const flowSources = {};
+      for (const col of FLOW_COLUMNS) {
+        const fromOfficial = official?.flows?.[col.field];
+        if (fromOfficial != null) {
+          flows[col.field] = Number(fromOfficial);
+          flowSources[col.field] = 'official';
+          continue;
+        }
+        const derived = itemFlows ? itemFlows[col.field] : null;
+        if (derived != null && !staleMetrics) {
+          flows[col.field] = Number(derived.toFixed(2));
+          flowSources[col.field] = 'derived';
+          continue;
+        }
+        flows[col.field] = null;
+        flowSources[col.field] = 'none';
+      }
+
+      // 期末：官方期末优先；无官方时，历史业务日不给实时库存（口径不对）
+      const gradeStock = grade?.gradeStock ?? null;
+      let closingQty = gradeStock;
+      let closingSource = 'derived';
+      if (official?.closingQty != null) {
+        closingQty = Number(official.closingQty);
+        closingSource = 'official';
+      } else if (staleMetrics) {
+        closingQty = null;
+        closingSource = 'none';
+      }
+
+      // 期初：官方期初优先，其次本地快照
+      let openingQty = opening ? opening.closingQty : null;
+      let openingSource = opening ? 'snapshot' : 'none';
+      if (official?.openingQty != null) {
+        openingQty = Number(official.openingQty);
+        openingSource = 'official';
+      } else if (staleMetrics) {
+        openingQty = null;
+        openingSource = 'none';
+      }
+
+      return {
+        warehouse: base.warehouse,
+        dbWarehouse: base.dbWarehouse,
+        openingQty,
+        openingQtyExtra: null,
+        ...flows,
+        closingQty,
+        closingSkuCount: grade?.skuCount ?? null,
+        closingTakenAt: takenAt,
+        shipQty30d: grade?.shipQty ?? null,
+        turnoverDays: grade?.turnoverDays ?? null,
+        gradeStock,
+        warnLevel: grade?.warnLevel ?? null,
+        slowLevel: grade?.slowLevel ?? null,
+        staleLevel: grade?.staleLevel ?? null,
+        zombieLevel: grade?.zombieLevel ?? null,
+        ungradedSku: grade?.ungradedSku ?? null,
+        hasGrade: Boolean(grade),
+        source: {
+          opening: openingSource,
+          closing: closingSource,
+          flows: flowSources,
+          hasOfficial: Boolean(official),
+        },
+      };
+    });
+
+    // 合计行：便于与表格总额核对
+    const sum = (k) => items.reduce((acc, it) => acc + (Number(it[k]) || 0), 0);
+    const totals = { warehouse: '合计', dbWarehouse: '', isTotal: true };
+    for (const k of ['openingQty', 'openingQtyExtra', ...FLOW_COLUMNS.map((c) => c.field), 'closingQty', 'warnLevel', 'slowLevel', 'staleLevel', 'zombieLevel']) {
+      // 若所有仓库该列均无数据（null），合计同样置空，避免误读为 0
+      totals[k] = items.every((it) => it[k] == null) ? null : Number(sum(k).toFixed(2));
+    }
+    // 合计行周转率按「总发货 / 总库存」重算，避免简单累加失真
+    totals.shipQty30d = Number(sum('shipQty30d').toFixed(2));
+    const totalStock = sum('closingQty');
+    totals.turnoverDays = totalStock > 0
+      ? Number((sum('shipQty30d') * 100 / totalStock).toFixed(2))
+      : null;
+
+    const noOpeningCount = items.filter((it) => it.openingQty == null).length;
+    const balanceMismatch = checkBalance([...officialMap.values()]);
+    const officialFlowFields = FLOW_COLUMNS
+      .filter((c) => items.some((it) => it.source.flows[c.field] === 'official'))
+      .map((c) => c.field);
+    const derivedFlowFields = FLOW_COLUMNS
+      .filter((c) => items.some((it) => it.source.flows[c.field] === 'derived'))
+      .map((c) => c.field);
+
+    const payload = {
+      openingDate,
+      latestBizDate,
+      systemBizDate,
+      staleMetrics,
+      asOf,
+      shipWindow: asOf ? { ...shipWindow(asOf), days: SHIP_WINDOW_DAYS } : null,
+      flowColumns: FLOW_COLUMNS,
+      flowColumnsAvailable: AVAILABLE_FLOW_FIELDS,
+      flowColumnsOfficial: officialFlowFields,
+      flowColumnsDerived: derivedFlowFields,
+      noOpeningCount,
+      official: {
+        hasData: officialMap.size > 0,
+        warehouseCount: officialMap.size,
+        availableDates: officialDates,
+        balanceMismatch,
+      },
+      items,
+      totals,
+    };
+    cachedResult = payload;
+    cachedResultAt = Date.now();
+    return res.json({ success: true, data: payload });
+  } catch (error) {
+    console.error('[daily-inventory] 查询失败:', error.message);
+    return res.status(500).json({ success: false, error: '每日进销存数据查询失败', detail: error.message });
+  }
+});
+
+/**
+ * 官方期初 = 上一业务日期末、官方期末 = 当日期末。
+ * 导入后回写本地快照，让「今日期初 = 昨日结存」的自动推算也对齐聚水潭口径。
+ */
+async function syncSnapshotFromOfficial(bizDate, rows) {
+  const byId = new Map(DAILY_INVENTORY_BASELINE.map((b) => [String(b.wmsCoId), b]));
+  const known = rows.filter((r) => r.wmsCoId != null);
+  if (!known.length) return { prev: 0, current: 0 };
+  const prevDate = prevDay(bizDate);
+
+  let prevCount = 0;
+  if (prevDate) {
+    const prev = await snapshotDb.fetchSnapshot(prevDate).catch(() => new Map());
+    prevCount = await snapshotDb.upsertSnapshot(prevDate, known
+      .filter((r) => r.openingQty != null)
+      .map((r) => ({
+        wmsCoId: r.wmsCoId,
+        warehouse: r.warehouse,
+        dbWarehouse: byId.get(String(r.wmsCoId))?.dbWarehouse || null,
+        closingQty: Number(r.openingQty),
+        skuCount: Number(prev.get(String(r.wmsCoId))?.skuCount || 0),
+        takenAt: null,
+      }))).catch((e) => {
+      console.error('[daily-inventory] 期初快照回写失败:', e.message);
+      return 0;
+    });
+  }
+
+  const current = await snapshotDb.fetchSnapshot(bizDate).catch(() => new Map());
+  const currentCount = await snapshotDb.upsertSnapshot(bizDate, known
+    .filter((r) => r.closingQty != null)
+    .map((r) => ({
+      wmsCoId: r.wmsCoId,
+      warehouse: r.warehouse,
+      dbWarehouse: byId.get(String(r.wmsCoId))?.dbWarehouse || null,
+      closingQty: Number(r.closingQty),
+      skuCount: Number(current.get(String(r.wmsCoId))?.skuCount || 0),
+      takenAt: null,
+    }))).catch((e) => {
+    console.error('[daily-inventory] 期末快照回写失败:', e.message);
+    return 0;
+  });
+
+  return { prev: prevCount, current: currentCount };
+}
+
+/**
+ * GET /api/daily-inventory/official
+ * 查询某业务日已导入的聚水潭官方进销存数据
+ */
+router.get('/official', async (req, res) => {
+  try {
+    const date = String(req.query?.date || '').trim();
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+      return res.status(400).json({ success: false, error: '请提供业务日期 date=YYYY-MM-DD' });
+    }
+    const map = await officialDb.fetchOfficial(date);
+    const dates = await officialDb.listOfficialDates(30);
+    return res.json({
+      success: true,
+      data: { date, rows: [...map.values()], availableDates: dates },
+    });
+  } catch (error) {
+    console.error('[daily-inventory] 官方数据查询失败:', error.message);
+    return res.status(500).json({ success: false, error: '官方数据查询失败', detail: error.message });
+  }
+});
+
+/**
+ * POST /api/daily-inventory/official-import
+ * 导入聚水潭进销存按仓导出（multipart: file=xlsx, date；或 JSON: {date, rows}）
+ */
+router.post('/official-import', upload.single('file'), async (req, res) => {
+  try {
+    const date = String((req.body && req.body.date) || req.query?.date || '').trim();
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+      return res.status(400).json({ success: false, error: '请提供业务日期 date（YYYY-MM-DD）' });
+    }
+
+    let rows = [];
+    let warnings = [];
+    let sheetName = null;
+    if (req.file && req.file.buffer) {
+      const parsed = parseWorkbook(req.file.buffer);
+      rows = parsed.rows;
+      warnings = parsed.warnings;
+      sheetName = parsed.sheetName;
+      if (!rows.length) {
+        return res.status(400).json({
+          success: false,
+          error: '未能从文件解析出仓库行',
+          detail: warnings.join('；') || '未找到含「仓库」列的工作表',
+        });
+      }
+    } else if (req.body && Array.isArray(req.body.rows)) {
+      const parsed = normalizeRecords(req.body.rows);
+      rows = parsed.rows;
+      warnings = parsed.warnings;
+      if (!rows.length) {
+        return res.status(400).json({ success: false, error: 'rows 中未解析到仓库行', detail: warnings.join('；') });
+      }
+    } else {
+      return res.status(400).json({ success: false, error: '请上传 xlsx 文件（字段名 file）或提供 rows 数组' });
+    }
+
+    const result = await importOfficial(date, rows, {
+      source: String((req.body && req.body.source) || 'jst-export'),
+    });
+    const synced = await syncSnapshotFromOfficial(date, rows);
+    cachedResult = null; // 导入后立即使查询缓存失效
+
+    return res.json({
+      success: true,
+      data: {
+        ...result,
+        sheetName,
+        warnings,
+        snapshotSynced: synced,
+      },
+    });
+  } catch (error) {
+    console.error('[daily-inventory] 官方数据导入失败:', error.message);
+    return res.status(500).json({ success: false, error: '官方数据导入失败', detail: error.message });
+  }
+});
+
+module.exports = router;

backend/src/api/dailyInventoryNotification.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// 每日进销存 · 定时截图通知（管理员专用）
+//
+// 安全约定：
+//   · 全部接口要求登录且 role === 'admin'
+//   · 响应里只有「是否已配置」与脱敏预览，绝不返回通知中心密钥 / 对象存储密钥
+//   · 收件人名单由后端校验与规范化，前端只能提交姓名文本
+
+const express = require('express');
+const {
+  getDailyInventoryNotificationAdminConfig,
+  listRunRecords,
+  saveDailyInventoryNotificationConfig,
+} = require('../services/dailyInventoryNotificationSettings');
+const {
+  runDailyInventoryNotificationJob,
+} = require('../jobs/dailyInventoryNotificationJob');
+
+const router = express.Router();
+
+function sendError(res, error, fallback) {
+  const status = Number(error?.statusCode) || 500;
+  console.error('[DailyInventoryNotification]', {
+    message: error?.message || fallback,
+    code: error?.code || null,
+    status,
+  });
+  res.status(status).json({ success: false, error: error.message || fallback });
+}
+
+/** 仅管理员可查看与修改通知设置、执行立即测试 */
+function requireAdmin(req, res, next) {
+  if (req?.user?.role !== 'admin') {
+    return res.status(403).json({ success: false, error: '仅管理员可操作通知设置' });
+  }
+  return next();
+}
+
+router.use(requireAdmin);
+
+// 读取通知设置（含通知中心 / 对象存储的配置状态与最近执行记录）
+router.get('/config', async (_req, res) => {
+  try {
+    res.json({ success: true, data: await getDailyInventoryNotificationAdminConfig() });
+  } catch (error) {
+    sendError(res, error, '加载每日进销存通知设置失败');
+  }
+});
+
+// 保存通知设置
+router.put('/config', async (req, res) => {
+  try {
+    const saved = await saveDailyInventoryNotificationConfig(req.body || {});
+    res.json({ success: true, data: { ...saved, admin: await getDailyInventoryNotificationAdminConfig() } });
+  } catch (error) {
+    sendError(res, error, '保存每日进销存通知设置失败');
+  }
+});
+
+// 立即测试：真实走一次截图 + 上传 + 通知，但不写入正式幂等记录
+router.post('/test', async (_req, res) => {
+  try {
+    const result = await runDailyInventoryNotificationJob({ mode: 'test' });
+    res.json({ success: result?.success === true, data: result });
+  } catch (error) {
+    sendError(res, error, '执行每日进销存通知测试失败');
+  }
+});
+
+// 最近执行记录（管理员排障用）
+router.get('/runs', async (req, res) => {
+  try {
+    const limit = Math.min(Math.max(Number(req.query?.limit) || 10, 1), 50);
+    res.json({ success: true, data: await listRunRecords(limit) });
+  } catch (error) {
+    sendError(res, error, '加载每日进销存通知执行记录失败');
+  }
+});
+
+module.exports = router;

backend/src/api/desktopClient.js

@@ -1,18 +1,6 @@
 const express = require('express');
 const crypto = require('crypto');
 const authMiddleware = require('../middleware/auth');
-const {
-  buildPublicUrl,
-  getDefaultS3Config,
-  getObjectFromDefaultS3,
-} = require('../services/objectStorage');
-const {
-  compareVersions,
-  getDesktopReleaseById,
-  getLatestDesktopRelease,
-  mapRelease,
-  normalizeVersion,
-} = require('../services/desktopReleaseService');
 const {
   DesktopSessionError,
   createDesktopSession,
@@ -24,23 +12,6 @@ const {
 
 const router = express.Router();
 
-function publicRelease(release) {
-  const mapped = mapRelease(release);
-  if (!mapped) return null;
-  return {
-    id: mapped.id,
-    version: mapped.version,
-    releaseNotes: mapped.releaseNotes,
-    platform: mapped.platform,
-    architecture: mapped.architecture,
-    fileName: mapped.fileName,
-    fileSize: mapped.fileSize,
-    sha256: mapped.sha256,
-    publishedAt: mapped.publishedAt,
-    downloadUrl: `/api/desktop-client/releases/${mapped.id}/download`,
-  };
-}
-
 function requestUserId(req) {
   return req.user?.sub ?? req.user?.id;
 }
@@ -164,68 +135,4 @@ router.post('/session/revoke', authMiddleware, async (req, res) => {
   }
 });
 
-router.get('/latest', async (req, res) => {
-  try {
-    const platform = req.query.platform || 'win32';
-    const architecture = req.query.architecture || '';
-    const release = await getLatestDesktopRelease(platform, architecture);
-    const currentVersion = normalizeVersion(req.query.currentVersion);
-    const data = publicRelease(release);
-    res.setHeader('Cache-Control', 'no-store, max-age=0');
-    res.json({
-      success: true,
-      data: data ? {
-        ...data,
-        currentVersion: currentVersion || null,
-        updateAvailable: currentVersion ? compareVersions(data.version, currentVersion) > 0 : null,
-      } : null,
-    });
-  } catch (error) {
-    console.error('获取桌面客户端最新版本失败:', error);
-    res.status(500).json({ success: false, error: '获取桌面客户端最新版本失败' });
-  }
-});
-
-router.get('/releases/:id/download', async (req, res) => {
-  try {
-    const release = await getDesktopReleaseById(Number(req.params.id));
-    if (!release) {
-      return res.status(404).json({ success: false, error: '安装包不存在或已下线' });
-    }
-
-    const storageConfig = await getDefaultS3Config();
-    if (storageConfig?.customDomain) {
-      return res.redirect(302, buildPublicUrl(storageConfig, release.objectKey));
-    }
-
-    const object = await getObjectFromDefaultS3(release.objectKey, {
-      range: req.headers.range,
-    });
-    const encodedName = encodeURIComponent(release.fileName).replace(/%20/g, '+');
-    res.status(object.ContentRange ? 206 : 200);
-    const fallbackContentType = release.platform === 'darwin'
-      ? 'application/x-apple-diskimage'
-      : 'application/vnd.microsoft.portable-executable';
-    res.setHeader('Content-Type', object.ContentType || fallbackContentType);
-    res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${encodedName}`);
-    res.setHeader('Accept-Ranges', object.AcceptRanges || 'bytes');
-    res.setHeader('Cache-Control', 'private, max-age=3600');
-    if (object.ContentLength != null) res.setHeader('Content-Length', String(object.ContentLength));
-    if (object.ContentRange) res.setHeader('Content-Range', object.ContentRange);
-    if (object.ETag) res.setHeader('ETag', object.ETag);
-
-    object.Body.on('error', (error) => {
-      console.error('桌面客户端安装包下载流中断:', error);
-      if (!res.headersSent) res.status(502).end();
-      else res.destroy(error);
-    });
-    object.Body.pipe(res);
-  } catch (error) {
-    console.error('下载桌面客户端安装包失败:', error);
-    if (!res.headersSent) {
-      res.status(502).json({ success: false, error: '安装包下载失败，请稍后重试' });
-    }
-  }
-});
-
 module.exports = router;

backend/src/api/install.js

@@ -5,6 +5,11 @@ const {
   shouldAutoRestartAfterInstall,
   testSystemDatabaseBootstrapConnection,
 } = require('../services/installService');
+const {
+  DEFAULT_BOOTSTRAP_ENDPOINT,
+  enrollRemoteInstallation,
+  scheduleRemoteRestart,
+} = require('../services/remoteEnrollmentService');
 
 const router = express.Router();
 
@@ -18,6 +23,47 @@ router.get('/status', async (_req, res) => {
   }
 });
 
+router.get('/remote-bootstrap', (_req, res) => {
+  res.json({
+    enabled: true,
+    defaultEndpoint: DEFAULT_BOOTSTRAP_ENDPOINT,
+    supervised: process.env.CANGKU_REMOTE_SUPERVISOR === 'true',
+  });
+});
+
+router.post('/remote-bootstrap', async (req, res) => {
+  try {
+    res.set('Cache-Control', 'no-store');
+    const status = await getInstallStatus();
+    if (!status.required) {
+      return res.status(409).json({ error: '系统数据库已经配置，不能重复注册远程部署' });
+    }
+
+    const result = await enrollRemoteInstallation(req.body || {});
+    const restartScheduled = process.env.CANGKU_REMOTE_SUPERVISOR === 'true';
+    res.once('finish', () => {
+      setTimeout(() => {
+        try {
+          scheduleRemoteRestart();
+        } catch (error) {
+          console.error('写入远程启动标记失败:', error.message);
+        }
+      }, 800);
+    });
+    return res.json({
+      success: true,
+      message: restartScheduled
+        ? '远程系统数据库配置完成，服务正在自动重启'
+        : '远程系统数据库配置完成，请使用 npm run remote:dev 重新启动',
+      restartScheduled,
+      ...result,
+    });
+  } catch (error) {
+    console.error('远程部署注册失败:', error.message);
+    return res.status(400).json({ error: error.message || '远程部署注册失败' });
+  }
+});
+
 router.post('/system-database/test', async (req, res) => {
   try {
     const startTime = Date.now();

backend/src/api/mkhBom.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const express = require('express');
+const {
+  getMkhBomList,
+  getMkhBomDetail,
+  listMkhBomExportRows,
+  clearMkhBomCache,
+} = require('../services/mkhBomService');
+const {
+  getMkhReplenishAlertAdminConfig,
+  resetMkhReplenishAlertState,
+  saveMkhReplenishAlertConfig,
+} = require('../services/mkhReplenishAlertSettings');
+const { checkMkhReplenishAlerts } = require('../jobs/mkhReplenishAlertJob');
+const {
+  saveYydNotificationCenterConfig,
+} = require('../services/yydNotificationCenterSettings');
+
+const router = express.Router();
+
+function sendError(res, error, fallback) {
+  const status = Number(error?.statusCode) || 500;
+  console.error('[MkhBom]', {
+    message: error?.message || fallback,
+    code: error?.code || null,
+    status,
+  });
+  res.status(status).json({ success: false, error: error.message || fallback });
+}
+
+function buildSyncQuery(query = {}) {
+  return { ...query, live: '1', fresh: '1' };
+}
+
+// MKH-BOM 资料列表（模块化组合商品 + 配件汇总）
+router.get('/list', async (req, res) => {
+  try {
+    res.set('Cache-Control', 'no-store');
+    res.json({ success: true, data: await getMkhBomList(req.query || {}) });
+  } catch (error) {
+    sendError(res, error, '加载 MKH-BOM 资料列表失败');
+  }
+});
+
+// 单个 MKH 组合商品的 BOM 配件明细（打印用）
+router.get('/detail', async (req, res) => {
+  try {
+    const skuId = req.query?.skuId || req.query?.comboSkuId;
+    res.set('Cache-Control', 'no-store');
+    res.json({ success: true, data: await getMkhBomDetail(skuId) });
+  } catch (error) {
+    sendError(res, error, '加载 MKH-BOM 明细失败');
+  }
+});
+
+// 导出：当前筛选条件下的全部数据（不分页）
+//   mode=products（默认）→ 商品清单；mode=components → 配件明细摊平
+router.get('/export', async (req, res) => {
+  try {
+    res.json({ success: true, data: await listMkhBomExportRows(req.query || {}) });
+  } catch (error) {
+    sendError(res, error, '导出 MKH-BOM 资料失败');
+  }
+});
+
+// 补货预警推送设置（接收人 / 开关 / 推送范围）
+router.get('/alert-config', async (req, res) => {
+  try {
+    res.json({ success: true, data: await getMkhReplenishAlertAdminConfig() });
+  } catch (error) {
+    sendError(res, error, '加载补货预警推送设置失败');
+  }
+});
+
+// 保存补货预警推送设置
+router.put('/alert-config', async (req, res) => {
+  try {
+    const data = await saveMkhReplenishAlertConfig(req.body || {});
+    res.json({ success: true, data });
+  } catch (error) {
+    sendError(res, error, '保存补货预警推送设置失败');
+  }
+});
+
+// 立即检查并推送（dryRun: 只预览不发送；force: 忽略「只推新增」推全量；reset: 先清空已推送记录）
+router.post('/alert-check', async (req, res) => {
+  try {
+    const body = req.body || {};
+    if (body.reset === true) await resetMkhReplenishAlertState();
+    const result = await checkMkhReplenishAlerts({
+      dryRun: body.dryRun === true,
+      force: body.force === true,
+    });
+    res.json({ success: true, data: result });
+  } catch (error) {
+    sendError(res, error, '执行补货预警推送失败');
+  }
+});
+
+// 保存统一通知中心凭据（补货预警的推送通道）
+router.put('/notification-center', async (req, res) => {
+  try {
+    await saveYydNotificationCenterConfig(req.body || {});
+    res.json({ success: true, data: await getMkhReplenishAlertAdminConfig() });
+  } catch (error) {
+    sendError(res, error, '保存统一通知中心配置失败');
+  }
+});
+
+// 手动同步：先清空本页服务端缓存（BOM / 补货索引 / 加工单 / 待发货 / 配件库存 / 仓位），
+// 再在同一次请求中直连副本库读取新快照。这样不会被同步前尚未完成的旧列表请求覆盖。
+router.post('/sync', async (req, res) => {
+  try {
+    const cache = clearMkhBomCache();
+    // fresh=1 是真正重读库存 / 加工单 / 待发货数据的协议。
+    // 只清缓存再传 live=1 会落到旧快照，导致按钮显示“同步成功”却数值不变。
+    const snapshot = await getMkhBomList(buildSyncQuery(req.body?.query));
+    res.set('Cache-Control', 'no-store');
+    res.json({ success: true, data: { cache, snapshot } });
+  } catch (error) {
+    sendError(res, error, '同步 MKH-BOM 数据失败');
+  }
+});
+
+module.exports = router;
+module.exports._private = { buildSyncQuery };

backend/src/api/modularStockMonitor.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const express = require('express');
+const {
+  getModularStockList,
+  getModularStockFilters,
+  getPurchaseInTransitList,
+  syncModularStock,
+} = require('../services/modularStockMonitorService');
+
+const router = express.Router();
+
+function sendError(res, error, fallback) {
+  const status = Number(error?.statusCode) || 500;
+  console.error('[ModularStockMonitor]', {
+    message: error?.message || fallback,
+    code: error?.code || null,
+    status,
+  });
+  res.status(status).json({ success: false, error: error.message || fallback });
+}
+
+// 配件库存监控明细列表（默认仅「简尚-崔桥工厂半成品包装项目仓」）
+router.get('/list', async (req, res) => {
+  try {
+    res.json({ success: true, data: await getModularStockList(req.query || {}) });
+  } catch (error) {
+    sendError(res, error, '加载配件库存监控列表失败');
+  }
+});
+
+// 筛选下拉选项（品类 / 预警等级）
+router.get('/filters', async (_req, res) => {
+  try {
+    res.json({ success: true, data: await getModularStockFilters() });
+  } catch (error) {
+    sendError(res, error, '加载配件库存监控筛选选项失败');
+  }
+});
+
+// 采购在途明细列表：目标仓全部「采购数量 > 已入库数量」的采购单明细
+router.get('/purchase-in-transit', async (req, res) => {
+  try {
+    res.json({ success: true, data: await getPurchaseInTransitList(req.query || {}) });
+  } catch (error) {
+    sendError(res, error, '加载采购在途明细失败');
+  }
+});
+
+// 手动同步：重新取最新监控日，前端「同步」按钮调用后再拉一次列表即拿到最新快照
+router.post('/sync', async (_req, res) => {
+  try {
+    res.json({ success: true, data: await syncModularStock() });
+  } catch (error) {
+    sendError(res, error, '同步配件库存监控数据失败');
+  }
+});
+
+module.exports = router;

backend/src/api/pickingBinSalesAnalysis.js

@@ -0,0 +1,282 @@
+const express = require('express');
+const cloudDb = require('../config/cloudDatabase');
+const { DAILY_INVENTORY_BASELINE } = require('../config/dailyInventoryBaseline');
+const {
+  PICKING_BIN_GRADE_RULES,
+  PICKING_BIN_WINDOW_OPTIONS,
+  PICKING_BIN_DEFAULT_DAYS,
+  PICKING_BIN_TOTAL_LABEL,
+  PICKING_BIN_BIN_TYPES,
+} = require('../config/pickingBinSalesAnalysis');
+const { fetchPickingBinSkuRows } = require('../services/pickingBinSalesAnalysis');
+const { sendWorkbookDownload } = require('../services/exportWorkbook');
+
+const router = express.Router();
+
+/** 库存衡量基准时刻：快照日次日 01:00（报表库每日凌晨跑批，标注 T-1） */
+const AS_OF_TIME = '01:00';
+
+/** 结果缓存：一次要扫订单明细 + 仓位明细两张大表，避免连续刷新重复打库 */
+const RESULT_CACHE_TTL_MS = 5 * 60 * 1000;
+const cacheByKey = new Map();
+
+const round2 = (v) => Math.round((Number(v) || 0) * 100) / 100;
+const round4 = (v) => Math.round((Number(v) || 0) * 10000) / 10000;
+
+/** 快照日 + 次日 01:00 作为统一的统计基准时刻 */
+function nextDayAsOf(bizDate) {
+  if (!bizDate || !/^\d{4}-\d{2}-\d{2}$/.test(bizDate)) return null;
+  const d = new Date(`${bizDate}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + 1);
+  return `${d.toISOString().slice(0, 10)} ${AS_OF_TIME}`;
+}
+
+/** 发货窗口：[asOf - N 天, asOf) */
+function buildShipWindow(asOf, days) {
+  const to = new Date(`${asOf.slice(0, 10)}T${AS_OF_TIME}:00Z`);
+  const from = new Date(to.getTime() - days * 86400000);
+  const fmt = (dt) => dt.toISOString().slice(0, 19).replace('T', ' ');
+  return { shipFrom: fmt(from), shipTo: fmt(to) };
+}
+
+async function fetchLatestBizDate() {
+  const rows = await cloudDb.query(
+    `SELECT MAX(CONVERT(VARCHAR(10), date, 23)) AS d FROM rpt.pm_stockMonitor`
+  );
+  return rows[0]?.d || null;
+}
+
+async function fetchBinTakenAt() {
+  const rows = await cloudDb.query(
+    `SELECT MAX(updateTime) AS takenAt FROM rpt.jst_packInventoryInfo`
+  );
+  return rows[0]?.takenAt || null;
+}
+
+/** 解析并收敛统计窗口天数，只允许白名单内的取值 */
+function resolveDays(raw) {
+  const n = Number.parseInt(String(raw ?? ''), 10);
+  return PICKING_BIN_WINDOW_OPTIONS.includes(n) ? n : PICKING_BIN_DEFAULT_DAYS;
+}
+
+/** 解析仓库过滤，只允许出现在仓库清单里的 wmsCoId，防止任意拼参 */
+function resolveWarehouses(raw) {
+  const known = DAILY_INVENTORY_BASELINE.filter((b) => b.wmsCoId != null);
+  const requested = String(raw || '')
+    .split(',')
+    .map((v) => v.trim())
+    .filter(Boolean);
+  const picked = requested.length > 0
+    ? known.filter((b) => requested.includes(String(b.wmsCoId)))
+    : known;
+  return picked;
+}
+
+const GRADE_MAP = new Map(PICKING_BIN_GRADE_RULES.map((g) => [g.key, g]));
+
+/** 明细行按「仓库 × 商品编码」去重后的商品个数 */
+function dedupeCount(list) {
+  return new Set(list.map((it) => `${it.wmsCoId}::${it.skuId}`)).size;
+}
+
+/**
+ * GET /api/picking-bin-sales-analysis
+ * 拣选库位动销分析：仓库 × 仓位 × 商品编码 → 库存数量 / 商品销量 / 商品日销 / 动销等级
+ * 动销等级按「商品日销」判定（商品整档销量 ÷ 天数），不做仓位分摊。
+ */
+router.get('/', async (req, res) => {
+  try {
+    const force = String(req.query?.refresh || '') === '1';
+    const days = resolveDays(req.query?.days);
+    const warehouses = resolveWarehouses(req.query?.wmsCoId);
+    const wmsCoIds = warehouses.map((b) => String(b.wmsCoId));
+
+    const cacheKey = `${days}::${wmsCoIds.join('|')}`;
+    const latestBizDate = await fetchLatestBizDate().catch(() => null);
+    const cached = cacheByKey.get(cacheKey);
+    if (!force && cached && cached.latestBizDate === latestBizDate
+      && Date.now() - cached.at < RESULT_CACHE_TTL_MS) {
+      return res.json({ success: true, data: cached.payload, cached: true });
+    }
+
+    const asOf = nextDayAsOf(latestBizDate);
+    if (!asOf) {
+      return res.status(503).json({
+        success: false,
+        error: '业务库暂无库存监控数据，无法定位统计基准日',
+      });
+    }
+
+    const { shipFrom, shipTo } = buildShipWindow(asOf, days);
+    const [rows, takenAt] = await Promise.all([
+      fetchPickingBinSkuRows(cloudDb, wmsCoIds, { shipFrom, shipTo, days }),
+      fetchBinTakenAt().catch(() => null),
+    ]);
+
+    const whMap = new Map(warehouses.map((b) => [String(b.wmsCoId), b.warehouse]));
+    const items = rows.map((r) => ({
+      wmsCoId: r.wmsCoId,
+      binName: r.binName,
+      binType: r.binType,
+      skuId: r.skuId,
+      warehouse: whMap.get(r.wmsCoId) || r.wmsCoId,
+      stockQty: r.stockQty,
+      skuCount: r.skuCount,
+      salesQty: round2(r.salesQty),
+      dailySales: round4(r.dailySales),
+      gradeKey: r.gradeKey,
+      gradeLabel: GRADE_MAP.get(r.gradeKey)?.label || '',
+    }));
+
+    // 每个「仓库 × 商品」只计一次销量，避免同一商品跨多个仓位被重复累加
+    const skuSalesMap = new Map();
+    rows.forEach((r) => {
+      const key = `${r.wmsCoId}::${r.skuId}`;
+      if (!skuSalesMap.has(key)) skuSalesMap.set(key, r.salesQty);
+    });
+    const dedupeSales = (list) => {
+      const seen = new Set();
+      return list.reduce((acc, it) => {
+        const key = `${it.wmsCoId}::${it.skuId}`;
+        if (seen.has(key)) return acc;
+        seen.add(key);
+        return acc + (skuSalesMap.get(key) || 0);
+      }, 0);
+    };
+
+    // 各动销等级汇总：商品数按「仓库 × 商品」去重，库存按明细行求和（无重复）
+    const summary = PICKING_BIN_GRADE_RULES.map((grade) => {
+      const hit = items.filter((it) => it.gradeKey === grade.key);
+      const salesQty = round2(dedupeSales(hit));
+      return {
+        key: grade.key,
+        label: grade.label,
+        tip: grade.tip,
+        rowCount: hit.length,
+        skuCount: dedupeCount(hit),
+        stockQty: round2(hit.reduce((acc, it) => acc + it.stockQty, 0)),
+        salesQty,
+        dailySales: round4(salesQty / days),
+      };
+    });
+
+    const dedupeAll = new Set(items.map((it) => `${it.wmsCoId}::${it.skuId}`));
+    const totalSales = round2(dedupeSales(items));
+    const total = {
+      key: '__total__',
+      label: PICKING_BIN_TOTAL_LABEL,
+      rowCount: items.length,
+      skuCount: dedupeAll.size,
+      stockQty: round2(summary.reduce((acc, s) => acc + s.stockQty, 0)),
+      salesQty: totalSales,
+      dailySales: round4(totalSales / days),
+    };
+
+    const payload = {
+      days,
+      windowOptions: PICKING_BIN_WINDOW_OPTIONS,
+      binTypes: [...PICKING_BIN_BIN_TYPES],
+      binTypeOptions: [...PICKING_BIN_BIN_TYPES],
+      latestBizDate,
+      asOf,
+      shipWindow: { shipFrom, shipTo, days },
+      takenAt,
+      grades: PICKING_BIN_GRADE_RULES.map((g) => ({ key: g.key, label: g.label, tip: g.tip })),
+      totalLabel: PICKING_BIN_TOTAL_LABEL,
+      warehouses: warehouses.map((b) => ({ wmsCoId: String(b.wmsCoId), warehouse: b.warehouse })),
+      items,
+      summary,
+      total,
+    };
+
+    cacheByKey.set(cacheKey, { latestBizDate, at: Date.now(), payload });
+    return res.json({ success: true, data: payload });
+  } catch (error) {
+    console.error('[picking-bin-sales-analysis] 查询失败:', error.message);
+    return res.status(500).json({
+      success: false,
+      error: '拣选库位动销分析数据查询失败',
+      detail: error.message,
+    });
+  }
+});
+
+/**
+ * GET /api/picking-bin-sales-analysis/export
+ * 导出库位明细（只含拣选位）。query: days、wmsCoId（逗号分隔）、grade（逗号分隔）、format（xlsx|csv）
+ */
+router.get('/export', async (req, res) => {
+  try {
+    const days = resolveDays(req.query?.days);
+    const warehouses = resolveWarehouses(req.query?.wmsCoId);
+    const wmsCoIds = warehouses.map((b) => String(b.wmsCoId));
+    const format = String(req.query?.format || 'xlsx').toLowerCase() === 'csv' ? 'csv' : 'xlsx';
+
+    const grades = String(req.query?.grade || '')
+      .split(',')
+      .map((v) => v.trim())
+      .filter((v) => GRADE_MAP.has(v));
+
+    const latestBizDate = await fetchLatestBizDate().catch(() => null);
+    const asOf = nextDayAsOf(latestBizDate);
+    if (!asOf) {
+      return res.status(503).json({
+        success: false,
+        error: '业务库暂无库存监控数据，无法定位统计基准日',
+      });
+    }
+
+    const { shipFrom, shipTo } = buildShipWindow(asOf, days);
+    // 导出按「仓位 × 商品编码」拆行：一个仓位有 N 个商品就输出 N 行
+    const rows = await fetchPickingBinSkuRows(cloudDb, wmsCoIds, { shipFrom, shipTo, days });
+
+    const whMap = new Map(warehouses.map((b) => [String(b.wmsCoId), b.warehouse]));
+    const filtered = grades.length > 0
+      ? rows.filter((r) => grades.includes(r.gradeKey))
+      : rows;
+
+    const sheetRows = filtered.map((r) => [
+      whMap.get(r.wmsCoId) || r.wmsCoId,
+      r.binName,
+      r.binType,
+      r.skuId,
+      r.stockQty,
+      r.skuCount,
+      round2(r.salesQty),
+      round4(r.allocatedSalesQty),
+      round4(r.dailySales),
+      GRADE_MAP.get(r.gradeKey)?.label || r.gradeKey,
+      days,
+      latestBizDate || '',
+    ]);
+
+    const fileName = `拣选库位动销分析-${(latestBizDate || '').replace(/-/g, '') || '未知日期'}`;
+    const { totalRows } = sendWorkbookDownload(res, {
+      fileName,
+      format,
+      sheets: [{
+        name: '库位动销明细',
+        header: [
+          '仓库', '仓位', '类型', '商品编码', '库存数量', '仓位SKU数',
+          `商品销量(近${days}天)`, `分摊销量(近${days}天)`, '商品日销',
+          '动销等级', '统计天数', '统计基准日',
+        ],
+        rows: sheetRows,
+      }],
+    });
+    console.log(`[picking-bin-sales-analysis] 导出: ${totalRows} 行, 仓库 ${wmsCoIds.length} 个, 仅拣选位, 窗口 ${days} 天`);
+    return null;
+  } catch (error) {
+    console.error('[picking-bin-sales-analysis] 导出失败:', error.message);
+    if (!res.headersSent) {
+      return res.status(500).json({
+        success: false,
+        error: '拣选库位动销分析导出失败',
+        detail: error.message,
+      });
+    }
+    return null;
+  }
+});
+
+module.exports = router;

backend/src/api/pricingCalculator.js

@@ -1,833 +0,0 @@
-const express = require('express');
-const XLSX = require('xlsx');
-const database = require('../config/database');
-const {
-  getCompanySkusBySpu,
-  fetchFreightProfile,
-  getSelectionFissionProfitPricingContext,
-  getSelectionFissionProductCodeMeta,
-  saveSelectionFissionProfitPricingTable,
-} = require('../services/planningSelectionFissionService');
-
-const router = express.Router();
-
-const HISTORY_TABLE = 'pricing_calculator_history';
-// 运费/售后画像查询设定超时，避免整页等待。
-const FREIGHT_PROFILE_TIMEOUT_MS = Math.max(
-  Number.parseInt(process.env.PRICING_CALC_FREIGHT_TIMEOUT_MS || '30000', 10) || 30000,
-  5000
-);
-const MAX_HISTORY_ROWS = 500;
-const MAX_PAYLOAD_BYTES = 1024 * 1024;
-const CALCULATOR_TYPES = new Set(['company', 'alibaba1688']);
-
-let historyTableReady = null;
-
-async function ensureHistoryTable() {
-  if (!historyTableReady) {
-    historyTableReady = (async () => {
-      // 先查表是否存在：生产/隧道账号通常只有 SELECT/INSERT/UPDATE/DELETE，
-      // MariaDB 对 CREATE TABLE IF NOT EXISTS 也会校验 CREATE 权限，存在时直接跳过。
-      const existing = await database.local.query(
-        `SELECT 1
-         FROM information_schema.tables
-         WHERE table_schema = DATABASE()
-           AND table_name = ?
-         LIMIT 1`,
-        [HISTORY_TABLE]
-      );
-      if (existing.length > 0) {
-        return;
-      }
-      await database.local.query(
-        `CREATE TABLE IF NOT EXISTS ${HISTORY_TABLE} (
-          id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键ID',
-          user_id BIGINT NOT NULL COMMENT '测算人用户ID',
-          user_name VARCHAR(100) NULL COMMENT '测算人显示名',
-          spu_code VARCHAR(160) NOT NULL COMMENT '公司SPU',
-          brand VARCHAR(100) NULL COMMENT '品牌名称',
-          note VARCHAR(500) NULL COMMENT '备注',
-          row_count INT NOT NULL DEFAULT 0 COMMENT '测算行数',
-          payload_json LONGTEXT NOT NULL COMMENT '完整测算快照 JSON',
-          created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
-          updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
-          INDEX idx_pricing_calc_history_user_created (user_id, created_at)
-        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='上架测算历史记录'`
-      );
-    })();
-  }
-  try {
-    await historyTableReady;
-  } catch (error) {
-    // 建表失败后允许下次请求重试
-    historyTableReady = null;
-    throw error;
-  }
-}
-
-function sendError(res, error, fallbackMessage) {
-  const status = error.status || error.statusCode || 500;
-  res.status(status).json({
-    success: false,
-    error: error.message || fallbackMessage,
-  });
-}
-
-function getRequestUser(req) {
-  const user = req.user || {};
-  return {
-    id: Number(user.sub || user.id || 0) || null,
-    name: user.name || user.username || '',
-    isAdmin: user.role === 'admin',
-  };
-}
-
-function requireUserId(req, res) {
-  const { id } = getRequestUser(req);
-  if (!id) {
-    res.status(401).json({ success: false, error: '当前登录状态无效，请重新登录' });
-    return null;
-  }
-  return id;
-}
-
-const normalizeText = (value, maxLength) => String(value ?? '').trim().slice(0, maxLength);
-
-const normalizeCalculatorType = (value) => (
-  CALCULATOR_TYPES.has(value) ? value : 'company'
-);
-
-function sanitizeHistoryProduct(input) {
-  const product = input && typeof input === 'object' ? input : {};
-  const dimensions = (Array.isArray(product.skuDimensions) ? product.skuDimensions : [])
-    .slice(0, 4)
-    .map((dimension) => ({
-      name: normalizeText(dimension?.name, 120),
-      values: (Array.isArray(dimension?.values) ? dimension.values : [])
-        .slice(0, 500)
-        .map((value) => normalizeText(value, 500))
-        .filter(Boolean),
-    }))
-    .filter((dimension) => dimension.name);
-  return {
-    productId: normalizeText(product.productId, 80),
-    title: normalizeText(product.title, 500),
-    mainImage: normalizeText(product.mainImage, 2000),
-    sourceUrl: normalizeText(product.sourceUrl, 2000),
-    storeName: normalizeText(product.storeName, 300),
-    category: normalizeText(product.category, 500),
-    skuDimensions: dimensions,
-  };
-}
-
-function mapSkuRow(row) {
-  const qgyf = Number(row?.raw?.qgyf);
-  return {
-    skuCode: row.skuCode || '',
-    status: row.saleStatus || '',
-    stock: row.stock ?? null,
-    stockWarehouses: Array.isArray(row.stockWarehouses) ? row.stockWarehouses : [],
-    name: row.skuName || row.productName || '',
-    image: row.skuImageUrl || '',
-    size: row.size || '',
-    color: row.colorName || '',
-    cost: row.cost ?? null,
-    minimumPrice: row.minimumPrice ?? null,
-    salePrice: row?.raw?.sale_price ?? row?.raw?.salePrice ?? null,
-    // qgyf = 聚水潭接口返回的全国平均运费（按条码）
-    freight: Number.isFinite(qgyf) ? qgyf : null,
-    supplier: row.supplierName || '',
-    category: row.categoryName || '',
-    lengthCm: row.lengthCm ?? row?.raw?.length_cm ?? row?.raw?.length ?? null,
-    widthCm: row.widthCm ?? row?.raw?.width_cm ?? row?.raw?.width ?? null,
-    heightCm: row.heightCm ?? row?.raw?.height_cm ?? row?.raw?.height ?? null,
-    weight: row.weight ?? row?.raw?.weight ?? row?.raw?.gross_weight ?? null,
-  };
-}
-
-async function fetchFreightProfileBestEffort(spuCode, skuRows, user) {
-  const emptyProfile = {
-    nationalFreight: null,
-    zone1Freight: null,
-    zone2Freight: null,
-    zone3Freight: null,
-    zone4Freight: null,
-    aftersaleRatio: null,
-    minimumPricesBySku: {},
-    raw: null,
-  };
-  try {
-    const result = await Promise.race([
-      fetchFreightProfile({ spuCode, skuRows }, user),
-      new Promise((resolve) => {
-        setTimeout(() => resolve({ ...emptyProfile, warning: '运费/售后信息查询超时，可手动填写运费' }), FREIGHT_PROFILE_TIMEOUT_MS);
-      }),
-    ]);
-    return result && typeof result === 'object' ? { ...emptyProfile, ...result } : emptyProfile;
-  } catch (error) {
-    return { ...emptyProfile, warning: error.message || '运费/售后信息查询失败' };
-  }
-}
-
-// 拉取 SPU 下全部条码（含销售、退市、停产）+ 运费/售后画像（尽力而为）
-// 运费由聚水潭接口 qgyf 字段按条码直出，
-// 默认跳过；如需售后占比/最低限价画像，可设 PRICING_CALC_FREIGHT_PROFILE=on 重新开启。
-const FREIGHT_PROFILE_ENABLED = String(process.env.PRICING_CALC_FREIGHT_PROFILE || 'off').toLowerCase() === 'on';
-
-function getSelectionSkuCodeSet(selectionContext) {
-  if (!selectionContext) return null;
-  const selectedSkuCodes = Array.isArray(selectionContext.skuSceneImages?.selectedSkuCodes)
-    ? selectionContext.skuSceneImages.selectedSkuCodes
-    : [];
-  const fallbackSkuCodes = Array.isArray(selectionContext.rows)
-    ? selectionContext.rows.map((row) => row.skuCode)
-    : [];
-  return new Set(
-    (selectedSkuCodes.length > 0 ? selectedSkuCodes : fallbackSkuCodes)
-      .map((skuCode) => normalizeText(skuCode, 160).toUpperCase())
-      .filter(Boolean)
-  );
-}
-
-function filterSkuRowsForSelectionContext(skuRows, selectionContext) {
-  const rows = Array.isArray(skuRows) ? skuRows : [];
-  const selectedSkuCodes = getSelectionSkuCodeSet(selectionContext);
-  if (!selectedSkuCodes) return rows;
-  return rows.filter((row) => selectedSkuCodes.has(
-    normalizeText(row?.skuCode || row?.sku_code || row?.barcode, 160).toUpperCase()
-  ));
-}
-
-router.get('/product-code/meta', async (req, res) => {
-  const userId = requireUserId(req, res);
-  if (!userId) return;
-  try {
-    res.json({ success: true, data: await getSelectionFissionProductCodeMeta() });
-  } catch (error) {
-    sendError(res, error, '公司SKU编码配置加载失败');
-  }
-});
-
-router.get('/spu/:spuCode', async (req, res) => {
-  const spuCode = normalizeText(req.params.spuCode, 160).toUpperCase();
-  if (!spuCode) {
-    return res.status(400).json({ success: false, error: '请输入公司 SPU' });
-  }
-
-  try {
-    const planId = Number.parseInt(req.query.planId, 10) || 0;
-    const itemId = Number.parseInt(req.query.itemId, 10) || 0;
-    if (Boolean(planId) !== Boolean(itemId)) {
-      return res.status(400).json({ success: false, error: '选品定价上下文缺少方案ID或SPU任务ID' });
-    }
-    const skuResult = await getCompanySkusBySpu(spuCode, { includeInactive: true });
-    const allSkuRows = Array.from(skuResult.rows || []);
-    if (allSkuRows.length === 0) {
-      return res.status(404).json({
-        success: false,
-        error: `未查询到 SPU「${spuCode}」的条码，请确认 SPU 是否正确`,
-      });
-    }
-
-    let selectionContext = null;
-    if (planId && itemId) {
-      selectionContext = await getSelectionFissionProfitPricingContext(planId, itemId);
-      if (selectionContext.spuCode.toUpperCase() !== spuCode) {
-        return res.status(409).json({ success: false, error: `该选品任务绑定的是SPU ${selectionContext.spuCode}` });
-      }
-    }
-    const skuRows = filterSkuRowsForSelectionContext(allSkuRows, selectionContext);
-    if (selectionContext && skuRows.length === 0) {
-      return res.status(409).json({
-        success: false,
-        error: '选品任务已选 SKU 不在当前 SPU 条码列表中，请返回 SKU 节点重新确认',
-      });
-    }
-
-    const freightProfile = FREIGHT_PROFILE_ENABLED
-      ? await fetchFreightProfileBestEffort(spuCode, skuRows, req.user)
-      : { nationalFreight: null, aftersaleRatio: null, minimumPricesBySku: {}, warning: null };
-    const warnings = [...(skuResult.warnings || [])];
-    if (freightProfile.warning) {
-      warnings.push(freightProfile.warning);
-    }
-
-    const savedRowsBySku = new Map((selectionContext?.rows || []).map((row) => [
-      String(row.skuCode || '').toUpperCase(),
-      row,
-    ]));
-    res.json({
-      success: true,
-      data: {
-        spu: spuCode,
-        source: skuResult.source,
-        warnings,
-        freightProfile: {
-          nationalFreight: freightProfile.nationalFreight ?? null,
-          zone1Freight: freightProfile.zone1Freight ?? null,
-          zone2Freight: freightProfile.zone2Freight ?? null,
-          zone3Freight: freightProfile.zone3Freight ?? null,
-          zone4Freight: freightProfile.zone4Freight ?? null,
-          aftersaleRatio: freightProfile.aftersaleRatio ?? null,
-          minimumPricesBySku: freightProfile.minimumPricesBySku || {},
-        },
-        selectionContext: selectionContext ? {
-          planId: selectionContext.planId,
-          itemId: selectionContext.itemId,
-          taskCode: selectionContext.taskCode,
-          schemeCode: selectionContext.schemeCode,
-          listedItemId: selectionContext.listedItemId,
-          pricingTableSavedAt: selectionContext.pricingTableSavedAt,
-          pricingTableSavedBy: selectionContext.pricingTableSavedBy,
-          pricingTableVersion: selectionContext.pricingTableVersion,
-          workflowProfile: selectionContext.workflowProfile,
-          productCodeStatus: selectionContext.productCodeStatus,
-          productCodeStyleCode: selectionContext.productCodeStyleCode,
-          productCodeConfig: selectionContext.productCodeConfig,
-          productCodeErrorMessage: selectionContext.productCodeErrorMessage,
-          productCodeRequestedAt: selectionContext.productCodeRequestedAt,
-          productCodeCompletedAt: selectionContext.productCodeCompletedAt,
-        } : null,
-        rows: skuRows.map((skuRow) => {
-          const mapped = mapSkuRow(skuRow);
-          const saved = savedRowsBySku.get(String(mapped.skuCode || '').toUpperCase());
-          return {
-            ...mapped,
-            savedPricing: saved ? {
-              price: saved.finalPrice,
-              groupPrice: saved.groupPrice,
-              installFee: saved.installationFee,
-              coupon: saved.discountAmount,
-              activityDiscount: saved.activityDiscount,
-              shipping: saved.freightNational,
-              commission: saved.platformCommissionRatio,
-              promoRate: saved.promotionRatio,
-              adFee: saved.marketingAdRatio,
-              seeding: saved.farmingRatio,
-              afterSale: saved.aftersaleRatio,
-              insurance: saved.insuranceRatio,
-              brandFee: saved.brandUsageRatio,
-              targetMargin: saved.operatingProfitRatio,
-              originalSkuName: saved.originalSkuName,
-              selectedSkuName: saved.selectedSkuName,
-              internalProductCode: saved.internalProductCode,
-              productCodeProductName: saved.productCodeProductName,
-              productCodeColorSpec: saved.productCodeColorSpec,
-            } : null,
-          };
-        }),
-      },
-    });
-  } catch (error) {
-    sendError(res, error, 'SPU 条码查询失败，请稍后重试');
-  }
-});
-
-// 保存一条测算历史（完整行快照，含输入与公式结果）
-router.post('/history', async (req, res) => {
-  const userId = requireUserId(req, res);
-  if (!userId) return;
-
-  const body = req.body || {};
-  const spuCode = normalizeText(body.spuCode, 160).toUpperCase();
-  const calculatorType = normalizeCalculatorType(body.calculatorType);
-  const rows = Array.isArray(body.rows) ? body.rows : [];
-  if (!spuCode) {
-    return res.status(400).json({ success: false, error: '缺少 SPU 编码' });
-  }
-  if (rows.length === 0) {
-    return res.status(400).json({ success: false, error: '测算行为空，无法保存' });
-  }
-  if (rows.length > MAX_HISTORY_ROWS) {
-    return res.status(400).json({ success: false, error: `单条历史最多保存 ${MAX_HISTORY_ROWS} 行` });
-  }
-
-  const payload = {
-    version: 4,
-    calculatorType,
-    spuCode,
-    isBlackLabelShop: body.isBlackLabelShop === true,
-    brand: normalizeText(body.brand, 100),
-    note: normalizeText(body.note, 500),
-    savedAt: new Date().toISOString(),
-    summary: body.summary && typeof body.summary === 'object' ? body.summary : null,
-    freightProfile: body.freightProfile && typeof body.freightProfile === 'object' ? body.freightProfile : null,
-    product: calculatorType === 'alibaba1688' ? sanitizeHistoryProduct(body.product) : null,
-    rows,
-  };
-  const payloadJson = JSON.stringify(payload);
-  if (Buffer.byteLength(payloadJson, 'utf8') > MAX_PAYLOAD_BYTES) {
-    return res.status(400).json({ success: false, error: '测算快照过大，无法保存' });
-  }
-
-  try {
-    let selectionPricing = null;
-    const planId = Number.parseInt(body.selectionContext?.planId || body.planId, 10) || 0;
-    const itemId = Number.parseInt(body.selectionContext?.itemId || body.itemId, 10) || 0;
-    if (Boolean(planId) !== Boolean(itemId)) {
-      return res.status(400).json({ success: false, error: '选品定价上下文缺少方案ID或SPU任务ID' });
-    }
-    if (planId && itemId) {
-      // 测算页会展示实时接口中的全部条码；自动上架保存用户保留的任务 SKU 子集。
-      const pricingContext = await getSelectionFissionProfitPricingContext(planId, itemId);
-      const listingSkuCodes = new Set((pricingContext.rows || []).map((row) => (
-        normalizeText(row.skuCode, 160).toUpperCase()
-      )));
-      const listingRows = rows.filter((row) => listingSkuCodes.has(
-        normalizeText(row.skuCode || row.sku || row.barcode, 160).toUpperCase()
-      ));
-      selectionPricing = await saveSelectionFissionProfitPricingTable(
-        planId,
-        itemId,
-        {
-          spuCode,
-          rows: listingRows,
-          note: payload.note,
-          productCodeConfig: body.productCodeConfig,
-        },
-        req.user,
-        { pricingContext }
-      );
-    }
-    let insertId = null;
-    if (!selectionPricing) {
-      await ensureHistoryTable();
-      const inserted = await database.local.insert(HISTORY_TABLE, {
-        user_id: userId,
-        user_name: getRequestUser(req).name || null,
-        spu_code: spuCode,
-        brand: payload.brand || null,
-        note: payload.note || null,
-        row_count: rows.length,
-        payload_json: payloadJson,
-      });
-      insertId = inserted.insertId;
-    }
-    res.json({
-      success: true,
-      data: {
-        id: insertId,
-        spuCode,
-        rowCount: rows.length,
-        selectionPricing: selectionPricing ? {
-          planId: selectionPricing.planId,
-          itemId: selectionPricing.itemId,
-          taskCode: selectionPricing.taskCode,
-          pricingTableSavedAt: selectionPricing.pricingTableSavedAt,
-          pricingTableVersion: selectionPricing.pricingTableVersion,
-          productCodeStatus: selectionPricing.productCodeStatus,
-          productCodeStyleCode: selectionPricing.productCodeStyleCode,
-          productCodeConfig: selectionPricing.productCodeConfig,
-          productCodeCompletedAt: selectionPricing.productCodeCompletedAt,
-          productCodes: (selectionPricing.rows || []).map((row) => ({
-            skuCode: row.skuCode,
-            originalSkuName: row.originalSkuName,
-            selectedSkuName: row.selectedSkuName,
-            internalProductCode: row.internalProductCode,
-            productCodeProductName: row.productCodeProductName,
-          })),
-        } : null,
-      },
-    });
-  } catch (error) {
-    sendError(res, error, '保存测算记录失败');
-  }
-});
-
-// 历史列表（管理员可见全部，普通用户仅本人，不含快照正文）
-router.get('/history', async (req, res) => {
-  const userId = requireUserId(req, res);
-  if (!userId) return;
-  const { isAdmin } = getRequestUser(req);
-
-  const page = Math.max(Number.parseInt(req.query.page, 10) || 1, 1);
-  const pageSize = Math.min(Math.max(Number.parseInt(req.query.pageSize, 10) || 20, 1), 100);
-  const spuCode = normalizeText(req.query.spuCode, 160).toUpperCase();
-  const calculatorType = normalizeText(req.query.calculatorType, 30);
-  const offset = (page - 1) * pageSize;
-
-  try {
-    await ensureHistoryTable();
-    const where = [];
-    const params = [];
-    if (!isAdmin) {
-      where.push('user_id = ?');
-      params.push(userId);
-    }
-    if (spuCode) {
-      where.push('spu_code = ?');
-      params.push(spuCode);
-    }
-    if (calculatorType === 'alibaba1688') {
-      where.push('payload_json LIKE ?');
-      params.push('%"calculatorType":"alibaba1688"%');
-    } else if (calculatorType === 'company') {
-      // 兼容 version 1-3 的公司品历史，它们还没有 calculatorType 字段。
-      where.push('payload_json NOT LIKE ?');
-      params.push('%"calculatorType":"alibaba1688"%');
-    }
-    const whereSql = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
-
-    const [countRows, list] = await Promise.all([
-      database.local.query(`SELECT COUNT(*) AS total FROM ${HISTORY_TABLE} ${whereSql}`, params),
-      database.local.query(
-        `SELECT id, user_id, user_name, spu_code, brand, note, row_count, created_at, updated_at
-         FROM ${HISTORY_TABLE}
-         ${whereSql}
-         ORDER BY id DESC
-         LIMIT ${pageSize} OFFSET ${offset}`,
-        params
-      ),
-    ]);
-
-    res.json({
-      success: true,
-      data: {
-        list: list.map((row) => ({
-          id: row.id,
-          userName: row.user_name || '',
-          spuCode: row.spu_code,
-          brand: row.brand || '',
-          note: row.note || '',
-          rowCount: row.row_count,
-          calculatorType: calculatorType === 'alibaba1688' ? 'alibaba1688' : 'company',
-          createdAt: row.created_at,
-          updatedAt: row.updated_at,
-        })),
-        total: Number(countRows[0]?.total || 0),
-        page,
-        pageSize,
-      },
-    });
-  } catch (error) {
-    sendError(res, error, '查询测算历史失败');
-  }
-});
-
-async function loadOwnHistoryRow(req, res) {
-  const userId = requireUserId(req, res);
-  if (!userId) return null;
-  const { isAdmin } = getRequestUser(req);
-
-  const id = Number.parseInt(req.params.id, 10);
-  if (!Number.isFinite(id) || id <= 0) {
-    res.status(400).json({ success: false, error: '无效的历史记录 ID' });
-    return null;
-  }
-
-  await ensureHistoryTable();
-  // 服务端强制数据边界：管理员可见全部，普通用户的他人记录表现为不存在
-  const rows = isAdmin
-    ? await database.local.query(`SELECT * FROM ${HISTORY_TABLE} WHERE id = ? LIMIT 1`, [id])
-    : await database.local.query(
-        `SELECT * FROM ${HISTORY_TABLE} WHERE id = ? AND user_id = ? LIMIT 1`,
-        [id, userId]
-      );
-  if (rows.length === 0) {
-    res.status(404).json({ success: false, error: '测算记录不存在或已被删除' });
-    return null;
-  }
-  return rows[0];
-}
-
-// 历史详情（仅本人）
-router.get('/history/:id', async (req, res) => {
-  try {
-    const row = await loadOwnHistoryRow(req, res);
-    if (!row) return;
-
-    let payload = null;
-    try {
-      payload = JSON.parse(row.payload_json);
-    } catch {
-      payload = null;
-    }
-
-    res.json({
-      success: true,
-      data: {
-        id: row.id,
-        userName: row.user_name || '',
-        spuCode: row.spu_code,
-        brand: row.brand || '',
-        note: row.note || '',
-        rowCount: row.row_count,
-        createdAt: row.created_at,
-        updatedAt: row.updated_at,
-        payload,
-      },
-    });
-  } catch (error) {
-    sendError(res, error, '查询测算记录失败');
-  }
-});
-
-// 删除历史（本人，或管理员可管理全部）
-router.delete('/history/:id', async (req, res) => {
-  try {
-    const row = await loadOwnHistoryRow(req, res);
-    if (!row) return;
-
-    await database.local.query(
-      `DELETE FROM ${HISTORY_TABLE} WHERE id = ? AND user_id = ?`,
-      [row.id, row.user_id]
-    );
-    res.json({ success: true, data: { id: row.id } });
-  } catch (error) {
-    sendError(res, error, '删除测算记录失败');
-  }
-});
-
-// 导出测算表：按前端给定的列顺序（与页面显示一致）与行数据生成 xlsx 下载
-const MAX_EXPORT_ROWS = 2000;
-const MAX_EXPORT_COLUMNS = 40;
-
-router.post('/export', async (req, res) => {
-  const userId = requireUserId(req, res);
-  if (!userId) return;
-
-  const body = req.body || {};
-  const spuCode = normalizeText(body.spu, 160).toUpperCase() || 'SPU';
-  const columns = Array.isArray(body.columns) ? body.columns : [];
-  const rows = Array.isArray(body.rows) ? body.rows : [];
-
-  const validColumns = columns
-    .filter((col) => col && typeof col === 'object')
-    .slice(0, MAX_EXPORT_COLUMNS)
-    .map((col) => ({
-      key: normalizeText(col.key, 60),
-      label: normalizeText(col.label, 60) || normalizeText(col.key, 60),
-      percent: col.percent === true,
-    }))
-    .filter((col) => col.key);
-
-  if (validColumns.length === 0) {
-    return res.status(400).json({ success: false, error: '缺少导出列配置' });
-  }
-  if (rows.length === 0) {
-    return res.status(400).json({ success: false, error: '导出数据为空' });
-  }
-  if (rows.length > MAX_EXPORT_ROWS) {
-    return res.status(400).json({ success: false, error: `单次最多导出 ${MAX_EXPORT_ROWS} 行` });
-  }
-
-  try {
-    const aoa = [validColumns.map((col) => col.label)];
-    rows.forEach((row) => {
-      aoa.push(validColumns.map((col) => {
-        const value = row && typeof row === 'object' ? row[col.key] : null;
-        return value === null || value === undefined ? '' : value;
-      }));
-    });
-    const sheet = XLSX.utils.aoa_to_sheet(aoa);
-    // 百分比列：保持数值，设置百分比数字格式（0.06 在 Excel 显示为 6.00%）
-    validColumns.forEach((col, colIndex) => {
-      if (!col.percent) return;
-      for (let rowIndex = 1; rowIndex < aoa.length; rowIndex += 1) {
-        const addr = XLSX.utils.encode_cell({ c: colIndex, r: rowIndex });
-        const cell = sheet[addr];
-        if (cell && typeof cell.v === 'number') {
-          cell.z = '0.00%';
-        }
-      }
-    });
-    sheet['!cols'] = validColumns.map((col) => ({ wch: Math.max(12, String(col.label).length * 2 + 6) }));
-    const workbook = XLSX.utils.book_new();
-    XLSX.utils.book_append_sheet(workbook, sheet, '上架测算');
-    const buffer = XLSX.write(workbook, { type: 'buffer', bookType: 'xlsx' });
-
-    const stamp = new Date();
-    const pad = (n) => String(n).padStart(2, '0');
-    const filename = `上架测算_${spuCode}_${stamp.getFullYear()}${pad(stamp.getMonth() + 1)}${pad(stamp.getDate())}-${pad(stamp.getHours())}${pad(stamp.getMinutes())}.xlsx`;
-    res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
-    res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(filename)}`);
-    res.send(buffer);
-  } catch (error) {
-    res.status(500).json({ success: false, error: `导出失败：${error.message}` });
-  }
-});
-
-// ===== 用户个性化默认值（每运营维护自己的配置，无配置时前端用系统默认） =====
-const PREFS_TABLE = 'pricing_calculator_user_prefs';
-let prefsTableReady = null;
-
-async function ensurePrefsTable() {
-  if (!prefsTableReady) {
-    prefsTableReady = (async () => {
-      const existing = await database.local.query(
-        `SELECT 1
-         FROM information_schema.tables
-         WHERE table_schema = DATABASE()
-           AND table_name = ?
-         LIMIT 1`,
-        [PREFS_TABLE]
-      );
-      if (existing.length > 0) {
-        return;
-      }
-      await database.local.query(
-        `CREATE TABLE IF NOT EXISTS ${PREFS_TABLE} (
-          user_id BIGINT PRIMARY KEY COMMENT '用户ID',
-          prefs_json VARCHAR(2000) NOT NULL COMMENT '个性化默认值 JSON',
-          created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
-          updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间'
-        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='上架测算用户个性化默认值'`
-      );
-    })();
-  }
-  try {
-    await prefsTableReady;
-  } catch (error) {
-    prefsTableReady = null;
-    throw error;
-  }
-}
-
-// 允许的偏好字段与取值范围（targetMargin 为小数，0.15 = 15%）
-const PREF_FIELD_RANGES = {
-  coupon: { min: 0, max: 100000 },
-  activityDiscount: { min: 0.01, max: 1 },
-  installFee: { min: 0, max: 100000 },
-  targetMargin: { min: -1, max: 1 },
-};
-
-function sanitizePrefs(input) {
-  const src = input && typeof input === 'object' ? input : {};
-  const prefs = {};
-  Object.entries(PREF_FIELD_RANGES).forEach(([key, range]) => {
-    const num = Number(src[key]);
-    if (Number.isFinite(num)) {
-      prefs[key] = Math.min(range.max, Math.max(range.min, num));
-    }
-  });
-  return prefs;
-}
-
-const PREFS_PROFILE_KEY = '_profiles';
-const PREFS_PROFILES = new Set(['company', 'alibaba1688']);
-
-function normalizePrefsProfile(value) {
-  return PREFS_PROFILES.has(value) ? value : 'company';
-}
-
-function parsePrefsStorage(value) {
-  try {
-    const parsed = typeof value === 'string' ? JSON.parse(value || 'null') : value;
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
-  } catch {
-    return {};
-  }
-}
-
-function readPrefsProfile(storageValue, profile = 'company') {
-  const storage = parsePrefsStorage(storageValue);
-  const normalizedProfile = normalizePrefsProfile(profile);
-  const source = normalizedProfile === 'company'
-    ? storage
-    : storage[PREFS_PROFILE_KEY]?.[normalizedProfile];
-  const prefs = sanitizePrefs(source);
-  return Object.keys(prefs).length > 0 ? prefs : null;
-}
-
-function writePrefsProfile(storageValue, profile, prefs) {
-  const storage = parsePrefsStorage(storageValue);
-  const normalizedProfile = normalizePrefsProfile(profile);
-  if (normalizedProfile === 'company') {
-    return { ...storage, ...prefs };
-  }
-  return {
-    ...storage,
-    [PREFS_PROFILE_KEY]: {
-      ...(storage[PREFS_PROFILE_KEY] && typeof storage[PREFS_PROFILE_KEY] === 'object'
-        ? storage[PREFS_PROFILE_KEY]
-        : {}),
-      [normalizedProfile]: prefs,
-    },
-  };
-}
-
-function createPrefsPatch(profile, prefs) {
-  const normalizedProfile = normalizePrefsProfile(profile);
-  return normalizedProfile === 'company'
-    ? prefs
-    : { [PREFS_PROFILE_KEY]: { [normalizedProfile]: prefs } };
-}
-
-async function persistPrefsProfile(userId, profile, prefs) {
-  const patch = JSON.stringify(createPrefsPatch(profile, prefs));
-  try {
-    // JSON_MERGE_PATCH 在数据库内原子合并，保留另一测算类型的配置，且只需一次网络往返。
-    await database.local.query(
-      `INSERT INTO ${PREFS_TABLE} (user_id, prefs_json) VALUES (?, ?)
-       ON DUPLICATE KEY UPDATE prefs_json = JSON_MERGE_PATCH(
-         IF(JSON_VALID(prefs_json), prefs_json, '{}'),
-         VALUES(prefs_json)
-       )`,
-      [userId, patch]
-    );
-  } catch (error) {
-    const canFallback = ['ER_SP_DOES_NOT_EXIST', 'ER_PARSE_ERROR', 'ER_NOT_SUPPORTED_YET']
-      .includes(error.code);
-    if (!canFallback) throw error;
-
-    // 兼容不支持 JSON_MERGE_PATCH 的旧版 MySQL / MariaDB。
-    const existingRows = await database.local.query(
-      `SELECT prefs_json FROM ${PREFS_TABLE} WHERE user_id = ? LIMIT 1`,
-      [userId]
-    );
-    const storage = writePrefsProfile(existingRows[0]?.prefs_json, profile, prefs);
-    await database.local.query(
-      `INSERT INTO ${PREFS_TABLE} (user_id, prefs_json) VALUES (?, ?)
-       ON DUPLICATE KEY UPDATE prefs_json = VALUES(prefs_json)`,
-      [userId, JSON.stringify(storage)]
-    );
-  }
-}
-
-router.get('/prefs', async (req, res) => {
-  const userId = requireUserId(req, res);
-  if (!userId) return;
-  try {
-    await ensurePrefsTable();
-    const rows = await database.local.query(
-      `SELECT prefs_json FROM ${PREFS_TABLE} WHERE user_id = ? LIMIT 1`,
-      [userId]
-    );
-    const profile = normalizePrefsProfile(req.query.profile);
-    const prefs = rows.length > 0
-      ? readPrefsProfile(rows[0].prefs_json, profile)
-      : null;
-    res.json({ success: true, data: { prefs } });
-  } catch (error) {
-    sendError(res, error, '读取个性化配置失败');
-  }
-});
-
-router.put('/prefs', async (req, res) => {
-  const userId = requireUserId(req, res);
-  if (!userId) return;
-  const prefs = sanitizePrefs(req.body?.prefs ?? req.body);
-  const profile = normalizePrefsProfile(req.body?.profile);
-  if (Object.keys(prefs).length === 0) {
-    return res.status(400).json({ success: false, error: '缺少有效的配置项' });
-  }
-  try {
-    await ensurePrefsTable();
-    await persistPrefsProfile(userId, profile, prefs);
-    res.json({ success: true, data: { prefs } });
-  } catch (error) {
-    sendError(res, error, '保存个性化配置失败');
-  }
-});
-
-module.exports = router;
-module.exports._test = {
-  filterSkuRowsForSelectionContext,
-  createPrefsPatch,
-  getSelectionSkuCodeSet,
-  normalizeCalculatorType,
-  readPrefsProfile,
-  sanitizeHistoryProduct,
-  sanitizePrefs,
-  writePrefsProfile,
-};

backend/src/api/pricingCalculatorExternal.js

@@ -1,73 +0,0 @@
-'use strict';
-
-const crypto = require('crypto');
-const express = require('express');
-const pricingCalculatorRoutes = require('./pricingCalculator');
-const {
-  requireDesktopPageAccess,
-  requireExternalAutomationApiKey,
-} = require('../services/externalAutomationAuth');
-
-const router = express.Router();
-const MAX_OPERATOR_NAME_LENGTH = 100;
-const MAX_SAFE_ID = BigInt(Number.MAX_SAFE_INTEGER);
-
-function normalizeOperatorName(value) {
-  return String(value || '').trim().slice(0, MAX_OPERATOR_NAME_LENGTH);
-}
-
-function decodeOperatorNameHeader(value) {
-  const encoded = String(value || '').trim();
-  if (!encoded || !/^[A-Za-z0-9_-]+$/.test(encoded)) return '';
-  try {
-    return Buffer.from(encoded, 'base64url').toString('utf8');
-  } catch {
-    return '';
-  }
-}
-
-function desktopPricingUserId(operatorName) {
-  const normalized = normalizeOperatorName(operatorName).toLocaleLowerCase('zh-CN');
-  if (!normalized) return null;
-  const digest = crypto.createHash('sha256').update(`desktop-pricing:${normalized}`, 'utf8').digest();
-  const value = (digest.readBigUInt64BE(0) % (MAX_SAFE_ID - 1n)) + 1n;
-  return -Number(value);
-}
-
-function requireDesktopPricingOperator(req, res, next) {
-  if (req.externalApiKey?.authType === 'jwt' && req.user?.name) {
-    return next();
-  }
-
-  const operatorName = normalizeOperatorName(
-    decodeOperatorNameHeader(req.get('x-operator-name-encoded'))
-      || req.get('x-operator-name')
-      || req.query?.operatorName
-      || req.body?.operatorName
-  );
-  if (!operatorName) {
-    return res.status(400).json({ success: false, error: '缺少运营花名' });
-  }
-
-  const userId = desktopPricingUserId(operatorName);
-  req.user = {
-    id: userId,
-    sub: userId,
-    name: operatorName,
-    username: operatorName,
-    role: 'operator',
-    authSource: 'desktop-api-key',
-  };
-  return next();
-}
-
-router.use(
-  requireExternalAutomationApiKey,
-  requireDesktopPageAccess('planning_upload'),
-  requireDesktopPricingOperator,
-  pricingCalculatorRoutes
-);
-
-module.exports = router;
-module.exports.desktopPricingUserId = desktopPricingUserId;
-module.exports.requireDesktopPricingOperator = requireDesktopPricingOperator;

backend/src/api/productAnalysis.js

@@ -9,7 +9,7 @@ const router = express.Router();
 
 const PRODUCT_SNAPSHOT_TABLE = 'op_pdd_sku_dimension_goods_daily';
 const PRODUCT_SPREAD_TABLE = 'pdd_ReportGoodsSpread';
-const USER_PREFS_TABLE = 'pricing_calculator_user_prefs';
+const USER_PREFS_TABLE = 'product_analysis_user_prefs';
 const PRODUCT_SIGNAL_PREFS_KEY = 'productAnalysisSignalThresholds';
 const PRODUCT_META_CACHE_TTL_MS = 5 * 60 * 1000;
 const PRODUCT_SOURCE_CACHE_TTL_MS = Math.max(Number(process.env.PRODUCT_ANALYSIS_SOURCE_CACHE_TTL_MS) || 60 * 1000, 10 * 1000);

backend/src/api/returnInventoryWarning.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const express = require('express');
+const {
+  getReturnInventoryWarningList,
+  buildReturnInventoryWarningExport,
+} = require('../services/returnInventoryWarningService');
+const { sendWorkbookDownload } = require('../services/exportWorkbook');
+
+const router = express.Router();
+
+function sendError(res, error, fallback = '退货库存预警请求失败') {
+  const status = Number(error?.statusCode) || 500;
+  console.error('[ReturnInventoryWarning]', {
+    message: error?.message || fallback,
+    code: error?.code || null,
+    status,
+    stack: error?.stack || null,
+  });
+  res.status(status).json({ success: false, error: error.message || fallback });
+}
+
+// 退货库存预警明细列表（固定过滤仓库：销售退仓 横林二仓）
+router.get('/list', async (req, res) => {
+  try {
+    res.json({ success: true, data: await getReturnInventoryWarningList(req.query || {}) });
+  } catch (error) {
+    sendError(res, error, '加载退货库存预警列表失败');
+  }
+});
+
+/**
+ * 导出退货入库明细（固定过滤仓库：销售退仓 横林二仓）
+ * query: warehouse, date, keyword, format=xlsx|csv
+ * 注意：导出走服务端全量拉取，不受列表分页限制。
+ */
+router.get('/export', async (req, res) => {
+  try {
+    const query = req.query || {};
+    const format = String(query.format || 'xlsx').toLowerCase() === 'csv' ? 'csv' : 'xlsx';
+    const result = await buildReturnInventoryWarningExport(query);
+
+    console.log('[ReturnInventoryWarning][export]', {
+      format,
+      warehouse: result.warehouse,
+      date: result.date,
+      rows: result.totalRows,
+      matchedTotal: result.matchedTotal,
+      truncated: result.truncated,
+    });
+
+    sendWorkbookDownload(res, { fileName: result.fileName, format, sheets: result.sheets });
+  } catch (error) {
+    sendError(res, error, '导出退货入库明细失败');
+  }
+});
+
+module.exports = router;

backend/src/api/returnMonitor.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const express = require('express');
+const {
+  getDashboard,
+  runDailyCompare,
+  backfillHistory,
+  getInStockLinesForCode,
+  resolveDiscrepancy,
+  updateInboundStatus,
+  hasComparedToday,
+  todayInShanghai,
+  buildReturnMonitorExport,
+} = require('../services/returnMonitorService');
+const { sendWorkbookDownload } = require('../services/exportWorkbook');
+
+const router = express.Router();
+
+function sendError(res, error, fallback = '退货入库核销请求失败') {
+  const status = Number(error?.statusCode) || 500;
+  console.error('[ReturnMonitor]', {
+    message: error?.message || fallback,
+    status,
+    stack: error?.stack || null,
+  });
+  res.status(status).json({ success: false, error: error?.message || fallback });
+}
+
+/**
+ * 看板数据（KPI / 库龄分布 / 超期清单 / 按编码汇总 / 差异清单 / 入库明细）
+ * query: date, overdueDays, status, keyword, page, pageSize, refresh=1
+ */
+router.get('/dashboard', async (req, res) => {
+  try {
+    const query = req.query || {};
+    const refresh = String(query.refresh || '') === '1';
+    const bizDate = String(query.date || '').trim() || todayInShanghai();
+    let compare = null;
+
+    // 首次打开或显式刷新时，先跑一轮「同步 + 比对」
+    if (refresh || !(await hasComparedToday(bizDate))) {
+      compare = await runDailyCompare({ date: bizDate, trigger: refresh ? 'manual' : 'api' });
+    }
+
+    const data = await getDashboard(query);
+    res.json({ success: true, data: { ...data, compare } });
+  } catch (error) {
+    sendError(res, error, '加载退货入库核销看板失败');
+  }
+});
+
+/** 手动触发一轮「同步 + 每日比对」；backfillDays 用于补历史（库龄分布/超期清单） */
+router.post('/sync', async (req, res) => {
+  try {
+    const body = req.body || {};
+    const date = String(body.date || '').trim() || todayInShanghai();
+    const lookbackDays = body.lookbackDays === undefined ? 3 : Number(body.lookbackDays) || 0;
+
+    let backfill = null;
+    if (body.backfillDays) {
+      backfill = await backfillHistory({
+        days: Number(body.backfillDays) || 180,
+        toDate: date,
+      });
+    }
+
+    const result = await runDailyCompare({ date, trigger: 'manual', lookbackDays, bootstrapDays: 0 });
+    res.json({ success: true, data: { ...result, backfill } });
+  } catch (error) {
+    sendError(res, error, '同步退货入库数据失败');
+  }
+});
+
+/**
+ * 导出看板数据
+ * query: scope=all|detail|overdue|code|discrepancy|age, format=xlsx|csv,
+ *        date, overdueDays, keyword, status
+ * xlsx 支持多工作表；csv 只能承载一张表（scope=all 时自动降级为 detail）。
+ */
+router.get('/export', async (req, res) => {
+  try {
+    const query = req.query || {};
+    const format = String(query.format || 'xlsx').toLowerCase() === 'csv' ? 'csv' : 'xlsx';
+    const requestedScope = String(query.scope || 'all').trim() || 'all';
+    const scope = format === 'csv' && requestedScope === 'all' ? 'detail' : requestedScope;
+
+    const result = await buildReturnMonitorExport({
+      date: query.date,
+      overdueDays: query.overdueDays,
+      keyword: query.keyword,
+      status: query.status,
+      scope,
+    });
+
+    console.log('[ReturnMonitor][export]', {
+      format,
+      scope: result.scope,
+      date: result.date,
+      counts: result.counts,
+    });
+
+    sendWorkbookDownload(res, { fileName: result.fileName, format, sheets: result.sheets });
+  } catch (error) {
+    sendError(res, error, '导出退货入库核销数据失败');
+  }
+});
+
+/** 某商品编码当前的全部在库入库行（差异清单「手动指定」勾选用） */
+router.get('/code-lines', async (req, res) => {
+  try {
+    const query = req.query || {};
+    res.json({
+      success: true,
+      data: await getInStockLinesForCode({
+        productCode: query.productCode,
+        page: query.page,
+        pageSize: query.pageSize,
+      }),
+    });
+  } catch (error) {
+    sendError(res, error, '加载该商品编码的在库入库行失败');
+  }
+});
+
+/** 处理差异清单：mode=fifo 采纳 FIFO 建议；mode=manual 手动指定行 */
+router.post('/discrepancy/resolve', async (req, res) => {
+  try {
+    const body = req.body || {};
+    const result = await resolveDiscrepancy({
+      productCode: body.productCode,
+      mode: body.mode === 'manual' ? 'manual' : 'fifo',
+      ids: body.ids,
+      outboundDate: body.outboundDate,
+      operator: req.user?.username || req.user?.name || body.operator,
+      remark: body.remark,
+    });
+    const data = await getDashboard({});
+    res.json({ success: true, data: { result, dashboard: data } });
+  } catch (error) {
+    sendError(res, error, '差异核销失败');
+  }
+});
+
+/** 人工标记单行状态（在库 / 已出库 / 已报废） */
+router.post('/inbound/mark', async (req, res) => {
+  try {
+    const body = req.body || {};
+    const result = await updateInboundStatus({
+      id: body.id,
+      status: body.status,
+      outboundDate: body.outboundDate,
+      operator: req.user?.username || req.user?.name || body.operator,
+      remark: body.remark,
+    });
+    res.json({ success: true, data: result });
+  } catch (error) {
+    sendError(res, error, '更新退货入库状态失败');
+  }
+});
+
+module.exports = router;

backend/src/api/returnStockWarning.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const express = require('express');
+const multer = require('multer');
+const {
+  buildExportColumns,
+  getReturnStockWarningExportRows,
+  getReturnStockWarningList,
+  resolveWarehouse,
+  resolveWarehouseKey,
+} = require('../services/returnStockWarningService');
+const {
+  clearStockWarningImport,
+  importStockWarning,
+} = require('../services/returnStockWarningImport');
+const { sendWorkbookDownload } = require('../services/exportWorkbook');
+
+const router = express.Router();
+const upload = multer({
+  storage: multer.memoryStorage(),
+  limits: { fileSize: 20 * 1024 * 1024 },
+});
+
+const resolveScope = (value) => (['imported', 'replica'].includes(String(value)) ? String(value) : 'all');
+
+/**
+ * GET /api/return-stock-warning/list —— 退货库存预警列表（客退数据监控，按仓库出数）
+ * warehouse: 仓库标识 cuiqiao / subei / suining / shandong / henan（缺省 = 崔桥工厂仓）
+ */
+router.get('/list', async (req, res, next) => {
+  try {
+    const payload = await getReturnStockWarningList({
+      warehouse: req.query.warehouse,
+      page: req.query.page,
+      pageSize: req.query.pageSize,
+      keyword: req.query.keyword,
+      supplier: req.query.supplier,
+      sortBy: req.query.sortBy,
+      sortOrder: req.query.sortOrder,
+      qtyBasis: req.query.qtyBasis,
+      createdAtBasis: req.query.createdAtBasis,
+      scope: resolveScope(req.query.scope),
+      focusDays: req.query.focusDays,
+      alertDays: req.query.alertDays,
+      warningLevel: req.query.warningLevel,
+      priceFocusMin: req.query.priceFocusMin,
+      priceHighMin: req.query.priceHighMin,
+      priceLevel: req.query.priceLevel,
+      returnLimitDays: req.query.returnLimitDays,
+      refresh: req.query.refresh,
+    });
+    res.json({ success: true, data: payload });
+  } catch (error) {
+    next(error);
+  }
+});
+
+/** GET /api/return-stock-warning/export —— 服务端全量导出（xlsx / csv） */
+router.get('/export', async (req, res, next) => {
+  try {
+    const format = String(req.query.format || 'xlsx').toLowerCase() === 'csv' ? 'csv' : 'xlsx';
+    const keyword = String(req.query.keyword || '').trim();
+    const warehouse = resolveWarehouse(req.query.warehouse);
+    const rows = await getReturnStockWarningExportRows({
+      warehouse: req.query.warehouse,
+      keyword,
+      supplier: req.query.supplier,
+      qtyBasis: req.query.qtyBasis,
+      createdAtBasis: req.query.createdAtBasis,
+      scope: resolveScope(req.query.scope),
+      focusDays: req.query.focusDays,
+      alertDays: req.query.alertDays,
+      warningLevel: req.query.warningLevel,
+      priceFocusMin: req.query.priceFocusMin,
+      priceHighMin: req.query.priceHighMin,
+      priceLevel: req.query.priceLevel,
+      returnLimitDays: req.query.returnLimitDays,
+      refresh: req.query.refresh,
+    });
+
+    const exportColumns = buildExportColumns(warehouse);
+    sendWorkbookDownload(res, {
+      fileName: `${warehouse.shortName}客退数据监控_${keyword || '全部'}`,
+      format,
+      sheets: [{
+        name: `${warehouse.shortName}客退数据监控`,
+        header: exportColumns.map((column) => column.title),
+        rows: rows.map((row) => exportColumns.map((column) => row[column.key])),
+      }],
+    });
+  } catch (error) {
+    next(error);
+  }
+});
+
+/** POST /api/return-stock-warning/import —— 导入聚水潭「箱及仓位库存」导出文件 */
+router.post('/import', upload.single('file'), async (req, res, next) => {
+  try {
+    if (!req.file || !req.file.buffer) {
+      res.status(400).json({ success: false, message: '请选择要导入的文件（xlsx / xls / csv）' });
+      return;
+    }
+    // multer 按 latin1 解析 multipart 文件名，中文会变成乱码，这里转回 UTF-8
+    const rawName = req.file.originalname || '';
+    const fileName = /[\u00c0-\u00ff]/.test(rawName)
+      ? Buffer.from(rawName, 'latin1').toString('utf8')
+      : rawName;
+
+    const result = await importStockWarning({
+      buffer: req.file.buffer,
+      fileName,
+      importedBy: req.user?.username || req.user?.name || null,
+      // 导入落在哪个仓库下：优先取表单字段，其次 query，最后回落默认仓
+      warehouseKey: resolveWarehouseKey(req.body?.warehouse || req.query.warehouse),
+    });
+    res.json({ success: true, data: result });
+  } catch (error) {
+    next(error);
+  }
+});
+
+/** DELETE /api/return-stock-warning/import —— 清除当前仓库的导入，回到系统推算口径 */
+router.delete('/import', async (req, res, next) => {
+  try {
+    const result = await clearStockWarningImport(resolveWarehouseKey(req.query.warehouse));
+    res.json({ success: true, data: result });
+  } catch (error) {
+    next(error);
+  }
+});
+
+module.exports = router;

backend/src/api/stockSalesAnalysis.js

@@ -0,0 +1,281 @@
+const express = require('express');
+const cloudDb = require('../config/cloudDatabase');
+const { DAILY_INVENTORY_BASELINE } = require('../config/dailyInventoryBaseline');
+const {
+  SALES_GRADE_RULES,
+  SALES_TOTAL_LABEL,
+  STOCK_SALES_WINDOW_OPTIONS,
+  STOCK_SALES_DEFAULT_DAYS,
+} = require('../config/stockSalesAnalysis');
+const { fetchGradeRows, fetchZeroSaleSkuRows } = require('../services/stockSalesAnalysis');
+const { sendWorkbookDownload } = require('../services/exportWorkbook');
+
+const router = express.Router();
+
+/** 库存衡量基准时刻：快照日次日 01:00（报表库每日凌晨跑批，标注 T-1） */
+const AS_OF_TIME = '01:00';
+
+/** 结果缓存：一次要扫订单明细 + 库存明细两张大表，避免连续刷新重复打库 */
+const RESULT_CACHE_TTL_MS = 5 * 60 * 1000;
+const cacheByDays = new Map();
+
+const round2 = (v) => Math.round((Number(v) || 0) * 100) / 100;
+
+/** 快照日 + 次日 01:00 作为统一的统计基准时刻 */
+function nextDayAsOf(bizDate) {
+  if (!bizDate || !/^\d{4}-\d{2}-\d{2}$/.test(bizDate)) return null;
+  const d = new Date(`${bizDate}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + 1);
+  return `${d.toISOString().slice(0, 10)} ${AS_OF_TIME}`;
+}
+
+/** 发货窗口：[asOf - N 天, asOf) */
+function buildShipWindow(asOf, days) {
+  const to = new Date(`${asOf.slice(0, 10)}T${AS_OF_TIME}:00Z`);
+  const from = new Date(to.getTime() - days * 86400000);
+  const fmt = (dt) => dt.toISOString().slice(0, 19).replace('T', ' ');
+  return { shipFrom: fmt(from), shipTo: fmt(to) };
+}
+
+async function fetchLatestBizDate() {
+  const rows = await cloudDb.query(
+    `SELECT MAX(CONVERT(VARCHAR(10), date, 23)) AS d FROM rpt.pm_stockMonitor`
+  );
+  return rows[0]?.d || null;
+}
+
+async function fetchInventoryTakenAt() {
+  const rows = await cloudDb.query(
+    `SELECT MAX(modified) AS takenAt FROM rpt.jst_inventoryInfo`
+  );
+  return rows[0]?.takenAt || null;
+}
+
+/** 解析并收敛统计窗口天数，只允许白名单内的取值 */
+function resolveDays(raw) {
+  const n = Number.parseInt(String(raw ?? ''), 10);
+  return STOCK_SALES_WINDOW_OPTIONS.includes(n) ? n : STOCK_SALES_DEFAULT_DAYS;
+}
+
+/**
+ * GET /api/stock-sales-analysis
+ * 仓库库存动销分析：仓库 × 动销等级 → SKU数量 / SKU占比 / 库存数量 / 库存占比 / 销量
+ */
+router.get('/', async (req, res) => {
+  try {
+    const force = String(req.query?.refresh || '') === '1';
+    const days = resolveDays(req.query?.days);
+    const latestBizDate = await fetchLatestBizDate().catch(() => null);
+
+    const cached = cacheByDays.get(days);
+    if (!force && cached && cached.latestBizDate === latestBizDate
+      && Date.now() - cached.at < RESULT_CACHE_TTL_MS) {
+      return res.json({ success: true, data: cached.payload, cached: true });
+    }
+
+    const asOf = nextDayAsOf(latestBizDate);
+    if (!asOf) {
+      return res.status(503).json({
+        success: false,
+        error: '业务库暂无库存监控数据，无法定位统计基准日',
+      });
+    }
+
+    const { shipFrom, shipTo } = buildShipWindow(asOf, days);
+    const warehouses = DAILY_INVENTORY_BASELINE.filter((b) => b.wmsCoId != null);
+    const wmsCoIds = warehouses.map((b) => b.wmsCoId);
+
+    const [rows, takenAt] = await Promise.all([
+      fetchGradeRows(cloudDb, wmsCoIds, { shipFrom, shipTo, days }),
+      fetchInventoryTakenAt().catch(() => null),
+    ]);
+
+    // (仓库, 等级) → 指标
+    const matrix = new Map();
+    rows.forEach((r) => {
+      matrix.set(`${r.wmsCoId}::${r.gradeKey}`, r);
+    });
+
+    const buildBucket = (grade, cell) => ({
+      key: grade.key,
+      label: grade.label,
+      tip: grade.tip,
+      skuCount: cell?.skuCount ?? 0,
+      stockQty: round2(cell?.stockQty ?? 0),
+      salesQty: round2(cell?.salesQty ?? 0),
+      dailySales: Number((cell?.dailySales ?? 0).toFixed(2)),
+    });
+
+    const items = warehouses.map((base) => {
+      const id = String(base.wmsCoId);
+      const buckets = SALES_GRADE_RULES.map((grade) => (
+        buildBucket(grade, matrix.get(`${id}::${grade.key}`))
+      ));
+
+      const totalSku = buckets.reduce((acc, b) => acc + b.skuCount, 0);
+      const totalStock = buckets.reduce((acc, b) => acc + b.stockQty, 0);
+      const totalSales = round2(buckets.reduce((acc, b) => acc + b.salesQty, 0));
+
+      return {
+        warehouse: base.warehouse,
+        dbWarehouse: base.dbWarehouse,
+        wmsCoId: base.wmsCoId,
+        hasData: totalSku > 0 || totalStock !== 0 || totalSales !== 0,
+        buckets: buckets.map((b) => ({
+          ...b,
+          skuRatio: totalSku > 0 ? b.skuCount / totalSku : null,
+          stockRatio: totalStock !== 0 ? b.stockQty / totalStock : null,
+        })),
+        total: {
+          key: '__total__',
+          label: SALES_TOTAL_LABEL,
+          skuCount: totalSku,
+          skuRatio: totalSku > 0 ? 1 : null,
+          stockQty: totalStock,
+          stockRatio: totalStock !== 0 ? 1 : null,
+          salesQty: totalSales,
+          dailySales: Number((totalSales / days).toFixed(2)),
+        },
+      };
+    });
+
+    // 全仓合计：各等级跨仓累加 + 汇总
+    const grandBuckets = SALES_GRADE_RULES.map((grade) => {
+      const skuCount = items.reduce((acc, it) => acc + (it.buckets.find((b) => b.key === grade.key)?.skuCount || 0), 0);
+      const stockQty = round2(items.reduce((acc, it) => acc + (it.buckets.find((b) => b.key === grade.key)?.stockQty || 0), 0));
+      const salesQty = round2(items.reduce((acc, it) => acc + (it.buckets.find((b) => b.key === grade.key)?.salesQty || 0), 0));
+      return {
+        key: grade.key,
+        label: grade.label,
+        tip: grade.tip,
+        skuCount,
+        stockQty,
+        salesQty,
+        dailySales: Number((salesQty / days).toFixed(2)),
+      };
+    });
+    const grandSku = grandBuckets.reduce((acc, b) => acc + b.skuCount, 0);
+    const grandStock = round2(grandBuckets.reduce((acc, b) => acc + b.stockQty, 0));
+    const grandSales = round2(grandBuckets.reduce((acc, b) => acc + b.salesQty, 0));
+    const grandTotal = {
+      key: '__total__',
+      label: SALES_TOTAL_LABEL,
+      skuCount: grandSku,
+      skuRatio: grandSku > 0 ? 1 : null,
+      stockQty: grandStock,
+      stockRatio: grandStock !== 0 ? 1 : null,
+      salesQty: grandSales,
+      dailySales: Number((grandSales / days).toFixed(2)),
+    };
+
+    const payload = {
+      days,
+      windowOptions: STOCK_SALES_WINDOW_OPTIONS,
+      latestBizDate,
+      asOf,
+      shipWindow: { shipFrom, shipTo, days },
+      takenAt,
+      grades: SALES_GRADE_RULES.map((g) => ({ key: g.key, label: g.label, tip: g.tip })),
+      totalLabel: SALES_TOTAL_LABEL,
+      items,
+      grand: {
+        warehouse: '全部仓库合计',
+        hasData: grandSku > 0,
+        buckets: grandBuckets.map((b) => ({
+          ...b,
+          skuRatio: grandSku > 0 ? b.skuCount / grandSku : null,
+          stockRatio: grandStock !== 0 ? b.stockQty / grandStock : null,
+        })),
+        total: grandTotal,
+      },
+      emptyWarehouseCount: items.filter((it) => !it.hasData).length,
+    };
+
+    cacheByDays.set(days, { latestBizDate, at: Date.now(), payload });
+    return res.json({ success: true, data: payload });
+  } catch (error) {
+    console.error('[stock-sales-analysis] 查询失败:', error.message);
+    return res.status(500).json({
+      success: false,
+      error: '仓库库存动销分析数据查询失败',
+      detail: error.message,
+    });
+  }
+});
+
+/**
+ * GET /api/stock-sales-analysis/zero-sales-export
+ * 导出「销售=0」档的 SKU 级明细。
+ * query: days（统计窗口）、wmsCoId（可选，逗号分隔，不传=全部仓库）、format（xlsx|csv，默认 xlsx）
+ */
+router.get('/zero-sales-export', async (req, res) => {
+  try {
+    const days = resolveDays(req.query?.days);
+    const format = String(req.query?.format || 'xlsx').toLowerCase() === 'csv' ? 'csv' : 'xlsx';
+    const latestBizDate = await fetchLatestBizDate().catch(() => null);
+
+    const asOf = nextDayAsOf(latestBizDate);
+    if (!asOf) {
+      return res.status(503).json({
+        success: false,
+        error: '业务库暂无库存监控数据，无法定位统计基准日',
+      });
+    }
+
+    const { shipFrom, shipTo } = buildShipWindow(asOf, days);
+
+    // 仓库过滤：只允许出现在仓库清单里的 wmsCoId，防止任意拼参
+    const known = new Map(
+      DAILY_INVENTORY_BASELINE.filter((b) => b.wmsCoId != null)
+        .map((b) => [String(b.wmsCoId), b])
+    );
+    const requested = String(req.query?.wmsCoId || '')
+      .split(',')
+      .map((v) => v.trim())
+      .filter((v) => known.has(v));
+    const wmsCoIds = requested.length > 0 ? requested : [...known.keys()];
+
+    const rows = await fetchZeroSaleSkuRows(cloudDb, wmsCoIds, { shipFrom, shipTo, days });
+
+    const sheetRows = rows.map((r) => {
+      const base = known.get(r.wmsCoId);
+      return [
+        base?.warehouse || r.wmsCoId,
+        r.skuId,
+        r.skuName,
+        r.binName,
+        r.stockQty,
+        r.salesQty,
+        days,
+        latestBizDate || '',
+      ];
+    });
+
+    const scopeLabel = requested.length === 1 ? `-${known.get(requested[0]).warehouse}` : '';
+    const fileName = `库存动销分析-销售0明细${scopeLabel}-${(latestBizDate || '').replace(/-/g, '') || '未知日期'}`;
+    const { totalRows } = sendWorkbookDownload(res, {
+      fileName,
+      format,
+      sheets: [{
+        name: '销售=0明细',
+        header: ['仓库', 'SKU编码', 'SKU名称', '系统仓位', '库存数量', `销量(近${days}天)`, '统计天数', '统计基准日'],
+        rows: sheetRows,
+      }],
+    });
+    console.log(`[stock-sales-analysis] 销售=0明细导出: ${totalRows} 行, 仓库 ${wmsCoIds.length} 个, 窗口 ${days} 天`);
+    return null;
+  } catch (error) {
+    console.error('[stock-sales-analysis] 销售=0明细导出失败:', error.message);
+    // 响应可能已部分写出（sendWorkbookDownload 之后一般不会抛），仅在未发送时回 JSON
+    if (!res.headersSent) {
+      return res.status(500).json({
+        success: false,
+        error: '销售=0明细导出失败',
+        detail: error.message,
+      });
+    }
+    return null;
+  }
+});
+
+module.exports = router;

backend/src/api/storeCheckup.js

@@ -1,999 +0,0 @@
-const express = require('express');
-const jianSunDb = require('../config/jianSunDatabase');
-
-const router = express.Router();
-const META_CACHE_TTL_MS = 60 * 1000;
-const OVERVIEW_CACHE_TTL_MS = 60 * 1000;
-const HOME_SUMMARY_CACHE_TTL_MS = 10 * 60 * 1000;
-const HOME_SUMMARY_STALE_TTL_MS = 24 * 60 * 60 * 1000;
-const HOME_COMPENSATION_CACHE_TTL_MS = 10 * 60 * 1000;
-const HOME_COMPENSATION_SAMPLE_SIZE = 10000;
-const metaCache = { value: null, expiresAt: 0, promise: null };
-const overviewCache = new Map();
-const overviewInFlight = new Map();
-const homeSummaryCache = new Map();
-const homeSummaryInFlight = new Map();
-const homeReviewCache = new Map();
-const homeReviewInFlight = new Map();
-const homeCompensationCache = new Map();
-const homeCompensationSummaryCache = new Map();
-const homeCompensationSummaryInFlight = new Map();
-
-const TAB_KEYS = new Set(['overview', 'business', 'after-sales', 'customer-service', 'service-score', 'stars']);
-
-function normalizeDate(value) {
-  const text = String(value || '').trim();
-  return /^\d{4}-\d{2}-\d{2}$/.test(text) ? text : '';
-}
-
-function addDays(value, offset) {
-  const date = new Date(`${value}T00:00:00Z`);
-  date.setUTCDate(date.getUTCDate() + offset);
-  return date.toISOString().slice(0, 10);
-}
-
-function inclusiveDayCount(startDate, endDate) {
-  const start = new Date(`${startDate}T00:00:00Z`);
-  const end = new Date(`${endDate}T00:00:00Z`);
-  return Math.floor((end.getTime() - start.getTime()) / 86400000) + 1;
-}
-
-function toNumber(value) {
-  const number = Number(value);
-  return Number.isFinite(number) ? number : 0;
-}
-
-function normalizeCompensationDate(value) {
-  const text = String(value || '').trim();
-  return /^\d{4}-\d{2}-\d{2}$/.test(text) ? text : '';
-}
-
-function compensationDate(value) {
-  const text = String(value || '').trim();
-  return /^\d{4}-\d{2}-\d{2}/.test(text) ? text.slice(0, 10) : '';
-}
-
-async function loadRecentCompensationRows(shopName = '') {
-  const cacheKey = shopName || '*';
-  const cached = homeCompensationCache.get(cacheKey);
-  if (cached?.rows && cached.expiresAt > Date.now()) return cached.rows;
-  if (cached?.promise) return cached.promise;
-
-  const promise = jianSunDb.query(
-    `SELECT TOP (${HOME_COMPENSATION_SAMPLE_SIZE})
-       id, chargeAmount, chargeReason, chargeTime, couponDetailId,
-       goodsId, goodsName, orderSn, shopName
-     FROM dbo.pdd_abnormal_compensation WITH (NOLOCK)
-     WHERE (@shopName = '' OR shopName = @shopName)
-     ORDER BY id DESC`,
-    { shopName }
-  ).then((rows) => {
-    const normalizedRows = rows
-      .map((row) => ({
-        id: row.id,
-        date: compensationDate(row.chargeTime),
-        amount: toNumber(row.chargeAmount),
-        reason: String(row.chargeReason || '').trim() || '未分类',
-        goodsId: String(row.goodsId || '').trim(),
-        goodsName: String(row.goodsName || '').trim(),
-        orderSn: String(row.orderSn || '').trim(),
-        detailId: String(row.couponDetailId || '').trim(),
-        shopName: String(row.shopName || '').trim(),
-      }))
-      .filter((row) => row.date);
-    homeCompensationCache.set(cacheKey, {
-      rows: normalizedRows,
-      expiresAt: Date.now() + HOME_COMPENSATION_CACHE_TTL_MS,
-      promise: null,
-    });
-    if (homeCompensationCache.size > 12) {
-      const firstKey = homeCompensationCache.keys().next().value;
-      homeCompensationCache.delete(firstKey);
-    }
-    return normalizedRows;
-  }).finally(() => {
-    const entry = homeCompensationCache.get(cacheKey);
-    if (entry?.promise) homeCompensationCache.delete(cacheKey);
-  });
-  homeCompensationCache.set(cacheKey, { rows: null, expiresAt: 0, promise });
-  return promise;
-}
-
-async function resolveCompensationDateRange(req, rows) {
-  const latestAvailableDate = rows.reduce((latest, row) => (row.date > latest ? row.date : latest), '');
-  const endDate = normalizeCompensationDate(req.query.endDate) || latestAvailableDate;
-  const startDate = normalizeCompensationDate(req.query.startDate) || (endDate ? addDays(endDate, -29) : '');
-  if (!startDate || !endDate) {
-    const error = new Error('赔付数据没有可用日期');
-    error.statusCode = 404;
-    throw error;
-  }
-  const dayCount = inclusiveDayCount(startDate, endDate);
-  if (dayCount < 1) {
-    const error = new Error('赔付开始日期不能晚于结束日期');
-    error.statusCode = 400;
-    throw error;
-  }
-  if (dayCount > 90) {
-    const error = new Error('赔付查询日期范围不能超过90天');
-    error.statusCode = 400;
-    throw error;
-  }
-  return { startDate, endDate, dayCount, latestAvailableDate };
-}
-
-function createCompensationGroup(row) {
-  return {
-    amount: 0,
-    recordCount: 0,
-    orderKeys: new Set(),
-    ...row,
-  };
-}
-
-function addCompensationRecord(group, row) {
-  group.amount += row.amount;
-  group.recordCount += 1;
-  group.orderKeys.add(row.orderSn || row.detailId || String(row.id));
-}
-
-function queryHomeCompensationSummary(rows, range) {
-  const selectedRows = rows.filter((row) => row.date >= range.startDate && row.date <= range.endDate);
-  const orderKeys = new Set();
-  const goodsKeys = new Set();
-  const reasonGroups = new Map();
-  const goodsGroups = new Map();
-  let totalAmount = 0;
-
-  selectedRows.forEach((row) => {
-    const orderKey = row.orderSn || row.detailId || String(row.id);
-    orderKeys.add(orderKey);
-    if (row.goodsId) goodsKeys.add(row.goodsId);
-    totalAmount += row.amount;
-
-    const reasonGroup = reasonGroups.get(row.reason) || createCompensationGroup({ reason: row.reason });
-    addCompensationRecord(reasonGroup, row);
-    reasonGroups.set(row.reason, reasonGroup);
-
-    const goodsKey = row.goodsId || `unknown-${row.id}`;
-    const goodsGroup = goodsGroups.get(goodsKey) || createCompensationGroup({
-      goodsId: row.goodsId || '未识别商品ID',
-      goodsName: row.goodsName,
-      shopName: row.shopName,
-    });
-    addCompensationRecord(goodsGroup, row);
-    if (!goodsGroup.goodsName && row.goodsName) goodsGroup.goodsName = row.goodsName;
-    if (!goodsGroup.shopName && row.shopName) goodsGroup.shopName = row.shopName;
-    goodsGroups.set(goodsKey, goodsGroup);
-  });
-
-  const toGroupResult = (group) => ({
-    ...group,
-    orderCount: group.orderKeys.size,
-    amount: Number(group.amount.toFixed(2)),
-    share: totalAmount > 0 ? Number((group.amount * 100 / totalAmount).toFixed(2)) : 0,
-    orderKeys: undefined,
-  });
-  const reasonDistribution = [...reasonGroups.values()]
-    .map(toGroupResult)
-    .sort((left, right) => right.amount - left.amount || right.orderCount - left.orderCount)
-    .slice(0, 6);
-  const highCompensationGoods = [...goodsGroups.values()]
-    .map(toGroupResult)
-    .sort((left, right) => right.amount - left.amount || right.orderCount - left.orderCount)
-    .slice(0, 6);
-
-  return {
-    ...range,
-    sampledRecordCount: rows.length,
-    selectedRecordCount: selectedRows.length,
-    compensationCount: orderKeys.size,
-    recordCount: selectedRows.length,
-    totalAmount: Number(totalAmount.toFixed(2)),
-    averageAmount: orderKeys.size ? Number((totalAmount / orderKeys.size).toFixed(2)) : 0,
-    affectedGoodsCount: goodsKeys.size,
-    reasonDistribution,
-    highCompensationGoods,
-  };
-}
-
-function toNullableNumber(value) {
-  if (value === null || value === undefined || value === '') return null;
-  const number = Number(value);
-  return Number.isFinite(number) ? number : null;
-}
-
-function averageNullable(rows, field) {
-  const values = rows.map((row) => toNullableNumber(row[field])).filter((value) => value !== null);
-  return values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : null;
-}
-
-function cleanShopName(value) {
-  const text = String(value || '').trim();
-  return text || '';
-}
-
-function shopFilterSql() {
-  return '(@shopName IS NULL OR @shopName = \'\' OR shopName = @shopName)';
-}
-
-async function loadMeta() {
-  if (metaCache.value && metaCache.expiresAt > Date.now()) return metaCache.value;
-  if (metaCache.promise) return metaCache.promise;
-
-  metaCache.promise = Promise.all([
-    jianSunDb.query(
-      `SELECT
-         shopName,
-         CONVERT(varchar(10), MIN(TRY_CONVERT(date, statDate)), 23) AS minDate,
-         CONVERT(varchar(10), MAX(TRY_CONVERT(date, statDate)), 23) AS latestDate
-       FROM dbo.pdd_DataNormal
-       WHERE shopName IS NOT NULL AND LTRIM(RTRIM(shopName)) <> ''
-       GROUP BY shopName
-       ORDER BY shopName`
-    ),
-    jianSunDb.query(
-      `SELECT
-         CONVERT(varchar(10), MIN(TRY_CONVERT(date, statDate)), 23) AS minDate,
-         CONVERT(varchar(10), MAX(TRY_CONVERT(date, statDate)), 23) AS latestDate
-       FROM dbo.pdd_DataNormal
-       WHERE statDate IS NOT NULL`
-    ),
-  ]).then(([shopRows, dateRows]) => {
-    const shops = shopRows
-      .map((row) => ({
-        name: cleanShopName(row.shopName),
-        minDate: normalizeDate(row.minDate),
-        latestDate: normalizeDate(row.latestDate),
-      }))
-      .filter((row) => row.name);
-    const globalDate = dateRows[0] || {};
-    const data = {
-      shops,
-      minDate: normalizeDate(globalDate.minDate),
-      latestDate: normalizeDate(globalDate.latestDate),
-    };
-    metaCache.value = data;
-    metaCache.expiresAt = Date.now() + META_CACHE_TTL_MS;
-    return data;
-  }).finally(() => {
-    metaCache.promise = null;
-  });
-
-  return metaCache.promise;
-}
-
-async function resolveContext(req) {
-  const meta = await loadMeta();
-  const shopName = cleanShopName(req.query.shopName);
-  const shop = shopName ? meta.shops.find((item) => item.name === shopName) : null;
-  const requestedDate = normalizeDate(req.query.date);
-  const date = requestedDate || shop?.latestDate || meta.latestDate;
-  return { meta, shopName, date };
-}
-
-async function queryLatestRows({ table, dateColumn, fields, targetDate, shopName }) {
-  const rows = await jianSunDb.query(
-    `WITH ranked AS (
-       SELECT ${fields},
-         ROW_NUMBER() OVER (PARTITION BY shopName ORDER BY id DESC) AS rowNumber
-       FROM dbo.${table}
-       WHERE ${shopFilterSql()}
-         AND [${dateColumn}] = @targetDate
-     )
-     SELECT * FROM ranked WHERE rowNumber = 1`,
-    { targetDate, shopName: shopName || null }
-  );
-  return rows;
-}
-
-async function queryBusinessSnapshot(targetDate, shopName) {
-  const rows = await queryLatestRows({
-    table: 'pdd_DataNormal',
-    dateColumn: 'statDate',
-    targetDate,
-    shopName,
-    fields: '[id], shopName, statDate, cfmOrdrAmt, payOrdrAup, payUvRto',
-  });
-  const sales = rows.reduce((sum, row) => sum + toNumber(row.cfmOrdrAmt), 0);
-  const averageConversion = averageNullable(rows, 'payUvRto');
-  const count = rows.length;
-  return {
-    shopCount: count,
-    sales,
-    averageAov: averageNullable(rows, 'payOrdrAup'),
-    averageConversion: averageConversion === null ? null : averageConversion * 100,
-    rows,
-  };
-}
-
-async function queryAfterSalesSnapshot(targetDate, shopName) {
-  const rows = await queryLatestRows({
-    table: 'pdd_ShopNormalOverflow',
-    dateColumn: 'createTime',
-    targetDate,
-    shopName,
-    fields: '[id], shopName, createTime, executedCount, afterSalesCount, waitSellerHandle, platformHandling, waitBuyerHandle, todosCount, todosEndedCount, cfmOrdrCnt',
-  });
-  const fields = ['executedCount', 'afterSalesCount', 'waitSellerHandle', 'platformHandling', 'waitBuyerHandle', 'todosCount', 'todosEndedCount', 'cfmOrdrCnt'];
-  const data = fields.reduce((result, field) => ({ ...result, [field]: rows.reduce((sum, row) => sum + toNumber(row[field]), 0) }), {});
-  return { ...data, shopCount: rows.length, rows };
-}
-
-async function queryCustomerServiceSnapshot(targetDate, shopName) {
-  const [refundRows, receptionRows] = await Promise.all([
-    queryLatestRows({
-      table: 'pdd_DataCustomerService',
-      dateColumn: 'createTime',
-      targetDate,
-      shopName,
-      fields: '[id], shopName, createTime, dsptRfSucOrdrCnt1m, dsptRfSucRto1m, pltInvlOrdrCnt1m, pltInvlOrdrRto1m, qurfOrdRto1m, avgSucRfProcTime1m, ssslAvgSucRfProcTime1mPct, sucRfOrdrCnt1d, sucRfOrdrAmt1d, rfSucRto1m, avgSlfSucRfProcTime1mMgr, avgSlfSucRfProcTime1mMr',
-    }),
-    jianSunDb.query(
-      `WITH ranked AS (
-         SELECT *, ROW_NUMBER() OVER (PARTITION BY shopName, cs_name ORDER BY id DESC) AS rowNumber
-         FROM dbo.pdd_customer_overflow
-         WHERE ${shopFilterSql()}
-           AND [createTime] = @targetDate
-       )
-       SELECT
-         SUM(ISNULL(consult_user_cnt, 0)) AS consultUserCount,
-         SUM(ISNULL(inquiry_user, 0)) AS inquiryUserCount,
-         SUM(ISNULL(final_group_user, 0)) AS finalGroupUserCount,
-         SUM(ISNULL(cs_sales_amount, 0)) AS csSalesAmount,
-         SUM(ISNULL(need_manu_reply_consult_user_cnt, 0)) AS needManualReplyCount,
-         SUM(ISNULL(receive_user_cnt, 0)) AS receiveUserCount,
-         SUM(ISNULL(delay_reply, 0)) AS delayReplyCount,
-         AVG(TRY_CONVERT(decimal(18, 8), reply_rate_3_min)) AS replyRate3Min,
-         AVG(TRY_CONVERT(decimal(18, 8), reply_30s_rate)) AS replyRate30s,
-         SUM(ISNULL(unsatisfied_serve_score_cnt, 0)) AS unsatisfiedScoreCount,
-         SUM(ISNULL(complain_user_cnt, 0)) AS complainUserCount,
-         AVG(TRY_CONVERT(decimal(18, 8), avg_reply_time)) AS averageReplyTime,
-         SUM(ISNULL(serve_refund_cnt, 0)) AS serviceRefundCount,
-         COUNT(DISTINCT cs_name) AS customerServiceCount
-       FROM ranked
-       WHERE rowNumber = 1 AND cs_name = N'店铺总计'`,
-      { targetDate, shopName: shopName || null }
-    ),
-  ]);
-
-  const refundFields = [
-    'dsptRfSucOrdrCnt1m', 'pltInvlOrdrCnt1m', 'sucRfOrdrCnt1d', 'sucRfOrdrAmt1d',
-  ];
-  const refundTotals = refundFields.reduce((result, field) => ({
-    ...result,
-    [field]: refundRows.reduce((sum, row) => sum + toNumber(row[field]), 0),
-  }), {});
-  const averageFields = [
-    'dsptRfSucRto1m', 'pltInvlOrdrRto1m', 'qurfOrdRto1m', 'avgSucRfProcTime1m',
-    'ssslAvgSucRfProcTime1mPct', 'rfSucRto1m', 'avgSlfSucRfProcTime1mMgr', 'avgSlfSucRfProcTime1mMr',
-  ];
-  const averages = averageFields.reduce((result, field) => ({
-    ...result,
-    [field]: averageNullable(refundRows, field),
-  }), {});
-  return {
-    ...refundTotals,
-    ...averages,
-    shopCount: refundRows.length,
-    reception: receptionRows[0] || {},
-    rows: refundRows,
-  };
-}
-
-async function queryServiceScoreSnapshot(targetDate, shopName) {
-  const rows = await queryLatestRows({
-    table: 'pdd_MallServiceScore',
-    dateColumn: 'createTime',
-    targetDate,
-    shopName,
-    fields: '[id], shopName, createTime, cstmrServScore, attiLmScore, jcfwLmScore, spLmScore, fhLmScore, wlLmScore',
-  });
-  const fields = ['cstmrServScore', 'attiLmScore', 'jcfwLmScore', 'spLmScore', 'fhLmScore', 'wlLmScore'];
-  const values = fields.reduce((result, field) => ({
-    ...result,
-    [field]: averageNullable(rows, field),
-  }), {});
-  return { ...values, shopCount: rows.length, rows };
-}
-
-async function queryStarsSnapshot(targetDate, shopName) {
-  const rows = await queryLatestRows({
-    table: 'pdd_ShopStars',
-    dateColumn: 'createTime',
-    targetDate,
-    shopName,
-    fields: '[id], shopName, createTime, mallStarTomms, mallStarTommsChange, mallStarDesc, ptHelpRate1m, aprsIn3minRplyUsrRto1m, rfSignTime1m, rfProcTime1m, dsr3m, posTypeRto1m, seriousInferiorRto1m, adjNfkAvgCfmSignTime1m, lgstMergeFine1m, gmvRk, ptHelpRate1mNextStarRkDesc, ptHelpRate1mNextPctThreshold, aprsIn3minRplyUsrRto1mNextStarRkDesc, aprsIn3minRplyUsrRto1mNextPctThreshold, rfSignTime1mNextStarRkDesc, rfSignTime1mNextPctThreshold, rfProcTime1mNextStarRkDesc, rfProcTime1mNextPctThreshold, dsr3mNextStarRkDesc, dsr3mNextPctThreshold, posTypeRto1mNextStarRkDesc, posTypeRto1mNextPctThreshold, seriousInferiorRto1mNextStarRkDesc, seriousInferiorRto1mNextPctThreshold, adjNfkAvgCfmSignTime1mNextStarRkDesc, adjNfkAvgCfmSignTime1mNextPctThreshold, lgstMergeFine1mNextStarRkDesc, lgstMergeFine1mNextPctThreshold, gmvRkNextStarRkDesc, gmvRkNextPctThreshold, scoreRk',
-  });
-  const averageFields = ['mallStarTomms', 'mallStarTommsChange', 'ptHelpRate1m', 'aprsIn3minRplyUsrRto1m', 'rfSignTime1m', 'rfProcTime1m', 'dsr3m', 'posTypeRto1m', 'seriousInferiorRto1m', 'adjNfkAvgCfmSignTime1m', 'lgstMergeFine1m', 'gmvRk'];
-  const values = averageFields.reduce((result, field) => ({
-    ...result,
-    [field]: averageNullable(rows, field),
-  }), {});
-  const first = rows[0] || {};
-  const targetFields = [
-    ['ptHelpRate1m', '平台求助率', 'ptHelpRate1mNextStarRkDesc', 'ptHelpRate1mNextPctThreshold'],
-    ['aprsIn3minRplyUsrRto1m', '3分钟人工回复率', 'aprsIn3minRplyUsrRto1mNextStarRkDesc', 'aprsIn3minRplyUsrRto1mNextPctThreshold'],
-    ['rfSignTime1m', '在途订单退款时长', 'rfSignTime1mNextStarRkDesc', 'rfSignTime1mNextPctThreshold'],
-    ['rfProcTime1m', '签收退货后退款时长', 'rfProcTime1mNextStarRkDesc', 'rfProcTime1mNextPctThreshold'],
-    ['dsr3m', '90天用户评价得分', 'dsr3mNextStarRkDesc', 'dsr3mNextPctThreshold'],
-    ['posTypeRto1m', '积极评论率', 'posTypeRto1mNextStarRkDesc', 'posTypeRto1mNextPctThreshold'],
-    ['seriousInferiorRto1m', '严重劣质率', 'seriousInferiorRto1mNextStarRkDesc', 'seriousInferiorRto1mNextPctThreshold'],
-    ['adjNfkAvgCfmSignTime1m', '成团到签收时效', 'adjNfkAvgCfmSignTime1mNextStarRkDesc', 'adjNfkAvgCfmSignTime1mNextPctThreshold'],
-    ['lgstMergeFine1m', '物流综合处罚率', 'lgstMergeFine1mNextStarRkDesc', 'lgstMergeFine1mNextPctThreshold'],
-    ['gmvRk', '店铺活跃度', 'gmvRkNextStarRkDesc', 'gmvRkNextPctThreshold'],
-  ];
-  const targets = shopName ? targetFields.map(([field, label, statusField, thresholdField]) => ({
-    field,
-    label,
-    value: toNullableNumber(first[field]),
-    status: first[statusField] || null,
-    threshold: toNullableNumber(first[thresholdField]),
-  })) : [];
-  const targetFailureCount = rows.reduce((count, row) => count + targetFields.filter(([, , statusField]) => includesFailure(row[statusField])).length, 0);
-  return { ...values, shopCount: rows.length, targets, targetFailureCount, rows };
-}
-
-function includesFailure(value) {
-  const text = String(value || '').trim();
-  return text.includes('不达标') || text.includes('未达标') || text.includes('下降');
-}
-
-function buildIssues({ afterSales, customerService, stars }) {
-  const issues = [];
-  const addIssue = (key, tone, title, value, description, source) => {
-    if (toNumber(value) > 0 || includesFailure(value)) {
-      issues.push({ key, tone, title, value, description, source });
-    }
-  };
-  addIssue('wait-seller-handle', 'error', '待商家处理售后单', afterSales.waitSellerHandle, '需要优先处理，避免售后时效继续积压', '店铺售后');
-  addIssue('platform-handling', 'warning', '平台处理中售后单', afterSales.platformHandling, '平台介入中的售后订单需要关注处理结果', '店铺售后');
-  addIssue('delay-reply', 'warning', '三分钟未回复咨询', customerService.reception.delayReplyCount, '客服响应存在延迟', '客服接待');
-  addIssue('complaint', 'error', '客服投诉数', customerService.reception.complainUserCount, '存在客户投诉，需要回溯客服接待记录', '客服接待');
-  addIssue('star-target', 'warning', '星级指标存在未达标项', stars.targetFailureCount, '可在“星级提升”中查看具体指标和下一星级标准', '店铺星级');
-  return issues;
-}
-
-async function queryOverview(context) {
-  const { shopName, date } = context;
-  const [business, afterSales, customerService, serviceScore, stars] = await Promise.all([
-    queryBusinessSnapshot(date, shopName),
-    queryAfterSalesSnapshot(date, shopName),
-    queryCustomerServiceSnapshot(date, shopName),
-    queryServiceScoreSnapshot(date, shopName),
-    queryStarsSnapshot(date, shopName),
-  ]);
-  const reception = customerService.reception || {};
-  return {
-    date,
-    shopName: shopName || '全部店铺',
-    shopCount: business.shopCount,
-    business: {
-      sales: business.sales,
-      averageAov: business.averageAov,
-      averageConversion: business.averageConversion,
-    },
-    afterSales: {
-      afterSalesCount: afterSales.afterSalesCount,
-      executedCount: afterSales.executedCount,
-      waitSellerHandle: afterSales.waitSellerHandle,
-      platformHandling: afterSales.platformHandling,
-      waitBuyerHandle: afterSales.waitBuyerHandle,
-      todosCount: afterSales.todosCount,
-      todosEndedCount: afterSales.todosEndedCount,
-      cfmOrdrCnt: afterSales.cfmOrdrCnt,
-    },
-    customerService: {
-      ...customerService,
-      reception: {
-        consultUserCount: toNumber(reception.consultUserCount),
-        inquiryUserCount: toNumber(reception.inquiryUserCount),
-        finalGroupUserCount: toNumber(reception.finalGroupUserCount),
-        csSalesAmount: toNumber(reception.csSalesAmount),
-        needManualReplyCount: toNumber(reception.needManualReplyCount),
-        receiveUserCount: toNumber(reception.receiveUserCount),
-        delayReplyCount: toNumber(reception.delayReplyCount),
-        replyRate3Min: toNullableNumber(reception.replyRate3Min),
-        replyRate30s: toNullableNumber(reception.replyRate30s),
-        unsatisfiedScoreCount: toNumber(reception.unsatisfiedScoreCount),
-        complainUserCount: toNumber(reception.complainUserCount),
-        averageReplyTime: toNullableNumber(reception.averageReplyTime),
-        serviceRefundCount: toNumber(reception.serviceRefundCount),
-        customerServiceCount: toNumber(reception.customerServiceCount),
-      },
-    },
-    serviceScore: {
-      cstmrServScore: serviceScore.cstmrServScore,
-      attiLmScore: serviceScore.attiLmScore,
-      jcfwLmScore: serviceScore.jcfwLmScore,
-      spLmScore: serviceScore.spLmScore,
-      fhLmScore: serviceScore.fhLmScore,
-      wlLmScore: serviceScore.wlLmScore,
-    },
-    stars: {
-      mallStarTomms: stars.mallStarTomms,
-      mallStarTommsChange: stars.mallStarTommsChange,
-      dsr3m: stars.dsr3m,
-      ptHelpRate1m: stars.ptHelpRate1m,
-      aprsIn3minRplyUsrRto1m: stars.aprsIn3minRplyUsrRto1m,
-      targets: stars.targets,
-    },
-    issues: buildIssues({ afterSales, customerService, stars }),
-    coverage: {
-      business: business.shopCount > 0,
-      afterSales: afterSales.shopCount > 0,
-      customerService: customerService.shopCount > 0 || Boolean(reception.customerServiceCount),
-      serviceScore: serviceScore.shopCount > 0,
-      stars: stars.shopCount > 0,
-    },
-  };
-}
-
-async function queryHomeSummary(context) {
-  const { shopName, date } = context;
-  const [afterSales, customerService, serviceScore, stars] = await Promise.all([
-    queryAfterSalesSnapshot(date, shopName),
-    queryCustomerServiceSnapshot(date, shopName),
-    queryServiceScoreSnapshot(date, shopName),
-    queryStarsSnapshot(date, shopName),
-  ]);
-  const reception = customerService.reception || {};
-  const riskItems = [
-    {
-      key: 'waitSellerHandle',
-      label: '待商家处理',
-      value: toNumber(afterSales.waitSellerHandle),
-      tone: 'error',
-    },
-    {
-      key: 'delayReplyCount',
-      label: '三分钟未回复',
-      value: toNumber(reception.delayReplyCount),
-      tone: 'warning',
-    },
-    {
-      key: 'complainUserCount',
-      label: '客服投诉',
-      value: toNumber(reception.complainUserCount),
-      tone: 'error',
-    },
-    {
-      key: 'starTargetFailure',
-      label: '星级未达标项',
-      value: toNumber(stars.targetFailureCount),
-      tone: 'warning',
-    },
-  ];
-  const riskSignalCount = riskItems.reduce((sum, item) => sum + item.value, 0);
-  const riskTypeCount = riskItems.filter((item) => item.value > 0).length;
-  const coverageModules = [
-    afterSales.shopCount > 0,
-    customerService.shopCount > 0 || Boolean(reception.customerServiceCount),
-    serviceScore.shopCount > 0,
-    stars.shopCount > 0,
-  ].filter(Boolean).length;
-
-  return {
-    date,
-    shopName: shopName || '全部店铺',
-    shopCount: Math.max(
-      toNumber(afterSales.shopCount),
-      toNumber(customerService.shopCount),
-      toNumber(serviceScore.shopCount),
-      toNumber(stars.shopCount)
-    ),
-    totalShopCount: shopName ? 1 : context.meta.shops.length,
-    coverageModules,
-    totalModules: 4,
-    status: riskSignalCount > 0 ? 'attention' : 'healthy',
-    riskSignalCount,
-    riskTypeCount,
-    averageStar: toNullableNumber(stars.mallStarTomms),
-    starChange: toNullableNumber(stars.mallStarTommsChange),
-    evaluationScore: toNullableNumber(stars.dsr3m),
-    riskItems,
-    serviceScores: [
-      { key: 'cstmrServScore', label: '服务体验', value: toNullableNumber(serviceScore.cstmrServScore) },
-      { key: 'spLmScore', label: '商品服务', value: toNullableNumber(serviceScore.spLmScore) },
-      { key: 'wlLmScore', label: '物流服务', value: toNullableNumber(serviceScore.wlLmScore) },
-      { key: 'fhLmScore', label: '发货服务', value: toNullableNumber(serviceScore.fhLmScore) },
-    ],
-  };
-}
-
-async function resolveReviewDateRange(req) {
-  const shopName = cleanShopName(req.query.shopName);
-  let endDate = normalizeDate(req.query.endDate);
-  if (!endDate) {
-    const rows = await jianSunDb.query(
-      `SELECT TOP (1) LEFT(createTime, 10) AS latestDate
-       FROM dbo.pdd_Evaluation WITH (NOLOCK)
-       WHERE createTime >= '2000-01-01'
-         AND createTime < '2100-01-01'
-         AND descScore BETWEEN 1 AND 5
-         AND (@shopName = '' OR shopName = @shopName)
-       ORDER BY createTime DESC`,
-      { shopName }
-    );
-    endDate = normalizeDate(rows[0]?.latestDate);
-  }
-  const startDate = normalizeDate(req.query.startDate) || (endDate ? addDays(endDate, -29) : '');
-  if (!startDate || !endDate) {
-    const error = new Error('评价数据没有可用日期');
-    error.statusCode = 404;
-    throw error;
-  }
-  const dayCount = inclusiveDayCount(startDate, endDate);
-  if (dayCount < 1) {
-    const error = new Error('评价开始日期不能晚于结束日期');
-    error.statusCode = 400;
-    throw error;
-  }
-  if (dayCount > 90) {
-    const error = new Error('评价查询日期范围不能超过90天');
-    error.statusCode = 400;
-    throw error;
-  }
-  return { startDate, endDate, dayCount, shopName };
-}
-
-async function queryHomeReviewSummary(range) {
-  const params = {
-    startDate: range.startDate,
-    endDateExclusive: addDays(range.endDate, 1),
-    shopName: range.shopName || '',
-  };
-  const [summaryRows, keywordRows] = await Promise.all([
-    jianSunDb.query(
-      `SELECT
-         COUNT_BIG(1) AS totalReviewCount,
-         SUM(CASE WHEN descScore IN (4, 5) THEN 1 ELSE 0 END) AS goodReviewCount,
-         SUM(CASE WHEN descScore IN (1, 2, 3) THEN 1 ELSE 0 END) AS badReviewCount,
-         SUM(CASE WHEN descScore = 1 THEN 1 ELSE 0 END) AS score1Count,
-         SUM(CASE WHEN descScore = 2 THEN 1 ELSE 0 END) AS score2Count,
-         SUM(CASE WHEN descScore = 3 THEN 1 ELSE 0 END) AS score3Count,
-         SUM(CASE WHEN descScore = 4 THEN 1 ELSE 0 END) AS score4Count,
-         SUM(CASE WHEN descScore = 5 THEN 1 ELSE 0 END) AS score5Count,
-         AVG(TRY_CONVERT(decimal(18, 6), descScore)) AS averageScore,
-         COUNT(DISTINCT goodsId) AS reviewedGoodsCount,
-         COUNT(DISTINCT NULLIF(LTRIM(RTRIM(shopName)), '')) AS reviewedShopCount
-       FROM dbo.pdd_Evaluation WITH (NOLOCK)
-       WHERE createTime >= @startDate
-         AND createTime < @endDateExclusive
-         AND descScore BETWEEN 1 AND 5
-         AND (@shopName = '' OR shopName = @shopName)`,
-      params
-    ),
-    jianSunDb.query(
-      `SELECT keywords, COUNT_BIG(1) AS reviewCount
-       FROM dbo.pdd_Evaluation WITH (NOLOCK)
-       WHERE createTime >= @startDate
-         AND createTime < @endDateExclusive
-         AND descScore BETWEEN 1 AND 3
-         AND (@shopName = '' OR shopName = @shopName)
-         AND NULLIF(LTRIM(RTRIM(keywords)), '') IS NOT NULL
-       GROUP BY keywords`,
-      params
-    ),
-  ]);
-  const row = summaryRows[0] || {};
-  const totalReviewCount = toNumber(row.totalReviewCount);
-  const goodReviewCount = toNumber(row.goodReviewCount);
-  const badReviewCount = toNumber(row.badReviewCount);
-  const scoreCounts = [1, 2, 3, 4, 5].map((score) => ({
-    score,
-    count: toNumber(row[`score${score}Count`]),
-  }));
-  const negativeKeywordPattern = /差|不符|异味|瑕疵|破损|低|少发|错发|不好|问题|慢|难/;
-  const badKeywordCounts = new Map();
-  keywordRows.forEach((item) => {
-    const weight = toNumber(item.reviewCount);
-    String(item.keywords || '').split(/[,，]/).forEach((value) => {
-      const keyword = value.trim();
-      if (!keyword || !negativeKeywordPattern.test(keyword)) return;
-      badKeywordCounts.set(keyword, (badKeywordCounts.get(keyword) || 0) + weight);
-    });
-  });
-  const badKeywords = [...badKeywordCounts.entries()]
-    .map(([keyword, count]) => ({ keyword, count }))
-    .sort((left, right) => right.count - left.count || left.keyword.localeCompare(right.keyword, 'zh-CN'))
-    .slice(0, 5);
-
-  return {
-    ...range,
-    totalReviewCount,
-    goodReviewCount,
-    goodReviewRate: totalReviewCount > 0 ? goodReviewCount * 100 / totalReviewCount : 0,
-    badReviewCount,
-    badReviewRate: totalReviewCount > 0 ? badReviewCount * 100 / totalReviewCount : 0,
-    averageScore: toNullableNumber(row.averageScore),
-    reviewedGoodsCount: toNumber(row.reviewedGoodsCount),
-    reviewedShopCount: toNumber(row.reviewedShopCount),
-    distribution: scoreCounts.map((item) => ({
-      ...item,
-      rate: totalReviewCount > 0 ? item.count * 100 / totalReviewCount : 0,
-    })),
-    badKeywords,
-  };
-}
-
-async function queryBusinessTab(context) {
-  const startDate = addDays(context.date, -29);
-  const rows = await jianSunDb.query(
-    `WITH ranked AS (
-       SELECT
-         statDate,
-         shopName, cfmOrdrAmt, payOrdrAup, payUvRto,
-         ROW_NUMBER() OVER (PARTITION BY shopName, statDate ORDER BY id DESC) AS rowNumber
-       FROM dbo.pdd_DataNormal
-       WHERE ${shopFilterSql()}
-         AND statDate BETWEEN @startDate AND @targetDate
-     )
-     SELECT statDate,
-       SUM(TRY_CONVERT(decimal(38, 6), cfmOrdrAmt)) AS sales,
-       AVG(TRY_CONVERT(decimal(38, 6), payOrdrAup)) AS averageAov,
-       AVG(TRY_CONVERT(decimal(38, 8), payUvRto)) AS averageConversion,
-       COUNT(*) AS shopCount
-     FROM ranked
-     WHERE rowNumber = 1
-     GROUP BY statDate
-     ORDER BY statDate`,
-    { startDate, targetDate: context.date, shopName: context.shopName || '' }
-  );
-  return {
-    status: rows.length ? 'ready' : 'empty',
-    metrics: [
-      { key: 'sales', label: '成交额', value: rows.reduce((sum, row) => sum + toNumber(row.sales), 0), unit: 'currency' },
-      { key: 'averageAov', label: '平均支付客单价', value: rows.length ? toNumber(rows.at(-1).averageAov) : null, unit: 'currency' },
-      { key: 'averageConversion', label: '最新支付转化率', value: rows.length ? toNumber(rows.at(-1).averageConversion) * 100 : null, unit: 'percent' },
-    ],
-    trend: rows.map((row) => ({ date: row.statDate, sales: toNumber(row.sales), averageAov: toNumber(row.averageAov), averageConversion: toNumber(row.averageConversion) * 100 })),
-  };
-}
-
-async function queryAfterSalesTab(context) {
-  const rows = await queryLatestRows({
-    table: 'pdd_ShopNormalOverflow',
-    dateColumn: 'createTime',
-    targetDate: context.date,
-    shopName: context.shopName,
-    fields: '[id], shopName, createTime, executedCount, afterSalesCount, waitSellerHandle, platformHandling, waitBuyerHandle, todosCount, todosEndedCount, cfmOrdrCnt',
-  });
-  return {
-    status: rows.length ? 'ready' : 'empty',
-    rows,
-    columns: [
-      { key: 'shopName', title: '店铺' }, { key: 'afterSalesCount', title: '售后总量' }, { key: 'executedCount', title: '已处理' },
-      { key: 'waitSellerHandle', title: '待商家处理' }, { key: 'platformHandling', title: '平台处理中' }, { key: 'waitBuyerHandle', title: '待买家处理' },
-      { key: 'todosCount', title: '工单总量' }, { key: 'todosEndedCount', title: '已完结工单' },
-    ],
-  };
-}
-
-async function queryCustomerServiceTab(context) {
-  const rows = await jianSunDb.query(
-    `WITH ranked AS (
-       SELECT *, ROW_NUMBER() OVER (PARTITION BY shopName, cs_name ORDER BY id DESC) AS rowNumber
-       FROM dbo.pdd_customer_overflow
-       WHERE ${shopFilterSql()}
-         AND [createTime] = @targetDate
-     )
-     SELECT
-       cs_name AS csName,
-       SUM(ISNULL(consult_user_cnt, 0)) AS consultUserCount,
-       SUM(ISNULL(inquiry_user, 0)) AS inquiryUserCount,
-       SUM(ISNULL(final_group_user, 0)) AS finalGroupUserCount,
-       SUM(ISNULL(cs_sales_amount, 0)) AS csSalesAmount,
-       SUM(ISNULL(receive_user_cnt, 0)) AS receiveUserCount,
-       SUM(ISNULL(delay_reply, 0)) AS delayReplyCount,
-       AVG(TRY_CONVERT(decimal(18, 8), reply_rate_3_min)) AS replyRate3Min,
-       AVG(TRY_CONVERT(decimal(18, 8), reply_30s_rate)) AS replyRate30s,
-       SUM(ISNULL(complain_user_cnt, 0)) AS complainUserCount
-     FROM ranked
-     WHERE rowNumber = 1 AND ISNULL(cs_name, '') <> N'店铺总计'
-     GROUP BY cs_name
-     ORDER BY SUM(ISNULL(cs_sales_amount, 0)) DESC`,
-    { targetDate: context.date, shopName: context.shopName || '' }
-  );
-  return {
-    status: rows.length ? 'ready' : 'empty',
-    rows,
-    columns: [
-      { key: 'csName', title: '客服账号' }, { key: 'consultUserCount', title: '咨询人数' }, { key: 'inquiryUserCount', title: '询单人数' },
-      { key: 'finalGroupUserCount', title: '成团人数' }, { key: 'csSalesAmount', title: '客服销售额' }, { key: 'receiveUserCount', title: '人工接待' },
-      { key: 'replyRate30s', title: '30秒应答率' }, { key: 'replyRate3Min', title: '3分钟回复率' }, { key: 'complainUserCount', title: '投诉数' },
-    ],
-  };
-}
-
-async function queryServiceScoreTab(context) {
-  const snapshot = await queryServiceScoreSnapshot(context.date, context.shopName);
-  return {
-    status: snapshot.shopCount ? 'ready' : 'empty',
-    metrics: [
-      { key: 'cstmrServScore', label: '消费者服务体验分', value: snapshot.cstmrServScore, unit: 'score' },
-      { key: 'attiLmScore', label: '服务态度', value: snapshot.attiLmScore, unit: 'score' },
-      { key: 'jcfwLmScore', label: '基础服务', value: snapshot.jcfwLmScore, unit: 'score' },
-      { key: 'spLmScore', label: '商品服务', value: snapshot.spLmScore, unit: 'score' },
-      { key: 'fhLmScore', label: '发货服务', value: snapshot.fhLmScore, unit: 'score' },
-      { key: 'wlLmScore', label: '物流服务', value: snapshot.wlLmScore, unit: 'score' },
-    ],
-    rows: snapshot.rows,
-    columns: [
-      { key: 'shopName', title: '店铺' }, { key: 'cstmrServScore', title: '消费者服务体验分' }, { key: 'attiLmScore', title: '服务态度' },
-      { key: 'jcfwLmScore', title: '基础服务' }, { key: 'spLmScore', title: '商品服务' }, { key: 'fhLmScore', title: '发货服务' }, { key: 'wlLmScore', title: '物流服务' },
-    ],
-  };
-}
-
-async function queryStarsTab(context) {
-  const snapshot = await queryStarsSnapshot(context.date, context.shopName);
-  return {
-    status: snapshot.shopCount ? 'ready' : 'empty',
-    metrics: [
-      { key: 'mallStarTomms', label: '综合体验星级', value: snapshot.mallStarTomms, unit: 'star' },
-      { key: 'mallStarTommsChange', label: '星级变化', value: snapshot.mallStarTommsChange, unit: 'starChange' },
-      { key: 'dsr3m', label: '90天用户评价得分', value: snapshot.dsr3m, unit: 'score' },
-      { key: 'ptHelpRate1m', label: '30天平台求助率', value: snapshot.ptHelpRate1m, unit: 'ratio' },
-      { key: 'aprsIn3minRplyUsrRto1m', label: '30天3分钟人工回复率', value: snapshot.aprsIn3minRplyUsrRto1m, unit: 'ratio' },
-    ],
-    targets: snapshot.targets,
-    rows: snapshot.rows,
-    columns: [
-      { key: 'shopName', title: '店铺' }, { key: 'mallStarTomms', title: '综合体验星级' }, { key: 'mallStarTommsChange', title: '星级变化' },
-      { key: 'dsr3m', title: '90天评价得分' }, { key: 'ptHelpRate1m', title: '平台求助率' }, { key: 'aprsIn3minRplyUsrRto1m', title: '3分钟回复率' },
-    ],
-  };
-}
-
-router.get('/meta', async (_req, res) => {
-  try {
-    res.json({ success: true, data: await loadMeta() });
-  } catch (error) {
-    console.error('[StoreCheckup] 查询元数据失败:', error.message);
-    res.status(500).json({ success: false, error: error.message });
-  }
-});
-
-router.get('/overview', async (req, res) => {
-  try {
-    const context = await resolveContext(req);
-    const cacheKey = `${context.shopName || '*'}:${context.date}`;
-    const cached = overviewCache.get(cacheKey);
-    if (cached && cached.expiresAt > Date.now()) {
-      return res.json({ success: true, data: cached.data });
-    }
-    let pending = overviewInFlight.get(cacheKey);
-    if (!pending) {
-      pending = queryOverview(context)
-        .then((data) => {
-          overviewCache.set(cacheKey, { data, expiresAt: Date.now() + OVERVIEW_CACHE_TTL_MS });
-          return data;
-        })
-        .finally(() => overviewInFlight.delete(cacheKey));
-      overviewInFlight.set(cacheKey, pending);
-    }
-    const data = await pending;
-    res.json({ success: true, data });
-  } catch (error) {
-    console.error('[StoreCheckup] 查询体检概览失败:', error.message);
-    res.status(500).json({ success: false, error: error.message });
-  }
-});
-
-router.get('/home-summary', async (req, res) => {
-  try {
-    const context = await resolveContext(req);
-    const cacheKey = `${context.shopName || '*'}:${context.date}`;
-    const cached = homeSummaryCache.get(cacheKey);
-    if (cached && cached.expiresAt > Date.now()) {
-      return res.json({ success: true, data: cached.data });
-    }
-    const refreshSummary = () => {
-      let pending = homeSummaryInFlight.get(cacheKey);
-      if (pending) return pending;
-      pending = queryHomeSummary(context)
-        .then((data) => {
-          const now = Date.now();
-          homeSummaryCache.set(cacheKey, {
-            data,
-            expiresAt: now + HOME_SUMMARY_CACHE_TTL_MS,
-            staleUntil: now + HOME_SUMMARY_STALE_TTL_MS,
-          });
-          return data;
-        })
-        .finally(() => homeSummaryInFlight.delete(cacheKey));
-      homeSummaryInFlight.set(cacheKey, pending);
-      return pending;
-    };
-    if (cached && cached.staleUntil > Date.now()) {
-      refreshSummary().catch((error) => {
-        console.error('[StoreCheckup] 后台刷新首页摘要失败:', error.message);
-      });
-      return res.json({ success: true, data: { ...cached.data, refreshing: true } });
-    }
-    return res.json({ success: true, data: await refreshSummary() });
-  } catch (error) {
-    console.error('[StoreCheckup] 查询首页摘要失败:', error.message);
-    return res.status(500).json({ success: false, error: error.message });
-  }
-});
-
-router.get('/home-reviews', async (req, res) => {
-  try {
-    const range = await resolveReviewDateRange(req);
-    const cacheKey = `${range.shopName || '*'}:${range.startDate}:${range.endDate}`;
-    const cached = homeReviewCache.get(cacheKey);
-    if (cached && cached.expiresAt > Date.now()) {
-      return res.json({ success: true, data: cached.data });
-    }
-    let pending = homeReviewInFlight.get(cacheKey);
-    if (!pending) {
-      pending = queryHomeReviewSummary(range)
-        .then((data) => {
-          homeReviewCache.set(cacheKey, { data, expiresAt: Date.now() + HOME_SUMMARY_CACHE_TTL_MS });
-          return data;
-        })
-        .finally(() => homeReviewInFlight.delete(cacheKey));
-      homeReviewInFlight.set(cacheKey, pending);
-    }
-    return res.json({ success: true, data: await pending });
-  } catch (error) {
-    console.error('[StoreCheckup] 查询首页评价摘要失败:', error.message);
-    return res.status(error.statusCode || 500).json({ success: false, error: error.message });
-  }
-});
-
-router.get('/home-compensation', async (req, res) => {
-  try {
-    const shopName = cleanShopName(req.query.shopName);
-    const rows = await loadRecentCompensationRows(shopName);
-    const range = { ...(await resolveCompensationDateRange(req, rows)), shopName };
-    const cacheKey = `${shopName || '*'}:${range.startDate}:${range.endDate}`;
-    const cached = homeCompensationSummaryCache.get(cacheKey);
-    if (cached && cached.expiresAt > Date.now()) {
-      return res.json({ success: true, data: cached.data });
-    }
-    let pending = homeCompensationSummaryInFlight.get(cacheKey);
-    if (!pending) {
-      pending = Promise.resolve(queryHomeCompensationSummary(rows, range))
-        .then((data) => {
-          homeCompensationSummaryCache.set(cacheKey, {
-            data,
-            expiresAt: Date.now() + HOME_COMPENSATION_CACHE_TTL_MS,
-          });
-          return data;
-        })
-        .finally(() => homeCompensationSummaryInFlight.delete(cacheKey));
-      homeCompensationSummaryInFlight.set(cacheKey, pending);
-    }
-    return res.json({ success: true, data: await pending });
-  } catch (error) {
-    console.error('[StoreCheckup] 查询首页赔付摘要失败:', error.message);
-    return res.status(error.statusCode || 500).json({ success: false, error: error.message });
-  }
-});
-
-router.get('/tabs/:tabKey', async (req, res) => {
-  try {
-    const tabKey = String(req.params.tabKey || '').trim();
-    if (!TAB_KEYS.has(tabKey) || tabKey === 'overview') {
-      return res.status(400).json({ success: false, error: '不支持的店铺体检模块' });
-    }
-    const context = await resolveContext(req);
-    const handlers = {
-      business: queryBusinessTab,
-      'after-sales': queryAfterSalesTab,
-      'customer-service': queryCustomerServiceTab,
-      'service-score': queryServiceScoreTab,
-      stars: queryStarsTab,
-    };
-    const data = await handlers[tabKey](context);
-    return res.json({ success: true, data: { ...data, date: context.date, shopName: context.shopName || '全部店铺' } });
-  } catch (error) {
-    console.error('[StoreCheckup] 查询体检模块失败:', error.message);
-    return res.status(500).json({ success: false, error: error.message });
-  }
-});
-
-module.exports = router;

backend/src/api/warehouseShipTimeliness.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * 仓储中心 24 小时发货时效 —— HTTP 路由（2026-10-20 新增）
+ * ────────────────────────────────────────────────────────────────────────────
+ * GET /api/warehouse-ship-timeliness/list
+ *   query:
+ *     round  'NOON' | 'AFTERNOON'  手动指定核验轮次；不传按当前时刻自动判定
+ *     limit  明细条数上限（默认 500，最大 2000）
+ *
+ * GET /api/warehouse-ship-timeliness/rounds
+ *   只返回今日两轮的描述（页面顶部提示用，不打订单表，秒回）
+ *
+ * 挂载见 src/index.js：`/api/warehouse-ship-timeliness` + authMiddleware
+ */
+
+const express = require('express');
+const { getShipTimeliness } = require('../services/warehouseShipTimelinessService');
+const { describeRounds, CENTERS } = require('../services/warehouseShipTimelinessRegistry');
+
+const router = express.Router();
+
+function sendError(res, error, fallback) {
+  const status = Number(error?.statusCode) || 500;
+  console.error('[WarehouseShipTimeliness]', {
+    message: error?.message || fallback,
+    code: error?.code || null,
+    status,
+  });
+  res.status(status).json({ success: false, error: error.message || fallback });
+}
+
+// 时效总览：每个主仓「超时未发」数量 + 超时订单明细
+router.get('/list', async (req, res) => {
+  try {
+    const data = await getShipTimeliness(req.query || {});
+    res.json({ success: true, data });
+  } catch (error) {
+    sendError(res, error, '加载仓储中心发货时效失败');
+  }
+});
+
+// 仅轮次信息（不查订单）
+router.get('/rounds', async (_req, res) => {
+  try {
+    res.json({
+      success: true,
+      data: {
+        rounds: describeRounds(new Date()),
+        centers: CENTERS.map((c) => ({
+          key: c.key,
+          name: c.name,
+          placeholder: Boolean(c.placeholder),
+        })),
+      },
+    });
+  } catch (error) {
+    sendError(res, error, '加载核验轮次失败');
+  }
+});
+
+module.exports = router;

backend/src/config/cloudDatabase.js

@@ -19,6 +19,8 @@ const DEFAULT_REPORT_REPLICA_APP_SCHEMA = 'app';
 let pool = null;
 let activeCloudConfig = null;
 let cachedCloudConfigCandidates = null;
+// 负缓存（失败态）的过期时间戳。0 表示没有失败态缓存。
+let cachedCloudConfigExpiresAt = 0;
 
 function isPoolUsable(activePool) {
   return Boolean(activePool && activePool.connected && activePool.healthy !== false);
@@ -30,7 +32,11 @@ const parsePositiveInt = (value, fallback) => {
 };
 
 const DEFAULT_CONNECT_TIMEOUT_MS = parsePositiveInt(process.env.CLOUD_DB_CONNECT_TIMEOUT_MS, 30000);
-const DEFAULT_REQUEST_TIMEOUT_MS = parsePositiveInt(process.env.CLOUD_DB_REQUEST_TIMEOUT_MS, 600000);
+// 原先默认 600000ms（10 分钟），配合 maxAttempts=2 最坏可挂 20 分钟，用户体感就是「卡死」。
+// 收敛到 60s：本页最重的冷查实测 16~42s，仍有充足余量。
+const DEFAULT_REQUEST_TIMEOUT_MS = parsePositiveInt(process.env.CLOUD_DB_REQUEST_TIMEOUT_MS, 60000);
+// 解析「系统库配置」失败时的负缓存存活时间。到期后自动重试，使隧道恢复后无需重启后端。
+const NEGATIVE_CONFIG_CACHE_TTL_MS = parsePositiveInt(process.env.CLOUD_DB_CONFIG_NEGATIVE_TTL_MS, 30000);
 const CLOUD_DB_POOL_MAX = parsePositiveInt(process.env.CLOUD_DB_POOL_MAX, 10);
 const CLOUD_DB_POOL_IDLE_TIMEOUT_MS = parsePositiveInt(process.env.CLOUD_DB_POOL_IDLE_TIMEOUT_MS, 30000);
 const LOCAL_CONFIG_DB_CONNECT_TIMEOUT_MS = parsePositiveInt(process.env.LOCAL_DB_CONNECT_TIMEOUT_MS, 5000);
@@ -536,6 +542,10 @@ function normalizeMssqlConfig(rawConfig, meta = {}) {
         trustServerCertificate: true,
         connectTimeout: DEFAULT_CONNECT_TIMEOUT_MS,
         requestTimeout: DEFAULT_REQUEST_TIMEOUT_MS,
+        // 业务库的 DATETIME 存的是北京时间（无时区标记）。mssql 驱动默认 useUTC=true 会把它
+        // 当成 UTC 解析，而本项目所有时间格式化都是用本地 getter 还原墙上时间，两者叠加会让
+        // 显示值整体 +8 小时（例如库里 16:56:07 被显示成次日 00:56:07）。按本地时间解析才对得上。
+        useUTC: false,
       },
       pool: {
         max: CLOUD_DB_POOL_MAX,
@@ -673,7 +683,15 @@ async function loadCandidateConfig(localPool, profile) {
 }
 
 async function resolveCloudConfigCandidates() {
-  if (cachedCloudConfigCandidates) {
+  // 缓存有效判据：**非 null** 且在有效期内。
+  //
+  // 旧实现是 `if (cachedCloudConfigCandidates)`，而 [] 在 JS 里是 truthy —— 一旦系统库
+  // 读取失败一次（隧道抖动），就会把空数组当作合法缓存永久返回，之后永不重试，
+  // 直接抛「业务数据库尚未配置」500，直到重启后端。这是典型的「永久负缓存」反模式。
+  //
+  // 现在：成功态 expiresAt = Infinity（靠 resetPool 显式失效）；失败态带 30s TTL，
+  // 到期自动重新解析，隧道恢复后无需人工干预即可自愈。
+  if (cachedCloudConfigCandidates !== null && Date.now() < cachedCloudConfigExpiresAt) {
     return cachedCloudConfigCandidates;
   }
 
@@ -705,6 +723,7 @@ async function resolveCloudConfigCandidates() {
     }
 
     cachedCloudConfigCandidates = candidates;
+    cachedCloudConfigExpiresAt = Number.POSITIVE_INFINITY;
     return cachedCloudConfigCandidates;
   } catch (error) {
     console.warn('[CloudDB] 无法从数据库读取配置:', error.message);
@@ -716,15 +735,23 @@ async function resolveCloudConfigCandidates() {
     }
   }
 
-  cachedCloudConfigCandidates = [];
+  // 失败态：按需回退到环境变量配置，并把结果记为「带 TTL 的负缓存」。
+  const fallbacks = [];
   if (hasCompleteEnvConfig(process.env, 'default')) {
     console.log('[CloudDB] 使用环境变量配置（CLOUD_DB_*）');
-    cachedCloudConfigCandidates.push(buildMssqlPoolConfigFromEnv(process.env, 'default'));
+    fallbacks.push(buildMssqlPoolConfigFromEnv(process.env, 'default'));
   }
   if (hasCompleteEnvConfig(process.env, 'public')) {
     console.log('[CloudDB] 使用环境变量配置（CLOUD_DB_PUBLIC_*）');
-    cachedCloudConfigCandidates.push(buildMssqlPoolConfigFromEnv(process.env, 'public'));
+    fallbacks.push(buildMssqlPoolConfigFromEnv(process.env, 'public'));
   }
+
+  cachedCloudConfigCandidates = fallbacks;
+  cachedCloudConfigExpiresAt = Date.now() + NEGATIVE_CONFIG_CACHE_TTL_MS;
+  console.warn(
+    `[CloudDB] 系统库配置暂不可用（${fallbacks.length > 0 ? '暂用环境变量兜底' : '且无环境变量兜底'}），`
+    + `${NEGATIVE_CONFIG_CACHE_TTL_MS}ms 后自动重试`
+  );
   return cachedCloudConfigCandidates;
 }
 
@@ -737,7 +764,20 @@ async function connectWithCandidate(candidate) {
 }
 
 async function queryWithCandidateConnection(candidate, sqlText, params = {}, options = {}) {
-  const nextPool = new sql.ConnectionPool(candidate.mssqlConfig);
+  // request.timeout（请求级）在 mssql 12.x 上实测不生效（始终按池配置的默认值掐断），
+  // 慢查询必须通过「池配置级 requestTimeout」放宽，这里允许调用方覆盖候选连接的池级超时。
+  let mssqlConfig = candidate.mssqlConfig;
+  const poolRequestTimeout = parsePositiveInt(options.connectRequestTimeoutMs, 0);
+  if (poolRequestTimeout > 0) {
+    mssqlConfig = {
+      ...candidate.mssqlConfig,
+      options: {
+        ...candidate.mssqlConfig.options,
+        requestTimeout: poolRequestTimeout,
+      },
+    };
+  }
+  const nextPool = new sql.ConnectionPool(mssqlConfig);
 
   try {
     await nextPool.connect();
@@ -961,10 +1001,21 @@ const getPool = async () => {
   throw lastError || new Error(NOT_CONFIGURED_MESSAGE);
 };
 
+/**
+ * 统一失效「云配置候选」缓存。
+ *
+ * 抽成单点：数组与负缓存 TTL 时间戳必须同时清，只清数组会让陈旧的 expiresAt 残留，
+ * 下次读取时 `Date.now() < expiresAt` 仍可能成立 → 又退化回「负缓存不失效」。
+ */
+function invalidateCloudConfigCache() {
+  cachedCloudConfigCandidates = null;
+  cachedCloudConfigExpiresAt = 0;
+}
+
 const resetPool = async () => {
   if (!pool) {
     activeCloudConfig = null;
-    cachedCloudConfigCandidates = null;
+    invalidateCloudConfigCache();
     return;
   }
 
@@ -975,7 +1026,7 @@ const resetPool = async () => {
   } finally {
     pool = null;
     activeCloudConfig = null;
-    cachedCloudConfigCandidates = null;
+    invalidateCloudConfigCache();
   }
 };
 
@@ -1026,6 +1077,14 @@ const queryWithFreshConnection = async (sqlText, params = {}, options = {}) => {
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
     const candidates = await resolveCloudConfigCandidates();
     if (!Array.isArray(candidates) || candidates.length === 0) {
+      // 候选为空 = 本轮配置解析失败，且没有任何环境变量兜底。
+      //
+      // 这里刻意**不**清缓存：失败态已由 resolveCloudConfigCandidates 写成「带 TTL 的负缓存」。
+      // TTL 内的后续请求快速失败（不必每个请求都去撞系统库的慢超时），到期自动重新解析 ——
+      // 隧道恢复后无需重启后端。旧实现把这次失败永久固化，正是「必须重启后端」的根因。
+      //
+      // 注：getPool() 里的同款分支行为与此保持一致，两条路径统一由 TTL 负责恢复；
+      //     「坏连接池」由 query() 的 catch → resetPool() 负责，各司其职。
       throw new Error(NOT_CONFIGURED_MESSAGE);
     }
 
@@ -1047,11 +1106,36 @@ const queryWithFreshConnection = async (sqlText, params = {}, options = {}) => {
   return [];
 };
 
+/**
+ * 慢查询专用入口：走独立临时连接，池级 requestTimeout 放宽到 SLOW_QUERY_POOL_TIMEOUT_MS。
+ * 背景：mssql 12.x 的 request.timeout（请求级）不生效，超过池默认 60s 的查询必须用
+ * 池配置级 requestTimeout 才能放宽。适用场景：动销分析这类多表大窗口聚合。
+ */
+const SLOW_QUERY_POOL_TIMEOUT_MS = parsePositiveInt(
+  process.env.CLOUD_DB_SLOW_QUERY_TIMEOUT_MS,
+  300000
+);
+
+const querySlow = async (sqlText, params = {}, options = {}) => {
+  const poolRequestTimeout = parsePositiveInt(
+    options.connectRequestTimeoutMs,
+    SLOW_QUERY_POOL_TIMEOUT_MS
+  );
+  return queryWithFreshConnection(sqlText, params, {
+    ...options,
+    connectRequestTimeoutMs: poolRequestTimeout,
+    requestTimeout: poolRequestTimeout,
+  });
+};
+
 /**
  * 测试连接
  */
 const test = async () => {
   try {
+    // 「测试连接」是用户在系统设置里验证配置的入口，必须读最新配置：
+    // 先显式失效，避免 30s 内的失败态负缓存让用户看到「刚改好却连不上」。
+    invalidateCloudConfigCache();
     const candidates = await resolveCloudConfigCandidates();
     if (!Array.isArray(candidates) || candidates.length === 0) {
       return { success: false, message: NOT_CONFIGURED_MESSAGE };
@@ -1080,7 +1164,7 @@ const close = async () => {
   }
   pool = null;
   activeCloudConfig = null;
-  cachedCloudConfigCandidates = null;
+  invalidateCloudConfigCache();
 };
 
 /**
@@ -1094,6 +1178,7 @@ const reload = async () => {
 module.exports = {
   getPool,
   query,
+  querySlow,
   queryWithFreshConnection,
   createPinnedQueryClient,
   test,

backend/src/config/dailyInventoryBaseline.js

@@ -0,0 +1,216 @@
+/**
+ * 每日进销存 —— 仓库清单（纯映射，不含业务数值）
+ *
+ * 重要：本文件只描述「要统计哪些仓库」以及它们与聚水潭 wms_co_id 的对应关系，
+ *       不再硬编码任何业务数值。所有数字都从数据库取：
+ *   - 期初数量：本地快照表 daily_inventory_snapshot 中「上一业务日」的期末结存
+ *   - 期末数量：业务库实时库存 rpt.jst_inventoryInfo（按 wms_co_id 单仓）
+ *   - 周转率 / 四级库存量：近 30 天发货 × 实时库存 × SKU 库龄，见 src/api/dailyInventory.js
+ *   - 12 个流水列：4 列可从业务库单据表还原（采购进仓/采购退货/销售出仓/销售退货，
+ *     见 src/services/dailyInventoryFlows.js）；其余 8 列缺调拨/盘点/加工/其它出入库单据表，
+ *     暂无法显示（前端渲染为「—」）
+ *
+ * 仓库清单随聚水潭仓库档案变化时需同步维护（来源表：rpt.jst_warehouseInfo）。
+ */
+
+/** 一级/二级菜单名 */
+const DAILY_INVENTORY_LEVEL1 = '大货库存监控';
+const DAILY_INVENTORY_LEVEL2 = '每日进销存';
+
+/** 12 个流水列的中文表头与字段映射（顺序与聚水潭进销存导出一致） */
+const FLOW_COLUMNS = [
+    {
+      "label": "加工进仓",
+      "field": "processIn"
+    },
+    {
+      "label": "采购退货",
+      "field": "purchaseReturn"
+    },
+    {
+      "label": "采购进仓",
+      "field": "purchaseIn"
+    },
+    {
+      "label": "其它进仓",
+      "field": "otherIn"
+    },
+    {
+      "label": "其它退货",
+      "field": "otherReturn"
+    },
+    {
+      "label": "销售出仓",
+      "field": "salesOut"
+    },
+    {
+      "label": "盘点",
+      "field": "stocktaking"
+    },
+    {
+      "label": "加工出仓",
+      "field": "processOut"
+    },
+    {
+      "label": "调拨出",
+      "field": "transferOut"
+    },
+    {
+      "label": "销售退货",
+      "field": "salesReturn"
+    },
+    {
+      "label": "调拨入",
+      "field": "transferIn"
+    },
+    {
+      "label": "其它出库",
+      "field": "otherOut"
+    }
+  ];
+
+/** 纳入口径的仓库（warehouse = 聚水潭主仓名，dbWarehouse = 库存监控表仓库名） */
+const DAILY_INVENTORY_BASELINE = [
+    {
+      "warehouse": "简尚-崔桥工厂半成品包装项目仓主仓",
+      "dbWarehouse": "简尚-崔桥工厂半成品包装项目仓",
+      "wmsCoId": 15718196
+    },
+    {
+      "warehouse": "简尚-崔桥工厂仓主仓",
+      "dbWarehouse": "简尚-崔桥工厂仓",
+      "wmsCoId": 15038426
+    },
+    {
+      "warehouse": "简尚-山东青岗集仓主仓",
+      "dbWarehouse": "简尚-山东青岗集仓",
+      "wmsCoId": 15137523
+    },
+    {
+      "warehouse": "简尚-河南洛宁仓主仓",
+      "dbWarehouse": "简尚-河南洛宁仓",
+      "wmsCoId": 15539084
+    },
+    {
+      "warehouse": "简尚-新苏北仓主仓",
+      "dbWarehouse": "简尚-新苏北仓",
+      "wmsCoId": 15038347
+    },
+    {
+      "warehouse": "简尚-横林二仓主仓",
+      "dbWarehouse": "简尚-横林二仓",
+      "wmsCoId": 15033302
+    },
+    {
+      "warehouse": "简尚-横林三仓主仓",
+      "dbWarehouse": "简尚-横林三仓",
+      "wmsCoId": 15043561
+    },
+    {
+      "warehouse": "简尚-山东品牌仓主仓",
+      "dbWarehouse": "简尚-山东品牌仓",
+      "wmsCoId": 15182705
+    },
+    {
+      "warehouse": "简尚-睢宁仓主仓",
+      "dbWarehouse": "简尚-睢宁仓",
+      "wmsCoId": 15032603
+    },
+    {
+      "warehouse": "简尚-分销部专用仓主仓",
+      "dbWarehouse": "简尚-分销部专用仓",
+      "wmsCoId": 15045426
+    },
+    {
+      "warehouse": "简尚-新外贸仓主仓",
+      "dbWarehouse": "简尚-新外贸仓",
+      "wmsCoId": 15045308
+    },
+    {
+      "warehouse": "简尚-分销部睢宁专用仓主仓",
+      "dbWarehouse": "简尚-分销部睢宁专用仓",
+      "wmsCoId": 15051960
+    },
+    {
+      "warehouse": "京仓-山东青岗集京东自营仓主仓",
+      "dbWarehouse": "京仓-山东青岗集京东自营仓",
+      "wmsCoId": 15835935
+    },
+    {
+      "warehouse": "简尚-崔桥工厂品牌仓主仓",
+      "dbWarehouse": "简尚-崔桥工厂品牌仓",
+      "wmsCoId": 15870495
+    },
+    {
+      "warehouse": "简尚-分销部苏北专用仓主仓",
+      "dbWarehouse": "简尚-分销部苏北专用仓",
+      "wmsCoId": 15045325
+    },
+    {
+      "warehouse": "简尚-运营C横林二仓专用仓主仓",
+      "dbWarehouse": "简尚-运营C横林二仓专用仓",
+      "wmsCoId": 15301814
+    },
+    {
+      "warehouse": "简尚-济南外贸仓主仓",
+      "dbWarehouse": "简尚-济南外贸仓",
+      "wmsCoId": 15051888
+    },
+    {
+      "warehouse": "简尚-分销部崔桥专用仓主仓",
+      "dbWarehouse": "简尚-分销部崔桥专用仓",
+      "wmsCoId": 15404402
+    },
+    {
+      "warehouse": "简尚-运营C崔桥工厂仓专用仓主仓",
+      "dbWarehouse": "简尚-运营C崔桥工厂仓专用仓",
+      "wmsCoId": 15301815
+    },
+    {
+      "warehouse": "简尚-运营D苏北专用仓主仓",
+      "dbWarehouse": "简尚-运营D苏北专用仓",
+      "wmsCoId": 15406876
+    },
+    {
+      "warehouse": "简尚-运营C睢宁专用仓主仓",
+      "dbWarehouse": "简尚-运营C睢宁专用仓",
+      "wmsCoId": 15301813
+    },
+    {
+      "warehouse": "简尚-运营C新苏北专用仓主仓",
+      "dbWarehouse": "简尚-运营C新苏北专用仓",
+      "wmsCoId": 15301812
+    },
+    {
+      "warehouse": "简尚-运营D睢宁专用仓主仓",
+      "dbWarehouse": "简尚-运营D睢宁专用仓",
+      "wmsCoId": 15051907
+    },
+    {
+      "warehouse": "简尚-山东青岗集京东仓主仓",
+      "dbWarehouse": "简尚-山东青岗集京东仓",
+      "wmsCoId": 15406664
+    },
+    {
+      "warehouse": "简尚-运营D专用仓库主仓",
+      "dbWarehouse": "简尚-运营D专用仓库",
+      "wmsCoId": 15051915
+    },
+    {
+      "warehouse": "简尚-崔桥工厂京东仓主仓",
+      "dbWarehouse": "简尚-崔桥工厂京东仓",
+      "wmsCoId": 15045345
+    },
+    {
+      "warehouse": "京仓-横林二仓京东自营仓主仓",
+      "dbWarehouse": "京仓-横林二仓京东自营仓",
+      "wmsCoId": 15835893
+    }
+  ];
+
+module.exports = {
+  DAILY_INVENTORY_LEVEL1,
+  DAILY_INVENTORY_LEVEL2,
+  FLOW_COLUMNS,
+  DAILY_INVENTORY_BASELINE,
+};

backend/src/config/dailyInventoryOfficialDb.js

@@ -0,0 +1,184 @@
+/**
+ * 每日进销存 —— 聚水潭「官方进销存导出」校正数据
+ *
+ * 背景：业务库（MSSQL / JSReportReplica）只能还原 4/12 个流水列，且口径与
+ *       聚水潭进销存报表不一致（采购按单据日期 vs 实际入库、销售出仓按订单发货 vs 出库单等），
+ *       其余 8 个流水列（调拨/盘点/加工/其它出入库）业务库根本没有对应单据表。
+ *       因此「每日进销存」以聚水潭官方导出的进销存报表为准：
+ *         官方有值 → 直接采用（source = official）
+ *         官方无值 → 回退业务库自动推算（source = derived）
+ *
+ * 存储：本地 MySQL 表 daily_inventory_official，主键 (biz_date, warehouse)。
+ */
+const { getPool } = require('./dailyInventorySnapshotDb');
+
+const TABLE = 'daily_inventory_official';
+
+/** 流水列 field（与 dailyInventoryBaseline.FLOW_COLUMNS 一致）→ 数据库列名 */
+const FLOW_DB_COLUMNS = {
+  processIn: 'process_in',
+  purchaseReturn: 'purchase_return',
+  purchaseIn: 'purchase_in',
+  otherIn: 'other_in',
+  otherReturn: 'other_return',
+  salesOut: 'sales_out',
+  stocktaking: 'stocktaking',
+  processOut: 'process_out',
+  transferOut: 'transfer_out',
+  salesReturn: 'sales_return',
+  transferIn: 'transfer_in',
+  otherOut: 'other_out',
+};
+
+const CREATE_SQL = `
+CREATE TABLE IF NOT EXISTS ${TABLE} (
+  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
+  biz_date        DATE          NOT NULL COMMENT '业务日期',
+  wms_co_id       BIGINT        NULL     COMMENT '聚水潭仓库 ID（未知仓为空）',
+  warehouse       VARCHAR(128)  NOT NULL COMMENT '仓库名（聚水潭主仓）',
+  opening_qty     DECIMAL(18,2) NULL     COMMENT '期初数量',
+  closing_qty     DECIMAL(18,2) NULL     COMMENT '期末数量',
+  process_in      DECIMAL(18,2) NULL COMMENT '加工进仓',
+  purchase_return DECIMAL(18,2) NULL COMMENT '采购退货',
+  purchase_in     DECIMAL(18,2) NULL COMMENT '采购进仓',
+  other_in        DECIMAL(18,2) NULL COMMENT '其它进仓',
+  other_return    DECIMAL(18,2) NULL COMMENT '其它退货',
+  sales_out       DECIMAL(18,2) NULL COMMENT '销售出仓',
+  stocktaking     DECIMAL(18,2) NULL COMMENT '盘点',
+  process_out     DECIMAL(18,2) NULL COMMENT '加工出仓',
+  transfer_out    DECIMAL(18,2) NULL COMMENT '调拨出',
+  sales_return    DECIMAL(18,2) NULL COMMENT '销售退货',
+  transfer_in     DECIMAL(18,2) NULL COMMENT '调拨入',
+  other_out       DECIMAL(18,2) NULL COMMENT '其它出库',
+  source          VARCHAR(32)   NOT NULL DEFAULT 'jst-export' COMMENT '数据来源',
+  created_at      DATETIME      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at      DATETIME      NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_date_wh (biz_date, warehouse),
+  KEY idx_date (biz_date)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='每日进销存-聚水潭官方进销存校正数据';`;
+
+async function ensureTable() {
+  await getPool().query(CREATE_SQL);
+}
+
+const num = (v) => {
+  if (v == null || v === '') return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+/**
+ * 写入某业务日的官方进销存（幂等，重复导入覆盖）
+ * @param {string} bizDate
+ * @param {Array<{warehouse:string, wmsCoId?:number|null, openingQty?:number|null, closingQty?:number|null, flows?:Object}>} rows
+ * @param {string} source
+ */
+async function upsertOfficial(bizDate, rows, source = 'jst-export') {
+  if (!bizDate || !rows.length) return 0;
+  await ensureTable();
+  const conn = await getPool().getConnection();
+  try {
+    for (const r of rows) {
+      const flows = r.flows || {};
+      await conn.query(
+        `INSERT INTO ${TABLE}
+           (biz_date, wms_co_id, warehouse, opening_qty, closing_qty,
+            process_in, purchase_return, purchase_in, other_in, other_return,
+            sales_out, stocktaking, process_out, transfer_out, sales_return, transfer_in, other_out, source)
+         VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+         ON DUPLICATE KEY UPDATE
+           wms_co_id = VALUES(wms_co_id),
+           opening_qty = VALUES(opening_qty), closing_qty = VALUES(closing_qty),
+           process_in = VALUES(process_in), purchase_return = VALUES(purchase_return),
+           purchase_in = VALUES(purchase_in), other_in = VALUES(other_in),
+           other_return = VALUES(other_return), sales_out = VALUES(sales_out),
+           stocktaking = VALUES(stocktaking), process_out = VALUES(process_out),
+           transfer_out = VALUES(transfer_out), sales_return = VALUES(sales_return),
+           transfer_in = VALUES(transfer_in), other_out = VALUES(other_out),
+           source = VALUES(source)`,
+        [
+          bizDate,
+          r.wmsCoId ?? null,
+          r.warehouse,
+          num(r.openingQty),
+          num(r.closingQty),
+          num(flows.processIn), num(flows.purchaseReturn), num(flows.purchaseIn),
+          num(flows.otherIn), num(flows.otherReturn), num(flows.salesOut),
+          num(flows.stocktaking), num(flows.processOut), num(flows.transferOut),
+          num(flows.salesReturn), num(flows.transferIn), num(flows.otherOut),
+          source,
+        ]
+      );
+    }
+    return rows.length;
+  } finally {
+    conn.release();
+  }
+}
+
+/** 删除某业务日的官方数据（重新导入前清理） */
+async function deleteOfficial(bizDate) {
+  if (!bizDate) return 0;
+  await ensureTable();
+  const [res] = await getPool().query(`DELETE FROM ${TABLE} WHERE biz_date = ?`, [bizDate]);
+  return res.affectedRows || 0;
+}
+
+/** 读取某业务日的官方进销存：key = 仓库名 */
+async function fetchOfficial(bizDate) {
+  const map = new Map();
+  if (!bizDate) return map;
+  try {
+    await ensureTable();
+    const cols = Object.values(FLOW_DB_COLUMNS).map((c) => `o.${c} AS ${c}`).join(', ');
+    const [rows] = await getPool().query(
+      `SELECT o.wms_co_id AS wmsCoId, o.warehouse AS warehouse,
+              o.opening_qty AS openingQty, o.closing_qty AS closingQty, o.source AS source,
+              ${cols}
+         FROM ${TABLE} o WHERE o.biz_date = ?`,
+      [bizDate]
+    );
+    const dbToField = Object.fromEntries(Object.entries(FLOW_DB_COLUMNS).map(([f, c]) => [c, f]));
+    rows.forEach((r) => {
+      const flows = {};
+      for (const [col, field] of Object.entries(dbToField)) flows[field] = num(r[col]);
+      map.set(String(r.warehouse), {
+        warehouse: r.warehouse,
+        wmsCoId: r.wmsCoId == null ? null : Number(r.wmsCoId),
+        openingQty: num(r.openingQty),
+        closingQty: num(r.closingQty),
+        source: r.source,
+        flows,
+      });
+    });
+  } catch (error) {
+    console.error('[daily-inventory-official] 读取官方数据失败:', error.message);
+  }
+  return map;
+}
+
+/** 已有官方数据的业务日（倒序） */
+async function listOfficialDates(limit = 30) {
+  try {
+    await ensureTable();
+    const [rows] = await getPool().query(
+      `SELECT DISTINCT biz_date AS d FROM ${TABLE} ORDER BY biz_date DESC LIMIT ?`,
+      [Number(limit) || 30]
+    );
+    return rows.map((r) => (typeof r.d === 'string' ? r.d.slice(0, 10) : String(r.d).slice(0, 10)));
+  } catch (error) {
+    console.error('[daily-inventory-official] 读取官方日期失败:', error.message);
+    return [];
+  }
+}
+
+module.exports = {
+  TABLE,
+  CREATE_SQL,
+  FLOW_DB_COLUMNS,
+  ensureTable,
+  upsertOfficial,
+  deleteOfficial,
+  fetchOfficial,
+  listOfficialDates,
+};

backend/src/config/dailyInventorySnapshotDb.js

@@ -0,0 +1,137 @@
+/**
+ * 每日进销存 —— 本地库存快照库访问
+ *
+ * 背景：业务库（MSSQL / JSReportReplica）只有「当前」实时库存 jst_inventoryInfo，
+ *       没有按天的历史库存结存表，因此「期初数量」无法回溯。
+ *       解决办法：项目本地 MySQL 每天落一份按仓库存的快照，
+ *       今日期初 = 上一业务日快照，期末 = 实时库存。
+ *
+ * 连接复用 LOCAL_DB_* 配置（与项目其它本地表同库）。
+ */
+const path = require('path');
+const dotenv = require('dotenv');
+const mysql = require('mysql2/promise');
+
+dotenv.config();
+dotenv.config({ path: path.resolve(__dirname, '../../.env') });
+
+const TABLE = 'daily_inventory_snapshot';
+
+const CREATE_SQL = `
+CREATE TABLE IF NOT EXISTS ${TABLE} (
+  id           BIGINT AUTO_INCREMENT PRIMARY KEY,
+  biz_date     DATE          NOT NULL COMMENT '业务日期（T-1）',
+  wms_co_id    BIGINT        NOT NULL COMMENT '聚水潭仓库 ID',
+  warehouse    VARCHAR(128)  NOT NULL COMMENT '仓库名（主仓）',
+  db_warehouse VARCHAR(128)  NULL     COMMENT '监控表仓库名',
+  closing_qty  DECIMAL(18,2) NOT NULL DEFAULT 0 COMMENT '该业务日期末数量',
+  sku_count    INT           NOT NULL DEFAULT 0 COMMENT '有库存 SKU 数',
+  taken_at     DATETIME      NULL     COMMENT '源库库存数据更新时间',
+  created_at   DATETIME      NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at   DATETIME      NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_date_wh (biz_date, wms_co_id),
+  KEY idx_date (biz_date)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='每日进销存-按仓库存快照';`;
+
+let pool = null;
+
+function getPool() {
+  if (pool) return pool;
+  pool = mysql.createPool({
+    host: process.env.LOCAL_DB_HOST,
+    port: Number(process.env.LOCAL_DB_PORT || 3306),
+    user: process.env.LOCAL_DB_USER,
+    password: process.env.LOCAL_DB_PASSWORD,
+    database: process.env.LOCAL_DB_NAME,
+    waitForConnections: true,
+    connectionLimit: 5,
+    connectTimeout: 10000,
+    // DATE/DATETIME 直接返回字符串，避免 JS Date 按本地时区回读时整体偏移一天
+    dateStrings: true,
+  });
+  return pool;
+}
+
+async function ensureTable() {
+  await getPool().query(CREATE_SQL);
+}
+
+/**
+ * 写入某业务日的期末快照（幂等，重复执行覆盖）
+ * @param {string} bizDate YYYY-MM-DD
+ * @param {Array<{wmsCoId:number, warehouse:string, dbWarehouse?:string, closingQty:number, skuCount:number, takenAt?:Date|null}>} rows
+ */
+async function upsertSnapshot(bizDate, rows) {
+  if (!bizDate || !rows.length) return 0;
+  await ensureTable();
+  const conn = await getPool().getConnection();
+  try {
+    for (const r of rows) {
+      await conn.query(
+        `INSERT INTO ${TABLE} (biz_date, wms_co_id, warehouse, db_warehouse, closing_qty, sku_count, taken_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON DUPLICATE KEY UPDATE warehouse = VALUES(warehouse), db_warehouse = VALUES(db_warehouse),
+           closing_qty = VALUES(closing_qty), sku_count = VALUES(sku_count), taken_at = VALUES(taken_at)`,
+        [bizDate, r.wmsCoId, r.warehouse, r.dbWarehouse || null, r.closingQty, r.skuCount, r.takenAt || null]
+      );
+    }
+    return rows.length;
+  } finally {
+    conn.release();
+  }
+}
+
+/**
+ * 读取某业务日的期末快照
+ * @returns {Promise<Map<string, {closingQty:number, skuCount:number, takenAt:Date|null}>>} key = wmsCoId 字符串
+ */
+async function fetchSnapshot(bizDate) {
+  const map = new Map();
+  if (!bizDate) return map;
+  try {
+    await ensureTable();
+    const [rows] = await getPool().query(
+      `SELECT wms_co_id AS wmsCoId, closing_qty AS closingQty, sku_count AS skuCount, taken_at AS takenAt
+         FROM ${TABLE} WHERE biz_date = ?`,
+      [bizDate]
+    );
+    rows.forEach((r) => map.set(String(r.wmsCoId), {
+      closingQty: Number(r.closingQty),
+      skuCount: Number(r.skuCount),
+      takenAt: r.takenAt || null,
+    }));
+  } catch (error) {
+    console.error('[daily-inventory-snapshot] 读取快照失败:', error.message);
+  }
+  return map;
+}
+
+/** 已有快照的业务日（倒序，最多 n 条） */
+async function listSnapshotDates(limit = 10) {
+  try {
+    await ensureTable();
+    const [rows] = await getPool().query(
+      `SELECT DISTINCT biz_date AS d FROM ${TABLE} ORDER BY biz_date DESC LIMIT ?`,
+      [Number(limit) || 10]
+    );
+    return rows.map((r) => {
+      if (typeof r.d === 'string') return r.d.slice(0, 10);
+      const v = new Date(r.d);
+      const pad = (n) => String(n).padStart(2, '0');
+      return `${v.getFullYear()}-${pad(v.getMonth() + 1)}-${pad(v.getDate())}`;
+    });
+  } catch (error) {
+    console.error('[daily-inventory-snapshot] 读取快照日期失败:', error.message);
+    return [];
+  }
+}
+
+module.exports = {
+  TABLE,
+  CREATE_SQL,
+  getPool,
+  ensureTable,
+  upsertSnapshot,
+  fetchSnapshot,
+  listSnapshotDates,
+};

backend/src/config/pickingBinSalesAnalysis.js

@@ -0,0 +1,78 @@
+/**
+ * 拣选库位动销分析 —— 口径配置（纯规则，不含业务数值）
+ *
+ * 一级菜单：大货库存监控
+ * 二级菜单：拣选库位动销分析
+ *
+ * 表头（需求表原列为 所在仓库 | 仓位 | 数量 | 类型 | 动销等级，这里做了扩充与优化）：
+ *   仓库 | 仓位 | 类型 | 商品编码 | 库存数量 | 近N天销量 | 日销 | 动销等级
+ *
+ * 粒度：仓位 × 商品编码（一个仓位有 N 个商品就输出 N 行），列表与导出共用。
+ *
+ * 口径：
+ *   库存数量：rpt.jst_packInventoryInfo 按 wms_co_id + 仓位 + sku_id 汇总 qty
+ *   统计范围：只统计真实拣选仓位（pack_type=Bin 且 bin_group 为空）；
+ *             箱记录（pack_type=Pack）与存货位（bin_group=存货）不纳入
+ *   销量：    4 个来源分支，均按 send_date 窗口（详见 services/pickingBinSalesAnalysis.js）：
+ *             ① jst_Orders 普通行；② jst_Orders 组合装行 → jst_comboProductItem 展开为子件；
+ *             ③ jst_qmcust_orderlist（全民客户 B2B 分销）普通行（排除拆单父单 Split）；
+ *             ④ qmcust 组合装行 → 同样展开。
+ *   日销：    商品窗口销量 / 窗口天数（整档，不按仓位分摊）
+ *   等级：    严格按商品日销判定，同一商品占多少个仓位都是同一等级
+ *
+ * 【为什么不分摊来定等级】同一 SKU 常常同时占用多个同类型仓位（崔桥工厂仓实测 3290 个
+ * 拣选 SKU 中 1431 个跨多个拣选位，最多 24 个）。若把销量摊到仓位再定等级，
+ * 一件爆款商品放在 10 个仓位就会被算成日销 1/10 的滞销品 —— 判断的是「摆法」而不是「商品」。
+ * 因此等级一律以商品自身的销售速度为准。
+ *
+ * 【分摊销量列】导出仍附带「分摊销量」= 商品销量 ÷ 其占用的同类型仓位数，
+ * 供需要按行求和的场景使用：恒等式（已实测校验，差异 0）
+ *   全部行分摊销量之和 = 有库位记录的那些 SKU 的销量之和。
+ * 注意它小于「全仓销量」：jst_packInventoryInfo 只覆盖部分 SKU 的仓位数据，
+ * 没有仓位记录的 SKU 的销量不会体现在任何库位上。
+ */
+
+const PICKING_BIN_LEVEL1 = '大货库存监控';
+const PICKING_BIN_LEVEL2 = '拣选库位动销分析';
+
+/** 可选的统计窗口天数；默认 30 天（需求指定按近 30 天销量划分动销等级） */
+const PICKING_BIN_WINDOW_OPTIONS = [7, 15, 30, 60];
+const PICKING_BIN_DEFAULT_DAYS = 30;
+
+/**
+ * 仓位类型：本功能只统计真实拣选仓位（pack_type=Bin 且 bin_group 为空）。
+ * 箱记录（pack_type=Pack）和存货位（bin_group=存货）不纳入动销等级统计，
+ * 取数在仓位库存表上直接过滤，
+ * 页面也不再提供类型切换。
+ */
+const BIN_TYPE_PICKING = '拣选';
+/** 固定统计范围：仅拣选位（保持数组形式，便于接口字段与后续扩展） */
+const PICKING_BIN_BIN_TYPES = [BIN_TYPE_PICKING];
+
+/**
+ * 动销等级（顺序即展示顺序）。判定依据为「商品日销」= 商品窗口整档销量 ÷ 天数，
+ * 不做仓位分摊，同一商品在所有仓位显示同一等级。
+ * lower 为日销下界（含），upper 为日销上界（不含）；null 表示不限制。
+ * zero 档为「窗口内无销量」，由 salesQty <= 0 兜底。
+ */
+const PICKING_BIN_GRADE_RULES = [
+  { key: 'hot', label: '爆款：日销≥20', lower: 20, upper: null, tip: '商品日均销量 ≥ 20 件' },
+  { key: 'best', label: '热卖款：10≤日销＜20', lower: 10, upper: 20, tip: '商品日均销量 10 ~ 20 件（含 10，不含 20）' },
+  { key: 'normal', label: '平销款：3≤日销＜10', lower: 3, upper: 10, tip: '商品日均销量 3 ~ 10 件（含 3，不含 10）' },
+  { key: 'slow1', label: '滞销款-1：1≤日销＜3', lower: 1, upper: 3, tip: '商品日均销量 1 ~ 3 件（含 1，不含 3）' },
+  { key: 'slow2', label: '滞销款-2：0＜日销＜1', lower: 0, upper: 1, tip: '商品日均销量大于 0 且小于 1 件' },
+  { key: 'zero', label: '销售=0', lower: 0, upper: 0, tip: '统计窗口内该商品无销量（仍占用库存）' },
+];
+
+const PICKING_BIN_TOTAL_LABEL = '汇总';
+
+module.exports = {
+  PICKING_BIN_LEVEL1,
+  PICKING_BIN_LEVEL2,
+  PICKING_BIN_WINDOW_OPTIONS,
+  PICKING_BIN_DEFAULT_DAYS,
+  BIN_TYPE_PICKING,
+  PICKING_BIN_BIN_TYPES,
+  PICKING_BIN_GRADE_RULES,
+  PICKING_BIN_TOTAL_LABEL,
+};

backend/src/config/productInformationDatabase.js

@@ -0,0 +1,169 @@
+/**
+ * 产品资料系统数据库连接模块（PostgreSQL）
+ *
+ * 数据来源：系统库 database_configs 表中 name = 'product_information_database' 的配置。
+ * 典型配置：postgres / 218.93.9.38:25432 / furniture3d_prod / external_full_reader / ssl=1
+ *
+ * 该库用于 MKH-BOM 资料页面的商品资料匹配：
+ *   external.intake_sku_items_ready_v1
+ *     —— 真实可用的 SKU 明细视图（约 4.6 万行）
+ *     —— source_sku_id 为聚水潭原始 SKU 编码（即业务库 BOM 的配件编码）
+ *     —— sku_code 为商品编码，barcode 为条码
+ *   external.warehouse_locations_v1 —— 库位主数据（当前仅 1 行：A-01 成品区）
+ *
+ * 说明：external.product_bom_v1 / product_skus_v1 当前为空视图，不可用。
+ */
+
+const { Pool } = require('pg');
+const database = require('./database');
+
+const CONFIG_NAME = 'product_information_database';
+const READY_VIEW = 'external.intake_sku_items_ready_v1';
+const LOCATION_VIEW = 'external.warehouse_locations_v1';
+
+const parsePositiveInt = (value, fallback) => {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+const POOL_MAX = parsePositiveInt(process.env.PRODUCT_DB_POOL_MAX, 4);
+
+let pool = null;
+let cachedSignature = '';
+
+const truthy = (value) => (
+  value === true || value === 1 || String(value || '').toLowerCase() === 'true' || String(value || '') === '1'
+);
+
+async function loadStoredConfig() {
+  const rows = await database.local.query(
+    `SELECT id, host, port, database_name, username, password, \`ssl\`, driver, status
+     FROM database_configs WHERE name = ? LIMIT 1`,
+    [CONFIG_NAME]
+  );
+
+  const config = rows[0];
+  if (!config) {
+    const error = new Error('产品资料系统数据库尚未配置，请在「系统设置 - 数据库配置」中完成配置');
+    error.statusCode = 503;
+    error.code = 'PRODUCT_DB_NOT_CONFIGURED';
+    throw error;
+  }
+
+  if (String(config.driver || '').toLowerCase() !== 'postgres') {
+    const error = new Error('产品资料系统数据库需要选择 PostgreSQL 类型');
+    error.statusCode = 503;
+    error.code = 'PRODUCT_DB_DRIVER_MISMATCH';
+    throw error;
+  }
+
+  return {
+    id: config.id,
+    host: String(config.host || '').trim(),
+    port: Number(config.port) || 5432,
+    database: String(config.database_name || '').trim(),
+    user: String(config.username || '').trim(),
+    password: config.password || '',
+    ssl: truthy(config.ssl),
+  };
+}
+
+const buildSignature = (config) => [
+  config.id,
+  config.host,
+  config.port,
+  config.database,
+  config.user,
+  config.ssl ? 'ssl' : 'nossl',
+].join('::');
+
+async function getPool() {
+  const config = await loadStoredConfig();
+  const signature = buildSignature(config);
+
+  if (pool && signature === cachedSignature) {
+    return pool;
+  }
+
+  if (pool) {
+    await pool.end().catch(() => {});
+    pool = null;
+  }
+
+  pool = new Pool({
+    host: config.host,
+    port: config.port,
+    database: config.database,
+    user: config.user,
+    password: config.password,
+    ssl: config.ssl ? { rejectUnauthorized: false } : false,
+    max: POOL_MAX,
+    idleTimeoutMillis: 30000,
+    connectionTimeoutMillis: 20000,
+    query_timeout: 180000,
+    statement_timeout: 180000,
+  });
+
+  pool.on('error', (error) => {
+    console.warn('[ProductDB] 连接池异常:', error.message);
+  });
+
+  cachedSignature = signature;
+  return pool;
+}
+
+/**
+ * 执行查询，返回行数组。
+ * @param {string} sqlText PostgreSQL 语句（使用 $1/$2 占位）
+ * @param {Array} params 参数数组
+ */
+async function query(sqlText, params = []) {
+  const maxAttempts = 2;
+  let lastError = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const activePool = await getPool();
+      const result = await activePool.query(sqlText, params);
+      return result.rows;
+    } catch (error) {
+      lastError = error;
+      if (error.code === 'PRODUCT_DB_NOT_CONFIGURED' || error.code === 'PRODUCT_DB_DRIVER_MISMATCH') {
+        throw error;
+      }
+      if (attempt < maxAttempts) {
+        console.warn(`[ProductDB] 查询失败，准备重连后重试 (${attempt}/${maxAttempts}): ${error.message}`);
+        await reset();
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+async function reset() {
+  if (pool) {
+    await pool.end().catch(() => {});
+  }
+  pool = null;
+  cachedSignature = '';
+}
+
+async function test() {
+  try {
+    const rows = await query('SELECT 1 AS test');
+    return { success: true, message: '产品资料系统数据库连接成功', data: rows };
+  } catch (error) {
+    return { success: false, message: `连接失败: ${error.message}` };
+  }
+}
+
+module.exports = {
+  query,
+  test,
+  reset,
+  getPool,
+  CONFIG_NAME,
+  READY_VIEW,
+  LOCATION_VIEW,
+};

backend/src/config/redis.js

@@ -41,13 +41,15 @@ function buildRedisClientConfig(config) {
   return {
     host: config.host,
     port: parseInt(config.port || '6379', 10),
-    username: process.env.REDIS_USERNAME || process.env.REDIS_USER || undefined,
+    username: config.username || process.env.REDIS_USERNAME || process.env.REDIS_USER || undefined,
     password: config.password || undefined,
     db: parseInt(config.db || '0', 10),
+    tls: config.tls ? { servername: config.tlsServerName || config.host } : undefined,
     connectTimeout: REDIS_CONNECT_TIMEOUT_MS,
     retryStrategy: (times) => (times > 1 ? null : 200),
     maxRetriesPerRequest: 1,
     enableOfflineQueue: false,
+    enableReadyCheck: false,
     lazyConnect: true,
   };
 }
@@ -61,8 +63,10 @@ function getConfigSignature(config) {
     host: config.host,
     port: parseInt(config.port || '6379', 10),
     db: parseInt(config.db || '0', 10),
-    username: process.env.REDIS_USERNAME || process.env.REDIS_USER || '',
+    username: config.username || process.env.REDIS_USERNAME || process.env.REDIS_USER || '',
     password: config.password || '',
+    tls: Boolean(config.tls),
+    tlsServerName: config.tlsServerName || '',
   });
 }
 

backend/src/config/stockSalesAnalysis.js

@@ -0,0 +1,47 @@
+/**
+ * 仓库库存动销分析 —— 口径配置（纯规则，不含业务数值）
+ *
+ * 一级菜单：大货库存监控
+ * 二级菜单：库存动销分析
+ *
+ * 表头（与需求表一致）：仓库 | 动销等级 | SKU数量 | SKU占比 | 库存数量 | 库存占比 | 销量
+ *
+ * 口径：
+ *   日销（日均销量）= 统计窗口内已发货件数 / 窗口天数
+ *   动销等级按「单个 SKU 的日销」分档，落在哪一档就计入哪一档
+ *   仓库内汇总：SKU占比 = 该等级 SKU 数 / 该仓库 SKU 总数
+ *               库存占比 = 该等级库存件数 / 该仓库库存总件数
+ *   仓库清单与「每日进销存」保持同一份（DAILY_INVENTORY_BASELINE）
+ */
+
+const STOCK_SALES_LEVEL1 = '大货库存监控';
+const STOCK_SALES_LEVEL2 = '库存动销分析';
+
+/** 可选的统计窗口天数；默认 30 天 */
+const STOCK_SALES_WINDOW_OPTIONS = [7, 14, 30];
+const STOCK_SALES_DEFAULT_DAYS = 30;
+
+/**
+ * 动销等级（顺序即表格行顺序，汇总行由 total 单独给出）。
+ * lower 为日销下界（含），upper 为日销上界（不含）；null 表示不限制。
+ */
+const SALES_GRADE_RULES = [
+  { key: 'hot', label: '爆款：日销≥20', lower: 20, upper: null, tip: '单个 SKU 日均销量 ≥ 20 件' },
+  { key: 'best', label: '热卖款：10≤日销＜20', lower: 10, upper: 20, tip: '单个 SKU 日均销量 10 ~ 20 件（含 10，不含 20）' },
+  { key: 'normal', label: '平销款：3≤日销＜10', lower: 3, upper: 10, tip: '单个 SKU 日均销量 3 ~ 10 件（含 3，不含 10）' },
+  { key: 'slow1', label: '滞销款-1：1≤日销＜3', lower: 1, upper: 3, tip: '单个 SKU 日均销量 1 ~ 3 件（含 1，不含 3）' },
+  { key: 'slow2', label: '滞销款-2：0＜日销＜1', lower: 0, upper: 1, tip: '单个 SKU 日均销量大于 0 且小于 1 件' },
+  { key: 'zero', label: '销售=0', lower: 0, upper: 0, tip: '统计窗口内无销量的 SKU（仍占用库存）' },
+];
+
+/** 汇总行的等级名（表内展示用） */
+const SALES_TOTAL_LABEL = '汇总';
+
+module.exports = {
+  STOCK_SALES_LEVEL1,
+  STOCK_SALES_LEVEL2,
+  STOCK_SALES_WINDOW_OPTIONS,
+  STOCK_SALES_DEFAULT_DAYS,
+  SALES_GRADE_RULES,
+  SALES_TOTAL_LABEL,
+};

backend/src/constants/sidebarPages.js

@@ -29,12 +29,27 @@ const SIDEBAR_PAGES = [
   buildPlanningPage({ pageKey: 'promotion_module', pageName: '推广模块', path: '/planning/operation/promotion-module' }),
   buildPlanningPage({ pageKey: 'new_product_test', pageName: '新品测款', path: '/planning/operation/new-product-test' }),
   buildPlanningPage({ pageKey: 'product_analysis', pageName: '商品分析', path: '/planning/operation/product-analysis' }),
-  buildPlanningPage({ pageKey: 'store_checkup', pageName: '店铺体检', path: '/planning/operation/store-checkup' }),
-  buildPlanningPage({ pageKey: 'review_analysis', pageName: '复盘分析', path: '/planning/operation/review-analysis' }),
-  buildPlanningPage({ pageKey: 'customer_service_checkup', pageName: '客服质检', path: '/planning/operation/customer-service-checkup' }),
-  buildPlanningPage({ pageKey: 'ai_buyer_show', pageName: 'AI买家秀', path: '/planning/operation/ai-buyer-show' }),
-  buildPlanningPage({ pageKey: 'ai_seeding_video', pageName: 'AI种草视频', path: '/planning/operation/ai-seeding-video' }),
+  buildPlanningPage({
+    pageKey: 'modular_stock_monitor',
+    pageName: '模块化库存监控 · 配件库存监控',
+    path: '/planning/operation/modular-stock-monitor',
+  }),
+  buildPlanningPage({
+    pageKey: 'mkh_bom',
+    pageName: '模块化库存监控 · MKH-BOM资料',
+    path: '/planning/operation/mkh-bom-data',
+  }),
   buildPlanningPage({ pageKey: 'work_orders', pageName: '工单待办', path: '/planning/operation/work-orders' }),
+  buildPlanningPage({
+    pageKey: 'stock_sales_analysis',
+    pageName: '大货库存监控 · 库存动销分析',
+    path: '/planning/operation/stock-sales-analysis',
+  }),
+  buildPlanningPage({
+    pageKey: 'picking_bin_sales_analysis',
+    pageName: '大货库存监控 · 拣选库位动销分析',
+    path: '/planning/operation/picking-bin-sales-analysis',
+  }),
   {
     pageKey: 'settings',
     pageName: '系统设置',

backend/src/index.js

@@ -19,7 +19,6 @@ const planningSelectionFissionExternalRoutes = require('./api/planningSelectionF
 const presaleExternalRoutes = require('./api/presaleExternal');
 const delistExternalRoutes = require('./api/delistExternal');
 const campaignCloudRoutes = require('./api/campaignCloud');
-const pricingCalculatorExternalRoutes = require('./api/pricingCalculatorExternal');
 const desktopClientRoutes = require('./api/desktopClient');
 const desktopPresenceRoutes = require('./api/desktopPresence');
 const desktopExecutionTaskRoutes = require('./api/desktopExecutionTasks');
@@ -33,11 +32,17 @@ const productCodeBoardRoutes = require('./api/productCodeBoard');
 const productAnalysisRoutes = require('./api/productAnalysis');
 const marketingEventsRoutes = require('./api/marketingEvents');
 const promotionModuleRoutes = require('./api/promotionModule');
-const csQualityRoutes = require('./api/csQuality');
-const aiBuyerShowRoutes = require('./api/aiBuyerShow');
-const storeCheckupRoutes = require('./api/storeCheckup');
-const pricingCalculatorRoutes = require('./api/pricingCalculator');
 const productMonitoringRoutes = require('./api/productMonitoring');
+const modularStockMonitorRoutes = require('./api/modularStockMonitor');
+const mkhBomRoutes = require('./api/mkhBom');
+const warehouseShipTimelinessRoutes = require('./api/warehouseShipTimeliness');
+const dailyInventoryRoutes = require('./api/dailyInventory');
+const dailyInventoryNotificationRoutes = require('./api/dailyInventoryNotification');
+const stockSalesAnalysisRoutes = require('./api/stockSalesAnalysis');
+const pickingBinSalesAnalysisRoutes = require('./api/pickingBinSalesAnalysis');
+const returnInventoryWarningRoutes = require('./api/returnInventoryWarning');
+const returnMonitorRoutes = require('./api/returnMonitor');
+const returnStockWarningRoutes = require('./api/returnStockWarning');
 const database = require('./config/database');
 const cloudDb = require('./config/cloudDatabase');
 const jianSunDb = require('./config/jianSunDatabase');
@@ -50,9 +55,18 @@ const { startPlanningMayProductSnapshotSchedulers } = require('./jobs/planningMa
 const { startPlanningDingWorkflowSyncSchedulers } = require('./jobs/planningDingWorkflowSyncJob');
 const { startOpsBIncentiveSnapshotSchedulers } = require('./jobs/opsBIncentiveSnapshotJob');
 const { startGoodsFirstSeenScheduler } = require('./jobs/goodsFirstSeenJob');
+const {
+  startDailyInventorySnapshotScheduler,
+} = require('./jobs/dailyInventorySnapshotJob');
+const {
+  startDailyInventoryNotificationScheduler,
+} = require('./jobs/dailyInventoryNotificationJob');
 const {
   startAlibaba1688ImageSearchExpiryScheduler,
 } = require('./jobs/alibaba1688ImageSearchExpiryJob');
+const {
+  startMkhReplenishAlertScheduler,
+} = require('./jobs/mkhReplenishAlertJob');
 const { DEFAULT_SITE_CONFIG, getInstallStatus } = require('./services/installService');
 const { ensureLocalSchema } = require('./services/localSchema');
 const {
@@ -636,7 +650,6 @@ async function startServer(options = {}) {
     cubejsApp.use('/api/external/selection-fission/presale', presaleExternalRoutes);
     cubejsApp.use('/api/external/selection-fission/delist', delistExternalRoutes);
     cubejsApp.use('/api/campaign', campaignCloudRoutes);
-    cubejsApp.use('/api/external/selection-fission/pricing-calculator', pricingCalculatorExternalRoutes);
   cubejsApp.use('/api/external/selection-fission/1688-products', alibaba1688ProductExternalRoutes);
   cubejsApp.use('/api/external/selection-fission', planningSelectionFissionExternalRoutes);
   cubejsApp.use('/api/external/presale', presaleExternalRoutes);
@@ -655,13 +668,22 @@ async function startServer(options = {}) {
   cubejsApp.use('/api/product-analysis', authMiddleware, productAnalysisRoutes);
   cubejsApp.use('/api/marketing-events', authMiddleware, marketingEventsRoutes);
   cubejsApp.use('/api/promotion-module', authMiddleware, promotionModuleRoutes);
-  cubejsApp.use('/api/cs-quality', authMiddleware, csQualityRoutes);
-  cubejsApp.use('/api/ai-buyer-show', authMiddleware, aiBuyerShowRoutes);
-  cubejsApp.use('/api/store-checkup', authMiddleware, storeCheckupRoutes);
-  cubejsApp.use('/api/pricing-calculator', authMiddleware, pricingCalculatorRoutes);
   cubejsApp.use('/api/planning-upload', authMiddleware, planningUploadPageCache, planningUploadRoutes);
   cubejsApp.use('/api/channel', authMiddleware, channelPageCache, channelRoutes);
   cubejsApp.use('/api/product-monitoring', authMiddleware, productMonitoringRoutes);
+  cubejsApp.use('/api/modular-stock-monitor', authMiddleware, modularStockMonitorRoutes);
+  cubejsApp.use('/api/mkh-bom', authMiddleware, mkhBomRoutes);
+  // 仓储中心 24 小时发货时效（2026-10-20 新增）：列表左侧侧栏，11 个主仓超时未发
+  cubejsApp.use('/api/warehouse-ship-timeliness', authMiddleware, warehouseShipTimelinessRoutes);
+  cubejsApp.use('/api/daily-inventory', authMiddleware, dailyInventoryRoutes);
+  cubejsApp.use('/api/daily-inventory-notification', authMiddleware, dailyInventoryNotificationRoutes);
+  cubejsApp.use('/api/stock-sales-analysis', authMiddleware, stockSalesAnalysisRoutes);
+  cubejsApp.use('/api/picking-bin-sales-analysis', authMiddleware, pickingBinSalesAnalysisRoutes);
+  cubejsApp.use('/api/return-inventory-warning', authMiddleware, returnInventoryWarningRoutes);
+  // 崔桥工厂仓客退：退货入库核销 + 每日库存监控
+  cubejsApp.use('/api/return-monitor', authMiddleware, returnMonitorRoutes);
+  // 崔桥工厂仓客退：退货库存预警（箱及仓位库存 · 崔桥工厂客退临时上架仓）
+  cubejsApp.use('/api/return-stock-warning', authMiddleware, returnStockWarningRoutes);
 
   // =====================
   // 数据分析 API（公开访问，可根据需要添加认证）
@@ -697,11 +719,41 @@ async function startServer(options = {}) {
     }
   });
 
+  // =====================
+  // 统一 API 兜底（必须放在所有路由之后）
+  // =====================
+  // 背景：此前没有任何 4 参错误处理中间件，路由里抛出的异常会落到 Express
+  // 默认处理器，返回一张 HTML 的 "Internal Server Error" 页面；前端 axios
+  // 读不到 error / message 字段，只能显示 "Request failed with status code 500"，
+  // 出问题时完全看不到真实原因。这里统一返回 JSON 并打印堆栈。
+  cubejsApp.use('/api', (req, res) => {
+    res.status(404).json({
+      success: false,
+      error: `接口不存在: ${req.method} ${req.originalUrl}`,
+    });
+  });
+
+  cubejsApp.use((err, req, res, next) => {
+    if (res.headersSent) {
+      return next(err);
+    }
+    const rawStatus = Number(err?.status || err?.statusCode);
+    const status = Number.isFinite(rawStatus) && rawStatus >= 400 && rawStatus <= 599
+      ? rawStatus
+      : 500;
+    const messageText = err?.message || '服务器内部错误';
+    console.error(`❌ [API ${status}] ${req.method} ${req.originalUrl} -> ${messageText}`);
+    if (err?.stack) {
+      console.error(err.stack);
+    }
+    return res.status(status).json({ success: false, error: messageText });
+  });
+
   console.log('='.repeat(50));
   console.log('🚀 后端服务已启动');
-  console.log(`📡 服务地址: http://localhost:4000`);
+  console.log(`📡 服务地址: http://localhost:${process.env.PORT || 4000}`);
   console.log(cubeMode === 'cube'
-    ? '📊 Cube.js API: http://localhost:4000/cubejs-api'
+    ? `📊 Cube.js API: http://localhost:${process.env.PORT || 4000}/cubejs-api`
     : '📊 Cube.js API: 已降级不可用，业务 API 继续运行');
 
   // 测试数据库连接
@@ -716,6 +768,11 @@ async function startServer(options = {}) {
   console.log(`   [缓存] ${redisTest.message}`);
   console.log('='.repeat(50));
 
+  // 每日进销存截图通知：与「后台定时任务总开关」解耦，保证即使总开关关闭，
+  // 只要功能启用就仍会按配置时间推送（可用 DAILY_INVENTORY_NOTIFICATION_ENABLED=false 单独关闭）。
+  // 它每分钟只做一次轻量判断，命中配置时间才真正截图上传。
+  startDailyInventoryNotificationScheduler();
+
   if (String(process.env.ENABLE_BACKGROUND_JOBS || 'true').toLowerCase() === 'false') {
     console.log('⏸️ 后台定时任务和预热已关闭，业务请求按需处理');
     return;
@@ -730,6 +787,8 @@ async function startServer(options = {}) {
   startOpsBIncentiveSnapshotSchedulers();
   startGoodsFirstSeenScheduler();
   startAlibaba1688ImageSearchExpiryScheduler();
+  startMkhReplenishAlertScheduler();
+  startDailyInventorySnapshotScheduler();
 
   // Keep the first selection-pool page request from paying the remote schema
   // inspection round-trip over the planning database tunnel.

backend/src/jobs/dailyInventoryNotificationJob.js

@@ -0,0 +1,351 @@
+'use strict';
+
+// 每日进销存 · 定时截图通知
+//
+// 执行流程：
+//   ① 单实例锁（MySQL GET_LOCK），避免多实例重复截图推送
+//   ② 校验：功能开启 / 有收件人 / 通知中心已配置 / 对象存储已配置，任一不满足就记录原因并退出
+//   ③ 按配置时间（默认 01:00 Asia/Shanghai）触发；业务日期 = 北京时间昨日（与页面 T-1 口径一致）
+//   ④ 截图 → 上传对象存储 → 拿到公开 HTTPS 地址后才发通知
+//   ⑤ 逐用户发送，用「业务日期 + 收件人」幂等键去重；单人失败不影响其他人
+//   ⑥ 截图/上传/通知失败均做有限次数重试与指数退避
+//   ⑦ 每次执行都落一条记录（时间 / 截图地址 / 通知对象 / 成功状态 / 失败原因）
+//
+// 立即测试（mode='test'）：走同一条链路，但幂等键带随机数，**不写入正式幂等记录**，
+// 因此不会影响下一次正式定时推送。
+
+const crypto = require('crypto');
+const cron = require('node-cron');
+const database = require('../config/database');
+const {
+  appendRunRecord,
+  buildIdempotencyKey,
+  getDailyInventoryNotificationRuntimeConfig,
+  getObjectStorageStatus,
+  hasNotified,
+  loadDailyInventoryNotificationState,
+  markNotified,
+  normalizeRecipients,
+} = require('../services/dailyInventoryNotificationSettings');
+const {
+  captureAndUploadDailyInventory,
+  chinaTimeParts,
+  resolvePageUrl,
+} = require('../services/dailyInventoryScreenshot');
+const {
+  getYydNotificationCenterRuntimeConfig,
+  isYydNotificationCenterConfigured,
+  sendYydNotification,
+} = require('../services/yydNotificationCenterClient');
+const TIMEZONE = 'Asia/Shanghai';
+const LOCK_KEY = 'daily_inventory_notification_job';
+const LOCK_WAIT_SECONDS = 2;
+const NOTIFICATION_TITLE = '每日进销存数据';
+const ACTION_TITLE = '查看每日进销存';
+
+// 重试策略：最多 3 次，退避 2s / 4s
+const MAX_ATTEMPTS = 3;
+const RETRY_BASE_DELAY_MS = 2000;
+// 命中时间后允许补跑的窗口与次数上限（防止全天每分钟重试刷屏）
+const RETRY_WINDOW_MINUTES = 30;
+const MAX_SCHEDULED_ATTEMPTS_PER_DAY = 3;
+
+let running = false;
+let timer = null;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** 有限次数重试 + 指数退避 */
+async function withRetry(task, { label, attempts = MAX_ATTEMPTS, baseDelayMs = RETRY_BASE_DELAY_MS } = {}) {
+  let lastError = null;
+  for (let index = 0; index < attempts; index += 1) {
+    try {
+      return await task();
+    } catch (error) {
+      lastError = error;
+      const delay = baseDelayMs * (2 ** index);
+      console.error(
+        `[DailyInventoryNotify] ${label} 第 ${index + 1}/${attempts} 次失败：${error.message}`
+        + `${index < attempts - 1 ? `，${delay}ms 后重试` : ''}`
+      );
+      if (index < attempts - 1) await sleep(delay);
+    }
+  }
+  throw lastError;
+}
+
+/** 业务日期 = 北京时间昨日（页面标注 T-1，凌晨跑批产出昨日快照） */
+function resolveBizDate(now = new Date()) {
+  const target = now instanceof Date ? now : new Date(now);
+  const shifted = new Date(target.getTime() - 24 * 60 * 60 * 1000);
+  return chinaTimeParts(shifted).bizDate;
+}
+
+function beijingTimeText(date = new Date()) {
+  const target = date instanceof Date ? date : new Date(date);
+  return new Intl.DateTimeFormat('zh-CN', {
+    timeZone: TIMEZONE,
+    year: 'numeric', month: '2-digit', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', second: '2-digit',
+    hour12: false,
+  }).format(target);
+}
+
+function currentBeijingHhMm(now = new Date()) {
+  const text = new Intl.DateTimeFormat('en-GB', {
+    timeZone: TIMEZONE, hour: '2-digit', minute: '2-digit', hour12: false,
+  }).format(now instanceof Date ? now : new Date(now));
+  return text;
+}
+
+/** 全实例锁：拿到锁才继续执行，拿不到说明其它实例正在跑 */
+async function withJobLock(runner) {
+  const pool = database.local.pool;
+  let connection = null;
+  try {
+    connection = await pool.getConnection();
+    const [rows] = await connection.query('SELECT GET_LOCK(?, ?) AS lockStatus', [LOCK_KEY, LOCK_WAIT_SECONDS]);
+    const acquired = Number(rows?.[0]?.lockStatus || 0) === 1;
+    if (!acquired) {
+      return { success: false, skipped: true, reason: 'lock_not_acquired' };
+    }
+    return await runner();
+  } catch (error) {
+    return { success: false, skipped: true, reason: 'lock_error', error: error.message };
+  } finally {
+    if (connection) {
+      try {
+        await connection.query('DO RELEASE_LOCK(?)', [LOCK_KEY]);
+      } catch (_error) {
+        // ignore
+      }
+      connection.release();
+    }
+  }
+}
+
+function buildNotificationContent({ bizDate, takenAt, imageUrl, pageUrl }) {
+  return [
+    `**数据日期：** ${bizDate}`,
+    `**截图生成时间：** ${takenAt}（${TIMEZONE}）`,
+    `**图片地址：** ${imageUrl}`,
+    `**页面地址：** ${pageUrl}`,
+    '',
+    `点击右下角「${ACTION_TITLE}」可直达每日进销存页面。`,
+  ].join('\n');
+}
+
+/**
+ * 执行一次（正式 / 测试）
+ * @param {Object} options
+ *   mode      'scheduled' | 'manual' | 'test'
+ *   force     true 时忽略「今天已调度过」的节流判断（手动触发用）
+ *   now       指定执行时刻，便于测试
+ */
+async function runDailyInventoryNotificationJob(options = {}) {
+  const mode = options.mode || 'scheduled';
+  const now = options.now ? new Date(options.now) : new Date();
+  const startedAt = now.toISOString();
+
+  if (running) {
+    return { success: false, skipped: true, reason: 'already_running' };
+  }
+  running = true;
+
+  try {
+    return await withJobLock(async () => {
+      const config = await getDailyInventoryNotificationRuntimeConfig({ forceRefresh: true });
+      const recipients = normalizeRecipients(config.recipients);
+      const bizDate = resolveBizDate(now);
+
+      const finish = async (payload) => {
+        await appendRunRecord({ ...payload, runAt: startedAt, bizDate, mode, notifyTime: config.notifyTime });
+        return payload;
+      };
+
+      if (!config.enabled) {
+        return finish({ success: false, reason: 'disabled', error: '功能未启用' });
+      }
+      if (!recipients.length) {
+        return finish({ success: false, reason: 'no_recipient', error: '未配置通知用户' });
+      }
+
+      let centerConfig = null;
+      try {
+        centerConfig = await getYydNotificationCenterRuntimeConfig();
+      } catch (_error) {
+        centerConfig = null;
+      }
+      if (!isYydNotificationCenterConfigured(centerConfig)) {
+        return finish({ success: false, reason: 'notification_center_not_configured', error: '统一通知中心未配置' });
+      }
+
+      const storage = await getObjectStorageStatus();
+      if (!storage.configured) {
+        return finish({ success: false, reason: 'object_storage_not_configured', error: '对象存储未配置' });
+      }
+
+      // 截图 → 上传（失败直接结束，绝不发通知）
+      let shot;
+      try {
+        shot = await withRetry(
+          // 对象键按业务日期归档：daily-inventory/2026-09-25/daily-inventory-20260925-010000.png
+          () => captureAndUploadDailyInventory({ now, bizDate }),
+          { label: '截图并上传' }
+        );
+      } catch (error) {
+        return finish({ success: false, reason: 'screenshot_failed', error: error.message });
+      }
+
+      const pageUrl = resolvePageUrl();
+      const takenAt = beijingTimeText(now);
+      const nonce = crypto.randomBytes(8).toString('hex');
+
+      const deliveries = [];
+      for (const recipient of recipients) {
+        const idempotencyKey = buildIdempotencyKey({ bizDate, recipient, mode, nonce });
+        // 正式推送先查幂等：同一业务日期 + 同一用户只成功通知一次
+        if (mode !== 'test' && await hasNotified(bizDate, recipient)) {
+          deliveries.push({ recipient, status: 'skipped', reason: 'already_notified' });
+          continue;
+        }
+        try {
+          const response = await withRetry(
+            () => sendYydNotification({
+              idempotencyKey,
+              recipientAlias: recipient,
+              title: NOTIFICATION_TITLE,
+              content: buildNotificationContent({
+                bizDate, takenAt, imageUrl: shot.url, pageUrl,
+              }),
+              actionTitle: ACTION_TITLE,
+              actionUrl: pageUrl,
+            }),
+            { label: `通知 ${recipient}` }
+          );
+          const deliveryId = response?.id || response?.data?.id || null;
+          if (mode !== 'test') await markNotified(bizDate, recipient, { deliveryId, idempotencyKey });
+          deliveries.push({ recipient, status: 'sent', deliveryId });
+        } catch (error) {
+          // 单人失败不阻断其他人
+          console.error(`[DailyInventoryNotify] 通知 ${recipient} 失败：${error.message}`);
+          deliveries.push({ recipient, status: 'failed', error: error.message });
+        }
+      }
+
+      const sentCount = deliveries.filter((d) => d.status === 'sent').length;
+      const failedCount = deliveries.filter((d) => d.status === 'failed').length;
+      const success = sentCount > 0;
+
+      console.log(
+        `[DailyInventoryNotify] ${mode} 完成：业务日 ${bizDate}，截图 ${shot.url}，`
+        + `通知成功 ${sentCount} / 失败 ${failedCount} / 跳过 ${deliveries.length - sentCount - failedCount}`
+      );
+
+      return finish({
+        success,
+        reason: success ? null : 'notify_failed',
+        error: success ? null : '所有收件人均通知失败',
+        screenshotUrl: shot.url,
+        screenshotKey: shot.key,
+        rowCount: shot.rowCount,
+        recipients: deliveries,
+      });
+    });
+  } finally {
+    running = false;
+  }
+}
+
+/** 同一业务日期已经发起过的正式调度次数与最后一次结果（用于失败重试节流） */
+async function scheduledAttemptStatus(bizDate) {
+  const state = await loadDailyInventoryNotificationState();
+  const runs = (Array.isArray(state.runs) ? state.runs : [])
+    .filter((r) => r.bizDate === bizDate && r.mode === 'scheduled');
+  return {
+    count: runs.length,
+    lastSuccess: runs.length ? runs[runs.length - 1].success === true : null,
+  };
+}
+
+function minutesOfDay(hhmm) {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(String(hhmm || ''));
+  if (!match) return null;
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  if (hour > 23 || minute > 59) return null;
+  return hour * 60 + minute;
+}
+
+/**
+ * 是否应当发起一次正式调度：
+ *   · 恰好命中配置时间 → 执行
+ *   · 命中时间之后的 RETRY_WINDOW_MINUTES 分钟内 → 仅在上一次失败且未超出重试上限时补跑
+ *   · 其余时间 → 不执行
+ */
+async function shouldRunScheduled(config, now) {
+  const target = minutesOfDay(config.notifyTime);
+  const current = minutesOfDay(currentBeijingHhMm(now));
+  if (target === null || current === null) return false;
+
+  const diff = current - target;
+  if (diff < 0 || diff > RETRY_WINDOW_MINUTES) return false;
+  if (diff === 0) return true;
+
+  const status = await scheduledAttemptStatus(resolveBizDate(now));
+  return status.lastSuccess === false && status.count < MAX_SCHEDULED_ATTEMPTS_PER_DAY;
+}
+
+function startDailyInventoryNotificationScheduler() {
+  const disabled = String(process.env.DAILY_INVENTORY_NOTIFICATION_ENABLED || 'true').trim().toLowerCase() === 'false';
+  if (disabled) {
+    console.log('[DailyInventoryNotify] 已通过环境变量关闭');
+    return null;
+  }
+  if (timer) return timer;
+  // 每分钟检查一次：命中配置的通知时间才真正执行，配置改动无需重启
+  timer = cron.schedule('* * * * *', async () => {
+    try {
+      const config = await getDailyInventoryNotificationRuntimeConfig({ forceRefresh: true });
+      if (!config.enabled) return;
+      const now = new Date();
+      if (!(await shouldRunScheduled(config, now))) return;
+      await runDailyInventoryNotificationJob({ mode: 'scheduled', now });
+    } catch (error) {
+      console.error('[DailyInventoryNotify] 定时检查失败:', error.message);
+    }
+  }, { timezone: TIMEZONE });
+
+  console.log(
+    `[Scheduler] 每日进销存截图通知已注册（按配置时间触发，${TIMEZONE}，`
+    + `失败后 ${RETRY_WINDOW_MINUTES} 分钟内最多补跑 ${MAX_SCHEDULED_ATTEMPTS_PER_DAY} 次）`
+  );
+  return timer;
+}
+
+function stopDailyInventoryNotificationScheduler() {
+  if (timer) {
+    timer.stop();
+    timer = null;
+  }
+}
+
+module.exports = {
+  ACTION_TITLE,
+  LOCK_KEY,
+  MAX_ATTEMPTS,
+  MAX_SCHEDULED_ATTEMPTS_PER_DAY,
+  NOTIFICATION_TITLE,
+  RETRY_BASE_DELAY_MS,
+  TIMEZONE,
+  RETRY_WINDOW_MINUTES,
+  beijingTimeText,
+  buildNotificationContent,
+  currentBeijingHhMm,
+  minutesOfDay,
+  resolveBizDate,
+  runDailyInventoryNotificationJob,
+  startDailyInventoryNotificationScheduler,
+  stopDailyInventoryNotificationScheduler,
+  withRetry,
+};

backend/src/jobs/dailyInventorySnapshotJob.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * 每日库存快照任务
+ *
+ * 业务库没有按天的历史库存结存表，「期初数量」无法回溯。
+ * 本任务每天定时把 26 个仓库的实时库存落一份到本地快照表 daily_inventory_snapshot，
+ * 使「今日期初 = 上一业务日期末」能够自动滚动。
+ *
+ * 默认 01:30 执行（报表库 01:00 跑批之后）。可用环境变量覆盖：
+ *   DAILY_INVENTORY_SNAPSHOT_ENABLED=false 关闭
+ *   DAILY_INVENTORY_SNAPSHOT_CRON='30 1 * * *'
+ */
+const cron = require('node-cron');
+const cloudDb = require('../config/cloudDatabase');
+const snapshotDb = require('../config/dailyInventorySnapshotDb');
+const { DAILY_INVENTORY_BASELINE } = require('../config/dailyInventoryBaseline');
+
+let running = false;
+let timer = null;
+
+const JOB_ENABLED = String(process.env.DAILY_INVENTORY_SNAPSHOT_ENABLED || 'true').toLowerCase() !== 'false';
+const JOB_CRON = process.env.DAILY_INVENTORY_SNAPSHOT_CRON || '30 1 * * *';
+
+/** 业务日 = 库存快照库最新日期（报表库每日凌晨跑批，标注 T-1） */
+async function resolveBizDate() {
+  const rows = await cloudDb.query(
+    `SELECT MAX(CONVERT(VARCHAR(10), date, 23)) AS d FROM rpt.pm_stockMonitor`
+  );
+  return rows[0]?.d || null;
+}
+
+function buildInClause(values, prefix) {
+  const params = {};
+  const clause = values
+    .map((v, i) => {
+      params[`${prefix}${i}`] = v;
+      return `@${prefix}${i}`;
+    })
+    .join(',');
+  return { clause, params };
+}
+
+async function syncOnce(trigger = 'cron') {
+  if (running) {
+    console.log(`[DailyInventorySnapshot] 上一次任务未结束，跳过 trigger=${trigger}`);
+    return { success: false, skipped: true, reason: 'already_running' };
+  }
+  running = true;
+  const startedAt = Date.now();
+  try {
+    const bizDate = await resolveBizDate();
+    if (!bizDate) {
+      console.log('[DailyInventorySnapshot] 未取到业务日，跳过');
+      return { success: false, skipped: true, reason: 'no_biz_date' };
+    }
+
+    const whs = DAILY_INVENTORY_BASELINE.filter((b) => b.wmsCoId != null);
+    const { clause, params } = buildInClause(whs.map((b) => b.wmsCoId), 'w');
+    const rows = await cloudDb.query(
+      `SELECT i.wms_co_id AS wmsCoId,
+              ISNULL(SUM(CAST(i.qty AS DECIMAL(18,2))), 0) AS closingQty,
+              SUM(CASE WHEN ABS(ISNULL(i.qty, 0)) > 0.0001 THEN 1 ELSE 0 END) AS skuCount,
+              MAX(i.modified) AS takenAt
+         FROM rpt.jst_inventoryInfo i
+        WHERE i.wms_co_id IN (${clause})
+        GROUP BY i.wms_co_id`,
+      params,
+      { requestTimeout: 120000 }
+    );
+
+    const m = new Map(rows.map((r) => [String(r.wmsCoId), r]));
+    const payload = whs.map((b) => {
+      const r = m.get(String(b.wmsCoId));
+      return {
+        wmsCoId: b.wmsCoId,
+        warehouse: b.warehouse,
+        dbWarehouse: b.dbWarehouse,
+        closingQty: Number(r?.closingQty ?? 0),
+        skuCount: Number(r?.skuCount ?? 0),
+        takenAt: r?.takenAt ? new Date(r.takenAt) : null,
+      };
+    });
+
+    const n = await snapshotDb.upsertSnapshot(bizDate, payload);
+    console.log(`[DailyInventorySnapshot] 业务日 ${bizDate} 写入 ${n}/${whs.length} 仓，耗时 ${Date.now() - startedAt}ms`);
+    return { success: true, bizDate, count: n };
+  } catch (error) {
+    console.error('[DailyInventorySnapshot] 执行失败:', error.message);
+    return { success: false, error: error.message };
+  } finally {
+    running = false;
+  }
+}
+
+function startDailyInventorySnapshotScheduler() {
+  if (!JOB_ENABLED) {
+    console.log('[DailyInventorySnapshot] 已通过环境变量关闭');
+    return null;
+  }
+  if (timer) return timer;
+  if (!cron.validate(JOB_CRON)) {
+    console.error(`[DailyInventorySnapshot] cron 表达式非法: ${JOB_CRON}`);
+    return null;
+  }
+  timer = cron.schedule(JOB_CRON, () => { syncOnce('cron'); }, { timezone: 'Asia/Shanghai' });
+  console.log(`[DailyInventorySnapshot] 已启动，cron=${JOB_CRON} (Asia/Shanghai)`);
+  return timer;
+}
+
+function stopDailyInventorySnapshotScheduler() {
+  if (timer) {
+    timer.stop();
+    timer = null;
+  }
+}
+
+module.exports = {
+  syncOnce,
+  startDailyInventorySnapshotScheduler,
+  stopDailyInventorySnapshotScheduler,
+};

backend/src/jobs/mkhReplenishAlertJob.js

@@ -0,0 +1,396 @@
+'use strict';
+
+// MKH 成品补货预警 · 定时推送
+//
+// 业务口径（2026-09-17 业务确认）：
+//   ① 推送范围：缺货（可用天数 ≤ 0）+ 3 天内预警商品（默认，可在页面里改成仅缺货）
+//      · 含「订单驱动」商品：近7日日销 = 0、但存在未发货订单的 MKH 成品
+//        （口径与取数见 mkhBomService 文件头 ⑩；正文里以「待发货订单 N 件」代替日销展示）
+//      · 含「配件不足」商品：配件现有库存可组装数 = 0（口径见 mkhBomService 文件头 ⑪）
+//        —— 这类商品**补不出去**，正文里明确写「配件不足，无法补货」并列出短板配件，
+//           不给出建议补货量（否则业务会照着补不到的目标去采购）
+//   ② 只提醒**新出现**的预警 —— 已经在「已推送」记录里的商品不重复推送，
+//      商品补货完成恢复到正常范围后会从记录里移除，下次再预警会重新提醒
+//   ③ 收件人：单独配置（配置为空时回退环境变量 → 统一通知中心默认收件人）
+//   ④ 时间：每天早上 09:00（Asia/Shanghai）
+//
+// 被未完成加工单豁免的「已排产」商品**不进入**推送清单（口径见 mkhBomService 文件头 ⑧）。
+
+const crypto = require('crypto');
+const cron = require('node-cron');
+const {
+  listReplenishAlertRows,
+} = require('../services/mkhBomService');
+const {
+  getMkhReplenishAlertRuntimeConfig,
+  loadMkhReplenishAlertState,
+  resolveMkhReplenishAlertRecipient,
+  saveMkhReplenishAlertState,
+} = require('../services/mkhReplenishAlertSettings');
+const {
+  isYydNotificationCenterConfigured,
+  sendYydNotification,
+} = require('../services/yydNotificationCenterClient');
+const {
+  getYydNotificationCenterRuntimeConfig,
+} = require('../services/yydNotificationCenterSettings');
+
+const DEFAULT_CRON = '0 9 * * *';
+const TIMEZONE = 'Asia/Shanghai';
+const OUT_OF_STOCK = '缺货';
+const WARNING = '预警';
+// 正文最多列出多少个商品（超出只报数量，避免超出通知中心 4800 字上限）
+const MAX_LISTED_ITEMS = 20;
+const STARTUP_DELAY_MS = 45 * 1000;
+
+function formatQty(value) {
+  if (value === null || value === undefined || value === '') return '—';
+  const num = Number(value);
+  if (!Number.isFinite(num)) return '—';
+  return Number.isInteger(num) ? String(num) : String(Number(num.toFixed(2)));
+}
+
+function formatChinaTime(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(date.getTime())) return '—';
+  return new Intl.DateTimeFormat('zh-CN', {
+    timeZone: TIMEZONE,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  }).format(date);
+}
+
+/** 北京时间 YYYYMMDD —— 幂等键按「天 + 本批商品」去重 */
+function chinaDateKey(date = new Date()) {
+  const text = new Intl.DateTimeFormat('en-CA', {
+    timeZone: TIMEZONE,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(date instanceof Date ? date : new Date(date));
+  return text.replace(/\D/g, '');
+}
+
+/**
+ * 对比「当前预警清单」与「已推送记录」：
+ *   fresh     本次新出现的（需要推送）
+ *   persisted 之前推过、目前仍在预警的（不重复推）
+ *   restored  之前推过、现在已经不预警的（补货完成，从记录里剔除）
+ */
+function diffAlertState(alerts = [], state = {}) {
+  const notified = state?.notified && typeof state.notified === 'object' ? state.notified : {};
+  const fresh = [];
+  const persisted = [];
+  alerts.forEach((row) => {
+    const skuId = String(row?.skuId || '');
+    if (!skuId) return;
+    if (notified[skuId]) persisted.push(row);
+    else fresh.push(row);
+  });
+  const alertIds = new Set(alerts.map((row) => String(row?.skuId || '')).filter(Boolean));
+  const restored = Object.keys(notified).filter((skuId) => !alertIds.has(skuId));
+  return { fresh, persisted, restored };
+}
+
+/**
+ * 生成下一版「已推送」记录：只保留当前仍在预警的商品。
+ * touch=false 时不刷新 lastNotifiedAt（用于「没有新预警、本轮未真正推送」的场景）。
+ */
+function buildNotifiedSnapshot(alerts = [], state = {}, nowIso, options = {}) {
+  const touch = options.touch !== false;
+  const prev = state?.notified && typeof state.notified === 'object' ? state.notified : {};
+  const next = {};
+  alerts.forEach((row) => {
+    const skuId = String(row?.skuId || '');
+    if (!skuId) return;
+    const old = prev[skuId];
+    const firstNotifiedAt = old?.firstNotifiedAt || nowIso;
+    next[skuId] = {
+      level: row.warningLevel || null,
+      firstNotifiedAt,
+      lastNotifiedAt: touch ? nowIso : (old?.lastNotifiedAt || firstNotifiedAt),
+      dailySale: Number(row.dailySale) || 0,
+      stock: Number(row.stock) || 0,
+    };
+  });
+  return next;
+}
+
+/** 本批商品的指纹 —— 同一天内同一批商品只推一次（服务重启后重复触发也能被通知中心去重） */
+function buildAlertSignature(alerts = []) {
+  const parts = alerts
+    .map((row) => `${String(row?.skuId || '')}:${row?.warningLevel || ''}`)
+    .sort();
+  return crypto.createHash('sha1').update(parts.join('|'), 'utf8').digest('hex').slice(0, 16);
+}
+
+/**
+ * 短板配件文案（见 mkhBomService 文件头 ⑪）：只列「可支配数 ≤ 0」的配件，
+ * 即真正卡住组装的那些，最多 2 个，避免正文过长。
+ */
+function formatShortageNote(row) {
+  const bottlenecks = Array.isArray(row?.bottleneckComponents) ? row.bottleneckComponents : [];
+  const detail = bottlenecks
+    .filter((item) => Number(item?.available) <= 0)
+    .slice(0, 2)
+    .map((item) => {
+      const occupied = Number(item.occupied) || 0;
+      return `${item.code}（库存 ${formatQty(item.stock)}`
+        + `${occupied > 0 ? ` − 加工单占用 ${formatQty(occupied)}` : ''}）`;
+    })
+    .join('、');
+  return detail ? `，短板配件：${detail}` : '';
+}
+
+function describeAlert(row) {
+  // 配件不足（见 mkhBomService 文件头 ⑪）：可组装数 = 0 → 补不出来，
+  // 建议补货量不再给数字（显示「—」），与页面口径保持一致。
+  const replenishText = row.componentShortage ? '建议补货 —' : `建议补货 ${formatQty(row.replenishQty)}`;
+  // 订单驱动（近7日日销=0 但有未发货订单，见 mkhBomService 文件头 ⑩）：
+  // 此时日销必然是 0，直接显示会让人误以为「没销量却要补货」，改展示待发货订单量
+  const metric = row.orderDriven
+    ? `待发货订单 ${formatQty(row.pendingOrderQty)} 件 ｜ 现有库存 ${formatQty(row.stock)} ｜ ${replenishText}（近7日暂无日销，按订单补）`
+    : `日销 ${formatQty(row.dailySale)} ｜ 现有库存 ${formatQty(row.stock)} ｜ ${replenishText}`;
+  const lines = [
+    `**${row.warningLevel === OUT_OF_STOCK ? '🔴 缺货' : '🟠 预警'}** — \`${row.skuId}\``,
+    String(row.productName || '').trim() || '（无名称）',
+    metric,
+  ];
+  if (row.componentShortage) {
+    lines.splice(2, 0, `⚠️ **配件不足，无法补货**（现有配件可组装 ${formatQty(row.assemblableQty)} 台${formatShortageNote(row)}）`);
+  }
+  return lines.join('\n');
+}
+
+function buildMkhReplenishNotification({
+  alerts = [],
+  allAlerts = alerts,
+  snapshot = {},
+  recipientAlias,
+  dateKey,
+}) {
+  const listed = alerts.slice(0, MAX_LISTED_ITEMS);
+  const outOfStockCount = alerts.filter((row) => row.warningLevel === OUT_OF_STOCK).length;
+
+  const totalCount = allAlerts.length || alerts.length;
+  const totalOutOfStock = Number.isFinite(Number(snapshot.outOfStockCount))
+    ? Number(snapshot.outOfStockCount)
+    : allAlerts.filter((row) => row.warningLevel === OUT_OF_STOCK).length;
+  const totalWarningOnly = Number.isFinite(Number(snapshot.warningOnlyCount))
+    ? Number(snapshot.warningOnlyCount)
+    : Math.max(0, totalCount - totalOutOfStock);
+
+  const titleParts = [`MKH 成品补货预警 · 新增 ${alerts.length} 个`];
+  if (outOfStockCount > 0) titleParts.push(`含 ${outOfStockCount} 个已缺货`);
+
+  const blocks = [
+    `**仓库：** 简尚-崔桥工厂品牌仓（MKH 模块化成品）`,
+    `**监控日：** ${snapshot.monitorDate || '—'} ｜ 日销口径：近 ${snapshot.saleWindowDays || 7} 日 ｜ 补货阈值：可用天数低于 ${snapshot.replenishDaysThreshold || 3} 天`,
+    `**本次新增：** ${alerts.length} 个${listed.length < alerts.length ? `（仅列出前 ${listed.length} 个）` : ''}`,
+  ];
+
+  listed.forEach((row, index) => {
+    blocks.push(`**${index + 1}.** ${describeAlert(row)}`);
+  });
+
+  blocks.push(
+    [
+      `---`,
+      `当前共 **${totalCount}** 个 MKH 商品需要补货（缺货 ${totalOutOfStock} ｜ ${snapshot.replenishDaysThreshold || 3}天内预警 ${totalWarningOnly}）。`,
+      `建议补货合计 ${formatQty(snapshot.replenishQtyTotal)} 件。`,
+      Number(snapshot.orderDrivenCount) > 0
+        ? `其中 **${snapshot.orderDrivenCount}** 个近7日无日销、因有未发货订单（合计 ${formatQty(snapshot.pendingOrderQtyTotal)} 件）而列入预警。`
+        : '',
+      Number(snapshot.componentShortageCount) > 0
+        ? `其中 **${snapshot.componentShortageCount}** 个因**配件库存不足**（可组装数 = 0）暂时补不出来，建议补货量显示「—」，需先采购配件。`
+        : '',
+      snapshot.workOrderDegraded === true
+        ? `> ⚠️ 加工单数据源暂不可用，在途量按 0 处理，预警数量可能偏多。`
+        : '',
+      snapshot.pendingOrderDegraded === true
+        ? `> ⚠️ 待发货订单数据源暂不可用，待发货量按 0 处理，可能遗漏「无日销但有订单」的商品。`
+        : '',
+      snapshot.componentStockDegraded === true
+        ? `> ⚠️ 配件库存数据源暂不可用，本次**未做**「配件不足」判定，可能存在补不出来的商品。`
+        : '',
+    ].filter(Boolean).join('\n\n')
+  );
+
+  const actionUrl = String(
+    process.env.MKH_REPLENISH_ALERT_ACTION_URL
+      || 'https://pddg.jiansuntuzhi.cn/planning/operation/mkh-bom-data?scope=warning'
+  ).trim();
+
+  return {
+    idempotencyKey: `mkh_replenish_alert:${recipientAlias}:${dateKey}:${buildAlertSignature(alerts)}:v1`,
+    recipientAlias,
+    title: titleParts.join(' · ').slice(0, 100),
+    content: blocks.join('\n\n').slice(0, 4800),
+    actionTitle: '查看补货清单',
+    actionUrl,
+  };
+}
+
+/**
+ * 执行一次检查。可选参数：
+ *   force   忽略「只推新增」，把当前全部预警商品推一次（手动触发 / 测试用）
+ *   dryRun  只计算不发送，用于预览将推送的内容
+ */
+async function checkMkhReplenishAlerts(options = {}) {
+  const now = options.now === undefined ? new Date() : new Date(options.now);
+  const nowIso = now.toISOString();
+  const dryRun = options.dryRun === true;
+
+  const config = await getMkhReplenishAlertRuntimeConfig({ forceRefresh: true });
+  const snapshot = await listReplenishAlertRows({ scope: config.scope });
+  const alerts = snapshot.rows || [];
+  const state = await loadMkhReplenishAlertState();
+  const { fresh, persisted, restored } = diffAlertState(alerts, state);
+
+  const summary = {
+    scope: snapshot.scope,
+    totalCount: snapshot.totalCount,
+    outOfStockCount: snapshot.outOfStockCount,
+    warningOnlyCount: snapshot.warningOnlyCount,
+    replenishQtyTotal: snapshot.replenishQtyTotal,
+    // 订单驱动（近7日无日销但有未发货订单）的商品数 / 待发货件数，口径见 mkhBomService 文件头 ⑩
+    orderDrivenCount: snapshot.orderDrivenCount,
+    pendingOrderQtyTotal: snapshot.pendingOrderQtyTotal,
+    // 配件不足（可组装数 = 0）的商品数，口径见 mkhBomService 文件头 ⑪
+    componentShortageCount: snapshot.componentShortageCount,
+    freshCount: fresh.length,
+    persistedCount: persisted.length,
+    restoredCount: restored.length,
+    monitorDate: snapshot.monitorDate,
+    workOrderDegraded: snapshot.workOrderDegraded,
+    pendingOrderDegraded: snapshot.pendingOrderDegraded,
+    componentStockDegraded: snapshot.componentStockDegraded,
+  };
+
+  if (!config.enabled) return { sent: false, reason: 'disabled', summary };
+
+  // 预警清空（都补完了）→ 清空已推送记录，下次再预警重新提醒
+  if (!alerts.length) {
+    if (!dryRun) await saveMkhReplenishAlertState({ notified: {}, lastRunAt: nowIso });
+    return { sent: false, reason: 'no_alert', summary };
+  }
+
+  const targets = options.force === true ? alerts : fresh;
+
+  if (!targets.length) {
+    if (!dryRun) {
+      await saveMkhReplenishAlertState({
+        notified: buildNotifiedSnapshot(alerts, state, nowIso, { touch: false }),
+        lastRunAt: nowIso,
+      });
+    }
+    return { sent: false, reason: 'no_new_alert', summary };
+  }
+
+  const recipient = await resolveMkhReplenishAlertRecipient({ config });
+  if (!recipient.alias) return { sent: false, reason: 'recipient_not_configured', summary };
+
+  const payload = buildMkhReplenishNotification({
+    alerts: targets,
+    allAlerts: alerts,
+    snapshot,
+    recipientAlias: recipient.alias,
+    dateKey: chinaDateKey(now),
+  });
+
+  // 预览不受「通知中心是否配置」影响，方便先核对口径
+  if (dryRun) {
+    return {
+      sent: false,
+      reason: 'dry_run',
+      summary,
+      recipient: recipient.alias,
+      recipientSource: recipient.source,
+      payload,
+    };
+  }
+
+  let centerConfig = null;
+  try {
+    centerConfig = await getYydNotificationCenterRuntimeConfig();
+  } catch (_error) {
+    centerConfig = null;
+  }
+  if (!isYydNotificationCenterConfigured(centerConfig)) {
+    return {
+      sent: false,
+      reason: 'notification_center_not_configured',
+      summary,
+      recipient: recipient.alias,
+      payload,
+    };
+  }
+
+  const response = await sendYydNotification(payload);
+  await saveMkhReplenishAlertState({
+    notified: buildNotifiedSnapshot(alerts, state, nowIso),
+    lastRunAt: nowIso,
+  });
+
+  return {
+    sent: true,
+    recipient: recipient.alias,
+    recipientSource: recipient.source,
+    newCount: targets.length,
+    deliveryId: response?.id || response?.data?.id || null,
+    summary,
+  };
+}
+
+async function runMkhReplenishAlertJob(source = 'scheduled', options = {}) {
+  try {
+    const result = await checkMkhReplenishAlerts(options);
+    if (result.sent) {
+      console.log(`[MkhReplenishAlert] ${source} 已推送 ${result.newCount} 个新增预警 → ${result.recipient}`);
+    } else {
+      console.log(`[MkhReplenishAlert] ${source} 跳过推送: ${result.reason}`);
+    }
+    return result;
+  } catch (error) {
+    console.error(`[MkhReplenishAlert] ${source} 执行失败:`, error.message || error);
+    return { sent: false, reason: 'error', error: error.message || String(error) };
+  }
+}
+
+function startMkhReplenishAlertScheduler() {
+  const disabled = String(process.env.DISABLE_MKH_REPLENISH_ALERT || '').trim().toLowerCase() === 'true';
+  if (disabled) {
+    console.log('[Scheduler] MKH 补货预警推送已禁用');
+    return;
+  }
+  const expression = String(process.env.MKH_REPLENISH_ALERT_CRON || DEFAULT_CRON).trim();
+  cron.schedule(expression, () => {
+    runMkhReplenishAlertJob('daily_schedule').catch(() => {});
+  }, { timezone: TIMEZONE });
+
+  const startupTimer = setTimeout(() => {
+    runMkhReplenishAlertJob('startup').catch(() => {});
+  }, STARTUP_DELAY_MS);
+  if (typeof startupTimer.unref === 'function') startupTimer.unref();
+
+  console.log(`[Scheduler] MKH 补货预警推送已注册: ${expression} (${TIMEZONE})`);
+}
+
+module.exports = {
+  DEFAULT_CRON,
+  MAX_LISTED_ITEMS,
+  TIMEZONE,
+  buildAlertSignature,
+  buildMkhReplenishNotification,
+  buildNotifiedSnapshot,
+  checkMkhReplenishAlerts,
+  chinaDateKey,
+  diffAlertState,
+  formatQty,
+  runMkhReplenishAlertJob,
+  startMkhReplenishAlertScheduler,
+};

backend/src/jobs/returnMonitorJob.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const cron = require('node-cron');
+const { runDailyCompare, todayInShanghai } = require('../services/returnMonitorService');
+
+// 每天 07:00（东八区）跑一轮：同步当日退货入库 + 现有库存 + 每日比对核销
+const JOB_CRON = String(process.env.RETURN_MONITOR_CRON || '0 7 * * *').trim();
+const TIMEZONE = 'Asia/Shanghai';
+const LOOKBACK_DAYS = Number(process.env.RETURN_MONITOR_LOOKBACK_DAYS || 3);
+
+async function runReturnMonitorCompare(trigger = 'cron') {
+  const bizDate = todayInShanghai();
+  try {
+    const result = await runDailyCompare({ date: bizDate, trigger, lookbackDays: LOOKBACK_DAYS });
+    console.log(`[ReturnMonitor] 每日比对完成: ${JSON.stringify(result)}`);
+    return result;
+  } catch (error) {
+    console.error('[ReturnMonitor] 每日比对失败:', error.message);
+    throw error;
+  }
+}
+
+function startReturnMonitorScheduler() {
+  if (String(process.env.RETURN_MONITOR_JOB_DISABLED || '').trim().toLowerCase() === 'true') {
+    console.log('[ReturnMonitor] 退货入库核销定时任务已禁用');
+    return;
+  }
+  cron.schedule(JOB_CRON, () => {
+    runReturnMonitorCompare('cron').catch(() => {});
+  }, { timezone: TIMEZONE });
+  console.log(`[Scheduler] 崔桥工厂仓客退库龄核销任务已注册: ${JOB_CRON} (${TIMEZONE})`);
+}
+
+module.exports = { startReturnMonitorScheduler, runReturnMonitorCompare };

backend/src/services/aiBuyerShowReviewService.js

@@ -1,375 +0,0 @@
-const axios = require('axios');
-const database = require('../config/database');
-
-const DEFAULT_REVIEW_TOTAL = 10;
-const REVIEW_TOTAL_OPTIONS = [5, 10, 20, 40, 60, 80, 100];
-const REVIEW_BATCH_SIZE = 5;
-const REVIEW_MAX_CONCURRENCY = 4;
-const REVIEW_MAX_REFILL_ATTEMPTS = 3;
-
-const SUPPORTED_SCENES = [
-  '卧室', '书房', '客厅', '餐厅', '阳台', '入户门', '玄关',
-  '办公室', '户外', '厨房', '电竞房',
-];
-const SUPPORTED_USER_TYPES = [
-  '自己', '妈妈', '爸爸', '儿子', '女儿', '老公', '老婆', '男朋友',
-  '女朋友', '闺蜜', '朋友', '同事', '室友', '老人', '孩子', '学生',
-  '上班族', '租房党', '新婚家庭', '宝妈', '宠物家庭', '客户', '领导',
-];
-
-function normalizeMultiInput(value) {
-  const raw = Array.isArray(value) ? value : String(value || '').split(/[,，、\n\r]+/);
-  return Array.from(new Set(raw.map((item) => String(item || '').trim()).filter(Boolean)));
-}
-
-function normalizeBoolean(value, fallback = true) {
-  if (value === undefined || value === null || value === '') return fallback;
-  if (typeof value === 'boolean') return value;
-  const normalized = String(value).trim().toLowerCase();
-  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
-  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
-  return fallback;
-}
-
-async function getSystemConfigMap(keys) {
-  try {
-    const placeholders = keys.map(() => '?').join(', ');
-    const rows = await database.local.query(
-      `SELECT config_key AS configKey, config_value AS configValue
-       FROM system_config
-       WHERE config_key IN (${placeholders})`,
-      keys
-    );
-    return new Map(rows.map((row) => [row.configKey, String(row.configValue || '').trim()]));
-  } catch (_) {
-    return new Map();
-  }
-}
-
-async function getRuntimeConfig() {
-  const keys = [
-    'ai_buyer_show_ark_api_key',
-    'ai_buyer_show_ark_base_url',
-    'ai_buyer_show_vision_model',
-    'ai_buyer_show_review_model',
-  ];
-  const stored = await getSystemConfigMap(keys);
-  const apiKey = String(process.env.ARK_API_KEY || stored.get(keys[0]) || '').trim();
-  if (!apiKey) {
-    const error = new Error('未配置豆包 ARK_API_KEY，无法生成攻心评价');
-    error.statusCode = 503;
-    throw error;
-  }
-  const baseUrl = process.env.ARK_BASE_URL
-    || stored.get(keys[1])
-    || 'https://ark.cn-beijing.volces.com/api/v3';
-  const visionModel = process.env.VISION_MODEL
-    || stored.get(keys[2])
-    || 'doubao-1-5-vision-pro-32k-250115';
-  const reviewModel = process.env.PDD_HEART_REVIEW_MODEL
-    || process.env.DOUBAO_TEXT_MODEL
-    || stored.get(keys[3])
-    || visionModel;
-  return { apiKey, baseUrl, visionModel, reviewModel };
-}
-
-function buildImageDataUrl(buffer, mimeType) {
-  const type = String(mimeType || '').startsWith('image/') ? mimeType : 'image/jpeg';
-  return `data:${type};base64,${buffer.toString('base64')}`;
-}
-
-function parseJsonContent(content, fallback) {
-  const trimmed = String(content || '')
-    .trim()
-    .replace(/^```json\s*/i, '')
-    .replace(/^```\s*/i, '')
-    .replace(/```$/i, '')
-    .trim();
-  if (!trimmed) return fallback;
-  try {
-    return JSON.parse(trimmed);
-  } catch (_) {
-    const candidate = trimmed.match(/\[[\s\S]*\]/)?.[0]
-      || trimmed.match(/\{[\s\S]*\}/)?.[0];
-    if (!candidate) return fallback;
-    try {
-      return JSON.parse(candidate);
-    } catch (_error) {
-      return fallback;
-    }
-  }
-}
-
-async function callChatCompletion(messages, modelType, options = {}) {
-  const config = await getRuntimeConfig();
-  const model = modelType === 'vision' ? config.visionModel : config.reviewModel;
-  try {
-    const response = await axios.post(
-      `${String(config.baseUrl).replace(/\/$/, '')}/chat/completions`,
-      {
-        model,
-        messages,
-        temperature: options.temperature ?? 0.68,
-        ...(options.maxTokens ? { max_tokens: options.maxTokens } : {}),
-      },
-      {
-        headers: {
-          Authorization: `Bearer ${config.apiKey}`,
-          'Content-Type': 'application/json',
-        },
-        timeout: 180000,
-      }
-    );
-    return {
-      content: response.data?.choices?.[0]?.message?.content || '',
-      model: response.data?.model || model,
-    };
-  } catch (error) {
-    const detail = error.response?.data?.error?.message
-      || error.response?.data?.message
-      || error.response?.data?.error
-      || error.message
-      || 'AI接口调用失败';
-    const wrapped = new Error(`AI接口调用失败：${detail}`);
-    wrapped.statusCode = error.response?.status || 502;
-    throw wrapped;
-  }
-}
-
-async function analyzeImage({ imageBuffer, mimeType, scenes, userTypes, sellingPoints }) {
-  const prompt = [
-    '你是拼多多商品评价运营助手。请识别商品图片，并结合运营填写的信息，严格返回 JSON 对象。',
-    '只返回 JSON，不要 markdown，不要解释。',
-    'JSON 字段：productCategory、productNameGuess、furnitureColors、visualScene、visualSellingPoints、userPainPoints、emotionalAngles。',
-    `运营选择场景：${scenes.length ? scenes.join('、') : '未填写，请根据图片判断最合适场景'}`,
-    `运营选择使用人：${userTypes.length ? userTypes.join('、') : '自己购买给自己使用'}`,
-    `运营填写卖点：${sellingPoints}`,
-  ].join('\n');
-  const result = await callChatCompletion([{
-    role: 'user',
-    content: [
-      { type: 'text', text: prompt },
-      { type: 'image_url', image_url: { url: buildImageDataUrl(imageBuffer, mimeType) } },
-    ],
-  }], 'vision');
-  return { analysis: parseJsonContent(result.content, {}), model: result.model };
-}
-
-function normalizeReviewText(value) {
-  return String(value || '').replace(/\s+/g, ' ').replace(/^["'“”]+|["'“”]+$/g, '').trim();
-}
-
-function stripEmoji(value) {
-  return String(value || '')
-    .replace(/[\u{1F000}-\u{1FAFF}\u{2600}-\u{27BF}]/gu, '')
-    .replace(/\p{Extended_Pictographic}/gu, '')
-    .replace(/[\u{FE0E}\u{FE0F}\u{200D}]/gu, '')
-    .replace(/\s{2,}/g, ' ')
-    .trim();
-}
-
-function normalizeReviewItem(value, useEmoji) {
-  const source = typeof value === 'string' ? { reviewContent: value } : (value || {});
-  const reviewContent = normalizeReviewText(
-    source.reviewContent || source.content || source.text || source.review || source['评价内容']
-  );
-  if (!reviewContent) return null;
-  return {
-    reviewContent: useEmoji ? reviewContent : stripEmoji(reviewContent),
-    userType: normalizeReviewText(source.userType || source.user || source.person || source['使用人']),
-    sellingPoint: normalizeReviewText(source.sellingPoint || source.selling_points || source.point || source['突出卖点']),
-    scene: normalizeReviewText(source.scene || source.usageScene || source['使用场景']),
-  };
-}
-
-function parseReviews(content, useEmoji) {
-  const parsed = parseJsonContent(content, null);
-  const source = Array.isArray(parsed) ? parsed : (Array.isArray(parsed?.reviews) ? parsed.reviews : []);
-  if (source.length) return source.map((item) => normalizeReviewItem(item, useEmoji)).filter(Boolean);
-  return String(content || '')
-    .split(/\n+/)
-    .map((line) => line.replace(/^\s*(\d+[.、)]|[-*])\s*/, ''))
-    .filter((line) => line.trim().length >= 30)
-    .map((line) => normalizeReviewItem(line, useEmoji))
-    .filter(Boolean);
-}
-
-function dedupeReviews(reviews) {
-  const seen = new Set();
-  return reviews.filter((review) => {
-    const key = review.reviewContent.replace(/[，。！？,.!?\s]/g, '').slice(0, 80);
-    if (!key || seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}
-
-function diversifyOpenings(reviews) {
-  const counts = new Map();
-  const replacements = {
-    '说实话': ['其实，', '老实讲，', '用下来，'],
-    '本来': ['一开始', '之前', '原先'],
-    '我是': ['家里', '最近', '买回来后'],
-  };
-  return reviews.map((review) => {
-    const opening = Object.keys(replacements).find((item) => review.reviewContent.startsWith(item));
-    if (!opening) return review;
-    const used = counts.get(opening) || 0;
-    counts.set(opening, used + 1);
-    if (used === 0 && opening !== '我是') return review;
-    return {
-      ...review,
-      reviewContent: review.reviewContent.replace(
-        new RegExp(`^${opening}[，,、\s]*`),
-        replacements[opening][used % replacements[opening].length]
-      ),
-    };
-  });
-}
-
-async function generateReviewBatch({ count, batchIndex, scenes, userTypes, sellingPoints, analysis, useEmoji }) {
-  const colors = normalizeMultiInput(analysis?.furnitureColors || analysis?.colors);
-  const prompt = [
-    '生成拼多多家具真实买家评价。',
-    `1. 本批生成 ${count} 条。`,
-    '2. 每条 50-200 个中文字符。',
-    '3. 真实买家口吻，不要广告腔，不要出现“攻心”“卖点”“AI”。',
-    '4. 角度要有差异，覆盖使用前顾虑、场景、到手体验、细节、家人反馈。',
-    '5. 不要夸张承诺，不要医疗功效，不要绝对化表达。',
-    '6. 场景和使用人自然交叉组合。',
-    `7. 家具颜色只能使用这些图片识别颜色：${colors.length ? colors.join('、') : '未识别到颜色时不要主动描写颜色'}。`,
-    '8. 文风口语化，像真实用户随手写的评价，不要整齐的产品说明书语气。',
-    useEmoji
-      ? '9. 允许少量使用 emoji，每条最多 0-2 个，不要每条都必须有。'
-      : '9. 严禁使用任何 emoji、颜文字或表情符号，一个都不要出现。',
-    '10. 只返回 JSON 数组，每个元素字段固定：reviewContent、userType、sellingPoint、scene。',
-    '11. 同一批开头必须分散，尽量不要使用“我是、本来、说实话、一开始、之前、之前还担心”开头。',
-    `批次：${batchIndex}`,
-    `可用场景：${scenes.length ? scenes.join('、') : analysis?.visualScene || '按图片判断'}`,
-    `可用使用人：${userTypes.length ? userTypes.join('、') : '自己购买给自己使用'}`,
-    `运营填写卖点：${sellingPoints}`,
-    `图片识别信息：${JSON.stringify(analysis || {})}`,
-  ].join('\n');
-  const result = await callChatCompletion([{ role: 'user', content: prompt }], 'review', {
-    maxTokens: Math.min(4096, 240 * count),
-  });
-  return { reviews: parseReviews(result.content, useEmoji), prompt, model: result.model };
-}
-
-async function runWithLimit(tasks, limit, onResult) {
-  let cursor = 0;
-  async function worker() {
-    while (cursor < tasks.length) {
-      const index = cursor;
-      cursor += 1;
-      const result = await tasks[index]();
-      onResult(result, index);
-    }
-  }
-  await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, () => worker()));
-}
-
-async function generateHeartReviews({
-  imageBuffer, mimeType, scene, userType, sellingPoints, useEmoji, reviewTotal, onEvent,
-}) {
-  const startedAt = Date.now();
-  const scenes = normalizeMultiInput(scene).filter((item) => SUPPORTED_SCENES.includes(item));
-  const userTypes = normalizeMultiInput(userType).filter((item) => SUPPORTED_USER_TYPES.includes(item));
-  const effectiveUserTypes = userTypes.length ? userTypes : ['自己购买给自己使用'];
-  const normalizedSellingPoints = String(sellingPoints || '').trim();
-  const targetTotal = REVIEW_TOTAL_OPTIONS.includes(Number(reviewTotal))
-    ? Number(reviewTotal)
-    : DEFAULT_REVIEW_TOTAL;
-  const normalizedUseEmoji = normalizeBoolean(useEmoji, true);
-  if (!normalizedSellingPoints) {
-    const error = new Error('请填写商品卖点');
-    error.statusCode = 400;
-    throw error;
-  }
-
-  const vision = await analyzeImage({
-    imageBuffer, mimeType, scenes, userTypes: effectiveUserTypes, sellingPoints: normalizedSellingPoints,
-  });
-  onEvent?.({ type: 'analysis', imageAnalysis: vision.analysis });
-
-  let reviews = [];
-  let reviewPrompt = '';
-  let reviewModel = '';
-  const append = (batch) => {
-    if (!reviewPrompt) reviewPrompt = batch.prompt;
-    if (!reviewModel) reviewModel = batch.model;
-    reviews = dedupeReviews(diversifyOpenings([...reviews, ...batch.reviews])).slice(0, targetTotal);
-    onEvent?.({ type: 'batch', total: reviews.length, targetTotal });
-  };
-  const makeTasks = (count, prefix) => Array.from({ length: Math.ceil(count / REVIEW_BATCH_SIZE) }, (_, index) => {
-    const batchCount = Math.min(REVIEW_BATCH_SIZE, count - index * REVIEW_BATCH_SIZE);
-    return () => generateReviewBatch({
-      count: batchCount,
-      batchIndex: `${prefix}${index + 1}`,
-      scenes: scenes.length ? scenes : [vision.analysis?.visualScene].filter(Boolean),
-      userTypes: effectiveUserTypes,
-      sellingPoints: normalizedSellingPoints,
-      analysis: vision.analysis,
-      useEmoji: normalizedUseEmoji,
-    });
-  });
-
-  await runWithLimit(makeTasks(targetTotal, ''), REVIEW_MAX_CONCURRENCY, append);
-  for (let attempt = 1; reviews.length < targetTotal && attempt <= REVIEW_MAX_REFILL_ATTEMPTS; attempt += 1) {
-    await runWithLimit(makeTasks(targetTotal - reviews.length, `补充${attempt}-`), REVIEW_MAX_CONCURRENCY, append);
-  }
-  if (reviews.length < targetTotal) {
-    const error = new Error(`AI返回评价数量不足，仅生成 ${reviews.length} 条，请重试`);
-    error.statusCode = 502;
-    throw error;
-  }
-
-  return {
-    scene: scenes.length ? scenes.join('、') : (vision.analysis?.visualScene || 'AI识别场景'),
-    scenes,
-    userTypes: effectiveUserTypes,
-    sellingPoints: normalizedSellingPoints,
-    useEmoji: normalizedUseEmoji,
-    imageAnalysis: vision.analysis,
-    reviewPrompt,
-    reviews: reviews.slice(0, targetTotal),
-    total: targetTotal,
-    targetTotal,
-    responseMs: Date.now() - startedAt,
-    models: { vision: vision.model, review: reviewModel },
-  };
-}
-
-function buildBuyerShowPrompt({ review, analysis, style = '真实' }) {
-  const normalizedStyle = style === '饱和' ? '饱和' : '真实';
-  const productHints = normalizeMultiInput([
-    analysis?.productCategory,
-    analysis?.productNameGuess,
-    ...(Array.isArray(analysis?.visualSellingPoints) ? analysis.visualSellingPoints : []),
-  ]).join('、');
-  const styleRule = normalizedStyle === '饱和'
-    ? '画面可以更精致、饱满、明亮，接近小红书达人分享风格，但商品主体仍必须真实可信，不能变成棚拍硬广、样板间或3D渲染图。'
-    : '普通买家用手机随手拍的真实照片，生活气息强，略微随意，普通室内自然光，不要商业摄影感、样板间、卖场图或渲染图。';
-  return [
-    `根据上传的商品参考图和下面这条买家评价，生成${normalizedStyle}风格的买家秀图片。系统会分 5 次生成 5 张单图，每次只生成其中一张照片。`,
-    `当前风格：${normalizedStyle}`,
-    '硬性要求：必须以参考图里的商品为唯一主体，严格保持商品外观、颜色、材质、比例、结构、边角、五金、纹理、开孔、抽屉、柜门、支脚、轮子等全部产品细节不变。不能改款、变形、新增或删减部件。商品参考图仅用于锁定商品本体，不允许沿用其房间、背景、软装和场景。',
-    '家具结构数量限制：柜体、柜门、抽屉、层板、支脚、把手、开孔、轮子、拉篮和五金件数量、位置、比例必须与参考图一致。',
-    '组图要求：5 张结果图必须像同一位买家在同一个房间、同一个时间围绕同一个商品连续拍摄。整体规划为 2 张完整商品照片 + 3 张局部细节照片。禁止拼图、分屏、九宫格和多画面排版。',
-    `买家评价：${review.reviewContent || ''}`,
-    `使用人：${review.userType || '按评价自然判断'}`,
-    `使用场景：${review.scene || '按评价自然判断'}`,
-    `突出卖点：${review.sellingPoint || '按评价自然提炼'}`,
-    productHints ? `图片识别到的商品信息：${productHints}` : '',
-    `${styleRule} 如果上传了场景参考图，必须以它作为唯一主要场景依据，尽量保留房间类型、空间布局、墙面地面、窗户、非主体家具、软装、生活物品、光线氛围和模特姿态；只有冲突或遮挡商品主体的元素才可轻微调整。没有场景参考图时，才根据评价重新构建生活化场景。场景适合时最好需要有中国模特自然出镜，不能露脸，不能遮挡商品。输出 4:3，1K。`,
-  ].filter(Boolean).join('\n');
-}
-
-module.exports = {
-  DEFAULT_REVIEW_TOTAL,
-  REVIEW_TOTAL_OPTIONS,
-  SUPPORTED_SCENES,
-  SUPPORTED_USER_TYPES,
-  buildBuyerShowPrompt,
-  generateHeartReviews,
-};

backend/src/services/aiBuyerShowSeedPackService.js

@@ -1,237 +0,0 @@
-const crypto = require('crypto');
-const {
-  getPool,
-  query,
-  resolveUser,
-} = require('./aiBuyerShowService');
-const { uploadBufferToDefaultS3 } = require('./objectStorage');
-
-const SEED_PACK_TABLE = 'pdd_seed_resource_packs';
-const MAX_SEED_PACK_FILE_BYTES = 200 * 1024 * 1024;
-
-let tableReady = false;
-
-function normalizeString(value) {
-  return String(value || '').trim();
-}
-
-function normalizeNullableString(value) {
-  const text = normalizeString(value);
-  return text || null;
-}
-
-// multer/busboy may decode multipart filenames as latin1, garbling non-ASCII
-// names; re-encode to recover the original UTF-8 text.
-function normalizeUploadFileName(value) {
-  const text = normalizeString(value);
-  if (!text) return '';
-  try {
-    const decoded = Buffer.from(text, 'latin1').toString('utf8');
-    return /[\uFFFD]/.test(decoded) ? text : decoded;
-  } catch (_) {
-    return text;
-  }
-}
-
-async function ensureSeedPackTable() {
-  if (tableReady) return;
-  await query(
-    `CREATE TABLE IF NOT EXISTS ${SEED_PACK_TABLE} (
-      id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '资源包ID',
-      pack_uid VARCHAR(64) NOT NULL COMMENT '资源包唯一标识',
-      shop_name VARCHAR(128) NOT NULL COMMENT '店铺名称',
-      product_id VARCHAR(64) NOT NULL COMMENT '商品ID',
-      sku_name VARCHAR(255) NULL COMMENT 'SKU名称',
-      file_name VARCHAR(255) NOT NULL COMMENT 'ZIP文件名',
-      file_size BIGINT NOT NULL DEFAULT 0 COMMENT '文件大小(字节)',
-      object_key VARCHAR(512) NOT NULL COMMENT '对象存储Key',
-      file_url VARCHAR(1024) NULL COMMENT '公开下载地址',
-      review_count INT NOT NULL DEFAULT 0 COMMENT '包含评价条数',
-      operator_id VARCHAR(64) NULL COMMENT '上传人ID',
-      operator_name VARCHAR(128) NOT NULL DEFAULT '' COMMENT '上传人',
-      download_count INT NOT NULL DEFAULT 0 COMMENT '下载次数',
-      created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '上传时间',
-      updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
-      UNIQUE KEY uk_pack_uid (pack_uid),
-      KEY idx_seed_pack_shop (shop_name),
-      KEY idx_seed_pack_product (product_id),
-      KEY idx_seed_pack_created (created_at)
-    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='种菜资源包'`
-  );
-  tableReady = true;
-}
-
-function normalizePackRow(row = {}) {
-  return {
-    id: Number(row.id),
-    packUid: row.pack_uid ?? row.packUid ?? '',
-    shopName: row.shop_name ?? row.shopName ?? '',
-    productId: row.product_id ?? row.productId ?? '',
-    skuName: row.sku_name ?? row.skuName ?? '',
-    fileName: row.file_name ?? row.fileName ?? '',
-    fileSize: Number(row.file_size ?? row.fileSize ?? 0),
-    fileUrl: row.file_url ?? row.fileUrl ?? '',
-    reviewCount: Number(row.review_count ?? row.reviewCount ?? 0),
-    operatorName: row.operator_name ?? row.operatorName ?? '',
-    downloadCount: Number(row.download_count ?? row.downloadCount ?? 0),
-    createdAt: row.created_at || null,
-  };
-}
-
-function validateSeedPackInput({ shopName, productId, file }) {
-  if (!normalizeString(shopName)) {
-    const error = new Error('店铺名称不能为空');
-    error.statusCode = 400;
-    return error;
-  }
-  if (!normalizeString(productId)) {
-    const error = new Error('商品ID不能为空');
-    error.statusCode = 400;
-    return error;
-  }
-  if (!file?.buffer || !file.buffer.length) {
-    const error = new Error('ZIP 文件不能为空');
-    error.statusCode = 400;
-    return error;
-  }
-  if (file.buffer.length > MAX_SEED_PACK_FILE_BYTES) {
-    const error = new Error('ZIP 文件不能超过 200MB');
-    error.statusCode = 413;
-    return error;
-  }
-  return null;
-}
-
-async function createSeedPack({ shopName, productId, skuName, fileName, reviewCount, file }, user = {}) {
-  await ensureSeedPackTable();
-  const operator = resolveUser(user);
-  const validationError = validateSeedPackInput({ shopName, productId, file });
-  if (validationError) throw validationError;
-
-  const uploaded = await uploadBufferToDefaultS3(
-    file.buffer,
-    'application/zip',
-    'seed-packs',
-    'zip'
-  );
-
-  const resolvedFileName = normalizeString(fileName)
-    || normalizeUploadFileName(file?.originalname)
-    || `种菜资源包_${Date.now()}.zip`;
-
-  const packUid = crypto.randomUUID();
-  const insertRows = await query(
-    `INSERT INTO ${SEED_PACK_TABLE} (
-       pack_uid, shop_name, product_id, sku_name, file_name, file_size,
-       object_key, file_url, review_count, operator_id, operator_name
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    [
-      packUid,
-      normalizeString(shopName).slice(0, 128),
-      normalizeString(productId).slice(0, 64),
-      normalizeNullableString(String(skuName || '').slice(0, 255)),
-      resolvedFileName.slice(0, 255),
-      file.buffer.length,
-      uploaded.key,
-      uploaded.url || '',
-      Math.max(Number(reviewCount) || 0, 0),
-      operator.id || null,
-      operator.name,
-    ]
-  );
-
-  const rows = await query(
-    `SELECT * FROM ${SEED_PACK_TABLE} WHERE id = ? LIMIT 1`,
-    [insertRows.insertId]
-  );
-  return normalizePackRow(rows[0]);
-}
-
-async function listSeedPacks({ page = 1, pageSize = 15, keyword = '' } = {}) {
-  await ensureSeedPackTable();
-  const normalizedPage = Math.max(Number(page) || 1, 1);
-  const normalizedPageSize = Math.min(Math.max(Number(pageSize) || 15, 1), 100);
-  const offset = (normalizedPage - 1) * normalizedPageSize;
-  const normalizedKeyword = normalizeString(keyword);
-  const likeKeyword = `%${normalizedKeyword}%`;
-  const whereSql = normalizedKeyword
-    ? 'WHERE shop_name LIKE ? OR product_id LIKE ? OR sku_name LIKE ? OR operator_name LIKE ? OR file_name LIKE ?'
-    : '';
-  const params = normalizedKeyword ? Array(5).fill(likeKeyword) : [];
-
-  const countRows = await query(
-    `SELECT COUNT(*) AS total FROM ${SEED_PACK_TABLE} ${whereSql}`,
-    params
-  );
-  const rows = await query(
-    `SELECT * FROM ${SEED_PACK_TABLE}
-     ${whereSql}
-     ORDER BY id DESC
-     LIMIT ? OFFSET ?`,
-    [...params, normalizedPageSize, offset]
-  );
-
-  return {
-    rows: rows.map(normalizePackRow),
-    total: Number(countRows[0]?.total || 0),
-    page: normalizedPage,
-    pageSize: normalizedPageSize,
-  };
-}
-
-async function getSeedPackDownload(id) {
-  await ensureSeedPackTable();
-  const packId = Number(id);
-  if (!Number.isFinite(packId) || packId <= 0) {
-    const error = new Error('资源包不存在');
-    error.statusCode = 404;
-    throw error;
-  }
-  const rows = await query(
-    `SELECT * FROM ${SEED_PACK_TABLE} WHERE id = ? LIMIT 1`,
-    [packId]
-  );
-  const pack = rows[0];
-  if (!pack) {
-    const error = new Error('资源包不存在');
-    error.statusCode = 404;
-    throw error;
-  }
-  await query(
-    `UPDATE ${SEED_PACK_TABLE} SET download_count = download_count + 1 WHERE id = ?`,
-    [packId]
-  );
-  return {
-    ...normalizePackRow(pack),
-    downloadCount: Number(pack.downloadCount || 0) + 1,
-  };
-}
-
-async function deleteSeedPack(id) {
-  await ensureSeedPackTable();
-  const packId = Number(id);
-  if (!Number.isFinite(packId) || packId <= 0) {
-    const error = new Error('资源包不存在');
-    error.statusCode = 404;
-    throw error;
-  }
-  const rows = await query(
-    `SELECT id FROM ${SEED_PACK_TABLE} WHERE id = ? LIMIT 1`,
-    [packId]
-  );
-  if (!rows.length) {
-    const error = new Error('资源包不存在');
-    error.statusCode = 404;
-    throw error;
-  }
-  await query(`DELETE FROM ${SEED_PACK_TABLE} WHERE id = ?`, [packId]);
-  return { id: packId };
-}
-
-module.exports = {
-  createSeedPack,
-  deleteSeedPack,
-  getSeedPackDownload,
-  listSeedPacks,
-  MAX_SEED_PACK_FILE_BYTES,
-};

backend/src/services/csQualityAiPrompt.js

@@ -1,111 +0,0 @@
-'use strict';
-
-const PRE_SALE_LABELS = [
-  '库存备货：是否有货',
-  '发货问题：发货地、发货速度、缺货问题、催发货、延期发货',
-  '批量外贸单：贴唛头',
-  '快递问题：是否包邮、指定快递、送货上门、物流速度、配送速度、到货时间',
-  '产品问题：是否防潮/防火、是否有背板/轨道、材质的区别、产地问题、质保时效、尺寸问题、板材厚度、是否支持定制、承重性',
-  '产品环保问题：检测报告、气味问题',
-  '价格问题：优惠券问题、买后比价、商品降价',
-  '下单错误：多拍错拍、地址/电话信息错误',
-  '决策信息不充分：尺码/尺寸/规格不合适',
-  '安装问题：安装说明书/安装视频、是否包安装、是否整装发货',
-  '发票问题：是否有发票、多开/少开发票、催发票',
-];
-
-const AFTER_SALE_LABELS = [
-  '发货履约问题：发货异常、虚假发货',
-  '物流配送问题：更新超时、丢件、派送超时、送货异常、退货到仓',
-  '商品交付问题：少发漏发、错发、运输产品破损',
-  '商品质量问题：产品质量、描述不符',
-  '安装服务问题：安装咨询、上门安装',
-  '客服服务问题：回复超时、服务态度极差、承诺未履行、操作错误',
-  '退换货问题：上门取件',
-  '平台业务问题：铺货错误、种菜异常',
-  '其他售后：其他',
-];
-
-function buildSystemPrompt() {
-  return [
-    '你是拼多多电商客服聊天质检与商品问题分析专家。',
-    '你的任务是分析一个商品ID在指定日期范围内的全部客服聊天，识别售前和售后诉求，并把结果聚合成可用于产品改进、详情页优化和售后管理的结构化数据。',
-    '',
-    '【发言方识别】',
-    '1. 每条消息已经提供“买家”或“客服”角色，优先使用该角色。',
-    '2. 客服寒暄、安抚、礼貌语和标准话术不能单独作为证据；客服明确确认已超时、已登记、已拒绝、承诺未履行时可辅助举证。',
-    '3. 归因以买家诉求为主，不能把客服建议或猜测当成买家问题。',
-    '',
-    '【售前/售后判定】',
-    '1. 出现“订单编号：xxx”“订单号：xxx”或订单卡片后，从该位置开始的后续买家内容按售后语境处理；之前内容独立判断。',
-    '2. 未出现订单号时，根据语义判断：下单前的购买决策咨询属于售前；已付款、已收货或明确反馈已发生问题属于售后。',
-    '3. “多久发货”在下单前是售前；“为什么还不发货”或“催发货”通常是售后。',
-    '4. 同一诉求无法区分时售后优先。否定、假设、举例、转述他人或已经解决的问题不能作为当前问题。',
-    '',
-    '【售前标签白名单】',
-    ...PRE_SALE_LABELS,
-    '售前无法匹配时使用 primary_reason=“未知”、secondary_reason=“其他问题”。',
-    '',
-    '【售后标签白名单】',
-    ...AFTER_SALE_LABELS,
-    '售后无法匹配时使用 primary_reason=“其他售后”、secondary_reason=“其他”。',
-    '',
-    '【标签边界】',
-    '商品与页面描述、宣传或明确承诺不一致，使用“商品质量问题/描述不符”；商品本身缺陷、故障、开裂、变形，使用“商品质量问题/产品质量”；发错型号、款式、颜色或规格，使用“商品交付问题/错发”；缺少商品或配件，使用“商品交付问题/少发漏发”；运输造成磕碰、断裂或包装损坏，使用“商品交付问题/运输产品破损”。',
-    '',
-    '【聚合规则】',
-    '1. 相同一级原因+二级原因的诉求合并为一条结果，统计 occurrence_count 和 affected_customer_count。',
-    '2. 不同语义的独立问题分别输出，例如少发漏发和运输破损不能合并。',
-    '3. 每条结果最多保留3条最有代表性的买家原话证据，证据不得改写或拼接。',
-    '4. affected_conversation_ids 必须列出当前问题涉及的全部会话ID（uid），不得只列关键证据中的客户，也不得填入无关客户。',
-    '5. 买家消息中的图片URL只提取与当前问题直接相关的图片，每条结果最多5张，必须原样保留。',
-    '6. product_improvement_areas只能从：产品本体、规格配置、宣传主图、详情页、客服话术、价格策略、库存备货、履约物流、安装服务、售后服务、无需改进 中选择。',
-    '',
-    '【严格输出】',
-    '只能输出合法JSON，不要输出Markdown代码块、解释或额外文字。JSON结构必须是：',
-    JSON.stringify({
-      schema_version: '1.0',
-      conversation_type: '售前|售后|混合|无有效咨询',
-      summary: {
-        conversation_count: 0,
-        pre_sale_conversation_count: 0,
-        after_sale_conversation_count: 0,
-        mixed_conversation_count: 0,
-        main_findings: [],
-      },
-      results: [{
-        consultation_type: '售前|售后',
-        primary_reason: '一级原因',
-        secondary_reason: '二级原因',
-        occurrence_count: 1,
-        affected_customer_count: 1,
-        affected_conversation_ids: ['uid'],
-        buyer_intent: '买家诉求概括',
-        evidence: [{ conversation_id: 'uid', nickname: '买家昵称', message_time: '消息时间', text: '买家原文' }],
-        image_urls: [],
-        product_improvement_areas: [],
-        improvement_suggestion: '',
-        confidence: 0.95,
-      }],
-    }, null, 2),
-  ].join('\n');
-}
-
-function buildUserPrompt({ product = {}, metrics = {}, chatText = '', startDate, endDate }) {
-  return [
-    `请分析商品ID：${product.goodsId || ''}`,
-    `商品名称：${product.goodsName || ''}`,
-    `所属店铺：${product.shopName || ''}`,
-    `图片地址：${product.hdThumbUrl || ''}`,
-    `分析日期：${startDate} 至 ${endDate}`,
-    `商品表现指标：${JSON.stringify(metrics)}`,
-    '',
-    '以下是该商品在指定日期范围内的聊天记录。每条记录已经标注角色，请结合上下文完成售前/售后识别、标签映射和问题聚合。',
-    chatText,
-  ].join('\n');
-}
-
-module.exports = {
-  buildSystemPrompt,
-  buildUserPrompt,
-};

backend/src/services/dailyInventoryFlows.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * 每日进销存 —— 流水列取数（业务库原生口径）
+ *
+ * 业务库 JSReportReplica 能还原的 4 个流水列（其余 8 列缺单据表，保持「—」）：
+ *   采购进仓(+):  rpt.jst_purchase × jst_purchaseItem，按 po_date，状态 Confirmed/Finished，取明细 qty
+ *                 （明细 inQty 全为 0 未同步，故用 qty）
+ *   采购退货(−):  rpt.jst_purchaseout × jst_purchaseoutItem，按 io_date
+ *   销售出仓(−):  rpt.jst_Orders × jst_OrderItem，按 send_date，排除 Delete/Cancelled
+ *                 （与「库存周转天数」的发货口径一致；与聚水潭进销存导出的出库单口径有偏差，
+ *                   因为销售出库单明细数量在业务库未同步，无法精确还原）
+ *   销售退货(+):  rpt.jst_returnAndRefundInfo × jst_returnAndRefundItem，按 as_date，
+ *                 类型限定 普通退货/拒收退货/换货/维修，取明细 r_qty（实收数量；
+ *                 qty 字段大多未同步，不能用）
+ *
+ * 符号约定与页面一致：流入为正、流出为负（前端负数标红）。
+ * 因为还有 8 类单据（调拨/盘点/加工/其它出入库）在业务库无表，
+ * 「期末 ≠ 期初 + 流水之和」，差值即缺失单据的影响。
+ */
+
+const FLOW_QUERIES = [
+  {
+    field: 'purchaseIn',
+    sign: 1,
+    sql: `
+      SELECT p.wms_co_id AS wmsCoId,
+             SUM(CAST(ISNULL(pi.qty, 0) AS DECIMAL(18, 2))) AS qty
+        FROM rpt.jst_purchase p
+        JOIN rpt.jst_purchaseItem pi ON pi.po_id = p.po_id
+       WHERE p.wms_co_id IN (%WAREHOUSES%)
+         AND p.po_date >= @from
+         AND ISNULL(p.status, '') IN ('Confirmed', 'Finished')
+       GROUP BY p.wms_co_id`,
+  },
+  {
+    field: 'purchaseReturn',
+    sign: -1,
+    sql: `
+      SELECT o.wms_co_id AS wmsCoId,
+             SUM(CAST(ISNULL(oi.qty, 0) AS DECIMAL(18, 2))) AS qty
+        FROM rpt.jst_purchaseout o
+        JOIN rpt.jst_purchaseoutItem oi ON oi.io_id = o.io_id
+       WHERE o.wms_co_id IN (%WAREHOUSES%)
+         AND o.io_date >= @from
+       GROUP BY o.wms_co_id`,
+  },
+  {
+    field: 'salesOut',
+    sign: -1,
+    sql: `
+      SELECT o.wms_co_id AS wmsCoId,
+             SUM(CAST(ISNULL(oi.qty, 0) AS DECIMAL(18, 2))) AS qty
+        FROM rpt.jst_Orders o
+        JOIN rpt.jst_OrderItem oi ON oi.o_id = o.o_id
+       WHERE o.wms_co_id IN (%WAREHOUSES%)
+         AND o.send_date >= @from
+         AND ISNULL(o.status, '') NOT IN ('Delete', 'Cancelled')
+       GROUP BY o.wms_co_id`,
+  },
+  {
+    field: 'salesReturn',
+    sign: 1,
+    sql: `
+      SELECT r.wms_co_id AS wmsCoId,
+             SUM(CAST(ISNULL(ri.r_qty, 0) AS DECIMAL(18, 2))) AS qty
+        FROM rpt.jst_returnAndRefundInfo r
+        JOIN rpt.jst_returnAndRefundItem ri ON ri.as_id = r.as_id
+       WHERE r.wms_co_id IN (%WAREHOUSES%)
+         AND r.as_date >= @from
+         AND ISNULL(r.type, '') IN (N'普通退货', N'拒收退货', N'换货', N'维修')
+       GROUP BY r.wms_co_id`,
+  },
+];
+
+/** mssql 不支持数组参数，按位展开成 @p0,@p1... */
+function buildInClause(values, prefix) {
+  const params = {};
+  const clause = values
+    .map((v, i) => {
+      params[`${prefix}${i}`] = v;
+      return `@${prefix}${i}`;
+    })
+    .join(',');
+  return { clause, params };
+}
+
+/** 业务库可还原的流水字段（带符号：流入 +1 / 流出 −1） */
+const AVAILABLE_FLOW_FIELDS = FLOW_QUERIES.map((q) => q.field);
+
+/**
+ * 拉取自 fromText（含）以来各仓的流水合计。
+ * @returns {Promise<Map<string, Object>>} key = wmsCoId 字符串，value = { purchaseIn, purchaseReturn, salesOut, salesReturn }（带符号，无记录的字段不出现）
+ */
+async function fetchFlows(cloudDb, wmsCoIds, fromText) {
+  if (!cloudDb || typeof cloudDb.query !== 'function') {
+    throw new TypeError('fetchFlows 第一个参数必须是数据库实例（防呆：调用漏传 cloudDb 时立即报错而非静默返回空）');
+  }
+  const map = new Map();
+  if (!wmsCoIds.length || !fromText) return map;
+  for (const q of FLOW_QUERIES) {
+    const { clause, params } = buildInClause(wmsCoIds, 'w');
+    const sqlText = q.sql.replace('%WAREHOUSES%', clause);
+    const rows = await cloudDb.query(sqlText, { ...params, from: fromText }, { requestTimeout: 120000 });
+    for (const r of rows) {
+      const key = String(r.wmsCoId);
+      const entry = map.get(key) || {};
+      const qty = Number(r.qty) || 0;
+      entry[q.field] = q.sign * qty;
+      map.set(key, entry);
+    }
+  }
+  return map;
+}
+
+module.exports = {
+  AVAILABLE_FLOW_FIELDS,
+  FLOW_QUERIES,
+  fetchFlows,
+  buildInClause,
+};

backend/src/services/dailyInventoryNotificationSettings.js

@@ -0,0 +1,330 @@
+'use strict';
+
+// 每日进销存 · 定时截图通知 —— 配置 + 执行记录 + 幂等记录（本地库 system_config）
+//
+// ── 配置键 daily_inventory_notification_config ────────────────────
+//   { enabled, notifyTime: 'HH:mm', recipients: ['张三', '李四'] }
+//
+// ── 状态键 daily_inventory_notification_state ──────────────────────
+//   { version, notified: { 'YYYY-MM-DD': { '别名': { notifiedAt, deliveryId } } }, runs: [...] }
+//   · notified 用于「同一业务日期 + 同一用户只成功通知一次」的幂等判断
+//   · runs 保留最近 N 次执行明细，供管理员在页面查询
+//
+// 安全约定：本文件对外只返回「是否已配置」这类布尔值与脱敏预览，
+//          绝不返回通知中心 projectSecret、对象存储 secretAccessKey 等密钥。
+
+const database = require('../config/database');
+const {
+  getYydNotificationCenterRuntimeConfig,
+  toAdminConfig: toNotificationCenterAdminConfig,
+} = require('./yydNotificationCenterSettings');
+const { getDefaultS3Config } = require('./objectStorage');
+
+const CONFIG_KEY = 'daily_inventory_notification_config';
+const STATE_KEY = 'daily_inventory_notification_state';
+
+const DEFAULT_NOTIFY_TIME = '01:00';
+const TIMEZONE = 'Asia/Shanghai';
+const MAX_RECIPIENTS = 20;
+const MAX_RECIPIENT_LENGTH = 50;
+const MAX_RUN_RECORDS = 30;
+const CONFIG_CACHE_TTL_MS = 30 * 1000;
+
+let cachedConfig = null;
+let cachedAt = 0;
+
+function normalizeText(value, maxLength = 200) {
+  return String(value ?? '').trim().slice(0, maxLength);
+}
+
+function safeJsonParse(value, fallback = {}) {
+  if (value && typeof value === 'object') return value;
+  try {
+    const parsed = JSON.parse(String(value || ''));
+    return parsed && typeof parsed === 'object' ? parsed : fallback;
+  } catch (_error) {
+    return fallback;
+  }
+}
+
+function normalizeFlag(value, fallback = false) {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (typeof value === 'boolean') return value;
+  const text = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(text)) return true;
+  if (['0', 'false', 'no', 'off'].includes(text)) return false;
+  return fallback;
+}
+
+/**
+ * 通知时间规范化：只接受 HH:mm（24 小时制），非法值回退默认 01:00。
+ * 允许传 'HH:mm:ss'，截断到分钟。
+ */
+function normalizeNotifyTime(value) {
+  const text = normalizeText(value, 10);
+  const match = /^(\d{1,2}):(\d{2})(?::\d{2})?$/.exec(text);
+  if (!match) return DEFAULT_NOTIFY_TIME;
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  if (!Number.isInteger(hour) || hour < 0 || hour > 23) return DEFAULT_NOTIFY_TIME;
+  if (!Number.isInteger(minute) || minute < 0 || minute > 59) return DEFAULT_NOTIFY_TIME;
+  return `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`;
+}
+
+/**
+ * 收件人名单规范化：trim → 去空 → 去重（保持输入顺序）→ 限长限量。
+ * 支持数组、逗号/换行/分号分隔的字符串。
+ */
+function normalizeRecipients(input) {
+  let list = [];
+  if (Array.isArray(input)) {
+    list = input;
+  } else if (typeof input === 'string') {
+    list = input.split(/[,，;；\n\r\t]+/);
+  } else if (input && typeof input === 'object') {
+    list = Object.values(input);
+  }
+
+  const seen = new Set();
+  const result = [];
+  for (const raw of list) {
+    const name = normalizeText(raw, MAX_RECIPIENT_LENGTH);
+    if (!name) continue;
+    if (seen.has(name)) continue;
+    seen.add(name);
+    result.push(name);
+    if (result.length >= MAX_RECIPIENTS) break;
+  }
+  return result;
+}
+
+/** 幂等键：正式推送按「业务日期 + 收件人」去重；测试推送带时间戳，不污染正式记录 */
+function buildIdempotencyKey({ bizDate, recipient, mode = 'scheduled', nonce = '' }) {
+  const scope = mode === 'test' ? `test:${normalizeText(nonce, 64)}` : 'daily';
+  return `daily_inventory_notification:${scope}:${bizDate}:${recipient}:v1`.slice(0, 160);
+}
+
+async function readSystemConfigValue(key) {
+  const rows = await database.local.query(
+    'SELECT config_value AS configValue FROM system_config WHERE config_key = ? LIMIT 1',
+    [key]
+  );
+  return rows?.[0]?.configValue;
+}
+
+async function upsertSystemConfigValue(key, value, configType = 'json') {
+  const payload = typeof value === 'string' ? value : JSON.stringify(value);
+  const rows = await database.local.query(
+    'SELECT id FROM system_config WHERE config_key = ? LIMIT 1',
+    [key]
+  );
+  if (rows?.[0]) {
+    await database.local.query(
+      'UPDATE system_config SET config_value = ?, config_type = ? WHERE config_key = ?',
+      [payload, configType, key]
+    );
+  } else {
+    await database.local.insert('system_config', {
+      config_key: key,
+      config_value: payload,
+      config_type: configType,
+    });
+  }
+  return payload;
+}
+
+// ── 配置 ────────────────────────────────────────────────────────
+async function getDailyInventoryNotificationRuntimeConfig({ forceRefresh = false } = {}) {
+  if (!forceRefresh && cachedConfig && Date.now() - cachedAt < CONFIG_CACHE_TTL_MS) {
+    return { ...cachedConfig };
+  }
+  let stored = {};
+  try {
+    stored = safeJsonParse(await readSystemConfigValue(CONFIG_KEY), {});
+  } catch (error) {
+    console.warn('读取每日进销存通知配置失败，使用默认值:', error.message);
+  }
+  cachedConfig = {
+    enabled: normalizeFlag(stored.enabled, false),
+    notifyTime: normalizeNotifyTime(stored.notifyTime ?? stored.notify_time),
+    recipients: normalizeRecipients(stored.recipients),
+  };
+  cachedAt = Date.now();
+  return { ...cachedConfig };
+}
+
+async function saveDailyInventoryNotificationConfig(input = {}) {
+  const current = await getDailyInventoryNotificationRuntimeConfig({ forceRefresh: true });
+  const next = {
+    enabled: normalizeFlag(input.enabled, current.enabled),
+    notifyTime: normalizeNotifyTime(
+      input.notifyTime ?? input.notify_time ?? current.notifyTime
+    ),
+    recipients: normalizeRecipients(
+      input.recipients === undefined ? current.recipients : input.recipients
+    ),
+  };
+  await upsertSystemConfigValue(CONFIG_KEY, next);
+  cachedConfig = { ...next };
+  cachedAt = Date.now();
+  return { ...next };
+}
+
+// ── 执行记录 / 幂等记录 ─────────────────────────────────────────
+async function loadDailyInventoryNotificationState() {
+  let parsed = {};
+  try {
+    parsed = safeJsonParse(await readSystemConfigValue(STATE_KEY), {});
+  } catch (error) {
+    console.warn('读取每日进销存通知状态失败，按空状态处理:', error.message);
+  }
+  const notified = parsed.notified && typeof parsed.notified === 'object' && !Array.isArray(parsed.notified)
+    ? parsed.notified
+    : {};
+  const runs = Array.isArray(parsed.runs) ? parsed.runs : [];
+  return { version: 1, notified, runs };
+}
+
+async function saveDailyInventoryNotificationState(state = {}) {
+  const value = {
+    version: 1,
+    notified: state.notified && typeof state.notified === 'object' && !Array.isArray(state.notified)
+      ? state.notified
+      : {},
+    runs: Array.isArray(state.runs) ? state.runs.slice(-MAX_RUN_RECORDS) : [],
+  };
+  await upsertSystemConfigValue(STATE_KEY, value);
+  return value;
+}
+
+/** 判断某业务日期是否已成功通知过某人（只认正式推送） */
+async function hasNotified(bizDate, recipient) {
+  const state = await loadDailyInventoryNotificationState();
+  const day = state.notified?.[bizDate];
+  return Boolean(day && day[recipient]);
+}
+
+/** 记录一次成功通知（正式推送才写；测试推送不写） */
+async function markNotified(bizDate, recipient, extra = {}) {
+  const state = await loadDailyInventoryNotificationState();
+  const day = { ...(state.notified?.[bizDate] || {}) };
+  day[recipient] = {
+    notifiedAt: new Date().toISOString(),
+    deliveryId: extra.deliveryId || null,
+    idempotencyKey: extra.idempotencyKey || null,
+  };
+  const notified = { ...(state.notified || {}), [bizDate]: day };
+  // 只保留最近 14 个业务日，避免状态无限膨胀
+  const keys = Object.keys(notified).sort();
+  const trimmed = {};
+  keys.slice(-14).forEach((k) => { trimmed[k] = notified[k]; });
+  return saveDailyInventoryNotificationState({ ...state, notified: trimmed });
+}
+
+/** 追加一条执行记录 */
+async function appendRunRecord(record = {}) {
+  const state = await loadDailyInventoryNotificationState();
+  const runs = [...(state.runs || []), {
+    runAt: record.runAt || new Date().toISOString(),
+    bizDate: record.bizDate || null,
+    mode: record.mode || 'scheduled',
+    success: record.success === true,
+    reason: record.reason || null,
+    error: record.error || null,
+    screenshotUrl: record.screenshotUrl || null,
+    screenshotKey: record.screenshotKey || null,
+    notifyTime: record.notifyTime || null,
+    recipients: Array.isArray(record.recipients) ? record.recipients : [],
+  }];
+  return saveDailyInventoryNotificationState({ ...state, runs });
+}
+
+function listRunRecords(limit = 10) {
+  return loadDailyInventoryNotificationState().then((state) => {
+    const runs = Array.isArray(state.runs) ? state.runs : [];
+    return runs.slice(-Math.max(Number(limit) || 10, 1)).reverse();
+  });
+}
+
+// ── 管理员视图（不含任何密钥） ───────────────────────────────────
+async function getObjectStorageStatus() {
+  try {
+    const config = await getDefaultS3Config(false);
+    return {
+      configured: Boolean(config && config.bucket && config.endpoint && config.accessKeyId),
+      bucket: config?.bucket || '',
+      endpoint: config?.endpoint || '',
+      // 只给脱敏信息，secretAccessKey 从不读取、从不返回
+      accessKeyIdPreview: config?.accessKeyId
+        ? `${String(config.accessKeyId).slice(0, 4)}***`
+        : '',
+    };
+  } catch (error) {
+    return { configured: false, bucket: '', endpoint: '', accessKeyIdPreview: '', error: error.message };
+  }
+}
+
+async function getDailyInventoryNotificationAdminConfig() {
+  const config = await getDailyInventoryNotificationRuntimeConfig({ forceRefresh: true });
+  let center = {};
+  try {
+    center = await getYydNotificationCenterRuntimeConfig();
+  } catch (_error) {
+    center = {};
+  }
+  const centerAdmin = toNotificationCenterAdminConfig(center);
+  const storage = await getObjectStorageStatus();
+  const state = await loadDailyInventoryNotificationState();
+  const runs = Array.isArray(state.runs) ? state.runs : [];
+
+  const blockingReasons = [];
+  if (!config.enabled) blockingReasons.push('功能未启用');
+  if (!config.recipients.length) blockingReasons.push('未配置通知用户');
+  if (!centerAdmin.configured) blockingReasons.push('统一通知中心未配置');
+  if (!storage.configured) blockingReasons.push('对象存储未配置');
+
+  return {
+    enabled: config.enabled,
+    notifyTime: config.notifyTime,
+    recipients: config.recipients,
+    timezone: TIMEZONE,
+    maxRecipients: MAX_RECIPIENTS,
+    notificationCenter: {
+      configured: centerAdmin.configured,
+      baseUrl: centerAdmin.baseUrl,
+      projectCode: centerAdmin.projectCode,
+      projectSecretConfigured: centerAdmin.projectSecretConfigured,
+      projectSecretPreview: centerAdmin.projectSecretPreview,
+    },
+    objectStorage: storage,
+    blockingReasons,
+    lastRunAt: runs.length ? runs[runs.length - 1].runAt : null,
+    lastRunSuccess: runs.length ? runs[runs.length - 1].success === true : null,
+    runs: runs.slice(-10).reverse(),
+  };
+}
+
+module.exports = {
+  CONFIG_KEY,
+  STATE_KEY,
+  DEFAULT_NOTIFY_TIME,
+  MAX_RECIPIENTS,
+  MAX_RECIPIENT_LENGTH,
+  MAX_RUN_RECORDS,
+  TIMEZONE,
+  appendRunRecord,
+  buildIdempotencyKey,
+  getDailyInventoryNotificationAdminConfig,
+  getDailyInventoryNotificationRuntimeConfig,
+  getObjectStorageStatus,
+  hasNotified,
+  listRunRecords,
+  loadDailyInventoryNotificationState,
+  markNotified,
+  normalizeFlag,
+  normalizeNotifyTime,
+  normalizeRecipients,
+  normalizeText,
+  saveDailyInventoryNotificationConfig,
+  saveDailyInventoryNotificationState,
+};

backend/src/services/dailyInventoryOfficial.js

@@ -0,0 +1,137 @@
+/**
+ * 每日进销存 —— 聚水潭官方进销存导出解析 / 导入
+ *
+ * 输入为聚水潭进销存报表按仓导出（xlsx），列包含：
+ *   仓库、期初数量、[12 个流水列]、期末数量
+ * 流水列符号沿用导出原值（出仓为负、入仓为正），前端不做二次转换。
+ */
+const XLSX = require('xlsx');
+const {
+  FLOW_COLUMNS,
+  DAILY_INVENTORY_BASELINE,
+} = require('../config/dailyInventoryBaseline');
+const officialDb = require('../config/dailyInventoryOfficialDb');
+
+const FLOW_FIELDS = FLOW_COLUMNS.map((c) => c.field);
+
+/** 流水列中文表头 → field */
+const LABEL_TO_FIELD = new Map(FLOW_COLUMNS.map((c) => [c.label, c.field]));
+
+/** 仓库名 → wms_co_id（来自项目仓库清单） */
+const WAREHOUSE_TO_ID = new Map(
+  DAILY_INVENTORY_BASELINE.map((b) => [b.warehouse, b.wmsCoId])
+);
+
+const num = (v) => {
+  if (v == null || v === '' || v === '-') return null;
+  const n = Number(String(v).replace(/,/g, '').trim());
+  return Number.isFinite(n) ? n : null;
+};
+
+/**
+ * 把「表头 → 值」的记录数组归一化为官方行
+ * @param {Array<Object>} records
+ * @returns {{rows: Array, warnings: string[]}}
+ */
+function normalizeRecords(records) {
+  const rows = [];
+  const warnings = [];
+  if (!Array.isArray(records)) return { rows, warnings: ['导入内容不是数组'] };
+
+  records.forEach((rec, idx) => {
+    const keys = Object.keys(rec);
+    const warehouseKey = keys.find((k) => String(k).trim() === '仓库');
+    if (!warehouseKey) return;
+    const warehouse = String(rec[warehouseKey] ?? '').trim();
+    if (!warehouse) return;
+
+    const openingKey = keys.find((k) => String(k).trim() === '期初数量');
+    const closingKey = keys.find((k) => String(k).trim() === '期末数量');
+    if (!openingKey && !closingKey) {
+      warnings.push(`第 ${idx + 2} 行缺少「期初数量 / 期末数量」列，已跳过`);
+      return;
+    }
+
+    // 12 个流水列先置 null，导出行里没出现的列保持 null（区别于显式为 0）
+    const flows = {};
+    for (const field of FLOW_FIELDS) flows[field] = null;
+    for (const k of keys) {
+      const label = String(k).trim();
+      const field = LABEL_TO_FIELD.get(label);
+      if (!field) continue;
+      flows[field] = num(rec[k]);
+    }
+
+    rows.push({
+      warehouse,
+      wmsCoId: WAREHOUSE_TO_ID.get(warehouse) ?? null,
+      openingQty: openingKey ? num(rec[openingKey]) : null,
+      closingQty: closingKey ? num(rec[closingKey]) : null,
+      flows,
+    });
+  });
+
+  if (!rows.length) warnings.push('未解析到任何仓库行，请确认包含「仓库」列');
+  return { rows, warnings };
+}
+
+/**
+ * 解析 xlsx 缓冲区（自动定位含「仓库」表头的工作表与表头行）
+ * @param {Buffer} buffer
+ */
+function parseWorkbook(buffer) {
+  const wb = XLSX.read(buffer, { type: 'buffer', cellDates: true });
+  const warnings = [];
+  for (const sheetName of wb.SheetNames) {
+    const ws = wb.Sheets[sheetName];
+    const grid = XLSX.utils.sheet_to_json(ws, { header: 1, defval: '', blankrows: false });
+    const headerIdx = grid.findIndex((r) => r.some((c) => String(c).trim() === '仓库'));
+    if (headerIdx < 0) continue;
+    const header = grid[headerIdx].map((c) => String(c).trim());
+    const body = grid.slice(headerIdx + 1)
+      .filter((r) => r.some((c) => String(c).trim() !== ''))
+      .map((r) => Object.fromEntries(header.map((h, i) => [h, r[i]])));
+    const { rows, warnings: w } = normalizeRecords(body);
+    if (rows.length) return { sheetName, rows, warnings: warnings.concat(w) };
+    warnings.push(...w);
+  }
+  return { sheetName: null, rows: [], warnings: warnings.length ? warnings : ['未找到含「仓库」列的工作表'] };
+}
+
+/** 恒等式校验：期初 + Σ流水 = 期末 */
+function checkBalance(rows, tolerance = 1) {
+  return rows
+    .map((r) => {
+      const flowSum = FLOW_FIELDS.reduce((acc, f) => acc + (Number(r.flows?.[f]) || 0), 0);
+      const opening = Number(r.openingQty) || 0;
+      const closing = Number(r.closingQty) || 0;
+      const diff = opening + flowSum - closing;
+      return { warehouse: r.warehouse, opening, flowSum, closing, diff: Number(diff.toFixed(2)) };
+    })
+    .filter((r) => Math.abs(r.diff) > tolerance);
+}
+
+/**
+ * 导入某业务日的官方进销存（先清后写）
+ * @returns {Promise<{bizDate:string, imported:number, warnings:string[], mismatches:Array, unknownWarehouses:string[], missingWarehouses:string[]}>}
+ */
+async function importOfficial(bizDate, rows, { source = 'jst-export' } = {}) {
+  await officialDb.deleteOfficial(bizDate);
+  const imported = await officialDb.upsertOfficial(bizDate, rows, source);
+  const mismatches = checkBalance(rows);
+  const unknownWarehouses = rows.filter((r) => r.wmsCoId == null).map((r) => r.warehouse);
+  const importedNames = new Set(rows.map((r) => r.warehouse));
+  const missingWarehouses = DAILY_INVENTORY_BASELINE
+    .filter((b) => !importedNames.has(b.warehouse))
+    .map((b) => b.warehouse);
+  return { bizDate, imported, warnings: [], mismatches, unknownWarehouses, missingWarehouses };
+}
+
+module.exports = {
+  FLOW_FIELDS,
+  LABEL_TO_FIELD,
+  normalizeRecords,
+  parseWorkbook,
+  checkBalance,
+  importOfficial,
+};

backend/src/services/dailyInventoryOpening.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * 每日进销存 —— 期初快照缺失时的兜底推导
+ *
+ * 正常情况下「期初 = 上一业务日快照」（每日 01:30 自动落库）。
+ * 若快照缺失（服务停机、新纳入仓库等），用「实时库存扣流水回推」推导
+ * 「上一业务日期末结存」并补写快照：
+ *
+ *   closing(D-1) = 当前实时库存 − 自 D 01:00 以来的净流入
+ *   净流入 = 采购进仓 + 销售退货 − 销售出仓 − 采购退货（带符号流水求和，见 dailyInventoryFlows）
+ *
+ * 口径校准（2026-09-27，对照聚水潭进销存导出 09-23 期初基准）：
+ *   崔桥工厂仓 基准 92388 / 回推 ≈89650；横林二仓 基准 63780 / 回推 ≈64029；
+ *   山东青岗集 基准 88377 / 回推 ≈88210；河南洛宁 基准 83305 / 回推 ≈82473。
+ *   偏差 0.3%~2.7%，来源为业务库缺失的 8 类单据（调拨/盘点/加工/其它出入库）。
+ *
+ * 注意：不要用 rpt.pm_stockMonitor 聚合 jsStock 充当全仓结存 ——
+ * 该表只覆盖纳入监控范围的 SKU 子集（横林二仓实测 1197 vs 全仓 63780），
+ * 系统性偏低，已在校准后弃用。
+ */
+
+const { fetchFlows } = require('./dailyInventoryFlows');
+
+/**
+ * 推导 openingDate 的期末快照并补写。
+ * @param {Object} opts
+ * @param {Object} opts.cloudDb          业务库（mssql）
+ * @param {Object} opts.snapshotDb       本地快照表访问模块
+ * @param {Array}  opts.baseline         仓库基线（warehouse/dbWarehouse/wmsCoId）
+ * @param {string} opts.openingDate      期初业务日（YYYY-MM-DD，即要补快照的日期）
+ * @param {string} opts.latestBizDate    最新业务日（YYYY-MM-DD，流水起点 = 其当日 01:00）
+ * @param {Date|null} opts.takenAt       实时库存数据时间
+ * @returns {Promise<{count:number, derivedCount:number}>}
+ */
+async function deriveAndStoreOpeningSnapshot(opts) {
+  const { cloudDb, snapshotDb, baseline, openingDate, latestBizDate, takenAt } = opts;
+  if (!openingDate || !latestBizDate) return { count: 0, derivedCount: 0 };
+  const whs = baseline.filter((b) => b.wmsCoId != null);
+  const wmsCoIds = whs.map((b) => b.wmsCoId);
+  const flowFrom = `${latestBizDate} 01:00:00`;
+
+  // 实时库存（与每日快照任务同口径：jst_inventoryInfo 按仓聚合）
+  let realtimeMap = new Map();
+  try {
+    const rows = await cloudDb.query(
+      `SELECT i.wms_co_id AS wmsCoId,
+              ISNULL(SUM(CAST(i.qty AS DECIMAL(18, 2))), 0) AS qty,
+              SUM(CASE WHEN ABS(ISNULL(i.qty, 0)) > 0.0001 THEN 1 ELSE 0 END) AS skuCount
+         FROM rpt.jst_inventoryInfo i
+        WHERE i.wms_co_id IN (${wmsCoIds.map((_, i) => `@w${i}`).join(',')})
+        GROUP BY i.wms_co_id`,
+      Object.fromEntries(wmsCoIds.map((id, i) => [`w${i}`, id])),
+      { requestTimeout: 120000 }
+    );
+    realtimeMap = new Map(rows.map((r) => [String(r.wmsCoId), r]));
+  } catch (error) {
+    console.error('[daily-inventory-opening] 实时库存聚合失败:', error.message);
+  }
+
+  // 自期初时刻以来的带符号流水（流出为负）
+  let flowMap = new Map();
+  try {
+    flowMap = await fetchFlows(cloudDb, wmsCoIds, flowFrom);
+  } catch (error) {
+    console.error('[daily-inventory-opening] 流水取数失败:', error.message);
+  }
+
+  let derivedCount = 0;
+  const payload = whs.map((b) => {
+    const rt = realtimeMap.get(String(b.wmsCoId));
+    const f = flowMap.get(String(b.wmsCoId)) || {};
+    const netInflow = (f.purchaseIn || 0) + (f.salesReturn || 0) + (f.salesOut || 0) + (f.purchaseReturn || 0);
+    const closingQty = Number(rt?.qty ?? 0) - netInflow;
+    derivedCount += 1;
+    return {
+      wmsCoId: b.wmsCoId,
+      warehouse: b.warehouse,
+      dbWarehouse: b.dbWarehouse,
+      closingQty: Number(closingQty.toFixed(2)),
+      skuCount: Number(rt?.skuCount ?? 0),
+      takenAt: takenAt ? new Date(takenAt) : null,
+    };
+  });
+
+  const count = await snapshotDb.upsertSnapshot(openingDate, payload);
+  console.log(`[daily-inventory-opening] 已补写 ${openingDate} 快照 ${count}/${whs.length} 仓（实时库存扣流水回推）`);
+  return { count, derivedCount };
+}
+
+module.exports = { deriveAndStoreOpeningSnapshot };

backend/src/services/dailyInventoryScreenshot.js

@@ -0,0 +1,307 @@
+'use strict';
+
+// 每日进销存 · 页面截图与上传
+//
+// 要点：
+//   1. 使用服务端签发的**短时效** JWT 作为专用身份访问页面（15 分钟过期），
+//      令牌只写入浏览器 localStorage，不会出现在截图地址、日志或接口响应里。
+//   2. 截图前必须等到数据真正加载完成：表格有数据行、没有 Spin 加载中、没有错误提示。
+//   3. 表格带内部滚动，直接截屏只能看到一屏；截图前注入 CSS 展开滚动容器，
+//      再整页截图，保证数据是完整的。
+//   4. 截图落在系统临时目录，上传成功后立即删除。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const jwt = require('jsonwebtoken');
+const bcrypt = require('bcryptjs');
+const database = require('../config/database');
+const { uploadFileToDefaultS3 } = require('./objectStorage');
+
+const TIMEZONE = 'Asia/Shanghai';
+const PAGE_PATH = '/planning/operation/daily-inventory';
+// 生产主站（见《服务器部署规范》）：可用 DAILY_INVENTORY_SCREENSHOT_BASE_URL / PUBLIC_SITE_URL 覆盖
+const DEFAULT_BASE_URL = 'https://ck.yydd.ai';
+// 页面首次加载要扫订单明细，约 15~20 秒，等待上限给到 3 分钟
+const PAGE_READY_TIMEOUT_MS = 3 * 60 * 1000;
+/**
+ * 截图专用服务账号
+ *
+ * 页面启动时会调用 /api/auth/verify，该接口要求令牌的 sub 必须是系统库 users 表中
+ * 真实且 active 的用户；仅签名合法但用户不存在的令牌会被判定为未登录并跳转登录页，
+ * 截图也就拿不到任何数据。因此这里不使用凭空捏造的身份，而是在系统库维护一个
+ * 仅供服务端使用的专用账号，令牌以该账号的 id 作为 sub。
+ *
+ * 该账号只以服务端签发的短时效令牌方式使用：密码哈希是随机值且永不对外，
+ * 任何人无法通过密码登录；删除该行即可彻底回收。
+ */
+const SERVICE_USERNAME = String(
+  process.env.DAILY_INVENTORY_SCREENSHOT_USERNAME || 'daily_inventory_screenshot_bot'
+).trim().slice(0, 50) || 'daily_inventory_screenshot_bot';
+const SERVICE_NAME = '每日进销存截图服务';
+const SERVICE_EMAIL = `${SERVICE_USERNAME}@service.local`;
+
+let cachedServiceUserId = null;
+
+const EXPAND_CSS = `
+.ant-table-body, .ant-table-content, .ant-table-container { max-height: none !important; overflow: visible !important; }
+.daily-inventory-page { overflow: visible !important; }
+.ant-table-cell-fix-left, .ant-table-cell-fix-right { position: static !important; }
+`;
+
+function normalizeText(value, maxLength = 500) {
+  return String(value ?? '').trim().slice(0, maxLength);
+}
+
+/** 北京时间日期/时间片段：YYYY-MM-DD、YYYYMMDD、HHmmss */
+function chinaTimeParts(date = new Date()) {
+  const target = date instanceof Date ? date : new Date(date);
+  const dateText = new Intl.DateTimeFormat('en-CA', {
+    timeZone: TIMEZONE, year: 'numeric', month: '2-digit', day: '2-digit',
+  }).format(target);
+  const timeText = new Intl.DateTimeFormat('en-GB', {
+    timeZone: TIMEZONE, hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false,
+  }).format(target);
+  return {
+    bizDate: dateText,
+    dateKey: dateText.replace(/\D/g, ''),
+    timeKey: timeText.replace(/\D/g, ''),
+  };
+}
+
+function resolveBaseUrl() {
+  const raw = normalizeText(
+    process.env.DAILY_INVENTORY_SCREENSHOT_BASE_URL
+      || process.env.PUBLIC_SITE_URL
+      || DEFAULT_BASE_URL,
+    500
+  ).replace(/\/+$/, '');
+  return raw || DEFAULT_BASE_URL;
+}
+
+function resolvePageUrl() {
+  return `${resolveBaseUrl()}${PAGE_PATH}`;
+}
+
+/** 清空服务账号 id 缓存（账号被重建或测试时刷新用） */
+function resetScreenshotServiceUserCache() {
+  cachedServiceUserId = null;
+}
+
+/** 生成一个无法用于登录的密码哈希（随机串无人知晓，仅满足字段非空约束） */
+function buildUnusablePasswordHash() {
+  return bcrypt.hash(crypto.randomBytes(32).toString('hex'), 10);
+}
+
+/**
+ * 确保系统库存在截图专用服务账号，并返回其 id。
+ * 只维护 auth_source='service' 的本服务账号，不触碰任何人工账号。
+ */
+async function ensureScreenshotServiceUser() {
+  if (cachedServiceUserId) return cachedServiceUserId;
+
+  const rows = await database.local.query(
+    'SELECT id, role, status FROM users WHERE username = ? LIMIT 1',
+    [SERVICE_USERNAME]
+  );
+  let user = rows[0];
+
+  if (!user) {
+    const created = await database.local.insert('users', {
+      username: SERVICE_USERNAME,
+      password_hash: await buildUnusablePasswordHash(),
+      name: SERVICE_NAME,
+      email: SERVICE_EMAIL,
+      role: 'admin',
+      status: 'active',
+      auth_source: 'service',
+    });
+    user = { id: created.insertId, role: 'admin', status: 'active' };
+  } else if (user.status !== 'active' || user.role !== 'admin') {
+    await database.local.query(
+      "UPDATE users SET role = 'admin', status = 'active', auth_source = 'service' WHERE id = ? AND auth_source = 'service'",
+      [user.id]
+    );
+  }
+
+  cachedServiceUserId = Number(user.id);
+  return cachedServiceUserId;
+}
+
+/**
+ * 签发截图专用短时效令牌。
+ * sub 为系统库中的专用服务账号 id，令牌只写入浏览器 localStorage，
+ * 不会出现在截图地址、日志或接口响应里，也不含任何密钥。
+ */
+async function signScreenshotToken() {
+  const secret = process.env.CUBEJS_SECRET;
+  if (!secret) throw new Error('缺少 CUBEJS_SECRET，无法签发截图身份令牌');
+  const userId = await ensureScreenshotServiceUser();
+  return jwt.sign(
+    {
+      sub: String(userId),
+      username: SERVICE_USERNAME,
+      name: SERVICE_NAME,
+      role: 'admin',
+      authSource: 'service',
+      allowedPageKeys: [],
+    },
+    secret,
+    { expiresIn: '15m' }
+  );
+}
+
+/**
+ * 截图文件名与对象键。
+ * 目录与文件名里的日期都用**业务日期**，时间用执行时刻，便于按数据日期归档：
+ *   daily-inventory/2026-09-25/daily-inventory-20260925-010000.png
+ */
+function buildScreenshotNames({ bizDate, timeKey }) {
+  const safeDate = normalizeText(bizDate, 10);
+  const dateKey = safeDate.replace(/\D/g, '');
+  const fileName = `daily-inventory-${dateKey}-${timeKey}.png`;
+  return {
+    fileName,
+    objectKey: `daily-inventory/${safeDate}/${fileName}`,
+  };
+}
+
+/** 截图存放的临时文件（不落业务目录，上传后立即删除） */
+function buildTempFilePath({ bizDate, timeKey }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'daily-inventory-shot-'));
+  const { fileName, objectKey } = buildScreenshotNames({ bizDate, timeKey });
+  return { dir, filePath: path.join(dir, fileName), objectKey };
+}
+
+async function launchBrowser() {
+  let playwright;
+  try {
+    playwright = require('playwright');
+  } catch (_error) {
+    throw new Error('未安装 playwright，无法执行页面截图');
+  }
+  try {
+    return await playwright.chromium.launch({
+      args: ['--no-sandbox', '--disable-dev-shm-usage', '--disable-gpu'],
+    });
+  } catch (error) {
+    const detail = normalizeText(error?.message, 300);
+    throw new Error(`浏览器启动失败（服务器需先执行 npx playwright install chromium）：${detail}`);
+  }
+}
+
+/** 等到数据真正渲染完成：有数据行、无加载中、无错误提示 */
+async function waitForPageReady(page) {
+  await page.waitForSelector('.daily-inventory-table .ant-table-tbody tr', {
+    timeout: PAGE_READY_TIMEOUT_MS,
+    state: 'attached',
+  });
+
+  await page.waitForFunction(
+    () => {
+      const spinning = document.querySelector('.daily-inventory-page .ant-spin-spinning');
+      const skeleton = document.querySelector('.ant-skeleton');
+      const rows = document.querySelectorAll('.daily-inventory-table .ant-table-tbody tr');
+      return !spinning && !skeleton && rows.length > 0;
+    },
+    { timeout: PAGE_READY_TIMEOUT_MS, polling: 500 }
+  );
+
+  const errorText = await page.evaluate(() => {
+    const node = document.querySelector('.daily-inventory-page .ant-alert-error');
+    return node ? node.textContent || '' : '';
+  });
+  if (errorText) {
+    throw new Error(`页面返回错误提示，放弃截图：${normalizeText(errorText, 200)}`);
+  }
+
+  const rowCount = await page.evaluate(
+    () => document.querySelectorAll('.daily-inventory-table .ant-table-tbody tr').length
+  );
+  if (!rowCount) throw new Error('页面未渲染出任何数据行，放弃截图');
+  return rowCount;
+}
+
+/**
+ * 执行一次截图并上传到默认对象存储桶
+ * @returns {Promise<{url:string, key:string, bizDate:string, size:number, rowCount:number, takenAt:string}>}
+ */
+async function captureAndUploadDailyInventory(options = {}) {
+  const now = options.now ? new Date(options.now) : new Date();
+  const { timeKey } = chinaTimeParts(now);
+  // 业务日期由调用方（定时任务）给出；未指定时按北京时间当天兜底
+  const bizDate = normalizeText(options.bizDate, 10) || chinaTimeParts(now).bizDate;
+  const token = await signScreenshotToken();
+  const pageUrl = resolvePageUrl();
+
+  const browser = await launchBrowser();
+  const { dir, filePath, objectKey } = buildTempFilePath({ bizDate, timeKey });
+  let rowCount = 0;
+
+  try {
+    const context = await browser.newContext({
+      viewport: { width: 1680, height: 1050 },
+      deviceScaleFactor: 1,
+      timezoneId: TIMEZONE,
+      locale: 'zh-CN',
+    });
+    // 令牌只注入浏览器 localStorage，URL 与日志里都不出现
+    await context.addInitScript((value) => {
+      try {
+        window.localStorage.setItem('token', value);
+      } catch (_error) {
+        // 忽略：首个 document 可能还不允许访问 localStorage
+      }
+    }, token);
+
+    const page = await context.newPage();
+    page.on('pageerror', () => {});
+    await page.goto(pageUrl, { waitUntil: 'domcontentloaded', timeout: PAGE_READY_TIMEOUT_MS });
+    rowCount = await waitForPageReady(page);
+
+    // 展开内部滚动容器，保证整页截图包含完整数据区
+    await page.addStyleTag({ content: EXPAND_CSS });
+    await page.waitForTimeout(500);
+    await page.screenshot({ path: filePath, fullPage: true });
+
+    const stats = await fs.promises.stat(filePath);
+    if (!stats.size) throw new Error('截图文件为空');
+
+    const uploaded = await uploadFileToDefaultS3(filePath, {
+      key: objectKey,
+      mimeType: 'image/png',
+      folder: 'daily-inventory',
+      extension: 'png',
+    });
+
+    return {
+      url: uploaded.url,
+      key: uploaded.key,
+      bizDate,
+      size: stats.size,
+      rowCount,
+      takenAt: now.toISOString(),
+    };
+  } finally {
+    await browser.close().catch(() => {});
+    fs.rm(dir, { recursive: true, force: true }, () => {});
+  }
+}
+
+module.exports = {
+  DEFAULT_BASE_URL,
+  PAGE_PATH,
+  PAGE_READY_TIMEOUT_MS,
+  SERVICE_NAME,
+  SERVICE_USERNAME,
+  TIMEZONE,
+  buildScreenshotNames,
+  captureAndUploadDailyInventory,
+  chinaTimeParts,
+  ensureScreenshotServiceUser,
+  resetScreenshotServiceUserCache,
+  resolveBaseUrl,
+  resolvePageUrl,
+  signScreenshotToken,
+};

backend/src/services/desktopReleaseService.js

@@ -1,254 +0,0 @@
-const database = require('../config/database');
-
-const DESKTOP_RELEASE_CONFIG_KEY = 'desktop_client_releases';
-const MAX_RELEASE_HISTORY = 50;
-const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
-const SUPPORTED_PLATFORMS = new Set(['win32', 'darwin']);
-const SUPPORTED_ARCHITECTURES = new Set(['x64', 'arm64', 'universal']);
-
-function normalizeVersion(value) {
-  return String(value || '').trim().replace(/^v/i, '');
-}
-
-function versionParts(value) {
-  const normalized = normalizeVersion(value);
-  if (!VERSION_PATTERN.test(normalized)) return null;
-  return normalized.split('.').map((part) => Number(part));
-}
-
-function compareVersions(left, right) {
-  const leftParts = versionParts(left);
-  const rightParts = versionParts(right);
-  if (!leftParts || !rightParts) return 0;
-  for (let index = 0; index < 3; index += 1) {
-    if (leftParts[index] !== rightParts[index]) {
-      return leftParts[index] > rightParts[index] ? 1 : -1;
-    }
-  }
-  return 0;
-}
-
-function validateVersion(value) {
-  const version = normalizeVersion(value);
-  if (!VERSION_PATTERN.test(version)) {
-    throw new Error('版本号格式必须为 x.y.z，例如 0.0.9');
-  }
-  return version;
-}
-
-function normalizePlatform(value, fileName = '') {
-  const normalized = String(value || '').trim().toLowerCase();
-  if (['darwin', 'mac', 'macos', 'osx'].includes(normalized)) return 'darwin';
-  if (['win32', 'win', 'windows'].includes(normalized)) return 'win32';
-  if (String(fileName || '').toLowerCase().endsWith('.dmg')) return 'darwin';
-  return 'win32';
-}
-
-function normalizeArchitecture(value, fileName = '', platform = '') {
-  const normalized = String(value || '').trim().toLowerCase();
-  if (SUPPORTED_ARCHITECTURES.has(normalized)) return normalized;
-  const fileMatch = String(fileName || '').toLowerCase().match(/[-_.](arm64|x64|universal)(?=[-_.]|$)/);
-  if (fileMatch) return fileMatch[1];
-  return normalizePlatform(platform, fileName) === 'darwin' ? 'arm64' : 'x64';
-}
-
-function normalizeStoredRelease(value) {
-  if (!value || typeof value !== 'object') return null;
-  const version = normalizeVersion(value.version);
-  if (!VERSION_PATTERN.test(version) || !value.objectKey) return null;
-  const platform = normalizePlatform(value.platform, value.fileName || value.objectKey);
-  const architecture = normalizeArchitecture(value.architecture, value.fileName || value.objectKey, platform);
-  const defaultFileName = platform === 'darwin'
-    ? `pdd-auto-sale-${version}-${architecture}.dmg`
-    : `pdd-auto-sale-${version}-setup.exe`;
-  return {
-    id: Number(value.id) || Date.now(),
-    version,
-    releaseNotes: String(value.releaseNotes || ''),
-    objectKey: String(value.objectKey),
-    platform,
-    architecture,
-    fileName: String(value.fileName || defaultFileName),
-    fileSize: Number(value.fileSize || 0),
-    sha256: String(value.sha256 || ''),
-    publishedByUserId: value.publishedByUserId == null ? null : Number(value.publishedByUserId),
-    publishedByName: String(value.publishedByName || ''),
-    publishedAt: value.publishedAt || value.createdAt || null,
-    createdAt: value.createdAt || value.publishedAt || null,
-    updatedAt: value.updatedAt || value.publishedAt || null,
-  };
-}
-
-function parseReleaseStorage(value) {
-  try {
-    const parsed = typeof value === 'string' ? JSON.parse(value || '{}') : value;
-    const releases = Array.isArray(parsed?.releases)
-      ? parsed.releases.map(normalizeStoredRelease).filter(Boolean)
-      : [];
-    const storedLatestVersions = parsed?.latestVersions && typeof parsed.latestVersions === 'object'
-      ? parsed.latestVersions
-      : {};
-    const latestVersions = {};
-    for (const platform of SUPPORTED_PLATFORMS) {
-      const version = normalizeVersion(storedLatestVersions[platform]);
-      if (VERSION_PATTERN.test(version)) latestVersions[platform] = version;
-    }
-    const legacyLatestVersion = normalizeVersion(parsed?.latestVersion);
-    if (!latestVersions.win32 && VERSION_PATTERN.test(legacyLatestVersion)) {
-      latestVersions.win32 = legacyLatestVersion;
-    }
-    for (const release of releases) {
-      if (!latestVersions[release.platform]) latestVersions[release.platform] = release.version;
-    }
-    return {
-      latestVersion: latestVersions.win32 || legacyLatestVersion,
-      latestVersions,
-      releases,
-    };
-  } catch {
-    return { latestVersion: '', latestVersions: {}, releases: [] };
-  }
-}
-
-async function loadReleaseStorage() {
-  const rows = await database.local.query(
-    'SELECT config_value FROM system_config WHERE config_key = ? LIMIT 1',
-    [DESKTOP_RELEASE_CONFIG_KEY]
-  );
-  return parseReleaseStorage(rows[0]?.config_value);
-}
-
-async function saveReleaseStorage(storage) {
-  const value = JSON.stringify(storage);
-  const existing = await database.local.query(
-    'SELECT id FROM system_config WHERE config_key = ? LIMIT 1',
-    [DESKTOP_RELEASE_CONFIG_KEY]
-  );
-  if (existing.length) {
-    await database.local.query(
-      'UPDATE system_config SET config_value = ?, config_type = ? WHERE config_key = ?',
-      [value, 'json', DESKTOP_RELEASE_CONFIG_KEY]
-    );
-    return;
-  }
-  await database.local.insert('system_config', {
-    config_key: DESKTOP_RELEASE_CONFIG_KEY,
-    config_value: value,
-    config_type: 'json',
-  });
-}
-
-async function ensureDesktopReleaseSchema() {
-  // Release metadata uses system_config because the runtime account cannot create tables.
-}
-
-function mapRelease(release, latestVersion = '') {
-  const normalized = normalizeStoredRelease(release);
-  if (!normalized) return null;
-  return {
-    ...normalized,
-    isLatest: normalized.version === normalizeVersion(latestVersion),
-  };
-}
-
-async function getLatestDesktopRelease(platform = 'win32', architecture = '') {
-  const storage = await loadReleaseStorage();
-  const targetPlatform = normalizePlatform(platform);
-  const targetArchitecture = architecture
-    ? normalizeArchitecture(architecture, '', targetPlatform)
-    : '';
-  const platformReleases = storage.releases
-    .filter((release) => release.platform === targetPlatform)
-    .sort((left, right) => (
-      compareVersions(right.version, left.version)
-      || String(right.publishedAt || '').localeCompare(String(left.publishedAt || ''))
-    ));
-  const latestVersion = storage.latestVersions[targetPlatform] || platformReleases[0]?.version || '';
-  const versionReleases = platformReleases.filter((release) => release.version === latestVersion);
-  const latest = (targetArchitecture
-    ? versionReleases.find((release) => release.architecture === targetArchitecture)
-      || versionReleases.find((release) => release.architecture === 'universal')
-    : null)
-    || versionReleases[0]
-    || platformReleases[0]
-    || null;
-  return latest ? mapRelease(latest, latestVersion || latest.version) : null;
-}
-
-async function getDesktopReleaseById(id) {
-  const storage = await loadReleaseStorage();
-  const release = storage.releases.find((item) => String(item.id) === String(id));
-  return release ? mapRelease(release, storage.latestVersions[release.platform]) : null;
-}
-
-async function listDesktopReleases(limit = 50) {
-  const storage = await loadReleaseStorage();
-  const safeLimit = Math.min(Math.max(Number(limit) || 50, 1), 100);
-  return storage.releases
-    .map((release) => mapRelease(release, storage.latestVersions[release.platform]))
-    .filter(Boolean)
-    .sort((left, right) => {
-      if (left.isLatest !== right.isLatest) return left.isLatest ? -1 : 1;
-      return String(right.publishedAt || '').localeCompare(String(left.publishedAt || ''));
-    })
-    .slice(0, safeLimit);
-}
-
-async function publishDesktopRelease(input) {
-  const version = validateVersion(input.version);
-  const storage = await loadReleaseStorage();
-  const platform = normalizePlatform(input.platform, input.fileName || input.objectKey);
-  const architecture = normalizeArchitecture(input.architecture, input.fileName || input.objectKey, platform);
-  const existing = storage.releases.find((release) => (
-    release.version === version
-    && release.platform === platform
-    && release.architecture === architecture
-  ));
-  const now = new Date().toISOString();
-  const release = {
-    id: existing?.id || Date.now(),
-    version,
-    platform,
-    architecture,
-    releaseNotes: input.releaseNotes || '',
-    objectKey: input.objectKey,
-    fileName: input.fileName,
-    fileSize: Number(input.fileSize || 0),
-    sha256: input.sha256,
-    publishedByUserId: input.publishedByUserId || null,
-    publishedByName: input.publishedByName || '',
-    publishedAt: now,
-    createdAt: existing?.createdAt || now,
-    updatedAt: now,
-  };
-  const releases = [
-    release,
-    ...storage.releases.filter((item) => !(
-      item.version === version
-      && item.platform === platform
-      && item.architecture === architecture
-    )),
-  ].slice(0, MAX_RELEASE_HISTORY);
-  const latestVersions = { ...storage.latestVersions, [platform]: version };
-  await saveReleaseStorage({
-    latestVersion: latestVersions.win32 || version,
-    latestVersions,
-    releases,
-  });
-  return mapRelease(release, version);
-}
-
-module.exports = {
-  compareVersions,
-  ensureDesktopReleaseSchema,
-  getDesktopReleaseById,
-  getLatestDesktopRelease,
-  listDesktopReleases,
-  mapRelease,
-  normalizeVersion,
-  normalizeArchitecture,
-  normalizePlatform,
-  parseReleaseStorage,
-  publishDesktopRelease,
-  validateVersion,
-};

backend/src/services/desktopSessionService.js

@@ -66,7 +66,7 @@ function buildDesktopCapabilities(user) {
   const allowed = new Set(Array.isArray(user?.allowedPageKeys) ? user.allowedPageKeys : []);
   const isAdmin = user?.role === 'admin';
   const canPlan = isAdmin || allowed.has('planning_upload');
-  const canUseMarket = isAdmin || allowed.has('market_insight') || canPlan;
+  const canUseMarket = isAdmin || canPlan;
 
   return {
     controlCenter: true,
@@ -80,7 +80,6 @@ function buildDesktopCapabilities(user) {
     marketingEvents: isAdmin || allowed.has('marketing_events'),
     promotion: isAdmin || allowed.has('promotion_module'),
     productTest: isAdmin || allowed.has('new_product_test'),
-    reviewAnalysis: isAdmin || allowed.has('review_analysis'),
   };
 }
 

backend/src/services/exportWorkbook.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * 通用表格导出
+ * --------------------------------------------------------------------------
+ * 把 [{ name, header: string[], rows: any[][] }] 渲染成：
+ *   - xlsx：多工作表工作簿（基于 backend 已依赖的 xlsx 包）
+ *   - csv ：单工作表、带 UTF-8 BOM（Excel 直接打开中文不乱码）
+ * 语义与 frontend/src/utils/tableExport.js 的「表头 + 行」保持一致。
+ */
+
+const xlsx = require('xlsx');
+
+const XLSX_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+const CSV_CONTENT_TYPE = 'text/csv; charset=utf-8';
+
+// Excel 工作表名限制：<=31 字符，且不能包含 : \ / ? * [ ]
+const sanitizeSheetName = (name, fallback) => {
+  const cleaned = String(name || '').replace(/[:\\/?*[\]]/g, ' ').replace(/\s+/g, ' ').trim();
+  return (cleaned || fallback).slice(0, 31);
+};
+
+const toCellValue = (value) => (
+  value === null || value === undefined || value === '' ? '' : value
+);
+
+const sheetToAoa = (sheet) => ([
+  (sheet?.header || []).map(toCellValue),
+  ...((sheet?.rows || []).map((row) => (row || []).map(toCellValue))),
+]);
+
+/** 多工作表 xlsx buffer；工作表名重复/非法时自动去重与截断 */
+const buildXlsxBuffer = (sheets = []) => {
+  const workbook = xlsx.utils.book_new();
+  const usedNames = new Set();
+
+  sheets.forEach((sheet, index) => {
+    const base = sanitizeSheetName(sheet?.name, `工作表${index + 1}`);
+    let name = base;
+    let suffix = 2;
+    while (usedNames.has(name)) {
+      name = `${base.slice(0, 27)}(${suffix})`;
+      suffix += 1;
+    }
+    usedNames.add(name);
+
+    const worksheet = xlsx.utils.aoa_to_sheet(sheetToAoa(sheet));
+    worksheet['!cols'] = (sheet?.header || []).map((title) => ({
+      wch: Math.max(10, Math.min(32, String(title || '').length * 2 + 6)),
+    }));
+    xlsx.utils.book_append_sheet(workbook, worksheet, name);
+  });
+
+  return xlsx.write(workbook, { type: 'buffer', bookType: 'xlsx' });
+};
+
+const quoteCsvCell = (value) => {
+  const text = value === null || value === undefined ? '' : String(value);
+  return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+};
+
+/** 单工作表 csv buffer（只取第一个工作表），前置 BOM */
+const buildCsvBuffer = (sheets = []) => {
+  const sheet = sheets[0] || { header: [], rows: [] };
+  const lines = [(sheet.header || []).map(quoteCsvCell).join(',')];
+  (sheet.rows || []).forEach((row) => {
+    lines.push((row || []).map(quoteCsvCell).join(','));
+  });
+  return Buffer.from(`\ufeff${lines.join('\r\n')}`, 'utf8');
+};
+
+const sanitizeFileName = (fileName) => String(fileName || '导出数据').replace(/[\\/:*?"<>|]/g, '_').trim() || '导出数据';
+
+/**
+ * 直接把导出结果写回响应。
+ * @param {import('express').Response} res
+ * @param {{ fileName?: string, format?: 'xlsx'|'csv', sheets?: Array }} payload
+ */
+const sendWorkbookDownload = (res, { fileName, format = 'xlsx', sheets = [] } = {}) => {
+  const isCsv = String(format).toLowerCase() === 'csv';
+  const exportSheets = isCsv ? sheets.slice(0, 1) : sheets;
+  const buffer = isCsv ? buildCsvBuffer(exportSheets) : buildXlsxBuffer(exportSheets);
+  const totalRows = exportSheets.reduce((sum, sheet) => sum + ((sheet?.rows || []).length), 0);
+  const fullName = `${sanitizeFileName(fileName)}${isCsv ? '.csv' : '.xlsx'}`;
+
+  res.setHeader('Content-Type', isCsv ? CSV_CONTENT_TYPE : XLSX_CONTENT_TYPE);
+  res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(fullName)}`);
+  res.setHeader('X-Export-Count', String(totalRows));
+  res.send(buffer);
+  return { totalRows, fullName };
+};
+
+module.exports = {
+  XLSX_CONTENT_TYPE,
+  CSV_CONTENT_TYPE,
+  sanitizeSheetName,
+  buildXlsxBuffer,
+  buildCsvBuffer,
+  sendWorkbookDownload,
+};

backend/src/services/localSchema.js

@@ -3,7 +3,6 @@ const { cleanupRetiredFeatureSettings } = require('./retiredFeatures');
 const { ensureDepartmentPagePermissions, ensureSidebarRolePermissions } = require('./pageAccess');
 const { repairDuplicateExternalDepartments } = require('./socialAuth');
 const { ensureSetupConfigDefaults } = require('./setupWizard');
-const { ensureDesktopReleaseSchema } = require('./desktopReleaseService');
 const { ensureDesktopPresenceSchema } = require('./desktopPresenceService');
 const { ensureDesktopExecutionTaskSchema } = require('./desktopExecutionTaskService');
 const { ensureThirdPartySsoSchema } = require('./thirdPartySsoService');
@@ -13,6 +12,11 @@ const {
   ensureProductMonitoringSchema,
   warmProductMonitoringDataset,
 } = require('./productMonitoringService');
+const { ensureReturnMonitorSchema } = require('./returnMonitorSchema');
+const {
+  ensureReturnStockWarningSchema,
+} = require('./returnStockWarningSchema');
+const { warmReturnStockWarningCache } = require('./returnStockWarningService');
 
 const USER_COLUMNS = [
   ['auth_source', "VARCHAR(20) NOT NULL DEFAULT 'local' COMMENT 'Recent auth source: local/dingtalk/google'"],
@@ -119,6 +123,18 @@ async function ensureTable(tableName, createSql) {
   }
 }
 
+async function tableExists(tableName) {
+  const rows = await database.local.query(
+    `SELECT 1
+     FROM information_schema.tables
+     WHERE table_schema = DATABASE()
+       AND table_name = ?
+     LIMIT 1`,
+    [tableName]
+  );
+  return rows.length > 0;
+}
+
 async function indexExists(tableName, indexName) {
   const rows = await database.local.query(
     `SELECT 1
@@ -279,7 +295,27 @@ async function ensureLocalSchema() {
       UNIQUE KEY uk_ops_b_period_scope (scope_start, scope_end)
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`
   );
-  await ensureDesktopReleaseSchema();
+  await ensureTable(
+    'product_analysis_user_prefs',
+    `CREATE TABLE IF NOT EXISTS product_analysis_user_prefs (
+      user_id BIGINT PRIMARY KEY COMMENT '用户ID',
+      prefs_json VARCHAR(2000) NOT NULL COMMENT '个性化配置 JSON',
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品分析用户个性化配置'`
+  );
+  if (await tableExists('pricing_calculator_user_prefs')) {
+    await database.local.query(
+      `INSERT INTO product_analysis_user_prefs (user_id, prefs_json, created_at, updated_at)
+       SELECT user_id, prefs_json, created_at, updated_at
+       FROM pricing_calculator_user_prefs
+       WHERE JSON_VALID(prefs_json)
+         AND JSON_EXTRACT(prefs_json, '$.productAnalysisSignalThresholds') IS NOT NULL
+       ON DUPLICATE KEY UPDATE
+         prefs_json = VALUES(prefs_json),
+         updated_at = VALUES(updated_at)`
+    );
+  }
   await ensureDesktopPresenceSchema();
   await ensureDesktopExecutionTaskSchema();
   await ensureThirdPartySsoSchema();
@@ -921,6 +957,10 @@ async function ensureLocalSchema() {
   );
 
   await ensureProductMonitoringSchema();
+  await ensureReturnMonitorSchema();
+  await ensureReturnStockWarningSchema();
+  // 退货库存预警数据集（约 1,800 行，首次回源 3~10s）后台预热，不阻塞启动
+  void warmReturnStockWarningCache();
 
   await ensureSidebarRolePermissions();
   // 商品监控数据集（5.6 万行，构建约 30s）后台预热，不阻塞启动

backend/src/services/mkhReplenishAlertSettings.js

@@ -0,0 +1,227 @@
+'use strict';
+
+// MKH 成品补货预警推送 —— 配置 + 推送状态（本地库 system_config）
+//
+// ── 配置键 mkh_replenish_alert_config ─────────────────────────────
+//   { enabled, recipientAlias, scope }
+//   · recipientAlias 为空时回退顺序：环境变量 → 统一通知中心默认收件人
+//   · scope: 'warning'（缺货 + 3 天内预警，默认）| 'outOfStock'（仅缺货）
+//
+// ── 状态键 mkh_replenish_alert_state ──────────────────────────────
+//   { version, notified: { [skuId]: { level, firstNotifiedAt, lastNotifiedAt, ... } }, lastRunAt }
+//   · 用于实现「只提醒新出现的预警」：已在 notified 里的商品不再重复推送；
+//     商品恢复到正常范围后从 notified 移除，下次再预警会重新提醒。
+
+const database = require('../config/database');
+const {
+  getYydNotificationCenterRuntimeConfig,
+  toAdminConfig: toNotificationCenterAdminConfig,
+} = require('./yydNotificationCenterSettings');
+
+const CONFIG_KEY = 'mkh_replenish_alert_config';
+const STATE_KEY = 'mkh_replenish_alert_state';
+const CONFIG_CACHE_TTL_MS = 30 * 1000;
+
+const SCOPES = Object.freeze({ WARNING: 'warning', OUT_OF_STOCK: 'outOfStock' });
+
+const SCOPE_OPTIONS = Object.freeze([
+  { value: SCOPES.WARNING, label: '缺货 + 3天内预警' },
+  { value: SCOPES.OUT_OF_STOCK, label: '仅缺货' },
+]);
+
+let cachedConfig = null;
+let cachedAt = 0;
+
+function normalizeText(value, maxLength = 200) {
+  return String(value ?? '').trim().slice(0, maxLength);
+}
+
+function safeJsonParse(value, fallback = {}) {
+  if (value && typeof value === 'object') return value;
+  try {
+    const parsed = JSON.parse(String(value || ''));
+    return parsed && typeof parsed === 'object' ? parsed : fallback;
+  } catch (_error) {
+    return fallback;
+  }
+}
+
+function normalizeScope(value) {
+  const text = normalizeText(value, 40).toLowerCase();
+  if (!text) return SCOPES.WARNING;
+  if (text === 'outofstock' || text === 'out_of_stock' || text === '缺货') return SCOPES.OUT_OF_STOCK;
+  if (text === 'warning' || text === 'warn' || text === '预警' || text === 'all') return SCOPES.WARNING;
+  return SCOPES.WARNING;
+}
+
+function normalizeFlag(value, fallback = true) {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (typeof value === 'boolean') return value;
+  const text = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(text)) return true;
+  if (['0', 'false', 'no', 'off'].includes(text)) return false;
+  return fallback;
+}
+
+async function readSystemConfigValue(key) {
+  const rows = await database.local.query(
+    'SELECT config_value AS configValue FROM system_config WHERE config_key = ? LIMIT 1',
+    [key]
+  );
+  return rows?.[0]?.configValue;
+}
+
+async function upsertSystemConfigValue(key, value, configType = 'json') {
+  const payload = typeof value === 'string' ? value : JSON.stringify(value);
+  const rows = await database.local.query(
+    'SELECT id FROM system_config WHERE config_key = ? LIMIT 1',
+    [key]
+  );
+  if (rows?.[0]) {
+    await database.local.query(
+      'UPDATE system_config SET config_value = ?, config_type = ? WHERE config_key = ?',
+      [payload, configType, key]
+    );
+  } else {
+    await database.local.insert('system_config', {
+      config_key: key,
+      config_value: payload,
+      config_type: configType,
+    });
+  }
+  return payload;
+}
+
+// ── 配置 ────────────────────────────────────────────────────────
+async function getMkhReplenishAlertRuntimeConfig({ forceRefresh = false } = {}) {
+  if (!forceRefresh && cachedConfig && Date.now() - cachedAt < CONFIG_CACHE_TTL_MS) {
+    return { ...cachedConfig };
+  }
+  let stored = {};
+  try {
+    stored = safeJsonParse(await readSystemConfigValue(CONFIG_KEY), {});
+  } catch (error) {
+    console.warn('读取补货预警推送配置失败，使用默认值:', error.message);
+  }
+  cachedConfig = {
+    enabled: normalizeFlag(stored.enabled, true),
+    recipientAlias: normalizeText(stored.recipientAlias || stored.recipient_alias, 50),
+    scope: normalizeScope(stored.scope),
+    recipientAliasFallback: normalizeText(process.env.MKH_REPLENISH_ALERT_RECIPIENT_ALIAS, 50),
+  };
+  cachedAt = Date.now();
+  return { ...cachedConfig };
+}
+
+/**
+ * 解析实际收件人 alias：配置填写值 → 环境变量 → 统一通知中心默认收件人。
+ */
+async function resolveMkhReplenishAlertRecipient(options = {}) {
+  const config = options.config || await getMkhReplenishAlertRuntimeConfig();
+  if (config.recipientAlias) return { alias: config.recipientAlias, source: 'config' };
+  if (config.recipientAliasFallback) return { alias: config.recipientAliasFallback, source: 'environment' };
+  let center = {};
+  try {
+    center = await getYydNotificationCenterRuntimeConfig({ forceRefresh: options.forceRefresh === true });
+  } catch (_error) {
+    center = {};
+  }
+  const alias = normalizeText(center?.recipientAlias, 50);
+  return { alias, source: alias ? 'notification_center' : 'none' };
+}
+
+async function getMkhReplenishAlertAdminConfig() {
+  const config = await getMkhReplenishAlertRuntimeConfig({ forceRefresh: true });
+  const recipient = await resolveMkhReplenishAlertRecipient({ config });
+  let center = {};
+  try {
+    center = await getYydNotificationCenterRuntimeConfig();
+  } catch (_error) {
+    center = {};
+  }
+  const centerAdmin = toNotificationCenterAdminConfig(center);
+  const state = await loadMkhReplenishAlertState();
+  return {
+    enabled: config.enabled,
+    scope: config.scope,
+    recipientAlias: config.recipientAlias,
+    effectiveRecipientAlias: recipient.alias || '',
+    recipientSource: recipient.source,
+    notificationCenterConfigured: centerAdmin.configured,
+    notificationCenterBaseUrl: centerAdmin.baseUrl,
+    notificationCenter: {
+      configured: centerAdmin.configured,
+      baseUrl: centerAdmin.baseUrl,
+      projectCode: centerAdmin.projectCode,
+      projectSecretConfigured: centerAdmin.projectSecretConfigured,
+      projectSecretPreview: centerAdmin.projectSecretPreview,
+      recipientAlias: centerAdmin.recipientAlias,
+    },
+    notifiedCount: Object.keys(state.notified || {}).length,
+    lastRunAt: state.lastRunAt || null,
+    scopeOptions: SCOPE_OPTIONS.map((item) => ({ ...item })),
+  };
+}
+
+async function saveMkhReplenishAlertConfig(input = {}) {
+  const current = await getMkhReplenishAlertRuntimeConfig({ forceRefresh: true });
+  const rawAlias = input.recipientAlias ?? input.recipient_alias;
+  const next = {
+    enabled: normalizeFlag(input.enabled, current.enabled),
+    recipientAlias: normalizeText(rawAlias === undefined ? current.recipientAlias : rawAlias, 50),
+    scope: normalizeScope(input.scope || current.scope),
+  };
+  await upsertSystemConfigValue(CONFIG_KEY, next);
+  cachedConfig = { ...next, recipientAliasFallback: current.recipientAliasFallback };
+  cachedAt = Date.now();
+  return getMkhReplenishAlertAdminConfig();
+}
+
+// ── 推送状态 ────────────────────────────────────────────────────
+async function loadMkhReplenishAlertState() {
+  let parsed = {};
+  try {
+    parsed = safeJsonParse(await readSystemConfigValue(STATE_KEY), {});
+  } catch (error) {
+    console.warn('读取补货预警推送状态失败，按空状态处理:', error.message);
+  }
+  const notified = parsed.notified && typeof parsed.notified === 'object' && !Array.isArray(parsed.notified)
+    ? parsed.notified
+    : {};
+  return {
+    version: 1,
+    notified,
+    lastRunAt: normalizeText(parsed.lastRunAt, 40) || null,
+  };
+}
+
+async function saveMkhReplenishAlertState(state = {}) {
+  const value = {
+    version: 1,
+    notified: state.notified && typeof state.notified === 'object' ? state.notified : {},
+    lastRunAt: normalizeText(state.lastRunAt, 40) || null,
+  };
+  await upsertSystemConfigValue(STATE_KEY, value);
+  return value;
+}
+
+/** 清空「已推送」记录，让下一次检查重新按新增口径判断（便于测试）。 */
+async function resetMkhReplenishAlertState() {
+  return saveMkhReplenishAlertState({ notified: {}, lastRunAt: null });
+}
+
+module.exports = {
+  CONFIG_KEY,
+  STATE_KEY,
+  SCOPES,
+  SCOPE_OPTIONS,
+  getMkhReplenishAlertAdminConfig,
+  getMkhReplenishAlertRuntimeConfig,
+  loadMkhReplenishAlertState,
+  normalizeFlag,
+  normalizeScope,
+  resetMkhReplenishAlertState,
+  resolveMkhReplenishAlertRecipient,
+  saveMkhReplenishAlertConfig,
+  saveMkhReplenishAlertState,
+};

backend/src/services/modularStockMonitorService.js

@@ -0,0 +1,635 @@
+'use strict';
+
+// 模块化库存监控 —— 配件库存监控
+//
+// 需求来源：《模块化库存监控.xlsx》
+//   一级功能：模块化库存监控   二级功能：配件库存监控
+//   表头：图片 | 预警 | 商品编码 | 名称 | 当日入库库存 | 当日出库库存 | 实时库存 |
+//         仓位 | 近15天日均发货量 | 库存可用天数 | 所在仓库
+//   数据范围：仅取「简尚-崔桥工厂半成品包装项目仓」仓库下的商品编码
+//
+// 数据来源（业务库 JSReportReplica / schema=rpt，2026-09-12 实测确认）：
+//   主表  rpt.jst_sku            —— SKU 档案；other_3 = 所属仓库
+//         目标仓库共 794 个 SKU
+//   库存  rpt.jst_inventoryInfo  —— 实时库存 qty；按 wms_co_id 区分仓库
+//         目标仓库 wms_co_id = 15718196（rpt.jst_warehouseInfo 查得）
+//         该表为 0/缺行而箱及仓位库存已有正库存时，用同仓 rpt.jst_packInventoryInfo 合计补齐；
+//         只补 0，不覆盖 inventoryInfo 中的正库存，避免箱表未覆盖散货时低估库存。
+//   监控  rpt.pm_stockMonitor    —— 日更快照，目标仓每天 794 行，覆盖全部 SKU：
+//         fifteenAvgSale 近15天日均发货量（2026-09-17 由 7 天改 15 天，见下）
+//         jsUseDays     库存可用天数
+//         safetyDays    安全天数（默认 15）
+//         suggestStock  建议备货量
+//         jsStock       监控表口径库存（作为 inventoryInfo 的兜底）
+//         nearSecondSale 近一日发货量 → 当日出库
+//
+// ⚠️ 关联键坑（2026-09-12 修正）：
+//   pm_stockMonitor 里同时有 sku 与 sku_id 两列：
+//     sku    = 短款号，如 DNZ040967        —— 用它关联只能命中 34 / 794
+//     sku_id = 完整 SKU 编码 DNZ040967N1440V01 —— 必须用它关联，命中 794 / 794
+//   当日入库：业务库无出入库流水表，用采购到货 rpt.jst_purchaseItem 按「监控日」汇总 inQty
+//   （全库 207 张视图均无库存流水表；dws_sn_sales_full_info_di 是成品销售明细，只命中 97 / 794）
+//
+// ✅ 仓位 location（2026-09-18 改源，旧的「无数据源」结论作废）：
+//   - 旧源 rpt.jst_sku.bin / other_bin 在目标仓 794 行**恒为空**，所以页面长期显示「未维护」
+//   - 新源 rpt.jst_packInventoryInfo.bin（真货位）：该表 2026-09-18 10:48 被上游刷新后
+//     目标仓 794 个 SKU **命中 727 个**（如 ZT-8 / BCP01-01-1）
+//   - 详见 buildLocationSql() 注释
+
+const cloudDatabase = require('../config/cloudDatabase');
+const productDb = require('../config/productInformationDatabase');
+
+const WAREHOUSE_NAME = '简尚-崔桥工厂半成品包装项目仓';
+// rpt.jst_warehouseInfo 中「简尚-崔桥工厂半成品包装项目仓」对应的 wms_co_id
+const WAREHOUSE_WMS_CO_ID = 15718196;
+
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 200;
+const DEFAULT_SAFETY_DAYS = 15;
+// 预警阈值：库存可用天数 <= 7 天即预警（缺货 = 实时库存 <= 0）
+// ⚠️ 2026-09-17 业务确认：未配置MKH 的配件不进任何预警（见 buildWarningOrderSql）
+const LOW_STOCK_DAYS_THRESHOLD = 7;
+
+const WARNING_LEVEL = Object.freeze({
+  OUT_OF_STOCK: '缺货',
+  WARNING: '预警',
+  NORMAL: '正常',
+});
+
+// 模块化配置状态（2026-09-17 业务确认口径，2026-09-17 晚修正）：
+//   「已配置MKH」= 该 SKU 作为「配件商品编码」出现在聚水潭 SKU 级 BOM 维护中，
+//                  被某个 MKH 模块化成品引用：
+//                  业务库 rpt.jst_skuBomItem 中 map_outer_sku_id = 该 SKU
+//                  且父项 sku_id 以 'MKH' 开头（即 MKH 成品档案，如 MKHSJZ0033260600001）。
+//   「未配置MKH」= 未出现在任何 MKH 成品的 BOM 配件清单中。
+//   实测目标仓 794 个 SKU 中 **699** 个命中（按 map_outer_sku_id 匹配、父项 MKH 过滤）。
+//   ⚠️ 历史口径均已废弃：
+//      · 早期「产品资料系统数据库商品档案」口径（661/794）—— 覆盖面过宽、与 BOM 无关；
+//      · 上一版「jst_comboProductItem 组合装引用」口径（29/794）—— 仅命中 MKH- 组合装，
+//        漏掉了真正以 MKH 成品为父项的 BOM 配件，数量明显偏低。
+//   ✅ 当前采用 rpt.jst_skuBomItem（聚水潭 SKU BOM 明细，含配件商品编码 map_outer_sku_id）。
+const MKH_STATUS = Object.freeze({
+  CONFIGURED: '已配置MKH',
+  UNCONFIGURED: '未配置MKH',
+});
+
+const SORTABLE_FIELDS = Object.freeze({
+  skuId: 's.sku_id',
+  productName: 's.name',
+  category: 's.category',
+  realtimeStock: 'realtimeStock',
+  avgShip15d: 'm.fifteenAvgSale',
+  stockDays: 'stockDays',
+  warningLevel: 'warningOrder',
+  mkhStatus: 'mkhStatus',
+  location: 'location',
+  warehouse: 's.other_3',
+});
+
+// 实时库存优先使用库存表；库存表没有正库存时，用同仓「箱及仓位库存」补齐。
+// 聚水潭上游可能已经生成箱/仓位库存，但 jst_inventoryInfo 仍停留在旧值。
+// 只补 0/缺行，避免箱表只记录部分装箱库存时压低库存表中的有效库存。
+const buildRealtimeStockSql = () => (
+  `CASE
+     WHEN inv.qty > 0 THEN inv.qty
+     WHEN ISNULL(ploc.packQty, 0) > 0 THEN ploc.packQty
+     WHEN inv.qty IS NOT NULL THEN inv.qty
+     ELSE ISNULL(m.jsStock, 0)
+   END`
+);
+
+// 箱表兜底生效时，监控快照的 jsUseDays 仍基于旧库存，需要同步重算。
+// 无日销时返回 NULL，不能因为旧快照为 0 天而把已有库存误报为低库存。
+const buildStockDaysSql = () => (
+  `CASE
+     WHEN ISNULL(inv.qty, 0) <= 0 AND ISNULL(ploc.packQty, 0) > 0 THEN
+       CASE
+         WHEN ISNULL(m.fifteenAvgSale, 0) > 0
+           THEN CAST(ploc.packQty / NULLIF(m.fifteenAvgSale, 0) AS DECIMAL(18, 2))
+         ELSE NULL
+       END
+     ELSE m.jsUseDays
+   END`
+);
+
+/**
+ * 「已配置MKH」判定表达式（2026-09-17 晚修正口径）：
+ *   该 SKU 作为「配件商品编码」（map_outer_sku_id）出现在聚水潭 SKU 级 BOM 维护
+ *   rpt.jst_skuBomItem 中，且父项 sku_id 以 'MKH' 开头（即被某个 MKH 模块化成品引用）。
+ */
+const buildConfiguredExistsSql = () => (
+  `EXISTS (
+     SELECT 1 FROM rpt.jst_skuBomItem x
+     WHERE x.map_outer_sku_id = s.sku_id
+       AND x.sku_id LIKE N'MKH%'
+   )`
+);
+
+/**
+ * 统一的「预警等级(数值)」表达式（2026-09-17 业务确认：未配置MKH 不进任何预警）。
+ *   0 = 缺货 / 1 = 预警 / 2 = 正常
+ *   未配置MKH（cfg.configured = 0）一律判为「正常」，不报缺货也不报预警。
+ *   注意 cfg / inv / m 三个别名都来自 buildBaseSql 的 OUTER APPLY，WHERE / SELECT 中均可引用。
+ *   列表映射、汇总计数、筛选、排序四处共用此表达式，避免口径不一致。
+ */
+const buildWarningOrderSql = () => (
+  `CASE
+     WHEN cfg.configured = 0 THEN 2
+     WHEN ${buildRealtimeStockSql()} <= 0 THEN 0
+     WHEN ${buildStockDaysSql()} IS NOT NULL
+       AND ${buildStockDaysSql()} <= ${LOW_STOCK_DAYS_THRESHOLD} THEN 1
+     ELSE 2
+   END`
+);
+
+/**
+ * 统一的「仓位」表达式（2026-09-18 改源）。
+ *   旧源 `jst_sku.bin / other_bin` 在目标仓 794 行**恒为空**（页面因此长期显示「未维护」）；
+ *   真货位在 `rpt.jst_packInventoryInfo.bin` —— 该表 2026-09-18 10:48 被上游刷新后，
+ *   目标仓 794 个 SKU **命中 727 个**（09-19 实测；该表小时级增量刷新，命中数会变）。
+ *   ⚠️ 只取 bin，**不 join 仓名**，所以不受该表 wh_id / wms_co_id 关联列问题影响（见
+ *      mkhBomService 文件头 ⑤；那个坑只影响 MKH-BOM 页配件仓位列的仓名文本）。
+ *   · 只取 `qty > 0` 的箱，同 SKU 多箱时取库存最大的那个（列表页只展示主货位）
+ *   · 取不到才回退商品档案的 bin / other_bin（目前仍全空，保留兜底不影响结果）
+ *   与 MKH-BOM 页 `mkhBomService.loadComponentLocations()` 同源，区别只在本页取单个主货位。
+ *   ⚠️ 列表映射、仓位筛选两处共用此表达式，改口径时只改这里。
+ */
+const buildLocationSql = () => (
+  `COALESCE(
+     ploc.bin,
+     NULLIF(LTRIM(RTRIM(s.bin)), N''),
+     NULLIF(LTRIM(RTRIM(s.other_bin)), N'')
+   )`
+);
+
+const buildBaseSql = () => `
+FROM dbo.jst_sku s
+OUTER APPLY (
+  SELECT TOP 1 i.qty
+  FROM dbo.jst_inventoryInfo i
+  WHERE i.sku_id = s.sku_id AND i.wms_co_id = @wmsCoId
+  ORDER BY i.updateTime DESC
+) inv
+OUTER APPLY (
+  SELECT TOP 1 m2.fifteenAvgSale, m2.jsUseDays, m2.safetyDays, m2.suggestStock,
+               m2.date, m2.jsStock, m2.nearSecondSale
+  FROM dbo.pm_stockMonitor m2
+  WHERE m2.sku_id = s.sku_id AND m2.warehouse = @warehouseName
+  ORDER BY m2.date DESC
+) m
+OUTER APPLY (
+  SELECT CAST(SUM(ISNULL(p.inQty, 0)) AS DECIMAL(18, 2)) AS inQty
+  FROM dbo.jst_purchaseItem p
+  WHERE p.sku_id = s.sku_id
+    AND p.delivery_date >= @monitorDate
+    AND p.delivery_date < DATEADD(DAY, 1, @monitorDate)
+) pin
+-- 采购在途：该 SKU 全部采购单中「已下单 − 已入库」的未到货部分合计
+--   jst_purchaseItem.qty = 采购数量，inQty = 已入库数量，plan_arrive_qty 全库恒为 0（不可用）、
+--   is_delivery 全库恒为 0（不可信），故在途口径 = SUM(MAX(0, qty − inQty))。
+--   ⚠️ 此列只参与「取数/展示」，绝不参与 ORDER BY / 聚合（参考本文件头 MSSQL 坑说明，
+--      对 OUTER APPLY 列做排序/聚合会触发灾难性执行计划）。
+OUTER APPLY (
+  SELECT CAST(SUM(CASE WHEN p.qty > ISNULL(p.inQty, 0) THEN p.qty - ISNULL(p.inQty, 0) ELSE 0 END) AS DECIMAL(18, 2)) AS transit
+  FROM dbo.jst_purchaseItem p
+  WHERE p.sku_id = s.sku_id
+) ptr
+OUTER APPLY (
+  SELECT TOP 1 NULLIF(LTRIM(RTRIM(c.pictureSkucode)), N'') AS pictureSkucode
+  FROM dbo.fys_skuCostPriceUpdate c
+  WHERE UPPER(LTRIM(RTRIM(TRY_CONVERT(NVARCHAR(100), c.sku)))) = UPPER(LTRIM(RTRIM(TRY_CONVERT(NVARCHAR(100), s.sku_id))))
+  ORDER BY c.createTime DESC
+) cost
+-- 仓位及箱库存：先按 SKU/仓位一次性汇总，再关联目标仓，避免对 794 个 SKU
+-- 分别扫描无独立索引的上游视图。rn=1 是库存最大的主货位，packQty 是该 SKU 全仓合计。
+LEFT JOIN (
+  SELECT ranked.sku_id, ranked.wms_co_id, ranked.bin, ranked.packQty
+  FROM (
+    SELECT
+      pk.sku_id,
+      pk.wms_co_id,
+      NULLIF(LTRIM(RTRIM(pk.bin)), N'') AS bin,
+      SUM(ISNULL(pk.qty, 0)) AS binQty,
+      SUM(SUM(ISNULL(pk.qty, 0))) OVER (PARTITION BY pk.sku_id, pk.wms_co_id) AS packQty,
+      ROW_NUMBER() OVER (
+        PARTITION BY pk.sku_id, pk.wms_co_id
+        ORDER BY SUM(ISNULL(pk.qty, 0)) DESC, NULLIF(LTRIM(RTRIM(pk.bin)), N'') ASC
+      ) AS rn
+    FROM dbo.jst_packInventoryInfo pk WITH (NOLOCK)
+    WHERE pk.wms_co_id = @wmsCoId
+      AND NULLIF(LTRIM(RTRIM(pk.bin)), N'') IS NOT NULL
+    GROUP BY pk.sku_id, pk.wms_co_id, NULLIF(LTRIM(RTRIM(pk.bin)), N'')
+    HAVING SUM(ISNULL(pk.qty, 0)) > 0
+  ) ranked
+  WHERE ranked.rn = 1
+) ploc ON ploc.sku_id = s.sku_id AND ploc.wms_co_id = @wmsCoId
+-- 模块化配置状态：见文件头部「已配置MKH」口径说明
+OUTER APPLY (
+  SELECT CAST(CASE WHEN ${buildConfiguredExistsSql()} THEN 1 ELSE 0 END AS BIT) AS configured
+) cfg
+WHERE s.other_3 = @warehouseName`;
+
+const toNumber = (value) => {
+  if (value === null || value === undefined || value === '') return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+const toText = (value) => {
+  if (value === null || value === undefined) return null;
+  const text = String(value).trim();
+  return text === '' ? null : text;
+};
+
+const WARNING_ORDER = {
+  [WARNING_LEVEL.OUT_OF_STOCK]: 0,
+  [WARNING_LEVEL.WARNING]: 1,
+  [WARNING_LEVEL.NORMAL]: 2,
+};
+
+/**
+ * 取目标仓最新监控日（pm_stockMonitor 快照日），作为「当日入库 / 当日出库」的统计基准日。
+ * 业务库没有出入库流水表，只能以监控日为基准做按日汇总。
+ */
+async function resolveMonitorDate() {
+  const rows = await cloudDatabase.query(
+    `SELECT CAST(MAX(date) AS DATE) AS monitorDate
+     FROM dbo.pm_stockMonitor
+     WHERE warehouse = @warehouseName`,
+    { warehouseName: WAREHOUSE_NAME },
+    { requestTimeout: 120000 }
+  );
+
+  const raw = rows?.[0]?.monitorDate;
+  if (!raw) return null;
+  const d = new Date(raw);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString().slice(0, 10);
+}
+
+const buildFilters = (query = {}, monitorDate = null) => {
+  const conditions = [];
+  const params = {
+    wmsCoId: WAREHOUSE_WMS_CO_ID,
+    warehouseName: WAREHOUSE_NAME,
+    monitorDate,
+  };
+
+  const keyword = toText(query.keyword);
+  if (keyword) {
+    params.keyword = `%${keyword}%`;
+    conditions.push('(s.sku_id LIKE @keyword OR s.name LIKE @keyword)');
+  }
+
+  const category = toText(query.category);
+  if (category) {
+    params.category = category;
+    conditions.push('s.category = @category');
+  }
+
+  const location = toText(query.location);
+  if (location) {
+    params.location = location;
+    conditions.push(`${buildLocationSql()} = @location`);
+  }
+
+  const mkhStatus = toText(query.mkhStatus);
+  if (mkhStatus === MKH_STATUS.CONFIGURED || mkhStatus === MKH_STATUS.UNCONFIGURED) {
+    params.mkhStatus = mkhStatus;
+    conditions.push(`CASE WHEN cfg.configured = 1 THEN N'${MKH_STATUS.CONFIGURED}' ELSE N'${MKH_STATUS.UNCONFIGURED}' END = @mkhStatus`);
+  }
+
+  const warningLevel = toText(query.warningLevel);
+  if (warningLevel && Object.prototype.hasOwnProperty.call(WARNING_ORDER, warningLevel)) {
+    params.warningOrder = WARNING_ORDER[warningLevel];
+    // 用统一表达式，未配置MKH 不参与预警判定（筛「缺货 / 预警」时不会漏出未配置MKH）
+    conditions.push(`${buildWarningOrderSql()} = @warningOrder`);
+  }
+
+  const onlyWarning = String(query.onlyWarning || '').toLowerCase();
+  if (['1', 'true', 'yes'].includes(onlyWarning)) {
+    // 仅看缺货 / 预警：统一表达式 <= 1（未配置MKH 一律为 2，自动排除）
+    conditions.push(`${buildWarningOrderSql()} <= 1`);
+  }
+
+  return { conditions, params };
+};
+
+/**
+ * 用「产品资料系统数据库」补齐商品图片。
+ *
+ * ⚠️ 2026-09-15 实测：目标仓 794 个 SKU 在业务库里图片字段全部为空——
+ *    rpt.jst_sku.pic / pic_big          794/794 为 NULL
+ *    rpt.fys_skuCostPriceUpdate.pictureSkucode  794/794 为 NULL
+ *    且 rpt.jst_sku 中只有 pic / pic_big 两个图片列，无其他图片源。
+ * 因此图片统一改从产品资料系统数据库（PostgreSQL）取：
+ *    external.product_catalog_wide_base_v1
+ *      按 barcode（完整 SKU 编码）匹配，image_url 优先、product_thumbnail_url 兜底
+ *      实测目标仓 661 条可匹配，其中 481 条带图。
+ * 查询失败时静默降级，不影响列表主流程。
+ */
+async function attachProductImages(rows = []) {
+  const codes = Array.from(new Set(rows.map((row) => toText(row.skuId)).filter(Boolean)));
+  if (codes.length === 0) {
+    return rows;
+  }
+
+  const imageMap = new Map();
+  try {
+    const imageRows = await productDb.query(
+      `SELECT barcode, image_url, product_thumbnail_url
+       FROM external.product_catalog_wide_base_v1
+       WHERE barcode = ANY($1)`,
+      [codes]
+    );
+
+    imageRows.forEach((row) => {
+      const code = toText(row.barcode);
+      if (!code || imageMap.has(code)) return;
+      const url = toText(row.image_url) || toText(row.product_thumbnail_url);
+      if (url) imageMap.set(code, url);
+    });
+  } catch (error) {
+    console.warn('[ModularStock] 读取产品资料库图片失败，降级为业务库图片:', error.message);
+  }
+
+  return rows.map((row) => ({
+    ...row,
+    productImageUrl: imageMap.get(toText(row.skuId)) || null,
+  }));
+}
+
+/**
+ * 「已配置MKH」判定说明（2026-09-17 晚修正）：
+ *   直接由 buildBaseSql 的 cfg 子查询判定，数据源为聚水潭 SKU 级 BOM 维护
+ *   rpt.jst_skuBomItem（map_outer_sku_id = 该 SKU 且父项 sku_id 以 'MKH' 开头），
+ *   不再依赖产品资料系统数据库。产品资料库仅用于补齐商品图片（见 attachProductImages）。
+ */
+
+const mapRow = (row = {}) => {
+  const realtimeStock = Number(row.realtimeStock || 0);
+  const stockDays = toNumber(row.stockDays);
+  const safetyDays = toNumber(row.safetyDays) ?? DEFAULT_SAFETY_DAYS;
+  // 预警等级以 SQL 端 buildWarningOrderSql() 的判定为准（已含「未配置MKH 不进预警」规则），
+  // 前端显示与排序口径保持一致，避免前后端各算一份。
+  const warningOrder = Number(row.warningOrder ?? WARNING_ORDER[WARNING_LEVEL.NORMAL]);
+  const warningLevel = warningOrder === WARNING_ORDER[WARNING_LEVEL.OUT_OF_STOCK]
+    ? WARNING_LEVEL.OUT_OF_STOCK
+    : warningOrder === WARNING_ORDER[WARNING_LEVEL.WARNING]
+      ? WARNING_LEVEL.WARNING
+      : WARNING_LEVEL.NORMAL;
+
+  return {
+    skuId: toText(row.skuId),
+    productName: toText(row.productName),
+    category: toText(row.category),
+    // 图片优先取产品资料系统数据库（业务库 pic/pic_big 目标仓全为空）
+    imageUrl: toText(row.productImageUrl) || toText(row.imageUrl),
+    warningLevel,
+    warningOrder,
+    mkhStatus: toText(row.mkhStatus) || MKH_STATUS.UNCONFIGURED,
+    // 业务库无出入库流水表：入库取采购到货（监控日），出库取 pm_stockMonitor 近一日发货量
+    inQtyToday: toNumber(row.inQtyToday) ?? 0,
+    outQtyToday: toNumber(row.outQtyToday) ?? 0,
+    realtimeStock,
+    purchaseTransit: toNumber(row.purchaseTransit) ?? 0,
+    location: toText(row.location),
+    avgShip15d: toNumber(row.avgShip15d),
+    stockDays,
+    safetyDays,
+    suggestStock: toNumber(row.suggestStock),
+    warehouse: toText(row.warehouse) || WAREHOUSE_NAME,
+  };
+};
+
+const buildProjection = () => `
+  s.sku_id                                                                        AS skuId,
+  s.name                                                                          AS productName,
+  s.category                                                                      AS category,
+  ${buildRealtimeStockSql()}                                                     AS realtimeStock,
+  ISNULL(ptr.transit, 0)                                                          AS purchaseTransit,
+  ISNULL(pin.inQty, 0)                                                            AS inQtyToday,
+  ISNULL(m.nearSecondSale, 0)                                                     AS outQtyToday,
+  ${buildLocationSql()}                                                           AS location,
+  m.fifteenAvgSale                                                                AS avgShip15d,
+  ${buildStockDaysSql()}                                                          AS stockDays,
+  m.safetyDays                                                                    AS safetyDays,
+  m.suggestStock                                                                  AS suggestStock,
+  s.other_3                                                                       AS warehouse,
+  COALESCE(
+    NULLIF(LTRIM(RTRIM(s.pic_big)), N''),
+    NULLIF(LTRIM(RTRIM(s.pic)), N''),
+    cost.pictureSkucode
+  )                                                                               AS imageUrl,
+  CASE WHEN cfg.configured = 1 THEN N'已配置MKH' ELSE N'未配置MKH' END               AS mkhStatus,
+  ${buildWarningOrderSql()}                                                      AS warningOrder,
+  m.date                                                                          AS monitorDate`;
+
+async function getModularStockList(query = {}) {
+  const page = Math.max(1, Number.parseInt(query.page, 10) || 1);
+  const requestedSize = Number.parseInt(query.pageSize, 10) || DEFAULT_PAGE_SIZE;
+  const pageSize = Math.min(MAX_PAGE_SIZE, Math.max(1, requestedSize));
+  const monitorDate = await resolveMonitorDate();
+  const { conditions, params } = buildFilters(query, monitorDate);
+  const baseSql = buildBaseSql();
+  const whereSql = conditions.length ? `${baseSql} AND ${conditions.join(' AND ')}` : baseSql;
+
+  const sortField = SORTABLE_FIELDS[query.sortField] ? query.sortField : 'realtimeStock';
+  const sortOrder = String(query.sortOrder || 'DESC').toUpperCase() === 'ASC' ? 'ASC' : 'DESC';
+  const orderSql = `${SORTABLE_FIELDS[sortField]} ${sortOrder}`;
+
+  const offset = (page - 1) * pageSize;
+
+  // 已按 s.sku_id 排序时不再追加 tie-breaker，否则 ORDER BY 出现重复列报错 169
+  const orderClause = SORTABLE_FIELDS[sortField] === 's.sku_id'
+    ? orderSql
+    : `${orderSql}, s.sku_id ASC`;
+
+  const rows = await cloudDatabase.query(
+    `SELECT ${buildProjection()}
+     ${whereSql}
+     ORDER BY ${orderClause}
+     OFFSET ${offset} ROWS FETCH NEXT ${pageSize} ROWS ONLY`,
+    params,
+    { requestTimeout: 180000 }
+  );
+
+  const [totalRow] = await cloudDatabase.query(
+    `SELECT COUNT_BIG(*) AS total ${whereSql}`,
+    params,
+    { requestTimeout: 180000 }
+  );
+
+  const [summaryRow] = await buildSummary(whereSql, params);
+
+  // 用产品资料系统数据库补齐图片（业务库目标仓图片字段全为空）
+  const enrichedRows = await attachProductImages(rows);
+
+  return {
+    rows: enrichedRows.map(mapRow),
+    total: Number(totalRow?.total || 0),
+    page,
+    pageSize,
+    warehouse: WAREHOUSE_NAME,
+    monitorDate: summaryRow?.monitorDate || monitorDate,
+    summary: {
+      skuCount: summaryRow?.skuCount || 0,
+      outOfStockCount: summaryRow?.outOfStockCount || 0,
+      lowStockDaysCount: summaryRow?.lowStockDaysCount || 0,
+      configuredCount: summaryRow?.configuredCount || 0,
+      unconfiguredCount: (summaryRow?.skuCount || 0) - (summaryRow?.configuredCount || 0),
+      totalStock: summaryRow?.totalStock || 0,
+      totalPurchaseTransit: summaryRow?.totalPurchaseTransit || 0,
+    },
+  };
+}
+
+async function buildSummary(whereSql, params) {
+  const rows = await cloudDatabase.query(
+    `SELECT
+       COUNT_BIG(*)                                                                   AS skuCount,
+       SUM(CASE WHEN ${buildWarningOrderSql()} = 0 THEN 1 ELSE 0 END)                          AS outOfStockCount,
+       CAST(ISNULL(SUM(${buildRealtimeStockSql()}), 0) AS BIGINT)                                  AS totalStock,
+       CAST(ISNULL(SUM(ISNULL(ptr.transit, 0)), 0) AS BIGINT)                                   AS totalPurchaseTransit,
+       SUM(CASE WHEN ${buildWarningOrderSql()} = 1 THEN 1 ELSE 0 END)                          AS lowStockDaysCount,
+       SUM(CASE WHEN cfg.configured = 1 THEN 1 ELSE 0 END)                                       AS configuredCount,
+       MAX(m.date)                                                                    AS monitorDate
+     ${whereSql}`,
+    params,
+    { requestTimeout: 180000 }
+  );
+  const row = rows[0] || {};
+
+  return [{
+    skuCount: Number(row.skuCount || 0),
+    outOfStockCount: Number(row.outOfStockCount || 0),
+    totalStock: Number(row.totalStock || 0),
+    totalPurchaseTransit: Number(row.totalPurchaseTransit || 0),
+    lowStockDaysCount: Number(row.lowStockDaysCount || 0),
+    configuredCount: Number(row.configuredCount || 0),
+    monitorDate: row.monitorDate ? new Date(row.monitorDate).toISOString().slice(0, 10) : null,
+  }];
+}
+
+async function getModularStockFilters() {
+  // 2026-09-18 修正：品类下拉不需要 JOIN 库存/采购/监控等重表，只用 SKU 主表即可，
+  // 避免 buildBaseSql 里新增采购在途 OUTER APPLY 后把 filters 接口拖慢。
+  const rows = await cloudDatabase.query(
+    `SELECT DISTINCT s.category
+     FROM dbo.jst_sku s
+     WHERE s.other_3 = @warehouseName
+       AND s.category IS NOT NULL
+       AND LTRIM(RTRIM(s.category)) <> N''
+     ORDER BY s.category`,
+    { warehouseName: WAREHOUSE_NAME },
+    { requestTimeout: 60000 }
+  );
+
+  return {
+    categories: rows.map((row) => toText(row.category)).filter(Boolean),
+    warningLevels: [WARNING_LEVEL.OUT_OF_STOCK, WARNING_LEVEL.WARNING, WARNING_LEVEL.NORMAL],
+    mkhStatuses: [MKH_STATUS.CONFIGURED, MKH_STATUS.UNCONFIGURED],
+    warehouse: WAREHOUSE_NAME,
+  };
+}
+
+/**
+ * 采购在途明细列表：目标仓全部「采购数量 > 已入库数量」的采购单明细。
+ *   口径：在途数量 = qty − inQty（已下单但尚未入库的部分）。
+ *   支持 keyword 搜索商品编码 / 名称，支持按 transitQty（默认）/ skuId / purchaseQty / deliveryDate 排序。
+ */
+async function getPurchaseInTransitList(query = {}) {
+  const page = Math.max(1, Number.parseInt(query.page, 10) || 1);
+  const requestedSize = Number.parseInt(query.pageSize, 10) || DEFAULT_PAGE_SIZE;
+  const pageSize = Math.min(MAX_PAGE_SIZE, Math.max(1, requestedSize));
+
+  const keyword = toText(query.keyword);
+  const params = { warehouseName: WAREHOUSE_NAME };
+  let whereSql = `s.other_3 = @warehouseName AND p.qty > ISNULL(p.inQty, 0)`;
+  if (keyword) {
+    params.keyword = `%${keyword}%`;
+    whereSql += ` AND (p.sku_id LIKE @keyword OR p.name LIKE @keyword)`;
+  }
+
+  const sortField = String(query.sortField || '').trim();
+  const sortOrder = String(query.sortOrder || 'DESC').toUpperCase() === 'ASC' ? 'ASC' : 'DESC';
+  const orderMap = {
+    skuId: 'p.sku_id',
+    deliveryDate: 'p.delivery_date',
+    transitQty: 'transitQty',
+    purchaseQty: 'p.qty',
+  };
+  const orderCol = orderMap[sortField] || 'transitQty';
+  const orderClause = sortField === 'skuId'
+    ? `${orderCol} ${sortOrder}`
+    : `${orderCol} ${sortOrder}, p.sku_id ASC`;
+
+  const offset = (page - 1) * pageSize;
+
+  const [rows, totalRow] = await Promise.all([
+    cloudDatabase.query(
+      `SELECT
+         p.sku_id                                   AS skuId,
+         p.name                                     AS productName,
+         CAST(p.qty AS BIGINT)                      AS purchaseQty,
+         CAST(ISNULL(p.inQty, 0) AS BIGINT)         AS inQty,
+         CAST(p.qty - ISNULL(p.inQty, 0) AS BIGINT) AS transitQty,
+         p.delivery_date                            AS deliveryDate,
+         CAST(p.po_id AS NVARCHAR(50))              AS poId,
+         CAST(p.poi_id AS NVARCHAR(50))             AS poiId
+       FROM rpt.jst_purchaseItem p
+       INNER JOIN dbo.jst_sku s ON s.sku_id = p.sku_id
+       WHERE ${whereSql}
+       ORDER BY ${orderClause}
+       OFFSET ${offset} ROWS FETCH NEXT ${pageSize} ROWS ONLY`,
+      params,
+      { requestTimeout: 180000 }
+    ),
+    cloudDatabase.query(
+      `SELECT COUNT_BIG(*) AS total
+       FROM rpt.jst_purchaseItem p
+       INNER JOIN dbo.jst_sku s ON s.sku_id = p.sku_id
+       WHERE ${whereSql}`,
+      params,
+      { requestTimeout: 180000 }
+    ),
+  ]);
+
+  return {
+    rows: rows.map((row) => ({
+      skuId: toText(row.skuId),
+      productName: toText(row.productName),
+      purchaseQty: Number(row.purchaseQty || 0),
+      inQty: Number(row.inQty || 0),
+      transitQty: Number(row.transitQty || 0),
+      deliveryDate: row.deliveryDate ? new Date(row.deliveryDate).toISOString().slice(0, 10) : null,
+      poId: toText(row.poId),
+      poiId: toText(row.poiId),
+    })),
+    total: Number(totalRow?.[0]?.total || 0),
+    page,
+    pageSize,
+    warehouse: WAREHOUSE_NAME,
+  };
+}
+
+// 手动同步：本页无进程内缓存（每次请求直连副本库），同步动作 = 重新解析监控日并返回，
+// 前端据此刷新列表到最新快照。
+// 注意：副本库由聚水潭侧同步，应用层无法触发上游拉取，这里只保证取到最新监控日。
+async function syncModularStock() {
+  const monitorDate = await resolveMonitorDate();
+  return {
+    syncedAt: new Date().toISOString(),
+    monitorDate,
+  };
+}
+
+module.exports = {
+  WAREHOUSE_NAME,
+  WAREHOUSE_WMS_CO_ID,
+  WARNING_LEVEL,
+  DEFAULT_SAFETY_DAYS,
+  getModularStockList,
+  getModularStockFilters,
+  getPurchaseInTransitList,
+  syncModularStock,
+};

backend/src/services/pickingBinSalesAnalysis.js

@@ -0,0 +1,243 @@
+'use strict';
+
+/**
+ * 拣选库位动销分析 —— 业务库取数
+ *
+ *   库存：rpt.jst_packInventoryInfo 按 wms_co_id + 仓位 + sku_id 汇总 qty（仓位为空的行不参与）
+ *   范围：只统计真实拣选仓位（pack_type=Bin 且 bin_group 为空）；
+ *         箱记录（pack_type=Pack）与存货位（bin_group=存货）不纳入
+ *   销量（4 个来源分支，均按 send_date 窗口）：
+ *     1) rpt.jst_Orders × jst_OrderItem 普通行（sku_type<>combine），排除 Delete/Cancelled
+ *     2) rpt.jst_Orders 组合装行（sku_id 为 ZH-... 拼接串）→ JOIN jst_comboProductItem 展开为子件×数量
+ *     3) rpt.jst_qmcust_orderlist（全民客户 B2B 分销）普通行，排除 Delete/Cancelled/Split/Question
+ *        （Split 是拆单父单，与拆出的子单重复，必须排除）
+ *     4) rpt.jst_qmcust_orderlist 组合装行 → 同样按映射表展开
+ *   粒度：仓位 × 商品编码（一个仓位有 N 个商品就输出 N 行），列表与导出共用
+ *
+ *   【日销与动销等级口径】按「商品日销」判定，不做仓位分摊：
+ *       商品日销 = 该商品在窗口内的整档销量 ÷ 窗口天数
+ *   同一件商品无论占用几个仓位，各行显示的销量 / 日销 / 动销等级完全一致 ——
+ *   不会因为货放得散就被算成滞销。
+ *
+ *   附带输出「分摊销量」= 商品销量 ÷ 该商品占用的同类型仓位数，用于需要按行求和的场景：
+ *       恒等式（已实测校验，差异 0）：全部行分摊销量之和 = 有库位记录的那些 SKU 的销量之和。
+ *   注意它小于「全仓销量」：jst_packInventoryInfo 只覆盖部分 SKU 的仓位数据，
+ *   没有仓位记录的 SKU 的销量不会体现在任何库位上。
+ */
+
+const { PICKING_BIN_GRADE_RULES, BIN_TYPE_PICKING } = require('../config/pickingBinSalesAnalysis');
+
+/** mssql 不支持数组参数，按位展开成 @p0,@p1... */
+function buildInClause(values, prefix) {
+  const params = {};
+  const clause = values
+    .map((v, i) => {
+      const key = `${prefix}${i}`;
+      params[key] = v;
+      return `@${key}`;
+    })
+    .join(',');
+  return { clause, params };
+}
+
+/**
+ * 日销分档表达式：从高档往低档依次命中，最后一档「销售=0」由 salesQty <= 0 兜底。
+ * 传入的 salesExpr 是窗口销量（商品整档销量），除以天数得到日销。
+ */
+function buildGradeCase(salesExpr = 'ISNULL(s.salesQty, 0)', daysParam = '@days') {
+  const branches = PICKING_BIN_GRADE_RULES
+    .filter((rule) => rule.lower > 0)
+    .map((rule) => {
+      const daily = `(${salesExpr} / ${daysParam})`;
+      const lower = `${daily} >= ${rule.lower}`;
+      const upper = rule.upper == null ? null : `${daily} < ${rule.upper}`;
+      const cond = upper ? `${lower} AND ${upper}` : lower;
+      return `WHEN ${cond} THEN '${rule.key}'`;
+    });
+
+  return `
+      CASE
+        ${branches.join('\n        ')}
+        WHEN ${salesExpr} > 0 THEN 'slow2'
+        ELSE 'zero'
+      END`;
+}
+
+/**
+ * 拉取「仓位 × 商品编码」粒度明细（列表与导出共用）。
+ *
+ *   - stockQty：该商品在此仓位的实际库存
+ *   - salesQty：该商品在此仓库的窗口销量（整档，不按仓位分摊），动销等级的判定依据
+ *   - dailySales：salesQty / 窗口天数 = 商品日销
+ *   - allocatedSalesQty：salesQty ÷ 该商品占用的同类型仓位数，用于需要按行求和的场景
+ *   - skuCount：该仓位内存放的商品数（仓位粒度，同一仓位多行重复）
+ *
+ * @param {object} cloudDb 业务库实例
+ * @param {string[]} wmsCoIds 仓库编码
+ * @param {{shipFrom:string, shipTo:string, days:number}} options
+ * @returns {Promise<Array<{wmsCoId:string, binName:string, binType:string, skuId:string,
+ *   stockQty:number, skuCount:number, salesQty:number, allocatedSalesQty:number,
+ *   dailySales:number, gradeKey:string}>>}
+ */
+async function fetchPickingBinSkuRows(cloudDb, wmsCoIds, options = {}) {
+  if (!cloudDb || typeof cloudDb.query !== 'function') {
+    throw new TypeError('fetchPickingBinSkuRows 的第一个参数必须是业务库实例');
+  }
+  const { shipFrom, shipTo, days } = options;
+  if (!Array.isArray(wmsCoIds) || wmsCoIds.length === 0) return [];
+  if (!shipFrom || !shipTo || !days) return [];
+
+  const binIn = buildInClause(wmsCoIds, 'w');
+  const shipIn = buildInClause(wmsCoIds, 'v');
+
+  // 统计范围固定为真实拣选仓位：pack_type=Bin 且 bin_group 为空。
+  // 仅过滤 bin_group 会把同样为空的 Pack 箱记录误标为拣选位。
+  const sqlText = `
+    WITH bin AS (
+      SELECT p.wms_co_id AS wmsCoId,
+             LTRIM(RTRIM(p.bin)) AS binName,
+             N'${BIN_TYPE_PICKING}' AS binType,
+             p.sku_id AS skuId,
+             SUM(CAST(ISNULL(p.qty, 0) AS DECIMAL(18, 2))) AS binSkuQty
+        FROM rpt.jst_packInventoryInfo p
+       WHERE p.wms_co_id IN (${binIn.clause})
+         AND ISNULL(p.bin, '') <> ''
+         AND ISNULL(p.qty, 0) <> 0
+         AND p.pack_type = N'Bin'
+         AND ISNULL(p.bin_group, '') = ''
+       GROUP BY p.wms_co_id,
+                LTRIM(RTRIM(p.bin)),
+                p.sku_id
+    ),
+    binSpan AS (
+      SELECT wmsCoId, skuId, binType, COUNT(DISTINCT binName) AS binCount
+        FROM bin
+       GROUP BY wmsCoId, skuId, binType
+    ),
+    ship AS (
+      -- 1) 线上店铺订单：普通商品行（sku_type<>combine，组合装行在下一分支展开）
+      SELECT o.wms_co_id AS wmsCoId,
+             oi.sku_id   AS skuId,
+             SUM(CAST(ISNULL(oi.qty, 0) AS DECIMAL(18, 2))) AS salesQty
+        FROM rpt.jst_OrderItem oi
+        JOIN rpt.jst_Orders o ON o.o_id = oi.o_id
+       WHERE o.wms_co_id IN (${shipIn.clause})
+         AND o.send_date >= @shipFrom
+         AND o.send_date < @shipTo
+         AND ISNULL(o.status, '') NOT IN ('Delete', 'Cancelled')
+         AND ISNULL(oi.sku_type, 'normal') <> 'combine'
+       GROUP BY o.wms_co_id, oi.sku_id
+      UNION ALL
+      -- 2) 线上店铺订单：组合装行（sku_id 为 ZH-子件A-N-子件B-M 拼接串）→ 按映射表展开为子件
+      SELECT o.wms_co_id AS wmsCoId,
+             ci.src_sku_id AS skuId,
+             SUM(CAST(ISNULL(oi.qty, 0) * ISNULL(ci.qty, 0) AS DECIMAL(18, 2))) AS salesQty
+        FROM rpt.jst_OrderItem oi
+        JOIN rpt.jst_Orders o ON o.o_id = oi.o_id
+        JOIN rpt.jst_comboProductItem ci ON ci.combine_sku_id = oi.sku_id
+       WHERE o.wms_co_id IN (${shipIn.clause})
+         AND o.send_date >= @shipFrom
+         AND o.send_date < @shipTo
+         AND ISNULL(o.status, '') NOT IN ('Delete', 'Cancelled')
+         AND oi.sku_type = 'combine'
+       GROUP BY o.wms_co_id, ci.src_sku_id
+      UNION ALL
+      -- 3) 全民客户（B2B 分销）订单：普通商品行（拆单父单 Split 与子单重复，需排除）
+      SELECT o.wms_co_id AS wmsCoId,
+             oi.sku_id   AS skuId,
+             SUM(CAST(ISNULL(oi.qty, 0) AS DECIMAL(18, 2))) AS salesQty
+        FROM rpt.jst_qmcust_orderlist_item oi
+        JOIN rpt.jst_qmcust_orderlist o ON o.o_id = oi.o_id
+       WHERE o.wms_co_id IN (${shipIn.clause})
+         AND o.send_date >= @shipFrom
+         AND o.send_date < @shipTo
+         AND ISNULL(o.status, '') NOT IN ('Delete', 'Cancelled', 'Split', 'Question')
+         AND ISNULL(oi.sku_type, 'normal') <> 'combine'
+       GROUP BY o.wms_co_id, oi.sku_id
+      UNION ALL
+      -- 4) 全民客户订单：组合装行展开为子件
+      SELECT o.wms_co_id AS wmsCoId,
+             ci.src_sku_id AS skuId,
+             SUM(CAST(ISNULL(oi.qty, 0) * ISNULL(ci.qty, 0) AS DECIMAL(18, 2))) AS salesQty
+        FROM rpt.jst_qmcust_orderlist_item oi
+        JOIN rpt.jst_qmcust_orderlist o ON o.o_id = oi.o_id
+        JOIN rpt.jst_comboProductItem ci ON ci.combine_sku_id = oi.sku_id
+       WHERE o.wms_co_id IN (${shipIn.clause})
+         AND o.send_date >= @shipFrom
+         AND o.send_date < @shipTo
+         AND ISNULL(o.status, '') NOT IN ('Delete', 'Cancelled', 'Split', 'Question')
+         AND oi.sku_type = 'combine'
+       GROUP BY o.wms_co_id, ci.src_sku_id
+    ),
+    shipAgg AS (
+      -- 同一个 仓库+商品 可能同时命中多个来源分支（线上普通/线上组合装/全民客户普通/全民客户组合装），
+      -- 必须先按 仓库+商品 汇总成一行再 join，否则一个仓位行会被拆成多行、每行只带某分支的销量。
+      SELECT wmsCoId,
+             skuId,
+             SUM(CAST(salesQty AS DECIMAL(18, 2))) AS salesQty
+        FROM ship
+       GROUP BY wmsCoId, skuId
+    ),
+    binAgg AS (
+      SELECT wmsCoId,
+             binName,
+             binType,
+             COUNT(DISTINCT skuId) AS skuCount
+        FROM bin
+       GROUP BY wmsCoId, binName, binType
+    )
+    SELECT b.wmsCoId,
+           b.binName,
+           b.binType,
+           b.skuId,
+           CAST(SUM(CAST(b.binSkuQty AS DECIMAL(18, 2))) AS DECIMAL(18, 2))                    AS stockQty,
+           CAST(a.skuCount AS INT)                                                             AS skuCount,
+           CAST(ISNULL(s.salesQty, 0) AS DECIMAL(18, 2))                                       AS salesQty,
+           CAST(ISNULL(s.salesQty, 0) / NULLIF(sp.binCount, 0) AS DECIMAL(18, 4))              AS allocatedSalesQty,
+           CAST(ISNULL(s.salesQty, 0) / @days AS DECIMAL(18, 4))                               AS dailySales,
+           ${buildGradeCase('ISNULL(s.salesQty, 0)')}                                          AS gradeKey
+      FROM bin b
+      JOIN binSpan sp
+        ON sp.wmsCoId = b.wmsCoId AND sp.skuId = b.skuId AND sp.binType = b.binType
+      JOIN binAgg a
+        ON a.wmsCoId = b.wmsCoId AND a.binName = b.binName AND a.binType = b.binType
+      LEFT JOIN shipAgg s
+        ON s.wmsCoId = b.wmsCoId AND s.skuId = b.skuId
+     GROUP BY b.wmsCoId, b.binName, b.binType, b.skuId, a.skuCount, s.salesQty, sp.binCount
+    HAVING ABS(SUM(CAST(b.binSkuQty AS DECIMAL(18, 2)))) > 0.0001
+     ORDER BY b.wmsCoId, b.binType, b.binName, b.skuId`;
+
+  // 该查询 union 了 4 个销量来源（含 qmcust 全渠道扫描），全仓窗口可能超过默认 60s；
+  // mssql 12.x 请求级 timeout 不生效，必须走池级放宽的慢查询入口。
+  const runQuery = typeof cloudDb.querySlow === 'function' ? cloudDb.querySlow : cloudDb.query;
+  const rows = await runQuery(
+    sqlText,
+    {
+      ...binIn.params,
+      ...shipIn.params,
+      shipFrom,
+      shipTo,
+      days,
+    },
+    { requestTimeout: 120000 }
+  );
+
+  return rows.map((r) => ({
+    wmsCoId: String(r.wmsCoId),
+    binName: r.binName || '',
+    binType: r.binType || '',
+    skuId: r.skuId == null ? '' : String(r.skuId).trim(),
+    stockQty: Number(r.stockQty) || 0,
+    skuCount: Number(r.skuCount) || 0,
+    salesQty: Number(r.salesQty) || 0,
+    allocatedSalesQty: Number(r.allocatedSalesQty) || 0,
+    dailySales: Number(r.dailySales) || 0,
+    gradeKey: r.gradeKey || 'zero',
+  }));
+}
+
+module.exports = {
+  buildGradeCase,
+  buildInClause,
+  fetchPickingBinSkuRows,
+};

backend/src/services/redisConfig.js

@@ -54,8 +54,11 @@ const STORED_PROFILE_LABELS = {
 const ENV_MAPPING = {
   host: 'REDIS_HOST',
   port: 'REDIS_PORT',
+  username: 'REDIS_USERNAME',
   password: 'REDIS_PASSWORD',
   db: 'REDIS_DB',
+  tls: 'REDIS_TLS',
+  tlsServerName: 'REDIS_TLS_SERVER_NAME',
 };
 
 const DEFAULT_CHANGZHOU_SERVER_IP = '192.168.150.234';
@@ -86,6 +89,12 @@ function normalizeDb(value) {
   return Number.isFinite(db) && db >= 0 ? db : DEFAULT_REDIS_CONFIG.db;
 }
 
+function normalizeBoolean(value) {
+  return [true, 1, '1', 'true', 'yes', 'on'].includes(
+    typeof value === 'string' ? value.toLowerCase() : value
+  );
+}
+
 function normalizeRuntimeProfile(value) {
   const requestedProfile = String(value || '').trim();
   if (!requestedProfile) {
@@ -189,7 +198,10 @@ function mapConfig(config = {}, { includePassword = false, source = 'database' }
     profileName: config.profileName || config.profile_name || STORED_PROFILE_LABELS[profileKey] || profileKey,
     host,
     port: normalizePort(config.port),
+    username: String(config.username || '').trim(),
     db: normalizeDb(config.db),
+    tls: normalizeBoolean(config.tls),
+    tlsServerName: String(config.tlsServerName || config.tls_server_name || '').trim(),
     hasPassword: Boolean(password),
     enabled,
     source,
@@ -203,8 +215,11 @@ function getEnvRedisConfig(options = {}) {
     profileName: '.env Redis',
     host: process.env[ENV_MAPPING.host] || '',
     port: process.env[ENV_MAPPING.port],
+    username: process.env[ENV_MAPPING.username] || '',
     db: process.env[ENV_MAPPING.db],
     password: process.env[ENV_MAPPING.password] || '',
+    tls: process.env[ENV_MAPPING.tls],
+    tlsServerName: process.env[ENV_MAPPING.tlsServerName] || '',
     enabled: Boolean(String(process.env[ENV_MAPPING.host] || '').trim()),
   }, {
     includePassword: Boolean(options.includePassword),
@@ -354,12 +369,15 @@ async function probeRedisConnection(config) {
   const client = new Redis({
     host: config.host,
     port: normalizePort(config.port),
+    username: config.username || undefined,
     password: config.password || undefined,
     db: normalizeDb(config.db),
+    tls: config.tls ? { servername: config.tlsServerName || config.host } : undefined,
     lazyConnect: true,
     connectTimeout: REDIS_PROFILE_CONNECT_TIMEOUT_MS,
     maxRetriesPerRequest: 1,
     enableOfflineQueue: false,
+    enableReadyCheck: false,
     retryStrategy: () => null,
   });
 
@@ -390,8 +408,11 @@ async function getRuntimeRedisConfig() {
       return {
         host: candidate.host,
         port: candidate.port,
+        username: candidate.username || undefined,
         password: candidate.password || undefined,
         db: candidate.db,
+        tls: candidate.tls,
+        tlsServerName: candidate.tlsServerName,
         source: candidate.source,
       };
     }
@@ -400,8 +421,11 @@ async function getRuntimeRedisConfig() {
       return {
         host: candidate.host,
         port: candidate.port,
+        username: candidate.username || undefined,
         password: candidate.password || undefined,
         db: candidate.db,
+        tls: candidate.tls,
+        tlsServerName: candidate.tlsServerName,
         source: candidate.profileKey || candidate.source,
       };
     }
@@ -411,8 +435,11 @@ async function getRuntimeRedisConfig() {
     return {
       host: envCandidate.host,
       port: envCandidate.port,
+      username: envCandidate.username || undefined,
       password: envCandidate.password || undefined,
       db: envCandidate.db,
+      tls: envCandidate.tls,
+      tlsServerName: envCandidate.tlsServerName,
       source: envCandidate.source,
     };
   }

backend/src/services/remoteEnrollmentService.js

@@ -0,0 +1,67 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const REPOSITORY_ROOT = path.resolve(__dirname, '../../..');
+const SETUP_MODULE_PATH = path.join(REPOSITORY_ROOT, 'scripts', 'setup-remote.mjs');
+const RESTART_MARKER_PATH = path.join(REPOSITORY_ROOT, '.remote-access', 'restart-requested.json');
+const DEFAULT_BOOTSTRAP_ENDPOINT = 'https://ck.yydd.ai:8443/v1/enroll';
+
+function normalizeEndpoint(value) {
+  const endpoint = new URL(String(value || DEFAULT_BOOTSTRAP_ENDPOINT).trim());
+  if (endpoint.protocol !== 'https:' || endpoint.username || endpoint.password) {
+    throw new Error('配置请求地址必须是没有内嵌账号密码的 HTTPS 地址');
+  }
+  return endpoint.toString();
+}
+
+async function enrollRemoteInstallation(input = {}) {
+  const endpoint = normalizeEndpoint(input.endpoint);
+  const apiKey = String(input.apiKey || '').trim();
+  const label = String(input.label || os.hostname()).trim();
+  if (!apiKey) throw new Error('请输入部署 Key');
+  if (!label || label.length > 80) throw new Error('设备名称必须为 1 到 80 个字符');
+
+  const setupModule = await import(pathToFileURL(SETUP_MODULE_PATH).href);
+  const { enrollment, connection } = await setupModule.configureRemoteAccess({
+    endpoint,
+    key: apiKey,
+    label,
+    replace: false,
+  });
+
+  return {
+    installationId: enrollment.installation_id,
+    certificateValidUntil: enrollment.ssh.valid_until,
+    systemDatabase: {
+      host: '127.0.0.1',
+      port: connection.localDatabasePort,
+      database: enrollment.database.name,
+    },
+    redis: {
+      host: enrollment.redis.host,
+      port: Number(enrollment.redis.port),
+      tls: true,
+    },
+    adminUsername: enrollment.application_admin.username,
+    adminPassword: enrollment.application_admin.password,
+  };
+}
+
+function scheduleRemoteRestart() {
+  fs.mkdirSync(path.dirname(RESTART_MARKER_PATH), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(
+    RESTART_MARKER_PATH,
+    `${JSON.stringify({ requestedAt: new Date().toISOString() })}\n`,
+    { mode: 0o600 }
+  );
+  fs.chmodSync(RESTART_MARKER_PATH, 0o600);
+}
+
+module.exports = {
+  DEFAULT_BOOTSTRAP_ENDPOINT,
+  enrollRemoteInstallation,
+  normalizeEndpoint,
+  scheduleRemoteRestart,
+};

backend/src/services/retiredFeatures.js

@@ -1,14 +1,31 @@
-const RETIRED_PAGE_KEYS = ['planning_upload', 'market_insight', 'agent', 'ai_skill_tags'];
-const RETIRED_ENTRY_KEYS = new Set(['market-insight', 'agent', 'ai-skill-tags', 'platform-switch']);
+const RETIRED_PAGE_KEYS = [
+  'planning_upload', 'market_insight', 'agent', 'ai_skill_tags',
+  'store_checkup', 'review_analysis', 'customer_service_checkup',
+  'pricing_calculator', 'desktop_client_download', 'ai_buyer_show', 'ai_seeding_video',
+];
+const RETIRED_ENTRY_KEYS = new Set([
+  'market-insight', 'agent', 'ai-skill-tags', 'platform-switch',
+  'store-management', 'store-checkup', 'review-analysis', 'customer-service-checkup',
+  'operation-tools', 'pricing-calculator', 'desktop-client-download', 'ai-buyer-show', 'ai-seeding-video',
+  'desktop-client-releases',
+]);
 const RETIRED_CONFIG_KEYS = [
   'openclaw_chat_config', 'openclaw_chat_skill_tags',
   'selection_similar_products_config', 'alibaba_1688_image_search_config',
+  'cs_quality_ai_config', 'desktop_client_releases',
+  'ai_buyer_show_ark_api_key', 'ai_buyer_show_ark_base_url',
+  'ai_buyer_show_vision_model', 'ai_buyer_show_review_model',
 ];
+const RETIRED_DATABASE_CONFIG_NAMES = ['ai_buyer_show_database'];
 
 function isRetiredSystemConfigKey(key) {
   return RETIRED_CONFIG_KEYS.includes(String(key || '').trim());
 }
 
+function isRetiredDatabaseConfigName(name) {
+  return RETIRED_DATABASE_CONFIG_NAMES.includes(String(name || '').trim());
+}
+
 function pruneRetiredSidebarConfig(value) {
   try {
     const config = typeof value === 'string' ? JSON.parse(value) : value;
@@ -28,6 +45,9 @@ async function cleanupRetiredFeatureSettings(db) {
     await db.query(`DELETE FROM ${table} WHERE page_key IN (${RETIRED_PAGE_KEYS.map(() => '?').join(',')})`, RETIRED_PAGE_KEYS);
   }
   await db.query(`DELETE FROM system_config WHERE config_key IN (${RETIRED_CONFIG_KEYS.map(() => '?').join(',')})`, RETIRED_CONFIG_KEYS);
+  await db.query(`DELETE FROM database_configs WHERE name IN (${RETIRED_DATABASE_CONFIG_NAMES.map(() => '?').join(',')})`, RETIRED_DATABASE_CONFIG_NAMES);
+  await db.query('DROP TABLE IF EXISTS pricing_calculator_history');
+  await db.query('DROP TABLE IF EXISTS pricing_calculator_user_prefs');
   const rows = await db.query("SELECT config_value FROM system_config WHERE config_key = ?", ['sidebar_navigation']);
   if (rows.length) {
     const current = rows[0].config_value;
@@ -36,4 +56,12 @@ async function cleanupRetiredFeatureSettings(db) {
   }
 }
 
-module.exports = { RETIRED_PAGE_KEYS, RETIRED_CONFIG_KEYS, isRetiredSystemConfigKey, pruneRetiredSidebarConfig, cleanupRetiredFeatureSettings };
+module.exports = {
+  RETIRED_PAGE_KEYS,
+  RETIRED_CONFIG_KEYS,
+  RETIRED_DATABASE_CONFIG_NAMES,
+  isRetiredSystemConfigKey,
+  isRetiredDatabaseConfigName,
+  pruneRetiredSidebarConfig,
+  cleanupRetiredFeatureSettings,
+};

backend/src/services/returnInventoryWarningService.js

@@ -0,0 +1,412 @@
+'use strict';
+
+const cloudDb = require('../config/cloudDatabase');
+
+/**
+ * 退货库存预警服务
+ * --------------------------------------------------------------------------
+ * 数据来源：业务数据库（MSSQL 报表副本 / JSReportReplica, schema rpt）。
+ * 固定过滤仓库：「销售退仓 横林二仓」对应业务库仓库名「简尚-横林二仓销退仓」。
+ *
+ * 日期口径（重要）：
+ *   列表按「退货入库日期」筛选，取 jst_returnAndRefundItem.receive_date（明细级收货日期），
+ *   而不是 jst_returnAndRefundInfo.as_date（售后申请日期）。原因：
+ *     - as_date 是售后单申请日，很多退货是几天后才实际收货入库的；
+ *     - 只按 as_date 过滤，会漏掉"前几天申请、今天才收货入库"的明细。
+ *   实测（2026-09-12）：按 as_date 过滤只有 366 条明细；按 receive_date 过滤有 745 条明细，
+ *   更接近聚水潭「销售退仓」当天口径。
+ *
+ * 数据来源口径（重要，2026-09-15 修正）：
+ *   副本里有两条互不重叠的退货入库同步管线，必须取并集才对得上聚水潭「销售退仓」：
+ *     ① ERP 售后单   jst_returnAndRefundInfo × jst_returnAndRefundItem
+ *     ② 奇门退款单   jst_qmcust_refundlist  × jst_qmcust_refundlist_item
+ *   去重键 = (退货单号 as_id, 商品编码 sku_id)，同键优先取 ERP 行。
+ *
+ * 字段映射（业务库 -> 逻辑字段，与前端页面表头一一对应）：
+ *   退货入库时间 returnInboundTime <- jst_returnAndRefundItem.receive_date（回退 info.as_date）
+ *   快递单号   expressNo          <- jst_returnAndRefundInfo.l_id
+ *   供应商     supplier           <- jst_sku.supplier_name
+ *   预警       warning            <- ope_clear_task.alert（按 sku 取最新月）
+ *   商品编码   productCode        <- jst_returnAndRefundItem.sku_id
+ *   入库件数   inboundQty         <- jst_returnAndRefundItem.r_qty（实收件数；
+ *                                    当 r_qty 为 0 时回退到 qty）
+ *   在库天数   stockDays          <- DATEDIFF(DAY, 入库日期, 出库日期)；出库未发生 → null
+ *   退货总库存 returnTotalStock   <- jst_inventoryInfo.return_qty（横林二仓 wms_co_id=15033302）
+ *   出库日期   outboundDate       <- 业务库暂无 采购退货 表 → null
+ *   出库件数   outboundQty        <- 业务库暂无对应来源 → null
+ *
+ * 说明：dbo.* 引用会被 cloudDatabase.rewriteReportReplicaSql 改写为 rpt.*。
+ * 仓库过滤条件以字面量 N'...' 写入 SQL，规避中文参数化时的 Unicode 问题。
+ * 若业务库不可用或查询失败，接口兜底返回演示数据并附带 notice。
+ */
+
+// 前端展示名（入参）与业务库真实仓库名映射
+const WAREHOUSE_DISPLAY = '销售退仓 横林二仓';
+const WAREHOUSE_DB = '简尚-横林二仓销退仓';
+// 横林二仓在 jst_inventoryInfo 中的仓编码（wh_id=2）
+const HENLIN2_WMS_CO_ID = 15033302;
+// 单页最大条数（一天 1000+ 条，留足余量）
+const MAX_PAGE_SIZE = 3000;
+
+// 已知的副本缺口（前端 / 业务侧可见）
+const KNOWN_GAPS = [
+  '退货总库存：期望"箱及仓位库存-横林二仓-客退临时上架仓"（仓位级），但 rpt 副本仅有 jst_inventoryInfo（仓+SKU 级），无仓位维度。当前按 wms_co_id=15033302 取 return_qty 作为仓级近似值。',
+  '出库日期/出库件数：期望"聚水潭采购退货-横林二仓"，但 rpt 副本中没有采购退货表（jst_purchase/jst_purchaseItem 是采购入库单据）。当前为 null。',
+  '条数口径（2026-09-15 已修正）：本表取「ERP 售后单 + 奇门退款单」两条同步管线的并集，去重键为（退货单号 + 商品编码）。实测 09-14 并集 1179 条 vs 聚水潭「销售退仓」1194 条（吻合度 98.7%），较旧的单表口径（797 条 / 66.8%）大幅修正。剩余 1~2% 差额来自副本未覆盖的 WMS 退仓单据（退仓单号 / 上架状态 / 箱号维度在 rpt 副本中不存在）。',
+];
+
+function resolveWarehouseDbName(incoming) {
+  const v = String(incoming || '').trim();
+  if (!v || v === WAREHOUSE_DISPLAY) return WAREHOUSE_DB;
+  return v; // 允许直接传入真实仓库名
+}
+
+// 取"今天"（东八区）的 YYYY-MM-DD
+function todayInShanghai() {
+  const now = new Date();
+  const utcMs = now.getTime() + now.getTimezoneOffset() * 60000;
+  const shMs = utcMs + 8 * 3600000;
+  return new Date(shMs).toISOString().slice(0, 10);
+}
+
+function normalizeDateInput(value) {
+  const v = String(value || '').trim();
+  if (!v) return '';
+  // 接受 YYYY-MM-DD 或 YYYY/MM/DD
+  const m = v.match(/^(\d{4})[-/](\d{1,2})[-/](\d{1,2})/);
+  if (!m) return '';
+  const mm = String(m[2]).padStart(2, '0');
+  const dd = String(m[3]).padStart(2, '0');
+  return `${m[1]}-${mm}-${dd}`;
+}
+
+// 演示数据（仅当业务库查询失败时兜底，便于核对页面布局与字段）
+const DEMO_ROWS = [
+  { returnInboundTime: '2026-09-12 15:38:03', expressNo: '76024510836500010001', supplier: '越子涵', warning: '正常', productCode: 'SZ001541N961V01', inboundQty: 1, stockDays: null, returnTotalStock: 0, outboundDate: null, outboundQty: null },
+  { returnInboundTime: '2026-09-12 15:37:49', expressNo: '730006113799', supplier: '艾米莉', warning: '正常', productCode: 'SJ004831N1172V01', inboundQty: 1, stockDays: null, returnTotalStock: 0, outboundDate: null, outboundQty: null },
+  { returnInboundTime: '2026-09-11 10:20:00', expressNo: 'SF2025514008294', supplier: '常州苗苗', warning: '黄色预警', productCode: 'SJZ000316N1253V01', inboundQty: 12, stockDays: null, returnTotalStock: 86, outboundDate: null, outboundQty: null },
+  { returnInboundTime: '2026-09-10 09:12:00', expressNo: 'SF1234567890123', supplier: '横林家居厂', warning: '红色预警', productCode: 'HL20240001', inboundQty: 120, stockDays: null, returnTotalStock: 320, outboundDate: null, outboundQty: null },
+];
+
+// ---------------------------------------------------------------------------
+// 数据来源（2026-09-15 修正）：两条同步管线取并集
+// ---------------------------------------------------------------------------
+// 副本里「退货入库」其实有两条互相独立的同步管线，且数据几乎不重叠：
+//   ① ERP 售后单：dbo.jst_returnAndRefundInfo × dbo.jst_returnAndRefundItem（状态以 WaitConfirm 为主）
+//   ② 奇门退款单：dbo.jst_qmcust_refundlist  × dbo.jst_qmcust_refundlist_item（状态以 Confirmed 为主）
+// 实测 2026-09-14：① 797 条、② 497 条，仅 115 条重叠（as_id + SKU 完全一致），并集 1179 条；
+// 聚水潭「销售退仓」界面当天 1194 条 → 吻合度 98.7%（只用 ① 仅 66.8%）。
+// 因此统一取并集，去重键 = (退货单号, 商品编码)，同键优先取 ERP 售后单（字段更全）。
+// ---------------------------------------------------------------------------
+
+function buildSourceCte(date) {
+  const mainDateClause = date ? `AND CAST(it.receive_date AS DATE) = @date` : '';
+  const qmDateClause = date ? `AND CAST(qit.receive_date AS DATE) = @date` : '';
+  return `
+    WITH src AS (
+      SELECT
+        CONVERT(NVARCHAR(50), i.as_id) AS as_id,
+        LTRIM(RTRIM(CONVERT(NVARCHAR(120), it.sku_id))) AS product_code,
+        ISNULL(NULLIF(it.r_qty, 0), it.qty) AS inbound_qty,
+        COALESCE(it.receive_date, i.as_date) AS inbound_time,
+        i.l_id AS express_no,
+        1 AS src_rank,
+        N'ERP售后单' AS src_label
+      FROM dbo.jst_returnAndRefundInfo i
+      JOIN dbo.jst_returnAndRefundItem it ON it.as_id = i.as_id
+      WHERE i.warehouse = N'${WAREHOUSE_DB}'
+        AND it.sku_id IS NOT NULL
+        AND LTRIM(RTRIM(CONVERT(NVARCHAR(120), it.sku_id))) <> N''
+        ${mainDateClause}
+      UNION ALL
+      SELECT
+        CONVERT(NVARCHAR(50), q.as_id),
+        LTRIM(RTRIM(CONVERT(NVARCHAR(120), qit.sku_id))),
+        ISNULL(NULLIF(qit.r_qty, 0), qit.qty),
+        COALESCE(qit.receive_date, q.as_date),
+        q.l_id,
+        2,
+        N'奇门退款单'
+      FROM dbo.jst_qmcust_refundlist q
+      JOIN dbo.jst_qmcust_refundlist_item qit
+        ON CONVERT(NVARCHAR(50), q.as_id) = CONVERT(NVARCHAR(50), qit.as_id)
+      WHERE q.warehouse = N'${WAREHOUSE_DB}'
+        AND qit.sku_id IS NOT NULL
+        AND LTRIM(RTRIM(CONVERT(NVARCHAR(120), qit.sku_id))) <> N''
+        ${qmDateClause}
+    ),
+    dedup AS (
+      SELECT as_id, product_code, inbound_qty, inbound_time, express_no, src_label
+      FROM (
+        SELECT src.*,
+               ROW_NUMBER() OVER (
+                 PARTITION BY src.as_id, UPPER(src.product_code)
+                 ORDER BY src.src_rank
+               ) AS rn
+        FROM src
+      ) ranked
+      WHERE ranked.rn = 1
+    )
+  `;
+}
+
+const FROM_JOINS = `
+    FROM dedup u
+    LEFT JOIN dbo.jst_sku sk ON sk.sku_id = u.product_code
+`;
+
+const SELECT_COLUMNS = `
+      CONVERT(NVARCHAR(19), u.inbound_time, 120) AS [returnInboundTime],
+      u.express_no AS [expressNo],
+      sk.supplier_name AS [supplier],
+      NULLIF(LTRIM(RTRIM(COALESCE(ct.alert, N''))), N'') AS [warning],
+      u.product_code AS [productCode],
+      u.inbound_qty AS [inboundQty],
+      ISNULL(inv.return_qty, 0) AS [returnTotalStock],
+      NULL AS [outboundDate],
+      NULL AS [outboundQty],
+      u.src_label AS [dataSource]
+`;
+
+const OUTER_APPLIES = `
+    OUTER APPLY (
+      SELECT TOP 1 alert
+      FROM dbo.ope_clear_task ct
+      WHERE ct.clear_skuoid = u.product_code
+      ORDER BY ct.stat_month DESC
+    ) ct
+    OUTER APPLY (
+      SELECT TOP 1 return_qty
+      FROM dbo.jst_inventoryInfo inv
+      WHERE inv.sku_id = u.product_code AND inv.wms_co_id = ${HENLIN2_WMS_CO_ID}
+    ) inv
+`;
+
+// 关键字过滤：与页面上的「商品编码 / 快递单号」搜索保持一致
+const buildKeywordClause = (keyword) => (
+  keyword ? `AND (u.product_code LIKE @keyword OR u.express_no LIKE @keyword)` : ''
+);
+
+function buildListSql({ offset, limit, date, keyword }) {
+  return `
+    ${buildSourceCte(date)}
+    SELECT ${SELECT_COLUMNS}
+    ${FROM_JOINS}
+    ${OUTER_APPLIES}
+    WHERE 1 = 1
+      ${buildKeywordClause(keyword)}
+    ORDER BY u.inbound_time DESC, u.as_id DESC
+    OFFSET @offset ROWS FETCH NEXT @limit ROWS ONLY
+  `;
+}
+
+function buildCountSql({ date, keyword }) {
+  return `
+    ${buildSourceCte(date)}
+    SELECT COUNT(*) AS [total]
+    FROM dedup u
+    WHERE 1 = 1
+      ${buildKeywordClause(keyword)}
+  `;
+}
+
+// 该仓「最新一条明细收货日」——用于前端在"今天还没同步到"时回退到最新有数据的日期
+function buildLatestDateSql() {
+  return `
+    ${buildSourceCte('')}
+    SELECT CONVERT(varchar(10), MAX(u.inbound_time), 120) AS [latestDate]
+    FROM dedup u
+  `;
+}
+
+async function fetchLatestDate() {
+  try {
+    const rows = await cloudDb.query(buildLatestDateSql(), {}, { requestTimeout: 180000 });
+    return rows?.[0]?.latestDate || null;
+  } catch (error) {
+    return null; // 单独失败不影响主列表
+  }
+}
+
+function normalizeRow(row = {}) {
+  return {
+    returnInboundTime: row.returnInboundTime ?? null,
+    expressNo: row.expressNo ?? null,
+    supplier: row.supplier ?? null,
+    warning: row.warning ?? null,
+    productCode: row.productCode ?? null,
+    inboundQty: row.inboundQty === null || row.inboundQty === undefined ? 0 : Number(row.inboundQty),
+    // 在库天数：当前副本无 采购退货 来源，固定为 null（有出库日期后再启用 DATEDIFF）
+    stockDays: null,
+    returnTotalStock: (row.returnTotalStock === null || row.returnTotalStock === undefined) ? null : Number(row.returnTotalStock),
+    outboundDate: null,
+    outboundQty: null,
+    // 并集口径下的数据来源：ERP售后单 / 奇门退款单（便于与聚水潭逐条核对）
+    dataSource: row.dataSource || null,
+  };
+}
+
+// 统一的查询口径解析：仓库展示名、业务库仓库名、日期（默认今天，'all'/'' = 不限）、关键字
+function resolveListQuery(params = {}) {
+  const displayWarehouse = params.warehouse || WAREHOUSE_DISPLAY;
+  const warehouse = resolveWarehouseDbName(displayWarehouse);
+
+  // 日期口径：默认今天（东八区）；传 date='' 或 'all' 表示不限日期
+  const rawDate = params.date === undefined ? todayInShanghai() : String(params.date || '').trim();
+  const date = (rawDate === '' || rawDate.toLowerCase() === 'all') ? '' : normalizeDateInput(rawDate);
+
+  const keyword = String(params.keyword || '').trim();
+  return { displayWarehouse, warehouse, date, keyword };
+}
+
+function buildSqlParams({ date, keyword }, extra = {}) {
+  const sqlParams = { ...extra };
+  if (date) sqlParams.date = date;
+  if (keyword) sqlParams.keyword = `%${keyword}%`;
+  return sqlParams;
+}
+
+async function getReturnInventoryWarningList(params = {}) {
+  const { displayWarehouse, date, keyword } = resolveListQuery(params);
+  const page = Math.max(1, parseInt(params.page, 10) || 1);
+  const pageSize = Math.min(MAX_PAGE_SIZE, Math.max(1, parseInt(params.pageSize, 10) || 500));
+  const offset = (page - 1) * pageSize;
+  const dateBasis = 'receive_date';
+
+  try {
+    const [rows, countRows, latestDate] = await Promise.all([
+      cloudDb.query(
+        buildListSql({ offset, limit: pageSize, date, keyword }),
+        buildSqlParams({ date, keyword }, { offset, limit: pageSize }),
+        { requestTimeout: 180000 }
+      ),
+      cloudDb.query(buildCountSql({ date, keyword }), buildSqlParams({ date, keyword }), { requestTimeout: 180000 }),
+      fetchLatestDate(),
+    ]);
+
+    const normalized = (rows || []).map(normalizeRow).filter((row) => row.productCode);
+    const total = Number(countRows?.[0]?.total ?? normalized.length);
+
+    return {
+      rows: normalized,
+      total,
+      page,
+      pageSize,
+      warehouse: displayWarehouse,
+      dateBasis,
+      date: date || null,
+      latestDate,
+      dateIsEmpty: total === 0,
+      isDemo: false,
+      gaps: KNOWN_GAPS,
+    };
+  } catch (error) {
+    const message = error?.message || '未知错误';
+    return {
+      rows: DEMO_ROWS.map((row) => ({ ...row })),
+      total: DEMO_ROWS.length,
+      page,
+      pageSize,
+      warehouse: displayWarehouse,
+      dateBasis,
+      date: date || null,
+      latestDate: null,
+      dateIsEmpty: true,
+      isDemo: true,
+      notice: `业务库查询失败，当前展示演示数据。原始错误：${message}`,
+      gaps: KNOWN_GAPS,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 导出
+// ---------------------------------------------------------------------------
+
+// 导出时按批拉取，避免一次 OFFSET/FETCH 过大导致副本查询超时
+const EXPORT_PAGE_SIZE = 2000;
+const EXPORT_MAX_ROWS = 50000;
+
+// 与页面表头一一对应
+const EXPORT_COLUMNS = [
+  { title: '退货入库时间', key: 'returnInboundTime' },
+  { title: '快递单号', key: 'expressNo' },
+  { title: '供应商', key: 'supplier' },
+  { title: '预警', key: 'warning' },
+  { title: '商品编码', key: 'productCode' },
+  { title: '入库件数', key: 'inboundQty' },
+  { title: '在库天数', key: 'stockDays' },
+  { title: '退货总库存', key: 'returnTotalStock' },
+  { title: '出库日期', key: 'outboundDate' },
+  { title: '出库件数', key: 'outboundQty' },
+  { title: '数据来源', key: 'dataSource' },
+];
+
+/** 拉取当前筛选条件下的全部明细（分页拉取，最多 EXPORT_MAX_ROWS 行） */
+async function getReturnInventoryWarningExportRows(params = {}) {
+  const { displayWarehouse, date, keyword } = resolveListQuery(params);
+  const maxRows = Math.max(1, parseInt(params.limit, 10) || EXPORT_MAX_ROWS);
+
+  const countPromise = cloudDb
+    .query(buildCountSql({ date, keyword }), buildSqlParams({ date, keyword }), { requestTimeout: 180000 })
+    .catch(() => null);
+
+  const rows = [];
+  let page = 1;
+
+  while (rows.length < maxRows) {
+    const offset = (page - 1) * EXPORT_PAGE_SIZE;
+    const limit = Math.min(EXPORT_PAGE_SIZE, maxRows - rows.length);
+
+    const batch = await cloudDb.query(
+      buildListSql({ offset, limit, date, keyword }),
+      buildSqlParams({ date, keyword }, { offset, limit }),
+      { requestTimeout: 300000 }
+    );
+
+    const normalized = (batch || []).map(normalizeRow).filter((row) => row.productCode);
+    rows.push(...normalized);
+
+    if (!batch || batch.length < limit) break;
+    page += 1;
+  }
+
+  const countRows = await countPromise;
+  const total = Number(countRows?.[0]?.total ?? rows.length);
+
+  return {
+    rows,
+    total,
+    truncated: total > rows.length,
+    warehouse: displayWarehouse,
+    date: date || null,
+    keyword,
+  };
+}
+
+/** 组装导出数据集（供 api 层渲染成 xlsx / csv） */
+async function buildReturnInventoryWarningExport(params = {}) {
+  const { rows, total, warehouse, date, keyword, truncated } = await getReturnInventoryWarningExportRows(params);
+
+  return {
+    fileName: `横林二仓当日退货入库明细_${date || '全部日期'}${keyword ? `_${keyword}` : ''}`,
+    sheets: [{
+      name: '退货入库明细',
+      header: EXPORT_COLUMNS.map((column) => column.title),
+      rows: rows.map((row) => EXPORT_COLUMNS.map((column) => row[column.key])),
+    }],
+    totalRows: rows.length,
+    matchedTotal: total,
+    truncated,
+    warehouse,
+    date,
+  };
+}
+
+module.exports = {
+  getReturnInventoryWarningList,
+  getReturnInventoryWarningExportRows,
+  buildReturnInventoryWarningExport,
+  DEFAULT_WAREHOUSE: WAREHOUSE_DISPLAY,
+  todayInShanghai,
+};

backend/src/services/returnMonitorSchema.js

@@ -0,0 +1,128 @@
+'use strict';
+
+/**
+ * 横林二仓客退「退货入库核销 + 每日库存监控」本地表结构
+ * --------------------------------------------------------------------------
+ * 为什么需要本地表：
+ *   业务库（JSReportReplica）只有退货单据的"事实"，没有"核销状态"。
+ *   而本需求的「状态（在库/已出库/已报废）」「出库日期」「差异人工确认结果」
+ *   是每天比对后累积出来的状态，必须落库持久化，否则每天重算会丢历史。
+ *
+ * 存放位置：系统库（LOCAL_DB_*，默认 shujuku2_system）
+ */
+
+const database = require('../config/database');
+
+const SCHEMA_SQL = [
+  // 1. 核心：退货入库主数据（一单一行 = 一个退货单的一个商品行）
+  `CREATE TABLE IF NOT EXISTS return_monitor_inbound (
+    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键',
+    warehouse_key VARCHAR(40) NOT NULL DEFAULT 'henlin2' COMMENT '仓库标识',
+    return_no VARCHAR(120) NOT NULL COMMENT '退货单号（聚水潭售后单号 as_id）',
+    product_code VARCHAR(120) NOT NULL COMMENT '商品编码（sku_id）',
+    sku_name VARCHAR(255) NULL COMMENT '商品名称',
+    supplier VARCHAR(255) NULL COMMENT '供应商',
+    qty INT NOT NULL DEFAULT 0 COMMENT '数量（入库件数）',
+    inbound_date DATE NOT NULL COMMENT '入库日期（取单据/收货日期）',
+    express_no VARCHAR(120) NULL COMMENT '快递单号',
+    order_no VARCHAR(120) NULL COMMENT '原订单号',
+    defective_qty INT NULL COMMENT '来源单据的不良品数量（如有）',
+    status VARCHAR(16) NOT NULL DEFAULT '在库' COMMENT '状态：在库/已出库/已报废',
+    outbound_date DATE NULL COMMENT '出库日期',
+    writeoff_mode VARCHAR(20) NOT NULL DEFAULT 'none' COMMENT '核销方式：none/auto_clear/fifo/manual/mark',
+    remark VARCHAR(500) NULL COMMENT '备注',
+    first_seen_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '首次同步时间',
+    last_synced_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '最近同步时间',
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_rm_inbound_line (warehouse_key, return_no, product_code, inbound_date),
+    KEY idx_rm_inbound_status (warehouse_key, status, inbound_date),
+    KEY idx_rm_inbound_code (warehouse_key, product_code),
+    KEY idx_rm_inbound_date (warehouse_key, inbound_date)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='横林二仓客退-退货入库主数据（核销状态）'`,
+
+  // 2. 现有库存每日快照（按商品编码）
+  `CREATE TABLE IF NOT EXISTS return_monitor_stock (
+    warehouse_key VARCHAR(40) NOT NULL DEFAULT 'henlin2' COMMENT '仓库标识',
+    stat_date DATE NOT NULL COMMENT '快照日期',
+    product_code VARCHAR(120) NOT NULL COMMENT '商品编码',
+    stock_qty INT NOT NULL DEFAULT 0 COMMENT '现有库存件数',
+    synced_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '同步时间',
+    PRIMARY KEY (warehouse_key, stat_date, product_code),
+    KEY idx_rm_stock_code (warehouse_key, product_code)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='横林二仓客退-现有库存每日快照'`,
+
+  // 3. 差异清单（部分出库，需人工确认）
+  `CREATE TABLE IF NOT EXISTS return_monitor_discrepancy (
+    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键',
+    warehouse_key VARCHAR(40) NOT NULL DEFAULT 'henlin2' COMMENT '仓库标识',
+    product_code VARCHAR(120) NOT NULL COMMENT '商品编码',
+    supplier VARCHAR(255) NULL COMMENT '供应商',
+    inbound_total INT NOT NULL DEFAULT 0 COMMENT '该编码在库入库总件数',
+    stock_qty INT NOT NULL DEFAULT 0 COMMENT '现有库存件数',
+    diff_qty INT NOT NULL DEFAULT 0 COMMENT '推定已出库件数 = 在库入库 - 现有库存',
+    fifo_plan_json MEDIUMTEXT NULL COMMENT 'FIFO 建议核销明细（JSON，仅前若干条用于展示）',
+    status VARCHAR(16) NOT NULL DEFAULT '待确认' COMMENT '状态：待确认/已确认/已忽略',
+    resolution VARCHAR(20) NULL COMMENT '处理方式：fifo/manual',
+    first_seen_date DATE NOT NULL COMMENT '首次进入差异清单日期',
+    last_seen_date DATE NOT NULL COMMENT '最近一次仍有差异的日期',
+    resolved_by VARCHAR(100) NULL COMMENT '处理人',
+    resolved_at DATETIME NULL COMMENT '处理时间',
+    remark VARCHAR(500) NULL COMMENT '备注',
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_rm_discrepancy_code (warehouse_key, product_code),
+    KEY idx_rm_discrepancy_status (warehouse_key, status, last_seen_date)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='横林二仓客退-部分出库差异清单'`,
+
+  // 4. 同步/比对日志
+  `CREATE TABLE IF NOT EXISTS return_monitor_job_log (
+    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键',
+    warehouse_key VARCHAR(40) NOT NULL DEFAULT 'henlin2' COMMENT '仓库标识',
+    biz_date DATE NOT NULL COMMENT '业务日期',
+    trigger_type VARCHAR(20) NOT NULL DEFAULT 'manual' COMMENT '触发方式：manual/cron/api',
+    inbound_rows INT NOT NULL DEFAULT 0 COMMENT '本次同步的入库明细行数',
+    stock_rows INT NOT NULL DEFAULT 0 COMMENT '本次同步的库存行数',
+    cleared_rows INT NOT NULL DEFAULT 0 COMMENT '整批核销（已出库）行数',
+    discrepancy_rows INT NOT NULL DEFAULT 0 COMMENT '差异编码数',
+    status VARCHAR(20) NOT NULL DEFAULT 'success' COMMENT '状态：success/failed',
+    error_message VARCHAR(1000) NULL COMMENT '错误信息',
+    elapsed_ms INT NOT NULL DEFAULT 0 COMMENT '耗时(ms)',
+    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    PRIMARY KEY (id),
+    KEY idx_rm_job_log_date (warehouse_key, biz_date, created_at)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='横林二仓客退-同步与比对日志'`,
+];
+
+// 兼容早期建表：把 TEXT 的 fifo_plan_json 放宽为 MEDIUMTEXT
+const COLUMN_MIGRATIONS = [
+  [
+    'return_monitor_discrepancy',
+    'fifo_plan_json',
+    "ALTER TABLE return_monitor_discrepancy MODIFY COLUMN fifo_plan_json MEDIUMTEXT NULL COMMENT 'FIFO 建议核销明细（JSON，仅前若干条用于展示）'",
+    'mediumtext',
+  ],
+];
+
+async function applyColumnMigrations() {
+  for (const [table, column, alterSql, expectedType] of COLUMN_MIGRATIONS) {
+    const rows = await database.local.query(
+      `SELECT DATA_TYPE AS d FROM information_schema.COLUMNS
+       WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ? LIMIT 1`,
+      [table, column]
+    );
+    const current = String(rows?.[0]?.d || '').toLowerCase();
+    if (current === expectedType) continue;
+    await database.local.query(alterSql);
+  }
+}
+
+async function ensureReturnMonitorSchema() {
+  for (const sql of SCHEMA_SQL) {
+    await database.local.query(sql);
+  }
+  await applyColumnMigrations();
+}
+
+module.exports = { ensureReturnMonitorSchema };

backend/src/services/returnStockWarehouseRegistry.js

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * 客退数据监控 —— 仓库注册表
+ * --------------------------------------------------------------------------
+ * 每个仓库一张「客退数据监控」看板，页面结构完全一致，差异只有三件事：
+ *   1. 库存取自哪个仓（jst_inventoryInfo.wms_co_id）；
+ *   2. 「客退临时上架仓」的库存在哪个自定义库存位上；
+ *   3. 退货单表（售后单 / 奇门退款单）里的销退仓名称（仅「最早入库时间」口径用）。
+ *
+ * 关于第 2 点——2026-09-17 用户给出了每个仓在聚水潭里的**准确仓位名**，并明确
+ * 「看板数据取自该仓位」。聚水潭给每个仓库单独开「自定义库存位」来做客退上架仓，
+ * **各仓用的位不一样**（2026-09-16 全库核对结论），所以两个字段要分开写：
+ *   · returnBinName = 用户口径的聚水潭仓位名，写进页面/导出的「数据来源」，便于核对；
+ *   · returnSlot    = 副本里真正取数的那一列，必须与上面的仓位名一一对应。
+ *
+ *   仓位名 → 库存位 对照（2026-09-27 复测，条件 ISNULL(col,0) > 0）：
+ *     箱及仓位库存 · 简尚-崔桥工厂仓   · 崔桥工厂客退临时上架仓 customize_qty_1  349 编码 /  507 件
+ *     箱及仓位库存 · 简尚-新苏北仓     · 新苏北客退上架仓   customize_qty_1     75 编码 /  362 件
+ *     箱及仓位库存 · 简尚-睢宁仓       · 睢宁客退上架仓     customize_qty_1     98 编码 /  243 件
+ *     箱及仓位库存 · 简尚-山东青岗集仓 · 青岗集客退上架仓   customize_qty_2    403 编码 /  912 件
+ *     箱及仓位库存 · 简尚-河南洛宁仓   · 河南洛宁客退上架仓 三位全为 0（无数据）
+ *
+ * ── 2026-09-27 重要更新：崔桥工厂仓的客退库存已经同步进副本了 ──
+ * 09-25 首次切换时该仓客退位只有 2 编码 / 2 件（当时判定「未同步进副本」），
+ * 09-26 起 IT 侧补上了同步：09-26 当天写入 317 编码 / 460 件，09-27 又补 31 编码 / 46 件，
+ * 09-27 10:11 实测 349 编码 / 507 件（= 副本 c1 合计，页面与副本完全对得上）。
+ * ⚠ 所以下面「崔桥必然近乎空白 / 只能靠导入」的旧结论已经作废，不要再拿它当依据。
+ *   现在这张看板能正常出数，**不需要**用导入功能兜底。
+ *
+ * ⚠ 崔桥工厂仓（15038426）是 2026-09-25 用户指定替换横林二仓的。复测结论：
+ * 副本里该仓客退位只有 2 编码 / 2 件，但退货单量很大（ERP 售后单 3,115 条 +
+ * 奇门退款单 1,812 条，warehouse='简尚-崔桥工厂仓销退仓'）——即「退货有，客退上架库存
+ * 没同步进副本」。全库 218 张表里没有任何「销退仓 / 客退仓 / 上架仓」命名的独立仓
+ * （jst_warehouseInfo 里 name 含「退」的为 0），销退仓只是退货单据里的 warehouse 文本值。
+ * 所以崔桥这张看板在当前副本下**必然近乎空白**，要出数只能：① 让 IT 把该仓客退上架仓
+ * 的库存同步进 jst_inventoryInfo 的自定义库存位；② 用页面「导入」上传聚水潭导出文件。
+ *
+ * ⚠ 副本里**没有任何仓位维度**（2026-09-17 复核：218 张表 / 5,496 个字段中，列名含
+ * bin / box / position / location / shelf / slot 的为 0 个；jst_sku.bin、jst_sku.other_bin、
+ * jst_returnAndRefundItem.box_id、jst_packInventoryInfo.bin 四个疑似字段 100% 为空）。
+ * 所以「按仓位名取数」在副本上做不到，只能用该仓位绑定的自定义库存位近似；
+ * 要逐箱还原（含真实的箱上架时间），必须导入聚水潭导出的文件。
+ *
+ * 河南洛宁仓（15539084）当天客退库存为 0：仓库存在、也有退货单，但三个自定义库存位
+ * 全为 0（只有 qty 总库存 83,273 件）。看板照样建，只是空表——页面会提示
+ * 「该仓当前没有客退在库数据」，等聚水潭侧同步进来后自动有内容。
+ */
+
+// 客退临时上架仓在 jst_inventoryInfo 里的候选列
+const RETURN_SLOT_COLUMNS = ['customize_qty_1', 'customize_qty_2', 'customize_qty_3'];
+
+const WAREHOUSE_LIST = [
+  {
+    key: 'cuiqiao',
+    // 页面标题 / 侧边栏名称（2026-09-25 用户指定：原「横林二仓客退数据监控」改为崔桥工厂仓）
+    title: '崔桥工厂仓客退数据监控',
+    shortName: '崔桥工厂仓',
+    // 仓库主表 jst_warehouseInfo.wms_co_id
+    wmsCoId: 15038426,
+    warehouseName: '简尚-崔桥工厂仓',
+    // 退货单（售后单 / 奇门退款单）里的销退仓名称，仅 firstInbound 口径用到
+    returnWarehouseDb: '简尚-崔桥工厂仓销退仓',
+    // 聚水潭「箱及仓位库存」里对应的仓位名（2026-09-25 用户指定，页面/导出直接显示它）
+    returnBinName: '崔桥工厂客退临时上架仓',
+    // 客退临时上架仓占用的自定义库存位
+    returnSlot: 'customize_qty_1',
+    // 2026-09-27 复测：客退位已同步进副本 —— 349 编码 / 507 件（c1 合计），
+    // 退货单口径：ERP 售后单 3,115 条 + 奇门退款单 1,812 条（warehouse='简尚-崔桥工厂仓销退仓'）。
+    hasReturnStock: true,
+  },
+  {
+    key: 'subei',
+    title: '苏北客退数据监控',
+    shortName: '苏北',
+    wmsCoId: 15038347,
+    warehouseName: '简尚-新苏北仓',
+    returnWarehouseDb: '简尚-新苏北仓销退仓',
+    // 2026-09-17 用户指定：苏北客退数据取自「新苏北客退上架仓」
+    returnBinName: '新苏北客退上架仓',
+    returnSlot: 'customize_qty_1',
+    hasReturnStock: true,
+  },
+  {
+    key: 'suining',
+    title: '睢宁客退数据监控',
+    shortName: '睢宁',
+    wmsCoId: 15032603,
+    warehouseName: '简尚-睢宁仓',
+    returnWarehouseDb: '简尚-睢宁仓销退仓',
+    // 2026-09-17 用户指定：睢宁客退数据取自「睢宁客退上架仓」
+    returnBinName: '睢宁客退上架仓',
+    returnSlot: 'customize_qty_1',
+    hasReturnStock: true,
+  },
+  {
+    key: 'shandong',
+    title: '山东客退数据监控',
+    shortName: '山东',
+    wmsCoId: 15137523,
+    warehouseName: '简尚-山东青岗集仓',
+    returnWarehouseDb: '简尚-山东青岗集仓销退仓',
+    // 2026-09-17 用户指定：山东客退数据取自「青岗集客退上架仓」
+    returnBinName: '青岗集客退上架仓',
+    // ★ 山东用的是第 2 个自定义库存位，与横林/苏北/睢宁不同
+    returnSlot: 'customize_qty_2',
+    hasReturnStock: true,
+  },
+  {
+    key: 'henan',
+    title: '河南客退数据监控',
+    shortName: '河南',
+    wmsCoId: 15539084,
+    warehouseName: '简尚-河南洛宁仓',
+    returnWarehouseDb: '简尚-河南洛宁仓销退仓',
+    // 2026-09-17 用户指定：河南客退数据取自「河南洛宁客退上架仓」
+    returnBinName: '河南洛宁客退上架仓',
+    // 该仓三个自定义库存位全为 0，河南洛宁客退上架仓在副本里取不到数据
+    returnSlot: 'customize_qty_1',
+    // 当前该仓客退库存为 0（仓库与退货单都在，只是当天没有客退在库）
+    hasReturnStock: false,
+  },
+];
+
+const DEFAULT_WAREHOUSE_KEY = 'cuiqiao';
+
+const WAREHOUSE_MAP = new Map(WAREHOUSE_LIST.map((item) => [item.key, item]));
+
+/** 归一化仓库标识：认 key（henlin2 / subei / ...），也容忍直接传 wms_co_id */
+function resolveWarehouseKey(value) {
+  const raw = String(value === null || value === undefined ? '' : value).trim();
+  if (!raw) return DEFAULT_WAREHOUSE_KEY;
+  const byKey = WAREHOUSE_MAP.get(raw.toLowerCase());
+  if (byKey) return byKey.key;
+  const byId = WAREHOUSE_LIST.find((item) => String(item.wmsCoId) === raw);
+  return byId ? byId.key : DEFAULT_WAREHOUSE_KEY;
+}
+
+/** 取仓库配置（永远返回一个有效配置，非法值回落到默认仓） */
+function resolveWarehouse(value) {
+  return WAREHOUSE_MAP.get(resolveWarehouseKey(value));
+}
+
+/**
+ * 页面/导出文案里的「数据来源」，例如
+ *   「箱及仓位库存 · 简尚-新苏北仓 · 新苏北客退上架仓」
+ * 仓位名逐仓不同（用户 2026-09-17 口径），必须读注册表，不能写死。
+ */
+function getWarehouseStockLabel(warehouse) {
+  return `箱及仓位库存 · ${warehouse.warehouseName} · ${warehouse.returnBinName}`;
+}
+
+module.exports = {
+  WAREHOUSE_LIST,
+  RETURN_SLOT_COLUMNS,
+  DEFAULT_WAREHOUSE_KEY,
+  resolveWarehouse,
+  resolveWarehouseKey,
+  getWarehouseStockLabel,
+};

backend/src/services/returnStockWarningImport.js

@@ -0,0 +1,275 @@
+'use strict';
+
+/**
+ * 聚水潭「箱及仓位库存 - {仓库} - 客退临时上架仓」导出文件导入
+ * --------------------------------------------------------------------------
+ * 用途：副本里没有箱/仓位维度，取不到聚水潭的「创建时间」，件数口径也可能不同。
+ * 导入后按商品编码覆盖「创建时间 / 件数 / 供应商」，页面与导出即与聚水潭一致。
+ *
+ * 按仓库隔离：每个看板（横林二仓 / 苏北 / 睢宁 / 山东 / 河南）各自上传自己仓库的导出文件，
+ * 落在 warehouse_key 下，互不覆盖。调用方通过 warehouseKey 传入。
+ *
+ * 文件要求：xlsx / xls / csv，表头需含「商品编码」（或 sku / 商品编号 / 货号）。
+ * 「创建时间」「数量/件数」「供应商」列名会自动模糊识别，不强制要求。
+ * 同一商品编码出现多行（多个箱/仓位）时：件数求和，创建时间取最早。
+ */
+
+const crypto = require('crypto');
+const XLSX = require('xlsx');
+const database = require('../config/database');
+
+// 与 returnStockWarehouseRegistry 的默认仓保持一致（不直接 require 以免循环依赖）
+const DEFAULT_WAREHOUSE_KEY = 'henlin2';
+
+const MAX_ROWS = 200000;
+
+const CODE_PATTERN = /(商品编码|商品编号|sku|货号|^编码$)/i;
+const TIME_PATTERN = /(创建时间|创建日期|上架时间|入库时间|入库日期|首次上架)/i;
+const QTY_PATTERN = /(件数|数量|库存数量|可用库存|库存)/i;
+const SUPPLIER_PATTERN = /(供应商|供货商)/i;
+
+const EXCLUDE_CODE_PATTERN = /(仓位|库位|货位|箱号|仓库)/i;
+
+function parseDateTimeValue(value) {
+  if (value === null || value === undefined || value === '') return null;
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || value <= 0) return null;
+    // Excel 序列号：按本地时钟解释，避免出现 +8 小时偏移
+    const days = Math.floor(value);
+    const frac = value - days;
+    const base = Date.UTC(1899, 11, 30);
+    const utc = new Date(base + days * 86400000 + Math.round(frac * 86400000));
+    return new Date(
+      utc.getUTCFullYear(), utc.getUTCMonth(), utc.getUTCDate(),
+      utc.getUTCHours(), utc.getUTCMinutes(), utc.getUTCSeconds()
+    );
+  }
+
+  const text = String(value).trim();
+  if (!text) return null;
+
+  const direct = new Date(text.replace(/\//g, '-').replace(/^(\d{4})-(\d{1,2})-(\d{1,2})/, (_, y, m, d) => `${y}-${m.padStart(2, '0')}-${d.padStart(2, '0')}`));
+  if (!Number.isNaN(direct.getTime())) return direct;
+
+  const nums = text.match(/\d+/g);
+  if (!nums || nums.length < 3) return null;
+  const [y, m, d, hh = '0', mm = '0', ss = '0'] = nums;
+  const built = new Date(Number(y), Number(m) - 1, Number(d), Number(hh), Number(mm), Number(ss));
+  return Number.isNaN(built.getTime()) ? null : built;
+}
+
+function parseNumberValue(value) {
+  if (value === null || value === undefined || value === '') return null;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  const text = String(value).replace(/[,，\s]/g, '');
+  if (!text) return null;
+  const parsed = Number(text);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function findHeaderRow(matrix) {
+  for (let i = 0; i < Math.min(matrix.length, 20); i += 1) {
+    const cells = (matrix[i] || []).map((cell) => String(cell === null || cell === undefined ? '' : cell).trim());
+    const hit = cells.some((cell) => CODE_PATTERN.test(cell) && !EXCLUDE_CODE_PATTERN.test(cell));
+    if (hit) return i;
+  }
+  return -1;
+}
+
+function resolveColumns(headerCells) {
+  const index = {
+    code: -1, time: -1, qty: -1, supplier: -1,
+  };
+  headerCells.forEach((raw, i) => {
+    const cell = String(raw === null || raw === undefined ? '' : raw).trim();
+    if (!cell) return;
+    if (index.code < 0 && CODE_PATTERN.test(cell) && !EXCLUDE_CODE_PATTERN.test(cell)) index.code = i;
+    if (index.time < 0 && TIME_PATTERN.test(cell)) index.time = i;
+    if (index.qty < 0 && QTY_PATTERN.test(cell)) index.qty = i;
+    if (index.supplier < 0 && SUPPLIER_PATTERN.test(cell)) index.supplier = i;
+  });
+  return index;
+}
+
+/**
+ * 解析文件为「按商品编码聚合」的记录
+ */
+function parseImportBuffer(buffer) {
+  const workbook = XLSX.read(buffer, { type: 'buffer', cellDates: true });
+  const sheetName = workbook.SheetNames[0];
+  if (!sheetName) {
+    throw new Error('文件里没有可读取的工作表');
+  }
+  const matrix = XLSX.utils.sheet_to_json(workbook.Sheets[sheetName], { header: 1, defval: null, blankrows: false });
+  if (!matrix.length) {
+    throw new Error('文件是空的');
+  }
+
+  const headerIndex = findHeaderRow(matrix);
+  if (headerIndex < 0) {
+    throw new Error('找不到表头，请确认文件里有一列叫「商品编码」（或 sku / 商品编号 / 货号）');
+  }
+
+  const columns = resolveColumns(matrix[headerIndex] || []);
+  if (columns.code < 0) {
+    throw new Error('找不到「商品编码」列');
+  }
+
+  const aggregated = new Map();
+  let skipped = 0;
+  let withCreatedAt = 0;
+  let withQty = 0;
+
+  for (let i = headerIndex + 1; i < matrix.length && aggregated.size < MAX_ROWS; i += 1) {
+    const row = matrix[i] || [];
+    const code = String(row[columns.code] === null || row[columns.code] === undefined
+      ? '' : row[columns.code]).trim();
+    if (!code) {
+      skipped += 1;
+      continue;
+    }
+
+    const time = columns.time >= 0 ? parseDateTimeValue(row[columns.time]) : null;
+    const qty = columns.qty >= 0 ? parseNumberValue(row[columns.qty]) : null;
+    const supplier = columns.supplier >= 0
+      ? String(row[columns.supplier] === null || row[columns.supplier] === undefined ? '' : row[columns.supplier]).trim()
+      : '';
+
+    const existing = aggregated.get(code);
+    if (!existing) {
+      aggregated.set(code, {
+        productCode: code,
+        createdAt: time,
+        inboundQty: qty === null ? null : qty,
+        supplier,
+      });
+    } else {
+      if (time && (!existing.createdAt || time < existing.createdAt)) existing.createdAt = time;
+      if (qty !== null) {
+        existing.inboundQty = (existing.inboundQty === null ? 0 : existing.inboundQty) + qty;
+      }
+      if (!existing.supplier && supplier) existing.supplier = supplier;
+    }
+  }
+
+  const records = Array.from(aggregated.values());
+  records.forEach((record) => {
+    if (record.createdAt) withCreatedAt += 1;
+    if (record.inboundQty !== null) withQty += 1;
+  });
+
+  return {
+    records,
+    sheetName,
+    headerIndex,
+    columns,
+    totalRows: matrix.length - headerIndex - 1,
+    skipped,
+    withCreatedAt,
+    withQty,
+  };
+}
+
+function toMysqlDateTime(value) {
+  if (!value) return null;
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return null;
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} `
+    + `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+/**
+ * 写入导入数据（按仓库整批替换：以该仓最新一次导出为准）
+ * 只删/写当前仓库的行，不会动其它看板的导入数据。
+ */
+async function importStockWarning({ buffer, fileName, importedBy, warehouseKey }) {
+  const parsed = parseImportBuffer(buffer);
+  if (!parsed.records.length) {
+    throw new Error('没有解析到任何有效的商品编码行');
+  }
+
+  const key = String(warehouseKey || DEFAULT_WAREHOUSE_KEY).trim() || DEFAULT_WAREHOUSE_KEY;
+  const batchId = `${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+
+  await database.local.query(
+    'DELETE FROM return_stock_warning_import WHERE warehouse_key = ?',
+    [key]
+  );
+
+  const chunkSize = 500;
+  for (let i = 0; i < parsed.records.length; i += chunkSize) {
+    const chunk = parsed.records.slice(i, i + chunkSize);
+    const values = chunk.map((record) => ([
+      key,
+      record.productCode,
+      toMysqlDateTime(record.createdAt),
+      record.inboundQty,
+      record.supplier || null,
+      batchId,
+    ]));
+    await database.local.query(
+      `INSERT INTO return_stock_warning_import
+         (warehouse_key, product_code, created_at, inbound_qty, supplier, batch_id)
+       VALUES ?
+       ON DUPLICATE KEY UPDATE
+         created_at = VALUES(created_at),
+         inbound_qty = VALUES(inbound_qty),
+         supplier = VALUES(supplier),
+         batch_id = VALUES(batch_id)`,
+      [values]
+    );
+  }
+
+  await database.local.query(
+    `INSERT INTO return_stock_warning_import_batch
+       (batch_id, warehouse_key, file_name, total_rows, matched_rows, with_created_at, with_qty, skipped_rows, imported_by)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      batchId,
+      key,
+      String(fileName || '').slice(0, 255),
+      parsed.totalRows,
+      parsed.records.length,
+      parsed.withCreatedAt,
+      parsed.withQty,
+      parsed.skipped,
+      importedBy || null,
+    ]
+  );
+
+  return {
+    batchId,
+    warehouseKey: key,
+    fileName: String(fileName || ''),
+    sheetName: parsed.sheetName,
+    totalRows: parsed.totalRows,
+    matchedRows: parsed.records.length,
+    withCreatedAt: parsed.withCreatedAt,
+    withQty: parsed.withQty,
+    skippedRows: parsed.skipped,
+    detectedColumns: {
+      code: parsed.columns.code,
+      time: parsed.columns.time,
+      qty: parsed.columns.qty,
+      supplier: parsed.columns.supplier,
+    },
+  };
+}
+
+/** 清除当前仓库的导入，回到「系统推算」口径（不影响其它看板） */
+async function clearStockWarningImport(warehouseKey) {
+  const key = String(warehouseKey || DEFAULT_WAREHOUSE_KEY).trim() || DEFAULT_WAREHOUSE_KEY;
+  await database.local.query('DELETE FROM return_stock_warning_import WHERE warehouse_key = ?', [key]);
+  await database.local.query('DELETE FROM return_stock_warning_import_batch WHERE warehouse_key = ?', [key]);
+  return { cleared: true, warehouseKey: key };
+}
+
+module.exports = {
+  importStockWarning,
+  clearStockWarningImport,
+  parseImportBuffer,
+};

backend/src/services/returnStockWarningSchema.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * 退货库存预警（客退数据监控）本地表
+ * --------------------------------------------------------------------------
+ * 为什么需要本地表：
+ *   报表副本（JSReportReplica）只有仓库级库存表 jst_inventoryInfo，
+ *   没有聚水潭「箱及仓位库存」的箱/仓位维度，因此：
+ *     - 「创建时间」= 聚水潭该箱/仓位记录的上架时间，副本里根本没有这个字段；
+ *     - 「件数」也可能与聚水潭口径不同（副本只能按 return_qty + 客退自定义库存位近似）。
+ *   要跟聚水潭页面 100% 对齐，唯一办法是把聚水潭导出的「箱及仓位库存」导入进来，
+ *   按商品编码覆盖创建时间（可选覆盖件数），并持久化。
+ *
+ * 按仓库隔离（2026-09-16 新增）：
+ *   现在有横林二仓 / 苏北 / 睢宁 / 山东 / 河南 五张看板，每张上传的是各自仓库的聚水潭导出文件，
+ *   同一份文件里同一个商品编码可能同时出现在多个仓；如果不按仓隔离，后导入的会把先导入的覆盖掉。
+ *   因此两张表都加了 warehouse_key，主键从 (product_code) 改成 (warehouse_key, product_code)。
+ */
+
+const database = require('../config/database');
+
+const DEFAULT_WAREHOUSE_KEY = 'henlin2';
+
+const SCHEMA_SQL = [
+  // 1. 按「仓库 + 商品编码」的导入覆盖值（以聚水潭导出为准）
+  `CREATE TABLE IF NOT EXISTS return_stock_warning_import (
+    warehouse_key VARCHAR(32) NOT NULL DEFAULT '${DEFAULT_WAREHOUSE_KEY}' COMMENT '仓库标识（henlin2/subei/suining/shandong/henan）',
+    product_code VARCHAR(120) NOT NULL COMMENT '商品编码',
+    created_at DATETIME NULL COMMENT '聚水潭创建时间（上架时间）',
+    inbound_qty INT NULL COMMENT '聚水潭件数（导入，可为空=不覆盖）',
+    supplier VARCHAR(255) NULL COMMENT '聚水潭供应商（导入，可为空）',
+    batch_id VARCHAR(64) NOT NULL COMMENT '导入批次',
+    imported_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '导入时间',
+    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    PRIMARY KEY (warehouse_key, product_code),
+    KEY idx_rswi_batch (batch_id)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='退货库存预警-聚水潭导入覆盖值（按仓库+商品编码）'`,
+
+  // 2. 导入批次日志
+  `CREATE TABLE IF NOT EXISTS return_stock_warning_import_batch (
+    batch_id VARCHAR(64) NOT NULL COMMENT '导入批次',
+    warehouse_key VARCHAR(32) NOT NULL DEFAULT '${DEFAULT_WAREHOUSE_KEY}' COMMENT '仓库标识',
+    file_name VARCHAR(255) NULL COMMENT '文件名',
+    total_rows INT NOT NULL DEFAULT 0 COMMENT '解析出的行数',
+    matched_rows INT NOT NULL DEFAULT 0 COMMENT '成功写入的编码数',
+    with_created_at INT NOT NULL DEFAULT 0 COMMENT '含创建时间的行数',
+    with_qty INT NOT NULL DEFAULT 0 COMMENT '含件数的行数',
+    skipped_rows INT NOT NULL DEFAULT 0 COMMENT '无商品编码被跳过的行数',
+    imported_by VARCHAR(100) NULL COMMENT '导入人',
+    imported_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '导入时间',
+    PRIMARY KEY (batch_id),
+    KEY idx_rswibatch_time (imported_at),
+    KEY idx_rswibatch_wh (warehouse_key, imported_at)
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='退货库存预警-聚水潭导入批次日志'`,
+];
+
+/** 某张表上是否存在某列 */
+async function hasColumn(table, column) {
+  const rows = await database.local.query(
+    `SELECT COUNT(*) AS cnt
+     FROM information_schema.COLUMNS
+     WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ?`,
+    [table, column]
+  );
+  return Number(rows?.[0]?.cnt || 0) > 0;
+}
+
+/** 某张表的主键列（按顺序） */
+async function getPrimaryKeyColumns(table) {
+  const rows = await database.local.query(
+    `SELECT COLUMN_NAME
+     FROM information_schema.KEY_COLUMN_USAGE
+     WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND CONSTRAINT_NAME = 'PRIMARY'
+     ORDER BY ORDINAL_POSITION`,
+    [table]
+  );
+  return (rows || []).map((row) => String(row.COLUMN_NAME || '').toUpperCase());
+}
+
+/**
+ * 老库升级：给已存在的两张表补 warehouse_key，并把导入表主键改成 (warehouse_key, product_code)。
+ * 幂等，每次启动都跑一遍，已经是新结构时不做任何事。
+ */
+async function migrateReturnStockWarningSchema() {
+  // 逐列补：两张表都要有 warehouse_key
+  const targets = ['return_stock_warning_import', 'return_stock_warning_import_batch'];
+  for (const table of targets) {
+    // eslint-disable-next-line no-await-in-loop
+    if (!(await hasColumn(table, 'warehouse_key'))) {
+      // 老数据全部归到默认仓（横林二仓）——它本来就是为横林二仓建的
+      // eslint-disable-next-line no-await-in-loop
+      await database.local.query(
+        `ALTER TABLE ${table}
+         ADD COLUMN warehouse_key VARCHAR(32) NOT NULL DEFAULT '${DEFAULT_WAREHOUSE_KEY}'
+           COMMENT '仓库标识' AFTER ${table === 'return_stock_warning_import' ? 'product_code' : 'batch_id'}`
+      );
+    }
+  }
+
+  // 主键改造：老结构是 (product_code)，需要换成 (warehouse_key, product_code)
+  const pk = await getPrimaryKeyColumns('return_stock_warning_import');
+  if (pk.length === 1 && pk[0] === 'PRODUCT_CODE') {
+    await database.local.query(
+      'ALTER TABLE return_stock_warning_import DROP PRIMARY KEY, ADD PRIMARY KEY (warehouse_key, product_code)'
+    );
+  }
+
+  // 批次表的仓库索引
+  const idxRows = await database.local.query(
+    `SELECT COUNT(*) AS cnt
+     FROM information_schema.STATISTICS
+     WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'return_stock_warning_import_batch'
+       AND INDEX_NAME = 'idx_rswibatch_wh'`
+  );
+  if (Number(idxRows?.[0]?.cnt || 0) === 0) {
+    await database.local.query(
+      'ALTER TABLE return_stock_warning_import_batch ADD KEY idx_rswibatch_wh (warehouse_key, imported_at)'
+    );
+  }
+}
+
+async function ensureReturnStockWarningSchema() {
+  for (const sql of SCHEMA_SQL) {
+    // eslint-disable-next-line no-await-in-loop
+    await database.local.query(sql);
+  }
+  await migrateReturnStockWarningSchema();
+}
+
+module.exports = { ensureReturnStockWarningSchema, migrateReturnStockWarningSchema };

backend/src/services/stockSalesAnalysis.js

@@ -0,0 +1,248 @@
+'use strict';
+
+/**
+ * 仓库库存动销分析 —— 业务库取数
+ *
+ * 一次查询覆盖全部仓库 × 全部动销等级：
+ *   库存件数：rpt.jst_inventoryInfo 实时库存（按 wms_co_id + sku_id 汇总）
+ *   销量：    rpt.jst_OrderItem × rpt.jst_Orders，按 send_date，排除 Delete/Cancelled
+ *             （与「每日进销存」的发货口径一致）
+ *   日销：    销量 / 统计窗口天数 → 分档得到动销等级
+ *
+ * 只统计「有库存或有销量」的 SKU：库存为 0 且窗口内无销量的 SKU 已下架，
+ * 计入「销售=0」会虚增分母，故整体剔除。
+ */
+
+const { SALES_GRADE_RULES } = require('../config/stockSalesAnalysis');
+
+/** mssql 不支持数组参数，按位展开成 @p0,@p1... */
+function buildInClause(values, prefix) {
+  const params = {};
+  const clause = values
+    .map((v, i) => {
+      const key = `${prefix}${i}`;
+      params[key] = v;
+      return `@${key}`;
+    })
+    .join(',');
+  return { clause, params };
+}
+
+/**
+ * 日销分档表达式：从高档往低档依次命中。
+ * 最后一档「销售=0」由 `salesQty <= 0` 兜底（销量为 NULL 视同 0）。
+ */
+function buildGradeCase(salesExpr = 'ISNULL(b.salesQty, 0)', daysParam = '@days') {
+  const branches = SALES_GRADE_RULES
+    .filter((rule) => rule.lower > 0)
+    .map((rule) => {
+      const daily = `(${salesExpr} / ${daysParam})`;
+      const lower = `${daily} >= ${rule.lower}`;
+      const upper = rule.upper == null ? null : `${daily} < ${rule.upper}`;
+      const cond = upper ? `${lower} AND ${upper}` : lower;
+      return `WHEN ${cond} THEN '${rule.key}'`;
+    });
+
+  return `
+      CASE
+        ${branches.join('\n        ')}
+        WHEN ${salesExpr} > 0 THEN 'slow2'
+        ELSE 'zero'
+      END`;
+}
+
+/**
+ * 每个仓库 × 每个动销等级的 SKU 数、库存件数、销量。
+ * @returns {Promise<Array<{wmsCoId:string, gradeKey:string, skuCount:number, stockQty:number, salesQty:number, dailySales:number}>>}
+ */
+async function fetchGradeRows(cloudDb, wmsCoIds, { shipFrom, shipTo, days }) {
+  if (!cloudDb || typeof cloudDb.query !== 'function') {
+    throw new TypeError('fetchGradeRows 的第一个参数必须是业务库实例');
+  }
+  if (!Array.isArray(wmsCoIds) || wmsCoIds.length === 0) return [];
+  if (!shipFrom || !shipTo || !days) return [];
+
+  const invIn = buildInClause(wmsCoIds, 'w');
+  const shipIn = buildInClause(wmsCoIds, 'v');
+  const gradeCase = buildGradeCase();
+
+  const sqlText = `
+    WITH inv AS (
+      SELECT i.wms_co_id AS wmsCoId,
+             i.sku_id    AS skuId,
+             SUM(CAST(ISNULL(i.qty, 0) AS DECIMAL(18, 2))) AS stockQty
+        FROM rpt.jst_inventoryInfo i
+       WHERE i.wms_co_id IN (${invIn.clause})
+       GROUP BY i.wms_co_id, i.sku_id
+    ),
+    ship AS (
+      SELECT o.wms_co_id AS wmsCoId,
+             oi.sku_id   AS skuId,
+             SUM(CAST(ISNULL(oi.qty, 0) AS DECIMAL(18, 2))) AS salesQty
+        FROM rpt.jst_OrderItem oi
+        JOIN rpt.jst_Orders o ON o.o_id = oi.o_id
+       WHERE o.wms_co_id IN (${shipIn.clause})
+         AND o.send_date >= @shipFrom
+         AND o.send_date < @shipTo
+         AND ISNULL(o.status, '') NOT IN ('Delete', 'Cancelled')
+       GROUP BY o.wms_co_id, oi.sku_id
+    ),
+    base AS (
+      SELECT u.wmsCoId,
+             u.skuId,
+             SUM(u.stockQty) AS stockQty,
+             SUM(u.salesQty) AS salesQty
+        FROM (
+          SELECT wmsCoId, skuId, stockQty, CAST(0 AS DECIMAL(18, 2)) AS salesQty FROM inv
+          UNION ALL
+          SELECT wmsCoId, skuId, CAST(0 AS DECIMAL(18, 2)) AS stockQty, salesQty FROM ship
+        ) u
+       GROUP BY u.wmsCoId, u.skuId
+    ),
+    graded AS (
+      SELECT b.wmsCoId,
+             b.stockQty,
+             b.salesQty,
+             ${gradeCase} AS gradeKey
+        FROM base b
+       WHERE ABS(ISNULL(b.stockQty, 0)) > 0.0001
+          OR ABS(ISNULL(b.salesQty, 0)) > 0.0001
+    )
+    SELECT g.wmsCoId,
+           g.gradeKey,
+           COUNT(*)                                     AS skuCount,
+           CAST(SUM(ISNULL(g.stockQty, 0)) AS DECIMAL(18, 2))  AS stockQty,
+           CAST(SUM(ISNULL(g.salesQty, 0)) AS DECIMAL(18, 2))  AS salesQty,
+           CAST(SUM(ISNULL(g.salesQty, 0) / @days) AS DECIMAL(18, 4)) AS dailySales
+      FROM graded g
+     GROUP BY g.wmsCoId, g.gradeKey`;
+
+  const rows = await cloudDb.query(sqlText, {
+    ...invIn.params,
+    ...shipIn.params,
+    shipFrom,
+    shipTo,
+    days,
+  }, { requestTimeout: 180000 });
+
+  return rows.map((r) => ({
+    wmsCoId: String(r.wmsCoId),
+    gradeKey: String(r.gradeKey),
+    skuCount: Number(r.skuCount) || 0,
+    stockQty: Number(r.stockQty) || 0,
+    salesQty: Number(r.salesQty) || 0,
+    dailySales: Number(r.dailySales) || 0,
+  }));
+}
+
+/**
+ * 「销售=0」档的 SKU 级明细（导出用）。
+ * 口径与 fetchGradeRows 完全一致：同一分档表达式命中 gradeKey='zero'，
+ * 即统计窗口内销量 <= 0 且「有库存或有销量」的 SKU。
+ *
+ * 系统仓位取自 rpt.jst_packInventoryInfo.bin（jst_sku.bin 全为空、库存表无仓位字段）。
+ * 每个仓位独立一行，库存数量按该仓位的实际 qty 统计（各仓位行之和 = SKU 总库存）：
+ *   - 有仓位数据的 SKU：按 (wms_co_id, sku_id, bin) 展开，qty=0 的仓位行剔除；
+ *   - 无仓位数据的 SKU（仓位表未覆盖的仓库）：保留一行，仓位为空、库存取 SKU 总库存，避免丢数。
+ * @returns {Promise<Array<{wmsCoId:string, skuId:string, skuName:string, binName:string, stockQty:number, salesQty:number}>>}
+ */
+async function fetchZeroSaleSkuRows(cloudDb, wmsCoIds, { shipFrom, shipTo, days }) {
+  if (!cloudDb || typeof cloudDb.query !== 'function') {
+    throw new TypeError('fetchZeroSaleSkuRows 的第一个参数必须是业务库实例');
+  }
+  if (!Array.isArray(wmsCoIds) || wmsCoIds.length === 0) return [];
+  if (!shipFrom || !shipTo || !days) return [];
+
+  const invIn = buildInClause(wmsCoIds, 'w');
+  const shipIn = buildInClause(wmsCoIds, 'v');
+  const gradeCase = buildGradeCase();
+
+  const sqlText = `
+    WITH bin AS (
+      SELECT p.wms_co_id AS wmsCoId,
+             p.sku_id    AS skuId,
+             LTRIM(RTRIM(p.bin)) AS b,
+             SUM(CAST(ISNULL(p.qty, 0) AS DECIMAL(18, 2))) AS binQty
+        FROM rpt.jst_packInventoryInfo p
+       WHERE ISNULL(p.bin, '') <> ''
+         AND ISNULL(p.qty, 0) <> 0
+       GROUP BY p.wms_co_id, p.sku_id, LTRIM(RTRIM(p.bin))
+    ),
+    inv AS (
+      SELECT i.wms_co_id AS wmsCoId,
+             i.sku_id    AS skuId,
+             SUM(CAST(ISNULL(i.qty, 0) AS DECIMAL(18, 2))) AS stockQty
+        FROM rpt.jst_inventoryInfo i
+       WHERE i.wms_co_id IN (${invIn.clause})
+       GROUP BY i.wms_co_id, i.sku_id
+    ),
+    ship AS (
+      SELECT o.wms_co_id AS wmsCoId,
+             oi.sku_id   AS skuId,
+             SUM(CAST(ISNULL(oi.qty, 0) AS DECIMAL(18, 2))) AS salesQty
+        FROM rpt.jst_OrderItem oi
+        JOIN rpt.jst_Orders o ON o.o_id = oi.o_id
+       WHERE o.wms_co_id IN (${shipIn.clause})
+         AND o.send_date >= @shipFrom
+         AND o.send_date < @shipTo
+         AND ISNULL(o.status, '') NOT IN ('Delete', 'Cancelled')
+       GROUP BY o.wms_co_id, oi.sku_id
+    ),
+    base AS (
+      SELECT u.wmsCoId,
+             u.skuId,
+             SUM(u.stockQty) AS stockQty,
+             SUM(u.salesQty) AS salesQty
+        FROM (
+          SELECT wmsCoId, skuId, stockQty, CAST(0 AS DECIMAL(18, 2)) AS salesQty FROM inv
+          UNION ALL
+          SELECT wmsCoId, skuId, CAST(0 AS DECIMAL(18, 2)) AS stockQty, salesQty FROM ship
+        ) u
+       GROUP BY u.wmsCoId, u.skuId
+    ),
+    graded AS (
+      SELECT b.wmsCoId,
+             b.skuId,
+             b.stockQty,
+             b.salesQty,
+             ${gradeCase} AS gradeKey
+        FROM base b
+       WHERE ABS(ISNULL(b.stockQty, 0)) > 0.0001
+          OR ABS(ISNULL(b.salesQty, 0)) > 0.0001
+    )
+    SELECT g.wmsCoId,
+           g.skuId,
+           ISNULL(s.name, '') AS skuName,
+           ISNULL(bn.b, '') AS binName,
+           CAST(COALESCE(bn.binQty, g.stockQty) AS DECIMAL(18, 2)) AS stockQty,
+           CAST(g.salesQty AS DECIMAL(18, 2)) AS salesQty
+      FROM graded g
+      LEFT JOIN rpt.jst_sku s ON s.sku_id = g.skuId
+      LEFT JOIN bin bn ON bn.wmsCoId = g.wmsCoId AND bn.skuId = g.skuId
+     WHERE g.gradeKey = 'zero'
+     ORDER BY g.wmsCoId, g.stockQty DESC, g.skuId, bn.b`;
+
+  const rows = await cloudDb.query(sqlText, {
+    ...invIn.params,
+    ...shipIn.params,
+    shipFrom,
+    shipTo,
+    days,
+  }, { requestTimeout: 180000 });
+
+  return rows.map((r) => ({
+    wmsCoId: String(r.wmsCoId),
+    skuId: String(r.skuId ?? ''),
+    skuName: r.skuName == null ? '' : String(r.skuName),
+    binName: r.binName == null ? '' : String(r.binName),
+    stockQty: Number(r.stockQty) || 0,
+    salesQty: Number(r.salesQty) || 0,
+  }));
+}
+
+module.exports = {
+  buildInClause,
+  buildGradeCase,
+  fetchGradeRows,
+  fetchZeroSaleSkuRows,
+};

backend/src/services/supplierExitDateProvider.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * 「最晚退厂时间」取数（2026-09-28 新增）
+ *
+ * 业务口径：供应商不再合作时，工作平台会给该供应商一个「最晚退厂时间」，
+ * 即它放在仓里的货最后必须拉走的日期，看板上跟「供应商是否合作」列并排展示。
+ *
+ * ── 数据在哪 ──────────────────────────────────────────────────────────────
+ * 工作平台库。副本实例（218.93.9.21:1433）上共有 9 个库：
+ *   master / model / msdb / tempdb / SSISDB / JSReportReplica（副本，我们只读它）/
+ *   DataPlatformControl / WorkbenchDataShared / WorkbenchIdentity。
+ * 「工作平台」= WorkbenchDataShared（配套身份库 WorkbenchIdentity，控制库 DataPlatformControl）。
+ *
+ * ── 当前为什么是空的（2026-09-28 已逐条取证，别再重复排查）───────────────
+ *  ① 副本账号 cangku 访问 WorkbenchDataShared / WorkbenchIdentity / DataPlatformControl
+ *     **一律被拒**：The server principal "cangku" is not able to access the database
+ *     "WorkbenchDataShared" under the current security context.
+ *  ② 系统设置（database_configs）里只有 cloud_database_public（JSReportReplica）与
+ *     product_information_database（PostgreSQL），没有工作平台库。
+ *  ③ 本机 .env 与生产 /opt/cangku/shared/backend.env 里的 JIAN_SUN_DB_HOST/USER/PASSWORD、
+ *     WORK_ORDER_* 全部为空（只留了端口/库名占位）。
+ *  ④ 副本库内部没有任何「退厂」字段：5,496 个字段全量搜过，COLUMN_NAME 含「退厂」的为 0；
+ *     最接近的 fys_supplier.NoCoopTime（不合作时间）**不能拿来顶替** —— 它是停更快照
+ *     （DownloadTime 多在 2023~2024），崔桥仓 8 个不合作供应商里只有 1 个有值，
+ *     而且那 1 条自身还标着 IsCoop='合作'，自相矛盾。
+ *
+ * ── IT 开通后怎么接（只需改本文件）────────────────────────────────────────
+ * 二选一，改完即生效，页面与导出都会自动出数：
+ *  A. 给副本账号授只读：让 IT 执行 `USE WorkbenchDataShared; GRANT SELECT TO [cangku];`
+ *     （或建同义词/视图），然后把下面 EXIT_DATE_QUERY 填成跨库查询，例如：
+ *     SELECT SupplierName AS supplierName, CONVERT(varchar(10), LatestExitDate, 120) AS exitDate
+ *     FROM WorkbenchDataShared.dbo.<供应商不合作表>
+ *  B. 让 IT 把「供应商不合作」表同步进 JSReportReplica（像 js_supplier / fys_supplier 那样），
+ *     再把 EXIT_DATE_QUERY 指向副本里的表名。
+ * 查询只需要返回两列：supplierName（供应商名，口径同 js_supplier.scmname / jst_sku.supplier_name，
+ * 即简称）与 exitDate（最晚退厂日期，字符串 'YYYY-MM-DD' 或 datetime 均可）。
+ *
+ * 未接入时本模块恒返回 available=false，页面该列显示「待接入」，不会报错、不影响其他列。
+ */
+
+const cloudDb = require('../config/cloudDatabase');
+
+const SOURCE_LABEL = '工作平台（WorkbenchDataShared）· 供应商不合作';
+const UNAVAILABLE_MESSAGE = '工作平台库尚未授权，待 IT 开通后自动出数';
+
+// ---- 接入点（IT 开通后配这两个环境变量即可，不必改代码）--------------------
+//   SUPPLIER_EXIT_DATE_ENABLED=true
+//   SUPPLIER_EXIT_DATE_SQL=<查询语句，需返回 supplierName / exitDate 两列>
+// 也可以在下面 CODE_* 常量里直接写死（env 优先）。
+const CODE_EXIT_DATE_ENABLED = false;
+const CODE_EXIT_DATE_QUERY = '';
+const ENABLED = process.env.SUPPLIER_EXIT_DATE_ENABLED === 'true' || CODE_EXIT_DATE_ENABLED;
+const EXIT_DATE_QUERY = process.env.SUPPLIER_EXIT_DATE_SQL || CODE_EXIT_DATE_QUERY;
+// ---------------------------------------------------------------------------
+
+const CACHE_TTL_MS = Number.parseInt(process.env.SUPPLIER_EXIT_DATE_CACHE_TTL_MS, 10) >= 0
+  ? Number.parseInt(process.env.SUPPLIER_EXIT_DATE_CACHE_TTL_MS, 10)
+  : 30 * 60 * 1000;
+
+let cache = null; // { at, payload }
+
+const formatExitDate = (value) => {
+  if (value === null || value === undefined || value === '') return '';
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return '';
+    const y = value.getFullYear();
+    const m = String(value.getMonth() + 1).padStart(2, '0');
+    const d = String(value.getDate()).padStart(2, '0');
+    return `${y}-${m}-${d}`;
+  }
+  const text = String(value).trim();
+  if (!text) return '';
+  const match = text.match(/^(\d{4})[-/.](\d{1,2})[-/.](\d{1,2})/);
+  if (!match) return text;
+  return `${match[1]}-${match[2].padStart(2, '0')}-${match[3].padStart(2, '0')}`;
+};
+
+/**
+ * 取「供应商 → 最晚退厂时间」映射。
+ * 返回 { available, sourceLabel, message, bySupplier: Map<string, string> }
+ */
+async function loadSupplierExitDates() {
+  const describe = () => ({
+    available: false,
+    sourceLabel: SOURCE_LABEL,
+    message: UNAVAILABLE_MESSAGE,
+    bySupplier: new Map(),
+  });
+
+  if (!ENABLED || !EXIT_DATE_QUERY) return describe();
+  if (cache && Date.now() - cache.at < CACHE_TTL_MS) return cache.payload;
+
+  try {
+    const rows = await cloudDb.query(EXIT_DATE_QUERY, {}, { requestTimeout: 120000 });
+    const bySupplier = new Map();
+    (rows || []).forEach((row) => {
+      const name = String(row.supplierName || '').trim();
+      const date = formatExitDate(row.exitDate);
+      if (!name || !date) return;
+      const prev = bySupplier.get(name);
+      // 同一供应商多条时取最晚的日期
+      if (!prev || date > prev) bySupplier.set(name, date);
+    });
+    const payload = {
+      available: true,
+      sourceLabel: SOURCE_LABEL,
+      message: '',
+      bySupplier,
+    };
+    cache = { at: Date.now(), payload };
+    return payload;
+  } catch (error) {
+    // 取不到不算致命：该列留空、页面提示待接入，其余列照常
+    console.warn('[SupplierExitDate] 最晚退厂时间取数失败:', error.message);
+    const payload = {
+      available: false,
+      sourceLabel: SOURCE_LABEL,
+      message: `工作平台库读取失败（${error.message}），该列暂空`,
+      bySupplier: new Map(),
+    };
+    cache = { at: Date.now(), payload };
+    return payload;
+  }
+}
+
+const EMPTY_EXIT_DATES = Object.freeze({
+  available: false,
+  sourceLabel: SOURCE_LABEL,
+  message: UNAVAILABLE_MESSAGE,
+  bySupplier: new Map(),
+});
+
+module.exports = {
+  loadSupplierExitDates,
+  formatExitDate,
+  EMPTY_EXIT_DATES,
+  EXIT_DATE_SOURCE_LABEL: SOURCE_LABEL,
+  EXIT_DATE_UNAVAILABLE_MESSAGE: UNAVAILABLE_MESSAGE,
+};

backend/src/services/warehouseShipTimelinessRegistry.js

@@ -0,0 +1,246 @@
+'use strict';
+
+/**
+ * 仓储中心 24 小时发货时效（2026-10-20 新增）
+ * ────────────────────────────────────────────────────────────────────────────
+ * 需求（yanhui 2026-10-20）：
+ *   MKH-BOM 列表左侧加一栏「仓储中心24小时发货时效」，下列 11 个仓：
+ *     横林二仓 / 横林三仓 / 横林二仓品牌仓 / 崔桥工厂仓 / 崔桥工厂品牌仓 /
+ *     崔桥工厂半成品仓 / 新苏北仓 / 睢宁仓 / 山东青岗集仓 / 山东品牌仓 / 河南洛宁仓
+ *   从系统库存抓取「已发货订单」与「未发货订单」，按**订单创建时间**算是否及时。
+ *   每天 12:00 核验「当天创建、7:00 前」的订单是否已发货；
+ *   每天 16:00 核验「当天创建、16:00 前」的订单是否已发货。
+ *   展示口径：**只显示超时未发**（业务确认）。
+ *
+ * 业务确认的口径（2026-10-20 AskUserQuestion）：
+ *   ① 子仓归属主仓 —— **连子仓一起算**（如 横林二仓 含京东云仓/京东自营仓/运营C专用仓 等）
+ *   ② 崔桥工厂半成品仓 —— 系统无同名仓，**先留空占位**（不映射到 15718196）
+ *   ③ 展示结构 —— **只显示超时未发**
+ *
+ * ── 数据源 ────────────────────────────────────────────────────────────────
+ * 订单：两张表**店铺互斥，必须都读**（见 mkhBomService 文件头）
+ *   rpt.jst_Orders            —— 京东 / 拼多多 / 抖音 / 得物 / 唯品会
+ *   rpt.jst_qmcust_orderlist  —— 天猫 / 淘宝 / 1688
+ * 字段口径：
+ *   · 创建时间：`order_date`（订单创建时间，业务要求按此算时效）
+ *   · 发货时间：`send_date`（为空 = 未发货）
+ *   · 发货仓：  `wms_co_id`（订单**发货仓**，不是 SKU 的归属仓）
+ *   ⚠️ 用户原话「从系统库存抓取」—— 本实现取的是**订单维度**的仓库归属，
+ *      因为 jst_inventoryInfo 只有「某 SKU 在某仓有多少件」，没有订单记录。
+ *
+ * ── 仓库归属（按名称包含匹配，最长匹配优先）────────────────────────────────
+ * `rpt.jst_warehouseInfo` 实测（2026-10-20）：
+ *   横林二仓        15033302  + 15197138/15301814/15835893/16040225/16132681
+ *   横林三仓        15043561
+ *   横林二仓品牌仓  16132681（**同时命中也属于「横林二仓」，靠最长匹配优先归到品牌仓**）
+ *   崔桥工厂仓      15038426  + 15301815/16040410
+ *   崔桥工厂品牌仓  15870495
+ *   崔桥工厂半成品仓  ——  无同名仓，留空
+ *   新苏北仓        15038347  + 15315031/15301812
+ *   睢宁仓          15032603  + 15051907/15051960/15052203/15301813/15386911
+ *   山东青岗集仓    15137523  + 15283033/15406664/15835935/16040432/16129076
+ *   山东品牌仓      15182705
+ *   河南洛宁仓      15539084
+ * ⟹ 仓库 ID → 主仓 的映射**在启动时从库表读取并缓存**（不用手写 ID 常量，
+ *    避免上游新增子仓后要改代码；新增子仓只要名字里带主仓关键词就会自动归入）。
+ *    缓存 TTL 1 小时，可用 clearWarehouseCache() 手动清。
+ *
+ * ── 时效判定 ──────────────────────────────────────────────────────────────
+ * 截止时刻（每日两轮，取**当前已生效且最晚**的那一轮；未到 12:00 时无截止）：
+ *   12:00 → 核验「当天 00:00 ~ 07:00 创建」的订单
+ *   16:00 → 核验「当天 00:00 ~ 16:00 创建」的订单
+ * 判定：
+ *   · 超时未发 = `send_date IS NULL` 且 `order_date <= 截止时刻`
+ *   · 按时已发 = `send_date IS NOT NULL` 且 `send_date <= 截止时刻`  → **不计入超时**
+ *   · 已发但超时 = `send_date > 截止时刻` → 也算超时（已发，但没赶上截止）
+ * 业务只要「超时未发」，所以列表只返回 `send_date IS NULL` 的超时单；
+ * 但 summary 里仍给出 `overdueShipped`，避免「已发但超时」被当成没超时。
+ *
+ * ── 时区 ──────────────────────────────────────────────────────────────────
+ * 订单时间列存的是**东八区本地时间**（实测 `order_date` 与 `created` 相差十几秒，
+ * 均为北京时间）。因此 SQL 里统一用 `CAST(GETDATE() AS date)` 取「今天」，
+ * 服务器与数据库都在东八区；**不要**在 Node 侧用 UTC 日期做判断。
+ */
+
+const cloudDatabase = require('../config/cloudDatabase');
+
+// ── 主仓定义（业务给定的 11 个）──────────────────────────────────────────
+// keywords：该主仓在 rpt.jst_warehouseInfo.name 里应包含的关键词（任一命中即归属）
+// 顺序即展示顺序；`match` 用最长关键词优先，所以「横林二仓品牌仓」不会被「横林二仓」抢走。
+const CENTERS = Object.freeze([
+  { key: 'HL2', name: '横林二仓', keywords: ['横林二仓'] },
+  { key: 'HL3', name: '横林三仓', keywords: ['横林三仓'] },
+  { key: 'HL2_BRAND', name: '横林二仓品牌仓', keywords: ['横林二仓品牌仓'] },
+  { key: 'CQ', name: '崔桥工厂仓', keywords: ['崔桥工厂仓'] },
+  { key: 'CQ_BRAND', name: '崔桥工厂品牌仓', keywords: ['崔桥工厂品牌仓'] },
+  // 系统内无同名仓（最接近的「简尚-崔桥工厂半成品包装项目仓」15718196 是配件仓，
+  // 业务确认先留空占位，不并进来）
+  { key: 'CQ_WIP', name: '崔桥工厂半成品仓', keywords: [], placeholder: true },
+  { key: 'XSB', name: '新苏北仓', keywords: ['新苏北'] },
+  { key: 'SN', name: '睢宁仓', keywords: ['睢宁'] },
+  { key: 'SD_QGJ', name: '山东青岗集仓', keywords: ['山东青岗集'] },
+  { key: 'SD_BRAND', name: '山东品牌仓', keywords: ['山东品牌仓'] },
+  { key: 'HN_LN', name: '河南洛宁仓', keywords: ['河南洛宁'] },
+]);
+
+// 「横林三仓」与「横林二仓」不含对方，安全；但「崔桥工厂品牌仓」含「崔桥工厂仓」片段，
+// 靠关键词长度倒序匹配即可（见 resolveCenter）。
+const SORTED_KEYWORDS = CENTERS
+  .filter((c) => c.keywords.length)
+  .flatMap((c) => c.keywords.map((kw) => ({ kw, center: c })))
+  .sort((a, b) => b.kw.length - a.kw.length);
+
+// ── 时效轮次（业务给定）──────────────────────────────────────────────────
+// cutoffHour：当天几点截止；windowEndHour：只核验「创建时间不晚于该时刻」的订单
+const ROUNDS = Object.freeze([
+  { key: 'NOON', label: '12:00 轮', cutoffHour: 12, windowEndHour: 7 },
+  { key: 'AFTERNOON', label: '16:00 轮', cutoffHour: 16, windowEndHour: 16 },
+]);
+
+// 只排除取消/合并单；Question 仍计入（与 mkhBomService 待发货口径一致）
+//
+// 🔥 Split（拆单）：**必须排除**。拆单是「父单被拆成子单」的中间态，父单本身
+// 不会发货（`send_date` 永远为空），子单才是真正进仓发货的那一单。
+// 2026-10-20 实测：不加这个条件，一年前的 Split 父单全被算成「超时未发」，
+// 全库未发 Split 单占比极高 —— 会让页面变成上万条的垃圾列表。
+// ⚠️ 与 mkhBomService 的差异：那边是「预警今天要发的货」，Split 父单不带真实
+//    发货需求，被算进去也无害；这边是「考核仓库时效」，误算就要背锅，必须排除。
+const EXCLUDED_STATUS_SQL = `ISNULL(o.status, N'') NOT IN (N'Cancelled', N'Merged', N'Split')`;
+
+const WAREHOUSE_CACHE_TTL_MS = 60 * 60 * 1000;
+let warehouseCache = { at: 0, rows: [] };
+
+function toNumber(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function pad2(n) {
+  return String(n).padStart(2, '0');
+}
+
+/**
+ * 用「关键词最长匹配」把仓库名归到主仓。
+ * @returns {object|null} CENTERS 里的元素；无法归属返回 null
+ */
+function resolveCenter(warehouseName) {
+  if (!warehouseName) return null;
+  for (const item of SORTED_KEYWORDS) {
+    if (warehouseName.includes(item.kw)) return item.center;
+  }
+  return null;
+}
+
+/**
+ * 拉取仓库表并建立「主仓 → wms_co_id 列表」映射。
+ * 缓存 1 小时；仓库表变更不频繁，且新增子仓会自动被关键词捞到。
+ */
+async function loadCenterWarehouseMap(force = false) {
+  const fresh = Date.now() - warehouseCache.at < WAREHOUSE_CACHE_TTL_MS;
+  if (!force && fresh && warehouseCache.rows.length) {
+    return warehouseCache.rows;
+  }
+  // ⚠️ cloudDatabase.query() 直接返回 recordset 数组，不是 {recordset} 对象
+  const rows = (await cloudDatabase.query(
+    `SELECT Id, name, wms_co_id
+       FROM dbo.jst_warehouseInfo`,
+    {},
+    { requestTimeout: 60000 }
+  )) || [];
+  const byCenter = new Map(CENTERS.map((c) => [c.key, []]));
+  const unmatched = [];
+  for (const row of rows) {
+    const center = resolveCenter(String(row.name || ''));
+    if (center && byCenter.has(center.key)) {
+      byCenter.get(center.key).push({
+        wmsCoId: Number(row.wms_co_id),
+        warehouseId: Number(row.Id),
+        name: String(row.name || ''),
+      });
+    } else {
+      unmatched.push({ wmsCoId: Number(row.wms_co_id), name: String(row.name || '') });
+    }
+  }
+  const list = CENTERS.map((c) => ({
+    key: c.key,
+    name: c.name,
+    placeholder: Boolean(c.placeholder),
+    warehouses: byCenter.get(c.key) || [],
+  }));
+  warehouseCache = { at: Date.now(), rows: list, unmatchedCount: unmatched.length };
+  return list;
+}
+
+function clearWarehouseCache() {
+  warehouseCache = { at: 0, rows: [] };
+}
+
+/**
+ * 计算「当前已生效」的核验轮次。
+ *
+ *   12:00 之前  → **未到核验时间，返回 null**。
+ *                 业务明确要求（2026-10-20 确认）：12:00 之前不做核验，
+ *                 前端显示「未到核验时间」，**不要回填昨天的数据** ——
+ *                 昨天已结算的结果留到昨天，拿到今天看容易被当成今天的超时。
+ *   12:00~15:59 → 用 12:00 轮（窗口 00:00~07:00）
+ *   16:00 之后  → 用 16:00 轮（窗口 00:00~16:00，覆盖范围更大）
+ *
+ * @param {Date} now 以**东八区本地时间**为准的 Date（生产/本地机器均为东八区）
+ * @returns {object|null} null 表示当前不在任何核验时段内
+ */
+function resolveActiveRound(now = new Date()) {
+  const hour = now.getHours();
+  const minute = now.getMinutes();
+  const minutes = hour * 60 + minute;
+  let active = null;
+  for (const round of ROUNDS) {
+    if (minutes >= round.cutoffHour * 60) active = round;
+  }
+
+  // 12:00 前：首轮核验还没开始，不做判定
+  if (!active) return null;
+
+  const y = now.getFullYear();
+  const m = pad2(now.getMonth() + 1);
+  const d = pad2(now.getDate());
+  return {
+    ...active,
+    deadline: `${y}-${m}-${d} ${pad2(active.cutoffHour)}:00:00`,
+    windowStart: `${y}-${m}-${d} 00:00:00`,
+    windowEnd: `${y}-${m}-${d} ${pad2(active.windowEndHour)}:00:00`,
+    date: `${y}-${m}-${d}`,
+    settled: false,
+    isPreviousDay: false,
+  };
+}
+
+/**
+ * 取「当天两轮」的完整描述（页面顶部展示用），不论是否已到时间。
+ */
+function describeRounds(now = new Date()) {
+  const y = now.getFullYear();
+  const m = pad2(now.getMonth() + 1);
+  const d = pad2(now.getDate());
+  const date = `${y}-${m}-${d}`;
+  return ROUNDS.map((r) => ({
+    key: r.key,
+    label: r.label,
+    date,
+    deadline: `${date} ${pad2(r.cutoffHour)}:00:00`,
+    windowStart: `${date} 00:00:00`,
+    windowEnd: `${date} ${pad2(r.windowEndHour)}:00:00`,
+    active: now.getHours() * 60 + now.getMinutes() >= r.cutoffHour * 60,
+  }));
+}
+
+module.exports = {
+  CENTERS,
+  ROUNDS,
+  resolveCenter,
+  loadCenterWarehouseMap,
+  clearWarehouseCache,
+  resolveActiveRound,
+  describeRounds,
+  EXCLUDED_STATUS_SQL,
+  toNumber,
+};

backend/src/services/warehouseShipTimelinessService.js

@@ -0,0 +1,528 @@
+'use strict';
+
+/**
+ * 仓储中心 24 小时发货时效 —— 取数/聚合服务（2026-10-20 新增）
+ * ────────────────────────────────────────────────────────────────────────────
+ * 配置与口径定义见 warehouseShipTimelinessRegistry.js（主仓关键词、轮次、时区说明）。
+ *
+ * ── 一次请求做几件事 ──────────────────────────────────────────────────────
+ *   ① 读仓库表 → 主仓 → wms_co_id 集合（缓存 1h）
+ *   ② 一次 SQL 同时取「超时未发」和「已超时已发」两类，按 wms_co_id 分组
+ *   ③ 归并到主仓，返回每仓的 count / orderAmount，以及全量超时明细
+ *
+ * ── SQL 设计要点（踩过的坑）───────────────────────────────────────────────
+ *   · 两张订单表**店铺互斥**，用 UNION ALL 合并后一次性分组，不要分别查再在
+ *     Node 侧合并 —— 两趟扫描在 rpt 视图上代价翻倍。
+ *   · `wms_co_id IN (...)` 直接内联仓库 ID（都是整数，无注入风险），因为仓库
+ *     集合动态生成，用参数化会引入可变数量的 @p0..@pN，反而难维护。
+ *   · **不要在 ORDER BY 里对聚合列做算术**（见 MEMORY：会触发灾难计划）。
+ *     这里 SQL 只 GROUP BY 取原始计数/金额，排序与派生字段全在 Node 侧算。
+ *   · 时间比较一律用**字面量字符串**（形如 '2026-10-20 16:00:00'），由
+ *     resolveActiveRound 在东八区算出；不用 GETDATE() 做相对偏移，避免
+ *     数据库与应用的时区假设不一致。
+ *   · 明细行带 `TOP (@limit)`，`@limit` 走参数化，避免界面一次拉几万行。
+ */
+
+const cloudDatabase = require('../config/cloudDatabase');
+const registry = require('./warehouseShipTimelinessRegistry');
+
+const { CENTERS, EXCLUDED_STATUS_SQL, toNumber } = registry;
+
+// 明细上限：只用于页面展示，超出部分用 truncated 标记提示
+const DEFAULT_DETAIL_LIMIT = 500;
+const MAX_DETAIL_LIMIT = 2000;
+
+/**
+ * 把 UTC Date / 字符串 统一格式化成 'YYYY-MM-DD HH:mm:ss'（按服务器本地时区）。
+ * mssql 驱动默认把 datetime 解析为 UTC 语义的 Date，这里只做展示，统一成
+ * 与库内一致的东八区墙钟时间。
+ */
+function formatDateTime(value) {
+  if (!value) return '';
+  if (typeof value === 'string') return value.replace('T', ' ').slice(0, 19);
+  const d = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(d.getTime())) return '';
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} `
+    + `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+/** 两个 'YYYY-MM-DD HH:mm:ss' 相差多少分钟（四舍五入） */
+function diffMinutes(fromText, toText) {
+  const a = new Date(String(fromText).replace(' ', 'T')).getTime();
+  const b = new Date(String(toText).replace(' ', 'T')).getTime();
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return 0;
+  return Math.round((b - a) / 60000);
+}
+
+/**
+ * 构造两表合并的子查询。
+ *
+ * 🔥 三条必须同时满足（2026-10-20 实测踩坑）：
+ *   ① `order_date >= @windowStart` —— **必须有下界**。只写 `<= @deadline` 会把
+ *      一年前创建、至今未发的历史单全捞进来（实测 13,553 条，最早 2025-09-01）。
+ *   ② `order_date <= @deadline`   —— 上界：截止时刻后创建的订单不参与本轮考核。
+ *   ③ Split 已在 EXCLUDED_STATUS_SQL 里排掉（拆单父单永不发货）。
+ *
+ * @param {number[]} wmsIds 主仓下所有 wms_co_id
+ * @param {string} deadline 截止时刻字面量
+ * @param {'pending'|'shippedLate'} mode 取哪一类
+ */
+function buildUnionSql(wmsIds, deadline, mode) {
+  const idList = wmsIds.join(',');
+  // pending：未发货且窗口内已创建 → 超时未发
+  // shippedLate：已发货但发货时间晚于截止时刻 → 已超时已发
+  const cond = mode === 'pending'
+    ? `o.send_date IS NULL`
+    : `o.send_date IS NOT NULL AND o.send_date > @deadline`;
+  const branch = (table) => `
+        SELECT N'${table}' AS src, o.o_id, o.so_id, o.shop_name, o.shop_id,
+               o.order_date, o.send_date, o.status, o.shop_status,
+               o.wms_co_id, o.pay_amount, o.labels
+          FROM dbo.${table} o
+         WHERE o.wms_co_id IN (${idList})
+           AND o.order_date >= @windowStart
+           AND o.order_date <= @deadline
+           AND ${cond}
+           AND ${EXCLUDED_STATUS_SQL}`;
+  return `${branch('jst_Orders')}
+        UNION ALL${branch('jst_qmcust_orderlist')}`;
+}
+
+/**
+ * 单个主仓的仓库 ID 集合 → 逗号串（用于按主仓分桶时拼 IN 条件）
+ */
+function joinIds(ids) {
+  return ids.join(',');
+}
+
+/**
+ * 主入口：计算某一天、某一轮次的仓储中心发货时效。
+ *
+ * @param {object} options
+ * @param {string} [options.round] 'NOON' | 'AFTERNOON'，不传则按当前时刻自动判定
+ * @param {Date}   [options.now]   仅测试用
+ * @param {number} [options.limit] 明细条数上限
+ * @returns {Promise<object>}
+ */
+async function getShipTimeliness(options = {}) {
+  const now = options.now instanceof Date ? options.now : new Date();
+  const limit = Math.min(
+    Math.max(Number(options.limit) || DEFAULT_DETAIL_LIMIT, 1),
+    MAX_DETAIL_LIMIT
+  );
+
+  // ① 主仓 → 仓库映射
+  const centerList = await registry.loadCenterWarehouseMap();
+  const pad2 = (n) => String(n).padStart(2, '0');
+
+  // ② 决定本轮截止时刻
+  const rounds = registry.describeRounds(now);
+  let round = null;
+  if (options.round) {
+    const target = registry.ROUNDS.find((r) => r.key === String(options.round).toUpperCase());
+    if (!target) {
+      const err = new Error(`未知的核验轮次: ${options.round}`);
+      err.statusCode = 400;
+      throw err;
+    }
+    const pad = (n) => String(n).padStart(2, '0');
+    const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+    round = {
+      ...target,
+      date,
+      deadline: `${date} ${pad(target.cutoffHour)}:00:00`,
+      windowStart: `${date} 00:00:00`,
+      windowEnd: `${date} ${pad(target.windowEndHour)}:00:00`,
+      active: now.getHours() * 60 + now.getMinutes() >= target.cutoffHour * 60,
+    };
+  } else {
+    round = registry.resolveActiveRound(now);
+  }
+
+  // 🔥 12:00 前没有任何轮次生效（业务口径：12:00 才开始第一轮核验）。
+  //    这里**直接返回「未到核验时间」**，既不查库、也不回填昨天 ——
+  //    让业务清楚知道「现在还没到看数据的时候」，而不是拿旧数字去对仓库。
+  if (!round) {
+    const centerList = await registry.loadCenterWarehouseMap();
+    const nextRound = rounds.find((r) => r.cutoffHour === 12) || rounds[0];
+    return {
+      generatedAt: formatDateTime(now),
+      date: `${now.getFullYear()}-${pad2(now.getMonth() + 1)}-${pad2(now.getDate())}`,
+      round: null,
+      notStarted: true,
+      isPreviousDay: false,
+      rounds,
+      nextRoundAt: nextRound ? nextRound.deadline : '',
+      deadline: '',
+      window: null,
+      summary: emptySummary(),
+      centers: buildEmptyCenters(centerList),
+      orders: [],
+      truncated: false,
+      detailLimit: limit,
+      detailDegraded: false,
+      freshness: null,
+      note: '今日 12:00 首轮核验开始后才展示超时数据',
+    };
+  }
+
+  // 没有归属任何主仓的仓库不用查
+  const allWmsIds = [...new Set(
+    centerList.flatMap((c) => c.warehouses.map((w) => w.wmsCoId)).filter((n) => Number.isFinite(n))
+  )];
+
+  if (!allWmsIds.length) {
+    return {
+      generatedAt: formatDateTime(now),
+      date: round.date,
+      round: { key: round.key, label: round.label },
+      isPreviousDay: Boolean(round.isPreviousDay),
+      rounds,
+      deadline: round.deadline,
+      window: { start: round.windowStart, end: round.windowEnd },
+      summary: emptySummary(),
+      centers: buildEmptyCenters(centerList),
+      orders: [],
+      truncated: false,
+      detailLimit: limit,
+      note: '仓库表中未匹配到任何目标主仓，请检查仓库命名',
+    };
+  }
+
+  // ③ 一趟 SQL 取全量分组结果。原实现拆成「超时未发 / 已超时已发 / 窗口总数」
+  //    三条 SQL，在 rpt 视图上三趟全表扫描实测 213 秒；合并成一趟后按
+  //    `src + 是否超时` 打标记再 GROUP BY，只扫一次两表。
+  //
+  // 分组维度：主仓 不直接在 SQL 里 GROUP（仓库→主仓的映射在 Node 侧缓存里），
+  // 所以按 wms_co_id 分组，回 Node 侧累加到主仓。
+  //
+  // 🔥 「算不算已发货」的三态判定（2026-10-20 实测新增）：
+  //   上游 `send_date` 回写**明显滞后** —— 实测 10-20 当天 700 单里只有 100 单
+  //   有 send_date，且都集中在 08:16~08:44（刚回写的那几单）。若只看 send_date，
+  //   中午 12:00 核验时当天早上的单会**全部被判超时**，页面毫无价值。
+  //   因此引入出库表 `rpt.jst_salesOutboundInfo` 作为佐证：
+  //     · 判为「已发」= send_date 有值 **或** 出库表能查到该 o_id
+  //     · 判为「按时」= send_date <= 截止 **或** 出库行 io_date <= 截止
+  //   ⚠️ 出库表同样滞后（每天 04:00 起才有数据，当天往往 0 行，次日凌晨灌），
+  //      所以它只能**减少误判**（把「已发的判成没发」纠正过来），
+  //      不能凭空补出「没发的单已经发了」。最终仍可能有误报，故返回值里带
+  //      `freshness` 让前端明示「数据可能滞后」。
+  // ⚠️ 出库表 `qty` 列全表恒 0（见 MEMORY），判断有无出库**只看行数 / io_date**。
+  //
+  // 每条订单归属哪一类（互斥）：
+  //   pending      —— 两源都查不到发货痕迹 → 超时未发
+  //   shippedLate  —— 有发货痕迹但发货时间 > 截止 → 已发但超时
+  //   onTime       —— 发货时间 <= 截止 → 按时已发
+  // ⚠️ OUTER APPLY 里只取 `io_date`，用「io_date 是否为 NULL」判断出库表有无命中。
+  //    别在外面引用 `ob.o_id` —— APPLY 子查询只 SELECT 了 io_date，引用不存在的列
+  //    会报 `Invalid column name 'o_id'`（2026-10-20 已踩）。
+  //
+  // ⚡ 性能关键（2026-10-20 实测）：
+  //    · 原实现「汇总 SQL + 明细 SQL」各扫一遍窗口，合计 108 秒；
+  //    · 窗口内订单只有几百条（实测 420 条），所以改成**一趟取回全部窗口订单明细**，
+  //      汇总与明细都在 Node 里算 —— 少一次大表扫描。
+  //    · 返回列加上 pay_amount / status，供 Node 侧分桶。
+  //
+  // 🔥🔥 两表**不能 UNION ALL 成一条 SQL**（2026-10-20 实测，这是本文件最大的坑）：
+  //    · `jst_qmcust_orderlist` 是**宽视图**（上百列），拆开单独跑很快，但一旦参与
+  //      UNION ALL + 派生表 + OUTER APPLY 的嵌套，优化器会放弃谓词下推，
+  //      变成先物化整表再过滤 —— 实测单条 SQL 跑 200~320 秒。
+  //    · 两表**分别查、Node 侧合并**：jst_Orders 5.5 秒、jst_qmcust_orderlist 35 秒，
+  //      合计约 40 秒，比合并版快 5~8 倍。
+  //    · 两表店铺完全互斥（京东/拼多多/抖音/得物/唯品会 vs 天猫/淘宝/1688），
+  //      o_id 不会有交集，直接拼接即可，不需要再按 o_id 去重（仍保留一次去重兜底）。
+  //
+  // 🔥 `jst_qmcust_orderlist` 单表也有 35 秒，而同样条件的 `jst_Orders` 只要 2 秒。
+  //    曾尝试把它的窗口过滤换成 `created`（实测快 10 倍），但**已证伪，不能用**：
+  //      · 2026-10-20 实测 2,581 行里，`order_date` 与 `created` 完全相等的只有 4 行，
+  //        相差 >1 小时的有 412 行，最大差 24.7 天，**198 行甚至跨日**；
+  //      · 典型形态：`order_date=10-18 23:58` 而 `created=10-19 04:00:08` ——
+  //        上游每天凌晨 4 点批量补录，`created` 是**灌库时间**不是下单时间；
+  //      · 同一窗口下 `created` 比 `order_date` 多命中 30 单（全是补录单）。
+  //    业务口径是「按**订单创建时间**算是否及时」，只有 `order_date` 是对的。
+  //    所以：**两表都用 `order_date`**，性能只能靠「两表分开查 + Node 侧合并」。
+  // ⚠️ 换回 `created` 之前必须先跑 `.workbuddy/tmp/probe-od-vs-created.cjs` 复测。
+  const windowBranch = (table) => `
+        SELECT N'${table}' AS src,
+               o.wms_co_id, o.o_id, o.so_id, o.shop_name, o.order_date,
+               o.send_date, o.status, o.shop_status, o.pay_amount, o.labels,
+               ob.io_date AS ob_io_date
+          FROM dbo.${table} o
+          OUTER APPLY (
+            SELECT TOP 1 s.io_date
+              FROM dbo.jst_salesOutboundInfo s
+             WHERE s.o_id = o.o_id
+             ORDER BY s.io_date ASC
+          ) ob
+         WHERE o.wms_co_id IN (${joinIds(allWmsIds)})
+           AND o.order_date >= @windowStart
+           AND o.order_date <= @deadline
+           AND ${EXCLUDED_STATUS_SQL}`;
+
+  const params = { deadline: round.deadline, windowStart: round.windowStart };
+  // ⚠️ 超时给足：qmcust 单表实测 35~80 秒（视图谓词下推较差），
+  //    不能按 jst_Orders 的 5 秒去设，否则会被误杀成 500。
+  const queryOpts = { requestTimeout: 300000, connectRequestTimeoutMs: 320000 };
+
+  // 两表并行查（互不依赖），Node 侧合并
+  const [ordersRows, qmcustRows] = await Promise.allSettled([
+    cloudDatabase.query(windowBranch('jst_Orders'), params, queryOpts),
+    cloudDatabase.query(windowBranch('jst_qmcust_orderlist'), params, queryOpts),
+  ]);
+
+  // 🔥 用 allSettled 而不是 all：一张表超时/报错时，另一张表的数据仍然可用，
+  //    否则整页变空白。降级情况记录在 detailDegraded + note 里。
+  const mergeWarnings = [];
+  const windowRows = [];
+  if (ordersRows.status === 'fulfilled') {
+    windowRows.push(...(ordersRows.value || []));
+  } else {
+    mergeWarnings.push(`jst_Orders 查询失败：${ordersRows.reason?.message || '未知错误'}`);
+  }
+  if (qmcustRows.status === 'fulfilled') {
+    windowRows.push(...(qmcustRows.value || []));
+  } else {
+    mergeWarnings.push(`jst_qmcust_orderlist 查询失败：${qmcustRows.reason?.message || '未知错误'}`);
+  }
+  if (!windowRows.length && mergeWarnings.length) {
+    // 两表全挂 —— 这才是真正的失败，直接抛给上层
+    const err = new Error(mergeWarnings.join('；'));
+    err.statusCode = 502;
+    throw err;
+  }
+
+  // ④ 数据新鲜度：出库表最新 io_date。
+  //   ⚠️ 只用于「提示用户数据可能滞后」，不参与超时判定。
+  //   两个源都滞后时（出库表当天 0 行 + send_date 昨天就停了），说明上游还没灌数，
+  //   此时「超时未发」的准确性无法保证 —— 前端必须显式告警，不能让业务拿着
+  //   一份假数据去考核仓库。
+  const freshness = await loadShipFreshness(round);
+
+  // ⑤ 三态归类（在 Node 侧做，SQL 只负责取数）
+  const wmsToCenter = new Map();
+  for (const c of centerList) {
+    for (const w of c.warehouses) wmsToCenter.set(w.wmsCoId, c.key);
+  }
+
+  const acc = new Map(centerList.map((c) => [c.key, {
+    pendingCount: 0,
+    pendingAmount: 0,
+    shippedLateCount: 0,
+    onTimeCount: 0,
+  }]));
+
+  const pendingRows = [];
+  // 两表店铺互斥、o_id 理论不重叠，但历史上出现过同一 o_id 被两边都收录的情况，
+  // 按 `${src}-${o_id}` 去重（跨表同 o_id 也算重复，取先到的 jst_Orders）。
+  const seenKey = new Set();
+  for (const row of windowRows || []) {
+    const bucket = acc.get(wmsToCenter.get(Number(row.wms_co_id)));
+    if (!bucket) continue;
+    const dedupeKey = String(row.o_id || '');
+    if (dedupeKey) {
+      if (seenKey.has(dedupeKey)) continue;
+      seenKey.add(dedupeKey);
+    }
+    const kind = bucketOf(row, round.deadline);
+    if (kind === 'pending') {
+      bucket.pendingCount += 1;
+      bucket.pendingAmount += toNumber(row.pay_amount);
+      pendingRows.push(row);
+    } else if (kind === 'shippedLate') {
+      bucket.shippedLateCount += 1;
+    } else {
+      bucket.onTimeCount += 1;
+    }
+  }
+
+  // 明细：只要「超时未发」，最早创建的最急，排前面
+  // 用 formatDateTime 转成 'YYYY-MM-DD HH:mm:ss' 再比字符串 —— 字典序与时间序一致，
+  // 且不受 mssql 驱动把 datetime 解析成 UTC Date 的影响（见文件头时区说明）。
+  pendingRows.sort((a, b) => {
+    const x = formatDateTime(a.order_date);
+    const y = formatDateTime(b.order_date);
+    if (x < y) return -1;
+    if (x > y) return 1;
+    return 0;
+  });
+  const detailRows = pendingRows.slice(0, limit);
+
+  const centers = centerList.map((c) => {
+    const b = acc.get(c.key) || { pendingCount: 0, pendingAmount: 0, shippedLateCount: 0, onTimeCount: 0 };
+    const totalCount = b.pendingCount + b.shippedLateCount + b.onTimeCount;
+    return {
+      key: c.key,
+      name: c.name,
+      placeholder: c.placeholder,
+      warehouseCount: c.warehouses.length,
+      warehouses: c.warehouses.map((w) => ({ wmsCoId: w.wmsCoId, name: w.name })),
+      // 列表主展示：超时未发
+      overdueUnshipped: b.pendingCount,
+      overdueUnshippedAmount: Math.round(b.pendingAmount * 100) / 100,
+      // 辅助信息
+      overdueShipped: b.shippedLateCount,
+      windowOrderCount: totalCount,
+      onTimeRate: totalCount > 0
+        ? Math.round((b.onTimeCount / totalCount) * 1000) / 10
+        : null,
+    };
+  });
+
+  const orders = (detailRows || []).map((r) => {
+    const orderDate = formatDateTime(r.order_date);
+    const center = centerList.find((c) => c.key === wmsToCenter.get(Number(r.wms_co_id)));
+    const warehouse = center && center.warehouses.find((w) => w.wmsCoId === Number(r.wms_co_id));
+    return {
+      oId: String(r.o_id || ''),
+      soId: String(r.so_id || ''),
+      source: r.src === 'jst_qmcust_orderlist' ? 'qmcust' : 'orders',
+      shopName: String(r.shop_name || ''),
+      orderDate,
+      sendDate: formatDateTime(r.send_date),
+      status: String(r.status || ''),
+      shopStatus: String(r.shop_status || ''),
+      wmsCoId: Number(r.wms_co_id),
+      warehouseName: warehouse ? warehouse.name : '',
+      centerKey: center ? center.key : '',
+      centerName: center ? center.name : '',
+      payAmount: toNumber(r.pay_amount),
+      labels: String(r.labels || ''),
+      // 相对截止时刻的超时时长（分钟）
+      overdueMinutes: diffMinutes(orderDate, round.deadline),
+    };
+  });
+
+  const summary = centers.reduce((acc2, c) => {
+    acc2.overdueUnshipped += c.overdueUnshipped;
+    acc2.overdueShipped += c.overdueShipped;
+    acc2.overdueUnshippedAmount += c.overdueUnshippedAmount;
+    acc2.windowOrderCount += c.windowOrderCount;
+    if (c.overdueUnshipped > 0) acc2.overdueCenterCount += 1;
+    return acc2;
+  }, emptySummary());
+  summary.overdueUnshippedAmount = Math.round(summary.overdueUnshippedAmount * 100) / 100;
+  // 按时率统一口径：按时 = 窗口内总数 - 超时未发 - 已发超时
+  // （与各仓算法完全一致，避免两处各算一遍算出不同数字）
+  summary.onTimeRate = summary.windowOrderCount > 0
+    ? Math.round(((summary.windowOrderCount - summary.overdueUnshipped - summary.overdueShipped)
+      / summary.windowOrderCount) * 1000) / 10
+    : null;
+
+  const totalPending = summary.overdueUnshipped;
+
+  return {
+    generatedAt: formatDateTime(now),
+    date: round.date,
+    // ⚠️ 前端要展示「核验 07:00 / 16:00 前」，必须把 windowEnd 一起带出去。
+    //    早先只回了 key/label，前端拿不到 cutoff，页面就渲染成「核验 前」。
+    round: {
+      key: round.key,
+      label: round.label,
+      cutoffHour: round.cutoffHour,
+      windowEnd: round.windowEnd,
+    },
+    // 12:00 前不会走到这里（见上方 notStarted 分支），留着兼容显式指定 round 的调用
+    notStarted: false,
+    isPreviousDay: false,
+    rounds,
+    deadline: round.deadline,
+    window: { start: round.windowStart, end: round.windowEnd },
+    summary,
+    centers,
+    orders,
+    truncated: totalPending > orders.length,
+    detailLimit: limit,
+    // 任一张订单表查询失败 → 数字不完整，前端要显式告警（不能拿残缺数据考核仓库）
+    detailDegraded: mergeWarnings.length > 0,
+    freshness,
+    note: mergeWarnings.length ? `${mergeWarnings.join('；')}（数据不完整）` : '',
+  };
+}
+
+/**
+ * 计算发货数据新鲜度。
+ *
+ * 🔥 业务上这是**最容易被误判成系统 bug** 的地方（见 MEMORY 入口 1）：
+ *    上游 send_date / 出库表都滞后，「超时未发」数量会虚高。
+ *    这里只如实报告滞后程度，不做任何「猜测补数」。
+ *
+ * @returns {Promise<{outboundMaxIo: string, sendDateMax: string, stale: boolean, hint: string}>}
+ */
+async function loadShipFreshness(round) {
+  try {
+    const rows = await cloudDatabase.query(
+      `SELECT CONVERT(varchar(19), MAX(io_date), 120) AS outbound_max
+         FROM dbo.jst_salesOutboundInfo`,
+      {},
+      { requestTimeout: 60000 }
+    );
+    const outboundMaxIo = rows && rows[0] ? String(rows[0].outbound_max || '') : '';
+    // 出库表最新一行早于今天 → 当天发货数据尚未灌入
+    const outboundStale = !outboundMaxIo || outboundMaxIo.slice(0, 10) < round.date;
+    return {
+      outboundMaxIo,
+      stale: outboundStale,
+      hint: outboundStale
+        ? `出库表最新数据 ${outboundMaxIo || '暂无'}，今天（${round.date}）的发货记录尚未灌入，`
+          + '「超时未发」可能偏多，请以仓库实际发货情况为准'
+        : '',
+    };
+  } catch (e) {
+    // 新鲜度查询失败绝不能影响主结果
+    console.warn('[ShipTimeliness] 取新鲜度失败:', e.message);
+    return { outboundMaxIo: '', stale: true, hint: '发货数据新鲜度未知' };
+  }
+}
+
+/**
+ * 单条订单的三态归类（与服务层口径一一对应）：
+ *   pending      —— send_date 为空 **且** 出库表无命中 → 超时未发
+ *   shippedLate  —— 有发货痕迹但发货时间晚于截止    → 已发但超时
+ *   onTime       —— 发货时间不晚于截止              → 按时已发
+ *
+ * 「发货时间」取值优先级：send_date 有值就用 send_date，否则用出库表 io_date。
+ * （两个都滞后时以 send_date 为准，因为它是订单系统自己的回写，语义最直接。）
+ *
+ * @param {object} row 含 send_date / ob_io_date
+ * @param {string} deadline 'YYYY-MM-DD HH:mm:ss'
+ */
+function bucketOf(row, deadline) {
+  const sendDate = formatDateTime(row.send_date);
+  const ioDate = formatDateTime(row.ob_io_date);
+  if (!sendDate && !ioDate) return 'pending';
+  const shippedAt = sendDate || ioDate;
+  return shippedAt > deadline ? 'shippedLate' : 'onTime';
+}
+
+function emptySummary() {
+  return {
+    overdueUnshipped: 0,
+    overdueShipped: 0,
+    overdueUnshippedAmount: 0,
+    overdueCenterCount: 0,
+    windowOrderCount: 0,
+    onTimeRate: null,
+  };
+}
+
+function buildEmptyCenters(centerList) {
+  return centerList.map((c) => ({
+    key: c.key,
+    name: c.name,
+    placeholder: c.placeholder,
+    warehouseCount: c.warehouses.length,
+    warehouses: c.warehouses.map((w) => ({ wmsCoId: w.wmsCoId, name: w.name })),
+    overdueUnshipped: 0,
+    overdueUnshippedAmount: 0,
+    overdueShipped: 0,
+    windowOrderCount: 0,
+    onTimeRate: null,
+  }));
+}
+
+module.exports = {
+  getShipTimeliness,
+  DEFAULT_DETAIL_LIMIT,
+  MAX_DETAIL_LIMIT,
+};

backend/test/cloudDatabaseConfigCache.test.js

@@ -0,0 +1,126 @@
+/**
+ * 配置负缓存 TTL 回归测试。
+ *
+ * 背景（线上真实故障）：
+ *   隧道抖动 → 系统库（走 SSH 隧道）读取失败 → 旧实现把「空候选」永久缓存下来
+ *   （入口是 `if (cachedCloudConfigCandidates)`，而 [] 在 JS 里是 truthy），
+ *   此后永不重试，直接抛「业务数据库尚未配置」500，**必须重启后端**才能恢复。
+ *
+ * 修复：失败态记为「带 TTL 的负缓存」，到期自动重新解析。
+ * 本文件锁定三条语义：
+ *   ① TTL 内不重复解析（不必每个请求都去撞系统库的慢超时）
+ *   ② TTL 到期后必须重试
+ *   ③ 上游恢复后能自动回到正常态，且成功态不会被 TTL 反复淘汰
+ */
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+// ── 必须在加载被测模块之前完成环境与替身准备 ─────────────────────────────
+// 1) 先清掉业务库环境变量，稳定走「无环境变量兜底」分支（否则 fallbacks 非空，不会报未配置）
+for (const key of Object.keys(process.env)) {
+  if (/^(CLOUD_DB|APP_DB|SQLSERVER)_/u.test(key)) {
+    delete process.env[key];
+  }
+}
+// 2) 再缩短负缓存 TTL —— 必须在上面那次清理之后，否则会被同一前缀规则一并删掉
+process.env.CLOUD_DB_CONFIG_NEGATIVE_TTL_MS = '150';
+
+// 3) 让「系统库读取」可控：替换 mysql2/promise 的 createPool
+const MYSQL_PROMISE_PATH = require.resolve('mysql2/promise');
+const realMysqlPromise = require(MYSQL_PROMISE_PATH);
+
+let systemDbDialAttempts = 0;
+let systemDbMode = 'down'; // down = 模拟隧道断开；recovered = 模拟隧道已恢复
+
+const systemConfigRow = {
+  name: 'cloud_database',
+  host: '127.0.0.1',
+  port: 59999, // 故意指向无人监听的端口，避免测试真去连业务库
+  database_name: 'JSReportReplica',
+  username: 'probe',
+  password: 'probe',
+  ssl: 0,
+  driver: 'mssql',
+  use_env_config: 0,
+  is_default: 1,
+};
+
+require.cache[MYSQL_PROMISE_PATH].exports = Object.assign({}, realMysqlPromise, {
+  createPool: () => {
+    systemDbDialAttempts += 1;
+    return {
+      query: async () => {
+        if (systemDbMode === 'down') {
+          throw Object.assign(new Error('connect ECONNREFUSED 127.0.0.1:13307'), {
+            code: 'ECONNREFUSED',
+          });
+        }
+        return [[systemConfigRow]];
+      },
+      end: async () => {},
+    };
+  },
+});
+
+const cloudDatabase = require('../src/config/cloudDatabase');
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const NOT_CONFIGURED = /业务数据库尚未配置/u;
+
+test('负缓存带 TTL：TTL 内不重复解析，到期后必须重试', async () => {
+  await cloudDatabase.close();
+  const base = systemDbDialAttempts;
+
+  await assert.rejects(
+    () => cloudDatabase.queryWithFreshConnection('SELECT 1 AS x'),
+    NOT_CONFIGURED
+  );
+  assert.equal(systemDbDialAttempts, base + 1, '首次查询应真正尝试解析配置');
+
+  await assert.rejects(
+    () => cloudDatabase.queryWithFreshConnection('SELECT 1 AS x'),
+    NOT_CONFIGURED
+  );
+  assert.equal(systemDbDialAttempts, base + 1, 'TTL 内应命中负缓存，不重复解析');
+
+  await sleep(220);
+  await assert.rejects(
+    () => cloudDatabase.queryWithFreshConnection('SELECT 1 AS x'),
+    NOT_CONFIGURED
+  );
+  assert.equal(
+    systemDbDialAttempts,
+    base + 2,
+    'TTL 到期后必须重试 —— 这正是「隧道恢复后无需重启后端」的关键'
+  );
+});
+
+test('隧道恢复后自动复原：TTL 到期重试能读回配置，且成功态不被 TTL 淘汰', async () => {
+  await sleep(220); // 越过上一轮的负缓存 TTL
+  systemDbMode = 'recovered';
+  const base = systemDbDialAttempts;
+
+  await assert.rejects(
+    () => cloudDatabase.queryWithFreshConnection('SELECT 1 AS x'),
+    (error) => {
+      // 关键断言：不应再是「尚未配置」——说明配置已成功读回，
+      // 失败只是发生在后面连业务库那一层（这里故意指向空端口）。
+      assert.doesNotMatch(
+        error.message,
+        NOT_CONFIGURED,
+        '配置读取应已恢复，不该再报「业务数据库尚未配置」'
+      );
+      return true;
+    }
+  );
+  assert.ok(systemDbDialAttempts > base, '上游恢复后应重新解析配置');
+
+  // 成功态 expiresAt = Infinity：后续查询不得再反复解析系统库
+  const afterRecovery = systemDbDialAttempts;
+  await assert.rejects(() => cloudDatabase.queryWithFreshConnection('SELECT 1 AS x'));
+  assert.equal(
+    systemDbDialAttempts,
+    afterRecovery,
+    '成功态不应被 TTL 反复淘汰（否则每个请求都要多打一次系统库）'
+  );
+});

backend/test/csQualityService.test.js

@@ -1,255 +0,0 @@
-'use strict';
-
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const {
-  QWEN_PROVIDER,
-  AGNES_PROVIDER,
-  DEFAULT_QWEN_BASE_URL,
-  DEFAULT_QWEN_MODEL,
-  DEFAULT_AGNES_BASE_URL,
-  DEFAULT_AGNES_MODEL,
-  _test: {
-    resolveAiConfig,
-    buildAiRequestPayload,
-    parseModelJson,
-    mapChatDataMeta,
-    aggregateChatDimensionRows,
-    createChatBatches,
-    normalizeAnalysis,
-    mergeBatchAnalysesLocally,
-    reconcileMergedAnalysis,
-    sumUsages,
-    getAiErrorDetail,
-    isRetryableAiError,
-    getAiRetryDelayMs,
-    sanitizePublicError,
-  },
-} = require('../src/services/csQualityService');
-
-test('chat data metadata exposes the actual available date range', () => {
-  assert.deepEqual(mapChatDataMeta({
-    minDate: '2026-06-22',
-    latestDate: '2026-07-31 23:59:59',
-    messageCount: '792771',
-  }), {
-    tableName: 'rpt.pdd_GoodsChatMessages',
-    minDate: '2026-06-22',
-    latestDate: '2026-07-31',
-    messageCount: 792771,
-  });
-});
-
-function message(uid, content, index = 1) {
-  return {
-    uid,
-    nickname: `买家-${uid}`,
-    msgId: `${uid}-${index}`,
-    msgTime: `2026-07-30 10:00:${String(index).padStart(2, '0')}`,
-    directionLabel: '买家',
-    csname: '客服A',
-    content,
-  };
-}
-
-function result(overrides = {}) {
-  return {
-    consultation_type: '售前',
-    primary_reason: '产品问题',
-    secondary_reason: '尺寸问题',
-    occurrence_count: 1,
-    affected_customer_count: 1,
-    affected_conversation_ids: ['u1'],
-    buyer_intent: '咨询尺寸',
-    evidence: [{ conversation_id: 'u1', nickname: '买家-u1', message_time: '2026-07-30 10:00:01', text: '多高' }],
-    image_urls: [],
-    product_improvement_areas: ['详情页'],
-    improvement_suggestion: '补充尺寸图',
-    confidence: 0.9,
-    ...overrides,
-  };
-}
-
-test('customer-service quality defaults to the verified Qwen model and endpoint', () => {
-  const config = resolveAiConfig({ apiKey: 'test-key' });
-  assert.equal(QWEN_PROVIDER, 'aliyun-model-studio');
-  assert.equal(config.provider, QWEN_PROVIDER);
-  assert.equal(config.baseUrl, DEFAULT_QWEN_BASE_URL);
-  assert.equal(config.model, DEFAULT_QWEN_MODEL);
-  assert.equal(config.batchConcurrency, 2);
-  assert.equal(config.batchMaxChars, 45000);
-  assert.equal(config.mergeMaxBatches, 8);
-  assert.equal(config.requestRetryCount, 2);
-  assert.equal(config.retryBaseDelayMs, 1500);
-});
-
-test('customer-service quality resolves the Agnes China endpoint and request format', () => {
-  const config = resolveAiConfig({
-    provider: AGNES_PROVIDER,
-    apiKey: 'test-key',
-  });
-  assert.equal(config.provider, AGNES_PROVIDER);
-  assert.equal(config.baseUrl, DEFAULT_AGNES_BASE_URL);
-  assert.equal(config.model, DEFAULT_AGNES_MODEL);
-  assert.equal(config.timeoutMs, 600000);
-
-  const payload = buildAiRequestPayload(config, [{ role: 'user', content: 'test' }], 2048);
-  assert.equal(payload.model, DEFAULT_AGNES_MODEL);
-  assert.equal(payload.max_tokens, 2048);
-  assert.equal(payload.temperature, 0);
-  assert.equal(payload.stream, false);
-  assert.equal('max_completion_tokens' in payload, false);
-  assert.equal('response_format' in payload, false);
-});
-
-test('Qwen requests retain the provider-specific JSON parameters', () => {
-  const config = resolveAiConfig({ apiKey: 'test-key' });
-  const payload = buildAiRequestPayload(config, [{ role: 'user', content: 'test' }], 2048);
-  assert.equal(payload.max_completion_tokens, 2048);
-  assert.deepEqual(payload.response_format, { type: 'json_object' });
-  assert.equal(payload.enable_thinking, false);
-  assert.equal('max_tokens' in payload, false);
-});
-
-test('chat batching keeps every customer conversation intact', () => {
-  const rows = [
-    message('u1', '甲'.repeat(700), 1),
-    message('u1', '乙'.repeat(700), 2),
-    message('u2', '丙'.repeat(700), 1),
-    message('u3', '丁'.repeat(700), 1),
-  ];
-  const batches = createChatBatches(rows, 1300);
-
-  assert.equal(batches.length, 3);
-  assert.deepEqual(batches[0].conversationIds, ['u1']);
-  assert.equal(batches[0].messageCount, 2);
-  assert.ok(batches.every((batch) => !(
-    batch.conversationIds.includes('u1') && batch.conversationIds.length > 1
-  )));
-  assert.deepEqual(batches.flatMap((batch) => batch.conversationIds), ['u1', 'u2', 'u3']);
-  assert.equal(batches[0].startDate, '2026-07-30');
-  assert.equal(batches[0].endDate, '2026-07-30');
-});
-
-test('chat dimension snapshot derives goods and customers in one aggregation', () => {
-  const snapshot = aggregateChatDimensionRows([
-    {
-      goodsId: 'g1', uid: 'u1', csname: '客服A', goodsName: '商品1', shopName: '店铺1',
-      nickname: '客户1', messageCount: 2, firstMsgTime: '2026-07-29T08:00:00.000Z', lastMsgTime: '2026-07-29T08:01:00.000Z',
-    },
-    {
-      goodsId: 'g1', uid: 'u1', csname: '客服B', goodsName: '商品1', shopName: '店铺1',
-      nickname: '客户1', messageCount: 3, firstMsgTime: '2026-07-29T08:02:00.000Z', lastMsgTime: '2026-07-29T08:04:00.000Z',
-    },
-    {
-      goodsId: 'g1', uid: 'u2', csname: '客服A', goodsName: '商品1', shopName: '店铺1',
-      nickname: '客户2', messageCount: 1, firstMsgTime: '2026-07-29T09:00:00.000Z', lastMsgTime: '2026-07-29T09:00:00.000Z',
-    },
-    {
-      goodsId: 'g2', uid: 'u3', csname: '客服C', goodsName: '商品2', shopName: '店铺2',
-      nickname: '客户3', messageCount: 4, firstMsgTime: '2026-07-29T10:00:00.000Z', lastMsgTime: '2026-07-29T10:03:00.000Z',
-    },
-  ]);
-
-  assert.equal(snapshot.goodsRows.length, 2);
-  assert.equal(snapshot.goodsRows[0].goodsId, 'g1');
-  assert.equal(snapshot.goodsRows[0].messageCount, 6);
-  assert.equal(snapshot.goodsRows[0].userCount, 2);
-  assert.equal(snapshot.goodsRows[0].csCount, 2);
-  assert.equal(snapshot.customersByGoods.g1.length, 2);
-  assert.equal(snapshot.customersByGoods.g1[0].uid, 'u1');
-  assert.equal(snapshot.customersByGoods.g1[0].messageCount, 5);
-  assert.equal(snapshot.customersByGoods.g1[0].csname, '客服B');
-  assert.equal(snapshot.customersByGoods.g1[0].firstMsgTime, '2026-07-29T08:00:00.000Z');
-  assert.equal(snapshot.customersByGoods.g1[0].lastMsgTime, '2026-07-29T08:04:00.000Z');
-});
-
-test('local merge sums disjoint batch counts and deduplicates evidence', () => {
-  const analyses = [
-    {
-      summary: { pre_sale_conversation_count: 1, after_sale_conversation_count: 0, mixed_conversation_count: 0, main_findings: ['尺寸咨询较多'] },
-      results: [result()],
-    },
-    {
-      summary: { pre_sale_conversation_count: 2, after_sale_conversation_count: 0, mixed_conversation_count: 0, main_findings: ['尺寸咨询较多'] },
-      results: [result({
-        occurrence_count: 3,
-        affected_customer_count: 2,
-        affected_conversation_ids: ['u1', 'u2'],
-        evidence: [
-          { conversation_id: 'u1', nickname: '买家-u1', message_time: '2026-07-30 10:00:01', text: '多高' },
-          { conversation_id: 'u2', nickname: '买家-u2', message_time: '2026-07-30 10:00:02', text: '多宽' },
-        ],
-      })],
-    },
-  ];
-  const merged = mergeBatchAnalysesLocally(analyses, { customerCount: 3, messageCount: 12 });
-
-  assert.equal(merged.results.length, 1);
-  assert.equal(merged.results[0].occurrence_count, 4);
-  assert.equal(merged.results[0].affected_customer_count, 3);
-  assert.deepEqual(merged.results[0].affected_conversation_ids, ['u1', 'u2']);
-  assert.equal(merged.results[0].evidence.length, 2);
-  assert.equal(merged.summary.conversation_count, 3);
-  assert.equal(merged.summary.pre_sale_conversation_count, 3);
-  assert.deepEqual(merged.summary.main_findings, ['尺寸咨询较多']);
-});
-
-test('model merge cannot change deterministic counts or drop a label group', () => {
-  const local = mergeBatchAnalysesLocally([{
-    summary: { pre_sale_conversation_count: 2, after_sale_conversation_count: 0, mixed_conversation_count: 0, main_findings: [] },
-    results: [result({ occurrence_count: 4, affected_customer_count: 2 })],
-  }], { customerCount: 2, messageCount: 8 });
-  const model = {
-    schema_version: '1.0',
-    conversation_type: '售前',
-    summary: { conversation_count: 99, pre_sale_conversation_count: 99, after_sale_conversation_count: 0, mixed_conversation_count: 0, main_findings: ['优化后的结论'] },
-    results: [result({ occurrence_count: 99, affected_customer_count: 99, buyer_intent: '优化后的诉求' })],
-  };
-  const reconciled = reconcileMergedAnalysis(model, local, { customerCount: 2, messageCount: 8 });
-
-  assert.equal(reconciled.results[0].occurrence_count, 4);
-  assert.equal(reconciled.results[0].affected_customer_count, 2);
-  assert.equal(reconciled.results[0].buyer_intent, '优化后的诉求');
-  assert.deepEqual(reconciled.results[0].affected_conversation_ids, ['u1']);
-  assert.equal(reconciled.summary.conversation_count, 2);
-  assert.equal(reconciled.summary.pre_sale_conversation_count, 2);
-});
-
-test('analysis normalization keeps every valid affected conversation id', () => {
-  const normalized = normalizeAnalysis({
-    summary: {},
-    results: [{
-      consultation_type: '售前',
-      primary_reason: '产品问题',
-      secondary_reason: '尺寸问题',
-      occurrence_count: 3,
-      affected_customer_count: 3,
-      affected_conversation_ids: ['u1', 'u2', 'not-in-batch'],
-      evidence: [{ conversation_id: 'u3', text: '尺寸是多少' }],
-    }],
-  }, { customerCount: 3, messageCount: 10 }, {
-    allowedConversationIds: ['u1', 'u2', 'u3'],
-  });
-
-  assert.deepEqual(normalized.results[0].affected_conversation_ids, ['u1', 'u2', 'u3']);
-  assert.equal(normalized.results[0].affected_customer_count, 3);
-});
-
-test('Qwen JSON parsing, usage aggregation and error extraction are provider-safe', () => {
-  assert.deepEqual(parseModelJson('```json\n{"ok":true}\n```'), { ok: true });
-  assert.deepEqual(sumUsages([
-    { prompt_tokens: 10, completion_tokens: 3, total_tokens: 13 },
-    { input_tokens: 7, output_tokens: 2 },
-  ]), { prompt_tokens: 17, completion_tokens: 5, total_tokens: 22 });
-  assert.equal(getAiErrorDetail({ response: { data: { error: { message: 'rate limited' } } } }), 'rate limited');
-  assert.equal(getAiErrorDetail({ message: 'Bearer sk-secret-example-1234567890 failed' }), 'Bearer [redacted] failed');
-  assert.equal(isRetryableAiError({ code: 'ETIMEDOUT' }), true);
-  assert.equal(isRetryableAiError({ response: { status: 429 } }), true);
-  assert.equal(isRetryableAiError({ response: { status: 401 } }), false);
-  assert.equal(getAiRetryDelayMs({}, 1, 1500), 1500);
-  assert.equal(getAiRetryDelayMs({}, 2, 1500), 3000);
-  assert.equal(getAiRetryDelayMs({ response: { headers: { 'retry-after': '2' } } }, 1, 1500), 2000);
-  assert.equal(sanitizePublicError('千问模型请求失败：qwen-timeout'), 'AI服务请求失败：AI服务');
-  assert.equal(sanitizePublicError('https://apihub.agnes-ai.com/v1 failed'), 'https://AI服务/v1 failed');
-});

backend/test/dailyInventoryFlows.test.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  AVAILABLE_FLOW_FIELDS,
+  buildInClause,
+  fetchFlows,
+} = require('../src/services/dailyInventoryFlows');
+const { deriveAndStoreOpeningSnapshot } = require('../src/services/dailyInventoryOpening');
+
+const BASELINE = [
+  { warehouse: '仓A主仓', dbWarehouse: '仓A', wmsCoId: 101 },
+  { warehouse: '仓B主仓', dbWarehouse: '仓B', wmsCoId: 102 },
+  { warehouse: '仓C主仓', dbWarehouse: null, wmsCoId: 103 },
+];
+
+/** 构造一个按 SQL 关键字路由的假业务库 */
+function fakeCloudDb(handler) {
+  return { query: async (sql, params) => handler(String(sql), params || {}) };
+}
+
+test('buildInClause 展开参数且不为 async', () => {
+  const { clause, params } = buildInClause([1, 2], 'w');
+  assert.equal(clause, '@w0,@w1');
+  assert.deepEqual(params, { w0: 1, w1: 2 });
+});
+
+test('fetchFlows 查询四类单据并按符号约定返回（流入正、流出负）', async () => {
+  const seen = [];
+  const db = fakeCloudDb((sql, params) => {
+    seen.push(sql);
+    if (sql.includes('jst_purchaseItem')) return [{ wmsCoId: 101, qty: '100' }];
+    if (sql.includes('jst_purchaseoutItem')) return [{ wmsCoId: 101, qty: '30' }];
+    if (sql.includes('jst_OrderItem')) return [{ wmsCoId: 101, qty: '50' }];
+    if (sql.includes('jst_returnAndRefundItem')) return [{ wmsCoId: 101, qty: '8' }];
+    return [];
+  });
+  const map = await fetchFlows(db, [101, 102], '2026-09-26 01:00:00');
+  const f = map.get('101');
+  assert.equal(f.purchaseIn, 100, '采购进仓为流入正数');
+  assert.equal(f.purchaseReturn, -30, '采购退货为流出负数');
+  assert.equal(f.salesOut, -50, '销售出仓为流出负数');
+  assert.equal(f.salesReturn, 8, '销售退货为流入正数');
+  assert.equal(seen.length, 4, '应发出 4 条单据查询');
+  assert.ok(seen.every((s) => s.includes('@from')), '每条查询都带 @from 参数');
+  assert.deepEqual(AVAILABLE_FLOW_FIELDS.sort(), ['purchaseIn', 'purchaseReturn', 'salesOut', 'salesReturn']);
+});
+
+test('fetchFlows 空仓库列表直接返回空 Map', async () => {
+  const map = await fetchFlows(fakeCloudDb(() => []), [], '2026-09-26 01:00:00');
+  assert.equal(map.size, 0);
+});
+
+test('deriveAndStoreOpeningSnapshot：全部仓库用实时库存扣流水回推，并保留基线仓库名', async () => {
+  const upserts = [];
+  const cloudDb = fakeCloudDb((sql, params) => {
+    if (sql.includes('jst_inventoryInfo')) {
+      return [
+        { wmsCoId: 101, qty: '520', skuCount: '13' },
+        { wmsCoId: 102, qty: '300', skuCount: '9' },
+        { wmsCoId: 103, qty: '10', skuCount: '2' },
+      ];
+    }
+    if (sql.includes('jst_purchaseItem')) return [{ wmsCoId: 102, qty: '60' }];
+    if (sql.includes('jst_purchaseoutItem')) return [{ wmsCoId: 102, qty: '10' }];
+    if (sql.includes('jst_OrderItem')) return [{ wmsCoId: 102, qty: '40' }];
+    if (sql.includes('jst_returnAndRefundItem')) return [];
+    return [];
+  });
+  const snapshotDb = {
+    async upsertSnapshot(bizDate, rows) {
+      upserts.push({ bizDate, rows });
+      return rows.length;
+    },
+  };
+
+  const result = await deriveAndStoreOpeningSnapshot({
+    cloudDb,
+    snapshotDb,
+    baseline: BASELINE,
+    openingDate: '2026-09-25',
+    latestBizDate: '2026-09-26',
+    takenAt: null,
+  });
+
+  assert.equal(result.count, 3);
+  assert.equal(result.derivedCount, 3);
+  assert.equal(upserts.length, 1);
+  assert.equal(upserts[0].bizDate, '2026-09-25');
+
+  const byWh = new Map(upserts[0].rows.map((r) => [r.wmsCoId, r]));
+  // 仓A：无流水 → 等于实时库存 520
+  assert.equal(byWh.get(101).closingQty, 520);
+  // 仓B：300 − 净流入(60 − 10 − 40) = 300 − 10 = 290
+  assert.equal(byWh.get(102).closingQty, 290);
+  // 仓C：无流水 → 等于实时库存 10
+  assert.equal(byWh.get(103).closingQty, 10);
+  // 带回基线仓库名，保证后续按 wmsCoId 读取正确
+  assert.equal(byWh.get(102).warehouse, '仓B主仓');
+  assert.equal(byWh.get(102).dbWarehouse, '仓B');
+});
+
+test('fetchFlows 缺少数据库实例参数时立即抛错（防静默空结果）', async () => {
+  await assert.rejects(
+    () => fetchFlows([101, 102], '2026-09-26 01:00:00'),
+    /第一个参数必须是数据库实例/
+  );
+});

backend/test/dailyInventoryNotification.test.js

@@ -0,0 +1,333 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  DEFAULT_NOTIFY_TIME,
+  MAX_RECIPIENTS,
+  buildIdempotencyKey,
+  normalizeFlag,
+  normalizeNotifyTime,
+  normalizeRecipients,
+} = require('../src/services/dailyInventoryNotificationSettings');
+const {
+  ACTION_TITLE,
+  NOTIFICATION_TITLE,
+  buildNotificationContent,
+  minutesOfDay,
+  resolveBizDate,
+  withRetry,
+} = require('../src/jobs/dailyInventoryNotificationJob');
+const {
+  buildScreenshotNames,
+  chinaTimeParts,
+} = require('../src/services/dailyInventoryScreenshot');
+
+// ── 收件人名单规范化 ────────────────────────────────────────────
+test('normalizeRecipients 去空值、去空白、保持顺序', () => {
+  assert.deepEqual(normalizeRecipients(['张三', '  ', '李四', '', null, undefined]), ['张三', '李四']);
+});
+
+test('normalizeRecipients 去重且忽略首尾空格', () => {
+  assert.deepEqual(normalizeRecipients([' 张三 ', '张三', '李四', ' 李四']), ['张三', '李四']);
+});
+
+test('normalizeRecipients 支持逗号/中文逗号/分号/换行分隔的字符串', () => {
+  assert.deepEqual(
+    normalizeRecipients('张三,李四，王五;赵六\n孙七'),
+    ['张三', '李四', '王五', '赵六', '孙七']
+  );
+});
+
+test('normalizeRecipients 对非法输入返回空数组', () => {
+  assert.deepEqual(normalizeRecipients(null), []);
+  assert.deepEqual(normalizeRecipients(undefined), []);
+  assert.deepEqual(normalizeRecipients(12345), []);
+});
+
+test('normalizeRecipients 超量时截断到上限', () => {
+  const list = Array.from({ length: MAX_RECIPIENTS + 5 }, (_, i) => `用户${i}`);
+  const result = normalizeRecipients(list);
+  assert.equal(result.length, MAX_RECIPIENTS);
+  assert.equal(result[0], '用户0');
+});
+
+// ── 通知时间校验 ────────────────────────────────────────────────
+test('normalizeNotifyTime 接受合法 HH:mm 并补零', () => {
+  assert.equal(normalizeNotifyTime('1:05'), '01:05');
+  assert.equal(normalizeNotifyTime('23:59'), '23:59');
+  assert.equal(normalizeNotifyTime('00:00'), '00:00');
+});
+
+test('normalizeNotifyTime 支持 HH:mm:ss 并截断到分钟', () => {
+  assert.equal(normalizeNotifyTime('01:00:30'), '01:00');
+});
+
+test('normalizeNotifyTime 非法值回退默认 01:00', () => {
+  assert.equal(normalizeNotifyTime('24:00'), DEFAULT_NOTIFY_TIME);
+  assert.equal(normalizeNotifyTime('12:60'), DEFAULT_NOTIFY_TIME);
+  assert.equal(normalizeNotifyTime('abc'), DEFAULT_NOTIFY_TIME);
+  assert.equal(normalizeNotifyTime(''), DEFAULT_NOTIFY_TIME);
+  assert.equal(normalizeNotifyTime(null), DEFAULT_NOTIFY_TIME);
+});
+
+test('normalizeFlag 只接受明确的布尔语义，未知值回退默认', () => {
+  assert.equal(normalizeFlag('true', false), true);
+  assert.equal(normalizeFlag('off', true), false);
+  assert.equal(normalizeFlag('maybe', true), true);
+  assert.equal(normalizeFlag(null, false), false);
+});
+
+// ── 幂等键 ──────────────────────────────────────────────────────
+test('buildIdempotencyKey 正式推送按业务日期+收件人稳定生成', () => {
+  const a = buildIdempotencyKey({ bizDate: '2026-09-25', recipient: '张三', mode: 'scheduled' });
+  const b = buildIdempotencyKey({ bizDate: '2026-09-25', recipient: '张三', mode: 'scheduled' });
+  const c = buildIdempotencyKey({ bizDate: '2026-09-25', recipient: '李四', mode: 'scheduled' });
+  assert.equal(a, b);
+  assert.notEqual(a, c);
+});
+
+test('buildIdempotencyKey 测试推送带随机数，不占用正式幂等记录', () => {
+  const formal = buildIdempotencyKey({ bizDate: '2026-09-25', recipient: '张三', mode: 'scheduled' });
+  const t1 = buildIdempotencyKey({ bizDate: '2026-09-25', recipient: '张三', mode: 'test', nonce: 'n1' });
+  const t2 = buildIdempotencyKey({ bizDate: '2026-09-25', recipient: '张三', mode: 'test', nonce: 'n2' });
+  assert.notEqual(t1, t2);
+  assert.notEqual(t1, formal);
+});
+
+// ── 通知正文 ────────────────────────────────────────────────────
+test('buildNotificationContent 包含数据日期、生成时间、图片地址与页面链接', () => {
+  const content = buildNotificationContent({
+    bizDate: '2026-09-25',
+    takenAt: '2026/09/25 01:00:00',
+    imageUrl: 'https://cdn.example.com/daily-inventory/2026-09-25/daily-inventory-20260925-010000.png',
+    pageUrl: 'https://ck.yydd.ai/planning/operation/daily-inventory',
+  });
+  assert.match(content, /2026-09-25/);
+  assert.match(content, /2026\/09\/25 01:00:00/);
+  assert.match(content, /https:\/\/cdn\.example\.com\//);
+  assert.match(content, /https:\/\/ck\.yydd\.ai\/planning\/operation\/daily-inventory/);
+  assert.match(content, new RegExp(ACTION_TITLE));
+  assert.equal(NOTIFICATION_TITLE, '每日进销存数据');
+});
+
+// ── 业务日期与调度时刻 ──────────────────────────────────────────
+test('resolveBizDate 取北京时间昨日（与页面 T-1 口径一致）', () => {
+  assert.equal(resolveBizDate(new Date('2026-09-25T01:00:00+08:00')), '2026-09-24');
+  assert.equal(resolveBizDate(new Date('2026-09-25T23:30:00+08:00')), '2026-09-24');
+});
+
+test('minutesOfDay 正确换算，非法值返回 null', () => {
+  assert.equal(minutesOfDay('00:00'), 0);
+  assert.equal(minutesOfDay('01:00'), 60);
+  assert.equal(minutesOfDay('23:59'), 1439);
+  assert.equal(minutesOfDay('24:00'), null);
+  assert.equal(minutesOfDay('abc'), null);
+  assert.equal(minutesOfDay(null), null);
+});
+
+test('chinaTimeParts 生成对象键所需的日期与时间片段', () => {
+  const parts = chinaTimeParts(new Date('2026-09-25T01:00:00+08:00'));
+  assert.equal(parts.bizDate, '2026-09-25');
+  assert.equal(parts.dateKey, '20260925');
+  assert.equal(parts.timeKey, '010000');
+  assert.equal(
+    `daily-inventory/${parts.bizDate}/daily-inventory-${parts.dateKey}-${parts.timeKey}.png`,
+    'daily-inventory/2026-09-25/daily-inventory-20260925-010000.png'
+  );
+});
+
+test('buildScreenshotNames 用业务日期归档目录与文件名，时间取执行时刻', () => {
+  const names = buildScreenshotNames({ bizDate: '2026-09-25', timeKey: '010000' });
+  assert.equal(names.fileName, 'daily-inventory-20260925-010000.png');
+  assert.equal(
+    names.objectKey,
+    'daily-inventory/2026-09-25/daily-inventory-20260925-010000.png'
+  );
+});
+
+test('buildScreenshotNames 业务日期与执行日期不同时以业务日期为准', () => {
+  // 凌晨 01:00 推送的是「昨日」数据，归档必须落在业务日而不是执行日
+  const names = buildScreenshotNames({ bizDate: '2026-09-25', timeKey: '010000' });
+  assert.ok(!names.objectKey.includes('2026-09-26'));
+  assert.ok(names.objectKey.startsWith('daily-inventory/2026-09-25/'));
+});
+
+test('buildScreenshotNames 业务日期缺失时回退空目录占位而不抛错', () => {
+  const names = buildScreenshotNames({ bizDate: '', timeKey: '010000' });
+  assert.equal(names.fileName, 'daily-inventory--010000.png');
+});
+
+// ── 幂等记录：同一业务日期 + 同一用户只成功通知一次 ────────────
+async function withStubbedState(runner) {
+  const database = require('../src/config/database');
+  const settings = require('../src/services/dailyInventoryNotificationSettings');
+  const original = database.local;
+  const store = new Map();
+
+  database.local = {
+    async query(sql, params) {
+      const text = String(sql);
+      if (text.startsWith('SELECT config_value')) {
+        const value = store.get(params[0]);
+        return value === undefined ? [] : [{ configValue: value }];
+      }
+      if (text.startsWith('SELECT id FROM system_config')) {
+        const value = store.get(params[0]);
+        return value === undefined ? [] : [{ id: 1 }];
+      }
+      // UPDATE system_config SET config_value = ? ...
+      store.set(params[params.length - 1], params[0]);
+      return { affectedRows: 1 };
+    },
+    async insert(_table, data) {
+      store.set(data.config_key, data.config_value);
+      return { insertId: 1 };
+    },
+  };
+
+  try {
+    return await runner(settings);
+  } finally {
+    database.local = original;
+  }
+}
+
+test('markNotified 后同一业务日期同一用户命中幂等，跨日期互不影响', async () => {
+  await withStubbedState(async (settings) => {
+    assert.equal(await settings.hasNotified('2026-09-25', '苏适'), false);
+    await settings.markNotified('2026-09-25', '苏适', { deliveryId: 'd-1' });
+    assert.equal(await settings.hasNotified('2026-09-25', '苏适'), true);
+    // 同一天其他用户不受影响
+    assert.equal(await settings.hasNotified('2026-09-25', '李四'), false);
+    // 同一用户换一天应当重新通知
+    assert.equal(await settings.hasNotified('2026-09-26', '苏适'), false);
+  });
+});
+
+test('appendRunRecord 保留执行时间、截图地址、通知对象与失败原因', async () => {
+  await withStubbedState(async (settings) => {
+    await settings.appendRunRecord({
+      runAt: '2026-09-25T01:00:00.000Z',
+      bizDate: '2026-09-25',
+      mode: 'scheduled',
+      success: false,
+      error: '所有收件人均通知失败',
+      screenshotUrl: 'https://scqny.jiansun.vip/daily-inventory/2026-09-25/x.png',
+      recipients: [{ recipient: '苏适', status: 'failed', error: '通知中心 502' }],
+    });
+    const runs = await settings.listRunRecords(5);
+    assert.equal(runs.length, 1);
+    assert.equal(runs[0].bizDate, '2026-09-25');
+    assert.equal(runs[0].success, false);
+    assert.equal(runs[0].error, '所有收件人均通知失败');
+    assert.equal(runs[0].recipients[0].recipient, '苏适');
+    assert.ok(runs[0].screenshotUrl.startsWith('https://'));
+  });
+});
+
+// ── 重试与退避 ──────────────────────────────────────────────────
+test('withRetry 第二次成功后返回结果', async () => {
+  let calls = 0;
+  const result = await withRetry(
+    async () => {
+      calls += 1;
+      if (calls < 2) throw new Error('临时失败');
+      return 'ok';
+    },
+    { label: '单元测试', attempts: 3, baseDelayMs: 1 }
+  );
+  assert.equal(result, 'ok');
+  assert.equal(calls, 2);
+});
+
+test('withRetry 超过次数后抛出最后一次错误', async () => {
+  let calls = 0;
+  await assert.rejects(
+    withRetry(
+      async () => {
+        calls += 1;
+        throw new Error(`失败${calls}`);
+      },
+      { label: '单元测试', attempts: 3, baseDelayMs: 1 }
+    ),
+    /失败3/
+  );
+  assert.equal(calls, 3);
+});
+
+// ── 截图身份：必须使用系统库中真实存在的服务账号 ──────────────
+test('ensureScreenshotServiceUser 账号不存在时创建，存在时复用 id', async () => {
+  const database = require('../src/config/database');
+  const screenshot = require('../src/services/dailyInventoryScreenshot');
+  const original = database.local;
+  const calls = { select: 0, insert: 0, update: 0 };
+  let existing = null;
+
+  database.local = {
+    async query(sql, params) {
+      if (String(sql).startsWith('SELECT id, role, status FROM users')) {
+        calls.select += 1;
+        return existing ? [existing] : [];
+      }
+      calls.update += 1;
+      return { affectedRows: 1 };
+    },
+    async insert(_table, data) {
+      calls.insert += 1;
+      assert.equal(data.role, 'admin');
+      assert.equal(data.status, 'active');
+      assert.equal(data.auth_source, 'service');
+      assert.ok(String(data.password_hash || '').length > 20, '密码哈希不能为空');
+      existing = { id: 4242, role: data.role, status: data.status };
+      return { insertId: 4242 };
+    },
+  };
+
+  try {
+    screenshot.resetScreenshotServiceUserCache();
+    const created = await screenshot.ensureScreenshotServiceUser();
+    assert.equal(created, 4242);
+    assert.equal(calls.insert, 1);
+    assert.equal(calls.select, 1);
+
+    // 第二次调用命中缓存，不再查库
+    assert.equal(await screenshot.ensureScreenshotServiceUser(), 4242);
+    assert.equal(calls.select, 1);
+  } finally {
+    database.local = original;
+    screenshot.resetScreenshotServiceUserCache();
+  }
+});
+
+test('signScreenshotToken 的 sub 指向服务账号 id 且通过签名校验', async () => {
+  const database = require('../src/config/database');
+  const screenshot = require('../src/services/dailyInventoryScreenshot');
+  const jwt = require('jsonwebtoken');
+  const original = database.local;
+  const originalSecret = process.env.CUBEJS_SECRET;
+  process.env.CUBEJS_SECRET = originalSecret || 'test-secret-for-unit';
+
+  database.local = {
+    async query() {
+      return [{ id: 99, role: 'admin', status: 'active' }];
+    },
+    async insert() {
+      throw new Error('不应在账号已存在时插入');
+    },
+  };
+
+  try {
+    screenshot.resetScreenshotServiceUserCache();
+    const token = await screenshot.signScreenshotToken();
+    const payload = jwt.verify(token, process.env.CUBEJS_SECRET || 'test-secret');
+    assert.equal(payload.sub, '99');
+    assert.equal(payload.role, 'admin');
+    assert.equal(payload.authSource, 'service');
+  } finally {
+    database.local = original;
+    process.env.CUBEJS_SECRET = originalSecret;
+    screenshot.resetScreenshotServiceUserCache();
+  }
+});

backend/test/dailyInventoryOfficial.test.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const XLSX = require('xlsx');
+
+const {
+  normalizeRecords,
+  parseWorkbook,
+  checkBalance,
+} = require('../src/services/dailyInventoryOfficial');
+
+const RECORDS = [
+  {
+    一级功能按键: '大货库存监控',
+    二级功能按键: '每日进销存',
+    仓库: '简尚-崔桥工厂仓主仓',
+    期初数量: 90811,
+    加工进仓: 0,
+    采购退货: 0,
+    采购进仓: 0,
+    其它进仓: 0,
+    其它退货: 0,
+    销售出仓: -3252,
+    盘点: 0,
+    加工出仓: 0,
+    调拨出: -881,
+    销售退货: 0,
+    调拨入: 4144,
+    期初: 0,
+    其它出库: 0,
+    期末数量: 90822,
+  },
+  {
+    仓库: '简尚-新外贸仓主仓',
+    期初数量: 5165,
+    销售出仓: -1743,
+    期末数量: 3422,
+  },
+];
+
+test('normalizeRecords 解析官方导出并映射仓库 ID', () => {
+  const { rows, warnings } = normalizeRecords(RECORDS);
+  assert.equal(rows.length, 2);
+  assert.deepEqual(warnings, []);
+
+  const [cuiqiao] = rows;
+  assert.equal(cuiqiao.warehouse, '简尚-崔桥工厂仓主仓');
+  assert.equal(cuiqiao.wmsCoId, 15038426); // 来自项目仓库清单
+  assert.equal(cuiqiao.openingQty, 90811);
+  assert.equal(cuiqiao.closingQty, 90822);
+  assert.equal(cuiqiao.flows.salesOut, -3252);
+  assert.equal(cuiqiao.flows.transferIn, 4144);
+  assert.equal(cuiqiao.flows.otherIn, 0); // 导出里显式为 0 的列保留 0
+  // 导出里没有出现的流水列保持 null，不能被当成 0
+  assert.equal(rows[1].flows.transferOut, null);
+  assert.equal(rows[1].flows.stocktaking, null);
+  // 导出里的第二个「期初」列不参与映射
+  assert.equal(Object.prototype.hasOwnProperty.call(cuiqiao.flows, 'openingQty'), false);
+});
+
+test('normalizeRecords 跳过无仓库名的行，未匹配仓库的 wmsCoId 为 null', () => {
+  const { rows } = normalizeRecords([
+    { 仓库: '', 期初数量: 1, 期末数量: 1 },
+    { 仓库: '某某新仓主仓', 期初数量: 10, 期末数量: 10 },
+  ]);
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].warehouse, '某某新仓主仓');
+  assert.equal(rows[0].wmsCoId, null);
+});
+
+test('checkBalance 校验「期初 + 流水 = 期末」，不闭合的仓库会被列出', () => {
+  const { rows } = normalizeRecords(RECORDS);
+  assert.deepEqual(checkBalance(rows), []);
+
+  const broken = checkBalance([{
+    warehouse: '差异仓', openingQty: 100, closingQty: 90, flows: { salesOut: -5 },
+  }]);
+  assert.equal(broken.length, 1);
+  assert.equal(broken[0].diff, 5);
+});
+
+test('parseWorkbook 能从 xlsx 缓冲区还原仓库行（表头不在首行也能定位）', () => {
+  const grid = [
+    ['说明', '这一行是导出时附加的标题'],
+    ['一级功能按键', '二级功能按键', '仓库', '期初数量', '销售出仓', '调拨入', '期末数量'],
+    ['大货库存监控', '每日进销存', '简尚-崔桥工厂仓主仓', 90811, -3252, 4144, 90822],
+    ['', '', '简尚-新外贸仓主仓', 5165, -1743, 0, 3422],
+  ];
+  const ws = XLSX.utils.aoa_to_sheet(grid);
+  const wb = XLSX.utils.book_new();
+  XLSX.utils.book_append_sheet(wb, ws, 'Sheet2');
+  const buffer = XLSX.write(wb, { type: 'buffer', bookType: 'xlsx' });
+
+  const { rows, sheetName } = parseWorkbook(buffer);
+  assert.equal(sheetName, 'Sheet2');
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0].warehouse, '简尚-崔桥工厂仓主仓');
+  assert.equal(rows[0].flows.transferIn, 4144);
+  assert.equal(rows[1].closingQty, 3422);
+});

backend/test/desktopReleaseService.test.js

@@ -1,60 +0,0 @@
-const assert = require('node:assert/strict');
-const test = require('node:test');
-
-const {
-  compareVersions,
-  normalizeArchitecture,
-  normalizePlatform,
-  parseReleaseStorage,
-  validateVersion,
-} = require('../src/services/desktopReleaseService');
-
-test('desktop release versions are compared numerically', () => {
-  assert.equal(compareVersions('0.0.10', '0.0.9'), 1);
-  assert.equal(compareVersions('v1.2.3', '1.2.3'), 0);
-  assert.equal(compareVersions('2.0.0', '10.0.0'), -1);
-});
-
-test('desktop release versions require an x.y.z value', () => {
-  assert.equal(validateVersion('v1.2.3'), '1.2.3');
-  assert.throws(() => validateVersion('1.2'), /版本号格式/);
-});
-
-test('desktop release storage drops invalid records without losing the latest version', () => {
-  const storage = parseReleaseStorage(JSON.stringify({
-    latestVersion: '0.0.9',
-    releases: [
-      { id: 9, version: '0.0.9', objectKey: 'desktop-client/0.0.9/setup.exe' },
-      { id: 8, version: 'invalid', objectKey: 'desktop-client/invalid/setup.exe' },
-    ],
-  }));
-
-  assert.equal(storage.latestVersion, '0.0.9');
-  assert.equal(storage.releases.length, 1);
-  assert.equal(storage.releases[0].version, '0.0.9');
-  assert.equal(storage.releases[0].platform, 'win32');
-  assert.equal(storage.releases[0].architecture, 'x64');
-  assert.equal(storage.latestVersions.win32, '0.0.9');
-});
-
-test('desktop release platform and architecture are inferred from installers', () => {
-  assert.equal(normalizePlatform('', 'pdd-auto-sale-0.0.10-arm64.dmg'), 'darwin');
-  assert.equal(normalizePlatform('', 'pdd-auto-sale-0.0.10-setup.exe'), 'win32');
-  assert.equal(normalizeArchitecture('', 'pdd-auto-sale-0.0.10-arm64.dmg', 'darwin'), 'arm64');
-  assert.equal(normalizeArchitecture('', 'pdd-auto-sale-0.0.10-setup.exe', 'win32'), 'x64');
-});
-
-test('desktop release storage keeps Windows and macOS installers for the same version', () => {
-  const storage = parseReleaseStorage({
-    latestVersions: { win32: '0.0.10', darwin: '0.0.10' },
-    releases: [
-      { id: 10, version: '0.0.10', objectKey: 'desktop-client/win32/0.0.10/setup.exe', fileName: 'pdd-auto-sale-0.0.10-setup.exe' },
-      { id: 11, version: '0.0.10', objectKey: 'desktop-client/darwin/0.0.10/app.dmg', fileName: 'pdd-auto-sale-0.0.10-arm64.dmg' },
-    ],
-  });
-
-  assert.equal(storage.releases.length, 2);
-  assert.deepEqual(storage.releases.map((release) => release.platform), ['win32', 'darwin']);
-  assert.equal(storage.latestVersions.win32, '0.0.10');
-  assert.equal(storage.latestVersions.darwin, '0.0.10');
-});

backend/test/desktopSessionService.test.js

@@ -95,7 +95,6 @@ test('desktop capabilities follow resolved page permissions', () => {
     marketingEvents: false,
     promotion: false,
     productTest: false,
-    reviewAnalysis: false,
   });
   assert.equal(buildDesktopCapabilities(resolvedUser({ role: 'admin', allowedPageKeys: [] })).promotion, true);
 });

backend/test/externalAutomationSharedAuth.test.js

@@ -5,7 +5,6 @@ const assert = require('node:assert/strict');
 const jwt = require('jsonwebtoken');
 const presaleRouter = require('../src/api/presaleExternal');
 const autoListingRouter = require('../src/api/planningSelectionFissionExternal');
-const pricingRouter = require('../src/api/pricingCalculatorExternal');
 const alibaba1688Router = require('../src/api/alibaba1688ProductExternal');
 const {
   requireDesktopPageAccess,
@@ -38,40 +37,6 @@ test('presale and auto-listing external APIs use the same request key middleware
   assert.equal(getRouteMiddleware(alibaba1688Router, '/:productId'), requireExternalAutomationApiKey);
 });
 
-test('desktop pricing uses the shared request key middleware', () => {
-  const middlewareLayer = pricingRouter.stack.find((item) => item.name === 'requireExternalAutomationApiKey');
-  assert.equal(middlewareLayer?.handle, requireExternalAutomationApiKey);
-});
-
-test('desktop pricing identity is stable, isolated and uses negative safe integers', () => {
-  const first = pricingRouter.desktopPricingUserId('香茗');
-  assert.equal(first, pricingRouter.desktopPricingUserId(' 香茗 '));
-  assert.notEqual(first, pricingRouter.desktopPricingUserId('江陵'));
-  assert.equal(Number.isSafeInteger(first), true);
-  assert.equal(first < 0, true);
-});
-
-test('desktop pricing accepts a UTF-8 base64url nickname header', () => {
-  const nickname = '胖大海';
-  const req = {
-    get(name) {
-      return name.toLowerCase() === 'x-operator-name-encoded'
-        ? Buffer.from(nickname, 'utf8').toString('base64url')
-        : '';
-    },
-    query: {},
-    body: {},
-  };
-  let nextCalled = false;
-
-  pricingRouter.requireDesktopPricingOperator(req, {}, () => { nextCalled = true; });
-
-  assert.equal(nextCalled, true);
-  assert.equal(req.user.name, nickname);
-  assert.equal(req.user.id, req.user.sub);
-  assert.ok(req.user.id < 0);
-});
-
 test('shared external auth accepts a valid desktop JWT without an API key', async () => {
   const previousSecret = process.env.CUBEJS_SECRET;
   process.env.CUBEJS_SECRET = 'desktop-session-test-secret';
@@ -178,20 +143,3 @@ test('desktop page access enforces JWT permissions and preserves API key compati
     assert.equal(nextCalled, true);
   }
 });
-
-test('desktop pricing keeps the verified JWT user identity', () => {
-  const req = {
-    externalApiKey: { authType: 'jwt' },
-    user: { sub: '42', id: 42, name: '陆南亭' },
-    get() { return ''; },
-    query: {},
-    body: {},
-  };
-  let nextCalled = false;
-
-  pricingRouter.requireDesktopPricingOperator(req, {}, () => { nextCalled = true; });
-
-  assert.equal(nextCalled, true);
-  assert.equal(req.user.id, 42);
-  assert.equal(req.user.name, '陆南亭');
-});

backend/test/mkhBomApi.test.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { _private } = require('../src/api/mkhBom');
+
+test('manual MKH sync always forces a live operational refresh', () => {
+  assert.deepEqual(
+    _private.buildSyncQuery({ page: 2, fresh: 0, live: 0 }),
+    { page: 2, fresh: '1', live: '1' }
+  );
+});

backend/test/mkhReplenishAlertJob.test.js

@@ -0,0 +1,194 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  buildAlertSignature,
+  buildMkhReplenishNotification,
+  buildNotifiedSnapshot,
+  chinaDateKey,
+  diffAlertState,
+  formatQty,
+} = require('../src/jobs/mkhReplenishAlertJob');
+
+const alert = (skuId, level = '缺货', extra = {}) => ({
+  skuId,
+  warningLevel: level,
+  productName: `商品 ${skuId}`,
+  dailySale: 1,
+  stock: 0,
+  replenishQty: 3,
+  ...extra,
+});
+
+test('diffAlertState splits fresh / persisted / restored', () => {
+  const state = { notified: { A: { level: '缺货' }, B: { level: '预警' }, Z: { level: '缺货' } } };
+  const { fresh, persisted, restored } = diffAlertState([alert('A'), alert('B'), alert('C')], state);
+
+  assert.deepEqual(fresh.map((r) => r.skuId), ['C']);
+  assert.deepEqual(persisted.map((r) => r.skuId), ['A', 'B']);
+  // Z 已补货恢复，应从已推送记录里剔除
+  assert.deepEqual(restored, ['Z']);
+});
+
+test('diffAlertState treats empty state as all fresh', () => {
+  const { fresh, persisted, restored } = diffAlertState([alert('A'), alert('B')], {});
+  assert.equal(fresh.length, 2);
+  assert.equal(persisted.length, 0);
+  assert.deepEqual(restored, []);
+});
+
+test('buildNotifiedSnapshot keeps firstNotifiedAt and drops restored skus', () => {
+  const state = { notified: { A: { firstNotifiedAt: '2026-09-01T01:00:00.000Z', lastNotifiedAt: '2026-09-01T01:00:00.000Z' } } };
+  const next = buildNotifiedSnapshot([alert('A'), alert('B')], state, '2026-09-17T01:00:00.000Z');
+
+  assert.deepEqual(Object.keys(next).sort(), ['A', 'B']);
+  assert.equal(next.A.firstNotifiedAt, '2026-09-01T01:00:00.000Z');
+  assert.equal(next.A.lastNotifiedAt, '2026-09-17T01:00:00.000Z');
+  assert.equal(next.B.firstNotifiedAt, '2026-09-17T01:00:00.000Z');
+});
+
+test('buildNotifiedSnapshot with touch=false does not refresh lastNotifiedAt', () => {
+  const state = { notified: { A: { firstNotifiedAt: '2026-09-01T01:00:00.000Z', lastNotifiedAt: '2026-09-05T01:00:00.000Z' } } };
+  const next = buildNotifiedSnapshot([alert('A')], state, '2026-09-17T01:00:00.000Z', { touch: false });
+  assert.equal(next.A.lastNotifiedAt, '2026-09-05T01:00:00.000Z');
+});
+
+test('buildAlertSignature is order independent but content sensitive', () => {
+  const a = alert('A');
+  const b = alert('B', '预警');
+  assert.equal(buildAlertSignature([a, b]), buildAlertSignature([b, a]));
+  assert.notEqual(buildAlertSignature([a, b]), buildAlertSignature([a]));
+  // 等级变化也算变化（缺货 → 预警 应产生新指纹）
+  assert.notEqual(buildAlertSignature([alert('A', '缺货')]), buildAlertSignature([alert('A', '预警')]));
+});
+
+test('chinaDateKey renders Beijing date regardless of UTC offset', () => {
+  // 2026-09-16T17:30:00Z === 2026-09-17 01:30 (北京) → 跨日必须算 09-17
+  assert.equal(chinaDateKey(new Date('2026-09-16T17:30:00Z')), '20260917');
+  assert.equal(chinaDateKey(new Date('2026-09-16T01:00:00Z')), '20260916');
+});
+
+test('formatQty trims trailing zeros and tolerates bad input', () => {
+  assert.equal(formatQty(3), '3');
+  assert.equal(formatQty(2.9700000001), '2.97');
+  assert.equal(formatQty(0.28), '0.28');
+  assert.equal(formatQty(null), '—');
+  assert.equal(formatQty('abc'), '—');
+});
+
+test('notification carries recipient, idempotency key and shortfall details', () => {
+  const fresh = [alert('MKHDNZ0409260700428', '缺货', { dailySale: 2.97, replenishQty: 9 })];
+  const all = [...fresh, alert('MKHDNZ0409260700486', '预警', { dailySale: 2, stock: 1, replenishQty: 5 })];
+  const snapshot = {
+    monitorDate: '2026-09-16',
+    saleWindowDays: 15,
+    replenishDaysThreshold: 3,
+    outOfStockCount: 1,
+    warningOnlyCount: 1,
+    replenishQtyTotal: 14,
+  };
+
+  const payload = buildMkhReplenishNotification({
+    alerts: fresh,
+    allAlerts: all,
+    snapshot,
+    recipientAlias: '苏适',
+    dateKey: '20260917',
+  });
+
+  assert.equal(payload.recipientAlias, '苏适');
+  assert.equal(payload.idempotencyKey, `mkh_replenish_alert:苏适:20260917:${buildAlertSignature(fresh)}:v1`);
+  assert.ok(payload.title.includes('新增 1 个'));
+  assert.ok(payload.title.includes('含 1 个已缺货'));
+  assert.ok(payload.content.includes('MKHDNZ0409260700428'));
+  assert.ok(payload.content.includes('现有库存 0'));
+  assert.ok(payload.content.includes('建议补货 9'));
+  // 汇总用全量口径，不是本批新增
+  assert.ok(payload.content.includes('当前共 **2** 个'));
+  assert.equal(payload.actionTitle, '查看补货清单');
+  assert.ok(payload.content.length <= 4800);
+});
+
+test('notification truncates long lists but keeps the totals', () => {
+  const many = Array.from({ length: 40 }, (_, i) => alert(`MKH${String(i).padStart(4, '0')}`));
+  const payload = buildMkhReplenishNotification({
+    alerts: many,
+    allAlerts: many,
+    snapshot: { outOfStockCount: 40, warningOnlyCount: 0, replenishQtyTotal: 120 },
+    recipientAlias: '苏适',
+    dateKey: '20260917',
+  });
+
+  assert.ok(payload.content.includes('仅列出前 20 个'));
+  assert.ok(payload.content.includes('当前共 **40** 个'));
+  assert.equal(payload.content.includes('MKH0039'), false);
+  assert.ok(payload.content.length <= 4800);
+});
+
+test('notification flags degraded work-order source', () => {
+  const payload = buildMkhReplenishNotification({
+    alerts: [alert('A')],
+    allAlerts: [alert('A')],
+    snapshot: { outOfStockCount: 1, warningOnlyCount: 0, replenishQtyTotal: 3, workOrderDegraded: true },
+    recipientAlias: '苏适',
+    dateKey: '20260917',
+  });
+  assert.ok(payload.content.includes('加工单数据源暂不可用'));
+});
+
+// ── 配件不足（见 mkhBomService 文件头 ⑪）──────────────────────────
+test('notification spells out 配件不足 and drops the replenish target', () => {
+  const shortage = alert('MKHDNZ0409260600843', '缺货', {
+    dailySale: 0,
+    stock: 0,
+    replenishQty: 1,
+    componentShortage: true,
+    assemblableQty: 0,
+    bottleneckComponents: [
+      { code: 'DNZ040958N1440V01', name: '白架通用前拉杆', perQty: 1, stock: 0, occupied: 0, available: 0, can: 0 },
+      { code: 'DNZ041106B01V01', name: '通用小K', perQty: 1, stock: 23, occupied: 0, available: 23, can: 23 },
+    ],
+  });
+
+  const payload = buildMkhReplenishNotification({
+    alerts: [shortage],
+    allAlerts: [shortage],
+    snapshot: {
+      outOfStockCount: 1,
+      warningOnlyCount: 0,
+      replenishQtyTotal: 1,
+      componentShortageCount: 1,
+    },
+    recipientAlias: '苏适',
+    dateKey: '20260917',
+  });
+
+  assert.ok(payload.content.includes('配件不足，无法补货'));
+  // 补不出来的商品不再给补货数字，避免业务照着一个补不到的目标去采购
+  assert.ok(payload.content.includes('建议补货 —'));
+  assert.equal(payload.content.includes('建议补货 1'), false);
+  // 只列真正卡住的短板（可支配数 ≤ 0），库存充足的不列
+  assert.ok(payload.content.includes('DNZ040958N1440V01'));
+  assert.equal(payload.content.includes('DNZ041106B01V01'), false);
+  // 汇总段说明本批里有几个配件不足
+  assert.ok(payload.content.includes('因**配件库存不足**'));
+});
+
+test('notification flags degraded component stock source', () => {
+  const payload = buildMkhReplenishNotification({
+    alerts: [alert('A')],
+    allAlerts: [alert('A')],
+    snapshot: {
+      outOfStockCount: 1,
+      warningOnlyCount: 0,
+      replenishQtyTotal: 3,
+      componentStockDegraded: true,
+    },
+    recipientAlias: '苏适',
+    dateKey: '20260917',
+  });
+  assert.ok(payload.content.includes('配件库存数据源暂不可用'));
+  assert.ok(payload.content.includes('未做'));
+});

backend/test/pickingBinSalesAnalysis.test.js

@@ -0,0 +1,171 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  buildGradeCase,
+  buildInClause,
+  fetchPickingBinSkuRows,
+} = require('../src/services/pickingBinSalesAnalysis');
+const {
+  PICKING_BIN_GRADE_RULES,
+  PICKING_BIN_DEFAULT_DAYS,
+  PICKING_BIN_WINDOW_OPTIONS,
+  PICKING_BIN_BIN_TYPES,
+} = require('../src/config/pickingBinSalesAnalysis');
+
+test('buildInClause 按位展开参数', () => {
+  const { clause, params } = buildInClause([101, 102], 'w');
+  assert.equal(clause, '@w0,@w1');
+  assert.deepEqual(params, { w0: 101, w1: 102 });
+});
+
+test('buildGradeCase 覆盖全部正向等级，并以销售=0 兜底', () => {
+  const expr = buildGradeCase();
+  PICKING_BIN_GRADE_RULES.filter((rule) => rule.lower > 0).forEach((rule) => {
+    assert.ok(expr.includes(`THEN '${rule.key}'`), `${rule.key} 未出现在分档表达式中`);
+  });
+  assert.ok(expr.includes("THEN 'slow2'"));
+  assert.ok(expr.includes("ELSE 'zero'"));
+});
+
+test('等级按商品销量判定（默认表达式取 s.salesQty，不含仓位汇总列）', () => {
+  const expr = buildGradeCase();
+  assert.ok(expr.includes('ISNULL(s.salesQty, 0) / @days'));
+  assert.ok(!expr.includes('x.salesQty'));
+});
+
+test('默认窗口为 30 天，统计范围固定为拣选位', () => {
+  assert.equal(PICKING_BIN_DEFAULT_DAYS, 30);
+  assert.ok(PICKING_BIN_WINDOW_OPTIONS.includes(30));
+  assert.deepEqual(PICKING_BIN_BIN_TYPES, ['拣选']);
+});
+
+test('fetchPickingBinSkuRows 首参不是数据库实例时抛错', async () => {
+  await assert.rejects(
+    () => fetchPickingBinSkuRows({}, [101], { shipFrom: 'a', shipTo: 'b', days: 30 }),
+    TypeError
+  );
+});
+
+test('fetchPickingBinSkuRows 缺失必要窗口参数时返回空数组，不打库', async () => {
+  let called = 0;
+  const db = { query: async () => { called += 1; return [{ skuId: 'S1' }]; } };
+  assert.deepEqual(await fetchPickingBinSkuRows(db, [], { shipFrom: 'a', shipTo: 'b', days: 30 }), []);
+  assert.deepEqual(await fetchPickingBinSkuRows(db, [101], { shipFrom: null, shipTo: 'b', days: 30 }), []);
+  assert.deepEqual(await fetchPickingBinSkuRows(db, [101], { shipFrom: 'a', shipTo: 'b', days: 0 }), []);
+  assert.equal(called, 0);
+});
+
+test('fetchPickingBinSkuRows 按仓位×商品输出，等级与日销来自商品整档销量', async () => {
+  let captured = null;
+  const db = {
+    query: async (sqlText, params) => {
+      captured = { sqlText, params };
+      return [
+        {
+          wmsCoId: 101, binName: 'XA01-01-01', binType: '拣选', skuId: 'SKU1',
+          stockQty: 12, skuCount: 2, salesQty: 600, allocatedSalesQty: 300,
+          dailySales: 20, gradeKey: 'hot',
+        },
+        {
+          wmsCoId: 101, binName: 'XA01-01-01', binType: '拣选', skuId: 'SKU2',
+          stockQty: 8, skuCount: 2, salesQty: 45, allocatedSalesQty: 22.5,
+          dailySales: 1.5, gradeKey: 'slow1',
+        },
+      ];
+    },
+  };
+
+  const rows = await fetchPickingBinSkuRows(db, [101, 102], {
+    shipFrom: '2026-09-08 01:00:00',
+    shipTo: '2026-10-08 01:00:00',
+    days: 30,
+  });
+
+  assert.equal(rows.length, 2);
+  assert.deepEqual(rows.map((r) => r.skuId), ['SKU1', 'SKU2']);
+  // 同一仓位两个商品拆两行，库存是各商品在该仓位的实际库存
+  assert.deepEqual(rows.map((r) => r.stockQty), [12, 8]);
+  // 等级按商品自身日销，同一仓位的多行可以不同
+  assert.deepEqual(rows.map((r) => r.gradeKey), ['hot', 'slow1']);
+  // 分摊销量 = 商品销量 ÷ 占用的同类型仓位数（用于按行求和）
+  assert.deepEqual(rows.map((r) => r.allocatedSalesQty), [300, 22.5]);
+  assert.deepEqual(rows[0], {
+    wmsCoId: '101',
+    binName: 'XA01-01-01',
+    binType: '拣选',
+    skuId: 'SKU1',
+    stockQty: 12,
+    skuCount: 2,
+    salesQty: 600,
+    allocatedSalesQty: 300,
+    dailySales: 20,
+    gradeKey: 'hot',
+  });
+
+  // 参数必须带上两个仓库、发货窗口与天数
+  assert.equal(captured.params.w0, 101);
+  assert.equal(captured.params.w1, 102);
+  assert.equal(captured.params.v0, 101);
+  assert.equal(captured.params.shipFrom, '2026-09-08 01:00:00');
+  assert.equal(captured.params.shipTo, '2026-10-08 01:00:00');
+  assert.equal(captured.params.days, 30);
+
+  // 商品销量按占用仓位数分摊（供求和），但等级依据的是未分摊的商品销量
+  assert.ok(captured.sqlText.includes('/ NULLIF(sp.binCount, 0)'));
+  assert.ok(captured.sqlText.includes('ISNULL(s.salesQty, 0) / @days AS DECIMAL(18, 4)'));
+  // 统计范围固定为真实拣选仓位：pack_type=Bin 且 bin_group 为空；只统计有库存的行
+  assert.ok(captured.sqlText.includes("p.pack_type = N'Bin'"));
+  assert.ok(captured.sqlText.includes("ISNULL(p.bin_group, '') = ''"));
+  assert.ok(captured.sqlText.includes('ISNULL(p.qty, 0) <> 0'));
+  assert.ok(captured.sqlText.includes('HAVING ABS(SUM(CAST(b.binSkuQty AS DECIMAL(18, 2)))) > 0.0001'));
+});
+
+test('fetchPickingBinSkuRows 只统计真实拣选仓位，排除 Pack 箱记录且不带类型参数', async () => {
+  let captured = null;
+  const db = {
+    query: async (sqlText, params) => { captured = { sqlText, params }; return []; },
+  };
+  await fetchPickingBinSkuRows(db, [101], { shipFrom: 'a', shipTo: 'b', days: 15 });
+  // Pack 箱记录和存货位被排除，且不再有 binType IN (...) 的可变过滤
+  assert.ok(captured.sqlText.includes("p.pack_type = N'Bin'"));
+  assert.ok(captured.sqlText.includes("ISNULL(p.bin_group, '') = ''"));
+  assert.ok(!captured.sqlText.includes('b.binType IN'));
+  assert.equal(captured.params.t0, undefined);
+  assert.equal(captured.params.binTypes, undefined);
+  // 多来源 union 后必须再按 仓库+商品 汇总，否则同一仓位行会被拆成多行
+  assert.ok(captured.sqlText.includes('shipAgg AS ('));
+  assert.ok(captured.sqlText.includes('LEFT JOIN shipAgg s'));
+  assert.ok(!captured.sqlText.includes('LEFT JOIN ship s'));
+});
+
+test('销量覆盖 4 个来源：线上普通行 + 组合装展开 + 全民客户普通行 + 全民客户组合装展开', async () => {
+  let captured = null;
+  const db = {
+    query: async (sqlText, params) => { captured = { sqlText, params }; return []; },
+  };
+  await fetchPickingBinSkuRows(db, [101], { shipFrom: 'a', shipTo: 'b', days: 30 });
+
+  // ① 线上店铺订单普通行
+  assert.ok(captured.sqlText.includes('FROM rpt.jst_OrderItem'), '缺少 jst_OrderItem 普通行分支');
+  // ② 线上订单组合装行按映射表展开为子件
+  assert.ok(captured.sqlText.includes('JOIN rpt.jst_comboProductItem'), '缺少组合装展开分支');
+  assert.ok(captured.sqlText.includes("oi.sku_type = 'combine'"), '缺少组合装行识别条件');
+  // ③ 全民客户（B2B 分销）渠道普通行，排除拆单父单 Split 与问题单
+  assert.ok(captured.sqlText.includes('FROM rpt.jst_qmcust_orderlist_item'), '缺少 qmcust 分支');
+  assert.ok(captured.sqlText.includes("'Split', 'Question'"), 'qmcust 未排除拆单父单/问题单');
+  // 四个分支共用同一发货窗口
+  assert.equal(captured.sqlText.split('o.send_date >= @shipFrom').length, 5);
+});
+
+test('gradeKey 缺失时兜底为 zero', async () => {
+  const db = { query: async () => [{ wmsCoId: 101, binName: 'X', binType: '拣选', skuId: 'S1', stockQty: 5 }] };
+  const rows = await fetchPickingBinSkuRows(db, [101], { shipFrom: 'a', shipTo: 'b', days: 15 });
+  assert.equal(rows[0].gradeKey, 'zero');
+  assert.equal(rows[0].salesQty, 0);
+  assert.equal(rows[0].allocatedSalesQty, 0);
+  assert.equal(rows[0].dailySales, 0);
+  assert.equal(rows[0].skuId, 'S1');
+});

backend/test/pricingCalculatorSelection.test.js

@@ -1,110 +0,0 @@
-'use strict';
-
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const {
-  _test: {
-    filterSkuRowsForSelectionContext,
-    createPrefsPatch,
-    getSelectionSkuCodeSet,
-    normalizeCalculatorType,
-    readPrefsProfile,
-    sanitizeHistoryProduct,
-    writePrefsProfile,
-  },
-} = require('../src/api/pricingCalculator');
-
-const skuRows = [
-  { skuCode: 'SKU-A' },
-  { skuCode: 'SKU-B' },
-  { skuCode: 'SKU-C' },
-];
-
-test('selection pricing only returns explicitly selected SKU rows', () => {
-  const selectionContext = {
-    skuSceneImages: { selectedSkuCodes: ['sku-a', 'SKU-C'] },
-    rows: [{ skuCode: 'SKU-A' }, { skuCode: 'SKU-B' }, { skuCode: 'SKU-C' }],
-  };
-
-  assert.deepEqual(
-    filterSkuRowsForSelectionContext(skuRows, selectionContext),
-    [{ skuCode: 'SKU-A' }, { skuCode: 'SKU-C' }]
-  );
-});
-
-test('selection pricing falls back to stored pricing rows for legacy tasks', () => {
-  const selectionContext = {
-    skuSceneImages: {},
-    rows: [{ skuCode: 'SKU-B' }],
-  };
-
-  assert.deepEqual([...getSelectionSkuCodeSet(selectionContext)], ['SKU-B']);
-  assert.deepEqual(
-    filterSkuRowsForSelectionContext(skuRows, selectionContext),
-    [{ skuCode: 'SKU-B' }]
-  );
-});
-
-test('standalone pricing continues to return all SPU SKU rows', () => {
-  assert.deepEqual(filterSkuRowsForSelectionContext(skuRows, null), skuRows);
-});
-
-test('pricing preferences keep legacy company values and isolate 1688 defaults', () => {
-  const legacy = JSON.stringify({
-    coupon: 30,
-    activityDiscount: 0.7,
-    installFee: 5,
-    targetMargin: 0.15,
-  });
-  const withDropship = writePrefsProfile(legacy, 'alibaba1688', {
-    coupon: 20,
-    activityDiscount: 0.6,
-    installFee: 0,
-    targetMargin: 0.12,
-  });
-
-  assert.deepEqual(readPrefsProfile(withDropship, 'company'), {
-    coupon: 30,
-    activityDiscount: 0.7,
-    installFee: 5,
-    targetMargin: 0.15,
-  });
-  assert.deepEqual(readPrefsProfile(withDropship, 'alibaba1688'), {
-    coupon: 20,
-    activityDiscount: 0.6,
-    installFee: 0,
-    targetMargin: 0.12,
-  });
-
-  const updatedCompany = writePrefsProfile(withDropship, 'company', { targetMargin: 0.18 });
-  assert.equal(readPrefsProfile(updatedCompany, 'company').targetMargin, 0.18);
-  assert.equal(readPrefsProfile(updatedCompany, 'alibaba1688').targetMargin, 0.12);
-  assert.deepEqual(createPrefsPatch('company', { targetMargin: 0.15 }), { targetMargin: 0.15 });
-  assert.deepEqual(createPrefsPatch('alibaba1688', { targetMargin: 0.12 }), {
-    _profiles: { alibaba1688: { targetMargin: 0.12 } },
-  });
-});
-
-test('1688 history product keeps bounded identity and specification dimensions', () => {
-  assert.equal(normalizeCalculatorType('alibaba1688'), 'alibaba1688');
-  assert.equal(normalizeCalculatorType('unknown'), 'company');
-  assert.deepEqual(sanitizeHistoryProduct({
-    productId: ' 1073252781818 ',
-    title: ' 测试商品 ',
-    skuDimensions: [
-      { name: '颜色', values: ['原木色', '胡桃色'] },
-      { name: '尺寸', values: ['60cm'] },
-    ],
-  }), {
-    productId: '1073252781818',
-    title: '测试商品',
-    mainImage: '',
-    sourceUrl: '',
-    storeName: '',
-    category: '',
-    skuDimensions: [
-      { name: '颜色', values: ['原木色', '胡桃色'] },
-      { name: '尺寸', values: ['60cm'] },
-    ],
-  });
-});

backend/test/remoteEnrollmentService.test.js

@@ -0,0 +1,17 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  DEFAULT_BOOTSTRAP_ENDPOINT,
+  normalizeEndpoint,
+} = require('../src/services/remoteEnrollmentService');
+
+test('remote enrollment defaults to the managed HTTPS endpoint', () => {
+  assert.equal(normalizeEndpoint(''), DEFAULT_BOOTSTRAP_ENDPOINT);
+  assert.equal(normalizeEndpoint('https://ck.yydd.ai:8443/v1/enroll'), 'https://ck.yydd.ai:8443/v1/enroll');
+});
+
+test('remote enrollment refuses insecure or credential-bearing endpoints', () => {
+  assert.throws(() => normalizeEndpoint('http://ck.yydd.ai/v1/enroll'), /HTTPS/u);
+  assert.throws(() => normalizeEndpoint('https://user:secret@ck.yydd.ai/v1/enroll'), /HTTPS/u);
+});

backend/test/retiredFeatures.test.js

@@ -1,14 +1,26 @@
 const test = require('node:test');
 const assert = require('node:assert/strict');
-const { pruneRetiredSidebarConfig, cleanupRetiredFeatureSettings, isRetiredSystemConfigKey } = require('../src/services/retiredFeatures');
+const {
+  pruneRetiredSidebarConfig,
+  cleanupRetiredFeatureSettings,
+  isRetiredDatabaseConfigName,
+  isRetiredSystemConfigKey,
+} = require('../src/services/retiredFeatures');
 
 test('retired sidebar cleanup is recursive and idempotent', () => {
-  const saved = JSON.stringify({ entries: [{ key: 'agent' }, { key: 'manage', children: [{ key: 'ai-skill-tags' }, { key: 'settings', label: '管理设置' }] }] });
+  const saved = JSON.stringify({ entries: [
+    { key: 'agent' },
+    { key: 'store-management', children: [{ key: 'store-checkup' }] },
+    { key: 'operation-tools', children: [{ key: 'pricing-calculator' }] },
+    { key: 'manage', children: [{ key: 'ai-skill-tags' }, { key: 'desktop-client-releases' }, { key: 'settings', label: '管理设置' }] },
+  ] });
   const clean = pruneRetiredSidebarConfig(saved);
   assert.deepEqual(JSON.parse(clean).entries, [{ key: 'manage', children: [{ key: 'settings', label: '管理设置' }] }]);
   assert.equal(pruneRetiredSidebarConfig(clean), clean);
   assert.equal(pruneRetiredSidebarConfig('{invalid'), '{invalid');
   assert.equal(isRetiredSystemConfigKey('openclaw_chat_skill_tags'), true);
+  assert.equal(isRetiredSystemConfigKey('cs_quality_ai_config'), true);
+  assert.equal(isRetiredDatabaseConfigName('ai_buyer_show_database'), true);
   assert.equal(isRetiredSystemConfigKey('site_name'), false);
 });
 
@@ -19,8 +31,9 @@ test('upgrade removes only retired settings and permission rows', async () => {
     return sql.startsWith('SELECT') ? [{ config_value: '{"entries":[{"key":"agent"},{"key":"product-analysis"}]}' }] : [];
   } });
   const deletes = calls.filter((call) => call.sql.startsWith('DELETE'));
-  assert.equal(deletes.length, 4);
+  assert.equal(deletes.length, 5);
   assert.ok(deletes.every((call) => call.sql.includes(' WHERE ') && call.params.length > 0));
+  assert.equal(calls.filter((call) => call.sql.startsWith('DROP TABLE IF EXISTS')).length, 2);
   const update = calls.find((call) => call.sql.startsWith('UPDATE'));
   assert.deepEqual(JSON.parse(update.params[0]).entries, [{ key: 'product-analysis' }]);
 });

backend/test/retiredRoutes.test.js

@@ -6,7 +6,7 @@ const express = require('express');
 test('retired market endpoints return 404 while retained incentive and calculator endpoints work', async () => {
   const originalLoad = Module._load;
   Module._load = function (id, parent, ...rest) {
-    if (parent?.filename.endsWith('/api/planningUpload.js')) {
+    if (/[\\/]api[\\/]planningUpload\.js$/.test(parent?.filename || '')) {
       if (id.endsWith('/pageAccess')) return { getResolvedUserWithPageAccess: async () => ({ role: 'admin' }) };
       if (id.endsWith('/opsBIncentiveBoardService')) return {
         getOpsBIncentiveBoard: async () => ({ rows: [] }), getOpsBIncentiveBatches: async () => [], getOpsBIncentiveDaily: async () => [],

backend/test/stockSalesAnalysis.test.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  buildGradeCase,
+  buildInClause,
+  fetchGradeRows,
+  fetchZeroSaleSkuRows,
+} = require('../src/services/stockSalesAnalysis');
+const { SALES_GRADE_RULES } = require('../src/config/stockSalesAnalysis');
+
+test('buildInClause 按位展开仓库参数', () => {
+  const { clause, params } = buildInClause([101, 102], 'w');
+  assert.equal(clause, '@w0,@w1');
+  assert.deepEqual(params, { w0: 101, w1: 102 });
+});
+
+test('buildGradeCase 覆盖全部正向等级，并以销售=0 兜底', () => {
+  const expr = buildGradeCase();
+  SALES_GRADE_RULES.filter((rule) => rule.lower > 0).forEach((rule) => {
+    assert.ok(expr.includes(`THEN '${rule.key}'`), `${rule.key} 未出现在分档表达式中`);
+  });
+  assert.ok(expr.includes("THEN 'slow2'"));
+  assert.ok(expr.includes("ELSE 'zero'"));
+});
+
+test('fetchGradeRows 首参不是数据库实例时抛错，避免静默返回空数组', async () => {
+  await assert.rejects(
+    () => fetchGradeRows({}, [101], { shipFrom: 'a', shipTo: 'b', days: 30 }),
+    TypeError
+  );
+});
+
+test('fetchGradeRows 无仓库或缺失窗口时直接返回空结果', async () => {
+  let called = 0;
+  const db = { query: async () => { called += 1; return []; } };
+  assert.deepEqual(await fetchGradeRows(db, [], { shipFrom: 'a', shipTo: 'b', days: 30 }), []);
+  assert.deepEqual(await fetchGradeRows(db, [101], { shipFrom: null, shipTo: 'b', days: 30 }), []);
+  assert.equal(called, 0);
+});
+
+test('fetchGradeRows 把仓库参数与窗口参数一并传给业务库', async () => {
+  let captured = null;
+  const db = {
+    query: async (sqlText, params) => {
+      captured = { sqlText, params };
+      return [
+        { wmsCoId: 101, gradeKey: 'hot', skuCount: 2, stockQty: 438, salesQty: 1136, dailySales: 37.87 },
+      ];
+    },
+  };
+
+  const rows = await fetchGradeRows(db, [101, 102], {
+    shipFrom: '2026-08-28 01:00:00',
+    shipTo: '2026-09-27 01:00:00',
+    days: 30,
+  });
+
+  assert.equal(rows.length, 1);
+  assert.equal(rows[0].wmsCoId, '101');
+  assert.equal(rows[0].stockQty, 438);
+
+  assert.equal(captured.params.w0, 101);
+  assert.equal(captured.params.w1, 102);
+  assert.equal(captured.params.v0, 101);
+  assert.equal(captured.params.days, 30);
+  assert.equal(captured.params.shipFrom, '2026-08-28 01:00:00');
+  assert.equal(captured.params.shipTo, '2026-09-27 01:00:00');
+  assert.ok(captured.sqlText.includes('@days'));
+  assert.ok(captured.sqlText.includes('rpt.jst_inventoryInfo'));
+  assert.ok(captured.sqlText.includes('rpt.jst_OrderItem'));
+});
+
+test('fetchZeroSaleSkuRows 首参不是数据库实例时抛错，避免静默返回空数组', async () => {
+  await assert.rejects(
+    () => fetchZeroSaleSkuRows({}, [101], { shipFrom: 'a', shipTo: 'b', days: 30 }),
+    TypeError
+  );
+});
+
+test('fetchZeroSaleSkuRows 无仓库或缺失窗口时直接返回空结果', async () => {
+  let called = 0;
+  const db = { query: async () => { called += 1; return []; } };
+  assert.deepEqual(await fetchZeroSaleSkuRows(db, [], { shipFrom: 'a', shipTo: 'b', days: 30 }), []);
+  assert.deepEqual(await fetchZeroSaleSkuRows(db, [101], { shipFrom: 'a', shipTo: null, days: 30 }), []);
+  assert.equal(called, 0);
+});
+
+test('fetchZeroSaleSkuRows 复用同一分档口径并关联 SKU 名称', async () => {
+  let captured = null;
+  const db = {
+    query: async (sqlText, params) => {
+      captured = { sqlText, params };
+      return [
+        { wmsCoId: 101, skuId: 'SKU-A', skuName: '款式A', binName: 'A01-01-1', stockQty: 7, salesQty: 0 },
+        { wmsCoId: 101, skuId: 'SKU-A', skuName: '款式A', binName: 'A02-03-1', stockQty: 5, salesQty: 0 },
+        { wmsCoId: 101, skuId: 'SKU-B', skuName: '款式B', binName: null, stockQty: 3, salesQty: 0 },
+      ];
+    },
+  };
+
+  const rows = await fetchZeroSaleSkuRows(db, [101, 102], {
+    shipFrom: '2026-08-28 01:00:00',
+    shipTo: '2026-09-27 01:00:00',
+    days: 30,
+  });
+
+  // 每个仓位独立一行；无仓位的 SKU 保留一行（仓位为空、库存取总库存）
+  assert.equal(rows.length, 3);
+  assert.equal(rows[0].wmsCoId, '101');
+  assert.equal(rows[0].skuName, '款式A');
+  assert.equal(rows[0].binName, 'A01-01-1');
+  assert.equal(rows[0].stockQty, 7);
+  assert.equal(rows[1].binName, 'A02-03-1');
+  assert.equal(rows[1].stockQty, 5);
+  assert.equal(rows[2].binName, '');
+  assert.equal(rows[2].stockQty, 3);
+
+  // 口径必须与 fetchGradeRows 一致：同一段 gradeCase 表达式 + 同样的「有库存或有销量」过滤
+  assert.ok(captured.sqlText.includes("ELSE 'zero'"));
+  assert.ok(captured.sqlText.includes("g.gradeKey = 'zero'"));
+  assert.ok(captured.sqlText.includes('rpt.jst_sku'));
+  assert.ok(captured.sqlText.includes("NOT IN ('Delete', 'Cancelled')"));
+  assert.equal(captured.params.w0, 101);
+  assert.equal(captured.params.days, 30);
+
+  // 系统仓位：来自 rpt.jst_packInventoryInfo，按「仓库+SKU+仓位」聚合出仓位级库存，
+  // 每仓位一行（COALESCE 兜底无仓位 SKU 取总库存），排除无仓位与零库存记录
+  assert.ok(captured.sqlText.includes('rpt.jst_packInventoryInfo'));
+  assert.ok(captured.sqlText.includes('COALESCE(bn.binQty, g.stockQty)'));
+  assert.ok(captured.sqlText.includes('binName'));
+});
+
+test('fetchZeroSaleSkuRows 的仓位必须按同一仓库匹配，避免跨仓错配', async () => {
+  let captured = null;
+  const db = {
+    query: async (sqlText) => {
+      captured = sqlText;
+      return [];
+    },
+  };
+  await fetchZeroSaleSkuRows(db, [101], {
+    shipFrom: '2026-08-28 01:00:00', shipTo: '2026-09-27 01:00:00', days: 30,
+  });
+  assert.ok(captured.includes('bn.wmsCoId = g.wmsCoId AND bn.skuId = g.skuId'));
+  assert.ok(captured.includes("ISNULL(p.qty, 0) <> 0"));
+});

backend/test/warehouseShipTimeliness.test.js

@@ -0,0 +1,233 @@
+/**
+ * 仓储中心 24 小时发货时效 —— 口径回归测试（2026-10-20 新增）
+ *
+ * 这个功能最容易出错的是「口径」，不是 SQL 语法。本文件锁定四条关键语义：
+ *   ① 主仓归属用**关键词最长匹配** —— 「横林二仓品牌仓」不能被「横林二仓」抢走，
+ *      否则品牌仓的订单会被重复计入两个仓；
+ *   ② 核验轮次的时刻选择 —— 12:00 前**不做核验（返回 null）**、12:00~15:59 用
+ *      7:00 窗口、16:00 后用 16:00 窗口；
+ *   ③ 状态排除表 —— Cancelled / Merged / Split 必须排除（Split 是拆单父单，
+ *      永不发货，不排除会把一年前的单全算成超时未发）；
+ *   ④ 服务层分桶算术 —— pending/shippedLate/onTime 三态互斥，按时率不为负。
+ *
+ * ⚠️ 本文件**不连数据库**，纯逻辑测试。
+ */
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const registry = require('../src/services/warehouseShipTimelinessRegistry');
+
+// ── ① 主仓归属：最长匹配 ────────────────────────────────────────────────
+test('resolveCenter 用最长关键词匹配，品牌仓不会被主仓抢走', () => {
+  assert.equal(registry.resolveCenter('简尚-横林二仓品牌仓').key, 'HL2_BRAND');
+  assert.equal(registry.resolveCenter('简尚-横林二仓').key, 'HL2');
+  assert.equal(registry.resolveCenter('简尚-崔桥工厂品牌仓').key, 'CQ_BRAND');
+  assert.equal(registry.resolveCenter('简尚-崔桥工厂仓').key, 'CQ');
+  assert.equal(registry.resolveCenter('简尚-山东品牌仓').key, 'SD_BRAND');
+  assert.equal(registry.resolveCenter('简尚-山东青岗集仓').key, 'SD_QGJ');
+});
+
+test('resolveCenter 能捞到各种命名的子仓', () => {
+  const cases = [
+    ['京仓-横林二仓京东云仓', 'HL2'],
+    ['简尚-运营C横林二仓专用仓', 'HL2'],
+    ['简尚-横林二仓京东仓', 'HL2'],
+    ['简尚-崔桥工厂仓唯品仓', 'CQ'],
+    ['简尚-运营C崔桥工厂仓专用仓', 'CQ'],
+    ['简尚-新苏北临时仓', 'XSB'],
+    ['简尚-分销部睢宁专用仓', 'SN'],
+    ['京仓-山东青岗集京东仓储', 'SD_QGJ'],
+    ['简尚-山东青岗集仓马来海外仓', 'SD_QGJ'],
+    ['简尚-河南洛宁仓', 'HN_LN'],
+  ];
+  for (const [name, expected] of cases) {
+    assert.equal(registry.resolveCenter(name)?.key, expected, name);
+  }
+});
+
+test('resolveCenter 不会把无关代发仓误并入（山东/河南是高频前缀）', () => {
+  // 这是最容易翻车的地方：仓库表里有上百个「工厂-山东XX代发仓」，
+  // 如果关键词写成「山东」就会全被并进山东品牌仓/青岗集仓。
+  const shouldBeNull = [
+    '工厂-山东菏泽森美代发仓',
+    '工厂-山东恒思代发仓',
+    '工厂-河南千优代发仓',
+    '工厂-河北霸州派雅世佳代发仓',
+    '简尚-苏州福利品仓',
+    '简尚-崔桥工厂半成品包装项目仓',
+  ];
+  for (const name of shouldBeNull) {
+    assert.equal(registry.resolveCenter(name), null, `${name} 不应归属任何主仓`);
+  }
+});
+
+test('崔桥工厂半成品仓是占位仓：没有关键词、匹配不到任何仓', () => {
+  const c = registry.CENTERS.find((x) => x.key === 'CQ_WIP');
+  assert.ok(c, 'CQ_WIP 必须存在（业务要求列出来）');
+  assert.equal(c.placeholder, true);
+  assert.deepEqual(c.keywords, []);
+});
+
+// ── ② 核验轮次 ──────────────────────────────────────────────────────────
+const at = (h, m) => new Date(2026, 9, 20, h, m, 0); // 2026-10-20 本机时区（东八区）
+
+test('12:00 前不做核验，返回 null（不回填昨日数据）', () => {
+  // 业务口径（2026-10-20 确认）：中午 12:00 才开始第一轮核验，
+  // 12:00 之前页面显示「未到核验时间」，**不能用昨天的结算结果冒充今天**。
+  assert.equal(registry.resolveActiveRound(at(9, 30)), null);
+  assert.equal(registry.resolveActiveRound(at(11, 59)), null);
+  assert.equal(registry.resolveActiveRound(at(0, 5)), null);
+});
+
+test('12:00~15:59 用 12:00 轮，核验窗口是当天 00:00~07:00', () => {
+  const r = registry.resolveActiveRound(at(12, 0));
+  assert.ok(r);
+  assert.equal(r.key, 'NOON');
+  assert.equal(r.deadline, '2026-10-20 12:00:00');
+  assert.equal(r.windowStart, '2026-10-20 00:00:00');
+  assert.equal(r.windowEnd, '2026-10-20 07:00:00');
+});
+
+test('16:00 之后用 16:00 轮，核验窗口扩到当天 00:00~16:00', () => {
+  const r = registry.resolveActiveRound(at(16, 0));
+  assert.equal(r.key, 'AFTERNOON');
+  assert.equal(r.deadline, '2026-10-20 16:00:00');
+  assert.equal(r.windowEnd, '2026-10-20 16:00:00');
+
+  // 深夜仍沿用当天 16:00 轮（午夜后又回到新的一天）
+  assert.equal(registry.resolveActiveRound(at(23, 59)).key, 'AFTERNOON');
+});
+
+// ── ③ 状态排除 ──────────────────────────────────────────────────────────
+test('排除 Cancelled / Merged / Split，但保留 Question（仍算待发）', () => {
+  const sql = registry.EXCLUDED_STATUS_SQL;
+  assert.match(sql, /Cancelled/);
+  assert.match(sql, /Merged/);
+  assert.match(sql, /Split/);
+  assert.doesNotMatch(sql, /Question/);
+});
+
+// ── ④ 服务层分桶（注入假查询，不连库）──
+function stubDb(dbPath, realDb) {
+  const wmsId = 15038426;
+  // 重构后服务层是「一趟取回窗口内全部订单，Node 侧分桶」，
+  // 所以 stub 要返回**明细行**而不是聚合行。三态各造几条：
+  //   · 超时未发 3 单 / 合计 300
+  //   · 已发但超时 1 单（send_date 晚于 16:00）
+  //   · 按时 6 单（send_date 早于 16:00）
+  const mk = (sendDate, amount, oId) => ({
+    src: 'jst_Orders',
+    wms_co_id: wmsId,
+    o_id: oId,
+    so_id: String(oId),
+    shop_name: '测试店',
+    order_date: '2026-10-20 01:00:00',
+    send_date: sendDate,
+    status: 'Delivering',
+    shop_status: '',
+    pay_amount: amount,
+    labels: '',
+    ob_io_date: null,
+  });
+
+  const stubRows = [
+    mk(null, 100, 1), mk(null, 100, 2), mk(null, 100, 3),
+    mk('2026-10-20 18:30:00', 50, 4),
+    mk('2026-10-20 09:00:00', 100, 5), mk('2026-10-20 09:00:00', 100, 6),
+    mk('2026-10-20 10:00:00', 100, 7), mk('2026-10-20 10:00:00', 100, 8),
+    mk('2026-10-20 11:00:00', 100, 9), mk('2026-10-20 11:00:00', 100, 10),
+  ];
+
+  // 记录业务表被查了几次 —— 12:00 前应当为 0
+  // ⚠️ 现在是**两表并行分别查**（jst_Orders + jst_qmcust_orderlist），
+  //    所以两表都返回同一批 stubRows；服务层按 o_id 去重后仍应算 10 条，
+  //    这也顺带验证了「跨表同 o_id 去重」逻辑。
+  const calls = { order: 0 };
+  require.cache[dbPath] = {
+    id: dbPath,
+    filename: dbPath,
+    loaded: true,
+    exports: {
+      query: async (sql) => {
+        if (/jst_warehouseInfo/u.test(sql)) {
+          return [{ Id: 1, name: '简尚-崔桥工厂仓', wms_co_id: wmsId }];
+        }
+        if (/jst_salesOutboundInfo/u.test(sql) && /MAX\(io_date\)/u.test(sql)) {
+          // 新鲜度查询：返回空，走 stale 分支也不影响主结果
+          return [{ outbound_max: '2026-10-19 23:00:00' }];
+        }
+        calls.order += 1;
+        return stubRows;
+      },
+    },
+  };
+  void realDb;
+  return { calls, wmsId };
+}
+
+test('服务层三态分桶互斥，按时率不为负', async () => {
+  const dbPath = require.resolve('../src/config/cloudDatabase');
+  const realDb = require.cache[dbPath];
+  stubDb(dbPath, realDb);
+  delete require.cache[require.resolve('../src/services/warehouseShipTimelinessService')];
+  delete require.cache[require.resolve('../src/services/warehouseShipTimelinessRegistry')];
+
+  try {
+    const svc = require('../src/services/warehouseShipTimelinessService');
+    const data = await svc.getShipTimeliness({ now: at(16, 5), limit: 10 });
+    const c = data.centers.find((x) => x.key === 'CQ');
+    assert.ok(c, '应能归到崔桥工厂仓');
+    assert.equal(c.overdueUnshipped, 3);
+    assert.equal(c.overdueShipped, 1);
+    assert.equal(c.windowOrderCount, 10, '总数 = pending + shippedLate + onTime');
+    assert.equal(c.onTimeRate, 60, '按时 6/10 = 60%（跨表重复 o_id 必须去重，否则总数会翻倍）');
+
+    // 汇总口径与各仓一致，且按时率不会是负数
+    assert.equal(data.summary.overdueUnshipped, 3);
+    assert.equal(data.summary.windowOrderCount, 10);
+    assert.equal(data.summary.onTimeRate, 60);
+    assert.ok(data.summary.onTimeRate >= 0);
+
+    // 前端要展示「核验 16:00 前」，round 必须带出 windowEnd ——
+    // 只回 key/label 的话页面会渲染成「核验 前」（2026-10-20 真渲染时抓到）
+    assert.ok(data.round, 'round 不能为空');
+    assert.equal(data.round.key, 'AFTERNOON');
+    assert.equal(data.round.cutoffHour, 16);
+    assert.match(String(data.round.windowEnd), /16:00:00$/, 'round.windowEnd 必须带出截止时刻');
+  } finally {
+    // 还原，避免污染同进程内其它测试
+    if (realDb) require.cache[dbPath] = realDb;
+    else delete require.cache[dbPath];
+    delete require.cache[require.resolve('../src/services/warehouseShipTimelinessService')];
+    delete require.cache[require.resolve('../src/services/warehouseShipTimelinessRegistry')];
+  }
+});
+
+test('服务层 12:00 前返回 notStarted，且不去查订单表', async () => {
+  const dbPath = require.resolve('../src/config/cloudDatabase');
+  const realDb = require.cache[dbPath];
+  const { calls } = stubDb(dbPath, realDb);
+  delete require.cache[require.resolve('../src/services/warehouseShipTimelinessService')];
+  delete require.cache[require.resolve('../src/services/warehouseShipTimelinessRegistry')];
+
+  try {
+    const svc = require('../src/services/warehouseShipTimelinessService');
+    const data = await svc.getShipTimeliness({ now: at(9, 30), limit: 10 });
+    assert.equal(data.notStarted, true);
+    assert.equal(data.round, null);
+    assert.equal(data.orders.length, 0);
+    assert.equal(data.summary.overdueUnshipped, 0);
+    // 11 个主仓仍然列出来（结构不能塌），但数字全为 0
+    assert.equal(data.centers.length, registry.CENTERS.length);
+    assert.ok(data.centers.every((c) => c.overdueUnshipped === 0));
+    assert.equal(calls.order, 0, '未到核验时间不应扫订单表');
+    assert.match(data.note, /12:00/);
+    // 下一轮核验时刻要告诉前端，方便提示「12:00 开始」
+    assert.equal(data.nextRoundAt, '2026-10-20 12:00:00');
+  } finally {
+    if (realDb) require.cache[dbPath] = realDb;
+    else delete require.cache[dbPath];
+    delete require.cache[require.resolve('../src/services/warehouseShipTimelinessService')];
+    delete require.cache[require.resolve('../src/services/warehouseShipTimelinessRegistry')];
+  }
+});

deploy/production/README.md

@@ -0,0 +1,16 @@
+# 生产部署（Docker）
+
+生产实例使用 MySQL、Redis、Redis TLS 网关、Node.js 后端和部署注册服务容器。MySQL、后端与注册服务只监听内部网络或服务器回环地址；Nginx 暴露 `ck.yydd.ai:8443`，Redis TLS 网关暴露 `ck.yydd.ai:6380`。
+
+服务器目录约定：
+
+- `/opt/cangku/app`：仓库代码和前端构建结果
+- `/opt/cangku/shared`：权限为 `0700` 的环境配置
+- `/opt/cangku/data`：MySQL、Redis 和部署注册服务持久数据
+- `/www/wwwroot/cangku-acme`：Let's Encrypt HTTP-01 校验目录
+
+真实密码、JWT 密钥、部署 Key 和第三方数据库配置不得写入仓库。`mysql.env`、`redis.env`、`backend.env` 和 `bootstrap.env` 只在服务器生成并保持 `0600` 权限。
+
+SSH 隧道账号只接受由注册服务 CA 签发的短期证书，只允许转发到服务器 `127.0.0.1:3307`，并关闭终端、TTY、代理转发和密码认证。生产主机的 SSH 管理账号使用独立密钥，关闭密码登录。
+
+Redis 原始端口不映射到宿主机，容器以镜像内置的非特权 `redis` 用户运行。公网 `6380` 只接受 TLS，注册服务为每台设备创建独立 ACL 账号；停用安装会删除该账号。ACL 保存在 Redis 数据卷的 `users.acl`，注册与撤销后立即执行 `ACL SAVE`，容器重启不会丢失设备账号。证书文件应归属 HAProxy 容器的 `99:99` 并保持 `0600`，续期后需重新生成 `/opt/cangku/shared/redis-tls.pem`、恢复该属主并重启 TLS 网关。

deploy/production/build-frontend.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+FRONTEND_DIR="$REPO_DIR/frontend"
+SOURCE_GIT_FULL_SHA="$(cd "$REPO_DIR" && git rev-parse HEAD)"
+SOURCE_GIT_SHA="$(cd "$REPO_DIR" && git rev-parse --short HEAD)"
+SOURCE_GIT_REF="$(cd "$REPO_DIR" && git symbolic-ref --quiet --short HEAD 2>/dev/null || true)"
+SOURCE_GIT_REF="${SOURCE_GIT_REF:-main}"
+
+test -f "$FRONTEND_DIR/package-lock.json" || {
+  echo 'frontend/package-lock.json 不存在，停止构建' >&2
+  exit 1
+}
+
+docker run --rm \
+  -e "SOURCE_GIT_SHA=$SOURCE_GIT_SHA" \
+  -e "SOURCE_GIT_FULL_SHA=$SOURCE_GIT_FULL_SHA" \
+  -e "SOURCE_GIT_REF=$SOURCE_GIT_REF" \
+  -v "$FRONTEND_DIR:/host-frontend" \
+  node:22-bookworm-slim \
+  sh -lc '
+    set -eu
+    mkdir -p /workspace
+    tar -C /host-frontend --exclude=node_modules --exclude=dist -cf - . | tar -C /workspace -xf -
+    cd /workspace
+    npm ci --no-audit --no-fund
+    npm run build
+    mkdir -p /host-frontend/dist
+    find /host-frontend/dist -mindepth 1 -delete
+    cp -a /workspace/dist/. /host-frontend/dist/
+  '
+
+node - "$FRONTEND_DIR/dist/__build_version__.json" "$SOURCE_GIT_FULL_SHA" <<'NODE'
+const fs = require('node:fs');
+const [versionPath, expectedSha] = process.argv.slice(2);
+const metadata = JSON.parse(fs.readFileSync(versionPath, 'utf8'));
+if (metadata.sourceGitFullSha !== expectedSha) {
+  throw new Error(`前端构建 SHA 不匹配：${metadata.sourceGitFullSha} != ${expectedSha}`);
+}
+process.stdout.write(`前端构建已验证：${metadata.version}\n`);
+NODE

deploy/production/docker-compose.yml

@@ -0,0 +1,117 @@
+name: cangku
+
+services:
+  mysql:
+    image: mysql:8.0.39
+    container_name: cangku-mysql
+    restart: unless-stopped
+    env_file:
+      - /opt/cangku/shared/mysql.env
+    command:
+      - --character-set-server=utf8mb4
+      - --collation-server=utf8mb4_unicode_ci
+    ports:
+      - 127.0.0.1:3307:3306
+    volumes:
+      - /opt/cangku/data/mysql:/var/lib/mysql
+      - ../../backend/database/init.sql:/docker-entrypoint-initdb.d/001-init.sql:ro
+      - ../../backend/database/summary_tables.sql:/docker-entrypoint-initdb.d/002-summary-tables.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -uroot -p$$MYSQL_ROOT_PASSWORD --silent"]
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 30s
+    networks:
+      - cangku-internal
+
+  redis:
+    image: redis:7.4-alpine
+    container_name: cangku-redis
+    restart: unless-stopped
+    user: "999:1000"
+    env_file:
+      - /opt/cangku/shared/redis.env
+    command: ["sh", "-c", "if [ ! -s /data/users.acl ]; then printf 'user default on >%s ~* +@all\\n' \"$$REDIS_PASSWORD\" > /data/users.acl; fi; exec redis-server --appendonly yes --save 60 1000 --aclfile /data/users.acl"]
+    volumes:
+      - /opt/cangku/data/redis:/data
+    healthcheck:
+      test: ["CMD-SHELL", "REDISCLI_AUTH=$$REDIS_PASSWORD redis-cli ping | grep -q PONG"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      start_period: 10s
+    networks:
+      - cangku-internal
+
+  redis-gateway:
+    image: haproxy:3.0-alpine
+    container_name: cangku-redis-gateway
+    restart: unless-stopped
+    ports:
+      - 6380:6380
+    volumes:
+      - ./haproxy-redis.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
+      - /opt/cangku/shared/redis-tls.pem:/usr/local/etc/haproxy/certs/redis.pem:ro,z
+    depends_on:
+      redis:
+        condition: service_healthy
+    networks:
+      - cangku-internal
+
+  backend:
+    build:
+      context: ../../backend
+      dockerfile: Dockerfile.production
+    container_name: cangku-backend
+    restart: unless-stopped
+    env_file:
+      - /opt/cangku/shared/backend.env
+    ports:
+      - 127.0.0.1:4090:4090
+    volumes:
+      - /opt/cangku/data/backend:/app/runtime
+    depends_on:
+      mysql:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "node", "-e", "const s=require('node:net').connect(4090,'127.0.0.1',()=>{s.end();process.exit(0)});s.setTimeout(3000,()=>process.exit(1));s.on('error',()=>process.exit(1))"]
+      interval: 10s
+      timeout: 5s
+      retries: 18
+      start_period: 30s
+    networks:
+      - cangku-internal
+
+  bootstrap:
+    build:
+      context: ../../remote-access/server
+      dockerfile: Dockerfile.production
+    container_name: cangku-bootstrap
+    restart: unless-stopped
+    env_file:
+      - /opt/cangku/shared/bootstrap.env
+    ports:
+      - 127.0.0.1:4092:4092
+    volumes:
+      - /opt/cangku/data/bootstrap:/var/lib/cangku-bootstrap
+      - /etc/ssh/ssh_host_ed25519_key.pub:/etc/ssh/ssh_host_ed25519_key.pub:ro
+    depends_on:
+      mysql:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:4092/health', timeout=3)"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 10s
+    networks:
+      - cangku-internal
+
+networks:
+  cangku-internal:
+    name: cangku-internal

deploy/production/haproxy-redis.cfg

@@ -0,0 +1,16 @@
+global
+    log stdout format raw local0
+
+defaults
+    log global
+    mode tcp
+    timeout connect 5s
+    timeout client 1h
+    timeout server 1h
+
+frontend redis_tls
+    bind *:6380 ssl crt /usr/local/etc/haproxy/certs/redis.pem ssl-min-ver TLSv1.2
+    default_backend redis_plain
+
+backend redis_plain
+    server redis redis:6379 check

deploy/production/nginx-ck.yydd.ai.conf

@@ -0,0 +1,69 @@
+server {
+    listen 80;
+    server_name ck.yydd.ai;
+
+    location ^~ /.well-known/acme-challenge/ {
+        root /www/wwwroot/cangku-acme;
+        default_type text/plain;
+    }
+
+    location / {
+        return 308 https://$host:8443$request_uri;
+    }
+}
+
+server {
+    listen 8443 ssl http2;
+    server_name ck.yydd.ai;
+
+    ssl_certificate /etc/letsencrypt/live/ck.yydd.ai/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/ck.yydd.ai/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_session_cache shared:CangkuTLS:10m;
+    ssl_session_timeout 1d;
+
+    root /opt/cangku/app/frontend/dist;
+    index index.html;
+    client_max_body_size 100m;
+
+    add_header X-Content-Type-Options nosniff always;
+    add_header Referrer-Policy strict-origin-when-cross-origin always;
+
+    location = /health {
+        proxy_pass http://127.0.0.1:4090/health;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+
+    location = /v1/enroll {
+        limit_except POST { deny all; }
+        proxy_pass http://127.0.0.1:4092/v1/enroll;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+    }
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:4090;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+    }
+
+    location /cubejs-api/ {
+        proxy_pass http://127.0.0.1:4090;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto https;
+    }
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

docs/库存流水单据表需求.md

@@ -0,0 +1,101 @@
+# 业务库补表需求：每日进销存流水
+
+> 提给：DBA / 聚水潭数据同步负责人
+> 提出方：仓库系统（cangku）· 大货库存监控 → 每日进销存
+> 日期：2026-09-24
+
+## 背景
+
+「每日进销存」页面需要按仓库展示 26 个仓的日内进销存流水，表头 21 列：
+
+| # | 列 | # | 列 |
+|---|---|---|---|
+| 1 | 仓库 | 12 | 销售退货 |
+| 2 | 期初数量 | 13 | 调拨入 |
+| 3 | 加工进仓 | 14 | 期初(2) |
+| 4 | 采购退货 | 15 | 其它出库 |
+| 5 | 采购进仓 | 16 | 期末数量 |
+| 6 | 其它进仓 | 17 | 库存周转天数 |
+| 7 | 其它退货 | 18 | 滞销预警级库存量 |
+| 8 | 销售出仓 | 19 | 商品慢流级库存量 |
+| 9 | 盘点 | 20 | 商品呆滞级库存量 |
+| 10 | 加工出仓 | 21 | 商品僵尸级库存量 |
+| 11 | 调拨出 | | |
+
+其中 1、16~21 列已能从业务库算出（见下表「已具备」），**2~15 列目前无法从业务库还原**。
+
+## 已具备（无需补表）
+
+| 列 | 来源 | 说明 |
+|---|---|---|
+| 仓库 | `rpt.jst_warehouseInfo` | `wms_co_id` 与仓库名映射 |
+| 期末数量 | `rpt.jst_inventoryInfo` | 按 `wms_co_id` 单仓 `SUM(qty)`，实时 |
+| 库存周转天数 | 近 30 天发货 ÷ 实时库存 | `jst_OrderItem` × `jst_Orders`（`send_date`） |
+| 四级库存量 | 实时库存 × 发货 × `pm_stockMonitor.created` | 库龄 = 基准时刻 − SKU 建档时间 |
+
+## 缺口一：没有按天的历史库存结存表（阻塞「期初数量」）
+
+`rpt.jst_inventoryInfo` 只有**当前**库存，没有历史版本；`rpt.pm_stockMonitor` 是「归属仓」口径的每日快照（`jsStock`），与实物库存口径不一致（崔桥 115135 vs 实物 92439），不能当结存用。
+
+**现状的临时方案**：项目本地 MySQL 建了 `daily_inventory_snapshot` 表，每天 01:30 把 26 仓实时库存落一份快照，`今日期初 = 昨日快照`。这是自采数据，一旦任务漏跑就会断链。
+
+**请求**：请提供按天、按仓、按 SKU 的库存结存表，形如：
+
+```
+jst_inventoryDaily(
+  biz_date   DATE,      -- 业务日
+  wms_co_id  BIGINT,    -- 仓库
+  sku_id     VARCHAR,   -- SKU
+  qty        DECIMAL,   -- 当日结存
+  ...
+)
+```
+
+有了它，「期初数量」即可直接取上一业务日结存，本地快照表可退役。
+
+## 缺口二：缺少 4 类单据表（阻塞 12 个流水列）
+
+业务库 `rpt` 下已排查过全部 220 张表，**不存在**以下单据：
+
+| 缺失单据 | 影响的列 |
+|---|---|
+| 调拨单（调拨出 / 调拨入） | 调拨出、调拨入 |
+| 盘点单 | 盘点 |
+| 加工单（加工进仓 / 加工出仓） | 加工进仓、加工出仓 |
+| 其它出入库单 | 其它进仓、其它退货、其它出库、期初(2) |
+
+请补充按单据行（SKU 级）的明细表，至少包含：
+
+```
+业务日期 / 单据号 / 仓库 wms_co_id / sku_id / 数量 / 单据类型(出|入) / 状态
+```
+
+## 缺口三：已有单据的数值与进销存口径不一致（阻塞 销售出仓 / 采购进仓 / 采购退货 / 销售退货）
+
+这 4 类单据表**存在**，但按天汇总后与聚水潭进销存导出的数值对不上，不能直接用：
+
+| 列 | 现有来源 | 9-23 崔桥工厂仓实测 | 基准值 | 偏差 |
+|---|---|---:|---:|---|
+| 销售出仓 | `jst_OrderItem` × `jst_Orders` 按 `send_date` | 1,769 | 4,273 | **−59%** |
+| 销售出仓 | 同上，按 `order_date` | 1,723 | 4,273 | −60% |
+| 销售出仓 | 同上，按 `modified` | 5,471 | 4,273 | +28% |
+| 采购进仓 | `jst_purchaseItem.inQty` × `jst_purchase` 按 `confirm_date` | 数百 | 1,295 | 严重偏低 |
+
+其它已排除的候选：
+
+- `rpt.jst_salesOutboundInfo`：`qty` 全为 0，且 `order_type` 只含销售类订单，不含调拨 / 其它出库。
+- `rpt.jst_originalBillInfo`（1,500 万行）：是支付宝 / 财务账单表（`channel=alipayCSV`、`fee_name=交易收款`、`sku_id` 为 null），与库存流水无关。
+- `rpt.jst_qmcust_salesoutbound`（奇门出库单）：非本业务口径。
+
+**请求**：确认这 4 类表在报表库（JSReportReplica）的同步是否完整、以及「进销存导出」所用的日期字段是哪一个（发 / 审 / 确 / 记账）。给出字段口径后这 4 列即可接入。
+
+## 验收标准
+
+补表后，任一业务日应满足行内恒等式：
+
+```
+期末数量 = 期初数量 + 加工进仓 + 采购进仓 + 其它进仓 + 其它退货 + 销售退货 + 调拨入
+          − 采购退货 − 销售出仓 − 盘点 − 加工出仓 − 调拨出 − 其它出库
+```
+
+页面会以该恒等式做逐仓自校验，全部通过后才会撤下「暂缺单据来源」的提示。