liufumingren a123009159 fix(stockout): 出库单明细 item_id 统一落 StockStore 主键 id,修复非数字 itemId 导致建单失败
- 奇门 stockout.create 调用方把「编码+名称」拼接串同时放入 itemId/itemCode/itemName,
  itemCode 降级精确匹配成功并解析出 stock_id 后,item_id 仍落报文原值(非数字),
  写入 BIGINT 列触发 MySQL 严格模式 1366 Incorrect integer value 建单失败
- 对齐 entry_order 建单口径:item_id 统一写实际匹配到的 StockStore 主键 id(纯数字)
- 验证:test/temp_test_stockout_itemid_normalize.js 5/5 PASS(非数字 itemId 降级匹配
  建单成功 + 数字主键回归);生产日志核实:2026-10-08 10:09 奇门请求
  app_key=23204092,stock_id 解析正确仅 item_id 落库报错
- 文档同步:methods/qimen.json 0.3.10 -> 0.3.11,stockout.create 补充 item_id
  归一化 notes + changes 变更记录
2026-10-08 16:07:59 +08:00

229 lines
20 KiB
JSON
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

[
{
"version": "2026.10.08-qimen-stockout-item-id-normalize",
"date": "2026-10-08",
"type": "updated",
"module": "stockout",
"summary": "qimen stockout.create 明细 item_id 落库口径修正:统一写入实际匹配到的 StockStore 数字主键 id,修复调用方把「编码+名称」拼接串放进 itemId(同时 itemCode 可精确匹配)时写入 BIGINT 列触发 MySQL 严格模式 1366(Incorrect integer value for column item_id)导致建单失败的问题;与 entryorder.create 建单口径对齐。",
"methods": [
"stockout.create"
],
"notes": [
"app/service/systems/stockout_order.js#create 校验循环 items.push:itemId 由 line.itemId 改为 wmsStock.id(StockStore 主键,纯数字);itemCode/itemName 仍落报文原值,stockId 仍为 wmsStock.stock_id",
"回传影响:stockout 确认回传(order_async.js buildStockoutConfirmDataInternal)itemId 改为 StockStore 主键 id,符合奇门 itemId=「仓储系统商品ID」语义,与入库单确认回传口径一致",
"生产案例:2026-10-08 10:09 奇门 stockout.create(app_key=23204092)报 Incorrect integer value: LB006小光兔灵感五色眼影盘#01情懒落日 for column item_id,调用方 itemId/itemCode/itemName 三字段均为拼接串,系统按 itemCode 匹配到 StockStore(stock_id=162580)但落库仍用报文原值",
"验证:test/temp_test_stockout_itemid_normalize.js(非数字 itemId + itemCode 降级匹配 → 建单成功且 item_id=StockStore 主键;数字主键回归通过),5/5 PASS"
]
},
{
"version": "2026.09.12-qimen-order-cancel-rk-entry-order-support",
"date": "2026-09-12",
"type": "updated",
"module": "order",
"summary": "qimen order.cancel 的 RK 组(B2BRK/SCRK/LYRK/CCRK/CGRK/DBRK/QTRK)取消入库单语义升级:由「直接置 order_status=CANCELLED」升级为委托 ctx.service.systems.storage.entry.cancel 完整作废流程(守卫 sync_status=SUCCESS/COMPLETED + 回退收货单占用 + ENTRY_ORDER_CANCEL 操作日志),取消成功后不回传任何奇门事件(skipExternalSync=true),已作废按幂等成功;同步修正上一轮「RK 组将入库单 order_status 置 CANCELLED」的过时措辞。",
"methods": [
"order.cancel"
],
"notes": [
"app/service/qimenMethods/order.js cancel 的 case RK:空单号返回「入库单号不能为空」;委托 ctx.service.systems.storage.entry.cancel({ entryOrderCode }, { storeId, warehouseId, operatorLabel=qimen:xxx, skipExternalSync=true, idempotent=true, notFoundMessage=未找到对应的入库单 })",
"守卫口径(systems/storage/entry.js _guardCancelEntryOrder):sync_status=SUCCESS 返回「入库单已完成回传,不可取消」,order_status=COMPLETED 返回「已完成入库单不允许作废」;幂等模式下已 CANCELLED 优先按成功处理(幂等判定优先于回传状态判定)",
"作废动作(_doCancelEntryOrder):状态置 CANCELLED + 按台账回退关联收货单占用(重算 storage_status)+ 写 ENTRY_ORDER_CANCEL 操作日志;skipExternalSync=true 跳过 QM 来源的 qimenEntrySync 取消回传,取消成功不回传奇门事件",
"共享实现 QM 回传失败分支文案为「取消失败: xxx」(RK 渠道 skipExternalSync=true 不触发回传,该分支不会出现)",
"methods/qimen.json:order.cancel 的 description(RK 组改为委托共享作废流程)、request.orderType(RK 组改为已实现并注明完整作废语义)、errors(新增入库单号不能为空/已完成入库单不允许作废/入库单已完成回传,不可取消)、notes(RK 组 note 重写为完整实现语义)",
"order.pending 的 request.orderType 枚举描述仅列枚举名,无「将入库单 order_status 置 CANCELLED」过时措辞,保持不动",
"文档版本 0.3.9 -> 0.3.10(docMeta.version),updatedAt 保持 2026-09-12",
"本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)"
]
},
{
"version": "2026.09.12-qimen-order-cancel-ck-stockout-support",
"date": "2026-09-12",
"type": "updated",
"module": "order",
"summary": "qimen order.cancel 的 CK 组(PTCK/DBCK/B2BCK/QTCK/CGTH)由「取消出库单未开发完成」改为已支持:按出库单号查 wms_order_stockout,仅 CREATED/PENDING 允许取消(COMPLETED/TRANSFERRED 拒绝),委托共享实现 systems/stockout_order.js#cancel(单事务 + 行锁,释放 QM_STOCKOUT 锁定并写 STOCKOUT_CANCEL 操作日志,已 CANCELLED 幂等返回成功);同步修正上一轮遗留的「CK 组(未开发)」过时措辞与 errors/notes。",
"methods": [
"order.cancel"
],
"notes": [
"app/service/qimenMethods/order.js cancel 的 case CK:空单号返回「出库单号不能为空」,否则委托 ctx.service.systems.stockoutOrder.cancel({ stockoutOrderCode }, { storeId, warehouseId, operatorLabel=qimen:xxx })",
"出库单状态枚举 CREATING/CREATED/PENDING/COMPLETED/CANCELLED/TRANSFERRED;仅 CREATED/PENDING 可取消(canCancel),已 CANCELLED 幂等返回成功,COMPLETED/TRANSFERRED 返回「出库单当前状态(xxx)不允许取消」",
"取消成功不向奇门回传任何事件;释放 QM_STOCKOUT 库存锁定(写 UNLOCK 流水),「释放数量超过已锁定库存」视为幂等跳过;写 wms_operation_log(business_type=stockout,operation_code=STOCKOUT_CANCEL)",
"methods/qimen.json:order.cancel 的 description、request.orderCode(补充 CK 组为出库单号)、request.orderType(CK 组改为已实现并标注状态约束)、response.message(补充取消出库单成功)、errors(移除「取消出库单未开发完成」,新增出库单号不能为空/未找到对应的出库单/出库单当前状态(xxx)不允许取消/取消失败:xxx)、notes(新增 CK 组实现语义)",
"order.pending 的 CK 组枚举名称(PTCK=普通出库单、DBCK=调拨出库、B2BCK=B2B出库、QTCK=其他出库、CGTH=采购退货出库单)保持不变,order.cancel 沿用同一口径",
"文档版本 0.3.8 -> 0.3.9(docMeta.version),updatedAt 保持 2026-09-12",
"本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)"
]
},
{
"version": "2026.09.12-qimen-order-cancel-pending-orderType-enum",
"date": "2026-09-12",
"type": "updated",
"module": "order",
"summary": "qimen order.cancel / order.pending 补齐 request.orderType 作业类型枚举说明(原为占位文本):全量枚举 ORDER(JYCK/HHCK/BFCK,取消发货单已实现)/ RK(B2BRK/SCRK/LYRK/CCRK/CGRK/DBRK/QTRK,入库单 order_status 置 CANCELLED)/ CK(PTCK/DBCK/B2BCK/QTCK/CGTH,未开发)/ JG(CNJG,未开发)/ BACKORDER(XTRK/THRK/HHRK,未开发);同步补全 order.cancel 取消逻辑说明(直接取消/拦截/幂等)、response 与 errors。",
"methods": [
"order.cancel",
"order.pending"
],
"notes": [
"app/service/qimenMethods/order.js:构造函数 this.orderType 定义 orderType→{method,name} 全量映射,cancel/pending 均按 orderType.method switch 分发",
"order.cancel 的 request.orderType 参数 description 由占位文本补齐为全量枚举(含各组的取消支持情况);request.orderCode description 补充 ORDER 组为发货单号、RK 组为入库单号",
"order.cancel 补齐 response(flag/code/message,code=1 成功/0 失败)与 errors(订单号不能为空/未找到对应的订单/未找到对应的入库单/取消失败,已通知拦截执行/订单已同步,不可取消,已转为拦截处理/取消出库单未开发完成/取消加工单未开发完成/取消退货单未开发完成)",
"order.cancel notes 补充取消逻辑:未拣货且未打印直接取消(status=cancel, outbound_status=fin, step=4);已拣货/已打印拦截(intercept_status=intercepting);已同步转拦截(intercept_status=requested);已取消幂等返回取消订单成功",
"order.pending 的 request.orderType 参数 description 同步补齐为同一套枚举(pending 当前所有类型分支均未开发完成,返回锁定XX未开发完成),response/errors 同步补齐",
"文档版本 0.3.7 -> 0.3.8(docMeta.version),updatedAt 2026-09-12",
"本次仅同步文档,未修改任何业务代码;写入通过 script/update-api-doc.cjs(先 --dry-run 校验)"
]
},
{
"version": "2026.08.30-entryorder-create-item-match-fix",
"date": "2026-08-30",
"summary": "entryorder.create 商品匹配修复文档同步:明细行商品匹配三级策略(itemId 主键直查 > itemCode 精确匹配 > itemCode 归一化条码匹配)、编码支持中文后缀、item_id 统一写入 StockStore 数字主键、失败信息回显真实 SKU/商品/编码并附订单行号",
"methods": [
"entryorder.create"
],
"notes": [
"商品匹配三级策略:itemId 主键直查(纯数字且不超 BIGINT 范围、货主一致)> itemCode 精确匹配 > itemCode 归一化条码匹配(取编码开头连续数字)",
"带中文后缀编码(如 6934864201409-新品、6902226688892-赠品装)精确匹配不到时按归一化条码对齐;归一化命中多商品时报错不静默",
"item_id 统一写入实际匹配到的 StockStore 数字主键 id,修复 Data truncated for column 'item_id'",
"失败信息回显真实 SKU/商品/编码并附订单行号(未同步推送到仓库 / wms无对应关系 / 归一化匹配到多个商品)",
"测试:新增 qimen.entryorder.match.regression.test.js、entry_order.match.unit.test.js,修正 qimen.entryorder.create.status.test.js,10 passing / 0 failing(2026-08-30)",
"代码依据:app/service/systems/entry_order.js addOrder,qimenMethods/entryorder.js 与 openapiMethods/entryorder.js 共用同一逻辑"
],
"type": "updated",
"module": "entryorder"
},
{
"version": "2026.08.25-stockout-create-express-fallback-zt",
"date": "2026-08-25",
"summary": "stockout.create 快递兜底口径调整:兜底仅使用出库单兜底快递编码(policy_config.stockout_default_express_code,默认 ZT 自提),不再回退订单默认快递(default_express_code/全局 STO);快递解析改为独立实现,不再复用订单侧 resolveExpressSnapshot 兜底链。",
"methods": [
"stockout.create"
],
"notes": [
"qimenMethods/stockout.js create 快递解析重写:开启 enable_external_express_code 且传 logisticsCode 时按 wms_express_setting 映射 → 系统快递列表匹配;未传/未开启/匹配不到时取 stockout_default_express_code(为空则 'ZT'),从系统快递列表解析名称,仍不存在则编码=名称=ZT",
"app/model/store_warehouse.js POLICY_CONFIG_FIELDS:新增 stockout_default_express_code(名称:出库单默认快递,type list,default 'ZT'),getPolicyConfigFieldListWithOptions 同步注入快递选项,与 default_express_code 表现一致",
"注意:ZT 需在系统快递列表中维护(自提),否则出库单 express_code/express_name 直接落库 ZT"
],
"type": "updated",
"module": "stockout"
},
{
"version": "2026.08.25-stockout-create-receiver-info",
"date": "2026-08-25",
"summary": "stockout.create 解析 receiverInfo 落库(13 个标准字段)并接入出库单兜底快递编码:快递解析在未传 logisticsCode 或匹配不到时,优先使用货主合约配置 stockout_default_express_code(出库单兜底快递),为空再回退 default_express_code/全局 STO。",
"methods": [
"stockout.create"
],
"notes": [
"qimenMethods/stockout.js create 新增 receiverInfo 解析:company/name/zipCode/tel/mobile/email/countryCode/province/city/area/town/detailAddress/id 共 13 字段落库 receiver_* 列(空值转 NULL)",
"快递解析改为传入覆盖默认快递后的 expressPolicyConfig(default_express_code = stockout_default_express_code || default_express_code)复用 resolveExpressSnapshot 匹配链路",
"app/model/store_warehouse.js POLICY_CONFIG_FIELDS 新增 stockout_default_express_code(type list,默认空,描述:出库单未传快递编码或匹配不到时使用的兜底快递编码)",
"receiverInfo 中的 idType/idNumber 扩展字段暂不落库(数据库未建列)"
],
"type": "updated",
"module": "stockout"
},
{
"version": "2026.08.25-stockout-create-express-resolve",
"date": "2026-08-25",
"summary": "stockout.create 新增 logisticsCode 快递编码解析(简化口径):货主开启 enable_external_express_code 时按 wms_express_setting → 系统快递列表匹配,匹配不到(含未开启)一律兜底默认快递,不走订单快递策略漏斗(matchPolicy)。解析结果落库 express_code/express_name。",
"methods": [
"stockout.create"
],
"notes": [
"qimenMethods/stockout.js create 在事务外解析 deliveryOrder.logisticsCode:调 deliveryOrder.getStoreWarehousePolicyConfig 读策略开关 + deliveryOrder.resolveExpressSnapshot(编码映射+兜底,不含策略漏斗),取 sysLogisticsCode/sysLogisticsName 落库 express_code/express_name",
"解析失败仅告警不阻断建单(express_code/express_name 保持 NULL),confirm 前仍可走 storage.stockout.updateExpress 手工补填",
"注意:出库单 express_code 存系统快递编码,stockout.confirm 出站回传 logisticsCode 时直接使用该值"
],
"type": "updated",
"module": "stockout"
},
{
"version": "2026.07.01-qimen-01",
"date": "2026-07-01",
"summary": "补充 entryorder.create 的 request body 子结构和 response 结构",
"methods": [
"entryorder.create"
],
"notes": [
"补充 request.entryOrder 子结构(entryOrderCode/warehouseCode/ownerCode/orderType)",
"补充 request.orderLines.orderLine 子结构(itemCode/itemId/itemName/planQty/orderLineNo/inventoryType)",
"补充 response 结构(entryOrderId/entryOrderCode/createTime/status)",
"参考代码:systems/entry_order.js addOrder 和 qimenMethods/entryorder.js create 返回值"
],
"type": "updated",
"module": "entryorder"
},
{
"version": "2026.04.07-qimen-01",
"date": "2026-04-07",
"summary": "初始化 qimen 文档变更记录 sidecar,后续接口文档变更将持续追加到本数组。",
"methods": [
"*"
],
"notes": [
"methods/qimen.json 仍为单一事实来源(SSOT)。",
"本文件仅记录变更历史与补充说明。"
]
},
{
"version": "2026.06.30-stockout-create-01",
"date": "2026-06-30",
"summary": "stockout.create 重构:从不可用的 deliveryOrder 旧链路迁移到 wms_order_stockout 专用表;返回字段 deliveryOrderId→stockoutOrderId/stockoutOrderCode",
"methods": [
"stockout.create"
],
"notes": [
"params 补全 deliveryOrder 和 orderLines 内部全部子字段",
"response 从空补充为 stockoutOrderId/stockoutOrderCode",
"文档与代码实现(qimenMethods/stockout.js create 方法)对齐"
]
},
{
"version": "2026.06.30-stockout-query-01",
"date": "2026-06-30",
"summary": "stockout.query 从占位(接口未完善)实现为完整查询:按 deliveryOrderCode 查 wms_order_stockout 主表+明细表",
"methods": [
"stockout.query"
],
"notes": [
"params 补全 request.deliveryOrder.deliveryOrderCode(body)",
"response 从空补充为 deliveryOrder 主单 + orderLines.orderLine 明细 + totalLines",
"文档与代码实现(qimenMethods/stockout.js query 方法)对齐"
],
"type": "updated"
},
{
"version": "2026.08.07-stockout-confirm-01",
"date": "2026-08-07",
"summary": "stockout.confirm 从入站改为出站:确认后由 WMS 出站调用 taobao.qimen.stockout.confirm 通知 ERP",
"methods": [
"stockout.confirm"
],
"notes": [
"移除 qimenMethods/stockout.js 中错误的入站 confirm 方法(stockout.confirm 是出站而非入站)",
"storage.stockout.confirm 确认后通过 qimenClient.send() 出站调用 taobao.qimen.stockout.confirm",
"出站 payload 包含 deliveryOrder/packages/orderLines,logisticsCode=OTHER",
"qimen.json 移除 stockout.confirm 入站条目"
],
"type": "changed",
"module": "stockout"
},
{
"version": "2026.08.17-qimen-order-cancel-01",
"date": "2026-08-17",
"summary": "order.cancel 触发拦截的两个分支统一转发快递群发起拦截(创建售后工单+通知快递群),仅限有运单的订单处理",
"methods": [
"order.cancel"
],
"notes": [
"已拣货/已打印分支:保留原有 createInterceptWorkOrdersAndNotify 调用,新增前置判断——先查订单运单,无运单不再创建工单/通知快递群",
"已同步订单分支(sync_status=fin):新增与分支一相同的拦截处理——有运单时创建售后工单并通知对应快递群,与正常货主发起拦截一致",
"无运单订单仍按原逻辑更新拦截状态与异常群通知,不创建工单、不通知快递群",
"createInterceptWorkOrdersAndNotify 内部本就按运单驱动(无运单直接返回),外层判断进一步避免无谓调用"
],
"type": "changed",
"module": "order"
}
]