diff --git a/WMS-OMS-取号对接.md b/WMS-OMS-取号对接.md index 665a388..df78585 100644 --- a/WMS-OMS-取号对接.md +++ b/WMS-OMS-取号对接.md @@ -1255,3 +1255,40 @@ WMS 侧待发布(打印层兼容 + 菜鸟 printinfo 回拼 + 本次 key 兜底 取号 → 查 `wms_order_express.printinfo/encryptprintinfo` 长度(约 3.4–3.8KB / 172)→ 打印验证。 wms/ + +--- + +## OMS 侧:发货确认回传序列号(SN)留存与反查(2026-11-13) + +WMS 回传 `deliveryorder.confirm` 时,明细行可能带上序列号列表: + +```json +{ + "request": { + "deliveryOrder": { "deliveryOrderCode": "FH_123", "status": "DELIVERED" }, + "packages": { "package": [ { "expressCode": "YT123", "packageCode": "PK-1", "items": [ { "itemCode": "SKU-A", "snList": [ "SN3" ] } ] } ] }, + "orderLines": [ { "orderLineNo": "1", "itemCode": "SKU-A", "snList": [ "SN1", "SN2" ] } ] + } +} +``` + +OMS 侧处理: + +| 项 | 说明 | +|---|---| +| 落库表 | `order_sn_codes`(一行一个 SN;`order_id` = `order_index.id`,订单在状态表间流转时 ID 不变,故转表不搬 SN) | +| 解析字段 | 行级 `orderLines[].snList` / `snCodes` / `snCode`(兼容逗号分隔、`[{ snCode }]` 对象数组),包裹级 `packages.package[].items[].snList` | +| 附加字段 | 行号 / 商品编码 / 商品ID / 商品名称 / 包裹号 / 运单号 / 仓库ID(来自 app_key) | +| 幂等 | 同一订单重复回传同一 SN 不新增(先按订单查已存在 SN,唯一键 `uk_osc_order_sn` 兜底) | +| 实现 | `backend/app/lib/orderSnCodes.js`(`extractSnEntries` / `saveOrderSnCodes`),由 `orderCallback.confirmDelivery` 调用;老表发货单(`order_deliveries`)不回写 | + +订单查询按 SN 反查(支持多个,逗号 / 换行分隔,最多 200 个,精确匹配): + +``` +GET /api/order-status/list?status=delivery&sn_codes=SN1,SN2 +``` + +- 后端先按 `(principal_id, sn_code)` 从 `order_sn_codes` 取命中的订单ID,再回状态表过滤; +- 订单导出的筛选条件同样支持「序列号」(`sn_codes`); +- 订单详情(`GET /api/order-status/:id`)返回 `order.sn_codes`,页面详情抽屉展示序列号明细。 + diff --git a/backend/app/contract/index.js b/backend/app/contract/index.js index b823c0c..b1dcb68 100644 --- a/backend/app/contract/index.js +++ b/backend/app/contract/index.js @@ -2504,6 +2504,21 @@ module.exports = { updated_at: { type: 'string', description: '更新时间' }, archived_at: { type: 'string', description: '归档时间(仅历史表)' }, transferred_at: { type: 'string', description: '转入历史时间(仅历史表)' }, + sn_codes: { type: 'array', itemType: 'orderStatusSnCode', description: '序列号(SN)列表(仅详情返回;WMS 发货确认回传的 snList)' }, + }, + /** 订单序列号(SN)行(order_sn_codes) */ + orderStatusSnCode: { + id: { type: 'integer', description: '主键' }, + order_id: { type: 'integer', description: '订单ID(= order_index.id)' }, + order_line_no: { type: 'string', description: '回传明细行号(orderLineNo)' }, + item_id: { type: 'integer', description: '商品ID(itemId)' }, + item_code: { type: 'string', description: '商品编码(itemCode)' }, + item_name: { type: 'string', description: '商品名称(itemName)' }, + package_code: { type: 'string', description: '包裹号(packageCode)' }, + express_code: { type: 'string', description: '运单号(expressCode)' }, + sn_code: { type: 'string', description: '序列号(SN)' }, + source: { type: 'string', description: '来源:wms=仓库回传' }, + created_at: { type: 'string', description: '回传留存时间' }, }, orderStatusPage: { ...buildPage('orderStatusItem', '订单列表'), diff --git a/backend/app/controller/orderStatus.js b/backend/app/controller/orderStatus.js index 54d6602..68bcc34 100644 --- a/backend/app/controller/orderStatus.js +++ b/backend/app/controller/orderStatus.js @@ -51,7 +51,8 @@ class OrderStatusController extends Controller { * @summary 订单列表 * @description 按 status 定位状态表分页查询(pending 待审核 / queued 待推送 / exception 异常 / * outsourcing 委外中 / delivery 配送 / void 已作废 / canceled 已取消 / history 历史)。 - * 支持订单号、来源订单号、店铺、收货人、收货地址、备注(异常原因)、关键词与创建时间区间过滤; + * 支持订单号、来源订单号、店铺、收货人、收货地址、备注(异常原因)、关键词、平台单号、 + * 序列号(SN)与创建时间区间过滤; * 历史视图另支持归档时间区间。返回行附状态中文、店铺名称与商品明细摘要。 * @router get /api/order-status/list * @apikey @@ -63,6 +64,7 @@ class OrderStatusController extends Controller { * @request query integer shop_id 店铺ID * @request query string platform_codes 电商平台编码,多选用逗号分隔(PDD / DYXD / SPH…,见系统预设平台编码) * @request query string platform_order_nos 平台单号,多个精确匹配用逗号分隔(最多 200 个) + * @request query string sn_codes 序列号(SN),多个精确匹配用逗号分隔(最多 200 个;WMS 发货确认回传的 snList) * @request query string receiver 收货人,模糊匹配 * @request query string address 收货地址,模糊匹配 * @request query string remark 备注 / 异常原因,模糊匹配 diff --git a/backend/app/lib/orderCallback.js b/backend/app/lib/orderCallback.js index a70ee5d..9cfb706 100644 --- a/backend/app/lib/orderCallback.js +++ b/backend/app/lib/orderCallback.js @@ -4,6 +4,7 @@ const completeInbound = require('../utils/completeInbound'); const { applyStockChange } = require('../utils/stockRecord'); const { deductDeliveryStock } = require('../utils/deliveryStock'); const { ORDER_STATUS, orderModelName, orderStatusLabel } = require('./orderStatus'); +const { saveOrderSnCodes } = require('./orderSnCodes'); /** * 外部回调(对外通用回调接口 /openapi)驱动 OMS 单据的共用处理逻辑。 @@ -827,6 +828,7 @@ function buildExpressOverride(order, express) { * 处理内容:① 回写运单号 express_code 与物流公司(缺失或变化时)② 状态「已推送(3)」→「已完成(4)」 * ③ 若审核时已锁定库存(order_deliveries.stock_locked=1)则扣减库存(总数量与锁定同减) * 并写 order_deduct 流水;历史单据(stock_locked=0)不扣减,避免凭空减少总数量 + * ④ 明细行 / 包裹商品的 `snList` 落到 order_sn_codes(订单查询可按 SN 反查,见 lib/orderSnCodes.js) * 幂等:已完成(4) 的单据再次收到(可能多次)相同报文时只做缺失字段补写并直接回成功 * (不重复改状态、不重复扣减库存、不重复写推送结果);状态非 3/4 时返回失败,交由调用方告警/重试。 * @param {Object} ctx egg context @@ -864,6 +866,21 @@ async function confirmDelivery(ctx, { principalId, warehouseId, data }) { { express: expressResult.first } ); + // 明细行 snList → order_sn_codes(订单查询可按 SN 反查);老表发货单没有索引表 ID,不做关联 + // 仅对「委外中 / 已配送」的订单留存(其余状态本次确认会被拒绝,避免留下不该有的 SN) + const recordSn = resolved.isNewModel + && [ ORDER_STATUS.OUTSOURCING, ORDER_STATUS.DELIVERY ].includes(resolved.index.current_status); + const snResult = recordSn + ? await saveOrderSnCodes(ctx, { + principalId, + orderId: Number(resolved.index.id), + orderNo: resolved.index.order_no, + warehouseId, + lines, + packages, + }) + : { inserted: 0, total: 0 }; + // 新表(order_index + 状态表):委外中 → 配送(扣减锁定库存),已配送幂等回执 if (resolved.isNewModel) { const result = await confirmOrderStatusDelivery(ctx, { resolved, payload, packages, lines, pkgInfo }); @@ -872,6 +889,7 @@ async function confirmDelivery(ctx, { principalId, warehouseId, data }) { orderNo: resolved.order.parent_order_no || resolved.index.order_no, }); } + if (result.data) result.data.sn_codes_added = snResult.inserted; return result; } diff --git a/backend/app/lib/orderSnCodes.js b/backend/app/lib/orderSnCodes.js new file mode 100644 index 0000000..db82e2f --- /dev/null +++ b/backend/app/lib/orderSnCodes.js @@ -0,0 +1,265 @@ +'use strict'; + +/** + * 订单序列号(SN)关联表的解析与写入 + * + * 背景:WMS 回传发货确认(deliveryorder.confirm)时,明细行可能带 `snList`: + * { request: { orderLines: [ { orderLineNo: '1', itemCode: 'SKU-A', snList: [ 'SN1', 'SN2' ] } ], + * packages: { package: [ { expressCode, packageCode, items: [ { itemCode, snList } ] } ] } } } + * 这些 SN 原先只留在 `wms_push_result.confirm` 的 JSON 摘要里,无法反查订单; + * 现在统一落 `order_sn_codes`(一行一个 SN,`order_id` = order_index.id), + * 订单列表即可按「主体 + SN(支持多个)」反查出订单。 + * + * 幂等:同一订单重复回传同一报文时不新增行(先查已存在的 SN,再由唯一键 `uk_osc_order_sn` 兜底)。 + */ + +/** SN 列宽(order_sn_codes.sn_code),超长截断避免异常报文撑爆索引 */ +const SN_MAX_LEN = 255; +/** 单次回传最多留存的 SN 条数,防止异常报文写入过多数据 */ +const SN_MAX_COUNT = 2000; + +/** + * 字段取值并截断(去空白;空值返回 '') + * @param {Object} obj 源对象 + * @param {Array} keys 候选字段名 + * @param {Number} max 最大长度 + * @return {String} 值 + */ +function pickText(obj, keys, max) { + if (!obj || typeof obj !== 'object') return ''; + for (const key of keys) { + const value = obj[key]; + if (value === undefined || value === null) continue; + if (typeof value === 'object') continue; + const text = String(value).trim(); + if (text) return text.slice(0, max); + } + return ''; +} + +/** + * 数字ID归一化(非正整数返回 null) + * @param {*} value 原值 + * @return {Number|null} 数值 + */ +function toId(value) { + const num = Number(value); + return Number.isInteger(num) && num > 0 ? num : null; +} + +/** + * 从明细行的 SN 字段取 SN 列表(兼容数组 / 逗号分隔字符串 / 对象数组) + * 支持字段:snList / sn_list / snCodes / sn_codes / snCode / sn_code / sn + * @param {Object} obj 明细行或包裹内商品 + * @return {Array} SN 列表(原值去空白,未去重) + */ +function extractSnValues(obj) { + if (!obj || typeof obj !== 'object') return []; + const values = []; + const push = raw => { + if (raw === undefined || raw === null) return; + if (Array.isArray(raw)) { + raw.forEach(push); + return; + } + if (typeof raw === 'object') { + // 兼容 [{ snCode: 'xxx' }, { sn: 'xxx' }, { code: 'xxx' }] + push(raw.snCode ?? raw.sn_code ?? raw.sn ?? raw.code ?? raw.value); + return; + } + const text = String(raw).trim(); + if (!text) return; + // 一个字段里塞了多个 SN("SN1,SN2" / 换行分隔)时拆开 + if (/[,,;;\r\n]/.test(text)) { + text.split(/[,,;;\r\n]+/).forEach(item => push(item)); + return; + } + values.push(text.slice(0, SN_MAX_LEN)); + }; + for (const key of [ 'snList', 'sn_list', 'snCodes', 'sn_codes', 'snCode', 'sn_code', 'sn' ]) { + if (obj[key] !== undefined && obj[key] !== null) push(obj[key]); + } + return values; +} + +/** + * 包裹内商品数组归一化(兼容 items 数组 / items.item 数组) + * @param {Object} pkg 包裹 + * @return {Array} 商品数组 + */ +function packageItems(pkg) { + const raw = pkg && pkg.items; + if (Array.isArray(raw)) return raw.filter(item => item && typeof item === 'object'); + if (raw && Array.isArray(raw.item)) return raw.item.filter(item => item && typeof item === 'object'); + return []; +} + +/** + * 从发货确认报文的明细行 / 包裹中解析 SN 条目 + * + * 行级 SN 与包裹内商品 SN 都收:行级带 orderLineNo/itemCode,包裹级额外带 packageCode/expressCode; + * 同一 SN 只保留首次出现的条目(MySQL 比较不区分大小写,这里也按小写去重)。 + * @param {Object} p 参数 + * @param {Array} [p.lines] 明细行数组(request.orderLines) + * @param {Array} [p.packages] 包裹数组(request.packages.package) + * @return {Array} SN 条目:{ sn_code, order_line_no, item_id, item_code, item_name, package_code, express_code } + */ +function extractSnEntries({ lines = [], packages = [] } = {}) { + const entries = []; + const seen = new Set(); + + const add = (sn, meta) => { + const text = String(sn == null ? '' : sn).trim().slice(0, SN_MAX_LEN); + if (!text) return false; + const key = text.toLowerCase(); + if (seen.has(key)) return false; + seen.add(key); + entries.push({ + sn_code: text, + order_line_no: meta.order_line_no || null, + item_id: meta.item_id || null, + item_code: meta.item_code || null, + item_name: meta.item_name || null, + package_code: meta.package_code || null, + express_code: meta.express_code || null, + }); + return entries.length >= SN_MAX_COUNT; + }; + + for (const line of Array.isArray(lines) ? lines : []) { + if (!line || typeof line !== 'object') continue; + const meta = { + order_line_no: pickText(line, [ 'orderLineNo', 'order_line_no' ], 20), + item_id: toId(line.itemId ?? line.item_id), + item_code: pickText(line, [ 'itemCode', 'item_code' ], 100), + item_name: pickText(line, [ 'itemName', 'item_name' ], 255), + }; + for (const sn of extractSnValues(line)) { + if (add(sn, meta)) return entries; + } + } + + for (const pkg of Array.isArray(packages) ? packages : []) { + if (!pkg || typeof pkg !== 'object') continue; + const packageCode = pickText(pkg, [ 'packageCode', 'package_code' ], 50); + const expressCode = pickText(pkg, [ 'expressCode', 'express_code' ], 50); + for (const item of packageItems(pkg)) { + const meta = { + order_line_no: pickText(item, [ 'orderLineNo', 'order_line_no' ], 20), + item_id: toId(item.itemId ?? item.item_id), + item_code: pickText(item, [ 'itemCode', 'item_code' ], 100), + item_name: pickText(item, [ 'itemName', 'item_name' ], 255), + package_code: packageCode, + express_code: expressCode, + }; + for (const sn of extractSnValues(item)) { + if (add(sn, meta)) return entries; + } + } + } + + return entries; +} + +/** + * 把回传报文里的 SN 落到 order_sn_codes(幂等:已存在的 SN 跳过) + * @param {Object} ctx egg context + * @param {Object} p 参数 + * @param {Number} p.principalId 主体ID + * @param {Number} p.orderId 订单ID(order_index.id) + * @param {String} [p.orderNo] 订单号(冗余留痕) + * @param {Number} [p.warehouseId] 仓库ID(app_key 定位到的仓库) + * @param {Array} [p.lines] 明细行数组 + * @param {Array} [p.packages] 包裹数组 + * @param {Object} [p.transaction] 事务(传入时随调用方事务写入) + * @return {Promise<{inserted: Number, total: Number}>} inserted 新增条数 / total 报文里的 SN 条数 + */ +async function saveOrderSnCodes(ctx, { principalId, orderId, orderNo, warehouseId, lines, packages, transaction } = {}) { + const entries = extractSnEntries({ lines, packages }); + if (!entries.length) return { inserted: 0, total: 0 }; + + const Op = ctx.app.Sequelize.Op; + const existing = await ctx.model.OrderSnCode.findAll({ + where: { + principal_id: principalId, + order_id: orderId, + sn_code: { [Op.in]: entries.map(entry => entry.sn_code) }, + }, + attributes: [ 'sn_code' ], + raw: true, + transaction, + }); + const stored = new Set(existing.map(row => String(row.sn_code || '').trim().toLowerCase())); + const rows = entries + .filter(entry => !stored.has(entry.sn_code.toLowerCase())) + .map(entry => ({ + principal_id: principalId, + order_id: orderId, + order_no: orderNo || null, + warehouse_id: warehouseId || null, + order_line_no: entry.order_line_no, + item_id: entry.item_id, + item_code: entry.item_code, + item_name: entry.item_name, + package_code: entry.package_code, + express_code: entry.express_code, + sn_code: entry.sn_code, + source: 'wms', + })); + + if (rows.length) { + // ignoreDuplicates:并发/重推时由唯一键 uk_osc_order_sn 兜底,不报错 + await ctx.model.OrderSnCode.bulkCreate(rows, { ignoreDuplicates: true, transaction }); + ctx.logger.info( + `[order-sn] 订单 ${orderNo || orderId} 留存序列号 ${rows.length} 个(报文共 ${entries.length} 个)` + ); + } + return { inserted: rows.length, total: entries.length }; +} + +/** + * 订单的 SN 列表(详情展示用,按行号 / 自增ID排序) + * @param {Object} ctx egg context + * @param {Object} p 参数 + * @param {Number} p.principalId 主体ID + * @param {Number} p.orderId 订单ID(order_index.id) + * @return {Promise>} SN 行 + */ +async function listOrderSnCodes(ctx, { principalId, orderId } = {}) { + if (!orderId) return []; + const rows = await ctx.model.OrderSnCode.findAll({ + where: { principal_id: principalId, order_id: orderId }, + order: [[ 'order_line_no', 'ASC' ], [ 'id', 'ASC' ]], + raw: true, + }); + return rows; +} + +/** + * 按 SN 反查订单ID(订单列表筛选用) + * @param {Object} ctx egg context + * @param {Object} p 参数 + * @param {Number} p.principalId 主体ID + * @param {Array} p.snCodes SN 列表(精确匹配,最多 200 个由调用方限制) + * @return {Promise>} 命中的订单ID(去重) + */ +async function findOrderIdsBySnCodes(ctx, { principalId, snCodes } = {}) { + const list = Array.isArray(snCodes) ? snCodes : []; + if (!list.length) return []; + const Op = ctx.app.Sequelize.Op; + const rows = await ctx.model.OrderSnCode.findAll({ + where: { principal_id: principalId, sn_code: { [Op.in]: list } }, + attributes: [ 'order_id' ], + raw: true, + }); + return [ ...new Set(rows.map(row => Number(row.order_id)).filter(id => Number.isInteger(id) && id > 0)) ]; +} + +module.exports = { + SN_MAX_LEN, + SN_MAX_COUNT, + extractSnEntries, + saveOrderSnCodes, + listOrderSnCodes, + findOrderIdsBySnCodes, +}; diff --git a/backend/app/lib/orderStatus.js b/backend/app/lib/orderStatus.js index 48f3bfb..ac1d752 100644 --- a/backend/app/lib/orderStatus.js +++ b/backend/app/lib/orderStatus.js @@ -78,6 +78,9 @@ const ORDER_INDEX_TABLE = 'order_index'; /** 订单明细表表名(各状态表共用) */ const ORDER_ITEM_TABLE = 'order_status_items'; +/** 订单序列号(SN)关联表表名:WMS 回传的 snList 落这里,订单查询按 SN 反查 */ +const ORDER_SN_TABLE = 'order_sn_codes'; + /** 订单明细表模型名 */ const ORDER_ITEM_MODEL = 'OrderStatusItem'; @@ -176,6 +179,7 @@ module.exports = { ORDER_INDEX_TABLE, ORDER_ITEM_TABLE, ORDER_ITEM_MODEL, + ORDER_SN_TABLE, ORDER_TABLE_BY_STATUS, ORDER_MODEL_BY_STATUS, ORDER_STATUS_LIST, diff --git a/backend/app/model/orderSnCode.js b/backend/app/model/orderSnCode.js new file mode 100644 index 0000000..4efb405 --- /dev/null +++ b/backend/app/model/orderSnCode.js @@ -0,0 +1,45 @@ +'use strict'; + +const { ORDER_SN_TABLE } = require('../lib/orderStatus'); + +/** + * 订单序列号(SN)关联表模型(order_sn_codes) + * + * WMS 回传发货确认(deliveryorder.confirm)时明细行可能带 `snList`,由 + * app/lib/orderSnCodes.js 解析后落到本表:一行一个 SN,`order_id` 指向 order_index.id + * (订单在状态表之间流转时 ID 不变,故转表无需搬 SN)。订单查询按 SN 反查订单时 + * 走 `idx_osc_principal_sn`(principal_id + sn_code)。 + * @param {Egg.Application} app egg application + * @return {object} orderSnCode model + */ +module.exports = app => { + const { BIGINT, STRING, DATE } = app.Sequelize; + + const OrderSnCode = app.model.define('order_sn_code', { + id: { type: BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true, comment: '主键' }, + principal_id: { type: BIGINT.UNSIGNED, allowNull: false, comment: '所属主体ID(主体隔离)' }, + order_id: { type: BIGINT.UNSIGNED, allowNull: false, comment: '订单ID(order_index.id,全局唯一)' }, + order_no: { type: STRING(50), comment: '订单号(冗余,便于排查 / 导出)' }, + order_line_no: { type: STRING(20), comment: '回传明细行号(orderLineNo)' }, + item_id: { type: BIGINT.UNSIGNED, comment: '商品ID(itemId)' }, + item_code: { type: STRING(100), comment: '商品编码(itemCode)' }, + item_name: { type: STRING(255), comment: '商品名称(itemName)' }, + package_code: { type: STRING(50), comment: '包裹号(packageCode)' }, + express_code: { type: STRING(50), comment: '运单号(expressCode)' }, + warehouse_id: { type: BIGINT.UNSIGNED, comment: '仓库ID(app_key 定位到的仓库)' }, + sn_code: { type: STRING(255), allowNull: false, comment: '序列号(SN 原值,去空白;反查订单用)' }, + source: { type: STRING(20), allowNull: false, defaultValue: 'wms', comment: '来源:wms=仓库回传(预留手工补录)' }, + created_at: { type: DATE, comment: '创建时间' }, + updated_at: { type: DATE, comment: '更新时间' }, + }, { + tableName: ORDER_SN_TABLE, + comment: '订单序列号(SN)关联表(WMS 发货确认回传的 snList)', + }); + + OrderSnCode.associate = () => { + app.model.OrderSnCode.belongsTo(app.model.OrderIndex, { foreignKey: 'order_id', as: 'order' }); + app.model.OrderSnCode.belongsTo(app.model.Principal, { foreignKey: 'principal_id', as: 'principal' }); + }; + + return OrderSnCode; +}; diff --git a/backend/app/service/orderStatus.js b/backend/app/service/orderStatus.js index b3d3040..b83d3aa 100644 --- a/backend/app/service/orderStatus.js +++ b/backend/app/service/orderStatus.js @@ -20,6 +20,7 @@ const { resolveAccountName } = require('../lib/accountProfile'); const { PLATFORM_PRESETS, platformNameOf, resolvePlatform } = require('../lib/platformCode'); const { validateReceiver } = require('../lib/orderReceiver'); const { validateItems } = require('../lib/orderDeliveryItems'); +const { findOrderIdsBySnCodes, listOrderSnCodes } = require('../lib/orderSnCodes'); /** 外部发货同步状态文案(与 service/externalSendSync.js 的 SEND_STATUS 对齐) */ const EXTERNAL_SEND_STATUS_LABELS = { @@ -402,6 +403,14 @@ class OrderStatusService extends Service { const platformOrderNos = parseFilterValues(p.platform_order_nos, 200).map(no => no.slice(0, 50)); if (platformOrderNos.length) where.oaid_order_source_code = { [Op.in]: platformOrderNos }; + // 序列号(SN)反查:WMS 回传时落到 order_sn_codes,多个精确匹配(逗号 / 换行分隔); + // 先取命中的订单ID再回到状态表过滤,避免拼接超长 IN 子句,也便于走 idx_osc_principal_sn + const snCodes = parseFilterValues(p.sn_codes, 200).map(code => code.slice(0, 255)); + if (snCodes.length) { + const snOrderIds = await findOrderIdsBySnCodes(ctx, { principalId, snCodes }); + where.id = { [Op.in]: snOrderIds.length ? snOrderIds : [ -1 ] }; + } + // 所在公司权限:仅列出自己所属公司(货主)的订单 const access = await this._scopeAccess(principalId); if (!access.isGroup) { @@ -1549,7 +1558,8 @@ class OrderStatusService extends Service { } } const items = await this.listItems({ order_id: row.id }); - return { order: plain, items: items.list }; + const snCodes = await listOrderSnCodes(ctx, { principalId, orderId: Number(row.id) }); + return { order: { ...plain, sn_codes: snCodes }, items: items.list }; } /** diff --git a/backend/app/utils/exportDefs.js b/backend/app/utils/exportDefs.js index 2ed5b4c..1593e36 100644 --- a/backend/app/utils/exportDefs.js +++ b/backend/app/utils/exportDefs.js @@ -758,6 +758,7 @@ const EXPORT_TYPES = { { key: 'parent_order_no', label: '来源订单号', type: 'text', placeholder: '支持模糊匹配' }, { key: 'platform_codes', label: '电商平台', type: 'select', options: PLATFORM_TYPE_OPTIONS, multiple: true }, { key: 'platform_order_nos', label: '平台单号', type: 'text', placeholder: '多个用英文逗号分隔(精确匹配)' }, + { key: 'sn_codes', label: '序列号', type: 'text', placeholder: '多个用英文逗号分隔(精确匹配,反查订单)' }, { key: 'receiver', label: '收货人', type: 'text' }, { key: 'address', label: '收货地址', type: 'text' }, { key: 'remark', label: '备注', type: 'text' }, @@ -816,6 +817,16 @@ const EXPORT_TYPES = { // 电商平台(多选)与平台单号(多个精确匹配),与列表接口同口径 whereIn(wh, 't.source_platform_code', csvValues(f.platform_codes, 50).map(code => code.toUpperCase())); whereIn(wh, 't.oaid_order_source_code', csvValues(f.platform_order_nos, 200)); + // 序列号(SN)反查:与列表接口同口径,命中 order_sn_codes 的订单才导出 + const snCodes = csvValues(f.sn_codes, 200); + if (snCodes.length) { + wh.raw( + 'EXISTS (SELECT 1 FROM order_sn_codes osc WHERE osc.order_id = t.id AND osc.principal_id = ? ' + + `AND osc.sn_code IN (${snCodes.map(() => '?').join(',')}))`, + ctx.principalId, + ...snCodes + ); + } // 外部发货同步状态(配送视图/配送异常视图用:0待同步 1已同步 2待重试 3异常,支持逗号多选) const sendStatuses = csvValues(f.external_send_status, 10) .map(value => Number(value)) diff --git a/backend/database/migrations/20261113220000-create-order-sn-codes.js b/backend/database/migrations/20261113220000-create-order-sn-codes.js new file mode 100644 index 0000000..7ad568a --- /dev/null +++ b/backend/database/migrations/20261113220000-create-order-sn-codes.js @@ -0,0 +1,69 @@ +'use strict'; + +/** + * 订单序列号(SN)关联表 order_sn_codes + * + * 背景:WMS 回传发货确认(deliveryorder.confirm)时,明细行可能带 `snList`(序列号列表)。 + * OMS 原先把确认报文整体存进订单的 `wms_push_result.confirm`(JSON,无法按 SN 反查), + * 现改为**另存关联表**:一行一个 SN,带行号 / 商品 / 包裹 / 运单号,供订单查询按 SN 反查订单。 + * + * 归属口径: + * - `order_id` = order_index.id(订单全局唯一 ID;订单在状态表之间流转时不变,因此转表不用搬 SN) + * - `principal_id` 冗余主体,查询按「主体 + SN」走索引 + * - 一条 SN 可能在同一订单里重复回传(WMS 重推),由唯一键 `uk_osc_order_sn` 兜底去重 + * + * 幂等:showAllTables 判断表是否存在。 + */ +module.exports = { + async up(queryInterface, Sequelize) { + const tables = await queryInterface.showAllTables(); + const exists = tables + .map(t => (typeof t === 'string' ? t : (t.tableName || t.TABLE_NAME))) + .includes('order_sn_codes'); + if (exists) return; + + const { BIGINT, STRING, DATE } = Sequelize; + await queryInterface.createTable('order_sn_codes', { + id: { type: BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true, comment: '主键' }, + principal_id: { type: BIGINT.UNSIGNED, allowNull: false, comment: '所属主体ID(主体隔离)' }, + order_id: { type: BIGINT.UNSIGNED, allowNull: false, comment: '订单ID(order_index.id,全局唯一;流转状态表不变)' }, + order_no: { type: STRING(50), allowNull: true, comment: '订单号(冗余,便于排查 / 导出)' }, + order_line_no: { type: STRING(20), allowNull: true, comment: '回传明细行号(orderLineNo)' }, + item_id: { type: BIGINT.UNSIGNED, allowNull: true, comment: '商品ID(itemId)' }, + item_code: { type: STRING(100), allowNull: true, comment: '商品编码(itemCode)' }, + item_name: { type: STRING(255), allowNull: true, comment: '商品名称(itemName)' }, + package_code: { type: STRING(50), allowNull: true, comment: '包裹号(packages.package.packageCode)' }, + express_code: { type: STRING(50), allowNull: true, comment: '运单号(packages.package.expressCode)' }, + warehouse_id: { type: BIGINT.UNSIGNED, allowNull: true, comment: '仓库ID(app_key 定位到的仓库)' }, + sn_code: { type: STRING(255), allowNull: false, comment: '序列号(SN 原值,去空白;反查订单用)' }, + source: { type: STRING(20), allowNull: false, defaultValue: 'wms', comment: '来源:wms=仓库回传(预留手工补录)' }, + created_at: { type: DATE, allowNull: true, comment: '创建时间' }, + updated_at: { type: DATE, allowNull: true, comment: '更新时间' }, + }, { + comment: '订单序列号(SN)关联表(WMS 发货确认回传的 snList)', + charset: 'utf8mb4', + collate: 'utf8mb4_unicode_ci', + }); + + // 反查订单:principal_id + sn_code(订单列表按 SN 多值精确匹配) + await queryInterface.addIndex('order_sn_codes', [ 'principal_id', 'sn_code' ], { + name: 'idx_osc_principal_sn', + }); + await queryInterface.addIndex('order_sn_codes', [ 'order_id' ], { + name: 'idx_osc_order', + }); + // 同一订单重复回传同一 SN 时由唯一键兜底去重(代码层已先过滤,这里防并发) + await queryInterface.addIndex('order_sn_codes', [ 'principal_id', 'order_id', 'sn_code' ], { + name: 'uk_osc_order_sn', + unique: true, + }); + }, + + async down(queryInterface) { + const tables = await queryInterface.showAllTables(); + const exists = tables + .map(t => (typeof t === 'string' ? t : (t.tableName || t.TABLE_NAME))) + .includes('order_sn_codes'); + if (exists) await queryInterface.dropTable('order_sn_codes'); + }, +}; diff --git a/backend/test/app/lib/orderSnCodes.test.js b/backend/test/app/lib/orderSnCodes.test.js new file mode 100644 index 0000000..6800e1f --- /dev/null +++ b/backend/test/app/lib/orderSnCodes.test.js @@ -0,0 +1,89 @@ +'use strict'; + +const { assert } = require('egg-mock/bootstrap'); +const { extractSnEntries } = require('../../../app/lib/orderSnCodes'); + +describe('test/app/lib/orderSnCodes.test.js', () => { + it('解析明细行 snList(字符串数组)并带行号/商品信息', () => { + const entries = extractSnEntries({ + lines: [ + { + orderLineNo: '1', + itemCode: 'SKU-SN-001', + itemId: '162678', + itemName: '序列号商品A', + snList: [ + 'HTTPS://SUYUAN.HULIANZAOWU.COM/PRODUCT?Q=YGP9213002516455', + '6977752010196', + ], + }, + { orderLineNo: '2', itemCode: 'SKU-NORMAL-002', snList: [] }, + ], + }); + + assert(entries.length === 2); + assert(entries[0].sn_code === 'HTTPS://SUYUAN.HULIANZAOWU.COM/PRODUCT?Q=YGP9213002516455'); + assert(entries[0].order_line_no === '1'); + assert(entries[0].item_code === 'SKU-SN-001'); + assert(entries[0].item_id === 162678); + assert(entries[1].sn_code === '6977752010196'); + // 包裹维度字段在行级 SN 上为空 + assert(entries[0].package_code === null); + assert(entries[0].express_code === null); + }); + + it('解析包裹内商品的 snList,并带包裹号/运单号', () => { + const entries = extractSnEntries({ + packages: [ + { + packageCode: 'PK-20261113-0001', + expressCode: 'YT1234567890123', + items: [{ itemCode: 'SKU-SN-002', itemId: 162672, snList: [ 'SN-A', 'SN-B' ] }], + }, + ], + }); + + assert(entries.length === 2); + assert(entries[0].package_code === 'PK-20261113-0001'); + assert(entries[0].express_code === 'YT1234567890123'); + assert(entries[0].item_code === 'SKU-SN-002'); + assert(entries.map(entry => entry.sn_code).join(',') === 'SN-A,SN-B'); + }); + + it('兼容 snCodes 逗号分隔 / 对象数组 / snCode 单值', () => { + const entries = extractSnEntries({ + lines: [ + { orderLineNo: '1', snCodes: 'SN1,SN2;SN3' }, + { orderLineNo: '2', snList: [{ snCode: 'SN4' }, { sn: 'SN5' }] }, + { orderLineNo: '3', snCode: 'SN6' }, + ], + }); + + assert(entries.map(entry => entry.sn_code).join(',') === 'SN1,SN2,SN3,SN4,SN5,SN6'); + }); + + it('同一 SN 在行级与包裹级重复出现时只留一条(不区分大小写)', () => { + const entries = extractSnEntries({ + lines: [{ orderLineNo: '1', itemCode: 'SKU-A', snList: [ 'sn-x' ] }], + packages: [{ packageCode: 'PK-1', items: [{ itemCode: 'SKU-A', snList: [ 'SN-X' ] }] }], + }); + + assert(entries.length === 1); + assert(entries[0].sn_code === 'sn-x'); + assert(entries[0].package_code === null); + }); + + it('无 SN / 空报文返回空数组', () => { + const blankLine = { snList: [ ' ' ] }; + assert(extractSnEntries({}).length === 0); + assert(extractSnEntries({ lines: [{ orderLineNo: '1', snList: [] }] }).length === 0); + assert(extractSnEntries({ lines: [ null, 'x', blankLine ] }).length === 0); + }); + + it('单次回传条数上限 2000', () => { + const snList = Array.from({ length: 2100 }, (_, index) => `SN-${index}`); + const entries = extractSnEntries({ lines: [{ orderLineNo: '1', snList }] }); + assert(entries.length === 2000); + assert(entries[1999].sn_code === 'SN-1999'); + }); +}); diff --git a/frontend/src/api/orderStatus.ts b/frontend/src/api/orderStatus.ts index 797ed6a..455b8af 100644 --- a/frontend/src/api/orderStatus.ts +++ b/frontend/src/api/orderStatus.ts @@ -164,6 +164,23 @@ export interface OrderStatusItem { /** 仅历史视图 */ archived_at?: string | null transferred_at?: string | null + /** 序列号(SN)列表(仅详情返回;WMS 发货确认回传的 snList) */ + sn_codes?: OrderStatusSnCode[] +} + +/** 订单序列号(SN)行(order_sn_codes) */ +export interface OrderStatusSnCode { + id: number + order_id: number + order_line_no?: string | null + item_id?: number | null + item_code?: string | null + item_name?: string | null + package_code?: string | null + express_code?: string | null + sn_code: string + source?: string | null + created_at?: string } export interface OrderStatusQuery { @@ -176,6 +193,8 @@ export interface OrderStatusQuery { receiver?: string address?: string remark?: string + /** 序列号(SN):多个精确匹配,逗号分隔 */ + sn_codes?: string created_from?: string created_to?: string archived_from?: string diff --git a/frontend/src/views/Order/StatusPanel.vue b/frontend/src/views/Order/StatusPanel.vue index 0401d9b..d5186f8 100644 --- a/frontend/src/views/Order/StatusPanel.vue +++ b/frontend/src/views/Order/StatusPanel.vue @@ -41,6 +41,7 @@ import { type OrderStage, type OrderStatusFilters, type OrderStatusItem, + type OrderStatusSnCode, } from '@/api/orderStatus' /** @@ -84,6 +85,8 @@ const query = reactive({ platform_codes: [] as string[], /** 平台单号(多个精确匹配,支持批量粘贴) */ platform_order_nos: [] as string[], + /** 序列号(SN):多个精确匹配,WMS 回传的 snList 反查订单 */ + sn_codes: [] as string[], receiver: '', address: '', remark: '', @@ -175,6 +178,7 @@ const { loading, list, total, elapsed, fetchList, search, handlePageChange, hand if (query.shop_id !== '') params.shop_id = query.shop_id if (query.platform_codes.length) params.platform_codes = query.platform_codes.join(',') if (query.platform_order_nos.length) params.platform_order_nos = query.platform_order_nos.join(',') + if (query.sn_codes.length) params.sn_codes = query.sn_codes.join(',') if (query.receiver) params.receiver = query.receiver.trim() if (query.address) params.address = query.address.trim() if (query.remark) params.remark = query.remark.trim() @@ -207,6 +211,7 @@ function reset() { query.shop_id = '' query.platform_codes = [] query.platform_order_nos = [] + query.sn_codes = [] query.receiver = '' query.address = '' query.remark = '' @@ -227,6 +232,7 @@ const exportFilters = computed(() => ({ shop_id: query.shop_id, platform_codes: query.platform_codes.join(','), platform_order_nos: query.platform_order_nos.join(','), + sn_codes: query.sn_codes.join(','), created_from: query.createdRange[0], created_to: query.createdRange[1], archived_from: query.archivedRange[0], @@ -585,16 +591,20 @@ const detailVisible = ref(false) const detailLoading = ref(false) const detailRow = ref(null) const detailProducts = ref([]) +/** 仓库回传的序列号(order_sn_codes,随详情返回) */ +const detailSnCodes = ref([]) async function openDetail(row: OrderStatusItem) { detailRow.value = row detailProducts.value = [] + detailSnCodes.value = [] detailVisible.value = true detailLoading.value = true try { const { order, items } = await getOrderStatusDetail(row.id) detailRow.value = order detailProducts.value = items + detailSnCodes.value = order.sn_codes || [] } catch { // 拦截器已提示,退化为列表行展示 } finally { @@ -904,6 +914,14 @@ onBeforeUnmount(() => { @update:model-value="search" /> + + + { + +