fix(openapi): 入库单 ownerCode 补齐到 qimen_owner_code
- 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 示例 + 字段生效口径说明)
This commit is contained in:
parent
4edfd951c5
commit
4d8297aecb
@ -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'
|
||||
);
|
||||
|
||||
|
||||
@ -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",
|
||||
|
||||
@ -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=<MD5(canonicalQuery+self_app_secret+md5(stableStringify(body)))>",
|
||||
"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",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user