From 4d8297aecb95ac6ed0a592df8b968fd575dcd2fa Mon Sep 17 00:00:00 2001 From: liufumingren Date: Tue, 15 Sep 2026 16:19:10 +0800 Subject: [PATCH] =?UTF-8?q?fix(openapi):=20=E5=85=A5=E5=BA=93=E5=8D=95=20o?= =?UTF-8?q?wnerCode=20=E8=A1=A5=E9=BD=90=E5=88=B0=20qimen=5Fowner=5Fcode?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - OpenAPI 合约上下文的 customerId 恒为 null,导致 API 来源入库单 qimen_owner_code 为空、出站回传 entryorder.confirm 的 ownerCode 为空 - entryorder.create 改为用报文 entryOrder.ownerCode(trim 后)补齐 customerId, 落库口径与奇门侧一致(奇门侧取请求上下文 customerId) - 补充字段生效口径注释:warehouseCode 一律以 app_key 合约解析结果为准, operateTime / operatorName 当前未被底层消费,保留仅为兼容调用方 - 同步 methods/openapi.json 与 methods/changes/openapi.json(标准请求/响应 JSON 示例 + 字段生效口径说明) --- app/service/openapiMethods/entryorder.js | 13 ++- methods/changes/openapi.json | 31 +++++ methods/openapi.json | 141 +++++++++++++++++------ 3 files changed, 150 insertions(+), 35 deletions(-) diff --git a/app/service/openapiMethods/entryorder.js b/app/service/openapiMethods/entryorder.js index eef1e56..695658e 100644 --- a/app/service/openapiMethods/entryorder.js +++ b/app/service/openapiMethods/entryorder.js @@ -30,6 +30,10 @@ class OpenapiEntryorderService extends MainService { } // 字段映射:OpenAPI 风格字段名 → 底层 tryCreateEntryOrder 期望的字段名 + // 注意(2026-09-14):以下字段当前未被底层消费,保留仅为兼容调用方,勿据此判断生效: + // - warehouseCode:仓库上下文一律以 app_key 合约解析结果为准,报文值被忽略 + // - operateTime / operatorName:底层既不落库也不参与任何逻辑 + // 另:ownerCode 不通过本映射生效,由下方显式作为 customerId 传入(落 qimen_owner_code) const mappedEntryOrder = { entryOrderCode: entryOrder.entryOrderCode, orderType: entryOrder.entryOrderType || entryOrder.orderType || 'SCRK', @@ -58,9 +62,16 @@ class OpenapiEntryorderService extends MainService { }, }; + // 货主编码对齐奇门口径:奇门侧 qimen_owner_code 取自请求上下文 customerId + // (出站回传 entryorder.confirm 的 ownerCode 即取该列,见 buildEntryOrderConfirmRequest)。 + // OpenAPI 合约上下文的 customerId 恒为 null,会导致 API 来源入库单 qimen_owner_code 为空、 + // 回传 ownerCode 为空,故此处用报文 entryOrder.ownerCode 补齐(与奇门落库口径一致)。 + const info = this.getInfo(); + const ownerCode = String(entryOrder.ownerCode || '').trim(); + const res = await this.ctx.service.systems.entryOrder.addOrder( data, - this.getInfo(), + { ...info, customerId: ownerCode || info.customerId || '' }, 'API' ); diff --git a/methods/changes/openapi.json b/methods/changes/openapi.json index 3603be9..9674c0b 100644 --- a/methods/changes/openapi.json +++ b/methods/changes/openapi.json @@ -1,4 +1,35 @@ [ + { + "version": "2026.09.14-openapi-entryorder-standard-json", + "date": "2026-09-14", + "type": "updated", + "summary": "openapi entryorder.create 补充标准请求/响应 JSON:新增 requestExample(POST /openapi 的 query + headers + body 完整示例,含 entryOrder 全字段与 orderLines.orderLine 明细)与 responseExample(success 扁平响应 + businessFailure 业务失败响应两态),并追加说明性 notes。", + "methods": [ + "entryorder.create" + ], + "notes": [ + "requestExample 依据口径:entryOrder.ownerCode 落 wms_entry_order.qimen_owner_code;warehouseCode / operateTime / operatorName 当前未生效(保留字段);expectedArriveTime→expect_start_time、createTime→order_create_time、expectEndTime→expect_end_time、relatedOrders.relatedOrder.orderCode→purchase_order_code", + "responseExample 依据口径:/openapi 成功响应为扁平标准结构(flag/code/message + 业务字段 + timestamp),非 data 包裹;业务失败同样 HTTP 200 但 flag=failure、code=0;入口级失败(参数/时间戳/签名/合约)为 HTTP 400/401/403 + data:null", + "requestExample.query 中 sign 计算规则:canonicalQuery(query 去 sign 后按 key 字母序拼接)+ self_app_secret + md5(stableStringify(body)) 再取 md5(见 app/lib/api_sign.js)", + "两个新键为文档自描述键(self-describing),不参与运行时代码逻辑;update 脚本 upsert 为整条替换,spec 已从现有文档克隆完整 method 对象(含 params / requestBody / response / errors / notes),未丢字段" + ] + }, + { + "version": "2026.09.14-openapi-entryorder-owner-code-align", + "date": "2026-09-14", + "type": "updated", + "summary": "openapi entryorder.create 字段生效口径标注:明确 entryOrder.ownerCode 落库 wms_entry_order.qimen_owner_code(代码同步补齐,API 来源出站回传 entryorder.confirm 的 ownerCode 不再为空);标注 entryOrder.warehouseCode、entryOrder.operateTime、entryOrder.operatorName 当前未生效(仓库取 app_key 合约解析结果、后两者不落库不参与逻辑),保留字段不删除;补充主表/明细表落库列对照说明。", + "methods": [ + "entryorder.create" + ], + "notes": [ + "代码侧同步改动:app/service/openapiMethods/entryorder.js#create 将报文 entryOrder.ownerCode(trim 后)作为 customerId 传入 systems/entry_order.js#addOrder,最终落库 wms_entry_order.qimen_owner_code;奇门路径行为不变(仍取请求上下文 customerId)", + "口径依据:奇门侧 qimen_owner_code 取请求上下文 customerId,出站回传 buildEntryOrderConfirmRequest(receiving_entry_match.js)的 entryOrder.ownerCode 即取该列,此前 API 来源该列为空导致回传 ownerCode 为空", + "entryOrder.warehouseCode 在奇门侧参与合约校验(controller/home.js getQimenWarehouseCode + validateApi)并落 qimen_warehouse_code;OpenAPI 侧一律取合约 qimen_warehouse_code,报文值不生效", + "未变更:entryOrder.operateTime / operatorName 的映射保留在适配层,仅标注为当前未使用;本次不新增未登记参数项,避免扩大对外契约", + "文档写入流程:temp/api-doc-update-20260914-openapi-entryorder-field-annotation.json → npm run doc:api:update -- --spec=... --dry-run → 正式写入" + ] + }, { "version": "2026.09.12-openapi-order-cancel-rk-entry-order-support", "date": "2026-09-12", diff --git a/methods/openapi.json b/methods/openapi.json index 5bbc7ae..1b7364a 100644 --- a/methods/openapi.json +++ b/methods/openapi.json @@ -1,8 +1,8 @@ { "module": "openapi", "description": "开放 API 统一入口,独立链路,HTTP POST /openapi,记录入口校验/鉴权规则与返回格式。", - "version": "1.2.3", - "updatedAt": "2026-09-12", + "version": "1.2.5", + "updatedAt": "2026-09-14", "http": { "path": "/openapi", "method": "POST" @@ -1509,77 +1509,77 @@ "type": "string", "required": true, "source": "body", - "description": "入库单号(必填),外部系统的唯一入库单号" + "description": "入库单号(必填),外部系统的唯一入库单号,落库 wms_entry_order.entry_order_code" }, { "name": "entryOrder.entryOrderType", "type": "string", "required": false, "source": "body", - "description": "入库单类型,默认 SCRK(生产入库)" + "description": "入库单类型,默认 SCRK(生产入库),落库 wms_entry_order.order_type(兼容 entryOrder.orderType 传法)" }, { "name": "entryOrder.warehouseCode", "type": "string", "required": false, "source": "body", - "description": "仓库编码" + "description": "仓库编码。⚠️当前版本未生效:仓库上下文一律以 app_key 合约绑定的仓库为准(解析结果注入 storeId/warehouseId/qimen_warehouse_code),报文值被忽略,不参与落库与校验" }, { "name": "entryOrder.ownerCode", "type": "string", "required": false, "source": "body", - "description": "货主编码" + "description": "货主编码,落库 wms_entry_order.qimen_owner_code(出站回传 entryorder.confirm 的 entryOrder.ownerCode 即取该值);不传则落空串" }, { "name": "entryOrder.expectedArriveTime", "type": "string", "required": false, "source": "body", - "description": "预计到货时间,ISO 8601 格式" + "description": "预计到货时间,ISO 8601 格式,落库 wms_entry_order.expect_start_time(不传取当前时间;兼容 entryOrder.expectStartTime)" }, { "name": "entryOrder.totalOrderLines", "type": "number", "required": false, "source": "body", - "description": "总行数" + "description": "总行数,落库 wms_entry_order.total_order_lines(不传取明细行数)" }, { "name": "entryOrder.operateTime", "type": "string", "required": false, "source": "body", - "description": "操作时间,ISO 8601 格式" + "description": "操作时间,ISO 8601 格式。⚠️当前版本未生效:底层未落库、未参与任何逻辑(保留字段,仅为兼容调用方)" }, { "name": "entryOrder.operatorName", "type": "string", "required": false, "source": "body", - "description": "操作人" + "description": "操作人。⚠️当前版本未生效:底层未落库、未参与任何逻辑(保留字段,仅为兼容调用方)" }, { "name": "entryOrder.supplierCode", "type": "string", "required": false, "source": "body", - "description": "供应商编码" + "description": "供应商编码,落库 wms_entry_order.supplier_code" }, { "name": "entryOrder.supplierName", "type": "string", "required": false, "source": "body", - "description": "供应商名称" + "description": "供应商名称,落库 wms_entry_order.supplier_name" }, { "name": "entryOrder.remark", "type": "string", "required": false, "source": "body", - "description": "备注" + "description": "备注,落库 wms_entry_order.remark" }, { "name": "orderLines", @@ -1614,28 +1614,28 @@ "type": "string", "required": false, "source": "body", - "description": "商品名称,用于错误提示中的商品识别" + "description": "商品名称,用于错误提示中的商品识别。明细落库的 item_name/item_code/item_id/stock_id/owner_code 均取匹配到的 StockStore 值,非报文原值" }, { "name": "[].orderLine.planQty", "type": "number", "required": true, "source": "body", - "description": "计划入库数量(必填),必须大于 0" + "description": "计划入库数量(必填),必须大于 0,落库 wms_entry_items.count" }, { "name": "[].orderLine.inventoryType", "type": "string", "required": false, "source": "body", - "description": "库存类型,默认 ZP(正品)" + "description": "库存类型,默认 ZP(正品),落库 wms_entry_items.inventory_type" }, { "name": "[].orderLine.orderLineNo", "type": "string", "required": false, "source": "body", - "description": "行号" + "description": "行号,落库 wms_entry_items.order_line_no(不传按明细顺序 1..N)" } ], "requestBody": [ @@ -1651,77 +1651,77 @@ "type": "string", "required": true, "source": "body", - "description": "入库单号(必填),外部系统的唯一入库单号" + "description": "入库单号(必填),外部系统的唯一入库单号,落库 wms_entry_order.entry_order_code" }, { "name": "entryOrder.entryOrderType", "type": "string", "required": false, "source": "body", - "description": "入库单类型,默认 SCRK(生产入库)" + "description": "入库单类型,默认 SCRK(生产入库),落库 wms_entry_order.order_type(兼容 entryOrder.orderType 传法)" }, { "name": "entryOrder.warehouseCode", "type": "string", "required": false, "source": "body", - "description": "仓库编码" + "description": "仓库编码。⚠️当前版本未生效:仓库上下文一律以 app_key 合约绑定的仓库为准(解析结果注入 storeId/warehouseId/qimen_warehouse_code),报文值被忽略,不参与落库与校验" }, { "name": "entryOrder.ownerCode", "type": "string", "required": false, "source": "body", - "description": "货主编码" + "description": "货主编码,落库 wms_entry_order.qimen_owner_code(出站回传 entryorder.confirm 的 entryOrder.ownerCode 即取该值);不传则落空串" }, { "name": "entryOrder.expectedArriveTime", "type": "string", "required": false, "source": "body", - "description": "预计到货时间,ISO 8601 格式" + "description": "预计到货时间,ISO 8601 格式,落库 wms_entry_order.expect_start_time(不传取当前时间;兼容 entryOrder.expectStartTime)" }, { "name": "entryOrder.totalOrderLines", "type": "number", "required": false, "source": "body", - "description": "总行数" + "description": "总行数,落库 wms_entry_order.total_order_lines(不传取明细行数)" }, { "name": "entryOrder.operateTime", "type": "string", "required": false, "source": "body", - "description": "操作时间,ISO 8601 格式" + "description": "操作时间,ISO 8601 格式。⚠️当前版本未生效:底层未落库、未参与任何逻辑(保留字段,仅为兼容调用方)" }, { "name": "entryOrder.operatorName", "type": "string", "required": false, "source": "body", - "description": "操作人" + "description": "操作人。⚠️当前版本未生效:底层未落库、未参与任何逻辑(保留字段,仅为兼容调用方)" }, { "name": "entryOrder.supplierCode", "type": "string", "required": false, "source": "body", - "description": "供应商编码" + "description": "供应商编码,落库 wms_entry_order.supplier_code" }, { "name": "entryOrder.supplierName", "type": "string", "required": false, "source": "body", - "description": "供应商名称" + "description": "供应商名称,落库 wms_entry_order.supplier_name" }, { "name": "entryOrder.remark", "type": "string", "required": false, "source": "body", - "description": "备注" + "description": "备注,落库 wms_entry_order.remark" }, { "name": "orderLines", @@ -1756,28 +1756,28 @@ "type": "string", "required": false, "source": "body", - "description": "商品名称" + "description": "商品名称,用于错误提示中的商品识别。明细落库的 item_name/item_code/item_id/stock_id/owner_code 均取匹配到的 StockStore 值,非报文原值" }, { "name": "[].orderLine.planQty", "type": "number", "required": true, "source": "body", - "description": "计划入库数量(必填),必须大于 0" + "description": "计划入库数量(必填),必须大于 0,落库 wms_entry_items.count" }, { "name": "[].orderLine.inventoryType", "type": "string", "required": false, "source": "body", - "description": "库存类型,默认 ZP(正品)" + "description": "库存类型,默认 ZP(正品),落库 wms_entry_items.inventory_type" }, { "name": "[].orderLine.orderLineNo", "type": "string", "required": false, "source": "body", - "description": "行号" + "description": "行号,落库 wms_entry_items.order_line_no(不传按明细顺序 1..N)" } ], "response": [ @@ -1831,8 +1831,81 @@ "带中文后缀的编码(如 6934864201409-新品)精确匹配不到时按归一化条码对齐;归一化条码命中多个商品时报错,不静默取第一条", "item_id 统一写入实际匹配到的 StockStore 数字主键 id,避免非数字值写入 BIGINT 列触发 MySQL 严格模式报错(Data truncated for column 'item_id')", "失败信息回显真实 SKU/商品/编码并附订单行号;与奇门渠道共用 app/service/systems/entry_order.js addOrder 同一逻辑", - "timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400" - ] + "timestamp 时间戳时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),否则返回 400", + "字段生效口径(2026-09-14 核账):entryOrder.ownerCode → wms_entry_order.qimen_owner_code(出站回传 entryorder.confirm 的 ownerCode 取该值,代码已将报文 ownerCode 作为 customerId 传入 addOrder);entryOrder.entryOrderType → order_type(默认 SCRK);entryOrder.expectedArriveTime → expect_start_time;entryOrder.createTime → order_create_time;entryOrder.relatedOrders.relatedOrder.orderCode → purchase_order_code;entryOrder.logisticsCode / logisticsName / expressCode → logistics_code / logistics_name / express_code(当前未在参数表登记,代码已支持)", + "当前未生效字段(保留兼容,勿据此判断):entryOrder.warehouseCode(仓库上下文一律以 app_key 合约解析结果为准,报文值被忽略)、entryOrder.operateTime / entryOrder.operatorName(底层未落库、未参与任何逻辑)", + "标准请求/响应 JSON 见本条目 requestExample(query + headers + body)与 responseExample(success / businessFailure)两个键;两者为 2026-09-14 新增的自描述键,仅存于文档原始 JSON,未参与运行时代码逻辑" + ], + "requestExample": { + "query": "app_key=YOUR_APP_KEY&method=entryorder.create&v=1.0×tamp=1757865600&sign=", + "headers": { + "Content-Type": "application/json" + }, + "body": { + "entryOrder": { + "entryOrderCode": "TEST-RK-202609140001", + "entryOrderType": "SCRK", + "ownerCode": "OWNER001", + "warehouseCode": "", + "expectedArriveTime": "2026-09-15 10:00:00", + "expectEndTime": "2026-09-16 18:00:00", + "orderCreateTime": "2026-09-14 09:30:00", + "totalOrderLines": 2, + "supplierCode": "SUP001", + "supplierName": "示例供应商", + "logisticsCode": "SF", + "logisticsName": "顺丰速运", + "expressCode": "SF1234567890", + "remark": "openapi 入库单标准示例", + "relatedOrders": { + "relatedOrder": { + "orderCode": "PO-20260914-001" + } + }, + "operateTime": "", + "operatorName": "" + }, + "orderLines": { + "orderLine": [ + { + "orderLineNo": "1", + "itemCode": "SKU001", + "itemId": 10001, + "itemName": "示例商品A", + "planQty": 10, + "inventoryType": "ZP" + }, + { + "orderLineNo": "2", + "itemCode": "SKU002", + "itemId": 10002, + "itemName": "示例商品B", + "planQty": 5, + "inventoryType": "ZP" + } + ] + } + } + }, + "responseExample": { + "success": { + "flag": "success", + "code": 1, + "message": "入库单创建完成", + "createTime": "2026-09-14 09:30:00", + "entryOrderId": 88, + "entryOrderCode": "TEST-RK-202609140001", + "status": "CREATED", + "timestamp": 1757865600 + }, + "businessFailure": { + "flag": "failure", + "code": 0, + "message": "创建入库单失败,失败原因:\n订单行1:SKU10001商品《示例商品A》编码《SKU001》\n未同步推送到仓库", + "createTime": "2026-09-14 09:30:00", + "timestamp": 1757865600 + } + } }, { "method": "entryorder.query",