feat(backend): 发货单批量操作与店铺必填/推送校验

- 新增批量审核 audit-batch、批量推送 push-batch、切换发货仓库 change-warehouse、设置所属店铺 change-shop

  统一由 _buildScope 解析范围(scope_by=ids 按勾选 / filter 按筛选条件),支持 dry_run 预览影响范围

- 手工单必须选店铺:create/update 必填且不允许清空、audit 校验、pushOne 无店铺直接跳过;shop_nick 为空时按 shop_id 兜底补齐并回写快照

- 修复范围解析与「目标店铺」字段重名导致命中 0 条:店铺筛选取 from_shop_id,changeShop 前剔除 shop_id

- 契约新增 changeDeliveryWarehouseRequest/changeDeliveryShopRequest/orderDeliveryBatchRequest 等,createOrderDeliveryRequest 的 warehouse_id/shop_id 改为必填
This commit is contained in:
liufumingren 2026-09-13 02:42:23 +08:00
parent 8ef79914f9
commit 77da5e1c69
4 changed files with 198 additions and 9 deletions

View File

@ -1118,7 +1118,7 @@ module.exports = {
createOrderDeliveryRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入(服务端强制使用,请求体不可篡改)' },
warehouse_id: { type: 'integer', required: true, description: '仓库ID(关联 warehouses,需属于当前主体;推送 WMS 依赖该仓库的 warehouseCode 与接口配置)' },
shop_id: { type: 'integer', description: '店铺ID(关联 shops,需属于当前主体)' },
shop_id: { type: 'integer', required: true, description: '店铺ID(关联 shops,需属于当前主体;推送时 shopNick 取该店铺名称,WMS 侧靠它匹配快递策略,必填)' },
warehouse_code: { type: 'string', description: '仓库编码,缺省按 warehouse_id 取 warehouses.code' },
order_type: { type: 'string', description: '订单类型(ORDER 组枚举):JYCK 一般交易出库单 / HHCK 换货出库 / BFCK 补发出库,默认 JYCK' },
is_urgency: { type: 'string', description: '是否紧急:Y / N,默认 N' },
@ -1263,7 +1263,7 @@ module.exports = {
orderDeliveryBatchResult: {
matched: { type: 'integer', description: '命中范围条数' },
affected: { type: 'integer', description: '实际处理条数(审核生效条数 / 本次推送尝试条数)' },
auditable: { type: 'integer', description: '批量审核:可审核条数(待处理 1)' },
auditable: { type: 'integer', description: '批量审核:可审核条数(待处理 1 且已设置店铺)' },
pushable: { type: 'integer', description: '批量推送:可推送条数(已审核 2)' },
skipped: { type: 'integer', description: '范围内不符合条件的条数(按状态跳过)' },
pending_rest: { type: 'integer', description: '批量推送:超出单次上限、留给定时任务继续推送的条数' },
@ -1282,6 +1282,36 @@ module.exports = {
retry: { type: 'boolean', description: '是否待重试(无响应或超时,保留已审核)' },
message: { type: 'string', description: '结果说明' },
},
changeDeliveryShopRequest: {
principal_id: { type: 'integer', required: true, description: '所属主体ID,由请求拦截器注入(服务端强制使用)' },
shop_id: { type: 'integer', required: true, description: '目标店铺ID(需属于当前主体,会同步刷新 shop_nick 名称快照)' },
ids: { type: 'array', itemType: 'integer', description: '按选中设置:发货单ID数组(scope_by=ids 时必传且不能为空)' },
scope_by: { type: 'string', description: '范围类型:ids=按勾选(忽略筛选条件)/ filter=按筛选条件(忽略 ids);不传时按「有 ids 走 ids,否则走条件」兜底' },
dry_run: { type: 'boolean', description: 'true=仅预览影响范围(不写库并返回样例单据),默认 false 执行' },
delivery_order_code: { type: 'string', description: '条件:发货单号,模糊匹配' },
status: { type: 'integer', description: '条件:状态 1待处理 2已审核 3已推送 4已完成 5已作废 9已取消' },
order_type: { type: 'string', description: '条件:订单类型 JYCK / HHCK / BFCK' },
shop_id_filter: { type: 'integer', description: '条件:原店铺ID' },
from_shop_id: { type: 'integer', description: '条件:原店铺ID(shop_id 在设置店铺接口里是目标店铺,筛选请用本字段)' },
from_warehouse_id: { type: 'integer', description: '条件:原发货仓库ID' },
},
orderDeliveryShopChangeResult: {
target_shop: { type: 'object', description: '目标店铺 { id, name }' },
matched: { type: 'integer', description: '命中范围条数(已排除本就属于目标店铺的单据)' },
switchable: { type: 'integer', description: '可设置条数:待处理(1) / 已审核(2) / 已推送(3)' },
blocked: { type: 'integer', description: '不可设置条数:已完成(4) / 已作废(5) / 已取消(9)' },
blocked_reason: { type: 'object', description: '不可设置的状态分布,如 { "4": 2 }' },
same_shop: { type: 'integer', description: '范围内已属于目标店铺的条数(无需处理)' },
scope: { type: 'object', description: '操作范围 { by: "ids" | "filter", ids: [] }' },
samples: { type: 'array', itemType: 'orderDeliveryShopChangeSample', description: '样例单据(最多 5 条,仅 dry_run=true 返回)' },
updated: { type: 'integer', description: '本次实际更新条数(仅 dry_run=false 返回)' },
},
orderDeliveryShopChangeSample: {
id: { type: 'integer', description: '发货单ID' },
delivery_order_code: { type: 'string', description: '发货单号' },
status: { type: 'integer', description: '状态' },
shop_nick: { type: 'string', description: '当前店铺名称' },
},
orderDeliveryWarehouseChangeSample: {
id: { type: 'integer', description: '发货单ID' },
delivery_order_code: { type: 'string', description: '发货单号' },

View File

@ -86,6 +86,13 @@ const EDITABLE_STATUS = 1;
*/
const SWITCHABLE_WAREHOUSE_STATUS = [ 1, 2 ];
/**
* 可设置所属店铺的状态:待处理(1) / 已审核(2) / 已推送(3)
* - 店铺只影响推送时的快递策略匹配(shopNick)与 OMS 自身记录,不回写 WMS,
* 所以「已推送(3)」也允许修正;已完成(4) / 已作废(5) / 已取消(9) 不再变更
*/
const SHOP_SWITCHABLE_STATUS = [ 1, 2, 3 ];
/**
* @controller OrderDeliveryController 发货单(订单)管理
* 单据头 order_deliveries;字段口径对齐 WMS wms_order_delivery 与奇门 deliveryOrder/receiverInfo
@ -224,6 +231,13 @@ class OrderDeliveryController extends Controller {
ctx.body = { code: 400, message: 'warehouse_id(仓库)为必填项:推送仓库需要仓库编码与仓库接口配置' };
return;
}
// 店铺必填:shopNick 取所选店铺名称,WMS 侧靠它匹配快递策略(缺失时可能匹配不到快递)
const shopId = body.shop_id != null && body.shop_id !== '' ? Number(body.shop_id) : null;
if (!shopId) {
ctx.status = 400;
ctx.body = { code: 400, message: 'shop_id(店铺)为必填项:推送仓库时 shopNick 取所选店铺名称' };
return;
}
// 订单类型:ORDER 组枚举(JYCK/HHCK/BFCK),非法值拒绝,不传时默认 JYCK(一般交易出库单)
const orderType = normalizeDeliveryOrderType(body.order_type);
@ -274,8 +288,7 @@ class OrderDeliveryController extends Controller {
if (warehouse) payload.warehouse_code = warehouse.code;
}
// 店铺名称(shop_nick)取所选店铺名称,无需手工填写
const shopId = body.shop_id != null && body.shop_id !== '' ? Number(body.shop_id) : null;
// 店铺名称(shop_nick)取所选店铺名称,无需手工填写(shopId 已在前面必填校验中解析)
let shopNick = null;
if (shopId) {
const shop = await ctx.model.Shop.findByPk(shopId, { attributes: [ 'id', 'name' ] });
@ -387,6 +400,14 @@ class OrderDeliveryController extends Controller {
return;
}
// 店铺必填:不允许清空(shopNick 取店铺名称,推送时用于匹配快递策略)
const mergedShopId = body.shop_id === undefined ? order.shop_id : body.shop_id;
if (!(Number(mergedShopId) > 0)) {
ctx.status = 400;
ctx.body = { code: 400, message: 'shop_id(店铺)为必填项:推送仓库时 shopNick 取所选店铺名称' };
return;
}
if (body.warehouse_id !== undefined && body.warehouse_id !== null && body.warehouse_id !== '') {
body.warehouse_id = Number(body.warehouse_id);
// 仓库变更时同步刷新仓库编码快照
@ -539,6 +560,115 @@ class OrderDeliveryController extends Controller {
ctx.body = { code: 0, message: 'success', data: { ...result, updated } };
}
/**
* @summary 批量设置所属店铺
* @description 按「选中单据(ids)」或「筛选条件」把发货单的店铺设为目标店铺(同时刷新 shop_nick 名称快照);
* 店铺只影响推送时的快递策略匹配(shopNick)与 OMS 记录、不回写 WMS,因此「已推送(3)」也允许修正;
* 传 dry_run=true 时只返回影响范围
* @router post /api/order-deliveries/change-shop
* @apikey
* @request body changeDeliveryShopRequest *body
* @response 200 orderDeliveryShopChangeResult success
*/
async changeShop() {
const { ctx } = this;
const Op = this.app.Sequelize.Op;
const body = ctx.request.body || {};
const Model = ctx.model.OrderDelivery;
const targetShopId = body.shop_id != null && body.shop_id !== '' ? Number(body.shop_id) : null;
if (!targetShopId) {
ctx.status = 400;
ctx.body = { code: 400, message: 'shop_id(目标店铺)为必填项' };
return;
}
const ownerCheck = await this.assertOwnerBelongsToPrincipal(null, targetShopId);
if (!ownerCheck.ok) {
ctx.status = 404;
ctx.body = { code: 404, message: ownerCheck.message };
return;
}
const target = await ctx.model.Shop.findByPk(targetShopId, { attributes: [ 'id', 'name' ] });
// shop_id 在本接口是「目标店铺」,不能当作筛选条件(否则 scope 里会出现 shop_id = target 导致命中 0 条)
const scopeBody = { ...body };
delete scopeBody.shop_id;
const built = this._buildScope(ctx, scopeBody);
if (!built.ok) {
ctx.status = 400;
ctx.body = { code: 400, message: built.message };
return;
}
const { scopeBy, ids, where: scope, dryRun } = built;
// 已是目标店铺(含店铺为空)的都要纳入:空店铺正是需要补的
const notTarget = { [Op.or]: [{ shop_id: { [Op.ne]: targetShopId } }, { shop_id: null }] };
const matchedWhere = { [Op.and]: [ scope, notTarget ] };
const switchableWhere = { [Op.and]: [ matchedWhere, { status: { [Op.in]: SHOP_SWITCHABLE_STATUS } }] };
const matched = await Model.count({ where: matchedWhere });
const switchable = await Model.count({ where: switchableWhere });
const blocked = matched - switchable;
const sameShop = await Model.count({ where: { [Op.and]: [ scope, { shop_id: targetShopId }] } });
const blockedRows = blocked > 0
? await Model.findAll({
where: { [Op.and]: [ matchedWhere, { status: { [Op.notIn]: SHOP_SWITCHABLE_STATUS } }] },
attributes: [ 'status', [ Model.sequelize.fn('COUNT', Model.sequelize.col('id')), 'count' ]],
group: [ 'status' ],
raw: true,
})
: [];
const blockedReason = {};
for (const row of blockedRows) blockedReason[row.status] = Number(row.count);
const result = {
target_shop: { id: target.id, name: target.name },
matched,
switchable,
blocked,
blocked_reason: blockedReason,
same_shop: sameShop,
scope: { by: scopeBy, ids: scopeBy === 'ids' ? ids : [] },
};
if (dryRun) {
const samples = matched > 0
? await Model.findAll({
where: matchedWhere,
attributes: [ 'id', 'delivery_order_code', 'status', 'shop_id', 'shop_nick' ],
order: [[ 'id', 'ASC' ]],
limit: 5,
})
: [];
ctx.body = {
code: 0,
message: 'success',
data: {
...result,
samples: samples.map(s => ({
id: Number(s.id),
delivery_order_code: s.delivery_order_code,
status: Number(s.status),
shop_nick: s.shop_nick || null,
})),
},
};
return;
}
if (!switchable) {
ctx.body = { code: 0, message: 'success', data: { ...result, updated: 0 } };
return;
}
const [ updated ] = await Model.update(
{ shop_id: targetShopId, shop_nick: target.name },
{ where: switchableWhere }
);
ctx.body = { code: 0, message: 'success', data: { ...result, updated } };
}
/**
* 主体隔离辅助:校验仓库/店铺是否属于当前主体(为空则跳过)
* @param {Number|null} warehouseId 仓库ID
@ -607,7 +737,7 @@ class OrderDeliveryController extends Controller {
/**
* @summary 审核发货单
* @description 状态流转:待处理(1) → 已审核(2);需先录入明细;写入审核人与审核时间。
* @description 状态流转:待处理(1) → 已审核(2);需先录入明细且已选择店铺(手工单必须选店铺);写入审核人与审核时间。
* **审核只入队不推送**:由定时任务(app/schedule/orderDeliveryPush.js)异步递交 WMS,避免集中审核打满对方服务;
* 也可用「批量推送」或单条「推送」接口立即推送
* @router post /api/order-deliveries/{id}/audit
@ -635,6 +765,12 @@ class OrderDeliveryController extends Controller {
ctx.body = { code: 400, message: '单据无明细,无法审核' };
return;
}
// 手工单必须选店铺:shopNick 取店铺名称,推送时 WMS 靠它匹配快递策略
if (!(Number(order.shop_id) > 0)) {
ctx.status = 400;
ctx.body = { code: 400, message: '单据未设置店铺,无法审核:请先选择店铺(可用「批量操作 → 设置所属店铺」)' };
return;
}
// 清空上一轮推送记录(重试次数从 0 开始),状态置「已审核(2)」等待定时任务推送
await order.update({
@ -667,7 +803,8 @@ class OrderDeliveryController extends Controller {
}
const matchedWhere = built.where;
const auditableWhere = { [Op.and]: [ matchedWhere, { status: 1 }] };
// 可审核 = 待处理(1) 且已设置店铺(手工单必须选店铺,推送时 shopNick 取店铺名称)
const auditableWhere = { [Op.and]: [ matchedWhere, { status: 1 }, { shop_id: { [Op.ne]: null } }] };
const matched = await ctx.model.OrderDelivery.count({ where: matchedWhere });
const auditable = await ctx.model.OrderDelivery.count({ where: auditableWhere });
@ -1021,15 +1158,16 @@ class OrderDeliveryController extends Controller {
const code = body.delivery_order_code ? String(body.delivery_order_code).trim() : '';
const status = body.status === undefined || body.status === null || body.status === '' ? null : Number(body.status);
const orderType = body.order_type ? String(body.order_type).trim().toUpperCase() : '';
const shopId = body.shop_id ? Number(body.shop_id) : null;
// 店铺筛选:from_shop_id 为通用写法(shop_id 仅作兼容,设置店铺接口里 shop_id 是「目标店铺」不能当条件)
const fromShopId = body.from_shop_id ? Number(body.from_shop_id) : (body.shop_id ? Number(body.shop_id) : null);
const fromWarehouseId = body.from_warehouse_id ? Number(body.from_warehouse_id) : null;
if (!code && status === null && !orderType && !shopId && !fromWarehouseId) {
if (!code && status === null && !orderType && !fromShopId && !fromWarehouseId) {
return { ok: false, message: '请指定操作范围:勾选单据(ids)或至少传一个筛选条件' };
}
if (code) where.delivery_order_code = { [Op.like]: `%${code}%` };
if (status !== null) where.status = status;
if (orderType) where.order_type = orderType;
if (shopId) where.shop_id = shopId;
if (fromShopId) where.shop_id = fromShopId;
if (fromWarehouseId) where.warehouse_id = fromWarehouseId;
}

View File

@ -112,6 +112,9 @@ module.exports = app => {
// 批量切换发货仓库(按勾选 ids 或筛选条件;dry_run=true 仅预览影响范围)
router.post('/api/order-deliveries/change-warehouse', jwtAuth, principalCheck({ model: 'OrderDelivery' }), controller.orderDelivery.changeWarehouse);
// 批量设置所属店铺(shopNick 取店铺名称;dry_run=true 仅预览影响范围)
router.post('/api/order-deliveries/change-shop', jwtAuth, principalCheck({ model: 'OrderDelivery' }), controller.orderDelivery.changeShop);
// 发货单(订单):字段口径对齐 WMS 发货单(wms_order_delivery)与奇门 deliveryOrder,独立于出库单
// 状态流转专用动作需在 resources 之前注册,避免被 /api/order-deliveries/:id 误匹配
router.post('/api/order-deliveries/audit-batch', jwtAuth, principalCheck({ model: 'OrderDelivery' }), controller.orderDelivery.auditBatch);

View File

@ -138,6 +138,10 @@ class OrderDeliveryPushService extends Service {
if (!(Number(order.warehouse_id) > 0)) {
return { ok: false, skipped: true, message: '单据未指定仓库,无法推送' };
}
// 手工单必须选店铺:无店铺时不下推(否则报文中没有 shopNick,WMS 匹配不到快递策略)
if (!(Number(order.shop_id) > 0)) {
return { ok: false, skipped: true, message: '单据未设置店铺,无法推送:请先设置店铺(批量操作 → 设置所属店铺)' };
}
const api = await this.findWarehouseApi(order);
if (!api) {
@ -180,6 +184,20 @@ class OrderDeliveryPushService extends Service {
attemptedAt: now.toISOString(),
};
// 店铺名称兜底:shopNick 取所选店铺名称(WMS 侧靠它匹配快递策略),
// 历史数据可能只存了 shop_id 而没写快照,这里补一次并回写
if (!order.shop_nick && order.shop_id) {
const shop = await ctx.model.Shop.findByPk(order.shop_id, { attributes: [ 'id', 'name' ] });
if (shop && shop.name) {
order.shop_nick = shop.name;
await order.update({ shop_nick: shop.name });
ctx.logger.info(`[delivery-push] ${order.delivery_order_code} 补齐店铺名称快照:${shop.name}`);
}
}
if (!order.shop_nick) {
ctx.logger.warn(`[delivery-push] ${order.delivery_order_code} 未取到店铺名称(shop_nick 为空),推送报文中不会有 shopNick,WMS 侧可能匹配不到快递策略`);
}
const items = await ctx.model.OrderDeliveryItem.findAll({
where: { order_delivery_id: order.id },
order: [[ 'order_line_no', 'ASC' ], [ 'id', 'ASC' ]],