diff --git a/app/model/express_interface.js b/app/model/express_interface.js index b849d6e..bcdd79b 100644 --- a/app/model/express_interface.js +++ b/app/model/express_interface.js @@ -148,6 +148,11 @@ module.exports = app => { allowNull: true, comment: '产品编码', }, + goods_description: { + type: STRING(255), + allowNull: true, + comment: '物品描述', + }, weight_type: { type: INTEGER(10), allowNull: true, diff --git a/app/service/systemMethods/setting/expressInterface.js b/app/service/systemMethods/setting/expressInterface.js index 1d2d007..2a6eea5 100644 --- a/app/service/systemMethods/setting/expressInterface.js +++ b/app/service/systemMethods/setting/expressInterface.js @@ -278,6 +278,8 @@ class expressInterfaceService extends MainService { templateUrl: camelTemplateUrl, ext_data: extData, extData: camelExtData, + goods_description: goodsDescription, + goodsDescription: camelGoodsDescription, template_id: templateId, templateId: camelTemplateId, paymode, @@ -328,6 +330,9 @@ class expressInterfaceService extends MainService { if (extData !== undefined || camelExtData !== undefined) { payload.ext_data = extData !== undefined ? extData : camelExtData; } + if (goodsDescription !== undefined || camelGoodsDescription !== undefined) { + payload.goods_description = goodsDescription !== undefined ? goodsDescription : camelGoodsDescription; + } if (templateId !== undefined || camelTemplateId !== undefined) { payload.template_id = templateId !== undefined ? templateId : camelTemplateId; } diff --git a/app/service/systems/express_platform.js b/app/service/systems/express_platform.js index 74b6676..822fa6c 100644 --- a/app/service/systems/express_platform.js +++ b/app/service/systems/express_platform.js @@ -2008,7 +2008,7 @@ class ExpressPlatformService extends MainService { name: item.item_name || '商品', count: item.plan_qty, })) || [], - goods_description: '化妆品', + goods_description: String(listByWarehousePlatformCode.goods_description || '').trim() || '化妆品', id: `${orderDelivery.warehouse_id}_${orderDelivery.id}_${order_tmp.business_key}`, length: Number(orderDelivery.length || 1), width: Number(orderDelivery.width || 1), diff --git a/app/service/systems/setting/expressInterface.js b/app/service/systems/setting/expressInterface.js index 9fa73fc..3e11180 100644 --- a/app/service/systems/setting/expressInterface.js +++ b/app/service/systems/setting/expressInterface.js @@ -762,6 +762,7 @@ class SettingExpressInterfaceService extends Service { town_name: this.normalizeOptionalText(row.town_name, 'town_name', 255), site_code: this.normalizeOptionalText(row.site_code, 'site_code', 255), product_type: this.normalizeOptionalText(row.product_type, 'product_type', 50), + goods_description: this.normalizeOptionalText(row.goods_description, 'goods_description', 255), shop_name: this.normalizeOptionalText( (row.shop && row.shop.shop_name) || row.shop_name, 'shop_name', @@ -1087,7 +1088,7 @@ class SettingExpressInterfaceService extends Service { 'sys_express_code', 'sender_name', 'sender_tel', 'weight', 'viewer', 'client_id', 'is_share', 'province_name', 'city_name', 'district_name', 'site_code', - 'product_type', 'weight_type', 'shop_name', 'address', 'town_name', 'ispickup', 'shipperno', 'template_url', 'ext_data', 'is_enabled', + 'product_type', 'goods_description', 'weight_type', 'shop_name', 'address', 'town_name', 'ispickup', 'shipperno', 'template_url', 'ext_data', 'is_enabled', ], order: [[ 'weight', 'ASC' ], [ 'id', 'DESC' ]], offset, @@ -1278,6 +1279,11 @@ class SettingExpressInterfaceService extends Service { town_name: this.normalizeOptionalText(data.town_name || data.townName, 'town_name', 255), site_code: this.normalizeOptionalText(data.site_code || data.siteCode, 'site_code', 255), product_type: this.normalizeOptionalText(data.product_type || data.productType, 'product_type', 50), + goods_description: this.normalizeOptionalText( + data.goods_description !== undefined ? data.goods_description : data.goodsDescription, + 'goods_description', + 255 + ), shop_name: this.normalizeOptionalText(data.shop_name || data.shopName, 'shop_name', 255), }; @@ -1361,6 +1367,8 @@ class SettingExpressInterfaceService extends Service { || Object.prototype.hasOwnProperty.call(data, 'siteCode'); const hasProductType = Object.prototype.hasOwnProperty.call(data, 'product_type') || Object.prototype.hasOwnProperty.call(data, 'productType'); + const hasGoodsDescription = Object.prototype.hasOwnProperty.call(data, 'goods_description') + || Object.prototype.hasOwnProperty.call(data, 'goodsDescription'); const hasShopName = Object.prototype.hasOwnProperty.call(data, 'shop_name') || Object.prototype.hasOwnProperty.call(data, 'shopName'); const hasExtData = Object.prototype.hasOwnProperty.call(data, 'ext_data') @@ -1374,7 +1382,7 @@ class SettingExpressInterfaceService extends Service { && !hasProviderType && !hasProviderId && !hasViewer && !hasClientId && !hasIsPickup && !hasShipperNo && !hasTemplateUrl && !hasProvinceName && !hasCityName && !hasDistrictName && !hasAddress && !hasTownName && !hasSiteCode - && !hasProductType && !hasShopName && !hasExtData && !hasIsEnabled) { + && !hasProductType && !hasGoodsDescription && !hasShopName && !hasExtData && !hasIsEnabled) { throw this.createError('至少需要提供一个可更新字段', 400); } @@ -1559,6 +1567,14 @@ class SettingExpressInterfaceService extends Service { updates.product_type = this.normalizeOptionalText(data.product_type || data.productType, 'product_type', 50); } + if (hasGoodsDescription) { + updates.goods_description = this.normalizeOptionalText( + data.goods_description !== undefined ? data.goods_description : data.goodsDescription, + 'goods_description', + 255 + ); + } + if (hasShopName) { updates.shop_name = this.normalizeOptionalText(data.shop_name || data.shopName, 'shop_name', 255); } diff --git a/database/migrations/20261118200000-add-goods-description-to-express-interface.js b/database/migrations/20261118200000-add-goods-description-to-express-interface.js new file mode 100644 index 0000000..fcfb978 --- /dev/null +++ b/database/migrations/20261118200000-add-goods-description-to-express-interface.js @@ -0,0 +1,61 @@ +'use strict'; + +/** + * wms_express_interface 增加 goods_description 列(物品描述)。 + * + * 背景:菜鸟等电子面单接口的 package_info.goods_description 需要按快递接口配置下发, + * 原先在代码内硬编码为「化妆品」。现改为读取接口配置,未配置时仍回退到「化妆品」。 + * + * 幂等:列存在性判断后再执行,重复运行安全。 + */ + +const TABLE_NAME = 'wms_express_interface'; +const COLUMN_NAME = 'goods_description'; + +module.exports = { + /** + * 执行迁移:新增 goods_description 列。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @param {Object} Sequelize Sequelize 类型集合。 + * @return {Promise} 无返回值。 + */ + async up(queryInterface, Sequelize) { + const { STRING } = Sequelize; + const log = []; + + const columns = await queryInterface.describeTable(TABLE_NAME); + if (!columns || Object.keys(columns).length === 0) { + throw new Error(`表 ${TABLE_NAME} 不存在,无法新增 ${COLUMN_NAME}`); + } + + if (!Object.prototype.hasOwnProperty.call(columns, COLUMN_NAME)) { + await queryInterface.addColumn(TABLE_NAME, COLUMN_NAME, { + type: STRING(255), + allowNull: true, + comment: '物品描述', + }); + log.push({ action: 'add-column', columnName: COLUMN_NAME }); + } else { + log.push({ action: 'skip-add-column', columnName: COLUMN_NAME, reason: 'exists' }); + } + + console.log('[20261118200000-add-goods-description-to-express-interface] up results:', JSON.stringify(log)); + }, + + /** + * 回滚迁移:移除 goods_description 列。 + * @param {import('sequelize').QueryInterface} queryInterface 查询接口。 + * @return {Promise} 无返回值。 + */ + async down(queryInterface) { + const log = []; + + const columns = await queryInterface.describeTable(TABLE_NAME); + if (Object.prototype.hasOwnProperty.call(columns, COLUMN_NAME)) { + await queryInterface.removeColumn(TABLE_NAME, COLUMN_NAME); + log.push({ action: 'drop-column', columnName: COLUMN_NAME }); + } + + console.log('[20261118200000-add-goods-description-to-express-interface] down results:', JSON.stringify(log)); + }, +}; diff --git a/methods/changes/system.json b/methods/changes/system.json index 557e3a9..d4d1745 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,203 @@ [ + { + "version": "0.3.373-express-interface-goods-description", + "date": "2026-11-18", + "type": "updated", + "summary": "???????? goods_description????????????? package_info.goods_description ????????????????????", + "methods": [ + "setting.expressInterface.create", + "setting.expressInterface.update", + "setting.expressInterface.list", + "setting.expressInterface.listByWarehousePlatformCode" + ], + "notes": [ + "????wms_express_interface ?? goods_description VARCHAR(255) NULL COMMENT '????'??? 20261118200000-add-goods-description-to-express-interface.js??????", + "???setting.expressInterface.create / update ?? goods_description??? goodsDescription???????? 255 ??????????????? 400?????????????", + "???setting.expressInterface.list / update / listByWarehousePlatformCode ?? goods_description ???", + "?????app/service/systems/express_platform.js ???? package_info.goods_description ?????????????????????????????" + ] + }, + { + "version": "0.3.372-b2b-order-images", + "date": "2026-11-18", + "type": "added", + "summary": "新增 order.updateB2bOrderImages:B2B 订单图片更新(wms_file_reference business_type=b2b_order),B2B 列表挂载 images", + "methods": [ + "order.updateB2bOrderImages", + "order.pendingOrder2b.list", + "order.deliveryOrder2b.list" + ], + "notes": [ + "新接口:单订单全量覆盖更新 B2B 订单图片,入参 images 支持 { file_id, display_order } 或直接 file_id(兼容 file_ids/fileIds),传空数组清空;单订单最多 20 张,重复 file_id 去重,display_order 缺省按顺序补 0 起序号。", + "落库口径:wms_file_reference.business_type=b2b_order、business_id=订单ID字符串、warehouse_id=当前仓库、display_order 控制顺序、created_by=操作人姓名;文件本体复用 wms_file,不做物理删除。business_type 常量集中登记在 app/lib/file_business_types.js(stock / stock_check_record / receivingItem / b2b_order)。", + "校验:仅 B2B 订单(is_b2b=Y)且未取消;订单 current 优先、dispatch 兜底;文件必须属于当前仓库且未删除(B2B_IMAGE_FILE_INVALID);错误码前缀 B2B_IMAGE_ 由方法层统一转 failure 400。", + "事务:关联 diff(删除/新增/更新顺序)在同一事务内完成,失败整体回滚。", + "列表联动:order.pendingOrder2b.list / order.deliveryOrder2b.list 每行新增 images: [{ id, url, display_order }],按页一次性批量查询(FileReference include File),查询失败降级为空数组、不影响列表主流程。", + "操作日志:ORDER_B2B_IMAGES(「更新B2B订单图片」,已在 app/dict/businessDict.js 登记),extras 带 image_count / added_file_ids / removed_file_ids。" + ] + }, + { + "version": "0.3.371-b2b-prep-drop-claim-guard", + "date": "2026-11-18", + "type": "updated", + "summary": "order.startB2bPrep 新增作业前置条件:未打印、未分配储位、已拦截的订单不允许开始备货(领料不参与校验)", + "methods": [ + "order.startB2bPrep" + ], + "notes": [ + "前置条件:intercept_status=none(未拦截)→ print_status=fin(已打印)→ storage_status=fin(已分配储位),任一不满足即 failure 400(错误码 B2B_PREP_NOT_READY)且不写入 wms_order_b2b、不写操作日志;data 回带 order_id / print_status / storage_status / intercept_status。", + "领料(claim_status)不作为前置条件:领料仅由 pick.waveClaimScan 整波领单写入(要求订单 wave_id>0 且波次 source=0),B2B 订单已被强制排除在波次抓取之外、没有波次,claim_status 恒为 none,若把已领料列为前置条件会让所有 B2B 订单永久无法开始备货。", + "已分配储位与已打印对 B2B 均可达:储位分配走 orderStorageAllocation.allocatePicking(订单级,不依赖波次、未排除 is_b2b),打印/手工运单号录入同样按订单维度、不依赖波次。", + "幂等口径不变:同工号重复开始仍幂等成功,但同样先执行前置条件校验(备货中订单若被取消分配储位或改为拦截,重复开始会失败)。", + "实现:app/service/systems/order/order_b2b.js 中 assertPrepStartReady 新增(实际路径 app/service/systems/order_b2b.js),loadPrepTargets 增加查询 print_status/storage_status/intercept_status,由 startOrdersB2bPrep 在「已完成/其他工号」校验之后、幂等分支之前调用;cancelB2bPrep / finishB2bPrep / pickupB2b 不受影响。" + ] + }, + { + "version": "0.3.369-b2b-op-guard", + "date": "2026-11-18", + "type": "updated", + "summary": "反审回待审核、抓取散单、批量发货、克隆订单对 B2B 订单不再生效:命中 B2B 订单整批驳回并返回不生效提示", + "methods": [ + "order.pendingOrder.reverseReviewOrder", + "order.pendingOrder.cloneOrder", + "order.wave.singleFetchByIds", + "order.recheckOrder.batchQuickRecheck", + "order.recheckOrder.batchQuickRecheckByWave" + ], + "notes": [ + "口径:B2B 订单(wms_order_delivery.is_b2b=Y,NULL 存量行视为非 B2B)走备货/提货独立作业链路,不参与反审回待审核、抓取散单(按订单抓散单)、批量发货(快捷复核,含按波次)、克隆订单。", + "驳回方式:入参/波次内命中任意 B2B 订单即整批驳回(与既有「锁单/拦截」部分跳过口径不同,不做部分处理),错误文案「B2B 订单不支持{操作}(订单[ID...]),操作不生效」,最多展示前 10 个订单 ID。", + "order.pendingOrder.reverseReviewOrder:在运单号校验前先做 B2B 校验,命中时不改动 inspection_status/step/wave 关联。", + "order.pendingOrder.cloneOrder:在可取消状态校验前做 B2B 校验,命中时不取消原单、不释放库存、不创建新单。", + "order.wave.singleFetchByIds:原先的「排除 B2B 订单并返回 excluded_b2b_order_ids」改为整批驳回,响应移除 excluded_b2b_order_ids 字段(波次内不写入任何 B2B 订单)。", + "order.recheckOrder.batchQuickRecheck / batchQuickRecheckByWave:批次内命中 B2B 订单直接抛错,不产生 success/failed 明细(SN 订单的原先部分失败口径不变)。", + "实现:app/service/systemMethods/order/base.js#assertOrdersNotB2b 统一校验(isB2bOrderRow 判定 is_b2b=Y),由 pendingOrder.js#reverseReviewOrder / #cloneOrder、wave.js#singleFetchByIds、recheckOrder.js#batchQuickRecheck / #batchQuickRecheckByWave 调用。" + ] + }, + { + "version": "0.3.368", + "date": "2026-11-17", + "type": "updated", + "summary": "order.finishB2bPrep 备货完成同步扣减库存,口径与拣货完成一致", + "methods": [ + "order.finishB2bPrep" + ], + "notes": [ + "变更:备货完成(order.finishB2bPrep)在同一事务内同步执行库存出库,处理逻辑与拣货完成(systems/pick.js#wavePickTaskComplete、systemMethods/order/recheckOrder.js#_completePickForOrder)保持一致。", + "扣减明细:按 wms_picking(order_id + warehouse_id + status=pending + deleted_at IS NULL,FOR UPDATE)汇总各 storage_id 数量 → 校验 wms_storage.locked_quantity 足够 → 同时扣减 locked_quantity 与 quantity → 写入 wms_storage_transaction(transaction_type=OUTBOUND、order_type=PICK_OUTBOUND、order_id=订单ID、remark=备货完成出库(B2B))→ wms_picking 置 fin。", + "失败语义:任一 storage 锁定数量不足时整单失败(failure 400,data 带 storage_id/locked_quantity/deduction_quantity),备货完成不落库、库存不变。", + "无 pending 拣货记录的订单(未走拣货流程或已扣减过)不做库存变更,备货仍正常完成,响应 stock_deducted_* 为空/0。", + "响应新增 stock_deducted_storage_ids、stock_deducted_quantity 两个字段。", + "实现位置:app/service/systems/order_b2b.js#completeB2bPrepStockOutbound(新抽取的库存扣减方法),由 #finishOrdersB2bPrep 在事务内调用。", + "未改动订单主表 pick_status:备货完成只影响副表与库存,避免干扰拣货/复核状态机。" + ] + }, + { + "version": "0.3.367", + "date": "2026-11-17", + "type": "added", + "summary": "新增 order.pickupB2b:B2B 订单提货并记录提货时间(单订单)", + "methods": [ + "order.pickupB2b" + ], + "notes": [ + "新接口:传入单个订单ID,把 wms_order_b2b.is_picked_up 置 Y、picked_up_at 置提交时刻,记录提货时间。", + "校验:仅 B2B 订单(is_b2b=Y)、非已取消;要求备货已完成(prep_status=fin),否则 failure 400「订单未备货完成,不允许提货」;已提货幂等(already_picked_up=true,保留首次提货时间、不重复写日志)。", + "单订单口径:只接受 1 个订单ID,同备货三接口一致(方法层 app/service/systemMethods/order/index.js#runB2bSingleOrderAction 与业务层 normalizeB2bOrderIds 双层拦截)。", + "实现位置:app/service/systems/order_b2b.js#pickupOrdersB2b,出口 app/service/systemMethods/order/index.js#pickupB2b;操作码 ORDER_B2B_PICKUP 已在 app/dict/businessDict.js 登记为「B2B提货」。", + "列表联动:order.pendingOrder2b.list / order.deliveryOrder2b.list 已输出 is_picked_up、picked_up_at 并支持 where.is_picked_up 筛选,提货后立即反映。" + ] + }, + { + "version": "0.3.366", + "date": "2026-11-17", + "type": "updated", + "summary": "B2B 备货三接口改为单订单作业,禁止批量提交", + "methods": [ + "order.startB2bPrep", + "order.cancelB2bPrep", + "order.finishB2bPrep" + ], + "notes": [ + "变更:order.startB2bPrep / order.cancelB2bPrep / order.finishB2bPrep 由批量口径收紧为单订单作业,method 层(runB2bSingleOrderAction)与业务层(normalizeB2bOrderIds)双层拦截,传多个订单ID直接 failure 400「备货作业仅支持单个订单,请单条提交」,data.order_ids 返回传入的多个订单ID。", + "入参别名:ids / order_ids / orderIds / id / order_id / orderId 均支持单值或单元素数组,取值优先级同上。", + "原因:备货为逐个订单的实际作业,批量提交会出现部分成功难以追溯;批量场景由前端按订单循环调用。" + ] + }, + { + "version": "0.3.365", + "date": "2026-11-17", + "type": "added", + "summary": "新增 order.cancelB2bUrgent:批量取消 B2B 订单加急(仅 B2B 订单生效)", + "methods": [ + "order.cancelB2bUrgent" + ], + "notes": [ + "新接口:等价于 order.setB2bUrgent 传 is_urgent=N,内部强制把 is_urgent 覆盖为 N(调用方传 Y 也不会变成设置加急)。", + "跳过口径:非 B2B 与已取消订单跳过并在 skipped_reasons 返回原因,单次上限 200 单;current 未命中时兜底 dispatch 分表。", + "落库位置:wms_order_b2b.is_urgent 置 N,作业明细行缺失时补建;操作日志写 ORDER_B2B_SET_URGENT(说明「取消B2B订单加急」)。" + ] + }, + { + "version": "0.3.364", + "date": "2026-11-17", + "type": "added", + "summary": "新增 order.setB2bUrgent:批量设置 B2B 订单是否加急(仅 B2B 订单生效)", + "methods": [ + "order.setB2bUrgent" + ], + "notes": [ + "新接口:批量设置/取消 B2B 订单加急标记,写入 wms_order_b2b.is_urgent(不修改订单主表 is_urgency),关联条件 warehouse_id + order_id,作业明细行缺失时补建。", + "取值兼容:is_urgent 支持 Y/N、true/false、1/0、是/否,缺省 Y;非法取值直接报错。", + "跳过口径:非 B2B(is_b2b != Y)与已取消(status=cancel)订单跳过并在 skipped_reasons 返回原因,单次上限 200 单;current 未命中时兜底查询 dispatch 分表,两表都查不到计入 not_found_order_ids。", + "操作日志:每次设置写一条 ORDER_B2B_SET_URGENT(操作名称「设置B2B加急」)。列表联动:order.pendingOrder2b.list / order.deliveryOrder2b.list 的加急优先排序与 where.is_urgent 筛选立即生效。" + ] + }, + { + "version": "0.3.363", + "date": "2026-11-17", + "type": "added", + "summary": "新增 order.finishB2bPrep:B2B 订单备货完成,写入备注/总箱数/完成时间与用时", + "methods": [ + "order.finishB2bPrep" + ], + "notes": [ + "新接口:必传 prep_remark(备货备注)与 total_box_count(总箱数),写入 prep_remark、total_box_count、prep_at(提交时刻)与 prep_duration_seconds(提交时刻 - prep_start_at 秒数,缺失时按 0),prep_status 置 fin。", + "校验:仅 B2B 订单;prep_status 非 padding 返回「订单未处于备货中,不允许提交备货完成」;备货人工号与当前工号不一致返回「订单备货人为其他工号(xxx)」;备注为空或总箱数非正整数返回入参错误。", + "操作日志:每个订单写一条 ORDER_B2B_PREP_FINISH(操作名称「备货完成」)。", + "实现位置:app/service/systems/order_b2b.js#finishOrdersB2bPrep,出口 app/service/systemMethods/order/index.js#finishB2bPrep。" + ] + }, + { + "version": "0.3.362", + "date": "2026-11-17", + "type": "added", + "summary": "新增 order.cancelB2bPrep:取消 B2B 订单备货并重置备货人与时间", + "methods": [ + "order.cancelB2bPrep" + ], + "notes": [ + "新接口:把 wms_order_b2b.prep_status 重置为 none,清空 prep_operator_id / prep_operator_name / prep_start_at / prep_at,prep_duration_seconds 置 0;不清空 prep_remark 与 total_box_count。", + "校验:仅 B2B 订单;prep_status 非 padding 返回「订单未处于备货中,不允许取消备货」;备货人工号与当前工号不一致返回「订单备货人为其他工号(xxx)」。", + "操作日志:每个订单写一条 ORDER_B2B_PREP_CANCEL(操作名称「取消备货」)。", + "实现位置:app/service/systems/order_b2b.js#cancelOrdersB2bPrep,出口 app/service/systemMethods/order/index.js#cancelB2bPrep。" + ] + }, + { + "version": "0.3.361", + "date": "2026-11-17", + "type": "added", + "summary": "新增 order.startB2bPrep:B2B 订单备货开始并记录备货人工号与开始时间", + "methods": [ + "order.startB2bPrep" + ], + "notes": [ + "新接口:传入订单ID,把 wms_order_b2b.prep_status 置为 padding,写入 prep_operator_id(当前登录工号)、prep_operator_name 与 prep_start_at(服务端当前时间);作业明细行缺失时按默认值补建。", + "校验:仅 B2B 订单(is_b2b=Y,current 分表优先、dispatch 分表兜底),订单不存在或非 B2B 整单失败;prep_status=fin 返回「订单已备货完成,不允许重新开始备货」;已由其他工号开始返回「订单备货人为其他工号(xxx)」,同工号重复开始幂等成功(保留首次 prep_start_at)。", + "操作日志:每个订单写一条 ORDER_B2B_PREP_START(操作名称「备货开始」),事务提交后写入,失败仅告警。", + "实现位置:app/service/systems/order_b2b.js#startOrdersB2bPrep,出口 app/service/systemMethods/order/index.js#startB2bPrep。" + ] + }, { "version": "0.3.360", "date": "2026-11-15", diff --git a/methods/system.json b/methods/system.json index 5352bec..6f769b3 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.360", - "updatedAt": "2026-11-15", + "version": "0.3.372", + "updatedAt": "2026-11-18", "headers": [ { "name": "platform", @@ -3660,7 +3660,7 @@ "作业进度口径:pick_status=fin(拣货已完成)与 recheck_status=fin(复核已完成)均拒绝转换,避免把已分拣/已核对的订单改成 B2B;拣货中(pick_status=padding)与拣货异常(pick_status=error)目前不拦截,仅拦截已完成拣货。", "波次联动口径:已在波次中的订单(无论由团购/散单抓取还是库内抓取进入波次)转换成功后,在同一事务内执行摘除——订单 wave_id / wave_no / wave_scope / wave_strategy_version / wave_scan_result 清零,按波次重排 wms_order_wave_index(wave_index 重新连续编号),wms_wave_batch.total_orders 回写为剩余单数且 processed_orders 取不超过剩余值,剩余 0 单的波次置 wave_status=-1(作废)。", "拣货任务保护:若订单所在波次存在进行中的拣货任务(wms_wave_pick_task.status in (0,1)),该订单不转换、不摘除,返回原因「订单所在波次存在进行中的拣货任务,不允许转B2B」,涉及波次在 active_pick_task_wave_ids 返回;请走任务取消接口处理后再转。", - "落库行为:订单行 is_b2b 置 'Y'(同时刷新 updated_at);wms_order_b2b 以 (warehouse_id, order_id) 唯一键写入作业明细行,若已存在同仓同单行则重置作业字段(total_box_count=0、pickup_plate_number=null、prep_remark=null、prep_duration_seconds=0、prep_at=null、is_picked_up='N'、picked_up_at=null),created_at 保留首次创建时间。作业明细不再软删除(updated_at / deleted_at / is_print / store_id / delivery_order_code 字段已移除),取消 B2B 时物理删除该行。", + "落库行为:订单行 is_b2b 置 'Y'(同时刷新 updated_at);wms_order_b2b 以 (warehouse_id, order_id) 唯一键写入作业明细行,若已存在同仓同单行则重置作业字段(total_box_count=0、pickup_plate_number=null、prep_remark=null、prep_duration_seconds=0、prep_at=null、is_picked_up='N'、picked_up_at=null、is_urgent=订单 is_urgency 取值),created_at 保留首次创建时间。作业明细不再软删除(updated_at / deleted_at / is_print / store_id / delivery_order_code 字段已移除),取消 B2B 时物理删除该行。", "权限口径:该接口当前在 app/service/systemMethods/order/index.js 的 _noNeedRight / _noNeedLog / _noNeedAuth 名单内,即免接口权限校验、免接口访问日志、免仓库有效期校验,仅需登录。", "配套接口:order.cancelB2b(取消 B2B 出库,订单流转回正常订单);查询侧使用 order.pendingOrder2b.list / order.deliveryOrder2b.list。" ] @@ -3748,6 +3748,716 @@ "权限口径:该接口当前在 app/service/systemMethods/order/index.js 的 _noNeedRight / _noNeedLog / _noNeedAuth 名单内,即免接口权限校验、免接口访问日志、免仓库有效期校验,仅需登录。", "配套接口:order.convertToB2b(订单转 B2B);查询侧使用 order.pendingOrder2b.list / order.deliveryOrder2b.list(列表行带出作业明细字段)。" ] + }, + { + "method": "order.setB2bUrgent", + "description": "批量设置 B2B 订单是否加急(仅对 B2B 订单生效)。仓库取自当前登录上下文(ctx.user.store_id);订单先在 current 分表(wms_order_delivery_{warehouseId})查找,未命中的再兜底到 dispatch 分表(wms_order_delivery_{warehouseId}_dispatch,覆盖配送域 B2B 订单),两表都查不到的计入 not_found_order_ids。命中订单逐条校验:非 B2B 订单(is_b2b != 'Y')与已取消订单(status=cancel)跳过,原因通过 skipped_reasons 返回;其余订单在同一事务内按 warehouse_id + order_id 更新 wms_order_b2b.is_urgent(作业明细行缺失时补建),提交后写操作日志(ORDER_B2B_SET_URGENT,失败不影响主流程)。设置加急后 order.pendingOrder2b.list / order.deliveryOrder2b.list 的加急优先排序立即生效。单次最多 200 个订单。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "ids / order_ids / orderIds / id / order_id / orderId", + "type": "number[]", + "required": true, + "source": "body", + "description": "订单ID集合,单值或数组均可(内部统一转数组)。取值优先级:ids > order_ids > orderIds > id > order_id > orderId;仅保留正整数并去重,单次最多 200 个。" + }, + { + "name": "is_urgent / isUrgent / urgent", + "type": "string", + "required": false, + "source": "body", + "description": "是否加急,缺省 Y(即调用即设置加急)。支持 Y/N(大小写与首尾空格不敏感)、true/false、1/0、是/否;传 N/false/0 表示取消加急。取值非法时返回 400。" + } + ], + "response": [ + { + "name": "is_urgent", + "type": "string", + "required": true, + "description": "本次设置的加急标记(Y=加急 N=普通),与入参归一化结果一致" + }, + { + "name": "updated_order_ids", + "type": "number[]", + "required": true, + "description": "设置成功的订单 ID 列表(已去重)" + }, + { + "name": "updated_count", + "type": "number", + "required": true, + "description": "设置成功的订单数量" + }, + { + "name": "skipped_order_ids", + "type": "number[]", + "required": true, + "description": "命中订单但不满足条件被跳过的订单 ID 列表" + }, + { + "name": "skipped_count", + "type": "number", + "required": true, + "description": "被跳过的订单数量" + }, + { + "name": "skipped_reasons", + "type": "array", + "required": true, + "description": "跳过原因明细,每项 { order_id, delivery_order_code, reason };reason 取值:订单不是B2B订单 / 订单已取消,不允许设置加急" + }, + { + "name": "not_found_order_ids", + "type": "number[]", + "required": true, + "description": "current 与 dispatch 分表都查不到的订单 ID(不属于本仓、已归档/外仓或 ID 不存在)" + } + ], + "errors": [ + { + "code": "400", + "message": "订单ID不能为空(HTTP 仍为 200,响应体 flag=failure、code=400)" + }, + { + "code": "400", + "message": "单次最多设置 200 个订单(HTTP 仍为 200,响应体 flag=failure、code=400)" + }, + { + "code": "400", + "message": "is_urgent 参数不合法,仅支持 Y/N(或 true/false、1/0)(HTTP 仍为 200,响应体 flag=failure、code=400)" + }, + { + "code": "500", + "message": "未识别到当前仓库上下文,HTTP 500,message 为「接口错误: 未识别到当前仓库上下文」" + } + ], + "notes": [ + "生效范围(仅 B2B 订单):非 B2B 订单(is_b2b != 'Y')不设置并返回「订单不是B2B订单」;已取消订单返回「订单已取消,不允许设置加急」。拣货/复核/打印/锁定/拦截状态均不影响加急标记的设置。", + "落库位置:加急标记写在副表 wms_order_b2b.is_urgent(不修改订单主表 is_urgency),关联条件为 warehouse_id + order_id;作业明细行缺失时按默认值补建(total_box_count=0、prep_duration_seconds=0、is_picked_up='N' 等)。", + "与列表联动:设置后 order.pendingOrder2b.list / order.deliveryOrder2b.list 的「加急优先」排序与 where.is_urgent 筛选立即生效;列表行 is_urgent 字段同步反映最新值。", + "操作日志:每次设置写一条 ORDER_B2B_SET_URGENT 日志(操作名称「设置B2B加急」,说明「设置B2B订单加急」/「取消B2B订单加急」),失败仅告警不影响主流程。", + "权限口径:该接口当前在 app/service/systemMethods/order/index.js 的 _noNeedRight / _noNeedLog / _noNeedAuth 名单内(与 convertToB2b / cancelB2b 一致),即免接口权限校验、免接口访问日志、免仓库有效期校验,仅需登录。", + "配套接口:order.convertToB2b(转 B2B 时以订单 is_urgency 作为 is_urgent 初始值)、order.cancelB2b(取消 B2B,物理删除作业明细行)。" + ] + }, + { + "method": "order.cancelB2bUrgent", + "description": "取消 B2B 订单加急(仅对 B2B 订单生效)。等价于 order.setB2bUrgent 传 is_urgent='N',本接口内部强制把 is_urgent 覆盖为 N(调用方即使传 Y 也不会变成设置加急)。仓库取自当前登录上下文(ctx.user.store_id);订单先在 current 分表(wms_order_delivery_{warehouseId})查找,未命中的再兜底到 dispatch 分表(wms_order_delivery_{warehouseId}_dispatch),两表都查不到的计入 not_found_order_ids。命中订单逐条校验:非 B2B 订单(is_b2b != 'Y')与已取消订单(status=cancel)跳过,原因通过 skipped_reasons 返回;其余订单在同一事务内按 warehouse_id + order_id 把 wms_order_b2b.is_urgent 置为 'N'(作业明细行缺失时按默认值补建),提交后写操作日志(ORDER_B2B_SET_URGENT,说明「取消B2B订单加急」,失败不影响主流程)。取消后两个 B2B 列表的加急优先排序立即把该订单排回普通队列。单次最多 200 个订单。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "ids / order_ids / orderIds / id / order_id / orderId", + "type": "number[]", + "required": true, + "source": "body", + "description": "订单ID集合,单值或数组均可(内部统一转数组)。取值优先级:ids > order_ids > orderIds > id > order_id > orderId;仅保留正整数并去重,单次最多 200 个。本接口不需要传 is_urgent。" + } + ], + "response": [ + { + "name": "is_urgent", + "type": "string", + "required": true, + "description": "本次设置的加急标记,固定为 N" + }, + { + "name": "updated_order_ids", + "type": "number[]", + "required": true, + "description": "取消加急成功的订单 ID 列表(已去重)" + }, + { + "name": "updated_count", + "type": "number", + "required": true, + "description": "取消加急成功的订单数量" + }, + { + "name": "skipped_order_ids", + "type": "number[]", + "required": true, + "description": "命中订单但不满足条件被跳过的订单 ID 列表" + }, + { + "name": "skipped_count", + "type": "number", + "required": true, + "description": "被跳过的订单数量" + }, + { + "name": "skipped_reasons", + "type": "array", + "required": true, + "description": "跳过原因明细,每项 { order_id, delivery_order_code, reason };reason 取值:订单不是B2B订单 / 订单已取消,不允许设置加急" + }, + { + "name": "not_found_order_ids", + "type": "number[]", + "required": true, + "description": "current 与 dispatch 分表都查不到的订单 ID(不属于本仓、已归档/外仓或 ID 不存在)" + } + ], + "errors": [ + { + "code": "400", + "message": "订单ID不能为空(HTTP 仍为 200,响应体 flag=failure、code=400)" + }, + { + "code": "400", + "message": "单次最多设置 200 个订单(HTTP 仍为 200,响应体 flag=failure、code=400)" + }, + { + "code": "500", + "message": "未识别到当前仓库上下文,HTTP 500,message 为「接口错误: 未识别到当前仓库上下文」" + } + ], + "notes": [ + "生效范围(仅 B2B 订单):非 B2B 订单(is_b2b != 'Y')不处理并返回「订单不是B2B订单」;已取消订单返回「订单已取消,不允许设置加急」。拣货/复核/打印/锁定/拦截状态均不影响取消加急。", + "入参口径:本接口不接受 is_urgent,内部固定按 N 处理;如需设置或取消加急二合一,使用 order.setB2bUrgent(is_urgent 缺省 Y,传 N 即取消)。", + "落库位置:副表 wms_order_b2b.is_urgent 置为 'N',关联条件为 warehouse_id + order_id;不修改订单主表 is_urgency;作业明细行缺失时按默认值补建。", + "与列表联动:取消后 order.pendingOrder2b.list / order.deliveryOrder2b.list 的加急优先排序立即把该订单排回普通队列,列表行 is_urgent 同步为 N。", + "操作日志:写一条 ORDER_B2B_SET_URGENT 日志(操作名称「设置B2B加急」,说明「取消B2B订单加急」),失败仅告警不影响主流程。", + "权限口径:该接口当前在 app/service/systemMethods/order/index.js 的 _noNeedRight / _noNeedLog / _noNeedAuth 名单内(与 convertToB2b / cancelB2b / setB2bUrgent 一致),即免接口权限校验、免接口访问日志、免仓库有效期校验,仅需登录。", + "配套接口:order.setB2bUrgent(设置/取消加急)、order.convertToB2b、order.cancelB2b。" + ] + }, + { + "method": "order.startB2bPrep", + "description": "备货开始(仅 B2B 订单)。只需传订单 ID,操作人取当前登录工号作为备货人:写入 wms_order_b2b 的 prep_operator_id(工号)、prep_operator_name、prep_start_at(开始时间),并把 prep_status 置为 padding。作业前置条件:订单必须已打印(print_status=fin)、已分配储位(storage_status=fin)且未被拦截(intercept_status=none),任一不满足直接失败且不写入任何备货数据;领料(claim_status)不参与校验——领料只在波次整波领单流程产生,B2B 订单不参与波次、无领料环节。同工号对同一订单重复调用幂等成功且保留首次开始时间;订单已由其他工号开始(prep_operator_id 与当前工号不一致)返回失败;订单已备货完成(prep_status=fin)不允许重新开始。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "ids / order_ids / orderIds / id / order_id / orderId", + "type": "number", + "required": true, + "source": "body", + "description": "订单ID(备货为单订单作业,仅允许传 1 个;支持单值或单元素数组)。取值优先级:ids > order_ids > orderIds > id > order_id > orderId;传多个订单ID返回 failure 400「备货作业仅支持单个订单,请单条提交」。" + } + ], + "response": [ + { + "name": "prep_status", + "type": "string", + "required": true, + "description": "备货状态,固定为 padding" + }, + { + "name": "prep_operator_id", + "type": "number", + "required": true, + "description": "本次备货人工号ID" + }, + { + "name": "prep_operator_name", + "type": "string", + "required": false, + "description": "备货人姓名" + }, + { + "name": "started_order_ids", + "type": "number[]", + "required": true, + "description": "备货开始成功的订单 ID 列表(含幂等命中)" + }, + { + "name": "started_count", + "type": "number", + "required": true, + "description": "备货开始成功的订单数量" + }, + { + "name": "idempotent_order_ids", + "type": "number[]", + "required": true, + "description": "同工号重复开始、未重置开始时间的订单 ID 列表" + } + ], + "errors": [ + { + "code": "400", + "message": "订单ID不能为空(HTTP 仍为 200,响应体 flag=failure、code=400)" + }, + { + "code": "400", + "message": "订单不是B2B订单 / 订单不存在(响应体 flag=failure、code=400,data 带 not_b2b_order_ids 或 not_found_order_ids)" + }, + { + "code": "400", + "message": "作业前置条件不满足:订单未打印 / 未分配储位 / 已拦截,返回「订单{原因},不允许开始备货:{订单ID}」(响应体 flag=failure、code=400,data 带 order_id / print_status / storage_status / intercept_status)" + }, + { + "code": "400", + "message": "操作人工号不匹配或状态不允许(响应体 flag=failure、code=400,data 带 order_id / prep_operator_id / operator_id / prep_status)" + }, + { + "code": "500", + "message": "未识别到当前仓库上下文,HTTP 500,message 为「接口错误: 未识别到当前仓库上下文」" + }, + { + "code": "400", + "message": "备货作业仅支持单个订单,请单条提交(HTTP 仍为 200,响应体 flag=failure、code=400,data.order_ids 返回传入的多个订单ID)" + } + ], + "notes": [ + "单订单口径:备货为逐个订单作业,接口只接受 1 个订单ID,传多个(含数组长度>1)直接返回 failure 400,不做部分处理;批量备货请由前端按订单循环调用。", + "生效范围(仅 B2B 订单):所有目标订单必须存在于当前仓库(current 分表优先、dispatch 分表兜底)且 is_b2b='Y',任一订单不满足则整个请求失败且不写入任何数据(全部为响应体 flag=failure、code=400)。", + "操作人身份:取当前登录工号(ctx.user.employees_id 作为工号ID、employees_name 作为姓名),不接受前端传入;工号缺失时返回 failure 400「未识别到操作人工号」。", + "状态校验:prep_status=fin(已备货完成)返回「订单已备货完成,不允许重新开始备货」;prep_status=padding 且备货人为其他工号返回「订单备货人为其他工号(xxx),当前工号(yyy)不允许开始备货」;同工号重复开始幂等成功(idempotent_order_ids 返回,不覆盖 prep_start_at)。", + "落库位置:wms_order_b2b 按 warehouse_id + order_id;作业明细行缺失时按默认值补建(total_box_count=0、prep_duration_seconds=0、is_picked_up='N' 等)。", + "操作日志:每个订单写一条 ORDER_B2B_PREP_START(操作名称「备货开始」),提交后写入,失败仅告警不影响主流程。", + "配套接口:order.cancelB2bPrep(取消备货,重置备货人与开始时间)、order.finishB2bPrep(备货完成,写备注/总箱数/完成时间)。", + "作业前置条件(任一不满足即失败且不写入任何备货记录、不写操作日志):已打印 print_status=fin、已分配储位 storage_status=fin、未被拦截 intercept_status=none(拦截口径与 intercept_guard 一致:非 none 即视为已拦截,含 requested/intercepting/intercepted_* 等)。校验顺序:已拦截 → 未打印 → 未分配储位;同工号幂等重复开始同样执行该校验。", + "领料(claim_status)不作为前置条件:领料仅由「整波领料」写入(订单需在普通波次内,wave_id>0 且波次 source=0),B2B 订单不参与波次抓取、没有波次,claim_status 恒为 none,若要求已领料会永久阻断 B2B 备货。", + "校验失败文案:「订单已拦截,不允许开始备货:{订单ID}」/「订单未打印,不允许开始备货:{订单ID}」/「订单未分配储位,不允许开始备货:{订单ID}」;错误码 B2B_PREP_NOT_READY,data 回带 order_id / print_status / storage_status / intercept_status 便于前端定位。" + ] + }, + { + "method": "order.cancelB2bPrep", + "description": "取消备货(仅 B2B 订单)。将备货状态重置为 none,并清空 prep_operator_id / prep_operator_name / prep_start_at / prep_at,prep_duration_seconds 置 0。仅 prep_status=padding(备货中)的订单可取消,且必须由记录在案的同一工号操作:备货人与当前工号不一致返回失败。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "ids / order_ids / orderIds / id / order_id / orderId", + "type": "number", + "required": true, + "source": "body", + "description": "订单ID(备货为单订单作业,仅允许传 1 个;支持单值或单元素数组)。取值优先级:ids > order_ids > orderIds > id > order_id > orderId;传多个订单ID返回 failure 400「备货作业仅支持单个订单,请单条提交」。" + } + ], + "response": [ + { + "name": "prep_status", + "type": "string", + "required": true, + "description": "重置后的备货状态,固定为 none" + }, + { + "name": "canceled_order_ids", + "type": "number[]", + "required": true, + "description": "取消备货成功的订单 ID 列表" + }, + { + "name": "canceled_count", + "type": "number", + "required": true, + "description": "取消备货成功的订单数量" + } + ], + "errors": [ + { + "code": "400", + "message": "订单ID不能为空(HTTP 仍为 200,响应体 flag=failure、code=400)" + }, + { + "code": "400", + "message": "订单不是B2B订单 / 订单不存在(响应体 flag=failure、code=400,data 带 not_b2b_order_ids 或 not_found_order_ids)" + }, + { + "code": "400", + "message": "操作人工号不匹配或状态不允许(响应体 flag=failure、code=400,data 带 order_id / prep_operator_id / operator_id / prep_status)" + }, + { + "code": "500", + "message": "未识别到当前仓库上下文,HTTP 500,message 为「接口错误: 未识别到当前仓库上下文」" + }, + { + "code": "400", + "message": "备货作业仅支持单个订单,请单条提交(HTTP 仍为 200,响应体 flag=failure、code=400,data.order_ids 返回传入的多个订单ID)" + } + ], + "notes": [ + "单订单口径:备货为逐个订单作业,接口只接受 1 个订单ID,传多个(含数组长度>1)直接返回 failure 400,不做部分处理;批量备货请由前端按订单循环调用。", + "生效范围(仅 B2B 订单):所有目标订单必须存在于当前仓库(current 分表优先、dispatch 分表兜底)且 is_b2b='Y',任一订单不满足则整个请求失败且不写入任何数据(全部为响应体 flag=failure、code=400)。", + "操作人身份:取当前登录工号(ctx.user.employees_id 作为工号ID、employees_name 作为姓名),不接受前端传入;工号缺失时返回 failure 400「未识别到操作人工号」。", + "状态校验:prep_status 非 padding(未开始或已完成)返回「订单未处于备货中,不允许取消备货」;备货人工号与当前工号不一致返回「订单备货人为其他工号(xxx),当前工号(yyy)不允许取消备货」。", + "重置范围:prep_status=none、prep_operator_id=null、prep_operator_name=null、prep_start_at=null、prep_at=null、prep_duration_seconds=0;不清空 prep_remark 与 total_box_count(备货完成才会写入,取消仅针对备货中)。", + "操作日志:每个订单写一条 ORDER_B2B_PREP_CANCEL(操作名称「取消备货」),提交后写入,失败仅告警。", + "配套接口:order.startB2bPrep(重新开始备货)、order.finishB2bPrep。" + ] + }, + { + "method": "order.finishB2bPrep", + "description": "备货完成(仅 B2B 订单)。必传备货备注(prep_remark)与总箱数(total_box_count),写入 wms_order_b2b 的 prep_remark、total_box_count、prep_at(取提交时刻,即备货完成时间)与 prep_duration_seconds(提交时刻 - prep_start_at 的秒数),并把 prep_status 置为 fin。仅 prep_status=padding 的订单可提交,且必须由记录在案的同一工号(备货人)提交:工号不一致返回失败。备货完成时同步扣减库存,口径与拣货完成(order.wave/pick 完成链路)一致:按订单的 pending 拣货记录汇总扣减 wms_storage 的锁定数量与可用数量,并写入 wms_storage_transaction 出库流水(OUTBOUND / PICK_OUTBOUND),同时把 wms_picking 记录置为 fin,避免后续拣货/复核重复扣减。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "ids / order_ids / orderIds / id / order_id / orderId", + "type": "number", + "required": true, + "source": "body", + "description": "订单ID(备货为单订单作业,仅允许传 1 个;支持单值或单元素数组)。取值优先级:ids > order_ids > orderIds > id > order_id > orderId;传多个订单ID返回 failure 400「备货作业仅支持单个订单,请单条提交」。" + }, + { + "name": "prep_remark / prepRemark", + "type": "string", + "required": true, + "source": "body", + "description": "备货备注,必填,最长 500 字符" + }, + { + "name": "total_box_count / totalBoxCount", + "type": "number", + "required": true, + "source": "body", + "description": "总箱数,必填,大于等于 0 的整数" + } + ], + "response": [ + { + "name": "prep_status", + "type": "string", + "required": true, + "description": "备货状态,固定为 fin" + }, + { + "name": "prep_remark", + "type": "string", + "required": true, + "description": "本次写入的备货备注" + }, + { + "name": "total_box_count", + "type": "number", + "required": true, + "description": "本次写入的总箱数" + }, + { + "name": "prep_at", + "type": "string", + "required": true, + "description": "备货完成时间(提交时刻)" + }, + { + "name": "prep_duration_seconds", + "type": "number", + "required": true, + "description": "备货用时(秒)= 提交时刻 - 备货开始时间" + }, + { + "name": "finished_order_ids", + "type": "number[]", + "required": true, + "description": "备货完成成功的订单 ID 列表" + }, + { + "name": "finished_count", + "type": "number", + "required": true, + "description": "备货完成成功的订单数量" + }, + { + "name": "stock_deducted_storage_ids", + "type": "number[]", + "required": true, + "description": "本次扣减的库存记录(wms_storage.id)列表;无扣减时为空数组" + }, + { + "name": "stock_deducted_quantity", + "type": "number", + "required": true, + "description": "本次扣减的库存总量合计;无扣减时为 0" + } + ], + "errors": [ + { + "code": "400", + "message": "订单ID不能为空(HTTP 仍为 200,响应体 flag=failure、code=400)" + }, + { + "code": "400", + "message": "订单不是B2B订单 / 订单不存在(响应体 flag=failure、code=400,data 带 not_b2b_order_ids 或 not_found_order_ids)" + }, + { + "code": "400", + "message": "操作人工号不匹配或状态不允许(响应体 flag=failure、code=400,data 带 order_id / prep_operator_id / operator_id / prep_status)" + }, + { + "code": "500", + "message": "未识别到当前仓库上下文,HTTP 500,message 为「接口错误: 未识别到当前仓库上下文」" + }, + { + "code": "400", + "message": "备货备注不能为空 / 备货备注不能超过 500 个字符 / 总箱数必须为大于等于 0 的整数(响应体 flag=failure、code=400)" + }, + { + "code": "400", + "message": "备货作业仅支持单个订单,请单条提交(HTTP 仍为 200,响应体 flag=failure、code=400,data.order_ids 返回传入的多个订单ID)" + }, + { + "code": "400", + "message": "库存记录 X 锁定数量不足:当前锁定 N,需扣减 M(响应体 flag=failure、code=400,data 带 storage_id / locked_quantity / deduction_quantity;整单回滚,备货不完成)" + } + ], + "notes": [ + "单订单口径:备货为逐个订单作业,接口只接受 1 个订单ID,传多个(含数组长度>1)直接返回 failure 400,不做部分处理;批量备货请由前端按订单循环调用。", + "生效范围(仅 B2B 订单):所有目标订单必须存在于当前仓库(current 分表优先、dispatch 分表兜底)且 is_b2b='Y',任一订单不满足则整个请求失败且不写入任何数据(全部为响应体 flag=failure、code=400)。", + "操作人身份:取当前登录工号(ctx.user.employees_id 作为工号ID、employees_name 作为姓名),不接受前端传入;工号缺失时返回 failure 400「未识别到操作人工号」。", + "状态校验:prep_status 非 padding(未开始或已完成)返回「订单未处于备货中,不允许提交备货完成」;备货人工号与当前工号不一致返回「订单备货人为其他工号(xxx),当前工号(yyy)不允许提交备货完成」。", + "时间口径:prep_at 取服务端提交时刻;prep_duration_seconds = max(0, round((prep_at - prep_start_at)/1000)),prep_start_at 缺失时沿用原值(通常为 0)。", + "操作日志:每个订单写一条 ORDER_B2B_PREP_FINISH(操作名称「备货完成」),提交后写入,失败仅告警。", + "配套接口:order.startB2bPrep / order.cancelB2bPrep;列表侧 order.pendingOrder2b.list、order.deliveryOrder2b.list 输出 prep_status / prep_operator_id / prep_operator_name / prep_start_at 等字段并支持筛选。", + "库存扣减口径(与拣货完成一致):备货完成在同一事务内按 wms_picking(order_id + warehouse_id + status=pending + 未删除,FOR UPDATE)汇总各 storage_id 数量 → 校验 wms_storage.locked_quantity 足够(不足直接失败回滚)→ 同时扣减 locked_quantity 与 quantity → 写入 wms_storage_transaction(transaction_type=OUTBOUND、order_type=PICK_OUTBOUND、order_id=订单ID、operator 为当前工号、remark=备货完成出库(B2B))→ 把 wms_picking 置 fin。订单无 pending 拣货记录时(未走拣货流程或已扣减过)不做任何库存变更,备货仍正常完成。" + ] + }, + { + "method": "order.pickupB2b", + "description": "B2B 提货(仅 B2B 订单,单订单作业)。传入单个订单ID,记录提货时间:把 wms_order_b2b.is_picked_up 置为 'Y'、picked_up_at 置为提交时刻(即提货时间)。要求订单为 B2B(is_b2b=Y)、未取消,且备货已完成(prep_status=fin);已提货订单重复调用幂等成功并返回首次提货时间。订单先在 current 分表查找,未命中兜底 dispatch 分表。提货时间写入后,order.pendingOrder2b.list / order.deliveryOrder2b.list 的 is_picked_up、picked_up_at 字段立即反映。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "ids / order_ids / orderIds / id / order_id / orderId", + "type": "number", + "required": true, + "source": "body", + "description": "订单ID(单订单作业,仅允许传 1 个;支持单值或单元素数组)。取值优先级:ids > order_ids > orderIds > id > order_id > orderId;传多个订单ID返回 failure 400「提货仅支持单个订单,请单条提交」。" + } + ], + "response": [ + { + "name": "is_picked_up", + "type": "string", + "required": true, + "description": "是否已提货,固定为 Y" + }, + { + "name": "picked_up_at", + "type": "string", + "required": true, + "description": "提货时间:本次写入时为提交时刻;已提货幂等命中时为首次提货时间" + }, + { + "name": "picked_up_order_ids", + "type": "number[]", + "required": true, + "description": "提货订单ID(恒为单元素数组)" + }, + { + "name": "picked_up_count", + "type": "number", + "required": true, + "description": "提货订单数量,固定为 1" + }, + { + "name": "already_picked_up", + "type": "boolean", + "required": true, + "description": "是否为重复提货(true=已提货幂等命中,未改写提货时间与操作日志;false=本次首次提货)" + } + ], + "errors": [ + { + "code": "400", + "message": "订单ID不能为空(HTTP 仍为 200,响应体 flag=failure、code=400)" + }, + { + "code": "400", + "message": "提货仅支持单个订单,请单条提交(响应体 flag=failure、code=400,data.order_ids 返回传入的多个订单ID)" + }, + { + "code": "400", + "message": "仅 B2B 订单支持提货 / 订单不存在(响应体 flag=failure、code=400,data 带 not_b2b_order_ids 或 not_found_order_ids)" + }, + { + "code": "400", + "message": "订单未备货完成,不允许提货 / 订单已取消,不允许提货(响应体 flag=failure、code=400,data 带 order_id 与 prep_status/status)" + }, + { + "code": "500", + "message": "未识别到当前仓库上下文,HTTP 500,message 为「接口错误: 未识别到当前仓库上下文」" + } + ], + "notes": [ + "生效范围(仅 B2B 订单):订单必须存在于当前仓库(current 分表优先、dispatch 分表兜底)且 is_b2b='Y',否则返回 failure 400。", + "前置条件:备货已完成(prep_status='fin'),作业明细行缺失或备货未完成时返回「订单未备货完成,不允许提货」;已取消订单(status=cancel)返回「订单已取消,不允许提货」。", + "时间口径:picked_up_at 取服务端提交时刻;重复提货幂等,already_picked_up=true 且不再改写时间、不写操作日志。", + "落库位置:wms_order_b2b 按 warehouse_id + order_id 更新 is_picked_up、picked_up_at;不改订单主表状态。", + "操作日志:首次提货写一条 ORDER_B2B_PICKUP(操作名称「B2B提货」,说明「B2B订单提货」),提交后写入,失败仅告警。", + "单订单口径:只接受 1 个订单ID,传多个直接 failure 400,不做部分处理;批量提货请由前端按订单循环调用。", + "配套接口:order.startB2bPrep / order.cancelB2bPrep / order.finishB2bPrep(备货作业),order.setB2bUrgent / order.cancelB2bUrgent(加急)。" + ] + }, + { + "method": "order.updateB2bOrderImages", + "description": "更新 B2B 订单图片(单订单,全量覆盖)。图片关系统一落在 wms_file_reference:business_type 固定为 b2b_order、business_id 为订单ID(字符串)、warehouse_id 为当前登录仓库、display_order 控制展示顺序,文件本体复用 wms_file(不做物理删除)。传入 images 为全量覆盖语义:未包含的旧关联会被删除、新关联按列表顺序写入,传空数组表示清空该订单图片;仅 B2B 订单(is_b2b=Y)且未取消的订单可更新,订单在 current 分表优先、dispatch 分表兜底查找,文件必须属于当前仓库且未删除。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "ids / order_ids / orderIds / id / order_id / orderId", + "type": "number", + "required": true, + "source": "body", + "description": "订单ID(单订单作业,仅允许传 1 个;支持单值或单元素数组)。取值优先级:ids > order_ids > orderIds > id > order_id > orderId;传多个订单ID返回 failure 400「更新订单图片仅支持单个订单,请单条提交」。" + }, + { + "name": "images", + "type": "array|array", + "required": true, + "source": "body", + "description": "图片列表(全量覆盖;传 [] 清空)。元素支持 { file_id, display_order } 或直接传 file_id;兼容 file_ids / fileIds 简写(等价于只传 file_id 数组);file_id 必须为正整数且属于当前仓库未删除文件,display_order 缺省按去重后下标补 0 起序号,重复 file_id 自动去重(保留首次出现顺序),单订单最多 20 张。" + } + ], + "response": [ + { + "name": "order_id", + "type": "number", + "required": true, + "description": "订单ID" + }, + { + "name": "delivery_order_code", + "type": "string", + "required": true, + "description": "发货单号" + }, + { + "name": "image_count", + "type": "number", + "required": true, + "description": "更新后的图片数量" + }, + { + "name": "images", + "type": "array", + "required": true, + "description": "更新后的图片列表(按 display_order、id 升序)", + "children": [ + { + "name": "file_id", + "type": "number", + "description": "文件ID(wms_file.id)" + }, + { + "name": "url", + "type": "string", + "description": "文件访问地址(wms_file.file_url),文件缺失时为 null" + }, + { + "name": "display_order", + "type": "number", + "description": "展示顺序" + } + ] + }, + { + "name": "added_file_ids", + "type": "array", + "required": true, + "description": "本次新增的文件ID列表(按入参顺序)" + }, + { + "name": "removed_file_ids", + "type": "array", + "required": true, + "description": "本次移除的文件ID列表" + } + ], + "errors": [ + { + "code": "400", + "message": "订单ID不能为空(响应体 flag=failure、code=400)" + }, + { + "code": "400", + "message": "更新订单图片仅支持单个订单,请单条提交(响应体 flag=failure、code=400,data.order_ids 返回传入的多个订单ID)" + }, + { + "code": "400", + "message": "images 参数不能为空 / images 必须为数组 / 图片 file_id 必须为正整数 / display_order 必须为非负整数 / 单个订单最多维护 20 张图片(错误码 B2B_IMAGE_INPUT_INVALID)" + }, + { + "code": "400", + "message": "订单不存在或不属于当前仓库,无法更新图片:{订单ID}(错误码 B2B_IMAGE_ORDER_NOT_FOUND,data.order_id)" + }, + { + "code": "400", + "message": "仅 B2B 订单支持更新订单图片(错误码 B2B_IMAGE_NOT_B2B,data.order_id)" + }, + { + "code": "400", + "message": "订单已取消,不允许更新图片(错误码 B2B_IMAGE_STATUS_INVALID,data.order_id / status)" + }, + { + "code": "400", + "message": "图片文件不存在、已删除或不属于当前仓库:{文件ID列表}(错误码 B2B_IMAGE_FILE_INVALID,data.file_ids)" + }, + { + "code": "500", + "message": "未识别到当前仓库上下文,HTTP 500,message 为「接口错误: 未识别到当前仓库上下文」" + } + ], + "notes": [ + "business_type 口径:B2B 订单图片固定使用 b2b_order(集中定义在 app/lib/file_business_types.js),与商品图片 stock、盘点记录 stock_check_record、收货明细 receivingItem 隔离;business_id 为订单ID字符串,warehouse_id 必填以保证跨仓隔离。", + "全量覆盖语义:以 images 为准做 diff——未包含的旧关联删除、新增 file_id 插入、已存在但 display_order 变化的更新;整个过程在同一事务内完成,任意环节失败整体回滚,图片关联不落半套。", + "文件校验:file_id 必须存在于 wms_file 且 warehouse_id=当前仓库、is_deleted=false;任一文件不满足即整单失败,不写入任何关联。", + "订单校验:仅 is_b2b=Y 的订单可更新;status=cancel 的订单不允许更新;订单查找 current 分表优先、dispatch 分表兜底(配送域 B2B 订单)。", + "操作日志:成功后写一条 ORDER_B2B_IMAGES(操作名称「更新B2B订单图片」),extras 带 image_count / added_file_ids / removed_file_ids;失败仅告警不影响主流程。", + "列表联动:order.pendingOrder2b.list / order.deliveryOrder2b.list 已按页批量挂载 images: [{ id: file_id, url, display_order }](按 display_order 升序),无图片输出空数组。", + "实现:app/service/systems/order_b2b.js#updateOrderImages(含 normalizeOrderImages 归一化),出口 app/service/systemMethods/order/index.js#updateB2bOrderImages;列表挂载见 app/service/systemMethods/order/base.js#attachB2bJobDetail / #attachB2bOrderImages。" + ] } ] }, @@ -4191,7 +4901,7 @@ }, { "method": "order.pendingOrder.reverseReviewOrder", - "description": "将待处理订单反审回待审核状态。", + "description": "将待处理订单反审回待审核状态。B2B 订单(is_b2b=Y)走备货/提货独立作业链路,不支持反审:命中任意 B2B 订单时整批驳回(不做部分处理),接口返回错误提示「B2B 订单不支持反审回待审核(订单[ID...]),操作不生效」。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -4265,12 +4975,20 @@ ], "errors": [ { - "code": "400", - "description": "订单ID 不能为空或格式错误" + "code": 400, + "message": "订单ID 不能为空或格式错误" }, { - "code": "404", - "description": "订单不存在或不属于当前仓库" + "code": 404, + "message": "订单不存在或不属于当前仓库" + }, + { + "code": 400, + "message": "B2B 订单不支持反审回待审核(订单[ID...]),操作不生效" + }, + { + "code": 400, + "message": "订单已分配运单号,禁止反审" } ] }, @@ -5061,7 +5779,7 @@ }, { "method": "order.pendingOrder.cloneOrder", - "description": "克隆待处理订单(含已同步 sync_status=fin 订单)。完整流程:1. 查找原订单,校验可取消状态(step 0/1/2/3);2. 若原订单已分配储位(storage_status='fin'),先清除已分配库存,释放失败不阻断克隆(残留占用保留在原订单名下);3. 取消原订单(step→9, status→cancel),记录克隆日志;4. 以原订单业务数据创建新订单,所有流程状态字段重置为初始落库状态,发货单号重新生成为 SYS 前缀新单号(受唯一索引 delivery_order_code+store_id+warehouse_id 约束,不可复制原单号),原单号写入 pre_delivery_order_code 保留克隆追溯链,同步状态继承原订单(原订单已同步 sync_status=fin 则新订单直接置 fin 避免重复回传,否则重置 padding 重新同步);5. 克隆订单明细(含 stock_id),重置 order_id 为新订单 ID;6. 对新订单记录克隆创建日志。克隆新订单不重新占用库存(storage_status=none,不触发储位分配与库存锁定)。", + "description": "克隆待处理订单(含已同步 sync_status=fin 订单)。完整流程:1. 查找原订单,校验可取消状态(step 0/1/2/3);2. 若原订单已分配储位(storage_status='fin'),先清除已分配库存,释放失败不阻断克隆(残留占用保留在原订单名下);3. 取消原订单(step→9, status→cancel),记录克隆日志;4. 以原订单业务数据创建新订单,所有流程状态字段重置为初始落库状态,发货单号重新生成为 SYS 前缀新单号(受唯一索引 delivery_order_code+store_id+warehouse_id 约束,不可复制原单号),原单号写入 pre_delivery_order_code 保留克隆追溯链,同步状态继承原订单(原订单已同步 sync_status=fin 则新订单直接置 fin 避免重复回传,否则重置 padding 重新同步);5. 克隆订单明细(含 stock_id),重置 order_id 为新订单 ID;6. 对新订单记录克隆创建日志。克隆新订单不重新占用库存(storage_status=none,不触发储位分配与库存锁定)。B2B 订单(is_b2b=Y)不支持克隆:命中 B2B 订单时直接驳回,接口返回错误提示「B2B 订单不支持克隆订单(订单[ID...]),操作不生效」,原订单状态不变。", "isNeedAuth": true, "isNeedLogin": true, "headers": [ @@ -5108,6 +5826,10 @@ "code": 404, "message": "订单不存在" }, + { + "code": 400, + "message": "B2B 订单不支持克隆订单(订单[ID...]),操作不生效" + }, { "code": 400, "message": "订单状态不允许克隆(仅支持 step 0/1/2/3)" @@ -6704,7 +7426,7 @@ }, { "method": "order.pendingOrder2b.list", - "description": "B2B 待处理订单列表。查询条件与 order.pendingOrder.list 完全一致(current 分表 + 模块默认 where:outbound_status != padding 且 step in [1,2,3]),额外强制 is_b2b='Y'。固定条件与请求 where 取 AND,请求传入同名 is_b2b 条件无法覆盖。;列表行额外带出 wms_order_b2b 作业明细字段:total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、prep_at(备货完成时间)、is_picked_up(是否提货 Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间,与订单自身的 create_at 不同)。关联条件固定为 warehouse_id + order_id;无作业明细行时上述字段输出空值占位(数值 0、is_picked_up=N、时间为 null);另支持按 wms_order_b2b 作业明细字段筛选(仅本接口开放,普通订单列表不识别这些字段):total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、is_picked_up(Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间)、prep_at(备货完成时间)。支持简写与标准结构,如 {\"is_picked_up\":\"Y\"}、{\"pickup_plate_number\":{\"operator\":\"like\",\"value\":\"粤A\"}}、{\"prep_at\":{\"operator\":\"between\",\"value\":[\"2026-11-01 00:00:00\",\"2026-11-30 23:59:59\"]}};内部先按 warehouse_id + order_id 查 wms_order_b2b 取命中 order_id,再回填订单列表条件,未命中返回空列表。", + "description": "B2B 待处理订单列表。查询条件与 order.pendingOrder.list 完全一致(current 分表 + 模块默认 where:outbound_status != padding 且 step in [1,2,3]),额外强制 is_b2b='Y'。固定条件与请求 where 取 AND,请求传入同名 is_b2b 条件无法覆盖。;列表行额外带出 wms_order_b2b 作业明细字段:total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、is_urgent(是否加急 Y/N)、prep_at(备货完成时间)、is_picked_up(是否提货 Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间,与订单自身的 create_at 不同)。关联条件固定为 warehouse_id + order_id;无作业明细行时上述字段输出空值占位(数值 0、is_picked_up=N、时间为 null);另支持按 wms_order_b2b 作业明细字段筛选(仅本接口开放,普通订单列表不识别这些字段):total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、is_picked_up(Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间)、prep_at(备货完成时间)。支持简写与标准结构,如 {\"is_picked_up\":\"Y\"}、{\"pickup_plate_number\":{\"operator\":\"like\",\"value\":\"粤A\"}}、{\"prep_at\":{\"operator\":\"between\",\"value\":[\"2026-11-01 00:00:00\",\"2026-11-30 23:59:59\"]}};内部先按 warehouse_id + order_id 查 wms_order_b2b 取命中 order_id,再回填订单列表条件,未命中返回空列表。排序固定为加急优先:先按 wms_order_b2b.is_urgent='Y' 优先(Y 在前,无作业明细行的排在最后),再按 sort 参数指定字段(缺省 updated_at DESC, id DESC)排序。同时带出备货作业字段:prep_status(备货状态 none/padding/fin)、prep_operator_id(备货人工号)、prep_operator_name(备货人姓名)、prep_start_at(备货开始时间),并支持 where.prep_status / where.prep_operator_id / where.prep_start_at 筛选。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -6728,14 +7450,14 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象,语义与 order.pendingOrder.list 完全一致(禁止传入 warehouse_id / warehouseId)。另强制附加 is_b2b='Y':即使传入 {\"is_b2b\":\"N\"} 也只会得到空列表(固定条件与请求条件取 AND);另支持按 wms_order_b2b 作业明细字段筛选(仅本接口开放,普通订单列表不识别这些字段):total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、is_picked_up(Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间)、prep_at(备货完成时间)。支持简写与标准结构,如 {\"is_picked_up\":\"Y\"}、{\"pickup_plate_number\":{\"operator\":\"like\",\"value\":\"粤A\"}}、{\"prep_at\":{\"operator\":\"between\",\"value\":[\"2026-11-01 00:00:00\",\"2026-11-30 23:59:59\"]}};内部先按 warehouse_id + order_id 查 wms_order_b2b 取命中 order_id,再回填订单列表条件,未命中返回空列表。" + "description": "统一 where 条件对象,语义与 order.pendingOrder.list 完全一致(禁止传入 warehouse_id / warehouseId)。另强制附加 is_b2b='Y':即使传入 {\"is_b2b\":\"N\"} 也只会得到空列表(固定条件与请求条件取 AND);另支持按 wms_order_b2b 作业明细字段筛选(仅本接口开放,普通订单列表不识别这些字段):total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、is_picked_up(Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间)、prep_at(备货完成时间)。支持简写与标准结构,如 {\"is_picked_up\":\"Y\"}、{\"pickup_plate_number\":{\"operator\":\"like\",\"value\":\"粤A\"}}、{\"prep_at\":{\"operator\":\"between\",\"value\":[\"2026-11-01 00:00:00\",\"2026-11-30 23:59:59\"]}};内部先按 warehouse_id + order_id 查 wms_order_b2b 取命中 order_id,再回填订单列表条件,未命中返回空列表;is_urgent(是否加急,Y=加急 N=普通,支持简写与标准结构,如 {\"is_urgent\":\"Y\"});另支持 prep_status(none/padding/fin)、prep_operator_id(备货人工号)、prep_start_at(备货开始时间,支持 between 区间)筛选。" }, { "name": "sort", "type": "object", "required": false, "source": "body", - "description": "排序参数,支持 sortField / sortOrder;默认 updated_at DESC, id DESC" + "description": "排序参数,支持 sortField / sortOrder。加急订单(wms_order_b2b.is_urgent='Y')恒定优先,本参数只决定加急/非加急各自内部次序,缺省 updated_at DESC, id DESC。" } ], "response": [ @@ -6751,6 +7473,30 @@ "required": true, "description": "分页信息" }, + { + "name": "prep_status", + "type": "string", + "required": true, + "description": "备货状态:none=未开始 padding=备货中 fin=已完成(无作业明细行时为 none)" + }, + { + "name": "prep_operator_id", + "type": "number", + "required": false, + "description": "备货人工号ID(wms_order_b2b.prep_operator_id)" + }, + { + "name": "prep_operator_name", + "type": "string", + "required": false, + "description": "备货人姓名(wms_order_b2b.prep_operator_name)" + }, + { + "name": "prep_start_at", + "type": "string", + "required": false, + "description": "备货开始时间(wms_order_b2b.prep_start_at)" + }, { "name": "total_box_count", "type": "number", @@ -6781,6 +7527,12 @@ "required": false, "description": "备货完成时间(wms_order_b2b.prep_at)" }, + { + "name": "is_urgent", + "type": "string", + "required": true, + "description": "是否加急:Y=加急 N=普通(wms_order_b2b.is_urgent,无作业明细行时为 N)" + }, { "name": "is_picked_up", "type": "string", @@ -6812,7 +7564,10 @@ ], "notes": [ "B2B 作业明细输出口径:列表行按 warehouse_id + order_id 关联 wms_order_b2b 取数(分表 id 按仓库发号,不能只按 order_id 关联);副表已移除 store_id / delivery_order_code / is_print / updated_at / deleted_at 字段,取消 B2B 时物理删除明细行,故列表中的 created_at 为作业明细创建时间,无明细行时为空值占位。", - "B2B 作业明细筛选口径:仅在 order.pendingOrder2b.list / order.deliveryOrder2b.list 开放 total_box_count / pickup_plate_number / prep_remark / prep_duration_seconds / is_picked_up / picked_up_at / created_at / prep_at 作为 where 条件;内部转成 wms_order_b2b(warehouse_id + order_id)子查询取 order_id,再以 id IN (...) 回填,未命中返回空列表,不影响其他订单列表口径。" + "B2B 作业明细筛选口径:仅在 order.pendingOrder2b.list / order.deliveryOrder2b.list 开放 total_box_count / pickup_plate_number / prep_remark / prep_duration_seconds / is_picked_up / picked_up_at / created_at / prep_at 作为 where 条件;内部转成 wms_order_b2b(warehouse_id + order_id)子查询取 order_id,再以 id IN (...) 回填,未命中返回空列表,不影响其他订单列表口径。", + "加急口径:作业明细 is_urgent 在转 B2B 时以订单表 is_urgency 为初始值(仅 Y/y 视为加急,其余按 N);B2B 列表支持 where.is_urgent 筛选,与其他作业明细筛选一致按 warehouse_id + order_id 子查询回填。", + "排序口径:本接口在 sort 参数排序之前固定插入「加急优先」排序项——通过 (SELECT b2b.is_urgent FROM wms_order_b2b b2b WHERE b2b.warehouse_id = 当前仓库 AND b2b.order_id = 订单分表.id LIMIT 1) = 'Y' DESC 实现,加急订单(is_urgent=Y)恒定排在最前;sort 参数仍可指定次排序字段(默认 updated_at DESC, id DESC),但无法取消加急优先。", + "备货作业字段口径:prep_status/prep_operator_id/prep_operator_name/prep_start_at 由 order.startB2bPrep / order.cancelB2bPrep / order.finishB2bPrep 维护;列表按 warehouse_id + order_id 关联读取,无作业明细行时输出 none / null 占位。" ] } ] @@ -8060,7 +8815,7 @@ }, { "method": "order.recheckOrder.batchQuickRecheck", - "description": "批量快捷复核:传入订单 IDs 列表,对每个有效订单执行前置检查(已分配储位、已分配快递、已同步且未被拦截),必要时自动完成拣货(含库存锁定校验与扣减、库存流水写入、拣货任务状态同步)后标记复核(含复核任务记录、任务复核状态更新、车任务解绑、操作日志)。每个订单在独立事务中执行,支持部分失败,不满足条件的订单跳过并返回原因。复核状态更新后,会先自动清理波次内「已拦截且未打印」的订单(wave_id 清零回池、删除波次索引与任务订单关联、回写波次统计、写 ORDER_WAVE_REMOVE 日志并触发波次策略快扫),避免拦截订单卡住波次完成判定;已打印的拦截订单保持不动。SN(序列号管理)订单不支持快捷复核:has_sn_item='Y' 的订单会直接返回失败,需改用单订单复核并提交 SN 码,避免绕过 SN 校验。", + "description": "批量快捷复核:传入订单 IDs 列表,对每个有效订单执行前置检查(已分配储位、已分配快递、已同步且未被拦截),必要时自动完成拣货(含库存锁定校验与扣减、库存流水写入、拣货任务状态同步)后标记复核(含复核任务记录、任务复核状态更新、车任务解绑、操作日志)。每个订单在独立事务中执行,支持部分失败,不满足条件的订单跳过并返回原因。复核状态更新后,会先自动清理波次内「已拦截且未打印」的订单(wave_id 清零回池、删除波次索引与任务订单关联、回写波次统计、写 ORDER_WAVE_REMOVE 日志并触发波次策略快扫),避免拦截订单卡住波次完成判定;已打印的拦截订单保持不动。SN(序列号管理)订单不支持快捷复核:has_sn_item='Y' 的订单会直接返回失败,需改用单订单复核并提交 SN 码,避免绕过 SN 校验。B2B 订单(is_b2b=Y)不支持批量发货(快捷复核):入参命中任意 B2B 订单时整批驳回(不做部分处理),接口返回错误提示「B2B 订单不支持批量发货(订单[ID...]),操作不生效」,本次不产生任何复核结果。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -8139,12 +8894,16 @@ { "code": 400, "message": "订单ID列表不能为空" + }, + { + "code": 400, + "message": "B2B 订单不支持批量发货(订单[ID...]),操作不生效" } ] }, { "method": "order.recheckOrder.batchQuickRecheckByWave", - "description": "按波次批量快捷复核:传入波次 IDs 列表,对每个波次下所有有效订单执行前置检查(已分配储位、已分配快递、已同步且未被拦截),必要时自动完成拣货(含库存锁定校验与扣减、库存流水写入、拣货任务状态同步)后标记复核(含复核任务记录、任务复核状态更新、车任务解绑、操作日志)。每个订单在独立事务中执行,支持部分失败,不满足条件的订单跳过并返回原因。复核状态更新后,会先自动清理波次内「已拦截且未打印」的订单(wave_id 清零回池、删除波次索引与任务订单关联、回写波次统计、写 ORDER_WAVE_REMOVE 日志并触发波次策略快扫),避免拦截订单卡住波次完成判定;已打印的拦截订单保持不动。SN(序列号管理)订单不支持快捷复核:has_sn_item='Y' 的订单会直接返回失败,需改用单订单复核并提交 SN 码,避免绕过 SN 校验。", + "description": "按波次批量快捷复核:传入波次 IDs 列表,对每个波次下所有有效订单执行前置检查(已分配储位、已分配快递、已同步且未被拦截),必要时自动完成拣货(含库存锁定校验与扣减、库存流水写入、拣货任务状态同步)后标记复核(含复核任务记录、任务复核状态更新、车任务解绑、操作日志)。每个订单在独立事务中执行,支持部分失败,不满足条件的订单跳过并返回原因。复核状态更新后,会先自动清理波次内「已拦截且未打印」的订单(wave_id 清零回池、删除波次索引与任务订单关联、回写波次统计、写 ORDER_WAVE_REMOVE 日志并触发波次策略快扫),避免拦截订单卡住波次完成判定;已打印的拦截订单保持不动。SN(序列号管理)订单不支持快捷复核:has_sn_item='Y' 的订单会直接返回失败,需改用单订单复核并提交 SN 码,避免绕过 SN 校验。波次内命中 B2B 订单(is_b2b=Y)时整批驳回(不做部分处理),接口返回错误提示「B2B 订单不支持批量发货(订单[ID...]),操作不生效」,本次不产生任何复核结果。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -8233,6 +8992,10 @@ { "code": 400, "message": "波次ID列表不能为空" + }, + { + "code": 400, + "message": "B2B 订单不支持批量发货(订单[ID...]),操作不生效" } ] }, @@ -10070,7 +10833,7 @@ }, { "method": "order.wave.singleFetchByIds", - "description": "按订单 ID 列表抓取到一个散单波次。仅处理当前仓库的待处理订单(step in [1,2,3]),排除已在波次中的订单(wave_id>0),不区分快递;成功抓取后批量写入订单操作日志;当无可抓取订单时返回 wave_id=0。已锁定订单(lock_status 非 none)不允许抓取波次,返回 excluded_locked_order_ids。B2B 订单不参与抓取,返回 excluded_b2b_order_ids。SN(序列号管理)订单允许按订单 ID 显式抓取散单:SN 策略类型的含义只是「不会被散单/团购策略自动抓取」,手工按订单抓取不受限,因此 excluded_sn_order_ids 恒为空数组(字段保留兼容);抓取后的 manual_ids 波次在拣货侧固定走先拣后分(pick_mode=3),与 SN 策略一致。", + "description": "按订单 ID 列表抓取到一个散单波次。仅处理当前仓库的待处理订单(step in [1,2,3]),排除已在波次中的订单(wave_id>0),不区分快递;成功抓取后批量写入订单操作日志;当无可抓取订单时返回 wave_id=0。已锁定订单(lock_status 非 none)不允许抓取波次,返回 excluded_locked_order_ids。B2B 订单(is_b2b=Y)不参与抓取且不支持按订单抓取散单:入参命中任意 B2B 订单时整批驳回(不做部分抓取),接口返回错误提示「B2B 订单不支持抓取散单(订单[ID...]),操作不生效」,不创建波次、不写入任何订单日志。SN(序列号管理)订单允许按订单 ID 显式抓取散单:SN 策略类型的含义只是「不会被散单/团购策略自动抓取」,手工按订单抓取不受限,因此 excluded_sn_order_ids 恒为空数组(字段保留兼容);抓取后的 manual_ids 波次在拣货侧固定走先拣后分(pick_mode=3),与 SN 策略一致。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -10160,6 +10923,10 @@ { "code": "500", "message": "抓取失败或内部错误" + }, + { + "code": "400", + "message": "B2B 订单不支持抓取散单(订单[ID...]),操作不生效" } ] }, @@ -13476,7 +14243,7 @@ }, { "method": "order.deliveryOrder2b.list", - "description": "B2B 配送订单列表。查询条件与 order.deliveryOrder.list 完全一致(dispatch 分表 + 默认 dispatch_lane=m4),额外强制 is_b2b='Y'。固定条件与请求 where 取 AND,请求传入同名 is_b2b 条件无法覆盖。;列表行额外带出 wms_order_b2b 作业明细字段:total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、prep_at(备货完成时间)、is_picked_up(是否提货 Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间,与订单自身的 create_at 不同)。关联条件固定为 warehouse_id + order_id;无作业明细行时上述字段输出空值占位(数值 0、is_picked_up=N、时间为 null);另支持按 wms_order_b2b 作业明细字段筛选(仅本接口开放,普通订单列表不识别这些字段):total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、is_picked_up(Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间)、prep_at(备货完成时间)。支持简写与标准结构,如 {\"is_picked_up\":\"Y\"}、{\"pickup_plate_number\":{\"operator\":\"like\",\"value\":\"粤A\"}}、{\"prep_at\":{\"operator\":\"between\",\"value\":[\"2026-11-01 00:00:00\",\"2026-11-30 23:59:59\"]}};内部先按 warehouse_id + order_id 查 wms_order_b2b 取命中 order_id,再回填订单列表条件,未命中返回空列表。", + "description": "B2B 配送订单列表。查询条件与 order.deliveryOrder.list 完全一致(dispatch 分表 + 默认 dispatch_lane=m4),额外强制 is_b2b='Y'。固定条件与请求 where 取 AND,请求传入同名 is_b2b 条件无法覆盖。;列表行额外带出 wms_order_b2b 作业明细字段:total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、is_urgent(是否加急 Y/N)、prep_at(备货完成时间)、is_picked_up(是否提货 Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间,与订单自身的 create_at 不同)。关联条件固定为 warehouse_id + order_id;无作业明细行时上述字段输出空值占位(数值 0、is_picked_up=N、时间为 null);另支持按 wms_order_b2b 作业明细字段筛选(仅本接口开放,普通订单列表不识别这些字段):total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、is_picked_up(Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间)、prep_at(备货完成时间)。支持简写与标准结构,如 {\"is_picked_up\":\"Y\"}、{\"pickup_plate_number\":{\"operator\":\"like\",\"value\":\"粤A\"}}、{\"prep_at\":{\"operator\":\"between\",\"value\":[\"2026-11-01 00:00:00\",\"2026-11-30 23:59:59\"]}};内部先按 warehouse_id + order_id 查 wms_order_b2b 取命中 order_id,再回填订单列表条件,未命中返回空列表。排序固定为加急优先:先按 wms_order_b2b.is_urgent='Y' 优先(Y 在前,无作业明细行的排在最后),再按 sort 参数指定字段(缺省 delivery_time DESC, id DESC)排序。同时带出备货作业字段:prep_status(备货状态 none/padding/fin)、prep_operator_id(备货人工号)、prep_operator_name(备货人姓名)、prep_start_at(备货开始时间),并支持 where.prep_status / where.prep_operator_id / where.prep_start_at 筛选。", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -13500,14 +14267,14 @@ "type": "object", "required": false, "source": "body", - "description": "统一 where 条件对象,语义与 order.deliveryOrder.list 完全一致(禁止传入 warehouse_id / warehouseId)。另强制附加 is_b2b='Y':即使传入 {\"is_b2b\":\"N\"} 也只会得到空列表(固定条件与请求条件取 AND);另支持按 wms_order_b2b 作业明细字段筛选(仅本接口开放,普通订单列表不识别这些字段):total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、is_picked_up(Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间)、prep_at(备货完成时间)。支持简写与标准结构,如 {\"is_picked_up\":\"Y\"}、{\"pickup_plate_number\":{\"operator\":\"like\",\"value\":\"粤A\"}}、{\"prep_at\":{\"operator\":\"between\",\"value\":[\"2026-11-01 00:00:00\",\"2026-11-30 23:59:59\"]}};内部先按 warehouse_id + order_id 查 wms_order_b2b 取命中 order_id,再回填订单列表条件,未命中返回空列表。" + "description": "统一 where 条件对象,语义与 order.deliveryOrder.list 完全一致(禁止传入 warehouse_id / warehouseId)。另强制附加 is_b2b='Y':即使传入 {\"is_b2b\":\"N\"} 也只会得到空列表(固定条件与请求条件取 AND);另支持按 wms_order_b2b 作业明细字段筛选(仅本接口开放,普通订单列表不识别这些字段):total_box_count(总箱数)、pickup_plate_number(提货车牌)、prep_remark(备货备注)、prep_duration_seconds(备货用时/秒)、is_picked_up(Y/N)、picked_up_at(提货时间)、created_at(作业明细创建时间)、prep_at(备货完成时间)。支持简写与标准结构,如 {\"is_picked_up\":\"Y\"}、{\"pickup_plate_number\":{\"operator\":\"like\",\"value\":\"粤A\"}}、{\"prep_at\":{\"operator\":\"between\",\"value\":[\"2026-11-01 00:00:00\",\"2026-11-30 23:59:59\"]}};内部先按 warehouse_id + order_id 查 wms_order_b2b 取命中 order_id,再回填订单列表条件,未命中返回空列表;is_urgent(是否加急,Y=加急 N=普通,支持简写与标准结构,如 {\"is_urgent\":\"Y\"});另支持 prep_status(none/padding/fin)、prep_operator_id(备货人工号)、prep_start_at(备货开始时间,支持 between 区间)筛选。" }, { "name": "sort", "type": "object", "required": false, "source": "body", - "description": "排序参数,支持 sortField / sortOrder;默认 delivery_time DESC, id DESC" + "description": "排序参数,支持 sortField / sortOrder。加急订单(wms_order_b2b.is_urgent='Y')恒定优先,本参数只决定加急/非加急各自内部次序,缺省 delivery_time DESC, id DESC。" } ], "response": [ @@ -13523,6 +14290,30 @@ "required": true, "description": "分页信息" }, + { + "name": "prep_status", + "type": "string", + "required": true, + "description": "备货状态:none=未开始 padding=备货中 fin=已完成(无作业明细行时为 none)" + }, + { + "name": "prep_operator_id", + "type": "number", + "required": false, + "description": "备货人工号ID(wms_order_b2b.prep_operator_id)" + }, + { + "name": "prep_operator_name", + "type": "string", + "required": false, + "description": "备货人姓名(wms_order_b2b.prep_operator_name)" + }, + { + "name": "prep_start_at", + "type": "string", + "required": false, + "description": "备货开始时间(wms_order_b2b.prep_start_at)" + }, { "name": "total_box_count", "type": "number", @@ -13553,6 +14344,12 @@ "required": false, "description": "备货完成时间(wms_order_b2b.prep_at)" }, + { + "name": "is_urgent", + "type": "string", + "required": true, + "description": "是否加急:Y=加急 N=普通(wms_order_b2b.is_urgent,无作业明细行时为 N)" + }, { "name": "is_picked_up", "type": "string", @@ -13584,7 +14381,10 @@ ], "notes": [ "B2B 作业明细输出口径:列表行按 warehouse_id + order_id 关联 wms_order_b2b 取数(分表 id 按仓库发号,不能只按 order_id 关联);副表已移除 store_id / delivery_order_code / is_print / updated_at / deleted_at 字段,取消 B2B 时物理删除明细行,故列表中的 created_at 为作业明细创建时间,无明细行时为空值占位。", - "B2B 作业明细筛选口径:仅在 order.pendingOrder2b.list / order.deliveryOrder2b.list 开放 total_box_count / pickup_plate_number / prep_remark / prep_duration_seconds / is_picked_up / picked_up_at / created_at / prep_at 作为 where 条件;内部转成 wms_order_b2b(warehouse_id + order_id)子查询取 order_id,再以 id IN (...) 回填,未命中返回空列表,不影响其他订单列表口径。" + "B2B 作业明细筛选口径:仅在 order.pendingOrder2b.list / order.deliveryOrder2b.list 开放 total_box_count / pickup_plate_number / prep_remark / prep_duration_seconds / is_picked_up / picked_up_at / created_at / prep_at 作为 where 条件;内部转成 wms_order_b2b(warehouse_id + order_id)子查询取 order_id,再以 id IN (...) 回填,未命中返回空列表,不影响其他订单列表口径。", + "加急口径:作业明细 is_urgent 在转 B2B 时以订单表 is_urgency 为初始值(仅 Y/y 视为加急,其余按 N);B2B 列表支持 where.is_urgent 筛选,与其他作业明细筛选一致按 warehouse_id + order_id 子查询回填。", + "排序口径:本接口在 sort 参数排序之前固定插入「加急优先」排序项——通过 (SELECT b2b.is_urgent FROM wms_order_b2b b2b WHERE b2b.warehouse_id = 当前仓库 AND b2b.order_id = 订单分表.id LIMIT 1) = 'Y' DESC 实现,加急订单(is_urgent=Y)恒定排在最前;sort 参数仍可指定次排序字段(默认 delivery_time DESC, id DESC),但无法取消加急优先。", + "备货作业字段口径:prep_status/prep_operator_id/prep_operator_name/prep_start_at 由 order.startB2bPrep / order.cancelB2bPrep / order.finishB2bPrep 维护;列表按 warehouse_id + order_id 关联读取,无作业明细行时输出 none / null 占位。" ] } ] @@ -18050,6 +18850,12 @@ "required": false, "description": "产品类型" }, + { + "name": "goods_description", + "type": "string", + "required": false, + "description": "物品描述(电子面单 package_info.goods_description,可为空)" + }, { "name": "shop_name", "type": "string", @@ -18314,6 +19120,11 @@ "type": "string", "description": "快递产品类型" }, + { + "name": "goods_description", + "type": "string", + "description": "物品描述(电子面单 package_info.goods_description,可为空)" + }, { "name": "shop_name", "type": "string", @@ -18413,6 +19224,13 @@ "required": false, "source": "body", "description": "发件人详细地址(可选),使用 index.getShopExpressList 返回的 detail 字段值,非 full_address" + }, + { + "name": "goods_description", + "type": "string", + "required": false, + "source": "body", + "description": "物品描述(支持 goodsDescription),最多 255 个字符,可为空;用于电子面单 package_info.goods_description" } ], "response": [ @@ -18635,6 +19453,13 @@ "source": "body", "description": "产品类型/编码(支持 productType)" }, + { + "name": "goods_description", + "type": "string", + "required": false, + "source": "body", + "description": "物品描述(支持 goodsDescription),最多 255 个字符,可为空" + }, { "name": "shop_name", "type": "string", @@ -18850,6 +19675,12 @@ "required": false, "description": "产品类型/编码" }, + { + "name": "goods_description", + "type": "string", + "required": false, + "description": "物品描述(可为空)" + }, { "name": "shop_name", "type": "string", diff --git a/test/app/service/systems/express_platform.cainiao.test.js b/test/app/service/systems/express_platform.cainiao.test.js index 163c71d..cfd2a53 100644 --- a/test/app/service/systems/express_platform.cainiao.test.js +++ b/test/app/service/systems/express_platform.cainiao.test.js @@ -355,6 +355,26 @@ describe('test/app/service/systems/express_platform.cainiao.test.js', () => { assert.equal(bizBody.trade_order_info_dtos[0].template_url, DEFAULT_CAINIAO_TEMPLATE_URL); }); + it('should use configured goods_description and fall back to default when empty', async () => { + const { service, calls } = createCainiaoHarness(); + + const payload = buildPayload(); + payload.listByWarehousePlatformCode.goods_description = ' 化妆品套装 '; + await service.cainiao(payload); + + let requestBody = calls.curlOptions.options.data; + let bizBody = JSON.parse(requestBody.param_waybill_cloud_print_apply_new_request); + assert.equal(bizBody.trade_order_info_dtos[0].package_info.goods_description, '化妆品套装'); + + const fallbackPayload = buildPayload(); + fallbackPayload.listByWarehousePlatformCode.goods_description = ''; + await service.cainiao(fallbackPayload); + + requestBody = calls.curlOptions.options.data; + bizBody = JSON.parse(requestBody.param_waybill_cloud_print_apply_new_request); + assert.equal(bizBody.trade_order_info_dtos[0].package_info.goods_description, '化妆品'); + }); + it('should throw when taobao returns error_response', async () => { const { service } = createCainiaoHarness({ responseData: { diff --git a/test/app/service/systems/setting/expressInterface.test.js b/test/app/service/systems/setting/expressInterface.test.js index 5799133..761eaa3 100644 --- a/test/app/service/systems/setting/expressInterface.test.js +++ b/test/app/service/systems/setting/expressInterface.test.js @@ -167,6 +167,7 @@ function createHarness(options = {}) { district_name: {}, site_code: {}, product_type: {}, + goods_description: {}, weight_type: {}, shop_name: {}, address: {}, @@ -608,6 +609,7 @@ describe('test/app/service/systems/setting/expressInterface.test.js', () => { template_id: 1202, brandno: 'BRAND-SF', providertype: 'CAINIAO', + goods_description: '化妆品', name: '顺丰接口', express_code: 'SF', platform_code: 'TB', @@ -664,6 +666,8 @@ describe('test/app/service/systems/setting/expressInterface.test.js', () => { assert.equal(result.data[0].template_id, 1202); assert.equal(result.data[0].brandno, 'BRAND-SF'); assert.equal(result.data[0].providertype, 'CAINIAO'); + assert.equal(result.data[0].goods_description, '化妆品'); + assert.equal(Object.prototype.hasOwnProperty.call(result.data[1], 'goods_description'), false); assert.equal(result.data[1].express_code, 'ZTO'); assert.equal(result.data[1].brandno, 'BRAND-ZTO'); assert.equal(result.data[2].express_code, 'YTO'); @@ -1021,6 +1025,47 @@ describe('test/app/service/systems/setting/expressInterface.test.js', () => { assert.equal(calls.cacheDeletes.includes('express_interface:warehouse:100000:platform:PDD'), true); }); + it('should save trimmed goods_description on create', async () => { + const { ctx, calls } = createHarness(); + const service = new SettingExpressInterfaceService(ctx); + + const result = await service.create({ + name: '物品描述接口', + express_code: 'SF', + platform_code: 'TB', + goodsDescription: ' 化妆品套装 ', + }); + + assert.equal(calls.createPayload.goods_description, '化妆品套装'); + assert.equal(result.data.goods_description, '化妆品套装'); + }); + + it('should allow empty goods_description and reject value longer than 255', async () => { + const { ctx, calls } = createHarness(); + const service = new SettingExpressInterfaceService(ctx); + + const result = await service.update({ + id: 11, + goods_description: '', + }); + + assert.equal(calls.updatePayload.updates.goods_description, ''); + assert.equal(result.data.goods_description, ''); + + let error = null; + try { + await service.update({ + id: 11, + goods_description: 'a'.repeat(256), + }); + } catch (err) { + error = err; + } + + assert.equal(error && error.code, 400); + assert.equal(error && error.message, 'goods_description 长度不能超过 255'); + }); + it('should sync token from shop access_token when updating shop_id', async () => { const { ctx, calls } = createHarness(); const service = new SettingExpressInterfaceService(ctx);