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:
liufumingren 2026-09-15 16:19:10 +08:00
parent 4edfd951c5
commit 4d8297aecb
3 changed files with 150 additions and 35 deletions

View File

@ -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'
);

View File

@ -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",

View File

@ -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&timestamp=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",