feat(order.packing): 新增打包任务模块 list/get/setEndTime/forceRecord 方法及视频 CDN URL 拼接

- 新增 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 文档
This commit is contained in:
liufumingren 2026-07-27 03:41:24 +08:00
parent a69fd3f393
commit aedd815e17
5 changed files with 655 additions and 48 deletions

View File

@ -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;
};

View File

@ -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<Object>} 统一成功包装响应
*/
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<Object>} 统一成功包装响应
*/
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<Object>} 统一成功包装响应
*/
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<Object>} 统一成功包装响应
*/
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;

View File

@ -8,6 +8,39 @@ const Service = require('egg').Service;
* 数据来源:wms_pack_task 表。
*/
class OrderPackingService extends Service {
/**
* 获取仓库的录制电脑 ID(带缓存)。
* @param {number} warehouseId 仓库ID
* @return {Promise<number|null>} 录制电脑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<Object>} 操作结果
*/
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<Object>} 操作结果 { 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;

View File

@ -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,补充新增字段的说明。"
],

View File

@ -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",