From 74e53d4d87b1f027ade293e9d7d9e17059db556c Mon Sep 17 00:00:00 2001 From: liufumingren Date: Tue, 15 Sep 2026 18:19:57 +0800 Subject: [PATCH] =?UTF-8?q?feat(order):=20=E6=96=B0=E5=A2=9E=E9=85=8D?= =?UTF-8?q?=E9=80=81=E8=A1=A8=E8=B6=85=E6=9C=9F=E8=AE=A2=E5=8D=95=E5=BD=92?= =?UTF-8?q?=E6=A1=A3=E5=88=B0=E5=8E=86=E5=8F=B2=E8=A1=A8=E5=AE=9A=E6=97=B6?= =?UTF-8?q?=E4=BB=BB=E5=8A=A1=20-=20=E6=96=B0=E5=A2=9E=20systems/orderDeli?= =?UTF-8?q?veryArchive=EF=BC=88app/service/systems/order=5Fdelivery=5Farch?= =?UTF-8?q?ive.js=EF=BC=89=EF=BC=9A=20=20=20=E6=8A=8A=20wms=5Forder=5Fdeli?= =?UTF-8?q?very=5F{=E4=BB=93=E5=BA=93}=5Fdispatch=20=E4=B8=AD=20dispath=5F?= =?UTF-8?q?time=20=E8=B7=9D=E4=BB=8A=E8=B6=85=E8=BF=87=203=20=E4=B8=AA?= =?UTF-8?q?=E6=9C=88=E3=80=81=E6=88=96=20create=5Fat=20=20=20=E8=B7=9D?= =?UTF-8?q?=E4=BB=8A=E8=B6=85=E8=BF=87=204=20=E4=B8=AA=E6=9C=88=E7=9A=84?= =?UTF-8?q?=E8=AE=A2=E5=8D=95=EF=BC=88=E4=B8=8D=E9=99=90=E7=8A=B6=E6=80=81?= =?UTF-8?q?=EF=BC=89=E5=BD=92=E6=A1=A3=E5=88=B0=20=5Fhistory=20=E5=88=86?= =?UTF-8?q?=E8=A1=A8=EF=BC=9Bdispath=5Ftime=20=E4=B8=BA=20NULL=20=E7=9A=84?= =?UTF-8?q?=E5=AD=98=E9=87=8F=20=20=20=E8=AE=A2=E5=8D=95=E4=B8=8D=E7=89=B9?= =?UTF-8?q?=E6=AE=8A=E5=A4=84=E7=90=86=EF=BC=8CSQL=20=E4=B8=89=E5=80=BC?= =?UTF-8?q?=E9=80=BB=E8=BE=91=E4=B8=8B=E8=87=AA=E5=8A=A8=E7=94=B1=20create?= =?UTF-8?q?=5Fat=20=E6=9D=A1=E4=BB=B6=E5=85=9C=E5=BA=95=20-=20=E5=8D=95?= =?UTF-8?q?=E6=89=B9=E9=BB=98=E8=AE=A4=201000=20=E6=9D=A1=E3=80=81?= =?UTF-8?q?=E4=B8=80=E4=B8=AA=E4=BA=8B=E5=8A=A1=E5=86=85=E5=AE=8C=E6=88=90?= =?UTF-8?q?=EF=BC=9A=E5=86=99=E5=8E=86=E5=8F=B2=E8=A1=A8=EF=BC=88=E5=89=94?= =?UTF-8?q?=E9=99=A4=E5=8E=86=E5=8F=B2=E8=A1=A8=E4=B8=8D=E5=AD=98=E5=9C=A8?= =?UTF-8?q?=E7=9A=84=20=20=20dispatch=5Flane/dispath=5Ftime=E3=80=81?= =?UTF-8?q?=E5=86=99=20archive=5Ftime=3D=E5=BD=92=E6=A1=A3=E6=97=B6?= =?UTF-8?q?=E5=88=BB=E3=80=81id=20=E5=8E=9F=E6=A0=B7=E5=A4=8D=E5=88=B6?= =?UTF-8?q?=EF=BC=89=E2=86=92=20=E5=90=8C=E6=AD=A5=E5=A4=8D=E5=88=B6=20=20?= =?UTF-8?q?=20wms=5Forder=5Fitems=5F*=5Fdispatch=20=E5=95=86=E5=93=81?= =?UTF-8?q?=E6=98=8E=E7=BB=86=EF=BC=88=E8=A1=A5=20archive=5Ftime=EF=BC=89?= =?UTF-8?q?=E2=86=92=20=E6=9B=B4=E6=96=B0=E8=AE=A2=E5=8D=95=E7=B4=A2?= =?UTF-8?q?=E5=BC=95=E8=A1=A8=20=20=20wms=5Forder=5Fid=5Flocation=5F*=20?= =?UTF-8?q?=E7=9A=84=20location=20=E4=B8=BA=20history=20=E2=86=92=20?= =?UTF-8?q?=E5=88=A0=E9=99=A4=E6=BA=90=E8=A1=8C=EF=BC=88=E5=85=88=E5=AD=90?= =?UTF-8?q?=E8=A1=A8=E5=90=8E=E4=B8=BB=E8=A1=A8=EF=BC=89=EF=BC=8C=E4=BB=BB?= =?UTF-8?q?=E4=B8=80=E6=AD=A5=20=20=20=E5=A4=B1=E8=B4=A5=E6=95=B4=E4=BD=93?= =?UTF-8?q?=E5=9B=9E=E6=BB=9A=EF=BC=8C=E4=B8=8D=E4=BA=A7=E7=94=9F=E3=80=8C?= =?UTF-8?q?=E5=8E=86=E5=8F=B2=E8=A1=A8=E6=9C=89=E6=95=B0=E6=8D=AE=E4=BD=86?= =?UTF-8?q?=E9=85=8D=E9=80=81=E8=A1=A8=E6=B2=A1=E5=88=A0=E3=80=8D=E7=9A=84?= =?UTF-8?q?=E4=B8=AD=E9=97=B4=E6=80=81=20-=20=E5=8F=AF=E7=BB=AD=E8=B7=91?= =?UTF-8?q?=20/=20=E9=98=B2=E4=B8=AD=E6=96=AD=EF=BC=9A=E6=89=B9=E9=87=8F?= =?UTF-8?q?=E6=8F=90=E4=BA=A4=E4=B8=94=E6=8F=90=E4=BA=A4=E5=8D=B3=E5=88=A0?= =?UTF-8?q?=E9=99=A4=E6=BA=90=E8=A1=8C=EF=BC=8C=E9=87=8D=E8=B7=91=E5=A4=A9?= =?UTF-8?q?=E7=84=B6=E5=B9=82=E7=AD=89=EF=BC=9B=E5=AE=9E=E9=99=85=E6=9D=A1?= =?UTF-8?q?=E4=BB=B6=E5=88=97=20=20=20=EF=BC=88create=5Fat/dispath=5Ftime?= =?UTF-8?q?=EF=BC=89=E6=97=A0=E7=B4=A2=E5=BC=95=EF=BC=8C=E6=95=85=E6=8C=89?= =?UTF-8?q?=E4=B8=BB=E9=94=AE=20id=20=E6=B8=B8=E6=A0=87=E5=8F=96=E5=80=99?= =?UTF-8?q?=E9=80=89=E3=80=81=E7=A6=81=E7=94=A8=20OFFSET=EF=BC=9B=E5=8D=95?= =?UTF-8?q?=E6=89=B9=E9=81=87=20=20=20=E6=AD=BB=E9=94=81/=E9=94=81?= =?UTF-8?q?=E7=AD=89=E5=BE=85=E9=87=8D=E8=AF=95=203=20=E6=AC=A1=E5=90=8E?= =?UTF-8?q?=E8=B7=B3=E8=BF=87=E8=AF=A5=E6=89=B9=E5=B9=B6=E6=8E=A8=E8=BF=9B?= =?UTF-8?q?=E6=B8=B8=E6=A0=87=EF=BC=88=E4=B8=8A=E6=8A=A5=20failedBatches/f?= =?UTF-8?q?ailedCount=EF=BC=89=EF=BC=8C=20=20=20=E4=B8=8D=E4=B8=AD?= =?UTF-8?q?=E6=96=AD=E6=95=B4=E8=BD=AE=EF=BC=9B=E5=8D=95=E8=BD=AE=E6=97=B6?= =?UTF-8?q?=E9=95=BF=E9=A2=84=E7=AE=97=20maxRunMs=20=E7=94=A8=E5=B0=BD?= =?UTF-8?q?=E5=8D=B3=E5=81=9C=E6=AD=A2=E6=9C=AC=E8=BD=AE=EF=BC=8C=E5=89=A9?= =?UTF-8?q?=E4=BD=99=E8=AE=A2=E5=8D=95=E4=B8=8B=E4=B8=80=E8=BD=AE=E7=BB=A7?= =?UTF-8?q?=E7=BB=AD=20-=20=E5=8E=86=E5=8F=B2=E8=A1=A8=E5=B7=B2=E5=AD=98?= =?UTF-8?q?=E5=9C=A8=E5=90=8C=20id=20=E8=AE=B0=E5=BD=95=EF=BC=88=E5=8E=86?= =?UTF-8?q?=E5=8F=B2=E6=AE=8B=E7=95=99/=E4=BA=BA=E5=B7=A5=E8=A1=A5?= =?UTF-8?q?=E6=95=B0=EF=BC=89=E6=97=B6=E4=B8=8D=E9=87=8D=E5=A4=8D=E5=86=99?= =?UTF-8?q?=E5=85=A5=E4=BD=86=E4=BB=8D=E6=B8=85=E7=90=86=E6=BA=90=E8=A1=8C?= =?UTF-8?q?=EF=BC=8C=E4=BF=9D=E8=AF=81=E9=87=8D=E5=A4=8D=20=20=20=E6=89=A7?= =?UTF-8?q?=E8=A1=8C=E7=BB=93=E6=9E=9C=E4=B8=80=E8=87=B4=20-=20=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=20app/schedule/archive=5Fdispatch=5Forders=5Fto=5Fhis?= =?UTF-8?q?tory.js=EF=BC=9A=E9=BB=98=E8=AE=A4=E6=AF=8F=E6=97=A5=2006:00=20?= =?UTF-8?q?=E5=8D=95=20worker=20=20=20=E6=89=A7=E8=A1=8C=EF=BC=88cron=20?= =?UTF-8?q?=E5=8F=AF=E9=85=8D=EF=BC=89=EF=BC=8CRedis=20SET=20NX=20EX=20?= =?UTF-8?q?=E8=B7=A8=E8=BF=9B=E7=A8=8B=E4=BA=92=E6=96=A5=EF=BC=88=E8=BF=9B?= =?UTF-8?q?=E7=A8=8B=E8=A2=AB=E6=9D=80=E9=9D=A0=20TTL=20=E9=87=8A=E6=94=BE?= =?UTF-8?q?=EF=BC=89+=20=E6=89=B9=E7=BA=A7=E8=BF=9B=E5=BA=A6=20=20=20?= =?UTF-8?q?=E7=BC=93=E5=AD=98=20+=20=E6=89=A7=E8=A1=8C=E6=97=A5=E5=BF=97?= =?UTF-8?q?=E7=BC=93=E5=AD=98=EF=BC=8C=E4=B8=8A=E4=B8=80=E8=BD=AE=20status?= =?UTF-8?q?=3Drunning=20=E6=97=B6=E6=8C=89=E6=96=AD=E7=82=B9=E7=BB=AD?= =?UTF-8?q?=E8=B7=91=20-=20=E6=96=B0=E5=A2=9E=20config.orderDeliveryArchiv?= =?UTF-8?q?e=20=E9=85=8D=E7=BD=AE=EF=BC=9A=E5=BC=80=E5=85=B3/cron/?= =?UTF-8?q?=E5=BD=92=E6=A1=A3=E9=97=A8=E6=A7=9B=E6=9C=88=E6=95=B0/?= =?UTF-8?q?=E5=8D=95=E6=89=B9=E6=9D=A1=E6=95=B0/=E5=8D=95=E4=BB=93?= =?UTF-8?q?=E6=89=B9=E6=AC=A1=20=20=20=E4=B8=8A=E9=99=90/=E5=8D=95?= =?UTF-8?q?=E8=BD=AE=E6=97=B6=E9=95=BF=E9=A2=84=E7=AE=97/=E6=9F=A5?= =?UTF-8?q?=E8=AF=A2=E8=B6=85=E6=97=B6/=E9=87=8D=E8=AF=95=E6=AC=A1?= =?UTF-8?q?=E6=95=B0/=E9=94=81=20TTL=20-=20=E6=9C=AC=E5=9C=B0=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E5=BA=93=E5=AE=9E=E6=B5=8B=2044=20=E9=A1=B9=E6=96=AD?= =?UTF-8?q?=E8=A8=80=E5=85=A8=E9=83=A8=E9=80=9A=E8=BF=87=EF=BC=9A=E5=AD=97?= =?UTF-8?q?=E6=AE=B5=E4=BF=9D=E7=9C=9F=EF=BC=88=E8=AE=A2=E5=8D=95=E4=B8=8E?= =?UTF-8?q?=E6=98=8E=E7=BB=86=E9=80=90=E5=88=97=E4=B8=80=E8=87=B4=E3=80=81?= =?UTF-8?q?archive=5Ftime=20=20=20=E6=AD=A3=E7=A1=AE=E3=80=81=E6=97=A0=20d?= =?UTF-8?q?ispatch=5Flane/dispath=5Ftime=E3=80=81id=20=E5=8E=9F=E6=A0=B7?= =?UTF-8?q?=E5=A4=8D=E5=88=B6=EF=BC=89=E3=80=81=E7=B4=A2=E5=BC=95=E8=A1=A8?= =?UTF-8?q?=E4=BD=8D=E7=BD=AE=E6=9B=B4=E6=96=B0=E3=80=81=E6=BA=90=E8=A1=8C?= =?UTF-8?q?=E5=88=A0=E9=99=A4=E3=80=81=20=20=20=E5=B9=82=E7=AD=89=E5=A4=8D?= =?UTF-8?q?=E8=B7=91=E3=80=81=E6=B3=A8=E5=85=A5=E5=A4=B1=E8=B4=A5=E6=95=B4?= =?UTF-8?q?=E6=89=B9=E5=9B=9E=E6=BB=9A=E3=80=81=E5=8D=95=E6=89=B9=E5=A4=B1?= =?UTF-8?q?=E8=B4=A5=E5=90=8E=E7=BB=A7=E7=BB=AD=E3=80=81=E9=99=90=E9=A2=9D?= =?UTF-8?q?=E7=94=A8=E5=B0=BD=E5=90=8E=E9=87=8D=E8=B7=91=E7=BB=AD=E4=BC=A0?= =?UTF-8?q?=E3=80=81=E9=A2=84=E7=AE=97=E7=94=A8=E5=B0=BD=E5=81=9C=E6=AD=A2?= =?UTF-8?q?=E3=80=81=20=20=20=E6=97=A0=E5=90=8C=20id=20=E5=8F=8C=E5=86=99?= =?UTF-8?q?=E4=B8=8E=E5=AD=A4=E7=AB=8B=E6=98=8E=E7=BB=86=E6=AE=8B=E7=95=99?= =?UTF-8?q?=EF=BC=9BEgg=20=E5=B7=B2=E6=AD=A3=E7=A1=AE=E6=B3=A8=E5=86=8C?= =?UTF-8?q?=E8=AF=A5=E5=AE=9A=E6=97=B6=E4=BB=BB=E5=8A=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../archive_dispatch_orders_to_history.js | 384 +++++++++ app/service/systems/order_delivery_archive.js | 795 ++++++++++++++++++ config/config.default.js | 24 + 3 files changed, 1203 insertions(+) create mode 100644 app/schedule/archive_dispatch_orders_to_history.js create mode 100644 app/service/systems/order_delivery_archive.js diff --git a/app/schedule/archive_dispatch_orders_to_history.js b/app/schedule/archive_dispatch_orders_to_history.js new file mode 100644 index 0000000..27909cc --- /dev/null +++ b/app/schedule/archive_dispatch_orders_to_history.js @@ -0,0 +1,384 @@ +// app/schedule/archive_dispatch_orders_to_history.js +'use strict'; + +/** + * 配送表订单归档到历史表定时任务。 + * + * 默认每日凌晨 06:00:00(cron:秒 分 时 日 月 周)在单 worker 中执行一次, + * 把 `wms_order_delivery_{仓库}_dispatch` 中创建时间距今超过 4 个月 + * (或迁移进配送表时间距今超过 3 个月)的订单,连同商品明细一起归档到 + * `_history` 分表,并同步更新订单索引表 `wms_order_id_location_{仓库}` 的位置指针。 + * + * cron / 开关从 config.orderDeliveryArchive 读取(config.default.js 提供默认值), + * 本地环境可在 config.local.js 覆盖为短间隔以便快速验证,不影响生产 06:00 触发时间。 + * + * 中断与重跑安全(本任务每日只跑一轮,必须具备"断了也能接着跑"的性质): + * 1. 单批一个事务:写入历史表 + 更新位置指针 + 删除源行 全部成功或全部回滚, + * 不会出现"历史表有数据但配送表没删"的中间态; + * 2. 已迁移的行在提交时即从配送表删除,重新执行时查询不会命中 → 天然幂等续跑; + * 3. 单批失败(死锁等重试耗尽)只跳过该批并推进游标,不中断整轮,未迁移的行留待下一轮; + * 4. 跨进程互斥用 Redis 锁(NX + TTL),进程被杀后锁到期自动释放,下一轮可继续; + * 5. 每批进度写入 Redis(progress key),日志与进度缓存均可观察"跑到哪、迁了多少"。 + */ + + +/** 执行记录缓存 key(最近一次执行) */ +const EXECUTION_LOG_CACHE_KEY = 'schedule:archive_dispatch_to_history:last_execution'; +/** 执行记录缓存 TTL(秒) */ +const EXECUTION_LOG_CACHE_TTL = 300; +/** 执行历史缓存 key(保留最近 N 次) */ +const EXECUTION_LOG_HISTORY_CACHE_KEY = 'schedule:archive_dispatch_to_history:history'; +/** 执行历史保留条数 */ +const EXECUTION_LOG_HISTORY_MAX = 20; +/** 执行历史缓存 TTL(秒) */ +const EXECUTION_LOG_HISTORY_TTL = 86400; +/** 跨进程互斥锁 key */ +const LOCK_CACHE_KEY = 'schedule:archive_dispatch_to_history:lock'; +/** 进度缓存 key(供人工观察断点位置) */ +const PROGRESS_CACHE_KEY = 'schedule:archive_dispatch_to_history:progress'; +/** 进度缓存 TTL(秒):保留 2 天,便于次日对比上一轮跑到哪里 */ +const PROGRESS_CACHE_TTL = 2 * 24 * 60 * 60; +/** 默认 cron:每日凌晨 06:00 */ +const DEFAULT_CRON = '0 0 6 * * *'; +/** 默认互斥锁 TTL(秒),需覆盖单轮最长执行时间 */ +const DEFAULT_LOCK_TTL_SECONDS = 30 * 60; + +/** + * 获取 Redis cache 客户端。 + * + * @param {Object} app Egg 应用实例。 + * @return {Object|null} Redis 客户端或 null。 + */ +function getCacheRedisClient(app) { + if (!app || !app.redis || typeof app.redis.get !== 'function') { + return null; + } + + try { + return app.redis.get('cache') || null; + } catch (error) { + return null; + } +} + +/** + * 获取互斥锁(SET NX EX)。 + * + * @param {Object} ctx Egg 上下文。 + * @param {number} ttlSeconds 锁 TTL(秒)。 + * @return {Promise} 是否获取成功;Redis 不可用时返回 true(退化为进程内防重入)。 + */ +async function acquireLock(ctx, ttlSeconds) { + const redis = getCacheRedisClient(ctx.app); + + if (!redis || typeof redis.set !== 'function') { + ctx.logger.warn('[archive-dispatch-to-history] Redis 不可用,跨进程互斥降级为进程内防重入'); + return true; + } + + try { + const result = await redis.set(LOCK_CACHE_KEY, String(process.pid || ''), 'EX', ttlSeconds, 'NX'); + return result === 'OK'; + } catch (error) { + ctx.logger.warn(`[archive-dispatch-to-history] 获取互斥锁失败(按未加锁继续): ${error.message}`); + return true; + } +} + +/** + * 释放互斥锁。 + * + * @param {Object} ctx Egg 上下文。 + * @return {Promise} 无返回值。 + */ +async function releaseLock(ctx) { + const redis = getCacheRedisClient(ctx.app); + + if (!redis || typeof redis.del !== 'function') { + return; + } + + try { + await redis.del(LOCK_CACHE_KEY); + } catch (error) { + ctx.logger.warn(`[archive-dispatch-to-history] 释放互斥锁失败(等待 TTL 过期): ${error.message}`); + } +} + +/** + * 写入进度缓存。 + * + * @param {Object} ctx Egg 上下文。 + * @param {Object} payload 进度内容。 + * @return {Promise} 无返回值。 + */ +async function writeProgress(ctx, payload) { + try { + if (ctx.app && typeof ctx.app.setCacheAsync === 'function') { + await ctx.app.setCacheAsync(PROGRESS_CACHE_KEY, { + ...payload, + updated_at: new Date().toISOString(), + }, PROGRESS_CACHE_TTL); + } + } catch (error) { + ctx.logger.warn(`[archive-dispatch-to-history] 写入进度缓存失败: ${error.message}`); + } +} + +/** + * 读取上一轮进度缓存(用于识别"上一轮被中断")。 + * + * @param {Object} ctx Egg 上下文。 + * @return {Promise} 上一轮进度。 + */ +async function readProgress(ctx) { + try { + if (ctx.app && typeof ctx.app.getCacheAsync === 'function') { + const cached = await ctx.app.getCacheAsync(PROGRESS_CACHE_KEY); + return cached && typeof cached === 'object' ? cached : null; + } + } catch (error) { + ctx.logger.warn(`[archive-dispatch-to-history] 读取进度缓存失败: ${error.message}`); + } + + return null; +} + +/** + * 将本次执行日志写入缓存。 + * + * @param {Object} ctx Egg 上下文。 + * @param {Object} logEntry 日志条目。 + * @return {Promise} 无返回值。 + */ +async function writeExecutionLogToCache(ctx, logEntry) { + try { + if (ctx.app && typeof ctx.app.setCacheAsync === 'function') { + await ctx.app.setCacheAsync(EXECUTION_LOG_CACHE_KEY, logEntry, EXECUTION_LOG_CACHE_TTL); + } + } catch (error) { + ctx.logger.warn(`[archive-dispatch-to-history] 写入执行日志缓存失败: ${error.message}`); + } +} + +/** + * 将本次执行日志追加到历史记录缓存(保留最近 N 次)。 + * + * @param {Object} ctx Egg 上下文。 + * @param {Object} logEntry 日志条目。 + * @return {Promise} 无返回值。 + */ +async function appendExecutionHistory(ctx, logEntry) { + try { + if (typeof ctx.app.getCacheAsync !== 'function' || typeof ctx.app.setCacheAsync !== 'function') { + return; + } + + const rawHistory = await ctx.app.getCacheAsync(EXECUTION_LOG_HISTORY_CACHE_KEY); + const history = Array.isArray(rawHistory) ? rawHistory : []; + history.unshift(logEntry); + await ctx.app.setCacheAsync( + EXECUTION_LOG_HISTORY_CACHE_KEY, + history.slice(0, EXECUTION_LOG_HISTORY_MAX), + EXECUTION_LOG_HISTORY_TTL + ); + } catch (error) { + ctx.logger.warn(`[archive-dispatch-to-history] 写入执行历史缓存失败: ${error.message}`); + } +} + +/** + * 提取错误详情,方便定位问题位置。 + * + * @param {Error} error 错误对象。 + * @return {Object} 错误详情。 + */ +function extractErrorDetail(error) { + if (!error) return {}; + + const detail = { + name: error.name || '', + message: error.message || '', + code: error.code || '', + }; + + if (error.parent) { + detail.parent = { + name: error.parent.name || '', + message: error.parent.message || '', + code: error.parent.code || '', + sql: error.parent.sql || '', + }; + } + + if (error.stack) { + detail.stack_top = error.stack.split('\n').slice(0, 4).map(line => line.trim()); + } + + return detail; +} + +/** + * 每日凌晨 06:00 归档配送表超期订单到历史表。 + * + * @param {Object} app Egg 应用实例。 + * @return {Object} 定时任务定义(含 schedule 与 task)。 + */ +module.exports = app => { + const archiveConfig = (app.config && app.config.orderDeliveryArchive) || {}; + const archiveCron = typeof archiveConfig.cron === 'string' && archiveConfig.cron + ? archiveConfig.cron + : DEFAULT_CRON; + const lockTtlSeconds = Number(archiveConfig.lockTtlSeconds) > 0 + ? Number(archiveConfig.lockTtlSeconds) + : DEFAULT_LOCK_TTL_SECONDS; + + return { + schedule: { + cron: archiveCron, + type: 'worker', + immediate: false, + disable: archiveConfig.enable === false, + }, + + /** + * 执行配送表订单归档。 + * + * 任务失败只记录错误日志,不向上抛出,避免 schedule 崩溃; + * 未归档完成的订单保留在配送表,下一轮(或人工重跑)继续。 + * + * @param {Object} ctx Egg 上下文。 + * @return {Promise} 无返回值。 + */ + async task(ctx) { + const scheduleName = 'archive_dispatch_orders_to_history'; + + if (ctx.app._archiveDispatchOrdersToHistoryRunning) { + ctx.logger.info(`[${scheduleName}] 本轮任务跳过,上一轮尚未结束`); + return; + } + + const previousProgress = await readProgress(ctx); + if (previousProgress && previousProgress.status === 'running') { + ctx.logger.warn( + `[${scheduleName}] 检测到上一轮未正常结束(status=running, started_at=${previousProgress.started_at || '-'}),本轮按断点续跑:已迁移订单已从配送表移除,不会重复处理` + ); + } + + const lockAcquired = await acquireLock(ctx, lockTtlSeconds); + if (!lockAcquired) { + ctx.logger.info(`[${scheduleName}] 未获取到互斥锁,判定其他进程正在执行,本轮跳过`); + return; + } + + ctx.app._archiveDispatchOrdersToHistoryRunning = true; + + const startedAt = Date.now(); + const startedAtIso = new Date(startedAt).toISOString(); + let status = 'success'; + let errorMessage = ''; + let errorDetail = null; + let result = null; + + await writeProgress(ctx, { + status: 'running', + started_at: startedAtIso, + trigger: 'schedule', + pid: process.pid, + }); + + try { + result = await ctx.service.systems.orderDeliveryArchive.archiveDispatchOrdersToHistory({}, { + onBatch: async batch => { + await writeProgress(ctx, { + status: 'running', + started_at: startedAtIso, + trigger: 'schedule', + pid: process.pid, + warehouse_id: batch.warehouseId, + batch_index: batch.batchIndex, + last_id: batch.lastId, + total_selected: batch.summary.selectedCount, + total_archived: batch.summary.archivedCount, + total_items_archived: batch.summary.itemsArchivedCount, + failed_batches: batch.summary.failedBatches, + }); + }, + }); + + if (result.totalFailedBatches > 0) { + status = 'partial_failure'; + errorMessage = `failedBatches=${result.totalFailedBatches}, failedRows=${result.totalFailedCount}`; + ctx.logger.warn( + `[${scheduleName}] 本轮存在 ${result.totalFailedBatches} 个失败批次(共 ${result.totalFailedCount} 条订单未迁移),已跳过并保留在配送表,下一轮继续` + ); + } + + if (result.backlogRemaining) { + status = status === 'success' ? 'partial_budget_exhausted' : status; + ctx.logger.warn( + `[${scheduleName}] 单轮时长上限用尽,仍有仓库未处理完(elapsedMs=${result.elapsedMs}),剩余订单将在下一轮继续归档` + ); + } + + ctx.logger.info( + `[${scheduleName}] 本轮完成 archived=${result.totalArchived} alreadyArchived=${result.totalAlreadyArchived} itemsArchived=${result.totalItemsArchived} selected=${result.totalSelected} failedBatches=${result.totalFailedBatches} elapsedMs=${result.elapsedMs}` + ); + } catch (error) { + status = 'error'; + errorMessage = error.message; + errorDetail = extractErrorDetail(error); + ctx.logger.error(`[${scheduleName}] 归档失败: ${error.message}`, errorDetail); + } finally { + ctx.app._archiveDispatchOrdersToHistoryRunning = false; + await releaseLock(ctx); + } + + const logEntry = { + executed_at: new Date().toISOString(), + duration_ms: Date.now() - startedAt, + status, + error_message: errorMessage, + error_detail: errorDetail, + total_selected: result ? result.totalSelected : 0, + total_archived: result ? result.totalArchived : 0, + total_already_archived: result ? result.totalAlreadyArchived : 0, + total_items_archived: result ? result.totalItemsArchived : 0, + total_failed_batches: result ? result.totalFailedBatches : 0, + total_failed_count: result ? result.totalFailedCount : 0, + backlog_remaining: result ? Boolean(result.backlogRemaining) : false, + warehouse_ids: result ? result.warehouseIds : [], + warehouses: result + ? result.results.map(item => ({ + warehouse_id: item.warehouseId, + batches: item.batches, + archived: item.archivedCount, + items_archived: item.itemsArchivedCount, + failed_batches: item.failedBatches, + last_id: item.lastId, + stop_reason: item.stopReason, + })) + : [], + }; + + await writeExecutionLogToCache(ctx, logEntry); + await appendExecutionHistory(ctx, logEntry); + await writeProgress(ctx, { + status, + started_at: startedAtIso, + finished_at: new Date().toISOString(), + trigger: 'schedule', + pid: process.pid, + elapsed_ms: logEntry.duration_ms, + total_archived: logEntry.total_archived, + total_failed_batches: logEntry.total_failed_batches, + backlog_remaining: logEntry.backlog_remaining, + warehouses: logEntry.warehouses, + }); + + ctx.logger.info( + `[${scheduleName}] 执行日志已写入缓存 key=${EXECUTION_LOG_CACHE_KEY} history=${EXECUTION_LOG_HISTORY_CACHE_KEY} progress=${PROGRESS_CACHE_KEY}` + ); + }, + }; +}; diff --git a/app/service/systems/order_delivery_archive.js b/app/service/systems/order_delivery_archive.js new file mode 100644 index 0000000..6958229 --- /dev/null +++ b/app/service/systems/order_delivery_archive.js @@ -0,0 +1,795 @@ +'use strict'; + +const MainService = require('../main'); + +/** 单批处理条数(与 current → dispatch 迁移保持一致,单批一个事务) */ +const MAX_BATCH_SIZE = 1000; + +/** 归档门槛:订单创建时间(create_at)距今超过该月数即归档 */ +const DEFAULT_ARCHIVE_AFTER_MONTHS = 4; + +/** 归档门槛:订单迁移进配送表(dispath_time)距今超过该月数即归档 */ +const DEFAULT_DISPATCH_STAY_MONTHS = 3; + +/** 单仓库单轮最多处理的批次数(异常情况下防止死循环) */ +const DEFAULT_MAX_BATCHES_PER_WAREHOUSE = 200; + +/** 单轮总时长上限(毫秒):超过后停止本轮,剩余订单下一轮继续 */ +const DEFAULT_MAX_RUN_MS = 30 * 60 * 1000; + +/** 单批查询超时(毫秒) */ +const DEFAULT_QUERY_TIMEOUT_MS = 60 * 1000; + +/** 单批事务遇到死锁/锁等待时的最大尝试次数 */ +const DEFAULT_BATCH_MAX_ATTEMPTS = 3; + +/** 重试基础退避毫秒数(按尝试次数线性放大) */ +const BATCH_RETRY_BASE_DELAY_MS = 50; + +/** 历史表位置标识(写入订单索引表 wms_order_id_location_{仓库}.location) */ +const HISTORY_LOCATION = 'history'; + +/** 配送域分表名匹配(仅 _dispatch 参与归档) */ +const DISPATCH_TABLE_PATTERN = /^wms_order_delivery_(\d+)_dispatch$/; + +/** 可重试的数据库锁错误码 */ +const RETRYABLE_DATABASE_ERROR_CODES = new Set([ 1205, 1213, 'ER_LOCK_WAIT_TIMEOUT', 'ER_LOCK_DEADLOCK' ]); + +/** + * 按自然月回退时间(与 MySQL DATE_SUB(NOW(), INTERVAL n MONTH) 语义一致: + * 目标月份天数不足时取该月最后一天,如 3/31 回退 1 个月 → 2/28)。 + * + * @param {Date} baseDate 基准时间。 + * @param {number} months 回退月数(正整数)。 + * @return {Date} 回退后的时间。 + */ +function subtractMonths(baseDate, months) { + const base = baseDate instanceof Date ? baseDate : new Date(baseDate); + const normalizedMonths = Math.max(0, Math.floor(Number(months) || 0)); + + if (normalizedMonths === 0) { + return new Date(base.getTime()); + } + + const day = base.getDate(); + const target = new Date(base.getTime()); + // 先落到 1 号再回退月份,避免 9/30 回退 1 个月时被 JS 进位成 10/30 + target.setDate(1); + target.setMonth(target.getMonth() - normalizedMonths); + const daysInTargetMonth = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate(); + target.setDate(Math.min(day, daysInTargetMonth)); + + return target; +} + +/** + * 规范化正整数配置项。 + * + * @param {*} value 原始值。 + * @param {number} fallback 回退值。 + * @return {number} 规范化结果。 + */ +function normalizePositiveNumber(value, fallback) { + const parsed = Number(value); + return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback; +} + +/** + * 配送表订单归档到历史表的同步服务。 + * + * 归档链路(单批一个事务,全部成功或全部回滚): + * 1. 从 `wms_order_delivery_{仓库}_dispatch` 按主键游标取候选订单 + * (create_at 距今 > 4 个月,或 dispath_time 距今 > 3 个月); + * 2. 复制订单行到 `_history`(剔除历史表不存在的 dispatch_lane / dispath_time, + * 写入 archive_time = 当前时刻),id 原样复制(多表共用 id 契约); + * 3. 同步复制商品明细 `wms_order_items_{仓库}_dispatch` → `_history`; + * 4. 更新订单索引表 `wms_order_id_location_{仓库}` 的 location 为 history; + * 5. 硬删除 dispatch 源行(先子表后主表)。 + * + * 幂等与可续跑:每批提交后源行已消失,重跑查询不会命中;若历史表已存在同 id + * 记录(上一轮中断或人工补数的残留),则跳过写入但仍清理源行,保证重复执行安全。 + */ +class OrderDeliveryArchiveService extends MainService { + /** + * 读取归档任务默认参数(config.orderDeliveryArchive 优先)。 + * + * @return {Object} 归档参数。 + */ + getArchiveDefaults() { + const config = (this.app && this.app.config && this.app.config.orderDeliveryArchive) || {}; + + return { + archiveAfterMonths: normalizePositiveNumber(config.archiveAfterMonths, DEFAULT_ARCHIVE_AFTER_MONTHS), + dispatchStayMonths: normalizePositiveNumber(config.dispatchStayMonths, DEFAULT_DISPATCH_STAY_MONTHS), + batchSize: Math.min( + normalizePositiveNumber(config.batchSize, MAX_BATCH_SIZE), + MAX_BATCH_SIZE + ), + maxBatchesPerWarehouse: normalizePositiveNumber( + config.maxBatchesPerWarehouse, + DEFAULT_MAX_BATCHES_PER_WAREHOUSE + ), + maxRunMs: normalizePositiveNumber(config.maxRunMs, DEFAULT_MAX_RUN_MS), + queryTimeoutMs: normalizePositiveNumber(config.queryTimeoutMs, DEFAULT_QUERY_TIMEOUT_MS), + batchMaxAttempts: normalizePositiveNumber(config.batchMaxAttempts, DEFAULT_BATCH_MAX_ATTEMPTS), + }; + } + + /** + * 合并调用方参数与默认参数。 + * + * @param {Object} options 调用方参数。 + * @return {Object} 合并后的参数。 + */ + buildArchiveOptions(options = {}) { + const defaults = this.getArchiveDefaults(); + const source = this.isPlainObject(options) ? options : {}; + + return { + archiveAfterMonths: normalizePositiveNumber(source.archiveAfterMonths, defaults.archiveAfterMonths), + dispatchStayMonths: normalizePositiveNumber(source.dispatchStayMonths, defaults.dispatchStayMonths), + batchSize: Math.min(normalizePositiveNumber(source.batchSize, defaults.batchSize), MAX_BATCH_SIZE), + maxBatchesPerWarehouse: normalizePositiveNumber(source.maxBatchesPerWarehouse, defaults.maxBatchesPerWarehouse), + maxRunMs: normalizePositiveNumber(source.maxRunMs, defaults.maxRunMs), + queryTimeoutMs: normalizePositiveNumber(source.queryTimeoutMs, defaults.queryTimeoutMs), + batchMaxAttempts: normalizePositiveNumber(source.batchMaxAttempts, defaults.batchMaxAttempts), + }; + } + + /** + * 构造归档时间门槛。 + * + * 使用应用进程时钟(而非数据库 NOW()):dispath_time / create_at 均由应用以 + * `new Date()` 写入,两者同源比较可避免数据库时区与服务时区不一致带来的偏差。 + * + * @param {Date} [now] 基准时间,默认当前时间。 + * @param {Object} options 归档参数。 + * @return {{ now: Date, createThreshold: Date, dispatchThreshold: Date }} 门槛集合。 + */ + buildArchiveThresholds(now = new Date(), options = {}) { + const resolved = this.buildArchiveOptions(options); + const baseTime = now instanceof Date ? now : new Date(); + + return { + now: baseTime, + createThreshold: subtractMonths(baseTime, resolved.archiveAfterMonths), + dispatchThreshold: subtractMonths(baseTime, resolved.dispatchStayMonths), + }; + } + + /** + * 规范化仓库ID列表。 + * + * @param {Object} data 请求参数。 + * @return {Array} 仓库ID列表。 + */ + normalizeWarehouseIds(data = {}) { + if (!this.isPlainObject(data)) { + return []; + } + + const candidateValues = Array.isArray(data.warehouseIds) + ? data.warehouseIds + : [ data.warehouseId ?? data.warehouse_id ].filter(value => value !== undefined && value !== null && value !== ''); + + return Array.from(new Set(candidateValues + .map(value => Number(value)) + .filter(value => Number.isFinite(value) && value > 0))) + .sort((left, right) => left - right); + } + + /** + * 获取当前库中存在配送分表的仓库ID列表。 + * + * @return {Promise>} 仓库ID列表。 + */ + async listDispatchWarehouseIds() { + const factory = this.ctx.model && this.ctx.model.OrderDeliveryFactory; + + if (!factory || typeof factory.listManagedTableNames !== 'function') { + return []; + } + + const tableNames = await factory.listManagedTableNames(); + + return Array.from(new Set((Array.isArray(tableNames) ? tableNames : []) + .map(tableName => { + const matched = DISPATCH_TABLE_PATTERN.exec(String(tableName || '')); + return matched ? Number(matched[1]) : null; + }) + .filter(value => Number.isFinite(value) && value > 0))) + .sort((left, right) => left - right); + } + + /** + * 获取归档所需的模型集合。 + * + * @param {number} warehouseId 仓库ID。 + * @return {Promise} 模型集合。 + */ + async getArchiveModels(warehouseId) { + const orderFactory = this.ctx.model && this.ctx.model.OrderDeliveryFactory; + const itemsFactory = this.ctx.model && this.ctx.model.OrderItemsFactory; + + if (!orderFactory + || typeof orderFactory.getDispatchModel !== 'function' + || typeof orderFactory.getHistoryModel !== 'function') { + throw new Error('订单工厂未初始化,无法获取配送表/历史表模型'); + } + + if (!itemsFactory + || typeof itemsFactory.getDispatchModel !== 'function' + || typeof itemsFactory.getHistoryModel !== 'function') { + throw new Error('订单商品工厂未初始化,无法获取配送表/历史表模型'); + } + + return { + dispatchOrderModel: await orderFactory.getDispatchModel(warehouseId), + historyOrderModel: await orderFactory.getHistoryModel(warehouseId), + dispatchItemModel: await itemsFactory.getDispatchModel(warehouseId), + historyItemModel: await itemsFactory.getHistoryModel(warehouseId), + }; + } + + /** + * 构造候选订单查询条件。 + * + * 仅取 _dispatch 分表内满足下列任一条件的订单: + * - 创建时间距今超过 archiveAfterMonths(默认 4 个月); + * - 迁移进配送表时间(dispath_time)距今超过 dispatchStayMonths(默认 3 个月)。 + * + * 注意:dispath_time 为 NULL 的存量订单由上述 OR 的另一分支(create_at)兜底, + * 无需显式 IS NULL 判断 —— SQL 三值逻辑下 `dispath_time < ?` 对 NULL 结果为 + * UNKNOWN,天然不会命中。 + * + * 游标条件用主键 id(条件列 create_at / dispath_time 均无索引), + * 避免生产大表上的全表扫描 + filesort。 + * + * @param {number} warehouseId 仓库ID。 + * @param {number} lastId 上一批处理到的最大 id(0 表示从头开始)。 + * @param {Object} thresholds 归档时间门槛。 + * @return {Object} Sequelize where 条件。 + */ + buildCandidateWhere(warehouseId, lastId, thresholds) { + const { Op } = this.ctx.app.Sequelize; + const normalizedLastId = Number(lastId); + + return { + warehouse_id: warehouseId, + id: Number.isFinite(normalizedLastId) && normalizedLastId > 0 + ? { [Op.gt]: normalizedLastId } + : { [Op.gt]: 0 }, + [Op.or]: [ + { dispath_time: { [Op.lt]: thresholds.dispatchThreshold } }, + { create_at: { [Op.lt]: thresholds.createThreshold } }, + ], + }; + } + + /** + * 构造 Sequelize 查询参数(事务 + 超时)。 + * + * @param {Object|null} transaction 事务对象。 + * @param {number} [queryTimeoutMs] 查询超时时间。 + * @return {Object} Sequelize 查询参数。 + */ + buildQueryOptions(transaction, queryTimeoutMs) { + const queryOptions = {}; + + if (transaction) { + queryOptions.transaction = transaction; + } + + const normalizedTimeoutMs = Number(queryTimeoutMs); + if (Number.isFinite(normalizedTimeoutMs) && normalizedTimeoutMs > 0) { + queryOptions.timeout = normalizedTimeoutMs; + } + + return queryOptions; + } + + /** + * 构造写入历史表的订单行。 + * + * 历史表比配送表少两列,必须剔除,否则 Sequelize 属性映射会静默丢弃/报错: + * - dispatch_lane:配送域车道,仅 dispatch 分表存在; + * - dispath_time:迁移进配送表的时间,仅 dispatch 分表存在 + * (迁出/迁入时刻统一由 archive_time 表达)。 + * + * @param {Object} row 配送表订单行。 + * @param {Date} archiveTime 归档时间。 + * @return {Object} 可写入历史表的订单行。 + */ + buildHistoryOrderRow(row, archiveTime) { + const payload = { ...(row || {}) }; + delete payload.dispatch_lane; + delete payload.dispath_time; + payload.archive_time = archiveTime; + + return payload; + } + + /** + * 构造写入历史表的商品明细行。 + * + * 商品配送表与历史表列完全一致(历史表仅多 archive_time),无需剔除字段。 + * + * @param {Object} row 配送表商品明细行。 + * @param {Date} archiveTime 归档时间。 + * @return {Object} 可写入历史表的商品明细行。 + */ + buildHistoryItemRow(row, archiveTime) { + return { + ...(row || {}), + archive_time: archiveTime, + }; + } + + /** + * 识别可重试的数据库锁错误。 + * + * @param {Error} error 运行时错误。 + * @return {{ retryable: boolean, category: string, message: string }} 分类结果。 + */ + getArchiveErrorInfo(error) { + const errorMessage = String((error && error.message) || ''); + const errorName = String((error && error.name) || ''); + const parentError = error && error.parent ? error.parent : null; + const errorCode = parentError && (parentError.code || parentError.errno) + ? parentError.code || parentError.errno + : error && (error.code || error.errno); + const normalizedMessage = errorMessage.toLowerCase(); + + if (errorName === 'SequelizeTimeoutError' || errorName === 'TimeoutError' || errorCode === 'ETIMEDOUT') { + return { retryable: true, category: 'timeout', message: errorMessage }; + } + + if (errorName === 'SequelizeDatabaseError') { + if (normalizedMessage.includes('lock wait timeout')) { + return { retryable: true, category: 'lock_wait_timeout', message: errorMessage }; + } + + if (RETRYABLE_DATABASE_ERROR_CODES.has(errorCode) || normalizedMessage.includes('deadlock')) { + return { retryable: true, category: 'deadlock', message: errorMessage }; + } + } + + return { retryable: false, category: 'other', message: errorMessage }; + } + + /** + * 回滚事务(忽略回滚自身异常,避免掩盖原始错误)。 + * + * @param {Object} transaction 事务对象。 + * @return {Promise} 无返回值。 + */ + async rollbackQuietly(transaction) { + if (!transaction || typeof transaction.rollback !== 'function') { + return; + } + + try { + await transaction.rollback(); + } catch (error) { + this.ctx.logger.warn(`[archive-dispatch-to-history] 事务回滚失败: ${error.message}`); + } + } + + /** + * 单批归档:查询候选 → 写历史表 → 更新位置指针 → 删除源行,全部在一个事务内完成。 + * + * @param {number|string} warehouseId 仓库ID。 + * @param {Object} [params] 单批参数。 + * @param {number} [params.lastId] 上一批处理到的最大 id。 + * @param {number} [params.batchSize] 单批条数。 + * @param {Object} [params.thresholds] 归档时间门槛。 + * @param {Object} [options] 归档参数。 + * @return {Promise} 单批结果。 + */ + async archiveDispatchBatch(warehouseId, params = {}, options = {}) { + const resolved = this.buildArchiveOptions(options); + const normalizedWarehouseId = Number(warehouseId); + + if (!Number.isFinite(normalizedWarehouseId) || normalizedWarehouseId <= 0) { + throw new Error('仓库ID不能为空'); + } + + const batchSize = Math.min(normalizePositiveNumber(params.batchSize, resolved.batchSize), MAX_BATCH_SIZE); + const lastId = Number(params.lastId) > 0 ? Number(params.lastId) : 0; + const thresholds = params.thresholds || this.buildArchiveThresholds(new Date(), resolved); + const archiveTime = new Date(); + const { Op } = this.ctx.app.Sequelize; + + // 序列表初始化可能执行 DDL(隐式提交),必须在事务外完成: + // 位置指针与历史表写入必须同事务原子完成,无索引表宁可整批失败重试。 + await this.ctx.model.OrderDeliveryFactory.ensureLocationSequenceTable(normalizedWarehouseId); + + const transaction = await this.ctx.model.transaction(); + + try { + const models = await this.getArchiveModels(normalizedWarehouseId); + + // 加行锁读取候选:归档会删除源行,锁住候选可避免与并发修改(如拦截确认) + // 交错导致"归档了旧值、删掉了新值"。 + const candidateRows = await models.dispatchOrderModel.findAll({ + where: this.buildCandidateWhere(normalizedWarehouseId, lastId, thresholds), + order: [[ 'id', 'ASC' ]], + limit: batchSize, + raw: true, + lock: transaction.LOCK.UPDATE, + ...this.buildQueryOptions(transaction, resolved.queryTimeoutMs), + }); + + const rows = Array.isArray(candidateRows) ? candidateRows : []; + const orderIds = Array.from(new Set(rows + .map(row => Number(row && row.id)) + .filter(value => Number.isFinite(value) && value > 0))); + + if (orderIds.length === 0) { + await transaction.commit(); + + return { + warehouseId: normalizedWarehouseId, + lastId, + maxCandidateId: lastId, + selectedCount: 0, + archivedCount: 0, + alreadyArchivedCount: 0, + itemsSelectedCount: 0, + itemsArchivedCount: 0, + hasMore: false, + }; + } + + const maxCandidateId = Math.max(...orderIds); + + // 幂等保护:历史表已存在同 id 记录(上一轮中断残留 / 人工补数)时不再重复写入, + // 但仍清理源行,保证本任务重复执行或跨轮次执行结果一致。 + const existingHistoryRows = await models.historyOrderModel.findAll({ + where: { id: { [Op.in]: orderIds } }, + attributes: [ 'id' ], + raw: true, + ...this.buildQueryOptions(transaction, resolved.queryTimeoutMs), + }); + const existingHistoryIdSet = new Set((Array.isArray(existingHistoryRows) ? existingHistoryRows : []) + .map(row => Number(row && row.id))); + const rowsToArchive = rows.filter(row => !existingHistoryIdSet.has(Number(row.id))); + + // 商品明细:按 order_id 一并搬迁(子表同步迁入) + const dispatchItems = await models.dispatchItemModel.findAll({ + where: { order_id: { [Op.in]: orderIds } }, + order: [[ 'id', 'ASC' ]], + raw: true, + ...this.buildQueryOptions(transaction, resolved.queryTimeoutMs), + }); + const itemRows = Array.isArray(dispatchItems) ? dispatchItems : []; + const itemIds = Array.from(new Set(itemRows + .map(row => Number(row && row.id)) + .filter(value => Number.isFinite(value) && value > 0))); + + let itemsToArchive = itemRows; + if (itemIds.length > 0) { + const existingHistoryItems = await models.historyItemModel.findAll({ + where: { id: { [Op.in]: itemIds } }, + attributes: [ 'id' ], + raw: true, + ...this.buildQueryOptions(transaction, resolved.queryTimeoutMs), + }); + const existingItemIdSet = new Set((Array.isArray(existingHistoryItems) ? existingHistoryItems : []) + .map(row => Number(row && row.id))); + itemsToArchive = itemRows.filter(row => !existingItemIdSet.has(Number(row.id))); + } + + if (rowsToArchive.length > 0) { + await models.historyOrderModel.bulkCreate( + rowsToArchive.map(row => this.buildHistoryOrderRow(row, archiveTime)), + this.buildQueryOptions(transaction, resolved.queryTimeoutMs) + ); + } + + if (itemsToArchive.length > 0) { + await models.historyItemModel.bulkCreate( + itemsToArchive.map(row => this.buildHistoryItemRow(row, archiveTime)), + this.buildQueryOptions(transaction, resolved.queryTimeoutMs) + ); + } + + // 订单索引表位置指针 dispatch → history,与历史表写入同事务, + // 保证「订单去向」与数据所在表位原子一致。 + const locationFactory = this.ctx.model && this.ctx.model.OrderDeliveryFactory; + if (!locationFactory || typeof locationFactory.updateOrderLocation !== 'function') { + throw new Error('订单工厂缺少 updateOrderLocation,无法同步订单索引表位置'); + } + + for (const orderId of orderIds) { + await locationFactory.updateOrderLocation(orderId, normalizedWarehouseId, HISTORY_LOCATION, transaction); + } + + // 删除源行:先子表后主表 + if (itemIds.length > 0) { + await models.dispatchItemModel.destroy({ + where: { id: { [Op.in]: itemIds } }, + ...this.buildQueryOptions(transaction, resolved.queryTimeoutMs), + }); + } + + await models.dispatchOrderModel.destroy({ + where: { id: { [Op.in]: orderIds } }, + ...this.buildQueryOptions(transaction, resolved.queryTimeoutMs), + }); + + await transaction.commit(); + + return { + warehouseId: normalizedWarehouseId, + lastId: maxCandidateId, + maxCandidateId, + selectedCount: orderIds.length, + archivedCount: rowsToArchive.length, + alreadyArchivedCount: orderIds.length - rowsToArchive.length, + itemsSelectedCount: itemIds.length, + itemsArchivedCount: itemsToArchive.length, + hasMore: rows.length >= batchSize, + }; + } catch (error) { + await this.rollbackQuietly(transaction); + throw error; + } + } + + /** + * 归档指定仓库的配送表订单(按主键游标循环分批,直到无候选或达到限额)。 + * + * @param {number|string} warehouseId 仓库ID。 + * @param {Object} [options] 归档参数。 + * @param {Function} [options.onBatch] 单批完成回调(用于上报进度)。 + * @param {Function} [options.shouldStop] 外部中断判断回调。 + * @return {Promise} 仓库归档汇总。 + */ + async archiveDispatchOrdersForWarehouse(warehouseId, options = {}) { + const resolved = this.buildArchiveOptions(options); + const normalizedWarehouseId = Number(warehouseId); + + if (!Number.isFinite(normalizedWarehouseId) || normalizedWarehouseId <= 0) { + throw new Error('仓库ID不能为空'); + } + + const thresholds = options.thresholds || this.buildArchiveThresholds(new Date(), resolved); + const deadlineAt = options.deadlineAt > 0 ? Number(options.deadlineAt) : 0; + const onBatch = typeof options.onBatch === 'function' ? options.onBatch : null; + const shouldStop = typeof options.shouldStop === 'function' ? options.shouldStop : null; + + const summary = { + warehouseId: normalizedWarehouseId, + batches: 0, + selectedCount: 0, + archivedCount: 0, + alreadyArchivedCount: 0, + itemsArchivedCount: 0, + failedBatches: 0, + failedCount: 0, + lastId: Number(options.lastId) > 0 ? Number(options.lastId) : 0, + stopReason: '', + }; + + for (let batchIndex = 0; batchIndex < resolved.maxBatchesPerWarehouse; batchIndex++) { + if (shouldStop && shouldStop()) { + summary.stopReason = 'external_stop'; + break; + } + + if (deadlineAt > 0 && Date.now() >= deadlineAt) { + summary.stopReason = 'run_budget_exhausted'; + break; + } + + let batchResult = null; + let lastError = null; + + for (let attempt = 1; attempt <= resolved.batchMaxAttempts; attempt++) { + try { + batchResult = await this.archiveDispatchBatch(normalizedWarehouseId, { + lastId: summary.lastId, + batchSize: resolved.batchSize, + thresholds, + }, resolved); + break; + } catch (error) { + lastError = error; + const errorInfo = this.getArchiveErrorInfo(error); + + if (!errorInfo.retryable || attempt >= resolved.batchMaxAttempts) { + break; + } + + this.ctx.logger.warn( + `[archive-dispatch-to-history] 仓库 ${normalizedWarehouseId} 第 ${batchIndex + 1} 批遇到 ${errorInfo.category},` + + `重试 ${attempt}/${resolved.batchMaxAttempts}: ${errorInfo.message}` + ); + await new Promise(resolve => setTimeout(resolve, BATCH_RETRY_BASE_DELAY_MS * attempt)); + } + } + + if (!batchResult) { + // 单批彻底失败:记录后越过该批(游标推进到候选范围内已知的最大 id), + // 避免整轮卡死在同一批;未迁移的行保留在配送表,下一轮继续尝试。 + summary.failedBatches += 1; + summary.stopReason = 'batch_failure'; + this.ctx.logger.error( + `[archive-dispatch-to-history] 仓库 ${normalizedWarehouseId} 第 ${batchIndex + 1} 批归档失败,已跳过该批: ` + + `${lastError ? lastError.message : 'unknown error'}` + ); + + const skippedLastId = await this.resolveFailureCursor(normalizedWarehouseId, summary.lastId, thresholds, resolved); + summary.failedCount += skippedLastId.failedCount; + summary.lastId = skippedLastId.lastId; + + if (!skippedLastId.advanced) { + break; + } + + continue; + } + + summary.batches += 1; + summary.selectedCount += batchResult.selectedCount; + summary.archivedCount += batchResult.archivedCount; + summary.alreadyArchivedCount += batchResult.alreadyArchivedCount; + summary.itemsArchivedCount += batchResult.itemsArchivedCount; + summary.lastId = batchResult.lastId; + + if (onBatch) { + await onBatch({ ...batchResult, batchIndex: batchIndex + 1, summary: { ...summary } }); + } + + // 未取满一批(hasMore=false)说明候选已清空;取满但下一轮可能仍有候选,继续循环 + if (batchResult.selectedCount === 0 || !batchResult.hasMore) { + summary.stopReason = 'no_more_candidates'; + break; + } + } + + if (!summary.stopReason) { + summary.stopReason = 'max_batches_reached'; + } + + return summary; + } + + /** + * 单批失败后推进游标:取该批候选范围内的最大 id,返回下一次查询起点。 + * + * @param {number} warehouseId 仓库ID。 + * @param {number} lastId 当前游标。 + * @param {Object} thresholds 归档时间门槛。 + * @param {Object} options 归档参数。 + * @return {Promise<{ lastId: number, failedCount: number, advanced: boolean }>} 游标结果。 + */ + async resolveFailureCursor(warehouseId, lastId, thresholds, options) { + try { + const models = await this.getArchiveModels(warehouseId); + const rows = await models.dispatchOrderModel.findAll({ + where: this.buildCandidateWhere(warehouseId, lastId, thresholds), + attributes: [ 'id' ], + order: [[ 'id', 'ASC' ]], + limit: options.batchSize, + raw: true, + ...this.buildQueryOptions(null, options.queryTimeoutMs), + }); + const idList = (Array.isArray(rows) ? rows : []) + .map(row => Number(row && row.id)) + .filter(value => Number.isFinite(value) && value > 0); + + if (idList.length === 0) { + return { lastId, failedCount: 0, advanced: false }; + } + + return { + lastId: Math.max(...idList), + failedCount: idList.length, + advanced: true, + }; + } catch (error) { + this.ctx.logger.error(`[archive-dispatch-to-history] 推进失败游标时查询失败: ${error.message}`); + return { lastId, failedCount: 0, advanced: false }; + } + } + + /** + * 归档全部(或指定)仓库的配送表订单。 + * + * 每批一个事务、失败仅推进游标不中断整体,因此任务中断后重新执行即可续跑: + * 已迁移的行已从配送表删除,不会重复处理。 + * + * @param {Object} [data] 请求参数。 + * @param {number|Array} [data.warehouseId] 单个仓库ID或仓库ID列表。 + * @param {Array} [data.warehouseIds] 仓库ID列表。 + * @param {Object} [options] 归档参数(可覆盖 config.orderDeliveryArchive)。 + * @param {Function} [options.onBatch] 单批完成回调。 + * @param {Function} [options.onWarehouseDone] 单仓库完成回调。 + * @return {Promise} 归档汇总结果。 + */ + async archiveDispatchOrdersToHistory(data = {}, options = {}) { + const resolved = this.buildArchiveOptions(options); + const requestData = this.isPlainObject(data) ? data : {}; + const explicitWarehouseIds = this.normalizeWarehouseIds(requestData); + const warehouseIds = explicitWarehouseIds.length > 0 + ? explicitWarehouseIds + : await this.listDispatchWarehouseIds(); + + const startedAt = Date.now(); + const deadlineAt = startedAt + resolved.maxRunMs; + const thresholds = this.buildArchiveThresholds(new Date(startedAt), resolved); + const results = []; + + let totalSelected = 0; + let totalArchived = 0; + let totalAlreadyArchived = 0; + let totalItemsArchived = 0; + let totalFailedBatches = 0; + let totalFailedCount = 0; + + for (const warehouseId of warehouseIds) { + if (Date.now() >= deadlineAt) { + results.push({ + warehouseId, + batches: 0, + selectedCount: 0, + archivedCount: 0, + alreadyArchivedCount: 0, + itemsArchivedCount: 0, + failedBatches: 0, + failedCount: 0, + lastId: 0, + stopReason: 'run_budget_exhausted', + }); + continue; + } + + const warehouseResult = await this.archiveDispatchOrdersForWarehouse(warehouseId, { + ...resolved, + thresholds, + deadlineAt, + onBatch: options.onBatch, + shouldStop: options.shouldStop, + }); + + results.push(warehouseResult); + + totalSelected += warehouseResult.selectedCount; + totalArchived += warehouseResult.archivedCount; + totalAlreadyArchived += warehouseResult.alreadyArchivedCount; + totalItemsArchived += warehouseResult.itemsArchivedCount; + totalFailedBatches += warehouseResult.failedBatches; + totalFailedCount += warehouseResult.failedCount; + + if (typeof options.onWarehouseDone === 'function') { + await options.onWarehouseDone(warehouseResult); + } + } + + const backlogRemaining = results.some(result => result.stopReason === 'run_budget_exhausted'); + + return { + warehouseIds, + batchSize: resolved.batchSize, + archiveAfterMonths: resolved.archiveAfterMonths, + dispatchStayMonths: resolved.dispatchStayMonths, + thresholds: { + createThreshold: thresholds.createThreshold.toISOString(), + dispatchThreshold: thresholds.dispatchThreshold.toISOString(), + }, + elapsedMs: Date.now() - startedAt, + totalSelected, + totalArchived, + totalAlreadyArchived, + totalItemsArchived, + totalFailedBatches, + totalFailedCount, + backlogRemaining, + results, + }; + } +} + +module.exports = OrderDeliveryArchiveService; diff --git a/config/config.default.js b/config/config.default.js index e5740ee..f832d2f 100644 --- a/config/config.default.js +++ b/config/config.default.js @@ -253,6 +253,30 @@ module.exports = appInfo => { sleepMinMs: 100, sleepMaxMs: 500, }; + // 配送表(dispatch) → 历史表(history) 归档定时任务配置 + // 每日凌晨 06:00 把配送表超期订单(连同商品明细)迁入历史表,并更新订单索引表位置指针 + config.orderDeliveryArchive = { + // 开关:false 时不注册本定时任务 + enable: true, + // 触发 cron(秒 分 时 日 月 周):默认每日凌晨 06:00;本地环境可在 config.local.js 覆盖为短间隔 + cron: '0 0 6 * * *', + // 归档门槛一:订单创建时间(create_at)距今超过该月数即归档(dispath_time 为 NULL 的存量单只靠此条) + archiveAfterMonths: 4, + // 归档门槛二:迁移进配送表时间(dispath_time)距今超过该月数即归档 + dispatchStayMonths: 3, + // 单批条数(单批一个事务:写历史表 + 更新位置指针 + 删源行) + batchSize: 1000, + // 单仓库单轮最多批次数(异常情况下防死循环) + maxBatchesPerWarehouse: 200, + // 单轮总时长上限(毫秒):用尽后停止本轮,剩余订单下一轮继续(避免闯入业务高峰) + maxRunMs: 30 * 60 * 1000, + // 单批查询超时(毫秒) + queryTimeoutMs: 60 * 1000, + // 单批事务遇到死锁/锁等待的最大尝试次数 + batchMaxAttempts: 3, + // 跨进程互斥锁 TTL(秒),需覆盖单轮最长执行时间;进程被杀后锁到期自动释放 + lockTtlSeconds: 30 * 60, + }; // 打印自定义区模板出口域名 config.customAreaBaseUrl = 'https://api.ye4s.com'; // 仓库前端独立部署:证书部署目录。