[ { "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" } ]