From 77da5e1c6929133f784da48d8ff099443b0bce05 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sun, 13 Sep 2026 02:42:23 +0800 Subject: [PATCH] =?UTF-8?q?feat(backend):=20=E5=8F=91=E8=B4=A7=E5=8D=95?= =?UTF-8?q?=E6=89=B9=E9=87=8F=E6=93=8D=E4=BD=9C=E4=B8=8E=E5=BA=97=E9=93=BA?= =?UTF-8?q?=E5=BF=85=E5=A1=AB/=E6=8E=A8=E9=80=81=E6=A0=A1=E9=AA=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增批量审核 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 改为必填 --- backend/app/contract/index.js | 34 ++++- backend/app/controller/orderDelivery.js | 152 +++++++++++++++++++++-- backend/app/router.js | 3 + backend/app/service/orderDeliveryPush.js | 18 +++ 4 files changed, 198 insertions(+), 9 deletions(-) diff --git a/backend/app/contract/index.js b/backend/app/contract/index.js index 0c82863..959da43 100644 --- a/backend/app/contract/index.js +++ b/backend/app/contract/index.js @@ -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: '发货单号' }, diff --git a/backend/app/controller/orderDelivery.js b/backend/app/controller/orderDelivery.js index 0a31b1b..9a9910d 100644 --- a/backend/app/controller/orderDelivery.js +++ b/backend/app/controller/orderDelivery.js @@ -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; } diff --git a/backend/app/router.js b/backend/app/router.js index 4227a3c..946e262 100644 --- a/backend/app/router.js +++ b/backend/app/router.js @@ -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); diff --git a/backend/app/service/orderDeliveryPush.js b/backend/app/service/orderDeliveryPush.js index 8484cbd..319c2d2 100644 --- a/backend/app/service/orderDeliveryPush.js +++ b/backend/app/service/orderDeliveryPush.js @@ -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' ]],