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 两条计划投递成功或仅文本通知环境依赖失败,文件名均带时分秒、导出列与定义勾选一致)
This commit is contained in:
liufumingren 2026-09-10 20:59:39 +08:00
parent 0fe43c87b1
commit a4cadeb83b
16 changed files with 958 additions and 61 deletions

82
app/lib/intercept_time.js Normal file
View File

@ -0,0 +1,82 @@
'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,
};

View File

@ -32,7 +32,7 @@ module.exports = app => {
file_name: {
type: STRING(200),
allowNull: false,
comment: '导出文件名模板(支持 {date} 占位,如 7日出入库_{date}.xlsx)',
comment: '导出文件名模板(支持 {date}/{time}/{datetime}/{timestamp} 占位,如 7日出入库_{date}.xlsx)',
},
fields: {
type: app.Sequelize.JSON,

View File

@ -4,6 +4,7 @@ const Service = require('egg').Service;
// 群类型常量定义统一收口到 inbox/groups.js
const { GROUP } = require('./groups');
const { pickNoticeTimeOrderIds } = require('../../lib/intercept_time');
/**
* 站内信函数注册表。
@ -990,7 +991,7 @@ class InboxFunctionsService extends Service {
const orderModel = await ctx.model.OrderDeliveryFactory.getCurrentModel(warehouseId);
if (orderModel) {
const orders = await orderModel.findAll({
attributes: [ 'id', 'step', 'wave_id', 'inspection_status' ],
attributes: [ 'id', 'step', 'wave_id', 'inspection_status', 'intercept_time' ],
where: {
id: { [ctx.app.Sequelize.Op.in]: orderIds },
step: { [ctx.app.Sequelize.Op.in]: [ 1, 2, 3 ] },
@ -1066,12 +1067,23 @@ class InboxFunctionsService extends Service {
}
}
// 执行拦截状态设置(订单表 + 运单表,同步写入拦截时间)
// 执行拦截状态设置(订单表 + 运单表;通知拦截时间只在首次发起时写入,不覆盖已有值)
if (interceptOrderIds.length > 0) {
const noticeNow = new Date();
const interceptIdSet = new Set(interceptOrderIds.map(id => Number(id)));
const fillNoticeOrderIds = pickNoticeTimeOrderIds(
orders.filter(order => interceptIdSet.has(Number(order.id)))
);
await orderModel.update(
{ intercept_status: 'requested', intercept_time: new Date() },
{ intercept_status: 'requested' },
{ where: { id: { [ctx.app.Sequelize.Op.in]: interceptOrderIds } } }
);
if (fillNoticeOrderIds.length > 0) {
await orderModel.update(
{ intercept_time: noticeNow },
{ where: { id: { [ctx.app.Sequelize.Op.in]: fillNoticeOrderIds } } }
);
}
// 同步更新运单表拦截标记
await ctx.model.OrderExpress.update(
{ is_intercept: 'Y' },
@ -1787,7 +1799,7 @@ class InboxFunctionsService extends Service {
const orderModel = await ctx.model.OrderDeliveryFactory.getCurrentModel(warehouseId);
if (orderModel) {
const orders = await orderModel.findAll({
attributes: [ 'id', 'step', 'wave_id', 'inspection_status' ],
attributes: [ 'id', 'step', 'wave_id', 'inspection_status', 'intercept_time' ],
where: { id: { [ctx.app.Sequelize.Op.in]: orderIds }, step: { [ctx.app.Sequelize.Op.in]: [ 1, 2, 3 ] } },
raw: true,
});
@ -1832,10 +1844,21 @@ class InboxFunctionsService extends Service {
if (needIntercept) interceptOrderIds.push(order.id);
}
if (interceptOrderIds.length > 0) {
const noticeNow = new Date();
const interceptIdSet = new Set(interceptOrderIds.map(id => Number(id)));
const fillNoticeOrderIds = pickNoticeTimeOrderIds(
orders.filter(order => interceptIdSet.has(Number(order.id)))
);
await orderModel.update(
{ intercept_status: 'requested', intercept_time: new Date() },
{ intercept_status: 'requested' },
{ where: { id: { [ctx.app.Sequelize.Op.in]: interceptOrderIds } } }
);
if (fillNoticeOrderIds.length > 0) {
await orderModel.update(
{ intercept_time: noticeNow },
{ where: { id: { [ctx.app.Sequelize.Op.in]: fillNoticeOrderIds } } }
);
}
await ctx.model.OrderExpress.update(
{ is_intercept: 'Y' },
{ where: { order_id: { [ctx.app.Sequelize.Op.in]: interceptOrderIds }, warehouse_id: warehouseId } }

View File

@ -3,6 +3,7 @@
const MainService = require('../main');
const { getInterceptRequestBlockReason, resolveInterceptRequestGuardInfo } = require('../../lib/intercept_guard');
const { buildNoticeTimePatch } = require('../../lib/intercept_time');
class OpenapiOrderService extends MainService {
/**
@ -71,10 +72,12 @@ class OpenapiOrderService extends MainService {
});
if (!blockReason) {
// 通知拦截时间只在首次发起时写入(重复发起不覆盖已有值)
const noticeNow = new Date();
await existingOrder.update({
intercept_status: 'intercepting',
intercept_time: new Date(),
updated_at: new Date(),
...buildNoticeTimePatch(existingOrder.intercept_time, noticeNow),
updated_at: noticeNow,
}, {
transaction,
});

View File

@ -3,6 +3,7 @@
const MainService = require('../main');
const { getInterceptRequestBlockReason, resolveInterceptRequestGuardInfo } = require('../../lib/intercept_guard');
const { buildNoticeTimePatch } = require('../../lib/intercept_time');
class orderServer extends MainService {
@ -254,10 +255,12 @@ class orderServer extends MainService {
});
if (!blockReason) {
// 通知拦截时间只在首次发起时写入(重复发起不覆盖已有值)
const noticeNow = new Date();
await existingOrder.update({
intercept_status: 'intercepting',
intercept_time: new Date(),
updated_at: new Date(),
...buildNoticeTimePatch(existingOrder.intercept_time, noticeNow),
updated_at: noticeNow,
}, {
transaction,
});
@ -348,10 +351,12 @@ class orderServer extends MainService {
});
if (!syncBlockReason) {
// 通知拦截时间只在首次发起时写入(重复发起不覆盖已有值)
const noticeNow = new Date();
await existingOrder.update({
intercept_status: 'requested',
intercept_time: new Date(),
updated_at: new Date(),
...buildNoticeTimePatch(existingOrder.intercept_time, noticeNow),
updated_at: noticeNow,
}, {
transaction,
});

View File

@ -3,6 +3,7 @@
const OrderBaseService = require('./base');
const { getInterceptRequestBlockReason, resolveInterceptRequestGuardInfoMap } = require('../../../lib/intercept_guard');
const { pickNoticeTimeOrderIds } = require('../../../lib/intercept_time');
const PENDING_OUTBOUND_STATUS = 'padding';
const PENDING_CANCEL_STATUS = 'cancel';
@ -2502,10 +2503,11 @@ class PendingOrderService extends OrderBaseService {
);
if (syncedOrderIds.length > 0) {
const syncNow = new Date();
// 通知拦截时间只在首次发起时写入(重复发起不覆盖已有值)
const fillNoticeOrderIds = pickNoticeTimeOrderIds(syncedOrders);
await model.update(
{
intercept_status: 'requested',
intercept_time: syncNow,
updated_at: syncNow,
},
{
@ -2515,6 +2517,12 @@ class PendingOrderService extends OrderBaseService {
transaction,
}
);
if (fillNoticeOrderIds.length > 0) {
await model.update(
{ intercept_time: syncNow },
{ where: { id: fillNoticeOrderIds }, transaction }
);
}
// 同步更新运单表拦截标记
try {
const { Op: cancelOp } = this.app.Sequelize;
@ -3524,6 +3532,8 @@ class PendingOrderService extends OrderBaseService {
outbound_status: 'none',
lock_status: 'none',
intercept_status: 'none',
// 克隆重置拦截字段:通知拦截时间必须清空,避免新单继承原单发起拦截时刻
intercept_time: null,
sync_status: 'padding',
order_flag: '',
wave_id: 0,
@ -4707,7 +4717,7 @@ ${numbered}`;
}
const orderRows = await orderModel.findAll({
attributes: [ 'id', 'delivery_order_code', 'pre_delivery_order_code', 'wave_id', 'inspection_status' ],
attributes: [ 'id', 'delivery_order_code', 'pre_delivery_order_code', 'wave_id', 'inspection_status', 'intercept_time' ],
where: {
warehouse_id: warehouseId,
id: {
@ -4797,19 +4807,30 @@ ${numbered}`;
}
const now = new Date();
const updateValues = {
intercept_status: 'requested',
intercept_time: now,
updated_at: now,
};
await orderModel.update(updateValues, {
where: {
id: {
[Op.in]: chunkOrderIds,
// 通知拦截时间只在首次发起时写入(重复发起不覆盖已有值)
const fillNoticeOrderIds = pickNoticeTimeOrderIds(chunkRows);
await orderModel.update(
{ intercept_status: 'requested', updated_at: now },
{
where: {
id: {
[Op.in]: chunkOrderIds,
},
},
},
});
}
);
if (fillNoticeOrderIds.length > 0) {
await orderModel.update(
{ intercept_time: now },
{
where: {
id: {
[Op.in]: fillNoticeOrderIds,
},
},
}
);
}
// 同步更新运单表拦截标记
try {

View File

@ -3904,7 +3904,9 @@ class RecheckOrderService extends OrderBaseService {
* 2. 校验通过后将运单 is_back、is_intercept 设为 'Y'
* 3. 检查是否存在关联的未完结售后工单(wms_after_sale),若有则调用 handleWorkOrder 写入
* "库内拦截成功"步骤并将工单置为 completed
* 4. 同步更新 wms_order_delivery 的 intercept_status 为 intercepted_at_warehouse 并写入拦截时间 intercept_time,
* 4. 同步更新 wms_order_delivery 的 intercept_status 为 intercepted_at_warehouse(**不写 intercept_time**:
* 该字段恒为「最近一次发起拦截的通知时刻」,库内确定拦截不覆盖,见 app/lib/intercept_time.js;
* 库内确定拦截时刻以配送表 dispath_time 为准),
* 并释放储位分配(拦截模式:库存移入拦截锁定,不归还可用)与订单锁(仅订单级状态更新,不标记订单下其他面单)
*
* 注:库内拦截确认需标记退回 is_back='Y';发起拦截链路仅写 is_intercept,不写 is_back。
@ -4018,10 +4020,10 @@ class RecheckOrderService extends OrderBaseService {
});
if (order) {
// 库内确定拦截不写 intercept_time(不覆盖通知拦截时刻),库内确定时刻以配送表 dispath_time 为准
await orderModel.update(
{
intercept_status: 'intercepted_at_warehouse',
intercept_time: now,
step: 4,
outbound_status: 'fin',
updated_at: now,

View File

@ -40,7 +40,7 @@ class ReportDefinitionMethodService extends MainService {
* @param {number} [data.id] 报表定义ID(正整数;不传视为新增)
* @param {string} data.name 报表名称(必填,≤100)
* @param {string} data.type 报表类型(注册方法 key,如 stockFlow;新增必填)
* @param {string} data.file_name 导出文件名模板(支持 {date};新增必填,≤200,兼容 fileName)
* @param {string} data.file_name 导出文件名模板(支持 {date}/{time}/{datetime}/{timestamp};新增必填,≤200,兼容 fileName)
* @param {Array<string>} data.fields 勾选字段 key 数组(新增必填,须为该类型注册字段子集)
* @param {number} [data.is_enabled] 是否启用(0/1)
* @param {string} [data.remark] 备注(≤500)

View File

@ -282,8 +282,10 @@ class InterceptAutoConfirmService extends MainService {
* 其余订单继续处理;每单失败不影响其他订单。
*
* 每个订单的拦截处理:
* 1. 更新订单:intercept_status=intercepted_at_warehouse、intercept_time=当前时间、
* step=4、outbound_status=fin,where 同时限定拦截状态白名单防并发误更新
* 1. 更新订单:intercept_status=intercepted_at_warehouse、step=4、outbound_status=fin,
* where 同时限定拦截状态白名单防并发误更新;
* **不写 intercept_time**(该字段恒为「最近一次发起拦截的通知时刻」,库内确定拦截不覆盖,
* 见 app/lib/intercept_time.js;库内确定拦截时刻以配送表 dispath_time 为准)
* 2. 同步更新运单表:is_intercept='Y'、is_back='Y'
* 3. 释放储位分配(cancelAllocateStorage 拦截模式,临时注入仓库上下文)
* 4. 释放订单锁(lock_status='none')
@ -376,9 +378,9 @@ class InterceptAutoConfirmService extends MainService {
try {
const now = new Date();
// 库内确定拦截不写 intercept_time(不覆盖通知拦截时刻),库内确定时刻以配送表 dispath_time 为准
const updateValues = {
intercept_status: 'intercepted_at_warehouse',
intercept_time: now,
step: 4,
outbound_status: 'fin',
updated_at: now,

View File

@ -181,18 +181,35 @@ class ReportService extends Service {
}
/**
* 构建导出文件名(支持 file_name 模板的 {date} 占位)。
* 构建导出文件名(支持 file_name 模板占位符)。
*
* 占位符(2026-09-10 扩充,均为本地时区):
* - `{date}`:数据日期(请求 params.bizDate,缺省服务器当天,`YYYY-MM-DD`)——语义不变;
* - `{time}`:生成时刻 `HHmmss`(如 `200745`);
* - `{datetime}`:`{date}_{time}`(如 `2026-09-09_200745`);
* - `{timestamp}`:生成时刻毫秒时间戳(如 `1789136465123`)。
*
* 用途:同一天多次投递/手动导出同一报表时,文件名带生成时刻可避免 COS 同名覆盖
*(同名文件会被后一次写覆盖,且 CDN 可能继续回源旧内容)。
*
* @param {Object} definition 报表定义视图
* @param {string} [bizDate=''] 数据日期(YYYY-MM-DD,缺省用今天)
* @param {Date} [now=new Date()] 生成时刻(渲染 {time}/{datetime}/{timestamp} 用,可注入供测试)
* @return {string} 文件名
*/
buildFilename(definition, bizDate = '') {
const dateText = String(bizDate || '').trim() || scheduleDateOf(new Date());
buildFilename(definition, bizDate = '', now = new Date()) {
const nowDate = now instanceof Date && !Number.isNaN(now.getTime()) ? now : new Date();
const dateText = String(bizDate || '').trim() || scheduleDateOf(nowDate);
const timeText = `${String(nowDate.getHours()).padStart(2, '0')}`
+ `${String(nowDate.getMinutes()).padStart(2, '0')}`
+ `${String(nowDate.getSeconds()).padStart(2, '0')}`;
const template = String((definition && definition.file_name) || '').trim()
|| `${String((definition && definition.name) || 'report')}_${dateText}.xlsx`;
const filename = template.includes('{date}')
? template.replace(/\{date\}/g, dateText)
: template;
const filename = template
.replace(/\{datetime\}/g, `${dateText}_${timeText}`)
.replace(/\{date\}/g, dateText)
.replace(/\{time\}/g, timeText)
.replace(/\{timestamp\}/g, String(nowDate.getTime()));
return filename.endsWith('.xlsx') || filename.endsWith('.xls') ? filename : `${filename}.xlsx`;
}

View File

@ -1,6 +1,7 @@
'use strict';
const sevenDayStockFlow = require('./sevenDayStockFlow');
const interceptOrder = require('./interceptOrder');
/**
* 报表内置查询器注册表。
@ -16,6 +17,7 @@ const sevenDayStockFlow = require('./sevenDayStockFlow');
*/
const QUERIES = {
stockFlow: sevenDayStockFlow,
interceptOrder,
};
/**
@ -33,6 +35,17 @@ const DESCRIPTIONS = [
},
fields: (Array.isArray(sevenDayStockFlow.fields) ? sevenDayStockFlow.fields : []).map(field => ({ ...field })),
},
{
key: 'interceptOrder',
title: '库内确定拦截订单明细',
description: '按配送表 dispath_time(订单迁移进配送表的时间)统计昨日库内确定拦截订单'
+ '(intercept_status=intercepted_at_warehouse),按商品明细展开(一个商品一行),'
+ '列与订单导出含明细模式(export_mode=item)一致,仅不含「商品图片」列',
window: {
...(interceptOrder.defaultWindow || { dayCount: 1, cutoverHour: 0 }),
},
fields: (Array.isArray(interceptOrder.fields) ? interceptOrder.fields : []).map(field => ({ ...field })),
},
];
/**

View File

@ -0,0 +1,477 @@
'use strict';
const { scheduleDateOf } = require('../../../../lib/report/day_window');
/**
* 库内确定拦截订单明细查询器(静态字段清单)。
*
* 前 46 列与 order.export(export_mode=item,按商品明细展开)的列对齐,
* 仅去掉「商品图片」列(报表渲染不支持内嵌图片,订单导出该列本身也不落地 URL);
* 另附加 3 列(订单导出无):
* `source_order_codes`(平台交易单号,取订单表源单号字段,位置紧跟「外部单号」)、
* `intercept_notice_time`(通知拦截时间,取配送表 intercept_time,为空时回落 ORDER_INTERCEPT_REQUEST 日志最早时间)、
* `intercept_confirm_time`(库内确定拦截时间,取配送表 dispath_time)。
* key 与查询器返回的行字段一一对应,type 统一为 string:
* 渲染层对 string 字段原样输出,不做 zeroToDash/yesNo 转换,
* 从而保证单元格取值与订单导出逐格一致(见 render.js renderCell 口径);
* 两个时间列由查询器格式化为 'YYYY-MM-DD HH:mm:ss' 字符串(与订单导出的时间列同格式)。
* @type {Array<Object>}
*/
const FIELDS = Object.freeze([
{ key: 'id', label: '订单ID', type: 'string' },
{ key: 'delivery_order_code', label: '订单号', type: 'string' },
{ key: 'external_order_code', label: '外部单号', type: 'string' },
{ key: 'source_order_codes', label: '平台交易单号', type: 'string' },
{ key: 'status', label: '订单状态', type: 'string' },
{ key: 'wave_no', label: '波次号', type: 'string' },
{ key: 'wave_index', label: '波次序号', type: 'string' },
{ key: 'store_id', label: '货主', type: 'string' },
{ key: 'sys_platform_name', label: '平台', type: 'string' },
{ key: 'create_channel', label: '来源', type: 'string' },
{ key: 'shop_nick', label: '店铺昵称', type: 'string' },
{ key: 'receiver_name', label: '收件人', type: 'string' },
{ key: 'receiver_mobile', label: '收件人电话', type: 'string' },
{ key: 'receiver_province', label: '省', type: 'string' },
{ key: 'receiver_city', label: '市', type: 'string' },
{ key: 'receiver_district', label: '区', type: 'string' },
{ key: 'receiver_town', label: '镇', type: 'string' },
{ key: 'receiver_detail', label: '详细地址', type: 'string' },
{ key: 'item_name', label: '仓库商品名称', type: 'string' },
{ key: 'item_barcode', label: '商品条码', type: 'string' },
{ key: 'item_quantity', label: '数量', type: 'string' },
{ key: 'logistics_name', label: '物流公司', type: 'string' },
{ key: 'waybill_code', label: '运单号', type: 'string' },
{ key: 'business_type', label: '业务类型', type: 'string' },
{ key: 'logistics_interface_name', label: '运单接口', type: 'string' },
{ key: 'package_material_id', label: '包材ID', type: 'string' },
{ key: 'package_material_code', label: '包材编码', type: 'string' },
{ key: 'package_material_name', label: '包材名称', type: 'string' },
{ key: 'waybill_allocated_at', label: '分配时间', type: 'string' },
{ key: 'items_count', label: '商品种数', type: 'string' },
{ key: 'items_total', label: '商品件数', type: 'string' },
{ key: 'items_weight', label: '商品重量', type: 'string' },
{ key: 'weighing_weight', label: '称重重量(g)', type: 'string' },
{ key: 'total_amount', label: '订单金额', type: 'string' },
{ key: 'got_amount', label: '实收金额', type: 'string' },
{ key: 'create_at', label: '创建时间', type: 'string' },
{ key: 'pay_time', label: '支付时间', type: 'string' },
{ key: 'delivery_time', label: '发货时间', type: 'string' },
{ key: 'outbound_status', label: '出库状态', type: 'string' },
{ key: 'inspection_status', label: '复核状态', type: 'string' },
{ key: 'recheck_status', label: '复核完成状态', type: 'string' },
{ key: 'post_status', label: '配货状态', type: 'string' },
{ key: 'pack_status', label: '打包状态', type: 'string' },
{ key: 'remark', label: '备注', type: 'string' },
{ key: 'buyer_message', label: '买家留言', type: 'string' },
{ key: 'seller_message', label: '卖家留言', type: 'string' },
{ key: 'archive_time', label: '归档时间', type: 'string' },
{ key: 'intercept_notice_time', label: '通知拦截时间', type: 'string' },
{ key: 'intercept_confirm_time', label: '库内确定拦截时间', type: 'string' },
]);
/**
* 查询器缺省窗口元数据(供 report.definition.typeList 展示)。
* 本查询器为「单个自然日」粒度:dayCount=1、cutoverHour=0(00:00 切日,非 stockFlow 的 07:00)。
* @type {{dayCount: number, cutoverHour: number}}
*/
const DEFAULT_WINDOW = Object.freeze({ dayCount: 1, cutoverHour: 0 });
/** 查询表位:配送表(订单出库迁移后的表位,dispath_time 为该表独有字段) */
const DISPATCH_TABLE_TYPE = 'dispatch';
/** 库内确定拦截状态(order.recheckOrder.confirmIntercept / intercept_auto_confirm 写入值) */
const INTERCEPTED_AT_WAREHOUSE_STATUS = 'intercepted_at_warehouse';
/** 明细展开模式(与 order.export export_mode=item 一致:一个商品一行) */
const EXPORT_MODE_ITEM = 'item';
/** 单页拉取订单数(复用订单导出分页大小) */
const DEFAULT_PAGE_SIZE = 1000;
/** 单次报表生成的最大明细行数保护(防御性上限,正常日拦截单量远低于该值) */
const MAX_EXPORT_ROWS = 200000;
/** 通知拦截(发起拦截请求)操作日志编码:wms_operation_log.operation_code */
const ORDER_INTERCEPT_REQUEST_CODE = 'ORDER_INTERCEPT_REQUEST';
/** 拦截时间富化(回查配送表 + 操作日志)单批订单ID数 */
const ENRICH_CHUNK_SIZE = 500;
/**
* 两位补零。
* @param {number} value 数值
* @return {string} 补零字符串
*/
function pad2(value) {
return String(value).padStart(2, '0');
}
/**
* 本地时区格式化为 'YYYY-MM-DD HH:mm:ss'。
* @param {Date} date 时间对象
* @return {string} 格式化结果
*/
function formatDateTime(date) {
return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`
+ ` ${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`;
}
/**
* 解析统计日与查询区间。
*
* 规则:
* 1. `params.bizDate`(或 `biz_date`)为合法 `YYYY-MM-DD` 时,按该日自然日整天统计;
* 2. 未传/非法时回落「昨日自然日」,即 [昨日 00:00:00.000, 今日 00:00:00.000);
* 3. **硬约束:统计日不得晚于昨天**——传入今天/未来日期一律回落昨日,
* 保证「今天生成/投递的报表不含今天的数据」(当天新迁入的拦截单只会在次日报表里出现);
* 4. 区间为本地时区半开区间(start 含、end 不含),通过 `new Date(y, m, d)` 构造,
* 规避夏令时导致的步进偏差。
*
* @param {Object} [params={}] 查询器业务参数
* @return {{bizDate: string, start: Date, end: Date}} 统计日与区间
*/
function resolveBizDayWindow(params = {}) {
const safeParams = params && typeof params === 'object' ? params : {};
const rawBizDate = String(safeParams.bizDate || safeParams.biz_date || '').trim();
const now = new Date();
const todayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0, 0);
const yesterdayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1, 0, 0, 0, 0);
let baseDate = null;
const matched = /^(\d{4})-(\d{2})-(\d{2})$/.exec(rawBizDate);
if (matched) {
const year = Number(matched[1]);
const month = Number(matched[2]);
const day = Number(matched[3]);
const candidate = new Date(year, month - 1, day, 0, 0, 0, 0);
if (
candidate.getFullYear() === year
&& candidate.getMonth() === month - 1
&& candidate.getDate() === day
) {
baseDate = candidate;
}
}
if (!baseDate) {
baseDate = yesterdayStart;
}
// 今天及以后一律回落昨日:今天生成/投递的报表只含昨天(及更早显式指定日)的数据
if (baseDate.getTime() >= todayStart.getTime()) {
baseDate = yesterdayStart;
}
const start = new Date(baseDate.getFullYear(), baseDate.getMonth(), baseDate.getDate(), 0, 0, 0, 0);
const end = new Date(baseDate.getFullYear(), baseDate.getMonth(), baseDate.getDate() + 1, 0, 0, 0, 0);
return { bizDate: scheduleDateOf(start), start, end };
}
/**
* 按字段清单裁剪订单导出行,保证报表列与订单导出 item 模式对齐并丢弃多余键(如 item_image)。
* @param {Object} row 订单导出行
* @return {Object} 仅含注册字段的报表行
*/
function pickReportRow(row = {}) {
const safeRow = row && typeof row === 'object' ? row : {};
const result = {};
for (const field of FIELDS) {
const value = safeRow[field.key];
result[field.key] = value === undefined ? '' : value;
}
return result;
}
/**
* 安全格式化时间列(与订单导出 formatDateSafe 口径一致:空值/无效值返回空字符串)。
* @param {*} value 时间原始值
* @param {Object} app Egg app 实例(取 app.formatDate)
* @return {string} 'YYYY-MM-DD HH:mm:ss' 或空字符串
*/
function formatTimeValue(value, app) {
if (value === null || value === undefined || value === '' || value === 0) {
return '';
}
const date = value instanceof Date ? value : new Date(value);
if (Number.isNaN(date.getTime()) || date.getTime() <= 0) {
return '';
}
return app && typeof app.formatDate === 'function' ? app.formatDate(date) : formatDateTime(date);
}
/**
* 富化报表附加列(按订单ID回查,分片避免大 IN 列表)。
*
* - `source_order_codes`(平台交易单号):直接取配送表同名字段(`mapOrderExportRow(item)` 不输出该列);
* - `intercept_notice_time`(通知拦截时间):主取配送表 `intercept_time`
* (自 2026-09-10 起该字段为「最近一次发起拦截的通知时刻」,确认拦截不再覆盖,
* 见 `app/lib/intercept_time.js`);该列为空时回落 `wms_operation_log` 中
* `operation_code = 'ORDER_INTERCEPT_REQUEST'` 的**最早**记录时间(历史数据兼容)。
* 回查日志按 `business_type='order' + business_id=订单ID + warehouse_id=当前仓库` 三重过滤:
* 订单 ID 按仓库发号,必须同仓隔离,禁止仅凭订单ID跨仓串读。
* - `intercept_confirm_time`(库内确定拦截时间):取配送表 `dispath_time`
* (订单迁移进配送表的时间;库内确定拦截后订单会走 outbound_status=fin 的自动迁移,故等价于库内确定拦截时刻)。
*
* 时间列均格式化为 'YYYY-MM-DD HH:mm:ss';查不到值时留空字符串。
*
* @param {Object} args 入参
* @param {Object} args.ctx Egg 上下文
* @param {Object} args.app Egg app 实例(时间格式化)
* @param {Object} args.orderModel 配送表模型(读取 source_order_codes/intercept_time/dispath_time)
* @param {number} args.warehouseId 仓库ID
* @param {Array<Object>} args.rows 报表行(原地写入附加列,行内需含订单ID `id`)
* @return {Promise<Array<Object>>} 富化后的行数组(同一引用)
*/
async function enrichInterceptFields({ ctx, app, orderModel, warehouseId, rows = [] }) {
const list = Array.isArray(rows) ? rows : [];
if (list.length === 0) {
return list;
}
const orderIds = [ ...new Set(
list
.map(row => Number(row && row.id) || 0)
.filter(orderId => orderId > 0)
) ];
if (orderIds.length === 0) {
return list;
}
const { Op, fn, col } = app.Sequelize;
const noticeTimeMap = new Map();
const confirmTimeMap = new Map();
const sourceOrderCodeMap = new Map();
const logModel = ctx.model && ctx.model.OperationLog;
for (let offset = 0; offset < orderIds.length; offset += ENRICH_CHUNK_SIZE) {
const chunk = orderIds.slice(offset, offset + ENRICH_CHUNK_SIZE);
// 平台交易单号(source_order_codes)+ 通知拦截时间(intercept_time)+ 库内确定拦截时间(dispath_time)
try {
const orderRows = await orderModel.findAll({
where: { id: { [Op.in]: chunk } },
attributes: [ 'id', 'source_order_codes', 'intercept_time', 'dispath_time' ],
raw: true,
});
for (const orderRow of (Array.isArray(orderRows) ? orderRows : [])) {
const orderId = Number(orderRow && orderRow.id) || 0;
if (orderId > 0) {
sourceOrderCodeMap.set(orderId, orderRow.source_order_codes);
noticeTimeMap.set(orderId, orderRow.intercept_time);
confirmTimeMap.set(orderId, orderRow.dispath_time);
}
}
} catch (error) {
ctx.logger.warn(
'[report.interceptOrder] 回查配送表附加列失败,平台交易单号/拦截时间列留空: %s',
error && error.message ? error.message : `${error}`
);
}
// 通知拦截时间(兜底,仅补齐主取为空的订单):操作日志最早一条 ORDER_INTERCEPT_REQUEST
if (logModel && typeof logModel.findAll === 'function') {
const pendingIds = chunk.filter(
orderId => orderId > 0 && (noticeTimeMap.get(orderId) === null || noticeTimeMap.get(orderId) === undefined)
);
if (pendingIds.length === 0) {
continue;
}
try {
const logRows = await logModel.findAll({
attributes: [ 'business_id', [ fn('MIN', col('created_at')), 'notice_time' ]],
where: {
business_type: 'order',
operation_code: ORDER_INTERCEPT_REQUEST_CODE,
warehouse_id: warehouseId,
business_id: { [Op.in]: pendingIds.map(orderId => String(orderId)) },
},
group: [ 'business_id' ],
raw: true,
});
for (const logRow of (Array.isArray(logRows) ? logRows : [])) {
const orderId = Number(logRow && logRow.business_id) || 0;
if (orderId > 0) {
noticeTimeMap.set(orderId, logRow.notice_time);
}
}
} catch (error) {
ctx.logger.warn(
'[report.interceptOrder] 回查通知拦截操作日志失败,通知拦截时间列留空: %s',
error && error.message ? error.message : `${error}`
);
}
}
}
for (const row of list) {
const orderId = Number(row && row.id) || 0;
const sourceOrderCodes = sourceOrderCodeMap.get(orderId);
row.source_order_codes = sourceOrderCodes === null || sourceOrderCodes === undefined
? ''
: String(sourceOrderCodes);
row.intercept_notice_time = formatTimeValue(noticeTimeMap.get(orderId), app);
row.intercept_confirm_time = formatTimeValue(confirmTimeMap.get(orderId), app);
}
return list;
}
/**
* 内置查询器:库内确定拦截订单明细(昨日迁入配送表的库内拦截订单,按商品明细展开)。
*
* 口径与假设(供测试复核):
* 1. 数据源:配送表 `wms_order_delivery_{warehouseId}_dispatch`,仅取
* `intercept_status = 'intercepted_at_warehouse'`(库内确定拦截;由
* `order.recheckOrder.confirmIntercept` 与 `intercept_auto_confirm` 写入,同时 step=4、outbound_status=fin);
* 2. 时间基准:`dispath_time`(订单迁移进配送表的时刻,配送表独有字段,由
* `orderDeliveryMigration.buildDispatchRow` 写入 `new Date()`);
* 3. 时间范围:默认「昨日自然日」[昨日 00:00:00.000, 今日 00:00:00.000) 本地时区半开区间,
* 可通过 `params.bizDate`(YYYY-MM-DD)指定更早的统计日;非法值回落昨日,
* **今天及以后的日期一律回落昨日**(今天生成/投递的报表永不含今天数据,
* 当天新迁入配送表的拦截单只会在次日报表中出现);
* 4. 明细粒度与列:复用 `orderExport.buildOrderExportPage` → `mapOrderExportRow(row, ctx, 'item')`,
* 因此状态中文翻译、货主备注、条码/商品名回落、运单汇总、包材等取值与订单导出 item 模式逐格一致;
* 列清单 = 订单导出 item 模式 47 列去掉「商品图片」列(46 列)+ 3 列附加列
* (平台交易单号 source_order_codes、通知拦截时间、库内确定拦截时间,共 49 列);
* 5. 无商品明细的订单输出一行订单级数据(运单字段汇总),与订单导出 item 模式一致;
* 6. 主维度:warehouseId 必填(配送表按仓库分表);storeId > 0 时追加 `store_id` 过滤
* (货主维度报表与投递),否则为仓库维度全量;
* 7. 排序:按订单 ID 升序分页拉取(单页 1000 单,循环至不足一页);
* 8. 附加列(订单导出 item 模式无此 3 列):
* - `source_order_codes`(平台交易单号)= 配送表 `source_order_codes` 原值
* (`mapOrderExportRow(item)` 不输出该列,由本查询器回查补充,位置紧跟「外部单号」);
* - `intercept_notice_time`(通知拦截时间)= 配送表 `intercept_time`
* (自 2026-09-10 起为「最近一次发起拦截的通知时刻」,确认拦截不再覆盖;
* 为空时回落 `wms_operation_log` 的 ORDER_INTERCEPT_REQUEST 最早记录,按同仓隔离查询);
* - `intercept_confirm_time`(库内确定拦截时间)= 配送表 `dispath_time`
* (订单迁移进配送表的时间,库内确定拦截后基本都会走出库迁移);
* 两个时间列格式化为 'YYYY-MM-DD HH:mm:ss';
* 8. 波次序号(wave_index):复用订单导出同款 `attachOrderWaveIndex`,该实现按登录上下文仓库
* 取值,定时投递(无 ctx.user)场景降级为 0,手工导出(仓库主体)为真实序号。
*
* @param {Object} args 查询器入参
* @param {Object} args.ctx Egg 上下文
* @param {number|null} args.storeId 货主ID(可选,<=0 时不按货主过滤)
* @param {number|null} args.warehouseId 仓库ID(必填)
* @param {Object} [args.params={}] 业务参数(bizDate 统计日覆盖)
* @return {Promise<{windows: Array<Object>, rows: Array<Object>, meta: Object}>} 查询结果
*/
async function interceptOrder({ ctx, storeId = null, warehouseId = null, params = {} }) {
const { app } = ctx;
const { Op } = app.Sequelize;
const normalizedWarehouseId = Number(warehouseId) || 0;
if (normalizedWarehouseId <= 0) {
throw new Error('interceptOrder 查询器缺少仓库维度 warehouseId');
}
const { bizDate, start, end } = resolveBizDayWindow(params);
const normalizedStoreId = Number(storeId) || 0;
const orderExport = ctx.service && ctx.service.systems ? ctx.service.systems.orderExport : null;
if (!orderExport || typeof orderExport.buildOrderExportPage !== 'function') {
throw new Error('订单导出服务不可用,无法复用订单明细口径(orderExport.buildOrderExportPage)');
}
const target = orderExport.resolveExportTarget({ tableType: DISPATCH_TABLE_TYPE });
const orderModel = await orderExport.getOrderModelByTableType(DISPATCH_TABLE_TYPE, normalizedWarehouseId);
const queryWhere = {
intercept_status: INTERCEPTED_AT_WAREHOUSE_STATUS,
dispath_time: {
[Op.gte]: start,
[Op.lt]: end,
},
};
if (normalizedStoreId > 0) {
queryWhere.store_id = normalizedStoreId;
}
const pageSize = Number(typeof orderExport.getExportPageSize === 'function'
? orderExport.getExportPageSize()
: 0) || DEFAULT_PAGE_SIZE;
const rows = [];
let orderCount = 0;
let page = 1;
let truncated = false;
for (;;) {
const pageResult = await orderExport.buildOrderExportPage({
page,
pageSize,
queryWhere,
order: [[ 'id', 'ASC' ]],
orderModel,
target,
warehouseId: normalizedWarehouseId,
mode: EXPORT_MODE_ITEM,
});
const pageOrderCount = Number(pageResult && pageResult.orderCount) || 0;
if (pageOrderCount <= 0) {
break;
}
const pageRows = Array.isArray(pageResult && pageResult.exportRows) ? pageResult.exportRows : [];
for (const pageRow of pageRows) {
rows.push(pickReportRow(pageRow));
if (rows.length >= MAX_EXPORT_ROWS) {
truncated = true;
break;
}
}
orderCount += pageOrderCount;
if (truncated || pageOrderCount < pageSize) {
break;
}
page += 1;
}
if (truncated) {
ctx.logger.warn(
'[report.interceptOrder] 明细行数达到上限 %s,已截断(bizDate=%s warehouseId=%s)',
MAX_EXPORT_ROWS,
bizDate,
normalizedWarehouseId
);
}
// 附加列:平台交易单号(source_order_codes)+ 通知拦截时间(配送表 intercept_time,日志兜底)
// + 库内确定拦截时间(配送表 dispath_time)
await enrichInterceptFields({
ctx,
app,
orderModel,
warehouseId: normalizedWarehouseId,
rows,
});
const noticeTimeFilledCount = rows.filter(row => String(row.intercept_notice_time || '').trim()).length;
const confirmTimeFilledCount = rows.filter(row => String(row.intercept_confirm_time || '').trim()).length;
return {
windows: [],
rows,
meta: {
bizDate,
startTime: formatDateTime(start),
endTime: formatDateTime(end),
warehouseId: normalizedWarehouseId,
storeId: normalizedStoreId,
interceptStatus: INTERCEPTED_AT_WAREHOUSE_STATUS,
timeField: 'dispath_time',
orderCount,
rowCount: rows.length,
noticeTimeFilledCount,
confirmTimeFilledCount,
truncated,
},
};
}
module.exports = interceptOrder;
module.exports.fields = FIELDS;
module.exports.defaultWindow = DEFAULT_WINDOW;
// 纯函数导出(供单测/校验脚本复核口径,不作为查询器调用入口)
module.exports.resolveBizDayWindow = resolveBizDayWindow;
module.exports.pickReportRow = pickReportRow;
module.exports.enrichInterceptFields = enrichInterceptFields;

View File

@ -358,7 +358,8 @@ class ReturnReceivedService extends Service {
* 更新退回运单关联订单的退回状态并写入操作记录(不处理库存信息)。
* - current 表(待处理):设置 intercept_status='returned'、step=4、outbound_status='fin' 触发自动转配送表;
* - dispatch 表(配送中):仅更新 intercept_status='returned';
* - 两条链路均同步写入拦截时间 intercept_time(当前时间);
* - 两条链路均**不写** intercept_time(该字段恒为「最近一次发起拦截的通知时刻」,
* 退回入库不覆盖,见 app/lib/intercept_time.js);
* - 不释放储位分配、不释放订单锁。
* 兼容 current/dispatch 分表:先查 current 表,不存在再查 dispatch 表。
*
@ -400,7 +401,6 @@ class ReturnReceivedService extends Service {
const updateFields = {
intercept_status: 'returned',
intercept_time: new Date(),
updated_at: new Date(),
};

View File

@ -22,7 +22,7 @@
| `id` | BIGINT UNSIGNED | 主键,报表定义ID(接口入参 `report_id`,唯一性由主键承担) |
| `name` | STRING(100) | 报表名称 |
| `type` | STRING(50) | 报表类型(内置查询器注册 key,如 `stockFlow`) |
| `file_name` | STRING(200) | 导出文件名模板(支持 `{date}` 占位,如 `7日出入库_{date}.xlsx`) |
| `file_name` | STRING(200) | 导出文件名模板(支持 `{date}` 数据日期、`{time}` 生成时刻 HHmmss、`{datetime}` 数据日期_生成时刻、`{timestamp}` 毫秒时间戳,如 `7日出入库_{date}.xlsx`、`库内拦截_{date}_{time}.xlsx`) |
| `fields` | JSON | 勾选的字段 key 数组(该类型注册字段的子集;列头/合并/样式/格式化由类型硬编码字段规格决定) |
| `is_enabled` | TINYINT(1) | 是否启用:0=停用 1=启用(导出只读 is_enabled=1 的定义) |
| `remark` | STRING(500) | 备注 |
@ -50,9 +50,13 @@ report.generate(method 层,异步任务,入参 report_id)
| key | 标题 | 说明 |
|---|---|---|
| `stockFlow` | 库存变化以及补货报表 | 按日窗口聚合出入库流水与正品库存,输出每 SKU 产品名称/条码/外部编码/每日出入库/待处理订单占用数/可用库存/7日总出库数量/推荐采购量与是否触发预警 |
| `interceptOrder` | 库内确定拦截订单明细 | 以配送表 `dispath_time`(订单迁移进配送表的时间)为时间基准,统计昨日自然日库内确定拦截订单(`intercept_status='intercepted_at_warehouse'`),按商品明细展开(一个商品一行),列与订单导出含明细模式(`order.export` `export_mode=item`)一致、仅不含「商品图片」列,并附 2 列拦截时间(通知拦截时间/库内确定拦截时间) |
`stockFlow` 缺省窗口参数:`window = { dayCount: 7, cutoverHour: 7 }`。
`interceptOrder` 缺省窗口参数:`window = { dayCount: 1, cutoverHour: 0 }`(单个自然日、 00:00 切日)。
该类型**不使用** `params.dayCount`/`params.cutoverHour` 入参,统计日由 `params.bizDate` 控制(缺省=昨日)。
`stockFlow` 全量字段清单(9 组列,顺序固定,`report.definition.typeList` 直接返回该规格):
| key | label | type | computed | asText | 说明 |
@ -92,6 +96,121 @@ report.generate(method 层,异步任务,入参 report_id)
推荐采购量补偿到不低于 30;预警判定由 `warnOf(ck_total, available, rk_total)` 计算。
行内仍计算 `rk_total`/日均/预计可售天数等字段供判定与复核,但不进入导出列清单。
### 2.2 interceptOrder 口径与假设(供测试复核)
1. **数据源**:配送表 `wms_order_delivery_{warehouse_id}_dispatch`(订单出库迁移后的表位;
查询器经 `orderExport.getOrderModelByTableType('dispatch', warehouseId)` 取动态模型)。
2. **拦截状态**:仅取 `intercept_status = 'intercepted_at_warehouse'`(库内确定拦截;由
`order.recheckOrder.confirmIntercept` 与 `intercept_auto_confirm` 写入,同时 `step=4`、`outbound_status=fin`)。
注意该枚举**没有** `intercepted` 值,历史遗留值不参与统计。
3. **时间基准**:`dispath_time`(配送表独有列,= 订单迁移进配送表的时刻,由
`orderDeliveryMigration.buildDispatchRow` 写入 `new Date()`;2026-09-07 迁移 `20260907120000` 上线,
仅 dispatch 分表有该列,当前分表/历史表/委外表无此列)。
4. **统计区间**:默认「昨日自然日」`[昨日 00:00:00.000, 今日 00:00:00.000)`(本地时区半开区间,
与 stockFlow 的 07:00 切日口径**不同**);`params.bizDate`(`YYYY-MM-DD`,兼容 `biz_date`)
传入且为真实存在的日期时,按该日整天统计,缺省/非法一律回落昨日自然日。
**统计日不得晚于昨天**:传今天/未来日期一律回落昨日(上界恒为今日 00:00:00,不含),
保证「今天生成/投递的报表不含今天的数据」——当天新迁入配送表的拦截单只会出现在次日报表;
比昨天更早的显式日期仍被尊重(补数场景)。
5. **明细粒度与取值**:按订单 ID 升序分页(单页 1000 单,循环至不足一页)复用
`orderExport.buildOrderExportPage({ mode: 'item' })` → `mapOrderExportRow(item)`,因此状态中文翻译、
货主备注(`wms_store_warehouse.store_remask`)、仓库商品名/条码回落、运单汇总(多运单逗号拼接、
主/子单号业务类型、包材编码/名称、称重汇总)、收件人字段等与订单导出逐格一致;
行再按注册字段裁剪(丢弃 `item_image` 等未注册键,缺失值回落空字符串)。
6. **无商品明细的订单**:输出一行订单级数据(运单字段汇总、商品列为空),与订单导出 item 模式一致。
7. **主维度**:`warehouseId` 必填(配送表按仓库分表;`<=0` 抛「interceptOrder 查询器缺少仓库维度 warehouseId」);
`storeId > 0` 时追加 `store_id` 过滤(货主维度报表/定时投递),否则仓库维度全量。
8. **行数保护与 meta**:明细行数达 `MAX_EXPORT_ROWS = 200000` 时截断并打 warn(`meta.truncated = true`);
`meta` 返回 `bizDate/startTime/endTime/warehouseId/storeId/interceptStatus/timeField/orderCount/rowCount/truncated`。
9. **波次序号**:`wave_index` 沿用订单导出同款 `attachOrderWaveIndex`(仓库ID取 `ctx.user.store_id`),
定时投递(无 `ctx.user`)场景该列降级为 0,仓库主体手工导出为真实序号。
10. **附加列(订单导出 item 模式无此 3 列)**:
- `source_order_codes`(平台交易单号)= 配送表 `source_order_codes` 原值
(`mapOrderExportRow(item)` 不输出该列,由查询器回查补充,列位置紧跟「外部单号」);
- `intercept_notice_time`(通知拦截时间)= 配送表 `intercept_time`。该字段自 2026-09-10 起
语义统一为「最近一次发起拦截的通知时刻」(见 `app/lib/intercept_time.js`):首次发起时写入、
重复发起不覆盖、库内拦截确认/退回入库均不覆盖、取消/解除拦截置空;
若该列为空则回落 `wms_operation_log` 中 `operation_code='ORDER_INTERCEPT_REQUEST'` 的最早记录时间
(历史数据兼容,查询按 `business_type='order'` + `business_id=订单ID` + `warehouse_id=当前仓库`
三重过滤,订单 ID 按仓库发号必须同仓隔离);
- `intercept_confirm_time`(库内确定拦截时间)= 配送表 `dispath_time`
(订单迁移进配送表的时间;库内确定拦截后订单会走 `outbound_status=fin` 的自动迁移,故等价于库内确定拦截时刻。
不再使用 `intercept_time`,因为确认时不再覆盖该字段);
- 两列均格式化为 `YYYY-MM-DD HH:mm:ss`(空值输出空字符串);
`meta.noticeTimeFilledCount` / `meta.confirmTimeFilledCount` 返回两列的有值行数,便于核对覆盖率。
字段清单(49 列,顺序固定,全为 `string` 静态列;`report.definition.typeList` 直接返回该规格):
| key | label |
|---|---|
| `id` | 订单ID |
| `delivery_order_code` | 订单号 |
| `external_order_code` | 外部单号 |
| `source_order_codes` | 平台交易单号 |
| `status` | 订单状态 |
| `wave_no` | 波次号 |
| `wave_index` | 波次序号 |
| `store_id` | 货主 |
| `sys_platform_name` | 平台 |
| `create_channel` | 来源 |
| `shop_nick` | 店铺昵称 |
| `receiver_name` | 收件人 |
| `receiver_mobile` | 收件人电话 |
| `receiver_province` | 省 |
| `receiver_city` | 市 |
| `receiver_district` | 区 |
| `receiver_town` | 镇 |
| `receiver_detail` | 详细地址 |
| `item_name` | 仓库商品名称 |
| `item_barcode` | 商品条码 |
| `item_quantity` | 数量 |
| `logistics_name` | 物流公司 |
| `waybill_code` | 运单号 |
| `business_type` | 业务类型 |
| `logistics_interface_name` | 运单接口 |
| `package_material_id` | 包材ID |
| `package_material_code` | 包材编码 |
| `package_material_name` | 包材名称 |
| `waybill_allocated_at` | 分配时间 |
| `items_count` | 商品种数 |
| `items_total` | 商品件数 |
| `items_weight` | 商品重量 |
| `weighing_weight` | 称重重量(g) |
| `total_amount` | 订单金额 |
| `got_amount` | 实收金额 |
| `create_at` | 创建时间 |
| `pay_time` | 支付时间 |
| `delivery_time` | 发货时间 |
| `outbound_status` | 出库状态 |
| `inspection_status` | 复核状态 |
| `recheck_status` | 复核完成状态 |
| `post_status` | 配货状态 |
| `pack_status` | 打包状态 |
| `remark` | 备注 |
| `buyer_message` | 买家留言 |
| `seller_message` | 卖家留言 |
| `archive_time` | 归档时间 |
| `intercept_notice_time` | 通知拦截时间 |
| `intercept_confirm_time` | 库内确定拦截时间 |
与订单导出 item 模式的差异:不含 `item_image`(商品图片)列,另附加 3 列——
`source_order_codes`(平台交易单号,位置紧跟「外部单号」)、`intercept_notice_time`(通知拦截时间)、
`intercept_confirm_time`(库内确定拦截时间),订单导出无这 3 列。配置示例:
```json
// report.definition.save(新增拦截明细报表)
{
"name": "库内确定拦截订单明细",
"type": "interceptOrder",
"file_name": "库内确定拦截订单明细_{date}.xlsx",
"fields": ["id", "delivery_order_code", "external_order_code", "waybill_code", "item_name", "item_quantity", "create_at"],
"remark": "每日导出昨日库内确定拦截订单明细"
}
```
> 注:`fields` 必须为该类型注册字段的子集(新增时必填,且**不能为空数组**——渲染层按勾选字段生成列,
> 空数组会得到无列的空表;需全部 49 列时请显式列出全部 key),完整可选 key 见上文清单。
## 3. 渲染规则(renderSheetByType,无 sheet_config)
列定义不再由 `sheet_config.columns` 配置,而由**注册类型字段规格硬编码自动生成**
@ -116,7 +235,13 @@ report.generate(method 层,异步任务,入参 report_id)
## 4. 导出文件名(file_name)与上传目录(fileKey)
- `file_name` 为文件名模板,`{date}` 替换为数据日期(请求 `params.bizDate`,缺省服务器当天,`YYYY-MM-DD`)。
- `file_name` 为文件名模板,占位符(本地时区,2026-09-10 扩充):
- `{date}`:数据日期(请求 `params.bizDate`,缺省服务器当天,`YYYY-MM-DD`);
- `{time}`:生成时刻 `HHmmss`(如 `200745`);
- `{datetime}`:`{date}_{time}`(如 `2026-09-09_200745`);
- `{timestamp}`:生成时刻毫秒时间戳。
同一天多次投递/手动导出同一报表时,文件名带生成时刻(如 `interceptOrder_{date}_{time}`)可避免 COS 同名覆盖
(同名文件会被后一次写覆盖,且 CDN 可能仍回源旧内容)。
- 缺省模板:`<name>_<date>.xlsx`;不以 `.xlsx`/`.xls` 结尾时自动补 `.xlsx`。
- 上传目录(COS 文件 key)按「报表定义 + 货主/仓库」维度隔离(2026-08-31 修复「货主限制不符」缺陷:
修复前统一为 `exports/report/<report_id>/`,不同货主的报表文件会互相覆盖):
@ -245,7 +370,7 @@ report.generate(method 层,异步任务,入参 report_id)
}
```
- `type` 必须命中注册表(当前仅 `stockFlow`,未知报「未知的报表类型: <type>」);
- `type` 必须命中注册表(当前 `stockFlow`、`interceptOrder`,未知报「未知的报表类型: <type>」);
`fields` 必须为该类型注册字段子集(9 组列任意勾选,含非法 key 报可读错误并列出可用字段)。
- `file_name` 兼容 `fileName` 驼峰写法(驼峰优先);新增必填 `name`/`type`/`file_name`/`fields`;
更新按 `id` upsert,未传字段不覆盖;软删记录命中时自动恢复。
@ -310,6 +435,10 @@ report.generate(method 层,异步任务,入参 report_id)
}
```
> 说明:`list` 按注册顺序返回**全部**注册类型(当前 `stockFlow`、`interceptOrder`),上例仅展开 `stockFlow`;
> `interceptOrder` 的 `window` 为 `{ "dayCount": 1, "cutoverHour": 0 }`,`fields` 为 46 个 `type: "string"` 静态列
> (列清单与口径见 2.2 节)。
字段元素结构:`{ key, label, type, computed?, asText?, children? }`:
- `type`:`string` / `number` / `boolean` / `array`;

View File

@ -1,4 +1,127 @@
[
{
"version": "2026.09.10-report-filename-time-placeholder",
"date": "2026-09-10",
"type": "changed",
"summary": "报表导出文件名模板新增占位符:{time}(生成时刻 HHmmss)、{datetime}(数据日期_生成时刻)、{timestamp}(生成时刻毫秒时间戳);{date} 语义保持不变(仍为数据日期 params.bizDate,缺省服务器当天)。用于同一天多次投递/手动导出同一报表时避免 COS 同名覆盖(同名文件被后一次写覆盖且 CDN 可能仍回源旧内容,表现为「下载到的还是旧版列」)。缺省文件名模板不变,存量定义不受影响(未改 file_name 者行为完全不变)。",
"methods": [
"report.generate",
"report.definition.save",
"report.definition.list",
"report.deliveryPlan.save"
],
"module": "report",
"notes": [
"app/service/systems/report.js:buildFilename(definition, bizDate, now) 新增第三参 now(生成时刻,缺省 new Date(),可注入供测试);替换顺序 {datetime} -> {date} -> {time} -> {timestamp};{date} 取值逻辑(params.bizDate || 服务器当天)与既有行为完全一致;缺省模板仍为 <name>_<date>.xlsx。",
"根因与实测:2026-09-10 同一 (store 1000000, 定义 3, biz_date 2026-09-09) 在 19:40、19:58、20:07 三次投递使用同名 interceptOrder_2026-09-09.xlsx,COS 对象被覆盖且 CDN 仍回源旧版本,导致用户看到 10 列旧表(缺「仓库商品名称」)。定义改为 interceptOrder_{date}_{time} 后手动导出产出 interceptOrder_2026-09-09_201533.xlsx,文件 13 列(含仓库商品名称/平台交易单号/两列拦截时间)与定义勾选一致。",
"app/model/report_definition.js 字段注释、app/service/systemMethods/report/definition.js JSDoc、methods/system.json(report.definition.save description 与 file_name 参数/响应/定义对象说明共 4 处)、docs/report-config-guide.md 第 1 节模型表与第 4 节文件名说明同步为四种占位符;docMeta.version 0.3.108 -> 0.3.109,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。",
"测试:test/report_systems_engine.cjs 的 buildFilename 用例扩充({date}_{time}、{datetime}、{timestamp}、不同生成时刻文件名不同、未传 now 回落当前时刻、{date} 语义不变、缺省模板与自动补 .xlsx 保持);13 个 test/report_*.cjs 全部通过,ESLint 0 error。",
"数据/配置变更(仅开发库,已披露):wms_report_definition id=3 的 file_name 由 interceptOrder_{date} 改为 interceptOrder_{date}_{time},使定义重新投递/手动导出时文件名唯一。",
"兼容性:占位符为新增能力,未使用新占位符的既有定义(如 7日出入库数据 7daysStockFlow_{date})输出文件名与行为完全不变;未执行部署脚本,未改动生产数据。"
]
},
{
"version": "2026.09.10-intercept-order-source-order-codes",
"date": "2026-09-10",
"type": "added",
"summary": "interceptOrder(库内确定拦截订单明细)报表新增导出列「平台交易单号」(字段 key source_order_codes,取配送表 wms_order_delivery_*.source_order_codes 原值,列位置紧跟「外部单号」)。注册字段数 48 -> 49(订单导出 item 模式去掉商品图片 46 列 + 附加 3 列:平台交易单号 + 通知拦截时间 + 库内确定拦截时间);接口入参/响应契约不变,stockFlow 与 order.export 均不受影响。",
"methods": [
"report.definition.typeList",
"report.generate",
"report.definition.save"
],
"module": "report",
"notes": [
"app/service/systems/report/queries/interceptOrder.js:FIELDS 在 external_order_code(外部单号)之后插入 { key: 'source_order_codes', label: '平台交易单号', type: 'string' }。",
"app/service/systems/report/queries/interceptOrder.js:enrichInterceptTimes 重命名为 enrichInterceptFields(已导出),回查 attributes 由 [id, intercept_time, dispath_time] 扩为 [id, source_order_codes, intercept_time, dispath_time],同一批查询同时回填平台交易单号(null/undefined 归一化为空字符串);仍按 500 订单分片、异常只 warn 不阻断报表。",
"取数原因:明细行来自 orderExport.buildOrderExportPage(mode=item) → mapOrderExportRow(item),该映射不输出 source_order_codes,故由查询器回查补充。",
"测试:test/report_intercept_order_fields.cjs 同步为 49 列断言(预期列序 = 订单导出 item 去掉商品图片,在 external_order_code 后插入平台交易单号、末尾 2 列拦截时间),并补充平台交易单号取值与回查 attributes 断言;test/report_systems_engine.cjs 注册字段数断言 48 -> 49;13 个 report_*.cjs + test/intercept_time_lifecycle.cjs 全部通过,ESLint 0 error。",
"端到端:script/tmp-verify-intercept-order-dev.cjs D 段增加平台交易单号与配送表 source_order_codes 的逐单交叉核对(通过);同时修正该脚本 A 段旧断言(原先假设开发库昨日 0 行,现改为校验 meta.orderCount 与明细去重订单数一致)。",
"生产/开发验证:投递计划 id=2(货主 1000000 → 仓 100000,时间点 19:40)于 2026-09-10 19:40:45 投递成功(wms_report_delivery_log id=16 status=delivered,文件 exports/report/3/store-1000000/20260910/interceptOrder_2026-09-09.xlsx),文件内容核对为 1 表头 + 4 行明细(对应补测的 3 单)。",
"methods/system.json:report.definition.typeList description 与 fields 说明同步为 49 列(含平台交易单号);docMeta.version 0.3.107 -> 0.3.108,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。",
"docs/report-config-guide.md 2.2 节:字段清单新增 source_order_codes 行(紧跟 external_order_code)、列数 48 -> 49、第 10 条口径改为「附加列(3 列)」并说明平台交易单号来源;AI_METHOD_ROUTING.md report 速查同步。",
"注意:报表定义的 fields 需显式勾选 source_order_codes 才会出现在导出列中(已有定义不动则不输出该列);本次未修改任何已有 wms_report_definition 配置行,未执行部署脚本。"
]
},
{
"version": "2026.09.10-intercept-time-lifecycle",
"date": "2026-09-10",
"type": "changed",
"summary": "拦截时间 intercept_time 口径调整(wms_order_delivery):统一为「最近一次发起拦截的通知时刻」——发起/通知拦截仅**首次写入**(重复发起不覆盖已有值),库内拦截确认(order.recheckOrder.confirmIntercept / order.recheckOrder.interceptScan / 定时自动确认)与退回入库(returned)**不再写该字段**,取消/解除拦截(order.pendingOrder.batchUnintercept)与订单克隆重置**置空 null**;「库内确定拦截时刻」改用配送表 dispath_time(订单迁移进配送表的时间)。同步调整 interceptOrder 报表两列:通知拦截时间 intercept_notice_time = 配送表 intercept_time(为空回落 ORDER_INTERCEPT_REQUEST 操作日志最早一条),库内确定拦截时间 intercept_confirm_time = 配送表 dispath_time(原 key intercept_time 更名;该报表类型尚未落库定义行,无兼容问题)。",
"methods": [
"order.pendingOrder.batchIntercept",
"order.pendingOrder.batchUnintercept",
"order.pendingOrder.cloneOrder",
"order.recheckOrder.confirmIntercept",
"order.recheckOrder.interceptScan",
"report.definition.typeList",
"report.generate"
],
"module": "order",
"notes": [
"app/lib/intercept_time.js(新增):拦截时间字段口径工具(纯函数):isEmptyInterceptTime、buildNoticeTimePatch(currentValue, now)(空值才写入,已有值返回空对象=不覆盖)、pickNoticeTimeOrderIds(rows)(批量场景筛出尚未写入通知时刻的订单ID,去重保序);文件头注释固化生命周期口径(首次写入/不覆盖/取消置空/库内确定时刻改用 dispath_time)。",
"发起/通知拦截(首次写入,不覆盖):app/service/qimenMethods/order.js(intercepting/requested 两处 existingOrder.update 改为 ...buildNoticeTimePatch(existingOrder.intercept_time, noticeNow))、app/service/openapiMethods/order.js(intercepting)、app/service/inbox/functions.js(两处波次感知拦截:订单查询 attributes 增补 intercept_time,主更新只写 intercept_status,随后仅对 pickNoticeTimeOrderIds 命中的订单补写 intercept_time)、app/service/systemMethods/order/pendingOrder.js(取消订单转拦截的 syncedOrders 批量更新、batchIntercept 分批更新:同样先取空值订单子集再补写)。",
"库内拦截确认不再覆盖:app/service/systems/intercept_auto_confirm.js(confirmInterceptForOrderIds 的 updateValues 移除 intercept_time)、app/service/systemMethods/order/recheckOrder.js(interceptScan 的 orderModel.update 移除 intercept_time)。app/service/systems/return_received.js(退回入库 updateFields 移除 intercept_time)。",
"取消/清空:app/service/systemMethods/order/pendingOrder.js batchUnintercept 保持 intercept_time=null(解除拦截置空);cloneOrder 的 RESET_FIELDS 新增 intercept_time=null(避免克隆重置新单继承原单发起拦截时刻)。",
"interceptOrder 报表(app/service/systems/report/queries/interceptOrder.js):enrichInterceptTimes 改为 attributes=[id, intercept_time, dispath_time];intercept_notice_time ← intercept_time(为空时才回落 wms_operation_log 的 ORDER_INTERCEPT_REQUEST 最早记录,同仓隔离 business_type/business_id/warehouse_id 三重过滤,主取有值时不查日志);intercept_confirm_time ← dispath_time;meta 计数更名 confirmTimeFilledCount(原 interceptTimeFilledCount)。",
"测试:新增 test/intercept_time_lifecycle.cjs(纯函数 3 例 + 写入点静态守卫 4 例:确认链路不得同写 intercepted_at_warehouse 与 intercept_time、发起链路使用首次写入工具、取消与克隆重置置空、退回入库不覆盖);test/report_intercept_order_fields.cjs 同步更新(末 2 列 key、dispath_time 作为库内确定拦截时间、日志兜底用例、缺失/模型不可用降级),共 18 例;test/report_*.cjs 13 个文件 + 新测试全部通过;ESLint 0 error。",
"端到端校验(只读、无写操作):script/tmp-verify-intercept-order-dev.cjs D 段改为对开发库真实订单交叉核对「通知拦截时间=intercept_time(空时回落日志)」与「库内确定拦截时间=dispath_time」,与直连 SQL 一致。",
"兼容性与风险:intercept_time 在本次上线前的历史数据可能仍是确认时刻(旧逻辑覆盖所致),这部分历史行的「通知拦截时间」不可靠;报表按「昨日」取数,上线次日起数据即为新口径。自动确认定时任务仍以 intercept_time 作为「发起后超时」判定依据,语义反而更准确(未被确认覆盖)。",
"methods/system.json:order.pendingOrder.batchIntercept(首次写入不覆盖 + 取消清空说明)、order.pendingOrder.batchUnintercept(解除拦截清空 intercept_time)、order.recheckOrder.confirmIntercept 与 order.recheckOrder.interceptScan(确认不写 intercept_time、库内确定时刻以 dispath_time 为准)description 同步;report.definition.typeList 字段清单描述 key 更新为 intercept_confirm_time;docMeta.version 0.3.106 -> 0.3.107,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。",
"docs/report-config-guide.md 2.2 节第 10 条与字段清单、AI_METHOD_ROUTING.md report 速查(新增拦截时间口径变更条目)同步;本次未执行任何数据库/Redis 写操作,未运行部署脚本。"
]
},
{
"version": "2026.09.10-intercept-order-time-columns",
"date": "2026-09-10",
"type": "added",
"summary": "interceptOrder(库内确定拦截订单明细)报表新增导出列「通知拦截时间」与「库内确定拦截时间」:intercept_time(库内确定拦截时间)= 配送表 intercept_time(确认拦截时写入);intercept_notice_time(通知拦截时间)= wms_operation_log 中 operation_code='ORDER_INTERCEPT_REQUEST' 的最早记录时间(发起/通知拦截时刻,因为 intercept_time 在确认时会被覆盖,只能从操作日志反查,按订单ID+仓库ID同仓隔离;日志缺失时该列留空)。两列均格式化为 YYYY-MM-DD HH:mm:ss,列排在字段清单末尾,注册字段数 46 -> 48;接口入参/响应契约与 stockFlow 均不受影响。",
"methods": [
"report.definition.typeList",
"report.generate",
"report.definition.save"
],
"module": "report",
"notes": [
"app/service/systems/report/queries/interceptOrder.js:FIELDS 末尾新增 intercept_notice_time(label 通知拦截时间)、intercept_time(label 库内确定拦截时间),type 均为 string(渲染层原样输出保留与订单导出 item 模式一致的零转换口径);列顺序 = 订单导出 item 模式 47 列去掉商品图片(46)+ 末 2 列拦截时间,共 48 列。",
"app/service/systems/report/queries/interceptOrder.js:新增 enrichInterceptTimes(已导出供单测/脚本复核)——按订单ID分片(ENRICH_CHUNK_SIZE=500)回查:1)配送表模型 findAll(attributes: id/intercept_time) 取库内确定拦截时间;2)OperationLog.findAll(attributes: business_id + MIN(created_at) 别名 notice_time,group by business_id)取通知拦截时间,where 限定 business_type='order' + operation_code='ORDER_INTERCEPT_REQUEST' + warehouse_id=当前仓库 + business_id IN(订单ID字符串化)。两列分别格式化为 YYYY-MM-DD HH:mm:ss(空值/无效值空字符串,与订单导出 formatDateSafe 口径一致);任一回查异常只 warn 并留空,不影响报表主流程;OperationLog 模型缺失时跳过日志查询。",
"同仓隔离:订单 ID 按仓库发号(wms_order_id_location_{wh}),日志查询必须带 warehouse_id,禁止仅凭订单ID跨仓串读(与 order_express 同仓隔离修复同口径)。",
"app/service/systems/report/queries/interceptOrder.js:查询器返回 meta 新增 noticeTimeFilledCount / interceptTimeFilledCount(两列有值行数),便于核对日志覆盖率;rows 为同一行对象的拦截时间列赋值(同一订单的多条商品明细行同值)。",
"测试:test/report_intercept_order_fields.cjs 新增 2 例(拦截时间两列取值/查询条件/分组断言;空值与 OperationLog 模型不可用降级),并同步列数断言 46 -> 48(前 46 列仍与订单导出 item 模式逐列对齐,末 2 列固定为拦截时间);test/report_systems_engine.cjs 注册表字段数断言同步为 48。test/report_*.cjs 13 个文件全部通过。",
"真实数据校验(只读、无写操作):script/tmp-verify-intercept-order-dev.cjs 新增 D 段——以 egg 真实上下文调用 enrichInterceptTimes 对开发库 5 个库内确定拦截订单富化,并与直连 SQL(配送表 intercept_time、wms_operation_log 的 MIN(created_at))逐单交叉核对一致(开发库这 5 单均无 ORDER_INTERCEPT_REQUEST 日志,故通知拦截时间为空,符合预期);渲染表头列数校验同步为 48 且末两列表头为拦截时间列。",
"methods/system.json:report.definition.typeList 的 description 与 fields 说明同步为 48 列(前 46 列对齐订单导出 item 模式去掉商品图片,末 2 列为拦截时间);docMeta.version 0.3.105 -> 0.3.106,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。",
"docs/report-config-guide.md 2.2 节:字段清单补 2 行拦截时间列、新增第 10 条口径(两列来源/同仓隔离/空值语义/meta 计数),注册类型表与「与订单导出 item 模式差异」说明同步更新;AI_METHOD_ROUTING.md report 速查同步(48 列 + 两个时间列来源)。",
"兼容性:仅为报表列扩展(新报表类型尚未在 wms_report_definition 落库定义行,无存量定义受影响);stockFlow 与 order.export 列口径、report.generate / report.deliveryPlan 链路均未改动。"
]
},
{
"version": "2026.09.10-report-intercept-order-type",
"date": "2026-09-10",
"type": "added",
"summary": "通用报表新增注册类型 interceptOrder(库内确定拦截订单明细):以配送表 dispath_time(订单迁移进配送表的时间)为时间基准,统计昨日(自然日 [昨日 00:00:00, 今日 00:00:00) 本地时区半开区间)库内确定拦截订单(intercept_status=intercepted_at_warehouse),**统计日不得晚于昨天**(params.bizDate 传今天/未来一律回落昨日,今天发出去的报表不含今天数据;比昨天更早的显式日期仍被尊重以支持补数),按商品明细展开(一个商品一行),列与订单导出含明细模式(order.export export_mode=item)完全对齐、仅去掉「商品图片」列(共 46 列)。报表定义 type 填 interceptOrder 即可使用,report.generate / report.deliveryPlan / wms_report_definition 结构均无需变更。",
"methods": [
"report.definition.typeList",
"report.generate",
"report.definition.save"
],
"module": "report",
"notes": [
"app/service/systems/report/queries/interceptOrder.js(新增):查询器签名与 stockFlow 一致 async ({ctx, storeId, warehouseId, params}) => ({windows: [], rows, meta})。数据源为配送表 wms_order_delivery_{warehouseId}_dispatch(经 orderExport.getOrderModelByTableType('dispatch', warehouseId) 取模型),过滤 intercept_status='intercepted_at_warehouse' 且 dispath_time ∈ [统计日 00:00:00, 次日 00:00:00);warehouseId 必填(<=0 抛「interceptOrder 查询器缺少仓库维度 warehouseId」),storeId>0 时追加 store_id 过滤(货主维度报表/投递),否则仓库维度全量。",
"明细口径复用订单导出链路:按单页 1000 单分页循环(不足一页终止)调用 orderExport.buildOrderExportPage({ mode: 'item' }),即复用 mapOrderExportRow(item) 的状态中文翻译、货主备注、仓库商品名/条码回落、运单汇总、包材、收件人脱敏等取值,逐格与订单导出 item 模式一致;行再经 pickReportRow 按注册字段裁剪(丢弃 item_image 等多余键,缺失值回落空字符串)。",
"统计日解析 resolveBizDayWindow:params.bizDate(兼容 biz_date)为真实存在的 YYYY-MM-DD 时按该自然日整天统计,缺省/非法一律回落昨日自然日;区间左闭右开,用 new Date(y, m, d) 构造规避夏令时步进偏差。Sequelize 未配置 timezone(默认 UTC)+ MySQL 时区 UTC,dispath_time 写入(orderDeliveryMigration.buildDispatchRow 写 new Date())与本查询的时间过滤经同一序列化路径,口径自洽。",
"字段清单 FIELDS 共 46 列,与 order.export 的 ORDER_EXPORT_ITEM_COLUMNS(47 列)逐列对齐并去掉「商品图片」列,key/label/顺序一致;type 统一为 string(渲染层 renderCell 原样输出,不做 zeroToDash/yesNo 转换,且不声明 asText),以保证单元格取值与订单导出一致;无 array 展开列,windows 恒为空数组、单行表头、无表头合并。",
"app/service/systems/report/queries/index.js:QUERIES 注册 interceptOrder,DESCRIPTIONS 新增条目(title「库内确定拦截订单明细」、window {dayCount: 1, cutoverHour: 0}),report.definition.typeList 自动带出 46 列字段元数据供报表定义勾选。",
"行数保护与元信息:明细行数达 MAX_EXPORT_ROWS=200000 时截断并打 warn(meta.truncated=true);meta 返回 bizDate/startTime/endTime/warehouseId/storeId/interceptStatus/timeField/orderCount/rowCount/truncated 供复核。",
"波次序号(wave_index)沿用订单导出同款 attachOrderWaveIndex(仓库ID取 ctx.user.store_id),定时投递(无 ctx.user)场景该列降级为 0,仓库主体手工导出为真实序号(与 order.export 行为一致)。",
"统计日硬约束(同日补充):resolveBizDayWindow 解析出统计日后统一校验 baseDate >= 今日 00:00:00 时回落昨日——params.bizDate 传今天/未来(含手工导出误传当天)时查询区间仍为 [昨日 00:00:00, 今日 00:00:00),保证「今天发出去不含今天」;比昨天更早的显式日期仍被尊重(补数场景)。测试:test/report_intercept_order_fields.cjs 新增「硬约束:统计日不得晚于昨天」与「params.bizDate 传今天:查询区间仍为昨日」两例(共 16 例)。",
"测试:新增 test/report_intercept_order_fields.cjs(14 例:字段与订单导出 item 逐列对齐、pickReportRow 裁剪、统计日区间解析、查询器 mock 链路含分页/where/meta/storeId 过滤与错误分支);同步修正 test/report_systems_engine.cjs 与 test/report_stockflow_fields.cjs 中「注册表仅 1 种类型」的旧断言(改为按 key 定位并断言注册顺序 stockFlow → interceptOrder)。test/report_*.cjs 共 13 个文件全部通过。",
"端到端校验(只读、无写操作):script/tmp-verify-intercept-order-dev.cjs 以 egg 真实上下文在开发库跑通查询器(meta 正确、开发库历史拦截单 dispath_time 为 NULL 故昨日命中 0 行)、真实拦截订单 5 单 → 9 条商品明细行的取值映射,以及 renderSheetByType 渲染(表头 46 列、单行表头、无合并、无 textColumns)。",
"methods/system.json:report.generate description 类型举例补 interceptOrder;params.bizDate 说明补充「同时是 interceptOrder 的统计日覆盖(缺省昨日自然日)」;params.dayCount/params.cutoverHour 标注仅 stockFlow 生效;report.definition.typeList 的 description、response.list、window.dayCount、window.cutoverHour、fields 说明同步为两种类型口径;docMeta.version 0.3.104 -> 0.3.105,updatedAt 保持 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位。",
"docs/report-config-guide.md:新增注册类型行、46 列字段清单与 interceptOrder 口径章节;wms_report_definition 定义行由业务侧在后台配置(本次未插入定义行、未执行任何数据库写操作)。",
"未修改任何既有接口入参/响应契约:新增类型为注册表扩展,stockFlow 行为不变,report.generate / report.deliveryPlan / report.exportTaskProgress 链路无需改动。",
"README.md / AI_TOOLBOX.md 无需同步:检索确认无注册类型清单描述;AI_METHOD_ROUTING.md 第 6 节为函数清单,本次未新增/删除既有函数名(interceptOrder 为查询器注册 key),如需刷新可另行执行扫描脚本"
]
},
{
"version": "2026.09.10-cross-warehouse-order-express-warehouse-isolation",
"date": "2026-09-10",

View File

@ -1,7 +1,7 @@
{
"module": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.3.104",
"version": "0.3.109",
"updatedAt": "2026-09-10",
"headers": [
{
@ -4850,7 +4850,7 @@
},
{
"method": "order.pendingOrder.batchIntercept",
"description": "批量提交订单拦截请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 intercept_status 更新为 'requested' 并写入操作日志(ORDER_INTERCEPT_REQUEST)。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。",
"description": "批量提交订单拦截请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 intercept_status 更新为 'requested' 并写入操作日志(ORDER_INTERCEPT_REQUEST)。拦截时间 intercept_time 仅在订单首次发起拦截时写入(当时刻),重复发起不覆盖已有值;取消/解除拦截(order.pendingOrder.batchUnintercept)会清空该字段,故其恒为「最近一次发起拦截的通知时刻」,库内确定拦截时刻改用配送表 dispath_time。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -5429,7 +5429,7 @@
},
{
"method": "order.pendingOrder.batchUnintercept",
"description": "批量提交解除拦截请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 intercept_status 更新为 'none' 并写入操作日志(ORDER_INTERCEPT_CANCEL)。不操作库存拦截锁定数量字段。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。",
"description": "批量提交解除拦截请求(异步任务模式)。接收订单ID数组,提交后立即返回 task_id 和受理信息,后端异步将每个订单的 intercept_status 更新为 'none' 并写入操作日志(ORDER_INTERCEPT_CANCEL)。解除拦截同时将拦截时间 intercept_time 清空(置为 null,避免残留旧的发起拦截时刻)。不操作库存拦截锁定数量字段。相同 task_id 幂等提交会返回已存在任务的信息。仓库ID统一使用当前上下文(ctx.user.store_id)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -6299,7 +6299,7 @@
},
{
"method": "order.recheckOrder.confirmIntercept",
"description": "确认拦截:通过订单 ID 列表批量匹配订单,将拦截状态更新为 intercepted_at_warehouse(仓库已拦截,step=4、outbound_status=fin),同步标记运单退回与拦截(is_back='Y', is_intercept='Y'),并释放储位分配(cancelAllocateStorage 拦截模式 interceptMode=true:库存不归还可用,移入拦截锁定字段 intercept_locked_quantity)与订单锁(lock_status=none)。仅拦截当前指定订单,不波及波次内其他订单。前置条件:订单必须处于拦截发起中状态(requested/requesting/intercepting,历史值 intercepted 兼容),未发起拦截(none/空)的订单直接静默跳过不参与处理,已确认拦截(intercepted_at_warehouse)及其它非可确认状态(intercepted_in_transit/returning/returned/delivered_by_mistake/timeout/cancelled/failed/exception)一律跳过并记录失败原因;更新 SQL 的 where 同时限定拦截状态白名单,防止并发修改导致误更新。支持部分失败:未找到的订单与处理失败的订单记录在 failed 列表并返回失败原因,其余订单继续处理。全部订单处理完后按成功订单 ID 汇总批量创建售后工单 + 通知快递群。每个订单操作成功后写入操作日志(ORDER_INTERCEPT_CONFIRM)。运单标记、储位释放、锁释放、工单创建、日志写入失败均不影响主流程。",
"description": "确认拦截:通过订单 ID 列表批量匹配订单,将拦截状态更新为 intercepted_at_warehouse(仓库已拦截,step=4、outbound_status=fin),同步标记运单退回与拦截(is_back='Y', is_intercept='Y'),并释放储位分配(cancelAllocateStorage 拦截模式 interceptMode=true:库存不归还可用,移入拦截锁定字段 intercept_locked_quantity)与订单锁(lock_status=none)。仅拦截当前指定订单,不波及波次内其他订单。前置条件:订单必须处于拦截发起中状态(requested/requesting/intercepting,历史值 intercepted 兼容),未发起拦截(none/空)的订单直接静默跳过不参与处理,已确认拦截(intercepted_at_warehouse)及其它非可确认状态(intercepted_in_transit/returning/returned/delivered_by_mistake/timeout/cancelled/failed/exception)一律跳过并记录失败原因;更新 SQL 的 where 同时限定拦截状态白名单,防止并发修改导致误更新。支持部分失败:未找到的订单与处理失败的订单记录在 failed 列表并返回失败原因,其余订单继续处理。全部订单处理完后按成功订单 ID 汇总批量创建售后工单 + 通知快递群。每个订单操作成功后写入操作日志(ORDER_INTERCEPT_CONFIRM)。运单标记、储位释放、锁释放、工单创建、日志写入失败均不影响主流程。库内拦截确认**不写** intercept_time(该字段恒为「最近一次发起拦截的通知时刻」,确认时不覆盖),库内确定拦截时刻以配送表 dispath_time(订单迁移进配送表的时间)为准。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -6394,7 +6394,7 @@
},
{
"method": "order.recheckOrder.interceptScan",
"description": "拦截扫描:通过运单号查找运单记录。非拦截订单会被拒绝并提示「非拦截订单」:运单记录不存在,或运单 is_intercept≠'Y' 且关联订单 intercept_status 不在 requested/intercepting。校验通过后标记退回与拦截(is_back='Y', is_intercept='Y'),处理关联的未完结售后工单(写入「库内拦截成功」步骤并置为 completed)。若运单关联到订单,则将订单拦截状态更新为 intercepted_at_warehouse(step=4、outbound_status=fin)并释放储位分配(拦截模式:库存不归还可用,移入拦截锁定字段 intercept_locked_quantity)与订单锁(仅订单级状态更新,不标记订单下其他面单)。工单处理失败不阻断主流程。",
"description": "拦截扫描:通过运单号查找运单记录。非拦截订单会被拒绝并提示「非拦截订单」:运单记录不存在,或运单 is_intercept≠'Y' 且关联订单 intercept_status 不在 requested/intercepting。校验通过后标记退回与拦截(is_back='Y', is_intercept='Y'),处理关联的未完结售后工单(写入「库内拦截成功」步骤并置为 completed)。若运单关联到订单,则将订单拦截状态更新为 intercepted_at_warehouse(step=4、outbound_status=fin)并释放储位分配(拦截模式:库存不归还可用,移入拦截锁定字段 intercept_locked_quantity)与订单锁(仅订单级状态更新,不标记订单下其他面单)。该状态更新**不写** intercept_time(该字段恒为「最近一次发起拦截的通知时刻」),库内确定拦截时刻以配送表 dispath_time 为准。工单处理失败不阻断主流程。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -41886,7 +41886,7 @@
"list": [
{
"method": "report.generate",
"description": "提交报表导出异步任务(手动导出):按报表定义ID读取 wms_report_definition(is_enabled=1)配置,经注册类型对应的内置查询器(type=stockFlow 等)取数,并按类型硬编码字段规格(app/lib/report/render.js renderSheetByType)渲染 Excel 上传。上传目录按(报表定义 + 货主/仓库)维度隔离:store_id 有效时为 exports/report/{report_id}/store-{store_id},store_id 缺省且 warehouse_id 有效时为 exports/report/{report_id}/warehouse-{warehouse_id},两者均缺省时按 exports/report/{report_id}/common 兜底(保持手动导出兼容),避免不同货主的报表文件在 COS 上互相覆盖。立即返回任务受理信息(task_id/status=submitted),后台异步执行(执行中的错误体现在任务进度 error 字段),完成后可通过 report.generateTaskProgress 轮询进度并获取下载链接。warehouse_id 由服务端从登录上下文(ctx.user.store_id)自动注入,前端无需传递。仅登录即可调用(免权限:systemInit 声明 generate/generateTaskProgress 免权限;generate 不写审计日志)。",
"description": "提交报表导出异步任务(手动导出):按报表定义ID读取 wms_report_definition(is_enabled=1)配置,经注册类型对应的内置查询器(type=stockFlow / interceptOrder 等)取数,并按类型硬编码字段规格(app/lib/report/render.js renderSheetByType)渲染 Excel 上传。上传目录按(报表定义 + 货主/仓库)维度隔离:store_id 有效时为 exports/report/{report_id}/store-{store_id},store_id 缺省且 warehouse_id 有效时为 exports/report/{report_id}/warehouse-{warehouse_id},两者均缺省时按 exports/report/{report_id}/common 兜底(保持手动导出兼容),避免不同货主的报表文件在 COS 上互相覆盖。立即返回任务受理信息(task_id/status=submitted),后台异步执行(执行中的错误体现在任务进度 error 字段),完成后可通过 report.generateTaskProgress 轮询进度并获取下载链接。warehouse_id 由服务端从登录上下文(ctx.user.store_id)自动注入,前端无需传递。仅登录即可调用(免权限:systemInit 声明 generate/generateTaskProgress 免权限;generate 不写审计日志)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -41938,21 +41938,21 @@
"type": "string",
"required": false,
"source": "body",
"description": "数据日期(YYYY-MM-DD),用于导出文件名 file_name 模板的 {date} 占位;缺省取服务器当天"
"description": "数据日期(YYYY-MM-DD):用于导出文件名 file_name 模板的 {date} 占位(缺省取服务器当天);同时是 interceptOrder 查询器的统计日覆盖(按该日自然日整天统计,缺省为昨日自然日;该类型统计日不得晚于昨天,传今天/未来一律回落昨日,保证当天生成/投递的报表不含当天数据)"
},
{
"name": "params.dayCount",
"type": "number",
"required": false,
"source": "body",
"description": "窗口数量覆盖(stockFlow 查询器经 resolveWindowConfig 解析,缺省 7,<=0 视为 7)"
"description": "窗口数量覆盖(仅 stockFlow 查询器经 resolveWindowConfig 解析,缺省 7,<=0 视为 7;interceptOrder 不使用该参数)"
},
{
"name": "params.cutoverHour",
"type": "number",
"required": false,
"source": "body",
"description": "切点小时覆盖(缺省 7,钳制到 0-23)"
"description": "切点小时覆盖(仅 stockFlow 查询器生效,缺省 7,钳制到 0-23;interceptOrder 不使用该参数,固定按自然日 00:00 切日)"
}
],
"response": [
@ -42770,7 +42770,7 @@
},
{
"method": "report.definition.save",
"description": "新增/更新报表定义(wms_report_definition 管理侧写接口,按 id upsert:未传 id 视为新增,未传字段不覆盖):name 必填 ≤100;type 为注册类型 key(新增必填,必须命中注册表,未知报「未知的报表类型: <type>」);file_name 导出文件名模板支持 {date} 占位(新增必填 ≤200,兼容 fileName 驼峰写法,驼峰优先);fields 为勾选字段 key 数组(新增必填,必须为该类型注册字段子集,含非法 key 报可读错误并列出该类型可用字段);is_enabled 仅 0/1;remark ≤500 超出截断。软删记录命中时自动恢复(paranoid:false 按主键 id 查重)。模型已移除 code/scope 与 output_config/source_config/sheet_config 三段 JSON 配置(极简配置:type + fields)。需授权接口(管理类操作,systemInit 未声明免权限,仅通配符角色或已授权角色可用)。",
"description": "新增/更新报表定义(wms_report_definition 管理侧写接口,按 id upsert:未传 id 视为新增,未传字段不覆盖):name 必填 ≤100;type 为注册类型 key(新增必填,必须命中注册表,未知报「未知的报表类型: <type>」);file_name 导出文件名模板支持 {date}(数据日期)/ {time}(生成时刻 HHmmss)/ {datetime}(数据日期_生成时刻)/ {timestamp}(生成时刻毫秒时间戳)占位(新增必填 ≤200,兼容 fileName 驼峰写法,驼峰优先);fields 为勾选字段 key 数组(新增必填,必须为该类型注册字段子集,含非法 key 报可读错误并列出该类型可用字段);is_enabled 仅 0/1;remark ≤500 超出截断。软删记录命中时自动恢复(paranoid:false 按主键 id 查重)。模型已移除 code/scope 与 output_config/source_config/sheet_config 三段 JSON 配置(极简配置:type + fields)。需授权接口(管理类操作,systemInit 未声明免权限,仅通配符角色或已授权角色可用)。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [
@ -42808,7 +42808,7 @@
"type": "string",
"required": false,
"source": "body",
"description": "导出文件名模板(支持 {date} 占位;新增必填,≤200 字符;更新时未传不覆盖既有值)"
"description": "导出文件名模板(支持 {date} 数据日期 / {time} 生成时刻 HHmmss / {datetime} 数据日期_生成时刻 / {timestamp} 毫秒时间戳;新增必填,≤200 字符;更新时未传不覆盖既有值)"
},
{
"name": "fileName",
@ -42862,7 +42862,7 @@
"name": "file_name",
"type": "string",
"required": true,
"description": "导出文件名模板(支持 {date} 占位)"
"description": "导出文件名模板(支持 {date} 数据日期 / {time} 生成时刻 HHmmss / {datetime} 数据日期_生成时刻 / {timestamp} 毫秒时间戳)"
},
{
"name": "fields",
@ -43036,7 +43036,7 @@
"name": "file_name",
"type": "string",
"required": true,
"description": "导出文件名模板(支持 {date} 占位)"
"description": "导出文件名模板(支持 {date} 数据日期 / {time} 生成时刻 HHmmss / {datetime} 数据日期_生成时刻 / {timestamp} 毫秒时间戳;缺省模板为 <name>_<date>.xlsx)"
},
{
"name": "fields",
@ -43161,7 +43161,7 @@
},
{
"method": "report.definition.typeList",
"description": "查询报表类型注册清单(只读公共元数据):返回内置查询器注册表全量描述,每项含 key(类型 key,如 stockFlow)、title(标题,如「库存变化以及补货报表」)、description(口径描述)、window{dayCount,cutoverHour} 与全量字段清单 fields(含 computed 预计算标记与 asText 文本单元格标记)。当前仅注册 stockFlow 一种类型。免权限/免鉴权/免审计日志(definition.js systemInit 声明 _noNeedRight/_noNeedAuth/_noNeedLog='typeList',仅要求登录);同模块内 save/list/delete 为定义管理类操作,未声明免权限,仍需授权(isNeedAuth=true),权限口径存在差异。",
"description": "查询报表类型注册清单(只读公共元数据):返回内置查询器注册表全量描述,每项含 key(类型 key,如 stockFlow)、title(标题,如「库存变化以及补货报表」)、description(口径描述)、window{dayCount,cutoverHour} 与全量字段清单 fields(含 computed 预计算标记与 asText 文本单元格标记)。当前注册 stockFlow(7 日库存变化以及补货报表)与 interceptOrder(库内确定拦截订单明细,以配送表 dispath_time 迁移进配送表的时间为基准统计昨日 intercept_status=intercepted_at_warehouse 的订单,按商品明细展开,列与 order.export export_mode=item 一致但不含商品图片列,并附 3 列:平台交易单号、通知拦截时间、库内确定拦截时间)两种类型。免权限/免鉴权/免审计日志(definition.js systemInit 声明 _noNeedRight/_noNeedAuth/_noNeedLog='typeList',仅要求登录);同模块内 save/list/delete 为定义管理类操作,未声明免权限,仍需授权(isNeedAuth=true),权限口径存在差异。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
@ -43178,7 +43178,7 @@
"name": "list",
"type": "array",
"required": true,
"description": "注册类型清单(当前仅 stockFlow)",
"description": "注册类型清单(当前 stockFlow、interceptOrder 两种,按注册顺序:stockFlow 在前)",
"children": [
{
"name": "key",
@ -43208,19 +43208,19 @@
"name": "window.dayCount",
"type": "number",
"required": true,
"description": "窗口数量(stockFlow 默认 7)"
"description": "窗口数量(stockFlow 默认 7;interceptOrder 默认 1,即单个自然日)"
},
{
"name": "window.cutoverHour",
"type": "number",
"required": true,
"description": "切点小时 0-23(stockFlow 默认 7,窗口为 [D 07:00, D+1 07:00) 本地时区半开区间)"
"description": "切点小时 0-23(stockFlow 默认 7,窗口为 [D 07:00, D+1 07:00) 本地时区半开区间;interceptOrder 默认 0,按自然日 00:00 切日)"
},
{
"name": "fields",
"type": "array",
"required": true,
"description": "全量注册字段清单(该类型可用列元数据,当前 stockFlow 共 9 组列,顺序固定;daily 为数组类型列,含 children 子字段)"
"description": "全量注册字段清单(该类型可用列元数据,顺序固定:stockFlow 共 9 组列;interceptOrder 共 49 列:与订单导出含明细模式对齐去掉商品图片列(46 列)+ 附加 3 列(平台交易单号 source_order_codes 紧跟外部单号、通知拦截时间 intercept_notice_time、库内确定拦截时间 intercept_confirm_time))。stockFlow 的 daily 为数组类型列,含 children 子字段;interceptOrder 无展开列,均为 string 静态列"
},
{
"name": "fields[].key",