diff --git a/app/controller/inbox.js b/app/controller/inbox.js new file mode 100644 index 0000000..239cdc8 --- /dev/null +++ b/app/controller/inbox.js @@ -0,0 +1,127 @@ +'use strict'; + +const { Controller } = require('egg'); +const { toSuccess, toFailure } = require('../lib/api_response'); + +/** + * 站内信内部管理接口控制器。 + * 提供消息列表、详情、对话链、回信、重推、统计等管理功能。 + */ +class InboxController extends Controller { + /** + * 获取当前仓库上下文。 + * @return {{ warehouseId: number }} 仓库上下文。 + */ + getWarehouseContext() { + const { ctx } = this; + const warehouseId = Number(ctx.user && ctx.user.store_id); + + if (!Number.isFinite(warehouseId) || warehouseId <= 0) { + throw new Error('缺少仓库信息'); + } + + return { warehouseId }; + } + + /** + * 内部管理统一入口,分发到对应 service 方法。 + * @return {Promise} 无返回值,结果写入 ctx.body。 + */ + async index() { + const { ctx } = this; + + try { + const method = String(ctx.request.body && ctx.request.body.method || '').trim(); + if (!method || !method.startsWith('inbox.')) { + ctx.status = 400; + ctx.body = toFailure({ message: 'method 参数无效' }); + ctx.type = 'application/json'; + return; + } + + const action = method.replace('inbox.', ''); + const data = (ctx.request.body && ctx.request.body.data) || {}; + + let result; + + switch (action) { + case 'list': { + const { warehouseId } = this.getWarehouseContext(); + result = await ctx.service.inbox.index.list({ + warehouseId, + ...data, + }); + break; + } + + case 'detail': { + const { warehouseId } = this.getWarehouseContext(); + result = await ctx.service.inbox.index.detail({ + warehouseId, + id: data.id, + }); + break; + } + + case 'thread': { + const { warehouseId } = this.getWarehouseContext(); + result = await ctx.service.inbox.index.thread({ + warehouseId, + id: data.id, + }); + break; + } + + case 'reply': { + const { warehouseId } = this.getWarehouseContext(); + result = await ctx.service.inbox.index.reply({ + warehouseId, + parentId: data.parentId, + targetChannel: data.targetChannel, + targetUrl: data.targetUrl, + targetType: data.targetType, + refCode: data.refCode, + extData: data.extData, + flags: data.flags, + }); + break; + } + + case 'retry': { + const { warehouseId } = this.getWarehouseContext(); + result = await ctx.service.inbox.index.retry({ + warehouseId, + id: data.id, + }); + break; + } + + case 'stats': { + const { warehouseId } = this.getWarehouseContext(); + result = await ctx.service.inbox.index.stats({ + warehouseId, + direction: data.direction, + }); + break; + } + + default: + ctx.status = 400; + ctx.body = toFailure({ message: `不支持的 inbox 方法: ${action}` }); + ctx.type = 'application/json'; + return; + } + + ctx.status = 200; + ctx.body = toSuccess(result, 'ok'); + ctx.type = 'application/json'; + } catch (error) { + const message = String(error && error.message || '请求失败'); + ctx.status = 500; + ctx.body = toFailure({ message: `站内信错误: ${message}` }); + ctx.type = 'application/json'; + } + } +} + +module.exports = InboxController; diff --git a/app/model/inbox_message.js b/app/model/inbox_message.js new file mode 100644 index 0000000..6a43ce1 --- /dev/null +++ b/app/model/inbox_message.js @@ -0,0 +1,190 @@ +'use strict'; + +/** + * 站内信消息 Model。 + * 统一管理消息推送状态追踪:谁发来的、要推到哪、推送状态。 + * inbound(外部→WMS)与 outbound(WMS→外部)共表,direction + parent_id 形成对话链。 + * @param {Object} app Egg.js Application 实例。 + * @return {Object} Sequelize Model 定义。 + */ +module.exports = app => { + const { BIGINT, STRING, TINYINT, DATE, INTEGER, JSON: JSON_TYPE } = app.Sequelize; + + const InboxMessage = app.model.define('inbox_message', { + id: { + type: BIGINT.UNSIGNED, + primaryKey: true, + autoIncrement: true, + allowNull: false, + comment: '主键ID', + }, + ext_id: { + type: STRING(128), + allowNull: false, + comment: '外部唯一消息主键(IM msgId / API requestId 等),用于幂等去重', + }, + warehouse_id: { + type: BIGINT.UNSIGNED, + allowNull: false, + comment: '所属仓库ID', + }, + store_id: { + type: BIGINT.UNSIGNED, + allowNull: true, + comment: '关联货主ID', + }, + direction: { + type: STRING(10), + allowNull: false, + defaultValue: 'inbound', + validate: { + isIn: { + args: [[ 'inbound', 'outbound' ]], + msg: 'direction 必须是 inbound 或 outbound', + }, + }, + comment: '消息方向:inbound=外部→WMS收件 / outbound=WMS→外部回信', + }, + parent_id: { + type: BIGINT.UNSIGNED, + allowNull: true, + comment: '关联消息ID(回信时指向原消息,形成对话链)', + }, + source_type: { + type: STRING(20), + allowNull: false, + validate: { + isIn: { + args: [[ 'im', 'api', 'system' ]], + msg: 'source_type 必须是 im、api 或 system', + }, + }, + comment: '来源类型:im / api / system', + }, + source_extra: { + type: STRING(100), + allowNull: true, + comment: '来源附加信息(IM 平台 / API app_id)', + }, + target_type: { + type: STRING(20), + allowNull: false, + validate: { + isIn: { + args: [[ 'im', 'api', 'webhook' ]], + msg: 'target_type 必须是 im、api 或 webhook', + }, + }, + comment: '目标类型:im / api / webhook', + }, + target_channel: { + type: STRING(50), + allowNull: false, + validate: { + notEmpty: { + msg: 'target_channel 不能为空', + }, + }, + comment: '目标渠道:wecom / dingtalk / feishu / warehouse_api / webhook', + }, + target_url: { + type: STRING(500), + allowNull: false, + validate: { + notEmpty: { + msg: 'target_url 不能为空', + }, + len: { + args: [ 1, 500 ], + msg: 'target_url 长度应在1-500个字符之间', + }, + }, + comment: '推送目标URL(IM Bot webhook 地址 / API 回调地址)', + }, + ref_code: { + type: STRING(100), + allowNull: true, + comment: '外部引用编码,推送/回执时原样携带', + }, + ext_data: { + type: JSON_TYPE, + allowNull: true, + comment: '外部透传数据,外部传入任意JSON,WMS不解析,回信时原样返回', + }, + flags: { + type: JSON_TYPE, + allowNull: true, + comment: '处理标记,外部传入控制WMS处理行为', + }, + push_status: { + type: TINYINT(4), + allowNull: false, + defaultValue: 0, + validate: { + isIn: { + args: [[ 0, 1, 2, 3 ]], + msg: 'push_status 必须是 0(待推送)、1(推送中)、2(已送达)、3(失败)', + }, + }, + comment: '推送状态:0=待推送 1=推送中 2=已送达 3=失败', + }, + push_started_at: { + type: DATE, + allowNull: true, + comment: '开始推送时间(僵尸检测:超5分钟仍为1则重置为0)', + }, + retry_count: { + type: INTEGER(11), + allowNull: false, + defaultValue: 0, + comment: '已重试次数', + }, + push_response: { + type: JSON_TYPE, + allowNull: true, + comment: '目标响应(http_status, body, error)', + }, + pushed_at: { + type: DATE, + allowNull: true, + comment: '推送完成时间', + }, + work_order_id: { + type: BIGINT.UNSIGNED, + allowNull: true, + comment: '关联工单ID(预留)', + }, + work_order_no: { + type: STRING(50), + allowNull: true, + comment: '工单号(预留)', + }, + created_at: { + type: DATE, + allowNull: false, + defaultValue: app.Sequelize.literal('CURRENT_TIMESTAMP'), + comment: '创建时间', + }, + updated_at: { + type: DATE, + allowNull: false, + defaultValue: app.Sequelize.literal('CURRENT_TIMESTAMP'), + comment: '更新时间', + }, + deleted_at: { + type: DATE, + allowNull: true, + comment: '软删除时间', + }, + }, { + tableName: 'wms_inbox_message', + timestamps: true, + createdAt: 'created_at', + updatedAt: 'updated_at', + deletedAt: 'deleted_at', + paranoid: true, + comment: '站内信消息推送状态追踪表', + }); + + return InboxMessage; +}; diff --git a/app/router.js b/app/router.js index b437fe3..cf6fb6b 100644 --- a/app/router.js +++ b/app/router.js @@ -67,4 +67,7 @@ module.exports = app => { router.get('/testSendData', controller.home.testSendData); // IM交互入口 router.post('/im', controller.im.index); + + // 站内信内部管理接口 + router.post('/inbox', controller.inbox.index); }; diff --git a/app/service/inbox/dispatch/base.js b/app/service/inbox/dispatch/base.js new file mode 100644 index 0000000..eb6ff61 --- /dev/null +++ b/app/service/inbox/dispatch/base.js @@ -0,0 +1,118 @@ +'use strict'; + +const Service = require('egg').Service; +const apiSignLib = require('../../../lib/api_sign'); + +const WAREHOUSE_INTERFACE_TYPE_ID = 3; +const DISPATCH_TIMEOUT_MS = 10000; // 10s 超时 + +/** + * 统一出站基类,所有渠道 dispatch 继承此类。 + * 统一处理:查密钥、签名、发 HTTP。 + * 子类只需实现 push(record) 方法,关注消息格式转换。 + */ +class OutboundBase extends Service { + /** + * 获取仓库 ApiApp 密钥配置(IM 渠道无需签名,返回 null)。 + * @param {number} warehouseId 仓库ID。 + * @return {Promise} ApiApp 配置对象,含 appKey / selfAppSecret / warehouseId。 + */ + async getApiApp(warehouseId) { + const { ctx } = this; + try { + // 通过仓库ID查找该仓库的 warehouse 类型 ApiApp + const apiApp = await ctx.model.ApiApp.findOne({ + attributes: [ 'id', 'self_app_key', 'self_app_secret', 'is_enabled', 'interface_type_id', 'warehouse_id' ], + where: { + warehouse_id: warehouseId, + interface_type_id: WAREHOUSE_INTERFACE_TYPE_ID, + is_enabled: 1, + }, + raw: true, + }); + + if (!apiApp || !apiApp.self_app_secret) { + return null; + } + + return { + appKey: apiApp.self_app_key, + selfAppSecret: apiApp.self_app_secret, + warehouseId: Number(apiApp.warehouse_id), + }; + } catch (error) { + ctx.logger.warn(`[inbox dispatch] 获取仓库 ApiApp 失败: ${error.message}`); + return null; + } + } + + /** + * 生成 MD5 签名,返回带签名后的完整 URL。 + * @param {string} url 原始目标URL。 + * @param {*} body 请求体。 + * @param {Object} secret ApiApp 密钥对象,含 appKey / selfAppSecret。 + * @return {string} 带签名的完整URL。 + */ + signRequest(url, body, secret) { + const timestamp = Math.floor(Date.now() / 1000); + const query = { + app_key: secret.appKey, + timestamp, + }; + + const { sign } = apiSignLib.signRequest({ + query, + body, + selfAppSecret: secret.selfAppSecret, + }); + + const separator = url.includes('?') ? '&' : '?'; + return `${url}${separator}app_key=${encodeURIComponent(query.app_key)}×tamp=${timestamp}&sign=${encodeURIComponent(sign)}`; + } + + /** + * 统一 HTTP POST 发送。 + * @param {string} url 目标URL。 + * @param {*} body 请求体。 + * @param {Object} [options] 额外选项。 + * @param {Object} [options.headers] 自定义请求头。 + * @return {Promise<{status: number, data: *}>} 响应结果。 + */ + async post(url, body, options = {}) { + const { ctx } = this; + const headers = { + 'Content-Type': 'application/json', + ...(options.headers || {}), + }; + + try { + const response = await ctx.curl(url, { + method: 'POST', + dataType: 'json', + contentType: 'json', + data: body, + headers, + timeout: DISPATCH_TIMEOUT_MS, + }); + + return { + status: response.status, + data: response.data, + }; + } catch (error) { + throw new Error(`HTTP 推送失败: ${error.message}`); + } + } + + /** + * 子类必须实现的推送方法。 + * @param {Object} record 消息记录(Sequelize Model 实例),子类按需使用。 + * @throws {Error} 子类未实现时抛出。 + */ + async push(record) { + const id = record && record.id; + throw new Error(`子类必须实现 push(record) 方法,当前消息ID: ${id || '未知'}`); + } +} + +module.exports = OutboundBase; diff --git a/app/service/inbox/dispatch/dingtalk.js b/app/service/inbox/dispatch/dingtalk.js new file mode 100644 index 0000000..aab3df4 --- /dev/null +++ b/app/service/inbox/dispatch/dingtalk.js @@ -0,0 +1,35 @@ +'use strict'; + +const OutboundBase = require('./base'); + +/** + * 钉钉 Bot 渠道出站实现。 + * 推送 Markdown 消息到钉钉机器人 webhook。 + */ +class DingtalkDispatch extends OutboundBase { + /** + * 通过钉钉 Bot 推送消息。 + * @param {Object} record 消息记录(Sequelize Model 实例)。 + * @return {Promise<{status: number, data: *}>} 推送响应。 + */ + async push(record) { + const { ctx } = this; + + const extData = record.ext_data || {}; + const title = extData.title || '新消息通知'; + const text = extData.content || extData.text || `消息:${record.ref_code || record.ext_id}`; + + const body = { + msgtype: 'markdown', + markdown: { + title, + text: typeof text === 'string' ? text : JSON.stringify(text), + }, + }; + + ctx.logger.info(`[inbox dingtalk] 推送消息 ext_id=${record.ext_id} url=${record.target_url}`); + return await this.post(record.target_url, body); + } +} + +module.exports = DingtalkDispatch; diff --git a/app/service/inbox/dispatch/feishu.js b/app/service/inbox/dispatch/feishu.js new file mode 100644 index 0000000..26b5358 --- /dev/null +++ b/app/service/inbox/dispatch/feishu.js @@ -0,0 +1,60 @@ +'use strict'; + +const OutboundBase = require('./base'); + +/** + * 飞书 Bot 渠道出站实现。 + * 推送交互式卡片消息到飞书机器人 webhook。 + */ +class FeishuDispatch extends OutboundBase { + /** + * 通过飞书 Bot 推送消息。 + * @param {Object} record 消息记录(Sequelize Model 实例)。 + * @return {Promise<{status: number, data: *}>} 推送响应。 + */ + async push(record) { + const { ctx } = this; + + const extData = record.ext_data || {}; + const title = extData.title || '新消息通知'; + const content = extData.content || extData.text || `消息:${record.ref_code || record.ext_id}`; + + const body = { + msg_type: 'interactive', + card: { + header: { + title: { + tag: 'plain_text', + content: title, + }, + }, + elements: [ + { + tag: 'div', + text: { + tag: 'lark_md', + content: typeof content === 'string' ? content : JSON.stringify(content), + }, + }, + { + tag: 'hr', + }, + { + tag: 'note', + elements: [ + { + tag: 'plain_text', + content: `编号: ${record.ref_code || record.ext_id}`, + }, + ], + }, + ], + }, + }; + + ctx.logger.info(`[inbox feishu] 推送消息 ext_id=${record.ext_id} url=${record.target_url}`); + return await this.post(record.target_url, body); + } +} + +module.exports = FeishuDispatch; diff --git a/app/service/inbox/dispatch/webhook.js b/app/service/inbox/dispatch/webhook.js new file mode 100644 index 0000000..4df3812 --- /dev/null +++ b/app/service/inbox/dispatch/webhook.js @@ -0,0 +1,44 @@ +'use strict'; + +const OutboundBase = require('./base'); + +/** + * Webhook 渠道出站实现。 + * 直接 HTTP POST 推送 JSON 到目标 webhook URL。 + */ +class WebhookDispatch extends OutboundBase { + /** + * 通过 webhook 渠道推送消息。 + * @param {Object} record 消息记录(Sequelize Model 实例)。 + * @return {Promise<{status: number, data: *}>} 推送响应。 + */ + async push(record) { + const { ctx } = this; + + const body = { + ref_code: record.ref_code, + ext_data: record.ext_data, + message_id: record.ext_id, + direction: record.direction, + source_type: record.source_type, + created_at: record.created_at, + }; + + let targetUrl = record.target_url; + + // API 类型需要签名 + if (record.target_type === 'api') { + const apiApp = await this.getApiApp(record.warehouse_id); + if (apiApp) { + targetUrl = this.signRequest(targetUrl, body, apiApp); + } else { + ctx.logger.warn(`[inbox webhook] 仓库 ${record.warehouse_id} 没有可用 ApiApp,跳过签名`); + } + } + + ctx.logger.info(`[inbox webhook] 推送消息 ext_id=${record.ext_id} url=${targetUrl}`); + return await this.post(targetUrl, body); + } +} + +module.exports = WebhookDispatch; diff --git a/app/service/inbox/dispatch/wecom.js b/app/service/inbox/dispatch/wecom.js new file mode 100644 index 0000000..09ff283 --- /dev/null +++ b/app/service/inbox/dispatch/wecom.js @@ -0,0 +1,33 @@ +'use strict'; + +const OutboundBase = require('./base'); + +/** + * 企微 Bot 渠道出站实现。 + * 推送 Markdown 消息到企业微信机器人 webhook。 + */ +class WecomDispatch extends OutboundBase { + /** + * 通过企微 Bot 推送消息。 + * @param {Object} record 消息记录(Sequelize Model 实例)。 + * @return {Promise<{status: number, data: *}>} 推送响应。 + */ + async push(record) { + const { ctx } = this; + + const extData = record.ext_data || {}; + const content = extData.content || extData.text || `新消息通知:${record.ref_code || record.ext_id}`; + + const body = { + msgtype: 'markdown', + markdown: { + content: typeof content === 'string' ? content : JSON.stringify(content), + }, + }; + + ctx.logger.info(`[inbox wecom] 推送消息 ext_id=${record.ext_id} url=${record.target_url}`); + return await this.post(record.target_url, body); + } +} + +module.exports = WecomDispatch; diff --git a/app/service/inbox/index.js b/app/service/inbox/index.js new file mode 100644 index 0000000..6a68f32 --- /dev/null +++ b/app/service/inbox/index.js @@ -0,0 +1,354 @@ +'use strict'; + +const Service = require('egg').Service; +const crypto = require('crypto'); + +/** + * 站内信查询/管理服务。 + * 提供消息列表、详情、对话链、回复、重推、统计等管理功能。 + */ +class InboxService extends Service { + /** + * 消息列表(按仓库/状态/方向筛选,分页)。 + * @param {Object} params 查询参数。 + * @param {number} params.warehouseId 仓库ID(必填,服务端上下文注入)。 + * @param {string} [params.direction] 消息方向筛选:inbound / outbound。 + * @param {number} [params.pushStatus] 推送状态筛选:0/1/2/3。 + * @param {string} [params.targetChannel] 目标渠道筛选。 + * @param {string} [params.keyword] 关键词搜索(ext_id / ref_code)。 + * @param {number} [params.page=1] 页码。 + * @param {number} [params.pageSize=20] 每页数量。 + * @return {Promise<{list: Array, pagination: Object}>} 分页结果。 + */ + async list(params = {}) { + const { ctx } = this; + const { Op } = ctx.app.Sequelize; + const { InboxMessage } = ctx.model; + + const warehouseId = Number(params.warehouseId); + if (!Number.isFinite(warehouseId) || warehouseId <= 0) { + throw new Error('warehouseId 无效'); + } + + const page = Math.max(1, Number(params.page) || 1); + const pageSize = Math.min(200, Math.max(1, Number(params.pageSize) || 20)); + + const where = { + warehouse_id: warehouseId, + }; + + if (params.direction && [ 'inbound', 'outbound' ].includes(params.direction)) { + where.direction = params.direction; + } + + if (params.pushStatus !== undefined && params.pushStatus !== null && params.pushStatus !== '') { + const status = Number(params.pushStatus); + if ([ 0, 1, 2, 3 ].includes(status)) { + where.push_status = status; + } + } + + if (params.targetChannel && typeof params.targetChannel === 'string') { + where.target_channel = params.targetChannel.trim(); + } + + if (params.keyword && typeof params.keyword === 'string') { + const keyword = `%${params.keyword.trim()}%`; + where[Op.or] = [ + { ext_id: { [Op.like]: keyword } }, + { ref_code: { [Op.like]: keyword } }, + ]; + } + + const { count: total, rows } = await InboxMessage.findAndCountAll({ + attributes: { + exclude: [ 'ext_data', 'push_response' ], + }, + where, + order: [[ 'created_at', 'DESC' ]], + offset: (page - 1) * pageSize, + limit: pageSize, + }); + + return { + list: rows, + pagination: { + page, + pageSize, + total, + totalPages: Math.ceil(total / pageSize), + hasPrevious: page > 1, + hasNext: page * pageSize < total, + }, + }; + } + + /** + * 消息详情(含 push_response)。 + * @param {Object} params 查询参数。 + * @param {number} params.warehouseId 仓库ID(必填)。 + * @param {number} params.id 消息ID。 + * @return {Promise} 消息详情。 + */ + async detail(params = {}) { + const { ctx } = this; + const { InboxMessage } = ctx.model; + + const warehouseId = Number(params.warehouseId); + const id = Number(params.id); + + if (!Number.isFinite(warehouseId) || warehouseId <= 0) { + throw new Error('warehouseId 无效'); + } + if (!Number.isFinite(id) || id <= 0) { + throw new Error('消息ID无效'); + } + + const record = await InboxMessage.findOne({ + where: { id, warehouse_id: warehouseId }, + }); + + if (!record) { + throw new Error('消息不存在或无权访问'); + } + + return record; + } + + /** + * 对话链查询(原消息 + 所有回信),按 parent_id 递归。 + * @param {Object} params 查询参数。 + * @param {number} params.warehouseId 仓库ID(必填)。 + * @param {number} params.id 消息ID。 + * @return {Promise} 对话链列表。 + */ + async thread(params = {}) { + const { ctx } = this; + const { InboxMessage } = ctx.model; + + const warehouseId = Number(params.warehouseId); + const id = Number(params.id); + + if (!Number.isFinite(warehouseId) || warehouseId <= 0) { + throw new Error('warehouseId 无效'); + } + if (!Number.isFinite(id) || id <= 0) { + throw new Error('消息ID无效'); + } + + // 查找根消息 + const root = await InboxMessage.findOne({ + where: { id, warehouse_id: warehouseId }, + }); + + if (!root) { + throw new Error('消息不存在或无权访问'); + } + + // 收集对话链:从根到叶 + const thread = [ root ]; + + // 查找所有回信(以 root.id 为 parent_id) + const replies = await InboxMessage.findAll({ + where: { + warehouse_id: warehouseId, + parent_id: root.id, + }, + order: [[ 'created_at', 'ASC' ]], + }); + + thread.push(...replies); + + // 如果当前消息不是根(有 parent_id),也向上查找原消息 + if (root.parent_id) { + const parent = await InboxMessage.findOne({ + where: { + id: root.parent_id, + warehouse_id: warehouseId, + }, + }); + + if (parent) { + thread.unshift(parent); + } + } + + return thread; + } + + /** + * 系统回信:写入 outbound 记录 + 异步推送。 + * @param {Object} data 回信数据。 + * @param {number} data.warehouseId 仓库ID(必填,服务端上下文注入)。 + * @param {number} data.parentId 原消息ID。 + * @param {string} data.targetChannel 目标渠道。 + * @param {string} data.targetUrl 推送目标URL。 + * @param {string} [data.refCode] 引用编码。 + * @param {Object} [data.extData] 透传数据。 + * @param {Object} [data.flags] 处理标记。 + * @return {Promise} 回信结果。 + */ + async reply(data = {}) { + const { ctx } = this; + const { InboxMessage } = ctx.model; + + const warehouseId = Number(data.warehouseId); + const parentId = Number(data.parentId); + + if (!Number.isFinite(warehouseId) || warehouseId <= 0) { + throw new Error('warehouseId 无效'); + } + if (!Number.isFinite(parentId) || parentId <= 0) { + throw new Error('parentId 无效'); + } + + // 查找原消息 + const parent = await InboxMessage.findOne({ + where: { id: parentId, warehouse_id: warehouseId }, + }); + + if (!parent) { + throw new Error('原消息不存在或无权访问'); + } + + const extId = `sys:${crypto.randomUUID()}`; + + const result = await ctx.service.inbox.receiver.receive({ + ext_id: extId, + warehouse_id: warehouseId, + store_id: parent.store_id, + direction: 'outbound', + parent_id: parentId, + source_type: 'system', + source_extra: null, + target_type: data.targetType || parent.target_type, + target_channel: data.targetChannel, + target_url: data.targetUrl, + ref_code: data.refCode || parent.ref_code, + ext_data: data.extData || parent.ext_data, + flags: data.flags || {}, + }); + + return result; + } + + /** + * 手动重推。 + * @param {Object} params 重推参数。 + * @param {number} params.warehouseId 仓库ID(必填)。 + * @param {number} params.id 消息ID。 + * @return {Promise} 重推结果。 + */ + async retry(params = {}) { + const { ctx } = this; + const { InboxMessage } = ctx.model; + + const warehouseId = Number(params.warehouseId); + const id = Number(params.id); + + if (!Number.isFinite(warehouseId) || warehouseId <= 0) { + throw new Error('warehouseId 无效'); + } + if (!Number.isFinite(id) || id <= 0) { + throw new Error('消息ID无效'); + } + + const record = await InboxMessage.findOne({ + where: { id, warehouse_id: warehouseId }, + }); + + if (!record) { + throw new Error('消息不存在或无权访问'); + } + + if (![ 3 ].includes(record.push_status)) { + throw new Error('仅失败状态的消息可以手动重推'); + } + + // 重置为待推送状态,由异步推送接管 + await record.update({ + push_status: 0, + push_started_at: null, + }); + + // 触发异步推送 + setImmediate(() => { + ctx.service.inbox.receiver.asyncPush(record, 0).catch(err => { + ctx.logger.error(`[inbox] 手动重推异常 ext_id=${record.ext_id}: ${err.message}`); + }); + }); + + return { + ok: true, + id: record.id, + ext_id: record.ext_id, + message: '已触发重推', + }; + } + + /** + * 推送统计(按仓库 + 状态汇总)。 + * @param {Object} params 统计参数。 + * @param {number} params.warehouseId 仓库ID(必填)。 + * @param {string} [params.direction] 消息方向筛选。 + * @return {Promise} 统计结果。 + */ + async stats(params = {}) { + const { ctx } = this; + const { InboxMessage } = ctx.model; + const { Op } = ctx.app.Sequelize; + + const warehouseId = Number(params.warehouseId); + if (!Number.isFinite(warehouseId) || warehouseId <= 0) { + throw new Error('warehouseId 无效'); + } + + const where = { + warehouse_id: warehouseId, + }; + + if (params.direction && [ 'inbound', 'outbound' ].includes(params.direction)) { + where.direction = params.direction; + } + + // 按方向统计 + const directionStats = await InboxMessage.findAll({ + attributes: [ + 'direction', + [ ctx.app.Sequelize.fn('COUNT', ctx.app.Sequelize.col('id')), 'count' ], + ], + where, + group: [ 'direction' ], + raw: true, + }); + + // 按推送状态统计 + const statusStats = await InboxMessage.findAll({ + attributes: [ + 'push_status', + [ ctx.app.Sequelize.fn('COUNT', ctx.app.Sequelize.col('id')), 'count' ], + ], + where, + group: [ 'push_status' ], + raw: true, + }); + + // 最近24小时统计 + const recentWhere = { + ...where, + created_at: { + [Op.gte]: new Date(Date.now() - 24 * 60 * 60 * 1000), + }, + }; + + const recentCount = await InboxMessage.count({ where: recentWhere }); + + return { + total_by_direction: directionStats, + total_by_status: statusStats, + recent_24h_count: recentCount, + }; + } +} + +module.exports = InboxService; diff --git a/app/service/inbox/receiver.js b/app/service/inbox/receiver.js new file mode 100644 index 0000000..fd9433a --- /dev/null +++ b/app/service/inbox/receiver.js @@ -0,0 +1,370 @@ +'use strict'; + +const Service = require('egg').Service; + +const { URL } = require('url'); +const { networkInterfaces } = require('os'); + +/** 推送 body 大小上限:64KB */ +const MAX_PUSH_BODY_SIZE = 64 * 1024; +/** 最大重试次数 */ +const MAX_RETRY_COUNT = 3; +/** 僵尸恢复阈值:5分钟 */ +const ZOMBIE_RECOVERY_MINUTES = 5; + +/** + * 收集本机所有内网 IPv4 地址。 + * @return {string[]} 内网IP地址列表。 + */ +function getLocalInternalIps() { + const ips = new Set(); + const nets = networkInterfaces(); + for (const interfaces of Object.values(nets)) { + for (const iface of interfaces) { + if (iface.family === 'IPv4' && !iface.internal) { + ips.add(iface.address); + } + } + } + return Array.from(ips); +} + +/** 内网 IP 前缀集合 */ +const INTERNAL_IP_PREFIXES = [ + '127.', + '10.', + '192.168.', + '0.', +]; + +/** + * 判断给定 IP 是否属于本机内网IP。 + * @param {string} ip IP地址。 + * @return {boolean} 是否为内网IP。 + */ +function isInternalIp(ip) { + if (!ip || ip === 'localhost') return true; + + // 检查已知内网前缀 + for (const prefix of INTERNAL_IP_PREFIXES) { + if (ip.startsWith(prefix)) return true; + } + + // 检查 172.16.0.0 ~ 172.31.255.255 + const parts = ip.split('.').map(Number); + if (parts.length === 4 && parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) { + return true; + } + + // 检查本机实际内网IP + const localIps = getLocalInternalIps(); + if (localIps.includes(ip)) return true; + + return false; +} + +/** + * 校验 target_url 安全性:仅允许 https://,禁止内网IP。 + * @param {string} urlStr 目标URL。 + * @throws {Error} URL 不合法时抛出。 + */ +function validateTargetUrl(urlStr) { + if (!urlStr || typeof urlStr !== 'string') { + throw new Error('target_url 不能为空'); + } + + let parsed; + try { + parsed = new URL(urlStr); + } catch (e) { + throw new Error(`target_url 格式不合法: ${urlStr}`); + } + + if (parsed.protocol !== 'https:') { + throw new Error('target_url 仅允许 https:// 协议'); + } + + const hostname = parsed.hostname || ''; + if (isInternalIp(hostname)) { + throw new Error('target_url 不允许指向内网地址'); + } +} + +/** + * 站内信接收服务。 + * 统一处理消息入站:幂等去重、写库、异步推送、指数退避重试、僵尸恢复。 + */ +class InboxReceiverService extends Service { + /** + * 获取支持的目标渠道集合。 + * @return {Set} 支持的目标渠道。 + */ + static get SUPPORTED_CHANNELS() { + return new Set([ + 'webhook', + 'wecom', + 'dingtalk', + 'feishu', + 'warehouse_api', + ]); + } + + /** + * 初始化时执行僵尸恢复。 + * @param {Object} ctx Egg.js 上下文。 + */ + constructor(ctx) { + super(ctx); + // 异步执行僵尸恢复,不阻塞服务启动 + setImmediate(() => { + this.recoverZombieMessages().catch(err => { + ctx.logger.error(`[inbox] 僵尸恢复失败: ${err.message}`); + }); + }); + } + + /** + * 统一接收入口:幂等去重、写库、异步推送。 + * @param {Object} data 消息数据。 + * @param {string} data.ext_id 外部唯一消息主键。 + * @param {number} data.warehouse_id 所属仓库ID(服务端上下文注入,禁止外部传入)。 + * @param {number} [data.store_id] 关联货主ID。 + * @param {string} [data.direction='inbound'] 消息方向。 + * @param {number} [data.parent_id] 关联消息ID(回信时指向原消息)。 + * @param {string} data.source_type 来源类型:im / api / system。 + * @param {string} [data.source_extra] 来源附加信息。 + * @param {string} data.target_type 目标类型:im / api / webhook。 + * @param {string} data.target_channel 目标渠道。 + * @param {string} data.target_url 推送目标URL。 + * @param {string} [data.ref_code] 引用编码。 + * @param {Object} [data.ext_data] 透传数据。 + * @param {Object} [data.flags] 处理标记。 + * @return {Promise<{ok: boolean, id: number, ext_id: string}>} 接收结果。 + */ + async receive(data = {}) { + const { ctx } = this; + const { InboxMessage } = ctx.model; + + // 安全边界:校验 ext_id 不能为空 + const extId = String(data.ext_id || '').trim(); + if (!extId) { + throw new Error('ext_id 不能为空'); + } + + // 安全边界:warehouse_id 必须由服务端上下文提供 + const warehouseId = Number(data.warehouse_id); + if (!Number.isFinite(warehouseId) || warehouseId <= 0) { + throw new Error('warehouse_id 无效'); + } + + // 校验 target_channel 是否存在 + const targetChannel = String(data.target_channel || '').trim(); + if (!targetChannel || !InboxReceiverService.SUPPORTED_CHANNELS.has(targetChannel)) { + throw new Error(`不支持的目标渠道: ${targetChannel},支持的渠道: ${Array.from(InboxReceiverService.SUPPORTED_CHANNELS).join(', ')}`); + } + + // 安全边界:校验 target_url + validateTargetUrl(data.target_url); + + // 幂等检查:ext_id 已存在则直接返回 + const exist = await InboxMessage.findOne({ + where: { ext_id: extId }, + attributes: [ 'id', 'ext_id', 'push_status' ], + paranoid: false, + }); + + if (exist) { + ctx.logger.info(`[inbox] 消息已存在,跳过入库 ext_id=${extId} id=${exist.id}`); + return { + ok: true, + id: exist.id, + ext_id: extId, + }; + } + + // 推送 body 大小限制(序列化后检查) + const pushBody = { + ref_code: data.ref_code || null, + ext_data: data.ext_data || null, + }; + const bodySize = Buffer.byteLength(JSON.stringify(pushBody), 'utf8'); + if (bodySize > MAX_PUSH_BODY_SIZE) { + throw new Error(`推送 body 超过 64KB 限制(当前 ${Math.round(bodySize / 1024)}KB)`); + } + + // 写库 + const record = await InboxMessage.create({ + ext_id: extId, + warehouse_id: warehouseId, + store_id: data.store_id || null, + direction: data.direction || 'inbound', + parent_id: data.parent_id || null, + source_type: data.source_type || 'api', + source_extra: data.source_extra || null, + target_type: data.target_type, + target_channel: targetChannel, + target_url: data.target_url, + ref_code: data.ref_code || null, + ext_data: data.ext_data || null, + flags: data.flags || {}, + push_status: 0, + }); + + ctx.logger.info(`[inbox] 消息入库成功 ext_id=${extId} id=${record.id}`); + + // 异步后台推送(不阻塞响应) + setImmediate(() => { + this.asyncPush(record).catch(err => { + ctx.logger.error(`[inbox] setImmediate 异步推送异常 ext_id=${extId}: ${err.message}`); + // 异常已由 asyncPush 内部 try/catch,这里作为兜底 + try { + InboxMessage.update( + { + push_status: 3, + push_response: { error: `setImmediate 异常: ${err.message}` }, + pushed_at: new Date(), + }, + { where: { id: record.id, push_status: { [this.ctx.app.Sequelize.Op.in]: [ 0, 1 ] } } } + ); + } catch (updateErr) { + ctx.logger.error(`[inbox] 兜底更新推送状态失败 ext_id=${extId}: ${updateErr.message}`); + } + }); + }); + + return { + ok: true, + id: record.id, + ext_id: extId, + }; + } + + /** + * 异步推送 + 指数退避重试。 + * @param {Object} record 消息记录(Sequelize Model 实例)。 + * @param {number} [attempt=0] 当前重试次数。 + * @return {Promise} 推送结果。 + */ + async asyncPush(record, attempt = 0) { + const { ctx } = this; + const { InboxMessage } = ctx.model; + const { Op } = ctx.app.Sequelize; + + try { + // 乐观锁:仅 push_status=0 或(重试时 push_status=3)时可取走 + const allowedStatuses = attempt === 0 ? [ 0 ] : [ 3 ]; + const [ updatedCount ] = await InboxMessage.update( + { + push_status: 1, + push_started_at: new Date(), + }, + { + where: { + id: record.id, + push_status: { [Op.in]: allowedStatuses }, + }, + } + ); + + if (updatedCount === 0) { + ctx.logger.info(`[inbox] 消息已被其他进程取走,跳过推送 ext_id=${record.ext_id} id=${record.id}`); + return; + } + + // 获取 dispatch 服务 + const channel = record.target_channel; + if (!InboxReceiverService.SUPPORTED_CHANNELS.has(channel)) { + throw new Error(`不支持的目标渠道: ${channel}`); + } + + // 统一渠道映射:warehouse_api → webhook + const dispatchChannel = channel === 'warehouse_api' ? 'webhook' : channel; + const dispatchService = ctx.service.inbox.dispatch[dispatchChannel]; + + if (!dispatchService || typeof dispatchService.push !== 'function') { + throw new Error(`dispatch 渠道 ${dispatchChannel} 未实现`); + } + + // 执行推送 + const response = await dispatchService.push(record); + + // 推送成功 + await InboxMessage.update( + { + push_status: 2, + push_response: { + http_status: response.status, + body: response.data, + }, + pushed_at: new Date(), + }, + { where: { id: record.id, push_status: 1 } } + ); + + ctx.logger.info(`[inbox] 推送成功 ext_id=${record.ext_id} channel=${channel}`); + } catch (error) { + const next = attempt + 1; + ctx.logger.warn(`[inbox] 推送失败 ext_id=${record.ext_id} attempt=${next} error=${error.message}`); + + // 更新失败状态 + await InboxMessage.update( + { + push_status: next >= MAX_RETRY_COUNT ? 3 : 3, + retry_count: next, + push_response: { error: error.message }, + ...(next >= MAX_RETRY_COUNT ? { pushed_at: new Date() } : {}), + }, + { where: { id: record.id, push_status: 1 } } + ); + + // 指数退避重试:30s → 60s → 120s + if (next < MAX_RETRY_COUNT) { + const delay = 30000 * Math.pow(2, attempt); + ctx.logger.info(`[inbox] 将在 ${delay / 1000}s 后重试 ext_id=${record.ext_id} attempt=${next}`); + setTimeout(() => { + this.asyncPush(record, next).catch(err => { + ctx.logger.error(`[inbox] 重试推送异常 ext_id=${record.ext_id}: ${err.message}`); + }); + }, delay); + } else { + ctx.logger.error(`[inbox] 推送达到最大重试次数,标记为终态失败 ext_id=${record.ext_id}`); + } + } + } + + /** + * 僵尸恢复:重置卡在"推送中"超过5分钟的消息为"待推送"。 + * 在服务启动时及定时任务中调用。 + * @return {Promise} 恢复的消息数量。 + */ + async recoverZombieMessages() { + const { ctx } = this; + const { InboxMessage } = ctx.model; + const { Op } = ctx.app.Sequelize; + + const threshold = new Date(Date.now() - ZOMBIE_RECOVERY_MINUTES * 60 * 1000); + + const [ updatedCount ] = await InboxMessage.update( + { + push_status: 0, + push_started_at: null, + }, + { + where: { + push_status: 1, + push_started_at: { + [Op.lt]: threshold, + }, + }, + } + ); + + if (updatedCount > 0) { + ctx.logger.info(`[inbox] 僵尸恢复完成,重置 ${updatedCount} 条消息为待推送`); + } + + return updatedCount; + } +} + +module.exports = InboxReceiverService; diff --git a/app/service/warehouseMethods/inbox.js b/app/service/warehouseMethods/inbox.js new file mode 100644 index 0000000..847f579 --- /dev/null +++ b/app/service/warehouseMethods/inbox.js @@ -0,0 +1,64 @@ +'use strict'; + +const MainService = require('../main'); + +/** + * 仓库开放 API — 站内信模块处理器。 + * 接收仓库级外部适配器推送的 inbox.push 请求, + * 统一委托 app/service/inbox/receiver.receive 处理写库与异步推送。 + */ +class WarehouseInboxService extends MainService { + /** + * 仓库 API 消息入站入口。 + * warehouse_id 从验签后上下文注入,禁止外部传入。 + * @param {Object} options 请求参数。 + * @param {Object} options.body 请求体。 + * @return {Promise} 入站结果。 + */ + async push({ body = {} } = {}) { + const { ctx } = this; + const { warehouseId, appKey } = this.getInfo(); + + // 安全边界:warehouse_id 一律从验签后上下文获取 + if (!warehouseId) { + throw new Error('缺少仓库信息'); + } + + // 安全边界:校验必填参数 + if (!body.requestId || !String(body.requestId).trim()) { + throw new Error('requestId 不能为空'); + } + + if (!body.targetChannel || !String(body.targetChannel).trim()) { + throw new Error('targetChannel 不能为空'); + } + + if (!body.targetUrl || !String(body.targetUrl).trim()) { + throw new Error('targetUrl 不能为空'); + } + + // 构造 ext_id + const extId = `api:${String(appKey || 'unknown')}:${String(body.requestId).trim()}`; + + // 构造入站数据并委托给 inbox receiver + const result = await ctx.service.inbox.receiver.receive({ + ext_id: extId, + warehouse_id: warehouseId, + store_id: body.storeId || null, + direction: 'inbound', + parent_id: body.parentId || null, + source_type: body.sourceType || 'api', + source_extra: String(appKey || ''), + target_type: body.targetType || 'im', + target_channel: body.targetChannel, + target_url: body.targetUrl, + ref_code: body.refCode || null, + ext_data: body.extData || null, + flags: body.flags || {}, + }); + + return result; + } +} + +module.exports = WarehouseInboxService; diff --git a/database/designs/inbox-message-module-design.md b/database/designs/inbox-message-module-design.md new file mode 100644 index 0000000..14e4651 --- /dev/null +++ b/database/designs/inbox-message-module-design.md @@ -0,0 +1,441 @@ +# 站内信(Inbox)模块设计方案 + +> **状态**: 📋 设计中 +> **设计日期**: 2026-08-03 +> **设计人**: wms-test-agent +> **模块**: `app/service/inbox/`,独立文件模块 +> **表**: 1 张 — `wms_inbox_message` + +--- + +## 一、概念 + +消息推送状态追踪表。不重复存储消息内容(消息体由 IM 回调 / API 请求各自管理),只记录**谁发来的、要推到哪、推送状态**。收件(inbound)和回信(outbound)共表,`direction` + `parent_id` 形成对话链。 + +``` + inbound(外部 → WMS) outbound(WMS → 外部) + ┌──────────────────────┐ ┌──────────────────────┐ + │ IM 回调 / API push │ │ 系统回信 / 工单通知 │ + └──────────┬───────────┘ └──────────┬───────────┘ + │ │ + ▼ ▼ + ┌─────────────────────────────────────────┐ + │ wms_inbox_message(同一张表) │ + │ │ + │ direction: inbound │ outbound │ + │ parent_id: NULL │ parent_id: 原消息ID │ + │ │ + │ "IM msg_001 → API app_10 → success" │ + │ "WMS 回复 → 企微 Bot → success" │ + └─────────────────────────────────────────┘ + │ + ▼ setImmediate async push + dispatch → HTTP POST / Bot API +``` + +--- + +## 二、数据库表 + +### `wms_inbox_message` + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|------|------|------|--------|------| +| `id` | `BIGINT UNSIGNED` | ✅ | AUTO | 主键 | +| `ext_id` | `VARCHAR(128)` | ✅ | — | **外部唯一消息主键**(IM msgId / API requestId 等),唯一索引,幂等去重 | +| `warehouse_id` | `BIGINT UNSIGNED` | ✅ | — | 所属仓库 | +| `store_id` | `BIGINT UNSIGNED` | — | NULL | 关联货主 | +| `direction` | `VARCHAR(10)` | ✅ | `inbound` | `inbound`=外部→WMS 收件 / `outbound`=WMS→外部 回信 | +| `parent_id` | `BIGINT UNSIGNED` | — | NULL | 关联消息 ID(回信时指向原消息,形成对话链) | + +#### 来源 / 目标 + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `source_type` | `VARCHAR(20)` | ✅ | `im` / `api` | +| `source_extra` | `VARCHAR(100)` | — | 附加信息(IM 平台 / API app_id) | +| `target_type` | `VARCHAR(20)` | ✅ | `im` / `api` | +| `target_channel` | `VARCHAR(50)` | ✅ | 目标渠道:`wecom` / `dingtalk` / `feishu` / `warehouse_api` / `webhook` | +| `target_url` | `VARCHAR(500)` | ✅ | 推送目标 URL(IM Bot webhook 地址 / API 回调地址) | + +> **安全设计**: +> - `target_url` 不含 secret。IM Bot URL 中 token 已内嵌,API 推送时 secret 从 `ApiApp.self_app_secret` 查。 +> - **出站签名**:推送到仓库开放 API 时,使用与该仓库 ApiApp 相同的 MD5 签名算法(`canonicalQuery + self_app_secret + bodySign`),接收方用同一 `app_key` 验证。IM 通道则使用各自 Bot 的原生鉴权。 + +> **inbound vs outbound 的 source/target 语义**: +> ``` +> inbound(外部→WMS):source=外部来源 target=WMS 内部要转发到的渠道 +> outbound(WMS→外部):source=WMS 内部 target=要推送到的外部渠道 +> ``` +| `ref_code` | `VARCHAR(100)` | — | 外部引用编码,推送/回执时原样携带 | +| `ext_data` | `JSON` | — | **外部透传数据**,外部传入任意 JSON,WMS 不解析,回信时原样返回 | +| `flags` | `JSON` | — | **处理标记**,外部传入控制 WMS 处理行为,见下表 | + +> **`flags` 支持的标记**: +> ```json +> { +> "skip_ai_parse": true, // 跳过智能解析(内部员工发信时设为 true) +> "skip_auto_reply": true, // 跳过自动回复 +> "skip_forward": true // 仅存档,不转发 +> } +> ``` +> 外部不传 → 默认全部开启(智能解析 + 自动回复 + 转发)。内部系统调用 `inbox.push` 时按需关闭特定行为。 + +#### 推送状态 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|------|------|------|--------|------| +| `push_status` | `TINYINT(4)` | ✅ | 0 | 0=待推送 1=推送中 2=已送达 3=失败 | +| `push_started_at` | `DATETIME` | — | NULL | 开始推送时间(僵尸检测:超 5 分钟仍为 1 → 重置为 0) | +| `retry_count` | `INT(11)` | ✅ | 0 | 已重试次数 | +| `push_response` | `JSON` | — | NULL | 目标响应(http_status, body, error) | +| `pushed_at` | `DATETIME` | — | NULL | 推送完成时间 | + +> **防重机制**:`push_status` 字段本身即状态流转,不需要额外流转表。使用乐观锁 `UPDATE SET push_status=1 WHERE push_status=0` 保证单条消息不会被重复取走。`push_started_at` 用于进程崩溃后的僵尸恢复。 + +#### 关联(后续) + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `work_order_id` | `BIGINT UNSIGNED` | — | 🔮 关联工单 | +| `work_order_no` | `VARCHAR(50)` | — | 🔮 工单号 | + +#### 时间 + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|------|------|------|--------|------| +| `created_at` | `DATETIME` | ✅ | CURRENT_TIMESTAMP | | +| `updated_at` | `DATETIME` | ✅ | CURRENT_TIMESTAMP ON UPDATE | | +| `deleted_at` | `DATETIME` | — | NULL | 软删除 | + +### 索引 + +| 索引名 | 字段 | 用途 | +|--------|------|------| +| `PRIMARY` | `id` | — | +| `uk_ext_id` | `ext_id` UNIQUE | 外部幂等去重 | +| `idx_warehouse_status` | `warehouse_id, push_status` | 按仓库+状态查询 | +| `idx_warehouse_direction` | `warehouse_id, direction, created_at` | 收件/回信列表 | +| `idx_parent` | `parent_id` | 对话链查询 | +| `idx_created_at` | `created_at` | 时间范围 | + +> **`ext_id` 唯一键防碰撞**:不同来源的消息 ID 可能重复(IM msgId 与 API requestId 撞车)。入库时按来源加前缀: +> ``` +> IM 消息: ext_id = `im:wecom:${msg.msgId}` +> API 消息: ext_id = `api:${apiAppId}:${body.requestId}` +> 系统回信: ext_id = `sys:${uuid}` +> ``` +> 前缀保证不同来源的消息不会因 ID 相同而误判为重复。 + +> **容量规划**:`BIGINT UNSIGNED` 主键容量无限。单表 InnoDB 建议 ≤ 5000 万行。以 100 仓 × 日均 5000 条 = 日 50 万条计,达到上限需 ~100 天。届时加 `PARTITION BY HASH(warehouse_id) PARTITIONS 16` 即可水平扩展,无需分库分表,代码零改动。 + +### 安全边界(强制) + +| 边界 | 规则 | +|------|------| +| **warehouse_id 归属** | 禁止外部传入。IM 路径从回调解析获取,API 路径从验签后 `ctx.warehouseId` 获取 | +| **ext_id 前缀** | `im:{platform}:{msgId}` / `api:{appId}:{requestId}` / `sys:{uuid}`,receiver 入站时统一格式 | +| **target_url SSRF** | 仅允许 `https://`,禁止内网 IP(127.0.0.1/10.x/172.16-31.x/192.168.x) | +| **dispatch 超时** | HTTP 请求超时 10s,超时视为失败进入重试 | +| **setImmediate 异常** | `try/catch` 包裹,异常写入 `push_response.error`,`push_status=3` | +| **target_channel 校验** | `dispatch[channel]` 不存在时返回明确错误,不静默丢弃 | +| **僵尸恢复** | 启动时 + 每 5 分钟定时执行 `UPDATE push_status=0 WHERE push_status=1 AND push_started_at < NOW()-5MIN` | +| **推送 body 大小** | 限制 64KB,超限拒绝写入 | + +--- + +## 三、推送流程 + +``` +receiver.receive() + │ + ├─ 1. 幂等检查(ext_id 已存在 → 直接返回) + ├─ 2. INSERT(push_status=0) + └─ 3. setImmediate(() => asyncPush(record)) + │ + ├─ UPDATE push_status=1(推送中) + ├─ dispatch(target_channel, target_url) + │ ├─ 成功 → UPDATE push_status=2, pushed_at=NOW() + │ └─ 失败 → retry_count++ + │ ├─ < 3 次 → setTimeout(delay, asyncPush) 指数退避重试 + │ └─ ≥ 3 次 → UPDATE push_status=3(终态) + └─ 返回 +``` + +**指数退避**:30s → 60s → 120s,最多重试 3 次。 + +**关键**:不依赖定时任务轮询,利用 Node.js 事件循环的 `setImmediate` + `setTimeout` 在同一个进程内异步完成推送与重试。 + +--- + +## 四、两个接收入口 + +### IM 消息入站 + +``` +企微/钉钉/飞书 Bot 回调 → receiver.receive({ + // warehouse_id 由 IM 回调解析 / 签名验证后从上下文获取,不外部传入 + source_type: 'im', + ext_id: `im:wecom:${msg.msgId}`, + source_extra: 'wecom', + + target_type: 'api', + target_channel: 'warehouse_api', + target_url: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx', + ref_code: msg.userId, + ext_data: { conversation_id: msg.conversationId }, + flags: {}, + + warehouse_id: ctx.warehouseId, // ← 来自鉴权上下文,非外部传入 +}) +``` + +### 仓库 API 消息入站 + +``` +POST /warehouse?method=inbox.push → receiver.receive({ + // warehouse_id 由仓库 API 验签后从 ApiApp 解析,不外部传入 + source_type: 'api', + ext_id: `api:${ctx.apiAppId}:${body.requestId}`, + source_extra: String(ctx.apiAppId), + + target_type: 'im', + target_channel: body.targetChannel || 'wecom', + target_url: body.targetUrl, + ref_code: body.refCode, + ext_data: body.extData, + flags: body.flags || {}, + + warehouse_id: ctx.warehouseId, // ← 来自鉴权上下文,非外部传入 +}) +``` + +### 系统回信(outbound) + +``` +WMS 内部(工单通知/状态更新)→ receiver.reply({ + parent_id: 1, // 原消息 ID + target_type: 'im', + target_channel: 'wecom', + target_url: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx', + ref_code: 'TICKET-001', + ext_data: { ... }, // 继承原消息 ext_data + + warehouse_id: ctx.warehouseId, // ← WMS 内部上下文 +}) +// 自动写入 direction=outbound, parent_id=1 +// 推送成功后,可通过 inbox.thread 查完整对话链 +``` + +--- + +## 五、API + +### 5.1 内部管理 (`inbox.*`) + +| method | 说明 | +|--------|------| +| `inbox.list` | 消息列表(`direction` 区分收件/回信) | +| `inbox.detail` | 消息详情(含 push_response) | +| `inbox.thread` | 对话链(原消息 + 所有回信) | +| `inbox.reply` | 系统回信(写入 outbound 记录 + 异步推送) | +| `inbox.retry` | 手动重推 | +| `inbox.stats` | 推送统计 | + +### 5.2 仓库 API (`inbox.push`) + +`POST /warehouse?method=inbox.push` + +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `body.sourceType` | `string` | ✅ | 来源类型:`im` / `api` | +| `body.sourceChannel` | `string` | — | 来源渠道(IM 平台 / API 标识) | +| `body.requestId` | `string` | ✅ | 来源请求 ID(组成 ext_id) | +| `body.targetChannel` | `string` | ✅ | 目标渠道 | +| `body.targetUrl` | `string` | ✅ | 推送目标 URL | +| `body.refCode` | `string` | — | 引用编码 | +| `body.extData` | `object` | — | 透传数据 | +| `body.flags` | `object` | — | 处理标记 `{ skip_ai_parse, skip_auto_reply, skip_forward }` | +| `body.storeId` | `number` | — | 关联货主 | + +--- + +## 六、异步推送实现 + +不启动独立 consumer,利用 Egg.js / Node.js 原生异步能力: + +```javascript +// receiver.js +async receive(data) { + // 1. 幂等检查 + const exist = await this.ctx.model.InboxMessage.findOne({ + where: { ext_id: data.ext_id }, + }); + if (exist) return { ok: true, id: exist.id, ext_id: data.ext_id }; + + // 2. 写入记录 + const record = await this.ctx.model.InboxMessage.create({ + ext_id: data.ext_id, + warehouse_id: data.warehouse_id, + source_type: data.source_type, + source_extra: data.source_extra, + target_type: data.target_type, + target_channel: data.target_channel, + target_url: data.target_url, + ref_code: data.ref_code, + ext_data: data.ext_data, + flags: data.flags || {}, + push_status: 0, + }); + + // 3. 异步后台推送(不阻塞响应) + setImmediate(() => this.asyncPush(record)); + + return { ok: true, id: record.id, ext_id: data.ext_id }; +} + +async asyncPush(record, attempt = 0) { + // 乐观锁:仅 push_status=0 时可取走,防重 + const [ updated ] = await InboxMessage.update( + { push_status: 1, push_started_at: new Date() }, + { where: { id: record.id, push_status: attempt === 0 ? 0 : 3 } } + ); + if (!updated) return; // 已被其他进程取走 + + try { + // API 渠道:用仓库 ApiApp 生成 MD5 签名,接收方同密钥验证 + const payload = { ref_code: record.ref_code, ext_data: record.ext_data }; + const signedUrl = record.target_type === 'api' + ? await this.signRequest(record, payload) + : record.target_url; + + const res = await this.ctx.service.inbox.dispatch[record.target_channel].push( + signedUrl, payload + ); + await record.update({ + push_status: 2, + push_response: { http_status: res.status, body: res.data }, + pushed_at: new Date(), + }); + } catch (err) { + const next = attempt + 1; + await record.update({ push_status: 3, retry_count: next, push_response: { error: err.message } }); + + if (next < 3) { + const delay = 30000 * Math.pow(2, attempt); // 30s → 60s → 120s + setTimeout(() => this.asyncPush(record, next), delay); + } + } +} +``` + +**不需要**:定时任务、消息队列、独立 worker 进程。 + +> **僵尸恢复**:进程崩溃导致 `push_status=1` 的记录卡死时,启动时执行 `UPDATE SET push_status=0 WHERE push_status=1 AND push_started_at < NOW() - INTERVAL 5 MINUTE` 即可复活。 + +> **出站签名**:推送到 `target_type=api` 时,使用仓库 ApiApp 的 `self_app_secret` 生成 MD5 签名附加到 URL query: +> ``` +> signedUrl = target_url +> + '?app_key=' + apiApp.self_app_key +> + '×tamp=' + now +> + '&sign=' + md5(queryString + self_app_secret + md5(body)) +> ``` +> 接收方(仓库开放侧)可用同一 `app_key` 调用 `apiSignLib.verifyRequestSign()` 验证。IM 通道(wecom/dingtalk/feishu)使用各自 Bot 原生鉴权,不走此签名。 + +--- + +## 七、模块结构 + +**分层原则**:API 入口只做校验与签名,统一委托 `app/service/inbox/` 处理写库与推送逻辑。`methods/` 仅放接口定义,不放业务代码。 + +``` +入口层(校验 + 签名) 统一处理层(写库 + 推送) 数据层 +────────────────────────── ────────────────────────── ────── +app/controller/ app/service/inbox/ app/model/ + im.js ─────────────┐ ┌─ receiver.js inbox_message.js + warehouse.js ──────┤ │ 统一接收(幂等去重) ↑ + ├──调用──→ │ 写库(INSERT) │ + app/service/im.js ─┘ │ 异步推送(setImmediate) │ + │ │ 重试(setTimeout 指数退避) │ + │ │ │ + │ ├─ index.js │ + │ │ 列表/详情/重推/统计 │ + │ │ │ + │ └─ dispatch/ │ + │ base.js ← 统一出站:查 ApiApp、取密钥、签名、发 HTTP │ + │ webhook.js ← 继承 base,HTTP POST │ + │ wecom.js ← 继承 base,企微 Bot │ + │ dingtalk.js ← 继承 base,钉钉 Bot │ + │ feishu.js ← 继承 base,飞书 Bot │ + │ │ +methods/ (仅接口定义,不放逻辑) │ + warehouse.json ← inbox.push 参数声明 │ + system.json ← inbox.* 参数声明 │ +``` + +> **关键**:`app/service/inbox/` 是独立的统一处理目录,所有写库、推送、重试逻辑集中在此。后续新增渠道只需在 `dispatch/` 下加一个文件,不影响其他层。 + +### 统一出站基类 `dispatch/base.js` + +所有渠道 dispatch 继承此基类,统一处理查密钥、签名、发 HTTP: + +```javascript +// dispatch/base.js +class OutboundBase { + constructor(ctx) { this.ctx = ctx; } + + // 获取仓库 ApiApp 密钥(IM 渠道无需签名,返回 null) + async getApiApp(warehouseId) { + return await this.ctx.service.systems.apiSign.getApiAppConfigByAppKey( + /* appKey from warehouse */, WAREHOUSE_INTERFACE_TYPE_ID + ); + } + + // 生成 MD5 签名(复用 apiSignLib) + signRequest(url, body, secret) { + const query = { app_key: secret.appKey, timestamp: Math.floor(Date.now() / 1000) }; + const { sign } = apiSignLib.signRequest({ query, body, selfAppSecret: secret.selfAppSecret }); + return `${url}?app_key=${query.app_key}×tamp=${query.timestamp}&sign=${sign}`; + } + + // 统一发送(子类可覆盖签名逻辑) + async post(url, body) { /* axios/post */ } + + // 子类必须实现 + async push(record) { throw new Error('子类实现'); } +} +``` + +> **调用链**:`receiver.asyncPush()` → `dispatch[channel].push(record)` → 基类 `signRequest()` + `post()` → 外部。各渠道只关注消息格式转换,签名和 HTTP 由基类统一处理。 + +### 与现有系统集成 + +``` +app/controller/im.js(已有) + → IM 回调签名校验后 → ctx.service.inbox.receiver.receive({ source_type: 'im', ... }) + +app/controller/warehouse.js(已有) + → method=inbox.push → ctx.service.inbox.receiver.receive({ source_type: 'api', ... }) + +methods/warehouse.json(修改) + → 新增 inbox.push 方法定义,注册到 warehouse 开放接口方法列表 +``` + +--- + +## 八、文件变更清单 + +| 文件 | 操作 | +|------|------| +| `database/migrations/{ts}-create-inbox-message.js` | 新增 DDL | +| `app/model/inbox_message.js` | 新增 | +| `app/service/inbox/index.js` | 新增 | +| `app/service/inbox/receiver.js` | 新增(统一接收 + 写库 + 异步推送入口) | +| `app/service/inbox/dispatch/base.js` | 新增(统一出站:查密钥 + 签名 + HTTP) | +| `app/service/inbox/dispatch/webhook.js` | 新增(HTTP POST 推送) | +| `app/service/inbox/dispatch/wecom.js` | 新增(企微 Bot) | +| `app/service/inbox/dispatch/dingtalk.js` | 新增(钉钉 Bot) | +| `app/service/inbox/dispatch/feishu.js` | 新增(飞书 Bot) | +| `app/controller/inbox.js` | 新增 | +| `methods/warehouse.json` | 新增 `inbox.push` | +| `methods/system.json` | 新增 `inbox.*` | diff --git a/database/migrations/20260803120000-create-inbox-message.js b/database/migrations/20260803120000-create-inbox-message.js new file mode 100644 index 0000000..d31b668 --- /dev/null +++ b/database/migrations/20260803120000-create-inbox-message.js @@ -0,0 +1,182 @@ +'use strict'; + +const TABLE_NAME = 'wms_inbox_message'; + +module.exports = { + /** + * 创建站内信消息表。 + * @param {Object} queryInterface Sequelize QueryInterface 实例。 + * @param {Object} Sequelize Sequelize 类。 + * @return {Promise} 迁移执行结果。 + */ + up: async (queryInterface, Sequelize) => { + const tables = await queryInterface.showAllTables(); + const exists = tables.some(t => (typeof t === 'string' ? t : t.tableName) === TABLE_NAME); + if (exists) return; + + await queryInterface.createTable(TABLE_NAME, { + id: { + type: Sequelize.BIGINT(20).UNSIGNED, + primaryKey: true, + autoIncrement: true, + allowNull: false, + comment: '主键ID', + }, + ext_id: { + type: Sequelize.STRING(128), + allowNull: false, + comment: '外部唯一消息主键(IM msgId / API requestId 等),用于幂等去重', + }, + warehouse_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: false, + comment: '所属仓库ID', + }, + store_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: true, + comment: '关联货主ID', + }, + direction: { + type: Sequelize.STRING(10), + allowNull: false, + defaultValue: 'inbound', + comment: '消息方向:inbound=外部→WMS收件 / outbound=WMS→外部回信', + }, + parent_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: true, + comment: '关联消息ID(回信时指向原消息,形成对话链)', + }, + source_type: { + type: Sequelize.STRING(20), + allowNull: false, + comment: '来源类型:im / api', + }, + source_extra: { + type: Sequelize.STRING(100), + allowNull: true, + comment: '来源附加信息(IM 平台 / API app_id)', + }, + target_type: { + type: Sequelize.STRING(20), + allowNull: false, + comment: '目标类型:im / api', + }, + target_channel: { + type: Sequelize.STRING(50), + allowNull: false, + comment: '目标渠道:wecom / dingtalk / feishu / warehouse_api / webhook', + }, + target_url: { + type: Sequelize.STRING(500), + allowNull: false, + comment: '推送目标URL(IM Bot webhook 地址 / API 回调地址)', + }, + ref_code: { + type: Sequelize.STRING(100), + allowNull: true, + comment: '外部引用编码,推送/回执时原样携带', + }, + ext_data: { + type: Sequelize.JSON, + allowNull: true, + comment: '外部透传数据,外部传入任意JSON,WMS不解析,回信时原样返回', + }, + flags: { + type: Sequelize.JSON, + allowNull: true, + comment: '处理标记,外部传入控制WMS处理行为', + }, + push_status: { + type: Sequelize.TINYINT(4), + allowNull: false, + defaultValue: 0, + comment: '推送状态:0=待推送 1=推送中 2=已送达 3=失败', + }, + push_started_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '开始推送时间(僵尸检测:超5分钟仍为1则重置为0)', + }, + retry_count: { + type: Sequelize.INTEGER(11), + allowNull: false, + defaultValue: 0, + comment: '已重试次数', + }, + push_response: { + type: Sequelize.JSON, + allowNull: true, + comment: '目标响应(http_status, body, error)', + }, + pushed_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '推送完成时间', + }, + work_order_id: { + type: Sequelize.BIGINT(20).UNSIGNED, + allowNull: true, + comment: '关联工单ID(预留)', + }, + work_order_no: { + type: Sequelize.STRING(50), + allowNull: true, + comment: '工单号(预留)', + }, + created_at: { + type: Sequelize.DATE, + allowNull: false, + defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'), + comment: '创建时间', + }, + updated_at: { + type: Sequelize.DATE, + allowNull: false, + defaultValue: Sequelize.literal('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'), + comment: '更新时间', + }, + deleted_at: { + type: Sequelize.DATE, + allowNull: true, + comment: '软删除时间', + }, + }); + + // 唯一索引 — 外部幂等去重 + await queryInterface.addIndex(TABLE_NAME, [ 'ext_id' ], { + unique: true, + name: 'uk_ext_id', + }); + + // 仓库+状态查询 + await queryInterface.addIndex(TABLE_NAME, [ 'warehouse_id', 'push_status' ], { + name: 'idx_warehouse_status', + }); + + // 仓库+方向+时间 + await queryInterface.addIndex(TABLE_NAME, [ 'warehouse_id', 'direction', 'created_at' ], { + name: 'idx_warehouse_direction', + }); + + // 对话链查询 + await queryInterface.addIndex(TABLE_NAME, [ 'parent_id' ], { + name: 'idx_parent', + }); + + // 时间范围查询 + await queryInterface.addIndex(TABLE_NAME, [ 'created_at' ], { + name: 'idx_created_at', + }); + }, + + /** + * 回滚站内信消息表。 + * @param {Object} queryInterface Sequelize QueryInterface 实例。 + * @return {Promise} 迁移回滚结果。 + */ + down: async queryInterface => { + await queryInterface.dropTable(TABLE_NAME); + }, +}; diff --git a/methods/changes/system.json b/methods/changes/system.json index e2f76a4..8539d6e 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,5111 +1,5137 @@ [ - { - "version": "2026.08.01-system-01", - "date": "2026-08-01", - "type": "added", - "summary": "新增 apiApp 仓库 API 应用管理模块,支持当前仓库维度的 API 应用 CRUD、AppKey/Secret 自动生成与重新生成、IP 白名单、回调地址、限流等配置", - "methods": [ - "apiApp.list", - "apiApp.detail", - "apiApp.create", - "apiApp.update", - "apiApp.delete", - "apiApp.regenerateSecret" - ], - "notes": [ - "apiApp.list:分页查询当前仓库 API 应用列表,支持按 app_name(模糊)、is_enabled 筛选,Secret 自动脱敏(前8位+****)。", - "apiApp.detail:按 ID 查询单个应用详情,需同时匹配 warehouse_id(自动注入 ctx.user.store_id),Secret 脱敏。", - "apiApp.create:创建应用时自动生成 AppKey(AK{yyyyMMddHHmmss}{random8hex})和 AppSecret(64位hex)。默认 interface_type_id 取 WH_CHANNEL。仅创建时返回完整 Secret。", - "apiApp.update:更新可编辑字段(app_name、self_ip_whitelist、callback_url、rate_limit、sign_method、is_enabled),不可变字段为 self_app_key 和 interface_type_id。", - "apiApp.delete:软删除(is_enabled=0),不物理删除。", - "apiApp.regenerateSecret:重新生成 64位hex AppSecret,旧 Secret 立即失效。仅此次返回完整 Secret。", - "仓库隔离:所有操作按 ctx.user.store_id → warehouse_id 自动过滤。", - "Secret 安全策略:list/detail/update 返回脱敏值,仅 create/regenerateSecret 返回完整 Secret。" - ], - "module": "apiApp" - }, - { - "version": "2026.07.31-system-02", - "date": "2026-07-31", - "type": "added", - "summary": "新增 storage.inventory.export 库存导出与 storage.inventory.exportTaskProgress 导出进度查询,入参复用 list 的 where/sort/group_by_batch 语义,支持两种导出模式(聚合汇总 / 逐条明细),库位信息一并导出", - "methods": [ - "storage.inventory.export", - "storage.inventory.exportTaskProgress" - ], - "notes": [ - "storage.inventory.export:异步提交导出任务,返回 task_id 与受理信息,后端异步生成 Excel 并上传。入参 where/sort/group_by_batch 与 storage.inventory.list 完全一致,无需额外学习成本。", - "group_by_batch=false(默认):按 stock_id + space_id(库位)聚合导出库存汇总,含商品编码/名称/规格/单位/货主/库位编码/名称/总库存/锁定/可用/批次数/最近入库时间。", - "group_by_batch=true:按 storage_id 逐条导出库存明细,含库存记录ID/商品信息/库位信息/批次号/库存类型/数量/生产日期/过期日期/入库时间/入库单号/供应商批次号。", - "新增 storage.inventory.exportTaskProgress:按 task_id/taskId 查询导出任务进度与状态(submitted/running/success/failed/not_found),status=success 时返回 download_url 供客户端下载。", - "导出文件目录:exports/storage/inventory/{warehouseId}/,缓存 TTL 1800 秒。" - ], - "module": "storage.inventory" - }, - { - "version": "2026.07.31-system-01", - "date": "2026-07-31", - "type": "added", - "summary": "新增按波次批量快捷复核接口 batchQuickRecheckByWave,支持批量波次 IDs 的前置条件检查(储位、快递、同步、拦截),自动完成拣货并标记复核,支持部分失败", - "methods": [ - "order.recheckOrder.batchQuickRecheckByWave" - ], - "notes": [ - "新增 order.recheckOrder.batchQuickRecheckByWave 方法,复用 batchQuickRecheck 的 _completePickForOrder / _markRecheckForOrder / _tryCompleteWaveInTransaction 等内部事务方法", - "入参 wave_ids 支持数组或逗号分隔字符串,兼容 waveIds(驼峰)、wave_id(单值)", - "按波次维度批量查询订单后逐波次、逐订单执行前置校验与复核,每个订单独立事务,部分失败不影响其他订单", - "响应包含 success/failed 列表及计数,failed 项含 order_id、wave_id、delivery_order_code、reason 说明;波次下无订单时仅返回 wave_id + reason" - ], - "module": "order.recheckOrder" - }, - { - "version": "2026.07.29-system-01", - "date": "2026-07-29", - "type": "added", - "summary": "补全 waybill.warehouse group API 文档参数定义:完善 list/detail/export 的 params 与 response,新增 exportTaskProgress 异步进度查询接口", - "methods": [ - "waybill.warehouse.list", - "waybill.warehouse.detail", - "waybill.warehouse.export", - "waybill.warehouse.exportTaskProgress" - ], - "notes": [ - "waybill.warehouse.list:params 含 pagination/where/sort 完整字段定义,where 支持 15 个筛选维度(运单号、主单号、订单ID、订单号、物流编码、物流接口ID、平台编码、状态、退回/拦截/星河签收、包材ID、已称重、关键词、创建时间范围),sort 白名单 create_at/weighing_weight/id。response 含 list(28 个字段)+ pagination。", - "waybill.warehouse.detail:修正 id 参数为可选(required: false),与 waybillCode 二选一,waybillCode 优先。response 含 id/waybill_code/main_waybill_code/waybill_type/business_key/sibling_waybills/order/logistics/status_info/weight/package/print_records/print_count 等完整详情。", - "waybill.warehouse.export:response 补充 progress/message/update_time 字段,完整覆盖异步任务返回信息。", - "新增 waybill.warehouse.exportTaskProgress:按 task_id/taskId 查询导出进度,response 含 task_id/status/progress/current_count/total_count/message/result/error/download_url/update_time。", - "所有接口 isNeedAuth: false, isNeedLogin: true,仓库隔离通过 ctx.user.store_id 自动注入。" - ], - "module": "waybill.warehouse" - }, - { - "version": "2026.07.28-system-01", - "date": "2026-07-28", - "type": "added", - "summary": "新增 order.pendingOrder.batchMarkPrinted:批量设置订单为已打印状态,将 print_status 更新为 'fin'", - "methods": [ - "order.pendingOrder.batchMarkPrinted" - ], - "notes": [ - "同步批量更新接口,传入订单ID数组,直接将符合条件的订单 print_status 设为 'fin'。", - "双表查询:先查 current 表(wms_order_delivery_{warehouseId}),未命中的 ID 再兜底查 dispatch 表(wms_order_delivery_{warehouseId}_dispatch)。", - "dispatch 表查询失败仅记录 warn 日志,不影响 current 表已更新的结果。", - "仅允许 step 在 [1,2,3] 且 status 不为 'cancel' 的订单操作,已打印(print_status='fin')的订单会被静默跳过。", - "仓库上下文强制从 ctx.user.store_id 获取,禁止传入外部仓库ID。", - "入参支持 order_ids / orderIds / ids 三种别名,优先级 order_ids > orderIds > ids。", - "返回 updated_count 表示实际更新条数(current + dispatch 合计),ids 原样回传请求的订单ID列表。", - "写入操作日志 operation_code: ORDER_BATCH_MARK_PRINTED。" - ], - "module": "order.pendingOrder" - }, - { - "version": "2026.07.27-system-03", - "date": "2026-07-27", - "type": "changed", - "summary": "storage.receiving 导出接口拆分:export 改为按仓库维度,新增 storeExport 按货主维度导出", - "methods": [ - "storage.receiving.export", - "storage.receiving.exportTaskProgress", - "storage.receiving.storeExport", - "storage.receiving.storeExportTaskProgress" - ], - "notes": [ - "export 改为仓库维度:过滤条件从 store_id(平台激活货主)改为 warehouse_id(ctx.user.store_id),与 getReceivingList 保持一致。", - "exportTaskProgress 同步更新为仓库维度进度查询,任务 ID 前缀 receiving_export_。", - "新增 storeExport:货主维度导出,通过平台激活上下文获取 store_id,过滤逻辑与 getStoreReceivingList 一致。", - "新增 storeExportTaskProgress:货主维度进度查询,复用 exportTaskProgress 的缓存逻辑,任务 ID 前缀 receiving_store_export_。", - "导出格式:双 Sheet Excel(Sheet1=收货单列表 21 列,Sheet2=收货单明细 17 列),通过 ExcelJS stream + uploadService 上传 COS。", - "仓库导出上传路径 exports/receiving/{warehouseId}/,货主导出上传路径 exports/receiving/store/{storeId}/。", - "修复 exportReceivingList 中 where 条件二次解析问题:增加 ctx.whereParsed 复用(与 getStoreReceivingList 一致),避免 prepareWhereContext 已解析后再重复 parseWhereConditions 导致边界条件丢失。", - "命名对齐 entry 侧:storeExport / storeExportTaskProgress 方法名、任务 ID 前缀、上传路径均与 storage.entry.storeExport 模式一致。" - ], - "module": "storage.receiving" - }, - { - "version": "2026.07.27-system-02", - "date": "2026-07-27", - "type": "added", - "summary": "新增 order.pendingOrder.allocateSubOrderNumber:待处理订单分配子单号(异步任务),business_key 从 2 开始递增,跳过已分配运单号;新增 allocateSubOrderNumberProgress 按 task_id/business_key 查询进度", - "methods": [ - "order.pendingOrder.allocateSubOrderNumber", - "order.pendingOrder.allocateSubOrderNumberProgress" - ], - "notes": [ - "新增 allocateSubOrderNumber:入参 order_id + sub_order_count,按 business_key 2..(2+count-1) 全量传入 createWaybillCodePipeline。", - "并发安全:全量传入 pipeline,由其内部事务 + UNIQUE(order_id,business_key,status,warehouse_id) 索引保证并发去重。", - "pipeline 内部 createWaybillCode 事务:status=1 已分配→跳过;status=0 占位中→复用;无记录→INSERT status=0 占位。", - "异步任务模式:请求立即返回 task_id(sub_ 前缀),后台 setImmediate 执行,进度通过 Redis 缓存追踪。", - "新增 allocateSubOrderNumberProgress:支持 task_id 查整体进度,business_key 可选参数过滤单个业务ID的详情。", - "进度状态 submitted→running→success/partial/failed,progress 对应 5/50/80/100。", - "result.details 数组记录每个 business_key 的 status(skipped/allocated/failed/pending)与 waybill_code。", - "buildSubOrderDetails 回查最终状态:status=1+waybill→allocated,status=0→failed,无记录→failed。" - ], - "module": "order.pendingOrder" - }, - { - "version": "2026.07.27-system-01", - "date": "2026-07-27", - "type": "added", - "summary": "新增 order.packing 打包任务模块:list/get 查询 + setEndTime 设置结束时间,含视频 CDN URL 拼接与状态回写", - "methods": [ - "order.packing.list", - "order.packing.get", - "order.packing.setEndTime", - "order.packing.forceRecord" - ], - "notes": [ - "新增 order.packing.list:按仓库维度查询打包任务列表,支持分页/筛选/排序,关联工作台、视频和运单信息。", - "新增 order.packing.get:按 id + warehouse_id 查询单条打包任务详情。", - "新增 order.packing.setEndTime:设置打包任务结束时间,入参 id + end_time;若任务状态不是已完成(2)则同步更新为已完成。", - "新增 order.packing.forceRecord:强制重新录制打包任务视频,入参 id;校验录制电脑在线后重置视频状态并推送打印服务。", - "前端默认值逻辑:若任务已有 end_time 则打开时默认为当前时间,否则默认为 start_time + 5分钟。", - "视频 URL 自动拼接 CDN 域名前缀:http://w{warehouseId}-c{recordingComputerId}.o.gztbyc.com{videoPath};录制电脑从 wms_print_computer 按 is_recording=true 获取。", - "视频响应新增 status 字段(created/recording/completed/failed),与数据库 ENUM 保持一致。", - "pack_task_video Model 的 status 字段从 TINYINT 改为 STRING(20) 以匹配 DB ENUM 迁移。", - "forceRecord 通过打印服务 /record/force 推送录制任务,传入 pack_task_id、warehouse_id、computer_id、camera_ids。" - ], - "module": "order.packing" - }, - { - "version": "2026.07.10-system-01", - "date": "2026-07-10", - "type": "added", - "summary": "新增 storage.report.searchStore 货主侧库存报表,以 store_id 为主维度查询库存流水", - "methods": [ - "storage.report.searchStore", - "storage.report.exportStore" - ], - "notes": [ - "新增 searchStore 方法:与 search 共享核心逻辑,通过 searchMode='store' 切换主维度从 warehouse_id → store_id。", - "新增 exportStore 方法:与 export 共享核心逻辑,支持货主侧导出 Excel(含汇总 + 变更记录两个 sheet)。", - "systems 层 search/export 方法新增 searchMode 参数(默认 'warehouse'),不影响现有 warehouse 侧行为。", - "货主侧使用 ctx.user.store_id 作为主维度 store_id,辅助维度支持 warehouse_ids 过滤特定仓库。", - "systemMethods 层 searchStore 从 where.warehouse_ids 取值传给 search 的 storeIds(承载 warehouse 过滤)。", - "输出新增 warehouse_id / warehouse_name 字段,货主侧可区分不同仓库的库存。search 方法也同步输出这两个字段(向后兼容)。", - "修复 getStockDetails 的 warehouseId 判断:从 != null 改为 !== undefined,使显式传 null 可跳过 warehouse 过滤。", - "修复 loadReportReferenceMaps 未传递 warehouseId 给 getStockDetails 的问题。" - ], - "module": "storage.report" - }, - { - "version": "2026.07.09-system-01", - "date": "2026-07-09", - "type": "updated", - "summary": "签约 sign 方法改造:统一当前主体→store_id,解除角色校验,仓库可签仓库", - "methods": [ - "storeWarehouse.store.sign", - "storeWarehouse.warehouse.sign" - ], - "notes": [ - "resolvePairIds:统一当前主体始终在 store_id(货主方/消费方),对方在 warehouse_id(仓库方/提供方)。不再根据 isWarehouse 分支。", - "getCounterparty:移除 expectedRole 角色校验(仓库不再只能签货主,可签仓库)。", - "findScopedRelation:改为 OR 查询 store_id/warehouse_id 两边,兼容新旧签约数据。", - "sign preview:counterparty.role 改为根据对方 project 真实返回(warehouse/store),不再硬编码反推。", - "签仓库:仓库发起签约时对方 ID 传 counterparty_id,系统自动将当前仓库放 store_id。" - ], - "module": "storeWarehouse" - }, - { - "version": "2026.07.08-system-01", - "date": "2026-07-08", - "type": "updated", - "summary": "storeWarehouse.store.list 与 storeWarehouse.warehouse.list 拆分实现,不再共用;仓库侧支持查询外部合作仓库", - "methods": [ - "storeWarehouse.store.list", - "storeWarehouse.warehouse.list" - ], - "notes": [ - "拆分:store.list 调用 listForStore,warehouse.list 调用 listForWarehouse,不再共用同一个 list 方法。", - "新规则:两个方法均按 store_id = 当前主体ID 过滤(主体在 store_id 为货主方/消费方,对方在 warehouse_id 为仓库方/提供方)。", - "warehouse.list 新增支持查询外部合作仓库:当对方主体的 project='warehouse' 时为仓库-仓库合作,counterparty_role='warehouse'。", - "响应新增 counterparty_role 字段(store/warehouse),标识对方主体的真实角色。", - "warehouse.list 响应 use_status 改为 store_use_status(仓库在 store_id 方时,己方启用状态应为 store_use_status)。", - "旧 list 方法保留标记为 @deprecated,保持向后兼容。", - "新增 buildListWhereByStoreId 统一按 store_id 维度构建查询条件。" - ], - "module": "storeWarehouse" - }, - { - "version": "2026.07.06-system-01", - "date": "2026-07-06", - "type": "updated", - "summary": "order.wave.batchList:响应新增 pick_assignment_status(拣货分配状态),按订单 pick_status 聚合判定", - "methods": [ - "order.wave.batchList" - ], - "notes": [ - "响应 list 每项新增字段 pick_assignment_status (string):拣货分配状态,按波次下订单的 pick_status 聚合判定。", - "取值语义与 resolveAssignmentStatus 一致,自定义标签:未拣货(全 none)、部分拣货(混合且无 error)、已拣货(全 fin)、拣货异常(含 error)。", - "SQL 子查询新增 pick_none_count / pick_fin_count / pick_error_count 聚合列。" - ], - "module": "order.wave" - }, - { - "version": "2026.07.05-system-01", - "date": "2026-07-05", - "type": "added", - "summary": "新增 pick.wavePickComplete:传入 wave_id 一键完成整个波次拣货,内部复用 query 去重与任务创建逻辑后自动调用 wavePickTaskComplete(mode=1)", - "methods": [ - "pick.wavePickComplete" - ], - "notes": [ - "新增方法:pick.wavePickComplete,入参 wave_id(number,必填)。", - "内部流程:按 wave_id 查波次 → 活动任务去重(同用户复用 / 他人409冲突)→ 完成任务去重 → 无任务则创建(source=2 后台抓取)→ 调用 pick.wavePickTaskComplete mode=1 全部确认。", - "创建任务 remark 格式:pick.wavePickComplete wave_id={waveId},用于与 pick.query 区分。", - "响应:task_id、status(completed / already_completed)、tip、confirmed_order_ids、is_completed、progress。", - "错误码:400(参数/波次无订单)、401(缺少操作人)、404(波次不存在)、409(他人活动任务冲突)、500(创建/完成失败)。" - ], - "module": "pick" - }, - { - "version": "2026.07.03-system-02", - "date": "2026-07-03", - "type": "added", - "summary": "新增 order.pendingOrder.updateRemark:批量修改待处理订单备注(remark),不受 post_status 限制", - "methods": [ - "order.pendingOrder.updateRemark" - ], - "notes": [ - "新增方法:order.pendingOrder.updateRemark,用于批量修改待处理订单的备注(remark)字段。", - "入参:ids(number[],必填,正整数数组,不能为空)、remark(string,必填,最大500字符)。", - "特性:不受 post_status 限制,可对所有状态的订单生效;纯批量不支持单ID。", - "更新成功后写入操作日志。", - "响应:updated_count(number,实际更新行数)、ids(number[],原样返回请求的ID数组)。", - "错误码:400(ids 不能为空 / ids 仅支持正整数数组 / remark 不能为空)。" - ], - "module": "order.pendingOrder" - }, - { - "version": "2026.07.03-system-01", - "date": "2026-07-03", - "type": "updated", - "summary": "将 quick.waybill.toOrder 迁移为 index.toOrder 并移入基础模块,新增 waves 返回字段", - "methods": [ - "quick.waybill.toOrder", - "index.toOrder" - ], - "notes": [ - "移除快捷操作(quick)模块分组,原 quick.waybill.toOrder 方法从 methods/system.json 删除。", - "在基础模块(index)新增 index.toOrder 方法:入参仍为 waybill_code,响应从单一 order_id 扩展为 order_id + waves 结构。", - "waves 为数组,每项含 wave_id(波次ID)、wave_no(波次号)、order_ids(波次下所有订单ID列表),无波次时为空数组。", - "查询路径:运单号 → wms_order_express(status=1)→ order_id + warehouse_id → 遍历 current/history/dispatch 表获取波次信息 → 再遍历多表获取同波次所有订单ID。" - ] - }, - { - "date": "2026-06-24", - "type": "addition", - "summary": "新增批量绑定入库单明细与收货单明细接口,支持明细级数量分配与部分成功", - "version": "2026-06-24-add-bind-receiving-details", - "methods": [ - "storage.entry.bindReceivingDetails" - ], - "notes": [] - }, - { - "date": "2026-06-24", - "type": "deprecation", - "summary": "废弃手动匹配入库单收货单接口,由 storage.entry.bindReceivingDetails 替代", - "version": "2026-06-24-deprecate-manual-match-entry-order", - "methods": [ - "storage.receiving.manualMatchEntryOrder" - ], - "notes": [] - }, - { - "version": "2026.06.16-system-03", - "date": "2026-06-16", - "summary": "order.wave.waveStrategyFallbackOrderList 响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", - "methods": [ - "order.wave.waveStrategyFallbackOrderList" - ], - "notes": [ - "响应 list 每项新增字段 items_weight (number|null):订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null。", - "响应 list 每项新增字段 weight_type (string):重量类型中文标签,来自 wms_order.weight_type 经 formatWeightTypeLabel 转换;取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。" - ], - "type": "updated", - "module": "order.wave" - }, - { - "version": "2026.06.16-system-04", - "date": "2026-06-16", - "summary": "order.wave.singleOrderFetchList 响应新增 items_weight(总重量g)字段", - "methods": [ - "order.wave.singleOrderFetchList" - ], - "notes": [ - "响应 list 每项新增字段 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", - "为 null 时返回 null。" - ], - "type": "updated", - "module": "order.wave" - }, - { - "version": "2026.05.20-system-03", - "date": "2026-05-20", - "summary": "新增 storeWarehouse.store.queryPrintQuantityLogs:按 store_id 分页查询面单余额变更日志", - "methods": [ - "storeWarehouse.store.queryPrintQuantityLogs" - ], - "notes": [ - "新增方法:storeWarehouse.store.queryPrintQuantityLogs,用于按货主(store_id)分页查询面单余额变更日志。", - "入参:store_id(必填)、page(可选)、page_size / pageSize(可选,兼容别名)。", - "仅同步 methods/system.json 与本变更记录,不修改业务代码或测试。", - "返回:使用默认分页格式,响应在 `data` 下包含 `list`(变更日志数组)和 `pagination` 对象,`pagination` 字段:`page`、`pageSize`、`total`、`totalPages`、`hasPrevious`、`hasNext`。" - ], - "type": "added", - "module": "storeWarehouse" - }, - { - "version": "2026.05.13-system-01", - "date": "2026-05-13", - "summary": "完善 print.send 的 API 文档与返回说明", - "methods": [ - "print.send" - ], - "notes": [ - "补充请求参数说明:computerId、printer、template、data、type 标为必填,count、timestamp 保持可选。", - "补充 template 的子字段说明:page_width、page_height、template_content。", - "补充响应结构:flag、code、message、printId;其中成功时 code=200。", - "补充错误码说明:1001 对应不支持的打印类型,504 对应打印任务发送失败(包含打印机不存在、脱机、通讯失败等场景)。" - ], - "type": "updated" - }, - { - "version": "2026.05.08-system-06", - "date": "2026-05-08", - "summary": "新增取消拣货任务接口:order.wave.wavePickTaskCancel", - "methods": [ - "order.wave.wavePickTaskCancel" - ], - "notes": [ - "接口功能:取消拣货任务,同时释放关联波次(物理删除波次记录,订单回池)、解绑拣货车、写操作日志。", - "限制:仅允许在任务状态为 0(待开始)、1(拣货中)、2(待复核)时取消;状态为 3(已完成)或 9(已取消)时禁止取消,返回 400。", - "事务内操作:将任务状态更新为 9(已取消)、删除关联波次、清空订单 wave_id(回池)、解绑拣货车、写入 action_log 与 order_pick_trace;若有任一步骤失败则回滚并返回 500。" - ], - "type": "added" - }, - { - "version": "2026.07.01-system-01", - "date": "2026-07-01", - "summary": "storage.directInbound.addItem 参数名修正:entry_order_code → entry_order_id,类型 string → number", - "methods": [ - "storage.directInbound.addItem" - ], - "notes": [ - "文档 params 中 entry_order_code(string)改为 entry_order_id(number),与代码 app/service/systems/inbound_direct_log.js 第 544 行实际校验保持一致", - "同步修正 app/service/systemMethods/storage/direct_inbound.js JSDoc:@param {string} data.entry_order_code → @param {number} data.entry_order_id" - ], - "type": "fixed", - "module": "storage.directInbound" - }, - { - "version": "2026.07.01-system-02", - "date": "2026-07-01", - "summary": "新增 storage.entry.queryEntryLogs 接口文档定义", - "methods": [ - "storage.entry.queryEntryLogs" - ], - "notes": [ - "代码 method 层(systemMethods/storage/entry.js L284)和 systems 层(systems/operation_log.js L318)均已实现,补充文档定义", - "参数:id(number, required)、page(number, optional, 默认1)、pageSize(number, optional, 默认20)" - ], - "type": "added", - "module": "storage.entry" - }, - { - "version": "2026.06.18-system-01", - "date": "2026-06-18", - "summary": "order.pendingOrder.downloadCreateTemplate:模板列顺序调整,店铺名称(shop_nick)从末尾移至第2列B列,紧接*订单号之后", - "methods": [ - "order.pendingOrder.downloadCreateTemplate" - ], - "notes": [ - "调整 Excel 导入模板列顺序:店铺名称(shop_nick)从原第25列(Y列/末尾)移动至第2列(B列),紧跟在*订单号(delivery_order_code)之后。", - "同步更新 description 中的列顺序描述,明确 25 列(A-Y)的完整排列。", - "响应结构中移除冗余的 shop_nick 字段(模板列不属于 API 响应字段)。" - ], - "type": "updated", - "module": "order.pendingOrder" - }, - { - "version": "2026.05.17-system-09", - "date": "2026-05-17", - "summary": "为 storage.receiving.deleteDetail 文档补充约束:收货单已完成/已取消时禁止删除明细", - "methods": [ - "storage.receiving.deleteDetail" - ], - "notes": [ - "在 storage.receiving.deleteDetail 的 description 中补充:若关联收货单状态为 completed(已完成)或 cancelled(已取消),接口会返回删除失败(400),不允许删除明细。", - "在 errors 中补充或合并 400 描述以明确禁止删除已完成/已取消的收货单明细。" - ], - "type": "updated", - "module": "storage" - }, - { - "version": "2026.05.17-system-08", - "date": "2026-05-17", - "summary": "完善 storage.receiving.deleteDetail 文档:补充入参/返回/错误说明,明确用户上下文来源及删除约束", - "methods": [ - "storage.receiving.deleteDetail" - ], - "notes": [ - "补充 storage.receiving.deleteDetail 的参数说明:detail_id(来自请求体,必填);说明 creator_id 与 warehouse_id 来源于当前登录用户(ctx.user.employees_id / ctx.user.store_id)。", - "补充返回结构:成功时返回 code/message/data,data 包含 details(删除后剩余明细)和 selectId(建议选中ID);product_snapshot 若存在将被解析为对象或 null。", - "补充常见错误码:404(明细不存在或无权访问),400(收货单状态/已入库/删除失败),500(服务器异常)。", - "仅文档更新,不修改任何业务实现。" - ], - "type": "updated", - "module": "storage" - }, - { - "version": "2026.05.17-system-05", - "date": "2026-05-17", - "summary": "移除 storage.receiving.addItem(方法已下线/实现不存在)", - "methods": [ - "storage.receiving.addItem" - ], - "notes": [ - "仅同步文档:从 methods/system.json 中移除 storage.receiving.addItem,未修改任何业务代码或实现。", - "该方法已下线或实现不存在;请以当前 methods/system.json 的 SSOT 为准。" - ], - "type": "removed" - }, - { - "version": "2026.05.17-system-04", - "date": "2026-05-17", - "summary": "新增 stock.warehouse.import:仓库商品批量 JSON 导入(数组导入),SKU 为空创建/非空更新,支持 goods_code/货物编码 导入,更新写操作日志", - "methods": [ - "stock.warehouse.import" - ], - "notes": [ - "支持直接传入商品数组 JSON(主方式为数组,兼容 rows/items/list/data 包装)。", - "每项仅需传商品相关字段;SKU 为空时创建新商品,SKU 非空时为更新操作。", - "更新操作会写入操作日志以便审计。", - "支持导入 goods_code(货物编码)字段别名。", - "仅同步文档,不修改业务代码或实现。" - ], - "type": "added" - }, - { - "version": "2026.05.17-system-03", - "date": "2026-05-17", - "summary": "完善 stock.warehouse.handleBatchChange 文档:补充入参/出参/错误示例", - "methods": [ - "stock.warehouse.handleBatchChange" - ], - "notes": [ - "补充方法入参说明:ids/method/value 的字段类型、是否必填、来源与示例;完善响应结构示例与常见错误码说明。", - "仅文档更新,不改业务实现或语义。" - ], - "type": "updated" - }, - { - "version": "2026.05.17-system-02", - "date": "2026-05-17", - "summary": "stock.warehouse.export 由同步改为异步任务并新增进度查询 exportTaskProgress", - "methods": [ - "stock.warehouse.export", - "stock.warehouse.exportTaskProgress" - ], - "notes": [ - "stock.warehouse.export 改为异步提交导出任务:接口返回 task_id 与受理信息,后端异步生成导出文件。", - "新增 stock.warehouse.exportTaskProgress:按 task_id 查询任务状态与进度;当 status=success 时返回 download_url 供客户端下载;未找到时 status=not_found。", - "调用方式:先调用 stock.warehouse.export 获取 task_id,然后轮询 stock.warehouse.exportTaskProgress 直到 status=success 并获取 download_url。" - ], - "type": "updated" - }, - { - "version": "2026.05.17-system-01", - "date": "2026-05-17", - "summary": "新增 stock.warehouse.export:仓库商品导出(支持 where/sort),返回文件下载信息", - "methods": [ - "stock.warehouse.export" - ], - "notes": [ - "新增方法:stock.warehouse.export。复用 stock.warehouse.list 的 where/sort 过滤语义(支持 operator/value/type 标准 where 结构与历史简写)。", - "响应返回导出结果(示例字段:file_key、url),表示生成的 Excel 已上传并可下载/查询。" - ], - "type": "added" - }, - { - "version": "2026.05.16-system-01", - "date": "2026-05-16", - "summary": "同步 setting.expressInterface.create 文档入参:移除未使用的 express_platform_id,标注必填字段", - "methods": [ - "setting.expressInterface.create" - ], - "notes": [ - "移除文档中 express_platform_id(服务端实现未使用);确认必填字段 name/express_code/platform_code;仓库由系统自动填充,禁止传入 warehouse_id/warehouseId。" - ], - "type": "updated" - }, - { - "version": "2026.05.12-system-01", - "date": "2026-05-12", - "summary": "调整订单打印中间态返回结构为 waveGroups(波次 -> 平台 -> 订单)", - "methods": [ - "order.print.getWavePlatformPrintData" - ], - "notes": [ - "主要变更:将方法的主返回结构改为 waveGroups,按波次分组,波次内按平台分组,平台内为订单列表(波次 -> 平台 -> 订单)。", - "兼容性:保留旧字段 platform_groups 与 order_list 作为向后兼容字段,但文档主结构与推荐使用为 waveGroups。", - "返回结构说明:summary(total_waves/total_orders/total_platforms)、wave_ids(通过过滤的波次ID数组)、waveGroups(数组,项含 wave_id、wave_no、order_count、platforms[...],platforms项含 platform、platform_name、order_count、orders[...])、ext(missing_wave_ids、filtered_wave_ids)。", - "errors:保留 400 / 500 不变。" - ], - "type": "modified" - }, - { - "version": "2026.05.11-system-05", - "date": "2026-05-11", - "summary": "order.wave.batchList:支持 express/print 分配状态筛选,入参改为英文枚举(express/print)", - "methods": [ - "order.wave.batchList" - ], - "notes": [ - "修复 where.express_assignment_status 可按快递分配状态筛选。", - "新增 where.print_assignment_status 筛选(按打印分配聚合判断)。", - "express_assignment_status / print_assignment_status 要求使用英文枚举值:express=unassigned/partially_assigned/assigned,print=unprinted/partially_printed/printed;storage_assignment_status 继续兼容中文枚举(未分配/部分分配/已分配)。", - "若传入非法枚举值,接口返回 400(参数校验失败),message 中会说明允许取值。" - ], - "type": "updated" - }, - { - "version": "2026.05.11-system-04", - "date": "2026-05-11", - "summary": "调整 order.wave.waveStrategyFetchAdmin:由创建任务改为直接创建波次(不创建拣货任务)", - "methods": [ - "order.wave.waveStrategyFetchAdmin" - ], - "notes": [ - "接口行为变更:按策略直接抓取命中订单并创建波次,不再创建拣货任务(不返回 task_id/task_no 等任务字段)。", - "响应调整为建波结果:fetch_state(1=成功/2=失败)、wave_ids、wave_nos、created_wave_count、created_order_count、order_ids、(可选)wave_prefix、wave_prefix_source、tip/message。", - "错误调整:策略校验失败返回 400(并可能返回 validation_errors),缺少仓库上下文返回 400,建波失败返回 500 并在 message 中说明。" - ], - "type": "updated" - }, - { - "version": "2026.05.11-system-03", - "date": "2026-05-11", - "summary": "更新 pick.query:由查询拣货明细调整为按 keyword 获取/创建拣货任务", - "methods": [ - "pick.query" - ], - "notes": [ - "入参由 waybill_code/full_display 调整为 keyword(支持运单号或波次号)。", - "接口语义调整为任务化返回:命中活动任务则返回 existing 任务ID;无活动任务则创建并返回 created 任务ID。", - "新增任务归属冲突错误:当活动任务创建人非当前用户时返回冲突提示,并附带创建人及任务ID信息。" - ], - "type": "updated" - }, - { - "version": "2026.05.11-system-02", - "date": "2026-05-11", - "summary": "新增 pick.wavePickTaskCurrent:PDA 无参查询当前进行中拣货任务", - "methods": [ - "pick.wavePickTaskCurrent" - ], - "notes": [ - "新增 PDA 专用无参接口 pick.wavePickTaskCurrent。", - "按当前登录用户上下文(pick_user_id + warehouse_id)查询状态在 0/1/2 的最新任务。", - "命中返回 task_id,未命中返回 task_id=null。" - ], - "type": "added" - }, - { - "version": "2026.05.10-system-04", - "date": "2026-05-10", - "summary": "pick.wavePickTaskDetail 新增按任务类型区分的 picking_view 形态输出", - "methods": [ - "pick.wavePickTaskDetail" - ], - "notes": [ - "新增响应字段:picking_view(object),按 task.pick_mode 区分 5 种形态输出。", - "picking_view 字段说明:mode_code, mode_name, require_box_allocations, group_by, sort_by, items[](每项含 space_id、space_name、location_space、item_code、item_name、stock_id、total_qty、box_allocations[])。", - "当 pick_mode=1/3/4 时 require_box_allocations=true;当 pick_mode=2/5 时 require_box_allocations=false。" - ], - "type": "updated" - }, - { - "version": "2026.05.10-system-02", - "date": "2026-05-10", - "summary": "order.wave.waveStrategyFetchPda/Admin 返回新增 fetch_state 三态与简短 tip", - "methods": [ - "order.wave.waveStrategyFetchPda", - "order.wave.waveStrategyFetchAdmin" - ], - "notes": [ - "新增返回字段:fetch_state(number)、tip(string)、can_enter_pick_flow(boolean)", - "fetch_state 含义:1=创建成功(返回 task_id/task_no),2=普通失败(task_id=null),3=存在未完成任务(返回 existing task_id/task_no,前端可直接进入拣货流程)", - "当 fetch_state=3 时,字段 can_enter_pick_flow=true,表示前端可直接进入拣货流程;tip 为简短提示文本" - ], - "type": "updated" - }, - { - "version": "2026.05.10-system-03", - "date": "2026-05-10", - "summary": "裁剪 pick.wavePickTaskDetail 返回:移除 waves/orders,精简 task 并补充 boxes 拣货统计字段", - "methods": [ - "pick.wavePickTaskDetail" - ], - "notes": [ - "移除响应中的 waves 与 orders 子表,接口仅返回精简的 task、boxes、picking_details 与 picking_summary。", - "task 子字段裁剪为:task_id, task_no, status, pick_mode, start_at, finish_at, batch_no。", - "boxes 补充并明确返回:ref_label(箱参考标签)、required_qty(箱内需拣总数)、picked_qty(已拣数量)。", - "本次变更为文档层面的返回裁剪,前端应以新字段集合为准,旧字段可能不再返回。" - ], - "type": "updated" - }, - { - "version": "2026.05.10-system-01", - "date": "2026-05-10", - "summary": "order.wave.waveStrategyList 新增 strategy_type 最小过滤(散单/团购)", - "methods": [ - "order.wave.waveStrategyList" - ], - "notes": [ - "新增 strategy_type 过滤,仅 1/2", - "支持顶层 strategy_type 和 where.strategy_type,顶层优先", - "当前不引入其他 where 字段" - ], - "type": "updated" - }, - { - "version": "2026.05.09-system-02", - "date": "2026-05-09", - "summary": "新增 pick.wavePickTaskDetail:按任务ID解析拣货任务详情", - "methods": [ - "pick.wavePickTaskDetail" - ], - "notes": [ - "新增 pick.wavePickTaskDetail:传入 task_id 获取拣货任务完整信息,包含主表字段(task/pick_mode/status/wave_count/order_count/box_count 等)及三张子表数据(waves/orders/boxes)。", - "安全限制:接口会校验当前登录用户(operator_id/employees_id)与任务的 pick_user_id 是否一致;不一致时直接返回 403,不返回任何拣货信息。", - "鉴权配置:noNeedRight=true,noNeedAuth=true,isNeedLogin=true。" - ], - "type": "added" - }, - { - "version": "2026.05.08-system-05", - "date": "2026-05-08", - "summary": "order.wave.batchList:新增 source 字段并支持 where.source 过滤,返回 list item 中新增 source 字段", - "methods": [ - "order.wave.batchList" - ], - "notes": [ - "新增 where.source(可选,number)用于按来源过滤:0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务;不传则不过滤。", - "响应 list 每条记录新增字段 source(number),用于区分波次来源。", - "仅更新文档,业务代码不在此变更范围。" - ], - "type": "updated" - }, - { - "version": "2026.05.08-system-04", - "date": "2026-05-08", - "summary": "完善 order.wave.wavePickTaskList 文档:补充入参、分页与返回字段兼容说明", - "methods": [ - "order.wave.wavePickTaskList", - "order.wave.wavePickTaskCancel" - ], - "notes": [ - "入参补充:warehouse_id(必填)、status(支持单值或数组,建议传数组)、source、keyword、page_no、page_size;保留 pagination 对象以兼容旧客户端。", - "兼容说明:接口同时支持历史 where 结构与顶层参数;当存在同名顶层参数时以顶层参数优先;pagination 支持 page/current 与 pageSize/size 别名。", - "返回格式:响应包含 total 与 list;list 每项包含字段:task_id、task_no、status、source、pick_mode、wave_count、order_count、box_count、operator_id、operator_name、start_at、finish_at、created_at。为兼容旧客户端,响应同时保留旧字段:pick_user_id、pick_user_name、start_time、finish_time、create_time。", - "入参 strategy_id 当前主表未存,接口会忽略该过滤,不建议使用。", - "默认排序:create_time desc.", - "文档变更:移除 order.wave.wavePickTaskCancel 的入参 operator_id 与 warehouse_id;入参改为仅支持 task_ids(数组,必填),不再兼容单个 task_id;操作人与仓库由请求上下文(例如当前登录用户上下文)自动获取;若上下文缺失接口将返回错误。响应补充批量结果字段:cancelled_count、task_ids、task_nos(若后端返回)。仅更新文档,未修改业务实现。" - ], - "type": "updated" - }, - { - "version": "2026.05.08-system-03", - "date": "2026-05-08", - "summary": "升级按策略抓取接口为创建任务主流程:order.wave.waveStrategyFetchPda / order.wave.waveStrategyFetchAdmin", - "methods": [ - "order.wave.waveStrategyFetchPda", - "order.wave.waveStrategyFetchAdmin" - ], - "notes": [ - "将 PDA/Admin 场景的按策略抓取接口由受理壳方法升级为 '创建任务主流程':接口会执行参数校验并在同步响应中创建任务记录(state=created),返回 task_id、task_no、plan 与 plan_summary 供前端展示与后续查询。", - "入参新增/扩展与创建流程相关字段:至少包含 cart_id(关联拣货车/作业车ID)、source(操作来源语义)并保留并透传 strategy_id 与 strategy_params(策略参数),以支持在创建阶段对策略进行局部覆盖或透传。", - "成功返回示例字段:state=created、task_id、task_no、plan(对象)和 plan_summary(字符串);失败场景会返回 validation_errors(数组,每项含 field/message)或 message 描述创建失败原因。", - "边界说明:当前为最小主流程(创建与计划预览),后续扫描/任务执行阶段(如实际抓取订单、写入 wave 等)将在后续版本中追加与完善。" - ], - "type": "updated" - }, - { - "version": "2026.05.08-system-02", - "date": "2026-05-08", - "summary": "调整按策略抓取壳方法:order.wave.waveStrategyFetch 更名为 order.wave.waveStrategyFetchPda,并新增 order.wave.waveStrategyFetchAdmin", - "methods": [ - "order.wave.waveStrategyFetch", - "order.wave.waveStrategyFetchPda", - "order.wave.waveStrategyFetchAdmin" - ], - "notes": [ - "waveStrategyFetchPda 仅用于 PDA 场景", - "waveStrategyFetchAdmin 仅用于后台管理场景", - "两者当前均为壳子受理方法,不执行真实抓取" - ], - "type": "updated" - }, - { - "version": "2026.05.08-system-01", - "date": "2026-05-08", - "summary": "新增 order.wave.waveStrategyFetch:按策略提交抓取任务(壳子方法)", - "methods": [ - "order.wave.waveStrategyFetch" - ], - "notes": [ - "当前方法为壳子方法:仅受理并返回任务受理信息,不执行真实抓取逻辑,后续补齐执行链路。" - ], - "type": "added" - }, - { - "version": "2026.05.07-system-05", - "date": "2026-05-07", - "summary": "新增 order.wave.waveStrategyCreate 与 order.wave.waveStrategyUpdate:波次策略创建与更新接口(含参数校验与版本推进)", - "methods": [ - "order.wave.waveStrategyCreate", - "order.wave.waveStrategyUpdate" - ], - "notes": [ - "仓库 ID 与创建人(creator_name)由当前登录仓库/操作者上下文获取,接口不接受外部覆盖。", - "入参 allowed_owners 与 allowed_expresses 会校验是否在系统可用范围内(基于仓库签约货主或系统快递列表),若存在非法值接口会直接报错(400)。", - "max_same_structure 受仓库配置 min_group_order_fetch_quantity 限制:若传入值 >= min_group_order_fetch_quantity,则自动下调为 min_group_order_fetch_quantity - 1(最小值为 1)。", - "新建/更新成功后会触发仓库的 wave_strategy_version 自增(+1)并失效相关仓库配置缓存,调用方可通过策略版本推进或缓存变化感知策略已生效。" - ], - "type": "added" - }, - { - "version": "2026.05.07-system-06", - "date": "2026-05-07", - "summary": "收敛 order.wave.waveStrategyFallbackOrderList 返回字段,限定 where 白名单,补充 order.wave.singleFetchByIds 别名与返回语义", - "methods": [ - "order.wave.waveStrategyFallbackOrderList", - "order.wave.singleFetchByIds" - ], - "notes": [ - "收敛 order.wave.waveStrategyFallbackOrderList response.list 字段为 id, delivery_no, tracking_no, items_count, items_total, sys_logistics_name, store_name, province, sys_platform_name, item_snapshot;item_snapshot 格式示例:商品名称*数量|...。", - "限制 order.wave.waveStrategyFallbackOrderList.where 白名单,禁止传入 warehouse_id / warehouseId;传入未列出字段或别名冲突将返回 400。", - "补充 order.wave.singleFetchByIds:明确支持 ids / order_ids / orderIds 三个别名(优先顺序 ids -> order_ids -> orderIds)并说明返回字段 fetched_order_ids、excluded_existing_wave_order_ids、skipped_order_ids、not_found_order_ids 的语义与兼容性。" - ], - "type": "updated" - }, - { - "version": "2026.05.07-system-04", - "date": "2026-05-07", - "summary": "更新 order.wave.waveStrategyFallbackOrderList,新增商品快照字段 item_snapshot", - "methods": [ - "order.wave.waveStrategyFallbackOrderList" - ], - "notes": [ - "item_snapshot 返回格式为 商品名称1*数量|商品名称2*数量" - ], - "type": "updated" - }, - { - "version": "2026.05.07-system-03", - "date": "2026-05-07", - "summary": "新增 order.wave.waveStrategyQuickScan 与进度查询接口", - "methods": [ - "order.wave.waveStrategyQuickScan", - "order.wave.waveStrategyQuickScanTaskProgress" - ], - "notes": [ - "同仓只允许一个扫描任务并使用缓存锁;扫描范围为当前表非待审核、未分配波次且订单策略版本与仓库当前版本不一致的订单;命中策略标记 wave_scan_result=1,否则=2" - ], - "type": "added" - }, - { - "version": "2026.05.07-system-02", - "date": "2026-05-07", - "summary": "新增 order.wave.waveStrategyList:查询当前仓库波次策略列表", - "methods": [ - "order.wave.waveStrategyList" - ], - "notes": [ - "从 wms_wave_strategy 拉取当前仓库的波次策略列表,分页返回" - ], - "type": "added" - }, - { - "version": "2026.05.07-system-01", - "date": "2026-05-07", - "summary": "移除 order.wave.singleOrderFetchDetailList,新增 order.wave.waveStrategyFallbackOrderList(内置固定筛选条件)", - "methods": [ - "order.wave.singleOrderFetchDetailList", - "order.wave.waveStrategyFallbackOrderList" - ], - "notes": [ - "移除 order.wave.singleOrderFetchDetailList。", - "新增 order.wave.waveStrategyFallbackOrderList。", - "新接口基于订单通用查询口径,固定内置筛选条件:step != 0、wave_id = 0、wave_scan_result = 2。" - ], - "type": "updated" - }, - { - "version": "2026.05.06-system-06", - "date": "2026-05-06", - "summary": "新增 order.wave.singleOrderFetchDetailList:订单级散单候选明细视图", - "methods": [ - "order.wave.singleOrderFetchDetailList" - ], - "notes": [ - "新增 order.wave.singleOrderFetchDetailList:提供订单级的散单候选明细列表,返回按订单聚合的明细(非分组级)。", - "返回订单级而非分组级;响应每项包含订单 id、group_count、item_detail_machine、item_detail_machine_snapshot、item_detail、item_snapshot、logistics_name、store_id、distinguish_express、create_at 与 status_summary 等关键字段。", - "仍沿用 same_order_quantity 阈值来排除团购命中分组(仅保留 group_count < same_order_quantity 的候选项)。", - "singleOrderFetchList 暂保留以兼容现有前端,前端可在切换到订单级视图后迁移到本接口。" - ], - "type": "added" - }, - { - "version": "2026.05.06-system-05", - "date": "2026-05-06", - "summary": "storage.receiving.get 返回扩展:data.details[*] 新增 box_remainder、box_weight", - "methods": [ - "storage.receiving.get" - ], - "notes": [ - "storage.receiving.get 的响应在 data.details[*] 中新增可选字段:box_remainder(箱内剩余数量/零散数量,number,默认 0)与 box_weight(实测箱重,number,默认 0)。", - "兼容性:新增字段为可选,旧客户端无需修改;建议前端在需要展示箱内余量/箱重时使用这些字段。" - ], - "type": "updated" - }, - { - "version": "2026.05.06-system-04", - "date": "2026-05-06", - "summary": "storage.receiving.getReceivingDetail 返回扩展:明细增加 box_remainder、box_weight;storage.receiving.completeReceiving 通知包含这两个字段", - "methods": [ - "storage.receiving.getReceivingDetail", - "storage.receiving.completeReceiving" - ], - "notes": [ - "为支持箱规统计与通知回传,getReceivingDetail 的明细项(receiving.details 或 data.details)在响应中新增可选字段:box_remainder(箱内剩余数量/零散数量,number)与 box_weight(实测箱重,number,单位同系统重量)。", - "completeReceiving 在完成收货后会发送通知(或回调),通知 payload/metadata 中将包含每条明细的 box_remainder 与 box_weight 字段,供下游系统/前端展示或审计使用。", - "兼容性:新增字段为可选,旧客户端在未使用这些字段时无需变更。" - ], - "type": "updated" - }, - { - "version": "2026.05.06-system-03", - "date": "2026-05-06", - "summary": "storage.receiving.detailChange:新增入参/出参字段 box_remainder、box_weight", - "methods": [ - "storage.receiving.detailChange" - ], - "notes": [ - "为支持箱规细化与回写,detailChange 新增可选入参 box_remainder(箱内余量/零散数量)和 box_weight(实测箱重,单位同系统重量),写入后会回写至明细并在响应 data 中返回对应字段。", - "兼容性:新增字段为可选,不传入则不影响现有调用;建议前端在需要回写箱余与箱重时一并传入。" - ], - "type": "updated" - }, - { - "version": "2026.05.06-system-02", - "date": "2026-05-06", - "summary": "新增 order.wave.singleFetchByIds:按订单ID抓取到一个散单波次", - "methods": [ - "order.wave.singleFetchByIds" - ], - "notes": [ - "新增 order.wave.singleFetchByIds:按入参 ids(兼容 order_ids/orderIds)去重后筛选当前仓库内待处理且不在波次中的订单,若存在可抓取订单则创建单个散单波次并把这些订单写入该波次(不区分快递);成功后批量写入订单操作日志;若无可抓取订单返回 wave_id=0。", - "接口行为严格对齐实现:过滤条件包含 step in [1,2,3]、status != 'cancel'、outbound_status != 'padding';已在波次的订单会被排除并返回 excluded_existing_wave_order_ids;响应包含 ids、wave_id、wave_no、fetched_order_ids、fetched_order_count、excluded_existing_wave_order_ids、skipped_order_ids、not_found_order_ids。" - ], - "type": "added" - }, - { - "version": "2026.05.06-system-01", - "date": "2026-05-06", - "summary": "新增 order.wave.groupFetch 与 order.wave.singleFetch;order.wave.fetch 保留兼容别名;抓取进度补充上限字段", - "methods": [ - "order.wave.groupFetch", - "order.wave.singleFetch", - "order.wave.fetch", - "order.wave.fetchTaskProgress" - ], - "notes": [ - "新增 order.wave.groupFetch:抓取团购接口(异步任务提交),参数 structure_list 与原 fetch 一致。", - "新增 order.wave.singleFetch:抓取散单接口(异步任务提交),在 structure_list 每项新增必填字段 max_fetch_quantity(最大抓取上限,订单数,正整数)。", - "order.wave.fetch 保留为兼容别名(等同 groupFetch),避免误导客户端。", - "groupFetch/singleFetch/fetch 的响应新增可选字段 fetch_mode;singleFetch 响应额外返回 max_fetch_quantity。", - "order.wave.fetchTaskProgress 的响应增加单模式相关字段:fetch_mode、max_fetch_quantity、limit_reached、stop_reason,用于描述散单抓取的上限与停止原因。" - ], - "type": "updated" - }, - { - "version": "2026.05.05-system-02", - "date": "2026-05-05", - "summary": "order.wave.batchList:新增 where.storage_assignment_status 的过滤语义说明", - "methods": [ - "order.wave.batchList" - ], - "notes": [ - "新增 where 字段 `storage_assignment_status`:类型 string,可选值:`未分配`、`部分分配`、`已分配`;默认不传:不做分配状态限制。", - "过滤语义:`已分配`:聚合后全部 fin;`部分分配`:不含 error,且既不是全 none,也不是全 fin;`未分配`:全 none 或包含 error(异常并入未分配筛选集合)。", - "说明:返回字段 `storage_assignment_status` 的展示值保持不变;包含 error 时仍可能展示“分配异常”,但 where 的过滤语义把异常算到“未分配”集合,避免把过滤语义与展示值混淆。" - ], - "type": "updated" - }, - { - "version": "2026.05.05-system-01", - "date": "2026-05-05", - "summary": "新增 order.wave.singleOrderFetchList:散单候选分组查询(排除团购命中分组)", - "methods": [ - "order.wave.singleOrderFetchList" - ], - "notes": [ - "新增 order.wave.singleOrderFetchList:返回按机器结构分组的散单候选列表,接口会排除已达团购阈值(同组订单数量 >= same_order_quantity 或仓库配置 min_group_order_fetch_quantity)的分组,仅返回同组订单数量 < 阈值 的分组(散单候选)。", - "与 order.wave.groupOrderFetchList 的关键差异:groupOrderFetchList 返回满足团购阈值(>=)的分组;singleOrderFetchList 返回未达阈值(<)的散单候选分组。", - "影响范围:订单波次抓取相关前端/调度服务。兼容性:不影响或修改现有 order.wave.groupOrderFetchList,两个接口可并行使用。" - ], - "type": "added" - }, - { - "version": "2026.05.04-system-04", - "date": "2026-05-04", - "summary": "完善商品编码唯一性校验接口文档,补充 item_id(排除自身)和 owner_id(货主ID)入参说明,新增 unique/isUnique 返回字段描述", - "methods": [ - "stock.warehouse.checkItemCodeUnique" - ], - "notes": [ - "完善商品编码唯一性校验接口文档,补充 item_id(排除自身)和 owner_id(货主ID)入参说明,新增 unique/isUnique 返回字段描述" - ], - "type": "modified" - }, - { - "version": "2026.05.04-system-02", - "date": "2026-05-04", - "summary": "修改 pick.query 入参:order_id -> waybill_code", - "methods": [ - "pick.query" - ], - "notes": [ - "入参从 order_id 改为 waybill_code(快递号),通过快递号查找订单后再查波次拣货信息" - ], - "type": "breaking_change" - }, - { - "version": "2026.05.04-system-01", - "date": "2026-05-04", - "summary": "新增 system method pick.query:按订单查询波次拣货信息", - "methods": [ - "pick.query" - ], - "notes": [ - "按订单查询该订单所属波次的拣货信息,支持 full/full_display/is_full 控制是否完整显示;接口按当前登录用户仓库上下文过滤,防止跨仓越界。" - ], - "type": "added" - }, - { - "version": "2026.05.03-system-09", - "date": "2026-05-03", - "summary": "新增按 request_id 查询分配状态/结果接口", - "methods": [ - "order.pendingOrder.allocateStorageProgress" - ], - "notes": [ - "新增按 request_id 查询储位分配异步任务状态/结果接口,支持 status:submitted/running/success/failed/not_found;success 返回 result(底层分配结果),failed 返回 error(错误信息);兼容 requestId 参数名。" - ], - "type": "updated" - }, - { - "version": "2026.05.03-system-07", - "date": "2026-05-03", - "summary": "新增抓取进度查询接口", - "methods": [ - "order.wave.fetch", - "order.wave.fetchTaskProgress" - ], - "notes": [ - "新增按 task_id 查询抓取任务进度的接口 order.wave.fetchTaskProgress,支持返回 status(submitted/running/success/failed/not_found)及进度相关字段:progress_percent、finished_structure_count、total_fetched_quantity、duration_ms、error、update_time 等;同时明确 order.wave.fetch 为异步任务提交接口,客户端可通过 task_id 调用 order.wave.fetchTaskProgress 查询进度和最终结果。" - ], - "type": "updated" - }, - { - "version": "2026.05.03-system-05", - "date": "2026-05-03", - "summary": "补齐仓库设置模块 setting.warehouse 的 methods 文档", - "methods": [ - "setting.warehouse.getSettings", - "setting.warehouse.getFieldMeta", - "setting.warehouse.saveSettings" - ], - "notes": [ - "补齐仓库配置 methods API 文档" - ], - "type": "updated" - }, - { - "version": "2026.05.03-system-04", - "date": "2026-05-03", - "summary": "order.wave:自动加团新增跳过规则并新增批量结束自动加团接口", - "methods": [ - "order.wave.batchAutoGrouping", - "order.wave.batchFinishAutoGrouping" - ], - "notes": [ - "开启自动加团新增“已打印/超最大波次容量”跳过规则并在响应中返回跳过明细;新增批量结束自动加团接口(将 wave_status=0 的波次批量置为 1)" - ], - "type": "updated" - }, - { - "version": "2026.05.03-system-03", - "date": "2026-05-03", - "summary": "裁剪 order_list 以轻量化返回", - "methods": [ - "order.wave.batchList" - ], - "notes": [ - "移除响应中的 order_list 字段,接口仅返回波次基础信息与状态汇总(order_count / storage_assignment_status / express_assignment_status / print_assignment_status)" - ], - "type": "updated" - }, - { - "version": "2026.05.03-system-02", - "date": "2026-05-03", - "summary": "新增 order.wave.batchAutoGrouping:批量改为自动加团中", - "methods": [ - "order.wave.batchAutoGrouping" - ], - "notes": [ - "新增批量改为自动加团中接口及返回字段" - ], - "type": "updated" - }, - { - "version": "2026.04.22-system-02", - "date": "2026-04-22", - "summary": "新增 order.pendingOrder.syncOrderIds:待处理订单同步透传入口", - "methods": [ - "order.pendingOrder.syncOrderIds" - ], - "notes": [ - "新增 order.pendingOrder.syncOrderIds:仅接收 order_ids 并转发到服务层,当前不做业务处理。", - "接口保留登录态校验,入参仅接受订单 ID 相关字段,响应以服务层返回值为准。", - "该方法用于预留同步链路,后续补齐业务逻辑时再扩展服务层实现。" - ], - "type": "updated" - }, - { - "version": "2026.04.22-system-01", - "date": "2026-04-22", - "summary": "补全订单工作台各模块 detail 方法文档", - "methods": [ - "order.detail", - "order.pendingOrder.detail", - "order.reviewOrder.detail", - "order.expectionOrder.detail", - "order.outboundOrder.detail", - "order.deliveryOrder.detail", - "order.deliveryExpectionOrder.detail", - "order.entrustOrder.detail", - "order.archiveOrder.detail" - ], - "notes": [ - "补全文档:detail 为订单工作台通用详情方法,入参支持 ids/id/order_id/orderId;可选 tableType/tablePosition/type/moduleName,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等。", - "返回包含 order/detail(订单头)、orderItems/items(商品明细)、expresses(运单信息)、waybill_codes(去重运单号数组)。" - ], - "type": "updated" - }, - { - "version": "2026.04.19-system-01", - "date": "2026-04-19", - "summary": "新增方法 setting.expressInterface.listByWarehousePlatformCode:按 warehouse_id + platform_code 查询全字段列表并支持缓存", - "methods": [ - "setting.expressInterface.listByWarehousePlatformCode" - ], - "notes": [ - "新增 setting.expressInterface.listByWarehousePlatformCode:按 warehouse_id + platform_code 返回快递接口的全字段数组(不分页),每条记录包含 express 关联对象(id/code/name/platform 等)。", - "支持缓存,缓存键由 warehouse_id + platform_code 组成;缓存命中将直接返回缓存结果以提升查询性能。", - "在创建/更新/删除操作(setting.expressInterface.create/update/delete)后,会主动清理对应 warehouse_id + platform_code 的缓存以确保数据一致性。" - ], - "type": "added" - }, - { - "version": "2026.04.17-system-08", - "date": "2026-04-17", - "summary": "新增快递编码管理模块批量软删除接口 setting.express.delete", - "methods": [ - "setting.express.delete" - ], - "notes": [ - "新增批量软删除接口 setting.express.delete:接受 ids(数组、逗号字符串或单值),对属于当前仓库且未被删除的记录执行软删除(设置 deleted_at),并清理 express 列表缓存。", - "当任一目标记录的 code 被 wms_express_interface.express_code 引用时,接口会拒绝删除并返回 409,错误信息中包含被引用的编码列表。", - "响应包含 ids、deleted_ids、already_deleted_ids 与 status,已删除与未删除的 id 会明确分类。仅记录已实现行为。" - ], - "type": "added" - }, - { - "version": "2026.04.17-system-05", - "date": "2026-04-17", - "summary": "新增文档分组:平台编码管理模块(收口 index.getPlatformList 与 setting.platform.*)", - "methods": [ - "index.getPlatformList", - "setting.platform.list", - "setting.platform.create", - "setting.platform.update", - "setting.platform.delete" - ], - "notes": [ - "新增独立文档分组 '平台编码管理模块',将平台基础列表(index.getPlatformList)与平台设置管理接口(setting.platform.*)归并为单一分组以便维护;仅文档变更,不修改实现。", - "文档中仅包含已实现的方法与字段,未新增或推断不存在的参数/返回字段。" - ], - "type": "added" - }, - { - "version": "2026.04.17-system-04", - "date": "2026-04-17", - "summary": "新增独立平台设置模块 setting.platform(wms_platfrom_setting)及其 CRUD 接口:list/create/update/delete。", - "methods": [ - "setting.platform.list", - "setting.platform.create", - "setting.platform.update", - "setting.platform.delete" - ], - "notes": [ - "新增独立模块 setting.platform,映射数据表 wms_platfrom_setting;list 支持 where(id/code/name/platform_code/quickWhere)与 pagination(兼容 page/pageSize/page_size);create/update 要求 platform_code 必须存在于系统平台表(wms_platform),且禁止越权写入 warehouse_id;delete 需传入 id 并校验当前仓库范围。" - ], - "type": "added" - }, - { - "version": "2026.04.15-system-07", - "date": "2026-04-15", - "summary": "将 docs/order-workbench-list-api.md 引用统一为 window 链接格式", - "methods": [ - "order.list", - "order.reviewOrder.list", - "order.pendingOrder.list", - "order.outboundOrder.list", - "order.expectionOrder.list", - "order.entrustOrder.list", - "order.deliveryOrder.list", - "order.deliveryExpectionOrder.list" - ], - "notes": [ - "将所有 methods/system.json 中指向 docs/order-workbench-list-api.md 的说明统一替换为 docs/order-workbench-list-api.md 格式,以便 HTML 渲染识别为 window 链接。", - "仅修改 methods/system.json 的文档字段,不涉及任何业务代码或接口契约变化。" - ], - "type": "updated" - }, - { - "version": "2026.04.15-system-06", - "date": "2026-04-15", - "summary": "订单工作台列表文档补全 raw 字段字典与中文语义说明", - "methods": [ - "order.list", - "order.reviewOrder.list", - "order.pendingOrder.list", - "order.outboundOrder.list", - "order.expectionOrder.list", - "order.entrustOrder.list", - "order.deliveryOrder.list", - "order.deliveryExpectionOrder.list", - "order.archiveOrder.list" - ], - "notes": [ - "在 docs/order-workbench-list-api.md 中补充所有订单列表通用 raw 字段字典,明确每个字段的中文语义与 enum 取值。", - "补充 express_numbers / waybill_codes 两个服务层派生字段说明,便于前端直接渲染多个快递号。", - "methods/system.json 中所有订单 list 的 response.list 描述已指向该字段字典章节。" - ], - "type": "updated" - }, - { - "version": "2026.04.15-system-05", - "date": "2026-04-15", - "summary": "基础模块新增快递/平台列表查询接口并设置为不鉴权,复用缓存 service", - "methods": [ - "index.getExpressList", - "index.getPlatformList" - ], - "notes": [ - "新增 index.getExpressList,归属基础模块(module=index),对应 app/service/systems/express.js 中的 getExpressList。", - "index.getExpressList 设置为不鉴权,不需要 Authorization 头。", - "新增 index.getPlatformList,归属基础模块(module=index),对应 app/service/systems/platform.js 中的 getPlatformList。", - "index.getPlatformList 设置为不鉴权,不需要 Authorization 头。", - "快递列表与平台列表都支持缓存优先,缓存未命中时回源数据库并写入缓存。", - "平台列表支持缓存优先,缓存未命中时回源 wms_platform 并写入缓存。" - ], - "type": "added" - }, - { - "version": "2026.04.15-system-02", - "date": "2026-04-15", - "summary": "签约策略字段元信息新增 default_express_code / default_platform_code list 选项", - "methods": [ - "storeWarehouse.store.getPolicyConfigFields" - ], - "notes": [ - "getPolicyConfigFields 现在返回 default_express_code 与 default_platform_code 两个 list 字段,并从 wms_express / wms_platform 读取选项列表。", - "默认值仍保留为 default_express_code=STO、default_platform_code=TB。" - ], - "type": "updated" - }, - { - "version": "2026.04.15-system-03", - "date": "2026-04-15", - "summary": "签约策略字段移除 sku_visibility,receive_mode options 改为 value/label 结构", - "methods": [ - "storeWarehouse.store.savePolicyConfig", - "storeWarehouse.store.getPolicyConfigFields" - ], - "notes": [ - "策略字段定义不再包含 sku_visibility,历史值读取时仍会被归一化忽略。", - "receive_mode 的 options 改为 [{ value, label }] 格式,便于前端直接渲染。" - ], - "type": "updated" - }, - { - "version": "2026.04.15-system-04", - "date": "2026-04-15", - "summary": "按文件模块拆分 order 目录系统文档分组,覆盖订单工作台入口及各子模块方法", - "methods": [ - "order.list", - "order.manualOutboundOrder", - "order.badgeCount", - "order.outboundOrder.manualOutboundOrder", - "order.reviewOrder.list", - "order.reviewOrder.reviewOrder", - "order.pendingOrder.list", - "order.pendingOrder.reverseReviewOrder", - "order.pendingOrder.markPendingOutboundOrder", - "order.pendingOrder.cancelOrder", - "order.outboundOrder.list", - "order.expectionOrder.list", - "order.entrustOrder.list", - "order.deliveryOrder.list", - "order.deliveryExpectionOrder.list", - "order.archiveOrder.list" - ], - "notes": [ - "按 app/service/systemMethods/order 下的实际对外方法补全 methods/system.json 文档,只覆盖 system,不处理 qimen。", - "order 文档已按 index / reviewOrder / pendingOrder / outboundOrder / expectionOrder / entrustOrder / deliveryOrder / deliveryExpectionOrder / archiveOrder 拆成多个模块分组。", - "同步根据当前代码意图补充 params / response / errors,且不再把 index.js 已移除的兼容接口写回文档。" - ], - "type": "updated" - }, - { - "version": "2026.04.15-system-01", - "date": "2026-04-15", - "summary": "货主主体配置默认补齐 default_express_code / default_platform_code", - "methods": [ - "store.createStore", - "store.createWarehouse" - ], - "notes": [ - "当 subject_config 未传或缺少字段时,自动补齐 default_express_code=STO、default_platform_code=TB,并保留现有的 max_notice_webhook_count 默认值。", - "同步更新 methods/system.json 中 store.createStore 与 store.createWarehouse 的参数说明。" - ], - "type": "updated" - }, - { - "version": "2026.04.14-system-01", - "date": "2026-04-14", - "summary": "库存列表新增货主名称字段 stock.store_name", - "methods": [ - "storage.inventory.list" - ], - "notes": [ - "在 methods/system.json 的 storage.inventory.list response 中补充 stock.store_name:来源于签约表 store_remask,若无签约关系则为 null。", - "只同步文档,不修改业务代码。" - ], - "type": "updated" - }, - { - "version": "2026.04.13-system-01", - "date": "2026-04-13", - "summary": "补全 storage.receiving.detailChange 的入参/出参契约与错误码说明", - "methods": [ - "storage.receiving.detailChange" - ], - "notes": [ - "在 methods/system.json 中补充 storage.receiving.detailChange 的 params/response/errors,明确 id 与 receiving_id 必填。", - "说明 expiry_date 小于当前日期时返回 400 且 message 为 \"到期日期已过期,不能录入收货\"。", - "说明当传入 system_product_id 时会回填条码、重量、箱规、商品名称与 product_snapshot;未传时 barcode/product_name 也可单独更新。", - "同步补充文档:docs/storage-receiving-api.md 中新增 detailChange 段落。" - ], - "type": "updated" - }, - { - "version": "2026.04.07-system-01", - "date": "2026-04-07", - "summary": "修正 warehouse.getAreaRacks 的鉴权/权限链路文档,明确该接口需要 登录并走权限校验。", - "methods": [ - "warehouse.getAreaRacks" - ], - "notes": [ - "对齐当前 system 文档中的 isNeedAuth=true、isNeedLogin=true。", - "用于补充该接口权限链路修正文档的历史上下文,不改变 methods/system.json 的 SSOT 角色。" - ] - }, - { - "version": "2026.04.07-system-02", - "date": "2026-04-07", - "summary": "补充签约配置相关接口文档,覆盖策略字段元信息查询与面单数量人工调整。", - "methods": [ - "storeWarehouse.store.getPolicyConfigFields", - "storeWarehouse.store.adjustPrintQuantity" - ], - "notes": [ - "getPolicyConfigFields 说明为获取签约策略可配置字段元信息列表。", - "adjustPrintQuantity 说明为人工调整签约关系下的面单余额并记录变更日志,并 明确 id、change_quantity、reason 等关键入参。" - ] - }, - { - "version": "2026.04.07-system-03", - "date": "2026-04-07", - "summary": "对外命名从 qimenConfig 收口为 apiConfig,并在接口配置文档中强调 interface_type_id 校验。", - "methods": [ - "storeWarehouse.store.listApiConfig", - "storeWarehouse.store.saveApiConfig", - "storeWarehouse.store.deleteQimenConfig" - ], - "notes": [ - "文档对外统一使用 apiConfig / api_config 命名,减少 qimenConfig 历史别名歧义。", - "saveApiConfig 要求 interface_type_id 为必填且必须指向已存在的 wms_interface_type 记录。", - "listApiConfig / deleteQimenConfig 同步补充 interface_type_id 字段说明。" - ] - }, - { - "version": "2026.04.07-system-04", - "date": "2026-04-07", - "summary": "补充 /api/docs 文档体验增强说明,新增查看变更记录与查看原文 JSON 的入口说明。", - "methods": [ - "/api/docs", - "/api/docs/:docName", - "/api/docs/:docName/raw", - "/api/docs/:docName/changes" - ], - "notes": [ - "sidecar 变更数组用于承载文档历史说明,不替代 methods/system.json 作为 SSOT。", - "原文 JSON 入口继续用于直接查看当前生效文档。" - ] - }, - { - "version": "2026.04.07-system-05", - "date": "2026-04-07", - "summary": "修正 storeWarehouse.store.adjustPrintQuantity 的面单余额调整语义:由增减/累加改为覆盖设置目标余额。", - "methods": [ - "storeWarehouse.store.adjustPrintQuantity" - ], - "notes": [ - "adjustPrintQuantity 当前兼容 print_quantity、target_quantity、change_quantity、adjust_quantity 作为目标面单余额输入,不再按增减量解释。", - "变更日志中的 change_quantity 由 before/after 自动计算差值,以兼容历史审计与展示。" - ] - }, - { - "version": "2026.04.07-system-06", - "date": "2026-04-07", - "summary": "按接口类型分类限制必填字段,OPEN_API 创建时自动生成 self_app_key/self_app_secret", - "methods": [ - "storeWarehouse.store.saveApiConfig" - ], - "notes": [ - "QM_WMS 类型须填写 qimen_app_key/qimen_customer_id/qimen_warehouse_code;OPEN_API 类型三个奇门字段非必填,创建时自动生成 self_app_key(WMS+32位HEX)和 self_app_secret(64位HEX),更新时保留已有密钥。" - ], - "type": "changed" - }, - { - "version": "2026.04.07-system-07", - "date": "2026-04-07", - "summary": "新增接口类型列表查询接口,归属基础模块,无需权限", - "methods": [ - "index.listInterfaceTypes" - ], - "notes": [ - "返回所有已启用的接口类型(wms_interface_type),包含 id、interface_code、interface_name、interface_category、description 字段。设置 isNeedAuth: false, isNeedLogin: true。" - ], - "type": "added" - }, - { - "version": "2026.04.07-system-08", - "date": "2026-04-07", - "summary": "app_name 改为必传参数", - "methods": [ - "storeWarehouse.store.saveApiConfig" - ], - "notes": [ - "app_name 不再有默认值自动生成逻辑,调用方必须传入非空的 app_name,否则返 回 400 错误。" - ], - "type": "changed" - }, - { - "version": "2026.04.07-system-09", - "date": "2026-04-07", - "summary": "新增收货单快捷入库上架接口", - "methods": [ - "storage.inventory.quickPutaway" - ], - "notes": [ - "新建 storage.inventory 库存操作模块。quickPutaway 从收货单直接生成入库单 (SCRK)并写入 wms_storage 库存表,同时更新 wms_stock_warehouse 库存数量(悲观行锁),回填收货明细入库状态。要求收货单已完成且所有明细已匹配系统商品。" - ], - "type": "added" - }, - { - "version": "2026.04.08-system-01", - "date": "2026-04-08", - "summary": "新增收货单与入库单匹配入库接口", - "methods": [ - "storage.inventory.matchPutaway" - ], - "notes": [ - "接收多个收货单和入库单,按商品(stock_warehouse_id)进行数量匹配入库,完 成后根据入库单来源(QM/API)自动触发回传。入参为 receiving_ids(数组)和 entry_order_ids(数组),返回匹配汇总、各收货单入库状态、各入库单状态及回传结果。isNeedAuth=true, isNeedLogin=true, isNeedRight=false。" - ], - "type": "added" - }, - { - "version": "2026.04.08-system-02", - "date": "2026-04-08", - "summary": "saveApiConfig 新增 callback_url 可选参数", - "methods": [ - "storeWarehouse.store.saveApiConfig" - ], - "notes": [ - "新增 callback_url 参数(VARCHAR(500),可选),用于 OPEN_API 类型入库单的 回调地址配置。" - ], - "type": "changed" - }, - { - "version": "2026.04.08-system-03", - "date": "2026-04-08", - "summary": "serializeQimenConfig 新增返回 callback_url 字段,影响 list 和 listApiConfig 两个接口", - "methods": [ - "storeWarehouse.store.list", - "storeWarehouse.store.listApiConfig" - ], - "notes": [ - "serializeQimenConfig() 序列化方法新增 callback_url(string)字段。storeWarehouse.store.list 返回的每条记录 api_config 对象中包含 callback_url;storeWarehouse.store.listApiConfig 返回的 list 数组中每条配置包含 callback_url。" - ], - "type": "changed" - }, - { - "version": "2026.04.08-system-04", - "date": "2026-04-08", - "summary": "新增库存移库(库位转移)接口", - "methods": [ - "storage.inventory.transferLocation" - ], - "notes": [ - "新增 storage.inventory.transferLocation 接口,支持批量多商品多库位移库, 包含部分数量移库与全量移库。入参为 warehouse_id(仓库ID)和 transfers 数组(storage_id、target_space_id、quantity),触发 storage_transfer_completed 通知事件, 每条移库记录独立操作日志。isNeedAuth=true, isNeedLogin=true。" - ], - "type": "added" - }, - { - "version": "2026.04.08-system-05", - "date": "2026-04-08", - "summary": "简化移库接口入参,从批量 transfers 数组改为单条移库", - "methods": [ - "storage.inventory.transferLocation" - ], - "notes": [ - "移除 warehouse_id 和 transfers 数组入参,改为扁平的 storage_id + target_space_id + quantity 三个顶层参数。warehouse_id 从库存记录自动获取,接口从批量移库简化为单商品单库位移库。响应结构同步简化为单条结果对象。" - ], - "type": "modified" - }, - { - "version": "2026.04.08-system-06", - "date": "2026-04-08", - "summary": "新增商品库存明细查询接口", - "methods": [ - "stock.warehouse.getStockDetail" - ], - "notes": [ - "新增 stock.warehouse.getStockDetail 接口,按库位/批次维度查询商品库存分布。入参为 stock_id(必填,商品库存ID)和 pagination(可选,含 page/pageSize)。返回 stockItem(商品概要)、storageList(wms_storage 明细数组,含批次号、库位、数 量、锁定数量、生产日期、过期日期等,关联 location_space 库位信息)、pagination 分页信息。isNeedAuth=false, isNeedLogin=true。底层调用 stockStore.getStockDetail,自动校验商品归属当前仓库。" - ], - "type": "added" - }, - { - "version": "2026.04.08-system-07", - "date": "2026-04-08", - "summary": "新增入参 group_by_batch,支持按批次维度切换库存明细聚合方式", - "methods": [ - "stock.warehouse.getStockDetail" - ], - "notes": [ - "新增可选布尔参数 group_by_batch(默认 false)。false 时按库位合并数量,批次相关字段(batch_no, production_date, expiry_date, inbound_time, inbound_order_no, supplier_batch_no)置 null;true 时保持原逻辑返回每条明细。出参结构不变,但 storageList 中批次字段在合并模式下为 null。" - ], - "type": "modified" - }, - { - "version": "2026.04.08-system-08", - "date": "2026-04-08", - "summary": "新增按商品维度移库接口", - "methods": [ - "storage.inventory.transferByProduct" - ], - "notes": [ - "新增 storage.inventory.transferByProduct 接口,按库位+商品查找所有库存记 录合并移动。入参为 space_id(原库位ID)、stock_id(商品SKU ID,即 wms_stock_warehouse.id)、target_space_id(目标库位ID)、quantity(移库数量)。开启批次管理(is_batch_mgmt=Y)的商品会被拒绝,需使用 transferLocation 按库存记录精确移库。复用 storage_transfer_completed 通知事件,操作日志编码 STORAGE_TRANSFER_BY_PRODUCT。isNeedAuth=true, isNeedLogin=true。" - ], - "type": "added" - }, - { - "version": "2026.04.08-system-09", - "date": "2026-04-08", - "summary": "补充 storeWarehouse.store.list 完整 response 输出字段说明,移除 api_config / apiConfig", - "methods": [ - "storeWarehouse.store.list" - ], - "notes": [ - "从返回结果中移除 api_config 和 apiConfig 字段(代码中 delete serialized.api_config / delete serialized.apiConfig),文档 response 补充完整输出字段列表:id, store_id, store_name, warehouse_id, warehouse_name, counterparty_id, counterparty_name, current_subject_role, auth_status, auth_status_label, apply_reason, review_comment, apply_time, review_time, auth_start, auth_end, actual_end, print_quantity, applied_by, reviewed_by, ended_by, remask, use_status, policy_config, is_auth_valid, remaining_days 以及分页和 current_subject 信息。" - ], - "type": "updated" - }, - { - "version": "2026.04.08-system-10", - "date": "2026-04-08", - "summary": "货主列表返回新增 has_qimen_config 布尔字段", - "methods": [ - "storeWarehouse.store.list" - ], - "notes": [ - "storeWarehouse.store.list 返回的 data.list[] 中新增 has_qimen_config(boolean),表示该货主是否已配置奇门。" - ], - "type": "changed" - }, - { - "version": "2026.04.08-system-11", - "date": "2026-04-08", - "summary": "补全 stock.warehouse.search 接口文档,新增 params / response / errors 完整说明", - "methods": [ - "stock.warehouse.search" - ], - "notes": [ - "入参补充 keyword(string,模糊匹配 item_code / item_name / goods_code / barcode)和 store_id(number,按货主筛选)。响应补充 data 数组各字段(id, item_code, goods_code, item_name, sku_property, stock_unit, quantity, locked_quantity, brand_name, item_type, barcodes, store_stock)以及 total。errors 补充 code=0 搜 索失败场景。" - ], - "type": "updated" - }, - { - "version": "2026.04.08-system-12", - "date": "2026-04-08", - "summary": "新增 with_stock / is_batch 参数,支持返回关联库存明细(按库位分 组或按批次逐条)", - "methods": [ - "stock.warehouse.search" - ], - "notes": [ - "入参新增 with_stock(boolean,默认 false,是否返回关联库存数据)和 is_batch(boolean,默认 false,仅 with_stock=true 时生效,按批次明细返回)。响应 data[] 新增 storage[] 字段:is_batch=false 时按库位分组汇总(含 space_id、space、inventory_type、quantity、locked_quantity、available_quantity);is_batch=true 时逐 条返回批次明细(含 id、stock_id、space_id、batch_no、inventory_type、quantity、locked_quantity、available_quantity、production_date、expiry_date、inbound_time、inbound_order_no、supplier_batch_no、created_at、space)。" - ], - "type": "updated" - }, - { - "version": "2026.04.08-system-13", - "date": "2026-04-08", - "summary": "新增 wms_stock_transaction 表和模型", - "methods": [ - "wms_stock_transaction" - ], - "notes": [ - "新增出入库流水记录表 wms_stock_transaction,含 transaction_type(INBOUND/OUTBOUND)、warehouse_id、store_id、stock_id、storage_id、space_id、quantity、batch_no、inventory_type、order_type、order_no、order_id、receiving_id、entry_order_id、operator_id、operator_name、remark 等字段,关联 StockWarehouse 和 Storage 模型。" - ], - "type": "added" - }, - { - "version": "2026.04.08-system-14", - "date": "2026-04-08", - "summary": "quickPutaway 和 matchPutaway 入库时自动写入出入库记录", - "methods": [ - "storage.inventory.quickPutaway", - "storage.inventory.matchPutaway" - ], - "notes": [ - "入库操作完成后自动写入 wms_stock_transaction 记录。quickPutaway 写入 order_type='SCRK'(收货入库),matchPutaway 写入 order_type='MATCH'(匹配入库),均 自动填充 warehouse_id、store_id、stock_id、storage_id、space_id、quantity、batch_no、inventory_type 等字段。" - ], - "type": "updated" - }, - { - "version": "2026.04.08-system-15", - "date": "2026-04-08", - "summary": "新增 storage.inventory.list 出入库记录列表查询接口", - "methods": [ - "storage.inventory.list" - ], - "notes": [ - "出入库记录列表查询,支持 where 条件(transaction_type、stock_id、space_id、store_id、order_type、order_no、inventory_type、operator_name、created_at)、 分页(pagination)、排序(sort)和 group_by_batch 参数。默认合并模式按库位+商品 聚合返回合计数量与记录条数,group_by_batch=true 时返回每条明细含 batch_no、order_no、operator_name 等完整信息。响应均关联 stockItem(item_code、item_name、sku_property、stock_unit)。" - ], - "type": "added" - }, - { - "version": "2026.04.08-system-16", - "date": "2026-04-08", - "summary": "出入库流水记录查询接口从 storage.inventory.list 改名为 storage.transaction.list", - "methods": [ - "storage.transaction.list" - ], - "notes": [ - "将出入库流水记录查询从 storage.inventory.list 迁移到 storage.transaction.list,避免与库存列表概念混淆。功能和参数不变。isNeedAuth=false, isNeedLogin=true, isNeedRight=false。" - ], - "type": "rename", - "module": "storage" - }, - { - "version": "2026.04.08-system-17", - "date": "2026-04-08", - "summary": "新增 storage.inventory.list 库存列表查询接口", - "methods": [ - "storage.inventory.list" - ], - "notes": [ - "新增库存列表查询接口,查询 wms_storage 表。支持 where 条件(stock_id/space_id/store_id/inventory_type/batch_no/inbound_order_no/available_quantity/inbound_time/created_at)、分页、排序。支持 group_by_batch 参数:默认 false 按库位+商 品合并(SUM quantity/locked_quantity/available_quantity),true 返回每条明细含 batch_no/production_date/expiry_date 等。关联 stockItem(商品信息)和 space(库位信息)。isNeedAuth=false, isNeedLogin=true, isNeedRight=false。" - ], - "type": "add", - "module": "storage" - }, - { - "version": "2026.04.08-system-18", - "date": "2026-04-08", - "summary": "移除 storage.entry.create 创建入库单接口", - "methods": [ - "storage.entry.create" - ], - "notes": [ - "不再允许通过 API 创建入库单。入库单仅由快捷入库(quickPutaway)和匹配入库(matchPutaway)等内部流程自动创建。底层 service 实现保留但不再通过 systemMethods 对外暴露。" - ], - "type": "remove", - "module": "storage" - }, - { - "version": "2026.04.08-system-19", - "date": "2026-04-08", - "summary": "移除 storage.entry.addDetail / deleteDetail / detailChange 对外 接口", - "methods": [ - "storage.entry.addDetail", - "storage.entry.deleteDetail", - "storage.entry.detailChange" - ], - "notes": [ - "入库单明细编辑能力不再通过 systemMethods 对外暴露,入库单模块仅保留 list/get/cancel/completeEntry。" - ], - "type": "remove", - "module": "storage" - }, - { - "version": "2026.04.08-system-20", - "date": "2026-04-08", - "summary": "新增 storage.stockout 出库单模块(非订单出库单能力)", - "methods": [ - "storage.stockout.list", - "storage.stockout.toOrder", - "storage.stockout.listItems" - ], - "notes": [ - "新增 storage.stockout.list / toOrder / listItems 接口,作为非订单出库单的主出口(对应奇门 stockout.create)。storage.delivery.* 仅作为兼容转发保留;底层 部分能力仍复用 order 模块。" - ], - "type": "add", - "module": "storage" - }, - { - "version": "2026.04.08-system-21", - "date": "2026-04-08", - "summary": "将 storage.stockout.toOrder 标记为占位接口", - "methods": [ - "storage.stockout.toOrder" - ], - "notes": [ - "storage.stockout.toOrder 当前仅保留方法名用于后续扩展,暂不开放实际逻辑。调用时返回 code=405、message=占位接口,暂未开放。" - ], - "type": "change" - }, - { - "version": "2026.04.09-system-01", - "date": "2026-04-09", - "summary": "storage.entry.cancel 支持批量作废,新增 ids 入参并兼容单条 id", - "methods": [ - "storage.entry.cancel" - ], - "notes": [ - "新增入参 `ids`(number[])以支持批量作废,兼容旧入参 `id`;当同时传入 `ids` 与 `id` 时以 `ids` 为准。", - "参数校验:`ids` 必须为非空数组;非法 ID 或空数组返回 400。", - "业务约束:已完成/已作废/处于不可作废状态的单据不允许作废;批量场景下任一 单据不存在或状态不允许时整体返回 404/400,未执行部分更新。", - "响应说明:单条作废返回字段 `id`(number);批量作废返回字段 `ids`(number[])。", - "已同步更新 methods/system.json(storage.entry.cancel)为 SSOT。" - ] - }, - { - "version": "2026.04.09-system-02", - "date": "2026-04-09", - "summary": "新增基础模块车牌识别接口 index.recognizeLicensePlate", - "methods": [ - "index.recognizeLicensePlate" - ], - "notes": [ - "入参:base64(string,必填)或 imageBase64/image_base64(兼容)", - "响应:返回归一化后的识别对象,包含 licensePlate、plateNumber、color、confidence、requestId、imageSize、rawData", - "错误:400(参数或图片格式/尺寸问题),500(第三方 OCR 调用失败或云密钥未 配置)", - "文档中不包含任何敏感配置;实际腾讯云密钥保留在配置文件中,勿在文档中暴露 。" - ], - "type": "added" - }, - { - "version": "2026.04.09-system-03", - "date": "2026-04-09", - "summary": "收紧基础模块车牌识别接口响应,仅返回 licensePlate 字段", - "methods": [ - "index.recognizeLicensePlate" - ], - "notes": [ - "出参由 {licensePlate, plateNumber, color, confidence, requestId, imageSize, rawData} 调整为 {licensePlate}", - "调用方请仅依赖 licensePlate 字段以适配新版本;历史字段已裁剪且不再保证存 在。", - "文档中未包含任何云密钥或敏感配置信息。" - ], - "type": "changed" - }, - { - "version": "2026.04.10-system-01", - "date": "2026-04-10", - "summary": "订单审核字段由 audit_status 替换为整数字段 step,并添加数据库迁移", - "methods": [ - "order.getreviewOrderlist", - "order.reviewOrder.getreviewOrderlist", - "order.reviewOrder.reviewOrder", - "order.deliveryOrder.getdeliveryOrderlist", - "order.list", - "order.stats" - ], - "notes": [ - "字段变更:order 相关审核字段从字符串/枚举 audit_status 替换为整数 step。", - "step 映射:0=未审核,1=已审核,2=处理中,3=驳回/异常,4=配送中,5=已完成,9=已关闭。", - "reviewOrder 接口在更新 inspection_status 的同时会写入 step 字段。", - "必须执行迁移脚本:20260410150000-replace-audit-status-with-step-on-order-delivery-tables.js" - ], - "type": "changed" - }, - { - "version": "2026.04.13-system-02", - "date": "2026-04-13", - "summary": "stock.warehouse.search 返回新增效期管理字段并保留 is_shelf_life_mgmt", - "methods": [ - "stock.warehouse.search" - ], - "notes": [ - "响应 data[] 中新增字段:inbound_min_days、outbound_min_days、shelf_life_days、remaining_threshold_days(均为 number,单位:天)。", - "保留并说明 is_shelf_life_mgmt 布尔字段(boolean),表示是否启用效期管理(true=启用)。", - "仅更新文档(methods/system.json 与变更记录),代码行为不变。" - ], - "type": "updated" - }, - { - "version": "2026.04.13-system-02", - "date": "2026-04-13", - "summary": "新增 storage.expiry.list 库存有效期列表查询接口", - "methods": [ - "storage.expiry.list" - ], - "notes": [ - "该接口查询 wms_storage,关联 stockWarehouse 和 locationSpace,并按当前仓库与 remaining_threshold_days / expiry_date 过滤。" - ], - "type": "added" - }, - { - "version": "2026.04.13-system-03", - "date": "2026-04-13", - "summary": "新增 storage.inventory.list 库存列表返回效期字段与预警标记", - "methods": [ - "storage.inventory.list" - ], - "notes": [ - "库存列表响应增加生产日期、过期日期、效期预警是否触发字段", - "预警标记仅在商品启用保质期管理且到期日满足阈值条件时为 true" - ], - "type": "updated" - }, - { - "version": "2026.04.14-system-01", - "date": "2026-04-14", - "summary": "更新 index.searchSpace 文档", - "methods": [ - "index.searchSpace" - ], - "notes": [ - "补充 index.searchSpace 的 params/response,按 ctx.user.store_id 作为仓库上下文;keyword 为可选字符串,对 space_code 与 custom_barcode 做 %keyword% 模糊匹配;返回字段 id、space_code、custom_barcode、custom_name,最多 50 条;仅文档同步,无代码变更。" - ], - "type": "updated" - }, - { - "version": "2026.04.16-system-01", - "date": "2026-04-16", - "summary": "基础模块新增快递产品类型查询接口", - "methods": [ - "index.getExpressProductTypeList" - ], - "notes": [ - "新增 index.getExpressProductTypeList,归属基础模块(module=index),用于查询指定快递公司的产品类型列表。", - "对应服务实现:app/service/systems/express.js 中的 getExpressProductTypeList,支持传入 express_code 作为可选筛选参数(source=body)。", - "接口设置为免鉴权(isNeedAuth=false)但需登录(isNeedLogin=true),与 index.getExpressList / index.getPlatformList 一致,优先从缓存读取。" - ], - "type": "added" - }, - { - "version": "2026.04.17-system-01", - "date": "2026-04-17", - "summary": "新增快递管理模块(setting.express)及 5 个接口文档", - "methods": [ - "setting.express.list", - "setting.express.listBase", - "setting.express.create", - "setting.express.checkCodeUnique", - "setting.express.update" - ], - "notes": [ - "新增独立模块组:快递管理模块(module=setting.express),将快递映射管理相关接口独立为一组以便维护。", - "接口实现参考:app/service/systems/setting/express.js(返回结构)与 app/service/systemMethods/setting/express.js(对外方法包装)。", - "接口鉴权与上下文:isNeedAuth=false, isNeedLogin=true;需在请求中传入 Authorization 以携带登录上下文(用于获取当前仓库/货主上下文)。", - "已同步更新 methods/system.json,补充 params/response/errors,保持文档与实现一致。" - ], - "type": "added" - }, - { - "version": "2026.04.17-system-02", - "date": "2026-04-17", - "summary": "setting.express.list 分页入参统一为 pagination", - "methods": [ - "setting.express.list" - ], - "notes": [ - "将 setting.express.list 的分页入参文档从顶层 page/page_size/pageSize 迁移为 pagination 对象,主形态为 pagination;兼容 snake_case 的 page_size 与 camelCase 的 pageSize。", - "文档与当前实现一致:顶层 page/page_size/pageSize 会被归一化到 data.pagination 并转发到系统服务。" - ], - "type": "updated" - }, - { - "version": "2026.04.17-system-03", - "date": "2026-04-17", - "summary": "新增快递接口管理模块(setting.expressInterface)及 4 个接口文档", - "methods": [ - "setting.expressInterface.list", - "setting.expressInterface.create", - "setting.expressInterface.update", - "setting.expressInterface.delete" - ], - "notes": [ - "新增独立模块组:快递接口管理模块(module=setting.expressInterface),对应实现:app/service/systems/setting/expressInterface.js 与对外包装 app/service/systemMethods/setting/expressInterface.js。", - "接口为当前仓库范围(基于 ctx.user.store_id),仓库边界由系统服务强制校验;禁止通过接口指定 warehouse_id/warehouseId。操作需登录(isNeedLogin=true),无需额外鉴权(isNeedAuth=false)。", - "已在 methods/system.json 新增对应接口的 params/response/errors 文档,保持与实现一致。" - ], - "type": "added" - }, - { - "version": "2026.04.18-system-01", - "date": "2026-04-18", - "summary": "补充订单储位分配接口文档:order.storageAllocation.allocateStorage", - "methods": [ - "order.storageAllocation.allocateStorage" - ], - "notes": [ - "新增 order.storageAllocation.allocateStorage:按订单批量分配储位,支持多种入参别名(order_ids/ids/orderId 等)与仓库上下文优先级。", - "响应包含 requested_order_ids, pending_order_ids, allocated_order_ids, shortage_order_ids, skipped_orders, picking_count, stock_lock_summary, storage_lock_summary 等字段,用于前端展示分配结果与不足提示。" - ], - "type": "added" - }, - { - "version": "2026.04.18-system-02", - "date": "2026-04-18", - "summary": "新增 order.pendingOrder.allocateExpressCode:待处理订单模块的批量分配首单快递号(异步接口),复用 express.createWaybillCodePipeline。", - "methods": [ - "order.pendingOrder.allocateExpressCode" - ], - "notes": [ - "异步接口:调用后立即返回 task_id,后台执行运单创建,通过 allocateExpressCodeTaskProgress 查询进度。", - "入参为 ids(订单 ID 数组),sys_platform_code/logistics_code 等由后端从数据库读取。", - "拆单场景请使用 order.pendingOrder.allocateSubOrderNumber。" - ], - "type": "added" - }, - { - "version": "2026.04.18-system-03", - "date": "2026-04-18", - "summary": "将 order.storageAllocation.allocateStorage 迁移到 order.pendingOrder.allocateStorage,并移除原有公开分组。", - "methods": [ - "order.pendingOrder.allocateStorage" - ], - "notes": [ - "将对外入口从 order.storageAllocation.allocateStorage 迁移到 order.pendingOrder.allocateStorage,旧的 order.storageAllocation 分组已从 methods/system.json 中移除。", - "新的对外接口不接受 warehouse_id / warehouseId,仓库上下文由当前登录用户(ctx.user.store_id)提供。", - "本次变更仅同步文档位置与对外方法名,底层实现保留且通过新的 system 方法暴露。" - ], - "type": "changed" - }, - { - "version": "2026.04.19-system-02", - "date": "2026-04-19", - "summary": "新增待处理模块取消分配储位接口 order.pendingOrder.cancelAllocateStorage", - "methods": [ - "order.pendingOrder.cancelAllocateStorage" - ], - "notes": [ - "新增待处理模块取消分配储位接口 `order.pendingOrder.cancelAllocateStorage`,直接对接 `service.systems.orderStorageAllocation.cancelAllocateStorage` 实现。", - "接口现在仅接受订单ID(order_ids),不再接受 allow_storage_location;禁止传入 `warehouse_id/warehouseId`,仓库上下文由当前登录用户的 `store_id` 提供。", - "响应返回标准 { flag, code, message, data } 结构,data 包含取消分配的汇总结果(warehouse_id, requested_order_ids, cancellable_order_ids, skipped_orders, orders, picking_count, storage_unlock_summary, stock_unlock_summary)。" - ], - "type": "added" - }, - { - "version": "2026.04.21-system-01", - "date": "2026-04-21", - "summary": "新增 order.pendingOrder.updateOrderPlatform 方法:批量修改待处理订单平台信息", - "methods": [ - "order.pendingOrder.updateOrderPlatform" - ], - "notes": [ - "通过 code 查找 wms_platform,平台不存在时返回 404 错误。", - "仅操作当前仓库的当前订单表。", - "noNeedRight=true,noNeedAuth=true(isNeedAuth: true 在 spec 中对应权限配置 noNeedAuth=true)。" - ], - "type": "added" - }, - { - "version": "2026.04.21-system-02", - "date": "2026-04-21", - "summary": "新增方法 order.pendingOrder.updateOrderExpress:批量修改待处理订单的快递信息", - "methods": [ - "order.pendingOrder.updateOrderExpress" - ], - "notes": [ - "新增 order.pendingOrder.updateOrderExpress:批量修改待处理订单的快递信息,按 express_code 从仓库快递列表(带缓存)匹配快递项。", - "自定义映射(is_system_setting=true)时,sys_logistics_code/name 写入系统快递编码和名称,logistics_code/name 写入自定义编码和名称;系统快递(is_system_setting=false)时四个字段均写系统快递的 code/name。", - "只操作当前仓库的当前订单表,不处理其他订单表;操作后写入操作日志(ORDER_UPDATE_EXPRESS)。" - ], - "type": "added" - }, - { - "version": "2026.04.21-system-03", - "date": "2026-04-21", - "summary": "新增 order.expectionOrder.resolveException:将待处理异常订单转回正常待处理状态", - "methods": [ - "order.expectionOrder.resolveException" - ], - "notes": [ - "新增 order.expectionOrder.resolveException:批量将 step=3 的异常订单恢复为 step=2 正常待处理状态。", - "入参 ids 为订单ID 正整数数组,不能为空;仅操作当前仓库当前订单表。", - "返回 updated_count(实际更新行数)与 ids(本次操作ID列表)。", - "权限配置:noNeedLogin=false、noNeedRight=true、noNeedLog=false、noNeedAuth=true" - ], - "type": "added" - }, - { - "version": "2026.04.21-system-04", - "date": "2026-04-21", - "summary": "新增 order.pendingOrder.cloneOrder 方法:克隆待处理订单", - "methods": [ - "order.pendingOrder.cloneOrder" - ], - "notes": [ - "支持对 step 0/1/2/3 的待处理订单进行克隆操作。", - "若原订单已分配储位(storage_status=fin),克隆前自动清除已分配库存。", - "原订单取消后(step→9, status→cancel),以原订单业务数据创建新订单,流程状态字段全部重置为初始落库状态。", - "克隆订单明细含 stock_id,新订单 ID 重新绑定。", - "noNeedAuth=true,noNeedRight=true,noNeedLogin=false。" - ], - "type": "added" - }, - { - "version": "2026.04.21-system-06", - "date": "2026-04-21", - "summary": "新增 order.pendingOrder.createOrder:手动创建待处理/待审核订单", - "methods": [ - "order.pendingOrder.createOrder" - ], - "notes": [ - "新增 order.pendingOrder.createOrder:手动创建订单,step 由货主策略 need_order_approval 决定(1→待审核 step=0,0→待处理 step=1)。", - "必填字段:store_id、name、mobile/tel 至少一项、detail_address、items[](含 item_code 和 plan_qty)。", - "delivery_order_code 不传则自动生成(SYS+时间戳+随机4位);logistics_code/sys_platform_code 不传则读货主合约策略 default_express_code/default_platform_code。", - "不做库存锁定,储位分配为独立步骤。操作日志写入 ORDER_CREATE。", - "noNeedRight=true,noNeedAuth=true,noNeedLogin=false。" - ], - "type": "added" - }, - { - "version": "2026.04.21-system-07", - "date": "2026-04-21", - "summary": "新增 Excel 模板下载与批量导入创建订单接口:order.pendingOrder.downloadCreateTemplate 和 order.pendingOrder.importOrdersFromExcel", - "methods": [ - "order.pendingOrder.downloadCreateTemplate", - "order.pendingOrder.importOrdersFromExcel" - ], - "notes": [ - "新增 order.pendingOrder.downloadCreateTemplate:生成 Excel 导入模板,返回 base64 编码的 xlsx 文件,表头中带 * 的列为必填项(橙色背景),可选列为灰色背景,含示例数据行和填写说明工作表。", - "新增 order.pendingOrder.importOrdersFromExcel:接受 base64 编码的 xlsx 文件,按订单号分组,每组调用 createOrder 逻辑创建订单;不中断执行,逐条记录成功/失败结果返回。", - "多行相同订单号的行组成一个完整订单,每行代表一条商品明细;订单头信息(收件人、地址等)取每组第一行。", - "step 由货主策略 need_order_approval 决定(与 createOrder 一致);通过事务保证每个订单的主记录与明细原子写入。" - ], - "type": "added" - }, - { - "version": "2026.05.01-system-01", - "date": "2026-05-01", - "summary": "新增基础模块 IM 登录码接口文档:index.loginToIm", - "methods": [ - "index.loginToIm" - ], - "notes": [ - "新增 index.loginToIm 文档,入参为空对象({}),依赖当前登录用户上下文生成一次性 code。", - "响应增加 data.code 字段,长度固定 64 位(hex),默认有效期 5 分钟。", - "错误码补充:401(用户未登录)、400(用户信息不完整,缺 employees_id 或 employees_name)。", - "该接口仅做登录码签发,实际换取员工信息由 IM 侧 ssoCodeToId 完成并在成功后使 code 失效。" - ], - "type": "added" - }, - { - "version": "2026.05.01-system-03", - "date": "2026-05-01", - "summary": "扩展 index.loginToIm 返回字段:增加主体/主体类型/头像信息", - "methods": [ - "index.loginToIm" - ], - "notes": [ - "登录码签发接口响应新增 employees_id、employees_name、subject、store_type、avatar 字段。", - "subject 包含 id/name;store_type 严格取自 wms_store.project 字段,不再返回 subject_type 兼容字段。", - "同一批字段会写入 code 缓存,供 IM 侧 ssoCodeToId 换取并在成功后失效。" - ], - "type": "updated" - }, - { - "version": "2026.05.01-system-04", - "date": "2026-05-01", - "summary": "index.loginToIm 与 ssoCodeToId 改为严格字段模式,不再做兼容回退", - "methods": [ - "index.loginToIm" - ], - "notes": [ - "loginToIm 仅读取 ctx.user 标准字段:employees_id、employees_name、store_id、store_name、store_type、avatar。", - "不再兼容 id/real_name/username/company_name/avatar_url 等历史字段。", - "ssoCodeToId 返回值不再使用默认兜底,缺少关键字段时按 code 无效处理。" - ], - "type": "updated" - }, - { - "version": "2026.05.03-system-01", - "date": "2026-05-03", - "summary": "将 order.wave.fetch 调整为异步任务提交接口,删除同步返回抓取结果字段", - "methods": [ - "order.wave.fetch" - ], - "notes": [ - "接口从同步返回抓取结果改为提交任务并异步处理。", - "移除原方法中 result_list / total_request_quantity / total_fetched_quantity 等同步返回字段。" - ], - "type": "updated" - }, - { - "version": "2026.05.03-system-06", - "date": "2026-05-03", - "summary": "order.wave.batchList:新增 where 支持并限制传入字段", - "methods": [ - "order.wave.batchList" - ], - "notes": [ - "batchList 新增 where 支持及白名单过滤;禁止传入 warehouse_id/warehouseId。" - ], - "type": "updated" - }, - { - "version": "2026.05.03-system-08", - "date": "2026-05-03", - "summary": "order.pendingOrder.allocateStorage 改为异步提交", - "methods": [ - "order.pendingOrder.allocateStorage" - ], - "notes": [ - "接口变更为异步提交:调用后立即返回 request_id,后端异步执行储位分配;接口不再在响应中同步返回分配明细(如 requested_order_ids、allocated_order_ids 等)。客户端可后续通过任务 ID / 查询链路或事件获取最终分配结果。" - ], - "type": "updated" - }, - { - "version": "2026.05.03-system-10", - "date": "2026-05-03", - "summary": "新增订单批量移出波次接口", - "methods": [ - "order.wave.batchRemoveOrders" - ], - "notes": [ - "按订单ID批量移出波次;仅处理待处理订单表中非待审核订单(step in [1,2,3])。", - "操作在单事务内完成:清空订单的 wave_id/wave_no,并回写 wms_wave_batch 统计(重算 total_orders;当波次被清空时将 wave_status 置为 -1)。", - "仓库上下文来自当前登录用户(ctx.user.store_id)。" - ], - "type": "updated" - }, - { - "version": "2026.05.08-system-05", - "date": "2026-05-08", - "summary": "order.wave.batchList:新增 source 字段并支持 where.source 过滤,返回 list item 中新增 source 字段", - "methods": [ - "order.wave.batchList" - ], - "notes": [ - "新增 where.source(可选,number)用于按来源过滤:0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务;不传则不过滤。", - "响应 list 每条记录新增字段 source(number),用于区分波次来源。", - "仅更新文档,业务代码不在此变更范围。" - ], - "type": "updated" - }, - { - "version": "2026.05.09-system-01", - "date": "2026-05-09", - "summary": "新增 order.wave.wavePickTaskCancelSelf;order.wave.waveStrategyList 新增预演计数字段/参数", - "methods": [ - "order.wave.wavePickTaskCancelSelf", - "order.wave.waveStrategyList" - ], - "notes": [ - "新增接口 `order.wave.wavePickTaskCancelSelf`:仅支持单个 `task_id`(number,必填),明确不支持 `task_ids` 批量参数。", - "业务约束:仅允许取消当前登录用户本人创建的拣货任务;若尝试取消非本人创建任务,接口应返回 400 错误(仅允许取消本人创建任务)。", - "返回建议:与现有取消接口风格一致,包含 `cancelled_count`(0/1)、`task_id`、`task_no`(若后端返回)或相应的取消结果汇总。", - "错误码建议:400 参数不合法(task_id 缺失或传了 task_ids);400 仅允许取消本人创建任务;500 取消失败。", - "新增参数:calculate_next_fetch_order_count(number,可选),含别名 calculateNextFetchOrderCount;取值 0=不计算(默认),1=计算并返回每条策略的 next_fetch_order_count,用于前端在策略列表中预览抓取量。", - "新增响应字段:list[*].next_fetch_order_count(number),含义:按当前策略口径预演一次自动抓取时,预计会选中的订单数量;当未开启计算时返回 0。" - ], - "type": "added" - }, - { - "version": "2026.05.11-system-01", - "date": "2026-05-11", - "summary": "新增字段 wave_prefix(策略层波次前缀),并补充 PDA 抓取波次号生成行为说明", - "methods": [ - "order.wave.waveStrategyList", - "order.wave.waveStrategyCreate", - "order.wave.waveStrategyUpdate", - "order.wave.waveStrategyFetchPda" - ], - "notes": [ - "在 wave strategy 对象中新增可选字段 wave_prefix:策略波次前缀,优先于仓库前缀。", - "校验规则:长度 1-5,仅允许 A-Z0-9;保存时会转为大写;为空时回退仓库前缀:团购使用 group_wave_prefix,散单使用 delete_order_wave_prefix。", - "在 order.wave.waveStrategyList 的返回 list[*] 中新增字段 wave_prefix(string)。", - "在 order.wave.waveStrategyCreate / waveStrategyUpdate 的入参中新增可选字段 wave_prefix(string),创建/更新成功后保存为大写且触发策略版本推进。", - "在 order.wave.waveStrategyFetchPda 的行为说明中补充:生成波次号(wave_no)时优先使用策略层 wave_prefix,否则按策略类型回退到仓库前缀;前缀校验同上。" - ], - "type": "updated" - }, - { - "version": "2026.05.15-system-01", - "date": "2026-05-15", - "summary": "仅更新文档:将 setting.express.create 入参与实现对齐(新增 express_code,移除 platform)", - "methods": [ - "setting.express.create" - ], - "notes": [ - "仅同步文档,与实现对齐,未修改任何业务代码或行为" - ], - "type": "updated" - }, - { - "version": "2026.05.15-system-02", - "date": "2026-05-15", - "summary": "新增 storage.report.search:库存流水统计报表,支持按时间闭区间过滤与按库位/按商品聚合", - "methods": [ - "storage.report.search" - ], - "notes": [ - "方法新增:storage.report.search", - "时间过滤为闭区间:created_at >= start_time 且 created_at <= end_time", - "当 where.by_space 为 false(默认)时,按商品+货主聚合(多个库位汇总);当为 true 时按商品+库位返回", - "不返回无流水的商品/键(仅返回在查询区间内出现过流水的数据)" - ], - "type": "added" - }, - { - "version": "2026.05.15-system-03", - "date": "2026-05-15", - "summary": "库存报表模块主入口迁移到 stock.report.search,storage.report.search 保持兼容别名", - "methods": [ - "stock.report.search", - "storage.report.search" - ], - "notes": [ - "新增主入口方法 stock.report.search,沿用既有报表统计口径(时间闭区间、by_space/store_ids、返回字段保持一致)。", - "保留 storage.report.search 作为兼容别名,并在描述中明确建议迁移到 stock.report.search。", - "仅更新 methods 文档配置,不修改业务代码。" - ], - "type": "updated" - }, - { - "version": "2026.05.15-system-04", - "date": "2026-05-15", - "summary": "文档主入口统一为 stock.report.search,storage.report.search 调整为兼容别名简述", - "methods": [ - "stock.report.search", - "storage.report.search" - ], - "notes": [ - "保留 stock.report.search 作为库存报表唯一完整文档入口。", - "storage.report.search 不再维护完整重复字段,仅保留迁移与兼容说明。", - "仅更新 methods 文档配置,不修改业务代码。" - ], - "type": "updated" - }, - { - "version": "2026.05.15-system-05", - "date": "2026-05-15", - "summary": "拆分 storage.report 模块并移除错误 stock.report.search 文档入口", - "methods": [ - "storage.report.search", - "stock.report.search" - ], - "notes": [ - "将库存报表从 storage.inventory 中拆分为独立模块 storage.report,storage.report.search 文档改为主入口语义(不再作为兼容别名)。", - "从 storage.inventory 分组中移除错误的 stock.report.search 文档入口以及兼容别名条目 storage.report.search。", - "最终归属:storage.report.search 属于模块 storage.report;stock.report.search 的文档入口已移除以避免混淆(代码实现保留于 app/service/systemMethods/storage/report.js 的 storage.report.search)。", - "仅修改文档,不修改应用代码实现。" - ], - "type": "updated" - }, - { - "version": "2026.05.15-system-06", - "date": "2026-05-15", - "summary": "storage.report.search 新增排序能力文档说明", - "methods": [ - "storage.report.search" - ], - "notes": [ - "补充 sort 参数:支持 sortField/sort_field、sortOrder/sort_order。", - "补充排序白名单:begin_total、inbound_total、outbound_total、end_total。", - "补充非法排序字段/顺序回退默认排序说明。", - "响应说明补充:已按 sort 规则排序返回。" - ], - "type": "updated" - }, - { - "version": "2026.05.16-system-01", - "date": "2026-05-16", - "summary": "新增 storage.report.export:按与 storage.report.search 相同条件导出库存报表 Excel", - "methods": [ - "storage.report.export" - ], - "notes": [ - "新增方法:storage.report.export,复用 storage.report.search 的 where/sort 查询条件。", - "导出文件包含两个 sheet:汇总、变更记录。", - "用于在统计结果基础上回溯明细流水,提升库存变动追溯效率。" - ], - "type": "added" - }, - { - "version": "2026.05.16-system-02", - "date": "2026-05-16", - "summary": "storage.report.export 改为异步任务 + 新增 exportTaskProgress", - "methods": [ - "storage.report.export", - "storage.report.exportTaskProgress" - ], - "notes": [ - "调用方式调整为两步:先调用 storage.report.export 提交任务并获取 task_id,再调用 storage.report.exportTaskProgress 轮询任务进度。", - "下载链接获取方式:当 status=success 时,从 exportTaskProgress 响应的 download_url 字段获取导出文件地址。", - "任务状态值补充:submitted/running/success/failed/not_found。" - ], - "type": "updated" - }, - { - "version": "2026.05.16-system-03", - "date": "2026.05.16", - "summary": "同步 setting.expressInterface.create/update 入参与系统快递编码映射规则", - "methods": [ - "setting.expressInterface.create", - "setting.expressInterface.update" - ], - "notes": [ - "补充入参:sys_express_code、weight_type、address、town_name、ispickup、shipperno,并保留既有字段。", - "在参数说明补充 camelCase 别名支持:sysExpressCode、weightType、townName、isPickup、shipperNo 等。", - "同步约束变化:不再因同仓快递编码重复或平台重复直接返回 409;当 express_code 无法匹配系统快递编码时返回 400,文案为 express_code 未匹配到系统快递编码。" - ], - "type": "updated" - }, - { - "version": "2026.05.17-system-05", - "date": "2026-05-17", - "summary": "同步 storage.receiving.addDetail 的参数与返回值(从实现提取)", - "methods": [ - "storage.receiving.addDetail" - ], - "notes": [ - "补充 receiving_id 入参说明", - "补充返回的 details 数组与 selectId 字段", - "补充可能的错误码:404/400/500" - ], - "type": "updated" - }, - { - "version": "2026.05.17-system-06", - "date": "2026-05-17", - "summary": "重新同步 addDetail 文档", - "methods": [ - "storage.receiving.addDetail" - ], - "notes": [ - "再次从实现代码核对并补充参数/返回值/错误码,确保文档与实现一致", - "仅同步文档,不修改业务代码" - ], - "type": "updated" - }, - { - "version": "2026.05.17-system-07", - "date": "2026-05-17", - "summary": "addDetail 新增可选 item 入参并兼容空白创建链路", - "methods": [ - "storage.receiving.addDetail" - ], - "notes": [ - "item 有值时按传入字段创建(服务端覆盖 receiving_id 与 creator_id)", - "兼容不传 item 的空白创建链路;item.children 需覆盖关键字段(有则写、无则补齐)。" - ], - "type": "updated" - }, - { - "version": "2026.05.17-system-10", - "date": "2026-05-17", - "summary": "调整 storage.receiving.getReceivingDetail 库位字段输出语义:space_id 改为展示名称并补充兼容字段", - "methods": [ - "storage.receiving.getReceivingDetail" - ], - "notes": [ - "将 receiving.details.*.space_id 定义为展示名称(string|null),优先 custom_space_name,其次 space_name,不再作为原始数值ID文档语义。", - "新增并明确 receiving.details.*.space_id_raw(number|null)用于保留原始库位ID,兼容旧调用方。", - "补充 receiving.details.*.space_name(库位名称/编码)与 receiving.details.*.custom_space_name(自定义名称,可空)字段说明。" - ], - "type": "updated" - }, - { - "version": "2026.05.17-system-11", - "date": "2026-05-17", - "summary": "补充 subject_config.enable_external_express_code 字段文档与默认值语义", - "methods": [ - "store.createStore", - "store.createWarehouse", - "setting.warehouse.getSettings", - "setting.warehouse.saveSettings" - ], - "notes": [ - "在 store.createStore 与 store.createWarehouse 的 subject_config 入参中新增字段:enable_external_express_code(boolean),默认 false;开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)。", - "此 change 同时用于说明将在 setting.warehouse.getSettings / saveSettings 中补充该字段的文档说明(后续 doc-only 写入)。" - ], - "type": "updated", - "module": "store" - }, - { - "version": "2026.05.17-system-12", - "date": "2026-05-17", - "summary": "storeWarehouse.store 策略配置文档新增 enable_external_express_code 字段说明(向后兼容)", - "methods": [ - "storeWarehouse.store.getPolicyConfig", - "storeWarehouse.store.savePolicyConfig" - ], - "notes": [ - "在 getPolicyConfig / savePolicyConfig 的出参说明中补充 data.policy_config.enable_external_express_code 字段,明确为 flag(0=关闭,1=开启),默认 0。", - "在 savePolicyConfig 的入参说明中补充 policy_config.enable_external_express_code 字段定义。", - "本次为向后兼容的文档增强:新增可选策略字段说明,不影响现有调用。" - ], - "type": "updated" - }, - { - "version": "2026.05.19-system-01", - "date": "2026-05-19", - "summary": "补充 storage.entry.list 的 expense_record 筛选语义与未迁移环境错误提示", - "methods": [ - "storage.entry.list" - ], - "notes": [ - "在 where 参数说明中补充 expense_record 字段语义(费用是否记录)及 eq/in 支持。", - "明确 true/false、1/0、y/n、yes/no 的归一化规则与等价写法示例。", - "补充未完成表结构迁移时可能返回 400 及错误提示文案。" - ], - "type": "updated" - }, - { - "version": "2026.05.20-system-01", - "date": "2026-05-20", - "summary": "同步 order.recheckOrder.scanOrder 返回结构,补充 cart_match_view 语义化视图说明", - "methods": [ - "order.recheckOrder.scanOrder" - ], - "notes": [ - "新增返回字段:match_type(waybill/cart)与 cart_match_view(仅 cart 命中返回)。", - "cart_match_view 包含通用子字段:mode_code / mode_name / view_type / task;当车号命中时按 pick_mode 返回语义化结构:mode 1/5 返回 groups,mode 2 返回 orders,mode 3 返回 pick_groups,mode 4 返回 box_groups。" - ], - "type": "updated" - }, - { - "version": "2026.05.22-system-01", - "date": "2026-05-22", - "summary": "新增 index.getPlatformOauthLink 文档,补充平台授权链接接口说明", - "methods": [ - "index.getPlatformOauthLink" - ], - "notes": [ - "入参支持 code、platform_code、platformCode 三种平台编码字段别名。", - "当前仅支持 PDD;成功返回 data.platform_code、data.oauth_link 和 code=200,其他平台返回 code=400。", - "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" - ], - "type": "added", - "module": "index" - }, - { - "version": "2026.05.22-system-02", - "date": "2026-05-22", - "summary": "更新 index.getPlatformOauthLink 文档,补充仓库上下文、预占记录与错误说明", - "methods": [ - "index.getPlatformOauthLink" - ], - "notes": [ - "补充真实行为:从 ctx.user.store_id 读取当前仓库 ID,从 wms_platform.auth_base_url 读取授权基础地址,并在 wms_shops 创建平台授权预占记录。", - "补充 oauth_link 细节:追加 client_id、redirect_uri(配置非空时)以及长查询参数 wms_authorization_reservation_code,对应唯一 auth_random_code。", - "补充常见错误:平台编码为空、仓库上下文缺失、平台不存在、授权基础地址缺失/格式错误、不支持的平台,以及预占记录创建失败。" - ], - "type": "updated", - "module": "index" - }, - { - "version": "2026.05.22-system-03", - "date": "2026-05-22", - "summary": "同步 index.getPlatformOauthLink 当前实现:裸码入库与 state 拼接规则", - "methods": [ - "index.getPlatformOauthLink" - ], - "notes": [ - "补充真实行为:从 ctx.user.store_id 读取当前仓库,从 wms_platform.auth_base_url 读取基础授权链接,并优先复用 wms_shops 中 status=0 的未授权记录。", - "明确 auth_random_code 当前以裸码保存;若复用到历史带前缀记录,会先去掉 platformOauthReservationCodePrefix 后再回写。", - "更新 oauth_link 说明:state 由“前缀 + 平台编码 + '_' + 裸码”组成并整体 URL 编码后直接拼接到基础授权链接后,例如 xxxxx_PDD_;同时移除已不存在的基础地址格式错误/不支持平台错误描述。" - ], - "type": "updated", - "module": "index" - }, - { - "version": "2026.05.22-system-04", - "date": "2026-05-22", - "summary": "修正 index.getPlatformOauthLink 文档中的残留平台限制描述", - "methods": [ - "index.getPlatformOauthLink" - ], - "notes": [ - "移除 index.getPlatformOauthLink 参数与返回字段中残留的“当前仅支持 PDD”描述,避免与当前实现不一致。", - "保留授权链接仅依赖平台已配置基础授权链接模式的说明,不再把示例平台编码误写成实现限制。" - ], - "type": "updated", - "module": "index" - }, - { - "version": "2026.05.22-system-05", - "date": "2026-05-22", - "summary": "新增 index.getShopList 文档,并同步 custom_name 与店铺列表脱敏返回规则", - "methods": [ - "index.getShopList" - ], - "notes": [ - "新增 index.getShopList:接口依赖当前登录仓库上下文 ctx.user.store_id,不接受额外业务入参,缺少仓库时返回 400:未识别到当前仓库。", - "补充真实返回结构:data.list 为数组,包含 id、warehouse_id、platform_code、shop_name、custom_name、status、auth_expire_at、token_expires_at、refresh_token_expires_at、scope、created_at、updated_at 以及脱敏后的 owner_id、access_token、refresh_token、auth_random_code。", - "同步脱敏规则:owner_id 非空且长度大于 5 时返回前 3 位 + *** + 后 2 位,长度小于等于 5 时返回 ***;access_token、refresh_token、auth_random_code 非空时固定返回 ***,空值返回 null。", - "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改任何业务代码。" - ], - "type": "added", - "module": "index" - }, - { - "version": "2026.05.22-system-06", - "date": "2026-05-22", - "summary": "新增 index.getShopExpressList 文档,补充店铺快递列表统一返回结构", - "methods": [ - "index.getShopExpressList" - ], - "notes": [ - "按 ctx.user.store_id 校验店铺归属,仅允许查询当前登录仓库下的店铺。", - "服务端按店铺所属平台拉取并收敛快递签约/电子面单可用列表,统一返回前端消费结构。", - "未接入平台当前返回空列表;若店铺缺少授权 access_token,则返回 400:店铺未授权。", - "仅文档同步,不改业务代码。" - ], - "type": "added", - "module": "index" - }, - { - "version": "2026.05.22-system-07", - "date": "2026-05-22", - "summary": "同步快递接口文档:is_share 仅展示不可编辑", - "methods": [ - "setting.expressInterface.list", - "setting.expressInterface.create", - "setting.expressInterface.update" - ], - "notes": [ - "create/update 不再接受 is_share", - "list 仍可返回 is_share 作为展示信息", - "仅文档同步,不改业务代码" - ], - "type": "updated", - "module": "setting.expressInterface" - }, - { - "version": "2026.05.22-system-08", - "date": "2026-05-22", - "summary": "同步快递接口列表文档,移除未返回字段说明", - "methods": [ - "setting.expressInterface.list" - ], - "notes": [ - "根据 app/service/systems/setting/expressInterface.js 的 list() 查询字段与 normalizeInterfaceRow() 返回结构,同步 setting.expressInterface.list 不返回 token。", - "按当前实现清理 response.children 中未返回的 share_id、can_use_count 字段说明。", - "保留 is_share,并明确其仅用于展示,不作为编辑入参。" - ], - "type": "updated", - "module": "setting.expressInterface" - }, - { - "version": "2026.05.22-system-09", - "date": "2026-05-22", - "summary": "index.getShopList 支持按平台编码筛选店铺", - "methods": [ - "index.getShopList" - ], - "notes": [ - "index.getShopList 兼容 platform_code 与 platformCode 两种传参方式,服务端按 platform_code、platformCode 顺序读取首个 trim 后非空值作为平台筛选条件。", - "未传平台参数时返回当前登录仓库下全部已授权店铺;传入非空平台编码时仅返回该平台的已授权店铺。", - "本次仅补充筛选条件文档,不影响返回结构、排序规则与 owner_id/access_token/refresh_token/auth_random_code 的脱敏规则。", - "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改任何业务代码。" - ], - "type": "updated", - "module": "index" - }, - { - "version": "2026.05.22-system-10", - "date": "2026-05-22", - "summary": "快递接口配置新增 shop_id 字段", - "methods": [ - "setting.expressInterface.create", - "setting.expressInterface.update", - "setting.expressInterface.list" - ], - "notes": [ - "create/update 支持 shop_id/shopId(兼容 snake_case 与 camelCase),为店铺 ID,未传或空值按 null 处理。", - "list 返回 shop_id 字段,列表 where 支持按 shop_id 过滤。" - ], - "type": "updated" - }, - { - "version": "2026.05.22-system-11", - "date": "2026-05-22", - "summary": "调整快递接口列表排序规则", - "methods": [ - "setting.expressInterface.list" - ], - "notes": [ - "setting.expressInterface.list 改为按 weight ASC, id DESC 排序;优先按权重排序,权重相同再按 id 倒序。", - "本次仅同步该接口排序说明,不影响返回结构。" - ], - "type": "updated", - "module": "setting.expressInterface" - }, - { - "version": "2026.05.22-system-12", - "date": "2026-05-22", - "summary": "index.getShopExpressList 返回新增系统快递编码", - "methods": [ - "index.getShopExpressList" - ], - "notes": [ - "data.list[*] 新增 sys_express_code 字段,由平台快递编码 wp_code 映射系统快递编码,未匹配时返回空字符串。", - "补充 data.list[*].wp_name 说明:由系统快递基础表根据平台快递编码映射得到名称,未匹配时返回空字符串。", - "原有请求参数、鉴权方式与返回主结构保持不变。", - "仅文档同步,不改业务代码。" - ], - "type": "updated", - "module": "index" - }, - { - "version": "2026.05.23-system-01", - "date": "2026-05-23", - "summary": "补充快递接口列表 is_system_express_code 返回字段说明", - "methods": [ - "setting.expressInterface.list" - ], - "notes": [ - "在 setting.expressInterface.list 的 response.children 中补充 is_system_express_code 字段说明。", - "该字段表示当前行 express_code 是否为系统快递编码;不是系统快递编码返回 0,否则返回 1。", - "仅文档同步,不改业务代码。" - ], - "type": "updated", - "module": "setting.expressInterface" - }, - { - "version": "2026.05.23-system-02", - "date": "2026-05-23", - "summary": "完善 index.getExpressList 文档:补充过滤规则、返回字段与仓库维度行为", - "methods": [ - "index.getExpressList" - ], - "notes": [ - "补充 `systemOnly`、`express_code`、`expressCode` 的真实入参语义,明确真值识别规则与字段优先级。", - "补充默认模式、系统模式、按快递编码过滤模式下的返回差异,说明当前登录仓库维度来自 `ctx.user.store_id`。", - "补充 `data[*]` 各字段含义,明确系统基础快递与仓库自定义快递编码的差异字段。", - "仅文档同步,不修改业务代码。" - ], - "type": "updated", - "module": "index" - }, - { - "version": "2026.05.24-system-01", - "date": "2026-05-24", - "summary": "同步 index.getExpressList 文档:移除 expressCode 别名并明确 express_code 筛选语义", - "methods": [ - "index.getExpressList" - ], - "notes": [ - "移除 index.getExpressList 文档中的 expressCode 驼峰别名参数,仅保留 express_code。", - "明确当 systemOnly=false 且传入 express_code 时,接口按自定义映射记录中的系统快递编码字段 express_code 过滤,而不是按自定义 code 过滤。", - "保留 systemOnly=true 按系统快递编码过滤系统基础快递列表,以及默认合并逻辑、缓存优先、仓库维度来源不变的说明。" - ], - "type": "updated" - }, - { - "version": "2026.05.24-system-02", - "date": "2026-05-24", - "summary": "新增 index.getCainiaoStfTemplates 接口文档并明确模板返回语义", - "methods": [ - "index.getCainiaoStfTemplates" - ], - "notes": [ - "新增无参接口 index.getCainiaoStfTemplates:从当前仓库首个已授权 TB 店铺发起 cainiao.waybill.ii.search 查询菜鸟 STF 模板。", - "补充返回结构说明:data.platform_code 固定为 TB;data.list 返回模板数组并包含 template_id/template_name/template_url/cp_code/wp_code 字段。", - "明确模板列表为宽松结构解析并按 template_id/template_name/template_url 核心语义去重。", - "补充错误码说明:未识别仓库返回 400;当前仓库无已授权 TB 店铺返回 404。" - ], - "type": "added" - }, - { - "version": "2026.05.24-system-03", - "date": "2026-05-24", - "summary": "调整 index.getCainiaoStfTemplates 为免登录/免鉴权接口", - "methods": [ - "index.getCainiaoStfTemplates" - ], - "notes": [ - "将 index.getCainiaoStfTemplates 的 isNeedLogin 调整为 false,接口改为免登录访问。", - "保持 isNeedAuth=false,并同步免权限拦截配置,避免登录态与鉴权拦截。", - "该接口仍为无请求参数,headers 调整为空数组。" - ], - "type": "updated", - "module": "index" - }, - { - "version": "2026.05.24-system-04", - "date": "2026-05-24", - "summary": "调整 index.getCainiaoStfTemplates 为公共无参模板查询接口", - "methods": [ - "index.getCainiaoStfTemplates" - ], - "notes": [ - "index.getCainiaoStfTemplates 改为公共无参查询,不再依赖当前仓库、登录态或店铺授权。", - "接口直接调用 requestTbWaybillSearch({ cpCode: '' }) 查询公共模板,返回 data.platform_code='TB' 与模板数组。", - "requestTbWaybillSearch 支持 accessToken 缺失时不下发 session,因此该接口不再依赖 session。" - ], - "type": "updated" - }, - { - "version": "2026.05.24-system-05", - "date": "2026-05-24", - "summary": "同步 index.getCainiaoStfTemplates 改用淘宝标准模板公共接口", - "methods": [ - "index.getCainiaoStfTemplates" - ], - "notes": [ - "index.getCainiaoStfTemplates 改为调用淘宝开放平台 cainiao.cloudprint.stdtemplates.get,不再复用 cainiao.waybill.ii.search。", - "接口不需要用户授权,不下发 session,继续使用 https://eco.taobao.com/router/rest 与 TOP 公共签名参数。", - "模板列表改为从 cainiao_cloudprint_stdtemplates_get_response.result.datas[*].standard_templates[*] 做宽松兼容解析,统一返回 template_id/template_name/template_url/cp_code/wp_code。" - ], - "type": "updated" - }, - { - "version": "2026.05.24-system-06", - "date": "2026-05-24", - "summary": "新增 index.getPrintPlatformList 接口文档并明确打印平台下拉返回结构", - "methods": [ - "index.getPrintPlatformList" - ], - "notes": [ - "新增 index.getPrintPlatformList 文档,说明该接口供快递接口新增/编辑页下拉选择使用。", - "补充接口行为:仅返回未删除且状态为 ACTIVE 的打印平台,不分页,按 platform_name 与 id 升序返回。", - "补充 data[*] 返回字段说明,明确 code/name/value/label/platform_code/platform_name/status/remark 的含义。", - "仅文档同步,不修改业务代码。" - ], - "type": "added", - "module": "index" - }, - { - "version": "2026.05.24-system-07", - "date": "2026-05-24", - "summary": "新增 index.getPrintPlatformTemplateList 文档,明确 express_code 必填与模板过滤语义", - "methods": [ - "index.getPrintPlatformTemplateList" - ], - "notes": [ - "新增 index.getPrintPlatformTemplateList 方法文档,补充 platform_code 与 express_code 入参,其中 express_code 标记为必填。", - "明确业务语义:接口按 platform_code(默认 CAINIAO)定位 wms_express 中对应打印平台字段,并使用 express_code 过滤模板结果后返回。", - "补充返回结构 data.platform_code / data.express_code / data.responseData,说明未实现平台返回空对象。", - "仅文档同步,不修改业务代码。" - ], - "type": "added", - "module": "index" - }, - { - "version": "2026.05.25-system-01", - "date": "2026-05-25", - "summary": "新增 index.polyapiAuthorizeUrl 接口文档并标注免登录免鉴权特征", - "methods": [ - "index.polyapiAuthorizeUrl" - ], - "notes": [ - "新增基础模块方法 index.polyapiAuthorizeUrl,说明其为公共无参接口。", - "明确接口固定调用菠萝派 Differ.JH.BuildeAuthorizeUrl,返回体中以 data.respone 原样包裹上游响应。", - "同步标注 isNeedLogin=false、isNeedAuth=false,headers 为空数组。" - ], - "type": "added" - }, - { - "version": "2026.05.25-system-02", - "date": "2026-05-25", - "summary": "新增店铺模块相关接口文档(shops.list/add/del/edit)及授权会话接口 shops.GetAuthorizeSessionKey", - "methods": [ - "shops.list", - "shops.add", - "shops.del", - "shops.edit", - "shops.GetAuthorizeSessionKey" - ], - "notes": [ - "同步实现:shops.list 支持 where 分页与 quickWhere 快速搜索;shops.add/edit 校验 platform_code 存在且为 ACTIVE,custom_name 必填且长度限制;shops.del 为软删除,会返回 deleted=true 并清空敏感字段,若存在快递接口引用返回 409;shops.GetAuthorizeSessionKey 对 PDD/CAINIAO 平台生成预占码并返回 authorize_url,其他平台返回 501。", - "字段命名兼容说明:接口实现兼容 snake_case 与 camelCase 入参,文档以 snake_case 为主并注明兼容性。" - ], - "type": "added" - }, - { - "version": "2026.05.25-system-03", - "date": "2026-05-25", - "summary": "同步 shops.add 去入参化:移除 shop_name 入参并明确由授权后获取店铺名称", - "methods": [ - "shops.add" - ], - "notes": [ - "shops.add 入参移除 shop_name(及同义传参语义),仅保留 custom_name 与 platform_code 为关键请求字段。", - "补充说明:新增时 shop_name 由服务端生成 PENDING_* 占位名,后续以授权回调同步真实店铺名称。", - "仅文档同步,不修改任何业务代码。" - ], - "type": "updated", - "module": "shops" - }, - { - "version": "2026.05.28-system-02", - "date": "2026-05-28", - "summary": "新增 method: order.print.unlockWavePlatformPrintDataByGroup,按分组解锁波次平台打印锁", - "methods": [ - "order.print.unlockWavePlatformPrintDataByGroup" - ], - "notes": [ - "新增方法:order.print.unlockWavePlatformPrintDataByGroup,用于按分组规则批量解锁波次内被锁定的订单(将 print_lock_status 设为 'none')。", - "入参说明:group_type 默认为 platform_express(支持 platform、platform_express、order),unlock_scope 默认为 group(支持 group、wave);groups 为必须项,元素对象可包含 wave_id、platform、sys_logistics_code、order_ids 等字段。", - "返回说明:返回 summary(解锁统计)、unlocked_order_ids、unlocked_orders、ext.missing_wave_ids、ext.filtered_wave_ids 等字段。", - "实现参考:app/service/systemMethods/order/print.js 与 app/service/systems/order_print.js 的 unlockWavePlatformPrintDataByGroup 实现,相关单元测试位于 test/app/controller/system.order.print.unlockByGroup.test.js 与 test/app/service/systems/order_print.unlockWavePlatformPrintDataByGroup.test.js。" - ], - "type": "updated" - }, - { - "version": "2026.05.28-system-03", - "date": "2026-05-28", - "summary": "新增 order.updateExpressWeighingWeight 方法文档并补充单/多运单称重写入规则", - "methods": [ - "order.updateExpressWeighingWeight" - ], - "notes": [ - "新增 order.updateExpressWeighingWeight 入参说明:order_id、waybill_code、weighing_weight。", - "明确规则:单运单订单忽略 waybill_code 并直接更新唯一运单;多运单订单必须传 waybill_code 且需匹配订单下运单。", - "补充成功返回字段:order_id、waybill_code、weighing_weight。", - "补充错误码:400(参数校验与多运单缺失运单号)、404(运单记录不存在或未匹配)、500(模型未初始化或更新失败)。", - "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" - ], - "type": "added", - "module": "order.index" - }, - { - "version": "2026.05.28-system-01", - "date": "2026-05-28", - "summary": "新增包材相关 methods(create/update/delete/get),并提供 list 兼容说明", - "methods": [ - "setting.packageMaterial.create", - "setting.packageMaterial.update", - "setting.packageMaterial.delete", - "setting.packageMaterial.get", - "setting.packageMaterial.list" - ], - "notes": [ - "实现参考:app/service/systems/setting/packageMaterial.js", - "list 为兼容别名,内部转发至 get,建议新接入方改用 get" - ], - "type": "updated" - }, - { - "version": "2026.05.28-system-04", - "date": "2026-05-28", - "summary": "Add packageSupplier methods (create/update/delete/get) with list alias note", - "methods": [ - "setting.packageSupplier.create", - "setting.packageSupplier.update", - "setting.packageSupplier.delete", - "setting.packageSupplier.get", - "setting.packageSupplier.list" - ], - "notes": [ - "Reference implementation: app/service/systems/setting/packageSupplier.js", - "list is a compatibility alias; prefer get" - ], - "type": "updated" - }, - { - "version": "2026.05.28-system-05", - "date": "2026-05-28", - "summary": "新增 order.bindExpressPackageMaterial 方法文档,支持按订单运单绑定包材", - "methods": [ - "order.bindExpressPackageMaterial" - ], - "notes": [ - "新增 order.bindExpressPackageMaterial 入参说明:order_id、waybill_code、package_material_code(均必填)。", - "补充行为说明:按订单ID+运单号匹配 wms_order_express,按包材编码匹配包材并绑定 package_material_id 与 package_material_name_snapshot。", - "补充成功返回字段:order_id、waybill_code、package_material_id、package_material_name_snapshot、package_material_code。", - "补充错误码:400 参数错误、404 包材编码不存在、404 订单运单记录不存在、500 绑定包材失败。", - "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" - ], - "type": "added", - "module": "order.index" - }, - { - "version": "2026.05.29-system-01", - "date": "2026-05-29", - "summary": "新增 order.export 与 order.exportTaskProgress:订单导出异步任务与进度查询", - "methods": [ - "order.export", - "order.exportTaskProgress" - ], - "notes": [ - "order.export:提交导出任务,入参支持 table_type/tableType(枚举 current/history/dispatch/outsourced,兼容订单模块别名)与 module/module_name,where/sort 语义与 order.list 一致。接口提交后立即返回 task_id,后台异步执行导出,导出进度与结果通过 order.exportTaskProgress 查询。", - "order.exportTaskProgress:按 task_id 查询任务进度,返回 task_id、status、progress、current_count、total_count、message、error、download_url、update_time;任务上传完成后 download_url 返回可下载链接,未找到时 status=not_found。" - ], - "type": "added", - "module": "order.index" - }, - { - "version": "2026.05.30-system-01", - "date": "2026-05-30", - "summary": "新增 print.notifyLock(及 notify_lock 兼容别名),并补充 print.send 写入订单操作日志的行为说明", - "methods": [ - "print.notifyLock", - "print.notify_lock", - "print.send" - ], - "notes": [ - "新增 print.notifyLock:入参支持 order_ids/orderIds、waveGroups、data.waveGroups(至少一类提供订单 ID);仅执行订单锁定流程,不发送打印任务;写打印任务日志 + 订单操作日志;返回 locked_count、order_ids_count、order_ids、source;错误:无有效订单ID(400)、锁定失败(500)。", - "补充 print.send 文档:说明接口在执行打印任务记录的同时会写入订单操作日志(记录打印相关操作)。", - "新增兼容别名 print.notify_lock:文档说明等价转调到 print.notifyLock。" - ], - "type": "updated", - "module": "print" - }, - { - "version": "2026.06.03-system-01", - "date": "2026-06-03", - "summary": "同步 pick.query 文档为 keyword 任务化语义并补充冲突错误码", - "methods": [ - "pick.query" - ], - "notes": [ - "入参由 waybill_code/full_display 统一为 keyword(支持运单号或波次号)。", - "成功返回调整为 task_id/status/tip,status 取值 existing 或 created。", - "补充 409 冲突语义:波次已有他人活动任务时返回任务归属信息。" - ], - "type": "updated" - }, - { - "version": "2026.06.03-system-02", - "date": "2026-06-03", - "summary": "更新 pick.wavePickTaskDetail:增加快递号/储位分配前置校验并返回 action+order_ids", - "methods": [ - "pick.wavePickTaskDetail" - ], - "notes": [ - "新增前置校验:任务内若存在未分配快递号订单,返回 400,data.action=assign_express,data.order_ids 为未分配订单ID列表。", - "新增前置校验:任务内若存在未分配储位订单,返回 400,data.action=assign_storage,data.order_ids 为未分配订单ID列表。", - "保留原有权限校验与详情结构,仅补充分配校验失败分支的返回约定。" - ], - "type": "updated" - }, - { - "version": "2026.06.03-system-03", - "date": "2026-06-03", - "summary": "更新 order.wave.batchList:新增同步状态输出与筛选 sync_assignment_status", - "methods": [ - "order.wave.batchList" - ], - "notes": [ - "新增返回字段语义:list[].sync_assignment_status,取值为未同步/部分同步/已同步/同步异常。", - "新增筛选入参 where.sync_assignment_status,支持 unsynced/partially_synced/synced 英文枚举。", - "同步状态筛选规则与分配状态一致:error 并入 unsynced 过滤集合。" - ], - "type": "updated" - }, - { - "version": "2026.06.03-system-04", - "date": "2026-06-03", - "summary": "更新拣货中间态流程文档:wavePickTaskDetail 增加完成标记,并新增中间态/完全提交接口", - "methods": [ - "pick.wavePickTaskDetail", - "pick.wavePickTaskSubmit", - "pick.wavePickTaskComplete" - ], - "notes": [ - "更新 pick.wavePickTaskDetail 返回:新增 task.is_completed、task.progress(total_orders/picked_orders/pending_orders)以及顶层 is_completed。", - "新增 pick.wavePickTaskSubmit:支持保存中间态 payload 到任务 ext_json.pick_intermediate,并返回当前完成状态与进度。", - "新增 pick.wavePickTaskComplete:支持 mode=1 全部确认与 mode=2 部分确认(order_ids),返回 confirmed_order_ids 与最新进度。" - ], - "type": "updated" - }, - { - "version": "2026.06.03-system-05", - "date": "2026-06-03", - "summary": "拣货车能力拆分为一级模块 pickCart:扫码查询、任务绑车、CRUD、编码查重", - "methods": [ - "pickCart.scan", - "pickCart.bindTaskCart", - "pickCart.create", - "pickCart.update", - "pickCart.delete", - "pickCart.detail", - "pickCart.list", - "pickCart.codeDuplicateCheck" - ], - "notes": [ - "拣货车能力独立为一级模块 pickCart,不再挂在 pick 模块下。", - "新增 pickCart.scan:PDA 按 cart_code 扫码查询拣货车信息,用于进入任务绑定流程。", - "新增 pickCart.bindTaskCart:支持按 cart_id/cart_code 将拣货车绑定到指定拣货任务,若车已绑定其他活动任务则返回冲突。", - "新增 pickCart.create/pickCart.update/pickCart.delete/pickCart.detail/pickCart.list:补齐拣货车增删查改与分页查询能力。", - "新增 pickCart.codeDuplicateCheck:支持 exclude_cart_id 排除自身,供编辑场景做非自身重复校验;拣货车编码在当前仓库内不可重复。" - ], - "type": "updated" - }, - { - "version": "2026.06.03-system-06", - "date": "2026-06-03", - "summary": "更新 order.wave.batchList:新增 only_todo、复核状态聚合与复核筛选", - "methods": [ - "order.wave.batchList" - ], - "notes": [ - "新增入参 only_todo(默认 0):传 1/true 时仅返回仍有未复核订单的波次(unreviewed_order_count > 0)。", - "新增返回字段:list[].unreviewed_order_count(未复核订单数)与 list[].review_assignment_status(未复核/部分复核/已复核)。", - "新增 where.review_assignment_status 筛选,支持 unreviewed/partially_reviewed/reviewed 英文枚举。" - ], - "type": "updated", - "module": "order.wave" - }, - { - "version": "2026.06.04-system-01", - "date": "2026-06-04", - "summary": "裁剪 pick.wavePickTaskDetail 返回:团购小波次(pick_mode=1)不返回 picking_details 字段以减少带宽", - "methods": [ - "pick.wavePickTaskDetail" - ], - "notes": [ - "在 picking_details 字段 description 中补充:当 pick_mode=1(团购小波次)时该字段不返回,减少带宽浪费;其他 pick_mode(2/3/4/5)正常返回 picking_details。", - "在接口 description 中补充该裁剪行为的说明。", - "picking_summary、picking_view、boxes 等字段不受影响,pick_mode=1 时仍正常返回。" - ], - "type": "updated" - }, - { - "version": "2026.06.04-system-02", - "date": "2026-06-04", - "summary": "完善 index.getPlatformList 文档:补充入参 systemOnly/full、响应字段及错误码 500", - "methods": [ - "index.getPlatformList" - ], - "notes": [ - "补充入参说明:systemOnly(可选,支持 is_system 别名,真值识别 true/1/'1'/'true')、full(可选,真值识别同上,为 true 时返回全量表字段与 route_platform_code/platid 等扩展信息)", - "补充响应 data 数组每项字段:code、name、value、label、platform_code、platform_name、default_express_interface、is_system_setting、id(仅仓库自定义项)、alias(仅仓库自定义项)、full 模式扩展字段说明", - "说明合并逻辑:系统平台在前,仓库自定义在后,同 code 仅保留首条(系统优先);systemOnly=true 仅返回系统平台", - "补充缓存策略:优先读缓存,key 格式为 platform:list:{warehouseId}[:full] 或 platform:list:system[:full]", - "补充错误码 500:数据库或缓存访问异常", - "仅文档更新,不修改任何业务实现" - ], - "type": "updated", - "module": "index" - }, - { - "version": "2026.06.04-system-03", - "date": "2026-06-04", - "summary": "作废 order.pendingOrder.downloadCreateTemplate 和 order.pendingOrder.importOrdersFromExcel", - "methods": [ - "order.pendingOrder.downloadCreateTemplate", - "order.pendingOrder.importOrdersFromExcel" - ], - "notes": [ - "order.pendingOrder.downloadCreateTemplate:下载订单导入模板方法已从代码中移除,标记为 deprecated。", - "order.pendingOrder.importOrdersFromExcel:从 Excel 导入订单方法已从代码中移除,标记为 deprecated。", - "两个方法的文档条目保留在 methods/system.json 中,仅追加 status: 'deprecated' 与 description 中的'(已作废)'标记,未删除。" - ], - "type": "deprecated" - }, - { - "version": "2026.06.05-system-01", - "date": "2026-06-05", - "summary": "新增 storeWarehouse.store.openAccount 接口:仓库代货主一键开户(合并注册账号+创建货主+签约)", - "methods": [ - "storeWarehouse.store.openAccount" - ], - "notes": [ - "新增 storeWarehouse.store.openAccount 方法,归属货主-仓库签约模块(storeWarehouse.store)。", - "接口同时完成账号注册、货主创建和仓库-货主签约,一步完成开户全流程。", - "当前主体必须为仓库角色(Authorization header 中携带的 token 对应仓库用户)。", - "必填参数:username(登录账号)、password(初始密码)、company_name(公司全称)、business_license(营业执照号)、contact_person(联系人)、contact_phone(联系电话)。", - "响应返回新创建的 store_id、account_id、contract_id、company_name、username、role_id。" - ], - "type": "added", - "module": "storeWarehouse" - }, - { - "version": "2026.06.05-system-02", - "date": "2026-06-05", - "summary": "优化 storeWarehouse.store.openAccount 必填参数:password 改为随机生成、business_license 和 contact_phone 改为可选,必填仅剩 username/company_name/contact_person 三个", - "methods": [ - "storeWarehouse.store.openAccount" - ], - "notes": [ - "password:由必填改为可选,不传时自动随机生成 12 位密码", - "business_license:由必填改为可选", - "contact_phone:由必填改为可选" - ], - "type": "updated" - }, - { - "version": "2026.06.05-system-03", - "date": "2026-06-05", - "summary": "saveApiConfig 增加 callback_url 参数,支持配置 API 回调通知地址", - "methods": [ - "storeWarehouse.store.saveApiConfig" - ], - "notes": [ - "新增 callback_url 参数:OpenAPI 类型接口支持配置回调通知 URL", - "兼容别名 callbackUrl,最大 500 字符", - "存入 wms_api_app.callback_url 字段" - ], - "type": "modified" - }, - { - "version": "2026.06.05-system-04", - "date": "2026-06-05", - "summary": "createOrder 入参 item_code 改为 item_id,province/city/area 改为必填", - "methods": [ - "order.pendingOrder.createOrder" - ], - "notes": [ - "items[].item_code → items[].item_id:改用商品主键直接匹配,不依赖外部系统商品推送", - "province/city/area 新增必填校验,空值返回 400", - "item_name 优先外部传入,其次从 StockStore 缓存获取,最后兜底'商品'" - ], - "type": "modified" - }, - { - "version": "2026.06.05-system-05", - "date": "2026-06-05", - "summary": "新增 order.pendingOrder.parseAddress 智能地址解析方法", - "methods": [ - "order.pendingOrder.parseAddress" - ], - "notes": [ - "使用 DeepSeek AI 模型将非结构化地址字符串解析为省/市/区/详细地址/收件人/手机号", - "解析结果可直接用于 createOrder 的 receiverInfo 字段", - "DeepSeek API Key 通过 DEEPSEEK_API_KEY 环境变量配置" - ], - "type": "added" - }, - { - "version": "2026.06.05-system-06", - "date": "2026-06-05", - "summary": "waveStrategyUpdate/waveStrategyCreate 新增 wave_prefix 参数", - "methods": [ - "order.wave.waveStrategyUpdate", - "order.wave.waveStrategyCreate" - ], - "notes": [ - "新增 wave_prefix 波次编号前缀字段,最多 5 个字符,为空存 null" - ], - "type": "modified" - }, - { - "version": "2026.06.05-system-07", - "date": "2026-06-05", - "summary": "parseAddress 响应新增 town 字段(乡镇/街道)", - "methods": [ - "order.pendingOrder.parseAddress" - ], - "notes": [ - "响应 data 中新增 town 字段,返回 AI 解析出的乡镇/街道名称" - ], - "type": "modified" - }, - { - "version": "2026.06.05-system-08", - "date": "2026-06-05", - "summary": "为 order.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", - "methods": [ - "order.list" - ], - "notes": [ - "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" - ], - "type": "updated" - }, - { - "version": "2026.06.05-system-09", - "date": "2026-06-05", - "summary": "为 order.reviewOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", - "methods": [ - "order.reviewOrder.list" - ], - "notes": [ - "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" - ], - "type": "updated" - }, - { - "version": "2026.06.05-system-10", - "date": "2026-06-05", - "summary": "为 order.pendingOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", - "methods": [ - "order.pendingOrder.list" - ], - "notes": [ - "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" - ], - "type": "updated" - }, - { - "version": "2026.06.05-system-11", - "date": "2026-06-05", - "summary": "为 order.outboundOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", - "methods": [ - "order.outboundOrder.list" - ], - "notes": [ - "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" - ], - "type": "updated" - }, - { - "version": "2026.06.05-system-12", - "date": "2026-06-05", - "summary": "为 order.expectionOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", - "methods": [ - "order.expectionOrder.list" - ], - "notes": [ - "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" - ], - "type": "updated" - }, - { - "version": "2026.06.05-system-13", - "date": "2026-06-05", - "summary": "为 order.entrustOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", - "methods": [ - "order.entrustOrder.list" - ], - "notes": [ - "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" - ], - "type": "updated" - }, - { - "version": "2026.06.05-system-14", - "date": "2026-06-05", - "summary": "为 order.deliveryOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", - "methods": [ - "order.deliveryOrder.list" - ], - "notes": [ - "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" - ], - "type": "updated" - }, - { - "version": "2026.06.05-system-15", - "date": "2026-06-05", - "summary": "为 order.deliveryExpectionOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", - "methods": [ - "order.deliveryExpectionOrder.list" - ], - "notes": [ - "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" - ], - "type": "updated" - }, - { - "version": "2026.06.05-system-16", - "date": "2026-06-05", - "summary": "为 order.archiveOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", - "methods": [ - "order.archiveOrder.list" - ], - "notes": [ - "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" - ], - "type": "updated" - }, - { - "version": "2026.06.06-system-01", - "date": "2026-06-06", - "summary": "恢复 order.pendingOrder.downloadCreateTemplate:方法仍存在于代码中,取消 deprecated 标记,完善文档描述", - "methods": [ - "order.pendingOrder.downloadCreateTemplate" - ], - "notes": [ - "order.pendingOrder.downloadCreateTemplate 方法在 pendingOrder.js 中仍存在(line 2099),此前被误标记为 deprecated。", - "取消 status: 'deprecated' 标记,恢复为 active 状态。", - "移除 description 中的'(已作废)'后缀。", - "完善 description:说明模板包含必填列(橙色背景)、可选列(灰色背景)、示例数据行和填写说明工作表。", - "补充 response 字段说明:filename 和 mime 为固定值。" - ], - "type": "updated" - }, - { - "version": "2026.06.07-system-01", - "date": "2026-06-07", - "summary": "order.pendingOrder.createOrder 文档新增 shop_nick 入参(店铺名称,可选,最大长度200)", - "methods": [ - "order.pendingOrder.createOrder" - ], - "notes": [ - "在 order.pendingOrder.createOrder 的 request params 中新增 shop_nick 字段(string,非必填),对应代码实现中 shopNick: String(requestData.shop_nick || requestData.shopNick || '').trim()。", - "shop_nick 已在 COPY_FIELDS 白名单中(pendingOrder.js L1738),仅文档缺失,本次为补齐。" - ], - "type": "updated" - }, - { - "version": "2026.06.07-system-02", - "date": "2026-06-07", - "summary": "order.pendingOrder.downloadCreateTemplate:模板新增 shop_nick 列(店铺名称),store_id/province/city/area 标注为非必填", - "methods": [ - "order.pendingOrder.downloadCreateTemplate" - ], - "notes": [ - "模板新增 shop_nick(店铺名称)列,非必填。", - "明确标注 store_id(货主ID)、province(省份)、city(城市)、area(区/县)为非必填列。", - "响应文档中新增 shop_nick 字段说明。" - ], - "type": "updated" - }, - { - "version": "2026.06.07-system-03", - "date": "2026-06-07", - "summary": "新增 order.pendingOrder.updateAddress:批量修改待处理订单收件地址,限制未分配快递时可用", - "methods": [ - "order.pendingOrder.updateAddress" - ], - "notes": [ - "新增 method:order.pendingOrder.updateAddress,免权限(isNeedAuth=false),需登录", - "功能:批量修改待处理订单收件地址(name/mobile/tel/zip_code/province/city/area/town/detail_address)", - "约束:仅 post_status='none'(未分配快递)的订单可修改;至少提供一个有效地址字段", - "响应:返回 updated_count(实际更新行数)和 ids(请求订单ID数组)" - ], - "type": "added" - }, - { - "version": "2026.06.07-system-04", - "date": "2026-06-07", - "summary": "order.wave.wavePickTaskCancel 扩展可取消状态至 status=3,并新增拣货状态回退", - "methods": [ - "order.wave.wavePickTaskCancel" - ], - "notes": [ - "可取消状态从 [0,1,2] 扩展为 [0,1,2,3](status=3 已完成现在也可取消)", - "取消 status=2(待复核)或 status=3(已完成)任务时,自动回退 wms_wave_pick_task_order.pick_status(1→0)和 order_delivery.pick_status(fin→padding)", - "错误码 400 描述同步更新,补充 403 错误码说明" - ], - "type": "updated" - }, - { - "version": "2026.06.07-system-05", - "date": "2026-06-07", - "summary": "order.wave.wavePickTaskList 响应新增 cart_name 字段(拣货车名称)", - "methods": [ - "order.wave.wavePickTaskList" - ], - "notes": [ - "响应 list 子项新增 cart_name(string):通过 current_cart_id LEFT JOIN wms_pick_cart 表获取,未绑定拣货车时为空字符串。" - ], - "type": "updated" - }, - { - "version": "2026.06.07-system-06", - "date": "2026-06-07", - "summary": "pick.wavePickTaskComplete 新增后台抓取任务(source=2)拣货车绑定校验,未绑定拣货车时拒绝提交", - "methods": [ - "pick.wavePickTaskComplete" - ], - "notes": [ - "description 补充说明:后台抓取创建的任务(source=2)必须先绑定拣货车才能提交,否则返回 400。", - "errors 中 400 错误补充:后台抓取任务(source=2)未绑定拣货车时拒绝提交,错误消息为\"后台抓取任务必须先绑定拣货车才能提交\"。" - ], - "type": "updated" - }, - { - "version": "2026.06.07-system-07", - "date": "2026-06-07", - "summary": "order.wave.batchList 文档修正:移除代码中不存在的 sync_assignment_status 引用", - "methods": [ - "order.wave.batchList" - ], - "notes": [ - "从 where 描述中移除 sync_assignment_status(代码 buildBatchListWhereClause allowedFields 中不存在该字段,BATCH_LIST_ASSIGNMENT_FILTER_SCHEMAS 中也无 review 之外的同步类型)。", - "从 response list 描述中移除 sync_assignment_status(代码响应映射中仅返回 storage/express/print/review 四种 assignment_status,无 sync_assignment_status)。", - "v2026.06.03-system-03 变更记录中声称新增的 sync_assignment_status 实际从未在代码中实现,本次仅为文档修正,不涉及代码变更。" - ], - "type": "updated", - "module": "order.wave" - }, - { - "version": "2026.06.07-system-08", - "date": "2026-06-07", - "summary": "order.recheckOrder.confirmRecheck 补充后置行为说明:波次任务全部复核完成后自动解绑车任务", - "methods": [ - "order.recheckOrder.confirmRecheck" - ], - "notes": [ - "在 description 中补充:确认复核后,若该订单所属波次拣货任务下所有订单均已复核完成,则自动解绑车任务。解绑操作包括:清空 wms_wave_pick_task 的 current_cart_id/current_cart_code_snapshot、停用 wms_pick_task_cart_binding(is_active=0 并记录解绑人和时间)、释放 wms_pick_cart(清空 current_task_id/bind_user_id)。", - "解绑失败仅记录 warn 日志,不影响复核主流程。", - "入参和返回结构未变,仅补充行为说明。" - ], - "type": "updated" - }, - { - "version": "2026.06.07-system-10", - "date": "2026-06-07", - "summary": "移除 order.wave.groupFetch / singleFetch / fetch 响应中已废弃的 auto_fetch_disabled_marker 字段", - "methods": [ - "order.wave.groupFetch", - "order.wave.singleFetch", - "order.wave.fetch" - ], - "notes": [ - "auto_fetch_disabled_marker 字段已从代码 submitFetchTask 响应中移除,文档同步删除该字段的描述。", - "auto_fetch_disabled 字段同样已从代码中移除,且原文档中不存在此字段(仅有 auto_fetch_disabled_marker),无需额外处理。", - "涉及 method:order.wave.groupFetch、order.wave.singleFetch、order.wave.fetch,均移除 response 中的 auto_fetch_disabled_marker 字段。" - ], - "type": "updated", - "module": "order.wave" - }, - { - "version": "2026.06.08-system-01", - "date": "2026-06-08", - "summary": "order.recheckOrder 模块 scanOrder 返回值重构为统一 list 输出,新增 confirmIntercept 与 recheckOrderList 接口", - "methods": [ - "order.recheckOrder.scanOrder", - "order.recheckOrder.confirmIntercept", - "order.recheckOrder.recheckOrderList" - ], - "notes": [ - "scanOrder 返回值重构:统一使用 list 字段输出,新增 list_type 字段区分散单/团购模式。散单模式顶层新增 picker_id、picker_name、wave_id、wave_no、wave_type、pick_mode、strategy_id、strategy_name、total_orders、reviewed_count、unreviewed_count 等汇总字段。list 中每项新增 waybill_no、is_printed、is_reviewed、wave_index、intercept_status、store_remark、stock[](含 stock_id、item_code、item_name、sku_property、packing_requirements、barcodes[]、images[]、plan_qty、has_shared_barcode)。移除旧字段 logs、order、order_id(顶层)、waybill_no(顶层旧位置)、wave_match_view、items、expresses、cart_match_view。", - "scanOrder 入参新增 wave_no / waveNo 支持波次号直接扫描匹配。", - "新增 order.recheckOrder.confirmIntercept:确认拦截接口,将订单 intercept_status 更新为 intercepted_at_warehouse,返回 order_id、order_no、intercept_status、updated_at。", - "新增 order.recheckOrder.recheckOrderList:复核订单列表查询,支持 list_type=single(散单)与 list_type=group(团购),均返回统一 list + pagination 结构。" - ], - "type": "updated" - }, - { - "version": "2026.06.08-system-02", - "date": "2026-06-08", - "summary": "order.recheckOrder 模块新增 batchIntercept/batchInterceptTaskProgress,更新 scanOrder 团购模式响应结构,完善 confirmIntercept/recheckOrderList 文档", - "methods": [ - "order.recheckOrder.batchIntercept", - "order.recheckOrder.batchInterceptTaskProgress", - "order.recheckOrder.scanOrder", - "order.recheckOrder.confirmIntercept", - "order.recheckOrder.recheckOrderList" - ], - "notes": [ - "新增 order.recheckOrder.batchIntercept:批量提交订单拦截(异步任务模式),入参支持 order_ids/orderIds/ids(订单ID数组,不再使用 wave_ids),将 intercept_status 设为 'requested',返回 task_id/warehouse_id/message/accepted_at。支持幂等提交与 warehouse_id 校验。", - "新增 order.recheckOrder.batchInterceptTaskProgress:按 task_id 查询批量拦截任务进度,返回 state(submitted/running/success/failed/not_found)及对应的进度/计数/结果/错误字段。", - "更新 order.recheckOrder.scanOrder 响应文档:团购模式(cart 命中)list 项新增 wave_id/wave_no/wave_type/wave_status/total_orders/processed_orders/creator/create_time/update_time/order_count/pick_mode/box_no/orders[] 等波次级别字段;补充散单无波次信息时的回退详情模式说明(detail/items/expresses/logs)。", - "完善 order.recheckOrder.confirmIntercept:补充操作日志写入说明(ORDER_INTERCEPT_CONFIRM)及失败不影响主流程的容错描述。", - "完善 order.recheckOrder.recheckOrderList:补充散单模式默认排除 pick_status='none' 和 recheck_status='fin' 的说明;团购模式 where 支持 wave_no(模糊搜索)的说明。" - ], - "type": "updated" - }, - { - "version": "2026.06.08-system-03", - "date": "2026-06-08", - "summary": "移除 order.recheckOrder.batchIntercept 的 warehouse_id/warehouseId 入参,仓库ID统一使用当前上下文", - "methods": [ - "order.recheckOrder.batchIntercept" - ], - "notes": [ - "移除入参 warehouse_id / warehouseId:仓库ID统一从当前上下文(ctx.user.store_id)获取,不再由调用方传入。", - "移除对应错误码:warehouse_id 参数不合法(400)、warehouse_id 与当前仓库上下文不一致(400)。", - "description 中补充说明仓库ID来源为当前上下文。", - "response 中 warehouse_id 字段描述改为「取自当前上下文」。" - ], - "type": "updated" - }, - { - "version": "2026.06.08-system-10", - "date": "2026-06-08", - "summary": "batchIntercept / batchInterceptTaskProgress 从 order.recheckOrder 迁移至 order.pendingOrder", - "methods": [ - "order.pendingOrder.batchIntercept", - "order.pendingOrder.batchInterceptTaskProgress" - ], - "notes": [ - "method 从 order.recheckOrder.batchIntercept 重命名为 order.pendingOrder.batchIntercept,分组从订单复核模块迁移至订单待处理模块", - "method 从 order.recheckOrder.batchInterceptTaskProgress 重命名为 order.pendingOrder.batchInterceptTaskProgress,分组从订单复核模块迁移至订单待处理模块", - "接口入参、响应、错误码均保持不变,仅变更 method 名称与所属分组" - ], - "type": "updated" - }, - { - "version": "2026.06.08-system-04", - "date": "2026-06-08", - "summary": "新增 order.print.getOrderPrintData:按订单ID拉取打印数据,返回结构与 getWavePlatformPrintData 一致,不限制锁定状态", - "methods": [ - "order.print.getOrderPrintData" - ], - "notes": [ - "新增 order.print.getOrderPrintData 接口文档,入参为 warehouse_id + order_ids(非空数组),返回与 getWavePlatformPrintData 结构一致的 waveGroups / summary / wave_ids / ext", - "与 getWavePlatformPrintData 的区别:入参为 order_ids(非 wave_ids),ext 中返回 missing_order_ids / filtered_order_ids(非 missing_wave_ids / filtered_wave_ids)", - "不限制打印锁定状态,所有订单(无论是否被锁定)统一返回打印数据", - "自动过滤 post_status !== 'fin' 的订单(快递未完全分配),被过滤订单出现在 ext.filtered_order_ids" - ], - "type": "added", - "module": "order.print" - }, - { - "version": "2026.06.08-system-11", - "date": "2026-06-08", - "summary": "新增 order.pendingOrder 批量锁定/解锁/解除拦截及对应进度查询共 6 个异步任务接口文档", - "methods": [ - "order.pendingOrder.batchLock", - "order.pendingOrder.batchLockTaskProgress", - "order.pendingOrder.batchUnlock", - "order.pendingOrder.batchUnlockTaskProgress", - "order.pendingOrder.batchUnintercept", - "order.pendingOrder.batchUninterceptTaskProgress" - ], - "notes": [ - "新增 batchLock:批量锁定订单,lock_status → 'warehouse',操作日志 ORDER_LOCK,task_id 格式 order_lock_{warehouseId}_{timestamp}_{rand}。", - "新增 batchLockTaskProgress:查询批量锁定进度,返回 locked_order_count / locked_order_ids 等。", - "新增 batchUnlock:批量解锁订单,lock_status → 'none',操作日志 ORDER_UNLOCK,task_id 格式 order_unlock_{warehouseId}_{timestamp}_{rand}。", - "新增 batchUnlockTaskProgress:查询批量解锁进度,返回 unlocked_order_count / unlocked_order_ids 等。", - "新增 batchUnintercept:批量解除拦截订单,intercept_status → 'none',操作日志 ORDER_INTERCEPT_CANCEL,task_id 格式 order_unintercept_{warehouseId}_{timestamp}_{rand}。", - "新增 batchUninterceptTaskProgress:查询批量解除拦截进度,返回 unintercepted_order_count / unintercepted_order_ids 等。", - "以上 6 个接口均采用与已有 batchIntercept/batchInterceptTaskProgress 一致的异步任务模式:提交返回 task_id,进度查询返回 state + 进度字段。", - "仅同步文档,不修改业务代码或实现。" - ], - "type": "added", - "module": "order" - }, - { - "version": "2026.06.08-system-12", - "date": "2026-06-08", - "summary": "更新 order.print.getOrderPrintData:移除锁定限制,所有订单统一返回打印数据,不再区分锁定/未锁定", - "methods": [ - "order.print.getOrderPrintData" - ], - "notes": [ - "移除打印锁定限制:所有订单(包括已锁定)统一返回打印数据,不再区分锁定/未锁定状态", - "移除 locked_count、locked_orders、locked_wave_groups 等锁定相关字段", - "返回结构与 getWavePlatformPrintData 完全一致:summary / waveGroups / wave_ids / ext", - "ext 中使用 missing_order_ids / filtered_order_ids(替代锁定相关字段),与代码实现完全对齐" - ], - "type": "updated", - "module": "order.print" - }, - { - "version": "2026.06.08-system-13", - "date": "2026-06-08", - "summary": "更新 order.print.getOrderPrintData:移除 warehouse_id 入参,仓库ID统一从当前上下文获取", - "methods": [ - "order.print.getOrderPrintData" - ], - "notes": [ - "移除 warehouse_id / warehouseId 入参,仓库ID统一从 this.getContextWarehouseId() 获取", - "同步移除 errors 中 warehouse_id 必填 相关错误码", - "description 补充说明仓库ID从上下文获取,无需调用方传入", - "params 仅保留 order_ids(非空数组),与代码 method 层 getOrderPrintData(data) 解构一致" - ], - "type": "updated", - "module": "order.print" - }, - { - "version": "2026.06.08-system-14", - "date": "2026-06-08", - "summary": "新增 order.recheckOrder.scanTask 接口文档,并为 scanOrder 响应补充 task_id 字段", - "methods": [ - "order.recheckOrder.scanTask", - "order.recheckOrder.scanOrder" - ], - "notes": [ - "新增 order.recheckOrder.scanTask:按拣货任务 ID 拉取复核数据,数据结构与 scanOrder 完全一致,用于前端刷新。入参为 task_id(必填,number),返回 match_type='task',散单模式(pick_mode 2/3/4)返回扁平订单列表,团购模式(pick_mode 1/5)返回分组波次列表。", - "更新 order.recheckOrder.scanOrder 响应定义:补充 task_id 字段说明(散单有波次时由 buildSingleWaveScanView 返回,团单车号命中时由 cartMatchContext 返回)。", - "仅同步文档,不修改任何业务代码或实现。" - ], - "type": "updated" - }, - { - "version": "2026.06.08-system-15", - "date": "2026-06-08", - "summary": "新增 order.pendingOrder.manualWaybill 接口(手工录入运单号)", - "methods": [ - "order.pendingOrder.manualWaybill" - ], - "notes": [ - "为待处理订单手动录入运单号,写入 wms_order_express 表", - "仅允许 step 在 [1,2,3] 且 outbound_status 不为 'padding' 的订单操作", - "免权限(isNeedAuth: false),需登录", - "成功返回运单记录的 id、order_id、waybill_code、create_at" - ], - "type": "added" - }, - { - "version": "2026.06.09-system-01", - "date": "2026-06-09", - "summary": "order.pendingOrder.updateAddress 新增 remark 字段:订单留言/备注批量覆盖,不受 post_status 限制", - "methods": [ - "order.pendingOrder.updateAddress" - ], - "notes": [ - "在 params 中新增 remark 字段(string,可选,最大500字符),支持批量覆盖所选订单的 remark", - "remark 更新不受 post_status 限制,可对所有订单生效(地址字段仍仅允许 post_status='none')", - "更新 description 明确 remark 与地址字段的独立性", - "更新 response 中 updated_count 说明:取地址更新行数与备注更新行数的最大值", - "更新 errors 中缺少字段的错误描述,改为「至少需要提供一个地址字段或备注进行修改」", - "业务代码已同步实现,本次仅同步文档" - ], - "type": "updated" - }, - { - "version": "2026.06.09-system-02", - "date": "2026-06-09", - "summary": "order.updateExpressWeighingWeight 新增运单号模式文档:order_id=0 时从运单号反查,支持散单与团购批量两种返回结构", - "methods": [ - "order.updateExpressWeighingWeight" - ], - "notes": [ - "order_id 参数说明补充:设为0时切换为运单号模式,需配合 waybill_code 使用。", - "waybill_code 参数说明补充:运单号模式(order_id=0)下必填。", - "description 更新:明确订单模式与运单号模式两种路径及团购波次批量行为。", - "response 新增运单号散单场景字段(order_id、waybill_code、weighing_weight)与运单号团购批量场景字段(wave_no、business_key、weighing_weight、success_count)。", - "errors 新增运单号模式相关错误码:运单号不存在(404)、运单号对应的订单不存在(404)、波次下未找到订单(404)、批量更新失败(500)。", - "仅文档同步,不修改业务代码。" - ], - "type": "updated" - }, - { - "version": "2026.06.09-system-03", - "date": "2026-06-09", - "summary": "order.updateExpressWeighingWeight 团购返回新增拆单汇总字段,移除 success_count/total_count", - "methods": [ - "order.updateExpressWeighingWeight" - ], - "notes": [ - "团购批量模式 response 新增 total_weight(所有拆单重量累加)、split_count(waybill_code 非空的 business_key 数量)、splits(按 business_key 分组的拆单明细数组,每项含 business_key/weighing_weight/waybill_code)、store_name(货主名称)和 sys_logistics_name(系统快递名称)。", - "移除 response 中的 success_count 与 total_count 字段,改为由 total_weight 和 split_count 提供汇总信息。", - "更新 description 以反映团购模式返回拆单汇总结构。" - ], - "type": "updated" - }, - { - "version": "2026.06.10-system-01", - "date": "2026-06-10", - "summary": "order.detail 接口文档:expresses 数组新增字段 weighing_weight、sys_logistics_code、sys_logistics_name、business_key、created_at", - "methods": [ - "order.detail" - ], - "notes": [ - "expresses 数组新增字段:weighing_weight(称重重量,number|null)、sys_logistics_code(系统物流公司编码,string)、sys_logistics_name(系统物流公司名称,string)、business_key(业务标识,string)、created_at(创建时间戳毫秒,number|null)", - "字段来源:getOrderExpressesByOrderId 方法中 sys_logistics_code/sys_logistics_name 取自订单表 sys_logistics_code/sys_logistics_name,其余字段取自 OrderExpress 表" - ], - "type": "updated" - }, - { - "version": "2026.06.10-system-02", - "date": "2026-06-10", - "summary": "dashboard.order_trend 从 mock 数据改为查询真实数据库,按小时统计当日订单数与发货数,补充完整返回结构与错误说明", - "methods": [ - "dashboard.order_trend" - ], - "notes": [ - "接口实现从 mock 静态数据改为查询真实数据库(wms_order_delivery 与 dispatch 表),数据实时反映仓库当日运营情况。", - "订单筛选条件:step in [1,2,3],排除 outbound_status='padding' 和 status='cancel',统计 create_at 在今日 00:00 到当前时刻的订单,按 HOUR(create_at) 分组。", - "发货筛选条件:dispatch_lane='m4',统计 delivery_time 在今日 00:00 到当前时刻的发货记录,按 HOUR(delivery_time) 分组。", - "时段范围:从 08:00 到当前小时(最晚 23:00),若当前时间早于 08:00 则从 08:00 开始。", - "返回新增 summary 汇总对象:total_orders(订单总数)、total_shipments(发货总数)、shipment_rate(发货率百分比)、peak_hour(峰值时段)、peak_orders(峰值订单数)。", - "categories/orders/shipments 三个数组一一对应,提供按时段的订单与发货趋势数据,可直接用于前端折线图/柱状图渲染。", - "需要登录(Authorization header),从 token 中获取 warehouseId;若缺少仓库上下文则返回 flag='fail'。" - ], - "type": "updated", - "module": "dashboard" - }, - { - "version": "2026.06.10-system-03", - "date": "2026-06-10", - "summary": "order.pendingOrder.manualWaybill 新增可选参数 logistics_interface_name 与响应字段 business_key/logistics_interface_name,补充行为说明", - "methods": [ - "order.pendingOrder.manualWaybill" - ], - "notes": [ - "新增可选参数 logistics_interface_name(string,选填,trim 后为空则传 null)", - "响应新增字段 business_key(number):同一订单下从已有最大值 +1 递增,无记录时从 1 开始", - "响应新增字段 logistics_interface_name(string/null):写入的物流接口名称", - "补充 description 行为说明:完成后自动更新 wms_order_delivery_* 表的 print_status 和 post_status 为 'fin'", - "wms_order_express 表写入时 status 固定为 1,warehouse_id 从订单记录取" - ], - "type": "updated" - }, - { - "version": "2026.06.10-system-04", - "date": "2026-06-10", - "summary": "stock.warehouse.import 新增 barcode(条码)字段支持", - "methods": [ - "stock.warehouse.import" - ], - "notes": [ - "新增 barcode(条码)字段支持,支持别名:条码、bar_code、barCode、barcodeList、barcode_list、barcode。", - "条码字段支持数组格式(如 [\"6901234567890\"])和分号分隔字符串格式(如 \"6901234567890;6901234567891\")。", - "新建和更新路径均已支持条码导入,条码写入 wms_stock_barcodes 表。", - "仅同步文档,不修改业务代码或实现。" - ], - "type": "updated" - }, - { - "version": "2026.06.10-system-05", - "date": "2026-06-10", - "summary": "stock.warehouse.import 的 barcode 字段分隔符改为逗号,对齐 stock.warehouse.export 导出格式;仅接收字符串格式,不再支持数组", - "methods": [ - "stock.warehouse.import" - ], - "notes": [ - "barcode 字段分隔符从分号 ; 改为逗号 ,", - "barcode 字段仅接收字符串格式,不再支持数组格式", - "格式示例:\"6901234567890,6901234567891\",与 stock.warehouse.export 导出格式一致" - ], - "type": "modified" - }, - { - "version": "2026.06.13-system-01", - "date": "2026-06-13", - "summary": "setting.warehouse 的 auto_outbound_rules 新增 require_print 和 require_pick 两个可选条件字段(同步代码实现)", - "methods": [ - "setting.warehouse.getSettings", - "setting.warehouse.saveSettings" - ], - "notes": [ - "在 getSettings 响应和 saveSettings 入参中补充 subject_config.auto_outbound_rules 对象的完整字段文档(enabled、require_recheck、require_pack、require_weigh、require_sync、require_print、require_pick)。", - "require_print:是否要求已打印(print_status=fin),默认 true。", - "require_pick:是否要求已拣货(pick_status=fin),默认 true。", - "该规则由自动出库定时任务 order_auto_outbound 消费,全部开启的条件均满足时自动标记待出库。" - ], - "type": "updated" - }, - { - "version": "2026.06.13-system-02", - "date": "2026-06-13", - "summary": "order.recheckOrder.scanOrder 团购模式响应新增 orders_detail 字段,暴露非拦截订单的详细列表(含 is_printed、is_reviewed 等状态字段)", - "methods": [ - "order.recheckOrder.scanOrder" - ], - "notes": [ - "团购模式(list_type='group')波次视图项新增 orders_detail 字段:非拦截订单详细列表,每项含 order_id、delivery_order_code、waybill_no、pick_status、is_printed(print_status === 'fin')、is_reviewed(recheck_status === 'fin')、recheck_status、shop_nick、items_count、wave_index、intercept_status", - "orders_detail 与现有 order_ids(纯数字 ID 数组)并存,均在团购模式的波次视图项中返回", - "orders_detail 仅在 list_type='group' 时返回,散单模式不受影响", - "同步更新 list 字段 description 以反映 group 模式新增的 order_ids、orders_detail、stocks 字段" - ], - "type": "updated" - }, - { - "version": "2026.06.13-system-03", - "date": "2026-06-13", - "summary": "新增批量快捷复核接口 batchQuickRecheck,支持批量订单 IDs 的前置条件检查(储位、快递、同步、拦截),自动完成拣货并标记复核,支持部分失败。拣货完成后同步更新 wms_wave_pick_task 状态", - "methods": [ - "order.recheckOrder.batchQuickRecheck" - ], - "notes": [ - "新增 order.recheckOrder.batchQuickRecheck 方法", - "入参 ids 支持数组或逗号分隔字符串", - "响应包含 success/failed 列表及计数,failed 项含 reason 说明" - ], - "details": { - "description": "包含拣货任务状态同步:全部拣完→任务状态=2(已完成),未全拣完→任务状态推进为1(拣货中)" - }, - "type": "added" - }, - { - "version": "2026.06.14-system-01", - "date": "2026-06-14", - "summary": "新增 order.bindExpressPackageMaterialByWaybill 方法:支持仅凭运单号绑定包材,无需传入订单ID", - "methods": [ - "order.bindExpressPackageMaterialByWaybill" - ], - "notes": [ - "新增 order.bindExpressPackageMaterialByWaybill 入参说明:waybill_code(运单号,必填)、package_material_code(包材编码,必填)。无需传入 order_id。", - "成功返回字段:order_id、waybill_code、package_material_id、package_material_name_snapshot、package_material_code。", - "错误码定义:400(参数错误)、404(运单号不存在 / 包材编码不存在)、500(绑定包材失败)。" - ], - "type": "added" - }, - { - "version": "2026.06.15-system-01", - "date": "2026-06-15", - "summary": "order.detail / order.deliveryOrder.detail 的 expresses 数组新增包材字段", - "methods": [ - "order.detail", - "order.deliveryOrder.detail" - ], - "notes": [ - "expresses 数组每个元素新增 package_material_id(包材ID,number|null)和 package_material_name_snapshot(包材名称快照,string|null)字段。" - ], - "type": "updated" - }, - { - "version": "2026.06.15-system-02", - "date": "2026-06-15", - "summary": "order.deliveryOrder.detail 的 expresses 数组新增包材字段", - "methods": [ - "order.deliveryOrder.detail" - ], - "notes": [ - "expresses 数组每个元素新增 package_material_id(包材ID,number|null)和 package_material_name_snapshot(包材名称快照,string|null)字段。" - ], - "type": "updated" - }, - { - "version": "2026.06.15-system-03", - "date": "2026-06-15", - "summary": "新增 setting.packageMaterial.search 方法:支持按关键字模糊搜索包材编码和名称", - "methods": [ - "setting.packageMaterial.search" - ], - "notes": [ - "新增 setting.packageMaterial.search 入参 keyword(可选),为空返回前 50 条启用中包材,有值时对 material_code 和 material_name 做模糊匹配。", - "返回包材数组,字段:id、material_code、material_name、material_type、spec、status。" - ], - "type": "added" - }, - { - "version": "2026.06.16-system-01", - "date": "2026-06-16", - "summary": "新增 order.recheckOrder.queryRecheckOrderSingleList:散单复核列表接口,响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", - "methods": [ - "order.recheckOrder.queryRecheckOrderSingleList" - ], - "notes": [ - "新增方法 order.recheckOrder.queryRecheckOrderSingleList,为 recheckOrderList 散单模式的独立入口。", - "响应 list 每项新增字段 items_weight (DECIMAL(10,2)):订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null。", - "响应 list 每项新增字段 weight_type (string):重量类型中文标签,来自 wms_order.weight_type 经 formatWeightTypeLabel 转换;取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。" - ], - "type": "added", - "module": "order.recheckOrder" - }, - { - "version": "2026.06.16-system-02", - "date": "2026-06-16", - "summary": "为 order.wave.groupOrderFetchList / waveStrategyFallbackOrderList / singleOrderFetchList 响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", - "methods": [ - "order.wave.groupOrderFetchList", - "order.wave.waveStrategyFallbackOrderList", - "order.wave.singleOrderFetchList" - ], - "notes": [ - "order.wave.groupOrderFetchList:响应 list 每项新增 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", - "order.wave.waveStrategyFallbackOrderList:响应 list 每项新增 items_weight (number|null):订单总重量(g),来自 wms_order.items_weight;新增 weight_type (string):重量类型中文标签,取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。", - "order.wave.singleOrderFetchList:响应 list 每项新增 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", - "所有新增字段均为可选(required=false),为 null 时返回 null。" - ], - "type": "updated", - "module": "order.wave" - }, - { - "version": "2026.06.17-system-01", - "date": "2026-06-17", - "summary": "新增 order.pendingOrder.replenishmentDemand 分拣缺货补货需求计算接口文档", - "methods": [ - "order.pendingOrder.replenishmentDemand" - ], - "notes": [ - "新增分拣缺货补货需求计算方法,用于计算待处理订单的SKU在分拣区与存货区的库存分布及补货缺口", - "入参 order_ids/warehouse_id 均为可选;不传 order_ids 时自动查询当前仓库所有未完成储位分配的订单", - "纯只读查询接口,不修改任何数据", - "响应包含 list(明细)与 summary(汇总),其中 shortage = max(0, total_demand - pick_zone_quantity),replenishment_needed = min(shortage, storage_zone_quantity)" - ], - "type": "add", - "module": "order.pendingOrder" - }, - { - "version": "2026.06.17-system-02", - "date": "2026-06-17", - "type": "update", - "module": "order.pendingOrder", - "method": "order.pendingOrder.replenishmentDemand", - "description": "移除 order_ids 参数,改为纯仓库级别计算,自动查询当前仓库所有未完成储位分配的订单" - }, - { - "version": "2026.06.17-system-03", - "date": "2026-06-17", - "type": "update", - "module": "order.pendingOrder", - "method": "order.pendingOrder.replenishmentDemand", - "description": "新增 is_true_shortage 字段标识真正缺货(两区均无库存),summary 新增 total_true_shortage_skus 统计" - }, - { - "version": "2026.06.17-system-04", - "date": "2026-06-17", - "type": "migrate", - "module": "storage.management", - "summary": "从 order.pendingOrder.replenishmentDemand 迁移至 storage.management.replenishmentDemand(库存管理模块),原路径已删除,开发阶段无需兼容", - "methods": [ - "storage.management.replenishmentDemand" - ], - "notes": [ - "将 replenishmentDemand 接口从 order.pendingOrder 模块迁移到新建的 storage.management 库存管理模块。", - "旧条目 order.pendingOrder.replenishmentDemand 已从 order.pendingOrder 组中移除。", - "开发阶段无需兼容旧路径。" - ] - }, - { - "version": "2026.06.17-system-05", - "date": "2026-06-17", - "type": "update", - "module": "storage.management", - "summary": "storage.management.replenishmentDemand 移除 warehouse_id 入参,仓库ID改为纯从用户上下文(ctx.user)获取,接口无需入参", - "methods": [ - "storage.management.replenishmentDemand" - ], - "notes": [ - "移除 warehouse_id 入参,仓库ID改为纯从用户上下文(ctx.user)获取,接口无需入参" - ] - }, - { - "version": "2026.06.17-system-06", - "date": "2026-06-17", - "type": "update", - "module": "storage.management", - "method": "storage.management.replenishmentDemand", - "description": "新增分页入参(pagination)、排序入参(sort,默认按 shortage DESC)、响应新增 replenishment_locations(存货区可补货库位,最多5条)、响应新增 pagination 分页信息" - }, - { - "version": "2026.06.17-system-07", - "date": "2026-06-17", - "type": "update", - "module": "storage.management", - "summary": "replenishment_locations 新增 space_name 字段,优先取自定义名称(custom_name),无则回退库位编码(space_code)", - "methods": [ - "storage.management.replenishmentDemand" - ], - "notes": [ - "在 replenishment_locations.children 中新增 space_name 字段(string, required),放在 space_code 之后、available_quantity 之前。", - "space_name 取值逻辑:优先使用库位自定义名称 custom_name,若无自定义名称则回退为库位编码 space_code。" - ] - }, - { - "version": "2026.06.17-system-08", - "date": "2026-06-17", - "type": "update", - "module": "storage.management", - "summary": "合并 is_sufficient 和 is_true_shortage 为 replenishment_status 枚举字段(replenishable/true_shortage)", - "methods": [ - "storage.management.replenishmentDemand" - ], - "notes": [ - "删除 is_sufficient(boolean)和 is_true_shortage(boolean)两个字段。", - "新增 replenishment_status(string)枚举字段:replenishable=存货区足够覆盖缺口,移库可解决;true_shortage=存货区不足以覆盖缺口或两区均无库存,需采购。" - ] - }, - { - "version": "2026.06.18-system-01", - "date": "2026-06-18", - "summary": "入库单完成后异步匹配收货单并回传:completeEntry / entryorderConfirm 入库完成时自动匹配收货单,明细一致则按来源回传(奇门/OpenAPI),覆盖场景标记收货单部分入库;completeReceiving 完成后清除收货单缓存", - "methods": [ - "storage.entry.completeEntry", - "storage.receiving.completeReceiving" - ], - "notes": [ - "新增 app/service/systems/receiving_entry_match.js:入库单完成后异步匹配收货单并回传的核心服务,含 Redis 缓存收货单列表(TTL 300s)、remark 匹配收货单号、明细对比、奇门回传、OpenAPI 回调、部分入库标记等能力。", - "storage.entry.completeEntry 完成后通过 setImmediate 异步触发 matchAfterEntryCompleted,不阻塞主流程。", - "entry_order.js entryorderConfirm() 事务提交后(isFin 最终完成)同样异步触发匹配。", - "storage.receiving.completeReceiving 完成后清除收货单 Redis 缓存(cache:receiving_orders:warehouse:{warehouseId}),确保下次匹配获取最新收货单列表。", - "匹配规则:入库单 remark 包含收货单号 → 对比 SKU+数量 → 完全一致回传 / 收货单覆盖标记部分入库 / 其他不处理。", - "回传路径:source_type=QM → 奇门 taobao.qimen.entryorder.confirm;source_type=API → OpenAPI 回调(entry_order_receiving_matched 事件)。" - ], - "type": "updated" - }, - { - "version": "2026.06.18-system-02", - "date": "2026-06-18", - "summary": "新增 storage.receiving.manualMatchEntryOrder 接口", - "methods": [ - "storage.receiving.manualMatchEntryOrder" - ], - "notes": [ - "新增 storage.receiving.manualMatchEntryOrder:手动匹配入库单与收货单,传入 receivingId 和 entryOrderId,复用异步匹配服务的明细对比和回传逻辑,同步返回匹配结果", - "参数:receivingId (number, 必填)、entryOrderId (number, 必填)", - "校验:入库单存在性、收货单存在性、同仓库校验", - "返回 matchType (full_match/receiving_covers_entry/entry_exceeds_receiving/no_match)、comparisonResult、callbackSent、callbackResult、partialStorageMarked、entryOrder、receivingOrder" - ], - "type": "added", - "module": "storage" - }, - { - "version": "2026.06.18-system-03", - "date": "2026-06-18", - "summary": "新增 storage.receiving.getAvailableInboundQuantity 接口:按 stock_id 查询已审核收货单的可入库数量(actual_quantity - stored_quantity),排除未审核和已取消的收货单", - "methods": [ - "storage.receiving.getAvailableInboundQuantity" - ], - "notes": [ - "新增 system method:storage.receiving.getAvailableInboundQuantity,按 stock_id 查询已审核收货单中各明细的可入库数量(actual_quantity - stored_quantity),仅返回尚有可入库余量的明细。", - "实现文件:app/service/systemMethods/storage/receiving.js(包装层)、app/service/systems/storage/receiving.js(业务层)。", - "接口无需鉴权(isNeedAuth=false),但需要登录(isNeedLogin=true)。", - "入参 stock_id 为必填,对应 stock_warehouse.id;服务端从 ctx.user.store_id 获取仓库上下文。" - ], - "type": "added", - "module": "storage" - }, - { - "version": "2026.06.18-system-04", - "date": "2026-06-18", - "summary": "新增 storage.entry.bindReceivingDetails 接口和 wms_entry_receiving_binding 中间表:入库单明细可显式绑定收货明细(pending状态),提交入库时事务内完成双向扣减(stored_quantity/received_quantity),通过唯一约束和行锁防止超分和重复绑定。同时重构 completeEntry 调用链为 commitEntryWithBindings,无绑定时向后兼容。", - "methods": [ - "storage.entry.bindReceivingDetails", - "storage.entry.completeEntry" - ], - "notes": [ - "新增 storage.entry.bindReceivingDetails 方法:入库单明细绑定收货明细,pending 状态软绑定,每次调用清除旧 pending 绑定后创建新绑定。", - "新增 wms_entry_receiving_binding 中间表(migration: 20260618150000-create-wms-entry-receiving-binding.js),用于记录入库明细与收货明细的绑定关系。", - "重构 completeEntry 调用链:systemMethods 层 completeEntry 改为调用 commitEntryWithBindings,有绑定则事务内完成双向扣减(stored_quantity/received_quantity),无绑定时向后兼容仅变更入库单状态。", - "通过数据库唯一约束和行锁(SELECT ... FOR UPDATE)防止超分和重复绑定。", - "涉及文件: app/model/entry_receiving_binding.js, app/service/systems/storage/entry.js, app/service/systemMethods/storage/entry.js, database/migrations/20260618150000-create-wms-entry-receiving-binding.js" - ], - "type": "added", - "module": "storage.entry" - }, - { - "version": "2026.06.18-system-05", - "date": "2026-06-18", - "summary": "storage.entry.get 响应追加 pending_total/total_planned/bindings 字段,storage.receiving.getAvailableInboundQuantity 响应追加 pending_allocated_quantity 字段:前端可通过 get 查看入库明细的绑定状态,getAvailableInboundQuantity 的可用量已扣除全局 pending 绑定总量", - "methods": [ - "storage.entry.get", - "storage.receiving.getAvailableInboundQuantity" - ], - "notes": [ - "storage.entry.get:items 数组每项新增 pending_total(该入库明细当前 pending 绑定的总预分配数量)、total_planned(计划入库数量=count)、bindings(pending 绑定列表,每项含 id/entry_item_id/receiving_detail_id/allocated_quantity/status/receivingDetail 子对象)", - "storage.receiving.getAvailableInboundQuantity:list 每项新增 pending_allocated_quantity(该收货明细在当前 stock_id 所有入库单中的 pending 绑定总量),available_quantity 计算已扣除该值" - ], - "type": "updated" - }, - { - "version": "2026.06.18-system-06", - "date": "2026-06-18", - "summary": "bindReceivingDetails 重构为\"绑定即实收\"(received_quantity 在绑定时更新,不再等到 completeEntry),新增 unbindReceivingDetails 解绑接口(删除 pending 绑定并回退 received_quantity),commitEntryWithBindings 移除 received_quantity 更新逻辑", - "methods": [ - "storage.entry.bindReceivingDetails", - "storage.entry.unbindReceivingDetails", - "storage.entry.completeEntry" - ], - "notes": [ - "storage.entry.bindReceivingDetails:改为绑定即实收,绑定成功后立即更新入库明细 received_quantity;重复调用时先回退旧绑定量再创建新绑定,避免重复累加。", - "storage.entry.unbindReceivingDetails:新增解绑接口,删除该入库明细的所有 pending 绑定记录,并将 received_quantity 回退到绑定前的值;收货明细可用数量随绑定记录删除自动恢复。", - "storage.entry.completeEntry:commitEntryWithBindings 中移除 received_quantity 更新逻辑(received_quantity 已在绑定时更新,completeEntry 仅完成收货单侧入库数量扣减和库存上架)。" - ], - "type": "updated" - }, - { - "version": "2026.06.19-system-01", - "date": "2026-06-19", - "summary": "order.recheckOrder.scanOrder 响应 list[] 新增 items_weight(订单商品总重量g)和 suggested_package_material(推荐包材)字段", - "methods": [ - "order.recheckOrder.scanOrder" - ], - "notes": [ - "响应 list 每项新增 items_weight (number|null):订单商品总重量(g),来源于 wms_order_delivery.items_weight。散单模式每个订单对象包含,团购模式每个波次对象包含(取波次内首个正常订单的重量,为 null 时返回 0)。", - "响应 list 每项新增 suggested_package_material (object|null):推荐包材信息,根据订单商品结构(items_hash + items_crc)匹配 wms_package_material_item_relation 历史绑定记录,按 bind_count 降序取最优匹配。若 items_hash 为空或无匹配记录则为 null。包含子字段:id、code、name、spec、type、weight、length、width、height、bind_count。", - "同步更新 method description 和 list 字段 description,补充新增字段的说明。" - ], - "type": "updated", - "module": "order.recheckOrder" - }, - { - "version": "2026.06.21-system-01", - "date": "2026-06-21", - "summary": "order.bindExpressPackageMaterialByWaybill:入参 package_material_code 改为 package_material_id,类型由 string 改为 number|string", - "methods": [ - "order.bindExpressPackageMaterialByWaybill" - ], - "notes": [ - "入参字段名从 package_material_code 改为 package_material_id。", - "入参类型从 string 改为 number|string,与代码 normalizePackageMaterialId 的实现一致。", - "同步更新该方法 description 中'包材编码'为'包材ID'。" - ], - "type": "updated", - "module": "order" - }, - { - "version": "2026.06.21-system-comboGoods-01", - "date": "2026-06-21", - "summary": "新增 comboGoods 组合商品模块 5 个接口文档:list/create/update/delete/search", - "methods": [ - "comboGoods.list", - "comboGoods.create", - "comboGoods.update", - "comboGoods.delete", - "comboGoods.search" - ], - "notes": [ - "comboGoods.list:组合商品列表查询(分页),支持按 combo_code/combo_name/status/warehouse_id 筛选,返回含 simpleNotation 和 nameNotation 简记字段", - "comboGoods.create:创建组合商品(含明细一次性提交),校验 combo_code 唯一性、子商品有效性和货主一致性,事务保证原子写入", - "comboGoods.update:编辑组合商品(含明细替换),支持部分字段更新,传入 items 则先删旧明细再插入新明细", - "comboGoods.delete:软删除组合商品(status 置为 0)", - "comboGoods.search:关键字搜索组合商品,模糊匹配 combo_code 或 combo_name,仅返回启用状态记录,上限100条", - "数据表:wms_combo_goods(主表)+ wms_combo_goods_item(明细表);子商品校验依赖 wms_stock_warehouse 表", - "代码文件:app/service/systems/comboGoods.js(业务逻辑层)+ app/service/systemMethods/comboGoods.js(接口包装层)", - "isNeedAuth:list/search 无需鉴权,create/update/delete 需要鉴权" - ], - "type": "added", - "module": "comboGoods" - }, - { - "version": "2026.06.21-system-comboGoods-02", - "date": "2026-06-21", - "summary": "comboGoods 模块新增 custom_code(自定义编码)功能:create/update 支持传入 custom_code 并校验按货主唯一,list/search 返回新增 custom_code 字段,search 搜索范围扩展至 custom_code 且优先排列匹配项", - "methods": [ - "comboGoods.list", - "comboGoods.create", - "comboGoods.update", - "comboGoods.search" - ], - "notes": [ - "新增字段 custom_code(VARCHAR(64) NULL),仅做按货主唯一性校验(排除已删除记录),非全局唯一。", - "wms_combo_goods 表新增索引 uk_store_custom_code(warehouse_id, custom_code)。", - "comboGoods.create:新增可选入参 custom_code,如果非空则校验同货主非删除记录中 unique;返回新增 custom_code 字段。", - "comboGoods.update:新增可选入参 custom_code,如果非空则校验同货主非删除记录中 unique(排除自身 id)。", - "comboGoods.list:返回每条记录新增 custom_code 字段。", - "comboGoods.search:搜索条件扩大为 custom_code LIKE / combo_code LIKE / combo_name LIKE,custom_code 匹配项按 ORDER BY CASE 排在前面;返回新增 custom_code 字段。" - ], - "type": "updated" - }, - { - "version": "2026.06.21-system-comboGoods-03", - "date": "2026-06-21", - "summary": "stock.warehouse.search 新增 mode=\"combo\" 组合商品查询模式,新增 id/custom_code 参数,补充组合商品响应结构", - "methods": [ - "stock.warehouse.search" - ], - "notes": [ - "新增入参 mode(查询模式,传 \"combo\" 时搜索组合商品),id(mode=combo 时按组合商品ID精确查询),custom_code(mode=combo 时按自定义编码模糊查询)", - "原有 keyword 参数在 mode=combo 时模糊匹配 combo_code / combo_name / custom_code", - "mode=combo 响应结构新增 combo_code、combo_name、custom_code、items(子商品数组含 item_goods_sku_id/item_quantity)、simpleNotation(stock_id|数量格式)、nameNotation(【数量】商品名称格式)", - "mode=combo 时不返回 stock 模式特有的字段(item_code/goods_code/item_name/sku_property/stock_unit/quantity/locked_quantity/brand_name/item_type/barcodes/store_stock/效期字段/storage)", - "with_stock 和 is_batch 参数在 mode=combo 时不生效" - ], - "type": "updated" - }, - { - "version": "2026.06.22-system-wavePickTaskList-01", - "date": "2026-06-22", - "summary": "order.wave.wavePickTaskList 响应新增 wave_list 数组:每个拣货任务返回关联波次列表", - "methods": [ - "order.wave.wavePickTaskList" - ], - "notes": [ - "wavePickTaskList 响应 list 每项新增 wave_list 数组字段,通过批量查询 wms_wave_pick_task_wave 表获取关联波次详情。", - "wave_list 每项包含:wave_id(波次ID)、wave_no(波次号)、box_no(框号)、status(波次关联状态)、bind_time(绑定时间)、pick_time(拣货完成时间)。", - "无需额外入参,默认对所有拣货任务返回 wave_list;查询为空时返回空数组 []。", - "同步更新 methods/system.json 响应文档。" - ], - "type": "updated", - "module": "order.wave" - }, - { - "version": "2026.06.22-system-order-export-mode-01", - "date": "2026-06-22", - "summary": "order.export 新增 export_mode 参数:支持 waybill(默认,按运单展开)与 item(按商品明细展开)两种导出模式", - "methods": [ - "order.export" - ], - "notes": [ - "新增入参 export_mode/exportMode,枚举值:waybill(默认)— 按运单号展开,每运单一组,items_detail 列汇总商品;item — 按商品明细展开,每商品一行,运单信息汇总填充。", - "方法层(OrderIndexService.export)新增 export_mode/exportMode 解构并透传到 systems.orderExport.exportOrders。", - "同步更新 methods/system.json 文档:description 补充 export_mode 说明,params 新增 export_mode/exportMode 条目。", - "order.export 导出的列新增:业务类型、运单接口、包材ID、包材编码、包材名称。" - ], - "type": "updated", - "module": "order.index" - }, - { - "version": "2026.06.22-system-directInbound-01", - "date": "2026-06-22", - "summary": "新增 storage.directInbound 导入/PDA直接入库模块:getItems(获取入库信息)、addItem(增量添加商品)、commit(提交完成入库并回传)", - "methods": [ - "storage.directInbound.getItems", - "storage.directInbound.addItem", - "storage.directInbound.commit" - ], - "notes": [ - "新增 storage.directInbound 模块,用于非收货单途径的导入/PDA 直接入库场景。", - "storage.directInbound.getItems:根据入库单号获取入库明细及已有的导入/PDA 入库记录,返回每项的可入库余量。", - "storage.directInbound.addItem:按 stock_id 增量添加导入/PDA 入库记录,累加超过该 stock_id 在入库单中的计划总量时拒绝。支持 import(导入)和 pda(PDA)两种方式。", - "storage.directInbound.commit:提交确认完成入库,按实收数量写入 wms_storage 库存和 wms_storage_transaction 流水,同 stock_id 多条明细只写一次库存,更新入库单状态为 COMPLETED 并同步 sync_status=SUCCESS,异步触发奇门/API 回传(按实收数量回传)。不足量提交时未入库商品跳过。", - "新增数据表 wms_inbound_direct_log(migration: 20260622100000-create-wms-inbound-direct-log.js):记录非收货单途径入库操作,含 warehouse_id、stock_id、quantity、inbound_type(import/pda)、entry_order_id、operator 等字段。模型文件:app/model/inbound_direct_log.js。", - "新增操作日志:addItem 记录 DIRECT_INBOUND_ADD(异步),commit 记录 DIRECT_INBOUND_COMMIT(事务内)。commit 响应返回 order_status=COMPLETED 和 sync_status=SUCCESS。", - "涉及文件:app/service/systems/inbound_direct_log.js(业务层)、app/service/systemMethods/storage/direct_inbound.js(包装层)、app/model/inbound_direct_log.js、database/migrations/20260622100000-create-wms-inbound-direct-log.js、methods/system.json(新增导入/PDA入库模块)。", - "E2E 测试:test/e2e_direct_inbound.test.js(53项断言全覆盖)。" - ], - "type": "added", - "module": "storage.directInbound" - }, - { - "version": "2026.06.22-system-directInbound-02", - "date": "2026-06-22", - "summary": "storage.directInbound.addItem 新增批量模式(items 数组),getItems 响应 summary 新增 total_import/total_pda 分类型汇总", - "methods": [ - "storage.directInbound.addItem", - "storage.directInbound.getItems" - ], - "notes": [ - "addItem 新增批量模式:支持传入 items 数组一次添加多条商品,每项含 stock_id/quantity/inbound_type/remark。单条模式(stock_id/quantity/inbound_type 顶层字段)保持向后兼容。批量模式下所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。", - "addItem 批量模式响应结构:{ count, total_quantity, items: [...] },items 每项含 id/stock_id/quantity/inbound_type/plan_quantity/existing_before/existing_after/remaining。", - "getItems 响应 summary 新增 total_import(导入入库总数)和 total_pda(PDA入库总数)字段。", - "同步更新 methods/system.json 文档。" - ], - "type": "updated", - "module": "storage.directInbound" - }, - { - "version": "2026.06.22-system-directInbound-03", - "date": "2026-06-22", - "summary": "storage.directInbound 新增 space_id 库位支持:addItem 支持传入 space_id(单条和批量),commit 从入库记录取 space_id 写入 wms_storage 替代硬编码 1", - "methods": [ - "storage.directInbound.addItem", - "storage.directInbound.commit", - "storage.directInbound.getItems" - ], - "notes": [ - "addItem 新增可选入参 space_id(单条模式顶层字段 / 批量模式 items[].space_id),指定存放库位ID,关联 wms_location_space.id。", - "wms_inbound_direct_log 表新增 space_id 字段(migration: 20260622110000-add-space-id-to-wms-inbound-direct-log.js)。", - "commit 从入库记录中取第一个非空 space_id 写入 wms_storage,无记录时兜底使用库位 1。", - "getItems 响应中 direct_logs 每条记录包含 space_id 字段。", - "同步更新 methods/system.json 文档及模型文件。" - ], - "type": "updated", - "module": "storage.directInbound" - }, - { - "version": "2026.06.23-system-01", - "date": "2026-06-23", - "summary": "入库单(wms_entry_order)新增 CREATED 状态:order_status ENUM 从 CREATING/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED 扩展为 CREATING/CREATED/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED;默认值从 PENDING 变更为 CREATED;validTransitions 增加 CREATED 节点(CREATED→PENDING/CANCELLED,CREATING→CREATED/CANCELLED)", - "methods": [ - "storage.entry.list", - "storage.entry.get", - "storage.entry.cancel", - "storage.entry.completeEntry", - "storage.entry.bindReceivingDetails" - ], - "notes": [ - "Model 层:app/model/entry_order.js order_status ENUM 新增 CREATED,默认值从 PENDING 变更为 CREATED", - "Service 层:app/service/systems/entry_order.js addOrder 创建后状态从 CREATING→CREATED,validTransitions 增加 CREATED 节点", - "Service 层:app/service/systems/storage/entry.js createEntry 默认状态 PENDING→CREATED", - "Service 层:app/service/systems/storage/inventory.js 快捷入库默认 CREATED", - "文档同步:storage.entry.list where.order_status 枚举补充 CREATED;storage.entry.get description 补充 order_status 枚举含 CREATED;storage.entry.cancel 补充 CREATED 可作废说明;storage.entry.completeEntry/bindReceivingDetails 补充可操作状态含 CREATED" - ], - "type": "updated", - "module": "storage.entry" - }, - { - "version": "2026.06.23-system-02", - "date": "2026-06-23", - "summary": "入库单 CREATED 状态限制:CREATED 状态不允许绑定货物和完成入库,仅 PENDING/CONFIRMED/PARTIAL_RECEIVED 状态可操作", - "methods": [ - "storage.entry.cancel", - "storage.entry.completeEntry", - "storage.entry.bindReceivingDetails", - "storage.entry.unbindReceivingDetails" - ], - "notes": [ - "completeEntry / bindReceivingDetails / unbindReceivingDetails / commitEntryWithBindings 的可操作状态从原来的白名单(包含 CREATED)改为 PENDING / CONFIRMED / PARTIAL_RECEIVED,排除 CREATED。", - "CREATED 状态仅允许确认入库(→PENDING)或作废(→CANCELLED)。", - "storage.entry.cancel 补充明确 COMPLETED 状态不可作废,CREATED 可作废。", - "同步更新对应 method 的 description、errors 描述。" - ], - "type": "updated", - "module": "storage.entry" - }, - { - "version": "2026.06.23-system-03", - "date": "2026-06-23", - "summary": "storage.entry.cancel:CONFIRMED(已确认)状态不再允许作废,仅 CREATED 和 PENDING 可作废", - "methods": [ - "storage.entry.cancel" - ], - "notes": [ - "canCancel() 白名单移除 CONFIRMED,仅保留 CREATED 和 PENDING", - "validTransitions 中 CONFIRMED 不再可转为 CANCELLED", - "cancel() 方法新增 CONFIRMED 状态拦截,返回 400:已确认入库单不允许作废,请先完成收货", - "PARTIAL_RECEIVED 仍可作废,COMPLETED 不允许作废(行为不变)", - "更新 description 明确各状态可作废规则,errors 中补充 CONFIRMED 不可作废的说明" - ], - "type": "updated", - "module": "storage.entry" - }, - { - "version": "2026.06.23-system-04", - "date": "2026-06-23", - "summary": "入库单状态从 7 个简化为 5 个:移除 CONFIRMED 和 PARTIAL_RECEIVED,最终状态为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED;同步更新 storage.entry 所有 method 的状态枚举和错误信息描述", - "methods": [ - "storage.entry.list", - "storage.entry.get", - "storage.entry.cancel", - "storage.entry.completeEntry", - "storage.entry.bindReceivingDetails", - "storage.entry.unbindReceivingDetails" - ], - "notes": [ - "wms_entry_order.order_status ENUM 从 CREATING/CREATED/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED 简化为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED", - "storage.entry.list: where.order_status 描述和 where 参数描述中的状态枚举同步更新", - "storage.entry.get: entryOrder.order_status 描述同步更新", - "storage.entry.cancel: 移除 PARTIAL_RECEIVED 可作废和 CONFIRMED 不可作废的描述,仅保留 CREATED 和 PENDING 可作废,COMPLETED 不可作废", - "storage.entry.completeEntry: 可完成状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", - "storage.entry.bindReceivingDetails: 可操作状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", - "storage.entry.unbindReceivingDetails: 可操作状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", - "cancel() 取消 CONFIRMED 状态拦截(状态已不存在),COMPLETED 拦截保持不变" - ], - "type": "updated" - }, - { - "version": "2026.06.23-system-05", - "date": "2026-06-23", - "summary": "入库单状态语义调整:CREATED=已创建待审核,PENDING=已审核;同步更新 storage.entry 所有 method 的 description 中状态说明", - "methods": [ - "storage.entry.list", - "storage.entry.get", - "storage.entry.cancel", - "storage.entry.completeEntry", - "storage.entry.bindReceivingDetails", - "storage.entry.unbindReceivingDetails" - ], - "notes": [ - "CREATED 含义从\"已创建\"改为\"已创建待审核\"(需审核后才能绑定和完成入库)", - "PENDING 含义从\"待收货/收货中\"改为\"已审核\"(审核通过,可绑定和完成入库)", - "CREATED→PENDING 步骤语义:绑定审核", - "addOrder() 新增可选参数 autoReview(boolean,默认 false),false 创建后状态 CREATED(需审核),true 创建后状态 PENDING(自动审核通过)", - "快捷入库 quickPutaway 内部流程改为调用 addOrder({autoReview:true}) → bindReceivingDetails → commitEntryWithBindings,不再直接写库存,对外返回格式不变", - "storage.entry.list / storage.entry.get description 中补充 CREATED/PENDING 语义说明", - "storage.entry.cancel description 中补充可作废状态说明", - "storage.entry.completeEntry description 中补充可完成状态说明", - "storage.entry.bindReceivingDetails / storage.entry.unbindReceivingDetails description 中补充可绑定/解绑状态说明" - ], - "type": "updated" - }, - { - "version": "2026.06.23-system-06", - "date": "2026-06-23", - "summary": "storage.inventory.quickPutaway description 更新:补充内部已改为走 addOrder→bind→commit 链路,不再直接写库存", - "methods": [ - "storage.inventory.quickPutaway" - ], - "notes": [ - "快捷入库 quickPutaway 内部流程改为调用 addOrder({autoReview:true}) → bindReceivingDetails → commitEntryWithBindings,不再直接写库存,外部返回格式不变", - "description 中补充内部调用链路说明" - ], - "type": "updated" - }, - { - "version": "2026.06.23-system-07", - "date": "2026-06-23", - "summary": "storage.entry 大范围清理:删除 bindReceivingDetails/unbindReceivingDetails(明细级绑定已弃用),更新 completeEntry 为纯状态变更(不再做库存写入/异步匹配)", - "methods": [ - "storage.entry.bindReceivingDetails", - "storage.entry.unbindReceivingDetails", - "storage.entry.completeEntry" - ], - "notes": [ - "storage.entry.bindReceivingDetails:已从代码中删除,明细级绑定收货单功能下线。库存写入统一由 storage.inventory.matchPutaway 完成。", - "storage.entry.unbindReceivingDetails:已从代码中删除,明细级解绑功能下线。", - "storage.entry.completeEntry:改为纯状态变更(PENDING → COMPLETED),不再做库存写入和异步匹配回调。库存写入统一由 storage.inventory.matchPutaway 完成。" - ], - "type": "updated" - }, - { - "version": "2026.06.23-system-08", - "date": "2026-06-23", - "summary": "storage.inventory 清理:删除 quickPutaway(快捷入库已下线,统一由 matchPutaway 完成匹配入库)", - "methods": [ - "storage.inventory.quickPutaway" - ], - "notes": [ - "storage.inventory.quickPutaway:已从代码中删除,快捷入库功能下线。请使用 storage.inventory.matchPutaway 替代。" - ], - "type": "removed" - }, - { - "version": "2026.06.23-system-09", - "date": "2026-06-23", - "summary": "入库流程弃用清理:bindReceivingDetails/unbindReceivingDetails 标记为已删除并补充弃用原因,completeEntry 明确不涉及库存写入", - "methods": [ - "storage.entry.bindReceivingDetails", - "storage.entry.unbindReceivingDetails", - "storage.entry.completeEntry" - ], - "notes": [ - "storage.entry.bindReceivingDetails 与 storage.entry.unbindReceivingDetails 已从代码中移除,入库单与收货单关系改为 wms_entry_order_receiving 主表级关联,不再需要逐明细绑定/解绑。", - "wms_entry_receiving_binding 表不再写入新数据。", - "storage.entry.completeEntry 仅做状态变更(PENDING→COMPLETED),库存写入统一由 storage.inventory.matchPutaway 完成。", - "commitEntryWithBindings(内部方法)不再使用,库存写入统一走 matchPutaway 链路。" - ], - "type": "updated" - }, - { - "version": "2026.06.23-system-10", - "date": "2026-06-23", - "summary": "quickPutaway 弃用说明完善:明确替代方案为 matchPutaway;matchPutaway 标明为目前唯一库存写入入库链路", - "methods": [ - "storage.inventory.quickPutaway", - "storage.inventory.matchPutaway" - ], - "notes": [ - "storage.inventory.quickPutaway 已从代码中移除,替代方案为 storage.inventory.matchPutaway(支持多收货单+多入库单批量匹配入库)。", - "storage.inventory.matchPutaway 是目前唯一的库存写入入库链路,入库单状态变更由 storage.entry.completeEntry 单独处理。", - "本次为文档补充说明,不涉及代码变更。" - ], - "type": "updated" - }, - { - "version": "2026.06.23-system-11", - "date": "2026-06-23", - "summary": "删除 storage.receiving.getAvailableInboundQuantity:该方法依赖已弃用的 wms_entry_receiving_binding 明细绑定表,已从代码中移除", - "methods": [ - "storage.receiving.getAvailableInboundQuantity" - ], - "notes": [ - "该方法原用于按 stock_id 查询已审核收货单中各明细的可入库数量(actual_quantity - stored_quantity - pending_allocated_quantity)。", - "由于 wms_entry_receiving_binding 明细绑定表已弃用,入库单与收货单的关联改为通过 wms_entry_order_receiving 主表级关联,该查询方法不再适用。", - "替代方案:使用 storage.entry.get 查询入库单详情,通过顶层 receivingBindings 获取关联的收货单信息。" - ], - "type": "removed" - }, - { - "version": "2026.06.23-system-12", - "date": "2026-06-23", - "summary": "storage.entry.get 响应结构变更:不再返回 items[].bindings(明细级绑定),改为返回顶层 receivingBindings(主表级关联收货单信息)", - "methods": [ - "storage.entry.get" - ], - "notes": [ - "移除 items[].bindings(明细级绑定,原基于 wms_entry_receiving_binding 表),该绑定表已弃用。", - "新增顶层 receivingBindings(wms_entry_order_receiving 主表级关联),每项含 id/receiving_id/receiving(含 id/receiving_number/status/storage_status/created_at)。", - "items 中保留 external_item_code/external_item_id/warehouse_item_code/warehouse_item_name/warehouse_item_spec 等扁平化字段。", - "响应结构变更与 storage.directInbound.getItems 的返回结构对齐,后者同样使用顶层 receivingBindings。" - ], - "type": "modified" - }, - { - "version": "2026.06.23-system-13", - "date": "2026-06-23", - "summary": "新增 storage.entry.* 下 4 个 DirectInbound 方法:getDirectInboundItems、addItem、commit、removeItem,原 storage.directInbound.* 方法保留向后兼容并标记 deprecated", - "methods": [ - "storage.entry.getDirectInboundItems", - "storage.entry.addItem", - "storage.entry.commit", - "storage.entry.removeItem" - ], - "notes": [ - "storage.entry.getDirectInboundItems:获取入库单的导入/PDA 入库信息,参数与响应格式同原 storage.directInbound.getItems", - "storage.entry.addItem:按商品增量添加导入/PDA 入库记录(支持单条和批量),参数与响应格式同原 storage.directInbound.addItem", - "storage.entry.commit:提交确认完成导入/PDA 入库,按实收数量写入库存并异步回传奇门/API,参数与响应格式同原 storage.directInbound.commit", - "storage.entry.removeItem:移除一条导入/PDA 入库记录,参数与响应格式同原 storage.directInbound.removeItem", - "底层 inbound_direct_log.js 实现不变,仅入口从 storage.directInbound 模块迁入 storage.entry 模块" - ], - "type": "added" - }, - { - "version": "2026.06.23-system-14", - "date": "2026-06-23", - "summary": "storage.directInbound.* 下 4 个方法标记 deprecated,指向 storage.entry.* 下对应新方法", - "methods": [ - "storage.directInbound.getItems", - "storage.directInbound.addItem", - "storage.directInbound.commit", - "storage.directInbound.removeItem" - ], - "notes": [ - "storage.directInbound.getItems → 替代方法 storage.entry.getDirectInboundItems", - "storage.directInbound.addItem → 替代方法 storage.entry.addItem", - "storage.directInbound.commit → 替代方法 storage.entry.commit", - "storage.directInbound.removeItem → 替代方法 storage.entry.removeItem", - "旧方法保留向后兼容,参数与响应格式不变,仅入口模块变更" - ], - "type": "deprecated" - }, - { - "version": "2026.06.23-system-15", - "date": "2026-06-23", - "summary": "storage.inventory.matchPutaway 标记 deprecated,替代方案为 storage.entry.commit", - "methods": [ - "storage.inventory.matchPutaway" - ], - "notes": [ - "storage.inventory.matchPutaway 已弃用,请迁移至 storage.entry.commit", - "commit 提供导入/PDA 入库完成确认功能,按实收数量写入库存并异步回传" - ], - "type": "deprecated" - }, - { - "version": "2026.06.23-system-16", - "date": "2026-06-23", - "summary": "清理已弃用 method 条目:从 system.json 删除 storage.entry.bindReceivingDetails、storage.entry.unbindReceivingDetails、storage.inventory.matchPutaway 三个已从代码中移除的 method 文档条目", - "methods": [ - "storage.entry.bindReceivingDetails", - "storage.entry.unbindReceivingDetails", - "storage.inventory.matchPutaway" - ], - "notes": [ - "storage.entry.bindReceivingDetails:已从代码中删除,明细级绑定收货单功能下线。入库单与收货单关系改为 wms_entry_order_receiving 主表级关联。", - "storage.entry.unbindReceivingDetails:已从代码中删除,明细级解绑功能下线。", - "storage.inventory.matchPutaway:已从代码中删除,匹配入库功能下线。替代方案为 storage.entry.commit。", - "storage.inventory.quickPutaway:之前已标记 [已删除],本次确认条目保留(与 matchPutaway 同一 group,保留作为历史参考)。", - "storage.entry.create / addDetail / deleteDetail / detailChange:systems 层方法已删除,但从未在 system.json 中暴露为 API method,无需文档变更。" - ], - "type": "removed" - }, - { - "version": "2026.06.23-system-17", - "date": "2026-06-23", - "summary": "storage.entry.get 响应新增仓库库存、条码、入库进度字段", - "methods": [ - "storage.entry.get" - ], - "notes": [ - "items 每项新增 warehouse_quantity(仓库库存总量)、warehouse_locked_quantity(锁定数量)、warehouse_is_batch_mgmt(是否批次管理)、warehouse_is_shelf_life_mgmt(是否效期管理)、warehouse_image_url(商品图片URL)、warehouse_is_images(是否有图片)", - "items 每项新增 barcodes(条码列表,每项含 id/barcode/sku_property)", - "items 每项新增 direct_inbound_quantity(导入/PDA已入库数量)、remaining_quantity(剩余可入库数量)", - "同步更新 response 字段定义,将原有概要描述展开为逐字段说明", - "仅文档同步,不改业务代码" - ], - "type": "updated", - "module": "storage.entry" - }, - { - "version": "2026.06.24-system-01", - "date": "2026-06-24", - "summary": "新增批量绑定入库单明细与收货单明细接口 storage.entry.bindReceivingDetails,支持明细级数量分配与部分成功", - "methods": [ - "storage.entry.bindReceivingDetails" - ], - "notes": [ - "新增 storage.entry.bindReceivingDetails:批量绑定入库单明细与收货单明细,支持明细级数量分配与部分成功", - "storage.entry.get 追加 available_receiving_details 字段加载可匹配的收货单明细" - ], - "type": "addition" - }, - { - "version": "2026.06.24-system-02", - "date": "2026-06-24", - "summary": "storage.entry.bindReceivingDetails:response.failed 字段从简单 reason 描述升级为结构化错误返回(含 error_code、message、detail);同步更新 400 错误说明", - "methods": [ - "storage.entry.bindReceivingDetails" - ], - "notes": [ - "response.failed 新增 items 定义,每项含 entry_item_id、receiving_detail_id、allocated_quantity、error_code、message、detail", - "error_code 枚举:ENTRY_ITEM_NOT_FOUND、STOCK_NOT_FOUND、RECEIVING_DETAIL_MISMATCH、RECEIVING_DETAIL_NOT_FOUND、INSUFFICIENT_AVAILABLE_QUANTITY、ENTRY_ORDER_STATUS_INVALID", - "400 错误说明更新:入库单状态不允许绑定时,所有 bindings 均返回 failed 且 error_code 为 ENTRY_ORDER_STATUS_INVALID" - ], - "type": "updated" - }, - { - "version": "2026.06.24-system-03", - "date": "2026-06-24", - "summary": "新增 storage.entry.quickInbound 快捷直入/虚拟入库接口", - "methods": [ - "storage.entry.quickInbound" - ], - "notes": [ - "新增 quickInbound 方法:入库单所有商品按明细数量一键直入虚拟库位(space_id=2),跳过收货/质检流程", - "支持状态:CREATED、PENDING 状态的入库单可执行", - "拒绝状态:CANCELLED(已作废)、COMPLETED(已完成)", - "事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、变更入库单状态为 COMPLETED", - "事务外异步回传奇门/API" - ], - "type": "addition" - }, - { - "version": "2026.06.24-system-04", - "date": "2026-06-24", - "summary": "收窄 storage.entry.quickInbound 状态约束:仅允许 CREATED 状态执行快捷直入", - "methods": [ - "storage.entry.quickInbound" - ], - "notes": [ - "收窄状态约束:仅允许 CREATED 状态执行快捷直入,PENDING 状态不再允许" - ], - "type": "updated" - }, - { - "version": "2026.06.24-system-05", - "date": "2026-06-24", - "summary": "修正 storage.entry.quickInbound errors[4] message 以匹配代码实现:改为动态状态描述", - "methods": [ - "storage.entry.quickInbound" - ], - "notes": [ - "errors[4].message 从「入库单状态不允许快捷直入(仅支持CREATED状态)」改为「入库单状态不允许快捷直入,当前状态:非CREATED(如PENDING等)」,反映代码中 `${entryOrder.order_status}` 动态模板特性" - ], - "type": "updated" - }, - { - "version": "2026.06.24-system-06", - "date": "2026-06-24", - "summary": "新增入库单与收货单商品对照预览接口", - "methods": [ - "storage.entry.receivingCompare" - ], - "notes": [ - "新增 storage.entry.receivingCompare 方法:给定入库单ID和收货单ID,返回入库商品与收货商品的逐行对照视图。", - "comparison 列表中每项含 match_status(matched/entry_only),以及入库侧和收货侧的商品与数量信息。", - "receiving_only 列表包含仅存在于收货单中的商品明细。", - "summary 提供 total_entry_items、matched_items、entry_only_items、receiving_only_items 汇总统计。", - "纯只读接口,不产生任何数据写入或状态变更。" - ], - "type": "addition" - }, - { - "version": "2026.06.24-system-07", - "date": "2026-06-24", - "summary": "setting.warehouse 模块新增 7 个发件人信息字段到 subject_config", - "methods": [ - "setting.warehouse.getSettings", - "setting.warehouse.saveSettings" - ], - "notes": [ - "在 getSettings 的 response 中新增 subject_config.sender_name(发件人姓名)、sender_tel(发件人电话)、province_name(省份)、city_name(城市)、district_name(区/县)、town_name(镇/街道)、address(详细地址)共 7 个字段,均为可选字符串,默认空。", - "在 saveSettings 的 params 中新增对应的 7 个入参字段,source 为 body.subject_config,均为可选字符串,默认空,并标注 maxLength。", - "字段 key 与 store_warehouse.policy_config 中发件人字段命名完全一致,统一仓库级发件人默认值配置。", - "getFieldMeta 接口无需修改文档——其返回的字段元信息由 WAREHOUSE_SETTING_FIELDS 定义在运行时自动生成,新增字段会随代码自动纳入返回列表。" - ], - "type": "updated", - "module": "setting.warehouse" - }, - { - "version": "2026.06.25-system-01", - "date": "2026-06-25", - "summary": "新增 storage.entry.bindReceiving 接口:将收货单绑定到入库单(主表级关联,不做明细数量分配)", - "methods": [ - "storage.entry.bindReceiving" - ], - "notes": [ - "新增入库单与收货单的主表绑定接口,与已有的 storage.entry.bindReceivingDetails(明细级绑定)区分:bindReceiving 仅建立 wms_entry_order_receiving 主表关联,不做明细数量分配。", - "入库单需为 CREATED 或 PENDING 状态;收货单需存在、同仓库且未取消。", - "支持部分成功模式:逐条校验收货单,校验通过的建立绑定,不通过的返回 error_code 和 message。", - "响应包含 success(成功列表)、failed(失败列表)、success_count、failed_count。" - ], - "type": "addition" - }, - { - "version": "2026.06.25-system-02", - "date": "2026-06-25", - "summary": "storage.entry.bindReceiving:新增 OWNER_MISMATCH 错误码,用于收货单与入库单货主不一致校验", - "methods": [ - "storage.entry.bindReceiving" - ], - "notes": [ - "在 storage.entry.bindReceiving 的 errors 数组中新增 OWNER_MISMATCH(收货单与入库单货主不一致)错误码。", - "同步更新 response.failed.error_code 的枚举描述,补充 OWNER_MISMATCH。" - ], - "type": "updated", - "module": "storage.entry" - }, - { - "version": "2026.06.25-system-03", - "date": "2026-06-25", - "summary": "storage.entry.bindReceiving:新增收货单未审核错误码 RECEIVING_NOT_REVIEWED", - "methods": [ - "storage.entry.bindReceiving" - ], - "notes": [ - "在 errors 数组中新增错误码 RECEIVING_NOT_REVIEWED(收货单未审核),用于标识绑定前收货单尚未完成审核的场景。", - "同步更新 response.failed.items.properties.error_code.description,在可能值列表中补充 RECEIVING_NOT_REVIEWED。" - ], - "type": "updated" - }, - { - "version": "2026.06.25-system-04", - "date": "2026-06-25", - "summary": "storage.entry.list 响应新增 receivingBindings 和 hasReceiving 字段,where 新增 hasReceiving 虚拟筛选条件", - "methods": [ - "storage.entry.list" - ], - "notes": [ - "响应 list 数组每项新增 receivingBindings(收货单绑定列表,主表级关联)和 hasReceiving(是否存在收货单绑定,boolean)字段。", - "入参 where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单,内部通过 wms_entry_order_receiving 表查询实现。", - "同步更新 description 以说明 hasReceiving 虚拟筛选的使用方式。" - ], - "type": "updated" - }, - { - "version": "2026.06.26-system-01", - "date": "2026-06-26", - "summary": "storage.entry.receivingCompare 支持多收货单对照预览", - "methods": [ - "storage.entry.receivingCompare" - ], - "notes": [ - "支持多个收货单ID对照预览(新增 receiving_ids 数组入参,优先于 receiving_id 使用)", - "入参 receiving_id 从 required 改为 optional,与 receiving_ids 二选一", - "出参结构调整为 comparisons[] 数组(多收货单),新增 errors[] 和 total_summary", - "向后兼容原 receiving_id 单值传参(底层自动转为单元素数组)", - "新增 400 错误码:receiving_ids 或 receiving_id 必填", - "移除 404 错误码:收货单不存在(已改为在 comparisons[]/errors[] 中以 status=error 形式返回)" - ], - "type": "enhancement" - }, - { - "version": "2026.06.26-system-02", - "date": "2026-06-26", - "summary": "storage.receiving.getReceivingList 新增 filterDepleted 可选参数;storage.entry.receivingCompare 返回值 receiving_only 字段新增 receiving_allocated 和 receiving_available 说明", - "methods": [ - "storage.receiving.getReceivingList", - "storage.entry.receivingCompare" - ], - "notes": [ - "storage.receiving.getReceivingList:params 新增 filterDepleted(boolean, 默认 false),用于过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满)。", - "storage.entry.receivingCompare:response 中 receiving_only 字段的 description 补充 receiving_allocated(已分配数量)和 receiving_available(可再用量)两个子字段说明。" - ], - "type": "updated" - }, - { - "version": "2026.06.26-system-03", - "date": "2026-06-26", - "summary": "storage.receiving.getReceivingList:新增可选参数 entry_order_id,按入库单商品交集过滤收货单列表", - "methods": [ - "storage.receiving.getReceivingList" - ], - "notes": [ - "新增可选参数 entry_order_id(number),传入入库单 ID 后只返回至少有一条明细的 system_product_id 在入库单明细中存在的收货单。", - "与现有 filterDepleted 参数可组合使用,二者取交集。", - "不传则不过滤,保持原有行为不变。" - ], - "type": "updated" - }, - { - "version": "2026.06.27-system-01", - "date": "2026-06-27", - "summary": "新增 storage.entry.reviewEntry 接口:审核入库单(CREATED→PENDING),需绑定收货单", - "methods": [ - "storage.entry.reviewEntry" - ], - "notes": [ - "新增入库单审核接口,支持 CREATED→PENDING 状态流转。", - "审核前置条件:入库单必须已绑定收货单(EntryOrderReceiving 存在关联记录)。", - "审核通过后写入操作日志(ENTRY_ORDER_REVIEW)。" - ], - "type": "added" - }, - { - "version": "2026.06.29-system-01", - "date": "2026-06-29", - "summary": "storage.inventory.quickPutaway 重新实现:收货单快捷转入库单", - "methods": [ - "storage.inventory.quickPutaway" - ], - "notes": [ - "此前已从代码中删除(2026.06.23-system-08),现由 wms-dev-agent 重新实现。", - "核心流程:参数校验 → 加载收货单及明细 → 检查货主配置 policy_config.allow_receiving_quick_putaway → 按 stock_id(system_product_id)分组合并数量 → 创建入库单 SCRK(自动审批到 PENDING)→ 写入 wms_entry_order_receiving 主表级绑定 → 更新收货单 storage_status 为 partial → 更新收货单明细 storage_status/stored_quantity → 提交事务。", - "前置条件:收货单状态为 completed 且 is_review=true(已审核),货主仓库签约配置 allow_receiving_quick_putaway=1。", - "与旧实现的区别:不涉及 wms_entry_receiving_binding 明细级绑定,使用 wms_entry_order_receiving 主表级关联;直接创建入库单并写入绑定,不再走 matchPutaway 匹配链路。", - "返回:entry_order_id、entry_order_code(SCRK 格式)、order_status(PENDING)、receiving_id、total_lines、total_quantity。" - ], - "type": "addition" - }, - { - "version": "2026.06.29-system-02", - "date": "2026-06-29", - "summary": "storage.entry.list:quickWhere 搜索范围扩展,新增收货单 ID(receiving_id)支持 PDA 扫描托盘唛头搜索绑定的入库单", - "methods": [ - "storage.entry.list" - ], - "notes": [ - "quickWhere 搜索字段新增 receiving_id(收货单 ID / 托盘唛头),通过 wms_entry_order_receiving 绑定表关联搜索。", - "同步更新 description 和 where 参数的 description,明确 quickWhere 完整搜索字段列表:entry_order_code、purchase_order_code、supplier_name、store_name、warehouse_name、receiving_id。" - ], - "type": "updated", - "module": "storage" - }, - { - "version": "2026.06.29-system-03", - "date": "2026-06-29", - "summary": "新增 storage.receiving.scanDetail 接口:PDA 上架扫码定位收货明细", - "methods": [ - "storage.receiving.scanDetail" - ], - "notes": [ - "新增 storage.receiving.scanDetail(PDA专用):通过 entry_order_id + barcode 扫码快速定位收货明细。", - "搜索逻辑:纯数字 barcode 优先按明细 ID 精确匹配(托盘唛头),未命中则模糊匹配商品条码;非纯数字仅模糊匹配商品条码。", - "入参:entry_order_id(必填 number)、barcode(必填 string)。", - "出参:detail_id、receiving_id、barcode、product_name、actual_quantity、receiving_status。", - "错误码:入库单不存在或无权访问、该入库单尚未关联收货单、未找到匹配的收货明细。" - ], - "type": "added" - }, - { - "version": "2026.06.29-system-04", - "date": "2026-06-29", - "summary": "storage.receiving.scanDetail 响应结构从单条改为列表:返回 { list, total } 支持同一条码匹配多条明细", - "methods": [ - "storage.receiving.scanDetail" - ], - "notes": [ - "响应结构变更:原返回 data.detail_id/data.receiving_id 等单条字段,现改为顶层 list 数组 + total 计数。", - "同一条码可能匹配到多条收货明细(不同收货单的同一商品),以列表形式返回所有匹配结果。", - "list 中每条明细包含 detail_id/receiving_id/barcode/product_name/actual_quantity/receiving_status。", - "补充错误码:用户未绑定仓库、入库单ID/条码为空、未找到可用的收货明细、500服务器错误。", - "PDA专用接口,description 更新说明匹配逻辑。" - ], - "type": "updated", - "module": "storage.receiving" - }, - { - "version": "2026.06.30-system-01", - "date": "2026-06-30", - "summary": "新增 storage.entry.containerList:PDA 上架时拉取入库单绑定收货单中指定商品的可用容器列表", - "methods": [ - "storage.entry.containerList" - ], - "notes": [ - "新增接口 storage.entry.containerList,用于 PDA 上架场景拉取入库单已绑定收货单中指定 stock_id 的可用收货明细(容器)列表。", - "入参:entry_order_id(入库单ID,必填)、stock_id(商品 stock_id,必填)。", - "出参:data.list 返回可用明细列表,每项含 detail_id、receiving_id、barcode、product_name、actual_quantity、receiving_status;data.total 为总数。", - "已绑定占用的收货明细(wms_entry_receiving_binding 中已有记录且未软删除)会被排除。", - "PDA 专用接口,无需额外鉴权(isNeedAuth=false)。" - ], - "type": "added" - }, - { - "version": "2026.06.30-system-02", - "date": "2026-06-30", - "summary": "storage.entry.addItem 入参变更:entry_order_code → entry_order_id(number);quantity 改为可选(传入 receiving_detail_id 时自动计算);新增 receiving_detail_id/allocated_quantity 参数支持 PDA 上架收货明细绑定模式;space_id 绑定模式下必填", - "methods": [ - "storage.entry.addItem" - ], - "notes": [ - "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.addItem 实现对齐", - "quantity 改为可选:传入 receiving_detail_id 时自动从收货明细计算可用数量(actual_quantity - 已绑定数量)", - "新增 receiving_detail_id 参数:PDA 上架绑定收货明细时传入,触发预占绑定(wms_entry_receiving_binding status=pending)", - "新增 allocated_quantity 参数:预分配数量,默认等于 quantity", - "space_id 在绑定模式下必填;非绑定模式可选(commit 时兜底为 1)", - "PENDING 状态入库单必须传 receiving_detail_id 且已绑定收货单方可操作", - "CREATED + 已绑定收货单的入库单需先审核(reviewEntry)后才能上架", - "批量模式 items 数组同步支持 receiving_detail_id/allocated_quantity 字段", - "补充完整错误码列表:超量、可用数量不足、状态校验等" - ], - "type": "updated" - }, - { - "version": "2026.06.30-system-03", - "date": "2026-06-30", - "summary": "storage.entry.commit 入参变更:entry_order_code → entry_order_id(number),与底层 inboundDirectLog.commit 实现对齐", - "methods": [ - "storage.entry.commit" - ], - "notes": [ - "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.commit(entryOrderId) 实现对齐", - "补充 description 说明先同步后写库两段式流程:① 奇门/API 回传 → ② onSuccess 内事务写库存", - "补充 commit 后 EntryReceivingBinding 状态从 pending 更新为 committed 的说明" - ], - "type": "updated" - }, - { - "version": "2026.06.30-system-04", - "date": "2026-06-30", - "summary": "storage.directInbound.commit 入参变更:entry_order_code → entry_order_id(number),与底层 inboundDirectLog.commit 实现对齐", - "methods": [ - "storage.directInbound.commit" - ], - "notes": [ - "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.commit(entryOrderId) 实现对齐", - "该方法已标记 deprecated,推荐使用 storage.entry.commit" - ], - "type": "updated" - }, - { - "version": "2026.06.30-system-05", - "date": "2026-06-30", - "summary": "storage.entry.getDirectInboundItems 响应结构重构:entryOrder 精简字段,items[].count→planned、direct_inbound_quantity→completed,items[].bindings 新增,移除 direct_logs/summary 等冗余字段", - "methods": [ - "storage.entry.getDirectInboundItems" - ], - "notes": [ - "entryOrder 精简为 id / entry_order_code / order_status / store_remask 四个字段", - "items[].count → planned(计划数量),items[].direct_inbound_quantity → completed(已完成数量)", - "items[].bindings 新增,结构为 { detail_id, binding_id, allocated_quantity, space_id, space_name }", - "items[].stock 新增,返回 getStockDetails 缓存的商品详情(item_code、item_name、barcodes 等)", - "移除 direct_logs(现有响应中已不存在该顶层字段)", - "移除 summary(现有响应中已不存在该字段)", - "移除 items[].received_quantity、items[].remaining_quantity、items[].pending_binding_total 等旧字段", - "新增 receivingBindings 字段说明:入库单层级收货单绑定关系" - ], - "type": "updated" - }, - { - "version": "2026.06.30-system-06", - "date": "2026-06-30", - "summary": "storage.directInbound.getItems 响应结构重构:entryOrder 精简字段,items[].count→planned、direct_inbound_quantity→completed,items[].bindings 新增,移除 direct_logs/summary 等冗余字段", - "methods": [ - "storage.directInbound.getItems" - ], - "notes": [ - "响应结构与 storage.entry.getDirectInboundItems 对齐(两者共用同一个底层实现 inboundDirectLog.getItems)", - "entryOrder 精简为 id / entry_order_code / order_status / store_remask", - "items[].count → planned,items[].direct_inbound_quantity → completed", - "items[].bindings 新增 { detail_id, binding_id, allocated_quantity, space_id, space_name }", - "items[].stock 新增", - "移除 direct_logs、summary、items[].received_quantity、items[].remaining_quantity 等旧字段", - "新增 receivingBindings 字段" - ], - "type": "updated" - }, - { - "version": "2026.06.30-system-07", - "date": "2026-06-30", - "summary": "storage.entry.containerList 响应结构补充 stock 字段:返回商品详情(item_code、item_name、barcodes 等)", - "methods": [ - "storage.entry.containerList" - ], - "notes": [ - "响应 list[].stock 字段补充为必返回:通过 getStockDetails 批量获取商品详情缓存", - "stock 对象包含 item_code、item_name、sku_property、barcodes 等字段" - ], - "type": "updated" - }, - { - "version": "2026.06.30-system-08", - "date": "2026-06-30", - "summary": "storage.receiving.scanDetail 响应结构补充 stock 字段:返回商品详情(item_code、item_name、barcodes 等)", - "methods": [ - "storage.receiving.scanDetail" - ], - "notes": [ - "响应 list[].stock 字段补充为必返回:通过 getStockDetails 批量获取商品详情缓存", - "stock 对象包含 item_code、item_name、sku_property、barcodes 等字段", - "完善 error 列表:补充 未找到可用的收货明细、未找到匹配的收货明细、入库单ID不能为空、扫描条码不能为空 等错误" - ], - "type": "updated" - }, - { - "version": "2026.06.30-system-09", - "date": "2026-06-30", - "summary": "订单列表 list 响应新增 store_remark(货主备注)字段", - "methods": [ - "order.list", - "order.reviewOrder.list", - "order.pendingOrder.list", - "order.expectionOrder.list", - "order.entrustOrder.list", - "order.deliveryOrder.list", - "order.deliveryExpectionOrder.list", - "order.archiveOrder.list" - ], - "notes": [ - "数据库字段 store_remask,返回给前端的字段名为 store_remark。", - "服务层从 wms_store_warehouse.store_remask 按 store_id+warehouse_id 聚合批量填充。", - "货主备注值可能为空字符串(当货主未设置备注时)。", - "该字段对订单列表的所有 method 均适用(current/dispatch/outsourced/history 模型均返回)。" - ], - "type": "updated" - }, - { - "version": "2026.07.02-system-02", - "date": "2026-07-02", - "summary": "新增 quick.waybill.toOrder 接口:根据运单号快速查询订单ID", - "methods": [ - "quick.waybill.toOrder" - ], - "notes": [ - "新增 quick 模块组(快捷查询)", - "查询 wms_order_express 表中 status=1 的有效记录", - "无需登录和鉴权(免登录/免鉴权)" - ], - "type": "added" - }, - { - "version": "2026.07.02-system-01", - "date": "2026-07-02", - "summary": "修正 quick.waybill.toOrder 的 isNeedLogin 为 true,与代码实现保持一致", - "methods": [ - "quick.waybill.toOrder" - ], - "notes": [ - "文档中 isNeedLogin 为 false,但代码 systemMethods/quick/waybill.js 中 _noNeedLogin 为空字符串,未将 toOrder 加入免登录列表,实际需要登录验证,修正文档以与代码一致。" - ], - "type": "fixed" - }, - { - "version": "2026.07.03-system-01", - "date": "2026-07-03", - "summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog", - "methods": [ - "storage.entry.getDirectInboundItems" - ], - "notes": [ - "bindings 数组 description 中 wms_entry_receiving_binding 引用更新为 InboundDirectLog,明确旧表已弃用", - "binding_id description 中 wms_entry_receiving_binding.id 更新为 InboundDirectLog.id", - "allocated_quantity description 中补充来源 InboundDirectLog.quantity", - "wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at" - ], - "type": "updated" - }, - { - "version": "2026.07.03-system-02", - "date": "2026-07-03", - "summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog", - "methods": [ - "storage.directInbound.getItems" - ], - "notes": [ - "bindings 数组 description 中更新为来自 InboundDirectLog,明确旧表已弃用", - "binding_id description 更新为 InboundDirectLog.id", - "allocated_quantity description 中补充来源 InboundDirectLog.quantity", - "wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at" - ], - "type": "updated" - }, - { - "version": "2026.07.03-system-03", - "date": "2026-07-03", - "summary": "binding 表弃用文档同步:commit 描述中 EntryReceivingBinding 更新为 InboundDirectLog", - "methods": [ - "storage.entry.commit" - ], - "notes": [ - "commit description 中将 pending 状态的 EntryReceivingBinding 更新为 pending 状态的 InboundDirectLog,与代码实现一致" - ], - "type": "updated" - }, - { - "version": "2026-07-03-entry-get-params-fix", - "date": "2026-07-03", - "type": "updated", - "summary": "修正 storage.entry.get 文档:id 改为必填;移除未实现的 entry_order_code 参数;修正错误码与实际返回一致;补充 available_receiving_details 响应字段;修正 remaining_quantity 计算公式及 warehouse_image_url 实际行为", - "methods": [ - "storage.entry.get" - ], - "notes": [ - "params: 移除 entry_order_code(代码中从未使用该参数),id 从 required=false 改为 required=true", - "params: id 描述从'二选一'改为'必填'", - "errors: 400 的 message 从'参数错误:id 与 entry_order_code 至少提供一个'改为'id 参数不能为空'", - "errors: 移除不存在的 404 error,入库单不存在时实际返回 code=0, message='入库单不存在或无权访问'", - "errors: 删除不存在的 500 error", - "response: 新增 entryOrder.items[].available_receiving_details 字段及其描述", - "response: remaining_quantity 描述从 'count - received_quantity - direct_inbound_quantity' 修正为 'max(0, count - received_quantity)'", - "response: warehouse_image_url 描述从 StockWarehouse.image_url 改为'当前固定返回空字符串'", - "response: warehouse_is_images 类型从 number(0/1) 改为 string(Y/N),与 StockWarehouse.is_images 实际存储一致", - "response: warehouse_quantity/warehouse_locked_quantity/warehouse_is_batch_mgmt/warehouse_is_shelf_life_mgmt 补充无匹配时为 null 的说明", - "description: 更新描述以反映实际逻辑流程" - ] - }, - { - "version": "2026.07.03-system-04", - "date": "2026-07-03", - "type": "modified", - "summary": "order.pendingOrder.updateAddress 移除 remark(备注)修改功能,现在仅支持地址字段批量修改;备注修改已独立为 order.pendingOrder.updateRemark", - "methods": [ - "order.pendingOrder.updateAddress" - ], - "notes": [ - "移除入参 remark 参数定义项。", - "移除 remark 更新逻辑及相关描述,updateAddress 现在仅处理地址字段(name/mobile/tel/zip_code/province/city/area/town/detail_address)。", - "description 更新:去掉 remark 相关描述,仅描述地址字段修改规则。", - "response updated_count 描述更新:从「取地址更新行数与备注更新行数的最大值」改为单纯描述地址更新行数。", - "errors 更新:移除 remark 相关错误说明('remark 字段不受此限制' 等),修改 '至少需要提供一个地址字段或备注进行修改' 为 '至少需要提供一个地址字段进行修改'。", - "备注修改功能已独立为 order.pendingOrder.updateRemark 方法。" - ], - "module": "order.pendingOrder" - }, - { - "version": "2026-07-16", - "date": "2026-07-16", - "summary": "新增 workbench.bindCamera 接口,支持工作台绑定/解绑摄像头", - "methods": [ - "workbench.bindCamera" - ], - "notes": [ - "通过 device_ids JSON 字段存储绑定关系", - "传空数组可解绑" - ] - }, - { - "version": "2026.07.17-stock-report-migration-01", - "date": "2026-07-17", - "type": "updated", - "summary": "storage.report 模块迁移至 stock.report:修正语义错误,库存报表属于 stock 域而非 storage 域", - "methods": [ - "stock.report.search", - "stock.report.searchStore", - "stock.report.export", - "stock.report.exportStore", - "stock.report.exportTaskProgress" - ], - "notes": [ - "将 systemMethods/storage/report.js 移动到 systemMethods/stock/report.js", - "内部引用同步更新:类名 StorageReportMethodService→StockReportMethodService,缓存键 storage_report→stock_report,日志前缀 [storage.report]→[stock.report]", - "旧文件直接删除,不保留兼容(storage.report 为语义错误,调用方需同步更新 method 名)", - "更新 systems/storage/entry.js L273 注释引用", - "文档:methods/system.json module storage.report→stock.report,5个 method 名同步更新" - ] - }, - { - "version": "2026.07.17-stock-transaction-export-01", - "date": "2026-07-17", - "type": "added", - "summary": "新增 stock.transaction 商品流水导出(仓库侧+货主侧),异步任务模式,支持与列表查询一致的条件筛选", - "methods": [ - "stock.transaction.export", - "stock.transaction.exportStore", - "stock.transaction.exportTaskProgress" - ], - "notes": [ - "systems/stock_transaction.js 新增 exportList(),复用 queryList 的查询逻辑,不分页导出 Excel(上限 50000 条)", - "systemMethods/stock/transaction.js 新增 export/exportStore/exportTaskProgress,采用异步任务模式(setImmediate + 缓存)", - "仓库侧导出自动限定 warehouse_id=ctx.user.store_id,货主侧需传 store_id", - "导出 Excel 列:序号/创建时间/流水类型/仓库ID/货主ID/商品ID/变动数量/变更前库存/变更后库存/变更前锁定/变更后锁定/批次号/单据类型/单据号/收货单ID/入库单ID/发货单ID/操作人/备注" - ] - }, - { - "version": "2026.07.29-system-01", - "date": "2026-07-29", - "type": "added", - "summary": "新增 waybill.warehouse 运单模块(仓库侧):list(列表)、detail(详情)、export(导出)3 个接口,支持运单号独立查询与管理", - "methods": [ - "waybill.warehouse.list", - "waybill.warehouse.detail", - "waybill.warehouse.export" - ], - "notes": [ - "新增 waybill.warehouse.list:仓库侧运单列表查询,支持分页与多条件筛选(运单号/主单号/订单ID/订单号/物流公司/物流接口/平台/状态/退回/拦截/星河签收/包材/称重/关键词/时间范围),默认按 create_at desc 排序。", - "新增 waybill.warehouse.detail:仓库侧运单详情查询,含关联订单信息、兄弟运单(sibling_waybills)、物流信息、状态信息、称重信息、打包信息(打包状态/打包人/打包时间)、打印记录列表。", - "新增 waybill.warehouse.export:仓库侧运单导出,复用 list 筛选逻辑,异步任务模式,支持自定义导出字段。", - "仓库隔离策略:所有接口自动注入 warehouse_id = ctx.user.store_id(全系统统一约定),不可由前端入参覆盖。", - "快照字段方案:wms_order_express 表新增 delivery_order_code、store_id_snapshot、store_name_snapshot、warehouse_name_snapshot 四个快照列,列表查询无需 JOIN 订单表或货主表,仅单表查询 + SELF JOIN(主单号)。", - "主单号/子单号规则:同一 order_id 下 business_key=1 为主单号,business_key>1 为子单号,沿用系统已有约定。", - "命名空间规划:waybill.warehouse.* 本期实现(仓库侧),后续预留 waybill.store.*(货主侧)。", - "本模块一期仅提供只读查询,不涉及运单创建/修改/删除,不修改任何现有接口。" - ], - "module": "waybill.warehouse" - }, - { - "version": "2026.07.30-system-01", - "date": "2026-07-30", - "type": "changed", - "summary": "更新 waybill.warehouse group API 文档:list 新增 waybillType/storeId 筛选、移除 pack_status 响应字段;detail 精简 package 对象;export 响应改为纯异步任务模式(仅含 task_id/status/progress/message/update_time)", - "methods": [ - "waybill.warehouse.list", - "waybill.warehouse.detail", - "waybill.warehouse.export", - "waybill.warehouse.exportTaskProgress" - ], - "notes": [ - "waybill.warehouse.list:新增 where.waybillType 筛选(\"main\"/\"1\"=主单号,\"child\"/\"2\"=子单号),新增 where.storeId 货主ID等值筛选。where.orderNo 标注暂不可用(待快照字段就绪)。response 移除 pack_status 字段(两表无关联,不再返回),list 字段数从 28 减至 27。", - "waybill.warehouse.detail:package 对象移除 pack_status/pack_quantity/pack_at/packer_name 四个字段,仅保留 package_material_id 和 package_material_name。description 同步去掉\"打包状态\"相关描述。", - "waybill.warehouse.export:响应简化为纯异步任务模式,data 仅含 task_id/status/progress/message/update_time,不含 total_count/current_count/result/error/download_url 等执行期字段(这些信息由 exportTaskProgress 接口返回)。export 的 where 参数同步新增 waybillType 和 storeId。", - "waybill.warehouse.exportTaskProgress:无变更,保持不变。" - ], - "module": "waybill.warehouse" - } + { + "version": "2026.08.01-system-01", + "date": "2026-08-01", + "type": "added", + "summary": "新增 apiApp 仓库 API 应用管理模块,支持当前仓库维度的 API 应用 CRUD、AppKey/Secret 自动生成与重新生成、IP 白名单、回调地址、限流等配置", + "methods": [ + "apiApp.list", + "apiApp.detail", + "apiApp.create", + "apiApp.update", + "apiApp.delete", + "apiApp.regenerateSecret" + ], + "notes": [ + "apiApp.list:分页查询当前仓库 API 应用列表,支持按 app_name(模糊)、is_enabled 筛选,Secret 自动脱敏(前8位+****)。", + "apiApp.detail:按 ID 查询单个应用详情,需同时匹配 warehouse_id(自动注入 ctx.user.store_id),Secret 脱敏。", + "apiApp.create:创建应用时自动生成 AppKey(AK{yyyyMMddHHmmss}{random8hex})和 AppSecret(64位hex)。默认 interface_type_id 取 WH_CHANNEL。仅创建时返回完整 Secret。", + "apiApp.update:更新可编辑字段(app_name、self_ip_whitelist、callback_url、rate_limit、sign_method、is_enabled),不可变字段为 self_app_key 和 interface_type_id。", + "apiApp.delete:软删除(is_enabled=0),不物理删除。", + "apiApp.regenerateSecret:重新生成 64位hex AppSecret,旧 Secret 立即失效。仅此次返回完整 Secret。", + "仓库隔离:所有操作按 ctx.user.store_id → warehouse_id 自动过滤。", + "Secret 安全策略:list/detail/update 返回脱敏值,仅 create/regenerateSecret 返回完整 Secret。" + ], + "module": "apiApp" + }, + { + "version": "2026.07.31-system-02", + "date": "2026-07-31", + "type": "added", + "summary": "新增 storage.inventory.export 库存导出与 storage.inventory.exportTaskProgress 导出进度查询,入参复用 list 的 where/sort/group_by_batch 语义,支持两种导出模式(聚合汇总 / 逐条明细),库位信息一并导出", + "methods": [ + "storage.inventory.export", + "storage.inventory.exportTaskProgress" + ], + "notes": [ + "storage.inventory.export:异步提交导出任务,返回 task_id 与受理信息,后端异步生成 Excel 并上传。入参 where/sort/group_by_batch 与 storage.inventory.list 完全一致,无需额外学习成本。", + "group_by_batch=false(默认):按 stock_id + space_id(库位)聚合导出库存汇总,含商品编码/名称/规格/单位/货主/库位编码/名称/总库存/锁定/可用/批次数/最近入库时间。", + "group_by_batch=true:按 storage_id 逐条导出库存明细,含库存记录ID/商品信息/库位信息/批次号/库存类型/数量/生产日期/过期日期/入库时间/入库单号/供应商批次号。", + "新增 storage.inventory.exportTaskProgress:按 task_id/taskId 查询导出任务进度与状态(submitted/running/success/failed/not_found),status=success 时返回 download_url 供客户端下载。", + "导出文件目录:exports/storage/inventory/{warehouseId}/,缓存 TTL 1800 秒。" + ], + "module": "storage.inventory" + }, + { + "version": "2026.07.31-system-01", + "date": "2026-07-31", + "type": "added", + "summary": "新增按波次批量快捷复核接口 batchQuickRecheckByWave,支持批量波次 IDs 的前置条件检查(储位、快递、同步、拦截),自动完成拣货并标记复核,支持部分失败", + "methods": [ + "order.recheckOrder.batchQuickRecheckByWave" + ], + "notes": [ + "新增 order.recheckOrder.batchQuickRecheckByWave 方法,复用 batchQuickRecheck 的 _completePickForOrder / _markRecheckForOrder / _tryCompleteWaveInTransaction 等内部事务方法", + "入参 wave_ids 支持数组或逗号分隔字符串,兼容 waveIds(驼峰)、wave_id(单值)", + "按波次维度批量查询订单后逐波次、逐订单执行前置校验与复核,每个订单独立事务,部分失败不影响其他订单", + "响应包含 success/failed 列表及计数,failed 项含 order_id、wave_id、delivery_order_code、reason 说明;波次下无订单时仅返回 wave_id + reason" + ], + "module": "order.recheckOrder" + }, + { + "version": "2026.07.29-system-01", + "date": "2026-07-29", + "type": "added", + "summary": "补全 waybill.warehouse group API 文档参数定义:完善 list/detail/export 的 params 与 response,新增 exportTaskProgress 异步进度查询接口", + "methods": [ + "waybill.warehouse.list", + "waybill.warehouse.detail", + "waybill.warehouse.export", + "waybill.warehouse.exportTaskProgress" + ], + "notes": [ + "waybill.warehouse.list:params 含 pagination/where/sort 完整字段定义,where 支持 15 个筛选维度(运单号、主单号、订单ID、订单号、物流编码、物流接口ID、平台编码、状态、退回/拦截/星河签收、包材ID、已称重、关键词、创建时间范围),sort 白名单 create_at/weighing_weight/id。response 含 list(28 个字段)+ pagination。", + "waybill.warehouse.detail:修正 id 参数为可选(required: false),与 waybillCode 二选一,waybillCode 优先。response 含 id/waybill_code/main_waybill_code/waybill_type/business_key/sibling_waybills/order/logistics/status_info/weight/package/print_records/print_count 等完整详情。", + "waybill.warehouse.export:response 补充 progress/message/update_time 字段,完整覆盖异步任务返回信息。", + "新增 waybill.warehouse.exportTaskProgress:按 task_id/taskId 查询导出进度,response 含 task_id/status/progress/current_count/total_count/message/result/error/download_url/update_time。", + "所有接口 isNeedAuth: false, isNeedLogin: true,仓库隔离通过 ctx.user.store_id 自动注入。" + ], + "module": "waybill.warehouse" + }, + { + "version": "2026.07.28-system-01", + "date": "2026-07-28", + "type": "added", + "summary": "新增 order.pendingOrder.batchMarkPrinted:批量设置订单为已打印状态,将 print_status 更新为 'fin'", + "methods": [ + "order.pendingOrder.batchMarkPrinted" + ], + "notes": [ + "同步批量更新接口,传入订单ID数组,直接将符合条件的订单 print_status 设为 'fin'。", + "双表查询:先查 current 表(wms_order_delivery_{warehouseId}),未命中的 ID 再兜底查 dispatch 表(wms_order_delivery_{warehouseId}_dispatch)。", + "dispatch 表查询失败仅记录 warn 日志,不影响 current 表已更新的结果。", + "仅允许 step 在 [1,2,3] 且 status 不为 'cancel' 的订单操作,已打印(print_status='fin')的订单会被静默跳过。", + "仓库上下文强制从 ctx.user.store_id 获取,禁止传入外部仓库ID。", + "入参支持 order_ids / orderIds / ids 三种别名,优先级 order_ids > orderIds > ids。", + "返回 updated_count 表示实际更新条数(current + dispatch 合计),ids 原样回传请求的订单ID列表。", + "写入操作日志 operation_code: ORDER_BATCH_MARK_PRINTED。" + ], + "module": "order.pendingOrder" + }, + { + "version": "2026.07.27-system-03", + "date": "2026-07-27", + "type": "changed", + "summary": "storage.receiving 导出接口拆分:export 改为按仓库维度,新增 storeExport 按货主维度导出", + "methods": [ + "storage.receiving.export", + "storage.receiving.exportTaskProgress", + "storage.receiving.storeExport", + "storage.receiving.storeExportTaskProgress" + ], + "notes": [ + "export 改为仓库维度:过滤条件从 store_id(平台激活货主)改为 warehouse_id(ctx.user.store_id),与 getReceivingList 保持一致。", + "exportTaskProgress 同步更新为仓库维度进度查询,任务 ID 前缀 receiving_export_。", + "新增 storeExport:货主维度导出,通过平台激活上下文获取 store_id,过滤逻辑与 getStoreReceivingList 一致。", + "新增 storeExportTaskProgress:货主维度进度查询,复用 exportTaskProgress 的缓存逻辑,任务 ID 前缀 receiving_store_export_。", + "导出格式:双 Sheet Excel(Sheet1=收货单列表 21 列,Sheet2=收货单明细 17 列),通过 ExcelJS stream + uploadService 上传 COS。", + "仓库导出上传路径 exports/receiving/{warehouseId}/,货主导出上传路径 exports/receiving/store/{storeId}/。", + "修复 exportReceivingList 中 where 条件二次解析问题:增加 ctx.whereParsed 复用(与 getStoreReceivingList 一致),避免 prepareWhereContext 已解析后再重复 parseWhereConditions 导致边界条件丢失。", + "命名对齐 entry 侧:storeExport / storeExportTaskProgress 方法名、任务 ID 前缀、上传路径均与 storage.entry.storeExport 模式一致。" + ], + "module": "storage.receiving" + }, + { + "version": "2026.07.27-system-02", + "date": "2026-07-27", + "type": "added", + "summary": "新增 order.pendingOrder.allocateSubOrderNumber:待处理订单分配子单号(异步任务),business_key 从 2 开始递增,跳过已分配运单号;新增 allocateSubOrderNumberProgress 按 task_id/business_key 查询进度", + "methods": [ + "order.pendingOrder.allocateSubOrderNumber", + "order.pendingOrder.allocateSubOrderNumberProgress" + ], + "notes": [ + "新增 allocateSubOrderNumber:入参 order_id + sub_order_count,按 business_key 2..(2+count-1) 全量传入 createWaybillCodePipeline。", + "并发安全:全量传入 pipeline,由其内部事务 + UNIQUE(order_id,business_key,status,warehouse_id) 索引保证并发去重。", + "pipeline 内部 createWaybillCode 事务:status=1 已分配→跳过;status=0 占位中→复用;无记录→INSERT status=0 占位。", + "异步任务模式:请求立即返回 task_id(sub_ 前缀),后台 setImmediate 执行,进度通过 Redis 缓存追踪。", + "新增 allocateSubOrderNumberProgress:支持 task_id 查整体进度,business_key 可选参数过滤单个业务ID的详情。", + "进度状态 submitted→running→success/partial/failed,progress 对应 5/50/80/100。", + "result.details 数组记录每个 business_key 的 status(skipped/allocated/failed/pending)与 waybill_code。", + "buildSubOrderDetails 回查最终状态:status=1+waybill→allocated,status=0→failed,无记录→failed。" + ], + "module": "order.pendingOrder" + }, + { + "version": "2026.07.27-system-01", + "date": "2026-07-27", + "type": "added", + "summary": "新增 order.packing 打包任务模块:list/get 查询 + setEndTime 设置结束时间,含视频 CDN URL 拼接与状态回写", + "methods": [ + "order.packing.list", + "order.packing.get", + "order.packing.setEndTime", + "order.packing.forceRecord" + ], + "notes": [ + "新增 order.packing.list:按仓库维度查询打包任务列表,支持分页/筛选/排序,关联工作台、视频和运单信息。", + "新增 order.packing.get:按 id + warehouse_id 查询单条打包任务详情。", + "新增 order.packing.setEndTime:设置打包任务结束时间,入参 id + end_time;若任务状态不是已完成(2)则同步更新为已完成。", + "新增 order.packing.forceRecord:强制重新录制打包任务视频,入参 id;校验录制电脑在线后重置视频状态并推送打印服务。", + "前端默认值逻辑:若任务已有 end_time 则打开时默认为当前时间,否则默认为 start_time + 5分钟。", + "视频 URL 自动拼接 CDN 域名前缀:http://w{warehouseId}-c{recordingComputerId}.o.gztbyc.com{videoPath};录制电脑从 wms_print_computer 按 is_recording=true 获取。", + "视频响应新增 status 字段(created/recording/completed/failed),与数据库 ENUM 保持一致。", + "pack_task_video Model 的 status 字段从 TINYINT 改为 STRING(20) 以匹配 DB ENUM 迁移。", + "forceRecord 通过打印服务 /record/force 推送录制任务,传入 pack_task_id、warehouse_id、computer_id、camera_ids。" + ], + "module": "order.packing" + }, + { + "version": "2026.07.10-system-01", + "date": "2026-07-10", + "type": "added", + "summary": "新增 storage.report.searchStore 货主侧库存报表,以 store_id 为主维度查询库存流水", + "methods": [ + "storage.report.searchStore", + "storage.report.exportStore" + ], + "notes": [ + "新增 searchStore 方法:与 search 共享核心逻辑,通过 searchMode='store' 切换主维度从 warehouse_id → store_id。", + "新增 exportStore 方法:与 export 共享核心逻辑,支持货主侧导出 Excel(含汇总 + 变更记录两个 sheet)。", + "systems 层 search/export 方法新增 searchMode 参数(默认 'warehouse'),不影响现有 warehouse 侧行为。", + "货主侧使用 ctx.user.store_id 作为主维度 store_id,辅助维度支持 warehouse_ids 过滤特定仓库。", + "systemMethods 层 searchStore 从 where.warehouse_ids 取值传给 search 的 storeIds(承载 warehouse 过滤)。", + "输出新增 warehouse_id / warehouse_name 字段,货主侧可区分不同仓库的库存。search 方法也同步输出这两个字段(向后兼容)。", + "修复 getStockDetails 的 warehouseId 判断:从 != null 改为 !== undefined,使显式传 null 可跳过 warehouse 过滤。", + "修复 loadReportReferenceMaps 未传递 warehouseId 给 getStockDetails 的问题。" + ], + "module": "storage.report" + }, + { + "version": "2026.07.09-system-01", + "date": "2026-07-09", + "type": "updated", + "summary": "签约 sign 方法改造:统一当前主体→store_id,解除角色校验,仓库可签仓库", + "methods": [ + "storeWarehouse.store.sign", + "storeWarehouse.warehouse.sign" + ], + "notes": [ + "resolvePairIds:统一当前主体始终在 store_id(货主方/消费方),对方在 warehouse_id(仓库方/提供方)。不再根据 isWarehouse 分支。", + "getCounterparty:移除 expectedRole 角色校验(仓库不再只能签货主,可签仓库)。", + "findScopedRelation:改为 OR 查询 store_id/warehouse_id 两边,兼容新旧签约数据。", + "sign preview:counterparty.role 改为根据对方 project 真实返回(warehouse/store),不再硬编码反推。", + "签仓库:仓库发起签约时对方 ID 传 counterparty_id,系统自动将当前仓库放 store_id。" + ], + "module": "storeWarehouse" + }, + { + "version": "2026.07.08-system-01", + "date": "2026-07-08", + "type": "updated", + "summary": "storeWarehouse.store.list 与 storeWarehouse.warehouse.list 拆分实现,不再共用;仓库侧支持查询外部合作仓库", + "methods": [ + "storeWarehouse.store.list", + "storeWarehouse.warehouse.list" + ], + "notes": [ + "拆分:store.list 调用 listForStore,warehouse.list 调用 listForWarehouse,不再共用同一个 list 方法。", + "新规则:两个方法均按 store_id = 当前主体ID 过滤(主体在 store_id 为货主方/消费方,对方在 warehouse_id 为仓库方/提供方)。", + "warehouse.list 新增支持查询外部合作仓库:当对方主体的 project='warehouse' 时为仓库-仓库合作,counterparty_role='warehouse'。", + "响应新增 counterparty_role 字段(store/warehouse),标识对方主体的真实角色。", + "warehouse.list 响应 use_status 改为 store_use_status(仓库在 store_id 方时,己方启用状态应为 store_use_status)。", + "旧 list 方法保留标记为 @deprecated,保持向后兼容。", + "新增 buildListWhereByStoreId 统一按 store_id 维度构建查询条件。" + ], + "module": "storeWarehouse" + }, + { + "version": "2026.07.06-system-01", + "date": "2026-07-06", + "type": "updated", + "summary": "order.wave.batchList:响应新增 pick_assignment_status(拣货分配状态),按订单 pick_status 聚合判定", + "methods": [ + "order.wave.batchList" + ], + "notes": [ + "响应 list 每项新增字段 pick_assignment_status (string):拣货分配状态,按波次下订单的 pick_status 聚合判定。", + "取值语义与 resolveAssignmentStatus 一致,自定义标签:未拣货(全 none)、部分拣货(混合且无 error)、已拣货(全 fin)、拣货异常(含 error)。", + "SQL 子查询新增 pick_none_count / pick_fin_count / pick_error_count 聚合列。" + ], + "module": "order.wave" + }, + { + "version": "2026.07.05-system-01", + "date": "2026-07-05", + "type": "added", + "summary": "新增 pick.wavePickComplete:传入 wave_id 一键完成整个波次拣货,内部复用 query 去重与任务创建逻辑后自动调用 wavePickTaskComplete(mode=1)", + "methods": [ + "pick.wavePickComplete" + ], + "notes": [ + "新增方法:pick.wavePickComplete,入参 wave_id(number,必填)。", + "内部流程:按 wave_id 查波次 → 活动任务去重(同用户复用 / 他人409冲突)→ 完成任务去重 → 无任务则创建(source=2 后台抓取)→ 调用 pick.wavePickTaskComplete mode=1 全部确认。", + "创建任务 remark 格式:pick.wavePickComplete wave_id={waveId},用于与 pick.query 区分。", + "响应:task_id、status(completed / already_completed)、tip、confirmed_order_ids、is_completed、progress。", + "错误码:400(参数/波次无订单)、401(缺少操作人)、404(波次不存在)、409(他人活动任务冲突)、500(创建/完成失败)。" + ], + "module": "pick" + }, + { + "version": "2026.07.03-system-02", + "date": "2026-07-03", + "type": "added", + "summary": "新增 order.pendingOrder.updateRemark:批量修改待处理订单备注(remark),不受 post_status 限制", + "methods": [ + "order.pendingOrder.updateRemark" + ], + "notes": [ + "新增方法:order.pendingOrder.updateRemark,用于批量修改待处理订单的备注(remark)字段。", + "入参:ids(number[],必填,正整数数组,不能为空)、remark(string,必填,最大500字符)。", + "特性:不受 post_status 限制,可对所有状态的订单生效;纯批量不支持单ID。", + "更新成功后写入操作日志。", + "响应:updated_count(number,实际更新行数)、ids(number[],原样返回请求的ID数组)。", + "错误码:400(ids 不能为空 / ids 仅支持正整数数组 / remark 不能为空)。" + ], + "module": "order.pendingOrder" + }, + { + "version": "2026.07.03-system-01", + "date": "2026-07-03", + "type": "updated", + "summary": "将 quick.waybill.toOrder 迁移为 index.toOrder 并移入基础模块,新增 waves 返回字段", + "methods": [ + "quick.waybill.toOrder", + "index.toOrder" + ], + "notes": [ + "移除快捷操作(quick)模块分组,原 quick.waybill.toOrder 方法从 methods/system.json 删除。", + "在基础模块(index)新增 index.toOrder 方法:入参仍为 waybill_code,响应从单一 order_id 扩展为 order_id + waves 结构。", + "waves 为数组,每项含 wave_id(波次ID)、wave_no(波次号)、order_ids(波次下所有订单ID列表),无波次时为空数组。", + "查询路径:运单号 → wms_order_express(status=1)→ order_id + warehouse_id → 遍历 current/history/dispatch 表获取波次信息 → 再遍历多表获取同波次所有订单ID。" + ] + }, + { + "date": "2026-06-24", + "type": "addition", + "summary": "新增批量绑定入库单明细与收货单明细接口,支持明细级数量分配与部分成功", + "version": "2026-06-24-add-bind-receiving-details", + "methods": [ + "storage.entry.bindReceivingDetails" + ], + "notes": [] + }, + { + "date": "2026-06-24", + "type": "deprecation", + "summary": "废弃手动匹配入库单收货单接口,由 storage.entry.bindReceivingDetails 替代", + "version": "2026-06-24-deprecate-manual-match-entry-order", + "methods": [ + "storage.receiving.manualMatchEntryOrder" + ], + "notes": [] + }, + { + "version": "2026.06.16-system-03", + "date": "2026-06-16", + "summary": "order.wave.waveStrategyFallbackOrderList 响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", + "methods": [ + "order.wave.waveStrategyFallbackOrderList" + ], + "notes": [ + "响应 list 每项新增字段 items_weight (number|null):订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null。", + "响应 list 每项新增字段 weight_type (string):重量类型中文标签,来自 wms_order.weight_type 经 formatWeightTypeLabel 转换;取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。" + ], + "type": "updated", + "module": "order.wave" + }, + { + "version": "2026.06.16-system-04", + "date": "2026-06-16", + "summary": "order.wave.singleOrderFetchList 响应新增 items_weight(总重量g)字段", + "methods": [ + "order.wave.singleOrderFetchList" + ], + "notes": [ + "响应 list 每项新增字段 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", + "为 null 时返回 null。" + ], + "type": "updated", + "module": "order.wave" + }, + { + "version": "2026.05.20-system-03", + "date": "2026-05-20", + "summary": "新增 storeWarehouse.store.queryPrintQuantityLogs:按 store_id 分页查询面单余额变更日志", + "methods": [ + "storeWarehouse.store.queryPrintQuantityLogs" + ], + "notes": [ + "新增方法:storeWarehouse.store.queryPrintQuantityLogs,用于按货主(store_id)分页查询面单余额变更日志。", + "入参:store_id(必填)、page(可选)、page_size / pageSize(可选,兼容别名)。", + "仅同步 methods/system.json 与本变更记录,不修改业务代码或测试。", + "返回:使用默认分页格式,响应在 `data` 下包含 `list`(变更日志数组)和 `pagination` 对象,`pagination` 字段:`page`、`pageSize`、`total`、`totalPages`、`hasPrevious`、`hasNext`。" + ], + "type": "added", + "module": "storeWarehouse" + }, + { + "version": "2026.05.13-system-01", + "date": "2026-05-13", + "summary": "完善 print.send 的 API 文档与返回说明", + "methods": [ + "print.send" + ], + "notes": [ + "补充请求参数说明:computerId、printer、template、data、type 标为必填,count、timestamp 保持可选。", + "补充 template 的子字段说明:page_width、page_height、template_content。", + "补充响应结构:flag、code、message、printId;其中成功时 code=200。", + "补充错误码说明:1001 对应不支持的打印类型,504 对应打印任务发送失败(包含打印机不存在、脱机、通讯失败等场景)。" + ], + "type": "updated" + }, + { + "version": "2026.05.08-system-06", + "date": "2026-05-08", + "summary": "新增取消拣货任务接口:order.wave.wavePickTaskCancel", + "methods": [ + "order.wave.wavePickTaskCancel" + ], + "notes": [ + "接口功能:取消拣货任务,同时释放关联波次(物理删除波次记录,订单回池)、解绑拣货车、写操作日志。", + "限制:仅允许在任务状态为 0(待开始)、1(拣货中)、2(待复核)时取消;状态为 3(已完成)或 9(已取消)时禁止取消,返回 400。", + "事务内操作:将任务状态更新为 9(已取消)、删除关联波次、清空订单 wave_id(回池)、解绑拣货车、写入 action_log 与 order_pick_trace;若有任一步骤失败则回滚并返回 500。" + ], + "type": "added" + }, + { + "version": "2026.07.01-system-01", + "date": "2026-07-01", + "summary": "storage.directInbound.addItem 参数名修正:entry_order_code → entry_order_id,类型 string → number", + "methods": [ + "storage.directInbound.addItem" + ], + "notes": [ + "文档 params 中 entry_order_code(string)改为 entry_order_id(number),与代码 app/service/systems/inbound_direct_log.js 第 544 行实际校验保持一致", + "同步修正 app/service/systemMethods/storage/direct_inbound.js JSDoc:@param {string} data.entry_order_code → @param {number} data.entry_order_id" + ], + "type": "fixed", + "module": "storage.directInbound" + }, + { + "version": "2026.07.01-system-02", + "date": "2026-07-01", + "summary": "新增 storage.entry.queryEntryLogs 接口文档定义", + "methods": [ + "storage.entry.queryEntryLogs" + ], + "notes": [ + "代码 method 层(systemMethods/storage/entry.js L284)和 systems 层(systems/operation_log.js L318)均已实现,补充文档定义", + "参数:id(number, required)、page(number, optional, 默认1)、pageSize(number, optional, 默认20)" + ], + "type": "added", + "module": "storage.entry" + }, + { + "version": "2026.06.18-system-01", + "date": "2026-06-18", + "summary": "order.pendingOrder.downloadCreateTemplate:模板列顺序调整,店铺名称(shop_nick)从末尾移至第2列B列,紧接*订单号之后", + "methods": [ + "order.pendingOrder.downloadCreateTemplate" + ], + "notes": [ + "调整 Excel 导入模板列顺序:店铺名称(shop_nick)从原第25列(Y列/末尾)移动至第2列(B列),紧跟在*订单号(delivery_order_code)之后。", + "同步更新 description 中的列顺序描述,明确 25 列(A-Y)的完整排列。", + "响应结构中移除冗余的 shop_nick 字段(模板列不属于 API 响应字段)。" + ], + "type": "updated", + "module": "order.pendingOrder" + }, + { + "version": "2026.05.17-system-09", + "date": "2026-05-17", + "summary": "为 storage.receiving.deleteDetail 文档补充约束:收货单已完成/已取消时禁止删除明细", + "methods": [ + "storage.receiving.deleteDetail" + ], + "notes": [ + "在 storage.receiving.deleteDetail 的 description 中补充:若关联收货单状态为 completed(已完成)或 cancelled(已取消),接口会返回删除失败(400),不允许删除明细。", + "在 errors 中补充或合并 400 描述以明确禁止删除已完成/已取消的收货单明细。" + ], + "type": "updated", + "module": "storage" + }, + { + "version": "2026.05.17-system-08", + "date": "2026-05-17", + "summary": "完善 storage.receiving.deleteDetail 文档:补充入参/返回/错误说明,明确用户上下文来源及删除约束", + "methods": [ + "storage.receiving.deleteDetail" + ], + "notes": [ + "补充 storage.receiving.deleteDetail 的参数说明:detail_id(来自请求体,必填);说明 creator_id 与 warehouse_id 来源于当前登录用户(ctx.user.employees_id / ctx.user.store_id)。", + "补充返回结构:成功时返回 code/message/data,data 包含 details(删除后剩余明细)和 selectId(建议选中ID);product_snapshot 若存在将被解析为对象或 null。", + "补充常见错误码:404(明细不存在或无权访问),400(收货单状态/已入库/删除失败),500(服务器异常)。", + "仅文档更新,不修改任何业务实现。" + ], + "type": "updated", + "module": "storage" + }, + { + "version": "2026.05.17-system-05", + "date": "2026-05-17", + "summary": "移除 storage.receiving.addItem(方法已下线/实现不存在)", + "methods": [ + "storage.receiving.addItem" + ], + "notes": [ + "仅同步文档:从 methods/system.json 中移除 storage.receiving.addItem,未修改任何业务代码或实现。", + "该方法已下线或实现不存在;请以当前 methods/system.json 的 SSOT 为准。" + ], + "type": "removed" + }, + { + "version": "2026.05.17-system-04", + "date": "2026-05-17", + "summary": "新增 stock.warehouse.import:仓库商品批量 JSON 导入(数组导入),SKU 为空创建/非空更新,支持 goods_code/货物编码 导入,更新写操作日志", + "methods": [ + "stock.warehouse.import" + ], + "notes": [ + "支持直接传入商品数组 JSON(主方式为数组,兼容 rows/items/list/data 包装)。", + "每项仅需传商品相关字段;SKU 为空时创建新商品,SKU 非空时为更新操作。", + "更新操作会写入操作日志以便审计。", + "支持导入 goods_code(货物编码)字段别名。", + "仅同步文档,不修改业务代码或实现。" + ], + "type": "added" + }, + { + "version": "2026.05.17-system-03", + "date": "2026-05-17", + "summary": "完善 stock.warehouse.handleBatchChange 文档:补充入参/出参/错误示例", + "methods": [ + "stock.warehouse.handleBatchChange" + ], + "notes": [ + "补充方法入参说明:ids/method/value 的字段类型、是否必填、来源与示例;完善响应结构示例与常见错误码说明。", + "仅文档更新,不改业务实现或语义。" + ], + "type": "updated" + }, + { + "version": "2026.05.17-system-02", + "date": "2026-05-17", + "summary": "stock.warehouse.export 由同步改为异步任务并新增进度查询 exportTaskProgress", + "methods": [ + "stock.warehouse.export", + "stock.warehouse.exportTaskProgress" + ], + "notes": [ + "stock.warehouse.export 改为异步提交导出任务:接口返回 task_id 与受理信息,后端异步生成导出文件。", + "新增 stock.warehouse.exportTaskProgress:按 task_id 查询任务状态与进度;当 status=success 时返回 download_url 供客户端下载;未找到时 status=not_found。", + "调用方式:先调用 stock.warehouse.export 获取 task_id,然后轮询 stock.warehouse.exportTaskProgress 直到 status=success 并获取 download_url。" + ], + "type": "updated" + }, + { + "version": "2026.05.17-system-01", + "date": "2026-05-17", + "summary": "新增 stock.warehouse.export:仓库商品导出(支持 where/sort),返回文件下载信息", + "methods": [ + "stock.warehouse.export" + ], + "notes": [ + "新增方法:stock.warehouse.export。复用 stock.warehouse.list 的 where/sort 过滤语义(支持 operator/value/type 标准 where 结构与历史简写)。", + "响应返回导出结果(示例字段:file_key、url),表示生成的 Excel 已上传并可下载/查询。" + ], + "type": "added" + }, + { + "version": "2026.05.16-system-01", + "date": "2026-05-16", + "summary": "同步 setting.expressInterface.create 文档入参:移除未使用的 express_platform_id,标注必填字段", + "methods": [ + "setting.expressInterface.create" + ], + "notes": [ + "移除文档中 express_platform_id(服务端实现未使用);确认必填字段 name/express_code/platform_code;仓库由系统自动填充,禁止传入 warehouse_id/warehouseId。" + ], + "type": "updated" + }, + { + "version": "2026.05.12-system-01", + "date": "2026-05-12", + "summary": "调整订单打印中间态返回结构为 waveGroups(波次 -> 平台 -> 订单)", + "methods": [ + "order.print.getWavePlatformPrintData" + ], + "notes": [ + "主要变更:将方法的主返回结构改为 waveGroups,按波次分组,波次内按平台分组,平台内为订单列表(波次 -> 平台 -> 订单)。", + "兼容性:保留旧字段 platform_groups 与 order_list 作为向后兼容字段,但文档主结构与推荐使用为 waveGroups。", + "返回结构说明:summary(total_waves/total_orders/total_platforms)、wave_ids(通过过滤的波次ID数组)、waveGroups(数组,项含 wave_id、wave_no、order_count、platforms[...],platforms项含 platform、platform_name、order_count、orders[...])、ext(missing_wave_ids、filtered_wave_ids)。", + "errors:保留 400 / 500 不变。" + ], + "type": "modified" + }, + { + "version": "2026.05.11-system-05", + "date": "2026-05-11", + "summary": "order.wave.batchList:支持 express/print 分配状态筛选,入参改为英文枚举(express/print)", + "methods": [ + "order.wave.batchList" + ], + "notes": [ + "修复 where.express_assignment_status 可按快递分配状态筛选。", + "新增 where.print_assignment_status 筛选(按打印分配聚合判断)。", + "express_assignment_status / print_assignment_status 要求使用英文枚举值:express=unassigned/partially_assigned/assigned,print=unprinted/partially_printed/printed;storage_assignment_status 继续兼容中文枚举(未分配/部分分配/已分配)。", + "若传入非法枚举值,接口返回 400(参数校验失败),message 中会说明允许取值。" + ], + "type": "updated" + }, + { + "version": "2026.05.11-system-04", + "date": "2026-05-11", + "summary": "调整 order.wave.waveStrategyFetchAdmin:由创建任务改为直接创建波次(不创建拣货任务)", + "methods": [ + "order.wave.waveStrategyFetchAdmin" + ], + "notes": [ + "接口行为变更:按策略直接抓取命中订单并创建波次,不再创建拣货任务(不返回 task_id/task_no 等任务字段)。", + "响应调整为建波结果:fetch_state(1=成功/2=失败)、wave_ids、wave_nos、created_wave_count、created_order_count、order_ids、(可选)wave_prefix、wave_prefix_source、tip/message。", + "错误调整:策略校验失败返回 400(并可能返回 validation_errors),缺少仓库上下文返回 400,建波失败返回 500 并在 message 中说明。" + ], + "type": "updated" + }, + { + "version": "2026.05.11-system-03", + "date": "2026-05-11", + "summary": "更新 pick.query:由查询拣货明细调整为按 keyword 获取/创建拣货任务", + "methods": [ + "pick.query" + ], + "notes": [ + "入参由 waybill_code/full_display 调整为 keyword(支持运单号或波次号)。", + "接口语义调整为任务化返回:命中活动任务则返回 existing 任务ID;无活动任务则创建并返回 created 任务ID。", + "新增任务归属冲突错误:当活动任务创建人非当前用户时返回冲突提示,并附带创建人及任务ID信息。" + ], + "type": "updated" + }, + { + "version": "2026.05.11-system-02", + "date": "2026-05-11", + "summary": "新增 pick.wavePickTaskCurrent:PDA 无参查询当前进行中拣货任务", + "methods": [ + "pick.wavePickTaskCurrent" + ], + "notes": [ + "新增 PDA 专用无参接口 pick.wavePickTaskCurrent。", + "按当前登录用户上下文(pick_user_id + warehouse_id)查询状态在 0/1/2 的最新任务。", + "命中返回 task_id,未命中返回 task_id=null。" + ], + "type": "added" + }, + { + "version": "2026.05.10-system-04", + "date": "2026-05-10", + "summary": "pick.wavePickTaskDetail 新增按任务类型区分的 picking_view 形态输出", + "methods": [ + "pick.wavePickTaskDetail" + ], + "notes": [ + "新增响应字段:picking_view(object),按 task.pick_mode 区分 5 种形态输出。", + "picking_view 字段说明:mode_code, mode_name, require_box_allocations, group_by, sort_by, items[](每项含 space_id、space_name、location_space、item_code、item_name、stock_id、total_qty、box_allocations[])。", + "当 pick_mode=1/3/4 时 require_box_allocations=true;当 pick_mode=2/5 时 require_box_allocations=false。" + ], + "type": "updated" + }, + { + "version": "2026.05.10-system-02", + "date": "2026-05-10", + "summary": "order.wave.waveStrategyFetchPda/Admin 返回新增 fetch_state 三态与简短 tip", + "methods": [ + "order.wave.waveStrategyFetchPda", + "order.wave.waveStrategyFetchAdmin" + ], + "notes": [ + "新增返回字段:fetch_state(number)、tip(string)、can_enter_pick_flow(boolean)", + "fetch_state 含义:1=创建成功(返回 task_id/task_no),2=普通失败(task_id=null),3=存在未完成任务(返回 existing task_id/task_no,前端可直接进入拣货流程)", + "当 fetch_state=3 时,字段 can_enter_pick_flow=true,表示前端可直接进入拣货流程;tip 为简短提示文本" + ], + "type": "updated" + }, + { + "version": "2026.05.10-system-03", + "date": "2026-05-10", + "summary": "裁剪 pick.wavePickTaskDetail 返回:移除 waves/orders,精简 task 并补充 boxes 拣货统计字段", + "methods": [ + "pick.wavePickTaskDetail" + ], + "notes": [ + "移除响应中的 waves 与 orders 子表,接口仅返回精简的 task、boxes、picking_details 与 picking_summary。", + "task 子字段裁剪为:task_id, task_no, status, pick_mode, start_at, finish_at, batch_no。", + "boxes 补充并明确返回:ref_label(箱参考标签)、required_qty(箱内需拣总数)、picked_qty(已拣数量)。", + "本次变更为文档层面的返回裁剪,前端应以新字段集合为准,旧字段可能不再返回。" + ], + "type": "updated" + }, + { + "version": "2026.05.10-system-01", + "date": "2026-05-10", + "summary": "order.wave.waveStrategyList 新增 strategy_type 最小过滤(散单/团购)", + "methods": [ + "order.wave.waveStrategyList" + ], + "notes": [ + "新增 strategy_type 过滤,仅 1/2", + "支持顶层 strategy_type 和 where.strategy_type,顶层优先", + "当前不引入其他 where 字段" + ], + "type": "updated" + }, + { + "version": "2026.05.09-system-02", + "date": "2026-05-09", + "summary": "新增 pick.wavePickTaskDetail:按任务ID解析拣货任务详情", + "methods": [ + "pick.wavePickTaskDetail" + ], + "notes": [ + "新增 pick.wavePickTaskDetail:传入 task_id 获取拣货任务完整信息,包含主表字段(task/pick_mode/status/wave_count/order_count/box_count 等)及三张子表数据(waves/orders/boxes)。", + "安全限制:接口会校验当前登录用户(operator_id/employees_id)与任务的 pick_user_id 是否一致;不一致时直接返回 403,不返回任何拣货信息。", + "鉴权配置:noNeedRight=true,noNeedAuth=true,isNeedLogin=true。" + ], + "type": "added" + }, + { + "version": "2026.05.08-system-05", + "date": "2026-05-08", + "summary": "order.wave.batchList:新增 source 字段并支持 where.source 过滤,返回 list item 中新增 source 字段", + "methods": [ + "order.wave.batchList" + ], + "notes": [ + "新增 where.source(可选,number)用于按来源过滤:0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务;不传则不过滤。", + "响应 list 每条记录新增字段 source(number),用于区分波次来源。", + "仅更新文档,业务代码不在此变更范围。" + ], + "type": "updated" + }, + { + "version": "2026.05.08-system-04", + "date": "2026-05-08", + "summary": "完善 order.wave.wavePickTaskList 文档:补充入参、分页与返回字段兼容说明", + "methods": [ + "order.wave.wavePickTaskList", + "order.wave.wavePickTaskCancel" + ], + "notes": [ + "入参补充:warehouse_id(必填)、status(支持单值或数组,建议传数组)、source、keyword、page_no、page_size;保留 pagination 对象以兼容旧客户端。", + "兼容说明:接口同时支持历史 where 结构与顶层参数;当存在同名顶层参数时以顶层参数优先;pagination 支持 page/current 与 pageSize/size 别名。", + "返回格式:响应包含 total 与 list;list 每项包含字段:task_id、task_no、status、source、pick_mode、wave_count、order_count、box_count、operator_id、operator_name、start_at、finish_at、created_at。为兼容旧客户端,响应同时保留旧字段:pick_user_id、pick_user_name、start_time、finish_time、create_time。", + "入参 strategy_id 当前主表未存,接口会忽略该过滤,不建议使用。", + "默认排序:create_time desc.", + "文档变更:移除 order.wave.wavePickTaskCancel 的入参 operator_id 与 warehouse_id;入参改为仅支持 task_ids(数组,必填),不再兼容单个 task_id;操作人与仓库由请求上下文(例如当前登录用户上下文)自动获取;若上下文缺失接口将返回错误。响应补充批量结果字段:cancelled_count、task_ids、task_nos(若后端返回)。仅更新文档,未修改业务实现。" + ], + "type": "updated" + }, + { + "version": "2026.05.08-system-03", + "date": "2026-05-08", + "summary": "升级按策略抓取接口为创建任务主流程:order.wave.waveStrategyFetchPda / order.wave.waveStrategyFetchAdmin", + "methods": [ + "order.wave.waveStrategyFetchPda", + "order.wave.waveStrategyFetchAdmin" + ], + "notes": [ + "将 PDA/Admin 场景的按策略抓取接口由受理壳方法升级为 '创建任务主流程':接口会执行参数校验并在同步响应中创建任务记录(state=created),返回 task_id、task_no、plan 与 plan_summary 供前端展示与后续查询。", + "入参新增/扩展与创建流程相关字段:至少包含 cart_id(关联拣货车/作业车ID)、source(操作来源语义)并保留并透传 strategy_id 与 strategy_params(策略参数),以支持在创建阶段对策略进行局部覆盖或透传。", + "成功返回示例字段:state=created、task_id、task_no、plan(对象)和 plan_summary(字符串);失败场景会返回 validation_errors(数组,每项含 field/message)或 message 描述创建失败原因。", + "边界说明:当前为最小主流程(创建与计划预览),后续扫描/任务执行阶段(如实际抓取订单、写入 wave 等)将在后续版本中追加与完善。" + ], + "type": "updated" + }, + { + "version": "2026.05.08-system-02", + "date": "2026-05-08", + "summary": "调整按策略抓取壳方法:order.wave.waveStrategyFetch 更名为 order.wave.waveStrategyFetchPda,并新增 order.wave.waveStrategyFetchAdmin", + "methods": [ + "order.wave.waveStrategyFetch", + "order.wave.waveStrategyFetchPda", + "order.wave.waveStrategyFetchAdmin" + ], + "notes": [ + "waveStrategyFetchPda 仅用于 PDA 场景", + "waveStrategyFetchAdmin 仅用于后台管理场景", + "两者当前均为壳子受理方法,不执行真实抓取" + ], + "type": "updated" + }, + { + "version": "2026.05.08-system-01", + "date": "2026-05-08", + "summary": "新增 order.wave.waveStrategyFetch:按策略提交抓取任务(壳子方法)", + "methods": [ + "order.wave.waveStrategyFetch" + ], + "notes": [ + "当前方法为壳子方法:仅受理并返回任务受理信息,不执行真实抓取逻辑,后续补齐执行链路。" + ], + "type": "added" + }, + { + "version": "2026.05.07-system-05", + "date": "2026-05-07", + "summary": "新增 order.wave.waveStrategyCreate 与 order.wave.waveStrategyUpdate:波次策略创建与更新接口(含参数校验与版本推进)", + "methods": [ + "order.wave.waveStrategyCreate", + "order.wave.waveStrategyUpdate" + ], + "notes": [ + "仓库 ID 与创建人(creator_name)由当前登录仓库/操作者上下文获取,接口不接受外部覆盖。", + "入参 allowed_owners 与 allowed_expresses 会校验是否在系统可用范围内(基于仓库签约货主或系统快递列表),若存在非法值接口会直接报错(400)。", + "max_same_structure 受仓库配置 min_group_order_fetch_quantity 限制:若传入值 >= min_group_order_fetch_quantity,则自动下调为 min_group_order_fetch_quantity - 1(最小值为 1)。", + "新建/更新成功后会触发仓库的 wave_strategy_version 自增(+1)并失效相关仓库配置缓存,调用方可通过策略版本推进或缓存变化感知策略已生效。" + ], + "type": "added" + }, + { + "version": "2026.05.07-system-06", + "date": "2026-05-07", + "summary": "收敛 order.wave.waveStrategyFallbackOrderList 返回字段,限定 where 白名单,补充 order.wave.singleFetchByIds 别名与返回语义", + "methods": [ + "order.wave.waveStrategyFallbackOrderList", + "order.wave.singleFetchByIds" + ], + "notes": [ + "收敛 order.wave.waveStrategyFallbackOrderList response.list 字段为 id, delivery_no, tracking_no, items_count, items_total, sys_logistics_name, store_name, province, sys_platform_name, item_snapshot;item_snapshot 格式示例:商品名称*数量|...。", + "限制 order.wave.waveStrategyFallbackOrderList.where 白名单,禁止传入 warehouse_id / warehouseId;传入未列出字段或别名冲突将返回 400。", + "补充 order.wave.singleFetchByIds:明确支持 ids / order_ids / orderIds 三个别名(优先顺序 ids -> order_ids -> orderIds)并说明返回字段 fetched_order_ids、excluded_existing_wave_order_ids、skipped_order_ids、not_found_order_ids 的语义与兼容性。" + ], + "type": "updated" + }, + { + "version": "2026.05.07-system-04", + "date": "2026-05-07", + "summary": "更新 order.wave.waveStrategyFallbackOrderList,新增商品快照字段 item_snapshot", + "methods": [ + "order.wave.waveStrategyFallbackOrderList" + ], + "notes": [ + "item_snapshot 返回格式为 商品名称1*数量|商品名称2*数量" + ], + "type": "updated" + }, + { + "version": "2026.05.07-system-03", + "date": "2026-05-07", + "summary": "新增 order.wave.waveStrategyQuickScan 与进度查询接口", + "methods": [ + "order.wave.waveStrategyQuickScan", + "order.wave.waveStrategyQuickScanTaskProgress" + ], + "notes": [ + "同仓只允许一个扫描任务并使用缓存锁;扫描范围为当前表非待审核、未分配波次且订单策略版本与仓库当前版本不一致的订单;命中策略标记 wave_scan_result=1,否则=2" + ], + "type": "added" + }, + { + "version": "2026.05.07-system-02", + "date": "2026-05-07", + "summary": "新增 order.wave.waveStrategyList:查询当前仓库波次策略列表", + "methods": [ + "order.wave.waveStrategyList" + ], + "notes": [ + "从 wms_wave_strategy 拉取当前仓库的波次策略列表,分页返回" + ], + "type": "added" + }, + { + "version": "2026.05.07-system-01", + "date": "2026-05-07", + "summary": "移除 order.wave.singleOrderFetchDetailList,新增 order.wave.waveStrategyFallbackOrderList(内置固定筛选条件)", + "methods": [ + "order.wave.singleOrderFetchDetailList", + "order.wave.waveStrategyFallbackOrderList" + ], + "notes": [ + "移除 order.wave.singleOrderFetchDetailList。", + "新增 order.wave.waveStrategyFallbackOrderList。", + "新接口基于订单通用查询口径,固定内置筛选条件:step != 0、wave_id = 0、wave_scan_result = 2。" + ], + "type": "updated" + }, + { + "version": "2026.05.06-system-06", + "date": "2026-05-06", + "summary": "新增 order.wave.singleOrderFetchDetailList:订单级散单候选明细视图", + "methods": [ + "order.wave.singleOrderFetchDetailList" + ], + "notes": [ + "新增 order.wave.singleOrderFetchDetailList:提供订单级的散单候选明细列表,返回按订单聚合的明细(非分组级)。", + "返回订单级而非分组级;响应每项包含订单 id、group_count、item_detail_machine、item_detail_machine_snapshot、item_detail、item_snapshot、logistics_name、store_id、distinguish_express、create_at 与 status_summary 等关键字段。", + "仍沿用 same_order_quantity 阈值来排除团购命中分组(仅保留 group_count < same_order_quantity 的候选项)。", + "singleOrderFetchList 暂保留以兼容现有前端,前端可在切换到订单级视图后迁移到本接口。" + ], + "type": "added" + }, + { + "version": "2026.05.06-system-05", + "date": "2026-05-06", + "summary": "storage.receiving.get 返回扩展:data.details[*] 新增 box_remainder、box_weight", + "methods": [ + "storage.receiving.get" + ], + "notes": [ + "storage.receiving.get 的响应在 data.details[*] 中新增可选字段:box_remainder(箱内剩余数量/零散数量,number,默认 0)与 box_weight(实测箱重,number,默认 0)。", + "兼容性:新增字段为可选,旧客户端无需修改;建议前端在需要展示箱内余量/箱重时使用这些字段。" + ], + "type": "updated" + }, + { + "version": "2026.05.06-system-04", + "date": "2026-05-06", + "summary": "storage.receiving.getReceivingDetail 返回扩展:明细增加 box_remainder、box_weight;storage.receiving.completeReceiving 通知包含这两个字段", + "methods": [ + "storage.receiving.getReceivingDetail", + "storage.receiving.completeReceiving" + ], + "notes": [ + "为支持箱规统计与通知回传,getReceivingDetail 的明细项(receiving.details 或 data.details)在响应中新增可选字段:box_remainder(箱内剩余数量/零散数量,number)与 box_weight(实测箱重,number,单位同系统重量)。", + "completeReceiving 在完成收货后会发送通知(或回调),通知 payload/metadata 中将包含每条明细的 box_remainder 与 box_weight 字段,供下游系统/前端展示或审计使用。", + "兼容性:新增字段为可选,旧客户端在未使用这些字段时无需变更。" + ], + "type": "updated" + }, + { + "version": "2026.05.06-system-03", + "date": "2026-05-06", + "summary": "storage.receiving.detailChange:新增入参/出参字段 box_remainder、box_weight", + "methods": [ + "storage.receiving.detailChange" + ], + "notes": [ + "为支持箱规细化与回写,detailChange 新增可选入参 box_remainder(箱内余量/零散数量)和 box_weight(实测箱重,单位同系统重量),写入后会回写至明细并在响应 data 中返回对应字段。", + "兼容性:新增字段为可选,不传入则不影响现有调用;建议前端在需要回写箱余与箱重时一并传入。" + ], + "type": "updated" + }, + { + "version": "2026.05.06-system-02", + "date": "2026-05-06", + "summary": "新增 order.wave.singleFetchByIds:按订单ID抓取到一个散单波次", + "methods": [ + "order.wave.singleFetchByIds" + ], + "notes": [ + "新增 order.wave.singleFetchByIds:按入参 ids(兼容 order_ids/orderIds)去重后筛选当前仓库内待处理且不在波次中的订单,若存在可抓取订单则创建单个散单波次并把这些订单写入该波次(不区分快递);成功后批量写入订单操作日志;若无可抓取订单返回 wave_id=0。", + "接口行为严格对齐实现:过滤条件包含 step in [1,2,3]、status != 'cancel'、outbound_status != 'padding';已在波次的订单会被排除并返回 excluded_existing_wave_order_ids;响应包含 ids、wave_id、wave_no、fetched_order_ids、fetched_order_count、excluded_existing_wave_order_ids、skipped_order_ids、not_found_order_ids。" + ], + "type": "added" + }, + { + "version": "2026.05.06-system-01", + "date": "2026-05-06", + "summary": "新增 order.wave.groupFetch 与 order.wave.singleFetch;order.wave.fetch 保留兼容别名;抓取进度补充上限字段", + "methods": [ + "order.wave.groupFetch", + "order.wave.singleFetch", + "order.wave.fetch", + "order.wave.fetchTaskProgress" + ], + "notes": [ + "新增 order.wave.groupFetch:抓取团购接口(异步任务提交),参数 structure_list 与原 fetch 一致。", + "新增 order.wave.singleFetch:抓取散单接口(异步任务提交),在 structure_list 每项新增必填字段 max_fetch_quantity(最大抓取上限,订单数,正整数)。", + "order.wave.fetch 保留为兼容别名(等同 groupFetch),避免误导客户端。", + "groupFetch/singleFetch/fetch 的响应新增可选字段 fetch_mode;singleFetch 响应额外返回 max_fetch_quantity。", + "order.wave.fetchTaskProgress 的响应增加单模式相关字段:fetch_mode、max_fetch_quantity、limit_reached、stop_reason,用于描述散单抓取的上限与停止原因。" + ], + "type": "updated" + }, + { + "version": "2026.05.05-system-02", + "date": "2026-05-05", + "summary": "order.wave.batchList:新增 where.storage_assignment_status 的过滤语义说明", + "methods": [ + "order.wave.batchList" + ], + "notes": [ + "新增 where 字段 `storage_assignment_status`:类型 string,可选值:`未分配`、`部分分配`、`已分配`;默认不传:不做分配状态限制。", + "过滤语义:`已分配`:聚合后全部 fin;`部分分配`:不含 error,且既不是全 none,也不是全 fin;`未分配`:全 none 或包含 error(异常并入未分配筛选集合)。", + "说明:返回字段 `storage_assignment_status` 的展示值保持不变;包含 error 时仍可能展示“分配异常”,但 where 的过滤语义把异常算到“未分配”集合,避免把过滤语义与展示值混淆。" + ], + "type": "updated" + }, + { + "version": "2026.05.05-system-01", + "date": "2026-05-05", + "summary": "新增 order.wave.singleOrderFetchList:散单候选分组查询(排除团购命中分组)", + "methods": [ + "order.wave.singleOrderFetchList" + ], + "notes": [ + "新增 order.wave.singleOrderFetchList:返回按机器结构分组的散单候选列表,接口会排除已达团购阈值(同组订单数量 >= same_order_quantity 或仓库配置 min_group_order_fetch_quantity)的分组,仅返回同组订单数量 < 阈值 的分组(散单候选)。", + "与 order.wave.groupOrderFetchList 的关键差异:groupOrderFetchList 返回满足团购阈值(>=)的分组;singleOrderFetchList 返回未达阈值(<)的散单候选分组。", + "影响范围:订单波次抓取相关前端/调度服务。兼容性:不影响或修改现有 order.wave.groupOrderFetchList,两个接口可并行使用。" + ], + "type": "added" + }, + { + "version": "2026.05.04-system-04", + "date": "2026-05-04", + "summary": "完善商品编码唯一性校验接口文档,补充 item_id(排除自身)和 owner_id(货主ID)入参说明,新增 unique/isUnique 返回字段描述", + "methods": [ + "stock.warehouse.checkItemCodeUnique" + ], + "notes": [ + "完善商品编码唯一性校验接口文档,补充 item_id(排除自身)和 owner_id(货主ID)入参说明,新增 unique/isUnique 返回字段描述" + ], + "type": "modified" + }, + { + "version": "2026.05.04-system-02", + "date": "2026-05-04", + "summary": "修改 pick.query 入参:order_id -> waybill_code", + "methods": [ + "pick.query" + ], + "notes": [ + "入参从 order_id 改为 waybill_code(快递号),通过快递号查找订单后再查波次拣货信息" + ], + "type": "breaking_change" + }, + { + "version": "2026.05.04-system-01", + "date": "2026-05-04", + "summary": "新增 system method pick.query:按订单查询波次拣货信息", + "methods": [ + "pick.query" + ], + "notes": [ + "按订单查询该订单所属波次的拣货信息,支持 full/full_display/is_full 控制是否完整显示;接口按当前登录用户仓库上下文过滤,防止跨仓越界。" + ], + "type": "added" + }, + { + "version": "2026.05.03-system-09", + "date": "2026-05-03", + "summary": "新增按 request_id 查询分配状态/结果接口", + "methods": [ + "order.pendingOrder.allocateStorageProgress" + ], + "notes": [ + "新增按 request_id 查询储位分配异步任务状态/结果接口,支持 status:submitted/running/success/failed/not_found;success 返回 result(底层分配结果),failed 返回 error(错误信息);兼容 requestId 参数名。" + ], + "type": "updated" + }, + { + "version": "2026.05.03-system-07", + "date": "2026-05-03", + "summary": "新增抓取进度查询接口", + "methods": [ + "order.wave.fetch", + "order.wave.fetchTaskProgress" + ], + "notes": [ + "新增按 task_id 查询抓取任务进度的接口 order.wave.fetchTaskProgress,支持返回 status(submitted/running/success/failed/not_found)及进度相关字段:progress_percent、finished_structure_count、total_fetched_quantity、duration_ms、error、update_time 等;同时明确 order.wave.fetch 为异步任务提交接口,客户端可通过 task_id 调用 order.wave.fetchTaskProgress 查询进度和最终结果。" + ], + "type": "updated" + }, + { + "version": "2026.05.03-system-05", + "date": "2026-05-03", + "summary": "补齐仓库设置模块 setting.warehouse 的 methods 文档", + "methods": [ + "setting.warehouse.getSettings", + "setting.warehouse.getFieldMeta", + "setting.warehouse.saveSettings" + ], + "notes": [ + "补齐仓库配置 methods API 文档" + ], + "type": "updated" + }, + { + "version": "2026.05.03-system-04", + "date": "2026-05-03", + "summary": "order.wave:自动加团新增跳过规则并新增批量结束自动加团接口", + "methods": [ + "order.wave.batchAutoGrouping", + "order.wave.batchFinishAutoGrouping" + ], + "notes": [ + "开启自动加团新增“已打印/超最大波次容量”跳过规则并在响应中返回跳过明细;新增批量结束自动加团接口(将 wave_status=0 的波次批量置为 1)" + ], + "type": "updated" + }, + { + "version": "2026.05.03-system-03", + "date": "2026-05-03", + "summary": "裁剪 order_list 以轻量化返回", + "methods": [ + "order.wave.batchList" + ], + "notes": [ + "移除响应中的 order_list 字段,接口仅返回波次基础信息与状态汇总(order_count / storage_assignment_status / express_assignment_status / print_assignment_status)" + ], + "type": "updated" + }, + { + "version": "2026.05.03-system-02", + "date": "2026-05-03", + "summary": "新增 order.wave.batchAutoGrouping:批量改为自动加团中", + "methods": [ + "order.wave.batchAutoGrouping" + ], + "notes": [ + "新增批量改为自动加团中接口及返回字段" + ], + "type": "updated" + }, + { + "version": "2026.04.22-system-02", + "date": "2026-04-22", + "summary": "新增 order.pendingOrder.syncOrderIds:待处理订单同步透传入口", + "methods": [ + "order.pendingOrder.syncOrderIds" + ], + "notes": [ + "新增 order.pendingOrder.syncOrderIds:仅接收 order_ids 并转发到服务层,当前不做业务处理。", + "接口保留登录态校验,入参仅接受订单 ID 相关字段,响应以服务层返回值为准。", + "该方法用于预留同步链路,后续补齐业务逻辑时再扩展服务层实现。" + ], + "type": "updated" + }, + { + "version": "2026.04.22-system-01", + "date": "2026-04-22", + "summary": "补全订单工作台各模块 detail 方法文档", + "methods": [ + "order.detail", + "order.pendingOrder.detail", + "order.reviewOrder.detail", + "order.expectionOrder.detail", + "order.outboundOrder.detail", + "order.deliveryOrder.detail", + "order.deliveryExpectionOrder.detail", + "order.entrustOrder.detail", + "order.archiveOrder.detail" + ], + "notes": [ + "补全文档:detail 为订单工作台通用详情方法,入参支持 ids/id/order_id/orderId;可选 tableType/tablePosition/type/moduleName,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等。", + "返回包含 order/detail(订单头)、orderItems/items(商品明细)、expresses(运单信息)、waybill_codes(去重运单号数组)。" + ], + "type": "updated" + }, + { + "version": "2026.04.19-system-01", + "date": "2026-04-19", + "summary": "新增方法 setting.expressInterface.listByWarehousePlatformCode:按 warehouse_id + platform_code 查询全字段列表并支持缓存", + "methods": [ + "setting.expressInterface.listByWarehousePlatformCode" + ], + "notes": [ + "新增 setting.expressInterface.listByWarehousePlatformCode:按 warehouse_id + platform_code 返回快递接口的全字段数组(不分页),每条记录包含 express 关联对象(id/code/name/platform 等)。", + "支持缓存,缓存键由 warehouse_id + platform_code 组成;缓存命中将直接返回缓存结果以提升查询性能。", + "在创建/更新/删除操作(setting.expressInterface.create/update/delete)后,会主动清理对应 warehouse_id + platform_code 的缓存以确保数据一致性。" + ], + "type": "added" + }, + { + "version": "2026.04.17-system-08", + "date": "2026-04-17", + "summary": "新增快递编码管理模块批量软删除接口 setting.express.delete", + "methods": [ + "setting.express.delete" + ], + "notes": [ + "新增批量软删除接口 setting.express.delete:接受 ids(数组、逗号字符串或单值),对属于当前仓库且未被删除的记录执行软删除(设置 deleted_at),并清理 express 列表缓存。", + "当任一目标记录的 code 被 wms_express_interface.express_code 引用时,接口会拒绝删除并返回 409,错误信息中包含被引用的编码列表。", + "响应包含 ids、deleted_ids、already_deleted_ids 与 status,已删除与未删除的 id 会明确分类。仅记录已实现行为。" + ], + "type": "added" + }, + { + "version": "2026.04.17-system-05", + "date": "2026-04-17", + "summary": "新增文档分组:平台编码管理模块(收口 index.getPlatformList 与 setting.platform.*)", + "methods": [ + "index.getPlatformList", + "setting.platform.list", + "setting.platform.create", + "setting.platform.update", + "setting.platform.delete" + ], + "notes": [ + "新增独立文档分组 '平台编码管理模块',将平台基础列表(index.getPlatformList)与平台设置管理接口(setting.platform.*)归并为单一分组以便维护;仅文档变更,不修改实现。", + "文档中仅包含已实现的方法与字段,未新增或推断不存在的参数/返回字段。" + ], + "type": "added" + }, + { + "version": "2026.04.17-system-04", + "date": "2026-04-17", + "summary": "新增独立平台设置模块 setting.platform(wms_platfrom_setting)及其 CRUD 接口:list/create/update/delete。", + "methods": [ + "setting.platform.list", + "setting.platform.create", + "setting.platform.update", + "setting.platform.delete" + ], + "notes": [ + "新增独立模块 setting.platform,映射数据表 wms_platfrom_setting;list 支持 where(id/code/name/platform_code/quickWhere)与 pagination(兼容 page/pageSize/page_size);create/update 要求 platform_code 必须存在于系统平台表(wms_platform),且禁止越权写入 warehouse_id;delete 需传入 id 并校验当前仓库范围。" + ], + "type": "added" + }, + { + "version": "2026.04.15-system-07", + "date": "2026-04-15", + "summary": "将 docs/order-workbench-list-api.md 引用统一为 window 链接格式", + "methods": [ + "order.list", + "order.reviewOrder.list", + "order.pendingOrder.list", + "order.outboundOrder.list", + "order.expectionOrder.list", + "order.entrustOrder.list", + "order.deliveryOrder.list", + "order.deliveryExpectionOrder.list" + ], + "notes": [ + "将所有 methods/system.json 中指向 docs/order-workbench-list-api.md 的说明统一替换为 docs/order-workbench-list-api.md 格式,以便 HTML 渲染识别为 window 链接。", + "仅修改 methods/system.json 的文档字段,不涉及任何业务代码或接口契约变化。" + ], + "type": "updated" + }, + { + "version": "2026.04.15-system-06", + "date": "2026-04-15", + "summary": "订单工作台列表文档补全 raw 字段字典与中文语义说明", + "methods": [ + "order.list", + "order.reviewOrder.list", + "order.pendingOrder.list", + "order.outboundOrder.list", + "order.expectionOrder.list", + "order.entrustOrder.list", + "order.deliveryOrder.list", + "order.deliveryExpectionOrder.list", + "order.archiveOrder.list" + ], + "notes": [ + "在 docs/order-workbench-list-api.md 中补充所有订单列表通用 raw 字段字典,明确每个字段的中文语义与 enum 取值。", + "补充 express_numbers / waybill_codes 两个服务层派生字段说明,便于前端直接渲染多个快递号。", + "methods/system.json 中所有订单 list 的 response.list 描述已指向该字段字典章节。" + ], + "type": "updated" + }, + { + "version": "2026.04.15-system-05", + "date": "2026-04-15", + "summary": "基础模块新增快递/平台列表查询接口并设置为不鉴权,复用缓存 service", + "methods": [ + "index.getExpressList", + "index.getPlatformList" + ], + "notes": [ + "新增 index.getExpressList,归属基础模块(module=index),对应 app/service/systems/express.js 中的 getExpressList。", + "index.getExpressList 设置为不鉴权,不需要 Authorization 头。", + "新增 index.getPlatformList,归属基础模块(module=index),对应 app/service/systems/platform.js 中的 getPlatformList。", + "index.getPlatformList 设置为不鉴权,不需要 Authorization 头。", + "快递列表与平台列表都支持缓存优先,缓存未命中时回源数据库并写入缓存。", + "平台列表支持缓存优先,缓存未命中时回源 wms_platform 并写入缓存。" + ], + "type": "added" + }, + { + "version": "2026.04.15-system-02", + "date": "2026-04-15", + "summary": "签约策略字段元信息新增 default_express_code / default_platform_code list 选项", + "methods": [ + "storeWarehouse.store.getPolicyConfigFields" + ], + "notes": [ + "getPolicyConfigFields 现在返回 default_express_code 与 default_platform_code 两个 list 字段,并从 wms_express / wms_platform 读取选项列表。", + "默认值仍保留为 default_express_code=STO、default_platform_code=TB。" + ], + "type": "updated" + }, + { + "version": "2026.04.15-system-03", + "date": "2026-04-15", + "summary": "签约策略字段移除 sku_visibility,receive_mode options 改为 value/label 结构", + "methods": [ + "storeWarehouse.store.savePolicyConfig", + "storeWarehouse.store.getPolicyConfigFields" + ], + "notes": [ + "策略字段定义不再包含 sku_visibility,历史值读取时仍会被归一化忽略。", + "receive_mode 的 options 改为 [{ value, label }] 格式,便于前端直接渲染。" + ], + "type": "updated" + }, + { + "version": "2026.04.15-system-04", + "date": "2026-04-15", + "summary": "按文件模块拆分 order 目录系统文档分组,覆盖订单工作台入口及各子模块方法", + "methods": [ + "order.list", + "order.manualOutboundOrder", + "order.badgeCount", + "order.outboundOrder.manualOutboundOrder", + "order.reviewOrder.list", + "order.reviewOrder.reviewOrder", + "order.pendingOrder.list", + "order.pendingOrder.reverseReviewOrder", + "order.pendingOrder.markPendingOutboundOrder", + "order.pendingOrder.cancelOrder", + "order.outboundOrder.list", + "order.expectionOrder.list", + "order.entrustOrder.list", + "order.deliveryOrder.list", + "order.deliveryExpectionOrder.list", + "order.archiveOrder.list" + ], + "notes": [ + "按 app/service/systemMethods/order 下的实际对外方法补全 methods/system.json 文档,只覆盖 system,不处理 qimen。", + "order 文档已按 index / reviewOrder / pendingOrder / outboundOrder / expectionOrder / entrustOrder / deliveryOrder / deliveryExpectionOrder / archiveOrder 拆成多个模块分组。", + "同步根据当前代码意图补充 params / response / errors,且不再把 index.js 已移除的兼容接口写回文档。" + ], + "type": "updated" + }, + { + "version": "2026.04.15-system-01", + "date": "2026-04-15", + "summary": "货主主体配置默认补齐 default_express_code / default_platform_code", + "methods": [ + "store.createStore", + "store.createWarehouse" + ], + "notes": [ + "当 subject_config 未传或缺少字段时,自动补齐 default_express_code=STO、default_platform_code=TB,并保留现有的 max_notice_webhook_count 默认值。", + "同步更新 methods/system.json 中 store.createStore 与 store.createWarehouse 的参数说明。" + ], + "type": "updated" + }, + { + "version": "2026.04.14-system-01", + "date": "2026-04-14", + "summary": "库存列表新增货主名称字段 stock.store_name", + "methods": [ + "storage.inventory.list" + ], + "notes": [ + "在 methods/system.json 的 storage.inventory.list response 中补充 stock.store_name:来源于签约表 store_remask,若无签约关系则为 null。", + "只同步文档,不修改业务代码。" + ], + "type": "updated" + }, + { + "version": "2026.04.13-system-01", + "date": "2026-04-13", + "summary": "补全 storage.receiving.detailChange 的入参/出参契约与错误码说明", + "methods": [ + "storage.receiving.detailChange" + ], + "notes": [ + "在 methods/system.json 中补充 storage.receiving.detailChange 的 params/response/errors,明确 id 与 receiving_id 必填。", + "说明 expiry_date 小于当前日期时返回 400 且 message 为 \"到期日期已过期,不能录入收货\"。", + "说明当传入 system_product_id 时会回填条码、重量、箱规、商品名称与 product_snapshot;未传时 barcode/product_name 也可单独更新。", + "同步补充文档:docs/storage-receiving-api.md 中新增 detailChange 段落。" + ], + "type": "updated" + }, + { + "version": "2026.04.07-system-01", + "date": "2026-04-07", + "summary": "修正 warehouse.getAreaRacks 的鉴权/权限链路文档,明确该接口需要 登录并走权限校验。", + "methods": [ + "warehouse.getAreaRacks" + ], + "notes": [ + "对齐当前 system 文档中的 isNeedAuth=true、isNeedLogin=true。", + "用于补充该接口权限链路修正文档的历史上下文,不改变 methods/system.json 的 SSOT 角色。" + ] + }, + { + "version": "2026.04.07-system-02", + "date": "2026-04-07", + "summary": "补充签约配置相关接口文档,覆盖策略字段元信息查询与面单数量人工调整。", + "methods": [ + "storeWarehouse.store.getPolicyConfigFields", + "storeWarehouse.store.adjustPrintQuantity" + ], + "notes": [ + "getPolicyConfigFields 说明为获取签约策略可配置字段元信息列表。", + "adjustPrintQuantity 说明为人工调整签约关系下的面单余额并记录变更日志,并 明确 id、change_quantity、reason 等关键入参。" + ] + }, + { + "version": "2026.04.07-system-03", + "date": "2026-04-07", + "summary": "对外命名从 qimenConfig 收口为 apiConfig,并在接口配置文档中强调 interface_type_id 校验。", + "methods": [ + "storeWarehouse.store.listApiConfig", + "storeWarehouse.store.saveApiConfig", + "storeWarehouse.store.deleteQimenConfig" + ], + "notes": [ + "文档对外统一使用 apiConfig / api_config 命名,减少 qimenConfig 历史别名歧义。", + "saveApiConfig 要求 interface_type_id 为必填且必须指向已存在的 wms_interface_type 记录。", + "listApiConfig / deleteQimenConfig 同步补充 interface_type_id 字段说明。" + ] + }, + { + "version": "2026.04.07-system-04", + "date": "2026-04-07", + "summary": "补充 /api/docs 文档体验增强说明,新增查看变更记录与查看原文 JSON 的入口说明。", + "methods": [ + "/api/docs", + "/api/docs/:docName", + "/api/docs/:docName/raw", + "/api/docs/:docName/changes" + ], + "notes": [ + "sidecar 变更数组用于承载文档历史说明,不替代 methods/system.json 作为 SSOT。", + "原文 JSON 入口继续用于直接查看当前生效文档。" + ] + }, + { + "version": "2026.04.07-system-05", + "date": "2026-04-07", + "summary": "修正 storeWarehouse.store.adjustPrintQuantity 的面单余额调整语义:由增减/累加改为覆盖设置目标余额。", + "methods": [ + "storeWarehouse.store.adjustPrintQuantity" + ], + "notes": [ + "adjustPrintQuantity 当前兼容 print_quantity、target_quantity、change_quantity、adjust_quantity 作为目标面单余额输入,不再按增减量解释。", + "变更日志中的 change_quantity 由 before/after 自动计算差值,以兼容历史审计与展示。" + ] + }, + { + "version": "2026.04.07-system-06", + "date": "2026-04-07", + "summary": "按接口类型分类限制必填字段,OPEN_API 创建时自动生成 self_app_key/self_app_secret", + "methods": [ + "storeWarehouse.store.saveApiConfig" + ], + "notes": [ + "QM_WMS 类型须填写 qimen_app_key/qimen_customer_id/qimen_warehouse_code;OPEN_API 类型三个奇门字段非必填,创建时自动生成 self_app_key(WMS+32位HEX)和 self_app_secret(64位HEX),更新时保留已有密钥。" + ], + "type": "changed" + }, + { + "version": "2026.04.07-system-07", + "date": "2026-04-07", + "summary": "新增接口类型列表查询接口,归属基础模块,无需权限", + "methods": [ + "index.listInterfaceTypes" + ], + "notes": [ + "返回所有已启用的接口类型(wms_interface_type),包含 id、interface_code、interface_name、interface_category、description 字段。设置 isNeedAuth: false, isNeedLogin: true。" + ], + "type": "added" + }, + { + "version": "2026.04.07-system-08", + "date": "2026-04-07", + "summary": "app_name 改为必传参数", + "methods": [ + "storeWarehouse.store.saveApiConfig" + ], + "notes": [ + "app_name 不再有默认值自动生成逻辑,调用方必须传入非空的 app_name,否则返 回 400 错误。" + ], + "type": "changed" + }, + { + "version": "2026.04.07-system-09", + "date": "2026-04-07", + "summary": "新增收货单快捷入库上架接口", + "methods": [ + "storage.inventory.quickPutaway" + ], + "notes": [ + "新建 storage.inventory 库存操作模块。quickPutaway 从收货单直接生成入库单 (SCRK)并写入 wms_storage 库存表,同时更新 wms_stock_warehouse 库存数量(悲观行锁),回填收货明细入库状态。要求收货单已完成且所有明细已匹配系统商品。" + ], + "type": "added" + }, + { + "version": "2026.04.08-system-01", + "date": "2026-04-08", + "summary": "新增收货单与入库单匹配入库接口", + "methods": [ + "storage.inventory.matchPutaway" + ], + "notes": [ + "接收多个收货单和入库单,按商品(stock_warehouse_id)进行数量匹配入库,完 成后根据入库单来源(QM/API)自动触发回传。入参为 receiving_ids(数组)和 entry_order_ids(数组),返回匹配汇总、各收货单入库状态、各入库单状态及回传结果。isNeedAuth=true, isNeedLogin=true, isNeedRight=false。" + ], + "type": "added" + }, + { + "version": "2026.04.08-system-02", + "date": "2026-04-08", + "summary": "saveApiConfig 新增 callback_url 可选参数", + "methods": [ + "storeWarehouse.store.saveApiConfig" + ], + "notes": [ + "新增 callback_url 参数(VARCHAR(500),可选),用于 OPEN_API 类型入库单的 回调地址配置。" + ], + "type": "changed" + }, + { + "version": "2026.04.08-system-03", + "date": "2026-04-08", + "summary": "serializeQimenConfig 新增返回 callback_url 字段,影响 list 和 listApiConfig 两个接口", + "methods": [ + "storeWarehouse.store.list", + "storeWarehouse.store.listApiConfig" + ], + "notes": [ + "serializeQimenConfig() 序列化方法新增 callback_url(string)字段。storeWarehouse.store.list 返回的每条记录 api_config 对象中包含 callback_url;storeWarehouse.store.listApiConfig 返回的 list 数组中每条配置包含 callback_url。" + ], + "type": "changed" + }, + { + "version": "2026.04.08-system-04", + "date": "2026-04-08", + "summary": "新增库存移库(库位转移)接口", + "methods": [ + "storage.inventory.transferLocation" + ], + "notes": [ + "新增 storage.inventory.transferLocation 接口,支持批量多商品多库位移库, 包含部分数量移库与全量移库。入参为 warehouse_id(仓库ID)和 transfers 数组(storage_id、target_space_id、quantity),触发 storage_transfer_completed 通知事件, 每条移库记录独立操作日志。isNeedAuth=true, isNeedLogin=true。" + ], + "type": "added" + }, + { + "version": "2026.04.08-system-05", + "date": "2026-04-08", + "summary": "简化移库接口入参,从批量 transfers 数组改为单条移库", + "methods": [ + "storage.inventory.transferLocation" + ], + "notes": [ + "移除 warehouse_id 和 transfers 数组入参,改为扁平的 storage_id + target_space_id + quantity 三个顶层参数。warehouse_id 从库存记录自动获取,接口从批量移库简化为单商品单库位移库。响应结构同步简化为单条结果对象。" + ], + "type": "modified" + }, + { + "version": "2026.04.08-system-06", + "date": "2026-04-08", + "summary": "新增商品库存明细查询接口", + "methods": [ + "stock.warehouse.getStockDetail" + ], + "notes": [ + "新增 stock.warehouse.getStockDetail 接口,按库位/批次维度查询商品库存分布。入参为 stock_id(必填,商品库存ID)和 pagination(可选,含 page/pageSize)。返回 stockItem(商品概要)、storageList(wms_storage 明细数组,含批次号、库位、数 量、锁定数量、生产日期、过期日期等,关联 location_space 库位信息)、pagination 分页信息。isNeedAuth=false, isNeedLogin=true。底层调用 stockStore.getStockDetail,自动校验商品归属当前仓库。" + ], + "type": "added" + }, + { + "version": "2026.04.08-system-07", + "date": "2026-04-08", + "summary": "新增入参 group_by_batch,支持按批次维度切换库存明细聚合方式", + "methods": [ + "stock.warehouse.getStockDetail" + ], + "notes": [ + "新增可选布尔参数 group_by_batch(默认 false)。false 时按库位合并数量,批次相关字段(batch_no, production_date, expiry_date, inbound_time, inbound_order_no, supplier_batch_no)置 null;true 时保持原逻辑返回每条明细。出参结构不变,但 storageList 中批次字段在合并模式下为 null。" + ], + "type": "modified" + }, + { + "version": "2026.04.08-system-08", + "date": "2026-04-08", + "summary": "新增按商品维度移库接口", + "methods": [ + "storage.inventory.transferByProduct" + ], + "notes": [ + "新增 storage.inventory.transferByProduct 接口,按库位+商品查找所有库存记 录合并移动。入参为 space_id(原库位ID)、stock_id(商品SKU ID,即 wms_stock_warehouse.id)、target_space_id(目标库位ID)、quantity(移库数量)。开启批次管理(is_batch_mgmt=Y)的商品会被拒绝,需使用 transferLocation 按库存记录精确移库。复用 storage_transfer_completed 通知事件,操作日志编码 STORAGE_TRANSFER_BY_PRODUCT。isNeedAuth=true, isNeedLogin=true。" + ], + "type": "added" + }, + { + "version": "2026.04.08-system-09", + "date": "2026-04-08", + "summary": "补充 storeWarehouse.store.list 完整 response 输出字段说明,移除 api_config / apiConfig", + "methods": [ + "storeWarehouse.store.list" + ], + "notes": [ + "从返回结果中移除 api_config 和 apiConfig 字段(代码中 delete serialized.api_config / delete serialized.apiConfig),文档 response 补充完整输出字段列表:id, store_id, store_name, warehouse_id, warehouse_name, counterparty_id, counterparty_name, current_subject_role, auth_status, auth_status_label, apply_reason, review_comment, apply_time, review_time, auth_start, auth_end, actual_end, print_quantity, applied_by, reviewed_by, ended_by, remask, use_status, policy_config, is_auth_valid, remaining_days 以及分页和 current_subject 信息。" + ], + "type": "updated" + }, + { + "version": "2026.04.08-system-10", + "date": "2026-04-08", + "summary": "货主列表返回新增 has_qimen_config 布尔字段", + "methods": [ + "storeWarehouse.store.list" + ], + "notes": [ + "storeWarehouse.store.list 返回的 data.list[] 中新增 has_qimen_config(boolean),表示该货主是否已配置奇门。" + ], + "type": "changed" + }, + { + "version": "2026.04.08-system-11", + "date": "2026-04-08", + "summary": "补全 stock.warehouse.search 接口文档,新增 params / response / errors 完整说明", + "methods": [ + "stock.warehouse.search" + ], + "notes": [ + "入参补充 keyword(string,模糊匹配 item_code / item_name / goods_code / barcode)和 store_id(number,按货主筛选)。响应补充 data 数组各字段(id, item_code, goods_code, item_name, sku_property, stock_unit, quantity, locked_quantity, brand_name, item_type, barcodes, store_stock)以及 total。errors 补充 code=0 搜 索失败场景。" + ], + "type": "updated" + }, + { + "version": "2026.04.08-system-12", + "date": "2026-04-08", + "summary": "新增 with_stock / is_batch 参数,支持返回关联库存明细(按库位分 组或按批次逐条)", + "methods": [ + "stock.warehouse.search" + ], + "notes": [ + "入参新增 with_stock(boolean,默认 false,是否返回关联库存数据)和 is_batch(boolean,默认 false,仅 with_stock=true 时生效,按批次明细返回)。响应 data[] 新增 storage[] 字段:is_batch=false 时按库位分组汇总(含 space_id、space、inventory_type、quantity、locked_quantity、available_quantity);is_batch=true 时逐 条返回批次明细(含 id、stock_id、space_id、batch_no、inventory_type、quantity、locked_quantity、available_quantity、production_date、expiry_date、inbound_time、inbound_order_no、supplier_batch_no、created_at、space)。" + ], + "type": "updated" + }, + { + "version": "2026.04.08-system-13", + "date": "2026-04-08", + "summary": "新增 wms_stock_transaction 表和模型", + "methods": [ + "wms_stock_transaction" + ], + "notes": [ + "新增出入库流水记录表 wms_stock_transaction,含 transaction_type(INBOUND/OUTBOUND)、warehouse_id、store_id、stock_id、storage_id、space_id、quantity、batch_no、inventory_type、order_type、order_no、order_id、receiving_id、entry_order_id、operator_id、operator_name、remark 等字段,关联 StockWarehouse 和 Storage 模型。" + ], + "type": "added" + }, + { + "version": "2026.04.08-system-14", + "date": "2026-04-08", + "summary": "quickPutaway 和 matchPutaway 入库时自动写入出入库记录", + "methods": [ + "storage.inventory.quickPutaway", + "storage.inventory.matchPutaway" + ], + "notes": [ + "入库操作完成后自动写入 wms_stock_transaction 记录。quickPutaway 写入 order_type='SCRK'(收货入库),matchPutaway 写入 order_type='MATCH'(匹配入库),均 自动填充 warehouse_id、store_id、stock_id、storage_id、space_id、quantity、batch_no、inventory_type 等字段。" + ], + "type": "updated" + }, + { + "version": "2026.04.08-system-15", + "date": "2026-04-08", + "summary": "新增 storage.inventory.list 出入库记录列表查询接口", + "methods": [ + "storage.inventory.list" + ], + "notes": [ + "出入库记录列表查询,支持 where 条件(transaction_type、stock_id、space_id、store_id、order_type、order_no、inventory_type、operator_name、created_at)、 分页(pagination)、排序(sort)和 group_by_batch 参数。默认合并模式按库位+商品 聚合返回合计数量与记录条数,group_by_batch=true 时返回每条明细含 batch_no、order_no、operator_name 等完整信息。响应均关联 stockItem(item_code、item_name、sku_property、stock_unit)。" + ], + "type": "added" + }, + { + "version": "2026.04.08-system-16", + "date": "2026-04-08", + "summary": "出入库流水记录查询接口从 storage.inventory.list 改名为 storage.transaction.list", + "methods": [ + "storage.transaction.list" + ], + "notes": [ + "将出入库流水记录查询从 storage.inventory.list 迁移到 storage.transaction.list,避免与库存列表概念混淆。功能和参数不变。isNeedAuth=false, isNeedLogin=true, isNeedRight=false。" + ], + "type": "rename", + "module": "storage" + }, + { + "version": "2026.04.08-system-17", + "date": "2026-04-08", + "summary": "新增 storage.inventory.list 库存列表查询接口", + "methods": [ + "storage.inventory.list" + ], + "notes": [ + "新增库存列表查询接口,查询 wms_storage 表。支持 where 条件(stock_id/space_id/store_id/inventory_type/batch_no/inbound_order_no/available_quantity/inbound_time/created_at)、分页、排序。支持 group_by_batch 参数:默认 false 按库位+商 品合并(SUM quantity/locked_quantity/available_quantity),true 返回每条明细含 batch_no/production_date/expiry_date 等。关联 stockItem(商品信息)和 space(库位信息)。isNeedAuth=false, isNeedLogin=true, isNeedRight=false。" + ], + "type": "add", + "module": "storage" + }, + { + "version": "2026.04.08-system-18", + "date": "2026-04-08", + "summary": "移除 storage.entry.create 创建入库单接口", + "methods": [ + "storage.entry.create" + ], + "notes": [ + "不再允许通过 API 创建入库单。入库单仅由快捷入库(quickPutaway)和匹配入库(matchPutaway)等内部流程自动创建。底层 service 实现保留但不再通过 systemMethods 对外暴露。" + ], + "type": "remove", + "module": "storage" + }, + { + "version": "2026.04.08-system-19", + "date": "2026-04-08", + "summary": "移除 storage.entry.addDetail / deleteDetail / detailChange 对外 接口", + "methods": [ + "storage.entry.addDetail", + "storage.entry.deleteDetail", + "storage.entry.detailChange" + ], + "notes": [ + "入库单明细编辑能力不再通过 systemMethods 对外暴露,入库单模块仅保留 list/get/cancel/completeEntry。" + ], + "type": "remove", + "module": "storage" + }, + { + "version": "2026.04.08-system-20", + "date": "2026-04-08", + "summary": "新增 storage.stockout 出库单模块(非订单出库单能力)", + "methods": [ + "storage.stockout.list", + "storage.stockout.toOrder", + "storage.stockout.listItems" + ], + "notes": [ + "新增 storage.stockout.list / toOrder / listItems 接口,作为非订单出库单的主出口(对应奇门 stockout.create)。storage.delivery.* 仅作为兼容转发保留;底层 部分能力仍复用 order 模块。" + ], + "type": "add", + "module": "storage" + }, + { + "version": "2026.04.08-system-21", + "date": "2026-04-08", + "summary": "将 storage.stockout.toOrder 标记为占位接口", + "methods": [ + "storage.stockout.toOrder" + ], + "notes": [ + "storage.stockout.toOrder 当前仅保留方法名用于后续扩展,暂不开放实际逻辑。调用时返回 code=405、message=占位接口,暂未开放。" + ], + "type": "change" + }, + { + "version": "2026.04.09-system-01", + "date": "2026-04-09", + "summary": "storage.entry.cancel 支持批量作废,新增 ids 入参并兼容单条 id", + "methods": [ + "storage.entry.cancel" + ], + "notes": [ + "新增入参 `ids`(number[])以支持批量作废,兼容旧入参 `id`;当同时传入 `ids` 与 `id` 时以 `ids` 为准。", + "参数校验:`ids` 必须为非空数组;非法 ID 或空数组返回 400。", + "业务约束:已完成/已作废/处于不可作废状态的单据不允许作废;批量场景下任一 单据不存在或状态不允许时整体返回 404/400,未执行部分更新。", + "响应说明:单条作废返回字段 `id`(number);批量作废返回字段 `ids`(number[])。", + "已同步更新 methods/system.json(storage.entry.cancel)为 SSOT。" + ] + }, + { + "version": "2026.04.09-system-02", + "date": "2026-04-09", + "summary": "新增基础模块车牌识别接口 index.recognizeLicensePlate", + "methods": [ + "index.recognizeLicensePlate" + ], + "notes": [ + "入参:base64(string,必填)或 imageBase64/image_base64(兼容)", + "响应:返回归一化后的识别对象,包含 licensePlate、plateNumber、color、confidence、requestId、imageSize、rawData", + "错误:400(参数或图片格式/尺寸问题),500(第三方 OCR 调用失败或云密钥未 配置)", + "文档中不包含任何敏感配置;实际腾讯云密钥保留在配置文件中,勿在文档中暴露 。" + ], + "type": "added" + }, + { + "version": "2026.04.09-system-03", + "date": "2026-04-09", + "summary": "收紧基础模块车牌识别接口响应,仅返回 licensePlate 字段", + "methods": [ + "index.recognizeLicensePlate" + ], + "notes": [ + "出参由 {licensePlate, plateNumber, color, confidence, requestId, imageSize, rawData} 调整为 {licensePlate}", + "调用方请仅依赖 licensePlate 字段以适配新版本;历史字段已裁剪且不再保证存 在。", + "文档中未包含任何云密钥或敏感配置信息。" + ], + "type": "changed" + }, + { + "version": "2026.04.10-system-01", + "date": "2026-04-10", + "summary": "订单审核字段由 audit_status 替换为整数字段 step,并添加数据库迁移", + "methods": [ + "order.getreviewOrderlist", + "order.reviewOrder.getreviewOrderlist", + "order.reviewOrder.reviewOrder", + "order.deliveryOrder.getdeliveryOrderlist", + "order.list", + "order.stats" + ], + "notes": [ + "字段变更:order 相关审核字段从字符串/枚举 audit_status 替换为整数 step。", + "step 映射:0=未审核,1=已审核,2=处理中,3=驳回/异常,4=配送中,5=已完成,9=已关闭。", + "reviewOrder 接口在更新 inspection_status 的同时会写入 step 字段。", + "必须执行迁移脚本:20260410150000-replace-audit-status-with-step-on-order-delivery-tables.js" + ], + "type": "changed" + }, + { + "version": "2026.04.13-system-02", + "date": "2026-04-13", + "summary": "stock.warehouse.search 返回新增效期管理字段并保留 is_shelf_life_mgmt", + "methods": [ + "stock.warehouse.search" + ], + "notes": [ + "响应 data[] 中新增字段:inbound_min_days、outbound_min_days、shelf_life_days、remaining_threshold_days(均为 number,单位:天)。", + "保留并说明 is_shelf_life_mgmt 布尔字段(boolean),表示是否启用效期管理(true=启用)。", + "仅更新文档(methods/system.json 与变更记录),代码行为不变。" + ], + "type": "updated" + }, + { + "version": "2026.04.13-system-02", + "date": "2026-04-13", + "summary": "新增 storage.expiry.list 库存有效期列表查询接口", + "methods": [ + "storage.expiry.list" + ], + "notes": [ + "该接口查询 wms_storage,关联 stockWarehouse 和 locationSpace,并按当前仓库与 remaining_threshold_days / expiry_date 过滤。" + ], + "type": "added" + }, + { + "version": "2026.04.13-system-03", + "date": "2026-04-13", + "summary": "新增 storage.inventory.list 库存列表返回效期字段与预警标记", + "methods": [ + "storage.inventory.list" + ], + "notes": [ + "库存列表响应增加生产日期、过期日期、效期预警是否触发字段", + "预警标记仅在商品启用保质期管理且到期日满足阈值条件时为 true" + ], + "type": "updated" + }, + { + "version": "2026.04.14-system-01", + "date": "2026-04-14", + "summary": "更新 index.searchSpace 文档", + "methods": [ + "index.searchSpace" + ], + "notes": [ + "补充 index.searchSpace 的 params/response,按 ctx.user.store_id 作为仓库上下文;keyword 为可选字符串,对 space_code 与 custom_barcode 做 %keyword% 模糊匹配;返回字段 id、space_code、custom_barcode、custom_name,最多 50 条;仅文档同步,无代码变更。" + ], + "type": "updated" + }, + { + "version": "2026.04.16-system-01", + "date": "2026-04-16", + "summary": "基础模块新增快递产品类型查询接口", + "methods": [ + "index.getExpressProductTypeList" + ], + "notes": [ + "新增 index.getExpressProductTypeList,归属基础模块(module=index),用于查询指定快递公司的产品类型列表。", + "对应服务实现:app/service/systems/express.js 中的 getExpressProductTypeList,支持传入 express_code 作为可选筛选参数(source=body)。", + "接口设置为免鉴权(isNeedAuth=false)但需登录(isNeedLogin=true),与 index.getExpressList / index.getPlatformList 一致,优先从缓存读取。" + ], + "type": "added" + }, + { + "version": "2026.04.17-system-01", + "date": "2026-04-17", + "summary": "新增快递管理模块(setting.express)及 5 个接口文档", + "methods": [ + "setting.express.list", + "setting.express.listBase", + "setting.express.create", + "setting.express.checkCodeUnique", + "setting.express.update" + ], + "notes": [ + "新增独立模块组:快递管理模块(module=setting.express),将快递映射管理相关接口独立为一组以便维护。", + "接口实现参考:app/service/systems/setting/express.js(返回结构)与 app/service/systemMethods/setting/express.js(对外方法包装)。", + "接口鉴权与上下文:isNeedAuth=false, isNeedLogin=true;需在请求中传入 Authorization 以携带登录上下文(用于获取当前仓库/货主上下文)。", + "已同步更新 methods/system.json,补充 params/response/errors,保持文档与实现一致。" + ], + "type": "added" + }, + { + "version": "2026.04.17-system-02", + "date": "2026-04-17", + "summary": "setting.express.list 分页入参统一为 pagination", + "methods": [ + "setting.express.list" + ], + "notes": [ + "将 setting.express.list 的分页入参文档从顶层 page/page_size/pageSize 迁移为 pagination 对象,主形态为 pagination;兼容 snake_case 的 page_size 与 camelCase 的 pageSize。", + "文档与当前实现一致:顶层 page/page_size/pageSize 会被归一化到 data.pagination 并转发到系统服务。" + ], + "type": "updated" + }, + { + "version": "2026.04.17-system-03", + "date": "2026-04-17", + "summary": "新增快递接口管理模块(setting.expressInterface)及 4 个接口文档", + "methods": [ + "setting.expressInterface.list", + "setting.expressInterface.create", + "setting.expressInterface.update", + "setting.expressInterface.delete" + ], + "notes": [ + "新增独立模块组:快递接口管理模块(module=setting.expressInterface),对应实现:app/service/systems/setting/expressInterface.js 与对外包装 app/service/systemMethods/setting/expressInterface.js。", + "接口为当前仓库范围(基于 ctx.user.store_id),仓库边界由系统服务强制校验;禁止通过接口指定 warehouse_id/warehouseId。操作需登录(isNeedLogin=true),无需额外鉴权(isNeedAuth=false)。", + "已在 methods/system.json 新增对应接口的 params/response/errors 文档,保持与实现一致。" + ], + "type": "added" + }, + { + "version": "2026.04.18-system-01", + "date": "2026-04-18", + "summary": "补充订单储位分配接口文档:order.storageAllocation.allocateStorage", + "methods": [ + "order.storageAllocation.allocateStorage" + ], + "notes": [ + "新增 order.storageAllocation.allocateStorage:按订单批量分配储位,支持多种入参别名(order_ids/ids/orderId 等)与仓库上下文优先级。", + "响应包含 requested_order_ids, pending_order_ids, allocated_order_ids, shortage_order_ids, skipped_orders, picking_count, stock_lock_summary, storage_lock_summary 等字段,用于前端展示分配结果与不足提示。" + ], + "type": "added" + }, + { + "version": "2026.04.18-system-02", + "date": "2026-04-18", + "summary": "新增 order.pendingOrder.allocateExpressCode:待处理订单模块的批量分配首单快递号(异步接口),复用 express.createWaybillCodePipeline。", + "methods": [ + "order.pendingOrder.allocateExpressCode" + ], + "notes": [ + "异步接口:调用后立即返回 task_id,后台执行运单创建,通过 allocateExpressCodeTaskProgress 查询进度。", + "入参为 ids(订单 ID 数组),sys_platform_code/logistics_code 等由后端从数据库读取。", + "拆单场景请使用 order.pendingOrder.allocateSubOrderNumber。" + ], + "type": "added" + }, + { + "version": "2026.04.18-system-03", + "date": "2026-04-18", + "summary": "将 order.storageAllocation.allocateStorage 迁移到 order.pendingOrder.allocateStorage,并移除原有公开分组。", + "methods": [ + "order.pendingOrder.allocateStorage" + ], + "notes": [ + "将对外入口从 order.storageAllocation.allocateStorage 迁移到 order.pendingOrder.allocateStorage,旧的 order.storageAllocation 分组已从 methods/system.json 中移除。", + "新的对外接口不接受 warehouse_id / warehouseId,仓库上下文由当前登录用户(ctx.user.store_id)提供。", + "本次变更仅同步文档位置与对外方法名,底层实现保留且通过新的 system 方法暴露。" + ], + "type": "changed" + }, + { + "version": "2026.04.19-system-02", + "date": "2026-04-19", + "summary": "新增待处理模块取消分配储位接口 order.pendingOrder.cancelAllocateStorage", + "methods": [ + "order.pendingOrder.cancelAllocateStorage" + ], + "notes": [ + "新增待处理模块取消分配储位接口 `order.pendingOrder.cancelAllocateStorage`,直接对接 `service.systems.orderStorageAllocation.cancelAllocateStorage` 实现。", + "接口现在仅接受订单ID(order_ids),不再接受 allow_storage_location;禁止传入 `warehouse_id/warehouseId`,仓库上下文由当前登录用户的 `store_id` 提供。", + "响应返回标准 { flag, code, message, data } 结构,data 包含取消分配的汇总结果(warehouse_id, requested_order_ids, cancellable_order_ids, skipped_orders, orders, picking_count, storage_unlock_summary, stock_unlock_summary)。" + ], + "type": "added" + }, + { + "version": "2026.04.21-system-01", + "date": "2026-04-21", + "summary": "新增 order.pendingOrder.updateOrderPlatform 方法:批量修改待处理订单平台信息", + "methods": [ + "order.pendingOrder.updateOrderPlatform" + ], + "notes": [ + "通过 code 查找 wms_platform,平台不存在时返回 404 错误。", + "仅操作当前仓库的当前订单表。", + "noNeedRight=true,noNeedAuth=true(isNeedAuth: true 在 spec 中对应权限配置 noNeedAuth=true)。" + ], + "type": "added" + }, + { + "version": "2026.04.21-system-02", + "date": "2026-04-21", + "summary": "新增方法 order.pendingOrder.updateOrderExpress:批量修改待处理订单的快递信息", + "methods": [ + "order.pendingOrder.updateOrderExpress" + ], + "notes": [ + "新增 order.pendingOrder.updateOrderExpress:批量修改待处理订单的快递信息,按 express_code 从仓库快递列表(带缓存)匹配快递项。", + "自定义映射(is_system_setting=true)时,sys_logistics_code/name 写入系统快递编码和名称,logistics_code/name 写入自定义编码和名称;系统快递(is_system_setting=false)时四个字段均写系统快递的 code/name。", + "只操作当前仓库的当前订单表,不处理其他订单表;操作后写入操作日志(ORDER_UPDATE_EXPRESS)。" + ], + "type": "added" + }, + { + "version": "2026.04.21-system-03", + "date": "2026-04-21", + "summary": "新增 order.expectionOrder.resolveException:将待处理异常订单转回正常待处理状态", + "methods": [ + "order.expectionOrder.resolveException" + ], + "notes": [ + "新增 order.expectionOrder.resolveException:批量将 step=3 的异常订单恢复为 step=2 正常待处理状态。", + "入参 ids 为订单ID 正整数数组,不能为空;仅操作当前仓库当前订单表。", + "返回 updated_count(实际更新行数)与 ids(本次操作ID列表)。", + "权限配置:noNeedLogin=false、noNeedRight=true、noNeedLog=false、noNeedAuth=true" + ], + "type": "added" + }, + { + "version": "2026.04.21-system-04", + "date": "2026-04-21", + "summary": "新增 order.pendingOrder.cloneOrder 方法:克隆待处理订单", + "methods": [ + "order.pendingOrder.cloneOrder" + ], + "notes": [ + "支持对 step 0/1/2/3 的待处理订单进行克隆操作。", + "若原订单已分配储位(storage_status=fin),克隆前自动清除已分配库存。", + "原订单取消后(step→9, status→cancel),以原订单业务数据创建新订单,流程状态字段全部重置为初始落库状态。", + "克隆订单明细含 stock_id,新订单 ID 重新绑定。", + "noNeedAuth=true,noNeedRight=true,noNeedLogin=false。" + ], + "type": "added" + }, + { + "version": "2026.04.21-system-06", + "date": "2026-04-21", + "summary": "新增 order.pendingOrder.createOrder:手动创建待处理/待审核订单", + "methods": [ + "order.pendingOrder.createOrder" + ], + "notes": [ + "新增 order.pendingOrder.createOrder:手动创建订单,step 由货主策略 need_order_approval 决定(1→待审核 step=0,0→待处理 step=1)。", + "必填字段:store_id、name、mobile/tel 至少一项、detail_address、items[](含 item_code 和 plan_qty)。", + "delivery_order_code 不传则自动生成(SYS+时间戳+随机4位);logistics_code/sys_platform_code 不传则读货主合约策略 default_express_code/default_platform_code。", + "不做库存锁定,储位分配为独立步骤。操作日志写入 ORDER_CREATE。", + "noNeedRight=true,noNeedAuth=true,noNeedLogin=false。" + ], + "type": "added" + }, + { + "version": "2026.04.21-system-07", + "date": "2026-04-21", + "summary": "新增 Excel 模板下载与批量导入创建订单接口:order.pendingOrder.downloadCreateTemplate 和 order.pendingOrder.importOrdersFromExcel", + "methods": [ + "order.pendingOrder.downloadCreateTemplate", + "order.pendingOrder.importOrdersFromExcel" + ], + "notes": [ + "新增 order.pendingOrder.downloadCreateTemplate:生成 Excel 导入模板,返回 base64 编码的 xlsx 文件,表头中带 * 的列为必填项(橙色背景),可选列为灰色背景,含示例数据行和填写说明工作表。", + "新增 order.pendingOrder.importOrdersFromExcel:接受 base64 编码的 xlsx 文件,按订单号分组,每组调用 createOrder 逻辑创建订单;不中断执行,逐条记录成功/失败结果返回。", + "多行相同订单号的行组成一个完整订单,每行代表一条商品明细;订单头信息(收件人、地址等)取每组第一行。", + "step 由货主策略 need_order_approval 决定(与 createOrder 一致);通过事务保证每个订单的主记录与明细原子写入。" + ], + "type": "added" + }, + { + "version": "2026.05.01-system-01", + "date": "2026-05-01", + "summary": "新增基础模块 IM 登录码接口文档:index.loginToIm", + "methods": [ + "index.loginToIm" + ], + "notes": [ + "新增 index.loginToIm 文档,入参为空对象({}),依赖当前登录用户上下文生成一次性 code。", + "响应增加 data.code 字段,长度固定 64 位(hex),默认有效期 5 分钟。", + "错误码补充:401(用户未登录)、400(用户信息不完整,缺 employees_id 或 employees_name)。", + "该接口仅做登录码签发,实际换取员工信息由 IM 侧 ssoCodeToId 完成并在成功后使 code 失效。" + ], + "type": "added" + }, + { + "version": "2026.05.01-system-03", + "date": "2026-05-01", + "summary": "扩展 index.loginToIm 返回字段:增加主体/主体类型/头像信息", + "methods": [ + "index.loginToIm" + ], + "notes": [ + "登录码签发接口响应新增 employees_id、employees_name、subject、store_type、avatar 字段。", + "subject 包含 id/name;store_type 严格取自 wms_store.project 字段,不再返回 subject_type 兼容字段。", + "同一批字段会写入 code 缓存,供 IM 侧 ssoCodeToId 换取并在成功后失效。" + ], + "type": "updated" + }, + { + "version": "2026.05.01-system-04", + "date": "2026-05-01", + "summary": "index.loginToIm 与 ssoCodeToId 改为严格字段模式,不再做兼容回退", + "methods": [ + "index.loginToIm" + ], + "notes": [ + "loginToIm 仅读取 ctx.user 标准字段:employees_id、employees_name、store_id、store_name、store_type、avatar。", + "不再兼容 id/real_name/username/company_name/avatar_url 等历史字段。", + "ssoCodeToId 返回值不再使用默认兜底,缺少关键字段时按 code 无效处理。" + ], + "type": "updated" + }, + { + "version": "2026.05.03-system-01", + "date": "2026-05-03", + "summary": "将 order.wave.fetch 调整为异步任务提交接口,删除同步返回抓取结果字段", + "methods": [ + "order.wave.fetch" + ], + "notes": [ + "接口从同步返回抓取结果改为提交任务并异步处理。", + "移除原方法中 result_list / total_request_quantity / total_fetched_quantity 等同步返回字段。" + ], + "type": "updated" + }, + { + "version": "2026.05.03-system-06", + "date": "2026-05-03", + "summary": "order.wave.batchList:新增 where 支持并限制传入字段", + "methods": [ + "order.wave.batchList" + ], + "notes": [ + "batchList 新增 where 支持及白名单过滤;禁止传入 warehouse_id/warehouseId。" + ], + "type": "updated" + }, + { + "version": "2026.05.03-system-08", + "date": "2026-05-03", + "summary": "order.pendingOrder.allocateStorage 改为异步提交", + "methods": [ + "order.pendingOrder.allocateStorage" + ], + "notes": [ + "接口变更为异步提交:调用后立即返回 request_id,后端异步执行储位分配;接口不再在响应中同步返回分配明细(如 requested_order_ids、allocated_order_ids 等)。客户端可后续通过任务 ID / 查询链路或事件获取最终分配结果。" + ], + "type": "updated" + }, + { + "version": "2026.05.03-system-10", + "date": "2026-05-03", + "summary": "新增订单批量移出波次接口", + "methods": [ + "order.wave.batchRemoveOrders" + ], + "notes": [ + "按订单ID批量移出波次;仅处理待处理订单表中非待审核订单(step in [1,2,3])。", + "操作在单事务内完成:清空订单的 wave_id/wave_no,并回写 wms_wave_batch 统计(重算 total_orders;当波次被清空时将 wave_status 置为 -1)。", + "仓库上下文来自当前登录用户(ctx.user.store_id)。" + ], + "type": "updated" + }, + { + "version": "2026.05.08-system-05", + "date": "2026-05-08", + "summary": "order.wave.batchList:新增 source 字段并支持 where.source 过滤,返回 list item 中新增 source 字段", + "methods": [ + "order.wave.batchList" + ], + "notes": [ + "新增 where.source(可选,number)用于按来源过滤:0=普通波次(正常后台操作),1=管理后台策略任务,2=PDA策略任务;不传则不过滤。", + "响应 list 每条记录新增字段 source(number),用于区分波次来源。", + "仅更新文档,业务代码不在此变更范围。" + ], + "type": "updated" + }, + { + "version": "2026.05.09-system-01", + "date": "2026-05-09", + "summary": "新增 order.wave.wavePickTaskCancelSelf;order.wave.waveStrategyList 新增预演计数字段/参数", + "methods": [ + "order.wave.wavePickTaskCancelSelf", + "order.wave.waveStrategyList" + ], + "notes": [ + "新增接口 `order.wave.wavePickTaskCancelSelf`:仅支持单个 `task_id`(number,必填),明确不支持 `task_ids` 批量参数。", + "业务约束:仅允许取消当前登录用户本人创建的拣货任务;若尝试取消非本人创建任务,接口应返回 400 错误(仅允许取消本人创建任务)。", + "返回建议:与现有取消接口风格一致,包含 `cancelled_count`(0/1)、`task_id`、`task_no`(若后端返回)或相应的取消结果汇总。", + "错误码建议:400 参数不合法(task_id 缺失或传了 task_ids);400 仅允许取消本人创建任务;500 取消失败。", + "新增参数:calculate_next_fetch_order_count(number,可选),含别名 calculateNextFetchOrderCount;取值 0=不计算(默认),1=计算并返回每条策略的 next_fetch_order_count,用于前端在策略列表中预览抓取量。", + "新增响应字段:list[*].next_fetch_order_count(number),含义:按当前策略口径预演一次自动抓取时,预计会选中的订单数量;当未开启计算时返回 0。" + ], + "type": "added" + }, + { + "version": "2026.05.11-system-01", + "date": "2026-05-11", + "summary": "新增字段 wave_prefix(策略层波次前缀),并补充 PDA 抓取波次号生成行为说明", + "methods": [ + "order.wave.waveStrategyList", + "order.wave.waveStrategyCreate", + "order.wave.waveStrategyUpdate", + "order.wave.waveStrategyFetchPda" + ], + "notes": [ + "在 wave strategy 对象中新增可选字段 wave_prefix:策略波次前缀,优先于仓库前缀。", + "校验规则:长度 1-5,仅允许 A-Z0-9;保存时会转为大写;为空时回退仓库前缀:团购使用 group_wave_prefix,散单使用 delete_order_wave_prefix。", + "在 order.wave.waveStrategyList 的返回 list[*] 中新增字段 wave_prefix(string)。", + "在 order.wave.waveStrategyCreate / waveStrategyUpdate 的入参中新增可选字段 wave_prefix(string),创建/更新成功后保存为大写且触发策略版本推进。", + "在 order.wave.waveStrategyFetchPda 的行为说明中补充:生成波次号(wave_no)时优先使用策略层 wave_prefix,否则按策略类型回退到仓库前缀;前缀校验同上。" + ], + "type": "updated" + }, + { + "version": "2026.05.15-system-01", + "date": "2026-05-15", + "summary": "仅更新文档:将 setting.express.create 入参与实现对齐(新增 express_code,移除 platform)", + "methods": [ + "setting.express.create" + ], + "notes": [ + "仅同步文档,与实现对齐,未修改任何业务代码或行为" + ], + "type": "updated" + }, + { + "version": "2026.05.15-system-02", + "date": "2026-05-15", + "summary": "新增 storage.report.search:库存流水统计报表,支持按时间闭区间过滤与按库位/按商品聚合", + "methods": [ + "storage.report.search" + ], + "notes": [ + "方法新增:storage.report.search", + "时间过滤为闭区间:created_at >= start_time 且 created_at <= end_time", + "当 where.by_space 为 false(默认)时,按商品+货主聚合(多个库位汇总);当为 true 时按商品+库位返回", + "不返回无流水的商品/键(仅返回在查询区间内出现过流水的数据)" + ], + "type": "added" + }, + { + "version": "2026.05.15-system-03", + "date": "2026-05-15", + "summary": "库存报表模块主入口迁移到 stock.report.search,storage.report.search 保持兼容别名", + "methods": [ + "stock.report.search", + "storage.report.search" + ], + "notes": [ + "新增主入口方法 stock.report.search,沿用既有报表统计口径(时间闭区间、by_space/store_ids、返回字段保持一致)。", + "保留 storage.report.search 作为兼容别名,并在描述中明确建议迁移到 stock.report.search。", + "仅更新 methods 文档配置,不修改业务代码。" + ], + "type": "updated" + }, + { + "version": "2026.05.15-system-04", + "date": "2026-05-15", + "summary": "文档主入口统一为 stock.report.search,storage.report.search 调整为兼容别名简述", + "methods": [ + "stock.report.search", + "storage.report.search" + ], + "notes": [ + "保留 stock.report.search 作为库存报表唯一完整文档入口。", + "storage.report.search 不再维护完整重复字段,仅保留迁移与兼容说明。", + "仅更新 methods 文档配置,不修改业务代码。" + ], + "type": "updated" + }, + { + "version": "2026.05.15-system-05", + "date": "2026-05-15", + "summary": "拆分 storage.report 模块并移除错误 stock.report.search 文档入口", + "methods": [ + "storage.report.search", + "stock.report.search" + ], + "notes": [ + "将库存报表从 storage.inventory 中拆分为独立模块 storage.report,storage.report.search 文档改为主入口语义(不再作为兼容别名)。", + "从 storage.inventory 分组中移除错误的 stock.report.search 文档入口以及兼容别名条目 storage.report.search。", + "最终归属:storage.report.search 属于模块 storage.report;stock.report.search 的文档入口已移除以避免混淆(代码实现保留于 app/service/systemMethods/storage/report.js 的 storage.report.search)。", + "仅修改文档,不修改应用代码实现。" + ], + "type": "updated" + }, + { + "version": "2026.05.15-system-06", + "date": "2026-05-15", + "summary": "storage.report.search 新增排序能力文档说明", + "methods": [ + "storage.report.search" + ], + "notes": [ + "补充 sort 参数:支持 sortField/sort_field、sortOrder/sort_order。", + "补充排序白名单:begin_total、inbound_total、outbound_total、end_total。", + "补充非法排序字段/顺序回退默认排序说明。", + "响应说明补充:已按 sort 规则排序返回。" + ], + "type": "updated" + }, + { + "version": "2026.05.16-system-01", + "date": "2026-05-16", + "summary": "新增 storage.report.export:按与 storage.report.search 相同条件导出库存报表 Excel", + "methods": [ + "storage.report.export" + ], + "notes": [ + "新增方法:storage.report.export,复用 storage.report.search 的 where/sort 查询条件。", + "导出文件包含两个 sheet:汇总、变更记录。", + "用于在统计结果基础上回溯明细流水,提升库存变动追溯效率。" + ], + "type": "added" + }, + { + "version": "2026.05.16-system-02", + "date": "2026-05-16", + "summary": "storage.report.export 改为异步任务 + 新增 exportTaskProgress", + "methods": [ + "storage.report.export", + "storage.report.exportTaskProgress" + ], + "notes": [ + "调用方式调整为两步:先调用 storage.report.export 提交任务并获取 task_id,再调用 storage.report.exportTaskProgress 轮询任务进度。", + "下载链接获取方式:当 status=success 时,从 exportTaskProgress 响应的 download_url 字段获取导出文件地址。", + "任务状态值补充:submitted/running/success/failed/not_found。" + ], + "type": "updated" + }, + { + "version": "2026.05.16-system-03", + "date": "2026.05.16", + "summary": "同步 setting.expressInterface.create/update 入参与系统快递编码映射规则", + "methods": [ + "setting.expressInterface.create", + "setting.expressInterface.update" + ], + "notes": [ + "补充入参:sys_express_code、weight_type、address、town_name、ispickup、shipperno,并保留既有字段。", + "在参数说明补充 camelCase 别名支持:sysExpressCode、weightType、townName、isPickup、shipperNo 等。", + "同步约束变化:不再因同仓快递编码重复或平台重复直接返回 409;当 express_code 无法匹配系统快递编码时返回 400,文案为 express_code 未匹配到系统快递编码。" + ], + "type": "updated" + }, + { + "version": "2026.05.17-system-05", + "date": "2026-05-17", + "summary": "同步 storage.receiving.addDetail 的参数与返回值(从实现提取)", + "methods": [ + "storage.receiving.addDetail" + ], + "notes": [ + "补充 receiving_id 入参说明", + "补充返回的 details 数组与 selectId 字段", + "补充可能的错误码:404/400/500" + ], + "type": "updated" + }, + { + "version": "2026.05.17-system-06", + "date": "2026-05-17", + "summary": "重新同步 addDetail 文档", + "methods": [ + "storage.receiving.addDetail" + ], + "notes": [ + "再次从实现代码核对并补充参数/返回值/错误码,确保文档与实现一致", + "仅同步文档,不修改业务代码" + ], + "type": "updated" + }, + { + "version": "2026.05.17-system-07", + "date": "2026-05-17", + "summary": "addDetail 新增可选 item 入参并兼容空白创建链路", + "methods": [ + "storage.receiving.addDetail" + ], + "notes": [ + "item 有值时按传入字段创建(服务端覆盖 receiving_id 与 creator_id)", + "兼容不传 item 的空白创建链路;item.children 需覆盖关键字段(有则写、无则补齐)。" + ], + "type": "updated" + }, + { + "version": "2026.05.17-system-10", + "date": "2026-05-17", + "summary": "调整 storage.receiving.getReceivingDetail 库位字段输出语义:space_id 改为展示名称并补充兼容字段", + "methods": [ + "storage.receiving.getReceivingDetail" + ], + "notes": [ + "将 receiving.details.*.space_id 定义为展示名称(string|null),优先 custom_space_name,其次 space_name,不再作为原始数值ID文档语义。", + "新增并明确 receiving.details.*.space_id_raw(number|null)用于保留原始库位ID,兼容旧调用方。", + "补充 receiving.details.*.space_name(库位名称/编码)与 receiving.details.*.custom_space_name(自定义名称,可空)字段说明。" + ], + "type": "updated" + }, + { + "version": "2026.05.17-system-11", + "date": "2026-05-17", + "summary": "补充 subject_config.enable_external_express_code 字段文档与默认值语义", + "methods": [ + "store.createStore", + "store.createWarehouse", + "setting.warehouse.getSettings", + "setting.warehouse.saveSettings" + ], + "notes": [ + "在 store.createStore 与 store.createWarehouse 的 subject_config 入参中新增字段:enable_external_express_code(boolean),默认 false;开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)。", + "此 change 同时用于说明将在 setting.warehouse.getSettings / saveSettings 中补充该字段的文档说明(后续 doc-only 写入)。" + ], + "type": "updated", + "module": "store" + }, + { + "version": "2026.05.17-system-12", + "date": "2026-05-17", + "summary": "storeWarehouse.store 策略配置文档新增 enable_external_express_code 字段说明(向后兼容)", + "methods": [ + "storeWarehouse.store.getPolicyConfig", + "storeWarehouse.store.savePolicyConfig" + ], + "notes": [ + "在 getPolicyConfig / savePolicyConfig 的出参说明中补充 data.policy_config.enable_external_express_code 字段,明确为 flag(0=关闭,1=开启),默认 0。", + "在 savePolicyConfig 的入参说明中补充 policy_config.enable_external_express_code 字段定义。", + "本次为向后兼容的文档增强:新增可选策略字段说明,不影响现有调用。" + ], + "type": "updated" + }, + { + "version": "2026.05.19-system-01", + "date": "2026-05-19", + "summary": "补充 storage.entry.list 的 expense_record 筛选语义与未迁移环境错误提示", + "methods": [ + "storage.entry.list" + ], + "notes": [ + "在 where 参数说明中补充 expense_record 字段语义(费用是否记录)及 eq/in 支持。", + "明确 true/false、1/0、y/n、yes/no 的归一化规则与等价写法示例。", + "补充未完成表结构迁移时可能返回 400 及错误提示文案。" + ], + "type": "updated" + }, + { + "version": "2026.05.20-system-01", + "date": "2026-05-20", + "summary": "同步 order.recheckOrder.scanOrder 返回结构,补充 cart_match_view 语义化视图说明", + "methods": [ + "order.recheckOrder.scanOrder" + ], + "notes": [ + "新增返回字段:match_type(waybill/cart)与 cart_match_view(仅 cart 命中返回)。", + "cart_match_view 包含通用子字段:mode_code / mode_name / view_type / task;当车号命中时按 pick_mode 返回语义化结构:mode 1/5 返回 groups,mode 2 返回 orders,mode 3 返回 pick_groups,mode 4 返回 box_groups。" + ], + "type": "updated" + }, + { + "version": "2026.05.22-system-01", + "date": "2026-05-22", + "summary": "新增 index.getPlatformOauthLink 文档,补充平台授权链接接口说明", + "methods": [ + "index.getPlatformOauthLink" + ], + "notes": [ + "入参支持 code、platform_code、platformCode 三种平台编码字段别名。", + "当前仅支持 PDD;成功返回 data.platform_code、data.oauth_link 和 code=200,其他平台返回 code=400。", + "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" + ], + "type": "added", + "module": "index" + }, + { + "version": "2026.05.22-system-02", + "date": "2026-05-22", + "summary": "更新 index.getPlatformOauthLink 文档,补充仓库上下文、预占记录与错误说明", + "methods": [ + "index.getPlatformOauthLink" + ], + "notes": [ + "补充真实行为:从 ctx.user.store_id 读取当前仓库 ID,从 wms_platform.auth_base_url 读取授权基础地址,并在 wms_shops 创建平台授权预占记录。", + "补充 oauth_link 细节:追加 client_id、redirect_uri(配置非空时)以及长查询参数 wms_authorization_reservation_code,对应唯一 auth_random_code。", + "补充常见错误:平台编码为空、仓库上下文缺失、平台不存在、授权基础地址缺失/格式错误、不支持的平台,以及预占记录创建失败。" + ], + "type": "updated", + "module": "index" + }, + { + "version": "2026.05.22-system-03", + "date": "2026-05-22", + "summary": "同步 index.getPlatformOauthLink 当前实现:裸码入库与 state 拼接规则", + "methods": [ + "index.getPlatformOauthLink" + ], + "notes": [ + "补充真实行为:从 ctx.user.store_id 读取当前仓库,从 wms_platform.auth_base_url 读取基础授权链接,并优先复用 wms_shops 中 status=0 的未授权记录。", + "明确 auth_random_code 当前以裸码保存;若复用到历史带前缀记录,会先去掉 platformOauthReservationCodePrefix 后再回写。", + "更新 oauth_link 说明:state 由“前缀 + 平台编码 + '_' + 裸码”组成并整体 URL 编码后直接拼接到基础授权链接后,例如 xxxxx_PDD_;同时移除已不存在的基础地址格式错误/不支持平台错误描述。" + ], + "type": "updated", + "module": "index" + }, + { + "version": "2026.05.22-system-04", + "date": "2026-05-22", + "summary": "修正 index.getPlatformOauthLink 文档中的残留平台限制描述", + "methods": [ + "index.getPlatformOauthLink" + ], + "notes": [ + "移除 index.getPlatformOauthLink 参数与返回字段中残留的“当前仅支持 PDD”描述,避免与当前实现不一致。", + "保留授权链接仅依赖平台已配置基础授权链接模式的说明,不再把示例平台编码误写成实现限制。" + ], + "type": "updated", + "module": "index" + }, + { + "version": "2026.05.22-system-05", + "date": "2026-05-22", + "summary": "新增 index.getShopList 文档,并同步 custom_name 与店铺列表脱敏返回规则", + "methods": [ + "index.getShopList" + ], + "notes": [ + "新增 index.getShopList:接口依赖当前登录仓库上下文 ctx.user.store_id,不接受额外业务入参,缺少仓库时返回 400:未识别到当前仓库。", + "补充真实返回结构:data.list 为数组,包含 id、warehouse_id、platform_code、shop_name、custom_name、status、auth_expire_at、token_expires_at、refresh_token_expires_at、scope、created_at、updated_at 以及脱敏后的 owner_id、access_token、refresh_token、auth_random_code。", + "同步脱敏规则:owner_id 非空且长度大于 5 时返回前 3 位 + *** + 后 2 位,长度小于等于 5 时返回 ***;access_token、refresh_token、auth_random_code 非空时固定返回 ***,空值返回 null。", + "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改任何业务代码。" + ], + "type": "added", + "module": "index" + }, + { + "version": "2026.05.22-system-06", + "date": "2026-05-22", + "summary": "新增 index.getShopExpressList 文档,补充店铺快递列表统一返回结构", + "methods": [ + "index.getShopExpressList" + ], + "notes": [ + "按 ctx.user.store_id 校验店铺归属,仅允许查询当前登录仓库下的店铺。", + "服务端按店铺所属平台拉取并收敛快递签约/电子面单可用列表,统一返回前端消费结构。", + "未接入平台当前返回空列表;若店铺缺少授权 access_token,则返回 400:店铺未授权。", + "仅文档同步,不改业务代码。" + ], + "type": "added", + "module": "index" + }, + { + "version": "2026.05.22-system-07", + "date": "2026-05-22", + "summary": "同步快递接口文档:is_share 仅展示不可编辑", + "methods": [ + "setting.expressInterface.list", + "setting.expressInterface.create", + "setting.expressInterface.update" + ], + "notes": [ + "create/update 不再接受 is_share", + "list 仍可返回 is_share 作为展示信息", + "仅文档同步,不改业务代码" + ], + "type": "updated", + "module": "setting.expressInterface" + }, + { + "version": "2026.05.22-system-08", + "date": "2026-05-22", + "summary": "同步快递接口列表文档,移除未返回字段说明", + "methods": [ + "setting.expressInterface.list" + ], + "notes": [ + "根据 app/service/systems/setting/expressInterface.js 的 list() 查询字段与 normalizeInterfaceRow() 返回结构,同步 setting.expressInterface.list 不返回 token。", + "按当前实现清理 response.children 中未返回的 share_id、can_use_count 字段说明。", + "保留 is_share,并明确其仅用于展示,不作为编辑入参。" + ], + "type": "updated", + "module": "setting.expressInterface" + }, + { + "version": "2026.05.22-system-09", + "date": "2026-05-22", + "summary": "index.getShopList 支持按平台编码筛选店铺", + "methods": [ + "index.getShopList" + ], + "notes": [ + "index.getShopList 兼容 platform_code 与 platformCode 两种传参方式,服务端按 platform_code、platformCode 顺序读取首个 trim 后非空值作为平台筛选条件。", + "未传平台参数时返回当前登录仓库下全部已授权店铺;传入非空平台编码时仅返回该平台的已授权店铺。", + "本次仅补充筛选条件文档,不影响返回结构、排序规则与 owner_id/access_token/refresh_token/auth_random_code 的脱敏规则。", + "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改任何业务代码。" + ], + "type": "updated", + "module": "index" + }, + { + "version": "2026.05.22-system-10", + "date": "2026-05-22", + "summary": "快递接口配置新增 shop_id 字段", + "methods": [ + "setting.expressInterface.create", + "setting.expressInterface.update", + "setting.expressInterface.list" + ], + "notes": [ + "create/update 支持 shop_id/shopId(兼容 snake_case 与 camelCase),为店铺 ID,未传或空值按 null 处理。", + "list 返回 shop_id 字段,列表 where 支持按 shop_id 过滤。" + ], + "type": "updated" + }, + { + "version": "2026.05.22-system-11", + "date": "2026-05-22", + "summary": "调整快递接口列表排序规则", + "methods": [ + "setting.expressInterface.list" + ], + "notes": [ + "setting.expressInterface.list 改为按 weight ASC, id DESC 排序;优先按权重排序,权重相同再按 id 倒序。", + "本次仅同步该接口排序说明,不影响返回结构。" + ], + "type": "updated", + "module": "setting.expressInterface" + }, + { + "version": "2026.05.22-system-12", + "date": "2026-05-22", + "summary": "index.getShopExpressList 返回新增系统快递编码", + "methods": [ + "index.getShopExpressList" + ], + "notes": [ + "data.list[*] 新增 sys_express_code 字段,由平台快递编码 wp_code 映射系统快递编码,未匹配时返回空字符串。", + "补充 data.list[*].wp_name 说明:由系统快递基础表根据平台快递编码映射得到名称,未匹配时返回空字符串。", + "原有请求参数、鉴权方式与返回主结构保持不变。", + "仅文档同步,不改业务代码。" + ], + "type": "updated", + "module": "index" + }, + { + "version": "2026.05.23-system-01", + "date": "2026-05-23", + "summary": "补充快递接口列表 is_system_express_code 返回字段说明", + "methods": [ + "setting.expressInterface.list" + ], + "notes": [ + "在 setting.expressInterface.list 的 response.children 中补充 is_system_express_code 字段说明。", + "该字段表示当前行 express_code 是否为系统快递编码;不是系统快递编码返回 0,否则返回 1。", + "仅文档同步,不改业务代码。" + ], + "type": "updated", + "module": "setting.expressInterface" + }, + { + "version": "2026.05.23-system-02", + "date": "2026-05-23", + "summary": "完善 index.getExpressList 文档:补充过滤规则、返回字段与仓库维度行为", + "methods": [ + "index.getExpressList" + ], + "notes": [ + "补充 `systemOnly`、`express_code`、`expressCode` 的真实入参语义,明确真值识别规则与字段优先级。", + "补充默认模式、系统模式、按快递编码过滤模式下的返回差异,说明当前登录仓库维度来自 `ctx.user.store_id`。", + "补充 `data[*]` 各字段含义,明确系统基础快递与仓库自定义快递编码的差异字段。", + "仅文档同步,不修改业务代码。" + ], + "type": "updated", + "module": "index" + }, + { + "version": "2026.05.24-system-01", + "date": "2026-05-24", + "summary": "同步 index.getExpressList 文档:移除 expressCode 别名并明确 express_code 筛选语义", + "methods": [ + "index.getExpressList" + ], + "notes": [ + "移除 index.getExpressList 文档中的 expressCode 驼峰别名参数,仅保留 express_code。", + "明确当 systemOnly=false 且传入 express_code 时,接口按自定义映射记录中的系统快递编码字段 express_code 过滤,而不是按自定义 code 过滤。", + "保留 systemOnly=true 按系统快递编码过滤系统基础快递列表,以及默认合并逻辑、缓存优先、仓库维度来源不变的说明。" + ], + "type": "updated" + }, + { + "version": "2026.05.24-system-02", + "date": "2026-05-24", + "summary": "新增 index.getCainiaoStfTemplates 接口文档并明确模板返回语义", + "methods": [ + "index.getCainiaoStfTemplates" + ], + "notes": [ + "新增无参接口 index.getCainiaoStfTemplates:从当前仓库首个已授权 TB 店铺发起 cainiao.waybill.ii.search 查询菜鸟 STF 模板。", + "补充返回结构说明:data.platform_code 固定为 TB;data.list 返回模板数组并包含 template_id/template_name/template_url/cp_code/wp_code 字段。", + "明确模板列表为宽松结构解析并按 template_id/template_name/template_url 核心语义去重。", + "补充错误码说明:未识别仓库返回 400;当前仓库无已授权 TB 店铺返回 404。" + ], + "type": "added" + }, + { + "version": "2026.05.24-system-03", + "date": "2026-05-24", + "summary": "调整 index.getCainiaoStfTemplates 为免登录/免鉴权接口", + "methods": [ + "index.getCainiaoStfTemplates" + ], + "notes": [ + "将 index.getCainiaoStfTemplates 的 isNeedLogin 调整为 false,接口改为免登录访问。", + "保持 isNeedAuth=false,并同步免权限拦截配置,避免登录态与鉴权拦截。", + "该接口仍为无请求参数,headers 调整为空数组。" + ], + "type": "updated", + "module": "index" + }, + { + "version": "2026.05.24-system-04", + "date": "2026-05-24", + "summary": "调整 index.getCainiaoStfTemplates 为公共无参模板查询接口", + "methods": [ + "index.getCainiaoStfTemplates" + ], + "notes": [ + "index.getCainiaoStfTemplates 改为公共无参查询,不再依赖当前仓库、登录态或店铺授权。", + "接口直接调用 requestTbWaybillSearch({ cpCode: '' }) 查询公共模板,返回 data.platform_code='TB' 与模板数组。", + "requestTbWaybillSearch 支持 accessToken 缺失时不下发 session,因此该接口不再依赖 session。" + ], + "type": "updated" + }, + { + "version": "2026.05.24-system-05", + "date": "2026-05-24", + "summary": "同步 index.getCainiaoStfTemplates 改用淘宝标准模板公共接口", + "methods": [ + "index.getCainiaoStfTemplates" + ], + "notes": [ + "index.getCainiaoStfTemplates 改为调用淘宝开放平台 cainiao.cloudprint.stdtemplates.get,不再复用 cainiao.waybill.ii.search。", + "接口不需要用户授权,不下发 session,继续使用 https://eco.taobao.com/router/rest 与 TOP 公共签名参数。", + "模板列表改为从 cainiao_cloudprint_stdtemplates_get_response.result.datas[*].standard_templates[*] 做宽松兼容解析,统一返回 template_id/template_name/template_url/cp_code/wp_code。" + ], + "type": "updated" + }, + { + "version": "2026.05.24-system-06", + "date": "2026-05-24", + "summary": "新增 index.getPrintPlatformList 接口文档并明确打印平台下拉返回结构", + "methods": [ + "index.getPrintPlatformList" + ], + "notes": [ + "新增 index.getPrintPlatformList 文档,说明该接口供快递接口新增/编辑页下拉选择使用。", + "补充接口行为:仅返回未删除且状态为 ACTIVE 的打印平台,不分页,按 platform_name 与 id 升序返回。", + "补充 data[*] 返回字段说明,明确 code/name/value/label/platform_code/platform_name/status/remark 的含义。", + "仅文档同步,不修改业务代码。" + ], + "type": "added", + "module": "index" + }, + { + "version": "2026.05.24-system-07", + "date": "2026-05-24", + "summary": "新增 index.getPrintPlatformTemplateList 文档,明确 express_code 必填与模板过滤语义", + "methods": [ + "index.getPrintPlatformTemplateList" + ], + "notes": [ + "新增 index.getPrintPlatformTemplateList 方法文档,补充 platform_code 与 express_code 入参,其中 express_code 标记为必填。", + "明确业务语义:接口按 platform_code(默认 CAINIAO)定位 wms_express 中对应打印平台字段,并使用 express_code 过滤模板结果后返回。", + "补充返回结构 data.platform_code / data.express_code / data.responseData,说明未实现平台返回空对象。", + "仅文档同步,不修改业务代码。" + ], + "type": "added", + "module": "index" + }, + { + "version": "2026.05.25-system-01", + "date": "2026-05-25", + "summary": "新增 index.polyapiAuthorizeUrl 接口文档并标注免登录免鉴权特征", + "methods": [ + "index.polyapiAuthorizeUrl" + ], + "notes": [ + "新增基础模块方法 index.polyapiAuthorizeUrl,说明其为公共无参接口。", + "明确接口固定调用菠萝派 Differ.JH.BuildeAuthorizeUrl,返回体中以 data.respone 原样包裹上游响应。", + "同步标注 isNeedLogin=false、isNeedAuth=false,headers 为空数组。" + ], + "type": "added" + }, + { + "version": "2026.05.25-system-02", + "date": "2026-05-25", + "summary": "新增店铺模块相关接口文档(shops.list/add/del/edit)及授权会话接口 shops.GetAuthorizeSessionKey", + "methods": [ + "shops.list", + "shops.add", + "shops.del", + "shops.edit", + "shops.GetAuthorizeSessionKey" + ], + "notes": [ + "同步实现:shops.list 支持 where 分页与 quickWhere 快速搜索;shops.add/edit 校验 platform_code 存在且为 ACTIVE,custom_name 必填且长度限制;shops.del 为软删除,会返回 deleted=true 并清空敏感字段,若存在快递接口引用返回 409;shops.GetAuthorizeSessionKey 对 PDD/CAINIAO 平台生成预占码并返回 authorize_url,其他平台返回 501。", + "字段命名兼容说明:接口实现兼容 snake_case 与 camelCase 入参,文档以 snake_case 为主并注明兼容性。" + ], + "type": "added" + }, + { + "version": "2026.05.25-system-03", + "date": "2026-05-25", + "summary": "同步 shops.add 去入参化:移除 shop_name 入参并明确由授权后获取店铺名称", + "methods": [ + "shops.add" + ], + "notes": [ + "shops.add 入参移除 shop_name(及同义传参语义),仅保留 custom_name 与 platform_code 为关键请求字段。", + "补充说明:新增时 shop_name 由服务端生成 PENDING_* 占位名,后续以授权回调同步真实店铺名称。", + "仅文档同步,不修改任何业务代码。" + ], + "type": "updated", + "module": "shops" + }, + { + "version": "2026.05.28-system-02", + "date": "2026-05-28", + "summary": "新增 method: order.print.unlockWavePlatformPrintDataByGroup,按分组解锁波次平台打印锁", + "methods": [ + "order.print.unlockWavePlatformPrintDataByGroup" + ], + "notes": [ + "新增方法:order.print.unlockWavePlatformPrintDataByGroup,用于按分组规则批量解锁波次内被锁定的订单(将 print_lock_status 设为 'none')。", + "入参说明:group_type 默认为 platform_express(支持 platform、platform_express、order),unlock_scope 默认为 group(支持 group、wave);groups 为必须项,元素对象可包含 wave_id、platform、sys_logistics_code、order_ids 等字段。", + "返回说明:返回 summary(解锁统计)、unlocked_order_ids、unlocked_orders、ext.missing_wave_ids、ext.filtered_wave_ids 等字段。", + "实现参考:app/service/systemMethods/order/print.js 与 app/service/systems/order_print.js 的 unlockWavePlatformPrintDataByGroup 实现,相关单元测试位于 test/app/controller/system.order.print.unlockByGroup.test.js 与 test/app/service/systems/order_print.unlockWavePlatformPrintDataByGroup.test.js。" + ], + "type": "updated" + }, + { + "version": "2026.05.28-system-03", + "date": "2026-05-28", + "summary": "新增 order.updateExpressWeighingWeight 方法文档并补充单/多运单称重写入规则", + "methods": [ + "order.updateExpressWeighingWeight" + ], + "notes": [ + "新增 order.updateExpressWeighingWeight 入参说明:order_id、waybill_code、weighing_weight。", + "明确规则:单运单订单忽略 waybill_code 并直接更新唯一运单;多运单订单必须传 waybill_code 且需匹配订单下运单。", + "补充成功返回字段:order_id、waybill_code、weighing_weight。", + "补充错误码:400(参数校验与多运单缺失运单号)、404(运单记录不存在或未匹配)、500(模型未初始化或更新失败)。", + "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" + ], + "type": "added", + "module": "order.index" + }, + { + "version": "2026.05.28-system-01", + "date": "2026-05-28", + "summary": "新增包材相关 methods(create/update/delete/get),并提供 list 兼容说明", + "methods": [ + "setting.packageMaterial.create", + "setting.packageMaterial.update", + "setting.packageMaterial.delete", + "setting.packageMaterial.get", + "setting.packageMaterial.list" + ], + "notes": [ + "实现参考:app/service/systems/setting/packageMaterial.js", + "list 为兼容别名,内部转发至 get,建议新接入方改用 get" + ], + "type": "updated" + }, + { + "version": "2026.05.28-system-04", + "date": "2026-05-28", + "summary": "Add packageSupplier methods (create/update/delete/get) with list alias note", + "methods": [ + "setting.packageSupplier.create", + "setting.packageSupplier.update", + "setting.packageSupplier.delete", + "setting.packageSupplier.get", + "setting.packageSupplier.list" + ], + "notes": [ + "Reference implementation: app/service/systems/setting/packageSupplier.js", + "list is a compatibility alias; prefer get" + ], + "type": "updated" + }, + { + "version": "2026.05.28-system-05", + "date": "2026-05-28", + "summary": "新增 order.bindExpressPackageMaterial 方法文档,支持按订单运单绑定包材", + "methods": [ + "order.bindExpressPackageMaterial" + ], + "notes": [ + "新增 order.bindExpressPackageMaterial 入参说明:order_id、waybill_code、package_material_code(均必填)。", + "补充行为说明:按订单ID+运单号匹配 wms_order_express,按包材编码匹配包材并绑定 package_material_id 与 package_material_name_snapshot。", + "补充成功返回字段:order_id、waybill_code、package_material_id、package_material_name_snapshot、package_material_code。", + "补充错误码:400 参数错误、404 包材编码不存在、404 订单运单记录不存在、500 绑定包材失败。", + "仅通过文档脚本同步 methods/system.json 与 methods/changes/system.json,不修改业务代码。" + ], + "type": "added", + "module": "order.index" + }, + { + "version": "2026.05.29-system-01", + "date": "2026-05-29", + "summary": "新增 order.export 与 order.exportTaskProgress:订单导出异步任务与进度查询", + "methods": [ + "order.export", + "order.exportTaskProgress" + ], + "notes": [ + "order.export:提交导出任务,入参支持 table_type/tableType(枚举 current/history/dispatch/outsourced,兼容订单模块别名)与 module/module_name,where/sort 语义与 order.list 一致。接口提交后立即返回 task_id,后台异步执行导出,导出进度与结果通过 order.exportTaskProgress 查询。", + "order.exportTaskProgress:按 task_id 查询任务进度,返回 task_id、status、progress、current_count、total_count、message、error、download_url、update_time;任务上传完成后 download_url 返回可下载链接,未找到时 status=not_found。" + ], + "type": "added", + "module": "order.index" + }, + { + "version": "2026.05.30-system-01", + "date": "2026-05-30", + "summary": "新增 print.notifyLock(及 notify_lock 兼容别名),并补充 print.send 写入订单操作日志的行为说明", + "methods": [ + "print.notifyLock", + "print.notify_lock", + "print.send" + ], + "notes": [ + "新增 print.notifyLock:入参支持 order_ids/orderIds、waveGroups、data.waveGroups(至少一类提供订单 ID);仅执行订单锁定流程,不发送打印任务;写打印任务日志 + 订单操作日志;返回 locked_count、order_ids_count、order_ids、source;错误:无有效订单ID(400)、锁定失败(500)。", + "补充 print.send 文档:说明接口在执行打印任务记录的同时会写入订单操作日志(记录打印相关操作)。", + "新增兼容别名 print.notify_lock:文档说明等价转调到 print.notifyLock。" + ], + "type": "updated", + "module": "print" + }, + { + "version": "2026.06.03-system-01", + "date": "2026-06-03", + "summary": "同步 pick.query 文档为 keyword 任务化语义并补充冲突错误码", + "methods": [ + "pick.query" + ], + "notes": [ + "入参由 waybill_code/full_display 统一为 keyword(支持运单号或波次号)。", + "成功返回调整为 task_id/status/tip,status 取值 existing 或 created。", + "补充 409 冲突语义:波次已有他人活动任务时返回任务归属信息。" + ], + "type": "updated" + }, + { + "version": "2026.06.03-system-02", + "date": "2026-06-03", + "summary": "更新 pick.wavePickTaskDetail:增加快递号/储位分配前置校验并返回 action+order_ids", + "methods": [ + "pick.wavePickTaskDetail" + ], + "notes": [ + "新增前置校验:任务内若存在未分配快递号订单,返回 400,data.action=assign_express,data.order_ids 为未分配订单ID列表。", + "新增前置校验:任务内若存在未分配储位订单,返回 400,data.action=assign_storage,data.order_ids 为未分配订单ID列表。", + "保留原有权限校验与详情结构,仅补充分配校验失败分支的返回约定。" + ], + "type": "updated" + }, + { + "version": "2026.06.03-system-03", + "date": "2026-06-03", + "summary": "更新 order.wave.batchList:新增同步状态输出与筛选 sync_assignment_status", + "methods": [ + "order.wave.batchList" + ], + "notes": [ + "新增返回字段语义:list[].sync_assignment_status,取值为未同步/部分同步/已同步/同步异常。", + "新增筛选入参 where.sync_assignment_status,支持 unsynced/partially_synced/synced 英文枚举。", + "同步状态筛选规则与分配状态一致:error 并入 unsynced 过滤集合。" + ], + "type": "updated" + }, + { + "version": "2026.06.03-system-04", + "date": "2026-06-03", + "summary": "更新拣货中间态流程文档:wavePickTaskDetail 增加完成标记,并新增中间态/完全提交接口", + "methods": [ + "pick.wavePickTaskDetail", + "pick.wavePickTaskSubmit", + "pick.wavePickTaskComplete" + ], + "notes": [ + "更新 pick.wavePickTaskDetail 返回:新增 task.is_completed、task.progress(total_orders/picked_orders/pending_orders)以及顶层 is_completed。", + "新增 pick.wavePickTaskSubmit:支持保存中间态 payload 到任务 ext_json.pick_intermediate,并返回当前完成状态与进度。", + "新增 pick.wavePickTaskComplete:支持 mode=1 全部确认与 mode=2 部分确认(order_ids),返回 confirmed_order_ids 与最新进度。" + ], + "type": "updated" + }, + { + "version": "2026.06.03-system-05", + "date": "2026-06-03", + "summary": "拣货车能力拆分为一级模块 pickCart:扫码查询、任务绑车、CRUD、编码查重", + "methods": [ + "pickCart.scan", + "pickCart.bindTaskCart", + "pickCart.create", + "pickCart.update", + "pickCart.delete", + "pickCart.detail", + "pickCart.list", + "pickCart.codeDuplicateCheck" + ], + "notes": [ + "拣货车能力独立为一级模块 pickCart,不再挂在 pick 模块下。", + "新增 pickCart.scan:PDA 按 cart_code 扫码查询拣货车信息,用于进入任务绑定流程。", + "新增 pickCart.bindTaskCart:支持按 cart_id/cart_code 将拣货车绑定到指定拣货任务,若车已绑定其他活动任务则返回冲突。", + "新增 pickCart.create/pickCart.update/pickCart.delete/pickCart.detail/pickCart.list:补齐拣货车增删查改与分页查询能力。", + "新增 pickCart.codeDuplicateCheck:支持 exclude_cart_id 排除自身,供编辑场景做非自身重复校验;拣货车编码在当前仓库内不可重复。" + ], + "type": "updated" + }, + { + "version": "2026.06.03-system-06", + "date": "2026-06-03", + "summary": "更新 order.wave.batchList:新增 only_todo、复核状态聚合与复核筛选", + "methods": [ + "order.wave.batchList" + ], + "notes": [ + "新增入参 only_todo(默认 0):传 1/true 时仅返回仍有未复核订单的波次(unreviewed_order_count > 0)。", + "新增返回字段:list[].unreviewed_order_count(未复核订单数)与 list[].review_assignment_status(未复核/部分复核/已复核)。", + "新增 where.review_assignment_status 筛选,支持 unreviewed/partially_reviewed/reviewed 英文枚举。" + ], + "type": "updated", + "module": "order.wave" + }, + { + "version": "2026.06.04-system-01", + "date": "2026-06-04", + "summary": "裁剪 pick.wavePickTaskDetail 返回:团购小波次(pick_mode=1)不返回 picking_details 字段以减少带宽", + "methods": [ + "pick.wavePickTaskDetail" + ], + "notes": [ + "在 picking_details 字段 description 中补充:当 pick_mode=1(团购小波次)时该字段不返回,减少带宽浪费;其他 pick_mode(2/3/4/5)正常返回 picking_details。", + "在接口 description 中补充该裁剪行为的说明。", + "picking_summary、picking_view、boxes 等字段不受影响,pick_mode=1 时仍正常返回。" + ], + "type": "updated" + }, + { + "version": "2026.06.04-system-02", + "date": "2026-06-04", + "summary": "完善 index.getPlatformList 文档:补充入参 systemOnly/full、响应字段及错误码 500", + "methods": [ + "index.getPlatformList" + ], + "notes": [ + "补充入参说明:systemOnly(可选,支持 is_system 别名,真值识别 true/1/'1'/'true')、full(可选,真值识别同上,为 true 时返回全量表字段与 route_platform_code/platid 等扩展信息)", + "补充响应 data 数组每项字段:code、name、value、label、platform_code、platform_name、default_express_interface、is_system_setting、id(仅仓库自定义项)、alias(仅仓库自定义项)、full 模式扩展字段说明", + "说明合并逻辑:系统平台在前,仓库自定义在后,同 code 仅保留首条(系统优先);systemOnly=true 仅返回系统平台", + "补充缓存策略:优先读缓存,key 格式为 platform:list:{warehouseId}[:full] 或 platform:list:system[:full]", + "补充错误码 500:数据库或缓存访问异常", + "仅文档更新,不修改任何业务实现" + ], + "type": "updated", + "module": "index" + }, + { + "version": "2026.06.04-system-03", + "date": "2026-06-04", + "summary": "作废 order.pendingOrder.downloadCreateTemplate 和 order.pendingOrder.importOrdersFromExcel", + "methods": [ + "order.pendingOrder.downloadCreateTemplate", + "order.pendingOrder.importOrdersFromExcel" + ], + "notes": [ + "order.pendingOrder.downloadCreateTemplate:下载订单导入模板方法已从代码中移除,标记为 deprecated。", + "order.pendingOrder.importOrdersFromExcel:从 Excel 导入订单方法已从代码中移除,标记为 deprecated。", + "两个方法的文档条目保留在 methods/system.json 中,仅追加 status: 'deprecated' 与 description 中的'(已作废)'标记,未删除。" + ], + "type": "deprecated" + }, + { + "version": "2026.06.05-system-01", + "date": "2026-06-05", + "summary": "新增 storeWarehouse.store.openAccount 接口:仓库代货主一键开户(合并注册账号+创建货主+签约)", + "methods": [ + "storeWarehouse.store.openAccount" + ], + "notes": [ + "新增 storeWarehouse.store.openAccount 方法,归属货主-仓库签约模块(storeWarehouse.store)。", + "接口同时完成账号注册、货主创建和仓库-货主签约,一步完成开户全流程。", + "当前主体必须为仓库角色(Authorization header 中携带的 token 对应仓库用户)。", + "必填参数:username(登录账号)、password(初始密码)、company_name(公司全称)、business_license(营业执照号)、contact_person(联系人)、contact_phone(联系电话)。", + "响应返回新创建的 store_id、account_id、contract_id、company_name、username、role_id。" + ], + "type": "added", + "module": "storeWarehouse" + }, + { + "version": "2026.06.05-system-02", + "date": "2026-06-05", + "summary": "优化 storeWarehouse.store.openAccount 必填参数:password 改为随机生成、business_license 和 contact_phone 改为可选,必填仅剩 username/company_name/contact_person 三个", + "methods": [ + "storeWarehouse.store.openAccount" + ], + "notes": [ + "password:由必填改为可选,不传时自动随机生成 12 位密码", + "business_license:由必填改为可选", + "contact_phone:由必填改为可选" + ], + "type": "updated" + }, + { + "version": "2026.06.05-system-03", + "date": "2026-06-05", + "summary": "saveApiConfig 增加 callback_url 参数,支持配置 API 回调通知地址", + "methods": [ + "storeWarehouse.store.saveApiConfig" + ], + "notes": [ + "新增 callback_url 参数:OpenAPI 类型接口支持配置回调通知 URL", + "兼容别名 callbackUrl,最大 500 字符", + "存入 wms_api_app.callback_url 字段" + ], + "type": "modified" + }, + { + "version": "2026.06.05-system-04", + "date": "2026-06-05", + "summary": "createOrder 入参 item_code 改为 item_id,province/city/area 改为必填", + "methods": [ + "order.pendingOrder.createOrder" + ], + "notes": [ + "items[].item_code → items[].item_id:改用商品主键直接匹配,不依赖外部系统商品推送", + "province/city/area 新增必填校验,空值返回 400", + "item_name 优先外部传入,其次从 StockStore 缓存获取,最后兜底'商品'" + ], + "type": "modified" + }, + { + "version": "2026.06.05-system-05", + "date": "2026-06-05", + "summary": "新增 order.pendingOrder.parseAddress 智能地址解析方法", + "methods": [ + "order.pendingOrder.parseAddress" + ], + "notes": [ + "使用 DeepSeek AI 模型将非结构化地址字符串解析为省/市/区/详细地址/收件人/手机号", + "解析结果可直接用于 createOrder 的 receiverInfo 字段", + "DeepSeek API Key 通过 DEEPSEEK_API_KEY 环境变量配置" + ], + "type": "added" + }, + { + "version": "2026.06.05-system-06", + "date": "2026-06-05", + "summary": "waveStrategyUpdate/waveStrategyCreate 新增 wave_prefix 参数", + "methods": [ + "order.wave.waveStrategyUpdate", + "order.wave.waveStrategyCreate" + ], + "notes": [ + "新增 wave_prefix 波次编号前缀字段,最多 5 个字符,为空存 null" + ], + "type": "modified" + }, + { + "version": "2026.06.05-system-07", + "date": "2026-06-05", + "summary": "parseAddress 响应新增 town 字段(乡镇/街道)", + "methods": [ + "order.pendingOrder.parseAddress" + ], + "notes": [ + "响应 data 中新增 town 字段,返回 AI 解析出的乡镇/街道名称" + ], + "type": "modified" + }, + { + "version": "2026.06.05-system-08", + "date": "2026-06-05", + "summary": "为 order.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", + "methods": [ + "order.list" + ], + "notes": [ + "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" + ], + "type": "updated" + }, + { + "version": "2026.06.05-system-09", + "date": "2026-06-05", + "summary": "为 order.reviewOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", + "methods": [ + "order.reviewOrder.list" + ], + "notes": [ + "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" + ], + "type": "updated" + }, + { + "version": "2026.06.05-system-10", + "date": "2026-06-05", + "summary": "为 order.pendingOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", + "methods": [ + "order.pendingOrder.list" + ], + "notes": [ + "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" + ], + "type": "updated" + }, + { + "version": "2026.06.05-system-11", + "date": "2026-06-05", + "summary": "为 order.outboundOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", + "methods": [ + "order.outboundOrder.list" + ], + "notes": [ + "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" + ], + "type": "updated" + }, + { + "version": "2026.06.05-system-12", + "date": "2026-06-05", + "summary": "为 order.expectionOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", + "methods": [ + "order.expectionOrder.list" + ], + "notes": [ + "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" + ], + "type": "updated" + }, + { + "version": "2026.06.05-system-13", + "date": "2026-06-05", + "summary": "为 order.entrustOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", + "methods": [ + "order.entrustOrder.list" + ], + "notes": [ + "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" + ], + "type": "updated" + }, + { + "version": "2026.06.05-system-14", + "date": "2026-06-05", + "summary": "为 order.deliveryOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", + "methods": [ + "order.deliveryOrder.list" + ], + "notes": [ + "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" + ], + "type": "updated" + }, + { + "version": "2026.06.05-system-15", + "date": "2026-06-05", + "summary": "为 order.deliveryExpectionOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", + "methods": [ + "order.deliveryExpectionOrder.list" + ], + "notes": [ + "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" + ], + "type": "updated" + }, + { + "version": "2026.06.05-system-16", + "date": "2026-06-05", + "summary": "为 order.archiveOrder.list 响应新增 recheck_status 字段(复核状态:none=未复核,fin=已复核)", + "methods": [ + "order.archiveOrder.list" + ], + "notes": [ + "订单列表接口输出中新增 recheck_status 字段,类型 string,可选值 none/fin" + ], + "type": "updated" + }, + { + "version": "2026.06.06-system-01", + "date": "2026-06-06", + "summary": "恢复 order.pendingOrder.downloadCreateTemplate:方法仍存在于代码中,取消 deprecated 标记,完善文档描述", + "methods": [ + "order.pendingOrder.downloadCreateTemplate" + ], + "notes": [ + "order.pendingOrder.downloadCreateTemplate 方法在 pendingOrder.js 中仍存在(line 2099),此前被误标记为 deprecated。", + "取消 status: 'deprecated' 标记,恢复为 active 状态。", + "移除 description 中的'(已作废)'后缀。", + "完善 description:说明模板包含必填列(橙色背景)、可选列(灰色背景)、示例数据行和填写说明工作表。", + "补充 response 字段说明:filename 和 mime 为固定值。" + ], + "type": "updated" + }, + { + "version": "2026.06.07-system-01", + "date": "2026-06-07", + "summary": "order.pendingOrder.createOrder 文档新增 shop_nick 入参(店铺名称,可选,最大长度200)", + "methods": [ + "order.pendingOrder.createOrder" + ], + "notes": [ + "在 order.pendingOrder.createOrder 的 request params 中新增 shop_nick 字段(string,非必填),对应代码实现中 shopNick: String(requestData.shop_nick || requestData.shopNick || '').trim()。", + "shop_nick 已在 COPY_FIELDS 白名单中(pendingOrder.js L1738),仅文档缺失,本次为补齐。" + ], + "type": "updated" + }, + { + "version": "2026.06.07-system-02", + "date": "2026-06-07", + "summary": "order.pendingOrder.downloadCreateTemplate:模板新增 shop_nick 列(店铺名称),store_id/province/city/area 标注为非必填", + "methods": [ + "order.pendingOrder.downloadCreateTemplate" + ], + "notes": [ + "模板新增 shop_nick(店铺名称)列,非必填。", + "明确标注 store_id(货主ID)、province(省份)、city(城市)、area(区/县)为非必填列。", + "响应文档中新增 shop_nick 字段说明。" + ], + "type": "updated" + }, + { + "version": "2026.06.07-system-03", + "date": "2026-06-07", + "summary": "新增 order.pendingOrder.updateAddress:批量修改待处理订单收件地址,限制未分配快递时可用", + "methods": [ + "order.pendingOrder.updateAddress" + ], + "notes": [ + "新增 method:order.pendingOrder.updateAddress,免权限(isNeedAuth=false),需登录", + "功能:批量修改待处理订单收件地址(name/mobile/tel/zip_code/province/city/area/town/detail_address)", + "约束:仅 post_status='none'(未分配快递)的订单可修改;至少提供一个有效地址字段", + "响应:返回 updated_count(实际更新行数)和 ids(请求订单ID数组)" + ], + "type": "added" + }, + { + "version": "2026.06.07-system-04", + "date": "2026-06-07", + "summary": "order.wave.wavePickTaskCancel 扩展可取消状态至 status=3,并新增拣货状态回退", + "methods": [ + "order.wave.wavePickTaskCancel" + ], + "notes": [ + "可取消状态从 [0,1,2] 扩展为 [0,1,2,3](status=3 已完成现在也可取消)", + "取消 status=2(待复核)或 status=3(已完成)任务时,自动回退 wms_wave_pick_task_order.pick_status(1→0)和 order_delivery.pick_status(fin→padding)", + "错误码 400 描述同步更新,补充 403 错误码说明" + ], + "type": "updated" + }, + { + "version": "2026.06.07-system-05", + "date": "2026-06-07", + "summary": "order.wave.wavePickTaskList 响应新增 cart_name 字段(拣货车名称)", + "methods": [ + "order.wave.wavePickTaskList" + ], + "notes": [ + "响应 list 子项新增 cart_name(string):通过 current_cart_id LEFT JOIN wms_pick_cart 表获取,未绑定拣货车时为空字符串。" + ], + "type": "updated" + }, + { + "version": "2026.06.07-system-06", + "date": "2026-06-07", + "summary": "pick.wavePickTaskComplete 新增后台抓取任务(source=2)拣货车绑定校验,未绑定拣货车时拒绝提交", + "methods": [ + "pick.wavePickTaskComplete" + ], + "notes": [ + "description 补充说明:后台抓取创建的任务(source=2)必须先绑定拣货车才能提交,否则返回 400。", + "errors 中 400 错误补充:后台抓取任务(source=2)未绑定拣货车时拒绝提交,错误消息为\"后台抓取任务必须先绑定拣货车才能提交\"。" + ], + "type": "updated" + }, + { + "version": "2026.06.07-system-07", + "date": "2026-06-07", + "summary": "order.wave.batchList 文档修正:移除代码中不存在的 sync_assignment_status 引用", + "methods": [ + "order.wave.batchList" + ], + "notes": [ + "从 where 描述中移除 sync_assignment_status(代码 buildBatchListWhereClause allowedFields 中不存在该字段,BATCH_LIST_ASSIGNMENT_FILTER_SCHEMAS 中也无 review 之外的同步类型)。", + "从 response list 描述中移除 sync_assignment_status(代码响应映射中仅返回 storage/express/print/review 四种 assignment_status,无 sync_assignment_status)。", + "v2026.06.03-system-03 变更记录中声称新增的 sync_assignment_status 实际从未在代码中实现,本次仅为文档修正,不涉及代码变更。" + ], + "type": "updated", + "module": "order.wave" + }, + { + "version": "2026.06.07-system-08", + "date": "2026-06-07", + "summary": "order.recheckOrder.confirmRecheck 补充后置行为说明:波次任务全部复核完成后自动解绑车任务", + "methods": [ + "order.recheckOrder.confirmRecheck" + ], + "notes": [ + "在 description 中补充:确认复核后,若该订单所属波次拣货任务下所有订单均已复核完成,则自动解绑车任务。解绑操作包括:清空 wms_wave_pick_task 的 current_cart_id/current_cart_code_snapshot、停用 wms_pick_task_cart_binding(is_active=0 并记录解绑人和时间)、释放 wms_pick_cart(清空 current_task_id/bind_user_id)。", + "解绑失败仅记录 warn 日志,不影响复核主流程。", + "入参和返回结构未变,仅补充行为说明。" + ], + "type": "updated" + }, + { + "version": "2026.06.07-system-10", + "date": "2026-06-07", + "summary": "移除 order.wave.groupFetch / singleFetch / fetch 响应中已废弃的 auto_fetch_disabled_marker 字段", + "methods": [ + "order.wave.groupFetch", + "order.wave.singleFetch", + "order.wave.fetch" + ], + "notes": [ + "auto_fetch_disabled_marker 字段已从代码 submitFetchTask 响应中移除,文档同步删除该字段的描述。", + "auto_fetch_disabled 字段同样已从代码中移除,且原文档中不存在此字段(仅有 auto_fetch_disabled_marker),无需额外处理。", + "涉及 method:order.wave.groupFetch、order.wave.singleFetch、order.wave.fetch,均移除 response 中的 auto_fetch_disabled_marker 字段。" + ], + "type": "updated", + "module": "order.wave" + }, + { + "version": "2026.06.08-system-01", + "date": "2026-06-08", + "summary": "order.recheckOrder 模块 scanOrder 返回值重构为统一 list 输出,新增 confirmIntercept 与 recheckOrderList 接口", + "methods": [ + "order.recheckOrder.scanOrder", + "order.recheckOrder.confirmIntercept", + "order.recheckOrder.recheckOrderList" + ], + "notes": [ + "scanOrder 返回值重构:统一使用 list 字段输出,新增 list_type 字段区分散单/团购模式。散单模式顶层新增 picker_id、picker_name、wave_id、wave_no、wave_type、pick_mode、strategy_id、strategy_name、total_orders、reviewed_count、unreviewed_count 等汇总字段。list 中每项新增 waybill_no、is_printed、is_reviewed、wave_index、intercept_status、store_remark、stock[](含 stock_id、item_code、item_name、sku_property、packing_requirements、barcodes[]、images[]、plan_qty、has_shared_barcode)。移除旧字段 logs、order、order_id(顶层)、waybill_no(顶层旧位置)、wave_match_view、items、expresses、cart_match_view。", + "scanOrder 入参新增 wave_no / waveNo 支持波次号直接扫描匹配。", + "新增 order.recheckOrder.confirmIntercept:确认拦截接口,将订单 intercept_status 更新为 intercepted_at_warehouse,返回 order_id、order_no、intercept_status、updated_at。", + "新增 order.recheckOrder.recheckOrderList:复核订单列表查询,支持 list_type=single(散单)与 list_type=group(团购),均返回统一 list + pagination 结构。" + ], + "type": "updated" + }, + { + "version": "2026.06.08-system-02", + "date": "2026-06-08", + "summary": "order.recheckOrder 模块新增 batchIntercept/batchInterceptTaskProgress,更新 scanOrder 团购模式响应结构,完善 confirmIntercept/recheckOrderList 文档", + "methods": [ + "order.recheckOrder.batchIntercept", + "order.recheckOrder.batchInterceptTaskProgress", + "order.recheckOrder.scanOrder", + "order.recheckOrder.confirmIntercept", + "order.recheckOrder.recheckOrderList" + ], + "notes": [ + "新增 order.recheckOrder.batchIntercept:批量提交订单拦截(异步任务模式),入参支持 order_ids/orderIds/ids(订单ID数组,不再使用 wave_ids),将 intercept_status 设为 'requested',返回 task_id/warehouse_id/message/accepted_at。支持幂等提交与 warehouse_id 校验。", + "新增 order.recheckOrder.batchInterceptTaskProgress:按 task_id 查询批量拦截任务进度,返回 state(submitted/running/success/failed/not_found)及对应的进度/计数/结果/错误字段。", + "更新 order.recheckOrder.scanOrder 响应文档:团购模式(cart 命中)list 项新增 wave_id/wave_no/wave_type/wave_status/total_orders/processed_orders/creator/create_time/update_time/order_count/pick_mode/box_no/orders[] 等波次级别字段;补充散单无波次信息时的回退详情模式说明(detail/items/expresses/logs)。", + "完善 order.recheckOrder.confirmIntercept:补充操作日志写入说明(ORDER_INTERCEPT_CONFIRM)及失败不影响主流程的容错描述。", + "完善 order.recheckOrder.recheckOrderList:补充散单模式默认排除 pick_status='none' 和 recheck_status='fin' 的说明;团购模式 where 支持 wave_no(模糊搜索)的说明。" + ], + "type": "updated" + }, + { + "version": "2026.06.08-system-03", + "date": "2026-06-08", + "summary": "移除 order.recheckOrder.batchIntercept 的 warehouse_id/warehouseId 入参,仓库ID统一使用当前上下文", + "methods": [ + "order.recheckOrder.batchIntercept" + ], + "notes": [ + "移除入参 warehouse_id / warehouseId:仓库ID统一从当前上下文(ctx.user.store_id)获取,不再由调用方传入。", + "移除对应错误码:warehouse_id 参数不合法(400)、warehouse_id 与当前仓库上下文不一致(400)。", + "description 中补充说明仓库ID来源为当前上下文。", + "response 中 warehouse_id 字段描述改为「取自当前上下文」。" + ], + "type": "updated" + }, + { + "version": "2026.06.08-system-10", + "date": "2026-06-08", + "summary": "batchIntercept / batchInterceptTaskProgress 从 order.recheckOrder 迁移至 order.pendingOrder", + "methods": [ + "order.pendingOrder.batchIntercept", + "order.pendingOrder.batchInterceptTaskProgress" + ], + "notes": [ + "method 从 order.recheckOrder.batchIntercept 重命名为 order.pendingOrder.batchIntercept,分组从订单复核模块迁移至订单待处理模块", + "method 从 order.recheckOrder.batchInterceptTaskProgress 重命名为 order.pendingOrder.batchInterceptTaskProgress,分组从订单复核模块迁移至订单待处理模块", + "接口入参、响应、错误码均保持不变,仅变更 method 名称与所属分组" + ], + "type": "updated" + }, + { + "version": "2026.06.08-system-04", + "date": "2026-06-08", + "summary": "新增 order.print.getOrderPrintData:按订单ID拉取打印数据,返回结构与 getWavePlatformPrintData 一致,不限制锁定状态", + "methods": [ + "order.print.getOrderPrintData" + ], + "notes": [ + "新增 order.print.getOrderPrintData 接口文档,入参为 warehouse_id + order_ids(非空数组),返回与 getWavePlatformPrintData 结构一致的 waveGroups / summary / wave_ids / ext", + "与 getWavePlatformPrintData 的区别:入参为 order_ids(非 wave_ids),ext 中返回 missing_order_ids / filtered_order_ids(非 missing_wave_ids / filtered_wave_ids)", + "不限制打印锁定状态,所有订单(无论是否被锁定)统一返回打印数据", + "自动过滤 post_status !== 'fin' 的订单(快递未完全分配),被过滤订单出现在 ext.filtered_order_ids" + ], + "type": "added", + "module": "order.print" + }, + { + "version": "2026.06.08-system-11", + "date": "2026-06-08", + "summary": "新增 order.pendingOrder 批量锁定/解锁/解除拦截及对应进度查询共 6 个异步任务接口文档", + "methods": [ + "order.pendingOrder.batchLock", + "order.pendingOrder.batchLockTaskProgress", + "order.pendingOrder.batchUnlock", + "order.pendingOrder.batchUnlockTaskProgress", + "order.pendingOrder.batchUnintercept", + "order.pendingOrder.batchUninterceptTaskProgress" + ], + "notes": [ + "新增 batchLock:批量锁定订单,lock_status → 'warehouse',操作日志 ORDER_LOCK,task_id 格式 order_lock_{warehouseId}_{timestamp}_{rand}。", + "新增 batchLockTaskProgress:查询批量锁定进度,返回 locked_order_count / locked_order_ids 等。", + "新增 batchUnlock:批量解锁订单,lock_status → 'none',操作日志 ORDER_UNLOCK,task_id 格式 order_unlock_{warehouseId}_{timestamp}_{rand}。", + "新增 batchUnlockTaskProgress:查询批量解锁进度,返回 unlocked_order_count / unlocked_order_ids 等。", + "新增 batchUnintercept:批量解除拦截订单,intercept_status → 'none',操作日志 ORDER_INTERCEPT_CANCEL,task_id 格式 order_unintercept_{warehouseId}_{timestamp}_{rand}。", + "新增 batchUninterceptTaskProgress:查询批量解除拦截进度,返回 unintercepted_order_count / unintercepted_order_ids 等。", + "以上 6 个接口均采用与已有 batchIntercept/batchInterceptTaskProgress 一致的异步任务模式:提交返回 task_id,进度查询返回 state + 进度字段。", + "仅同步文档,不修改业务代码或实现。" + ], + "type": "added", + "module": "order" + }, + { + "version": "2026.06.08-system-12", + "date": "2026-06-08", + "summary": "更新 order.print.getOrderPrintData:移除锁定限制,所有订单统一返回打印数据,不再区分锁定/未锁定", + "methods": [ + "order.print.getOrderPrintData" + ], + "notes": [ + "移除打印锁定限制:所有订单(包括已锁定)统一返回打印数据,不再区分锁定/未锁定状态", + "移除 locked_count、locked_orders、locked_wave_groups 等锁定相关字段", + "返回结构与 getWavePlatformPrintData 完全一致:summary / waveGroups / wave_ids / ext", + "ext 中使用 missing_order_ids / filtered_order_ids(替代锁定相关字段),与代码实现完全对齐" + ], + "type": "updated", + "module": "order.print" + }, + { + "version": "2026.06.08-system-13", + "date": "2026-06-08", + "summary": "更新 order.print.getOrderPrintData:移除 warehouse_id 入参,仓库ID统一从当前上下文获取", + "methods": [ + "order.print.getOrderPrintData" + ], + "notes": [ + "移除 warehouse_id / warehouseId 入参,仓库ID统一从 this.getContextWarehouseId() 获取", + "同步移除 errors 中 warehouse_id 必填 相关错误码", + "description 补充说明仓库ID从上下文获取,无需调用方传入", + "params 仅保留 order_ids(非空数组),与代码 method 层 getOrderPrintData(data) 解构一致" + ], + "type": "updated", + "module": "order.print" + }, + { + "version": "2026.06.08-system-14", + "date": "2026-06-08", + "summary": "新增 order.recheckOrder.scanTask 接口文档,并为 scanOrder 响应补充 task_id 字段", + "methods": [ + "order.recheckOrder.scanTask", + "order.recheckOrder.scanOrder" + ], + "notes": [ + "新增 order.recheckOrder.scanTask:按拣货任务 ID 拉取复核数据,数据结构与 scanOrder 完全一致,用于前端刷新。入参为 task_id(必填,number),返回 match_type='task',散单模式(pick_mode 2/3/4)返回扁平订单列表,团购模式(pick_mode 1/5)返回分组波次列表。", + "更新 order.recheckOrder.scanOrder 响应定义:补充 task_id 字段说明(散单有波次时由 buildSingleWaveScanView 返回,团单车号命中时由 cartMatchContext 返回)。", + "仅同步文档,不修改任何业务代码或实现。" + ], + "type": "updated" + }, + { + "version": "2026.06.08-system-15", + "date": "2026-06-08", + "summary": "新增 order.pendingOrder.manualWaybill 接口(手工录入运单号)", + "methods": [ + "order.pendingOrder.manualWaybill" + ], + "notes": [ + "为待处理订单手动录入运单号,写入 wms_order_express 表", + "仅允许 step 在 [1,2,3] 且 outbound_status 不为 'padding' 的订单操作", + "免权限(isNeedAuth: false),需登录", + "成功返回运单记录的 id、order_id、waybill_code、create_at" + ], + "type": "added" + }, + { + "version": "2026.06.09-system-01", + "date": "2026-06-09", + "summary": "order.pendingOrder.updateAddress 新增 remark 字段:订单留言/备注批量覆盖,不受 post_status 限制", + "methods": [ + "order.pendingOrder.updateAddress" + ], + "notes": [ + "在 params 中新增 remark 字段(string,可选,最大500字符),支持批量覆盖所选订单的 remark", + "remark 更新不受 post_status 限制,可对所有订单生效(地址字段仍仅允许 post_status='none')", + "更新 description 明确 remark 与地址字段的独立性", + "更新 response 中 updated_count 说明:取地址更新行数与备注更新行数的最大值", + "更新 errors 中缺少字段的错误描述,改为「至少需要提供一个地址字段或备注进行修改」", + "业务代码已同步实现,本次仅同步文档" + ], + "type": "updated" + }, + { + "version": "2026.06.09-system-02", + "date": "2026-06-09", + "summary": "order.updateExpressWeighingWeight 新增运单号模式文档:order_id=0 时从运单号反查,支持散单与团购批量两种返回结构", + "methods": [ + "order.updateExpressWeighingWeight" + ], + "notes": [ + "order_id 参数说明补充:设为0时切换为运单号模式,需配合 waybill_code 使用。", + "waybill_code 参数说明补充:运单号模式(order_id=0)下必填。", + "description 更新:明确订单模式与运单号模式两种路径及团购波次批量行为。", + "response 新增运单号散单场景字段(order_id、waybill_code、weighing_weight)与运单号团购批量场景字段(wave_no、business_key、weighing_weight、success_count)。", + "errors 新增运单号模式相关错误码:运单号不存在(404)、运单号对应的订单不存在(404)、波次下未找到订单(404)、批量更新失败(500)。", + "仅文档同步,不修改业务代码。" + ], + "type": "updated" + }, + { + "version": "2026.06.09-system-03", + "date": "2026-06-09", + "summary": "order.updateExpressWeighingWeight 团购返回新增拆单汇总字段,移除 success_count/total_count", + "methods": [ + "order.updateExpressWeighingWeight" + ], + "notes": [ + "团购批量模式 response 新增 total_weight(所有拆单重量累加)、split_count(waybill_code 非空的 business_key 数量)、splits(按 business_key 分组的拆单明细数组,每项含 business_key/weighing_weight/waybill_code)、store_name(货主名称)和 sys_logistics_name(系统快递名称)。", + "移除 response 中的 success_count 与 total_count 字段,改为由 total_weight 和 split_count 提供汇总信息。", + "更新 description 以反映团购模式返回拆单汇总结构。" + ], + "type": "updated" + }, + { + "version": "2026.06.10-system-01", + "date": "2026-06-10", + "summary": "order.detail 接口文档:expresses 数组新增字段 weighing_weight、sys_logistics_code、sys_logistics_name、business_key、created_at", + "methods": [ + "order.detail" + ], + "notes": [ + "expresses 数组新增字段:weighing_weight(称重重量,number|null)、sys_logistics_code(系统物流公司编码,string)、sys_logistics_name(系统物流公司名称,string)、business_key(业务标识,string)、created_at(创建时间戳毫秒,number|null)", + "字段来源:getOrderExpressesByOrderId 方法中 sys_logistics_code/sys_logistics_name 取自订单表 sys_logistics_code/sys_logistics_name,其余字段取自 OrderExpress 表" + ], + "type": "updated" + }, + { + "version": "2026.06.10-system-02", + "date": "2026-06-10", + "summary": "dashboard.order_trend 从 mock 数据改为查询真实数据库,按小时统计当日订单数与发货数,补充完整返回结构与错误说明", + "methods": [ + "dashboard.order_trend" + ], + "notes": [ + "接口实现从 mock 静态数据改为查询真实数据库(wms_order_delivery 与 dispatch 表),数据实时反映仓库当日运营情况。", + "订单筛选条件:step in [1,2,3],排除 outbound_status='padding' 和 status='cancel',统计 create_at 在今日 00:00 到当前时刻的订单,按 HOUR(create_at) 分组。", + "发货筛选条件:dispatch_lane='m4',统计 delivery_time 在今日 00:00 到当前时刻的发货记录,按 HOUR(delivery_time) 分组。", + "时段范围:从 08:00 到当前小时(最晚 23:00),若当前时间早于 08:00 则从 08:00 开始。", + "返回新增 summary 汇总对象:total_orders(订单总数)、total_shipments(发货总数)、shipment_rate(发货率百分比)、peak_hour(峰值时段)、peak_orders(峰值订单数)。", + "categories/orders/shipments 三个数组一一对应,提供按时段的订单与发货趋势数据,可直接用于前端折线图/柱状图渲染。", + "需要登录(Authorization header),从 token 中获取 warehouseId;若缺少仓库上下文则返回 flag='fail'。" + ], + "type": "updated", + "module": "dashboard" + }, + { + "version": "2026.06.10-system-03", + "date": "2026-06-10", + "summary": "order.pendingOrder.manualWaybill 新增可选参数 logistics_interface_name 与响应字段 business_key/logistics_interface_name,补充行为说明", + "methods": [ + "order.pendingOrder.manualWaybill" + ], + "notes": [ + "新增可选参数 logistics_interface_name(string,选填,trim 后为空则传 null)", + "响应新增字段 business_key(number):同一订单下从已有最大值 +1 递增,无记录时从 1 开始", + "响应新增字段 logistics_interface_name(string/null):写入的物流接口名称", + "补充 description 行为说明:完成后自动更新 wms_order_delivery_* 表的 print_status 和 post_status 为 'fin'", + "wms_order_express 表写入时 status 固定为 1,warehouse_id 从订单记录取" + ], + "type": "updated" + }, + { + "version": "2026.06.10-system-04", + "date": "2026-06-10", + "summary": "stock.warehouse.import 新增 barcode(条码)字段支持", + "methods": [ + "stock.warehouse.import" + ], + "notes": [ + "新增 barcode(条码)字段支持,支持别名:条码、bar_code、barCode、barcodeList、barcode_list、barcode。", + "条码字段支持数组格式(如 [\"6901234567890\"])和分号分隔字符串格式(如 \"6901234567890;6901234567891\")。", + "新建和更新路径均已支持条码导入,条码写入 wms_stock_barcodes 表。", + "仅同步文档,不修改业务代码或实现。" + ], + "type": "updated" + }, + { + "version": "2026.06.10-system-05", + "date": "2026-06-10", + "summary": "stock.warehouse.import 的 barcode 字段分隔符改为逗号,对齐 stock.warehouse.export 导出格式;仅接收字符串格式,不再支持数组", + "methods": [ + "stock.warehouse.import" + ], + "notes": [ + "barcode 字段分隔符从分号 ; 改为逗号 ,", + "barcode 字段仅接收字符串格式,不再支持数组格式", + "格式示例:\"6901234567890,6901234567891\",与 stock.warehouse.export 导出格式一致" + ], + "type": "modified" + }, + { + "version": "2026.06.13-system-01", + "date": "2026-06-13", + "summary": "setting.warehouse 的 auto_outbound_rules 新增 require_print 和 require_pick 两个可选条件字段(同步代码实现)", + "methods": [ + "setting.warehouse.getSettings", + "setting.warehouse.saveSettings" + ], + "notes": [ + "在 getSettings 响应和 saveSettings 入参中补充 subject_config.auto_outbound_rules 对象的完整字段文档(enabled、require_recheck、require_pack、require_weigh、require_sync、require_print、require_pick)。", + "require_print:是否要求已打印(print_status=fin),默认 true。", + "require_pick:是否要求已拣货(pick_status=fin),默认 true。", + "该规则由自动出库定时任务 order_auto_outbound 消费,全部开启的条件均满足时自动标记待出库。" + ], + "type": "updated" + }, + { + "version": "2026.06.13-system-02", + "date": "2026-06-13", + "summary": "order.recheckOrder.scanOrder 团购模式响应新增 orders_detail 字段,暴露非拦截订单的详细列表(含 is_printed、is_reviewed 等状态字段)", + "methods": [ + "order.recheckOrder.scanOrder" + ], + "notes": [ + "团购模式(list_type='group')波次视图项新增 orders_detail 字段:非拦截订单详细列表,每项含 order_id、delivery_order_code、waybill_no、pick_status、is_printed(print_status === 'fin')、is_reviewed(recheck_status === 'fin')、recheck_status、shop_nick、items_count、wave_index、intercept_status", + "orders_detail 与现有 order_ids(纯数字 ID 数组)并存,均在团购模式的波次视图项中返回", + "orders_detail 仅在 list_type='group' 时返回,散单模式不受影响", + "同步更新 list 字段 description 以反映 group 模式新增的 order_ids、orders_detail、stocks 字段" + ], + "type": "updated" + }, + { + "version": "2026.06.13-system-03", + "date": "2026-06-13", + "summary": "新增批量快捷复核接口 batchQuickRecheck,支持批量订单 IDs 的前置条件检查(储位、快递、同步、拦截),自动完成拣货并标记复核,支持部分失败。拣货完成后同步更新 wms_wave_pick_task 状态", + "methods": [ + "order.recheckOrder.batchQuickRecheck" + ], + "notes": [ + "新增 order.recheckOrder.batchQuickRecheck 方法", + "入参 ids 支持数组或逗号分隔字符串", + "响应包含 success/failed 列表及计数,failed 项含 reason 说明" + ], + "details": { + "description": "包含拣货任务状态同步:全部拣完→任务状态=2(已完成),未全拣完→任务状态推进为1(拣货中)" + }, + "type": "added" + }, + { + "version": "2026.06.14-system-01", + "date": "2026-06-14", + "summary": "新增 order.bindExpressPackageMaterialByWaybill 方法:支持仅凭运单号绑定包材,无需传入订单ID", + "methods": [ + "order.bindExpressPackageMaterialByWaybill" + ], + "notes": [ + "新增 order.bindExpressPackageMaterialByWaybill 入参说明:waybill_code(运单号,必填)、package_material_code(包材编码,必填)。无需传入 order_id。", + "成功返回字段:order_id、waybill_code、package_material_id、package_material_name_snapshot、package_material_code。", + "错误码定义:400(参数错误)、404(运单号不存在 / 包材编码不存在)、500(绑定包材失败)。" + ], + "type": "added" + }, + { + "version": "2026.06.15-system-01", + "date": "2026-06-15", + "summary": "order.detail / order.deliveryOrder.detail 的 expresses 数组新增包材字段", + "methods": [ + "order.detail", + "order.deliveryOrder.detail" + ], + "notes": [ + "expresses 数组每个元素新增 package_material_id(包材ID,number|null)和 package_material_name_snapshot(包材名称快照,string|null)字段。" + ], + "type": "updated" + }, + { + "version": "2026.06.15-system-02", + "date": "2026-06-15", + "summary": "order.deliveryOrder.detail 的 expresses 数组新增包材字段", + "methods": [ + "order.deliveryOrder.detail" + ], + "notes": [ + "expresses 数组每个元素新增 package_material_id(包材ID,number|null)和 package_material_name_snapshot(包材名称快照,string|null)字段。" + ], + "type": "updated" + }, + { + "version": "2026.06.15-system-03", + "date": "2026-06-15", + "summary": "新增 setting.packageMaterial.search 方法:支持按关键字模糊搜索包材编码和名称", + "methods": [ + "setting.packageMaterial.search" + ], + "notes": [ + "新增 setting.packageMaterial.search 入参 keyword(可选),为空返回前 50 条启用中包材,有值时对 material_code 和 material_name 做模糊匹配。", + "返回包材数组,字段:id、material_code、material_name、material_type、spec、status。" + ], + "type": "added" + }, + { + "version": "2026.06.16-system-01", + "date": "2026-06-16", + "summary": "新增 order.recheckOrder.queryRecheckOrderSingleList:散单复核列表接口,响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", + "methods": [ + "order.recheckOrder.queryRecheckOrderSingleList" + ], + "notes": [ + "新增方法 order.recheckOrder.queryRecheckOrderSingleList,为 recheckOrderList 散单模式的独立入口。", + "响应 list 每项新增字段 items_weight (DECIMAL(10,2)):订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null。", + "响应 list 每项新增字段 weight_type (string):重量类型中文标签,来自 wms_order.weight_type 经 formatWeightTypeLabel 转换;取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。" + ], + "type": "added", + "module": "order.recheckOrder" + }, + { + "version": "2026.06.16-system-02", + "date": "2026-06-16", + "summary": "为 order.wave.groupOrderFetchList / waveStrategyFallbackOrderList / singleOrderFetchList 响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", + "methods": [ + "order.wave.groupOrderFetchList", + "order.wave.waveStrategyFallbackOrderList", + "order.wave.singleOrderFetchList" + ], + "notes": [ + "order.wave.groupOrderFetchList:响应 list 每项新增 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", + "order.wave.waveStrategyFallbackOrderList:响应 list 每项新增 items_weight (number|null):订单总重量(g),来自 wms_order.items_weight;新增 weight_type (string):重量类型中文标签,取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。", + "order.wave.singleOrderFetchList:响应 list 每项新增 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", + "所有新增字段均为可选(required=false),为 null 时返回 null。" + ], + "type": "updated", + "module": "order.wave" + }, + { + "version": "2026.06.17-system-01", + "date": "2026-06-17", + "summary": "新增 order.pendingOrder.replenishmentDemand 分拣缺货补货需求计算接口文档", + "methods": [ + "order.pendingOrder.replenishmentDemand" + ], + "notes": [ + "新增分拣缺货补货需求计算方法,用于计算待处理订单的SKU在分拣区与存货区的库存分布及补货缺口", + "入参 order_ids/warehouse_id 均为可选;不传 order_ids 时自动查询当前仓库所有未完成储位分配的订单", + "纯只读查询接口,不修改任何数据", + "响应包含 list(明细)与 summary(汇总),其中 shortage = max(0, total_demand - pick_zone_quantity),replenishment_needed = min(shortage, storage_zone_quantity)" + ], + "type": "add", + "module": "order.pendingOrder" + }, + { + "version": "2026.06.17-system-02", + "date": "2026-06-17", + "type": "update", + "module": "order.pendingOrder", + "method": "order.pendingOrder.replenishmentDemand", + "description": "移除 order_ids 参数,改为纯仓库级别计算,自动查询当前仓库所有未完成储位分配的订单" + }, + { + "version": "2026.06.17-system-03", + "date": "2026-06-17", + "type": "update", + "module": "order.pendingOrder", + "method": "order.pendingOrder.replenishmentDemand", + "description": "新增 is_true_shortage 字段标识真正缺货(两区均无库存),summary 新增 total_true_shortage_skus 统计" + }, + { + "version": "2026.06.17-system-04", + "date": "2026-06-17", + "type": "migrate", + "module": "storage.management", + "summary": "从 order.pendingOrder.replenishmentDemand 迁移至 storage.management.replenishmentDemand(库存管理模块),原路径已删除,开发阶段无需兼容", + "methods": [ + "storage.management.replenishmentDemand" + ], + "notes": [ + "将 replenishmentDemand 接口从 order.pendingOrder 模块迁移到新建的 storage.management 库存管理模块。", + "旧条目 order.pendingOrder.replenishmentDemand 已从 order.pendingOrder 组中移除。", + "开发阶段无需兼容旧路径。" + ] + }, + { + "version": "2026.06.17-system-05", + "date": "2026-06-17", + "type": "update", + "module": "storage.management", + "summary": "storage.management.replenishmentDemand 移除 warehouse_id 入参,仓库ID改为纯从用户上下文(ctx.user)获取,接口无需入参", + "methods": [ + "storage.management.replenishmentDemand" + ], + "notes": [ + "移除 warehouse_id 入参,仓库ID改为纯从用户上下文(ctx.user)获取,接口无需入参" + ] + }, + { + "version": "2026.06.17-system-06", + "date": "2026-06-17", + "type": "update", + "module": "storage.management", + "method": "storage.management.replenishmentDemand", + "description": "新增分页入参(pagination)、排序入参(sort,默认按 shortage DESC)、响应新增 replenishment_locations(存货区可补货库位,最多5条)、响应新增 pagination 分页信息" + }, + { + "version": "2026.06.17-system-07", + "date": "2026-06-17", + "type": "update", + "module": "storage.management", + "summary": "replenishment_locations 新增 space_name 字段,优先取自定义名称(custom_name),无则回退库位编码(space_code)", + "methods": [ + "storage.management.replenishmentDemand" + ], + "notes": [ + "在 replenishment_locations.children 中新增 space_name 字段(string, required),放在 space_code 之后、available_quantity 之前。", + "space_name 取值逻辑:优先使用库位自定义名称 custom_name,若无自定义名称则回退为库位编码 space_code。" + ] + }, + { + "version": "2026.06.17-system-08", + "date": "2026-06-17", + "type": "update", + "module": "storage.management", + "summary": "合并 is_sufficient 和 is_true_shortage 为 replenishment_status 枚举字段(replenishable/true_shortage)", + "methods": [ + "storage.management.replenishmentDemand" + ], + "notes": [ + "删除 is_sufficient(boolean)和 is_true_shortage(boolean)两个字段。", + "新增 replenishment_status(string)枚举字段:replenishable=存货区足够覆盖缺口,移库可解决;true_shortage=存货区不足以覆盖缺口或两区均无库存,需采购。" + ] + }, + { + "version": "2026.06.18-system-01", + "date": "2026-06-18", + "summary": "入库单完成后异步匹配收货单并回传:completeEntry / entryorderConfirm 入库完成时自动匹配收货单,明细一致则按来源回传(奇门/OpenAPI),覆盖场景标记收货单部分入库;completeReceiving 完成后清除收货单缓存", + "methods": [ + "storage.entry.completeEntry", + "storage.receiving.completeReceiving" + ], + "notes": [ + "新增 app/service/systems/receiving_entry_match.js:入库单完成后异步匹配收货单并回传的核心服务,含 Redis 缓存收货单列表(TTL 300s)、remark 匹配收货单号、明细对比、奇门回传、OpenAPI 回调、部分入库标记等能力。", + "storage.entry.completeEntry 完成后通过 setImmediate 异步触发 matchAfterEntryCompleted,不阻塞主流程。", + "entry_order.js entryorderConfirm() 事务提交后(isFin 最终完成)同样异步触发匹配。", + "storage.receiving.completeReceiving 完成后清除收货单 Redis 缓存(cache:receiving_orders:warehouse:{warehouseId}),确保下次匹配获取最新收货单列表。", + "匹配规则:入库单 remark 包含收货单号 → 对比 SKU+数量 → 完全一致回传 / 收货单覆盖标记部分入库 / 其他不处理。", + "回传路径:source_type=QM → 奇门 taobao.qimen.entryorder.confirm;source_type=API → OpenAPI 回调(entry_order_receiving_matched 事件)。" + ], + "type": "updated" + }, + { + "version": "2026.06.18-system-02", + "date": "2026-06-18", + "summary": "新增 storage.receiving.manualMatchEntryOrder 接口", + "methods": [ + "storage.receiving.manualMatchEntryOrder" + ], + "notes": [ + "新增 storage.receiving.manualMatchEntryOrder:手动匹配入库单与收货单,传入 receivingId 和 entryOrderId,复用异步匹配服务的明细对比和回传逻辑,同步返回匹配结果", + "参数:receivingId (number, 必填)、entryOrderId (number, 必填)", + "校验:入库单存在性、收货单存在性、同仓库校验", + "返回 matchType (full_match/receiving_covers_entry/entry_exceeds_receiving/no_match)、comparisonResult、callbackSent、callbackResult、partialStorageMarked、entryOrder、receivingOrder" + ], + "type": "added", + "module": "storage" + }, + { + "version": "2026.06.18-system-03", + "date": "2026-06-18", + "summary": "新增 storage.receiving.getAvailableInboundQuantity 接口:按 stock_id 查询已审核收货单的可入库数量(actual_quantity - stored_quantity),排除未审核和已取消的收货单", + "methods": [ + "storage.receiving.getAvailableInboundQuantity" + ], + "notes": [ + "新增 system method:storage.receiving.getAvailableInboundQuantity,按 stock_id 查询已审核收货单中各明细的可入库数量(actual_quantity - stored_quantity),仅返回尚有可入库余量的明细。", + "实现文件:app/service/systemMethods/storage/receiving.js(包装层)、app/service/systems/storage/receiving.js(业务层)。", + "接口无需鉴权(isNeedAuth=false),但需要登录(isNeedLogin=true)。", + "入参 stock_id 为必填,对应 stock_warehouse.id;服务端从 ctx.user.store_id 获取仓库上下文。" + ], + "type": "added", + "module": "storage" + }, + { + "version": "2026.06.18-system-04", + "date": "2026-06-18", + "summary": "新增 storage.entry.bindReceivingDetails 接口和 wms_entry_receiving_binding 中间表:入库单明细可显式绑定收货明细(pending状态),提交入库时事务内完成双向扣减(stored_quantity/received_quantity),通过唯一约束和行锁防止超分和重复绑定。同时重构 completeEntry 调用链为 commitEntryWithBindings,无绑定时向后兼容。", + "methods": [ + "storage.entry.bindReceivingDetails", + "storage.entry.completeEntry" + ], + "notes": [ + "新增 storage.entry.bindReceivingDetails 方法:入库单明细绑定收货明细,pending 状态软绑定,每次调用清除旧 pending 绑定后创建新绑定。", + "新增 wms_entry_receiving_binding 中间表(migration: 20260618150000-create-wms-entry-receiving-binding.js),用于记录入库明细与收货明细的绑定关系。", + "重构 completeEntry 调用链:systemMethods 层 completeEntry 改为调用 commitEntryWithBindings,有绑定则事务内完成双向扣减(stored_quantity/received_quantity),无绑定时向后兼容仅变更入库单状态。", + "通过数据库唯一约束和行锁(SELECT ... FOR UPDATE)防止超分和重复绑定。", + "涉及文件: app/model/entry_receiving_binding.js, app/service/systems/storage/entry.js, app/service/systemMethods/storage/entry.js, database/migrations/20260618150000-create-wms-entry-receiving-binding.js" + ], + "type": "added", + "module": "storage.entry" + }, + { + "version": "2026.06.18-system-05", + "date": "2026-06-18", + "summary": "storage.entry.get 响应追加 pending_total/total_planned/bindings 字段,storage.receiving.getAvailableInboundQuantity 响应追加 pending_allocated_quantity 字段:前端可通过 get 查看入库明细的绑定状态,getAvailableInboundQuantity 的可用量已扣除全局 pending 绑定总量", + "methods": [ + "storage.entry.get", + "storage.receiving.getAvailableInboundQuantity" + ], + "notes": [ + "storage.entry.get:items 数组每项新增 pending_total(该入库明细当前 pending 绑定的总预分配数量)、total_planned(计划入库数量=count)、bindings(pending 绑定列表,每项含 id/entry_item_id/receiving_detail_id/allocated_quantity/status/receivingDetail 子对象)", + "storage.receiving.getAvailableInboundQuantity:list 每项新增 pending_allocated_quantity(该收货明细在当前 stock_id 所有入库单中的 pending 绑定总量),available_quantity 计算已扣除该值" + ], + "type": "updated" + }, + { + "version": "2026.06.18-system-06", + "date": "2026-06-18", + "summary": "bindReceivingDetails 重构为\"绑定即实收\"(received_quantity 在绑定时更新,不再等到 completeEntry),新增 unbindReceivingDetails 解绑接口(删除 pending 绑定并回退 received_quantity),commitEntryWithBindings 移除 received_quantity 更新逻辑", + "methods": [ + "storage.entry.bindReceivingDetails", + "storage.entry.unbindReceivingDetails", + "storage.entry.completeEntry" + ], + "notes": [ + "storage.entry.bindReceivingDetails:改为绑定即实收,绑定成功后立即更新入库明细 received_quantity;重复调用时先回退旧绑定量再创建新绑定,避免重复累加。", + "storage.entry.unbindReceivingDetails:新增解绑接口,删除该入库明细的所有 pending 绑定记录,并将 received_quantity 回退到绑定前的值;收货明细可用数量随绑定记录删除自动恢复。", + "storage.entry.completeEntry:commitEntryWithBindings 中移除 received_quantity 更新逻辑(received_quantity 已在绑定时更新,completeEntry 仅完成收货单侧入库数量扣减和库存上架)。" + ], + "type": "updated" + }, + { + "version": "2026.06.19-system-01", + "date": "2026-06-19", + "summary": "order.recheckOrder.scanOrder 响应 list[] 新增 items_weight(订单商品总重量g)和 suggested_package_material(推荐包材)字段", + "methods": [ + "order.recheckOrder.scanOrder" + ], + "notes": [ + "响应 list 每项新增 items_weight (number|null):订单商品总重量(g),来源于 wms_order_delivery.items_weight。散单模式每个订单对象包含,团购模式每个波次对象包含(取波次内首个正常订单的重量,为 null 时返回 0)。", + "响应 list 每项新增 suggested_package_material (object|null):推荐包材信息,根据订单商品结构(items_hash + items_crc)匹配 wms_package_material_item_relation 历史绑定记录,按 bind_count 降序取最优匹配。若 items_hash 为空或无匹配记录则为 null。包含子字段:id、code、name、spec、type、weight、length、width、height、bind_count。", + "同步更新 method description 和 list 字段 description,补充新增字段的说明。" + ], + "type": "updated", + "module": "order.recheckOrder" + }, + { + "version": "2026.06.21-system-01", + "date": "2026-06-21", + "summary": "order.bindExpressPackageMaterialByWaybill:入参 package_material_code 改为 package_material_id,类型由 string 改为 number|string", + "methods": [ + "order.bindExpressPackageMaterialByWaybill" + ], + "notes": [ + "入参字段名从 package_material_code 改为 package_material_id。", + "入参类型从 string 改为 number|string,与代码 normalizePackageMaterialId 的实现一致。", + "同步更新该方法 description 中'包材编码'为'包材ID'。" + ], + "type": "updated", + "module": "order" + }, + { + "version": "2026.06.21-system-comboGoods-01", + "date": "2026-06-21", + "summary": "新增 comboGoods 组合商品模块 5 个接口文档:list/create/update/delete/search", + "methods": [ + "comboGoods.list", + "comboGoods.create", + "comboGoods.update", + "comboGoods.delete", + "comboGoods.search" + ], + "notes": [ + "comboGoods.list:组合商品列表查询(分页),支持按 combo_code/combo_name/status/warehouse_id 筛选,返回含 simpleNotation 和 nameNotation 简记字段", + "comboGoods.create:创建组合商品(含明细一次性提交),校验 combo_code 唯一性、子商品有效性和货主一致性,事务保证原子写入", + "comboGoods.update:编辑组合商品(含明细替换),支持部分字段更新,传入 items 则先删旧明细再插入新明细", + "comboGoods.delete:软删除组合商品(status 置为 0)", + "comboGoods.search:关键字搜索组合商品,模糊匹配 combo_code 或 combo_name,仅返回启用状态记录,上限100条", + "数据表:wms_combo_goods(主表)+ wms_combo_goods_item(明细表);子商品校验依赖 wms_stock_warehouse 表", + "代码文件:app/service/systems/comboGoods.js(业务逻辑层)+ app/service/systemMethods/comboGoods.js(接口包装层)", + "isNeedAuth:list/search 无需鉴权,create/update/delete 需要鉴权" + ], + "type": "added", + "module": "comboGoods" + }, + { + "version": "2026.06.21-system-comboGoods-02", + "date": "2026-06-21", + "summary": "comboGoods 模块新增 custom_code(自定义编码)功能:create/update 支持传入 custom_code 并校验按货主唯一,list/search 返回新增 custom_code 字段,search 搜索范围扩展至 custom_code 且优先排列匹配项", + "methods": [ + "comboGoods.list", + "comboGoods.create", + "comboGoods.update", + "comboGoods.search" + ], + "notes": [ + "新增字段 custom_code(VARCHAR(64) NULL),仅做按货主唯一性校验(排除已删除记录),非全局唯一。", + "wms_combo_goods 表新增索引 uk_store_custom_code(warehouse_id, custom_code)。", + "comboGoods.create:新增可选入参 custom_code,如果非空则校验同货主非删除记录中 unique;返回新增 custom_code 字段。", + "comboGoods.update:新增可选入参 custom_code,如果非空则校验同货主非删除记录中 unique(排除自身 id)。", + "comboGoods.list:返回每条记录新增 custom_code 字段。", + "comboGoods.search:搜索条件扩大为 custom_code LIKE / combo_code LIKE / combo_name LIKE,custom_code 匹配项按 ORDER BY CASE 排在前面;返回新增 custom_code 字段。" + ], + "type": "updated" + }, + { + "version": "2026.06.21-system-comboGoods-03", + "date": "2026-06-21", + "summary": "stock.warehouse.search 新增 mode=\"combo\" 组合商品查询模式,新增 id/custom_code 参数,补充组合商品响应结构", + "methods": [ + "stock.warehouse.search" + ], + "notes": [ + "新增入参 mode(查询模式,传 \"combo\" 时搜索组合商品),id(mode=combo 时按组合商品ID精确查询),custom_code(mode=combo 时按自定义编码模糊查询)", + "原有 keyword 参数在 mode=combo 时模糊匹配 combo_code / combo_name / custom_code", + "mode=combo 响应结构新增 combo_code、combo_name、custom_code、items(子商品数组含 item_goods_sku_id/item_quantity)、simpleNotation(stock_id|数量格式)、nameNotation(【数量】商品名称格式)", + "mode=combo 时不返回 stock 模式特有的字段(item_code/goods_code/item_name/sku_property/stock_unit/quantity/locked_quantity/brand_name/item_type/barcodes/store_stock/效期字段/storage)", + "with_stock 和 is_batch 参数在 mode=combo 时不生效" + ], + "type": "updated" + }, + { + "version": "2026.06.22-system-wavePickTaskList-01", + "date": "2026-06-22", + "summary": "order.wave.wavePickTaskList 响应新增 wave_list 数组:每个拣货任务返回关联波次列表", + "methods": [ + "order.wave.wavePickTaskList" + ], + "notes": [ + "wavePickTaskList 响应 list 每项新增 wave_list 数组字段,通过批量查询 wms_wave_pick_task_wave 表获取关联波次详情。", + "wave_list 每项包含:wave_id(波次ID)、wave_no(波次号)、box_no(框号)、status(波次关联状态)、bind_time(绑定时间)、pick_time(拣货完成时间)。", + "无需额外入参,默认对所有拣货任务返回 wave_list;查询为空时返回空数组 []。", + "同步更新 methods/system.json 响应文档。" + ], + "type": "updated", + "module": "order.wave" + }, + { + "version": "2026.06.22-system-order-export-mode-01", + "date": "2026-06-22", + "summary": "order.export 新增 export_mode 参数:支持 waybill(默认,按运单展开)与 item(按商品明细展开)两种导出模式", + "methods": [ + "order.export" + ], + "notes": [ + "新增入参 export_mode/exportMode,枚举值:waybill(默认)— 按运单号展开,每运单一组,items_detail 列汇总商品;item — 按商品明细展开,每商品一行,运单信息汇总填充。", + "方法层(OrderIndexService.export)新增 export_mode/exportMode 解构并透传到 systems.orderExport.exportOrders。", + "同步更新 methods/system.json 文档:description 补充 export_mode 说明,params 新增 export_mode/exportMode 条目。", + "order.export 导出的列新增:业务类型、运单接口、包材ID、包材编码、包材名称。" + ], + "type": "updated", + "module": "order.index" + }, + { + "version": "2026.06.22-system-directInbound-01", + "date": "2026-06-22", + "summary": "新增 storage.directInbound 导入/PDA直接入库模块:getItems(获取入库信息)、addItem(增量添加商品)、commit(提交完成入库并回传)", + "methods": [ + "storage.directInbound.getItems", + "storage.directInbound.addItem", + "storage.directInbound.commit" + ], + "notes": [ + "新增 storage.directInbound 模块,用于非收货单途径的导入/PDA 直接入库场景。", + "storage.directInbound.getItems:根据入库单号获取入库明细及已有的导入/PDA 入库记录,返回每项的可入库余量。", + "storage.directInbound.addItem:按 stock_id 增量添加导入/PDA 入库记录,累加超过该 stock_id 在入库单中的计划总量时拒绝。支持 import(导入)和 pda(PDA)两种方式。", + "storage.directInbound.commit:提交确认完成入库,按实收数量写入 wms_storage 库存和 wms_storage_transaction 流水,同 stock_id 多条明细只写一次库存,更新入库单状态为 COMPLETED 并同步 sync_status=SUCCESS,异步触发奇门/API 回传(按实收数量回传)。不足量提交时未入库商品跳过。", + "新增数据表 wms_inbound_direct_log(migration: 20260622100000-create-wms-inbound-direct-log.js):记录非收货单途径入库操作,含 warehouse_id、stock_id、quantity、inbound_type(import/pda)、entry_order_id、operator 等字段。模型文件:app/model/inbound_direct_log.js。", + "新增操作日志:addItem 记录 DIRECT_INBOUND_ADD(异步),commit 记录 DIRECT_INBOUND_COMMIT(事务内)。commit 响应返回 order_status=COMPLETED 和 sync_status=SUCCESS。", + "涉及文件:app/service/systems/inbound_direct_log.js(业务层)、app/service/systemMethods/storage/direct_inbound.js(包装层)、app/model/inbound_direct_log.js、database/migrations/20260622100000-create-wms-inbound-direct-log.js、methods/system.json(新增导入/PDA入库模块)。", + "E2E 测试:test/e2e_direct_inbound.test.js(53项断言全覆盖)。" + ], + "type": "added", + "module": "storage.directInbound" + }, + { + "version": "2026.06.22-system-directInbound-02", + "date": "2026-06-22", + "summary": "storage.directInbound.addItem 新增批量模式(items 数组),getItems 响应 summary 新增 total_import/total_pda 分类型汇总", + "methods": [ + "storage.directInbound.addItem", + "storage.directInbound.getItems" + ], + "notes": [ + "addItem 新增批量模式:支持传入 items 数组一次添加多条商品,每项含 stock_id/quantity/inbound_type/remark。单条模式(stock_id/quantity/inbound_type 顶层字段)保持向后兼容。批量模式下所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。", + "addItem 批量模式响应结构:{ count, total_quantity, items: [...] },items 每项含 id/stock_id/quantity/inbound_type/plan_quantity/existing_before/existing_after/remaining。", + "getItems 响应 summary 新增 total_import(导入入库总数)和 total_pda(PDA入库总数)字段。", + "同步更新 methods/system.json 文档。" + ], + "type": "updated", + "module": "storage.directInbound" + }, + { + "version": "2026.06.22-system-directInbound-03", + "date": "2026-06-22", + "summary": "storage.directInbound 新增 space_id 库位支持:addItem 支持传入 space_id(单条和批量),commit 从入库记录取 space_id 写入 wms_storage 替代硬编码 1", + "methods": [ + "storage.directInbound.addItem", + "storage.directInbound.commit", + "storage.directInbound.getItems" + ], + "notes": [ + "addItem 新增可选入参 space_id(单条模式顶层字段 / 批量模式 items[].space_id),指定存放库位ID,关联 wms_location_space.id。", + "wms_inbound_direct_log 表新增 space_id 字段(migration: 20260622110000-add-space-id-to-wms-inbound-direct-log.js)。", + "commit 从入库记录中取第一个非空 space_id 写入 wms_storage,无记录时兜底使用库位 1。", + "getItems 响应中 direct_logs 每条记录包含 space_id 字段。", + "同步更新 methods/system.json 文档及模型文件。" + ], + "type": "updated", + "module": "storage.directInbound" + }, + { + "version": "2026.06.23-system-01", + "date": "2026-06-23", + "summary": "入库单(wms_entry_order)新增 CREATED 状态:order_status ENUM 从 CREATING/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED 扩展为 CREATING/CREATED/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED;默认值从 PENDING 变更为 CREATED;validTransitions 增加 CREATED 节点(CREATED→PENDING/CANCELLED,CREATING→CREATED/CANCELLED)", + "methods": [ + "storage.entry.list", + "storage.entry.get", + "storage.entry.cancel", + "storage.entry.completeEntry", + "storage.entry.bindReceivingDetails" + ], + "notes": [ + "Model 层:app/model/entry_order.js order_status ENUM 新增 CREATED,默认值从 PENDING 变更为 CREATED", + "Service 层:app/service/systems/entry_order.js addOrder 创建后状态从 CREATING→CREATED,validTransitions 增加 CREATED 节点", + "Service 层:app/service/systems/storage/entry.js createEntry 默认状态 PENDING→CREATED", + "Service 层:app/service/systems/storage/inventory.js 快捷入库默认 CREATED", + "文档同步:storage.entry.list where.order_status 枚举补充 CREATED;storage.entry.get description 补充 order_status 枚举含 CREATED;storage.entry.cancel 补充 CREATED 可作废说明;storage.entry.completeEntry/bindReceivingDetails 补充可操作状态含 CREATED" + ], + "type": "updated", + "module": "storage.entry" + }, + { + "version": "2026.06.23-system-02", + "date": "2026-06-23", + "summary": "入库单 CREATED 状态限制:CREATED 状态不允许绑定货物和完成入库,仅 PENDING/CONFIRMED/PARTIAL_RECEIVED 状态可操作", + "methods": [ + "storage.entry.cancel", + "storage.entry.completeEntry", + "storage.entry.bindReceivingDetails", + "storage.entry.unbindReceivingDetails" + ], + "notes": [ + "completeEntry / bindReceivingDetails / unbindReceivingDetails / commitEntryWithBindings 的可操作状态从原来的白名单(包含 CREATED)改为 PENDING / CONFIRMED / PARTIAL_RECEIVED,排除 CREATED。", + "CREATED 状态仅允许确认入库(→PENDING)或作废(→CANCELLED)。", + "storage.entry.cancel 补充明确 COMPLETED 状态不可作废,CREATED 可作废。", + "同步更新对应 method 的 description、errors 描述。" + ], + "type": "updated", + "module": "storage.entry" + }, + { + "version": "2026.06.23-system-03", + "date": "2026-06-23", + "summary": "storage.entry.cancel:CONFIRMED(已确认)状态不再允许作废,仅 CREATED 和 PENDING 可作废", + "methods": [ + "storage.entry.cancel" + ], + "notes": [ + "canCancel() 白名单移除 CONFIRMED,仅保留 CREATED 和 PENDING", + "validTransitions 中 CONFIRMED 不再可转为 CANCELLED", + "cancel() 方法新增 CONFIRMED 状态拦截,返回 400:已确认入库单不允许作废,请先完成收货", + "PARTIAL_RECEIVED 仍可作废,COMPLETED 不允许作废(行为不变)", + "更新 description 明确各状态可作废规则,errors 中补充 CONFIRMED 不可作废的说明" + ], + "type": "updated", + "module": "storage.entry" + }, + { + "version": "2026.06.23-system-04", + "date": "2026-06-23", + "summary": "入库单状态从 7 个简化为 5 个:移除 CONFIRMED 和 PARTIAL_RECEIVED,最终状态为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED;同步更新 storage.entry 所有 method 的状态枚举和错误信息描述", + "methods": [ + "storage.entry.list", + "storage.entry.get", + "storage.entry.cancel", + "storage.entry.completeEntry", + "storage.entry.bindReceivingDetails", + "storage.entry.unbindReceivingDetails" + ], + "notes": [ + "wms_entry_order.order_status ENUM 从 CREATING/CREATED/PENDING/CONFIRMED/PARTIAL_RECEIVED/COMPLETED/CANCELLED 简化为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED", + "storage.entry.list: where.order_status 描述和 where 参数描述中的状态枚举同步更新", + "storage.entry.get: entryOrder.order_status 描述同步更新", + "storage.entry.cancel: 移除 PARTIAL_RECEIVED 可作废和 CONFIRMED 不可作废的描述,仅保留 CREATED 和 PENDING 可作废,COMPLETED 不可作废", + "storage.entry.completeEntry: 可完成状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", + "storage.entry.bindReceivingDetails: 可操作状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", + "storage.entry.unbindReceivingDetails: 可操作状态从 PENDING/CONFIRMED/PARTIAL_RECEIVED 改为仅 PENDING", + "cancel() 取消 CONFIRMED 状态拦截(状态已不存在),COMPLETED 拦截保持不变" + ], + "type": "updated" + }, + { + "version": "2026.06.23-system-05", + "date": "2026-06-23", + "summary": "入库单状态语义调整:CREATED=已创建待审核,PENDING=已审核;同步更新 storage.entry 所有 method 的 description 中状态说明", + "methods": [ + "storage.entry.list", + "storage.entry.get", + "storage.entry.cancel", + "storage.entry.completeEntry", + "storage.entry.bindReceivingDetails", + "storage.entry.unbindReceivingDetails" + ], + "notes": [ + "CREATED 含义从\"已创建\"改为\"已创建待审核\"(需审核后才能绑定和完成入库)", + "PENDING 含义从\"待收货/收货中\"改为\"已审核\"(审核通过,可绑定和完成入库)", + "CREATED→PENDING 步骤语义:绑定审核", + "addOrder() 新增可选参数 autoReview(boolean,默认 false),false 创建后状态 CREATED(需审核),true 创建后状态 PENDING(自动审核通过)", + "快捷入库 quickPutaway 内部流程改为调用 addOrder({autoReview:true}) → bindReceivingDetails → commitEntryWithBindings,不再直接写库存,对外返回格式不变", + "storage.entry.list / storage.entry.get description 中补充 CREATED/PENDING 语义说明", + "storage.entry.cancel description 中补充可作废状态说明", + "storage.entry.completeEntry description 中补充可完成状态说明", + "storage.entry.bindReceivingDetails / storage.entry.unbindReceivingDetails description 中补充可绑定/解绑状态说明" + ], + "type": "updated" + }, + { + "version": "2026.06.23-system-06", + "date": "2026-06-23", + "summary": "storage.inventory.quickPutaway description 更新:补充内部已改为走 addOrder→bind→commit 链路,不再直接写库存", + "methods": [ + "storage.inventory.quickPutaway" + ], + "notes": [ + "快捷入库 quickPutaway 内部流程改为调用 addOrder({autoReview:true}) → bindReceivingDetails → commitEntryWithBindings,不再直接写库存,外部返回格式不变", + "description 中补充内部调用链路说明" + ], + "type": "updated" + }, + { + "version": "2026.06.23-system-07", + "date": "2026-06-23", + "summary": "storage.entry 大范围清理:删除 bindReceivingDetails/unbindReceivingDetails(明细级绑定已弃用),更新 completeEntry 为纯状态变更(不再做库存写入/异步匹配)", + "methods": [ + "storage.entry.bindReceivingDetails", + "storage.entry.unbindReceivingDetails", + "storage.entry.completeEntry" + ], + "notes": [ + "storage.entry.bindReceivingDetails:已从代码中删除,明细级绑定收货单功能下线。库存写入统一由 storage.inventory.matchPutaway 完成。", + "storage.entry.unbindReceivingDetails:已从代码中删除,明细级解绑功能下线。", + "storage.entry.completeEntry:改为纯状态变更(PENDING → COMPLETED),不再做库存写入和异步匹配回调。库存写入统一由 storage.inventory.matchPutaway 完成。" + ], + "type": "updated" + }, + { + "version": "2026.06.23-system-08", + "date": "2026-06-23", + "summary": "storage.inventory 清理:删除 quickPutaway(快捷入库已下线,统一由 matchPutaway 完成匹配入库)", + "methods": [ + "storage.inventory.quickPutaway" + ], + "notes": [ + "storage.inventory.quickPutaway:已从代码中删除,快捷入库功能下线。请使用 storage.inventory.matchPutaway 替代。" + ], + "type": "removed" + }, + { + "version": "2026.06.23-system-09", + "date": "2026-06-23", + "summary": "入库流程弃用清理:bindReceivingDetails/unbindReceivingDetails 标记为已删除并补充弃用原因,completeEntry 明确不涉及库存写入", + "methods": [ + "storage.entry.bindReceivingDetails", + "storage.entry.unbindReceivingDetails", + "storage.entry.completeEntry" + ], + "notes": [ + "storage.entry.bindReceivingDetails 与 storage.entry.unbindReceivingDetails 已从代码中移除,入库单与收货单关系改为 wms_entry_order_receiving 主表级关联,不再需要逐明细绑定/解绑。", + "wms_entry_receiving_binding 表不再写入新数据。", + "storage.entry.completeEntry 仅做状态变更(PENDING→COMPLETED),库存写入统一由 storage.inventory.matchPutaway 完成。", + "commitEntryWithBindings(内部方法)不再使用,库存写入统一走 matchPutaway 链路。" + ], + "type": "updated" + }, + { + "version": "2026.06.23-system-10", + "date": "2026-06-23", + "summary": "quickPutaway 弃用说明完善:明确替代方案为 matchPutaway;matchPutaway 标明为目前唯一库存写入入库链路", + "methods": [ + "storage.inventory.quickPutaway", + "storage.inventory.matchPutaway" + ], + "notes": [ + "storage.inventory.quickPutaway 已从代码中移除,替代方案为 storage.inventory.matchPutaway(支持多收货单+多入库单批量匹配入库)。", + "storage.inventory.matchPutaway 是目前唯一的库存写入入库链路,入库单状态变更由 storage.entry.completeEntry 单独处理。", + "本次为文档补充说明,不涉及代码变更。" + ], + "type": "updated" + }, + { + "version": "2026.06.23-system-11", + "date": "2026-06-23", + "summary": "删除 storage.receiving.getAvailableInboundQuantity:该方法依赖已弃用的 wms_entry_receiving_binding 明细绑定表,已从代码中移除", + "methods": [ + "storage.receiving.getAvailableInboundQuantity" + ], + "notes": [ + "该方法原用于按 stock_id 查询已审核收货单中各明细的可入库数量(actual_quantity - stored_quantity - pending_allocated_quantity)。", + "由于 wms_entry_receiving_binding 明细绑定表已弃用,入库单与收货单的关联改为通过 wms_entry_order_receiving 主表级关联,该查询方法不再适用。", + "替代方案:使用 storage.entry.get 查询入库单详情,通过顶层 receivingBindings 获取关联的收货单信息。" + ], + "type": "removed" + }, + { + "version": "2026.06.23-system-12", + "date": "2026-06-23", + "summary": "storage.entry.get 响应结构变更:不再返回 items[].bindings(明细级绑定),改为返回顶层 receivingBindings(主表级关联收货单信息)", + "methods": [ + "storage.entry.get" + ], + "notes": [ + "移除 items[].bindings(明细级绑定,原基于 wms_entry_receiving_binding 表),该绑定表已弃用。", + "新增顶层 receivingBindings(wms_entry_order_receiving 主表级关联),每项含 id/receiving_id/receiving(含 id/receiving_number/status/storage_status/created_at)。", + "items 中保留 external_item_code/external_item_id/warehouse_item_code/warehouse_item_name/warehouse_item_spec 等扁平化字段。", + "响应结构变更与 storage.directInbound.getItems 的返回结构对齐,后者同样使用顶层 receivingBindings。" + ], + "type": "modified" + }, + { + "version": "2026.06.23-system-13", + "date": "2026-06-23", + "summary": "新增 storage.entry.* 下 4 个 DirectInbound 方法:getDirectInboundItems、addItem、commit、removeItem,原 storage.directInbound.* 方法保留向后兼容并标记 deprecated", + "methods": [ + "storage.entry.getDirectInboundItems", + "storage.entry.addItem", + "storage.entry.commit", + "storage.entry.removeItem" + ], + "notes": [ + "storage.entry.getDirectInboundItems:获取入库单的导入/PDA 入库信息,参数与响应格式同原 storage.directInbound.getItems", + "storage.entry.addItem:按商品增量添加导入/PDA 入库记录(支持单条和批量),参数与响应格式同原 storage.directInbound.addItem", + "storage.entry.commit:提交确认完成导入/PDA 入库,按实收数量写入库存并异步回传奇门/API,参数与响应格式同原 storage.directInbound.commit", + "storage.entry.removeItem:移除一条导入/PDA 入库记录,参数与响应格式同原 storage.directInbound.removeItem", + "底层 inbound_direct_log.js 实现不变,仅入口从 storage.directInbound 模块迁入 storage.entry 模块" + ], + "type": "added" + }, + { + "version": "2026.06.23-system-14", + "date": "2026-06-23", + "summary": "storage.directInbound.* 下 4 个方法标记 deprecated,指向 storage.entry.* 下对应新方法", + "methods": [ + "storage.directInbound.getItems", + "storage.directInbound.addItem", + "storage.directInbound.commit", + "storage.directInbound.removeItem" + ], + "notes": [ + "storage.directInbound.getItems → 替代方法 storage.entry.getDirectInboundItems", + "storage.directInbound.addItem → 替代方法 storage.entry.addItem", + "storage.directInbound.commit → 替代方法 storage.entry.commit", + "storage.directInbound.removeItem → 替代方法 storage.entry.removeItem", + "旧方法保留向后兼容,参数与响应格式不变,仅入口模块变更" + ], + "type": "deprecated" + }, + { + "version": "2026.06.23-system-15", + "date": "2026-06-23", + "summary": "storage.inventory.matchPutaway 标记 deprecated,替代方案为 storage.entry.commit", + "methods": [ + "storage.inventory.matchPutaway" + ], + "notes": [ + "storage.inventory.matchPutaway 已弃用,请迁移至 storage.entry.commit", + "commit 提供导入/PDA 入库完成确认功能,按实收数量写入库存并异步回传" + ], + "type": "deprecated" + }, + { + "version": "2026.06.23-system-16", + "date": "2026-06-23", + "summary": "清理已弃用 method 条目:从 system.json 删除 storage.entry.bindReceivingDetails、storage.entry.unbindReceivingDetails、storage.inventory.matchPutaway 三个已从代码中移除的 method 文档条目", + "methods": [ + "storage.entry.bindReceivingDetails", + "storage.entry.unbindReceivingDetails", + "storage.inventory.matchPutaway" + ], + "notes": [ + "storage.entry.bindReceivingDetails:已从代码中删除,明细级绑定收货单功能下线。入库单与收货单关系改为 wms_entry_order_receiving 主表级关联。", + "storage.entry.unbindReceivingDetails:已从代码中删除,明细级解绑功能下线。", + "storage.inventory.matchPutaway:已从代码中删除,匹配入库功能下线。替代方案为 storage.entry.commit。", + "storage.inventory.quickPutaway:之前已标记 [已删除],本次确认条目保留(与 matchPutaway 同一 group,保留作为历史参考)。", + "storage.entry.create / addDetail / deleteDetail / detailChange:systems 层方法已删除,但从未在 system.json 中暴露为 API method,无需文档变更。" + ], + "type": "removed" + }, + { + "version": "2026.06.23-system-17", + "date": "2026-06-23", + "summary": "storage.entry.get 响应新增仓库库存、条码、入库进度字段", + "methods": [ + "storage.entry.get" + ], + "notes": [ + "items 每项新增 warehouse_quantity(仓库库存总量)、warehouse_locked_quantity(锁定数量)、warehouse_is_batch_mgmt(是否批次管理)、warehouse_is_shelf_life_mgmt(是否效期管理)、warehouse_image_url(商品图片URL)、warehouse_is_images(是否有图片)", + "items 每项新增 barcodes(条码列表,每项含 id/barcode/sku_property)", + "items 每项新增 direct_inbound_quantity(导入/PDA已入库数量)、remaining_quantity(剩余可入库数量)", + "同步更新 response 字段定义,将原有概要描述展开为逐字段说明", + "仅文档同步,不改业务代码" + ], + "type": "updated", + "module": "storage.entry" + }, + { + "version": "2026.06.24-system-01", + "date": "2026-06-24", + "summary": "新增批量绑定入库单明细与收货单明细接口 storage.entry.bindReceivingDetails,支持明细级数量分配与部分成功", + "methods": [ + "storage.entry.bindReceivingDetails" + ], + "notes": [ + "新增 storage.entry.bindReceivingDetails:批量绑定入库单明细与收货单明细,支持明细级数量分配与部分成功", + "storage.entry.get 追加 available_receiving_details 字段加载可匹配的收货单明细" + ], + "type": "addition" + }, + { + "version": "2026.06.24-system-02", + "date": "2026-06-24", + "summary": "storage.entry.bindReceivingDetails:response.failed 字段从简单 reason 描述升级为结构化错误返回(含 error_code、message、detail);同步更新 400 错误说明", + "methods": [ + "storage.entry.bindReceivingDetails" + ], + "notes": [ + "response.failed 新增 items 定义,每项含 entry_item_id、receiving_detail_id、allocated_quantity、error_code、message、detail", + "error_code 枚举:ENTRY_ITEM_NOT_FOUND、STOCK_NOT_FOUND、RECEIVING_DETAIL_MISMATCH、RECEIVING_DETAIL_NOT_FOUND、INSUFFICIENT_AVAILABLE_QUANTITY、ENTRY_ORDER_STATUS_INVALID", + "400 错误说明更新:入库单状态不允许绑定时,所有 bindings 均返回 failed 且 error_code 为 ENTRY_ORDER_STATUS_INVALID" + ], + "type": "updated" + }, + { + "version": "2026.06.24-system-03", + "date": "2026-06-24", + "summary": "新增 storage.entry.quickInbound 快捷直入/虚拟入库接口", + "methods": [ + "storage.entry.quickInbound" + ], + "notes": [ + "新增 quickInbound 方法:入库单所有商品按明细数量一键直入虚拟库位(space_id=2),跳过收货/质检流程", + "支持状态:CREATED、PENDING 状态的入库单可执行", + "拒绝状态:CANCELLED(已作废)、COMPLETED(已完成)", + "事务内操作:更新入库明细收货量、累加库存总量、写入库存流水、写入虚拟库位库存、变更入库单状态为 COMPLETED", + "事务外异步回传奇门/API" + ], + "type": "addition" + }, + { + "version": "2026.06.24-system-04", + "date": "2026-06-24", + "summary": "收窄 storage.entry.quickInbound 状态约束:仅允许 CREATED 状态执行快捷直入", + "methods": [ + "storage.entry.quickInbound" + ], + "notes": [ + "收窄状态约束:仅允许 CREATED 状态执行快捷直入,PENDING 状态不再允许" + ], + "type": "updated" + }, + { + "version": "2026.06.24-system-05", + "date": "2026-06-24", + "summary": "修正 storage.entry.quickInbound errors[4] message 以匹配代码实现:改为动态状态描述", + "methods": [ + "storage.entry.quickInbound" + ], + "notes": [ + "errors[4].message 从「入库单状态不允许快捷直入(仅支持CREATED状态)」改为「入库单状态不允许快捷直入,当前状态:非CREATED(如PENDING等)」,反映代码中 `${entryOrder.order_status}` 动态模板特性" + ], + "type": "updated" + }, + { + "version": "2026.06.24-system-06", + "date": "2026-06-24", + "summary": "新增入库单与收货单商品对照预览接口", + "methods": [ + "storage.entry.receivingCompare" + ], + "notes": [ + "新增 storage.entry.receivingCompare 方法:给定入库单ID和收货单ID,返回入库商品与收货商品的逐行对照视图。", + "comparison 列表中每项含 match_status(matched/entry_only),以及入库侧和收货侧的商品与数量信息。", + "receiving_only 列表包含仅存在于收货单中的商品明细。", + "summary 提供 total_entry_items、matched_items、entry_only_items、receiving_only_items 汇总统计。", + "纯只读接口,不产生任何数据写入或状态变更。" + ], + "type": "addition" + }, + { + "version": "2026.06.24-system-07", + "date": "2026-06-24", + "summary": "setting.warehouse 模块新增 7 个发件人信息字段到 subject_config", + "methods": [ + "setting.warehouse.getSettings", + "setting.warehouse.saveSettings" + ], + "notes": [ + "在 getSettings 的 response 中新增 subject_config.sender_name(发件人姓名)、sender_tel(发件人电话)、province_name(省份)、city_name(城市)、district_name(区/县)、town_name(镇/街道)、address(详细地址)共 7 个字段,均为可选字符串,默认空。", + "在 saveSettings 的 params 中新增对应的 7 个入参字段,source 为 body.subject_config,均为可选字符串,默认空,并标注 maxLength。", + "字段 key 与 store_warehouse.policy_config 中发件人字段命名完全一致,统一仓库级发件人默认值配置。", + "getFieldMeta 接口无需修改文档——其返回的字段元信息由 WAREHOUSE_SETTING_FIELDS 定义在运行时自动生成,新增字段会随代码自动纳入返回列表。" + ], + "type": "updated", + "module": "setting.warehouse" + }, + { + "version": "2026.06.25-system-01", + "date": "2026-06-25", + "summary": "新增 storage.entry.bindReceiving 接口:将收货单绑定到入库单(主表级关联,不做明细数量分配)", + "methods": [ + "storage.entry.bindReceiving" + ], + "notes": [ + "新增入库单与收货单的主表绑定接口,与已有的 storage.entry.bindReceivingDetails(明细级绑定)区分:bindReceiving 仅建立 wms_entry_order_receiving 主表关联,不做明细数量分配。", + "入库单需为 CREATED 或 PENDING 状态;收货单需存在、同仓库且未取消。", + "支持部分成功模式:逐条校验收货单,校验通过的建立绑定,不通过的返回 error_code 和 message。", + "响应包含 success(成功列表)、failed(失败列表)、success_count、failed_count。" + ], + "type": "addition" + }, + { + "version": "2026.06.25-system-02", + "date": "2026-06-25", + "summary": "storage.entry.bindReceiving:新增 OWNER_MISMATCH 错误码,用于收货单与入库单货主不一致校验", + "methods": [ + "storage.entry.bindReceiving" + ], + "notes": [ + "在 storage.entry.bindReceiving 的 errors 数组中新增 OWNER_MISMATCH(收货单与入库单货主不一致)错误码。", + "同步更新 response.failed.error_code 的枚举描述,补充 OWNER_MISMATCH。" + ], + "type": "updated", + "module": "storage.entry" + }, + { + "version": "2026.06.25-system-03", + "date": "2026-06-25", + "summary": "storage.entry.bindReceiving:新增收货单未审核错误码 RECEIVING_NOT_REVIEWED", + "methods": [ + "storage.entry.bindReceiving" + ], + "notes": [ + "在 errors 数组中新增错误码 RECEIVING_NOT_REVIEWED(收货单未审核),用于标识绑定前收货单尚未完成审核的场景。", + "同步更新 response.failed.items.properties.error_code.description,在可能值列表中补充 RECEIVING_NOT_REVIEWED。" + ], + "type": "updated" + }, + { + "version": "2026.06.25-system-04", + "date": "2026-06-25", + "summary": "storage.entry.list 响应新增 receivingBindings 和 hasReceiving 字段,where 新增 hasReceiving 虚拟筛选条件", + "methods": [ + "storage.entry.list" + ], + "notes": [ + "响应 list 数组每项新增 receivingBindings(收货单绑定列表,主表级关联)和 hasReceiving(是否存在收货单绑定,boolean)字段。", + "入参 where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单,内部通过 wms_entry_order_receiving 表查询实现。", + "同步更新 description 以说明 hasReceiving 虚拟筛选的使用方式。" + ], + "type": "updated" + }, + { + "version": "2026.06.26-system-01", + "date": "2026-06-26", + "summary": "storage.entry.receivingCompare 支持多收货单对照预览", + "methods": [ + "storage.entry.receivingCompare" + ], + "notes": [ + "支持多个收货单ID对照预览(新增 receiving_ids 数组入参,优先于 receiving_id 使用)", + "入参 receiving_id 从 required 改为 optional,与 receiving_ids 二选一", + "出参结构调整为 comparisons[] 数组(多收货单),新增 errors[] 和 total_summary", + "向后兼容原 receiving_id 单值传参(底层自动转为单元素数组)", + "新增 400 错误码:receiving_ids 或 receiving_id 必填", + "移除 404 错误码:收货单不存在(已改为在 comparisons[]/errors[] 中以 status=error 形式返回)" + ], + "type": "enhancement" + }, + { + "version": "2026.06.26-system-02", + "date": "2026-06-26", + "summary": "storage.receiving.getReceivingList 新增 filterDepleted 可选参数;storage.entry.receivingCompare 返回值 receiving_only 字段新增 receiving_allocated 和 receiving_available 说明", + "methods": [ + "storage.receiving.getReceivingList", + "storage.entry.receivingCompare" + ], + "notes": [ + "storage.receiving.getReceivingList:params 新增 filterDepleted(boolean, 默认 false),用于过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满)。", + "storage.entry.receivingCompare:response 中 receiving_only 字段的 description 补充 receiving_allocated(已分配数量)和 receiving_available(可再用量)两个子字段说明。" + ], + "type": "updated" + }, + { + "version": "2026.06.26-system-03", + "date": "2026-06-26", + "summary": "storage.receiving.getReceivingList:新增可选参数 entry_order_id,按入库单商品交集过滤收货单列表", + "methods": [ + "storage.receiving.getReceivingList" + ], + "notes": [ + "新增可选参数 entry_order_id(number),传入入库单 ID 后只返回至少有一条明细的 system_product_id 在入库单明细中存在的收货单。", + "与现有 filterDepleted 参数可组合使用,二者取交集。", + "不传则不过滤,保持原有行为不变。" + ], + "type": "updated" + }, + { + "version": "2026.06.27-system-01", + "date": "2026-06-27", + "summary": "新增 storage.entry.reviewEntry 接口:审核入库单(CREATED→PENDING),需绑定收货单", + "methods": [ + "storage.entry.reviewEntry" + ], + "notes": [ + "新增入库单审核接口,支持 CREATED→PENDING 状态流转。", + "审核前置条件:入库单必须已绑定收货单(EntryOrderReceiving 存在关联记录)。", + "审核通过后写入操作日志(ENTRY_ORDER_REVIEW)。" + ], + "type": "added" + }, + { + "version": "2026.06.29-system-01", + "date": "2026-06-29", + "summary": "storage.inventory.quickPutaway 重新实现:收货单快捷转入库单", + "methods": [ + "storage.inventory.quickPutaway" + ], + "notes": [ + "此前已从代码中删除(2026.06.23-system-08),现由 wms-dev-agent 重新实现。", + "核心流程:参数校验 → 加载收货单及明细 → 检查货主配置 policy_config.allow_receiving_quick_putaway → 按 stock_id(system_product_id)分组合并数量 → 创建入库单 SCRK(自动审批到 PENDING)→ 写入 wms_entry_order_receiving 主表级绑定 → 更新收货单 storage_status 为 partial → 更新收货单明细 storage_status/stored_quantity → 提交事务。", + "前置条件:收货单状态为 completed 且 is_review=true(已审核),货主仓库签约配置 allow_receiving_quick_putaway=1。", + "与旧实现的区别:不涉及 wms_entry_receiving_binding 明细级绑定,使用 wms_entry_order_receiving 主表级关联;直接创建入库单并写入绑定,不再走 matchPutaway 匹配链路。", + "返回:entry_order_id、entry_order_code(SCRK 格式)、order_status(PENDING)、receiving_id、total_lines、total_quantity。" + ], + "type": "addition" + }, + { + "version": "2026.06.29-system-02", + "date": "2026-06-29", + "summary": "storage.entry.list:quickWhere 搜索范围扩展,新增收货单 ID(receiving_id)支持 PDA 扫描托盘唛头搜索绑定的入库单", + "methods": [ + "storage.entry.list" + ], + "notes": [ + "quickWhere 搜索字段新增 receiving_id(收货单 ID / 托盘唛头),通过 wms_entry_order_receiving 绑定表关联搜索。", + "同步更新 description 和 where 参数的 description,明确 quickWhere 完整搜索字段列表:entry_order_code、purchase_order_code、supplier_name、store_name、warehouse_name、receiving_id。" + ], + "type": "updated", + "module": "storage" + }, + { + "version": "2026.06.29-system-03", + "date": "2026-06-29", + "summary": "新增 storage.receiving.scanDetail 接口:PDA 上架扫码定位收货明细", + "methods": [ + "storage.receiving.scanDetail" + ], + "notes": [ + "新增 storage.receiving.scanDetail(PDA专用):通过 entry_order_id + barcode 扫码快速定位收货明细。", + "搜索逻辑:纯数字 barcode 优先按明细 ID 精确匹配(托盘唛头),未命中则模糊匹配商品条码;非纯数字仅模糊匹配商品条码。", + "入参:entry_order_id(必填 number)、barcode(必填 string)。", + "出参:detail_id、receiving_id、barcode、product_name、actual_quantity、receiving_status。", + "错误码:入库单不存在或无权访问、该入库单尚未关联收货单、未找到匹配的收货明细。" + ], + "type": "added" + }, + { + "version": "2026.06.29-system-04", + "date": "2026-06-29", + "summary": "storage.receiving.scanDetail 响应结构从单条改为列表:返回 { list, total } 支持同一条码匹配多条明细", + "methods": [ + "storage.receiving.scanDetail" + ], + "notes": [ + "响应结构变更:原返回 data.detail_id/data.receiving_id 等单条字段,现改为顶层 list 数组 + total 计数。", + "同一条码可能匹配到多条收货明细(不同收货单的同一商品),以列表形式返回所有匹配结果。", + "list 中每条明细包含 detail_id/receiving_id/barcode/product_name/actual_quantity/receiving_status。", + "补充错误码:用户未绑定仓库、入库单ID/条码为空、未找到可用的收货明细、500服务器错误。", + "PDA专用接口,description 更新说明匹配逻辑。" + ], + "type": "updated", + "module": "storage.receiving" + }, + { + "version": "2026.06.30-system-01", + "date": "2026-06-30", + "summary": "新增 storage.entry.containerList:PDA 上架时拉取入库单绑定收货单中指定商品的可用容器列表", + "methods": [ + "storage.entry.containerList" + ], + "notes": [ + "新增接口 storage.entry.containerList,用于 PDA 上架场景拉取入库单已绑定收货单中指定 stock_id 的可用收货明细(容器)列表。", + "入参:entry_order_id(入库单ID,必填)、stock_id(商品 stock_id,必填)。", + "出参:data.list 返回可用明细列表,每项含 detail_id、receiving_id、barcode、product_name、actual_quantity、receiving_status;data.total 为总数。", + "已绑定占用的收货明细(wms_entry_receiving_binding 中已有记录且未软删除)会被排除。", + "PDA 专用接口,无需额外鉴权(isNeedAuth=false)。" + ], + "type": "added" + }, + { + "version": "2026.06.30-system-02", + "date": "2026-06-30", + "summary": "storage.entry.addItem 入参变更:entry_order_code → entry_order_id(number);quantity 改为可选(传入 receiving_detail_id 时自动计算);新增 receiving_detail_id/allocated_quantity 参数支持 PDA 上架收货明细绑定模式;space_id 绑定模式下必填", + "methods": [ + "storage.entry.addItem" + ], + "notes": [ + "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.addItem 实现对齐", + "quantity 改为可选:传入 receiving_detail_id 时自动从收货明细计算可用数量(actual_quantity - 已绑定数量)", + "新增 receiving_detail_id 参数:PDA 上架绑定收货明细时传入,触发预占绑定(wms_entry_receiving_binding status=pending)", + "新增 allocated_quantity 参数:预分配数量,默认等于 quantity", + "space_id 在绑定模式下必填;非绑定模式可选(commit 时兜底为 1)", + "PENDING 状态入库单必须传 receiving_detail_id 且已绑定收货单方可操作", + "CREATED + 已绑定收货单的入库单需先审核(reviewEntry)后才能上架", + "批量模式 items 数组同步支持 receiving_detail_id/allocated_quantity 字段", + "补充完整错误码列表:超量、可用数量不足、状态校验等" + ], + "type": "updated" + }, + { + "version": "2026.06.30-system-03", + "date": "2026-06-30", + "summary": "storage.entry.commit 入参变更:entry_order_code → entry_order_id(number),与底层 inboundDirectLog.commit 实现对齐", + "methods": [ + "storage.entry.commit" + ], + "notes": [ + "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.commit(entryOrderId) 实现对齐", + "补充 description 说明先同步后写库两段式流程:① 奇门/API 回传 → ② onSuccess 内事务写库存", + "补充 commit 后 EntryReceivingBinding 状态从 pending 更新为 committed 的说明" + ], + "type": "updated" + }, + { + "version": "2026.06.30-system-04", + "date": "2026-06-30", + "summary": "storage.directInbound.commit 入参变更:entry_order_code → entry_order_id(number),与底层 inboundDirectLog.commit 实现对齐", + "methods": [ + "storage.directInbound.commit" + ], + "notes": [ + "入参 entry_order_code(string) → entry_order_id(number),与底层 inboundDirectLog.commit(entryOrderId) 实现对齐", + "该方法已标记 deprecated,推荐使用 storage.entry.commit" + ], + "type": "updated" + }, + { + "version": "2026.06.30-system-05", + "date": "2026-06-30", + "summary": "storage.entry.getDirectInboundItems 响应结构重构:entryOrder 精简字段,items[].count→planned、direct_inbound_quantity→completed,items[].bindings 新增,移除 direct_logs/summary 等冗余字段", + "methods": [ + "storage.entry.getDirectInboundItems" + ], + "notes": [ + "entryOrder 精简为 id / entry_order_code / order_status / store_remask 四个字段", + "items[].count → planned(计划数量),items[].direct_inbound_quantity → completed(已完成数量)", + "items[].bindings 新增,结构为 { detail_id, binding_id, allocated_quantity, space_id, space_name }", + "items[].stock 新增,返回 getStockDetails 缓存的商品详情(item_code、item_name、barcodes 等)", + "移除 direct_logs(现有响应中已不存在该顶层字段)", + "移除 summary(现有响应中已不存在该字段)", + "移除 items[].received_quantity、items[].remaining_quantity、items[].pending_binding_total 等旧字段", + "新增 receivingBindings 字段说明:入库单层级收货单绑定关系" + ], + "type": "updated" + }, + { + "version": "2026.06.30-system-06", + "date": "2026-06-30", + "summary": "storage.directInbound.getItems 响应结构重构:entryOrder 精简字段,items[].count→planned、direct_inbound_quantity→completed,items[].bindings 新增,移除 direct_logs/summary 等冗余字段", + "methods": [ + "storage.directInbound.getItems" + ], + "notes": [ + "响应结构与 storage.entry.getDirectInboundItems 对齐(两者共用同一个底层实现 inboundDirectLog.getItems)", + "entryOrder 精简为 id / entry_order_code / order_status / store_remask", + "items[].count → planned,items[].direct_inbound_quantity → completed", + "items[].bindings 新增 { detail_id, binding_id, allocated_quantity, space_id, space_name }", + "items[].stock 新增", + "移除 direct_logs、summary、items[].received_quantity、items[].remaining_quantity 等旧字段", + "新增 receivingBindings 字段" + ], + "type": "updated" + }, + { + "version": "2026.06.30-system-07", + "date": "2026-06-30", + "summary": "storage.entry.containerList 响应结构补充 stock 字段:返回商品详情(item_code、item_name、barcodes 等)", + "methods": [ + "storage.entry.containerList" + ], + "notes": [ + "响应 list[].stock 字段补充为必返回:通过 getStockDetails 批量获取商品详情缓存", + "stock 对象包含 item_code、item_name、sku_property、barcodes 等字段" + ], + "type": "updated" + }, + { + "version": "2026.06.30-system-08", + "date": "2026-06-30", + "summary": "storage.receiving.scanDetail 响应结构补充 stock 字段:返回商品详情(item_code、item_name、barcodes 等)", + "methods": [ + "storage.receiving.scanDetail" + ], + "notes": [ + "响应 list[].stock 字段补充为必返回:通过 getStockDetails 批量获取商品详情缓存", + "stock 对象包含 item_code、item_name、sku_property、barcodes 等字段", + "完善 error 列表:补充 未找到可用的收货明细、未找到匹配的收货明细、入库单ID不能为空、扫描条码不能为空 等错误" + ], + "type": "updated" + }, + { + "version": "2026.06.30-system-09", + "date": "2026-06-30", + "summary": "订单列表 list 响应新增 store_remark(货主备注)字段", + "methods": [ + "order.list", + "order.reviewOrder.list", + "order.pendingOrder.list", + "order.expectionOrder.list", + "order.entrustOrder.list", + "order.deliveryOrder.list", + "order.deliveryExpectionOrder.list", + "order.archiveOrder.list" + ], + "notes": [ + "数据库字段 store_remask,返回给前端的字段名为 store_remark。", + "服务层从 wms_store_warehouse.store_remask 按 store_id+warehouse_id 聚合批量填充。", + "货主备注值可能为空字符串(当货主未设置备注时)。", + "该字段对订单列表的所有 method 均适用(current/dispatch/outsourced/history 模型均返回)。" + ], + "type": "updated" + }, + { + "version": "2026.07.02-system-02", + "date": "2026-07-02", + "summary": "新增 quick.waybill.toOrder 接口:根据运单号快速查询订单ID", + "methods": [ + "quick.waybill.toOrder" + ], + "notes": [ + "新增 quick 模块组(快捷查询)", + "查询 wms_order_express 表中 status=1 的有效记录", + "无需登录和鉴权(免登录/免鉴权)" + ], + "type": "added" + }, + { + "version": "2026.07.02-system-01", + "date": "2026-07-02", + "summary": "修正 quick.waybill.toOrder 的 isNeedLogin 为 true,与代码实现保持一致", + "methods": [ + "quick.waybill.toOrder" + ], + "notes": [ + "文档中 isNeedLogin 为 false,但代码 systemMethods/quick/waybill.js 中 _noNeedLogin 为空字符串,未将 toOrder 加入免登录列表,实际需要登录验证,修正文档以与代码一致。" + ], + "type": "fixed" + }, + { + "version": "2026.07.03-system-01", + "date": "2026-07-03", + "summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog", + "methods": [ + "storage.entry.getDirectInboundItems" + ], + "notes": [ + "bindings 数组 description 中 wms_entry_receiving_binding 引用更新为 InboundDirectLog,明确旧表已弃用", + "binding_id description 中 wms_entry_receiving_binding.id 更新为 InboundDirectLog.id", + "allocated_quantity description 中补充来源 InboundDirectLog.quantity", + "wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at" + ], + "type": "updated" + }, + { + "version": "2026.07.03-system-02", + "date": "2026-07-03", + "summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog", + "methods": [ + "storage.directInbound.getItems" + ], + "notes": [ + "bindings 数组 description 中更新为来自 InboundDirectLog,明确旧表已弃用", + "binding_id description 更新为 InboundDirectLog.id", + "allocated_quantity description 中补充来源 InboundDirectLog.quantity", + "wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at" + ], + "type": "updated" + }, + { + "version": "2026.07.03-system-03", + "date": "2026-07-03", + "summary": "binding 表弃用文档同步:commit 描述中 EntryReceivingBinding 更新为 InboundDirectLog", + "methods": [ + "storage.entry.commit" + ], + "notes": [ + "commit description 中将 pending 状态的 EntryReceivingBinding 更新为 pending 状态的 InboundDirectLog,与代码实现一致" + ], + "type": "updated" + }, + { + "version": "2026-07-03-entry-get-params-fix", + "date": "2026-07-03", + "type": "updated", + "summary": "修正 storage.entry.get 文档:id 改为必填;移除未实现的 entry_order_code 参数;修正错误码与实际返回一致;补充 available_receiving_details 响应字段;修正 remaining_quantity 计算公式及 warehouse_image_url 实际行为", + "methods": [ + "storage.entry.get" + ], + "notes": [ + "params: 移除 entry_order_code(代码中从未使用该参数),id 从 required=false 改为 required=true", + "params: id 描述从'二选一'改为'必填'", + "errors: 400 的 message 从'参数错误:id 与 entry_order_code 至少提供一个'改为'id 参数不能为空'", + "errors: 移除不存在的 404 error,入库单不存在时实际返回 code=0, message='入库单不存在或无权访问'", + "errors: 删除不存在的 500 error", + "response: 新增 entryOrder.items[].available_receiving_details 字段及其描述", + "response: remaining_quantity 描述从 'count - received_quantity - direct_inbound_quantity' 修正为 'max(0, count - received_quantity)'", + "response: warehouse_image_url 描述从 StockWarehouse.image_url 改为'当前固定返回空字符串'", + "response: warehouse_is_images 类型从 number(0/1) 改为 string(Y/N),与 StockWarehouse.is_images 实际存储一致", + "response: warehouse_quantity/warehouse_locked_quantity/warehouse_is_batch_mgmt/warehouse_is_shelf_life_mgmt 补充无匹配时为 null 的说明", + "description: 更新描述以反映实际逻辑流程" + ] + }, + { + "version": "2026.07.03-system-04", + "date": "2026-07-03", + "type": "modified", + "summary": "order.pendingOrder.updateAddress 移除 remark(备注)修改功能,现在仅支持地址字段批量修改;备注修改已独立为 order.pendingOrder.updateRemark", + "methods": [ + "order.pendingOrder.updateAddress" + ], + "notes": [ + "移除入参 remark 参数定义项。", + "移除 remark 更新逻辑及相关描述,updateAddress 现在仅处理地址字段(name/mobile/tel/zip_code/province/city/area/town/detail_address)。", + "description 更新:去掉 remark 相关描述,仅描述地址字段修改规则。", + "response updated_count 描述更新:从「取地址更新行数与备注更新行数的最大值」改为单纯描述地址更新行数。", + "errors 更新:移除 remark 相关错误说明('remark 字段不受此限制' 等),修改 '至少需要提供一个地址字段或备注进行修改' 为 '至少需要提供一个地址字段进行修改'。", + "备注修改功能已独立为 order.pendingOrder.updateRemark 方法。" + ], + "module": "order.pendingOrder" + }, + { + "version": "2026-07-16", + "date": "2026-07-16", + "summary": "新增 workbench.bindCamera 接口,支持工作台绑定/解绑摄像头", + "methods": [ + "workbench.bindCamera" + ], + "notes": [ + "通过 device_ids JSON 字段存储绑定关系", + "传空数组可解绑" + ] + }, + { + "version": "2026.07.17-stock-report-migration-01", + "date": "2026-07-17", + "type": "updated", + "summary": "storage.report 模块迁移至 stock.report:修正语义错误,库存报表属于 stock 域而非 storage 域", + "methods": [ + "stock.report.search", + "stock.report.searchStore", + "stock.report.export", + "stock.report.exportStore", + "stock.report.exportTaskProgress" + ], + "notes": [ + "将 systemMethods/storage/report.js 移动到 systemMethods/stock/report.js", + "内部引用同步更新:类名 StorageReportMethodService→StockReportMethodService,缓存键 storage_report→stock_report,日志前缀 [storage.report]→[stock.report]", + "旧文件直接删除,不保留兼容(storage.report 为语义错误,调用方需同步更新 method 名)", + "更新 systems/storage/entry.js L273 注释引用", + "文档:methods/system.json module storage.report→stock.report,5个 method 名同步更新" + ] + }, + { + "version": "2026.07.17-stock-transaction-export-01", + "date": "2026-07-17", + "type": "added", + "summary": "新增 stock.transaction 商品流水导出(仓库侧+货主侧),异步任务模式,支持与列表查询一致的条件筛选", + "methods": [ + "stock.transaction.export", + "stock.transaction.exportStore", + "stock.transaction.exportTaskProgress" + ], + "notes": [ + "systems/stock_transaction.js 新增 exportList(),复用 queryList 的查询逻辑,不分页导出 Excel(上限 50000 条)", + "systemMethods/stock/transaction.js 新增 export/exportStore/exportTaskProgress,采用异步任务模式(setImmediate + 缓存)", + "仓库侧导出自动限定 warehouse_id=ctx.user.store_id,货主侧需传 store_id", + "导出 Excel 列:序号/创建时间/流水类型/仓库ID/货主ID/商品ID/变动数量/变更前库存/变更后库存/变更前锁定/变更后锁定/批次号/单据类型/单据号/收货单ID/入库单ID/发货单ID/操作人/备注" + ] + }, + { + "version": "2026.07.29-system-01", + "date": "2026-07-29", + "type": "added", + "summary": "新增 waybill.warehouse 运单模块(仓库侧):list(列表)、detail(详情)、export(导出)3 个接口,支持运单号独立查询与管理", + "methods": [ + "waybill.warehouse.list", + "waybill.warehouse.detail", + "waybill.warehouse.export" + ], + "notes": [ + "新增 waybill.warehouse.list:仓库侧运单列表查询,支持分页与多条件筛选(运单号/主单号/订单ID/订单号/物流公司/物流接口/平台/状态/退回/拦截/星河签收/包材/称重/关键词/时间范围),默认按 create_at desc 排序。", + "新增 waybill.warehouse.detail:仓库侧运单详情查询,含关联订单信息、兄弟运单(sibling_waybills)、物流信息、状态信息、称重信息、打包信息(打包状态/打包人/打包时间)、打印记录列表。", + "新增 waybill.warehouse.export:仓库侧运单导出,复用 list 筛选逻辑,异步任务模式,支持自定义导出字段。", + "仓库隔离策略:所有接口自动注入 warehouse_id = ctx.user.store_id(全系统统一约定),不可由前端入参覆盖。", + "快照字段方案:wms_order_express 表新增 delivery_order_code、store_id_snapshot、store_name_snapshot、warehouse_name_snapshot 四个快照列,列表查询无需 JOIN 订单表或货主表,仅单表查询 + SELF JOIN(主单号)。", + "主单号/子单号规则:同一 order_id 下 business_key=1 为主单号,business_key>1 为子单号,沿用系统已有约定。", + "命名空间规划:waybill.warehouse.* 本期实现(仓库侧),后续预留 waybill.store.*(货主侧)。", + "本模块一期仅提供只读查询,不涉及运单创建/修改/删除,不修改任何现有接口。" + ], + "module": "waybill.warehouse" + }, + { + "version": "2026.07.30-system-01", + "date": "2026-07-30", + "type": "changed", + "summary": "更新 waybill.warehouse group API 文档:list 新增 waybillType/storeId 筛选、移除 pack_status 响应字段;detail 精简 package 对象;export 响应改为纯异步任务模式(仅含 task_id/status/progress/message/update_time)", + "methods": [ + "waybill.warehouse.list", + "waybill.warehouse.detail", + "waybill.warehouse.export", + "waybill.warehouse.exportTaskProgress" + ], + "notes": [ + "waybill.warehouse.list:新增 where.waybillType 筛选(\"main\"/\"1\"=主单号,\"child\"/\"2\"=子单号),新增 where.storeId 货主ID等值筛选。where.orderNo 标注暂不可用(待快照字段就绪)。response 移除 pack_status 字段(两表无关联,不再返回),list 字段数从 28 减至 27。", + "waybill.warehouse.detail:package 对象移除 pack_status/pack_quantity/pack_at/packer_name 四个字段,仅保留 package_material_id 和 package_material_name。description 同步去掉\"打包状态\"相关描述。", + "waybill.warehouse.export:响应简化为纯异步任务模式,data 仅含 task_id/status/progress/message/update_time,不含 total_count/current_count/result/error/download_url 等执行期字段(这些信息由 exportTaskProgress 接口返回)。export 的 where 参数同步新增 waybillType 和 storeId。", + "waybill.warehouse.exportTaskProgress:无变更,保持不变。" + ], + "module": "waybill.warehouse" + }, + { + "version": "2026.08.03-system-01", + "date": "2026-08-03", + "type": "added", + "summary": "新增站内信(Inbox)管理模块,支持消息列表、详情、对话链、回信、重推、统计等管理功能,仓库维度隔离,warehouseId 由服务端上下文注入", + "methods": [ + "inbox.list", + "inbox.detail", + "inbox.thread", + "inbox.reply", + "inbox.retry", + "inbox.stats" + ], + "notes": [ + "入口:POST /system,body.method=inbox.{action},路由到 app/controller/inbox.index", + "inbox.list:分页查询消息列表,支持 direction/pushStatus/targetChannel/keyword 筛选,列表不含 ext_data 和 push_response 大字段", + "inbox.detail:查单条消息详情,含完整 push_response 推送响应信息", + "inbox.thread:对话链查询,从指定消息向上查找根消息,向下收集所有回信,按时间升序返回", + "inbox.reply:系统回信,自动继承原消息 ext_data/ref_code,写入 direction=outbound + parent_id 形成对话链,异步推送到目标渠道", + "inbox.retry:手动重推失败消息(仅 push_status=3 可重推),重置为 push_status=0 并触发 setImmediate 异步推送", + "inbox.stats:按方向/推送状态汇总统计 + 最近24小时新增数量", + "安全边界:warehouse_id 由 ctx.user.store_id 注入(内部管理端),外部不可传入,保证仓库隔离", + "底层服务:app/service/inbox/index.js(查询管理)+ app/service/inbox/receiver.js(接收推送)" + ], + "module": "inbox" + } ] diff --git a/methods/changes/warehouse.json b/methods/changes/warehouse.json index 120a920..7a8c0f5 100644 --- a/methods/changes/warehouse.json +++ b/methods/changes/warehouse.json @@ -1,22 +1,41 @@ [ - { - "version": "2026.08.01-warehouse-01", - "date": "2026-08-01", - "type": "added", - "summary": "新增 /warehouse 仓库开放 API 入口,支持仓库级外部适配器 HMAC-SHA256 签名鉴权调用,首批上线 index.ping 心跳 + store.list 货主列表", - "methods": [ - "index.ping", - "store.list" - ], - "notes": [ - "POST /warehouse 为新增入口,独立于 /openapi(货主级),鉴权使用 interface_type_id=3 的仓库 API 应用(由 apiApp 模块管理)。", - "签名算法与 /openapi 完全一致:query 参数字典序 + body 拼接 → HMAC-SHA256 → hex。", - "时间戳 ±10 分钟有效期,Redis 缓存 API 应用配置 300 秒(缓存前缀 warehouse:api-app)。", - "无需 StoreWarehouse 合约关联,直接通过 api_app.warehouse_id 确定仓库上下文。", - "index.ping:无需 body 参数,返回 warehouse_id / app_key / server_time / status。", - "store.list:分页查询当前仓库下已授权的货主,通过 wms_store_warehouse 关联 wms_store,仅返回 auth_status=2 + store.status=1 + warehouse_use_status=1 的记录。", - "api_sign.js 改造:getApiAppConfigByAppKey 新增 interfaceTypeId 参数(默认 2 保持向后兼容),warehouse 入口传 3,查询增加 interface_type_id 条件并返回 warehouse_id。" - ], - "module": "warehouse" - } + { + "version": "2026.08.01-warehouse-01", + "date": "2026-08-01", + "type": "added", + "summary": "新增 /warehouse 仓库开放 API 入口,支持仓库级外部适配器 HMAC-SHA256 签名鉴权调用,首批上线 index.ping 心跳 + store.list 货主列表", + "methods": [ + "index.ping", + "store.list" + ], + "notes": [ + "POST /warehouse 为新增入口,独立于 /openapi(货主级),鉴权使用 interface_type_id=3 的仓库 API 应用(由 apiApp 模块管理)。", + "签名算法与 /openapi 完全一致:query 参数字典序 + body 拼接 → HMAC-SHA256 → hex。", + "时间戳 ±10 分钟有效期,Redis 缓存 API 应用配置 300 秒(缓存前缀 warehouse:api-app)。", + "无需 StoreWarehouse 合约关联,直接通过 api_app.warehouse_id 确定仓库上下文。", + "index.ping:无需 body 参数,返回 warehouse_id / app_key / server_time / status。", + "store.list:分页查询当前仓库下已授权的货主,通过 wms_store_warehouse 关联 wms_store,仅返回 auth_status=2 + store.status=1 + warehouse_use_status=1 的记录。", + "api_sign.js 改造:getApiAppConfigByAppKey 新增 interfaceTypeId 参数(默认 2 保持向后兼容),warehouse 入口传 3,查询增加 interface_type_id 条件并返回 warehouse_id。" + ], + "module": "warehouse" + }, + { + "version": "2026.08.03-warehouse-01", + "date": "2026-08-03", + "type": "added", + "summary": "新增仓库开放 API 站内信模块 inbox.push,支持外部系统将消息推入仓库站内信,WMS 异步转发到目标渠道(IM/API/webhook)", + "methods": [ + "inbox.push" + ], + "notes": [ + "POST /warehouse?method=inbox.push,interface_type_id=3(仓库侧),使用 MD5 签名鉴权", + "warehouse_id 由验签后上下文注入,禁止外部传入(安全边界)", + "ext_id 格式:api:{appKey}:{requestId},用于幂等去重", + "target_url 仅允许 https://,禁止内网 IP(SSRF 防护)", + "推送 body 大小限制 64KB", + "异步推送使用 setImmediate,不阻塞响应;失败指数退避重试(30s→60s→120s,最多3次)", + "路由到 app/service/warehouseMethods/inbox.push → app/service/inbox/receiver.receive" + ], + "module": "inbox" + } ] diff --git a/methods/system.json b/methods/system.json index 62dc192..59b9c11 100644 --- a/methods/system.json +++ b/methods/system.json @@ -2,7 +2,7 @@ "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", "version": "0.3.9", - "updatedAt": "2026-07-30", + "updatedAt": "2026-08-03", "headers": [ { "name": "platform", @@ -31595,6 +31595,607 @@ ] } ] + }, + { + "groupName": "站内信模块", + "module": "inbox", + "list": [ + { + "method": "inbox.list", + "description": "站内信消息列表,按仓库/方向/状态/渠道筛选,支持关键词搜索(ext_id / ref_code),分页返回(默认20条/页,最大200条)", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(从中解析 warehouseId 仓库上下文)" + } + ], + "params": [ + { + "name": "direction", + "type": "string", + "required": false, + "source": "body", + "description": "消息方向筛选:inbound(收件)/ outbound(回信)" + }, + { + "name": "pushStatus", + "type": "number", + "required": false, + "source": "body", + "description": "推送状态筛选:0=待推送 1=推送中 2=已送达 3=失败" + }, + { + "name": "targetChannel", + "type": "string", + "required": false, + "source": "body", + "description": "目标渠道筛选:wecom / dingtalk / feishu / warehouse_api / webhook" + }, + { + "name": "keyword", + "type": "string", + "required": false, + "source": "body", + "description": "关键词搜索,模糊匹配 ext_id 和 ref_code" + }, + { + "name": "page", + "type": "number", + "required": false, + "source": "body", + "description": "页码,默认 1", + "defaultValue": 1 + }, + { + "name": "pageSize", + "type": "number", + "required": false, + "source": "body", + "description": "每页数量,默认 20,最大 200", + "defaultValue": 20 + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "消息列表(不含 ext_data 和 push_response 大字段)", + "children": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "消息ID" + }, + { + "name": "ext_id", + "type": "string", + "required": true, + "description": "外部唯一消息主键" + }, + { + "name": "warehouse_id", + "type": "number", + "required": true, + "description": "所属仓库ID" + }, + { + "name": "direction", + "type": "string", + "required": true, + "description": "消息方向:inbound / outbound" + }, + { + "name": "source_type", + "type": "string", + "required": true, + "description": "来源类型:im / api / system" + }, + { + "name": "target_type", + "type": "string", + "required": true, + "description": "目标类型:im / api / webhook" + }, + { + "name": "target_channel", + "type": "string", + "required": true, + "description": "目标渠道" + }, + { + "name": "push_status", + "type": "number", + "required": true, + "description": "推送状态:0=待推送 1=推送中 2=已送达 3=失败" + }, + { + "name": "retry_count", + "type": "number", + "required": true, + "description": "已重试次数" + }, + { + "name": "created_at", + "type": "string", + "required": true, + "description": "创建时间" + } + ] + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息", + "children": [ + { + "name": "page", + "type": "number", + "required": true, + "description": "当前页码" + }, + { + "name": "pageSize", + "type": "number", + "required": true, + "description": "每页数量" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "总记录数" + }, + { + "name": "totalPages", + "type": "number", + "required": true, + "description": "总页数" + }, + { + "name": "hasPrevious", + "type": "boolean", + "required": true, + "description": "是否有上一页" + }, + { + "name": "hasNext", + "type": "boolean", + "required": true, + "description": "是否有下一页" + } + ] + } + ], + "errors": [ + { + "code": "400", + "message": "method 参数无效" + }, + { + "code": "500", + "message": "warehouseId 无效" + } + ] + }, + { + "method": "inbox.detail", + "description": "站内信消息详情,含完整 push_response 推送响应信息", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(从中解析 warehouseId 仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "消息ID" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "消息ID" + }, + { + "name": "ext_id", + "type": "string", + "required": true, + "description": "外部唯一消息主键" + }, + { + "name": "warehouse_id", + "type": "number", + "required": true, + "description": "所属仓库ID" + }, + { + "name": "direction", + "type": "string", + "required": true, + "description": "消息方向" + }, + { + "name": "source_type", + "type": "string", + "required": true, + "description": "来源类型" + }, + { + "name": "target_type", + "type": "string", + "required": true, + "description": "目标类型" + }, + { + "name": "target_channel", + "type": "string", + "required": true, + "description": "目标渠道" + }, + { + "name": "target_url", + "type": "string", + "required": true, + "description": "推送目标URL" + }, + { + "name": "push_status", + "type": "number", + "required": true, + "description": "推送状态" + }, + { + "name": "retry_count", + "type": "number", + "required": true, + "description": "已重试次数" + }, + { + "name": "push_response", + "type": "object", + "required": false, + "description": "推送目标响应(http_status, body, error)" + }, + { + "name": "ext_data", + "type": "object", + "required": false, + "description": "外部透传数据" + }, + { + "name": "created_at", + "type": "string", + "required": true, + "description": "创建时间" + }, + { + "name": "updated_at", + "type": "string", + "required": true, + "description": "更新时间" + } + ], + "errors": [ + { + "code": "400", + "message": "method 参数无效" + }, + { + "code": "404", + "message": "消息不存在或无权访问" + }, + { + "code": "500", + "message": "消息ID无效 / warehouseId 无效" + } + ] + }, + { + "method": "inbox.thread", + "description": "站内信对话链查询,返回原消息 + 所有回信(按 parent_id 递归),按时间升序排列", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(从中解析 warehouseId 仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "消息ID(可为对话链中任意一条消息,自动向上查找根消息并收集所有回信)" + } + ], + "response": [ + { + "name": "thread", + "type": "array", + "required": true, + "description": "对话链消息数组,按时间升序排列,首元素为根消息,后续为回信" + } + ], + "errors": [ + { + "code": "400", + "message": "method 参数无效" + }, + { + "code": "404", + "message": "消息不存在或无权访问" + }, + { + "code": "500", + "message": "消息ID无效 / warehouseId 无效" + } + ] + }, + { + "method": "inbox.reply", + "description": "系统回信:写入 outbound 记录 + 异步推送到目标渠道。自动继承原消息的 ext_data、ref_code 等字段", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(从中解析 warehouseId 仓库上下文)" + } + ], + "params": [ + { + "name": "parentId", + "type": "number", + "required": true, + "source": "body", + "description": "原消息ID(回信指向的原消息)" + }, + { + "name": "targetChannel", + "type": "string", + "required": true, + "source": "body", + "description": "目标渠道:wecom / dingtalk / feishu / warehouse_api / webhook" + }, + { + "name": "targetUrl", + "type": "string", + "required": true, + "source": "body", + "description": "推送目标 URL" + }, + { + "name": "targetType", + "type": "string", + "required": false, + "source": "body", + "description": "目标类型:im / api / webhook,默认继承原消息的 target_type" + }, + { + "name": "refCode", + "type": "string", + "required": false, + "source": "body", + "description": "引用编码,默认继承原消息的 ref_code" + }, + { + "name": "extData", + "type": "object", + "required": false, + "source": "body", + "description": "透传数据,默认继承原消息的 ext_data" + }, + { + "name": "flags", + "type": "object", + "required": false, + "source": "body", + "description": "处理标记" + } + ], + "response": [ + { + "name": "ok", + "type": "boolean", + "required": true, + "description": "操作是否成功" + }, + { + "name": "id", + "type": "number", + "required": true, + "description": "回信记录 ID" + }, + { + "name": "ext_id", + "type": "string", + "required": true, + "description": "回信唯一标识(sys:{uuid})" + } + ], + "errors": [ + { + "code": "400", + "message": "method 参数无效 / parentId 无效 / targetChannel 不能为空 / targetUrl 不能为空" + }, + { + "code": "404", + "message": "原消息不存在或无权访问" + }, + { + "code": "500", + "message": "warehouseId 无效 / 回信失败" + } + ] + }, + { + "method": "inbox.retry", + "description": "手动重推失败(push_status=3)的站内信消息,重置为待推送状态并触发异步推送", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(从中解析 warehouseId 仓库上下文)" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "source": "body", + "description": "消息ID" + } + ], + "response": [ + { + "name": "ok", + "type": "boolean", + "required": true, + "description": "操作是否成功" + }, + { + "name": "id", + "type": "number", + "required": true, + "description": "消息ID" + }, + { + "name": "ext_id", + "type": "string", + "required": true, + "description": "外部唯一消息主键" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "操作结果描述" + } + ], + "errors": [ + { + "code": "400", + "message": "method 参数无效 / 仅失败状态的消息可以手动重推" + }, + { + "code": "404", + "message": "消息不存在或无权访问" + }, + { + "code": "500", + "message": "消息ID无效 / warehouseId 无效" + } + ] + }, + { + "method": "inbox.stats", + "description": "站内信推送统计:按方向汇总、按推送状态汇总、最近24小时新增数量", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token(从中解析 warehouseId 仓库上下文)" + } + ], + "params": [ + { + "name": "direction", + "type": "string", + "required": false, + "source": "body", + "description": "可选:按方向筛选统计(inbound / outbound),不传则统计全部" + } + ], + "response": [ + { + "name": "total_by_direction", + "type": "array", + "required": true, + "description": "按方向汇总统计", + "children": [ + { + "name": "direction", + "type": "string", + "required": true, + "description": "消息方向" + }, + { + "name": "count", + "type": "number", + "required": true, + "description": "消息数量" + } + ] + }, + { + "name": "total_by_status", + "type": "array", + "required": true, + "description": "按推送状态汇总统计", + "children": [ + { + "name": "push_status", + "type": "number", + "required": true, + "description": "推送状态:0/1/2/3" + }, + { + "name": "count", + "type": "number", + "required": true, + "description": "消息数量" + } + ] + }, + { + "name": "recent_24h_count", + "type": "number", + "required": true, + "description": "最近24小时新增消息数量" + } + ], + "errors": [ + { + "code": "400", + "message": "method 参数无效" + }, + { + "code": "500", + "message": "warehouseId 无效" + } + ] + } + ] } ] } diff --git a/methods/warehouse.json b/methods/warehouse.json index c344f36..7cd2644 100644 --- a/methods/warehouse.json +++ b/methods/warehouse.json @@ -2,7 +2,7 @@ "module": "warehouse", "description": "仓库开放 API 统一入口,供仓库级外部适配器(企微/钉钉/飞书/IM 等)调用,HTTP POST /warehouse,使用 MD5 签名鉴权(interface_type_id=3)", "version": "1.0.0", - "updatedAt": "2026-08-01", + "updatedAt": "2026-08-03", "http": { "path": "/warehouse", "method": "POST" @@ -197,6 +197,148 @@ ] } ] + }, + { + "groupName": "站内信模块", + "module": "inbox", + "list": [ + { + "method": "inbox.push", + "description": "外部系统将消息推入仓库站内信,WMS 异步转发到目标渠道。warehouse_id 由验签后上下文注入,禁止外部传入。", + "isNeedAuth": false, + "isNeedLogin": false, + "headers": [], + "params": [ + { + "name": "sourceType", + "type": "string", + "required": false, + "source": "body", + "description": "来源类型:im / api,默认 api" + }, + { + "name": "sourceChannel", + "type": "string", + "required": false, + "source": "body", + "description": "来源渠道标识(IM 平台名称 / API 标识),将写入 source_extra" + }, + { + "name": "requestId", + "type": "string", + "required": true, + "source": "body", + "description": "来源请求唯一 ID,与 appKey 组合为 ext_id(api:{appKey}:{requestId}),用于幂等去重" + }, + { + "name": "targetType", + "type": "string", + "required": false, + "source": "body", + "description": "目标类型:im / api / webhook,默认 im" + }, + { + "name": "targetChannel", + "type": "string", + "required": true, + "source": "body", + "description": "目标渠道:wecom / dingtalk / feishu / warehouse_api / webhook" + }, + { + "name": "targetUrl", + "type": "string", + "required": true, + "source": "body", + "description": "推送目标 URL(IM Bot webhook 地址 / API 回调地址),仅允许 https://,禁止内网 IP" + }, + { + "name": "refCode", + "type": "string", + "required": false, + "source": "body", + "description": "外部引用编码,推送/回执时原样携带" + }, + { + "name": "extData", + "type": "object", + "required": false, + "source": "body", + "description": "外部透传数据,任意 JSON,WMS 不解析,回信时原样返回" + }, + { + "name": "flags", + "type": "object", + "required": false, + "source": "body", + "description": "处理标记,可选:skip_ai_parse(跳过智能解析)、skip_auto_reply(跳过自动回复)、skip_forward(仅存档不转发)" + }, + { + "name": "storeId", + "type": "number", + "required": false, + "source": "body", + "description": "关联货主 ID" + }, + { + "name": "parentId", + "type": "number", + "required": false, + "source": "body", + "description": "关联消息 ID(回信时指向原消息,形成对话链)" + } + ], + "response": [ + { + "name": "ok", + "type": "boolean", + "required": true, + "description": "操作是否成功" + }, + { + "name": "id", + "type": "number", + "required": true, + "description": "站内信记录 ID" + }, + { + "name": "ext_id", + "type": "string", + "required": true, + "description": "外部唯一消息主键" + } + ], + "errors": [ + { + "code": "400", + "message": "requestId 不能为空" + }, + { + "code": "400", + "message": "targetChannel 不能为空" + }, + { + "code": "400", + "message": "targetUrl 不能为空" + }, + { + "code": "400", + "message": "缺少仓库信息" + }, + { + "code": "400", + "message": "target_url 仅允许 https:// 协议" + }, + { + "code": "400", + "message": "target_url 不允许指向内网地址" + }, + { + "code": "500", + "message": "站内信入站失败" + } + ] + } + ] } ] }