liufumingren 59bc65b443 feat(order): B2B 加急优先、分箱明细与取货储位,作业链路收口
- 列表:B2B 待处理/配送列表固定加急优先排序(wms_order_b2b.is_urgent='Y' 置顶),
  作业明细筛选口径不变
- 备货/提货:新增 setB2bUrgent/cancelB2bUrgent、startB2bPrep/cancelB2bPrep/finishB2bPrep、
  setB2bPickupPlate、pickupB2b、updateB2bOrderImages;提货即出库完成
  (写 outbound_status=fin / step=4 / delivery_time 并迁移到配送表),车牌与提货照片
  随单落库
- 分箱:新增 wms_order_b2b_items 与 order.updateB2bPackingItems、order.getB2bPackingSnapshot;
  快照按商品行返回 wms_picking 取货储位(items[].pick_locations / pick_location_count),
  列表不再携带储位明细
- 齐套校验:仓库 subject_config 新增 b2b_packing_quantity_check,备货完成时逐商品校验
  分箱数量合计等于 plan_qty 且总箱数与箱号数一致
- 拦截:B2B 订单不参与波次抓取、快捷复核批量发货、反审回待审核与克隆,命中即整批驳回
- 明细:order.pendingOrder.detail / order.deliveryOrder.detail 为 B2B 订单附加副表作业明细
  b2b、备货照片 images 与提货照片 pickup_images
- 迁移:wms_order_b2b 新增 is_urgent 与备货作业字段,新建 wms_order_b2b_items
- 文档:methods/system.json 与 methods/changes/system.json 同步至 0.3.375

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-19 18:17:19 +08:00

1095 lines
41 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'use strict';
const OrderBaseService = require('./base');
const ORDER_EXPORT_TASK_CACHE_KEY_PREFIX = 'order_export_task_';
const ORDER_EXPORT_TASK_CACHE_TTL_SECONDS = 1800;
class OrderIndexService extends OrderBaseService {
/**
* 初始化订单系统方法的免登录、免权限、免日志和免鉴权配置。
* @param {Egg.Context} ctx 上下文对象。
*/
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'list,badgeCount,manualOutboundOrder,queryOrderLogs,queryOrderLogList,detail,updateExpressWeighingWeight,export,exportTaskProgress,bindExpressPackageMaterialByWaybill,convertToB2b,cancelB2b,setB2bUrgent,cancelB2bUrgent,startB2bPrep,cancelB2bPrep,finishB2bPrep,updateB2bPackingItems,getB2bPackingSnapshot,setB2bPickupPlate,pickupB2b,updateB2bOrderImages';
const _noNeedLog = 'list,badgeCount,manualOutboundOrder,queryOrderLogs,queryOrderLogList,detail,updateExpressWeighingWeight,export,exportTaskProgress,bindExpressPackageMaterialByWaybill,convertToB2b,cancelB2b,setB2bUrgent,cancelB2bUrgent,startB2bPrep,cancelB2bPrep,finishB2bPrep,updateB2bPackingItems,getB2bPackingSnapshot,setB2bPickupPlate,pickupB2b,updateB2bOrderImages';
const _noNeedAuth = 'list,badgeCount,manualOutboundOrder,queryOrderLogs,queryOrderLogList,detail,updateExpressWeighingWeight,export,exportTaskProgress,bindExpressPackageMaterialByWaybill,convertToB2b,cancelB2b,setB2bUrgent,cancelB2bUrgent,startB2bPrep,cancelB2bPrep,finishB2bPrep,updateB2bPackingItems,getB2bPackingSnapshot,setB2bPickupPlate,pickupB2b,updateB2bOrderImages';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
/**
* 订单转 B2B 订单。
*
* 仅限待处理表中处于待处理阶段(step in [1,2,3])、未取消、未拣货、未复核、
* 未锁定、未拦截的订单(打印状态不限制);不符合条件跳过。
* 事务内:订单表 is_b2b 置 Y + 写入 wms_order_b2b 作业明细,提交后写操作日志。
*
* @param {Object} data 请求体。
* @param {Array<number|string>|number|string} [data.ids] 订单ID集合(优先)。
* @param {Array<number|string>|number|string} [data.order_ids] 订单ID集合别名。
* @param {Array<number|string>|number|string} [data.orderIds] 订单ID集合别名。
* @param {number|string} [data.id] 订单ID单值别名。
* @param {number|string} [data.order_id] 订单ID单值别名。
* @param {number|string} [data.orderId] 订单ID单值别名。
* @return {Promise<Object>} 统一成功包装响应(data 含 converted/skipped/not_found 分流结果)。
*/
async convertToB2b(data = {}) {
const requestData = this.isPlainObject(data) ? data : {};
const rawIds = requestData.ids !== undefined ? requestData.ids
: requestData.order_ids !== undefined ? requestData.order_ids
: requestData.orderIds !== undefined ? requestData.orderIds
: requestData.id !== undefined ? requestData.id
: requestData.order_id !== undefined ? requestData.order_id
: requestData.orderId;
const orderIds = [ ...new Set(
(Array.isArray(rawIds) ? rawIds : [ rawIds ])
.map(item => Number(item))
.filter(item => Number.isInteger(item) && item > 0)
) ];
if (orderIds.length === 0) {
return this.fail('订单ID不能为空', {}, 400);
}
if (orderIds.length > 200) {
return this.fail('单次最多转换 200 个订单', {}, 400);
}
const warehouseId = this.getWarehouseId();
const operator = this.getOrderLogOperator();
const result = await this.service.systems.orderB2b.convertOrdersToB2b({
warehouseId,
orderIds,
operator,
});
return this.success('ok', result);
}
/**
* 取消 B2B 出库:订单流转回正常订单。
*
* 仅限待处理表中 is_b2b=Y 且未锁定、未拦截的订单(打印状态不限制);
* 不符合条件跳过。事务内:订单表 is_b2b 置回 N + B2B 作业明细物理删除,
* 提交后写操作日志。
*
* @param {Object} data 请求体。
* @param {Array<number|string>|number|string} [data.ids] 订单ID集合(优先)。
* @param {Array<number|string>|number|string} [data.order_ids] 订单ID集合别名。
* @param {Array<number|string>|number|string} [data.orderIds] 订单ID集合别名。
* @param {number|string} [data.id] 订单ID单值别名。
* @param {number|string} [data.order_id] 订单ID单值别名。
* @param {number|string} [data.orderId] 订单ID单值别名。
* @return {Promise<Object>} 统一成功包装响应(data 含 canceled/skipped/not_found 分流结果)。
*/
async cancelB2b(data = {}) {
const requestData = this.isPlainObject(data) ? data : {};
const rawIds = requestData.ids !== undefined ? requestData.ids
: requestData.order_ids !== undefined ? requestData.order_ids
: requestData.orderIds !== undefined ? requestData.orderIds
: requestData.id !== undefined ? requestData.id
: requestData.order_id !== undefined ? requestData.order_id
: requestData.orderId;
const orderIds = [ ...new Set(
(Array.isArray(rawIds) ? rawIds : [ rawIds ])
.map(item => Number(item))
.filter(item => Number.isInteger(item) && item > 0)
) ];
if (orderIds.length === 0) {
return this.fail('订单ID不能为空', {}, 400);
}
if (orderIds.length > 200) {
return this.fail('单次最多取消 200 个订单', {}, 400);
}
const warehouseId = this.getWarehouseId();
const operator = this.getOrderLogOperator();
const result = await this.service.systems.orderB2b.cancelOrdersB2b({
warehouseId,
orderIds,
operator,
});
return this.success('ok', result);
}
/**
* 取消 B2B 订单加急(仅对 B2B 订单生效)。
*
* 等价于 order.setB2bUrgent 传 is_urgent='N',入参 is_urgent 被强制覆盖为 N,
* 避免调用方误传导致加急未被取消。校验与跳过口径同 setB2bUrgent:
* 非 B2B 订单、已取消订单跳过并在 skipped_reasons 返回原因。
*
* @param {Object} data 请求体。
* @param {Array<number|string>|number|string} [data.ids] 订单ID集合(优先)。
* @param {Array<number|string>|number|string} [data.order_ids] 订单ID集合别名。
* @param {Array<number|string>|number|string} [data.orderIds] 订单ID集合别名。
* @param {number|string} [data.id] 订单ID单值别名。
* @return {Promise<Object>} 统一成功包装响应(data.is_urgent 恒为 'N')。
*/
async cancelB2bUrgent(data = {}) {
const requestData = this.isPlainObject(data) ? data : {};
return await this.setB2bUrgent({
...requestData,
is_urgent: 'N',
isUrgent: 'N',
urgent: 'N',
});
}
/**
* 设置 B2B 订单是否加急(仅对 B2B 订单生效)。
*
* 非 B2B 订单跳过并在 skipped_reasons 返回原因;已取消订单同样跳过。
* 订单在 current 分表查找,未命中兜底到 dispatch 分表;事务内更新
* wms_order_b2b.is_urgent,提交后写操作日志。
*
* @param {Object} data 请求体。
* @param {Array<number|string>|number|string} [data.ids] 订单ID集合(优先)。
* @param {Array<number|string>|number|string} [data.order_ids] 订单ID集合别名。
* @param {Array<number|string>|number|string} [data.orderIds] 订单ID集合别名。
* @param {number|string} [data.id] 订单ID单值别名。
* @param {string|boolean|number} [data.is_urgent='Y'] 是否加急(兼容 is_urgent/isUrgent/urgent,支持 Y/N、true/false、1/0)。
* @return {Promise<Object>} 统一成功包装响应(data 含 updated/skipped/not_found 分流结果)。
*/
async setB2bUrgent(data = {}) {
const requestData = this.isPlainObject(data) ? data : {};
const rawIds = requestData.ids !== undefined ? requestData.ids
: requestData.order_ids !== undefined ? requestData.order_ids
: requestData.orderIds !== undefined ? requestData.orderIds
: requestData.id !== undefined ? requestData.id
: requestData.order_id !== undefined ? requestData.order_id
: requestData.orderId;
const orderIds = [ ...new Set(
(Array.isArray(rawIds) ? rawIds : [ rawIds ])
.map(item => Number(item))
.filter(item => Number.isInteger(item) && item > 0)
) ];
if (orderIds.length === 0) {
return this.fail('订单ID不能为空', {}, 400);
}
if (orderIds.length > 200) {
return this.fail('单次最多设置 200 个订单', {}, 400);
}
const isUrgent = requestData.is_urgent !== undefined ? requestData.is_urgent
: requestData.isUrgent !== undefined ? requestData.isUrgent
: requestData.urgent;
const warehouseId = this.getWarehouseId();
const operator = this.getOrderLogOperator();
let result;
try {
result = await this.service.systems.orderB2b.setOrdersB2bUrgent({
warehouseId,
orderIds,
isUrgent,
operator,
});
} catch (error) {
if (error && /is_urgent 参数不合法/.test(error.message)) {
return this.fail(error.message, {}, 400);
}
throw error;
}
return this.success('ok', result);
}
/**
* 备货开始(仅 B2B 订单,单订单作业):记录备货人工号与开始时间。
*
* 操作人为当前登录工号(ctx.user);同工号重复开始幂等成功,
* 订单已由其他工号开始或已完成时返回失败。ids 仅允许传 1 个订单ID。
* 作业前置条件:已打印(print_status=fin)、已分配储位(storage_status=fin)且未拦截
* (intercept_status=none),不满足返回 failure 400 且不写入任何备货数据;
* 领料(claim_status)不校验——领料只在波次整波领单流程产生,B2B 订单无波次。
*
* @param {Object} data 请求体。
* @param {Array<number|string>|number|string} [data.ids] 订单ID集合(优先)。
* @param {Array<number|string>|number|string} [data.order_ids] 订单ID集合别名。
* @return {Promise<Object>} 统一响应。
*/
async startB2bPrep(data = {}) {
return await this.runB2bSingleOrderAction(
data,
'startOrdersB2bPrep',
d => ({ warehouseId: this.getWarehouseId(), orderIds: this.normalizeB2bPrepOrderIds(d), operator: this.getOrderLogOperator() }),
'备货作业'
);
}
/**
* 取消备货(仅 B2B 订单,单订单作业):重置备货人、开始时间与备货状态。
*
* 仅备货中的订单可取消,且必须由记录在案的同一工号操作,否则返回失败。ids 仅允许传 1 个订单ID。
*
* @param {Object} data 请求体(入参同 startB2bPrep)。
* @return {Promise<Object>} 统一响应。
*/
async cancelB2bPrep(data = {}) {
return await this.runB2bSingleOrderAction(
data,
'cancelOrdersB2bPrep',
d => ({ warehouseId: this.getWarehouseId(), orderIds: this.normalizeB2bPrepOrderIds(d), operator: this.getOrderLogOperator() }),
'备货作业'
);
}
/**
* 备货结束(仅 B2B 订单,单订单作业):写入备货备注、总箱数、完成时间与备货用时。
*
* 结束时间取提交时刻;仅备货中的订单可结束,且必须由同一工号提交,否则返回失败。ids 仅允许传 1 个订单ID。
*
* @param {Object} data 请求体。
* @param {Array<number|string>|number|string} [data.ids] 订单ID集合(优先)。
* @param {string} data.prep_remark 备货备注(必填,兼容 prepRemark)。
* @param {number|string} data.total_box_count 总箱数(必填,兼容 totalBoxCount)。
* @return {Promise<Object>} 统一响应。
*/
async finishB2bPrep(data = {}) {
return await this.runB2bSingleOrderAction(
data,
'finishOrdersB2bPrep',
d => ({
warehouseId: this.getWarehouseId(),
orderIds: this.normalizeB2bPrepOrderIds(d),
operator: this.getOrderLogOperator(),
prepRemark: d.prep_remark !== undefined ? d.prep_remark : d.prepRemark,
totalBoxCount: d.total_box_count !== undefined ? d.total_box_count : d.totalBoxCount,
}),
'备货作业'
);
}
/**
* 全量更新单个 B2B 订单的商品分箱明细。
* @param {Object} data 请求体。
* @param {Array<Object>} data.items 分箱行:order_item_id、box_no、quantity。
* @return {Promise<Object>} 更新结果。
*/
async updateB2bPackingItems(data = {}) {
return await this.runB2bSingleOrderAction(
data,
'updateB2bPackingItems',
d => ({
warehouseId: this.getWarehouseId(),
orderIds: this.normalizeB2bPrepOrderIds(d),
operator: this.getOrderLogOperator(),
items: d.items,
}),
'更新分箱明细'
);
}
/**
* 获取单个 B2B 订单商品与分箱记录的完整快照。
* @param {Object} data 请求体。
* @return {Promise<Object>} 订单快照。
*/
async getB2bPackingSnapshot(data = {}) {
return await this.runB2bSingleOrderAction(
data,
'getB2bPackingSnapshot',
d => ({
warehouseId: this.getWarehouseId(),
orderIds: this.normalizeB2bPrepOrderIds(d),
}),
'查询分箱快照'
);
}
/**
* 录入/修改 B2B 提货车牌(单订单,提货前可改)。
*
* 仅 B2B 订单且未取消的订单可录入;订单已提货(is_picked_up='Y')后车牌锁定,
* 不允许再修改。作业明细行缺失时自动补建。传空字符串或 null 表示清空车牌;
* 车牌会去掉空格与分隔符并转大写后落库。ids 仅允许传 1 个订单ID。
*
* @param {Object} data 请求体。
* @param {number|string} [data.ids] 订单ID(单值或单元素数组)。
* @param {string|null} data.pickup_plate_number 提货车牌(必传键;兼容 pickupPlateNumber,空串/null 清空)。
* @return {Promise<Object>} 统一响应。
*/
async setB2bPickupPlate(data = {}) {
return await this.runB2bSingleOrderAction(
data,
'setOrdersB2bPickupPlate',
d => ({
warehouseId: this.getWarehouseId(),
orderIds: this.normalizeB2bPrepOrderIds(d),
operator: this.getOrderLogOperator(),
pickupPlateNumber: d.pickup_plate_number !== undefined ? d.pickup_plate_number : d.pickupPlateNumber,
}),
'录入提货车牌'
);
}
/**
* B2B 提货(单订单作业):记录提货时间。仅 B2B 订单生效。
*
* 要求备货已完成(prep_status=fin);已提货订单幂等成功(保留首次提货时间)。
* 可选传 pickup_plate_number 在提货同时写入车牌(提货后不允许再改);
* 可选传 file_ids(标准字段,兼容 pickup_file_ids / pickupFileIds / pickup_images / pickupImages)
* 在提货同时写入提货照片,照片只做一轮存在性校验后追加到 business_type='b2b_pickup' 的关联下。
* ids 仅允许传 1 个订单ID。
*
* @param {Object} data 请求体。
* @param {number|string} [data.ids] 订单ID(单值或单元素数组)。
* @param {string|null} [data.pickup_plate_number] 提货车牌(可选,兼容 pickupPlateNumber)。
* @param {Array<Object|number|string>} [data.file_ids] 提货照片列表(标准字段,
* 元素为 file_id 或 { file_id, display_order })。
* @return {Promise<Object>} 统一响应。
*/
async pickupB2b(data = {}) {
return await this.runB2bSingleOrderAction(
data,
'pickupOrdersB2b',
d => ({
warehouseId: this.getWarehouseId(),
orderIds: this.normalizeB2bPrepOrderIds(d),
operator: this.getOrderLogOperator(),
pickupPlateNumber: d.pickup_plate_number !== undefined ? d.pickup_plate_number : d.pickupPlateNumber,
pickupImages: this.resolveB2bPickupImageInput(d),
}),
'提货'
);
}
/**
* 解析 B2B 图片入参(统一标准字段 file_ids,兼容各别名)。
*
* 标准写法:file_ids,元素为 file_id(数字/数字字符串)或 { file_id, display_order }。
* 别名按传入顺序作为后备:同时传标准字段与别名时以 file_ids/fileIds 为准。
*
* @param {Object} data 请求体。
* @param {string[]} [aliasKeys=[]] 该场景额外接受的别名字段。
* @return {*} 原始图片入参(未传时返回 undefined)。
*/
resolveB2bFileIdsInput(data = {}, aliasKeys = []) {
const keys = [ 'file_ids', 'fileIds', ...aliasKeys ];
for (const key of keys) {
if (data[key] !== undefined) {
return data[key];
}
}
return undefined;
}
/**
* 解析提货时随车提交的照片入参(标准 file_ids)。
*
* 兼容别名:pickup_file_ids / pickupFileIds / pickup_images / pickupImages。
*
* @param {Object} data 请求体。
* @return {Array|undefined} 图片列表;未传时返回 undefined(表示本次不附带提货照片)。
*/
resolveB2bPickupImageInput(data = {}) {
return this.resolveB2bFileIdsInput(data, [ 'pickup_file_ids', 'pickupFileIds', 'pickup_images', 'pickupImages' ]);
}
/**
* 解析备货照片入参(标准 file_ids)。
*
* 兼容别名:images(历史写法,语义等价于 file_ids)。
*
* @param {Object} data 请求体。
* @return {*} 原始图片入参(未传时返回 undefined,由业务层判定为非法)。
*/
resolveB2bImageListInput(data = {}) {
return this.resolveB2bFileIdsInput(data, [ 'images' ]);
}
/**
* 更新 B2B 订单图片(单订单,全量覆盖)。
*
* 图片关系统一落在 wms_file_reference:business_type='b2b_order'、
* business_id=订单ID、warehouse_id=当前仓库、display_order 控制展示顺序。
* 标准入参为 file_ids(元素 file_id 或 { file_id, display_order }),
* 兼容别名 images / fileIds;全量覆盖语义:未包含的旧关联会被删除,
* 新关联按列表顺序写入;传空数组表示清空该订单图片。
* 仅 B2B 订单(is_b2b='Y')且未取消的订单可更新。
*
* @param {Object} data 请求体。
* @param {number|string} [data.id] 订单ID(单值或单元素数组)。
* @param {Array<Object|number|string>} data.file_ids 图片列表(标准字段),元素可为
* { file_id, display_order } 或直接传 file_id;兼容 images / fileIds 简写。
* @return {Promise<Object>} 统一响应。
*/
async updateB2bOrderImages(data = {}) {
const requestData = this.isPlainObject(data) ? data : {};
const orderIds = this.normalizeB2bPrepOrderIds(requestData);
if (orderIds.length === 0) {
return this.fail('订单ID不能为空', {}, 400);
}
if (orderIds.length > 1) {
return this.fail('更新订单图片仅支持单个订单,请单条提交', { order_ids: orderIds }, 400);
}
const rawImages = this.resolveB2bImageListInput(requestData);
try {
const result = await this.service.systems.orderB2b.updateOrderImages({
warehouseId: this.getWarehouseId(),
orderIds,
images: rawImages,
operator: this.getOrderLogOperator(),
});
return this.success('ok', result);
} catch (error) {
const code = String(error && error.code || '');
if (code.startsWith('B2B_IMAGE_')) {
return this.fail(error.message, error.data || {}, 400);
}
throw error;
}
}
/**
* 归一化备货/提货单订单入参(6 种别名,单值或单元素数组)。
* @param {Object} requestData 请求体。
* @return {number[]} 订单ID数组。
*/
normalizeB2bPrepOrderIds(requestData = {}) {
const rawIds = requestData.ids !== undefined ? requestData.ids
: requestData.order_ids !== undefined ? requestData.order_ids
: requestData.orderIds !== undefined ? requestData.orderIds
: requestData.id !== undefined ? requestData.id
: requestData.order_id !== undefined ? requestData.order_id
: requestData.orderId;
return [ ...new Set(
(Array.isArray(rawIds) ? rawIds : [ rawIds ])
.map(item => Number(item))
.filter(item => Number.isInteger(item) && item > 0)
) ];
}
/**
* B2B 单订单作业统一执行壳:入参校验 → 调业务层 → 统一成功/失败包装。
*
* 业务层抛出的备货/提货/车牌/图片校验错误(带 code/data,
* 前缀 B2B_PREP_ / B2B_PICKUP_ / B2B_PLATE_ / B2B_IMAGE_)统一转 failure 400,
* 便于前端展示原因;其它异常继续抛出(由控制器转 500)。
*
* @param {Object} data 请求体。
* @param {string} serviceMethod 业务方法名。
* @param {Function} buildParams 参数构造器。
* @param {string} [actionText='备货作业'] 动作文案(用于批量拒绝提示)。
* @return {Promise<Object>} 统一响应。
*/
async runB2bSingleOrderAction(data = {}, serviceMethod, buildParams, actionText = '备货作业') {
const requestData = this.isPlainObject(data) ? data : {};
const params = buildParams(requestData);
if (params.orderIds.length === 0) {
return this.fail('订单ID不能为空', {}, 400);
}
if (params.orderIds.length > 1) {
return this.fail(`${actionText}仅支持单个订单,请单条提交`, { order_ids: params.orderIds }, 400);
}
try {
const result = await this.service.systems.orderB2b[serviceMethod](params);
return this.success('ok', result);
} catch (error) {
const code = String(error && error.code || '');
if (code.startsWith('B2B_PREP_') || code.startsWith('B2B_PACKING_') || code.startsWith('B2B_PICKUP_')
|| code.startsWith('B2B_PLATE_') || code.startsWith('B2B_IMAGE_')) {
return this.fail(error.message, error.data || {}, 400);
}
throw error;
}
}
/**
* 提交订单导出任务。
*
* 入参支持 table_type/module 组合;where 与 sort 语义与订单列表保持一致。
* 方法层负责任务入队与进度缓存,导出由 systems.orderExport 异步执行。
*
* @param {Object} data 请求体。
* @param {string} [data.table_type] 导出表类型(current/history/dispatch/outsourced,兼容模块别名)。
* @param {string} [data.tableType] 导出表类型(驼峰写法)。
* @param {string} [data.module] 订单模块名(可选)。
* @param {string} [data.module_name] 订单模块名(下划线写法)。
* @param {string} [data.export_mode] 导出模式:waybill(默认,按运单展开)或 item(按商品明细展开)。
* @param {string} [data.exportMode] 导出模式(驼峰写法)。
* @param {Array<string>} [data.export_columns] 导出表头字段白名单(中文表头数组),不传或空数组输出全部列;非法表头会报错。
* @param {Array<string>} [data.exportColumns] 导出表头字段白名单(驼峰写法)。
* @param {Object} [data.where] 查询条件。
* @param {Object} [data.sort] 排序参数。
* @return {Promise<Object>} 统一成功包装响应。
*/
async export(data = {}) {
const requestData = this.isPlainObject(data) ? data : {};
const {
table_type: tableTypeSnake,
tableType: tableTypeCamel,
module: moduleName,
module_name: moduleNameSnake,
export_mode: exportModeSnake,
exportMode: exportModeCamel,
export_columns: exportColumnsSnake,
exportColumns: exportColumnsCamel,
where,
sort,
} = requestData;
const taskId = this.generateExportTaskId();
const tableType = tableTypeSnake || tableTypeCamel || 'current';
const module = moduleName || moduleNameSnake || '';
const taskPayload = {
task_id: taskId,
status: 'submitted',
progress: 0,
current_count: 0,
total_count: 0,
message: '导出任务已提交',
result: null,
error: '',
};
await this.setExportTaskProgress(taskId, taskPayload);
setImmediate(async () => {
try {
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'running',
progress: 5,
current_count: 0,
total_count: 0,
message: '导出任务执行中',
result: null,
error: '',
});
const exportMode = exportModeSnake || exportModeCamel || '';
const exportColumns = Array.isArray(exportColumnsSnake)
? exportColumnsSnake
: (Array.isArray(exportColumnsCamel) ? exportColumnsCamel : []);
const result = await this.service.systems.orderExport.exportOrders({
tableType,
moduleName: module,
export_mode: exportMode,
export_columns: exportColumns,
where: this.isPlainObject(where) ? { ...where } : {},
sort: this.isPlainObject(sort) ? { ...sort } : {},
onProgress: async progress => {
const safeProgress = this.isPlainObject(progress) ? progress : {};
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: safeProgress.status || 'running',
progress: safeProgress.progress,
current_count: safeProgress.currentCount,
total_count: safeProgress.totalCount,
message: safeProgress.message || '导出任务执行中',
result: safeProgress.result || null,
error: '',
});
},
});
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'success',
progress: 100,
current_count: result.current_count || 0,
total_count: result.total_count || 0,
message: '导出任务完成',
result,
error: '',
});
} catch (error) {
const errorMessage = error && error.message ? error.message : `${error}`;
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'failed',
progress: 100,
message: '导出任务失败',
result: null,
error: errorMessage,
});
}
});
return this.success('ok', {
...taskPayload,
update_time: Date.now(),
});
}
/**
* 查询订单导出任务进度。
* @param {Object} data 请求体。
* @param {string} [data.task_id] 任务ID(下划线写法)。
* @param {string} [data.taskId] 任务ID(驼峰写法)。
* @return {Promise<Object>} 统一成功包装响应。
*/
async exportTaskProgress(data = {}) {
const taskId = this.normalizeExportTaskId(data);
if (!taskId) {
return this.success('ok', {
task_id: '',
status: 'not_found',
progress: 0,
current_count: 0,
total_count: 0,
message: '任务不存在',
result: null,
error: '',
download_url: '',
update_time: Date.now(),
});
}
const cachedTask = await this.getExportTaskProgress(taskId);
if (!cachedTask) {
return this.success('ok', {
task_id: taskId,
status: 'not_found',
progress: 0,
current_count: 0,
total_count: 0,
message: '任务不存在',
result: null,
error: '',
download_url: '',
update_time: Date.now(),
});
}
const safeResult = this.isPlainObject(cachedTask.result) ? cachedTask.result : {};
const downloadUrl = String(
safeResult.url
|| safeResult.cndUrl
|| safeResult.cdnUrl
|| safeResult.cosUrl
|| safeResult.fileKey
|| ''
);
return this.success('ok', {
task_id: taskId,
...cachedTask,
download_url: downloadUrl,
});
}
/**
* 生成订单导出任务ID。
* @return {string} 任务ID。
*/
generateExportTaskId() {
const warehouseId = this.ctx?.user?.store_id || 'unknown';
const timestamp = Date.now();
const randomToken = Math.random().toString(36).slice(2, 10);
return `order_export_${warehouseId}_${timestamp}_${randomToken}`;
}
/**
* 规范导出任务ID。
* @param {Object} data 请求体。
* @param {string} [data.task_id] 任务ID。
* @param {string} [data.taskId] 任务ID。
* @return {string} 规范后的任务ID。
*/
normalizeExportTaskId(data = {}) {
const normalizedData = this.isPlainObject(data) ? data : {};
return String(normalizedData.task_id || normalizedData.taskId || '').trim();
}
/**
* 获取订单导出任务缓存键。
* @param {string} taskId 任务ID。
* @return {string} 缓存键。
*/
getExportTaskCacheKey(taskId = '') {
const normalizedTaskId = String(taskId || '').trim();
if (!normalizedTaskId) {
return '';
}
return `${ORDER_EXPORT_TASK_CACHE_KEY_PREFIX}${normalizedTaskId}`;
}
/**
* 写入订单导出任务进度缓存。
* @param {string} taskId 任务ID。
* @param {Object} payload 任务状态。
* @return {Promise<void>} 无返回值。
*/
async setExportTaskProgress(taskId = '', payload = {}) {
const cacheKey = this.getExportTaskCacheKey(taskId);
if (!cacheKey || typeof this.app.setCacheAsync !== 'function') {
return;
}
const safePayload = this.isPlainObject(payload) ? payload : {};
const normalizeCount = value => {
const numericValue = Number(value);
return Number.isFinite(numericValue) && numericValue >= 0 ? Math.round(numericValue) : 0;
};
const progressPayload = {
task_id: String(taskId || '').trim(),
status: String(safePayload.status || 'submitted').trim() || 'submitted',
progress: Number.isFinite(Number(safePayload.progress)) ? Math.min(100, Math.max(0, Math.round(Number(safePayload.progress)))) : 0,
current_count: normalizeCount(safePayload.current_count),
total_count: normalizeCount(safePayload.total_count),
message: String(safePayload.message || ''),
result: safePayload.result ?? null,
error: String(safePayload.error || ''),
update_time: Date.now(),
};
try {
await this.app.setCacheAsync(cacheKey, progressPayload, ORDER_EXPORT_TASK_CACHE_TTL_SECONDS);
} catch (error) {
const errorMessage = error && error.message ? error.message : `${error}`;
this.ctx.logger.warn(`[order.export] 写入导出任务缓存失败: ${errorMessage}`);
}
}
/**
* 读取订单导出任务进度缓存。
* @param {string} taskId 任务ID。
* @return {Promise<Object|null>} 任务缓存。
*/
async getExportTaskProgress(taskId = '') {
const cacheKey = this.getExportTaskCacheKey(taskId);
if (!cacheKey || typeof this.app.getCacheAsync !== 'function') {
return null;
}
try {
const cached = await this.app.getCacheAsync(cacheKey);
if (!this.isPlainObject(cached)) {
return null;
}
return cached;
} catch (error) {
const errorMessage = error && error.message ? error.message : `${error}`;
this.ctx.logger.warn(`[order.export] 读取导出任务缓存失败: ${errorMessage}`);
return null;
}
}
/**
* 订单工作台总列表入口。
* @param {Object} data 请求体。
* @return {Promise<Object>} 列表与分页信息。
*/
async list(data = {}) {
return await this.listByModule('order', data);
}
/**
* 手动出库入口。
* @param {Object} data 请求体。
* @return {Promise<Object>} 迁移结果。
*/
async manualOutboundOrder(data = {}) {
return await this.ctx.service.systems.orderDeliveryMigration.syncOutboundOrdersToDelivery(data);
}
/**
* 获取订单工作台 8 个标签页的角标计数。
* 其中配送、异常与归档相关标签页直接返回 99+。
* @return {Promise<Object>} 角标展示值对象。
*/
async badgeCount() {
const warehouseId = this.getWarehouseId();
if (warehouseId === null || warehouseId === undefined || warehouseId === '') {
throw new Error('缺少当前用户仓库上下文 store_id');
}
const cacheKey = this.getBadgeCountCacheKey(warehouseId);
const cachedBadgeCount = await this.app.getCacheAsync(cacheKey);
if (cachedBadgeCount && typeof cachedBadgeCount === 'object') {
return cachedBadgeCount;
}
const [ reviewOrder, pendingOrder, outboundOrder, expectionOrder, entrustOrder ] = await Promise.all([
this.getBadgeCountByModule('reviewOrder', warehouseId),
this.getBadgeCountByModule('pendingOrder', warehouseId),
this.getBadgeCountByModule('outboundOrder', warehouseId),
this.getBadgeCountByModule('expectionOrder', warehouseId),
this.getBadgeCountByModule('entrustOrder', warehouseId),
]);
const badgeCount = {
reviewOrder,
pendingOrder,
outboundOrder,
expectionOrder,
entrustOrder,
deliveryOrder: '99+',
deliveryExpectionOrder: '99+',
archiveOrder: '99+',
};
await this.app.setCacheAsync(cacheKey, badgeCount, 30);
return badgeCount;
}
/**
* 查询订单操作日志。
* @param {Object} data 请求体。
* @param {string|number} data.id 订单ID。
* @param {number} [data.page] 页码。
* @param {number} [data.pageSize] 每页数量。
* @return {Promise<Object>} 统一 success 包装的分页结果。
*/
async queryOrderLogs(data = {}) {
const { ctx, service } = this;
const requestData = data && typeof data === 'object' ? data : {};
const { id, page, pageSize } = requestData;
try {
const result = await service.systems.operationLog.queryOrderLogs({
id,
page,
pageSize,
warehouseId: ctx.user.store_id,
});
return this.success('ok', {
data: result,
code: 200,
});
} catch (e) {
return this.success(e.message, {
code: 200,
});
}
}
/**
* 查询订单日志列表(不分页,返回全部)。
*
* 仅接受 order_id 及常见别名(id、orderId),
* 仓库范围固定使用当前登录用户 store_id,避免越仓读取。
*
* @param {Object} data 请求体。
* @param {string|number} [data.order_id] 订单ID。
* @param {string|number} [data.id] 订单ID别名。
* @param {string|number} [data.orderId] 订单ID别名。
* @return {Promise<Object>} 统一 success/fail 结构。
*/
async queryOrderLogList(data = {}) {
const { service } = this;
const requestData = this.isPlainObject(data) ? data : {};
const {
order_id: orderId,
id,
orderId: orderIdAlias,
} = requestData;
const rawOrderId = orderId ?? id ?? orderIdAlias;
if (rawOrderId === undefined || rawOrderId === null || String(rawOrderId).trim() === '') {
return this.fail('order_id 参数不能为空', {}, 400);
}
const normalizedOrderId = Number(String(rawOrderId).trim());
if (!Number.isFinite(normalizedOrderId) || normalizedOrderId <= 0) {
return this.fail('order_id 参数不合法', {}, 400);
}
const warehouseId = this.getWarehouseId();
if (warehouseId === null || warehouseId === undefined || warehouseId === '') {
return this.fail('缺少当前用户仓库上下文 store_id', {}, 400);
}
const logs = await service.systems.operationLog.queryAllOrderLogs({
id: normalizedOrderId,
warehouseId,
});
return this.success('ok', {
list: logs,
total: logs.length,
code: 200,
});
}
/**
* 更新订单运单的称重重量。
*
* 规则:
* - 单运单订单:忽略传入 waybill_code,直接更新唯一记录。
* - 多运单订单:必须传入 waybill_code 且匹配到订单下记录。
* - 团购波次(wave_type = 1):将同一重量批量设置到该波次下所有订单的运单上。
* - 运单号模式(order_id = 0):从运单号反查,必传 waybill_code。团购时按 wave_no + business_key 批量设置。
*
* @param {Object} data 请求体。
* @param {string} [data.waybill_code] 运单号,多运单场景或运单号模式必填。
* @param {number|string} data.order_id 订单ID,传 0 时切换为运单号模式。
* @param {number|string} data.weighing_weight 称重重量(g)。
* @return {Promise<Object>} 统一成功/失败结构。
* 订单模式单订单:{data: {order_id, waybill_code, weighing_weight}};
* 订单模式团购批量:{data: {wave_id, wave_no, weighing_weight, total_weight, split_count, splits, store_name, sys_logistics_name}};
* 运单号模式单运单:{data: {order_id, waybill_code, weighing_weight}};
* 运单号模式团购批量:{data: {wave_id, wave_no, business_key, weighing_weight, total_weight, split_count, splits, store_name, sys_logistics_name}}。
*/
async updateExpressWeighingWeight(data = {}) {
const requestData = this.isPlainObject(data) ? data : {};
const {
waybill_code: waybillCode = '',
order_id: orderId,
weighing_weight: weighingWeight,
} = requestData;
try {
let result;
if (Number(orderId) === 0) {
// 运单号模式:从运单号反查订单与波次
result = await this.service.systems.orderExpress.updateWeighingWeightByWaybill({
waybillCode,
weighingWeight,
});
} else {
// 订单模式
result = await this.service.systems.orderExpress.updateWeighingWeight({
orderId,
waybillCode,
weighingWeight,
});
}
return this.success('ok', {
data: result,
code: 200,
});
} catch (error) {
const errorCode = Number(error && error.code);
const statusCode = Number.isFinite(errorCode) && errorCode > 0 ? errorCode : 400;
return this.fail(error && error.message ? error.message : '更新称重重量失败', {
data: null,
}, statusCode);
}
}
/**
* 按订单号与运单号绑定包材。
*
* @param {Object} data 请求体。
* @param {string} data.waybill_code 运单号。
* @param {number|string} data.order_id 订单ID。
* @param {string} data.package_material_code 包材编码。
* @return {Promise<Object>} 统一成功/失败结构。
*/
async bindExpressPackageMaterial(data = {}) {
const requestData = this.isPlainObject(data) ? data : {};
const {
waybill_code: waybillCode = '',
order_id: orderId,
package_material_code: packageMaterialCode = '',
} = requestData;
try {
const result = await this.service.systems.orderExpress.bindExpressPackageMaterial({
orderId,
waybillCode,
packageMaterialCode,
});
return this.success('ok', {
data: result,
code: 200,
});
} catch (error) {
const errorCode = Number(error && error.code);
const statusCode = Number.isFinite(errorCode) && errorCode > 0 ? errorCode : 500;
return this.fail(error && error.message ? error.message : '绑定包材失败', {
data: null,
}, statusCode);
}
}
/**
* 根据运单号绑定包材。
*
* method 层仅负责参数解构、systems 转发与统一返回结构。
* 无需传入订单ID,仅凭运单号即可完成包材绑定。
*
* 支持团购波次自动感知:
* - 非团购订单:仅绑定当前运单的包材。
* - 团购波次(wave_type=1):自动将同一波次下、相同快递业务键(business_key)的
* 所有运单批量绑定相同的包材,实现一键补齐。
*
* @param {Object} data 请求体。
* @param {string} data.waybill_code 运单号。
* @param {number|string} data.package_material_id 包材ID。
* @return {Promise<Object>} 统一成功/失败结构。
* 单条绑定:data 含 {order_id, waybill_code, package_material_id, package_material_name_snapshot, package_material_code};
* 团购批量绑定:data 含 {wave_id, wave_no, business_key, order_id, waybill_code, package_material_id, package_material_code, package_material_name_snapshot, bind_count, bound_waybills, store_name, sys_logistics_name}。
*/
async bindExpressPackageMaterialByWaybill(data = {}) {
const requestData = this.isPlainObject(data) ? data : {};
const {
waybill_code: waybillCode = '',
package_material_id: packageMaterialId = '',
} = requestData;
try {
const result = await this.service.systems.orderExpress.bindExpressPackageMaterialByWaybill({
waybillCode,
packageMaterialId,
});
return this.success('ok', {
data: result,
code: 200,
});
} catch (error) {
const errorCode = Number(error && error.code);
const statusCode = Number.isFinite(errorCode) && errorCode > 0 ? errorCode : 500;
return this.fail(error && error.message ? error.message : '绑定包材失败', {
data: null,
}, statusCode);
}
}
/**
* 根据运单号拉取复核数据。
*
* method 层仅负责参数解构、systems 转发与统一返回结构。
*
* @param {Object} data 请求体。
* @param {string} data.waybill_code 运单号。
* @return {Promise<Object>} 统一成功/失败结构。
*/
async pullReviewDataByWaybill(data = {}) {
const requestData = this.isPlainObject(data) ? data : {};
const {
waybill_code: waybillCode = '',
} = requestData;
try {
const result = await this.service.systems.orderReview.pullReviewDataByWaybill({
waybillCode,
});
return this.success('ok', {
data: result,
code: 200,
});
} catch (error) {
const errorCode = Number(error && error.code);
const statusCode = Number.isFinite(errorCode) && errorCode > 0 ? errorCode : 500;
return this.fail(error && error.message ? error.message : '拉取复核数据失败', {
data: null,
}, statusCode);
}
}
}
module.exports = OrderIndexService;