From 0fe43c87b148ab9ca286bd536ac6d24ea618ab54 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Thu, 10 Sep 2026 03:46:41 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20=E8=B7=A8=E4=BB=93=20order=5Fexpress=20?= =?UTF-8?q?=E6=A0=A1=E9=AA=8C=E4=B8=8E=20recheckOrder=20=E5=8E=9F=E7=94=9F?= =?UTF-8?q?=20SQL=20=E8=A1=A8=E5=90=8D=E4=BF=AE=E5=A4=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 跨仓 bug 修复:order_express 读取强制校验订单所属仓库 id(order.detail 与全部订单列表等 17 处) - recheckOrder 原生 SQL 表名补 wms_ 前缀,修复 queryRecheckOrderSingleList 恒 500 - 同步 methods 文档与变更记录 --- app/lib/intercept_guard.js | 6 +- app/service/inbox/functions.js | 4 +- app/service/qimenMethods/order.js | 26 +- app/service/systemMethods/order/base.js | 82 ++- .../systemMethods/order/pendingOrder.js | 16 +- .../systemMethods/order/recheckOrder.js | 7 +- app/service/systems/express.js | 4 + app/service/systems/express_platform.js | 25 +- app/service/systems/order_async.js | 27 +- app/service/systems/order_express.js | 27 +- app/service/systems/storage/report.js | 57 +- app/service/systems/waybill.js | 3 +- app/service/systems/workbench.js | 1 + methods/changes/system.json | 121 ++++ methods/system.json | 565 +++++++++++++++++- 15 files changed, 898 insertions(+), 73 deletions(-) diff --git a/app/lib/intercept_guard.js b/app/lib/intercept_guard.js index 670f388..4f63408 100644 --- a/app/lib/intercept_guard.js +++ b/app/lib/intercept_guard.js @@ -95,8 +95,12 @@ async function resolveInterceptRequestGuardInfo(ctx, params = {}) { let weighingWeight = 0; if (ctx && ctx.model && ctx.model.OrderExpress) { try { + // 强制同仓校验:读取称重重量必须同时带订单ID与仓库ID,禁止跨仓串读 const expressRows = await ctx.model.OrderExpress.findAll({ - where: { order_id: Number(orderId || 0) }, + where: { + order_id: Number(orderId || 0), + warehouse_id: warehouseId, + }, attributes: [ 'weighing_weight' ], raw: true, transaction, diff --git a/app/service/inbox/functions.js b/app/service/inbox/functions.js index 2bfe17a..c235e5b 100644 --- a/app/service/inbox/functions.js +++ b/app/service/inbox/functions.js @@ -163,10 +163,10 @@ class InboxFunctionsService extends Service { }; } - // 查已有快递单号 + // 查已有快递单号(强制同仓校验:同时匹配订单ID与仓库ID) const existingExpress = await ctx.model.OrderExpress.findOne({ attributes: [ 'waybill_code', 'logistics_name', 'status' ], - where: { order_id: orderDelivery.id, business_key: 1 }, + where: { order_id: orderDelivery.id, business_key: 1, warehouse_id: warehouseId }, raw: true, }); diff --git a/app/service/qimenMethods/order.js b/app/service/qimenMethods/order.js index eb9edde..33cc6ee 100644 --- a/app/service/qimenMethods/order.js +++ b/app/service/qimenMethods/order.js @@ -89,14 +89,31 @@ class orderServer extends MainService { }; } - async getInterceptExpressInfo(orderId) { + /** + * 查询订单关联的拦截运单信息。 + * + * 强制同仓校验:读取 wms_order_express 必须同时带订单ID与仓库ID, + * 禁止仅凭订单ID跨仓串读运单号;仓库ID缺失时拒绝读取。 + * + * @param {number|string} orderId 订单ID。 + * @param {number|string|null|undefined} warehouseId 仓库ID,必须为订单所属仓库。 + * @return {Promise>} 运单信息列表。 + */ + async getInterceptExpressInfo(orderId, warehouseId) { const { ctx } = this; const normalizedOrderId = Number(orderId || 0); + const normalizedWarehouseId = warehouseId !== null && warehouseId !== undefined && warehouseId !== '' + ? Number(warehouseId) + : 0; if (!Number.isFinite(normalizedOrderId) || normalizedOrderId <= 0) { return []; } + if (!Number.isFinite(normalizedWarehouseId) || normalizedWarehouseId <= 0) { + return []; + } + const orderExpressModel = ctx.model && ctx.model.OrderExpress; if (!orderExpressModel || typeof orderExpressModel.findAll !== 'function') { return []; @@ -105,6 +122,7 @@ class orderServer extends MainService { const rows = await orderExpressModel.findAll({ where: { order_id: normalizedOrderId, + warehouse_id: normalizedWarehouseId, }, attributes: [ 'waybill_code', 'logistics_code', 'logistics_name', 'logistics_interface_id' ], order: [[ 'id', 'DESC' ]], @@ -122,7 +140,7 @@ class orderServer extends MainService { async sendCancelInterceptNotice({ orderCode, existingOrder, info }) { const { ctx } = this; try { - const express = await this.getInterceptExpressInfo(existingOrder && existingOrder.id); + const express = await this.getInterceptExpressInfo(existingOrder && existingOrder.id, info.warehouseId); await ctx.service.systems.notice.send({ event: 'order_cancel_intercepted', @@ -287,7 +305,7 @@ class orderServer extends MainService { // 创建售后工单 + 通知快递群(仅限有运单的订单,与正常货主发起拦截一致;失败不影响主流程) try { - const interceptExpress = await this.getInterceptExpressInfo(existingOrder.id); + const interceptExpress = await this.getInterceptExpressInfo(existingOrder.id, info.warehouseId); if (Array.isArray(interceptExpress) && interceptExpress.length > 0) { await ctx.service.systems.afterSale.createInterceptWorkOrdersAndNotify({ orderIds: [ existingOrder.id ], @@ -381,7 +399,7 @@ class orderServer extends MainService { // 创建售后工单 + 通知快递群(仅限有运单的订单,与正常货主发起拦截一致;失败不影响主流程) try { - const interceptExpress = await this.getInterceptExpressInfo(existingOrder.id); + const interceptExpress = await this.getInterceptExpressInfo(existingOrder.id, info.warehouseId); if (Array.isArray(interceptExpress) && interceptExpress.length > 0) { await ctx.service.systems.afterSale.createInterceptWorkOrdersAndNotify({ orderIds: [ existingOrder.id ], diff --git a/app/service/systemMethods/order/base.js b/app/service/systemMethods/order/base.js index 9ad0997..19d6e1e 100644 --- a/app/service/systemMethods/order/base.js +++ b/app/service/systemMethods/order/base.js @@ -801,8 +801,13 @@ class OrderBaseService extends MainService { /** * 查询订单关联运单信息。 + * + * 强制同仓校验:查询条件必须同时包含订单ID与仓库ID, + * 禁止仅凭订单ID读取 wms_order_express,避免跨仓串读运单号。 + * 仓库ID优先取订单详情行(order.warehouse_id),缺省时回退当前用户上下文仓库。 + * * @param {number|string} orderId 订单ID。 - * @param {Object} [order] 订单详情行,用于补充 sys_logistics_code / sys_logistics_name。 + * @param {Object} [order] 订单详情行,用于补充 sys_logistics_code / sys_logistics_name 与仓库ID。 * @return {Promise} 运单信息列表。 */ async getOrderExpressesByOrderId(orderId, order) { @@ -817,9 +822,23 @@ class OrderBaseService extends MainService { return []; } + // 强制同仓校验:仓库ID优先取订单行,缺省回退当前上下文仓库;均缺失时拒绝读取 + const contextWarehouseId = this.getWarehouseId(); + const orderWarehouseId = Number(order && order.warehouse_id); + const warehouseId = Number.isFinite(orderWarehouseId) && orderWarehouseId > 0 + ? orderWarehouseId + : (contextWarehouseId !== null && contextWarehouseId !== undefined && contextWarehouseId !== '' + ? Number(contextWarehouseId) + : 0); + + if (!Number.isFinite(warehouseId) || warehouseId <= 0) { + return []; + } + const rows = await orderExpressModel.findAll({ where: { order_id: normalizedOrderId, + warehouse_id: warehouseId, }, attributes: [ 'waybill_code', 'logistics_code', 'logistics_name', 'logistics_interface_id', 'logistics_interface_name', 'weighing_weight', 'business_key', 'create_at', 'package_material_id', 'package_material_name_snapshot' ], order: [[ 'id', 'ASC' ]], @@ -880,6 +899,10 @@ class OrderBaseService extends MainService { /** * 批量补齐订单列表的快递号信息。 + * + * 强制同仓校验:运单查询按「订单ID + 仓库ID」分组执行, + * 禁止仅凭订单ID读取 wms_order_express,避免跨仓串读运单号。 + * * @param {Object[]} list 订单列表。 * @return {Promise} 补齐后的列表。 */ @@ -902,16 +925,53 @@ class OrderBaseService extends MainService { } const { Op } = this.app.Sequelize; - const expressRows = await orderExpressModel.findAll({ - where: { - order_id: { - [Op.in]: orderIds, - }, - }, - attributes: [ 'id', 'order_id', 'waybill_code', 'logistics_code', 'logistics_name', 'logistics_interface_id', 'platform_code' ], - order: [[ 'id', 'ASC' ]], - raw: true, - }); + + // 强制同仓校验:逐订单解析仓库归属(行内 warehouse_id 优先,缺省回退当前上下文仓库), + // 无法确定仓库归属的订单不参与运单查询,避免仅凭订单ID跨仓串读 + const contextWarehouseId = this.getWarehouseId(); + const warehouseIdByOrder = new Map(); + for (const item of list) { + const orderId = Number(item && item.id); + if (!Number.isFinite(orderId) || orderId <= 0) { + continue; + } + const rowWarehouseId = Number(item && item.warehouse_id); + if (Number.isFinite(rowWarehouseId) && rowWarehouseId > 0) { + warehouseIdByOrder.set(orderId, rowWarehouseId); + } else if (contextWarehouseId !== null && contextWarehouseId !== undefined && contextWarehouseId !== '') { + warehouseIdByOrder.set(orderId, Number(contextWarehouseId)); + } + } + + const scopedOrderIds = orderIds.filter(orderId => warehouseIdByOrder.has(orderId)); + const expressRows = []; + if (scopedOrderIds.length > 0) { + const orderIdsByWarehouse = new Map(); + for (const orderId of scopedOrderIds) { + const orderWarehouseId = warehouseIdByOrder.get(orderId); + if (!orderIdsByWarehouse.has(orderWarehouseId)) { + orderIdsByWarehouse.set(orderWarehouseId, []); + } + orderIdsByWarehouse.get(orderWarehouseId).push(orderId); + } + + for (const [ orderWarehouseId, warehouseOrderIds ] of orderIdsByWarehouse.entries()) { + const rows = await orderExpressModel.findAll({ + where: { + order_id: { + [Op.in]: warehouseOrderIds, + }, + warehouse_id: orderWarehouseId, + }, + attributes: [ 'id', 'order_id', 'waybill_code', 'logistics_code', 'logistics_name', 'logistics_interface_id', 'platform_code' ], + order: [[ 'id', 'ASC' ]], + raw: true, + }); + if (Array.isArray(rows)) { + expressRows.push(...rows); + } + } + } const expressMap = new Map(); if (Array.isArray(expressRows)) { diff --git a/app/service/systemMethods/order/pendingOrder.js b/app/service/systemMethods/order/pendingOrder.js index 82a30e7..19ae0c8 100644 --- a/app/service/systemMethods/order/pendingOrder.js +++ b/app/service/systemMethods/order/pendingOrder.js @@ -873,7 +873,7 @@ class PendingOrderService extends OrderBaseService { .map(order => Number(order && order.id || 0)) .filter(id => Number.isInteger(id) && id > 0); - await this.assertOrdersWithoutWaybill(targetOrderIds, transaction); + await this.assertOrdersWithoutWaybill(targetOrderIds, warehouseId, transaction); const affectedWaveIds = [ ...new Set(targetOrders .map(order => Number(order && order.wave_id || 0)) @@ -958,13 +958,16 @@ class PendingOrderService extends OrderBaseService { /** * 校验订单是否已分配运单号。 * + * 强制同仓校验:读取 wms_order_express 必须同时带上订单ID与仓库ID, + * 禁止仅凭订单ID跨仓串读运单号。 * 若任一订单存在非空运单号,直接抛出业务异常,阻止反审。 * * @param {Array} orderIds 订单ID集合。 + * @param {number|string|null|undefined} warehouseId 仓库ID,必须为当前订单所属仓库。 * @param {Object} transaction Sequelize 事务对象。 * @return {Promise} 无返回值。 */ - async assertOrdersWithoutWaybill(orderIds = [], transaction) { + async assertOrdersWithoutWaybill(orderIds = [], warehouseId = null, transaction) { const normalizedOrderIds = Array.isArray(orderIds) ? orderIds .map(orderId => Number(orderId || 0)) @@ -980,10 +983,19 @@ class PendingOrderService extends OrderBaseService { return; } + // 强制同仓校验:缺少仓库上下文时直接跳过校验读取(按无可读记录处理) + const normalizedWarehouseId = warehouseId !== null && warehouseId !== undefined && warehouseId !== '' + ? Number(warehouseId) + : 0; + if (!Number.isInteger(normalizedWarehouseId) || normalizedWarehouseId <= 0) { + return; + } + const expressRows = await orderExpressModel.findAll({ attributes: [ 'order_id', 'waybill_code' ], where: { order_id: normalizedOrderIds, + warehouse_id: normalizedWarehouseId, }, raw: true, transaction, diff --git a/app/service/systemMethods/order/recheckOrder.js b/app/service/systemMethods/order/recheckOrder.js index dadecfb..06870c4 100644 --- a/app/service/systemMethods/order/recheckOrder.js +++ b/app/service/systemMethods/order/recheckOrder.js @@ -1690,7 +1690,7 @@ class RecheckOrderService extends OrderBaseService { this.assertOrderCanRecheck(order); - const expresses = await this.getOrderExpressesByOrderId(orderId); + const expresses = await this.getOrderExpressesByOrderId(orderId, order); const waybillNo = String(expresses?.[0]?.waybill_code || '').trim(); const now = new Date(); @@ -3452,8 +3452,9 @@ class RecheckOrderService extends OrderBaseService { o.delivery_order_code LIKE :keyword OR o.pre_delivery_order_code LIKE :keyword OR EXISTS ( - SELECT 1 FROM order_express oe + SELECT 1 FROM wms_order_express oe WHERE oe.order_id = o.id + AND oe.warehouse_id = o.warehouse_id AND oe.waybill_code LIKE :keyword AND oe.delete_at IS NULL ) @@ -3593,7 +3594,7 @@ class RecheckOrderService extends OrderBaseService { o.create_at, o.recheck_time, wi.wave_index, - (SELECT oe.waybill_code FROM order_express oe WHERE oe.order_id = o.id AND oe.delete_at IS NULL LIMIT 1) AS waybill_code + (SELECT oe.waybill_code FROM wms_order_express oe WHERE oe.order_id = o.id AND oe.warehouse_id = o.warehouse_id AND oe.delete_at IS NULL LIMIT 1) AS waybill_code FROM ${orderTableName} o${waveIndexJoin} ${whereClause} ORDER BY o.id ASC diff --git a/app/service/systems/express.js b/app/service/systems/express.js index 538ebe0..35af0bb 100644 --- a/app/service/systems/express.js +++ b/app/service/systems/express.js @@ -2816,10 +2816,14 @@ class ExpressService extends Service { const orderExpressModel = this.ctx.model && this.ctx.model.OrderExpress; if (orderExpressModel && allOrderIds.length > 0) { try { + // 强制同仓校验:读取运单状态必须同时限定订单ID与仓库ID,禁止跨仓串读 + const statusCheckWarehouseId = Number(options && options.warehouse_id) + || this.getCurrentWarehouseId(); const successRows = await orderExpressModel.findAll({ where: { order_id: { [this.app.Sequelize.Op.in]: allOrderIds }, status: 1, + warehouse_id: statusCheckWarehouseId, }, attributes: [ 'order_id' ], raw: true, diff --git a/app/service/systems/express_platform.js b/app/service/systems/express_platform.js index ef6fa1c..b43d252 100644 --- a/app/service/systems/express_platform.js +++ b/app/service/systems/express_platform.js @@ -762,16 +762,23 @@ class ExpressPlatformService extends MainService { orderCount: orderIdList.length, orderIds: orderIdList.slice(0, 50), }); - const allocatedWaybillRows = await orderExpressModel.findAll({ - attributes: [ 'order_id', 'business_key', 'waybill_code' ], - where: { - order_id: { - [Op.in]: orderIdList, + // 强制同仓校验:读取已分配运单必须同时限定订单ID与仓库ID,禁止跨仓串读 + const allocatedWarehouseId = Number(listByWarehousePlatformCode && listByWarehousePlatformCode.warehouse_id) + || Number(this.ctx && this.ctx.user && this.ctx.user.store_id) + || 0; + const allocatedWaybillRows = allocatedWarehouseId > 0 + ? await orderExpressModel.findAll({ + attributes: [ 'order_id', 'business_key', 'waybill_code' ], + where: { + order_id: { + [Op.in]: orderIdList, + }, + warehouse_id: allocatedWarehouseId, }, - }, - order: [[ 'id', 'ASC' ]], - raw: true, - }); + order: [[ 'id', 'ASC' ]], + raw: true, + }) + : []; this.ctx.logger.info('[expressPlatform.polyapi] 查询已分配快递号后', { traceId, diff --git a/app/service/systems/order_async.js b/app/service/systems/order_async.js index a62647f..8601dba 100644 --- a/app/service/systems/order_async.js +++ b/app/service/systems/order_async.js @@ -135,7 +135,18 @@ function resolveOrderWaybillCodesInternal(orderRow = {}, waybillCodes = []) { return fallbackCode ? [ fallbackCode ] : []; } -async function buildOrderWaybillCodeMapInternal(service, orderIds = []) { +/** + * 按订单ID批量构建运单号映射。 + * + * 强制同仓校验:读取 wms_order_express 必须同时带订单ID与仓库ID, + * 禁止仅凭订单ID跨仓串读运单号;仓库ID缺失时返回空映射。 + * + * @param {Object} service 订单异步服务实例。 + * @param {Array} orderIds 订单ID列表。 + * @param {number|string|null|undefined} warehouseId 仓库ID,必须为订单所属仓库。 + * @return {Promise>} order_id 到运单号数组的映射。 + */ +async function buildOrderWaybillCodeMapInternal(service, orderIds = [], warehouseId = null) { const normalizedOrderIds = Array.isArray(orderIds) ? orderIds.map(orderId => Number(orderId)).filter(orderId => Number.isFinite(orderId) && orderId > 0) : []; @@ -146,12 +157,20 @@ async function buildOrderWaybillCodeMapInternal(service, orderIds = []) { return waybillCodeMap; } + const normalizedWarehouseId = warehouseId !== null && warehouseId !== undefined && warehouseId !== '' + ? Number(warehouseId) + : 0; + if (!Number.isFinite(normalizedWarehouseId) || normalizedWarehouseId <= 0) { + return waybillCodeMap; + } + const { Op } = service.app.Sequelize; const expressRows = await orderExpressModel.findAll({ where: { order_id: { [Op.in]: normalizedOrderIds, }, + warehouse_id: normalizedWarehouseId, }, attributes: [ 'order_id', 'business_key', 'waybill_code' ], order: [[ 'id', 'ASC' ]], @@ -462,7 +481,7 @@ async function syncManualOrdersInternal(service, groupedOrder = {}, context = {} } } - const waybillCodeMap = await buildOrderWaybillCodeMapInternal(service, orderIds); + const waybillCodeMap = await buildOrderWaybillCodeMapInternal(service, orderIds, warehouseId); // dispatch前最终去重,防止同一orderId在列表中重复导致并发双扣 const uniqueOrderIds = [ ...new Set(orderIds) ]; @@ -1563,7 +1582,7 @@ async function syncStockoutOrdersInternal(service, groupedOrder = {}, context = } } - const waybillCodeMap = await buildOrderWaybillCodeMapInternal(service, orderIds); + const waybillCodeMap = await buildOrderWaybillCodeMapInternal(service, orderIds, warehouseId); const itemsByOrderId = new Map(); for (const orderItem of Array.isArray(orderItemRows) ? orderItemRows : []) { @@ -2399,7 +2418,7 @@ async function syncQmOrdersInternal(service, groupedOrder = {}, context = {}) { } } - const waybillCodeMap = await buildOrderWaybillCodeMapInternal(service, orderIds); + const waybillCodeMap = await buildOrderWaybillCodeMapInternal(service, orderIds, warehouseId); const itemsByOrderId = new Map(); for (const orderItem of Array.isArray(orderItemRows) ? orderItemRows : []) { diff --git a/app/service/systems/order_express.js b/app/service/systems/order_express.js index 4649e7c..dac69a0 100644 --- a/app/service/systems/order_express.js +++ b/app/service/systems/order_express.js @@ -275,8 +275,12 @@ class OrderExpressService extends Service { /** * 读取订单下有效快递记录。 + * + * 强制同仓校验:读取 wms_order_express 必须同时带订单ID与仓库ID, + * 禁止仅凭订单ID跨仓串读运单号;仓库ID缺失时直接抛业务错误拒绝读取。 + * * @param {number} orderId 订单ID。 - * @param {number|string|null|undefined} warehouseId 仓库ID。 + * @param {number|string|null|undefined} warehouseId 仓库ID,必须为订单所属仓库。 * @return {Promise>} 快递记录列表。 */ async findValidOrderExpressRows(orderId, warehouseId) { @@ -285,15 +289,16 @@ class OrderExpressService extends Service { throw this.createBusinessError('订单快递模型未初始化', 500); } + if (warehouseId === null || warehouseId === undefined || warehouseId === '') { + throw this.createBusinessError('缺少仓库上下文,禁止读取订单运单记录', 400); + } + const where = { order_id: orderId, delete_at: null, + warehouse_id: warehouseId, }; - if (warehouseId !== null && warehouseId !== undefined && warehouseId !== '') { - where.warehouse_id = warehouseId; - } - const rows = await orderExpressModel.findAll({ where, attributes: [ 'id', 'order_id', 'waybill_code', 'weighing_weight' ], @@ -338,7 +343,7 @@ class OrderExpressService extends Service { ); } - // 先查运单表校验运单是否存在 + // 先查运单表校验运单是否存在(强制同仓校验:订单ID + 仓库ID) const orderExpressModel = this.ctx.model && this.ctx.model.OrderExpress; if (!orderExpressModel || typeof orderExpressModel.findOne !== 'function') { throw this.createBusinessError('运单模型未初始化', 500); @@ -348,6 +353,7 @@ class OrderExpressService extends Service { where: { order_id: normalizedOrderId, delete_at: null, + warehouse_id: warehouseId, }, attributes: [ 'id', 'order_id', 'waybill_code', 'business_key' ], raw: true, @@ -631,9 +637,11 @@ class OrderExpressService extends Service { } const { Op } = this.app.Sequelize; + // 强制同仓校验:批量更新称重重量必须同时限定订单ID与仓库ID const updateWhere = { order_id: { [Op.in]: orderIds }, delete_at: null, + warehouse_id: warehouseId, }; // 先验证匹配记录是否存在,避免 MySQL 因值未变返回 affected_rows=0 导致误判 @@ -709,11 +717,12 @@ class OrderExpressService extends Service { }; } - // 查询指定订单下所有有效运单记录 + // 查询指定订单下所有有效运单记录(强制同仓校验:订单ID + 仓库ID) const expressRows = await orderExpressModel.findAll({ where: { order_id: orderId, delete_at: null, + warehouse_id: warehouseId, }, attributes: [ 'business_key', 'weighing_weight', 'waybill_code' ], raw: true, @@ -977,9 +986,11 @@ class OrderExpressService extends Service { } const { Op } = this.app.Sequelize; + // 强制同仓校验:批量更新称重重量必须同时限定订单ID与仓库ID const updateWhere = { order_id: { [Op.in]: orderIds }, delete_at: null, + warehouse_id: warehouseId, }; // 先验证匹配记录是否存在,避免 MySQL 因值未变返回 affected_rows=0 导致误判 @@ -1713,11 +1724,13 @@ class OrderExpressService extends Service { ? { [Op.is]: null } : businessKey; + // 强制同仓校验:按订单ID批量查询运单必须同时限定仓库ID const expressRows = await orderExpressModel.findAll({ where: { order_id: { [Op.in]: orderIds }, business_key: businessKeyWhere, delete_at: null, + warehouse_id: warehouseId, }, attributes: [ 'id', 'order_id', 'waybill_code', 'business_key', 'package_material_id' ], raw: true, diff --git a/app/service/systems/storage/report.js b/app/service/systems/storage/report.js index 58e1353..c0f98d1 100644 --- a/app/service/systems/storage/report.js +++ b/app/service/systems/storage/report.js @@ -391,6 +391,7 @@ class StorageReportService extends Service { * @param {number[]} [options.entryOrderIds=[]] 入库单ID列表 * @param {number[]} [options.orderIds=[]] 出库单ID列表 * @param {number|null} [options.warehouseId=null] 仓库ID + * @param {Map} [options.orderWarehouseMap] 订单ID到仓库ID映射(货主模式跨仓库场景下用于运单同仓校验) * @return {Promise} 映射对象 */ async loadReportReferenceMaps({ @@ -401,6 +402,7 @@ class StorageReportService extends Service { entryOrderIds = [], orderIds = [], warehouseId = null, + orderWarehouseMap = null, } = {}) { const { ctx, app } = this; const normalizedStockIds = [ ...new Set((stockIds || []).map(item => Number(item)).filter(item => Number.isInteger(item) && item > 0)) ]; @@ -477,13 +479,44 @@ class StorageReportService extends Service { ) : [], normalizedOrderIds.length > 0 - ? ctx.model.query( - 'SELECT order_id, waybill_code FROM wms_order_express WHERE order_id IN (:ids)', - { - replacements: { ids: normalizedOrderIds }, - type: app.Sequelize.QueryTypes.SELECT, + ? (async () => { + // 强制同仓校验:读取 wms_order_express 必须同时带订单ID与仓库ID, + // 禁止仅凭订单ID跨仓串读运单号。 + // 仓库模式:直接用当前仓库ID过滤;货主模式:按订单所属仓库分组查询。 + const resultRows = []; + const querySql = 'SELECT order_id, waybill_code FROM wms_order_express WHERE order_id IN (:ids) AND warehouse_id = :warehouseId'; + if (Number.isInteger(normalizedWarehouseId) && normalizedWarehouseId > 0) { + resultRows.push(...await ctx.model.query( + querySql, + { + replacements: { ids: normalizedOrderIds, warehouseId: normalizedWarehouseId }, + type: app.Sequelize.QueryTypes.SELECT, + } + )); + } else if (orderWarehouseMap instanceof Map && orderWarehouseMap.size > 0) { + const idsByWarehouse = new Map(); + for (const orderId of normalizedOrderIds) { + const orderWarehouseId = Number(orderWarehouseMap.get(orderId)); + if (!Number.isInteger(orderWarehouseId) || orderWarehouseId <= 0) { + continue; + } + if (!idsByWarehouse.has(orderWarehouseId)) { + idsByWarehouse.set(orderWarehouseId, []); + } + idsByWarehouse.get(orderWarehouseId).push(orderId); + } + for (const [ orderWarehouseId, warehouseOrderIds ] of idsByWarehouse.entries()) { + resultRows.push(...await ctx.model.query( + querySql, + { + replacements: { ids: warehouseOrderIds, warehouseId: orderWarehouseId }, + type: app.Sequelize.QueryTypes.SELECT, + } + )); + } } - ) + return resultRows; + })() : [], normalizedStoreIds.length > 0 && Number.isInteger(normalizedWarehouseId) && normalizedWarehouseId > 0 ? ctx.model.StoreWarehouse.findAll({ @@ -665,6 +698,7 @@ class StorageReportService extends Service { t.created_at, t.transaction_type, t.store_id, + t.warehouse_id, t.stock_id, ${detailSpaceSelectSql}, t.quantity, @@ -701,6 +735,16 @@ class StorageReportService extends Service { ? [ ...new Set(summaryList.map(item => Number(item.space_id)).filter(item => Number.isInteger(item) && item > 0)) ] : []; + // 货主模式:从流水明细按订单ID收集所属仓库,用于运单查询强制同仓校验 + const detailOrderWarehouseMap = new Map(); + for (const item of safeDetailRows) { + const orderId = Number(item.order_id); + const rowWarehouseId = Number(item.warehouse_id); + if (Number.isInteger(orderId) && orderId > 0 && Number.isInteger(rowWarehouseId) && rowWarehouseId > 0) { + detailOrderWarehouseMap.set(orderId, rowWarehouseId); + } + } + const maps = await this.loadReportReferenceMaps({ stockIds: [ ...new Set([ ...summaryStockIds, ...detailStockIds ]) ], storeIds: [ ...new Set([ ...summaryStoreIds, ...detailStoreIds ]) ], @@ -709,6 +753,7 @@ class StorageReportService extends Service { entryOrderIds: detailEntryOrderIds, orderIds: detailOrderIds, warehouseId, + orderWarehouseMap: detailOrderWarehouseMap, }); const summaryColumns = [ diff --git a/app/service/systems/waybill.js b/app/service/systems/waybill.js index 9b05dfc..46403d5 100644 --- a/app/service/systems/waybill.js +++ b/app/service/systems/waybill.js @@ -389,13 +389,14 @@ class WaybillService extends MainService { // 提取所有唯一的 order_id const orderIds = [ ...new Set(rows.map(r => r.order_id).filter(Boolean)) ]; - // SELF JOIN:查询同 order_id 下 business_key=1 的主单号 + // SELF JOIN:查询同 order_id 下 business_key=1 的主单号(强制同仓校验,避免跨仓串读) const mainWaybillMap = new Map(); if (orderIds.length > 0) { const mainRecords = await ctx.model.OrderExpress.findAll({ where: { order_id: { [Op.in]: orderIds }, business_key: 1, + warehouse_id: warehouseId, }, attributes: [ 'order_id', 'waybill_code' ], raw: true, diff --git a/app/service/systems/workbench.js b/app/service/systems/workbench.js index 3d514ae..117e2ee 100644 --- a/app/service/systems/workbench.js +++ b/app/service/systems/workbench.js @@ -1354,6 +1354,7 @@ class WorkbenchService extends Service { where: { order_id: { [Op.in]: orderIds }, delete_at: null, + warehouse_id: warehouseId, }, } ); diff --git a/methods/changes/system.json b/methods/changes/system.json index 05dafc9..7542e6f 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,62 @@ [ + { + "version": "2026.09.10-cross-warehouse-order-express-warehouse-isolation", + "date": "2026-09-10", + "type": "fixed", + "summary": "跨仓运单号串读缺陷修复文档同步:修复前所有按订单 ID 读取 wms_order_express 的查询缺少 warehouse_id 强制校验,存在跨仓串读运单号风险;修复后所有读取链路均强制校验订单所属仓库(查询条件同时限定订单ID与仓库ID),仓库归属无法确定时跳过读取或拒绝读取。order.detail 及各订单列表接口 description 补充「运单号按订单所属仓库隔离读取」说明,接口入参/出参契约不变。", + "methods": [ + "order.detail", + "order.list", + "order.reviewOrder.list", + "order.pendingOrder.list", + "order.pendingOrder.detail", + "order.pendingOrder.reverseReviewOrder", + "order.outboundOrder.list", + "order.expectionOrder.list", + "order.entrustOrder.list", + "order.deliveryOrder.list", + "order.deliveryExpectionOrder.list", + "order.archiveOrder.list", + "order.wave.waveStrategyFallbackOrderList", + "order.recheckOrder.recheckOrderList", + "order.recheckOrder.queryRecheckOrderSingleList" + ], + "module": "order", + "notes": [ + "app/service/systemMethods/order/base.js:getOrderExpressesByOrderId 强制同仓校验(仓库ID优先取订单行 order.warehouse_id,缺省回退当前上下文仓库,均缺失返回空数组);attachOrderExpressNumbers 批量回填改为按「订单ID+仓库ID」逐仓分组查询(行内 warehouse_id 优先,缺省回退上下文仓库,无法确定仓库归属的订单不参与运单查询)", + "app/service/systemMethods/order/recheckOrder.js:confirmRecheck 调用 getOrderExpressesByOrderId 传入订单行;queryRecheckOrderSingleList 运单号关键词 EXISTS 搜索与 waybill_code 子查询均追加 oe.warehouse_id = o.warehouse_id 同仓条件", + "app/service/systemMethods/order/pendingOrder.js:detail 传订单行给 getOrderExpressesByOrderId;assertOrdersWithoutWaybill 增加 warehouseId 入参强制同仓校验(reverseReviewOrder 反审前运单校验传入当前仓库ID,缺少仓库上下文时跳过校验读取,按无可读记录处理)", + "app/service/systems/order_express.js:findValidOrderExpressRows 仓库ID缺失直接抛 400「缺少仓库上下文,禁止读取订单运单记录」;checkExpress 存在性校验、updateWeighingWeight、updateWeighingWeightByWaybill、按订单ID批量查询等读取链路全部追加 warehouse_id 条件", + "app/service/systems/storage/report.js:loadReportReferenceMaps 运单查询强制 AND warehouse_id(仓库模式用当前仓库ID;货主模式按订单所属仓库 Map 分组查询);库存流水明细 SELECT 增加 t.warehouse_id 并构建订单ID→仓库ID映射传入", + "app/service/systems/order_async.js:buildOrderWaybillCodeMapInternal 增加 warehouseId 入参并强制同仓校验(缺失返回空映射),syncManualOrders/syncStockoutOrders/syncQmOrders 三处调用均传入仓库ID", + "app/service/systems/waybill.js:主单号 SELF JOIN 查询追加 warehouse_id 条件;app/service/systems/workbench.js:打包列表运单查询追加 warehouse_id 条件", + "app/service/systems/express.js:运单状态 success 行查询追加 warehouse_id(取 options.warehouse_id 或当前仓库上下文);app/service/systems/express_platform.js:polyapi 已分配运单查询强制同仓校验,仓库ID缺失时不查询", + "app/service/qimenMethods/order.js:getInterceptExpressInfo 增加 warehouseId 入参强制同仓校验(缺失返回空数组),sendCancelInterceptNotice 与取消拦截链路均传入 info.warehouseId;app/service/inbox/functions.js:已分配快递单号查询追加 warehouse_id;app/lib/intercept_guard.js:拦截守卫称重查询追加 warehouse_id", + "methods/system.json:order.detail、order.pendingOrder.detail 与各订单列表接口(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、order.wave.waveStrategyFallbackOrderList、order.recheckOrder.recheckOrderList、order.recheckOrder.queryRecheckOrderSingleList)description 补充运单号按订单所属仓库隔离读取说明;params/response/errors/headers 契约均未变化;docMeta.version 0.3.103 -> 0.3.104,updatedAt 2026-09-08 -> 2026-09-10;本变更记录写入 methods/changes/system.json 数组首位", + "README.md / AI_TOOLBOX.md / AI_METHOD_ROUTING.md 无需同步:检索确认无 wms_order_express 读取口径描述;AI_METHOD_ROUTING.md 第 6 节为函数清单,本次未新增/删除函数名(仅实现与签名参数变化),无需刷新", + "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" + ] + }, + { + "version": "2026.09.08-front-config-cert-pem-echo", + "date": "2026-09-08", + "type": "changed", + "summary": "setting.warehouse.getFrontConfig 响应改为回显证书/私钥原文(cert_path/key_path 替换为 cert_pem/key_pem):cert_pem 读 cert_pem 列、key_pem 读 cert_key 列,未配置均为空字符串,响应仍 15 字段;saveFrontCert/saveFrontConfig 复用 buildFrontConfigOutput,响应口径同步返回 cert_pem/key_pem 原文;仅登录后的仓库主体(settings 页)接口回显,公共无鉴权接口 frontConfig.getByDomain 不受影响仍 6 字段白名单(domain/title/logo_url/login_bg_url/favicon_url/theme),严禁暴露证书内容。", + "methods": [ + "setting.warehouse.getFrontConfig", + "setting.warehouse.saveFrontConfig", + "setting.warehouse.saveFrontCert" + ], + "module": "setting.warehouse", + "notes": [ + "app/service/systems/setting/warehouse.js:buildFrontConfigOutput 输出字段 cert_path→cert_pem(证书 PEM 原文,读 cert_pem 列)、key_path→key_pem(私钥 PEM 原文,读 cert_key 列),未配置均为空字符串;响应仍 15 字段(warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/cert_pem/key_pem/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at);方法注释明确私钥原文回显仅限仓库主体登录后的 settings 页(getFrontConfig/saveFrontConfig/saveFrontCert 三个需登录接口复用本输出),公共无鉴权接口走 buildFrontConfigPublicOutput 白名单、不经过本方法", + "app/service/systems/setting/warehouse.js:getFrontConfig 响应含证书原文(cert_pem)与私钥原文(key_pem)供仓库主体 settings 页回显;buildFrontConfigPublicOutput/getFrontConfigByDomain 不变(仍仅 FRONT_CONFIG_PUBLIC_FIELDS 6 字段,严禁输出 cert_pem/cert_key 证书与私钥内容及 cert_path/key_path/sync_status 等内部字段)", + "app/service/systems/setting/warehouse.js:saveFrontConfig(约 L1260)与 saveFrontCert(约 L1380)响应均复用 buildFrontConfigOutput,响应口径与 getFrontConfig 一致返回 cert_pem/key_pem 原文;saveFrontCert 保存时证书/私钥 PEM 直接写 cert_pem/cert_key 列、cert_path/key_path 置空待定时任务回填真实路径的行为不变", + "methods/system.json:setting.warehouse.getFrontConfig/saveFrontConfig/saveFrontCert 三个条目 response 中 cert_path/key_path 字段替换为 cert_pem/key_pem(原文回显语义、未配置为空字符串、注明仅登录仓库主体 settings 页回显的安全口径);getFrontConfig description 补充证书/私钥原文回显与公共接口 6 字段白名单口径;saveFrontCert description 由「响应 15 字段不含证书/私钥内容」修正为「响应 15 字段含 cert_pem/key_pem 原文回显」并同步「内容供定时任务读取、禁止写入日志」口径;saveFrontCert response updated_at 字段描述移除「响应不含 cert_pem/cert_key 证书与私钥内容」旧口径;getFrontConfig response cert_expire_at 描述删除已废弃的「纯路径模式」口径;frontConfig.getByDomain 条目未改动(仍 6 字段白名单、isNeedLogin=false、isNeedAuth=false);docMeta.version 0.3.102 -> 0.3.103,updatedAt 保持 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", + "README.md / AI_TOOLBOX.md 无需同步:检索确认无 cert_path/key_path/getFrontConfig/saveFrontCert 字段描述引用;AI_METHOD_ROUTING.md 第 6 节仅方法名清单(getFrontConfig/saveFrontConfig/saveFrontCert 方法名未变、buildFrontConfigOutput 函数名未变)无需同步", + "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" + ] + }, { "version": "2026.09.08-wave-strategy-group-buy-cross-pool-merge", "date": "2026-09-08", @@ -36,6 +94,69 @@ "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" ] }, + { + "version": "2026.09.08-front-cert-inline-content-save", + "date": "2026-09-08", + "type": "changed", + "summary": "setting.warehouse.saveFrontCert 证书上传接口改版文档同步:入参 cert_pem/key_pem 重命名为 pem/key(必填,超长文案「pem|key 内容长度不能超过 65536 字符」);证书/私钥 PEM 内容直接写入 cert_pem/cert_key 列入库、保存时不再写暂存文件,cert_path/key_path 保存置空、等待未来定时任务部署后回填真实路径;cert_expire_at 仍由证书 validTo 权威写入,同步状态机重置(sync_status=0/sync_attempts=0/清空 last_sync_error/last_synced_at)与新旧 domain 公共拉取缓存清理保持不变;删除「证书暂存目录未配置/证书文件写入失败」500 错误分支;响应 15 字段不含证书内容(cert_pem/cert_key 仅定时任务读取)。", + "methods": [ + "setting.warehouse.saveFrontCert" + ], + "module": "setting.warehouse", + "notes": [ + "app/service/systems/setting/warehouse.js:saveFrontCert 入参改为 domain/pem/key(domain 经 normalizeFrontConfigText(data.domain,'domain',100) 校验非空 400「domain 不能为空」与超长 400「domain 长度不能超过 100 字符」;pem/key 经 normalizeFrontConfigPem 校验非空 400「pem 不能为空」「key 不能为空」、超长 400「pem|key 内容长度不能超过 65536 字符」);移除 writeFrontConfigCertFiles 落盘链路,证书内容直接入库 patch.cert_pem=certPem/cert_key=keyPem,patch.cert_path=null/key_path=null(等待未来定时任务从库内读取内容写 nginx 证书目录后回填真实路径);校验链 parseFrontConfigCertPem → assertFrontConfigCertValid → validateFrontConfigKeyPem → collectFrontConfigCertNames/frontConfigCertCoversDomain → assertFrontConfigDomainUnique 不变,任一失败统一「证书不合法」400;cert_expire_at=new Date(cert.validTo) 权威写入不变;sync_status=0/sync_attempts=0/清空 last_sync_error/last_synced_at 与新旧 domain front:config:domain:{*} 缓存清理逻辑不变;响应 buildFrontConfigOutput 15 字段不含 cert_pem/cert_key(内容仅定时任务读取)", + "app/service/systemMethods/setting/warehouse.js:saveFrontCert 薄出口透传改为 domain/pem/key,_noNeedRight/_noNeedAuth 不变;错误 code 透传不变", + "app/model/warehouse_front_config.js:cert_pem/cert_key TEXT 列承接证书内容(comment 注明仅定时任务读取、禁止写入日志/接口响应),cert_path/key_path 保存置空由未来定时任务回填;模型结构无变更", + "config/config.default.js:frontConfig.certStagingDir 保留(注释已更新为「保存接口不再写暂存文件、证书内容直接入库,目录供未来定时任务部署使用」),无配置键变化", + "methods/system.json:setting.warehouse.saveFrontCert 条目 params cert_pem→pem、key_pem→key(文案同步「pem/key 不能为空」与「pem|key 内容长度不能超过 65536 字符」);description 改为内容直接入库、cert_path/key_path 置空待定时任务回填、响应不含证书内容;errors 删除 500「证书暂存目录未配置(frontConfig.certStagingDir)或证书文件写入失败」分支,其余 400/403/409/500 文案按代码核实保留;response 15 字段结构不变;docMeta.version 0.3.99 -> 0.3.100,updatedAt 保持 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", + "AI_METHOD_ROUTING.md:第 6 节自动扫描清单定向修正 systems/setting/warehouse.js 31→30(writeFrontConfigCertFiles 已从代码移除);systemMethods/setting/warehouse.js 6 个方法名不变,其余条目未动", + "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" + ] + }, + { + "version": "2026.09.08-front-cert-config-split", + "date": "2026-09-08", + "type": "changed", + "summary": "前端独立部署「证书上传」与「配置保存」拆分文档同步:新增 setting.warehouse.saveFrontCert 接口文档(证书上传:domain+cert_pem/key_pem 成对必填,校验链任一失败统一返回「证书不合法」400,通过后自动权威写入 cert_expire_at、证书内容落盘只存路径、清新旧 domain 公共拉取缓存);saveFrontConfig 入参瘦身为仅品牌字段 title/logo_url/favicon_url/login_bg_url/theme(domain/cert_pem/key_pem/cert_path/key_path/cert_expire_at 不再受理,前端传值被方法层白名单静默忽略,domain 变更必须走 saveFrontCert)。", + "methods": [ + "setting.warehouse.saveFrontCert", + "setting.warehouse.saveFrontConfig" + ], + "module": "setting.warehouse", + "notes": [ + "app/service/systemMethods/setting/warehouse.js:新增 saveFrontCert 薄出口(透传 domain/cert_pem/key_pem,错误 code 透传);_noNeedRight/_noNeedAuth 增加 saveFrontCert(需登录、免权限、免鉴权,权限靠业务层 isWarehouse 判定);saveFrontConfig 方法层白名单收敛为 title/logo_url/favicon_url/login_bg_url/theme(domain/cert_path/key_path/cert_pem/key_pem/cert_expire_at 一律静默忽略)", + "app/service/systems/setting/warehouse.js:saveFrontCert 校验链 parseFrontConfigCertPem(crypto.X509Certificate)→ assertFrontConfigCertValid(未生效/已过期 400)→ validateFrontConfigKeyPem(SPKI 公钥指纹比对,私钥无法解析/不匹配 400)→ collectFrontConfigCertNames/frontConfigCertCoversDomain(SAN DNS/CN 精确或 *.example.com 通配,不覆盖 400),所有证书校验失败统一文案「证书不合法」;domain 经 normalizeFrontConfigText(data.domain,'domain',100) 校验非空(400「domain 不能为空」)与超长(400「domain 长度不能超过 100 字符」);cert_pem/key_pem 必填(400「cert_pem 不能为空」「key_pem 不能为空」)且 ≤65536 字符(超长 400「{字段} 内容长度不能超过 65536 字符」);通过后 patch.domain/cert_path/key_path/cert_expire_at=new Date(cert.validTo)(权威值非入参)+ sync_status=0/sync_attempts=0/清空 last_sync_error/last_synced_at;writeFrontConfigCertFiles 落盘 frontConfig.certStagingDir({store_id}_{domain}.crt/.key,内容不入库只回传路径,暂存目录未配置或写入失败 500);assertFrontConfigDomainUnique 全局唯一(409「域名 {domain} 已被其他仓库使用」,并发唯一索引冲突兜底 409「仓库前端配置保存冲突,请稍后重试」);写库成功后清理旧 domain 与新 domain 的 front:config:domain:{*} 缓存(先写库后清缓存,清缓存失败仅日志)", + "app/service/systems/setting/warehouse.js:saveFrontConfig 仅按 FRONT_CONFIG_TEXT_FIELDS(title/logo_url/favicon_url/login_bg_url)+ theme 组装 patch;不再受理 domain/cert_*;保存仍重置同步状态并清理当前 domain 公共拉取缓存;响应 buildFrontConfigOutput 15 字段(warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at),getFrontConfig/frontConfig.getByDomain 无变化未改动", + "methods/system.json:setting.warehouse 分组 list 末尾新增 saveFrontCert 条目(isNeedLogin=true、isNeedAuth=false、Authorization 头);saveFrontConfig 条目入参瘦身(移除 domain/cert_pem/key_pem/cert_path/key_path 入参说明,description 注明前端传值静默忽略)与 errors 修订(证书校验 400 统一文案「证书不合法」移至 saveFrontCert;保留 400/403/409 并发兜底/500);docMeta.version 0.3.98 -> 0.3.99,updatedAt 2026-09-07 -> 2026-09-08;本变更记录写入 methods/changes/system.json 数组首位", + "AI_METHOD_ROUTING.md:按文件内维护说明执行第 6 节自动扫描清单刷新(node .\\script\\tmp-gen-service-method-inventory.cjs → node .\\script\\tmp-update-ai-method-routing.cjs),systemMethods/setting/warehouse.js 3→6、systems/setting/warehouse.js 12→31(以扫描结果为准)", + "README.md / AI_TOOLBOX.md 无需同步:检索确认无 saveFrontConfig/saveFrontCert 相关描述", + "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" + ] + }, + { + "version": "2026.09.07-front-config-independent-deploy", + "date": "2026-09-07", + "type": "changed", + "summary": "仓库前端独立部署功能文档同步:新增 setting.warehouse.saveFrontConfig / setting.warehouse.getFrontConfig 与公共无鉴权接口 frontConfig.getByDomain 三个方法文档。保存配置支持上传 cert_pem/key_pem:后端解析证书并校验(无法解析/未生效/已过期/SAN-CN 不包含 domain/私钥不匹配报 400),自动权威写入 cert_expire_at(不再是入参,前端传值被忽略),证书内容落盘暂存目录、库内只存路径;纯路径模式(未提供 cert_pem)直接保存 cert_path/key_path 且不写有效期;保存即重置同步状态(sync_status=0、sync_attempts=0)。新增 favicon_url 字段(保存/查询/公共拉取均含)。公共拉取接口免登录、免鉴权、免权限(保留系统日志),响应仅 6 个公开字段(绝不返回证书路径/同步状态等内部字段),Redis 缓存 front:config:domain:{domain}(命中 TTL 600s、未登记域名空缓存 60s 防穿透、保存配置自动失效新旧域名缓存)。关联迁移 20260907150000(建表 wms_warehouse_front_config)与 20260907170000(favicon_url 列)。", + "methods": [ + "setting.warehouse.saveFrontConfig", + "setting.warehouse.getFrontConfig", + "frontConfig.getByDomain" + ], + "module": "setting.warehouse", + "notes": [ + "app/service/systemMethods/setting/warehouse.js:saveFrontConfig 方法层白名单仅透传 domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_pem/key_pem(cert_expire_at 不入白名单,前端传值直接忽略);getFrontConfig 无入参;两方法均需登录、免权限(_noNeedRight 含 getFrontConfig,saveFrontConfig)、免鉴权(_noNeedAuth 含两方法),saveFrontConfig 权限由业务层 getCurrentSubject().isWarehouse 判定(非仓库主体 403「仅仓库主体可配置前端独立部署」)", + "app/service/systemMethods/frontConfig.js:新模块 frontConfig(与 workbench/inbox 同级),getByDomain 配置 _noNeedLogin/_noNeedRight/_noNeedAuth='getByDomain'(免登录、免鉴权、免权限)、保留系统日志(_noNeedLog 为空);薄出口调用 systems.setting.warehouse.getFrontConfigByDomain,错误 code 透传(400/404/500)", + "app/service/systems/setting/warehouse.js:saveFrontConfig upsert 一仓一行;domain 非空时 assertFrontConfigDomainUnique 全局唯一校验(409「域名 {domain} 已被其他仓库使用」,并发唯一索引冲突兜底转 409「仓库前端配置保存冲突,请稍后重试」);normalizeFrontConfigText 校验文本字段长度(domain/title≤100、logo_url/login_bg_url/favicon_url≤255、cert_path/key_path≤500);normalizeFrontConfigTheme 校验 theme 为合法 JSON 对象;normalizeFrontConfigPem 限制 PEM ≤65536 字符;提供 cert_pem 时 parseFrontConfigCertPem(crypto.X509Certificate)+ assertFrontConfigCertValid(未生效/已过期 400)+ collectFrontConfigCertNames/frontConfigCertCoversDomain(SAN DNS/CN 精确或 *.example.com 通配匹配,不含 domain 报 400)+ validateFrontConfigKeyPem(SPKI 公钥指纹比对),writeFrontConfigCertFiles 落盘暂存目录({store_id}_{domain}.crt/.key,只回传路径、内容不入库,旧暂存文件不主动删除);key_pem 单独提供报 400;未提供 cert_pem 时纯路径模式直接落库、cert_expire_at 允许为空;保存即 patch.sync_status=0/sync_attempts=0 并清空 last_sync_error/last_synced_at;写库成功后清理新旧 domain 公共拉取缓存(先写库后清缓存,清缓存失败仅日志不影响保存)", + "app/service/systems/setting/warehouse.js:getFrontConfig 按 getCurrentWarehouseId()(ctx.user.store_id,未识别报 400「未识别到当前仓库,无法操作仓库设置」)查询 wms_warehouse_front_config,无记录返回 buildFrontConfigOutput 默认空配置(15 字段:warehouse_id/domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at/updated_at)", + "app/service/systems/setting/warehouse.js:getFrontConfigByDomain 校验 domain 必填非空(400「domain 不能为空」)且 ≤100 字符(400「domain 长度不能超过 100 字符」);Redis key front:config:domain:{domain},配置命中缓存 TTL 600s(FRONT_CONFIG_PUBLIC_CACHE_TTL_SECONDS),未登记域名写 {configured:false} 空缓存 TTL 60s(FRONT_CONFIG_PUBLIC_MISS_CACHE_TTL_SECONDS)防穿透并返回 404「域名未配置」;响应仅 FRONT_CONFIG_PUBLIC_FIELDS 白名单 6 字段(domain/title/logo_url/login_bg_url/favicon_url/theme),绝不返回 cert_path/key_path/sync_status/sync_attempts/last_sync_error 等内部字段;Redis 读异常降级查库、写异常仅日志", + "app/model/warehouse_front_config.js:wms_warehouse_front_config 单表一仓一行(uk_store_id 唯一、uk_domain 可空列唯一索引允许多 NULL,非空唯一性靠应用层校验),字段含 domain/title/logo_url/favicon_url/login_bg_url/theme/cert_path/key_path/cert_expire_at/sync_status/sync_attempts/last_sync_error/last_synced_at;不启用 paranoid,无 deleted_at", + "数据库迁移:database/migrations/20260907150000-create-wms-warehouse-front-config.js(建表 wms_warehouse_front_config 及索引)、database/migrations/20260907170000-add-favicon-url-to-wms-warehouse-front-config.js(新增 favicon_url 列)", + "methods/system.json:setting.warehouse 分组 list 末尾新增 saveFrontConfig/getFrontConfig 条目(isNeedLogin=true、isNeedAuth=false、Authorization 头);新增 frontConfig 分组(groupName 前端独立部署模块)与 frontConfig.getByDomain 条目(isNeedLogin=false、isNeedAuth=false、headers 为空,免登录免鉴权免权限);docMeta.version 0.3.97 -> 0.3.98,updatedAt 保持 2026-09-07;本变更记录写入 methods/changes/system.json 数组首位", + "README.md / AI_TOOLBOX.md / AI_METHOD_ROUTING.md 无需同步:检索确认无前端独立部署配置相关行为描述(AI_METHOD_ROUTING.md 为函数清单由扫描脚本维护,本任务未执行扫描,如需刷新可另行执行)", + "本次仅同步文档,未修改任何业务代码,未执行数据库/Redis 写操作" + ] + }, { "version": "2026.09.07-ai-method-routing-service-inventory-refresh", "date": "2026-09-07", diff --git a/methods/system.json b/methods/system.json index 3c186c0..f47b430 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.102", - "updatedAt": "2026-09-08", + "version": "0.3.104", + "updatedAt": "2026-09-10", "headers": [ { "name": "platform", @@ -1985,7 +1985,7 @@ "list": [ { "method": "order.list", - "description": "订单工作台总列表入口,查询当前登录用户仓库上下文下的订单总列表,支持 pagination / where / sort。", + "description": "订单工作台总列表入口,查询当前登录用户仓库上下文下的订单总列表,支持 pagination / where / sort。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -2052,7 +2052,7 @@ }, { "method": "order.detail", - "description": "查询单个订单详情,返回订单头、商品明细和运单信息", + "description": "查询单个订单详情,返回订单头、商品明细和运单信息;运单信息强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -2878,7 +2878,7 @@ "list": [ { "method": "order.reviewOrder.list", - "description": "待审核订单列表,默认仅查询 step=0 的订单。", + "description": "待审核订单列表,默认仅查询 step=0 的订单。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -3169,7 +3169,7 @@ "list": [ { "method": "order.pendingOrder.list", - "description": "待处理订单列表,默认筛选 outbound_status != padding 且 step in [1,2]。", + "description": "待处理订单列表,默认筛选 outbound_status != padding 且 step in [1,2]。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -3236,7 +3236,7 @@ }, { "method": "order.pendingOrder.detail", - "description": "查询单个订单详情,返回订单头、商品明细和运单信息;忽略传入的表位参数,固定先查配送表(dispatch),查不到再兜底查询待处理表(current)", + "description": "查询单个订单详情,返回订单头、商品明细和运单信息;忽略传入的表位参数,固定先查配送表(dispatch),查不到再兜底查询待处理表(current);运单信息强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -3267,36 +3267,40 @@ { "name": "detail", "type": "object", - "description": "订单头对象(raw 行数据,来自配送表或兜底的待处理表)" + "description": "订单头对象(raw 行数据,来自配送表或兜底的待处理表)", + "required": true }, { "name": "orderItems / items", "type": "array", - "description": "商品明细数组(以库存标准格式为主,附 plan_qty / order_line_no / stock_id / order_item_id / order_id 及拣货库位 picking_locations)" + "description": "商品明细数组(以库存标准格式为主,附 plan_qty / order_line_no / stock_id / order_item_id / order_id 及拣货库位 picking_locations)", + "required": true }, { "name": "expresses", "type": "array", - "description": "运单信息数组" + "description": "运单信息数组", + "required": true }, { "name": "storage_items", "type": "array", - "description": "按库位平铺的储位分配明细(附商品编码、名称、规格、单位等库存信息)" + "description": "按库位平铺的储位分配明细(附商品编码、名称、规格、单位等库存信息)", + "required": true } ], "errors": [ { "code": "400", - "description": "订单ID 为空或格式错误" + "message": "订单ID 为空或格式错误" }, { "code": "404", - "description": "订单不存在或不属于当前仓库" + "message": "订单不存在或不属于当前仓库" }, { "code": "500", - "description": "内部错误" + "message": "内部错误" } ] }, @@ -6455,7 +6459,7 @@ }, { "method": "order.recheckOrder.recheckOrderList", - "description": "复核订单列表查询,通过入参 list_type 区分散单模式与团购模式。散单模式(single,默认)返回待复核订单列表(每项为一个订单,排除 pick_status='none' 和 recheck_status='fin'),团购模式(group)返回波次维度的复核汇总列表(每项为一个波次及其订单复核统计,含 review_assignment_status 计算字段)。统一使用 list 字段名输出,均支持分页与筛选。", + "description": "复核订单列表查询,通过入参 list_type 区分散单模式与团购模式。散单模式(single,默认)返回待复核订单列表(每项为一个订单,排除 pick_status='none' 和 recheck_status='fin'),团购模式(group)返回波次维度的复核汇总列表(每项为一个波次及其订单复核统计,含 review_assignment_status 计算字段)。统一使用 list 字段名输出,均支持分页与筛选。;散单模式运单号回读与运单号关键词搜索强制同仓校验(order_express.warehouse_id 必须等于订单 warehouse_id),禁止跨仓串读", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -6968,7 +6972,7 @@ }, { "method": "order.recheckOrder.queryRecheckOrderSingleList", - "description": "散单模式复核列表查询,按订单维度返回待复核订单(排除 pick_status='none' 和 recheck_status='fin'),支持分页与关键词/波次号/复核状态筛选。与 recheckOrderList 不同:本方法仅处理散单模式,不包含团购分支。", + "description": "散单模式复核列表查询,按订单维度返回待复核订单(排除 pick_status='none' 和 recheck_status='fin'),支持分页与关键词/波次号/复核状态筛选。与 recheckOrderList 不同:本方法仅处理散单模式,不包含团购分支。;散单模式运单号回读与运单号关键词搜索强制同仓校验(order_express.warehouse_id 必须等于订单 warehouse_id),禁止跨仓串读", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -8866,7 +8870,7 @@ }, { "method": "order.wave.waveStrategyFallbackOrderList", - "description": "基于波次策略的回退候选订单列表。该接口内置固定筛选条件:step != 0、wave_id = 0,且满足以下任一条件:wave_scan_result = 2(未匹配任何波次策略)、print_status = 'fin'(已完全打印)、lock_status != 'none'(订单已锁定)、intercept_status != 'none'(订单已拦截)。用于展示策略未命中或需回退处理的订单候选。", + "description": "基于波次策略的回退候选订单列表。该接口内置固定筛选条件:step != 0、wave_id = 0,且满足以下任一条件:wave_scan_result = 2(未匹配任何波次策略)、print_status = 'fin'(已完全打印)、lock_status != 'none'(订单已锁定)、intercept_status != 'none'(订单已拦截)。用于展示策略未命中或需回退处理的订单候选。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -10885,7 +10889,7 @@ "list": [ { "method": "order.outboundOrder.list", - "description": "待出库订单列表,默认筛选 outbound_status in [none,padding] 且 step in [1,2]。", + "description": "待出库订单列表,默认筛选 outbound_status in [none,padding] 且 step in [1,2]。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -11133,7 +11137,7 @@ "list": [ { "method": "order.expectionOrder.list", - "description": "待处理异常订单列表,默认仅查询 step=3 的订单。", + "description": "待处理异常订单列表,默认仅查询 step=3 的订单。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -11318,7 +11322,7 @@ "list": [ { "method": "order.entrustOrder.list", - "description": "委托外仓订单列表,使用 outsourced 模型。", + "description": "委托外仓订单列表,使用 outsourced 模型。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -11456,7 +11460,7 @@ "list": [ { "method": "order.deliveryOrder.list", - "description": "配送订单列表,使用 dispatch 模型,默认筛选 dispatch_lane=m4。", + "description": "配送订单列表,使用 dispatch 模型,默认筛选 dispatch_lane=m4。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -11851,7 +11855,7 @@ "list": [ { "method": "order.deliveryExpectionOrder.list", - "description": "配送异常订单列表,使用 dispatch 模型,默认筛选 dispatch_lane=m5。", + "description": "配送异常订单列表,使用 dispatch 模型,默认筛选 dispatch_lane=m5。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -11995,7 +11999,7 @@ "list": [ { "method": "order.archiveOrder.list", - "description": "归档订单列表,使用 history 模型。", + "description": "归档订单列表,使用 history 模型。;列表运单号回填强制同仓校验:wms_order_express 按「订单ID + 订单所属仓库ID」隔离读取,禁止仅凭订单ID跨仓串读运单号", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -14771,6 +14775,443 @@ "message": "保存失败" } ] + }, + { + "method": "setting.warehouse.saveFrontConfig", + "description": "保存当前仓库前端独立部署品牌配置(upsert,一仓一行,仅仓库主体可操作,仅品牌字段部分更新)。仅受理 title(≤100 字符)、logo_url/login_bg_url/favicon_url(≤255 字符)、theme(合法 JSON 对象或 JSON 字符串),空值清空。domain 与证书相关字段(domain/cert_pem/key_pem/cert_path/key_path/cert_expire_at)不再受理:方法层白名单静默忽略前端传值,domain 变更必须走 setting.warehouse.saveFrontCert(重新校验证书)。保存即重置同步状态(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at),写库成功后清理当前 domain 的公共拉取缓存(先写库后清缓存,清缓存失败仅记日志)。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "title", + "type": "string", + "required": false, + "source": "body", + "description": "站点标题(可选,≤100 字符,超长报 400,空值清空)" + }, + { + "name": "logo_url", + "type": "string", + "required": false, + "source": "body", + "description": "Logo 地址(可选,≤255 字符,超长报 400,空值清空)" + }, + { + "name": "favicon_url", + "type": "string", + "required": false, + "source": "body", + "description": "站点 favicon 图标地址(可选,≤255 字符,超长报 400,空值清空)" + }, + { + "name": "login_bg_url", + "type": "string", + "required": false, + "source": "body", + "description": "登录页背景图地址(可选,≤255 字符,超长报 400,空值清空)" + }, + { + "name": "theme", + "type": "object|string", + "required": false, + "source": "body", + "description": "主题配置(可选,合法 JSON 对象或 JSON 字符串,否则报 400「theme 必须是合法的 JSON 对象」;空值清空)" + } + ], + "response": [ + { + "name": "warehouse_id", + "type": "number", + "required": true, + "description": "当前仓库 ID" + }, + { + "name": "domain", + "type": "string", + "required": true, + "description": "仓库自持域名(未配置为空字符串)" + }, + { + "name": "title", + "type": "string", + "required": true, + "description": "站点标题(未配置为空字符串)" + }, + { + "name": "logo_url", + "type": "string", + "required": true, + "description": "Logo 地址(未配置为空字符串)" + }, + { + "name": "favicon_url", + "type": "string", + "required": true, + "description": "站点 favicon 图标地址(未配置为空字符串)" + }, + { + "name": "login_bg_url", + "type": "string", + "required": true, + "description": "登录页背景图地址(未配置为空字符串)" + }, + { + "name": "theme", + "type": "object", + "required": true, + "description": "主题配置对象(未配置为 null)" + }, + { + "name": "cert_pem", + "type": "string", + "required": true, + "description": "证书 PEM 原文(读 cert_pem 列;未配置为空字符串;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" + }, + { + "name": "key_pem", + "type": "string", + "required": true, + "description": "私钥 PEM 原文(读 cert_key 列;未配置为空字符串;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" + }, + { + "name": "cert_expire_at", + "type": "string", + "required": true, + "description": "证书到期时间(由 saveFrontCert 上传证书后权威写入;未上传为 null)" + }, + { + "name": "sync_status", + "type": "number", + "required": true, + "description": "同步状态(0-待同步/1-同步成功/2-同步失败;本次保存后重置为 0)" + }, + { + "name": "sync_attempts", + "type": "number", + "required": true, + "description": "同步尝试次数(本次保存后重置为 0)" + }, + { + "name": "last_sync_error", + "type": "string", + "required": true, + "description": "最近一次同步失败原因(本次保存后清空)" + }, + { + "name": "last_synced_at", + "type": "string", + "required": true, + "description": "最近一次同步成功时间(本次保存后清空,可为 null)" + }, + { + "name": "updated_at", + "type": "string", + "required": true, + "description": "配置更新时间" + } + ], + "errors": [ + { + "code": "400", + "message": "未识别到当前仓库,无法操作仓库设置" + }, + { + "code": "400", + "message": "title/logo_url/login_bg_url/favicon_url 超长(title 长度不能超过 100 字符、其余不能超过 255 字符)/theme 非合法 JSON 对象" + }, + { + "code": "403", + "message": "仅仓库主体可配置前端独立部署(业务层 isWarehouse 判定)" + }, + { + "code": "409", + "message": "并发写入兜底:仓库前端配置保存冲突,请稍后重试" + }, + { + "code": "500", + "message": "签约关系服务不可用/WarehouseFrontConfig model 不可用/保存仓库前端配置失败" + } + ] + }, + { + "method": "setting.warehouse.getFrontConfig", + "description": "查询当前仓库前端独立部署配置(settings 页回显,仅登录仓库主体可调用)。无入参;按当前登录仓库 store_id 查询 wms_warehouse_front_config(一仓一行),无记录时返回默认空配置(warehouse_id 为当前仓库 ID,其余字段为空值/null)。响应 15 字段,含证书 PEM 原文(cert_pem,读 cert_pem 列)与私钥 PEM 原文(key_pem,读 cert_key 列)回显、未配置均为空字符串;公共无鉴权接口 frontConfig.getByDomain 仍仅返回 6 个公开字段白名单(domain/title/logo_url/login_bg_url/favicon_url/theme),不暴露证书/私钥内容。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [], + "response": [ + { + "name": "warehouse_id", + "type": "number", + "required": true, + "description": "当前仓库 ID" + }, + { + "name": "domain", + "type": "string", + "required": true, + "description": "仓库自持域名(未配置为空字符串)" + }, + { + "name": "title", + "type": "string", + "required": true, + "description": "站点标题(未配置为空字符串)" + }, + { + "name": "logo_url", + "type": "string", + "required": true, + "description": "Logo 地址(未配置为空字符串)" + }, + { + "name": "favicon_url", + "type": "string", + "required": true, + "description": "站点 favicon 图标地址(未配置为空字符串)" + }, + { + "name": "login_bg_url", + "type": "string", + "required": true, + "description": "登录页背景图地址(未配置为空字符串)" + }, + { + "name": "theme", + "type": "object", + "required": true, + "description": "主题配置对象(未配置为 null)" + }, + { + "name": "cert_pem", + "type": "string", + "required": true, + "description": "证书 PEM 原文(读 cert_pem 列;未配置为空字符串;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" + }, + { + "name": "key_pem", + "type": "string", + "required": true, + "description": "私钥 PEM 原文(读 cert_key 列;未配置为空字符串;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" + }, + { + "name": "cert_expire_at", + "type": "string", + "required": true, + "description": "证书到期时间(由 saveFrontCert 上传证书后权威写入;未上传为 null)" + }, + { + "name": "sync_status", + "type": "number", + "required": true, + "description": "同步状态(0-待同步/1-同步成功/2-同步失败,无记录为 0)" + }, + { + "name": "sync_attempts", + "type": "number", + "required": true, + "description": "同步尝试次数(无记录为 0)" + }, + { + "name": "last_sync_error", + "type": "string", + "required": true, + "description": "最近一次同步失败原因(无记录为空字符串)" + }, + { + "name": "last_synced_at", + "type": "string", + "required": true, + "description": "最近一次同步成功时间(无记录为 null)" + }, + { + "name": "updated_at", + "type": "string", + "required": true, + "description": "配置更新时间(无记录为 null)" + } + ], + "errors": [ + { + "code": "400", + "message": "未识别到当前仓库,无法操作仓库设置" + }, + { + "code": "500", + "message": "WarehouseFrontConfig model 不可用/获取仓库前端配置失败" + } + ] + }, + { + "method": "setting.warehouse.saveFrontCert", + "description": "上传当前仓库前端独立部署证书(upsert,一仓一行,需登录、仅仓库主体可操作)。入参 domain + pem/key 成对必填:校验链为证书可解析 → 未生效/已过期拒绝 → 私钥与证书成对(SPKI 公钥指纹比对)→ 证书 SAN DNS/CN 覆盖 domain(支持精确匹配与 *.example.com 通配,不覆盖报 400),任一证书校验失败均返回统一文案「证书不合法」(400,不返回细节)。通过后自动写入 cert_expire_at(证书 validTo 权威值,不接受前端传值),证书/私钥 PEM 内容直接写入 cert_pem/cert_key 列入库(不再写暂存文件,内容供定时任务读取、禁止写入日志),cert_path/key_path 保存时置空、等待未来定时任务部署证书后回填真实路径,domain 全局唯一(非空,已被其他仓库使用报 409)。保存即重置同步状态(sync_status=0、sync_attempts=0、清空 last_sync_error/last_synced_at),写库成功后清理旧 domain 与新 domain 的公共拉取缓存(先写库后清缓存,清缓存失败仅记日志)。响应 15 字段含证书 PEM 原文(cert_pem)与私钥 PEM 原文(key_pem)回显,仅登录仓库主体 settings 页接口回显;公共无鉴权接口 frontConfig.getByDomain 不返回证书内容。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "domain", + "type": "string", + "required": true, + "source": "body", + "description": "仓库自持域名(必填,trim 后非空,≤100 字符;全局唯一,已被其他仓库使用报 409)" + }, + { + "name": "pem", + "type": "string", + "required": true, + "source": "body", + "description": "证书 PEM 文本(必填,≤65536 字符,超长报 400「pem 内容长度不能超过 65536 字符」;须能解析为 X.509 证书、未过期且 SAN/CN 覆盖 domain)" + }, + { + "name": "key", + "type": "string", + "required": true, + "source": "body", + "description": "私钥 PEM 文本(必填,≤65536 字符,超长报 400「key 内容长度不能超过 65536 字符」;须与 pem 成对,按 SPKI 公钥指纹比对不匹配报 400)" + } + ], + "response": [ + { + "name": "warehouse_id", + "type": "number", + "required": true, + "description": "当前仓库 ID" + }, + { + "name": "domain", + "type": "string", + "required": true, + "description": "保存后的域名(本次上传生效)" + }, + { + "name": "title", + "type": "string", + "required": true, + "description": "站点标题(未配置为空字符串)" + }, + { + "name": "logo_url", + "type": "string", + "required": true, + "description": "Logo 地址(未配置为空字符串)" + }, + { + "name": "favicon_url", + "type": "string", + "required": true, + "description": "站点 favicon 图标地址(未配置为空字符串)" + }, + { + "name": "login_bg_url", + "type": "string", + "required": true, + "description": "登录页背景图地址(未配置为空字符串)" + }, + { + "name": "theme", + "type": "object", + "required": true, + "description": "主题配置对象(未配置为 null)" + }, + { + "name": "cert_pem", + "type": "string", + "required": true, + "description": "证书 PEM 原文(读 cert_pem 列,本次上传后即回显;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" + }, + { + "name": "key_pem", + "type": "string", + "required": true, + "description": "私钥 PEM 原文(读 cert_key 列,本次上传后即回显;仅登录仓库主体 settings 页接口回显,公共无鉴权接口 frontConfig.getByDomain 不返回)" + }, + { + "name": "cert_expire_at", + "type": "string", + "required": true, + "description": "证书到期时间(后端按证书 validTo 权威写入,非入参)" + }, + { + "name": "sync_status", + "type": "number", + "required": true, + "description": "同步状态(0-待同步/1-同步成功/2-同步失败;本次上传后重置为 0)" + }, + { + "name": "sync_attempts", + "type": "number", + "required": true, + "description": "同步尝试次数(本次上传后重置为 0)" + }, + { + "name": "last_sync_error", + "type": "string", + "required": true, + "description": "最近一次同步失败原因(本次上传后清空)" + }, + { + "name": "last_synced_at", + "type": "string", + "required": true, + "description": "最近一次同步成功时间(本次上传后清空,可为 null)" + }, + { + "name": "updated_at", + "type": "string", + "required": true, + "description": "配置更新时间" + } + ], + "errors": [ + { + "code": "400", + "message": "domain 不能为空/domain 长度不能超过 100 字符/pem 不能为空/key 不能为空/pem|key 内容长度不能超过 65536 字符" + }, + { + "code": "400", + "message": "证书校验失败统一文案「证书不合法」:无法解析为 X.509 PEM 证书/证书未生效/证书已过期/私钥无法解析/私钥与证书不匹配/SAN-CN 不覆盖 domain" + }, + { + "code": "400", + "message": "未识别到当前仓库,无法操作仓库设置" + }, + { + "code": "403", + "message": "仅仓库主体可配置前端独立部署(业务层 isWarehouse 判定)" + }, + { + "code": "409", + "message": "域名 {domain} 已被其他仓库使用(含并发唯一索引冲突兜底:仓库前端配置保存冲突,请稍后重试)" + }, + { + "code": "500", + "message": "签约关系服务不可用/WarehouseFrontConfig model 不可用" + } + ] } ] }, @@ -42942,6 +43383,84 @@ ] } ] + }, + { + "groupName": "前端独立部署模块", + "module": "frontConfig", + "list": [ + { + "method": "frontConfig.getByDomain", + "description": "按域名拉取仓库前端公开配置(公共无鉴权接口:免登录、免鉴权、免权限,保留系统日志)。响应仅含公开字段 domain/title/logo_url/login_bg_url/favicon_url/theme,绝不返回 cert_path/key_path/sync_status/sync_attempts/last_sync_error 等内部字段。Redis 缓存 key front:config:domain:{domain}:命中配置缓存 TTL 600s;未登记域名写 configured=false 空缓存 60s 防穿透并返回 404;保存配置时自动失效新旧域名缓存;Redis 异常降级查库。", + "isNeedAuth": false, + "isNeedLogin": false, + "headers": [], + "params": [ + { + "name": "domain", + "type": "string", + "required": true, + "source": "body", + "description": "待查询域名(必填,trim 后非空,≤100 字符;为空报 400「domain 不能为空」,超长报 400「domain 长度不能超过 100 字符」)" + } + ], + "response": [ + { + "name": "domain", + "type": "string", + "required": true, + "description": "仓库自持域名" + }, + { + "name": "title", + "type": "string", + "required": true, + "description": "站点标题(未配置为空字符串)" + }, + { + "name": "logo_url", + "type": "string", + "required": true, + "description": "Logo 地址(未配置为空字符串)" + }, + { + "name": "login_bg_url", + "type": "string", + "required": true, + "description": "登录页背景图地址(未配置为空字符串)" + }, + { + "name": "favicon_url", + "type": "string", + "required": true, + "description": "站点 favicon 图标地址(未配置为空字符串)" + }, + { + "name": "theme", + "type": "object", + "required": true, + "description": "主题配置对象(未配置为 null)" + } + ], + "errors": [ + { + "code": "400", + "message": "domain 不能为空" + }, + { + "code": "400", + "message": "domain 长度不能超过 100 字符" + }, + { + "code": "404", + "message": "域名未配置" + }, + { + "code": "500", + "message": "WarehouseFrontConfig model 不可用/获取前端配置失败" + } + ] + } + ] } ] }