From a4cadeb83b84b65b50885cdd5147c3011deb190e Mon Sep 17 00:00:00 2001 From: liufumingren Date: Thu, 10 Sep 2026 20:59:39 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=BA=93=E5=86=85=E7=A1=AE=E5=AE=9A?= =?UTF-8?q?=E6=8B=A6=E6=88=AA=E8=AE=A2=E5=8D=95=E6=98=8E=E7=BB=86=E6=8A=A5?= =?UTF-8?q?=E8=A1=A8=E4=B8=8E=E6=8B=A6=E6=88=AA=E6=97=B6=E9=97=B4=E5=8F=A3?= =?UTF-8?q?=E5=BE=84=E8=B0=83=E6=95=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增通用报表注册类型 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 两条计划投递成功或仅文本通知环境依赖失败,文件名均带时分秒、导出列与定义勾选一致) --- app/lib/intercept_time.js | 82 +++ app/model/report_definition.js | 2 +- app/service/inbox/functions.js | 33 +- app/service/openapiMethods/order.js | 7 +- app/service/qimenMethods/order.js | 13 +- .../systemMethods/order/pendingOrder.js | 49 +- .../systemMethods/order/recheckOrder.js | 6 +- .../systemMethods/report/definition.js | 2 +- app/service/systems/intercept_auto_confirm.js | 8 +- app/service/systems/report.js | 29 +- app/service/systems/report/queries/index.js | 13 + .../systems/report/queries/interceptOrder.js | 477 ++++++++++++++++++ app/service/systems/return_received.js | 4 +- docs/report-config-guide.md | 135 ++++- methods/changes/system.json | 123 +++++ methods/system.json | 36 +- 16 files changed, 958 insertions(+), 61 deletions(-) create mode 100644 app/lib/intercept_time.js create mode 100644 app/service/systems/report/queries/interceptOrder.js diff --git a/app/lib/intercept_time.js b/app/lib/intercept_time.js new file mode 100644 index 0000000..12d584d --- /dev/null +++ b/app/lib/intercept_time.js @@ -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} rows 订单行(需含 id 与 intercept_time) + * @return {Array} 需要写入通知拦截时间的订单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, +}; diff --git a/app/model/report_definition.js b/app/model/report_definition.js index 32a9693..823924c 100644 --- a/app/model/report_definition.js +++ b/app/model/report_definition.js @@ -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, diff --git a/app/service/inbox/functions.js b/app/service/inbox/functions.js index c235e5b..80734d4 100644 --- a/app/service/inbox/functions.js +++ b/app/service/inbox/functions.js @@ -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 } } diff --git a/app/service/openapiMethods/order.js b/app/service/openapiMethods/order.js index 18a7280..6c28056 100644 --- a/app/service/openapiMethods/order.js +++ b/app/service/openapiMethods/order.js @@ -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, }); diff --git a/app/service/qimenMethods/order.js b/app/service/qimenMethods/order.js index 33cc6ee..cb03402 100644 --- a/app/service/qimenMethods/order.js +++ b/app/service/qimenMethods/order.js @@ -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, }); diff --git a/app/service/systemMethods/order/pendingOrder.js b/app/service/systemMethods/order/pendingOrder.js index 19ae0c8..5a79006 100644 --- a/app/service/systemMethods/order/pendingOrder.js +++ b/app/service/systemMethods/order/pendingOrder.js @@ -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 { diff --git a/app/service/systemMethods/order/recheckOrder.js b/app/service/systemMethods/order/recheckOrder.js index 06870c4..001875b 100644 --- a/app/service/systemMethods/order/recheckOrder.js +++ b/app/service/systemMethods/order/recheckOrder.js @@ -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, diff --git a/app/service/systemMethods/report/definition.js b/app/service/systemMethods/report/definition.js index e301408..e4c71ba 100644 --- a/app/service/systemMethods/report/definition.js +++ b/app/service/systemMethods/report/definition.js @@ -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} data.fields 勾选字段 key 数组(新增必填,须为该类型注册字段子集) * @param {number} [data.is_enabled] 是否启用(0/1) * @param {string} [data.remark] 备注(≤500) diff --git a/app/service/systems/intercept_auto_confirm.js b/app/service/systems/intercept_auto_confirm.js index 53f973c..9979374 100644 --- a/app/service/systems/intercept_auto_confirm.js +++ b/app/service/systems/intercept_auto_confirm.js @@ -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, diff --git a/app/service/systems/report.js b/app/service/systems/report.js index 55336b8..12f457d 100644 --- a/app/service/systems/report.js +++ b/app/service/systems/report.js @@ -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`; } diff --git a/app/service/systems/report/queries/index.js b/app/service/systems/report/queries/index.js index 03c2bc2..dd3b914 100644 --- a/app/service/systems/report/queries/index.js +++ b/app/service/systems/report/queries/index.js @@ -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 })), + }, ]; /** diff --git a/app/service/systems/report/queries/interceptOrder.js b/app/service/systems/report/queries/interceptOrder.js new file mode 100644 index 0000000..ff162ae --- /dev/null +++ b/app/service/systems/report/queries/interceptOrder.js @@ -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} + */ +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} args.rows 报表行(原地写入附加列,行内需含订单ID `id`) + * @return {Promise>} 富化后的行数组(同一引用) + */ +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, rows: Array, 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; diff --git a/app/service/systems/return_received.js b/app/service/systems/return_received.js index e8b2953..eba5d84 100644 --- a/app/service/systems/return_received.js +++ b/app/service/systems/return_received.js @@ -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(), }; diff --git a/docs/report-config-guide.md b/docs/report-config-guide.md index 593c134..bb986f8 100644 --- a/docs/report-config-guide.md +++ b/docs/report-config-guide.md @@ -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 可能仍回源旧内容)。 - 缺省模板:`_.xlsx`;不以 `.xlsx`/`.xls` 结尾时自动补 `.xlsx`。 - 上传目录(COS 文件 key)按「报表定义 + 货主/仓库」维度隔离(2026-08-31 修复「货主限制不符」缺陷: 修复前统一为 `exports/report//`,不同货主的报表文件会互相覆盖): @@ -245,7 +370,7 @@ report.generate(method 层,异步任务,入参 report_id) } ``` -- `type` 必须命中注册表(当前仅 `stockFlow`,未知报「未知的报表类型: 」); +- `type` 必须命中注册表(当前 `stockFlow`、`interceptOrder`,未知报「未知的报表类型: 」); `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`; diff --git a/methods/changes/system.json b/methods/changes/system.json index 7542e6f..92050a3 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -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 || 服务器当天)与既有行为完全一致;缺省模板仍为 _.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", diff --git a/methods/system.json b/methods/system.json index f47b430..8627270 100644 --- a/methods/system.json +++ b/methods/system.json @@ -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(新增必填,必须命中注册表,未知报「未知的报表类型: 」);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(新增必填,必须命中注册表,未知报「未知的报表类型: 」);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} 毫秒时间戳;缺省模板为 _.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",