From aedd815e17dcf6a2e5f9cfee0c775782de44bf38 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Mon, 27 Jul 2026 03:41:24 +0800 Subject: [PATCH] =?UTF-8?q?feat(order.packing):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E6=89=93=E5=8C=85=E4=BB=BB=E5=8A=A1=E6=A8=A1=E5=9D=97=20list/g?= =?UTF-8?q?et/setEndTime/forceRecord=20=E6=96=B9=E6=B3=95=E5=8F=8A?= =?UTF-8?q?=E8=A7=86=E9=A2=91=20CDN=20URL=20=E6=8B=BC=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 order.packing.list: 打包任务列表查询,支持分页/筛选/排序,关联工作台/视频/运单 - 新增 order.packing.get: 打包任务详情查询 - 新增 order.packing.setEndTime: 设置结束时间,未完成任务自动标记为已完成 - 新增 order.packing.forceRecord: 强制重新录制,推送打印服务 - pack_task_video Model status 从 TINYINT 改为 STRING(20) 匹配 DB ENUM - 视频 URL 拼接 CDN 前缀: http://w{warehouseId}-c{computerId}.o.gztbyc.com{videoPath} - 录制电脑从 wms_print_computer(is_recording=true) + Redis 在线校验获取 - 更新 methods/system.json 与 methods/changes/system.json 文档 --- app/model/pack_task_video.js | 83 +++++++ app/service/systemMethods/order/packing.js | 94 +++++++ app/service/systems/order_packing.js | 208 +++++++++++++++- methods/changes/system.json | 48 +++- methods/system.json | 270 +++++++++++++++++++-- 5 files changed, 655 insertions(+), 48 deletions(-) create mode 100644 app/model/pack_task_video.js create mode 100644 app/service/systemMethods/order/packing.js diff --git a/app/model/pack_task_video.js b/app/model/pack_task_video.js new file mode 100644 index 0000000..1296917 --- /dev/null +++ b/app/model/pack_task_video.js @@ -0,0 +1,83 @@ +'use strict'; + +module.exports = app => { + const { STRING, BIGINT, DATE } = app.Sequelize; + + const PackTaskVideo = app.model.define('pack_task_video', { + id: { + type: BIGINT(20).UNSIGNED, + primaryKey: true, + autoIncrement: true, + comment: '主键ID', + }, + pack_task_id: { + type: BIGINT(20).UNSIGNED, + allowNull: false, + comment: '打包任务ID,关联 wms_pack_task.id', + }, + camera_id: { + type: BIGINT(20).UNSIGNED, + allowNull: true, + comment: '摄像头设备ID,关联 wms_camera.id', + }, + video_url: { + type: STRING(500), + allowNull: false, + comment: '视频地址(录像回放URL)', + }, + status: { + type: STRING(20), + allowNull: false, + defaultValue: 'created', + comment: '状态:created-已创建 recording-录制中 completed-已完成 failed-失败', + }, + remark: { + type: STRING(500), + allowNull: true, + comment: '备注', + }, + created_at: { + type: DATE, + allowNull: false, + comment: '创建时间', + }, + updated_at: { + type: DATE, + allowNull: false, + comment: '更新时间', + }, + deleted_at: { + type: DATE, + allowNull: true, + comment: '软删除时间', + }, + }, { + tableName: 'wms_pack_task_video', + timestamps: true, + createdAt: 'created_at', + updatedAt: 'updated_at', + paranoid: true, + deletedAt: 'deleted_at', + comment: '打包任务视频记录表', + indexes: [ + { name: 'idx_pack_task_id', fields: [ 'pack_task_id' ] }, + { name: 'idx_camera_id', fields: [ 'camera_id' ] }, + { name: 'idx_deleted_at', fields: [ 'deleted_at' ] }, + ], + }); + + PackTaskVideo.associate = () => { + app.model.PackTaskVideo.belongsTo(app.model.PackTask, { + foreignKey: 'pack_task_id', + targetKey: 'id', + as: 'packTask', + }); + app.model.PackTaskVideo.belongsTo(app.model.Camera, { + foreignKey: 'camera_id', + targetKey: 'id', + as: 'camera', + }); + }; + + return PackTaskVideo; +}; diff --git a/app/service/systemMethods/order/packing.js b/app/service/systemMethods/order/packing.js new file mode 100644 index 0000000..cbe7487 --- /dev/null +++ b/app/service/systemMethods/order/packing.js @@ -0,0 +1,94 @@ +'use strict'; + +const MainService = require('../../main'); + +/** + * 系统方法层:order.packing(打包任务接口包装层)。 + * 主要职责:统一包装系统方法接口,处理权限、日志等公共逻辑,调用底层 service 实现业务功能。 + * 注意:当前实现仅为包装层,实际业务逻辑完全依赖底层 service 的方法实现。 + */ +class OrderPackingMethodService extends MainService { + constructor(ctx) { + super(ctx); + const _noNeedLogin = ''; + const _noNeedRight = 'list,get'; + const _noNeedLog = 'list,get'; + const _noNeedAuth = 'list,get'; + this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth); + } + + /** + * 打包任务列表查询(仓库侧 system method 包装层)。 + * 按仓库维度查询打包任务,支持分页、筛选、排序。 + * + * @param {Object} data 请求体 + * @param {Object} [data.pagination] 分页参数 { page, pageSize } + * @param {Object} [data.where] 筛选条件。 + * 支持字段:status(任务状态)、pack_mode(打包模式)、waybill_code(运单号)、wave_no(波次号)、 + * order_id(订单ID)、workbench_id(工作台ID)、quickWhere(快捷搜索:波次号直接匹配 + 运单号通过express→order→wave链路解析)、 + * start_time_start / start_time_end(开始打包时间范围)。 + * @param {Object} [data.sort] 排序参数 { sortField, sortOrder } + * @return {Promise} 统一成功包装响应 + */ + async list(data = {}) { + const { service } = this; + const { pagination, sort } = data; + const { where } = this.prepareWhereContext(data, { + specialFieldMap: { + quickWhere: { + bucket: 'quick', + }, + }, + }); + const result = await service.systems.orderPacking.list(where, pagination, sort); + return this.success('ok', result); + } + + /** + * 打包任务详情查询(仓库侧 system method 包装层)。 + * + * @param {Object} data 请求体 + * @param {number} data.id 打包任务ID + * @return {Promise} 统一成功包装响应 + */ + async get(data = {}) { + const { service } = this; + const { id } = data; + const result = await service.systems.orderPacking.get({ id }); + return this.success('ok', result); + } + + /** + * 设置打包任务结束时间(仓库侧 system method 包装层)。 + * 若任务状态不是已完成,则同步更新状态为已完成。 + * 前端默认值逻辑:已有结束时间→当前时间;无结束时间→开始时间+5分钟。 + * + * @param {Object} data 请求体 + * @param {number} data.id 打包任务ID + * @param {string} data.end_time 结束时间(ISO 8601 或日期字符串) + * @return {Promise} 统一成功包装响应 + */ + async setEndTime(data = {}) { + const { service } = this; + const { id, end_time } = data; + const result = await service.systems.orderPacking.setEndTime({ id, end_time }); + return this.success('ok', result); + } + + /** + * 强制重新录制打包任务视频(仓库侧 system method 包装层)。 + * 将该任务推送到录制电脑,通过打印服务触发重新录制。 + * + * @param {Object} data 请求体 + * @param {number} data.id 打包任务ID + * @return {Promise} 统一成功包装响应 + */ + async forceRecord(data = {}) { + const { service } = this; + const { id } = data; + const result = await service.systems.orderPacking.forceRecord({ id }); + return this.success('ok', result); + } +} + +module.exports = OrderPackingMethodService; diff --git a/app/service/systems/order_packing.js b/app/service/systems/order_packing.js index 7188ddc..370f01a 100644 --- a/app/service/systems/order_packing.js +++ b/app/service/systems/order_packing.js @@ -8,6 +8,39 @@ const Service = require('egg').Service; * 数据来源:wms_pack_task 表。 */ class OrderPackingService extends Service { + /** + * 获取仓库的录制电脑 ID(带缓存)。 + * @param {number} warehouseId 仓库ID + * @return {Promise} 录制电脑ID,找不到返回 null + */ + async _getRecordingComputerId(warehouseId) { + const cacheKey = `_recordingComputer_${warehouseId}`; + if (this[cacheKey] !== undefined) { + return this[cacheKey]; + } + const row = await this.ctx.model.PrintComputer.findOne({ + where: { warehouse_id: warehouseId, is_recording: true, deleted_at: null }, + attributes: [ 'id' ], + raw: true, + }); + this[cacheKey] = row ? row.id : null; + return this[cacheKey]; + } + + /** + * 构建视频完整 URL。 + * 格式:http://w{warehouseId}-c{recordingComputerId}.o.gztbyc.com{videoPath} + * @param {number} warehouseId 仓库ID + * @param {number|null} recordingComputerId 录制电脑ID + * @param {string} videoPath 视频路径 + * @return {string} 完整 URL + */ + _buildVideoUrl(warehouseId, recordingComputerId, videoPath) { + if (!videoPath || !recordingComputerId) { + return videoPath || ''; + } + return `http://w${warehouseId}-c${recordingComputerId}.o.gztbyc.com${videoPath}`; + } /** * 打包任务列表查询(仓库侧)。 * 按仓库维度(warehouse_id)查询打包任务,支持分页、筛选、排序。 @@ -123,12 +156,25 @@ class OrderPackingService extends Service { const orderIds = [ ...new Set(expressRecords.map(r => r.order_id).filter(Boolean)) ]; if (orderIds.length > 0) { - // 查 order_delivery 获取 wave_id - const orderRecords = await ctx.model.OrderDelivery.findAll({ - where: { id: { [Op.in]: orderIds }, warehouse_id: warehouseId }, - attributes: [ 'id', 'wave_id' ], - raw: true, - }); + // 查 order_delivery 分表获取 wave_id(current + dispatch) + const orderDeliveryFactory = ctx.model.OrderDeliveryFactory; + const orderTableModels = [ + { label: 'current', getModel: () => orderDeliveryFactory.getCurrentModel(warehouseId) }, + { label: 'dispatch', getModel: () => orderDeliveryFactory.getDispatchModel(warehouseId) }, + ]; + const orderRecords = []; + for (const entry of orderTableModels) { + try { + const model = await entry.getModel(); + if (!model) continue; + const rows = await model.findAll({ + where: { id: { [Op.in]: orderIds }, warehouse_id: warehouseId }, + attributes: [ 'id', 'wave_id' ], + raw: true, + }); + orderRecords.push(...rows); + } catch (_err) { continue; } + } // order_id → wave_id 映射 const orderWaveMap = new Map(); @@ -240,7 +286,6 @@ class OrderPackingService extends Service { model: ctx.model.PackTaskVideo, as: 'videos', attributes: [ 'id', 'video_url', 'camera_id', 'status' ], - where: { status: 1 }, required: false, include: [ { @@ -254,13 +299,14 @@ class OrderPackingService extends Service { model: ctx.model.OrderExpress, as: 'expresses', attributes: [ 'id', 'waybill_code', 'logistics_code', 'logistics_name', 'logistics_interface_name', 'platform_code', 'status' ], - where: { delete_at: null }, + where: { warehouse_id: warehouseId, delete_at: null }, required: false, }, ], }); // 扁平化输出 + const recordingComputerId = await this._getRecordingComputerId(warehouseId); const list = rows.map(row => { const plain = row.get({ plain: true }); return { @@ -270,7 +316,8 @@ class OrderPackingService extends Service { workbench_barcode: plain.workbench?.barcode || null, videos: (plain.videos || []).map(v => ({ id: v.id, - video_url: v.video_url, + video_url: this._buildVideoUrl(warehouseId, recordingComputerId, v.video_url), + status: v.status || null, camera_id: v.camera_id, camera_name: v.camera?.custom_name || v.camera?.channel_name || null, })), @@ -339,7 +386,6 @@ class OrderPackingService extends Service { model: ctx.model.PackTaskVideo, as: 'videos', attributes: [ 'id', 'video_url', 'camera_id', 'status' ], - where: { status: 1 }, required: false, include: [ { @@ -353,7 +399,7 @@ class OrderPackingService extends Service { model: ctx.model.OrderExpress, as: 'expresses', attributes: [ 'id', 'waybill_code', 'logistics_code', 'logistics_name', 'logistics_interface_name', 'platform_code', 'status' ], - where: { delete_at: null }, + where: { warehouse_id: warehouseId, delete_at: null }, required: false, }, ], @@ -364,6 +410,7 @@ class OrderPackingService extends Service { } const plain = record.get({ plain: true }); + const recordingComputerId = await this._getRecordingComputerId(warehouseId); const data = { ...plain, workbench_name: plain.workbench?.name || null, @@ -371,7 +418,8 @@ class OrderPackingService extends Service { workbench_barcode: plain.workbench?.barcode || null, videos: (plain.videos || []).map(v => ({ id: v.id, - video_url: v.video_url, + video_url: this._buildVideoUrl(warehouseId, recordingComputerId, v.video_url), + status: v.status || null, camera_id: v.camera_id, camera_name: v.camera?.custom_name || v.camera?.channel_name || null, })), @@ -389,6 +437,142 @@ class OrderPackingService extends Service { return { code: 200, message: 'ok', data }; } + + /** + * 设置打包任务结束时间。 + * 按 id + warehouse_id 查找任务,更新结束时间。 + * 若任务状态不是已完成(2),则同时将状态更新为已完成。 + * + * @param {Object} options 操作参数 + * @param {number} options.id 打包任务ID + * @param {string} options.end_time 结束时间(ISO 8601 或日期字符串) + * @return {Promise} 操作结果 + */ + async setEndTime(options = {}) { + const { ctx } = this; + const { id, end_time } = options; + + if (!id) { + return { code: 400, message: '打包任务ID不能为空', data: null }; + } + if (!end_time) { + return { code: 400, message: '结束时间不能为空', data: null }; + } + + const warehouseId = Number(ctx.user && ctx.user.store_id); + if (!warehouseId) { + return { code: 400, message: '用户未绑定仓库,无法操作打包任务', data: null }; + } + + const record = await ctx.model.PackTask.findOne({ + where: { id: Number(id), warehouse_id: warehouseId }, + }); + + if (!record) { + return { code: 404, message: '打包任务不存在或无权访问', data: null }; + } + + const updates = { end_time: new Date(end_time) }; + + // 若任务状态不是已完成(2),同步更新为已完成 + if (record.status !== 2) { + updates.status = 2; + } + + await record.update(updates); + + return { + code: 200, + message: '结束时间设置成功', + data: { + id: record.id, + end_time: updates.end_time, + status: updates.status, + }, + }; + } + + /** + * 强制重新录制打包任务视频。 + * 将任务推送到录制电脑,通过打印服务触发重新录制。 + * + * @param {Object} options 操作参数 + * @param {number} options.id 打包任务ID + * @return {Promise} 操作结果 { code, message, data } + */ + async forceRecord(options = {}) { + const { ctx } = this; + const { id } = options; + + if (!id) { + return { code: 400, message: '打包任务ID不能为空', data: null }; + } + + const warehouseId = Number(ctx.user && ctx.user.store_id); + if (!warehouseId) { + return { code: 400, message: '用户未绑定仓库,无法操作打包任务', data: null }; + } + + // 1. 查找打包任务 + const packTask = await ctx.model.PackTask.findOne({ + where: { id: Number(id), warehouse_id: warehouseId }, + }); + if (!packTask) { + return { code: 404, message: '打包任务不存在或无权访问', data: null }; + } + + // 2. 查找仓库的录制电脑 + const recordingComputer = await ctx.model.PrintComputer.findOne({ + where: { warehouse_id: warehouseId, is_recording: true, deleted_at: null }, + raw: true, + }); + if (!recordingComputer) { + return { code: 400, message: '该仓库无录制电脑,无法强制录制', data: null }; + } + + // 3. 检查录制电脑是否在线 + const redisPrinter = ctx.app.redis.get('printer'); + const onlineKey = `warehouse:${warehouseId}:printer:${recordingComputer.id}`; + const onlineInfo = await redisPrinter.get(onlineKey); + if (!onlineInfo) { + return { code: 400, message: '该仓库录制电脑不在线,无法强制录制', data: null }; + } + + // 4. 重置视频记录状态为 created,触发重新录制 + await ctx.model.PackTaskVideo.update( + { status: 'created', video_url: '' }, + { where: { pack_task_id: Number(id), deleted_at: null } } + ); + + // 5. 通知打印服务推送强制录制任务 + const printServiceUrl = ctx.app.config.printService.url; + try { + await ctx.curl(`${printServiceUrl}/record/force`, { + method: 'POST', + contentType: 'json', + data: { + pack_task_id: Number(id), + warehouse_id: warehouseId, + computer_id: recordingComputer.id, + camera_ids: packTask.device_ids || [], + }, + dataType: 'json', + timeout: 10000, + }); + } catch (err) { + ctx.logger.warn(`通知打印服务强制录制 pack_task_id=${id} 失败: ${err.message}`); + return { code: 500, message: `通知打印服务失败: ${err.message}`, data: null }; + } + + return { + code: 200, + message: '强制录制任务已推送', + data: { + pack_task_id: Number(id), + computer_id: recordingComputer.id, + }, + }; + } } module.exports = OrderPackingService; diff --git a/methods/changes/system.json b/methods/changes/system.json index 3f26575..b6c7084 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,28 @@ [ + { + "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", @@ -147,12 +171,12 @@ { "version": "2026.06.16-system-03", "date": "2026-06-16", - "summary": "order.wave.waveStrategyFallbackOrderList 响应新增 items_weight(总重量kg)和 weight_type(重量类型)字段", + "summary": "order.wave.waveStrategyFallbackOrderList 响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", "methods": [ "order.wave.waveStrategyFallbackOrderList" ], "notes": [ - "响应 list 每项新增字段 items_weight (number|null):订单总重量(kg),来自 wms_order.items_weight,为 null 时返回 null。", + "响应 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", @@ -161,12 +185,12 @@ { "version": "2026.06.16-system-04", "date": "2026-06-16", - "summary": "order.wave.singleOrderFetchList 响应新增 items_weight(总重量kg)字段", + "summary": "order.wave.singleOrderFetchList 响应新增 items_weight(总重量g)字段", "methods": [ "order.wave.singleOrderFetchList" ], "notes": [ - "响应 list 每项新增字段 items_weight (number|null):订单总重量(kg),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", + "响应 list 每项新增字段 items_weight (number|null):订单总重量(g),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", "为 null 时返回 null。" ], "type": "updated", @@ -3648,13 +3672,13 @@ { "version": "2026.06.16-system-01", "date": "2026-06-16", - "summary": "新增 order.recheckOrder.queryRecheckOrderSingleList:散单复核列表接口,响应新增 items_weight(总重量kg)和 weight_type(重量类型)字段", + "summary": "新增 order.recheckOrder.queryRecheckOrderSingleList:散单复核列表接口,响应新增 items_weight(总重量g)和 weight_type(重量类型)字段", "methods": [ "order.recheckOrder.queryRecheckOrderSingleList" ], "notes": [ "新增方法 order.recheckOrder.queryRecheckOrderSingleList,为 recheckOrderList 散单模式的独立入口。", - "响应 list 每项新增字段 items_weight (DECIMAL(10,2)):订单总重量(kg),来自 wms_order.items_weight,为 null 时返回 null。", + "响应 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", @@ -3663,16 +3687,16 @@ { "version": "2026.06.16-system-02", "date": "2026-06-16", - "summary": "为 order.wave.groupOrderFetchList / waveStrategyFallbackOrderList / singleOrderFetchList 响应新增 items_weight(总重量kg)和 weight_type(重量类型)字段", + "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):订单总重量(kg),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", - "order.wave.waveStrategyFallbackOrderList:响应 list 每项新增 items_weight (number|null):订单总重量(kg),来自 wms_order.items_weight;新增 weight_type (string):重量类型中文标签,取值:常规/轻货/重货/冷链(对应 DB 值 0/1/2/3)。", - "order.wave.singleOrderFetchList:响应 list 每项新增 items_weight (number|null):订单总重量(kg),取组内首单 items_weight;组内订单 items_hash 相同重量一致。", + "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", @@ -3875,12 +3899,12 @@ { "version": "2026.06.19-system-01", "date": "2026-06-19", - "summary": "order.recheckOrder.scanOrder 响应 list[] 新增 items_weight(订单商品总重量kg)和 suggested_package_material(推荐包材)字段", + "summary": "order.recheckOrder.scanOrder 响应 list[] 新增 items_weight(订单商品总重量g)和 suggested_package_material(推荐包材)字段", "methods": [ "order.recheckOrder.scanOrder" ], "notes": [ - "响应 list 每项新增 items_weight (number|null):订单商品总重量(kg),来源于 wms_order_delivery.items_weight。散单模式每个订单对象包含,团购模式每个波次对象包含(取波次内首个正常订单的重量,为 null 时返回 0)。", + "响应 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,补充新增字段的说明。" ], diff --git a/methods/system.json b/methods/system.json index 8f9590d..0e5f33a 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.6", - "updatedAt": "2026-07-17", + "version": "0.3.7", + "updatedAt": "2026-07-27", "headers": [ { "name": "platform", @@ -123,7 +123,7 @@ "type": "string|number|object", "required": true, "source": "body", - "description": "修改值,类型依 method 而定:brand_name/packing_requirements/stock_unit 为 string(<=255 字符);prohibited_id 为 number(整数);gross_weight 为 number(正数,可含小数);managementFlags 为 object,必须包含 is_sn_mgmt/is_shelf_life_mgmt/is_batch_mgmt,值为 'Y' 或 'N'" + "description": "修改值,类型依 method 而定:brand_name/packing_requirements/stock_unit 为 string(<=255 字符);prohibited_id 为 number(整数);gross_weight 为 number(正整数,单位 g);managementFlags 为 object,必须包含 is_sn_mgmt/is_shelf_life_mgmt/is_batch_mgmt,值为 'Y' 或 'N'" }, { "name": "values", @@ -2142,7 +2142,7 @@ "type": "number|string", "required": true, "source": "body", - "description": "称重重量(kg),必填,必须大于 0,最多支持 3 位小数。" + "description": "称重重量(g),必填,必须大于 0,必须为正整数。" } ], "response": [ @@ -2162,7 +2162,7 @@ "name": "weighing_weight", "type": "number", "required": true, - "description": "已写入的称重重量(kg)。" + "description": "已写入的称重重量(g)。" }, { "name": "wave_no", @@ -2186,7 +2186,7 @@ "name": "total_weight", "type": "number", "required": false, - "description": "所有拆单重量累加(kg)。团购批量模式返回。" + "description": "所有拆单重量累加(g)。团购批量模式返回。" }, { "name": "split_count", @@ -2224,7 +2224,7 @@ }, { "code": 400, - "message": "weighing_weight 格式非法,最多支持 3 位小数" + "message": "weighing_weight 格式非法,必须为正整数(单位 g)" }, { "code": 400, @@ -5348,7 +5348,7 @@ "name": "list", "type": "array", "required": true, - "description": "统一列表输出。散单模式(list_type=single)有波次信息时:扁平订单数组;无波次信息时退回单订单详情模式(每项含 detail、items、expresses、logs)。团购模式(list_type=group):波次视图数组(每项含 wave_id、wave_no、wave_type、wave_status、total_orders、processed_orders、creator、create_time、update_time、order_count、pick_mode、box_no、order_ids、orders_detail、stocks[])。所有模式的 list[] 每项均附带 items_weight(订单商品总重量,单位 kg)与 suggested_package_material(推荐包材信息,无推荐时为 null)。", + "description": "统一列表输出。散单模式(list_type=single)有波次信息时:扁平订单数组;无波次信息时退回单订单详情模式(每项含 detail、items、expresses、logs)。团购模式(list_type=group):波次视图数组(每项含 wave_id、wave_no、wave_type、wave_status、total_orders、processed_orders、creator、create_time、update_time、order_count、pick_mode、box_no、order_ids、orders_detail、stocks[])。所有模式的 list[] 每项均附带 items_weight(订单商品总重量,单位 g)与 suggested_package_material(推荐包材信息,无推荐时为 null)。", "children": [ { "name": "order_id", @@ -5724,7 +5724,7 @@ { "name": "items_weight", "type": "number|null", - "description": "[全模式] 订单商品总重量(kg),来源于 wms_order_delivery.items_weight。散单模式每个订单对象包含,团购模式每个波次对象包含(取波次内首个正常订单的重量)" + "description": "[全模式] 订单商品总重量(g),来源于 wms_order_delivery.items_weight。散单模式每个订单对象包含,团购模式每个波次对象包含(取波次内首个正常订单的重量)" }, { "name": "suggested_package_material", @@ -5759,7 +5759,7 @@ { "name": "weight", "type": "number", - "description": "包材自身重量(kg)" + "description": "包材自身重量(g)" }, { "name": "length", @@ -6401,6 +6401,228 @@ } ] }, + { + "groupName": "订单打包模块", + "module": "order.packing", + "list": [ + { + "method": "order.packing.list", + "description": "打包任务列表查询。按仓库维度查询打包任务,支持分页、筛选、排序。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "pagination", + "type": "object", + "required": false, + "description": "分页参数 { page, pageSize },默认 page=1, pageSize=20", + "children": [ + { "name": "page", "type": "number", "required": false, "description": "页码" }, + { "name": "pageSize", "type": "number", "required": false, "description": "每页条数" } + ] + }, + { + "name": "sort", + "type": "object", + "required": false, + "description": "排序参数 { sortField, sortOrder }", + "children": [ + { "name": "sortField", "type": "string", "required": false, "description": "排序字段,支持:id、order_id、workbench_id、wave_id、pack_quantity、pack_mode、status、start_time、end_time、create_time、update_time" }, + { "name": "sortOrder", "type": "string", "required": false, "description": "排序方向:ASC / DESC,默认 DESC" } + ] + }, + { + "name": "where", + "type": "object", + "required": false, + "description": "筛选条件", + "children": [ + { "name": "status", "type": "number", "required": false, "description": "任务状态:0=待处理 1=打包中 2=已完成 3=异常" }, + { "name": "pack_mode", "type": "number", "required": false, "description": "打包模式:1=散单 2=团购" }, + { "name": "waybill_code", "type": "string", "required": false, "description": "运单号(模糊匹配)" }, + { "name": "wave_no", "type": "string", "required": false, "description": "波次号(模糊匹配)" }, + { "name": "order_id", "type": "number", "required": false, "description": "订单ID(精确匹配)" }, + { "name": "workbench_id", "type": "number", "required": false, "description": "工作台ID(精确匹配)" }, + { "name": "quickWhere", "type": "string", "required": false, "description": "快捷搜索:波次号模糊匹配 + 运单号通过 express→order→wave 链路解析" }, + { "name": "start_time_start", "type": "string", "required": false, "description": "开始打包时间范围起始(ISO 8601)" }, + { "name": "start_time_end", "type": "string", "required": false, "description": "开始打包时间范围结束(ISO 8601)" } + ] + } + ], + "response": [ + { + "name": "list", + "type": "array", + "required": true, + "description": "打包任务列表,每项含 id、order_id、warehouse_id、workbench_id、wave_id、wave_no、waybill_code、pack_quantity、item_quantity、sku_count、pack_mode、status、start_time、end_time、operator_text、device_ids、remark、meta、create_time、update_time、workbench_name、workbench_type、workbench_barcode、videos[]、expresses[]" + }, + { + "name": "pagination", + "type": "object", + "required": true, + "description": "分页信息,含 page、pageSize、total、totalPages、hasPrevious、hasNext" + } + ], + "errors": [] + }, + { + "method": "order.packing.get", + "description": "打包任务详情查询。按 id + warehouse_id 查询单条打包任务记录,含工作台、视频和运单关联信息。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "打包任务ID" + } + ], + "response": [ + { + "name": "data", + "type": "object", + "required": true, + "description": "打包任务详情,含 id、order_id、warehouse_id、workbench_id、wave_id、wave_no、waybill_code、pack_quantity、item_quantity、sku_count、pack_mode、status、start_time、end_time、operator_text、device_ids、remark、meta、create_time、update_time、workbench_name、workbench_type、workbench_barcode、videos[]、expresses[]" + } + ], + "errors": [ + { + "code": 400, + "description": "参数校验失败(如缺少 id)" + }, + { + "code": 404, + "description": "打包任务不存在或无权访问" + } + ] + }, + { + "method": "order.packing.setEndTime", + "description": "设置打包任务结束时间。若任务状态不是已完成(2),则同步更新状态为已完成。前端默认值:若任务已有结束时间则默认为当前时间,否则默认为开始时间+5分钟。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "打包任务ID" + }, + { + "name": "end_time", + "type": "string", + "required": true, + "description": "结束时间(ISO 8601 格式,如 2026-07-27T11:00:00.000Z)。前端默认值:若任务已有结束时间→当前时间;无结束时间→开始时间+5分钟" + } + ], + "response": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "打包任务ID" + }, + { + "name": "end_time", + "type": "string", + "required": true, + "description": "更新后的结束时间" + }, + { + "name": "status", + "type": "number", + "required": true, + "description": "更新后的任务状态" + } + ], + "errors": [ + { + "code": 400, + "description": "参数校验失败(如缺少 id 或 end_time、用户未绑定仓库)" + }, + { + "code": 404, + "description": "打包任务不存在或无权访问" + } + ] + }, + { + "method": "order.packing.forceRecord", + "description": "强制重新录制打包任务视频。将任务推送到录制电脑,通过打印服务触发重新录制。内部会重置视频状态为 created 并清空 video_url。", + "isNeedAuth": false, + "isNeedLogin": true, + "headers": [ + { + "name": "Authorization", + "type": "string", + "required": true, + "description": "Bearer token" + } + ], + "params": [ + { + "name": "id", + "type": "number", + "required": true, + "description": "打包任务ID" + } + ], + "response": [ + { + "name": "pack_task_id", + "type": "number", + "required": true, + "description": "打包任务ID" + }, + { + "name": "computer_id", + "type": "number", + "required": true, + "description": "录制电脑ID" + } + ], + "errors": [ + { + "code": 400, + "description": "参数校验失败(如缺少 id、用户未绑定仓库、无录制电脑、录制电脑不在线)" + }, + { + "code": 404, + "description": "打包任务不存在或无权访问" + }, + { + "code": 500, + "description": "通知打印服务失败" + } + ] + } + ] + }, { "groupName": "订单波次模块", "module": "order.wave", @@ -7639,7 +7861,7 @@ "name": "list", "type": "array", "required": true, - "description": "分组列表,每项包含 item_detail、item_detail_machine、item_detail_machine_snapshot、item_snapshot、group、group_count、items_total、items_weight(总重量kg,取组内首单 items_weight)、store_id、store_ids、logistics_name、distinguish_express、first_order_time、last_order_time、status_summary 等字段;若指定 return_order_ids=true 则额外包含 order_ids" + "description": "分组列表,每项包含 item_detail、item_detail_machine、item_detail_machine_snapshot、item_snapshot、group、group_count、items_total、items_weight(总重量g,取组内首单 items_weight)、store_id、store_ids、logistics_name、distinguish_express、first_order_time、last_order_time、status_summary 等字段;若指定 return_order_ids=true 则额外包含 order_ids" }, { "name": "pagination", @@ -7806,7 +8028,7 @@ { "name": "items_weight", "type": "number", - "description": "订单总重量(kg),来自 wms_order.items_weight,为 null 时返回 null" + "description": "订单总重量(g),来自 wms_order.items_weight,为 null 时返回 null" }, { "name": "weight_type", @@ -7927,7 +8149,7 @@ "name": "list", "type": "array", "required": true, - "description": "散单候选分组列表,每项包含 item_detail、item_detail_machine、item_detail_machine_snapshot、item_snapshot、group、group_count、items_total、items_weight(总重量kg,取组内首单 items_weight)、store_id、store_ids、logistics_name、distinguish_express、first_order_time、last_order_time、status_summary 等字段;返回的 group_count 均小于 same_order_quantity(或仓库配置的 min_group_order_fetch_quantity);若指定 return_order_ids=true 则额外包含 order_ids" + "description": "散单候选分组列表,每项包含 item_detail、item_detail_machine、item_detail_machine_snapshot、item_snapshot、group、group_count、items_total、items_weight(总重量g,取组内首单 items_weight)、store_id、store_ids、logistics_name、distinguish_express、first_order_time、last_order_time、status_summary 等字段;返回的 group_count 均小于 same_order_quantity(或仓库配置的 min_group_order_fetch_quantity);若指定 return_order_ids=true 则额外包含 order_ids" }, { "name": "pagination", @@ -10853,7 +11075,7 @@ { "name": "items_weight", "type": "number", - "description": "重量" + "description": "重量(单位 g)" } ] }, @@ -15952,7 +16174,7 @@ "type": "string|number|object", "required": true, "source": "body", - "description": "修改值,类型依 method 而定:brand_name/packing_requirements/stock_unit 为 string(<=255 字符);prohibited_id 为 number(整数);gross_weight 为 number(正数,可含小数);managementFlags 为 object,必须包含 is_sn_mgmt/is_shelf_life_mgmt/is_batch_mgmt,值为 'Y' 或 'N'" + "description": "修改值,类型依 method 而定:brand_name/packing_requirements/stock_unit 为 string(<=255 字符);prohibited_id 为 number(整数);gross_weight 为 number(正整数,单位 g);managementFlags 为 object,必须包含 is_sn_mgmt/is_shelf_life_mgmt/is_batch_mgmt,值为 'Y' 或 'N'" }, { "name": "values", @@ -18725,7 +18947,7 @@ "name": "receiving.details.*.box_weight", "type": "number", "required": false, - "description": "实测箱重(单位与系统重量一致,如 kg)" + "description": "实测箱重(单位与系统重量一致,如 g)" } ], "errors": [ @@ -19392,7 +19614,7 @@ "name": "data.details.*.box_weight", "type": "number", "required": false, - "description": "实测箱重(单位与系统重量一致,如 kg),默认 0" + "description": "实测箱重(单位与系统重量一致,如 g),默认 0" } ], "errors": [] @@ -19473,12 +19695,12 @@ { "name": "box_weight", "type": "number", - "description": "箱重" + "description": "箱重(单位 g)" }, { "name": "weight", "type": "number", - "description": "商品重量" + "description": "商品重量(单位 g)" }, { "name": "barcode", @@ -19778,14 +20000,14 @@ "type": "number", "required": false, "source": "body", - "description": "实测箱重(单位与系统重量一致,如 kg)" + "description": "实测箱重(单位与系统重量一致,如 g)" }, { "name": "weight", "type": "number", "required": false, "source": "body", - "description": "毛重/重量" + "description": "毛重/重量(单位 g)" } ], "response": [ @@ -19835,7 +20057,7 @@ "name": "data.box_weight", "type": "number", "required": false, - "description": "实测箱重(单位与系统重量一致,如 kg)" + "description": "实测箱重(单位与系统重量一致,如 g)" }, { "name": "data.updated_at", @@ -19892,7 +20114,7 @@ "params": [], "response": [], "notes": [ - "完成收货时会发送通知:通知 payload 或 metadata 将在每条明细中携带 box_remainder(箱内剩余数量/零散件数,number)与 box_weight(实测箱重,number,单位同系统重量,例如 kg)。新增字段为可选,旧客户端可忽略。" + "完成收货时会发送通知:通知 payload 或 metadata 将在每条明细中携带 box_remainder(箱内剩余数量/零散件数,number)与 box_weight(实测箱重,number,单位同系统重量,例如 g)。新增字段为可选,旧客户端可忽略。" ], "errors": [] } @@ -26295,7 +26517,7 @@ "type": "number", "required": false, "source": "body", - "description": "重量" + "description": "重量(单位 g)" }, { "name": "cost_price",