WMS_MAIN/methods/changes/openapi.json
liufumingren f8915a5733 fix(openapi/storage): 修复服务命名冲突、完善导入入库收货单占用与入库单详情字段
- openapi.js 重命名为 openapiEntry.js,消除与 openapi/ 目录同名冲突,恢复 ctx.service.openapi.callback 可用,修复 quickInbound API 回传报 Cannot read properties of undefined (reading 'sendWithRetry')
- 导入/PDA 入库 commit 新增非绑定模式收货单占用:带 receiving_detail_id 的记录优先按明细扣减,剩余导入量按 stock_id 匹配绑定收货单明细占用并回写收货单入库状态
- storage.entry.get 响应新增 total_order_lines / total_quantity / received_quantity 字段
- 同步 AI_METHOD_ROUTING.md 与 methods/changes 变更记录
2026-08-27 17:58:52 +08:00

327 lines
19 KiB
JSON
Raw 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.08.27-openapi-service-conflict-fix",
"date": "2026-08-27",
"summary": "修复 Egg 服务命名冲突:app/service/openapi.js 重命名为 openapiEntry.js,恢复 ctx.service.openapi.callback 可用",
"methods": [],
"notes": [
"根因:app/service/openapi.js 文件与 app/service/openapi/ 目录同名,Egg ContextLoader 把目录里的 callback/callbackRegistry 挂成 OpenapiService 类的静态属性,实例上不可见,导致运行时 ctx.service.openapi.callback 为 undefined",
"修复:openapi.js 重命名为 openapiEntry.js(服务路径 ctx.service.openapiEntry),app/controller/openapi.js 的 processRequest 引用同步更新,AI_METHOD_ROUTING.md 同步",
"影响:storage.entry.quickInbound 对 API 来源直入单回传 entry_order_direct_inbound_completed 事件不再报 Cannot read properties of undefined (reading 'sendWithRetry'),库存两段式(先回传后写库)可正常执行"
],
"type": "fixed"
},
{
"version": "2026.06.04-openapi-04",
"date": "2026-06-04",
"summary": "文档结构优化:拆分 endpoints 为 methods.groups 多分组(基础模块 / 发货单模块)",
"methods": [],
"notes": [
"将单一 endpoints 数组重构为 methods.groups 多分组结构",
"基础模块:index.ping",
"发货单模块:deliveryorder.create、deliveryorder.query",
"移除顶层 groupName 字段,分组名改由各 group 独立声明"
],
"type": "modified"
},
{
"version": "2026.06.04-openapi-03",
"date": "2026-06-04",
"summary": "新增 deliveryorder.create 和 deliveryorder.query 方法文档",
"methods": [
"deliveryorder.create",
"deliveryorder.query"
],
"notes": [
"新增 deliveryorder.create:创建发货单接口,支持订单主信息、收件人信息、订单明细的完整入参;创建渠道为 API,平台/快递自动匹配",
"新增 deliveryorder.query:查询发货单接口,根据 deliveryOrderCode 查询订单详情",
"所有参数使用驼峰命名(camelCase),不做下划线兼容",
"requestBody 字段按 deliveryOrder.xxx、deliveryOrder.receiverInfo.xxx、orderLines.orderLine、[].orderLine.xxx 层级清晰标注"
],
"type": "added"
},
{
"version": "2026.06.04-openapi-02",
"date": "2026-06-04",
"summary": "移除 ping.echo 和 index.health,只保留 index.ping",
"methods": [
"ping.echo",
"index.health"
],
"notes": [
"移除 ping.echo:回显接口暂不对外开放",
"移除 index.health:健康检查接口暂不对外开放",
"当前仅保留 index.ping 心跳接口"
],
"type": "removed"
},
{
"version": "2026.06.04-openapi-01",
"date": "2026-06-04",
"summary": "移除入口方法 openapi.index,新增 index.health 和 ping.echo 方法文档",
"methods": [
"openapi.index",
"index.health",
"ping.echo"
],
"notes": [
"移除 openapi.index:该方法是 POST /openapi 的入口端点,非业务方法,从文档中移除",
"新增 index.health:基础模块健康检查接口,返回 openapiMethods 模块状态",
"新增 ping.echo:ping 模块回显接口,将请求体原样返回,用于调试连通性和签名验证"
],
"type": "modified"
},
{
"version": "2026.04.26-openapi-01",
"date": "2026-04-26",
"summary": "新增 openapi 入口文档骨架(/openapi),包含请求体解析、app_key 与签名校验规则",
"methods": [
"openapi.index"
],
"notes": [
"新增 methods/openapi.json:记录 /openapi 入口的文档骨架与校验约定(JSON body 解析、统一错误格式、app_key 校验、签名规则)。",
"核心校验规则:1) body 使用 JSON 解析,优先 rawBody;2) 错误对外格式使用 toFailure(flag/code/message/data/timestamp);3) app_key 仅当数据库记录的 interface_type_id=2 且 is_enabled=1 时视为有效;4) 签名按 query 字段字母序排序(排除 sign/signature)+ selfAppSecret + bodySign(md5(stableSerialize(body))),对拼接字符串取 md5。"
],
"type": "added"
},
{
"version": "2026.04.26-openapi-02",
"date": "2026-04-26",
"summary": "说明:/openapi 入口不校验请求头,补充签名别名与 app_key 有效性说明",
"methods": [
"openapi.index"
],
"notes": [
"修正:明确 /openapi 入口不对请求头进行强制校验(与 qimen 一致),headers 字段仅作为参考。",
"确认:body JSON 解析(rawBody 优先)与错误消息保持为 'json数据为空' / 'json数据解析错误';app_key 校验仅当 wms_api_app.interface_type_id=2 且 is_enabled=1 时有效。",
"补充:签名字段别名说明(sign/signature)与 app_key 别名(app_key/appkey/self_app_key);签名算法与实现参见 app/lib/api_sign.js。"
],
"type": "modified"
},
{
"version": "2026.04.26-openapi-03",
"date": "2026-04-26",
"summary": "新增 openapi 方法 index.ping(基础模块,心跳接口)",
"methods": [
"index.ping"
],
"notes": [
"新增 openapi 可用性检测接口 index.ping,返回与系统成功结构一致(包含 code/message/data)。"
],
"type": "added"
},
{
"version": "2026.04.26-openapi-04",
"date": "2026-04-26",
"summary": "规范化 /openapi 文档:独立链路、移除请求头校验、返回风格改为 code/message/data、明确签名与 app_key 校验、指向 openapiMethods 分发。",
"methods": [
"openapi.index",
"index.ping"
],
"notes": [
"本次变更:",
"1) 明确 /openapi 为独立链路,不复用 system/qimen 的请求头校验;",
"2) 移除 platform/project 等请求头的强校验说明;",
"3) 返回结构与 system 风格对齐(使用 code/message/data,移除额外 flag 字段);",
"4) 保持 body 为 JSON(rawBody 优先),并明确错误文案为 'json数据为空' / 'json数据解析错误';",
"5) 明确 app_key 仅当 wms_api_app.interface_type_id=2 且 is_enabled=1 时视为有效;",
"6) 明确签名算法:query 按字母序排序 + self_app_secret + bodySign(md5(stableSerialize(body))),支持别名 sign/signature 与 app_key/appkey/self_app_key;",
"7) 说明 method 分发走 openapiMethods 专用目录,示例方法 index.ping(基础模块)。"
],
"type": "modified"
},
{
"version": "2026.06.04-openapi-05",
"date": "2026-06-04",
"summary": "新增订单模块 order.cancel 方法",
"methods": [
"order.cancel"
],
"notes": [
"新增 order.cancel:取消发货单接口,支持直接取消未拣货/未打印的订单;已拣货或已打印的改为拦截状态",
"当前支持 JYCK(一般交易出库)、HHCK(换货出库)、BFCK(补发出库)三种出库单类型",
"取消操作为不可逆操作"
],
"type": "added"
},
{
"version": "2026.06.04-openapi-06",
"date": "2026-06-04",
"summary": "补齐 deliveryorder.create、deliveryorder.query、order.cancel 的 params 入参文档",
"methods": [
"deliveryorder.create",
"deliveryorder.query",
"order.cancel"
],
"notes": [
"为三个方法的 params 数组补充标准 OpenAPI query 参数:method、v、timestamp、app_key、sign"
],
"type": "modified"
},
{
"version": "2026.06.04-openapi-07",
"date": "2026-06-04",
"summary": "修正 params 字段:从 query 签名参数改为 POST body 业务参数(与 requestBody 保持一致)",
"methods": [
"deliveryorder.create",
"deliveryorder.query",
"order.cancel"
],
"notes": [
"params 现包含 POST body 的业务入参(与 requestBody 一致),query 签名参数已通过页面顶部签名说明覆盖"
],
"type": "modified"
},
{
"version": "2026.06.04-openapi-08",
"date": "2026-06-04",
"summary": "新增商品模块 singleitem.synchronize 和 singleitem.query 方法",
"methods": [
"singleitem.synchronize",
"singleitem.query"
],
"notes": [
"新增 singleitem.synchronize:商品同步接口,按 itemCode 唯一约束创建或更新商品信息,联动库存表",
"新增 singleitem.query:商品查询接口,按 itemId 返回完整商品信息",
"所有参数使用驼峰命名(camelCase)"
],
"type": "added"
},
{
"version": "2026.06.04-openapi-09",
"date": "2026-06-04",
"summary": "singleitem.synchronize 的 warehouseCode 改为从 app_key 自动解析,不再要求调用方必传",
"methods": [
"singleitem.synchronize"
],
"notes": [
"warehouseCode 改为可选参数,默认从 app_key 绑定的仓库(api_app.qimen_warehouse_code)自动解析",
"ownerCode 同步改为可选参数"
],
"type": "modified"
},
{
"version": "2026.06.04-openapi-10",
"date": "2026-06-04",
"summary": "安全加固:移除 singleitem.synchronize 的 warehouseCode 和 ownerCode 入参,完全由 app_key 自动解析",
"methods": [
"singleitem.synchronize"
],
"notes": [
"warehouseCode 和 ownerCode 从 params 中移除,调用方不可传入或覆盖",
"两个字段完全由服务端根据 app_key 自动解析,确保仓库/货主绑定关系不可被篡改"
],
"type": "modified"
},
{
"version": "2026.06.04-openapi-11",
"date": "2026-06-04",
"summary": "新增库存模块 inventory.query 方法",
"methods": [
"inventory.query"
],
"notes": [
"新增 inventory.query:批量库存查询接口,按商品 ID 列表返回可用量和锁定量",
"支持批量查询,减少请求次数",
"库存不足的商品不会出现在返回结果中"
],
"type": "added"
},
{
"version": "2026.06.04-openapi-12",
"date": "2026-06-04",
"summary": "新增回调模块 callback.test 方法及统一回调通知系统",
"methods": [
"callback.test"
],
"notes": [
"新增 callback.test:模拟回调测试接口,向 callback_url 发送签名回调",
"新增 app/service/openapi/callback.js:统一回调服务,支持签名+重试+日志",
"订单同步完成时自动触发 API 渠道回调(fire-and-forget,不影响主流程)",
"回调签名算法与 OpenAPI 入口完全一致"
],
"type": "added"
},
{
"version": "2026.06.04-openapi-13",
"date": "2026-06-04",
"summary": "移除回调模块(回调测试改为独立页面 /docs/api/openapi/callback-test)",
"methods": [
"callback.test"
],
"notes": [
"回调测试不再作为 OpenAPI method,改为独立路由页面 /docs/api/openapi/callback-test",
"页面支持下拉选择注册事件、填入测试 URL、前端计算签名、模拟回调推送",
"回调事件注册表位于 app/service/openapi/callbackRegistry.js"
],
"type": "removed"
},
{
"version": "2026.06.05-openapi-14",
"date": "2026-06-05",
"summary": "增加 timestamp 时效校验(±10分钟),超时返回 400",
"methods": [],
"notes": [
"所有 OpenAPI 方法增加 timestamp 与服务器时间差校验,超过 ±10 分钟返回 400",
"docs.js 签名说明区同步更新注意事项"
],
"type": "modified"
},
{
"version": "2026.06.05-openapi-15",
"date": "2026-06-05",
"summary": "deliveryorder.create 收件人信息改为必填(name/mobile/province/city/area/detailAddress)",
"methods": [
"deliveryorder.create"
],
"notes": [
"receiverInfo 6个字段改为必填,避免快递取号时因地址缺失失败",
"mobile 和 tel 二选一必填"
],
"type": "modified"
},
{
"version": "2026.06.17-openapi-16",
"date": "2026-06-17",
"summary": "新增入库单模块(entryorder),支持 create(创建入库单)和 query(查询入库单)两个方法",
"methods": [
"entryorder.create",
"entryorder.query"
],
"notes": [
"新增 entryorder.create:创建入库单接口,支持入库单主信息(entryOrder)和商品明细(orderLines.orderLine)的完整入参;创建渠道固定为 API",
"新增 entryorder.query:查询入库单接口,根据 entryOrderCode 查询入库单详情,返回基本信息及商品明细",
"itemCode 与 itemId 二选一,优先使用 itemId",
"openapi 通道新增入库单创建和查询能力"
],
"type": "added"
},
{
"version": "2026.06.23-openapi-01",
"date": "2026-06-23",
"summary": "入库单新增 CREATED 状态:entryorder.create 返回 status 说明更新为 CREATING=创建中/CREATED=已创建;entryorder.query 返回 status 可能值补充 CREATED",
"methods": [
"entryorder.create",
"entryorder.query"
],
"notes": [
"entryorder.create response data.status 说明从通用描述更新为 CREATING=创建中明细行未全部插入 / CREATED=已创建完成",
"entryorder.query description 补充返回的 status 可能为 CREATING/CREATED/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED"
],
"type": "updated",
"module": "entryorder"
},
{
"version": "2026.06.23-openapi-02",
"date": "2026-06-23",
"summary": "入库单状态从 7 个简化为 5 个:移除 CONFIRMED 和 PARTIAL_RECEIVED,entryorder.query 的 status 枚举同步更新为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED",
"methods": [
"entryorder.query"
],
"notes": [
"entryorder.query description 中 status 枚举从 CREATING/CREATED/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED 简化为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED,与 wms_entry_order.order_status ENUM 当前定义一致"
],
"type": "updated"
}
]