feat(order): 留存 WMS 回传的 SN 列表并支持按 SN 反查订单

- 新增 order_sn_codes 关联表(order_id = order_index.id,一行一个 SN,唯一键兜底去重)
- deliveryorder.confirm 解析 orderLines[].snList / 包裹内商品 snList,幂等写入(仅委外中/已配送的订单)
- 订单列表新增 sn_codes 多值筛选(逗号/换行分隔,最多 200 个,精确匹配反查)
- 订单详情返回 sn_codes;订单导出支持「序列号」筛选
- 前端订单页新增「序列号」批量筛选与详情序列号明细
- 补充 WMS 回传报文说明与 lib 单测

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-13 22:42:57 +08:00
parent 69c272d260
commit 61309c430f
13 changed files with 617 additions and 2 deletions

View File

@ -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`,页面详情抽屉展示序列号明细。

View File

@ -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', '订单列表'),

View File

@ -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 备注 / 异常原因,模糊匹配

View File

@ -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;
}

View File

@ -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<String>} 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<String>} 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<Object>} 商品数组
*/
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<Object>} [p.lines] 明细行数组(request.orderLines)
* @param {Array<Object>} [p.packages] 包裹数组(request.packages.package)
* @return {Array<Object>} 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<Object>} [p.lines] 明细行数组
* @param {Array<Object>} [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<Array<Object>>} 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<String>} p.snCodes SN 列表(精确匹配,最多 200 个由调用方限制)
* @return {Promise<Array<Number>>} 命中的订单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,
};

View File

@ -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,

View File

@ -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;
};

View File

@ -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 };
}
/**

View File

@ -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))

View File

@ -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');
},
};

View File

@ -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');
});
});

View File

@ -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

View File

@ -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<OrderStatusItem | null>(null)
const detailProducts = ref<OrderItemLine[]>([])
/** 仓库回传的序列号(order_sn_codes,随详情返回) */
const detailSnCodes = ref<OrderStatusSnCode[]>([])
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"
/>
</el-form-item>
<el-form-item label="序列号">
<MultiValueFilter
v-model="query.sn_codes"
placeholder="批量查询,多个 SN"
width="200px"
@update:model-value="search"
/>
</el-form-item>
<el-form-item label="创建时间">
<el-date-picker
v-model="query.createdRange"
@ -1218,6 +1236,19 @@ onBeforeUnmount(() => {
<template #default="{ row }">{{ row.inventory_type === 'CC' ? '残次' : '正品' }}</template>
</el-table-column>
</DataTable>
<template v-if="detailSnCodes.length">
<el-divider content-position="left">序列号({{ detailSnCodes.length }} 个)</el-divider>
<DataTable :data="detailSnCodes" :stripe="true">
<el-table-column prop="order_line_no" label="行号" width="70" />
<el-table-column prop="item_code" label="商品编码" width="150" show-overflow-tooltip />
<el-table-column prop="sn_code" label="序列号" min-width="200" show-overflow-tooltip />
<el-table-column prop="express_code" label="运单号" width="150" show-overflow-tooltip />
<el-table-column label="回传时间" width="160">
<template #default="{ row }">{{ formatDateTime(row.created_at) }}</template>
</el-table-column>
</DataTable>
</template>
</template>
</el-drawer>