WMS_MAIN/app/lib/intercept_time.js
liufumingren a4cadeb83b feat: 库内确定拦截订单明细报表与拦截时间口径调整
- 新增通用报表注册类型 interceptOrder(库内确定拦截订单明细):以配送表 dispath_time 为时间基准,统计昨日自然日(不含当天,可用 params.bizDate 指定更早日期补数)intercept_status=intercepted_at_warehouse 的订单,按商品明细展开;列 = 订单导出 item 模式去掉商品图片(46 列)+ 平台交易单号 / 通知拦截时间 / 库内确定拦截时间,共 49 列
- intercept_time 口径统一为「最近一次发起拦截的通知时刻」:发起拦截首次写入不覆盖(新增 app/lib/intercept_time.js 与 qimen/openapi/inbox/pendingOrder 四处改造)、库内拦截确认与退回入库不再覆盖、取消/解除拦截与订单克隆重置置空;库内确定拦截时刻改用配送表 dispath_time
- 报表导出文件名模板新增 {time}(生成时刻 HHmmss)/ {datetime} / {timestamp} 占位符({date} 语义不变),避免同一天多次投递/导出同一报表时 COS 同名覆盖与 CDN 旧内容回源
- 文档同步:methods/system.json 0.3.104 -> 0.3.109(report.generate / report.definition.* 契约与拦截时间口径说明)、methods/changes/system.json 新增 4 条变更记录、docs/report-config-guide.md 新增 2.2 节、字段清单与文件名占位符说明
- 回归与实测:test/report_*.cjs 13 个文件 + test/intercept_time_lifecycle.cjs 全部通过,ESLint 0 error;开发库投递计划实测(19:40 / 20:25 两条计划投递成功或仅文本通知环境依赖失败,文件名均带时分秒、导出列与定义勾选一致)
2026-09-10 20:59:39 +08:00

83 lines
3.2 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'use strict';
/**
* 通知拦截时间(wms_order_delivery.intercept_time)字段口径工具(纯函数,无 ctx 依赖,可单测)。
*
* 背景:`intercept_time` 语义原为「进入拦截流程/库内拦截确认时写入」,
* 确认拦截会覆盖发起时刻,导致「通知拦截时间」丢失、且无法与「库内确定拦截时刻」区分。
*
* 自 2026-09-10 起统一为「最近一次发起拦截的通知时刻」:
* 1. 发起/通知拦截:**首次写入**(当前时间);重复发起**不覆盖**已有值;
* 2. 库内拦截确认(confirmIntercept / 拦截扫描 / 自动确认)、退回入库(returned):**不写该字段**(不覆盖);
* 3. 取消/解除拦截(batchUnintercept)与订单克隆重置:**置空 null**;
* 4. 因此「库内确定拦截时刻」不再使用本字段,改用配送表 `dispath_time`(订单迁移进配送表的时间,
* 库内确定拦截后基本都会走迁移)。
*/
/** 字段名常量 */
const INTERCEPT_TIME_FIELD = 'intercept_time';
/**
* 判断通知拦截时间是否为空(null/undefined/空串)。
* @param {*} value 字段值
* @return {boolean} 是否为空
*/
function isEmptyInterceptTime(value) {
return value === null || value === undefined || value === '';
}
/**
* 构造发起拦截时的更新片段:仅当当前值为空时才写入通知拦截时间(首次写入,不覆盖)。
*
* 用法(实例更新,实例行需能取到 intercept_time):
* ```js
* await order.update({ intercept_status: 'requested', ...buildNoticeTimePatch(order.intercept_time), updated_at: now });
* ```
*
* @param {*} currentValue 订单当前 intercept_time
* @param {Date} [now=new Date()] 本次通知时刻
* @return {Object} 需要写入的字段片段;已有值时返回空对象(不覆盖)
*/
function buildNoticeTimePatch(currentValue, now = new Date()) {
return isEmptyInterceptTime(currentValue) ? { [INTERCEPT_TIME_FIELD]: now } : {};
}
/**
* 从订单行中筛出「尚未写入通知拦截时间」的订单ID(批量写入用)。
*
* 用法(批量更新):主更新不写 intercept_time,随后仅对返回的订单ID写一次通知时刻:
* ```js
* const fillIds = pickNoticeTimeOrderIds(orderRows);
* await model.update({ intercept_status: 'requested', updated_at: now }, { where: { id: { [Op.in]: ids } } });
* if (fillIds.length > 0) {
* await model.update({ intercept_time: now }, { where: { id: { [Op.in]: fillIds } } });
* }
* ```
*
* @param {Array<Object>} rows 订单行(需含 id 与 intercept_time)
* @return {Array<number>} 需要写入通知拦截时间的订单ID(正整数,保序去重)
*/
function pickNoticeTimeOrderIds(rows = []) {
const seen = new Set();
const orderIds = [];
for (const row of (Array.isArray(rows) ? rows : [])) {
if (!row || !isEmptyInterceptTime(row[INTERCEPT_TIME_FIELD])) {
continue;
}
const orderId = Number(row.id || 0);
if (!Number.isInteger(orderId) || orderId <= 0 || seen.has(orderId)) {
continue;
}
seen.add(orderId);
orderIds.push(orderId);
}
return orderIds;
}
module.exports = {
INTERCEPT_TIME_FIELD,
isEmptyInterceptTime,
buildNoticeTimePatch,
pickNoticeTimeOrderIds,
};