diff --git a/app/service/systems/storage/receiving.js b/app/service/systems/storage/receiving.js index 6394d41..e778ed7 100644 --- a/app/service/systems/storage/receiving.js +++ b/app/service/systems/storage/receiving.js @@ -292,7 +292,7 @@ class ReceivingService extends Service { * @param {Object} data 请求体 * @param {number} data.id 收货单ID * @param {Object} data.pagination 分页参数 - * @return {Promise} 详情数据 + * @return {Promise} 详情数据,明细中的 space_id 会优先展示自定义库位名称,其次展示库位编码,并补充 space_id_raw 兼容原始ID */ async getReceivingDetail(data) { const { id, pagination } = data; @@ -313,13 +313,19 @@ class ReceivingService extends Service { // 2. 查询收货单明细,按分页 const receivingItems = await app.model.ReceivingDetail.findAll({ where: { receiving_id: id }, + include: [{ + model: app.model.LocationSpace, + as: 'receiving_space', + attributes: [ 'id', 'custom_name', 'space_code' ], + required: false, + }], offset: (page - 1) * pageSize, limit: pageSize, }); // 获取明细总数 const totalItems = await app.model.ReceivingDetail.count({ where: { receiving_id: id } }); // 组装分页信息 - const pagination = { + const detailPagination = { total: totalItems, currentPage: page, pageSize, @@ -359,8 +365,14 @@ class ReceivingService extends Service { // 5. 将图片合并到对应的明细中 const items = receivingItems.map(item => { const detail = item.toJSON(); + const { receiving_space: receivingSpace, ...detailBase } = detail; + const spaceName = receivingSpace?.custom_name || receivingSpace?.space_code || null; return { - ...detail, + ...detailBase, + space_id_raw: detailBase.space_id ?? null, + space_name: spaceName, + custom_space_name: receivingSpace?.custom_name ?? null, + space_id: spaceName, box_remainder: detail.box_remainder ?? 0, box_weight: detail.box_weight ?? 0, images: itemImagesMap[item.id] || [], @@ -385,7 +397,7 @@ class ReceivingService extends Service { id: image.file_id, url: image.file.file_url, })); // 包含主表图片链接 - receiving.dataValues.pagination = pagination; // 包含分页信息 + receiving.dataValues.pagination = detailPagination; // 包含分页信息 return { code: 200, message: '查询成功', data: { receiving } }; } catch (error) { diff --git a/methods/changes/system.json b/methods/changes/system.json index 5bc6ad9..32b76a9 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,5 +1,5 @@ [ - { + { "version": "2026.05.17-system-09", "date": "2026-05-17", "summary": "为 storage.receiving.deleteDetail 文档补充约束:收货单已完成/已取消时禁止删除明细", @@ -12,8 +12,8 @@ ], "type": "updated", "module": "storage" - }, - { + }, + { "version": "2026.05.17-system-08", "date": "2026-05-17", "summary": "完善 storage.receiving.deleteDetail 文档:补充入参/返回/错误说明,明确用户上下文来源及删除约束", @@ -28,21 +28,21 @@ ], "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-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/货物编码 导入,更新写操作日志", @@ -1899,9 +1899,7 @@ "补充可能的错误码:404/400/500" ], "type": "updated" - } - - , + }, { "version": "2026.05.17-system-06", "date": "2026-05-17", @@ -1927,5 +1925,36 @@ "兼容不传 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" } ] diff --git a/methods/system.json b/methods/system.json index b4ae260..d3b304f 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "2026.05.16-system-03", - "updatedAt": "2026-05-16", + "version": "0.0.0", + "updatedAt": "2026-05-17", "headers": [ { "name": "platform", @@ -8279,26 +8279,34 @@ { "name": "warehouse_id", "type": "number", + "required": true, "description": "仓库 ID" }, { "name": "subject_config", "type": "object", + "required": true, "description": "仓库的 subject_config 配置对象" + }, + { + "name": "subject_config.enable_external_express_code", + "type": "boolean", + "required": true, + "description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)" } ], "errors": [ { "code": "400", - "description": "未识别到当前仓库" + "message": "未识别到当前仓库" }, { "code": "404", - "description": "仓库不存在" + "message": "仓库不存在" }, { "code": "500", - "description": "获取失败" + "message": "获取失败" } ] }, @@ -8416,37 +8424,53 @@ "required": false, "source": "body", "description": "需清理缓存的仓库 ID(驼峰命名兼容)" + }, + { + "name": "subject_config.enable_external_express_code", + "type": "boolean", + "required": false, + "source": "body.subject_config", + "description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)" } ], "response": [ { "name": "warehouse_id", "type": "number", + "required": true, "description": "生效的仓库 ID" }, { "name": "subject_config", "type": "object", + "required": true, "description": "保存后的 subject_config" }, { "name": "cache_cleared_warehouse_id", "type": "number", + "required": true, "description": "被清理缓存的仓库 ID(若未清理则为 null)" + }, + { + "name": "subject_config.enable_external_express_code", + "type": "boolean", + "required": true, + "description": "保存后的 subject_config.enable_external_express_code 值" } ], "errors": [ { "code": "400", - "description": "未识别到当前仓库/参数不合法" + "message": "未识别到当前仓库/参数不合法" }, { "code": "404", - "description": "仓库不存在" + "message": "仓库不存在" }, { "code": "500", - "description": "保存失败" + "message": "保存失败" } ] } @@ -12211,6 +12235,30 @@ "required": false, "description": "收货单明细列表,单条记录包含明细字段(见下文)" }, + { + "name": "receiving.details.*.space_id", + "type": "string", + "required": false, + "description": "库位展示名称(string|null)。优先取 custom_space_name,其次取 space_name。兼容说明:该字段历史上为数值库位ID,现已调整为展示名称;原始ID请使用 receiving.details.*.space_id_raw。" + }, + { + "name": "receiving.details.*.space_id_raw", + "type": "number", + "required": false, + "description": "原始库位ID(number|null),用于兼容依赖旧语义(space_id=数字ID)的调用方。" + }, + { + "name": "receiving.details.*.space_name", + "type": "string", + "required": false, + "description": "库位名称/编码(string|null),作为展示名称的回退来源。" + }, + { + "name": "receiving.details.*.custom_space_name", + "type": "string", + "required": false, + "description": "库位自定义名称(string|null,可空)。" + }, { "name": "receiving.details.*.box_remainder", "type": "number", @@ -12227,11 +12275,11 @@ "errors": [ { "code": "0", - "description": "无记录或无权访问" + "message": "无记录或无权访问" }, { "code": "500", - "description": "服务器错误" + "message": "服务器错误" } ] }, @@ -12670,7 +12718,6 @@ } ] }, - { "method": "storage.receiving.removeItem", "description": "storage.receiving.removeItem 接口", @@ -14868,7 +14915,7 @@ "list": [ { "method": "store.createStore", - "description": "store.createStore 接口,subject_config 未传时默认写入 max_notice_webhook_count=5、default_express_code=STO、default_platform_code=TB、group_wave_prefix=B、min_group_order_fetch_quantity=13、auto_grouping_enabled=false(是否自动加团,默认 false(关闭))", + "description": "store.createStore 接口,subject_config 未传时默认写入 max_notice_webhook_count=5、default_express_code=STO、default_platform_code=TB、group_wave_prefix=B、min_group_order_fetch_quantity=13、auto_grouping_enabled=false(是否自动加团,默认 false(关闭))、enable_external_express_code=false(是否启用外部快递编码,默认 false(关闭))", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -14928,6 +14975,13 @@ "required": false, "source": "body.subject_config", "description": "是否自动加团,默认 false(关闭)" + }, + { + "name": "subject_config.enable_external_express_code", + "type": "boolean", + "required": false, + "source": "body.subject_config", + "description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)" } ], "response": [], @@ -14935,7 +14989,7 @@ }, { "method": "store.createWarehouse", - "description": "store.createWarehouse 接口,subject_config 未传时默认写入 max_notice_webhook_count=5、default_express_code=STO、default_platform_code=TB、group_wave_prefix=B、min_group_order_fetch_quantity=13、auto_grouping_enabled=false(是否自动加团,默认 false(关闭))", + "description": "store.createWarehouse 接口,subject_config 未传时默认写入 max_notice_webhook_count=5、default_express_code=STO、default_platform_code=TB、group_wave_prefix=B、min_group_order_fetch_quantity=13、auto_grouping_enabled=false(是否自动加团,默认 false(关闭))、enable_external_express_code=false(是否启用外部快递编码,默认 false(关闭))", "isNeedAuth": false, "isNeedLogin": true, "headers": [ @@ -14995,6 +15049,13 @@ "required": false, "source": "body.subject_config", "description": "是否自动加团,默认 false(关闭)" + }, + { + "name": "subject_config.enable_external_express_code", + "type": "boolean", + "required": false, + "source": "body.subject_config", + "description": "是否启用外部快递编码;默认 false(关闭)。开启后允许按外部系统传入的快递编码进行处理(如无匹配仍以业务校验为准)" } ], "response": [], diff --git a/test/app/service/systems/storage.receiving.getDetail.test.js b/test/app/service/systems/storage.receiving.getDetail.test.js index a260c25..290d0f4 100644 --- a/test/app/service/systems/storage.receiving.getDetail.test.js +++ b/test/app/service/systems/storage.receiving.getDetail.test.js @@ -16,32 +16,48 @@ describe('test/app/service/systems/storage.receiving.getDetail.test.js', () => { { id: 501, receiving_id: 123, + space_id: 3001, product_name: '测试商品A', box_remainder: 2, box_weight: 18.5, + receiving_space: { + id: 3001, + custom_name: 'A区定制位', + space_code: 'A-01-01', + }, toJSON() { return { id: this.id, receiving_id: this.receiving_id, + space_id: this.space_id, product_name: this.product_name, box_remainder: this.box_remainder, box_weight: this.box_weight, + receiving_space: this.receiving_space, }; }, }, { id: 502, receiving_id: 123, + space_id: 3002, product_name: '测试商品B', box_remainder: null, box_weight: null, + receiving_space: { + id: 3002, + custom_name: null, + space_code: 'B-02-03', + }, toJSON() { return { id: this.id, receiving_id: this.receiving_id, + space_id: this.space_id, product_name: this.product_name, box_remainder: this.box_remainder, box_weight: this.box_weight, + receiving_space: this.receiving_space, }; }, }, @@ -115,5 +131,13 @@ describe('test/app/service/systems/storage.receiving.getDetail.test.js', () => { assert.equal(Number(details[0].box_weight), 18.5); assert.equal(Number(details[1].box_remainder), 0); assert.equal(Number(details[1].box_weight), 0); + assert.equal(details[0].space_id, 'A区定制位'); + assert.equal(details[0].space_name, 'A区定制位'); + assert.equal(details[0].custom_space_name, 'A区定制位'); + assert.equal(Number(details[0].space_id_raw), 3001); + assert.equal(details[1].space_id, 'B-02-03'); + assert.equal(details[1].space_name, 'B-02-03'); + assert.equal(details[1].custom_space_name, null); + assert.equal(Number(details[1].space_id_raw), 3002); }); });