1
This commit is contained in:
parent
34273c166b
commit
478ad2ab0d
18
_diag6.cjs
Normal file
18
_diag6.cjs
Normal file
@ -0,0 +1,18 @@
|
||||
'use strict';
|
||||
const { loadDeployConfig, quoteForBash, runSsh } = require('./script/deploy-lib.cjs');
|
||||
const config = loadDeployConfig('production');
|
||||
|
||||
const script = [
|
||||
'echo \"=== v2 完整 Model 配置(行70-100)===\"',
|
||||
'sed -n \"70,100p\" ' + quoteForBash(config.deployRoot + '/v2/app/model/inbound_direct_log.js'),
|
||||
'echo \"\"',
|
||||
'echo \"=== v2 完整 Model 配置(行95-120)===\"',
|
||||
'sed -n \"95,120p\" ' + quoteForBash(config.deployRoot + '/v2/app/model/inbound_direct_log.js'),
|
||||
'echo \"\"',
|
||||
'echo \"=== current.md 指向 ===\"',
|
||||
'cat ' + quoteForBash(config.deployRoot + '/current.md'),
|
||||
'echo \"\"',
|
||||
'echo \"=== nginx upstream 指向 ===\"',
|
||||
'cat ' + quoteForBash(config.deployRoot + '/nginx-upstream.conf'),
|
||||
].join('\n');
|
||||
console.log(runSsh(config, script, { stdio: 'pipe' }));
|
||||
@ -45,6 +45,21 @@ module.exports = app => {
|
||||
allowNull: true,
|
||||
comment: '入库单号(冗余,方便查询)',
|
||||
},
|
||||
entry_item_id: {
|
||||
type: BIGINT(20).UNSIGNED,
|
||||
allowNull: true,
|
||||
comment: '入库明细ID',
|
||||
},
|
||||
receiving_detail_id: {
|
||||
type: INTEGER,
|
||||
allowNull: true,
|
||||
comment: '收货明细ID,绑定收货时使用',
|
||||
},
|
||||
status: {
|
||||
type: ENUM('pending', 'committed', 'released'),
|
||||
allowNull: true,
|
||||
comment: '绑定状态:pending=待提交 committed=已提交 released=已释放,非绑定模式为NULL',
|
||||
},
|
||||
remark: {
|
||||
type: STRING(500),
|
||||
allowNull: true,
|
||||
@ -71,10 +86,24 @@ module.exports = app => {
|
||||
allowNull: false,
|
||||
comment: '创建时间',
|
||||
},
|
||||
updated_at: {
|
||||
type: DATE,
|
||||
allowNull: true,
|
||||
comment: '更新时间',
|
||||
},
|
||||
deleted_at: {
|
||||
type: DATE,
|
||||
allowNull: true,
|
||||
comment: '软删除时间',
|
||||
},
|
||||
}, {
|
||||
tableName: 'wms_inbound_direct_log',
|
||||
comment: '非收货单途径入库直接记录表(导入/PDA入库)',
|
||||
timestamps: false,
|
||||
timestamps: true,
|
||||
createdAt: 'created_at',
|
||||
updatedAt: 'updated_at',
|
||||
paranoid: true,
|
||||
deletedAt: 'deleted_at',
|
||||
indexes: [
|
||||
{
|
||||
name: 'idx_warehouse_id',
|
||||
@ -96,8 +125,42 @@ module.exports = app => {
|
||||
name: 'idx_created_at',
|
||||
fields: [ 'created_at' ],
|
||||
},
|
||||
{
|
||||
name: 'idx_entry_item_id',
|
||||
fields: [ 'entry_item_id' ],
|
||||
},
|
||||
{
|
||||
name: 'idx_receiving_detail_id',
|
||||
fields: [ 'receiving_detail_id' ],
|
||||
},
|
||||
{
|
||||
name: 'idx_status',
|
||||
fields: [ 'status' ],
|
||||
},
|
||||
{
|
||||
name: 'uk_entry_receiving_binding',
|
||||
unique: true,
|
||||
fields: [ 'entry_item_id', 'receiving_detail_id', 'status' ],
|
||||
},
|
||||
],
|
||||
});
|
||||
|
||||
// 关联关系
|
||||
InboundDirectLog.associate = function() {
|
||||
const { InboundDirectLog, EntryItems, ReceivingDetail } = app.model;
|
||||
|
||||
// 关联入库明细
|
||||
InboundDirectLog.belongsTo(EntryItems, {
|
||||
foreignKey: 'entry_item_id',
|
||||
as: 'entryItem',
|
||||
});
|
||||
|
||||
// 关联收货明细
|
||||
InboundDirectLog.belongsTo(ReceivingDetail, {
|
||||
foreignKey: 'receiving_detail_id',
|
||||
as: 'receivingDetail',
|
||||
});
|
||||
};
|
||||
|
||||
return InboundDirectLog;
|
||||
};
|
||||
|
||||
@ -1244,8 +1244,11 @@ class OrderBaseService extends MainService {
|
||||
order: [[ 'id', 'ASC' ]],
|
||||
raw: true,
|
||||
});
|
||||
const orderItemImagesByStockId = await this.getOrderItemImagesByStockIds(orderItems);
|
||||
const orderItemsWithImages = this.attachImagesToOrderItems(orderItems, orderItemImagesByStockId);
|
||||
|
||||
// 通过 getStockDetails(带缓存)批量查询 stock_warehouse 标准信息
|
||||
// 为 items 附加 image_url、barcodes、item_name 等标准字段
|
||||
const orderItemsWithStockInfo = await this.attachStockDetailsToOrderItems(orderItems, warehouseId);
|
||||
|
||||
const expresses = await this.getOrderExpressesByOrderId(orderId, order);
|
||||
const logs = await this.getOrderOperationLogs(orderId);
|
||||
|
||||
@ -1255,9 +1258,8 @@ class OrderBaseService extends MainService {
|
||||
: [];
|
||||
|
||||
return {
|
||||
order,
|
||||
detail: order,
|
||||
items: orderItemsWithImages,
|
||||
items: orderItemsWithStockInfo,
|
||||
expresses,
|
||||
waybill_codes: waybillCodes,
|
||||
logs,
|
||||
@ -1265,93 +1267,205 @@ class OrderBaseService extends MainService {
|
||||
}
|
||||
|
||||
/**
|
||||
* 按订单商品批量查询图片并按 stock_id 建立映射。
|
||||
* 通过 stock_warehouse 带缓存的标准方法(getStockDetails),批量查询商品详情,
|
||||
* 将 order_items 仅作为 stock_id 来源,返回 getStockDetails 标准格式数据。
|
||||
* 每个结果会附带以下 order_items 关键关联字段:
|
||||
* - plan_qty:需求量
|
||||
* - order_line_no:行号
|
||||
* - stock_id:原 order_items 中的 stock_id 关联键
|
||||
* - order_item_id:原 order_items 主键 id,供下游(如 pendingOrder)关联使用
|
||||
* - order_id:所属订单 id
|
||||
*
|
||||
* @param {Object[]} orderItems 订单商品列表。
|
||||
* @return {Promise<Map<number, string[]>>} stock_id 对应的图片 URL 列表。
|
||||
* @param {number|string} warehouseId 仓库ID。
|
||||
* @return {Promise<Object[]>} 以 stock_warehouse 标准格式为主,附带少量 order_items 关键字段的数据。
|
||||
*/
|
||||
async getOrderItemImagesByStockIds(orderItems = []) {
|
||||
async attachStockDetailsToOrderItems(orderItems = [], warehouseId) {
|
||||
if (!Array.isArray(orderItems) || orderItems.length === 0) {
|
||||
return new Map();
|
||||
}
|
||||
|
||||
const stockIds = [ ...new Set(
|
||||
orderItems
|
||||
.map(item => Number(item && item.stock_id))
|
||||
.filter(Boolean)
|
||||
) ];
|
||||
|
||||
if (stockIds.length === 0) {
|
||||
return new Map();
|
||||
}
|
||||
|
||||
const fileReferenceModel = this.ctx.model && this.ctx.model.FileReference;
|
||||
const fileModel = this.ctx.model && this.ctx.model.File;
|
||||
if (!fileReferenceModel || typeof fileReferenceModel.findAll !== 'function' || !fileModel) {
|
||||
return new Map();
|
||||
}
|
||||
|
||||
try {
|
||||
const fileReferences = await fileReferenceModel.findAll({
|
||||
where: {
|
||||
business_type: 'stock',
|
||||
business_id: {
|
||||
[this.app.Sequelize.Op.in]: stockIds,
|
||||
},
|
||||
},
|
||||
include: [{
|
||||
model: fileModel,
|
||||
as: 'file',
|
||||
attributes: [ 'file_url' ],
|
||||
required: false,
|
||||
}],
|
||||
});
|
||||
|
||||
const imagesByStockId = new Map();
|
||||
for (const reference of fileReferences || []) {
|
||||
const row = reference && typeof reference.get === 'function'
|
||||
? reference.get({ plain: true })
|
||||
: reference;
|
||||
const stockId = Number(row && row.business_id);
|
||||
const imageUrl = (row && row.file && row.file.file_url) || row?.file_url || row?.url || row?.file_path || '';
|
||||
|
||||
if (!stockId || !imageUrl) {
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!imagesByStockId.has(stockId)) {
|
||||
imagesByStockId.set(stockId, []);
|
||||
}
|
||||
|
||||
imagesByStockId.get(stockId).push(String(imageUrl));
|
||||
}
|
||||
|
||||
return imagesByStockId;
|
||||
} catch (error) {
|
||||
this.ctx.logger?.warn?.('[order.base.detail] 查询订单商品图片失败,已降级为空图片数组', {
|
||||
error: error.message,
|
||||
});
|
||||
return new Map();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 将图片映射合并到订单商品列表中。
|
||||
* @param {Object[]} orderItems 订单商品列表。
|
||||
* @param {Map<number, string[]>} imagesByStockId 图片映射。
|
||||
* @return {Object[]} 合并后的订单商品列表。
|
||||
*/
|
||||
attachImagesToOrderItems(orderItems = [], imagesByStockId = new Map()) {
|
||||
if (!Array.isArray(orderItems)) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return orderItems.map(item => {
|
||||
// 构建 stockId → orderItem 关键字段的映射
|
||||
const stockIdToOrderItemMap = new Map();
|
||||
const stockIdsSet = new Set();
|
||||
for (const item of orderItems) {
|
||||
const stockId = Number(item && item.stock_id);
|
||||
const images = stockId ? (imagesByStockId.get(stockId) || []) : [];
|
||||
if (stockId) {
|
||||
stockIdsSet.add(stockId);
|
||||
// 同一个 stock_id 可能对应多条 order_items 行,保留最后一条的关键字段
|
||||
stockIdToOrderItemMap.set(stockId, {
|
||||
plan_qty: item.plan_qty != null ? item.plan_qty : 0,
|
||||
order_line_no: item.order_line_no || '',
|
||||
stock_id: stockId,
|
||||
order_item_id: item.id != null ? item.id : 0,
|
||||
order_id: item.order_id != null ? item.order_id : 0,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
const stockIds = [ ...stockIdsSet ];
|
||||
|
||||
if (stockIds.length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
/** @type {Map<number, Object>} */
|
||||
const stockDetailMap = new Map();
|
||||
try {
|
||||
const stockWarehouseSvc = this.ctx.service?.systems?.stockWarehouse;
|
||||
if (stockWarehouseSvc && typeof stockWarehouseSvc.getStockDetails === 'function') {
|
||||
const stockDetails = await stockWarehouseSvc.getStockDetails(stockIds, { warehouseId });
|
||||
for (const detail of stockDetails) {
|
||||
stockDetailMap.set(Number(detail.id), detail);
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
this.ctx.logger?.warn?.('[order.base.attachStockDetailsToOrderItems] 查询 stock_warehouse 详情失败,已降级为原始 items', {
|
||||
error: error.message,
|
||||
});
|
||||
return [];
|
||||
}
|
||||
|
||||
// 降级:当 getStockDetails 缓存层没有返回某些 stockId 的数据时,直接查 DB 补齐
|
||||
const missedIds = stockIds.filter(sid => !stockDetailMap.has(sid));
|
||||
if (missedIds.length > 0) {
|
||||
this.ctx.logger?.info?.('[order.base.attachStockDetailsToOrderItems] getStockDetails 未返回部分 stock 详情,降级为直接查 DB', {
|
||||
missedIds,
|
||||
warehouseId,
|
||||
});
|
||||
try {
|
||||
const { app } = this;
|
||||
const [ fallbackStockRows, fallbackBarcodeRows, fallbackImageRows ] = await Promise.all([
|
||||
app.model.StockWarehouse.findAll({
|
||||
where: { id: { [app.Sequelize.Op.in]: missedIds }, is_valid: 'Y' },
|
||||
attributes: [
|
||||
'id', 'item_code', 'item_name', 'sku_property',
|
||||
'quantity', 'locked_quantity', 'is_batch_mgmt',
|
||||
'is_shelf_life_mgmt', 'is_images',
|
||||
'store_id', 'packing_requirements', 'stock_unit',
|
||||
],
|
||||
raw: true,
|
||||
}),
|
||||
app.model.StockBarcode.findAll({
|
||||
where: { stock_id: { [app.Sequelize.Op.in]: missedIds } },
|
||||
attributes: [ 'id', 'barcode', 'stock_id' ],
|
||||
raw: true,
|
||||
}),
|
||||
app.model.FileReference.findAll({
|
||||
where: {
|
||||
business_type: 'stock',
|
||||
business_id: { [app.Sequelize.Op.in]: missedIds.map(String) },
|
||||
},
|
||||
include: [{
|
||||
model: app.model.File,
|
||||
as: 'file',
|
||||
attributes: [ 'file_url' ],
|
||||
required: false,
|
||||
}],
|
||||
order: [[ 'display_order', 'ASC' ]],
|
||||
raw: true,
|
||||
}),
|
||||
]);
|
||||
|
||||
const fallbackBarcodeMap = new Map();
|
||||
for (const row of fallbackBarcodeRows) {
|
||||
const sid = row.stock_id;
|
||||
if (!fallbackBarcodeMap.has(sid)) {
|
||||
fallbackBarcodeMap.set(sid, []);
|
||||
}
|
||||
fallbackBarcodeMap.get(sid).push({
|
||||
id: row.id,
|
||||
barcode: row.barcode,
|
||||
});
|
||||
}
|
||||
|
||||
const fallbackImageUrlMap = new Map();
|
||||
for (const row of fallbackImageRows) {
|
||||
const sid = Number(row.business_id);
|
||||
if (!fallbackImageUrlMap.has(sid)) {
|
||||
fallbackImageUrlMap.set(sid, []);
|
||||
}
|
||||
const url = (row['file.file_url'] && String(row['file.file_url']).trim()) || '';
|
||||
if (url) {
|
||||
fallbackImageUrlMap.get(sid).push(url);
|
||||
}
|
||||
}
|
||||
|
||||
for (const row of fallbackStockRows) {
|
||||
stockDetailMap.set(row.id, {
|
||||
id: row.id,
|
||||
item_code: row.item_code,
|
||||
item_name: row.item_name,
|
||||
sku_property: row.sku_property || '',
|
||||
quantity: row.quantity || 0,
|
||||
locked_quantity: row.locked_quantity || 0,
|
||||
is_batch_mgmt: row.is_batch_mgmt || 'N',
|
||||
is_shelf_life_mgmt: row.is_shelf_life_mgmt || 'N',
|
||||
is_images: row.is_images || 'N',
|
||||
store_id: row.store_id != null ? Number(row.store_id) : 0,
|
||||
packing_requirements: row.packing_requirements || '',
|
||||
stock_unit: row.stock_unit || '',
|
||||
image_url: fallbackImageUrlMap.get(row.id) || [],
|
||||
barcodes: fallbackBarcodeMap.get(row.id) || [],
|
||||
});
|
||||
}
|
||||
} catch (fallbackError) {
|
||||
this.ctx.logger?.warn?.('[order.base.attachStockDetailsToOrderItems] 降级查询也失败', {
|
||||
error: fallbackError.message,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// 以 getStockDetails 返回的标准格式为主,
|
||||
// 仅从 order_items 中附加 plan_qty、order_line_no、stock_id、order_item_id、order_id 关键关联字段
|
||||
return stockIds.map(stockId => {
|
||||
const stockDetail = stockDetailMap.get(stockId) || null;
|
||||
const orderItemFields = stockIdToOrderItemMap.get(stockId) || {};
|
||||
|
||||
if (!stockDetail) {
|
||||
return {
|
||||
id: stockId,
|
||||
item_code: '',
|
||||
item_name: '',
|
||||
sku_property: '',
|
||||
quantity: 0,
|
||||
locked_quantity: 0,
|
||||
is_batch_mgmt: 'N',
|
||||
is_shelf_life_mgmt: 'N',
|
||||
is_images: 'N',
|
||||
store_id: 0,
|
||||
packing_requirements: '',
|
||||
stock_unit: '',
|
||||
image_url: [],
|
||||
barcodes: [],
|
||||
plan_qty: orderItemFields.plan_qty || 0,
|
||||
order_line_no: orderItemFields.order_line_no || '',
|
||||
stock_id: orderItemFields.stock_id || stockId,
|
||||
order_item_id: orderItemFields.order_item_id || 0,
|
||||
order_id: orderItemFields.order_id || 0,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
...item,
|
||||
images: [ ...images ],
|
||||
id: stockDetail.id,
|
||||
item_code: stockDetail.item_code || '',
|
||||
item_name: stockDetail.item_name || '',
|
||||
sku_property: stockDetail.sku_property || '',
|
||||
quantity: stockDetail.quantity != null ? stockDetail.quantity : 0,
|
||||
locked_quantity: stockDetail.locked_quantity != null ? stockDetail.locked_quantity : 0,
|
||||
is_batch_mgmt: stockDetail.is_batch_mgmt || 'N',
|
||||
is_shelf_life_mgmt: stockDetail.is_shelf_life_mgmt || 'N',
|
||||
is_images: stockDetail.is_images || 'N',
|
||||
store_id: stockDetail.store_id != null ? Number(stockDetail.store_id) : 0,
|
||||
packing_requirements: stockDetail.packing_requirements || '',
|
||||
stock_unit: stockDetail.stock_unit || '',
|
||||
image_url: Array.isArray(stockDetail.image_url) ? [ ...stockDetail.image_url ] : [],
|
||||
barcodes: Array.isArray(stockDetail.barcodes) ? [ ...stockDetail.barcodes ] : [],
|
||||
plan_qty: orderItemFields.plan_qty || 0,
|
||||
order_line_no: orderItemFields.order_line_no || '',
|
||||
stock_id: orderItemFields.stock_id || stockId,
|
||||
order_item_id: orderItemFields.order_item_id || 0,
|
||||
order_id: orderItemFields.order_id || 0,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
@ -564,30 +564,26 @@ class PendingOrderService extends OrderBaseService {
|
||||
order: [[ 'id', 'ASC' ]],
|
||||
raw: true,
|
||||
});
|
||||
const orderItemImagesByStockId = await this.getOrderItemImagesByStockIds(orderItems);
|
||||
const orderItemsWithImages = this.attachImagesToOrderItems(orderItems, orderItemImagesByStockId);
|
||||
|
||||
// 收集订单明细中的 stock_id,用于查询商品库存主表信息
|
||||
const stockIds = [ ...new Set(
|
||||
orderItems.map(item => Number(item && item.stock_id)).filter(Boolean)
|
||||
) ];
|
||||
const stockMap = new Map();
|
||||
if (stockIds.length > 0) {
|
||||
const stockDetails = await this.ctx.service.systems.stockWarehouse.getStockDetails(
|
||||
stockIds,
|
||||
{ warehouseId }
|
||||
);
|
||||
for (const detail of stockDetails) {
|
||||
stockMap.set(detail.id, detail);
|
||||
}
|
||||
}
|
||||
// 通过 getStockDetails(带缓存)批量查询 stock_warehouse 标准信息
|
||||
// 返回以 stock_warehouse 格式为主、附带 plan_qty / order_line_no / stock_id / order_item_id / order_id 的数据
|
||||
const orderItemsWithImages = await this.attachStockDetailsToOrderItems(orderItems, warehouseId);
|
||||
|
||||
// 构建 order_item_id → orderItem 的快速查找映射
|
||||
// 构建 order_item_id → orderItem 的快速查找映射(仍基于原始 order_items)
|
||||
const orderItemMap = new Map();
|
||||
for (const item of orderItems) {
|
||||
orderItemMap.set(item.id, item);
|
||||
}
|
||||
|
||||
// 构建 stockMap:直接从 attachStockDetailsToOrderItems(已是 stock_warehouse 格式)中按 stock_id 建立映射
|
||||
const stockMap = new Map();
|
||||
for (const item of orderItemsWithImages) {
|
||||
const stockId = Number(item.stock_id);
|
||||
if (stockId) {
|
||||
stockMap.set(stockId, item);
|
||||
}
|
||||
}
|
||||
|
||||
// 查询已分配的储位信息(排除已取消的分配记录)
|
||||
const orderItemIds = orderItems.map(item => item.id).filter(Boolean);
|
||||
const pickingMap = new Map();
|
||||
@ -642,7 +638,7 @@ class PendingOrderService extends OrderBaseService {
|
||||
}
|
||||
const orderItemsWithPicking = orderItemsWithImages.map(item => ({
|
||||
...item,
|
||||
picking_locations: pickingMap.get(item.id) || [],
|
||||
picking_locations: pickingMap.get(item.order_item_id) || [],
|
||||
}));
|
||||
|
||||
const expresses = await this.getOrderExpressesByOrderId(orderId, order);
|
||||
|
||||
@ -1,71 +0,0 @@
|
||||
'use strict';
|
||||
const MainService = require('../../main');
|
||||
/**
|
||||
* 系统方法层:storage.directInbound(导入/PDA直接入库相关接口包装层)。
|
||||
* 主要职责:统一包装系统方法接口,处理权限、日志等公共逻辑,调用底层 service 实现业务功能。
|
||||
*/
|
||||
class DirectInboundService extends MainService {
|
||||
constructor(ctx) {
|
||||
super(ctx);
|
||||
const _noNeedLogin = '';
|
||||
const _noNeedRight = 'getItems,addItem,removeItem,commit';
|
||||
const _noNeedLog = 'getItems';
|
||||
const _noNeedAuth = 'getItems,addItem,removeItem,commit';
|
||||
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取入库单的导入/PDA 入库信息。
|
||||
* @param {Object} data 请求体
|
||||
* @param {string} data.entry_order_code 入库单号
|
||||
* @return {Promise<Object>} 统一成功包装响应
|
||||
*/
|
||||
async getItems(data = {}) {
|
||||
const { service } = this;
|
||||
const { entry_order_code } = data || {};
|
||||
const result = await service.systems.inboundDirectLog.getItems(entry_order_code);
|
||||
return this.success('ok', result);
|
||||
}
|
||||
|
||||
/**
|
||||
* 按商品增量添加导入/PDA 入库记录。
|
||||
* @param {Object} data 请求体
|
||||
* @param {number} data.entry_order_id 入库单 ID
|
||||
* @param {number} data.stock_id 商品SKU ID
|
||||
* @param {number} data.quantity 入库数量
|
||||
* @param {string} data.inbound_type 入库方式:import 或 pda
|
||||
* @param {string} [data.remark] 备注
|
||||
* @return {Promise<Object>} 统一成功包装响应
|
||||
*/
|
||||
async addItem(data = {}) {
|
||||
const { service } = this;
|
||||
const result = await service.systems.inboundDirectLog.addItem(data);
|
||||
return this.success('ok', result);
|
||||
}
|
||||
|
||||
/**
|
||||
* 提交确认完成导入/PDA 入库,写入库存并触发奇门/API 回传。
|
||||
* @param {Object} data 请求体
|
||||
* @param {number} data.entry_order_id 入库单 ID
|
||||
* @return {Promise<Object>} 统一成功包装响应
|
||||
*/
|
||||
async commit(data = {}) {
|
||||
const { service } = this;
|
||||
const { entry_order_id } = data || {};
|
||||
const result = await service.systems.inboundDirectLog.commit(entry_order_id);
|
||||
return this.success('ok', result);
|
||||
}
|
||||
|
||||
/**
|
||||
* 移除一条导入/PDA 入库记录。
|
||||
* @param {Object} data 请求体
|
||||
* @param {number} data.id 入库记录ID
|
||||
* @return {Promise<Object>} 统一成功包装响应
|
||||
*/
|
||||
async removeItem(data = {}) {
|
||||
const { service } = this;
|
||||
const result = await service.systems.inboundDirectLog.removeItem(data);
|
||||
return this.success('ok', result);
|
||||
}
|
||||
}
|
||||
module.exports = DirectInboundService;
|
||||
@ -38,10 +38,9 @@ class entryService extends MainService {
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询入库单详情。
|
||||
* 查询入库单详情。仅通过入库单 ID 定位。
|
||||
* @param {Object} data 请求体
|
||||
* @param {number} [data.id] 入库单ID
|
||||
* @param {string} [data.entry_order_code] 入库单号
|
||||
* @param {number} data.id 入库单ID(必填)
|
||||
* @return {Promise<Object>} 统一 success 包装
|
||||
*/
|
||||
async get(data = {}) {
|
||||
@ -64,19 +63,6 @@ class entryService extends MainService {
|
||||
return this.success('ok', result);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取入库单的导入/PDA 直接入库信息(从 storage.entry 模块暴露)。
|
||||
* @param {Object} data 请求体
|
||||
* @param {string} data.entry_order_code 入库单号
|
||||
* @return {Promise<Object>} 统一 success 包装
|
||||
*/
|
||||
async getDirectInboundItems(data = {}) {
|
||||
const { service } = this;
|
||||
const { entry_order_code } = data || {};
|
||||
const result = await service.systems.inboundDirectLog.getItems(entry_order_code);
|
||||
return this.success('ok', result);
|
||||
}
|
||||
|
||||
/**
|
||||
* 按商品增量添加导入/PDA 直接入库记录(从 storage.entry 模块暴露)。
|
||||
* @param {Object} data 请求体
|
||||
|
||||
@ -15,27 +15,21 @@ class InboundDirectLogService extends Service {
|
||||
/**
|
||||
* 获取入库单的受控入库信息(精简版)。
|
||||
* 返回入库单基本信息、明细列表(含计划数量与已完成数量)、收货单绑定关系。
|
||||
* @param {string} entryOrderCode 入库单号
|
||||
* @param {number} entryOrderId 入库单ID(必填)
|
||||
* @return {Promise<Object>} code/data/message 结构
|
||||
* - data.entryOrder: { id, entry_order_code, order_status, store_remask }
|
||||
* - data.items: [{ id, stock_id, planned, completed, stock, bindings }]
|
||||
* - data.receivingBindings: 收货单绑定关系列表
|
||||
*/
|
||||
async getItems(entryOrderCode) {
|
||||
async getItems(entryOrderId) {
|
||||
const { ctx, app } = this;
|
||||
const code = String(entryOrderCode || '').trim();
|
||||
const id = Number(entryOrderId || 0);
|
||||
|
||||
if (!code) {
|
||||
return { code: 400, message: 'entry_order_code 必填', data: null };
|
||||
if (!id) {
|
||||
return { code: 400, message: 'id 参数不能为空', data: null };
|
||||
}
|
||||
|
||||
const entryOrder = await ctx.model.EntryOrder.findOne({
|
||||
where: {
|
||||
entry_order_code: code,
|
||||
warehouse_id: ctx.user.store_id,
|
||||
is_enabled: 1,
|
||||
deleted_at: null,
|
||||
},
|
||||
const entryOrder = await ctx.model.EntryOrder.findByPk(id, {
|
||||
include: [
|
||||
{
|
||||
model: ctx.model.EntryItems,
|
||||
@ -67,6 +61,11 @@ class InboundDirectLogService extends Service {
|
||||
});
|
||||
|
||||
if (!entryOrder) {
|
||||
return { code: 404, message: '入库单不存在', data: null };
|
||||
}
|
||||
|
||||
// 校验仓库权限
|
||||
if (entryOrder.warehouse_id !== ctx.user.store_id || !entryOrder.is_enabled) {
|
||||
return { code: 404, message: '入库单不存在或无权访问', data: null };
|
||||
}
|
||||
|
||||
@ -171,13 +170,14 @@ class InboundDirectLogService extends Service {
|
||||
/** @type {Map<number, Array<Object>>} 按 entry_item_id 分组 */
|
||||
const bindingsMap = new Map();
|
||||
if (entryItemIds.length > 0) {
|
||||
// 1. 查绑定关系表
|
||||
const bindingRows = await ctx.model.EntryReceivingBinding.findAll({
|
||||
// 1. 查绑定关系表(从 InboundDirectLog 中筛选有 receiving_detail_id 的记录)
|
||||
const bindingRows = await ctx.model.InboundDirectLog.findAll({
|
||||
where: {
|
||||
entry_item_id: { [app.Sequelize.Op.in]: entryItemIds },
|
||||
receiving_detail_id: { [app.Sequelize.Op.ne]: null },
|
||||
deleted_at: null,
|
||||
},
|
||||
attributes: [ 'id', 'entry_item_id', 'receiving_detail_id', 'allocated_quantity', 'status' ],
|
||||
attributes: [ 'id', 'entry_item_id', 'receiving_detail_id', 'quantity', 'status' ],
|
||||
raw: true,
|
||||
});
|
||||
|
||||
@ -205,7 +205,7 @@ class InboundDirectLogService extends Service {
|
||||
bindingsMap.get(key).push({
|
||||
detail_id: b.receiving_detail_id,
|
||||
binding_id: b.id,
|
||||
allocated_quantity: b.allocated_quantity || 0,
|
||||
allocated_quantity: b.quantity || 0,
|
||||
});
|
||||
}
|
||||
}
|
||||
@ -310,10 +310,10 @@ class InboundDirectLogService extends Service {
|
||||
return { ok: false, error: { code: 400, message: `收货明细的商品(system_product_id=${receivingDetail.system_product_id})与传入的 stock_id(${stockId})不匹配` } };
|
||||
}
|
||||
|
||||
// 查询该收货明细已被占用的数量(pending + committed)
|
||||
// 查询该收货明细已被占用的数量(pending + committed),从 InboundDirectLog 查
|
||||
const allocatedSum = await ctx.model.query(
|
||||
`SELECT COALESCE(SUM(allocated_quantity), 0) AS total
|
||||
FROM wms_entry_receiving_binding
|
||||
`SELECT COALESCE(SUM(quantity), 0) AS total
|
||||
FROM wms_inbound_direct_log
|
||||
WHERE receiving_detail_id = :rdId AND status IN ('pending', 'committed') AND deleted_at IS NULL`,
|
||||
{
|
||||
replacements: { rdId: receivingDetailId },
|
||||
@ -431,7 +431,7 @@ class InboundDirectLogService extends Service {
|
||||
|
||||
/**
|
||||
* 将入库直接记录绑定到收货单明细(预占模式,status='pending')。
|
||||
* 校验收货明细存在、未取消、可用数量足够后,写入 wms_entry_receiving_binding 并确保主表绑定存在。
|
||||
* 校验收货明细存在、未取消、可用数量足够后,写入 wms_inbound_direct_log 并确保主表绑定存在。
|
||||
* @param {Object} ctx Egg.js 上下文对象
|
||||
* @param {Object} entryOrder 入库单实例
|
||||
* @param {Object} item 入库项参数,包含 allocated_quantity、item_code 等可选字段
|
||||
@ -463,10 +463,10 @@ class InboundDirectLogService extends Service {
|
||||
return { error: `收货明细不存在(id=${receivingDetailId})` };
|
||||
}
|
||||
|
||||
// 2. 查询已占用(pending + committed)的分配量
|
||||
// 2. 查询已占用(pending + committed)的分配量,从 InboundDirectLog 查
|
||||
const allocatedSum = await ctx.model.query(
|
||||
`SELECT COALESCE(SUM(allocated_quantity), 0) AS total
|
||||
FROM wms_entry_receiving_binding
|
||||
`SELECT COALESCE(SUM(quantity), 0) AS total
|
||||
FROM wms_inbound_direct_log
|
||||
WHERE receiving_detail_id = :rdId AND status IN ('pending', 'committed') AND deleted_at IS NULL`,
|
||||
{
|
||||
replacements: { rdId: receivingDetailId },
|
||||
@ -493,13 +493,22 @@ class InboundDirectLogService extends Service {
|
||||
...(transaction ? { transaction } : {}),
|
||||
});
|
||||
|
||||
// 4. 写入绑定(status='pending',预占不提交)
|
||||
const binding = await ctx.model.EntryReceivingBinding.create({
|
||||
// 4. 写入绑定到 InboundDirectLog(status='pending',预占不提交)
|
||||
const binding = await ctx.model.InboundDirectLog.create({
|
||||
warehouse_id: entryOrder.warehouse_id,
|
||||
store_id: entryOrder.store_id,
|
||||
stock_id: stockId,
|
||||
quantity: allocatedQty,
|
||||
inbound_type: item.inbound_type || 'import',
|
||||
entry_order_id: entryOrder.id,
|
||||
entry_order_code: entryOrder.entry_order_code,
|
||||
entry_item_id: entryItem?.id || 0,
|
||||
receiving_detail_id: receivingDetailId,
|
||||
allocated_quantity: allocatedQty,
|
||||
space_id: item.space_id ? Number(item.space_id) : null,
|
||||
status: 'pending',
|
||||
creator_id: ctx.user?.id || 0,
|
||||
operator_id: ctx.user?.employees_id || ctx.user?.id || null,
|
||||
operator_name: ctx.user?.employees_name || '',
|
||||
}, transaction ? { transaction } : {});
|
||||
|
||||
return {
|
||||
@ -819,10 +828,15 @@ class InboundDirectLogService extends Service {
|
||||
try {
|
||||
const processedStockIds = new Set();
|
||||
|
||||
// 查询 pending 绑定:entry_item_id → 收货明细ID
|
||||
// 查询 pending 绑定:entry_item_id → 收货明细ID(从 InboundDirectLog 查)
|
||||
const entryItemIds = entryItems.map(ei => ei.id);
|
||||
const pendingBindings = await ctx.model.EntryReceivingBinding.findAll({
|
||||
where: { entry_item_id: entryItemIds, status: 'pending', deleted_at: null },
|
||||
const pendingBindings = await ctx.model.InboundDirectLog.findAll({
|
||||
where: {
|
||||
entry_item_id: { [app.Sequelize.Op.in]: entryItemIds },
|
||||
receiving_detail_id: { [app.Sequelize.Op.ne]: null },
|
||||
status: 'pending',
|
||||
deleted_at: null,
|
||||
},
|
||||
attributes: [ 'id', 'entry_item_id', 'receiving_detail_id' ],
|
||||
raw: true,
|
||||
});
|
||||
@ -1007,9 +1021,9 @@ class InboundDirectLogService extends Service {
|
||||
}, { transaction });
|
||||
}
|
||||
|
||||
// 将 pending 绑定升级为 committed
|
||||
// 将 pending 绑定升级为 committed(在 InboundDirectLog 中更新状态)
|
||||
if (pendingBindings.length > 0) {
|
||||
await ctx.model.EntryReceivingBinding.update(
|
||||
await ctx.model.InboundDirectLog.update(
|
||||
{ status: 'committed', updated_at: new Date() },
|
||||
{ where: { id: pendingBindings.map(b => b.id) }, transaction }
|
||||
);
|
||||
@ -1425,16 +1439,17 @@ class InboundDirectLogService extends Service {
|
||||
* @return {Promise<void>}
|
||||
*/
|
||||
async _syncReceivingStorageStatus({ entryItemIds, transaction }) {
|
||||
const { ctx } = this;
|
||||
const { ctx, app } = this;
|
||||
|
||||
// 查询所有 committed 状态的绑定记录
|
||||
const committedBindings = await ctx.model.EntryReceivingBinding.findAll({
|
||||
// 查询所有 committed 状态的绑定记录(从 InboundDirectLog 中筛选有 receiving_detail_id 的记录)
|
||||
const committedBindings = await ctx.model.InboundDirectLog.findAll({
|
||||
where: {
|
||||
entry_item_id: entryItemIds,
|
||||
entry_item_id: { [app.Sequelize.Op.in]: entryItemIds },
|
||||
receiving_detail_id: { [app.Sequelize.Op.ne]: null },
|
||||
status: 'committed',
|
||||
deleted_at: null,
|
||||
},
|
||||
attributes: [ 'receiving_detail_id', 'allocated_quantity' ],
|
||||
attributes: [ 'receiving_detail_id', 'quantity' ],
|
||||
raw: true,
|
||||
transaction,
|
||||
});
|
||||
@ -1443,11 +1458,11 @@ class InboundDirectLogService extends Service {
|
||||
return;
|
||||
}
|
||||
|
||||
// 按 receiving_detail_id 汇总 allocated_quantity
|
||||
// 按 receiving_detail_id 汇总 quantity
|
||||
const detailQuantityMap = new Map();
|
||||
for (const b of committedBindings) {
|
||||
const detailId = b.receiving_detail_id;
|
||||
const qty = Number(b.allocated_quantity) || 0;
|
||||
const qty = Number(b.quantity) || 0;
|
||||
detailQuantityMap.set(detailId, (detailQuantityMap.get(detailId) || 0) + qty);
|
||||
}
|
||||
|
||||
|
||||
@ -963,10 +963,10 @@ class ReceivingEntryMatchService extends Service {
|
||||
};
|
||||
}
|
||||
|
||||
// 3. 查已 committed 的分配量
|
||||
// 3. 查已 committed 的分配量(从 InboundDirectLog 查)
|
||||
const allocatedSum = await ctx.model.query(
|
||||
`SELECT COALESCE(SUM(allocated_quantity), 0) AS total
|
||||
FROM wms_entry_receiving_binding
|
||||
`SELECT COALESCE(SUM(quantity), 0) AS total
|
||||
FROM wms_inbound_direct_log
|
||||
WHERE receiving_detail_id = :rdId AND status = 'committed' AND deleted_at IS NULL`,
|
||||
{
|
||||
replacements: { rdId: receivingDetailId },
|
||||
@ -983,16 +983,34 @@ class ReceivingEntryMatchService extends Service {
|
||||
};
|
||||
}
|
||||
|
||||
// 4. 写入明细绑定
|
||||
await ctx.model.EntryReceivingBinding.create({
|
||||
// 4. 获取入库单信息以写入 InboundDirectLog
|
||||
const entryOrder = await ctx.model.EntryOrder.findByPk(entryOrderId, { transaction });
|
||||
if (!entryOrder) {
|
||||
throw {
|
||||
error_code: 'ENTRY_ORDER_NOT_FOUND',
|
||||
message: '入库单不存在',
|
||||
detail: { entry_order_id: entryOrderId },
|
||||
};
|
||||
}
|
||||
|
||||
// 5. 写入明细绑定到 InboundDirectLog
|
||||
await ctx.model.InboundDirectLog.create({
|
||||
warehouse_id: entryOrder.warehouse_id,
|
||||
store_id: entryOrder.store_id,
|
||||
stock_id: expectedSpId || 0,
|
||||
quantity: qty,
|
||||
inbound_type: 'import',
|
||||
entry_order_id: entryOrderId,
|
||||
entry_order_code: entryOrder.entry_order_code,
|
||||
entry_item_id: entryItemId,
|
||||
receiving_detail_id: receivingDetailId,
|
||||
allocated_quantity: qty,
|
||||
status: 'committed',
|
||||
creator_id: ctx.currentUser?.id || 0,
|
||||
operator_id: ctx.currentUser?.employees_id || ctx.currentUser?.id || null,
|
||||
operator_name: ctx.currentUser?.employees_name || '',
|
||||
}, { transaction });
|
||||
|
||||
// 5. 确保主级绑定存在
|
||||
// 6. 确保主级绑定存在
|
||||
await ctx.model.EntryOrderReceiving.findOrCreate({
|
||||
where: { entry_order_id: entryOrderId, receiving_id: lockedDetail[0].receiving_id },
|
||||
defaults: { entry_order_id: entryOrderId, receiving_id: lockedDetail[0].receiving_id },
|
||||
@ -1082,9 +1100,11 @@ class ReceivingEntryMatchService extends Service {
|
||||
continue;
|
||||
}
|
||||
|
||||
// 2b. 查明细绑定是否存在
|
||||
const detailBindings = await ctx.model.EntryReceivingBinding.findAll({
|
||||
// 2b. 查明细绑定是否存在(从 InboundDirectLog 查 receiving_detail_id 非空的记录)
|
||||
const detailBindings = await ctx.model.InboundDirectLog.findAll({
|
||||
where: {
|
||||
entry_order_id: entryOrderId,
|
||||
receiving_detail_id: { [ctx.app.Sequelize.Op.ne]: null },
|
||||
status: 'committed',
|
||||
deleted_at: null,
|
||||
},
|
||||
@ -1095,7 +1115,7 @@ class ReceivingEntryMatchService extends Service {
|
||||
attributes: [],
|
||||
where: { receiving_id: receivingId },
|
||||
}],
|
||||
attributes: [ 'id', 'receiving_detail_id', 'allocated_quantity' ],
|
||||
attributes: [ 'id', 'receiving_detail_id', 'quantity' ],
|
||||
});
|
||||
|
||||
if (detailBindings.length === 0) {
|
||||
|
||||
@ -503,34 +503,28 @@ class EntryService extends Service {
|
||||
/**
|
||||
* 查询入库单详情,含商品信息、条码、入库进度。
|
||||
* @param {Object} data 请求参数
|
||||
* @param {number} [data.id] 入库单主键 ID
|
||||
* @param {string} [data.entry_order_code] 入库单号
|
||||
* @param {number} data.id 入库单主键 ID(必填)
|
||||
* @return {Promise<Object>} code/data/message 结构,data.entryOrder 为扁平化后的入库单详情
|
||||
*/
|
||||
async get(data = {}) {
|
||||
const { ctx } = this;
|
||||
const id = Number(data.id || 0);
|
||||
const entryOrderCode = data.entry_order_code ? String(data.entry_order_code).trim() : '';
|
||||
const warehouseId = ctx.user.store_id;
|
||||
|
||||
if (!id && !entryOrderCode) {
|
||||
if (!id) {
|
||||
return {
|
||||
code: 400,
|
||||
message: 'id 或 entry_order_code 至少传一个',
|
||||
message: 'id 参数不能为空',
|
||||
data: null,
|
||||
};
|
||||
}
|
||||
|
||||
const where = {
|
||||
id,
|
||||
warehouse_id: warehouseId,
|
||||
is_enabled: 1,
|
||||
deleted_at: null,
|
||||
};
|
||||
if (id) {
|
||||
where.id = id;
|
||||
} else {
|
||||
where.entry_order_code = entryOrderCode;
|
||||
}
|
||||
|
||||
const entryOrder = await ctx.model.EntryOrder.findOne({
|
||||
where,
|
||||
@ -705,11 +699,11 @@ class EntryService extends Service {
|
||||
rd.system_product_id,
|
||||
r.receiving_number,
|
||||
rd.actual_quantity,
|
||||
COALESCE(SUM(erb.allocated_quantity), 0) AS allocated_quantity,
|
||||
rd.actual_quantity - COALESCE(SUM(erb.allocated_quantity), 0) AS available_quantity
|
||||
COALESCE(SUM(erb.quantity), 0) AS allocated_quantity,
|
||||
rd.actual_quantity - COALESCE(SUM(erb.quantity), 0) AS available_quantity
|
||||
FROM wms_receiving_detail rd
|
||||
INNER JOIN wms_receiving r ON r.id = rd.receiving_id AND r.is_deleted = false
|
||||
LEFT JOIN wms_entry_receiving_binding erb
|
||||
LEFT JOIN wms_inbound_direct_log erb
|
||||
ON erb.receiving_detail_id = rd.id
|
||||
AND erb.status = 'committed'
|
||||
AND erb.deleted_at IS NULL
|
||||
@ -987,15 +981,6 @@ class EntryService extends Service {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取入库单的导入/PDA 直接入库信息(转发到 inboundDirectLog)。
|
||||
* @param {string} entryOrderCode 入库单号
|
||||
* @return {Promise<Object>} code/data/message 结构
|
||||
*/
|
||||
async getDirectInboundItems(entryOrderCode) {
|
||||
const { ctx } = this;
|
||||
return await ctx.service.systems.inboundDirectLog.getItems(entryOrderCode);
|
||||
}
|
||||
|
||||
/**
|
||||
* 按商品增量添加导入/PDA 直接入库记录(转发到 inboundDirectLog)。
|
||||
@ -1084,8 +1069,8 @@ class EntryService extends Service {
|
||||
const usedMap = new Map();
|
||||
if (detailIds.length > 0) {
|
||||
const usedRows = await ctx.model.query(
|
||||
`SELECT receiving_detail_id, COALESCE(SUM(allocated_quantity), 0) AS used_qty
|
||||
FROM wms_entry_receiving_binding
|
||||
`SELECT receiving_detail_id, COALESCE(SUM(quantity), 0) AS used_qty
|
||||
FROM wms_inbound_direct_log
|
||||
WHERE receiving_detail_id IN (:ids)
|
||||
AND status IN ('pending', 'committed')
|
||||
AND deleted_at IS NULL
|
||||
@ -1170,9 +1155,9 @@ class EntryService extends Service {
|
||||
return { code: 200, message: 'ok', data: { list: [], total: 0 } };
|
||||
}
|
||||
|
||||
// 3. 排除已绑定的收货明细(wms_entry_receiving_binding 中有记录且未软删除)
|
||||
// 3. 排除已绑定的收货明细(wms_inbound_direct_log 中有记录且未软删除)
|
||||
const notBoundCondition = app.Sequelize.literal(
|
||||
'NOT EXISTS (SELECT 1 FROM wms_entry_receiving_binding erb WHERE erb.receiving_detail_id = wms_receiving_detail.id AND erb.deleted_at IS NULL)'
|
||||
'NOT EXISTS (SELECT 1 FROM wms_inbound_direct_log erb WHERE erb.receiving_detail_id = wms_receiving_detail.id AND erb.deleted_at IS NULL)'
|
||||
);
|
||||
|
||||
// 4. 查询指定商品的未绑定收货明细
|
||||
@ -1695,10 +1680,10 @@ class EntryService extends Service {
|
||||
const entryItemIds = entryItems.map(ei => ei.id);
|
||||
const allocatedMap = new Map();
|
||||
if (receivingDetailIds.length > 0 && entryItemIds.length > 0) {
|
||||
const bindingRows = await ctx.model.EntryReceivingBinding.findAll({
|
||||
const bindingRows = await ctx.model.InboundDirectLog.findAll({
|
||||
attributes: [
|
||||
'receiving_detail_id',
|
||||
[ app.Sequelize.fn('SUM', app.Sequelize.col('allocated_quantity')), 'total_allocated' ],
|
||||
[ app.Sequelize.fn('SUM', app.Sequelize.col('quantity')), 'total_allocated' ],
|
||||
],
|
||||
where: {
|
||||
entry_item_id: { [app.Sequelize.Op.in]: entryItemIds },
|
||||
|
||||
@ -218,10 +218,10 @@ class ReceivingService extends Service {
|
||||
|
||||
const committedByDetailId = {};
|
||||
if (detailIds.length > 0) {
|
||||
const bindingRows = await ctx.model.EntryReceivingBinding.findAll({
|
||||
const bindingRows = await ctx.model.InboundDirectLog.findAll({
|
||||
attributes: [
|
||||
'receiving_detail_id',
|
||||
[ Sequelize.fn('SUM', Sequelize.col('allocated_quantity')), 'committed_sum' ],
|
||||
[ Sequelize.fn('SUM', Sequelize.col('quantity')), 'committed_sum' ],
|
||||
],
|
||||
where: {
|
||||
receiving_detail_id: { [Op.in]: detailIds },
|
||||
@ -4416,9 +4416,9 @@ class ReceivingService extends Service {
|
||||
return { code: 0, message: '该入库单尚未关联收货单', data: null };
|
||||
}
|
||||
|
||||
// 排除已绑定的收货明细(wms_entry_receiving_binding 中有记录且未软删除)
|
||||
// 排除已绑定的收货明细(wms_inbound_direct_log 中有记录且未软删除)
|
||||
const notBoundCondition = app.Sequelize.literal(
|
||||
'NOT EXISTS (SELECT 1 FROM wms_entry_receiving_binding erb WHERE erb.receiving_detail_id = wms_receiving_detail.id AND erb.deleted_at IS NULL)'
|
||||
'NOT EXISTS (SELECT 1 FROM wms_inbound_direct_log erb WHERE erb.receiving_detail_id = wms_receiving_detail.id AND erb.deleted_at IS NULL)'
|
||||
);
|
||||
|
||||
// 3. 查出所有未绑定的收货明细(不再在 SQL 层做 barcode 模糊匹配)
|
||||
|
||||
@ -6,8 +6,9 @@
|
||||
* UNLOCK:取消分配储位解锁
|
||||
*/
|
||||
module.exports = {
|
||||
async up(db) {
|
||||
await db.query(`
|
||||
async up(queryInterface) {
|
||||
const { sequelize } = queryInterface;
|
||||
await sequelize.query(`
|
||||
ALTER TABLE wms_storage_transaction
|
||||
MODIFY COLUMN transaction_type ENUM(
|
||||
'INBOUND', 'OUTBOUND', 'TRANSFER_OUT', 'TRANSFER_IN', 'LOCK', 'UNLOCK'
|
||||
@ -15,8 +16,9 @@ module.exports = {
|
||||
`);
|
||||
},
|
||||
|
||||
async down(db) {
|
||||
await db.query(`
|
||||
async down(queryInterface) {
|
||||
const { sequelize } = queryInterface;
|
||||
await sequelize.query(`
|
||||
ALTER TABLE wms_storage_transaction
|
||||
MODIFY COLUMN transaction_type ENUM(
|
||||
'INBOUND', 'OUTBOUND', 'TRANSFER_OUT', 'TRANSFER_IN'
|
||||
|
||||
@ -1,310 +0,0 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* 入库单 A5 默认打印模板(ENTRY_ORDER 业务类型)。
|
||||
*
|
||||
* 严格参照出库单"拣货单A5模板"(id=18)的格式与渲染引擎约定:
|
||||
* - 标签元素(纯文字)使用 custom: true + content + 扁平化样式属性
|
||||
* - 数据元素使用 field_code(无 custom)+ 扁平化样式属性
|
||||
* - 分割线使用 line 类型
|
||||
* - 表格使用 table 类型,rows 数组每项为列定义对象(type: "text", field_code, content, width 等)
|
||||
* - 字体大小使用 fontSize(字符串类型,如 "10")
|
||||
* - 加粗使用 bold(布尔类型)
|
||||
* - textAlign 用于对齐
|
||||
*
|
||||
* 模板布局(A5 148mm×210mm):
|
||||
* 1. 标题:"入 库 单"(fontSize: 18, bold: true, textAlign: center)
|
||||
* 2. 分割线
|
||||
* 3. 信息区(标签+字段模式,每行左右两列):
|
||||
* 入库单号:entry_order_code | 业务类型:order_type
|
||||
* 供应商:supplier_name | 采购单号:purchase_order_code
|
||||
* 仓库:warehouse_name | 货主:store_name
|
||||
* 物流公司:logistics_name | 运单号:express_code
|
||||
* 创建时间:order_create_time | 预期到货:expect_start_time
|
||||
* 4. 分割线
|
||||
* 5. 入库明细标题
|
||||
* 6. 表格(6列):商品编码、商品名称、条码、计划数量、已收数量、库存类型
|
||||
* - 每列为 type: "text" 的扁平对象(参照 id=18 格式)
|
||||
* 7. 分割线
|
||||
* 8. 单据总行数:total_order_lines
|
||||
* 9. 备注:remark
|
||||
* 10. 二维码:entry_order_code
|
||||
* 11. 打印时间:print_time
|
||||
*/
|
||||
|
||||
const TABLE = 'wms_print_template';
|
||||
|
||||
// 基于时间戳生成唯一元素 ID 前缀
|
||||
const TS_BASE = Date.now();
|
||||
|
||||
/**
|
||||
* 生成模板元素唯一 ID。
|
||||
* @param {string} type 元素类型前缀(text/line/table/barcode/qrcode)
|
||||
* @param {number} seq 序号
|
||||
* @return {string} 唯一 ID
|
||||
*/
|
||||
function makeId(type, seq) {
|
||||
return `${type}_${TS_BASE}_${String(seq).padStart(4, '0')}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成 text 类型标签元素(纯文字标签,如"入库单号:"),有 custom: true。
|
||||
* @param {number} seq 序号
|
||||
* @param {number} top 顶部位置(mm)
|
||||
* @param {number} left 左侧位置(mm)
|
||||
* @param {number} width 宽度(mm)
|
||||
* @param {number} height 高度(mm)
|
||||
* @param {string} content 文字内容
|
||||
* @param {string} fontSize 字体大小(字符串类型)
|
||||
* @param {object} options 可选配置 { bold, textAlign }
|
||||
* @return {object} 标签元素
|
||||
*/
|
||||
function label(seq, top, left, width, height, content, fontSize, options = {}) {
|
||||
return {
|
||||
id: makeId('text', seq),
|
||||
type: 'text',
|
||||
top,
|
||||
left,
|
||||
width,
|
||||
height,
|
||||
custom: true,
|
||||
content,
|
||||
fontSize,
|
||||
bold: options.bold || false,
|
||||
italic: false,
|
||||
underline: false,
|
||||
rotate: 0,
|
||||
textAlign: options.textAlign || 'left',
|
||||
lineHeight: height,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成 text 类型数据字段元素(绑定 field_code),无 custom。
|
||||
* @param {number} seq 序号
|
||||
* @param {number} top 顶部位置(mm)
|
||||
* @param {number} left 左侧位置(mm)
|
||||
* @param {number} width 宽度(mm)
|
||||
* @param {number} height 高度(mm)
|
||||
* @param {string} fieldCode 字段编码
|
||||
* @param {string} fontSize 字体大小(字符串类型)
|
||||
* @param {object} options 可选配置 { bold, textAlign }
|
||||
* @return {object} 数据字段元素
|
||||
*/
|
||||
function field(seq, top, left, width, height, fieldCode, fontSize, options = {}) {
|
||||
return {
|
||||
id: makeId('text', seq),
|
||||
type: 'text',
|
||||
top,
|
||||
left,
|
||||
width,
|
||||
height,
|
||||
field_code: fieldCode,
|
||||
fontSize,
|
||||
bold: options.bold || false,
|
||||
italic: false,
|
||||
underline: false,
|
||||
rotate: 0,
|
||||
textAlign: options.textAlign || 'left',
|
||||
lineHeight: height,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成分割线元素。
|
||||
* @param {number} seq 序号
|
||||
* @param {number} top 顶部位置(mm)
|
||||
* @param {number} left 左侧位置(mm)
|
||||
* @param {number} width 宽度(mm)
|
||||
* @param {number} height 高度(mm)
|
||||
* @return {object} 分割线元素
|
||||
*/
|
||||
function lineEl(seq, top, left, width, height) {
|
||||
return {
|
||||
id: makeId('line', seq),
|
||||
type: 'line',
|
||||
top,
|
||||
left,
|
||||
width,
|
||||
height,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成二维码元素。
|
||||
* @param {number} seq 序号
|
||||
* @param {number} top 顶部位置(mm)
|
||||
* @param {number} left 左侧位置(mm)
|
||||
* @param {number} width 宽度(mm)
|
||||
* @param {number} height 高度(mm)
|
||||
* @param {string} fieldCode 字段编码
|
||||
* @param {string} fontSize 字体大小
|
||||
* @return {object} 二维码元素
|
||||
*/
|
||||
function qrcodeEl(seq, top, left, width, height, fieldCode, fontSize) {
|
||||
return {
|
||||
id: makeId('qrcode', seq),
|
||||
type: 'qrcode',
|
||||
top,
|
||||
left,
|
||||
width,
|
||||
height,
|
||||
field_code: fieldCode,
|
||||
fontSize,
|
||||
bold: false,
|
||||
italic: false,
|
||||
underline: false,
|
||||
rotate: 0,
|
||||
textAlign: 'center',
|
||||
lineHeight: 6,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成表格列定义(严格参照 id=18 rows 格式)。
|
||||
* 每项为 type: "text" 的扁平对象,同时包含 field_code、content(中文表头)、width、样式属性。
|
||||
* @param {number} seq 序号
|
||||
* @param {string} fieldCode 字段编码
|
||||
* @param {string} content 中文表头内容
|
||||
* @param {number} colWidth 列宽(mm)
|
||||
* @param {string} fontSize 字体大小
|
||||
* @param {boolean} bold 是否加粗
|
||||
* @param {string} textAlign 对齐方式
|
||||
* @return {object} 列定义对象
|
||||
*/
|
||||
function tableColumn(seq, fieldCode, content, colWidth, fontSize, bold, textAlign) {
|
||||
return {
|
||||
id: makeId('text', seq),
|
||||
type: 'text',
|
||||
field_code: fieldCode,
|
||||
content,
|
||||
width: colWidth,
|
||||
height: 6,
|
||||
fontSize,
|
||||
bold: bold || false,
|
||||
italic: false,
|
||||
underline: false,
|
||||
rotate: 0,
|
||||
textAlign: textAlign || 'left',
|
||||
lineHeight: 6,
|
||||
};
|
||||
}
|
||||
|
||||
// ─── 构建入库单 A5 模板元素数组 ─────────────────────────────
|
||||
|
||||
const templateContent = [
|
||||
|
||||
// 1. 标题:入 库 单
|
||||
label(1, 6, 0, 148, 10, '入 库 单', '18', { bold: true, textAlign: 'center' }),
|
||||
|
||||
// 2. 分割线
|
||||
lineEl(2, 18, 10, 128, 0.5),
|
||||
|
||||
// 3. 信息区 - 第一行:入库单号 | 业务类型
|
||||
label(3, 21, 10, 26, 7, '入库单号:', '10'),
|
||||
field(4, 21, 36, 46, 7, 'entry_order_code', '10'),
|
||||
label(5, 21, 84, 20, 7, '业务类型:', '10'),
|
||||
field(6, 21, 104, 34, 7, 'order_type', '10'),
|
||||
|
||||
// 3. 信息区 - 第二行:供应商 | 采购单号
|
||||
label(7, 29, 10, 20, 7, '供应商:', '10'),
|
||||
field(8, 29, 30, 52, 7, 'supplier_name', '10'),
|
||||
label(9, 29, 84, 26, 7, '采购单号:', '10'),
|
||||
field(10, 29, 110, 28, 7, 'purchase_order_code', '10'),
|
||||
|
||||
// 3. 信息区 - 第三行:仓库 | 货主
|
||||
label(11, 37, 10, 18, 7, '仓库:', '10'),
|
||||
field(12, 37, 28, 54, 7, 'warehouse_name', '10'),
|
||||
label(13, 37, 84, 18, 7, '货主:', '10'),
|
||||
field(14, 37, 102, 36, 7, 'store_name', '10'),
|
||||
|
||||
// 3. 信息区 - 第四行:物流公司 | 运单号
|
||||
label(15, 45, 10, 26, 7, '物流公司:', '10'),
|
||||
field(16, 45, 36, 46, 7, 'logistics_name', '10'),
|
||||
label(17, 45, 84, 20, 7, '运单号:', '10'),
|
||||
field(18, 45, 104, 34, 7, 'express_code', '10'),
|
||||
|
||||
// 3. 信息区 - 第五行:创建时间 | 预期到货
|
||||
label(19, 53, 10, 26, 7, '创建时间:', '10'),
|
||||
field(20, 53, 36, 46, 7, 'order_create_time', '10'),
|
||||
label(21, 53, 84, 26, 7, '预期到货:', '10'),
|
||||
field(22, 53, 110, 28, 7, 'expect_start_time', '10'),
|
||||
|
||||
// 4. 分割线
|
||||
lineEl(23, 62, 10, 128, 0.5),
|
||||
|
||||
// 5. 入库明细标题
|
||||
label(24, 65, 10, 128, 7, '入库明细', '11', { bold: true, textAlign: 'left' }),
|
||||
|
||||
// 6. 表格(严格参照 id=18 rows 格式:每列为 type: "text" 对象)
|
||||
{
|
||||
id: makeId('table', 25),
|
||||
type: 'table',
|
||||
top: 74,
|
||||
left: 10,
|
||||
width: 128,
|
||||
height: 75,
|
||||
rowHeight: 6,
|
||||
headerHeight: 6,
|
||||
rows: [
|
||||
tableColumn(26, 'item_code', '商品编码', 22, '9', false, 'left'),
|
||||
tableColumn(27, 'item_name', '商品名称', 40, '9', false, 'left'),
|
||||
tableColumn(28, 'item_barcode', '条码', 22, '9', false, 'left'),
|
||||
tableColumn(29, 'plan_qty', '计划数量', 18, '9', false, 'left'),
|
||||
tableColumn(30, 'received_qty', '已收数量', 18, '9', false, 'left'),
|
||||
tableColumn(31, 'inventory_type', '库存类型', 8, '9', false, 'left'),
|
||||
],
|
||||
},
|
||||
|
||||
// 7. 分割线
|
||||
lineEl(32, 151, 10, 128, 0.5),
|
||||
|
||||
// 8. 单据总行数
|
||||
label(33, 155, 64, 26, 7, '单据总行数:', '9'),
|
||||
field(34, 155, 90, 48, 7, 'total_order_lines', '9'),
|
||||
|
||||
// 9. 备注
|
||||
label(35, 164, 10, 14, 7, '备注:', '9'),
|
||||
field(36, 164, 24, 114, 7, 'remark', '9'),
|
||||
|
||||
// 10. 二维码:entry_order_code
|
||||
qrcodeEl(37, 4, 120, 24, 24, 'entry_order_code', '8'),
|
||||
|
||||
// 11. 打印时间
|
||||
label(38, 174, 10, 26, 7, '打印时间:', '9'),
|
||||
field(39, 174, 36, 102, 7, 'print_time', '9'),
|
||||
|
||||
];
|
||||
|
||||
module.exports.up = async queryInterface => {
|
||||
const { sequelize } = queryInterface;
|
||||
|
||||
// 先删除可能存在的旧版本 id=20
|
||||
await sequelize.query(
|
||||
`DELETE FROM \`${TABLE}\` WHERE id = 20`,
|
||||
{ type: sequelize.QueryTypes.DELETE }
|
||||
);
|
||||
|
||||
// 插入修正后的入库单 A5 模板(id=20)
|
||||
await sequelize.query(
|
||||
`INSERT INTO \`${TABLE}\`
|
||||
(id, business_type, template_name, platform, warehouse_id, page_width, page_height, template_content, template_type, template_url, is_default, status, create_at, update_at)
|
||||
VALUES (20, 'ENTRY_ORDER', '入库单A5模板', 'default', NULL, 148, 210, :template_content, 'CUSTOM', '', true, 'ACTIVE', NOW(), NOW())`,
|
||||
{
|
||||
replacements: {
|
||||
template_content: JSON.stringify(templateContent),
|
||||
},
|
||||
type: sequelize.QueryTypes.INSERT,
|
||||
}
|
||||
);
|
||||
};
|
||||
|
||||
module.exports.down = async queryInterface => {
|
||||
const { sequelize } = queryInterface;
|
||||
await sequelize.query(
|
||||
`DELETE FROM \`${TABLE}\` WHERE id = 20`,
|
||||
{ type: sequelize.QueryTypes.DELETE }
|
||||
);
|
||||
};
|
||||
|
||||
module.exports.templateContent = templateContent;
|
||||
@ -1,53 +0,0 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* 将 wms_print_items 和 wms_print_template 表中已存在的入库单打印数据
|
||||
* 从 RECEIPT 迁移到 ENTRY_ORDER。
|
||||
*
|
||||
* 背景:
|
||||
* - RECEIPT 下同时有收货单(platform=warehouse)和入库单(platform=default)的数据
|
||||
* - 只有 platform='default' 的才是入库单,需要迁移
|
||||
* - platform='warehouse' 的是收货单,保留在 RECEIPT
|
||||
*
|
||||
* up: 将 business_type='RECEIPT' AND platform='default' → business_type='ENTRY_ORDER'
|
||||
* down:将 business_type='ENTRY_ORDER' AND platform='default' → business_type='RECEIPT'
|
||||
*/
|
||||
|
||||
const PRINT_ITEMS_TABLE = 'wms_print_items';
|
||||
const PRINT_TEMPLATE_TABLE = 'wms_print_template';
|
||||
|
||||
module.exports.up = async queryInterface => {
|
||||
const { sequelize } = queryInterface;
|
||||
|
||||
// 1) wms_print_items:入库单打印项迁移
|
||||
await sequelize.query(
|
||||
`UPDATE \`${PRINT_ITEMS_TABLE}\`
|
||||
SET business_type = 'ENTRY_ORDER', updated_at = NOW()
|
||||
WHERE business_type = 'RECEIPT' AND platform = 'default'`
|
||||
);
|
||||
|
||||
// 2) wms_print_template:入库单打印模板迁移
|
||||
await sequelize.query(
|
||||
`UPDATE \`${PRINT_TEMPLATE_TABLE}\`
|
||||
SET business_type = 'ENTRY_ORDER', update_at = NOW()
|
||||
WHERE business_type = 'RECEIPT' AND platform = 'default'`
|
||||
);
|
||||
};
|
||||
|
||||
module.exports.down = async queryInterface => {
|
||||
const { sequelize } = queryInterface;
|
||||
|
||||
// 1) wms_print_items:入库单打印项回退
|
||||
await sequelize.query(
|
||||
`UPDATE \`${PRINT_ITEMS_TABLE}\`
|
||||
SET business_type = 'RECEIPT', updated_at = NOW()
|
||||
WHERE business_type = 'ENTRY_ORDER' AND platform = 'default'`
|
||||
);
|
||||
|
||||
// 2) wms_print_template:入库单打印模板回退
|
||||
await sequelize.query(
|
||||
`UPDATE \`${PRINT_TEMPLATE_TABLE}\`
|
||||
SET business_type = 'RECEIPT', update_at = NOW()
|
||||
WHERE business_type = 'ENTRY_ORDER' AND platform = 'default'`
|
||||
);
|
||||
};
|
||||
@ -1,42 +0,0 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* 入库单 A5 默认打印模板(ENTRY_ORDER 业务类型)数据清理迁移。
|
||||
*
|
||||
* 背景:
|
||||
* 旧版本 migration 已创建了一个格式正确的入库单模板(id=20,扁平化 content/field_code/bold/fontSize 风格)。
|
||||
* 本 migration 后来又插入了一个格式错误的模板(id=21,使用了 label+style 包装,与渲染引擎不兼容)。
|
||||
*
|
||||
* 本迁移的作用:
|
||||
* - 删除格式错误的重复模板 id=21(如果存在)
|
||||
* - 保留下一个格式正确的模板(id=20)继续使用
|
||||
*
|
||||
* 渲染引擎解析逻辑见 app/service/systemMethods/print.js(customize 分支):
|
||||
* - 直接读取 item.content / item.fontSize / item.bold / item.textAlign 等扁平化属性
|
||||
* - 有 field_code 的元素用 data[field_code] 值覆盖 content
|
||||
* - 不支持 label / style 对象包装
|
||||
*/
|
||||
|
||||
const TABLE = 'wms_print_template';
|
||||
|
||||
module.exports.up = async queryInterface => {
|
||||
const { sequelize } = queryInterface;
|
||||
|
||||
// 删除格式错误的重复模板(id=21,使用了 label+style 包装格式)
|
||||
// 保留格式正确的模板 id=20(扁平化 content/field_code/bold/fontSize 风格)
|
||||
const [ duplicate ] = await sequelize.query(
|
||||
`SELECT id FROM \`${TABLE}\` WHERE id = 21 AND business_type = 'ENTRY_ORDER' AND template_name = '入库单A5模板' AND warehouse_id IS NULL AND delete_at IS NULL LIMIT 1`,
|
||||
{ type: sequelize.QueryTypes.SELECT }
|
||||
);
|
||||
|
||||
if (duplicate) {
|
||||
await sequelize.query(
|
||||
`DELETE FROM \`${TABLE}\` WHERE id = 21`,
|
||||
{ type: sequelize.QueryTypes.DELETE }
|
||||
);
|
||||
}
|
||||
};
|
||||
|
||||
module.exports.down = async () => {
|
||||
// down 不回滚:删除 id=21 是一条清理操作,不需要恢复
|
||||
};
|
||||
@ -1,151 +0,0 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* ENTRY_ORDER(入库单)打印项配置 v2 补充。
|
||||
*
|
||||
* 在 v1(20260622150000)基础上新增:
|
||||
* - entry_order_info 组:15 个新字段(sort_order 14~28)
|
||||
* - entry_items 表格:columns 从 6 扩展为 11,新增 5 列
|
||||
* - entry_items_info 组:17 个独立字段(group_sort=3, sort_order 1~17)
|
||||
*
|
||||
* up:INSERT IGNORE + UPDATE 表格配置
|
||||
* down:先恢复表格原始配置,再删除新增记录
|
||||
*/
|
||||
|
||||
const TABLE = 'wms_print_items';
|
||||
|
||||
// ─── 新增打印项 ────────────────────────────────────────────────
|
||||
const NEW_PRINT_ITEMS = [
|
||||
// ─── entry_order_info 组补充(group_sort=1, sort_order 14~28) ──
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '入库单ID', field_code: 'id', field_type: 'number', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 14, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '来源类型', field_code: 'source_type', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 15, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '同步状态', field_code: 'sync_status', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 16, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '同步返回信息', field_code: 'sync_message', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 17, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库ID', field_code: 'warehouse_id', field_type: 'number', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 18, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '货主ID', field_code: 'store_id', field_type: 'number', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 19, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '最迟预期到货时间', field_code: 'expect_end_time', field_type: 'datetime', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 20, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '物流公司编码', field_code: 'logistics_code', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 21, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '供应商编码', field_code: 'supplier_code', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 22, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '费用是否记录', field_code: 'expense_record', field_type: 'number', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 23, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '是否启用', field_code: 'is_enabled', field_type: 'number', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 24, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '创建时间', field_code: 'created_at', field_type: 'datetime', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 25, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '更新时间', field_code: 'updated_at', field_type: 'datetime', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 26, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '关联仓库名称', field_code: 'warehouse_company_name', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 27, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '关联货主名称', field_code: 'store_company_name', field_type: 'text', group_field: 'entry_order_info', group_label: '入库单信息', group_sort: 1, sort_order: 28, required: false, status: 1 },
|
||||
|
||||
// ─── entry_items_info 独立字段(group_sort=3) ──────────────────
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '商品SKU ID', field_code: 'stock_id', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 1, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '外部商品编码', field_code: 'external_item_code', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 2, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '外部商品ID', field_code: 'external_item_id', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 3, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库商品编码', field_code: 'warehouse_item_code', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 4, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库商品名称', field_code: 'warehouse_item_name', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 5, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库商品规格', field_code: 'warehouse_item_spec', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 6, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库当前库存总量', field_code: 'warehouse_quantity', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 7, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '仓库锁定数量', field_code: 'warehouse_locked_quantity', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 8, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '是否批次管理', field_code: 'warehouse_is_batch_mgmt', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 9, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '是否效期管理', field_code: 'warehouse_is_shelf_life_mgmt', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 10, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '直入已入库数量', field_code: 'direct_inbound_quantity', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 11, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '剩余可入库数量', field_code: 'remaining_quantity', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 12, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '外部业务编码', field_code: 'out_biz_code', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 13, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '订单行号', field_code: 'order_line_no', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 14, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '货主编码', field_code: 'owner_code', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 15, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '库存类型', field_code: 'inventory_type', field_type: 'text', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 16, required: false, status: 1 },
|
||||
{ business_type: 'ENTRY_ORDER', platform: 'default', field_name: '已确认收货数量', field_code: 'confirm_quantity', field_type: 'number', group_field: 'entry_items_info', group_label: '入库明细信息', group_sort: 3, sort_order: 17, required: false, status: 1 },
|
||||
];
|
||||
|
||||
// ─── 旧 items 表格配置(v1) ────────────────────────────────────
|
||||
const OLD_ITEMS_TABLE_CONFIG = {
|
||||
columns: 6,
|
||||
headers: [ '商品编码', '商品名称', '条码', '计划数量', '已收数量', '库存类型' ],
|
||||
};
|
||||
|
||||
// ─── 新 items 表格配置(v2 扩展为 11 列) ───────────────────────
|
||||
const NEW_ITEMS_TABLE_CONFIG = {
|
||||
columns: 11,
|
||||
headers: [ '行号', '商品编码(外部)', '商品名称', '条码', '仓库商品编码', '计划数量', '已收数量', '已确认数量', '直入数量', '剩余可入库', '库存类型' ],
|
||||
};
|
||||
|
||||
// ══════════════════════════════════════════════════════════════════
|
||||
const NEW_FIELD_CODES = NEW_PRINT_ITEMS.map(it => it.field_code);
|
||||
|
||||
module.exports.up = async queryInterface => {
|
||||
const { sequelize } = queryInterface;
|
||||
|
||||
// 1) 插入所有新增打印项(幂等)
|
||||
for (const item of NEW_PRINT_ITEMS) {
|
||||
await sequelize.query(
|
||||
`INSERT IGNORE INTO \`${TABLE}\`
|
||||
(business_type, platform, field_name, field_code, field_type, is_table, table_config, group_field, group_label, group_sort, sort_order, required, status, created_at, updated_at)
|
||||
VALUES (:business_type, :platform, :field_name, :field_code, :field_type, :is_table, :table_config, :group_field, :group_label, :group_sort, :sort_order, :required, :status, NOW(), NOW())`,
|
||||
{
|
||||
replacements: {
|
||||
business_type: item.business_type,
|
||||
platform: item.platform,
|
||||
field_name: item.field_name,
|
||||
field_code: item.field_code,
|
||||
field_type: item.field_type,
|
||||
is_table: item.is_table ? 1 : 0,
|
||||
table_config: item.table_config ? JSON.stringify(item.table_config) : null,
|
||||
group_field: item.group_field || null,
|
||||
group_label: item.group_label || null,
|
||||
group_sort: item.group_sort || 0,
|
||||
sort_order: item.sort_order || 0,
|
||||
required: item.required ? 1 : 0,
|
||||
status: item.status,
|
||||
},
|
||||
type: sequelize.QueryTypes.INSERT,
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
// 2) 更新 items 表格配置:6 列 → 11 列
|
||||
await sequelize.query(
|
||||
`UPDATE \`${TABLE}\`
|
||||
SET table_config = :table_config,
|
||||
updated_at = NOW()
|
||||
WHERE business_type = 'ENTRY_ORDER'
|
||||
AND platform = 'default'
|
||||
AND field_code = 'items'`,
|
||||
{
|
||||
replacements: {
|
||||
table_config: JSON.stringify(NEW_ITEMS_TABLE_CONFIG),
|
||||
},
|
||||
type: sequelize.QueryTypes.UPDATE,
|
||||
}
|
||||
);
|
||||
};
|
||||
|
||||
module.exports.down = async queryInterface => {
|
||||
const { sequelize } = queryInterface;
|
||||
|
||||
// 1) 恢复 items 表格原有配置(columns:6)
|
||||
await sequelize.query(
|
||||
`UPDATE \`${TABLE}\`
|
||||
SET table_config = :table_config,
|
||||
updated_at = NOW()
|
||||
WHERE business_type = 'ENTRY_ORDER'
|
||||
AND platform = 'default'
|
||||
AND field_code = 'items'`,
|
||||
{
|
||||
replacements: {
|
||||
table_config: JSON.stringify(OLD_ITEMS_TABLE_CONFIG),
|
||||
},
|
||||
type: sequelize.QueryTypes.UPDATE,
|
||||
}
|
||||
);
|
||||
|
||||
// 2) 精确删除本次新增的所有打印项
|
||||
if (NEW_FIELD_CODES.length > 0) {
|
||||
const placeholders = NEW_FIELD_CODES.map(() => '?').join(',');
|
||||
await sequelize.query(
|
||||
`DELETE FROM \`${TABLE}\`
|
||||
WHERE business_type = 'ENTRY_ORDER'
|
||||
AND platform = 'default'
|
||||
AND field_code IN (${placeholders})`,
|
||||
{
|
||||
replacements: NEW_FIELD_CODES,
|
||||
type: sequelize.QueryTypes.DELETE,
|
||||
}
|
||||
);
|
||||
}
|
||||
};
|
||||
@ -0,0 +1,100 @@
|
||||
'use strict';
|
||||
|
||||
const TABLE_NAME = 'wms_inbound_direct_log';
|
||||
|
||||
module.exports = {
|
||||
up: async (queryInterface, Sequelize) => {
|
||||
const tables = await queryInterface.showAllTables();
|
||||
const exists = tables.some(t => (typeof t === 'string' ? t : t.tableName) === TABLE_NAME);
|
||||
if (!exists) return;
|
||||
|
||||
const columns = await queryInterface.describeTable(TABLE_NAME);
|
||||
|
||||
// 新增 entry_item_id 字段
|
||||
if (!columns.entry_item_id) {
|
||||
await queryInterface.addColumn(TABLE_NAME, 'entry_item_id', {
|
||||
type: Sequelize.BIGINT(20).UNSIGNED,
|
||||
allowNull: true,
|
||||
defaultValue: null,
|
||||
comment: '入库明细ID',
|
||||
});
|
||||
}
|
||||
|
||||
// 新增 receiving_detail_id 字段
|
||||
if (!columns.receiving_detail_id) {
|
||||
await queryInterface.addColumn(TABLE_NAME, 'receiving_detail_id', {
|
||||
type: Sequelize.INTEGER(11),
|
||||
allowNull: true,
|
||||
defaultValue: null,
|
||||
comment: '收货明细ID,绑定收货时使用',
|
||||
});
|
||||
}
|
||||
|
||||
// 新增 status 字段
|
||||
if (!columns.status) {
|
||||
await queryInterface.addColumn(TABLE_NAME, 'status', {
|
||||
type: Sequelize.ENUM('pending', 'committed', 'released'),
|
||||
allowNull: true,
|
||||
defaultValue: null,
|
||||
comment: '绑定状态:pending=待提交 committed=已提交 released=已释放,非绑定模式为NULL',
|
||||
});
|
||||
}
|
||||
|
||||
// 新增 updated_at 字段
|
||||
if (!columns.updated_at) {
|
||||
await queryInterface.addColumn(TABLE_NAME, 'updated_at', {
|
||||
type: Sequelize.DATE,
|
||||
allowNull: true,
|
||||
defaultValue: null,
|
||||
comment: '更新时间',
|
||||
});
|
||||
}
|
||||
|
||||
// 新增 deleted_at 字段(软删除)
|
||||
if (!columns.deleted_at) {
|
||||
await queryInterface.addColumn(TABLE_NAME, 'deleted_at', {
|
||||
type: Sequelize.DATE,
|
||||
allowNull: true,
|
||||
defaultValue: null,
|
||||
comment: '软删除时间',
|
||||
});
|
||||
}
|
||||
|
||||
// 新增索引 idx_entry_item_id
|
||||
await queryInterface.addIndex(TABLE_NAME, [ 'entry_item_id' ], {
|
||||
name: 'idx_entry_item_id',
|
||||
});
|
||||
|
||||
// 新增索引 idx_receiving_detail_id
|
||||
await queryInterface.addIndex(TABLE_NAME, [ 'receiving_detail_id' ], {
|
||||
name: 'idx_receiving_detail_id',
|
||||
});
|
||||
|
||||
// 新增索引 idx_status
|
||||
await queryInterface.addIndex(TABLE_NAME, [ 'status' ], {
|
||||
name: 'idx_status',
|
||||
});
|
||||
|
||||
// 新增唯一约束 uk_entry_receiving_binding
|
||||
await queryInterface.addIndex(TABLE_NAME, [ 'entry_item_id', 'receiving_detail_id', 'status' ], {
|
||||
name: 'uk_entry_receiving_binding',
|
||||
unique: true,
|
||||
});
|
||||
},
|
||||
|
||||
down: async queryInterface => {
|
||||
// 移除唯一约束
|
||||
await queryInterface.removeIndex(TABLE_NAME, 'uk_entry_receiving_binding');
|
||||
// 移除索引
|
||||
await queryInterface.removeIndex(TABLE_NAME, 'idx_status');
|
||||
await queryInterface.removeIndex(TABLE_NAME, 'idx_receiving_detail_id');
|
||||
await queryInterface.removeIndex(TABLE_NAME, 'idx_entry_item_id');
|
||||
|
||||
// 移除字段
|
||||
await queryInterface.removeColumn(TABLE_NAME, 'deleted_at');
|
||||
await queryInterface.removeColumn(TABLE_NAME, 'updated_at');
|
||||
await queryInterface.removeColumn(TABLE_NAME, 'status');
|
||||
await queryInterface.removeColumn(TABLE_NAME, 'receiving_detail_id');
|
||||
await queryInterface.removeColumn(TABLE_NAME, 'entry_item_id');
|
||||
},
|
||||
};
|
||||
@ -0,0 +1,184 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* 数据迁移:将 wms_entry_receiving_binding 存量数据迁移到 wms_inbound_direct_log。
|
||||
*
|
||||
* 背景:
|
||||
* - wms_entry_receiving_binding 的"入库明细 ↔ 收货明细"绑定能力已迁移到 wms_inbound_direct_log。
|
||||
* - 本 migration 负责将 wms_entry_receiving_binding 中的历史数据同步到 wms_inbound_direct_log。
|
||||
*
|
||||
* 字段映射(source → target):
|
||||
* - entry_item_id / receiving_detail_id / allocated_quantity→quantity / status / creator_id→operator_id
|
||||
* - created_at→created_at / updated_at→updated_at / deleted_at→deleted_at
|
||||
*
|
||||
* 关联补全:
|
||||
* - entry_order_id / entry_order_code / warehouse_id / store_id:通过 wms_entry_items + wms_entry_order
|
||||
* - stock_id:从 wms_entry_items
|
||||
* - inbound_type:固定 'pda'
|
||||
* - space_id:固定 0
|
||||
*
|
||||
* @description 迁移脚本:20260703000001
|
||||
*/
|
||||
|
||||
/** 目标表名 */
|
||||
const TARGET_TABLE = 'wms_inbound_direct_log';
|
||||
/** 源表名 */
|
||||
const SOURCE_TABLE = 'wms_entry_receiving_binding';
|
||||
|
||||
/**
|
||||
* 规范化 showAllTables 返回的表名。
|
||||
* @param {string|Object} table 表名或表对象。
|
||||
* @return {string} 规范化后的表名。
|
||||
*/
|
||||
const normalizeTableName = table => {
|
||||
if (typeof table === 'string') return table;
|
||||
return table && typeof table === 'object' ? (table.tableName || table.name || '') : '';
|
||||
};
|
||||
|
||||
/**
|
||||
* 检查源表是否存在。
|
||||
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
|
||||
* @return {Promise<boolean>} 源表是否存在。
|
||||
*/
|
||||
const hasSourceTable = async queryInterface => {
|
||||
const allTables = await queryInterface.showAllTables();
|
||||
const tableSet = new Set((allTables || []).map(normalizeTableName));
|
||||
return tableSet.has(SOURCE_TABLE);
|
||||
};
|
||||
|
||||
/**
|
||||
* 检查目标表是否存在。
|
||||
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
|
||||
* @return {Promise<boolean>} 目标表是否存在。
|
||||
*/
|
||||
const hasTargetTable = async queryInterface => {
|
||||
const allTables = await queryInterface.showAllTables();
|
||||
const tableSet = new Set((allTables || []).map(normalizeTableName));
|
||||
return tableSet.has(TARGET_TABLE);
|
||||
};
|
||||
|
||||
/**
|
||||
* 统计源表总行数。
|
||||
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
|
||||
* @return {Promise<number>} 源表总行数。
|
||||
*/
|
||||
const countSourceRows = async queryInterface => {
|
||||
const [ rows ] = await queryInterface.sequelize.query(
|
||||
`SELECT COUNT(*) AS cnt FROM ${SOURCE_TABLE}`,
|
||||
{ type: queryInterface.sequelize.QueryTypes.SELECT }
|
||||
);
|
||||
return rows ? rows.cnt : 0;
|
||||
};
|
||||
|
||||
/**
|
||||
* 正向迁移:从 wms_entry_receiving_binding 迁移数据到 wms_inbound_direct_log。
|
||||
*
|
||||
* 去重策略:按 (entry_item_id, receiving_detail_id, status) GROUP BY 去重,
|
||||
* 重复组保留 id 最小的一条,其余跳过并打印数量。
|
||||
*
|
||||
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
|
||||
* @param {typeof import('sequelize')} Sequelize Sequelize 类型集合。
|
||||
* @return {Promise<void>} 无返回值。
|
||||
*/
|
||||
module.exports.up = async (queryInterface, Sequelize) => {
|
||||
void Sequelize;
|
||||
|
||||
// 幂等:源表不存在则跳过
|
||||
if (!(await hasSourceTable(queryInterface))) {
|
||||
console.log('wms_entry_receiving_binding 表不存在,跳过迁移');
|
||||
return;
|
||||
}
|
||||
|
||||
// 幂等:目标表不存在则跳过
|
||||
if (!(await hasTargetTable(queryInterface))) {
|
||||
console.log('wms_inbound_direct_log 表不存在,跳过迁移');
|
||||
return;
|
||||
}
|
||||
|
||||
const totalRows = await countSourceRows(queryInterface);
|
||||
console.log(`wms_entry_receiving_binding 总行数:${totalRows}`);
|
||||
|
||||
if (totalRows === 0) {
|
||||
console.log('无数据需要迁移,跳过');
|
||||
return;
|
||||
}
|
||||
|
||||
// 统计去重后跳过的行数
|
||||
const [ dupResult ] = await queryInterface.sequelize.query(
|
||||
`SELECT COUNT(*) AS skip_cnt
|
||||
FROM ${SOURCE_TABLE}
|
||||
WHERE id NOT IN (
|
||||
SELECT MIN(id)
|
||||
FROM ${SOURCE_TABLE}
|
||||
GROUP BY entry_item_id, receiving_detail_id, status
|
||||
)`,
|
||||
{ type: queryInterface.sequelize.QueryTypes.SELECT }
|
||||
);
|
||||
const skipCount = dupResult ? dupResult.skip_cnt : 0;
|
||||
if (skipCount > 0) {
|
||||
console.log(`检测到 ${skipCount} 条重复记录(按 entry_item_id + receiving_detail_id + status 分组去重),将被跳过`);
|
||||
}
|
||||
|
||||
// 执行 INSERT INTO ... SELECT
|
||||
const [ insertResult ] = await queryInterface.sequelize.query(
|
||||
`INSERT INTO ${TARGET_TABLE}
|
||||
(entry_item_id, receiving_detail_id, quantity, status,
|
||||
operator_id, created_at, updated_at, deleted_at,
|
||||
entry_order_id, entry_order_code, warehouse_id, store_id,
|
||||
stock_id, inbound_type, space_id)
|
||||
SELECT
|
||||
b.entry_item_id,
|
||||
b.receiving_detail_id,
|
||||
b.allocated_quantity,
|
||||
b.status,
|
||||
b.creator_id,
|
||||
b.created_at,
|
||||
b.updated_at,
|
||||
b.deleted_at,
|
||||
ei.order_id,
|
||||
eo.entry_order_code,
|
||||
eo.warehouse_id,
|
||||
eo.store_id,
|
||||
ei.stock_id,
|
||||
'pda',
|
||||
0
|
||||
FROM ${SOURCE_TABLE} b
|
||||
LEFT JOIN wms_entry_items ei ON b.entry_item_id = ei.id
|
||||
LEFT JOIN wms_entry_order eo ON ei.order_id = eo.id
|
||||
WHERE b.id IN (
|
||||
SELECT MIN(id)
|
||||
FROM ${SOURCE_TABLE}
|
||||
GROUP BY entry_item_id, receiving_detail_id, status
|
||||
)`,
|
||||
{ type: queryInterface.sequelize.QueryTypes.INSERT }
|
||||
);
|
||||
|
||||
const insertedCount = insertResult ? (Array.isArray(insertResult) ? insertResult.length : insertResult[1]) : 0;
|
||||
console.log(`迁移完成:成功插入 ${insertedCount} 行`);
|
||||
};
|
||||
|
||||
/**
|
||||
* 回滚迁移:删除从 wms_entry_receiving_binding 迁移过来的数据。
|
||||
*
|
||||
* 删除条件:receiving_detail_id IS NOT NULL AND entry_item_id IS NOT NULL
|
||||
* (仅删除有绑定关系的记录,不影响原有 direct-log 数据)
|
||||
*
|
||||
* @param {import('sequelize').QueryInterface} queryInterface 查询接口。
|
||||
* @return {Promise<void>} 无返回值。
|
||||
*/
|
||||
module.exports.down = async queryInterface => {
|
||||
if (!(await hasTargetTable(queryInterface))) {
|
||||
console.log('wms_inbound_direct_log 表不存在,跳过回滚');
|
||||
return;
|
||||
}
|
||||
|
||||
const [ deleteResult ] = await queryInterface.sequelize.query(
|
||||
`DELETE FROM ${TARGET_TABLE}
|
||||
WHERE receiving_detail_id IS NOT NULL
|
||||
AND entry_item_id IS NOT NULL`,
|
||||
{ type: queryInterface.sequelize.QueryTypes.DELETE }
|
||||
);
|
||||
|
||||
const deletedCount = deleteResult || 0;
|
||||
console.log(`回滚完成:删除 ${deletedCount} 行`);
|
||||
};
|
||||
@ -1,56 +0,0 @@
|
||||
{
|
||||
"docName": "<system|qimen|gateway>",
|
||||
"docMeta": {
|
||||
"updatedAt": "<YYYY-MM-DD>",
|
||||
"version": "<doc-version>"
|
||||
},
|
||||
"group": {
|
||||
"groupName": "<分组名称>",
|
||||
"module": "<group-module>"
|
||||
},
|
||||
"methods": [
|
||||
{
|
||||
"method": "<module.method>",
|
||||
"description": "<接口说明>",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [],
|
||||
"params": [
|
||||
{
|
||||
"name": "<param-name>",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"source": "body",
|
||||
"description": "<参数说明>"
|
||||
}
|
||||
],
|
||||
"response": [
|
||||
{
|
||||
"name": "<field-name>",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "<返回字段说明>"
|
||||
}
|
||||
],
|
||||
"errors": [
|
||||
{
|
||||
"code": 400,
|
||||
"message": "<错误说明>"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"change": {
|
||||
"version": "<YYYY.MM.DD-docName-xx>",
|
||||
"date": "<YYYY-MM-DD>",
|
||||
"summary": "<本次变更摘要>",
|
||||
"methods": [
|
||||
"<module.method>"
|
||||
],
|
||||
"notes": [
|
||||
"<变更说明 1>",
|
||||
"<变更说明 2>"
|
||||
],
|
||||
"type": "updated"
|
||||
}
|
||||
}
|
||||
@ -1,124 +0,0 @@
|
||||
# API 文档 JSON 固定写入流程
|
||||
|
||||
## 现有 JSON 结构
|
||||
|
||||
仓库内现有 API 文档分两类:
|
||||
|
||||
1. `methods/<docName>.json`
|
||||
- 根节点是对象
|
||||
- 关键字段固定为 `module`、`description`、`version`、`updatedAt`、`headers`、`methods.groups`
|
||||
- `methods.groups` 为数组,每个 group 固定为 `groupName`、`module`、`list`
|
||||
- `list` 中每个 method 固定包含 `method`、`description`、`isNeedAuth`、`isNeedLogin`、`headers`、`params`、`response`、`errors`
|
||||
|
||||
2. `methods/changes/<docName>.json`
|
||||
- 根节点是数组
|
||||
- 每条变更记录建议固定包含 `version`、`date`、`summary`、`methods`、`notes`
|
||||
- 可选补充 `type`
|
||||
|
||||
## 固定输入 spec
|
||||
|
||||
后续 API 文档写入统一通过脚本读取一个 spec JSON 完成,spec 结构固定如下:
|
||||
|
||||
```json
|
||||
{
|
||||
"docName": "system",
|
||||
"docMeta": {
|
||||
"updatedAt": "2026-04-15",
|
||||
"version": "0.3.5"
|
||||
},
|
||||
"group": {
|
||||
"groupName": "基础模块",
|
||||
"module": "index"
|
||||
},
|
||||
"methods": [
|
||||
{
|
||||
"method": "index.example",
|
||||
"description": "接口说明",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [],
|
||||
"params": [],
|
||||
"response": [],
|
||||
"errors": []
|
||||
}
|
||||
],
|
||||
"change": {
|
||||
"version": "2026.04.15-system-06",
|
||||
"date": "2026-04-15",
|
||||
"summary": "一句话说明本次接口文档变更",
|
||||
"methods": [
|
||||
"index.example"
|
||||
],
|
||||
"notes": [
|
||||
"补充关键字段说明。"
|
||||
],
|
||||
"type": "updated"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
说明:
|
||||
|
||||
- `docName` 目前必须对应已存在的 `methods/system.json`、`methods/qimen.json`、`methods/gateway.json`
|
||||
- `group` 用于定位或创建目标分组
|
||||
- `methods` 为要写入的完整 method 文档对象数组,脚本按 `method` 字段 upsert
|
||||
- `change` 默认必填;仅当明确是纯格式修复且不需要追加历史时,才允许加 `--doc-only`
|
||||
|
||||
注意:所有对 `methods/*.json` 与 `methods/changes/*.json` 的变更必须通过 spec + 脚本完成。spec 是唯一输入来源,不接受直接手写或直接提交目标 JSON 的改动。
|
||||
|
||||
## 固定命令
|
||||
|
||||
务必按顺序执行:复制 example -> 编辑 spec -> dry-run -> 修正 -> 正式写入。示例命令(PowerShell):
|
||||
|
||||
先做 dry-run(验证和查看差异):
|
||||
|
||||
```powershell
|
||||
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
|
||||
```
|
||||
|
||||
确认 dry-run 输出无误后执行正式写入:
|
||||
|
||||
```powershell
|
||||
npm run doc:api:update -- --spec=temp/api-doc-update.json
|
||||
```
|
||||
|
||||
仅修补主文档且不追加 changes 时(慎用):
|
||||
|
||||
```powershell
|
||||
npm run doc:api:update -- --spec=temp/api-doc-update.json --doc-only
|
||||
```
|
||||
|
||||
## 脚本保证
|
||||
|
||||
`script/update-api-doc.cjs` 会执行以下动作(脚本为写入守门人):
|
||||
|
||||
- 校验 spec JSON 是否符合固定结构与必填字段
|
||||
- 校验目标 `methods/*.json` 与 `methods/changes/*.json` 是否可解析
|
||||
- 在 dry-run 模式下不写入,仅打印将要变更的差异并返回校验结果
|
||||
- 按 `group` + `method` 做 upsert,避免覆盖或破坏其他分组/方法
|
||||
- 检查 change version 是否重复并拒绝冲突写入
|
||||
- 尽量保留目标 JSON 原有缩进与换行风格,减少无关 diff
|
||||
|
||||
脚本是对 methods JSON 的唯一写入通道;任何绕过脚本的改动都不被接受。
|
||||
|
||||
## 推荐流程
|
||||
|
||||
1. 先核对代码与测试,确认真实接口契约
|
||||
2. 如果是 system 参数结构变化,可先执行 `node .\script\tmp-struct-system-params.cjs`
|
||||
3. 按 [docs/api-doc-update-spec.example.json](docs/api-doc-update-spec.example.json) 复制一份 spec 到 `temp/` 并在该文件上编辑
|
||||
4. 先执行 dry-run(`--dry-run`),阅读输出并修正 spec
|
||||
5. 确认无误后执行正式写入(不带 `--dry-run`)
|
||||
6. 最后补充必要的 `docs/*.md` 或 `README.md`
|
||||
|
||||
最小示例流程(PowerShell):
|
||||
|
||||
```powershell
|
||||
# 复制示例到 temp 并编辑
|
||||
Copy-Item docs/api-doc-update-spec.example.json temp/api-doc-update.json
|
||||
|
||||
# dry-run
|
||||
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
|
||||
|
||||
# 正式写入
|
||||
npm run doc:api:update -- --spec=temp/api-doc-update.json
|
||||
```
|
||||
@ -1,387 +0,0 @@
|
||||
# 组合商品(comboGoods)模块 API 文档
|
||||
|
||||
## 模块概述
|
||||
|
||||
组合商品(comboGoods)模块提供组合商品的 CRUD 和搜索功能。组合商品是将多个系统商品(来自 `wms_stock_warehouse`)捆绑在一起的商品概念,用于订单快速选择。
|
||||
|
||||
**代码文件:**
|
||||
- 业务逻辑层:`app/service/systems/comboGoods.js`
|
||||
- 接口包装层:`app/service/systemMethods/comboGoods.js`
|
||||
|
||||
**数据表:**
|
||||
- `wms_combo_goods`:组合商品主表
|
||||
- `wms_combo_goods_item`:组合商品明细表
|
||||
|
||||
---
|
||||
|
||||
## 数据库表结构
|
||||
|
||||
### 主表:wms_combo_goods
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | number | 主键ID |
|
||||
| combo_code | string | 组合商品编码(唯一) |
|
||||
| combo_name | string | 组合商品名称 |
|
||||
| combo_sku_id | number | 组合商品SKU ID |
|
||||
| custom_code | string\|null | 自定义编码,按货主唯一(排除已删除记录) |
|
||||
| status | number | 状态:1=启用 0=停用 |
|
||||
| warehouse_id | number\|null | 仓库ID |
|
||||
| remark | string | 备注 |
|
||||
| creator_id | number | 创建人ID |
|
||||
| editor_id | number | 最后编辑人ID |
|
||||
| created_at | datetime | 创建时间 |
|
||||
| updated_at | datetime | 更新时间 |
|
||||
|
||||
### 明细表:wms_combo_goods_item
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | number | 主键ID |
|
||||
| combo_id | number | 关联的组合商品ID |
|
||||
| item_goods_sku_id | number | 子商品 stock_id(对应 wms_stock_warehouse.id) |
|
||||
| item_quantity | number | 子商品数量 |
|
||||
| sort_order | number | 排序号 |
|
||||
|
||||
---
|
||||
|
||||
## 约束规则
|
||||
|
||||
### 商品有效性校验
|
||||
|
||||
创建/编辑组合商品时,所有子商品必须在 `wms_stock_warehouse` 表中满足以下条件:
|
||||
- `is_valid = 'Y'`(有效状态)
|
||||
- `deleted_at IS NULL`(未删除)
|
||||
|
||||
任一子商品不满足条件,操作将被拒绝并返回具体的不合法 stock_id 列表。
|
||||
|
||||
### 货主一致性校验
|
||||
|
||||
所有子商品必须属于同一个货主(`store_id` 一致)。跨货主组合将返回错误:「所有子商品必须属于同一个货主,不允许跨货主组合」。
|
||||
|
||||
### 自定义编码(custom_code)校验
|
||||
|
||||
`custom_code` 为可选字段(VARCHAR(64)),仅做按货主唯一性校验(排除 status=0 的已删除记录)。
|
||||
- **create**:如果传入非空的 `custom_code`,会校验同货主非删除记录中唯一。
|
||||
- **update**:如果传入非空的 `custom_code`,会校验同货主非删除记录中唯一(排除自身 id)。
|
||||
- 唯一索引:`uk_store_custom_code(warehouse_id, custom_code)`。
|
||||
|
||||
---
|
||||
|
||||
## 简记格式说明
|
||||
|
||||
列表查询和搜索结果中会返回两种简记字段,供前端直接展示:
|
||||
|
||||
### simpleNotation(字符串简记)
|
||||
|
||||
格式:`stock_id|数量,stock_id2|数量`
|
||||
|
||||
示例:`1001|3,1002|5` 表示 stock_id=1001 的商品 3 件 + stock_id=1002 的商品 5 件。
|
||||
|
||||
### nameNotation(商品名称简记)
|
||||
|
||||
格式:`【数量】商品名称+【数量】商品名称`
|
||||
|
||||
示例:`【3】苹果+【5】香蕉` 表示苹果 3 件 + 香蕉 5 件。
|
||||
|
||||
商品名称从 `wms_stock_warehouse.item_name` 获取;若 stock_id 无有效商品信息,则显示为 `SKU#stock_id`。
|
||||
|
||||
---
|
||||
|
||||
## 接口列表
|
||||
|
||||
### 1. comboGoods.list — 组合商品列表查询(分页)
|
||||
|
||||
- **鉴权**:不需要(isNeedAuth=false)
|
||||
- **登录**:需要
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| pagination | object | 否 | 分页参数 |
|
||||
| pagination.page | number | 否 | 页码,默认 1 |
|
||||
| pagination.pageSize | number | 否 | 每页大小,默认 20,最大 200 |
|
||||
| where | object | 否 | 筛选条件 |
|
||||
| where.combo_code | string | 否 | 组合商品编码,精确匹配 |
|
||||
| where.combo_name | string | 否 | 组合商品名称,模糊匹配 |
|
||||
| where.status | number | 否 | 状态筛选:1=启用 0=停用 |
|
||||
| where.warehouse_id | number | 否 | 仓库ID筛选 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "comboGoods.list",
|
||||
"data": {
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"pageSize": 20
|
||||
},
|
||||
"where": {
|
||||
"combo_name": "春节礼包",
|
||||
"status": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "查询成功",
|
||||
"data": {
|
||||
"list": [
|
||||
{
|
||||
"id": 1,
|
||||
"combo_code": "COMBO-001",
|
||||
"combo_name": "春节礼包A",
|
||||
"combo_sku_id": 0,
|
||||
"custom_code": null,
|
||||
"status": 1,
|
||||
"warehouse_id": 1001,
|
||||
"remark": "",
|
||||
"creator_id": 10,
|
||||
"editor_id": 10,
|
||||
"created_at": "2026-06-01T10:00:00.000Z",
|
||||
"updated_at": "2026-06-01T10:00:00.000Z",
|
||||
"items": [
|
||||
{
|
||||
"id": 1,
|
||||
"combo_id": 1,
|
||||
"item_goods_sku_id": 1001,
|
||||
"item_quantity": 3,
|
||||
"sort_order": 0
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"combo_id": 1,
|
||||
"item_goods_sku_id": 1002,
|
||||
"item_quantity": 5,
|
||||
"sort_order": 1
|
||||
}
|
||||
],
|
||||
"simpleNotation": "1001|3,1002|5",
|
||||
"nameNotation": "【3】苹果+【5】香蕉"
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"page": 1,
|
||||
"pageSize": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. comboGoods.create — 创建组合商品
|
||||
|
||||
- **鉴权**:需要(isNeedAuth=true)
|
||||
- **登录**:需要
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| combo_code | string | 是 | 组合商品编码,全局唯一 |
|
||||
| combo_name | string | 是 | 组合商品名称 |
|
||||
| warehouse_id | number | 否 | 仓库ID |
|
||||
| remark | string | 否 | 备注 |
|
||||
| custom_code | string | 否 | 自定义编码,传入时校验按货主唯一(排除已删除记录) |
|
||||
| items | array | 是 | 子商品明细数组 |
|
||||
| items[].item_goods_sku_id | number | 是 | 子商品 stock_id |
|
||||
| items[].item_quantity | number | 是 | 子商品数量(正整数) |
|
||||
| items[].sort_order | number | 否 | 排序号,默认按数组索引 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "comboGoods.create",
|
||||
"data": {
|
||||
"combo_code": "COMBO-001",
|
||||
"combo_name": "春节礼包A",
|
||||
"warehouse_id": 1001,
|
||||
"remark": "2026春节促销礼包",
|
||||
"items": [
|
||||
{ "item_goods_sku_id": 1001, "item_quantity": 3 },
|
||||
{ "item_goods_sku_id": 1002, "item_quantity": 5 }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "创建成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"combo_code": "COMBO-001",
|
||||
"combo_name": "春节礼包A",
|
||||
"custom_code": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 常见错误
|
||||
|
||||
| 错误信息 | 说明 |
|
||||
|---------|------|
|
||||
| 组合商品编码不能为空 | combo_code 未传或为空 |
|
||||
| 组合商品名称不能为空 | combo_name 未传或为空 |
|
||||
| 子商品列表不能为空 | items 未传或为空数组 |
|
||||
| 组合商品编码 "XXX" 已存在 | combo_code 重复 |
|
||||
| 自定义编码 "XXX" 已被货主其他组合商品使用 | custom_code 在同一货主下重复(排除已删除) |
|
||||
| 以下子商品不存在或已停用:1001, 1002 | 子商品在 wms_stock_warehouse 中不存在或已停用 |
|
||||
| 所有子商品必须属于同一个货主,不允许跨货主组合 | 明细中商品的 store_id 不一致 |
|
||||
|
||||
---
|
||||
|
||||
### 3. comboGoods.update — 编辑组合商品
|
||||
|
||||
- **鉴权**:需要(isNeedAuth=true)
|
||||
- **登录**:需要
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| id | number | 是 | 组合商品ID |
|
||||
| combo_name | string | 否 | 组合商品名称 |
|
||||
| warehouse_id | number | 否 | 仓库ID |
|
||||
| remark | string | 否 | 备注 |
|
||||
| custom_code | string | 否 | 自定义编码,传入非空值时校验按货主唯一(排除已删除记录和自身 id) |
|
||||
| status | number | 否 | 状态:1=启用 0=停用 |
|
||||
| items | array | 否 | 子商品明细数组。传入非空数组时先删旧明细再插入新明细;不传保持原明细不变 |
|
||||
| items[].item_goods_sku_id | number | 是 | 子商品 stock_id |
|
||||
| items[].item_quantity | number | 是 | 子商品数量(正整数) |
|
||||
| items[].sort_order | number | 否 | 排序号 |
|
||||
|
||||
> **注意**:部分更新语义——不传的字段保持原值不变。items 为可选,不传或传空数组则保持原明细不变。
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "comboGoods.update",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"combo_name": "春节礼包A(升级版)",
|
||||
"remark": "更新备注",
|
||||
"items": [
|
||||
{ "item_goods_sku_id": 1001, "item_quantity": 5 },
|
||||
{ "item_goods_sku_id": 1003, "item_quantity": 2 }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "编辑成功",
|
||||
"data": {
|
||||
"id": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. comboGoods.delete — 删除组合商品
|
||||
|
||||
- **鉴权**:需要(isNeedAuth=true)
|
||||
- **登录**:需要
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| id | number | 是 | 组合商品ID |
|
||||
|
||||
> **注意**:删除操作为软删除,仅将 `status` 置为 0(停用),不会物理删除记录。
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "comboGoods.delete",
|
||||
"data": {
|
||||
"id": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "删除成功",
|
||||
"data": {
|
||||
"id": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. comboGoods.search — 关键字搜索组合商品
|
||||
|
||||
- **鉴权**:不需要(isNeedAuth=false)
|
||||
- **登录**:需要
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| keyword | string | 是 | 搜索关键字,模糊匹配 custom_code、combo_code 和 combo_name,custom_code 匹配项优先排在前面 |
|
||||
| limit | number | 否 | 最大返回条数,默认 20,最大 100 |
|
||||
|
||||
> **注意**:仅返回启用状态(status=1)的记录。该接口用于手工建单时前端选择组合商品。
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"method": "comboGoods.search",
|
||||
"data": {
|
||||
"keyword": "礼包",
|
||||
"limit": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "搜索成功",
|
||||
"data": {
|
||||
"list": [
|
||||
{
|
||||
"id": 1,
|
||||
"combo_code": "COMBO-001",
|
||||
"combo_name": "春节礼包A",
|
||||
"custom_code": null,
|
||||
"status": 1,
|
||||
"warehouse_id": 1001,
|
||||
"items": [
|
||||
{ "id": 1, "combo_id": 1, "item_goods_sku_id": 1001, "item_quantity": 3, "sort_order": 0 }
|
||||
],
|
||||
"simpleNotation": "1001|3,1002|5",
|
||||
"nameNotation": "【3】苹果+【5】香蕉"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -1,33 +0,0 @@
|
||||
# Express 模型与数据表整理
|
||||
|
||||
## 一览
|
||||
|
||||
| 模型文件 | Sequelize key | 数据表 | 当前状态 |
|
||||
| --- | --- | --- | --- |
|
||||
| app/model/express.js | Express | wms_express | 已补齐 |
|
||||
| app/model/express_setting.js | ExpressSetting | wms_express_setting | 已补齐 |
|
||||
| app/model/order_express.js | OrderExpress | wms_order_express | 已补齐 |
|
||||
| app/model/order_express_print_data.js | OrderExpressPrintData | wms_order_express_print_data | 已补齐 |
|
||||
| app/model/express_print_record.js | ExpressPrintRecord | wms_express_print_record | 已补齐 |
|
||||
|
||||
## 关键说明
|
||||
|
||||
- 本次仅整理模型与真实数据表对齐,不改动业务逻辑与接口行为。
|
||||
- 通过 `script/db-query.ps1` 实查,数据库中包含 5 张 express 相关表,上述模型已全部覆盖。
|
||||
- 既有字段型快递信息(如 `wms_entry_order.express_code`、`wms_order_delivery.express_code`)仍保留为业务字段,不属于独立主数据表。
|
||||
|
||||
## 建议的后续收敛
|
||||
|
||||
- 将 `index.getExpressList` 的配置源(`app.config.expressList`)逐步收敛到 `wms_express`,避免配置与数据表双源。
|
||||
- 若后续存在统一查询需求,可新增 `systems/express.js`,统一对 `Express / ExpressSetting / OrderExpress` 的读写入口。
|
||||
|
||||
## 包材关联字段说明
|
||||
|
||||
- **新增字段**:`wms_order_express.package_material_id`(可空,BIGINT unsigned)、`wms_order_express.package_material_name_snapshot`(可空,VARCHAR(128))。用于记录订单快递所使用的包材引用与名称快照,`package_material_id` 指向 `wms_package_material.id`。
|
||||
- **新增表**:`wms_package_material`(包材主数据表)和 `wms_package_supplier`(包材供应商表),均已在 migration 与 model 中定义;关键索引:`idx_wms_package_material_warehouse_id`、`uk_wms_package_material_warehouse_material_code`、`idx_wms_package_supplier_warehouse_id`、`uk_wms_package_supplier_warehouse_supplier_code`。
|
||||
- **索引**:为 `wms_order_express.package_material_id` 新增索引 `idx_wms_order_express_package_material_id`,以支持基于包材的过滤与联表查询。
|
||||
- **兼容性**:新增列为可空,不会破坏现有接口契约。若系统存在将 `wms_order_express` 全量返回给外部的接口(未在 methods/system.json 中声明新增字段),请在需要暴露字段的接口中补充文档说明并在变更记录中标注。当前已检查的 system 方法文档未需修改,因此本次不改 methods/system.json(无接口契约变化)。
|
||||
- **回滚要点**:迁移的 down 会删除新增列、索引与新增表;回滚前请务必备份或迁移相关业务数据。
|
||||
|
||||
文档维护者:WMS 文档代理
|
||||
|
||||
@ -1,122 +0,0 @@
|
||||
# 本地文件队列(app.fileWriter)
|
||||
|
||||
本文档说明仓库中提供的本地文件队列写入能力(实现文件:app/lib/file_writer.js),用于把业务数据按 JSON Lines 追加到本地文件并由消费者按需读取处理,适合低延迟、本地持久化、批处理/异步消费场景。
|
||||
|
||||
**实现要点(写入特性)**
|
||||
- 串行写入:同一进程内通过内部队列 `enqueue` 串行化写入,保证单进程内顺序性。
|
||||
- 强制落盘:每次写入使用文件句柄写入并调用 `handle.sync()` 进行 fsync,尽量保证数据落盘。
|
||||
- 自动轮转:当当前文件大小 + 待写入字节数 超过 `maxFileSize` 时,会自增序号并切换到新文件(sequence)。
|
||||
- 自动按行轮转:当单个数据文件累计达到 `maxFileLines` 行后,下一条写入会自动切换到下一个 sequence 文件,默认阈值为 `2000` 行。
|
||||
- 目录结构:默认 baseDir 下按业务与日期分区:
|
||||
- baseDir/<businessSegment>/<YYYY>/<MM>/<DD>/
|
||||
- 文件命名:文件前缀包含业务段与进程标识(`<business>-<machine>-<worker>-p<pid>-<seq>`),尾部带序号与扩展名(`fileExtension`,默认 `.log`)。
|
||||
- 进度(.progress)断点续传:每个消费者使用独立的隐藏进度文件(以 `.<consumerName>.progress` 命名),写入采用临时文件+rename 的原子替换策略,消费端可通过进度恢复消费位置。
|
||||
- Worker/进程隔离:写入文件名包含 `machineId`、`workerId` 与 `pid`,不同进程不会写入同一文件,避免互相竞争。
|
||||
- 清理策略:基于 `retentionDays` 定期删除过期的数据文件与进度文件。
|
||||
|
||||
**目录与文件示例**
|
||||
- 目录:`/path/to/runtime/file-writer/orders/2026/04/09/`
|
||||
- 数据文件示例:`orders-myhost-worker1-p1234-0001.log`
|
||||
- 进度文件示例:`.consumer-1.progress`(位于同一分区目录下)
|
||||
|
||||
**配置项说明(config.fileWriter)**
|
||||
- `baseDir`:基础目录,默认 `path.join(app.baseDir, 'runtime', 'file-writer')`。
|
||||
- `maxFileSize`:单文件最大字节数,超过后轮转。支持数字(字节)或带单位字符串(如 `100M`、`1G`)。默认 `100 * 1024 * 1024`(100MB)。
|
||||
- `maxFileLines`:单文件最大行数,达到后下一条写入会自动轮转到新的 sequence 文件。默认 `2000`。
|
||||
- `retentionDays`:保留天数,超过则删除。设为 `0` 或负值可禁用清理。默认 `7`。
|
||||
- `cleanupIntervalMs`:触发清理的最小间隔(毫秒),写入时会基于此决定是否执行清理,设置为 `0` 或负值可禁用定期清理。默认 `3600000`(1 小时)。
|
||||
- `sequenceWidth`:文件序号宽度(零填充),默认 `4`(例如 `0001`)。
|
||||
- `fileExtension`:数据文件扩展名,默认 `.log`。
|
||||
- `progressExtension`:进度文件扩展名,默认 `.progress`。
|
||||
- `machineId`、`workerId`(可选):可通过配置覆盖,默认使用主机名与 `process.env.EGG_WORKER_ID`。
|
||||
|
||||
默认配置位置:`config/config.default.js` 的 `config.fileWriter` 节点。
|
||||
|
||||
示例(可放入 `config/config.local.js` 覆盖默认):
|
||||
|
||||
```js
|
||||
const path = require('path');
|
||||
|
||||
exports.fileWriter = {
|
||||
baseDir: path.join(__dirname, '..', 'runtime', 'file-writer'),
|
||||
maxFileSize: '200M',
|
||||
maxFileLines: 2000,
|
||||
retentionDays: 14,
|
||||
cleanupIntervalMs: 60 * 60 * 1000,
|
||||
sequenceWidth: 4,
|
||||
fileExtension: '.log',
|
||||
progressExtension: '.progress',
|
||||
// machineId: 'my-host',
|
||||
// workerId: 'worker-1',
|
||||
};
|
||||
```
|
||||
|
||||
**写入示例(业务侧)**
|
||||
简单写入(在任何可以访问 `app` 的位置):
|
||||
|
||||
```js
|
||||
// 在 controller/service 中
|
||||
await app.fileWriter.write('orders', { id: 123, event: 'created', payload: { /* ... */ } });
|
||||
// 返回对象包含 filePath、sequence、bytesWritten 等信息
|
||||
```
|
||||
|
||||
**消费/读取示例(推荐使用 app.fileWriter 提供的 API)**
|
||||
推荐使用 `getProgressFilePath` + `consumeFiles` 提供的断点续传能力:
|
||||
|
||||
```js
|
||||
// 示例:定期或守护进程式消费 orders
|
||||
async function consumeOrders(app) {
|
||||
const writer = app.fileWriter;
|
||||
const progressFile = writer.getProgressFilePath('orders', new Date(), 'order-consumer-1');
|
||||
|
||||
const result = await writer.consumeFiles({
|
||||
businessName: 'orders',
|
||||
progressFilePath: progressFile,
|
||||
onRecord: async (record, meta) => {
|
||||
// record: 解析后的对象
|
||||
// meta: { filePath, offset, index }
|
||||
// 在这里实现消息处理逻辑(去重、入库、调用外部服务等)
|
||||
},
|
||||
parseJson: true,
|
||||
});
|
||||
|
||||
return result; // 包含 processedCount 与最新 progress
|
||||
}
|
||||
```
|
||||
|
||||
如需逐文件手动控制消费,也可使用 `readRecords`:
|
||||
|
||||
```js
|
||||
const res = await app.fileWriter.readRecords(filePath, { startOffset: 0 });
|
||||
for (const rec of res.records) {
|
||||
// 处理 rec
|
||||
}
|
||||
// 手动保存进度
|
||||
await app.fileWriter.saveProgress(progressFilePath, {
|
||||
filePath,
|
||||
offset: res.nextOffset,
|
||||
processedCount: (previousCount || 0) + res.records.length,
|
||||
});
|
||||
```
|
||||
|
||||
**进度文件(.progress)格式**
|
||||
- 保存为 JSON,包含至少字段:`filePath`、`offset`、`processedCount`、`updatedAt`。
|
||||
- 写入采用临时文件写入 + `fsync` + `rename` 的方式尽量保证原子性。
|
||||
|
||||
**注意事项 / 运行时建议**
|
||||
- 不要通过静态文件服务或外部 URL 直接暴露 `baseDir`(例如 `runtime/`),避免被外部下载或篡改。
|
||||
- 多 Worker / 多机部署:
|
||||
- 默认每个进程生成独立的数据文件(文件名包含 `machineId`、`workerId`、`pid`),不会有多个进程同时写入同一文件。若你的设计需要跨进程全局严格顺序,请在上游统一入口合并写入或使用集中式队列(如 Kafka/Redis)。
|
||||
- 消费者可以按进程拆分(针对单进程的文件)或由独立中心消费者按文件目录遍历处理。
|
||||
- 可通过配置显式设置 `machineId`/`workerId` 来标识不同实例。
|
||||
- 关闭或调整清理策略:若需长期保留数据,请将 `retentionDays` 设为合适值或禁用清理(`0` 或负值)。
|
||||
- 性能角度:每次写入触发 fsync 会有性能开销,适合需要高可靠性的场景;若对持久性要求不高,可考虑将写入逻辑改为批量 fsync(此处为实现约束,不建议直接修改核心行为)。
|
||||
|
||||
---
|
||||
|
||||
如果希望在项目首页或工具箱中添加跳转链接,建议把一行链接加入到 [README.md](README.md) 或 [AI_TOOLBOX.md](AI_TOOLBOX.md) 的相关位置,指向本文件 `docs/file-writer.md`。
|
||||
|
||||
----
|
||||
**参考实现位置**
|
||||
- 代码实现:app/lib/file_writer.js
|
||||
- 默认配置:config/config.default.js -> `config.fileWriter`
|
||||
@ -1,255 +0,0 @@
|
||||
# 消息通知事件 API 文档(独立于 system)
|
||||
|
||||
## 1. 文档说明
|
||||
|
||||
本文档描述 **WMS 对外消息通知能力** 的事件 API 约定。
|
||||
|
||||
特点:
|
||||
|
||||
- **独立于 `/system` 接口**
|
||||
- 不走 `method=xxx` 的 system 调用方式
|
||||
- 由内部业务在关键节点触发 `event`
|
||||
- 通过 WebHook 向外部系统推送标准 JSON 消息
|
||||
|
||||
当前已落地事件:
|
||||
|
||||
- `receiving_completed`:收货完成通知
|
||||
- `order_cancel_intercepted`:订单取消失败并触发拦截执行通知
|
||||
- `store_warehouse_print_quantity_adjusted`:货主面单余额人工调整通知
|
||||
|
||||
---
|
||||
|
||||
## 2. 触发方式
|
||||
|
||||
内部业务在以下位置触发:
|
||||
|
||||
- 文件:`app/service/systems/storage/receiving.js`
|
||||
- 方法:`completeReceiving()`
|
||||
- 通知方法:`sendCompletionNotice()`
|
||||
|
||||
触发时机:
|
||||
|
||||
1. 收货单状态更新为 `completed`
|
||||
2. 收货完成 Excel 报表上传成功或已生成完成结果
|
||||
3. 调用:
|
||||
|
||||
```js
|
||||
await ctx.service.systems.notice.send({
|
||||
businessName: 'receiving',
|
||||
event: 'receiving_completed',
|
||||
...
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 事件命名规则
|
||||
|
||||
本能力中,**事件名本身就是通知方法标识**。
|
||||
|
||||
示例:
|
||||
|
||||
| event | 含义 |
|
||||
|---|---|
|
||||
| `receiving_completed` | 收货单完成通知 |
|
||||
| `order_cancel_intercepted` | 订单取消失败并触发拦截执行通知 |
|
||||
| `store_warehouse_print_quantity_adjusted` | 货主面单余额人工调整通知 |
|
||||
|
||||
> 当前正式注册的业务事件包括 `receiving_completed`、`order_cancel_intercepted`、`store_warehouse_print_quantity_adjusted`。
|
||||
|
||||
对于外部订阅方来说,判断消息类型时,优先看:
|
||||
|
||||
- `event`
|
||||
- `businessName`
|
||||
- `message.type`
|
||||
|
||||
命名约束:
|
||||
|
||||
- 仅允许小写字母、数字、下划线
|
||||
- 首字符不能为数字
|
||||
- **禁止使用 `.`**
|
||||
|
||||
---
|
||||
|
||||
## 4. 当前已落地事件:`receiving_completed`
|
||||
|
||||
### 4.1 业务含义
|
||||
|
||||
当仓库完成一张收货单时,系统会向绑定的 WebHook 推送一条 `receiving_completed` 通知。
|
||||
|
||||
### 4.2 推送目标
|
||||
|
||||
由 `wms_notification_webhook` 决定:
|
||||
|
||||
- 先匹配仓库 `warehouseId` 绑定的接口
|
||||
- 若传了 `storeId / ownerId`,再匹配货主绑定的接口
|
||||
- `events` 命中以下任一规则即可推送:
|
||||
- `all`
|
||||
- `*`
|
||||
- `receiving_completed`
|
||||
|
||||
---
|
||||
|
||||
## 5. 请求方式
|
||||
|
||||
对外固定使用:
|
||||
|
||||
```http
|
||||
POST
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 收货完成通知 payload
|
||||
|
||||
### 6.1 字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `traceId` | `string` | 通知追踪 ID |
|
||||
| `event` | `string` | 固定为 `receiving_completed` |
|
||||
| `businessName` | `string` | 固定为 `receiving` |
|
||||
| `warehouseId` | `number` | 仓库 ID |
|
||||
| `storeId` | `number \| null` | 货主 ID,可为空 |
|
||||
| `businessId` | `number` | 收货单 ID |
|
||||
| `occurredAt` | `string` | 发生时间,ISO 格式 |
|
||||
| `subject` | `object` | 当前主体(仓库) |
|
||||
| `store` | `object` | 货主信息 |
|
||||
| `sender` | `object` | 操作人信息 |
|
||||
| `receivers` | `array` | 接收者占位 |
|
||||
| `message` | `object` | 消息主体 |
|
||||
| `metadata` | `object` | 业务扩展信息 |
|
||||
|
||||
### 6.2 示例(带完成报表)
|
||||
|
||||
```json
|
||||
{
|
||||
"traceId": "notice_1775368780099_c6fb8643",
|
||||
"event": "receiving_completed",
|
||||
"businessName": "receiving",
|
||||
"warehouseId": 100000,
|
||||
"storeId": 200000,
|
||||
"businessId": 12345,
|
||||
"occurredAt": "2026-04-05T12:00:00.000Z",
|
||||
"subject": {
|
||||
"id": 100000,
|
||||
"type": "warehouse",
|
||||
"name": "广州仓",
|
||||
"code": "",
|
||||
"config": {
|
||||
"max_notice_webhook_count": 5,
|
||||
"default_express_code": "STO",
|
||||
"default_platform_code": "TB"
|
||||
}
|
||||
},
|
||||
"store": {
|
||||
"id": 200000,
|
||||
"name": "某货主",
|
||||
"businessLicense": "9144XXXXXXXXXXXX",
|
||||
"storeRemask": "华南货主"
|
||||
},
|
||||
"sender": {
|
||||
"id": 10001,
|
||||
"name": "张三"
|
||||
},
|
||||
"receivers": [],
|
||||
"message": {
|
||||
"type": "file",
|
||||
"title": "收货单RCV202604050001已完成",
|
||||
"content": "收货单RCV202604050001已完成,匹配商品10件,未匹配商品0件,总数量120,完成人张三。",
|
||||
"url": "https://cdn.example.com/收货完成_RCV202604050001.xlsx",
|
||||
"fileName": "收货完成_RCV202604050001.xlsx",
|
||||
"mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
||||
"body": "收货单RCV202604050001已完成,匹配商品10件,未匹配商品0件,总数量120,完成人张三。"
|
||||
},
|
||||
"metadata": {
|
||||
"receivingId": 12345,
|
||||
"receivingNumber": "RCV202604050001",
|
||||
"warehouseId": 100000,
|
||||
"storeId": 200000,
|
||||
"stats": {
|
||||
"total_details": 10,
|
||||
"matched_details": 10,
|
||||
"unmatched_details": 0,
|
||||
"total_quantity": 120
|
||||
},
|
||||
"completionReport": {
|
||||
"fileKey": "收货完成_RCV202604050001.xlsx",
|
||||
"url": "https://cdn.example.com/收货完成_RCV202604050001.xlsx"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 返回值约定
|
||||
|
||||
针对当前旧回调接口的约定:
|
||||
|
||||
- 返回 `1` = **成功**
|
||||
- 返回 `0` = **失败**
|
||||
|
||||
---
|
||||
|
||||
## 8. 当前可信结论
|
||||
|
||||
已验证:
|
||||
|
||||
- `GET` 调用旧接口地址可返回 `1`
|
||||
- `POST {}` 可返回 `1`
|
||||
- 手工最小 probe JSON 可返回 `1`
|
||||
|
||||
因此:
|
||||
|
||||
> 若 `receiving_completed` 的统一通知实际推送触发远端错误,优先判断为 **payload 字段结构差异导致的远端解析异常**。
|
||||
|
||||
---
|
||||
|
||||
## 9. 当前已落地事件:`store_warehouse_print_quantity_adjusted`
|
||||
|
||||
### 9.1 业务含义
|
||||
|
||||
当仓库侧对某个货主签约关系执行人工面单余额调整后,系统会向相关 WebHook 推送一条 `store_warehouse_print_quantity_adjusted` 通知。
|
||||
|
||||
### 9.2 推送目标
|
||||
|
||||
由 `wms_notification_webhook` 决定:
|
||||
|
||||
- 匹配签约仓库 `warehouseId` 绑定的接口
|
||||
- 若签约中带有 `storeId`,同步匹配货主绑定的接口
|
||||
- `events` 命中以下任一规则即可推送:
|
||||
- `all`
|
||||
- `*`
|
||||
- `store_warehouse_print_quantity_adjusted`
|
||||
|
||||
### 9.3 metadata 关键字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `contractId` | `number` | 签约关系 ID |
|
||||
| `changeType` | `string` | 当前固定为 `manual_adjust` |
|
||||
| `businessType` | `string \| null` | 业务类型预留字段 |
|
||||
| `businessId` | `number \| null` | 业务关联 ID,预留给 `wms_order_express.id` |
|
||||
| `changeQuantity` | `number` | 本次调整值,整数,可正可负 |
|
||||
| `balanceBefore` | `number` | 调整前余额 |
|
||||
| `balanceAfter` | `number` | 调整后余额 |
|
||||
| `reason` | `string` | 调整缘由 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 后续事件扩展建议
|
||||
|
||||
下一步可继续补充:
|
||||
|
||||
- `receiving_cancelled`
|
||||
- `order_cancelled`
|
||||
- `stock_low`
|
||||
- `stock_changed`
|
||||
- `entry_order_created`
|
||||
- `entry_order_completed`
|
||||
|
||||
保持原则:
|
||||
|
||||
> **一个业务事件 = 一个对外通知 event**
|
||||
@ -1,335 +0,0 @@
|
||||
# 统一消息通知能力文档(草案)
|
||||
|
||||
## 1. 目标
|
||||
|
||||
用于沉淀 WMS 统一消息通知能力的接口结构、数据模型、事件订阅规则与对外推送格式,作为后续构建“消息通知中心 / WebHook 能力”的基础文档。
|
||||
|
||||
---
|
||||
|
||||
## 2. 能力结构
|
||||
|
||||
当前统一发送入口:
|
||||
|
||||
```js
|
||||
await ctx.service.systems.notice.send(options)
|
||||
```
|
||||
|
||||
当前调用链:
|
||||
|
||||
```text
|
||||
业务服务
|
||||
-> ctx.service.systems.notice.send(options)
|
||||
-> normalizePayload(options)
|
||||
-> findMatchedWebhooks(payload)
|
||||
-> GenericWebhookDriver.send({ hook, payload })
|
||||
-> POST JSON 到外部 hook_url
|
||||
```
|
||||
|
||||
代码位置:
|
||||
|
||||
- `app/service/systems/notice/index.js`
|
||||
- `app/service/systems/notice/drivers/generic.js`
|
||||
- `app/model/notification_webhook.js`
|
||||
|
||||
---
|
||||
|
||||
## 3. 相关数据模型
|
||||
|
||||
### 3.1 `wms_notification_webhook`
|
||||
|
||||
用于保存主体绑定的外部 WebHook 配置。
|
||||
|
||||
核心字段:
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| `store_id` | 主体 ID,可绑定到仓库主体或货主主体 |
|
||||
| `hook_name` | WebHook 名称 |
|
||||
| `hook_type` | WebHook 类型,当前支持 `customize` / `wecom` |
|
||||
| `hook_url` | 推送目标地址 |
|
||||
| `events` | 订阅事件列表 |
|
||||
| `status` | 状态,`1=启用`,`0=禁用` |
|
||||
| `remark` | 备注 |
|
||||
|
||||
### 3.2 `wms_store.subject_config`
|
||||
|
||||
用于保存主体级通知配置。
|
||||
|
||||
当前已使用字段:
|
||||
|
||||
| 字段 | 说明 |
|
||||
|---|---|
|
||||
| `max_notice_webhook_count` | 当前主体最多允许绑定 / 触达的消息推送接口数量,默认 `5` |
|
||||
| `default_express_code` | 默认快递编码,默认 `STO` |
|
||||
| `default_platform_code` | 默认平台编码,默认 `TB` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 事件能力结构建议(独立于 `/system`)
|
||||
|
||||
当前更推荐的能力组织方式是:**内部业务事件 = 对外通知方法标识**,而不是先对外包装成 `/system` method。
|
||||
|
||||
推荐结构:
|
||||
|
||||
```text
|
||||
系统内部业务事件
|
||||
-> ctx.service.systems.notice.send(options)
|
||||
-> payload 归一化
|
||||
-> 查找匹配的 webhook
|
||||
-> 按 hook_type 选择 driver
|
||||
-> 推送到外部系统
|
||||
```
|
||||
|
||||
当前已落地示例:
|
||||
|
||||
| event | 说明 |
|
||||
|---|---|
|
||||
| `receiving_completed` | 收货单完成通知 |
|
||||
| `order_cancel_intercepted` | 订单取消失败并触发拦截执行的通知 |
|
||||
|
||||
> 当前正式注册的业务事件包括 `receiving_completed`、`order_cancel_intercepted`;`all` / `*` 作为通配订阅值继续保留。收货完成事件的独立 API 文档见:`docs/notification-event-api.md`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 对内统一发送入参
|
||||
|
||||
`notice.send(options)` 推荐入参如下:
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|---|---|---:|---|
|
||||
| `warehouseId` | `number` | 是 | 仓库 ID |
|
||||
| `storeId` | `number` | 否 | 货主 ID,可空 |
|
||||
| `ownerId` | `number` | 否 | 货主 ID 别名,可空 |
|
||||
| `businessName` | `string` | 是 | 业务名称,如 `receiving` |
|
||||
| `event` | `string` | 否 | 具体事件,如 `receiving_completed` |
|
||||
| `messageType` | `string` | 是 | `text / image / file`,兼容中文 |
|
||||
| `title` | `string` | 否 | 消息标题 |
|
||||
| `content` | `string/object` | 否 | 消息正文 |
|
||||
| `url` | `string` | 条件必填 | 图片 / 文件类型时必填 |
|
||||
| `businessId` | `number|string` | 否 | 业务单据 ID |
|
||||
| `subject` | `object` | 否 | 主体信息 |
|
||||
| `sender` | `object` | 否 | 发送者信息 |
|
||||
| `receivers` | `array` | 否 | 接收者信息 |
|
||||
| `metadata` | `object` | 否 | 扩展元数据 |
|
||||
|
||||
### 5.1 入参约束
|
||||
|
||||
- `warehouseId` **必传**
|
||||
- `storeId / ownerId` **允许为空**
|
||||
- `messageType = image / file` 时,`url` **必填**
|
||||
- `event` 命名仅允许小写字母、数字、下划线,且首字符不能为数字;**禁止使用 `.`**
|
||||
|
||||
---
|
||||
|
||||
## 6. 对外统一推送 payload
|
||||
|
||||
当前对外固定为:`POST + application/json`
|
||||
|
||||
示例:
|
||||
|
||||
```json
|
||||
{
|
||||
"traceId": "notice_xxx",
|
||||
"event": "receiving_completed",
|
||||
"businessName": "receiving",
|
||||
"warehouseId": 100000,
|
||||
"storeId": 200000,
|
||||
"businessId": 123,
|
||||
"occurredAt": "2026-04-05T12:00:00.000Z",
|
||||
"subject": {
|
||||
"id": 100000,
|
||||
"type": "warehouse",
|
||||
"name": "广州仓",
|
||||
"code": "",
|
||||
"config": {
|
||||
"max_notice_webhook_count": 5,
|
||||
"default_express_code": "STO",
|
||||
"default_platform_code": "TB"
|
||||
}
|
||||
},
|
||||
"store": {
|
||||
"id": 200000,
|
||||
"name": "某货主",
|
||||
"businessLicense": "9144XXXXXXXXXXXX",
|
||||
"storeRemask": "华南货主"
|
||||
},
|
||||
"sender": {},
|
||||
"receivers": [],
|
||||
"message": {
|
||||
"type": "text",
|
||||
"title": "收货完成",
|
||||
"content": "收货单已完成",
|
||||
"url": "",
|
||||
"fileName": "",
|
||||
"mimeType": "",
|
||||
"body": "收货单已完成"
|
||||
},
|
||||
"metadata": {
|
||||
"source": "system"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 事件订阅规则
|
||||
|
||||
`events` 字段建议使用数组。
|
||||
|
||||
支持写法:
|
||||
|
||||
| 写法 | 含义 |
|
||||
|---|---|
|
||||
| `all` | 接收全部已注册通知 |
|
||||
| `*` | 兼容旧配置,等价于 `all` |
|
||||
| `receiving_completed` | 只接收收货完成事件 |
|
||||
| `order_cancel_intercepted` | 只接收订单取消拦截事件 |
|
||||
|
||||
> 若需新增其他事件,必须先在 `app/model/notification_webhook.js` 完成注册,否则发送入口会直接拒绝。
|
||||
|
||||
当前订单取消拦截通知由 `app/service/qimenMethods/order.js` 在拣货状态或打印状态未结束时发送,事件码为 `order_cancel_intercepted`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 命中与分发规则
|
||||
|
||||
当前 `findMatchedWebhooks(payload)` 逻辑:
|
||||
|
||||
1. 先判断 `warehouseId`,并查询该仓库主体绑定的启用接口
|
||||
2. 若 `storeId / ownerId` 非空,再查询该货主绑定的启用接口
|
||||
3. 过滤条件:
|
||||
- `status = 1`
|
||||
- `events` 命中当前消息
|
||||
4. 去重规则:
|
||||
- 优先按 `id`
|
||||
- 无 `id` 时按 `hook_url`
|
||||
5. 最终按 `subject_config.max_notice_webhook_count` 限制最大推送数量
|
||||
|
||||
---
|
||||
|
||||
## 9. 货主信息补充与缓存
|
||||
|
||||
若传了 `storeId / ownerId`,当前会补齐货主信息:
|
||||
|
||||
- `wms_store.business_license`
|
||||
- `wms_store_warehouse.store_remask`
|
||||
|
||||
缓存键:
|
||||
|
||||
```text
|
||||
warehouse:{warehouseId}store:{storeId}:info
|
||||
```
|
||||
|
||||
缓存 TTL:
|
||||
|
||||
```text
|
||||
600 秒
|
||||
```
|
||||
|
||||
查询顺序:
|
||||
|
||||
1. 优先读缓存
|
||||
2. 缓存未命中再查数据库
|
||||
3. 查到后回填缓存
|
||||
4. 若为空,则推送字段也保持空字符串
|
||||
|
||||
---
|
||||
|
||||
## 10. 回调返回值约定
|
||||
|
||||
对于现有旧接口(如 `notic`、`notic2`)的可信判定约定:
|
||||
|
||||
- 返回 `1` = **成功**
|
||||
- 返回 `0` = **失败**
|
||||
|
||||
---
|
||||
|
||||
## 11. 当前可信结论
|
||||
|
||||
已验证:
|
||||
|
||||
- `GET` 请求可通
|
||||
- `POST` 请求可通
|
||||
- `POST {}` 可返回 `1`
|
||||
- 手工最小 probe payload 可返回 `1`
|
||||
|
||||
因此:
|
||||
|
||||
> 若统一 `notice.send()` 的实际推送触发远端报错,优先判断为 **payload 字段结构差异导致的远端解析问题**,而不是地址或请求方式问题。
|
||||
|
||||
---
|
||||
|
||||
## 12. 新增功能需要通知时怎么接入
|
||||
|
||||
当其他功能模块需要新增通知时,建议按下面 4 步接入,避免各自重复造轮子:
|
||||
|
||||
### 12.1 注册事件
|
||||
|
||||
先在 `app/model/notification_webhook.js` 的 `AVAILABLE_EVENTS` 中登记新的事件编码。
|
||||
|
||||
要求:
|
||||
|
||||
- 事件名仅允许小写字母、数字、下划线
|
||||
- 首字符不能为数字
|
||||
- **禁止使用 `.`**
|
||||
- 未注册的事件,`notice.send()` 会直接拒绝发送
|
||||
|
||||
### 12.2 在业务 service 调用统一入口
|
||||
|
||||
在实际业务 service 中调用:
|
||||
|
||||
```js
|
||||
await ctx.service.systems.notice.send({
|
||||
warehouseId,
|
||||
storeId, // 可选,也可传 ownerId
|
||||
businessName: 'your_business',
|
||||
event: 'your_event_code',
|
||||
messageType: 'text',
|
||||
title: '通知标题',
|
||||
content: '通知内容',
|
||||
businessId,
|
||||
subject,
|
||||
sender,
|
||||
metadata,
|
||||
});
|
||||
```
|
||||
|
||||
接入原则:
|
||||
|
||||
- `warehouseId` 必传,`storeId / ownerId` 可空
|
||||
- 业务侧只负责组装业务语义并调用统一入口
|
||||
- 重试、分发、失败日志由 `app/service/systems/notice/index.js` 统一处理
|
||||
- 如需图片 / 文件通知,补充 `url`、`fileName`、`mimeType`
|
||||
|
||||
### 12.3 测试验证
|
||||
|
||||
至少补 2 类验证:
|
||||
|
||||
1. **notice 能力测试**:确认事件注册、WebHook 命中、payload 结构与失败处理符合预期
|
||||
- 参考:`test/app/service/systems/notice.test.js`
|
||||
2. **业务回归测试**:确认业务节点确实会触发通知调用
|
||||
- 参考:`test/app/service/systems/storage.receiving.report.test.js`
|
||||
|
||||
若对接的是外部地址,还应额外确认:
|
||||
|
||||
- 返回结果是否符合成功约定(如 `1` / `ok` / `errcode=0`)
|
||||
- 对方是否能正确解析当前 JSON payload
|
||||
|
||||
### 12.4 文档同步
|
||||
|
||||
接入完成后,至少同步以下文档:
|
||||
|
||||
- 本文档:补能力边界、接入规则或命中说明
|
||||
- `docs/notification-event-api.md`:新增事件说明与 payload 示例
|
||||
- 若对外暴露了新的 `/system` 接口或 method,再按需同步 `methods/*.json`
|
||||
|
||||
## 13. 后续扩展建议
|
||||
|
||||
建议后续继续补充:
|
||||
|
||||
1. 通知发送日志表
|
||||
2. 重试队列 / 死信队列
|
||||
3. 回调签名与鉴权
|
||||
4. WebHook 健康检查
|
||||
5. 失败告警与监控面板
|
||||
6. system 接口文档同步到 `methods/system.json`
|
||||
@ -1,97 +0,0 @@
|
||||
# 订单取消 / 状态机 — 库表核对清单(§0.7 执行用)
|
||||
|
||||
> 用途:实施 `order_todo.md` **§2.3a(取消进 M4)** 前,对 **`wms_order_delivery` 及分表** 做只读核对。
|
||||
> 不改变数据库;核对结果记录在工单或 `order_todo.md` 修订记录。
|
||||
|
||||
**PowerShell 提示**:`db-query.ps1` 若遇 **`ConvertFrom-Json` 无效 JSON**(中文注释导致编码问题),可在同一会话先执行 **`chcp 65001`** 再跑查询。
|
||||
|
||||
## 1. 列出本库所有发货单相关表
|
||||
|
||||
```sql
|
||||
SELECT TABLE_NAME
|
||||
FROM INFORMATION_SCHEMA.TABLES
|
||||
WHERE TABLE_SCHEMA = DATABASE()
|
||||
AND (
|
||||
TABLE_NAME = 'wms_order_delivery'
|
||||
OR TABLE_NAME REGEXP '^wms_order_delivery_[0-9]+(_history)?$'
|
||||
)
|
||||
ORDER BY TABLE_NAME;
|
||||
```
|
||||
|
||||
## 2. 对每张表核对关键列是否存在
|
||||
|
||||
将 `YOUR_TABLE` 替换为上一步的表名(含模板表 `wms_order_delivery` 与各仓 `wms_order_delivery_{wh}` / `_history`)。
|
||||
|
||||
```sql
|
||||
SELECT COLUMN_NAME, DATA_TYPE, COLUMN_TYPE, IS_NULLABLE, COLUMN_COMMENT
|
||||
FROM INFORMATION_SCHEMA.COLUMNS
|
||||
WHERE TABLE_SCHEMA = DATABASE()
|
||||
AND TABLE_NAME = 'YOUR_TABLE'
|
||||
AND COLUMN_NAME IN (
|
||||
'status',
|
||||
'intercept_status',
|
||||
'step',
|
||||
'outbound_status',
|
||||
'inspection_status',
|
||||
'delivery_time',
|
||||
'updated_at',
|
||||
'create_at'
|
||||
)
|
||||
ORDER BY COLUMN_NAME;
|
||||
```
|
||||
|
||||
## 3. 结论填写(人工)
|
||||
|
||||
| 检查项 | 是否满足「取消进 M4」筛选与展示 |
|
||||
|--------|----------------------------------|
|
||||
| `status` 含 `cancel` 枚举(与 ORM 一致) | |
|
||||
| `intercept_status` 含 `cancelled` 等 | |
|
||||
| `step` 存在且含「9=已关闭」语义 | |
|
||||
| 若产品要求 **独立「取消进 M4」列** | 缺则走 migration + 模型 + 工厂 DDL |
|
||||
|
||||
## 4. 参考
|
||||
|
||||
- 模型枚举源:`app/model/order_delivery.js`(`StatusEnum`、`step` 注释)
|
||||
- 规划说明:仓库根目录 `order_todo.md` §0.7、§2.3a
|
||||
|
||||
---
|
||||
|
||||
## 5. wms-db-agent 诊断记录(本机一次抽样,2026-04-10)
|
||||
|
||||
> 工具:`script/db-query.ps1`,client **`wms`**,`DATABASE() = wms`。以下为 **只读** 结果摘要;其它环境须自行重跑 §1~§2。
|
||||
|
||||
### 5.1 匹配到的表
|
||||
|
||||
| TABLE_NAME |
|
||||
|------------|
|
||||
| `wms_order_delivery`(基表/模板) |
|
||||
| `wms_order_delivery_100000` |
|
||||
| `wms_order_delivery_1000028` |
|
||||
|
||||
本库本次 **未发现** `*_history` 表。
|
||||
|
||||
### 5.2 目标列是否存在(Y/N)
|
||||
|
||||
| TABLE_NAME | status | intercept_status | step | outbound_status | inspection_status |
|
||||
|------------|:------:|:----------------:|:----:|:---------------:|:-----------------:|
|
||||
| `wms_order_delivery` | Y | **N** | Y | **N** | **N** |
|
||||
| `wms_order_delivery_100000` | Y | Y | Y | Y | Y |
|
||||
| `wms_order_delivery_1000028` | Y | Y | Y | Y | Y |
|
||||
|
||||
`delivery_time` / `updated_at` / `create_at` 三张表均有(基表 `updated_at`/`create_at` 为 YES)。
|
||||
|
||||
### 5.3 与 §0.7 / §2.3a 的对照结论
|
||||
|
||||
- **分表**(`_100000`、`_1000028`):§0.7 所列 **`status` / `intercept_status` / `step` / `outbound_status` / `inspection_status`** 均存在;`intercept_status` 含 **`cancelled`**,`status` 含 **`cancel`**;**可先不增列**,用组合条件做「取消进 M4」筛选(产品确认 WHERE 口径即可)。
|
||||
- **基表** `wms_order_delivery`:**缺** `intercept_status`、`outbound_status`、`inspection_status`;**业务筛选勿依赖基表**,以 **`wms_order_delivery_{warehouseId}`** 为准。
|
||||
- **枚举差异**:不同物理表上 **`status` 的 enum 集合不一致**(基表与分表、分表之间均有差异);规则与迁移须 **按仓/按表** 评估,勿假设全局一致。
|
||||
- **全量**:当前仅抽样 2 张分表;生产请对 **全部** `wms_order_delivery_*` 重跑本清单;若有 **`_history`** 须单独对齐列集。
|
||||
|
||||
### 5.4 §3 结论栏(代填,可改)
|
||||
|
||||
| 检查项 | 是否满足「取消进 M4」筛选与展示 |
|
||||
|--------|----------------------------------|
|
||||
| `status` 含 `cancel` 枚举(与 ORM 一致) | **分表:是**;基表:部分(见上 enum 差异) |
|
||||
| `intercept_status` 含 `cancelled` 等 | **分表:是**;**基表:无此列** |
|
||||
| `step` 存在且含「9=已关闭」语义 | **是**(int NOT NULL,注释一致) |
|
||||
| 若产品要求 **独立「取消进 M4」列** | **未检出有**;若需要仍须 migration(见 `order-delivery-migration-impact.md`) |
|
||||
@ -1,62 +0,0 @@
|
||||
# `wms_order_delivery*` / `wms_order_items*` 库表变更 — 影响面分析(供决策)
|
||||
|
||||
> 目的:回答「改库是否影响当前所有涉及 order 发货单表的逻辑」;**未连真实库**,结论基于代码静态分析。
|
||||
> 关联:`order_todo.md` §0.7、§2.3a;核对清单 `docs/order-cancel-db-checklist.md`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 结论摘要(是否可直接做迁移)
|
||||
|
||||
| 变更类型 | 对现有逻辑的典型影响 | 建议 |
|
||||
|----------|----------------------|------|
|
||||
| **仅核对列已存在、不做 DDL** | 无 | **推荐先做**(清单 `order-cancel-db-checklist.md`) |
|
||||
| **新增可空列 + 默认值**(`NULL` 默认 / `DEFAULT`) | Sequelize `create`/`update`/`find` 一般 **不崩**;未赋值的 `create` 不写该列则用库默认 | **低面影响**,但仍须 **同步** `app/model/order_delivery.js` + `order_delivery_factory.js` 的 `createPhysicalTable` DDL,且 **所有已存在分表** 需同一 migration 补列 |
|
||||
| **新增 NOT NULL 无默认** | 旧 `create`/`bulkCreate` 可能 **插入失败** | **高面影响**,**禁止**在未改全链路前做 |
|
||||
| **改 ENUM 取值 / 删列 / 改列类型** | `order.*` 列表 where、奇门/入库、报表可能 **全链路受影响** | **高面影响**,须单独评审与回归 |
|
||||
| **仅改索引 / 注释**(不改列语义) | 一般低;大表加索引注意锁表 | 可个案评估 |
|
||||
|
||||
**当前结论(在未跑 §0.7 清单、未选定「取消进 M4」专用列名之前):**
|
||||
**不在仓库内自动提交新的 `ALTER` migration。** 代码侧已具备 `status.cancel`、`intercept_status.cancelled`、`step`(含 9 关闭)等枚举(见 `order-state-machine-dictionary.md`),**若跑库确认列已齐全,则「取消进 M4」可先不增列,仅做应用筛选逻辑** — 此时 **无需表迁移**。
|
||||
若跑库确认 **缺列** 或产品 **强制** 要独立标记列 → **属有面影响变更**,请在你确认 **列名、类型、默认值、是否只加 current 或含 history** 后再做 migration。
|
||||
|
||||
**(已更新)** 本机 `wms` 库经 **wms-db-agent** 只读抽样结果见 **`docs/order-cancel-db-checklist.md` §5**:两张分表目标列齐全,**可先不增列**;基表缺列、勿作业务筛选;全量仓与 `_history` 须另跑。
|
||||
|
||||
---
|
||||
|
||||
## 2. 代码侧「会吃到表结构」的路径
|
||||
|
||||
### 2.1 动态模型来源(关键)
|
||||
|
||||
- `OrderDeliveryFactory` / `OrderItemsFactory` 使用 **`app.model.OrderDelivery.rawAttributes`**(及 `OrderItems`)**动态 `define` 每张分表**。
|
||||
- **新建物理表**时,`createPhysicalTable` 内 **手写 DDL 片段** 与模型字段 **必须长期一致**,否则新仓新表与 ORM 不一致。
|
||||
|
||||
### 2.2 业务入口(非穷举,均为 `getCurrentModel` 链)
|
||||
|
||||
| 区域 | 文件 |
|
||||
|------|------|
|
||||
| System 订单 method | `app/service/systemMethods/order/*.js`(经 `base.js#getOrderModels`) |
|
||||
| 业务发货单 | `app/service/systems/delivery_order.js`(`create` / `update` / `bulkCreate` 明细等) |
|
||||
| 奇门 | `app/service/qimenMethods/deliveryorder.js` |
|
||||
| 测试 / 探针 | `app/service/apiMethods/test.js`(命名 `WmsOrderDeliveryFactory` 需与挂载一致,否则仅测试路径) |
|
||||
|
||||
### 2.3 写入方式
|
||||
|
||||
- `DeliveryModel.create(orderData)`、`OrderItemsModel.bulkCreate(lineData)`:**对象字段驱动**;新增 **可空** 列且模型已声明时,旧代码路径 **通常无需改** 即可插入。
|
||||
|
||||
---
|
||||
|
||||
## 3. 若你决定「要做加列迁移」时的必做清单
|
||||
|
||||
1. 产品确认:**列名、含义、是否可空、默认值、是否写 history 表**。
|
||||
2. Migration:`findOrderDeliveryTables` 风格 **遍历** `wms_order_delivery` / `wms_order_delivery_*`(及若需要则 `wms_order_items_*`)。
|
||||
3. `app/model/order_delivery.js` 增加字段定义。
|
||||
4. `app/model/order_delivery_factory.js` 中 **`createPhysicalTable`** 同步列定义。
|
||||
5. 回归:`npm run test:local` 中与 `delivery_order` / `order` 相关用例;奇门若有联调则单独测。
|
||||
|
||||
---
|
||||
|
||||
## 4. 修订
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-04-10 | 初版:静态影响面结论;**未提交 migration** |
|
||||
@ -1,45 +0,0 @@
|
||||
# 订单发货单 — 状态机字段字典(骨架 v0)
|
||||
|
||||
> **单一事实来源(代码)**:`app/model/order_delivery.js` 内 `StatusEnum` 与 `step` 定义。
|
||||
> 本文档为 **v0 骨架**:便于产品 / 数仓 / 报表对齐;**与数仓字段映射、变更登记** 在后续迭代补全(见 `order_todo.md` §5.2)。
|
||||
|
||||
## 1. 主状态与步骤
|
||||
|
||||
| 字段 | 类型(ORM) | 枚举或取值 | 说明(摘自模型注释) |
|
||||
|------|-------------|------------|----------------------|
|
||||
| `status` | ENUM | `pedding`, `created`, `cancel`, `error` | 订单状态 |
|
||||
| `step` | INTEGER | `0` 未审核,`1` 已审核,`2` 处理中,`3` 驳回/异常,`4` 配送中,`5` 已完成,`9` 已关闭 | 订单步骤 |
|
||||
|
||||
## 2. 各环节状态机(ENUM)
|
||||
|
||||
| 字段 | 枚举值 |
|
||||
|------|--------|
|
||||
| `sync_status` | `padding`, `fin`, `error` |
|
||||
| `post_status` | `padding`, `fin`, `timeout`, `error`, `none` |
|
||||
| `storage_status` | `padding`, `fin`, `error`, `none` |
|
||||
| `pick_status` | `padding`, `fin`, `error`, `none` |
|
||||
| `pack_status` | `none`, `padding`, `fin`, `error` |
|
||||
| `inspection_status` | `none`, `padding`, `running`, `fin`, `error` |
|
||||
| `print_status` | `none`, `padding`, `fin`, `error` |
|
||||
| `claim_status` | `none`, `padding`, `fin`, `error` |
|
||||
| `outbound_status` | `none`, `padding`, `fin`, `error` |
|
||||
| `lock_status` | `none`, `warehouse`, `store` |
|
||||
| `intercept_status` | `none`, `requesting`, `requested`, `intercepting`, `intercepted_in_transit`, `intercepted_at_warehouse`, `returning`, `returned`, `delivered_by_mistake`, `timeout`, **`cancelled`**, `failed`, `exception` |
|
||||
|
||||
## 3. 其它与展示相关(非 ENUM)
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `delivery_time` | 发货时间;与 M6 出库时间策略相关 |
|
||||
| `create_at` / `updated_at` | 创建 / 更新时间 |
|
||||
|
||||
## 4. 待产品补充(v1+)
|
||||
|
||||
- 「取消进 M4」专用标记:若不用 `status`/`step`/`intercept_status` 组合表达,则 **新增列** 后的字典条目与数仓同步表。
|
||||
- 与奇门 **不同步** 的克隆续单字段(见 `order_todo.md` §2.4)。
|
||||
|
||||
## 5. 修订
|
||||
|
||||
| 版本 | 说明 |
|
||||
|------|------|
|
||||
| v0 | 自 `order_delivery.js` 摘录枚举骨架,无 DB 变更 |
|
||||
@ -1,188 +0,0 @@
|
||||
# 订单工作台 List 接口说明
|
||||
|
||||
本文档说明订单工作台(Order Workbench)中可用的 list 接口、参数约定、返回结构与行为要点。
|
||||
|
||||
**变更记录**
|
||||
- 本次已在 methods/system.json 中补充以下 method 定义,并在 methods/changes/system.json 中追加变更记录(参见变更文件),用于对外说明新增的 list 接口与分页/where 支持。
|
||||
|
||||
**新增/确认的接口(method 名称,主入口)**
|
||||
- order.list —— 订单工作台总列表入口(汇总所有分组)
|
||||
- order.reviewOrder.list —— 待审核订单工作台(step=0)
|
||||
- order.pendingOrder.list —— 待处理订单工作台(step in [1,2])
|
||||
- order.expectionOrder.list —— 待处理异常订单工作台(step=3)
|
||||
- order.entrustOrder.list —— 委托外仓订单工作台(outsourced 模型)
|
||||
- order.deliveryOrder.list —— 配送订单工作台(dispatch 模型,dispatch_lane=m4)
|
||||
- order.deliveryExpectionOrder.list —— 配送异常订单工作台(dispatch 模型,dispatch_lane=m5)
|
||||
- order.archiveOrder.list —— 归档订单工作台(history 模型)
|
||||
|
||||
兼容说明:代码中存在若干旧兼容入口(例如 getreviewOrderlist、getdeliveryOrderlist、getpendingOrderlist、getexpectionOrderlist、getentrustOrderlist、getarchiveOrderlist 等),这些为兼容旧调用保留的旧名入口,不作为首选主入口;建议新调用使用上文列出的主入口。
|
||||
|
||||
**工作台语义(简要)**
|
||||
- order.list:总列表入口,返回跨分组的订单集合,适用于需要不分组的通用搜索/分页场景。
|
||||
- reviewOrder:待审核(审核步骤为未审核)工作台,用于审核操作筛选与展示(默认 step=0)。审核提交接口仅接收 ids,批量审核,严格同仓校验,不做兼容。
|
||||
- pendingOrder:待处理工作台,通常包含需要人工或系统继续处理的订单(默认 step in [1,2])。
|
||||
- expectionOrder:异常工单集合(默认 step=3),用于定位异常状态订单。
|
||||
- entrustOrder:委托外仓相关订单,使用 outsourced 模型。
|
||||
- deliveryOrder / deliveryExpectionOrder:配送相关工作台,使用 dispatch 模型,分别以 dispatch_lane=m4 / m5 筛选。
|
||||
- archiveOrder:归档历史订单,使用 history 模型。
|
||||
|
||||
实现要点(参考实现位于 app/service/systemMethods/order/*):
|
||||
- 模块实现会根据模块名选择不同物理模型(current / dispatch / outsourced / history),由 OrderBaseService#getOrderModel 决定。
|
||||
- 每个模块还定义了 `defaultWhere`(例如 reviewOrder 的 step=0 等),请求的 `where` 会与模块默认条件合并后一起用于构造最终查询。
|
||||
|
||||
参数说明(公共约定)
|
||||
- pagination: object
|
||||
- pagination.page: number(可选),页码,从 1 开始,默认 1。
|
||||
- pagination.pageSize: number(可选),每页条数,默认 20。注意:服务端对 pageSize 做上限截断,最大不可超过 200(见下)。
|
||||
- where: object(可选)
|
||||
- 统一的筛选条件对象;支持两种写法:
|
||||
- 标准化结构:{ field: { operator: 'eq'|'in'|'like'|..., value: ..., type?: 'string'|'number' } }
|
||||
- 简写:{ field: value }(会被自动转换为 { operator: 'eq', value } 或在传数组时转换为 in)
|
||||
- 服务端会先对 where 做 normalize(兼容简写与 values 字段),再走 parseWhereConditions 生成底层查询条件,最后与模块的 defaultWhere 合并(后者优先级低于请求入参)。
|
||||
- 常见可用字段:id、delivery_order_code、order_status、dispatch_lane、quickWhere 等(具体过滤字段以实现解析器支持为准)。
|
||||
- sort: object(可选)
|
||||
- 支持 sortField / sortOrder 或 field / order;实现层会映射到允许的字段集合(如 id、step、status、delivery_time、updated_at 等),默认按 updated_at DESC, id DESC。
|
||||
|
||||
分页/大小限制
|
||||
- 默认 pageSize=20。
|
||||
- 最大 pageSize: 200(服务端在 normalizePagination 中对 pageSize 做截断,防止单次请求返回过大数据)。调用方仍应合理控制 pageSize,避免前端一次性请求过多数据。
|
||||
|
||||
返回结构(公共约定)
|
||||
- list: array — 当前页的记录数组(每项为订单对象的序列化行,字段视具体模型与序列化而定)。
|
||||
- pagination: object
|
||||
- pagination.page: number — 当前页
|
||||
- pagination.pageSize: number — 每页条数(实际返回值为服务端截断后的值)
|
||||
- pagination.total: number — 符合条件的总记录数
|
||||
- pagination.totalPages: number
|
||||
- pagination.hasPrevious / hasNext: boolean
|
||||
|
||||
订单列表 raw 字段字典(通用)
|
||||
- 说明:以下字段为所有订单列表的 raw 基础字段;`order.deliveryOrder.list` 和 `order.deliveryExpectionOrder.list` 额外包含 `dispatch_lane`;服务层还会补充 `express_numbers` 与 `waybill_codes` 两个派生字段,二者内容一致,都是该订单绑定的多个快递号。
|
||||
|
||||
| 字段 | 类型 | 中文语义 | 枚举/说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | number | 订单主键 ID | 订单记录主键 |
|
||||
| delivery_order_code | string | 发货单号 | 订单单号 |
|
||||
| pre_delivery_order_code | string | 预发货单号 | 预发货阶段单号 |
|
||||
| pre_delivery_order_id | string | 预发货单ID | 预发货记录关联 ID |
|
||||
| order_type | string | 订单类型 | 业务类型标识 |
|
||||
| warehouse_code | string | 仓库编码 | 仓库基础编码 |
|
||||
| order_flag | string | 订单标记 | 订单标签/标记信息 |
|
||||
| source_platform_code | string | 来源平台编码 | 原始平台编码 |
|
||||
| source_platform_name | string | 来源平台名称 | 原始平台名称 |
|
||||
| sys_platform_code | string | 系统平台编码 | 系统内平台编码 |
|
||||
| sys_platform_name | string | 系统平台名称 | 系统内平台名称 |
|
||||
| create_at | string | 创建时间 | ISO 时间字符串 |
|
||||
| delete_at | string | 删除时间 | ISO 时间字符串,通常为空 |
|
||||
| updated_at | string | 更新时间 | ISO 时间字符串 |
|
||||
| place_order_time | string | 店铺创建订单时间 | 平台下单时间 |
|
||||
| pay_time | string | 支付时间 | 支付完成时间 |
|
||||
| pay_no | string | 支付单号 | 支付流水号 |
|
||||
| service_code | string | 集包服务编码 | 集包/服务编码 |
|
||||
| operator_name | string | ERP审核人 | 审核人姓名 |
|
||||
| operate_time | string | ERP审核时间 | 审核时间 |
|
||||
| delivery_time | string | 发货时间 | 发货完成时间 |
|
||||
| shop_nick | string | 店铺名称 | 店铺昵称 |
|
||||
| seller_nick | string | 卖家名称 | 卖家昵称 |
|
||||
| buyer_nick | string | 买家名称 | 买家昵称 |
|
||||
| total_amount | number | 订单总金额 | 金额字段,保留两位小数 |
|
||||
| item_amount | number | 商品总金额 | 金额字段,保留两位小数 |
|
||||
| discount_amount | number | 订单折扣金额 | 金额字段,保留两位小数 |
|
||||
| freight | number | 快递费用 | 金额字段,保留两位小数 |
|
||||
| ar_amount | number | 应收金额 | 金额字段,保留两位小数 |
|
||||
| got_amount | number | 已收金额 | 金额字段,保留两位小数 |
|
||||
| service_fee | number | COD服务费 | 金额字段,保留两位小数 |
|
||||
| logistics_code | string | 物流公司编码 | 物流公司编码 |
|
||||
| logistics_name | string | 物流公司名称 | 物流公司名称 |
|
||||
| sys_logistics_code | string | 系统物流公司编码 | 系统内物流编码 |
|
||||
| sys_logistics_name | string | 系统物流公司名称 | 系统内物流名称 |
|
||||
| express_code | string | 面单号前置 | 面单号前缀 |
|
||||
| logistics_area_code | string | 快递区域编码 | 大头笔/区域编码 |
|
||||
| delivery_type | string | 发货服务类型 | 发货方式 |
|
||||
| is_urgency | enum | 是否紧急 | Y=是,N=否 |
|
||||
| invoice_flag | enum | 是否需要发票 | Y=需要,N=不需要 |
|
||||
| status | enum | 订单状态 | pedding=待处理,created=已创建,cancel=已取消,error=异常 |
|
||||
| name | string | 收件人姓名 | 收件人 |
|
||||
| zip_code | string | 收件人邮编 | 邮编 |
|
||||
| tel | string | 收件人电话 | 电话号码 |
|
||||
| mobile | string | 收件人移动电话 | 手机号 |
|
||||
| email | string | 收件人邮箱 | 邮箱 |
|
||||
| country_code | string | 国家编码 | 国家/地区编码 |
|
||||
| province | string | 省份 | 收件地址省 |
|
||||
| city | string | 城市 | 收件地址市 |
|
||||
| area | string | 区 | 收件地址区 |
|
||||
| town | string | 镇 | 收件地址镇 |
|
||||
| detail_address | string | 详细地址 | 街道/门牌详情 |
|
||||
| id_type | string | 证件类型 | 证件类型 |
|
||||
| id_number | number | 证件号码 | 证件号 |
|
||||
| oaid | string | OAID | 设备/终端标识 |
|
||||
| sync_status | enum | 同步状态 | padding=待同步,fin=完成,error=失败 |
|
||||
| store_id | number | 货主ID | 货主主键 |
|
||||
| store_remark | string | 货主备注 | 来自 wms_store_warehouse.store_remask,服务层按 store_id+warehouse_id 聚合填充 |
|
||||
| warehouse_id | number | 仓库ID | 仓库主键 |
|
||||
| from_key | number | 来源键 | 来源系统键值 |
|
||||
| items | string | 商品JSON字符串 | 原始商品明细 JSON |
|
||||
| items_count | number | 商品种类数 | SKU 种类数 |
|
||||
| items_total | number | 商品总数 | 商品件数总和 |
|
||||
| items_weight | number | 总重量(kg) | 总重量 |
|
||||
| items_hash | string | MD5哈希值(32位) | 商品明细哈希 |
|
||||
| items_crc | number | CRC32校验码 | 商品明细校验码 |
|
||||
| wave_id | number | 波次ID | 0 表示未分配 |
|
||||
| wave_no | string | 波次号 | 空字符串表示未分配 |
|
||||
| post_status | enum | 分配快递号状态机 | padding=处理中,fin=完成,timeout=超时,error=失败,none=未开始 |
|
||||
| storage_status | enum | 分配储位状态机 | padding=处理中,fin=完成,error=失败,none=未开始 |
|
||||
| pick_status | enum | 拣货状态机 | padding=处理中,fin=完成,error=失败,none=未开始 |
|
||||
| pack_status | enum | 打包状态机 | none=未开始,padding=处理中,fin=完成,error=失败 |
|
||||
| inspection_status | enum | 检验状态机 | none=未开始,padding=处理中,running=进行中,fin=完成,error=失败 |
|
||||
| step | number | 订单步骤 | 0=未审核,1=已审核,2=处理中,3=驳回/异常,4=配送中,5=已完成,9=已关闭 |
|
||||
| print_status | enum | 打印状态机 | none=未开始,padding=处理中,fin=完成,error=失败 |
|
||||
| claim_status | enum | 领取状态机 | none=未开始,padding=处理中,fin=完成,error=失败 |
|
||||
| outbound_status | enum | 出库状态机 | none=未开始,padding=处理中,fin=完成,timeout=超时,error=失败 |
|
||||
| lock_status | enum | 锁定状态机 | none=未锁定,warehouse=仓库锁定,store=货主锁定 |
|
||||
| intercept_status | enum | 拦截状态机 | none=未拦截,requesting=请求中,requested=已请求,intercepting=拦截中,intercepted_in_transit=运输中拦截成功,intercepted_at_warehouse=仓库拦截成功,returning=退回中,returned=已退回,delivered_by_mistake=误签收,timeout=超时,cancelled=已取消,failed=失败,exception=异常 |
|
||||
| dispatch_lane | string | 配送通道/分区 | 仅配送相关列表可能出现,常用于区分 m4 / m5 等通道 |
|
||||
| express_numbers | array[string] | 快递号列表 | 服务层聚合字段,内容来自 wms_order_express.waybill_code |
|
||||
| waybill_codes | array[string] | 运单号列表 | 与 express_numbers 内容一致,为兼容前端使用保留 |
|
||||
|
||||
补充说明
|
||||
- `express_numbers` 和 `waybill_codes` 都来自订单绑定的多条快递记录,适合前端直接渲染“多个快递号”。
|
||||
- `sys_platform_name`、`sys_logistics_name` 已由服务层归一化输出,前端无需再回表查询。
|
||||
- `dispatch_lane` 仅在 `order.deliveryOrder.list` / `order.deliveryExpectionOrder.list` 这两个配送类列表中出现;其余列表通常不返回该字段。
|
||||
|
||||
其他注意事项
|
||||
- `where` 的解析与支持的特殊字段由 parseWhereConditions 决定;若需要支持新的复杂筛选(如跨表/聚合条件),请先在解析器和后端模型中确认可支持的 specialFieldMap 与解析策略。
|
||||
- 推荐使用标准化 where 结构({ operator, value })以避免歧义;历史简写会被自动规范化,但可读性较差。
|
||||
- 兼容入口(get*)保留以兼容历史客户端,但文档与新开发均建议使用上述主入口方法名;兼容入口可能在不同 module 下存在重复实现(index + 子模块),以兼容不同调用路径。
|
||||
|
||||
方法清单(已在 methods/system.json 中登记)
|
||||
- order.list
|
||||
- order.reviewOrder.list
|
||||
- order.pendingOrder.list
|
||||
- order.expectionOrder.list
|
||||
- order.entrustOrder.list
|
||||
- order.deliveryOrder.list
|
||||
- order.deliveryExpectionOrder.list
|
||||
- order.archiveOrder.list
|
||||
|
||||
是否需要补充其它文档同步?
|
||||
- 建议同步更新:
|
||||
- 若有门户/前端 API 文档站(自动生成或展示 methods/system.json 的地方),应部署或刷新以展现新增条目。
|
||||
- 若存在 SDK 或对接说明(如 qimen 或第三方对接文档),如使用到工作台 list 场景也建议补充示例请求与常用 where 范例。
|
||||
|
||||
示例请求(简要)
|
||||
|
||||
请求体示例:
|
||||
{
|
||||
"pagination": { "page": 1, "pageSize": 50 },
|
||||
"where": { "delivery_order_code": { "operator": "like", "value": "ABC" }, "create_time_start": { "value": "2026-04-01" } },
|
||||
"sort": { "sortField": "updated_at", "sortOrder": "DESC" }
|
||||
}
|
||||
|
||||
响应示例(简要):
|
||||
{
|
||||
"list": [ /* 订单对象数组 */ ],
|
||||
"pagination": { "page":1, "pageSize":50, "total":1234, "totalPages":25, "hasPrevious":false, "hasNext":true }
|
||||
}
|
||||
|
||||
--
|
||||
文档维护者:WMS 文档代理
|
||||
@ -1,288 +0,0 @@
|
||||
# 订单工作台模块 — 规划草案(order_todo)
|
||||
|
||||
> 状态:**计划**,供评审与补充;实现前需与产品、DBA、前端对齐。
|
||||
> 关联:`OrderDeliveryFactory` / `OrderItemsFactory`(current / history 物理表)、`order_delivery` / `order_items` 基模型、现有 `order.*` system method。
|
||||
|
||||
---
|
||||
|
||||
## 0. 当前订单表、模型、工厂与关联(代码现状分析)
|
||||
|
||||
### 0.1 物理表与工厂命名
|
||||
|
||||
| 概念 | 物理表名模式 | 说明 |
|
||||
|------|----------------|------|
|
||||
| 发货单 current | `wms_order_delivery_{warehouseId}` | 按仓动态建表,`OrderDeliveryFactory.generateTableName(wh, 'current')` |
|
||||
| 发货单 history | `wms_order_delivery_{warehouseId}_history` | 多 `archive_time` 字段与索引;**业务代码尚未写入/迁移** |
|
||||
| 订单明细 current | `wms_order_items_{warehouseId}` | `OrderItemsFactory.generateTableName(wh, 'current')` |
|
||||
| 订单明细 history | `wms_order_items_{warehouseId}_history` | 同上,待迁移任务 |
|
||||
|
||||
基模型 `tableName` 为模板:`wms_order_delivery`、`wms_order_items`(用于 `rawAttributes` 复制到动态表)。
|
||||
|
||||
### 0.2 基模型 `OrderDelivery`(`app/model/order_delivery.js`)
|
||||
|
||||
- **主键与业务键**:`id`,`delivery_order_code` + `store_id` + `warehouse_id` 唯一索引(动态表工厂内复刻)。
|
||||
- **货主 / 仓库**:`store_id`(货主)、`warehouse_id`(仓库);**创建时落 M1/M2 可依据货主(store)侧配置**(配置表/字段待产品定义,当前模型无显式「进审开关」字段)。
|
||||
- **状态机字段(枚举在模型内)**:`status`,`sync_status`,`post_status`,`storage_status`,`pick_status`,`pack_status`,`inspection_status`,`print_status`,`claim_status`,`outbound_status`,`lock_status`,`intercept_status`。
|
||||
- **业务辅助**:`step`(注释:0 未审核 / 1 已审核 / 2 处理中 / 3 驳回异常 / 4 配送中 / 5 已完成 / 9 已关闭)、`wave_id`、金额与地址收件人、`items`(TEXT JSON 字符串)、`items_hash` / `items_crc` / `items_count` 等。
|
||||
- **物流展示相关(主表冗余)**:`logistics_code`、`logistics_name`、`express_code`、`delivery_time` 等;**细粒度快递轨迹**见下文物理表 `wms_order_express`。
|
||||
|
||||
### 0.3 基模型 `OrderItems`(`app/model/order_items.js`)
|
||||
|
||||
- **关联键**:`order_id` → 发货单 `id`;`item_code`、`item_id`、`stock_id`、`owner_code`、`plan_qty`、价格字段、`extend_props`(JSON)。
|
||||
- **索引**:`order_id`、`item_id`、`source_order_code`、`stock_id` 等。
|
||||
|
||||
动态明细表由工厂 `define` 时复制 `OrderItems.rawAttributes`,并 `copyAssociations` 自基模型。
|
||||
|
||||
### 0.4 工厂类职责
|
||||
|
||||
| 工厂 | 文件 | 职责摘要 |
|
||||
|------|------|----------|
|
||||
| `OrderDeliveryFactory` | `app/model/order_delivery_factory.js` | `getCurrentModel` / `getHistoryModel` / `getModelByTableName`;不存在则 `createPhysicalTable`;`setupAssociations` 将动态发货单与 **同仓同类型** 动态 `OrderItems` 做 `hasMany` / `belongsTo`;可选 `belongsTo` `Store`(货主/仓库别名) |
|
||||
| `OrderItemsFactory` | `app/model/order_items_factory.js` | 同上;并发建表锁 `creatingTables`;动态表带 `timestamps: true` |
|
||||
|
||||
**现状**:全仓业务查询路径普遍只调用 **`getCurrentModel`**;**`getHistoryModel` 无业务引用**。
|
||||
|
||||
### 0.5 其它订单相关物理表(非按仓工厂)
|
||||
|
||||
| 模型 | 表名 | 与订单关系 |
|
||||
|------|------|--------------|
|
||||
| `OrderExpress` | `wms_order_express` | `order_id` 关联订单主键;运单、物流接口、星河签收/退回/拦截等标记。**未纳入** `OrderDeliveryFactory` 动态表;若配送域拆分需定义 **order_id 与仓、自然月分区** 的一致性(否则跨表 JOIN 成本高)。 |
|
||||
|
||||
### 0.6 System 层与工厂衔接
|
||||
|
||||
- `app/service/systemMethods/order/base.js` 中 `getOrderModels(warehouseId)` **仅** `getCurrentModel` 取发货单 + 明细。
|
||||
- 列表类:`reviewOrder`、`pendingOrder`、`expectionOrder`、`deliveryOrder`、`archiveOrder` 等均基于上述 **current** 模型。
|
||||
|
||||
### 0.7 取消相关状态机(代码已有 vs 库表须核对)
|
||||
|
||||
**代码侧(`app/model/order_delivery.js`)已具备、可用于「取消」语义的枚举取值包括:**
|
||||
|
||||
| 位置 | 取值/说明 |
|
||||
|------|-----------|
|
||||
| `status` | 枚举含 **`cancel`**(订单状态) |
|
||||
| `intercept_status` | 枚举含 **`cancelled`** 等拦截/关闭链路 |
|
||||
| `step` | 整型步骤,注释含 **9 = 已关闭**;近期迁移为各分表补 `step`(见 `database/migrations/20260410150000-replace-audit-status-with-step-on-order-delivery-tables.js`) |
|
||||
|
||||
**实施 §2.3a 前必须执行:**
|
||||
|
||||
0. **核对清单(已产出,小阶段)**:只读 SQL 与步骤见 **`docs/order-cancel-db-checklist.md`**(不在仓库内自动连库执行)。**库表 DDL 变更影响面**见 **`docs/order-delivery-migration-impact.md`**。
|
||||
1. **对库**:对 `wms_order_delivery` 及 **`wms_order_delivery_%` 分表** 跑字段清单(`INFORMATION_SCHEMA`),确认 **`status` / `intercept_status` / `step` / `outbound_status`** 等与「取消后进 M4」**筛选用例**是否够用。
|
||||
2. **若产品要求独立可辨的「取消进 M4」标记**(例如与 `status=cancel` 但尚未占配送域行的组合区分):**库中无字段则新增**(如 `close_channel`、`cancelled_at`、`m4_reason_code` 等,名称待定),并同步:
|
||||
- `app/model/order_delivery.js`;
|
||||
- `OrderDeliveryFactory.createPhysicalTable` 生成的 DDL 模板;
|
||||
- 已有物理分表的 **补列 migration**(循环 `wms_order_delivery_*`)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与范围(含 outsourced)
|
||||
|
||||
### 1.1 工作台模块一览
|
||||
|
||||
| 模块 | 说明(产品语义) | 规划数据域 |
|
||||
|------|------------------|------------|
|
||||
| M1 待审核 | 需审核后进入后续履约 | **仅 current** |
|
||||
| M2 待处理 | 仓内/出库前正常队列 | **仅 current** |
|
||||
| M3 待处理异常 | 出库前各环节异常 | **仅 current** |
|
||||
| M4 配送订单 | 配送链路正常态 | **配送域工厂(首期已落地)**:单表 `wms_order_delivery_dispatch_{wh}` + 列 `dispatch_lane=m4`;**不按自然月拆物理表** |
|
||||
| M5 配送异常 | 配送链路异常(M4 子集) | **同上表**,`dispatch_lane=m5` 筛选;归档/近三月策略走 **查询与任务**,不必多分表 |
|
||||
| M6 归档订单 | 冷数据 | **history**(>3 月等策略) |
|
||||
| **outsourced 外仓发货** | 本仓不履约、推送外仓/三方履约;**已纳入 `OrderDeliveryFactory` 管理的 managed table / schema self-check 体系** | **由工厂统一管理,启动自检自动对齐结构**;仍可结合 current 扩展标记 + 外仓任务表落地 |
|
||||
|
||||
### 1.2 数据分层(与 §0 对齐)
|
||||
|
||||
| 层级 | 表 / 模型 | 时间 / 策略 |
|
||||
|------|-----------|-------------|
|
||||
| 热区 M1~M3 / outsourced(规划) | `wms_order_delivery_{wh}`、`wms_order_items_{wh}`(current) | 当日或未闭环;**创建时分流 M1 vs M2 由货主配置决定**;**到期仅克隆续单**,不进 M6(§2.4) |
|
||||
| 配送区 M4/M5 | **`wms_order_delivery_dispatch_{wh}`**(`OrderDeliveryFactory` 的 dispatch 模式) | **单物理表**;M4/M5 用 **`dispatch_lane`**;**不按自然月拆表**;「约 3 个月」保留为 **列表/归档任务的时间条件**(见 §2.5 落地说明) |
|
||||
| 冷数据 M6 | `*_history`(仅承接 **M4/M5** 迁入) | **超过 3 个月**等策略;**仅允许 M4/M5 进入 M6**;M1/M2/M3/outsourced **不走 M6 物理归档路径**(见 §2.4) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 模块规则与状态流转(补充)
|
||||
|
||||
### 2.1 订单创建:进入 M1 或 M2
|
||||
|
||||
- **规则**:创建时读取 **货主(store)配置**,决定初始进入 **M1(待审核)** 或 **M2(待处理)**。
|
||||
- **M1 → M2**:必须通过 **仓内库存校验**(满足可履约)**或** 选择 **推送 outsourced(外仓发货)** 路径之一;具体字段与接口待定义。
|
||||
- **M2 ⊥ outsourced(强制互斥)**:同一订单 **不得** 同时处于本仓待处理与外仓履约;进入或退出 M2/outsourced 的切换 **必须在单条(或可串行化的)数据库事务内完成**(状态位 + 外仓任务表等一并提交),失败 **整体回滚**,禁止半开状态。
|
||||
- **outsourced**:当前 **无完整状态机**;与 M4 的衔接仍遵守 §2.2 单向规则。
|
||||
|
||||
### 2.2 进入 M4 的约束(核心)
|
||||
|
||||
| 从 → 到 | 是否允许 | 说明 |
|
||||
|---------|----------|------|
|
||||
| **M2 → M4** | **允许(单向)** | M2、**outsourced 仅允许单向落入 M4** |
|
||||
| **outsourced → M4** | **允许(单向)** | 外仓发货完成后,依赖 **外部通知** 与出库状态机推进 |
|
||||
| **M1 → M4** | **禁止** | 须先 **切到 M2** 且 **状态机到达出库** 后,再经 **外部通知发货完成** 落入 M4 |
|
||||
| **M3 → M4** | **禁止** | 须先 **消除异常并回到 M2**,再走与 M2 相同路径进入 M4 |
|
||||
| **取消订单 → M4** | **允许(专用)** | 见 **§2.3a**:标记取消态后 **直进 M4**,**不可逆**、**零例外** |
|
||||
|
||||
### 2.3 M4 / M5 与外部机制
|
||||
|
||||
- **M4 ↔ M5 切换**:由 **外部机制** 驱动(承运商回传、网关、人工标记等),不在此文档展开协议。
|
||||
- **M4/M5 与 M1~M3**:除下节「补发副本」外,**同一订单在 M1/M2/M3/outsourced 与 M4/M5 不重复占位**:**M1~M3(及 outsourced)为唯一工作台态**;**M4/M5 为配送域单独态**(可理解为 **配送域一条影子/主数据**,与 current 热行通过 `order_id` / `delivery_order_code` / 快照关联)。
|
||||
|
||||
### 2.3a 订单取消(特殊路径:标记后进 M4)
|
||||
|
||||
- **规则**:发生 **订单取消** 时,须在热区/配送衔接层 **写入取消类状态标记**(状态机字段组合或专用列,见 **§0.7**),并 **直接进入 M4**(配送域占位,用于闭环展示与后续「仅 M4/M5 可进 M6」链路);**不可逆**,**不允许任何业务或技术例外**(含回滚接口、静默改回热区)。
|
||||
- **与 §2.2 的关系**:本条为 **取消专用例外**;非取消场景下 **M1/M3 仍禁止直落 M4**(见 §2.2 表)。
|
||||
- **库表**:上线前按 **§0.7** 核对;**缺字段则 migration 补充**,禁止仅靠应用层内存状态表达取消进 M4。
|
||||
|
||||
### 2.4 时间驱动的 M6(不可逆 + 准入白名单)
|
||||
|
||||
- **时间策略**:**所有订单类型均受时间维度约束,不另开例外**;**进入 M6(物理归档)后不可逆**,**不允许任何例外**(不设司法解冻、不设未归档回退通道)。
|
||||
- **谁可以进 M6(物理)**:**仅 M4、M5** 对应的配送域数据(及与其绑定的明细快照)允许在满足保留期后 **迁入 `history` / 冷存储**。
|
||||
- **谁不可以进 M6**:**M1、M2、M3、outsourced** 热区行 **不允许** 走与 M4/M5 **相同的** M6(history)迁入通道;**到期后仅允许「克隆续单」**:通过 **新行(新主键)** 承接后续履约,原行 **仅改标记**(§2.7),**不得**删/软删、**不得**将原行迁入 M6。
|
||||
- **克隆续单 / 补单(首期)**:**不与奇门等平台同步**;定位为 **补单**,由 **人工在仓内/运营侧处理**;系统可提供列表与标记能力,**接口与对账范围以本仓 WMS 为准**。
|
||||
- **M4/M5 → M6**:以 **出库时间**(如 `delivery_time` / 出库确认时间)为主键条件之一,满足 **>3 个月**(与 §1.2 口径对齐)后迁入 history;过程 **不可逆**。
|
||||
|
||||
### 2.5 配送域工厂(首期落地 + 后续)
|
||||
|
||||
- **已实现**:`app/model/order_delivery_factory.js` 的 dispatch 模式;物理表 **`wms_order_delivery_dispatch_{warehouseId}`**(与热区 `wms_order_delivery_{wh}` 命名同族,中间段 **`dispatch`**);**M4/M5 同表**,列 **`dispatch_lane` ENUM('m4','m5')** 区分;**不按自然月拆物理表**。`getDispatchModel(wh)` 为主入口;`getM4Model`/`getM5Model` 复用同一 dispatch 模式返回 **同一模型**。**outsourced 也已经纳入同一工厂管理,应用启动时会通过自检自动对齐 managed table 结构**。
|
||||
- **单测**:`test/app/model/order_delivery_dispatch_factory.test.js`;需连库时 `DISPATCH_FACTORY_TEST_MYSQL=1`(见 `config/plugin.js`);留表排查 `KEEP_DISPATCH_FACTORY_TABLES=1`。
|
||||
- **仍待**:与 current 的 **副本同步 / 事件驱动**;**强分区事务** 口径改为「单事务内同一 `warehouse_id` + 配送域表」即可(不再绑定 `yyyyMM` 表名);`wms_order_express` 与配送域行关联方案;M6 迁入仍以 **出库时间 + 保留期** 驱动(§2.4)。
|
||||
|
||||
### 2.6 M4/M5 副本回归 M1 / M2 / M3(补发 / 部分履约)
|
||||
|
||||
- **场景**:配送域需 **重新创建副本** 回到 **M1 或 M2 或 M3**(目标态由业务定)。
|
||||
- **强制携带**:**补发标记/补发单**;或 **引用原资料 + 部分商品行** 的 **补发语义**,并 **更新履约目标**(新 `delivery_order_code` 或子单号、关联原单 ID 等,待表设计)。
|
||||
- **约束**:回归后重新遵守 **§2.1~2.2** 的互斥与单向规则;原配送域行 **不得删除/软删**,仅 **改标记** 或保留为 **只读关联**(§2.7)。
|
||||
|
||||
### 2.7 副本、主单与删除策略(硬约束)
|
||||
|
||||
- **禁止物理删除**;**禁止软删除**(不使用 `delete_at` / `paranoid` 等表达「行消失」)。
|
||||
- **仅允许**:**改标记**(如 `lifecycle_state`、`superseded_by_id`、`closed_reason`、`is_supplement` 等,具体字段待表设计)或 **克隆** 新行(新主键)承载补发/续履约。
|
||||
- **适用范围**:**所有副本**(配送域副本、热区补发单、回归产生的克隆行、引用链上的历史快照)一律同上。
|
||||
- **运维级「克隆」语义**:在本规划中特指 **对状态机字段的合法变更**(含批量修正、`step` / 各 `*_status` / 取消标记等),**等价于「把行修正到合规状态」**;**不是**对 §2.3a「取消进 M4」或 §2.4「M6 不可逆」的 **豁免回滚**。若技术上采用「插入新行再改关联」实现修正,仍须满足 **不删旧行、仅标记**(§2.7 首条)。**审批角色与留痕** 见 **§5a 预留**,本期不落地。
|
||||
|
||||
### 2.8 互斥与唯一性(更新)
|
||||
|
||||
| 关系 | 说明 |
|
||||
|------|------|
|
||||
| M1 ⊥ (M2 ∪ M3) | 不变 |
|
||||
| M2 ⊥ M3 | 不变 |
|
||||
| **M2 ⊥ outsourced** | **强制互斥**;切换须 **事务**(§2.1) |
|
||||
| M5 ⊆ M4 | 不变 |
|
||||
| **M1~M3 / outsourced(热区)** | **同一订单唯一展示态**(互斥集合内择一) |
|
||||
| **M4 / M5** | **配送域内**可与热区并存为 **影子数据**;列表层需约定「主工作台只显示一侧」避免重复操作 |
|
||||
| **M6** | **仅 M4/M5 可物理迁入**;**不可逆、零例外**;热区到期 **不进 M6**,**仅允许克隆续单**(§2.4) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 查询设计任务(列表 + 明细)
|
||||
|
||||
### 3.1 列表查询(各模块)
|
||||
|
||||
**目标**:最小可用字段集 + **足够前端判断订单状态**(含 outsourced 外仓标记若存在)。
|
||||
|
||||
**原则**:
|
||||
|
||||
- 列表不返回大体积 `items` TEXT;仅标识、各 `*_status`、`outbound_status`、`inspection_status`、`step`、`updated_at` / `delivery_time`、货主/仓编码等。
|
||||
- 实现:**按模块常量 `LIST_FIELDS`**;M4/M5/outsourced 在配送域或扩展表就绪后各自维护一份。
|
||||
|
||||
### 3.2 明细查询
|
||||
|
||||
- 主单:**可对前端公开**的全部字段(排除密钥、内部调试字段)。
|
||||
- 明细行:`OrderItems` 动态表全量可公开字段。
|
||||
- **关联**:`Store`/仓库等(以 Sequelize `setupAssociations` / `copyAssociations` 为准,文档列出 **别名 + 字段子集**)。
|
||||
- **快递**:**暂不接订阅/路由逻辑**;列表/明细仅展示;**DTO 硬编码字段表 + 中文标签注释**(主表 `logistics_*` + 若联查 `wms_order_express` 则增加运单等字段)。
|
||||
|
||||
### 3.3 快递展示字段清单(示例)
|
||||
|
||||
| 字段 key | 前端标签 | 说明 |
|
||||
|----------|----------|------|
|
||||
| `logistics_name` | 承运商 | 仅展示 |
|
||||
| `logistics_code` | 物流编码 | 仅展示 |
|
||||
| `waybill_code`(express 表) | 运单号 | 仅展示 |
|
||||
| … | … | 不接路由、不订阅 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 执行任务(分阶段,可微调)
|
||||
|
||||
### 执行进度(小阶段 A-0,最小影响)
|
||||
|
||||
| 日期 | 内容 |
|
||||
|------|------|
|
||||
| 2026-04-10 | **无业务代码 / 无 migration 变更**。新增只读交付物:`docs/order-cancel-db-checklist.md`(§0.7 跑库步骤)、`docs/order-state-machine-dictionary.md`(状态机字典 **v0 骨架**,与 `app/model/order_delivery.js` 摘录一致)。**数仓映射、实际跑库结果** 仍待下一小阶段。 |
|
||||
| 2026-04-10 | **小阶段 A-1(影响面)**:新增 `docs/order-delivery-migration-impact.md`。**结论**:在未跑库确认缺列、且未敲定「取消进 M4」专用列前,**不自动提交 ALTER migration**;若清单验证列已齐,可先 **零表变更** 做应用筛选。详见该文档 **§1**。 |
|
||||
| 2026-04-10 | **小阶段 A-2(wms-db-agent 只读诊断)**:已对 `wms` 库跑清单;结果写入 **`docs/order-cancel-db-checklist.md` §5**。要点:**分表** `100000`/`1000028` 目标列齐全,可先不增列做筛选;**基表**缺三列、**勿**当业务表用;**无 `_history` 样本**;`chcp 65001` 防 JSON 解析失败。 |
|
||||
| 2026-04-11 | **基表状态列**:migration `20260410200000-add-status-columns-to-wms-order-delivery-base.js`(按需补列,与热区分表对齐)。**配送域**:`OrderDeliveryFactory` 的 dispatch 模式单表 `wms_order_delivery_dispatch_{wh}` + `dispatch_lane`;当前按单表落地,不再保留「m4/m5 分表 + 自然月表名」方案;单测与 `DISPATCH_FACTORY_TEST_MYSQL` 见上文 §2.5。 |
|
||||
| 2026-04-11 | **outsourced 收敛**:`outsourced` 纳入 `OrderDeliveryFactory` 的 managed table / schema self-check 体系,沿用启动自检自动对齐结构;旧兼容 shim 已移除,文档与代码统一收口到工厂管理。 |
|
||||
|
||||
### 阶段 A — 文档与规则冻结
|
||||
|
||||
- [x] 货主配置:「创建进 M1 / M2」的配置项落库位置与变更流程。
|
||||
- [ ] M1→M2:库存校验 API、outsourced 推送接口与回写字段。
|
||||
- [ ] 外部「发货完成」通知与状态机字段的映射表(落到 `outbound_status` / `step` 等)。
|
||||
- [x] **§0.7 清单文档**:`docs/order-cancel-db-checklist.md`(各环境人工执行)。
|
||||
- [x] **§0.7 跑库(本机 wms 一次)**:见 `docs/order-cancel-db-checklist.md` §5;**分表列齐**;**其它仓/生产须复跑**。
|
||||
- [x] **§0.7 基表状态列 migration**(与分表枚举对齐):`database/migrations/20260410200000-add-status-columns-to-wms-order-delivery-base.js`(已合并进仓库;其它环境须自行 `db:migrate`)。**独立「取消进 M4」业务列** 仍待产品定名后再 migration。
|
||||
- [x] **状态机字典 v0 骨架**:`docs/order-state-machine-dictionary.md`(与数仓/报表的 **字段映射表** 仍待补)。
|
||||
- [x] **订单表 DDL 影响面分析**:`docs/order-delivery-migration-impact.md`(初版静态结论;**2026-04-11** 起基表状态列以已合并 migration 为准,文档全文若与现网不一致须择机修订)。
|
||||
|
||||
### 阶段 B — 配送域工厂(3 自然月 + 强分区事务)
|
||||
|
||||
- [x] 配送域建表能力(`OrderDeliveryFactory` 的 dispatch 模式):表 **`wms_order_delivery_dispatch_{warehouseId}`**,**`dispatch_lane`** 区分 M4/M5。
|
||||
- [x] M4/M5 **单表** DDL 与动态模型(首期)。
|
||||
- [ ] 与 current 的 **副本同步** 或 **事件驱动** 方案(未做)。
|
||||
- [ ] `wms_order_express` 与配送域 **order_id**(及仓)一致性方案。
|
||||
|
||||
### 阶段 C — 归档 M6 + 时间消除
|
||||
|
||||
- [ ] **仅 M4/M5**:配送域 → history 的 **出库时间** 驱动任务;**不可逆** 校验与审计(**零例外**)。
|
||||
- [ ] **M1/M2/M3/outsourced**:到期 **仅克隆续单** 流程(新行 + 原行标记);**禁止** 迁入 M6;前端 **空态/引导续单** 文案。
|
||||
- [ ] **取消进 M4**:状态机字段字典、事务边界、与常规 M4 列表的 **展示分区**(避免与正常配送混淆)。
|
||||
- [ ] 全库 **禁止 DELETE/软删** 副本与主单的 ORM/脚本审计;运维修正走 **状态机变更**(§2.7);**审批流** 见 **§5a 预留**。
|
||||
|
||||
### 阶段 D — 补发副本与目标更新
|
||||
|
||||
- [ ] 补发单模型、原单引用、部分行、目标更新字段;**原行仅标记,禁止删/软删**。
|
||||
- [ ] 事务:副本创建 + 热区插入 + 配送域标记 **同一强分区键内** 或可补偿 Saga;与 **M2↔outsourced 事务切换** 共用事务规范文档。
|
||||
|
||||
### 阶段 E — API / 测试
|
||||
|
||||
- [ ] `methods/system.json` + changes;互斥与单向集成测试用例。
|
||||
|
||||
---
|
||||
|
||||
## 5. 待补充项 — 满足情况说明(已更新)
|
||||
|
||||
> **结论**:原「待补充项」中的 **业务原则 / 边界** 多数已在正文(§0.7、§2.3a、§2.4、§5a)**闭合**,**不再属于「方向未定的拍板」**;但 **可交付的设计稿与成文资产** 仍未完成,须在 **§4 各阶段** 跟踪直至产出。
|
||||
|
||||
### 5.1 规则层 — 视为已满足(已写入本文档)
|
||||
|
||||
| 原议题 | 满足方式 |
|
||||
|--------|----------|
|
||||
| 克隆续单是否与奇门同步 | **已决策:不同步**;首期 **人工补单** — 见 §2.4 |
|
||||
| 运维审批、留痕格式 | **已决策:本期不做**,仅预留 — 见 **§5a** |
|
||||
| 取消状态机是否依赖库表 | **已决策:以 DB 为准**,缺列则 migration — 见 **§0.7**、§2.3a |
|
||||
|
||||
### 5.2 交付层 — 尚未满足(须产出成果物,不等同于「原则未拍板」)
|
||||
|
||||
| 事项 | 当前状态 | 建议产出 / 跟踪位置 |
|
||||
|------|----------|----------------------|
|
||||
| **取消进 M4** 的配送域 **子类型 / 展示标签**(与正常 M4 区分色、筛选项) | 未完成 | 产品/UI 说明 + 接口 `where` 约定;**§4 阶段 C** |
|
||||
| **克隆续单** 的 **主键关联、单号规则、权限** | 未完成 | 表设计 + 人工补单 SOP;**§4 阶段 D**(原则「不奇门」已 §2.4) |
|
||||
| **改标记 / 状态机** 的 **字段字典** 及与 **数仓、报表** 同步 | **骨架已完成(v0)** | 成稿:`docs/order-state-machine-dictionary.md`;**数仓/报表映射与变更登记** 仍未完成 — **§4 阶段 A/C** |
|
||||
|
||||
### 5a. 预留(本期不实现)
|
||||
|
||||
- **运维审批** 角色、工单模板与 **留痕格式**:**本期不做**,仅在技术方案中 **预留扩展点**(配置键、审计表占位名、接口 hook 注释),避免后续硬改核心表结构。
|
||||
|
||||
---
|
||||
|
||||
## 6. 修订记录
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| (首版) | 根据讨论整理计划草案 |
|
||||
| 补充 | 增加 §0 当前表/模型/工厂/关联分析;outsourced、创建分流、进入 M4 约束、外部驱动 M4/M5、时间进 M6、配送域独立工厂与强分区事务、M4/M5 按出库时间进 M6、补发副本回归 M1/2/3 |
|
||||
| 补充 | **M2⊥outsourced 且事务进出**;**M6 仅 M4/M5 可物理迁入、不可逆**;热区到期不进 M6;**全副本禁止删/软删、仅标记或克隆**;§2.7 硬约束、§1.2/阶段 C/待补充项同步 |
|
||||
| 补充 | 热区到期 **仅克隆续单**;**§2.3a 取消→标记→直进 M4、不可逆零例外**;**运维「克隆」= 状态机合法变更** 写入 §2.2/§2.7/阶段 C |
|
||||
| 补充 | **§0.7** 取消状态机与分表核对/缺列 migration;**克隆续单不奇门同步、首期人工补单**;**字段字典与数仓报表同步**;**§5a 运维审批预留** |
|
||||
| 补充 | **§5 重写**:区分 **规则层已满足** vs **交付层未完成**;原 checklist 拆入 §5.1 / §5.2 并指向 §4 |
|
||||
| 2026-04-10 | **小阶段 A-0**:新增 `docs/order-cancel-db-checklist.md`、`docs/order-state-machine-dictionary.md`;§0.7 / §4 阶段 A / §5.2 同步;无代码变更 |
|
||||
| 2026-04-10 | **小阶段 A-1**:`docs/order-delivery-migration-impact.md`;**未提交 migration**(待你根据跑库 + 列名决策) |
|
||||
| 2026-04-10 | **小阶段 A-2**:wms-db-agent 只读诊断;`order-cancel-db-checklist.md` §5;**未提交 migration** |
|
||||
| 2026-04-11 | **配送域单表工厂** + **基表 migration**;§1.2 / §2.5 / §4 阶段 B 勾选与表述同步 |
|
||||
@ -1,65 +0,0 @@
|
||||
# 打印失败自动补偿(printRetryCompensation)操作说明
|
||||
|
||||
概述
|
||||
- 目的:定时扫描失败或超时的打印记录,按仓库分组并批量触发补打(调用内部方法 `print.retryFailed`)。
|
||||
- 实现位置:调度任务文件 [app/schedule/print_retry_compensation.js](app/schedule/print_retry_compensation.js)
|
||||
- 配置位置:全局配置 `config.printRetryCompensation`(见 `config/config.default.js`)
|
||||
|
||||
如何开启
|
||||
1. 在目标环境的配置文件中(例如 `config/config.local.js` 或部署时注入的 config),设置:
|
||||
|
||||
```js
|
||||
// 示例(config/config.local.js)
|
||||
module.exports = appInfo => {
|
||||
const config = exports = {};
|
||||
|
||||
config.printRetryCompensation = {
|
||||
enable: true, // 开启自动补偿
|
||||
intervalMs: 60 * 1000, // 最小执行间隔(ms),默认 60000
|
||||
batchSize: 50, // 每次扫描触发的最大打印记录数,默认 50
|
||||
force: false, // 是否以强制方式触发(当前实现不放宽状态判定)
|
||||
};
|
||||
|
||||
return config;
|
||||
};
|
||||
```
|
||||
|
||||
2. 启用后,Egg 的调度器会按文件中的 `schedule.interval`(30s)触发调度器,但实际执行受 `intervalMs` 控制(避免重复执行)。
|
||||
3. 部署/重启应用使配置生效。
|
||||
|
||||
关键参数说明
|
||||
- `enable` (boolean):是否启用自动补偿(默认 `false`)。
|
||||
- `intervalMs` (number, ms):两次实际执行之间的最小间隔(默认 60000)。注意调度器仍以 30s 触发,但若距离上次执行时间 < intervalMs 将跳过本轮。
|
||||
- `batchSize` (number):每次从数据库读出的最大记录数量(默认 50)。
|
||||
- `force` (boolean):是否强制补打。当前最小实现中 `force` 参数会被传递到 `print.retryFailed`,但 `getRetryEligibility` 中并未放宽状态检查(注释标注为“最小实现”)。如需放宽,需要修改 `app/service/systemMethods/print.js` 中的 `getRetryEligibility` 实现。
|
||||
|
||||
行为与兼容性(与代码的一致性要点)
|
||||
- 调度逻辑:
|
||||
- 调度入口:[app/schedule/print_retry_compensation.js](app/schedule/print_retry_compensation.js)
|
||||
- 查询条件:满足任一 send_status 为 `send_failed`,或 print_status 在 `['print_failed','timeout']`,且 `next_retry_at <= now`,并且 `retry_count < max_retry_count`。
|
||||
- 按 `warehouse_id` 分组后,逐仓调用:
|
||||
`ctx.service.systemMethods.print.retryFailed({ print_ids, warehouse_id, force })`。
|
||||
- `print.retryFailed` 对 `warehouse_id` 的兼容:
|
||||
- 支持显式传入 `warehouse_id`,优先使用该值。
|
||||
- 若未传入 `warehouse_id`,会回退使用 `ctx.user.store_id`(接口调用者的仓库上下文)。
|
||||
- 如果两者均无(例如外部无登录上下文且未传入 `warehouse_id`),方法会返回 400 错误:`warehouse_id 参数缺失,且当前上下文无可用仓库信息`。
|
||||
- 返回值要点:成功返回包含 `success_count` / `failed_count` / `skipped_count`、`retried`(尝试项)和 `skipped`(跳过项)摘要;调度器依据 `flag==='success'` 判定调用是否成功。
|
||||
|
||||
排障要点(常见问题排查)
|
||||
- 任务一直没有扫描到记录:检查数据库 `PrintRecord` 表中是否存在满足条件的行(`send_status`/`print_status`、`next_retry_at`、`retry_count < max_retry_count`)。
|
||||
- 调度被频繁跳过:检查 `config.printRetryCompensation.intervalMs` 与日志中 `ctx.app._printRetryCompensationLastRunAt` 的时间差;若 `_printRetryCompensationRunning` 标识长时间为 true,进程可能在上次运行时异常退出,建议重启应用清理状态。
|
||||
- 补打触发但实际发送失败:查看打印服务调用日志(`service.systems.print.index.sendToComputer` 返回值),并查看 `PrintRecord` 的 `error_message` / `fail_code` 字段。
|
||||
- 快递/组件离线导致发送失败:`print` 服务会在调用前检查组件在线性(从 Redis 的 `printer:{computerId}:name:{component}:status` 读取,期望值为 `connected`)。请检查对应 Redis key 是否存在并为 `connected`。
|
||||
- 打印任务编码冲突:如果出现唯一索引冲突(ER_DUP_ENTRY),日志会有 `打印任务编码冲突` 的警告,系统会按指数退避重试写入映射表。
|
||||
|
||||
回滚方式
|
||||
- 临时回滚:在运行环境配置中将 `printRetryCompensation.enable` 设为 `false` 并重启服务,调度器将不再触发实际补偿逻辑。
|
||||
- 速率/批量调整:将 `batchSize` 缩小或增大 `intervalMs`,以控制对打印服务的并发压力。
|
||||
|
||||
参考位置
|
||||
- 调度实现:[app/schedule/print_retry_compensation.js](app/schedule/print_retry_compensation.js)
|
||||
- 默认配置:[config/config.default.js](config/config.default.js)(`printRetryCompensation` 段)
|
||||
- 补打实现与仓库兼容性:[app/service/systemMethods/print.js](app/service/systemMethods/print.js) 中 `retryFailed` 与 `getRetryEligibility` 方法
|
||||
|
||||
附注
|
||||
- 本说明以当前代码实现为准(2026-05-20),如修改 `getRetryEligibility` 或补打流程,请同步更新本说明与 `methods/changes` 记录。
|
||||
@ -1,226 +0,0 @@
|
||||
# 奇门接口技术备忘
|
||||
|
||||
## 1. 文档来源
|
||||
|
||||
- 官方来源:open.taobao.com 文档,docId=118403,页面章节为“5. 接口说明”
|
||||
- 适用对象:WMS 与 ERP 之间的奇门对接排障、接口回查、协议备忘
|
||||
- 本文目标:把官方白皮书里的核心调用约定、接口地图和本地实现入口沉淀到仓库内,便于技术备用
|
||||
|
||||
## 2. 接入总览
|
||||
|
||||
奇门接口的统一特征是:
|
||||
|
||||
- 请求方式以 POST 为主
|
||||
- query 中携带 app_key、method、v、format、sign_method、sign、timestamp 等标准参数
|
||||
- body 使用 XML,根节点通常为 request
|
||||
- 响应也使用 XML,根节点通常为 response
|
||||
- 响应通常包含 flag、code、message 三个固定字段
|
||||
|
||||
官方白皮书中明确说明:
|
||||
|
||||
- 很多接口是同步接口,返回 success 不只是“消息接收成功”,而是代表业务已处理完成
|
||||
- 批量接口通常会在一个订单下承载多个 item 或 order 节点
|
||||
- 非叶子节点通常允许增加 remark 和 extendProps
|
||||
|
||||
## 3. 通用字段与约定
|
||||
|
||||
### 3.1 常见主键字段
|
||||
|
||||
- ownerCode:货主编码
|
||||
- warehouseCode:仓库编码,统仓统配等场景常填 OTHER
|
||||
- itemCode:ERP 商品编码
|
||||
- itemId:WMS 商品编码或仓储系统商品 ID,通常是条件必填
|
||||
- orderCode:单据编码
|
||||
- orderId:仓储系统单据编码
|
||||
- outBizCode:外部业务编码,常作为幂等键
|
||||
|
||||
### 3.2 常见状态枚举
|
||||
|
||||
订单类状态常见值:
|
||||
|
||||
- NEW:未开始处理
|
||||
- ACCEPT:仓库接单
|
||||
- PRINT:打印
|
||||
- PICK:拣货
|
||||
- CHECK:复核
|
||||
- PACKAGE:打包
|
||||
- WEIGH:称重
|
||||
- READY:待提货
|
||||
- DELIVERED:已发货
|
||||
- PARTDELIVERED:部分发货完成
|
||||
- PARTFULFILLED:部分收货完成
|
||||
- FULFILLED:收货完成
|
||||
- EXCEPTION:异常
|
||||
- CANCELED:取消
|
||||
- CLOSED:关闭
|
||||
- REJECT:拒单
|
||||
- REFUSE:客户拒签
|
||||
- SIGN:签收
|
||||
|
||||
库存类常见值:
|
||||
|
||||
- ZP:正品
|
||||
- CC:残次
|
||||
- JS:机损
|
||||
- XS:箱损
|
||||
- FP:废品
|
||||
- ZT:在途库存
|
||||
- DJ:冻结
|
||||
- OTHER:其他
|
||||
|
||||
### 3.3 常见业务规则
|
||||
|
||||
- 组合商品、条码、批次、生产日期、过期日期、生产批号等字段在多个接口里复用
|
||||
- 一些接口对 itemId 有条件必填要求,通常与仓库是否自定义 WMS 商品编码有关
|
||||
- 多次收货、多次发货、多次确认类接口会使用 confirmType
|
||||
- 分批发送时,totalOrderLines 常用于说明总行数,接收方据此判断是否收齐
|
||||
|
||||
## 4. 接口地图
|
||||
|
||||
以下为官方文档 5.x 章节的接口目录,按业务域整理。
|
||||
|
||||
### 4.1 商品与商品映射
|
||||
|
||||
- 5.1 商品查询接口:taobao.qimen.singleitem.query / singleitem.query
|
||||
- 5.2 商品同步接口:taobao.qimen.singleitem.synchronize / singleitem.synchronize
|
||||
- 5.3 商品同步接口(批量):taobao.qimen.items.synchronize / items.synchronize
|
||||
- 5.4 组合商品接口:taobao.qimen.combineitem.synchronize / combineitem.synchronize
|
||||
- 5.5 创建前后端商品映射接口:taobao.qimen.itemmapping.create / itemmapping.create
|
||||
- 5.6 前后端商品映射查询接口:taobao.qimen.itemmapping.query / itemmapping.query
|
||||
|
||||
### 4.2 入库与退货入库
|
||||
|
||||
- 5.7 入库单创建接口:taobao.qimen.entryorder.create / entryorder.create
|
||||
- 5.8 入库单确认接口:taobao.qimen.entryorder.confirm / entryorder.confirm
|
||||
- 5.9 入库单查询接口:taobao.qimen.entryorder.query / entryorder.query
|
||||
- 5.10 退货入库单创建接口:taobao.qimen.returnorder.create / returnorder.create
|
||||
- 5.11 退货入库单确认接口:taobao.qimen.returnorder.confirm / returnorder.confirm
|
||||
- 5.12 退货入库单查询接口:taobao.qimen.returnorder.query / returnorder.query
|
||||
|
||||
### 4.3 出库、发货与确认
|
||||
|
||||
- 5.13 出库单创建接口:taobao.qimen.stockout.create / stockout.create
|
||||
- 5.14 出库单确认接口:taobao.qimen.stockout.confirm / stockout.confirm
|
||||
- 5.15 出库单查询接口:taobao.qimen.stockout.query / stockout.query
|
||||
- 5.16 发货单创建接口:taobao.qimen.deliveryorder.create / deliveryorder.create
|
||||
- 5.17 发货单创建接口(批量):taobao.qimen.deliveryorder.batchcreate / deliveryorder.batchcreate
|
||||
- 5.18 发货单创建结果通知接口(批量):taobao.qimen.deliveryorder.batchcreate.answer / deliveryorder.batchcreate.answer
|
||||
- 5.19 发货单确认接口:taobao.qimen.deliveryorder.confirm / deliveryorder.confirm
|
||||
- 5.20 发货单确认接口(批量):taobao.qimen.deliveryorder.batchconfirm / deliveryorder.batchconfirm
|
||||
- 5.21 发货单查询接口:taobao.qimen.deliveryorder.query / deliveryorder.query
|
||||
|
||||
### 4.4 SN 与订单流水
|
||||
|
||||
- 5.22 订单SN通知接口:taobao.qimen.order.sn.report / order.sn.report
|
||||
- 5.23 发货单SN通知接口:taobao.qimen.sn.report / sn.report
|
||||
- 5.24 订单流水查询接口:taobao.qimen.orderprocess.query / orderprocess.query
|
||||
- 5.25 订单状态查询接口(批量):taobao.qimen.orderstatus.batchquery / orderstatus.batchquery
|
||||
- 5.26 订单流水通知接口:taobao.qimen.orderprocess.report / orderprocess.report
|
||||
- 5.27 订单异常通知接口:taobao.qimen.orderexception.report / orderexception.report
|
||||
|
||||
### 4.5 异常、退货、缺货与挂起
|
||||
|
||||
- 5.28 退货异常包裹单通知接口:taobao.qimen.returnapply.report / returnapply.report
|
||||
- 5.29 退货包裹状态通知接口:taobao.qimen.returnpackage.report / returnpackage.report
|
||||
- 5.30 发货单缺货通知接口:taobao.qimen.itemlack.report / itemlack.report
|
||||
- 5.31 发货单缺货查询接口:taobao.qimen.itemlack.query / itemlack.query
|
||||
- 5.32 单据取消接口:taobao.qimen.order.cancel / order.cancel
|
||||
- 5.33 单据挂起(恢复)接口:taobao.qimen.order.pending / order.pending
|
||||
|
||||
### 4.6 库存、仓库、加工与异动
|
||||
|
||||
- 5.34 库存查询接口(多商品):taobao.qimen.inventory.query / inventory.query
|
||||
- 5.35 库存查询接口(多条件):taobao.qimen.stock.query / stock.query
|
||||
- 5.36 仓库查询接口:taobao.qimen.warehouseinfo.query / warehouseinfo.query
|
||||
- 5.37 仓库同步接口:taobao.qimen.warehouseinfo.synchronize / warehouseinfo.synchronize
|
||||
- 5.38 库存盘点通知接口:taobao.qimen.inventory.report / inventory.report
|
||||
- 5.39 库存盘点查询接口:taobao.qimen.inventorycheck.query / inventorycheck.query
|
||||
- 5.40 仓内加工单创建接口:taobao.qimen.storeprocess.create / storeprocess.create
|
||||
- 5.41 仓内加工单确认接口:taobao.qimen.storeprocess.confirm / storeprocess.confirm
|
||||
- 5.42 库存异动通知接口:taobao.qimen.stockchange.report / stockchange.report
|
||||
|
||||
### 4.7 店铺、波次、调拨、规则与统计
|
||||
|
||||
- 5.43 店铺同步接口:taobao.qimen.shop.synchronize / shop.synchronize
|
||||
- 5.44 发货单波次通知接口:taobao.qimen.wavenum.report / wavenum.report
|
||||
- 5.45 调拨单创建接口:taobao.qimen.transferorder.create / transferorder.create
|
||||
- 5.46 调拨单查询接口:taobao.qimen.transferorder.query / transferorder.query
|
||||
- 5.47 调拨单通知接口:taobao.qimen.transferorder.report / transferorder.report
|
||||
- 5.48 渠道间库存规则设置接口:taobao.qimen.inventoryrule.create / inventoryrule.create
|
||||
- 5.49 库存汇总报表查询接口:taobao.qimen.inventorysum.query / inventorysum.query
|
||||
- 5.50 订单出库统计查询接口:taobao.qimen.deliveryordersum.query / deliveryordersum.query
|
||||
|
||||
### 4.8 基础能力
|
||||
|
||||
- 5.51 心跳接口:taobao.qimen.service.heartbeat / service.heartbeat
|
||||
- 5.52 供应商信息同步接口:taobao.qimen.supplier.synchronize / supplier.synchronize
|
||||
- 5.53 配送公司信息查询:taobao.qimen.expressinfo.query / expressinfo.query
|
||||
|
||||
## 5. 官方白皮书里的关键细节
|
||||
|
||||
### 5.1 商品接口
|
||||
|
||||
- 单品查询与单品同步字段高度一致,itemCode、itemName、barCode、itemType、brand、重量、尺寸、批次、保质期相关字段都会复用
|
||||
- 批量商品同步使用 items 节点包裹 item 列表
|
||||
- 组合商品接口的核心是 itemCode、ownerCode、warehouseCode 与子商品清单
|
||||
|
||||
### 5.2 入库与退货入库
|
||||
|
||||
- entryorder.create 与 returnorder.create 都是同步创建
|
||||
- confirm 接口用于最终状态回告,不只是接收消息
|
||||
- 订单行内常包含 itemCode、itemId、planQty、actualQty、inventoryType、batchCode、productDate、expireDate、produceCode
|
||||
- 入库场景支持 relatedOrders 关联单据信息
|
||||
|
||||
### 5.3 出库与发货
|
||||
|
||||
- stockout 更偏普通出库,不强调订单履约语义
|
||||
- deliveryorder 更偏订单驱动发货
|
||||
- 批量版 create/confirm 接口支持 orders 与 order 节点
|
||||
- 发货单确认会带包裹、发票、物流、重量、体积、SN、批次等信息
|
||||
|
||||
### 5.4 库存与盘点
|
||||
|
||||
- inventory.query 与 stock.query 都是库存查询,但入参组织方式不同
|
||||
- inventory.report 与 inventorycheck.query 用于盘点回传和盘点查询
|
||||
- stockchange.report 用于把引起库存变动的单据和库存变化同步给 ERP
|
||||
|
||||
### 5.5 组织与基础资料
|
||||
|
||||
- warehouseinfo.query / synchronize 处理仓库基础资料
|
||||
- shop.synchronize 处理店铺基础资料
|
||||
- supplier.synchronize 处理供应商基础资料
|
||||
- expressinfo.query 处理配送公司信息
|
||||
|
||||
## 6. 本地实现落点
|
||||
|
||||
当前仓库里与奇门相关的本地实现入口主要是:
|
||||
|
||||
- app/service/qimen.js:统一 XML 解析、method 路由与 XML 响应封装
|
||||
- app/service/qimenMethods/:具体奇门业务方法实现目录
|
||||
- typings/app/service/index.d.ts:qimenMethods 的类型入口
|
||||
- methods/qimen.json:当前奇门方法定义与参数结构的主索引
|
||||
- methods/changes/qimen.json:奇门文档变更记录副本
|
||||
|
||||
从代码层看,qimen.js 会先解析 XML,再根据 method 对应到 qimenMethods 下的具体模块调用。
|
||||
|
||||
## 7. 排障时的实用检查点
|
||||
|
||||
1. 先确认 method 名是否与官方文档一致,尤其是 singleitem、deliveryorder、entryorder、returnorder、stockout、inventory 这些主模块
|
||||
2. 再确认 XML 根节点和字段名是否和官方定义一致,奇门对字段名大小写和层级通常比较敏感
|
||||
3. 关注 itemId 是否被误传为空,很多接口里它是条件必填
|
||||
4. 关注 warehouseCode 是否在统仓统配场景下正确使用 OTHER
|
||||
5. 批量接口要核对 totalOrderLines、currentPage、pageSize 和明细数量是否一致
|
||||
6. 发生返回 success 但业务未落库时,要继续检查本地实现是否只是接收成功而不是业务处理成功
|
||||
|
||||
## 8. 结论
|
||||
|
||||
这份奇门白皮书覆盖了 WMS 与 ERP 对接的完整主干能力,核心可以归纳为:
|
||||
|
||||
- 商品主数据
|
||||
- 入库、退货入库、出库、发货
|
||||
- SN、流水、状态、异常
|
||||
- 库存、盘点、加工、异动
|
||||
- 仓库、店铺、供应商、配送公司基础资料
|
||||
- 调拨、波次、缺货、规则、统计与心跳
|
||||
|
||||
在本仓库中,奇门的本地实现已经有统一入口和方法分层,适合把本文作为日常联调与故障排查的快速备忘。
|
||||
@ -1,80 +0,0 @@
|
||||
# 库存效期模块(定时预警任务)
|
||||
|
||||
本文档基于源码实现(单一事实来源),定位与说明项目中关于库存效期扫描与预警的定时任务行为。实现文件:app/schedule/notice_stock_remaining.js。
|
||||
|
||||
## 概要
|
||||
|
||||
- 任务名称/文件:`app/schedule/notice_stock_remaining.js`
|
||||
- 调度配置:`interval: '30s'`、`type: 'worker'`、`immediate: false`(见文件头部 schedule 配置)
|
||||
- 目的:扫描启用保质期管理的仓库商品与对应库存(wms_stock_warehouse / wms_storage),对即将到期的库存发送效期预警通知,并通过缓存进行去重。
|
||||
|
||||
## 主要实现要点(按代码实现逐项说明)
|
||||
|
||||
1. 并发保护
|
||||
- 使用进程级标记 `ctx.app._noticeStockRemainingRunning`,若上一轮尚未结束则跳过本次运行。
|
||||
|
||||
2. 通知去重缓存
|
||||
- 缓存键:`notice_stock_remaining_notified_list`(文件常量 `CACHE_KEY`)。
|
||||
- 缓存 TTL:24 小时(`CACHE_TTL_SECONDS = 24 * 60 * 60`)。
|
||||
- 缓存存储格式兼容数组或对象,读取后标准化为 `storage:{id}` 格式的键集合用于去重。
|
||||
|
||||
3. 读取候选商品(wms_stock_warehouse)
|
||||
- 查询条件(stockWhere):
|
||||
- `is_shelf_life_mgmt: 'Y'`
|
||||
- `remaining_threshold_days: { [Op.gt]: 0 }`(使用 `Sequelize.Op.gt`)
|
||||
- 查询字段:`id, item_code, item_name, store_id, warehouse_id, remaining_threshold_days`
|
||||
- 排序:`remaining_threshold_days ASC, id ASC`
|
||||
- 结果用于构建 `stockMap`(包含每个 stock 的阈值),并计算 `maxThresholdDays`(用于缩小后续库存扫描时间窗口)。
|
||||
|
||||
4. 计算候选库存时间窗口
|
||||
- 以当前时间 `now`,计算 `maxExpiryDate = new Date(now.getTime() + maxThresholdDays * DAY_MS)`,其中 `DAY_MS = 24 * 60 * 60 * 1000`。
|
||||
|
||||
5. 查询候选库存记录(wms_storage)
|
||||
- 查询条件(storageWhere):
|
||||
- `stock_id` 在上一步筛选得到的 `stockIds` 列表中
|
||||
- `is_enabled: 1`
|
||||
- `delete_at: null`(paranoid 软删除过滤)
|
||||
- `quantity: { [Op.gt]: 0 }`
|
||||
- `expiry_date: { [Op.ne]: null, [Op.lte]: maxExpiryDate }`(到期日非空且小于等于计算窗口)
|
||||
- include:关联 `LocationSpace`(别名 `space`),属性取 `space_code, custom_name`,`required: false`。
|
||||
- 排序:`expiry_date ASC, inbound_time ASC, id ASC`。
|
||||
- 注意:实现中调用的是 `findAll`(无分页),因此会拉取匹配的全部候选记录并在内存中逐条处理。
|
||||
|
||||
6. 单条记录处理与判断逻辑
|
||||
- 对每条 `storageRecord`:
|
||||
- 生成去重键 `notifyKey = storage:{storageId}`(若无法解析 id 则跳过)。
|
||||
- 若该 `notifyKey` 已存在于缓存集合则跳过(避免重复通知)。
|
||||
- 根据 `stockMap` 获取本条记录对应商品的 `thresholdDays`(阈值天数);若不存在或阈值 <= 0 则跳过。
|
||||
- 读取 `expiry_date`,将其解析为 Date;若无或解析失败则跳过并记录 warn。
|
||||
- 计算剩余天数:`remainingDays = Math.max(0, Math.ceil((expiryDate - now) / DAY_MS))`。
|
||||
- 若 `remainingDays > thresholdDays` 则跳过(未达到阈值);否则组装通知并发送。
|
||||
|
||||
7. 通知发送与元数据
|
||||
- 使用通知服务:`ctx.service.systems.notice.send(payload)`。代码中若 `noticeResult.success === false` 则认为发送失败并保留重试;异常时记录错误并继续处理下一条。
|
||||
- 通知 payload 包含(示例字段):
|
||||
- `warehouseId`, `storeId`, `subject`(id/type/name), `businessName: 'storage'`, `event`(常量 `storage_transfer_completed`),`title`, `content`, `businessId: storageId`, `messageType: 'text'`
|
||||
- `metadata`:包含 `cacheKey`, `storageId`, `stockId`, `notifyKey`, `thresholdDays`, `remainingDays`, `warehouseId`, `storeId`, `stock: { id, item_code, item_name }`, `storage: { id, batch_no, expiry_date (ISO) }`
|
||||
|
||||
8. 回写去重缓存
|
||||
- 成功发送后,将 `notifyKey` 添加到 `updatedNotifiedList` 并在本轮结束后使用 `ctx.app.setCacheAsync(CACHE_KEY, dedupedList, CACHE_TTL_SECONDS)` 回写缓存(如果 `setCacheAsync` 可用)。
|
||||
|
||||
9. 日志与统计
|
||||
- 任务会记录候选商品数、候选库存数、实际发送计数与跳过计数;发送失败与异常会记录 warn/error 日志。
|
||||
|
||||
## 与公开 API 的关系
|
||||
|
||||
- 任务为内部定时任务(非 system API),其查询条件与模型字段直接对应数据库表 `wms_stock_warehouse` 与 `wms_storage`。
|
||||
- 若需要通过 API 查询某个商品的库存明细(包含批次与过期信息),请使用已有的 system 方法 `stock.warehouse.getStockDetail`(该接口支持 `pagination` 与 `group_by_batch`,API 文档位于 `methods/system.json`),与本任务的扫描逻辑互为补充:任务用于主动推送预警,API 用于按需查询。
|
||||
|
||||
## 注意事项(运维/集成)
|
||||
|
||||
- 通知发送依赖 `ctx.service.systems.notice`,在无该服务或返回异常时任务仅记录日志。
|
||||
- 任务扫描不分页:对于极大库存量的仓库,建议评估 `maxThresholdDays` 与索引(`idx_expiry_date` 已存在于模型)对查询性能的影响,或考虑将查询改为分片/分页处理。
|
||||
- 去重缓存使用全局缓存接口 `getCacheAsync` / `setCacheAsync`,请保证缓存后台(如 Redis)可用以避免重复通知泛滥。
|
||||
|
||||
## 实现位置(代码参考)
|
||||
|
||||
- 定时任务文件:app/schedule/notice_stock_remaining.js
|
||||
- 依赖模型:app/model/stock_warehouse.js、app/model/storage.js、app/model/location_space.js
|
||||
- 依赖服务:ctx.service.systems.notice
|
||||
|
||||
@ -1,178 +0,0 @@
|
||||
# stock.warehouse.list 前端查询规则
|
||||
|
||||
## 目的
|
||||
|
||||
本文档约束 `stock.warehouse.list` 的 `where` 构造格式,便于前端统一构建查询条件,并与后端解析器保持一致。
|
||||
|
||||
## 接口入口
|
||||
|
||||
- 路由:`POST /system`
|
||||
- method:`stock.warehouse.list`
|
||||
|
||||
## 请求体结构
|
||||
|
||||
```json
|
||||
{
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"pageSize": 20
|
||||
},
|
||||
"where": {
|
||||
"item_code": {
|
||||
"operator": "like",
|
||||
"value": "SKU",
|
||||
"type": "text"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## where 字段规则
|
||||
|
||||
`where` 必须是对象,且每个字段值也必须是对象。
|
||||
|
||||
正确示例:
|
||||
|
||||
```json
|
||||
{
|
||||
"where": {
|
||||
"item_name": {
|
||||
"operator": "like",
|
||||
"value": "鞋",
|
||||
"type": "text"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
错误示例(会返回解析失败原因):
|
||||
|
||||
```json
|
||||
{
|
||||
"where": {
|
||||
"item_name": "鞋"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 条件对象结构
|
||||
|
||||
每个 `where.<field>` 支持:
|
||||
|
||||
- `operator`:操作符,默认 `eq`
|
||||
- `value`:查询值
|
||||
- `type`:值类型(可选)
|
||||
- `field`:映射到真实字段(一般不需要前端传)
|
||||
|
||||
### 支持操作符
|
||||
|
||||
- `eq`
|
||||
- `ne`
|
||||
- `like` / `contains`
|
||||
- `startswith`
|
||||
- `endswith`
|
||||
- `gt`
|
||||
- `lt`
|
||||
- `ge`
|
||||
- `le`
|
||||
- `in`
|
||||
- `notin`
|
||||
- `between`
|
||||
- `notbetween`
|
||||
- `isnull`
|
||||
- `isnotnull`
|
||||
- `regexp`
|
||||
- `notregexp`
|
||||
|
||||
### 支持 type
|
||||
|
||||
- `boolean`:转换为 `Y/N`
|
||||
- `number`:转换为数字
|
||||
- `date`:日期字符串归一化
|
||||
- `daterange`:日期数组归一化
|
||||
- `text`:逗号分隔字符串拆分数组
|
||||
|
||||
## 特殊字段说明
|
||||
|
||||
### barcode
|
||||
|
||||
- 在条码表中先匹配,再回灌 `stock_id` 过滤主表。
|
||||
- 推荐:`operator=eq|like`。
|
||||
|
||||
### prohibited_type
|
||||
|
||||
- 传入的是违禁品类型 `id`。
|
||||
- 后端会映射到关联模型进行过滤。
|
||||
|
||||
### has_bound_item
|
||||
|
||||
- 筛选仓库商品是否已绑定外部商品(货主商品)。
|
||||
- `operator`:固定 `eq`(默认)。
|
||||
- `value`:
|
||||
- 已绑定:`true` / `1` / `"Y"` / `"y"`
|
||||
- 未绑定:`false` / `0` / `"N"` / `"n"`
|
||||
- 示例:
|
||||
- 查询已绑定外部商品的仓库商品:`has_bound_item={operator:eq,value:true}`
|
||||
- 查询未绑定外部商品的仓库商品:`has_bound_item={operator:eq,value:false}`
|
||||
|
||||
## 空值处理
|
||||
|
||||
以下值会被视为“空条件”并跳过:
|
||||
|
||||
- `null`
|
||||
- `undefined`
|
||||
- `""`
|
||||
- `[]`
|
||||
|
||||
## 排序规则
|
||||
|
||||
后端只接受以下排序字段:
|
||||
|
||||
- `id`
|
||||
- `item_code`
|
||||
- `item_name`
|
||||
- `quantity`
|
||||
- `locked_quantity`
|
||||
- `tag_price`
|
||||
- `retail_price`
|
||||
- `create_at`
|
||||
- `update_at`
|
||||
|
||||
当传入非法排序字段时,会回退为:
|
||||
|
||||
- `sortField=create_at`
|
||||
- `sortOrder=DESC`
|
||||
|
||||
## 失败返回(解构失败)
|
||||
|
||||
当 `where` 结构不合法时,返回示例:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "筛选条件解析失败: 字段 item_code 条件必须是对象",
|
||||
"data": {
|
||||
"list": [],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"pageSize": 20,
|
||||
"total": 0,
|
||||
"totalPages": 0,
|
||||
"hasPrevious": false,
|
||||
"hasNext": false
|
||||
},
|
||||
"summary": {
|
||||
"total_quantity": 0,
|
||||
"total_locked": 0,
|
||||
"total_available": 0,
|
||||
"total_items": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 前端建议
|
||||
|
||||
- 对 `in/notin/between/notbetween` 先做数组校验,再发请求。
|
||||
- 对 `where` 做 schema 校验,避免后端 400。
|
||||
- 对空输入不构造条件,减少无效查询。
|
||||
@ -1,487 +0,0 @@
|
||||
# 收货单 API 文档(`storage.receiving`)
|
||||
|
||||
## 1. 文档说明
|
||||
|
||||
本文档补充 `storage.receiving` 相关 system 方法中的收货明细商品绑定接口,当前重点覆盖:
|
||||
|
||||
- `storage.receiving.bindDetailProduct`
|
||||
|
||||
适用场景:
|
||||
|
||||
- 新增收货单明细后,为该明细绑定系统商品
|
||||
- 已绑定商品时,改绑为另一个系统商品
|
||||
- 前端或第三方系统对接收货单明细与系统商品的匹配动作
|
||||
|
||||
---
|
||||
|
||||
## 2. 统一调用方式
|
||||
|
||||
该项目的 system 方法统一通过 `/system` 调用,方法名通过 query 参数 `method` 传入。
|
||||
|
||||
### 请求方式
|
||||
|
||||
```http
|
||||
POST /system?method=storage.receiving.bindDetailProduct&v=1.0×tamp={unix_timestamp}
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer <token>
|
||||
platform: web
|
||||
project: wms
|
||||
```
|
||||
|
||||
### 调用示例
|
||||
|
||||
```bash
|
||||
curl -X POST "http://127.0.0.1:6060/system?method=storage.receiving.bindDetailProduct&v=1.0×tamp=1712400000" \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "platform: web" \
|
||||
-H "project: wms" \
|
||||
-d '{
|
||||
"detail_id": 12345,
|
||||
"system_product_id": 67890
|
||||
}'
|
||||
```
|
||||
|
||||
> 说明:该接口通常要求用户已登录,并以当前仓库角色执行;实际仓库上下文来自 `ctx.user.store_id`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 接口:`storage.receiving.bindDetailProduct`
|
||||
|
||||
### 3.1 接口用途
|
||||
|
||||
用于**绑定或改绑收货单明细的系统商品**。
|
||||
|
||||
调用成功后,系统会按当前仓库商品信息自动回填或更新以下内容:
|
||||
|
||||
- `system_product_id`
|
||||
- `product_name`
|
||||
- `product_snapshot`
|
||||
- `barcode`(有条码时)
|
||||
- `weight`(商品存在毛重时)
|
||||
- 箱规尺寸字段(启用箱规时)
|
||||
|
||||
同时会刷新整张收货单的统计信息。
|
||||
|
||||
### 3.2 请求参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---:|---|---|
|
||||
| `detail_id` | `number` | 是 | 收货单明细 ID |
|
||||
| `id` | `number` | 否 | 兼容字段,可替代 `detail_id` |
|
||||
| `system_product_id` | `number` | 是 | 要绑定的系统商品 ID(`StockWarehouse.id`) |
|
||||
|
||||
### 3.3 请求体示例
|
||||
|
||||
```json
|
||||
{
|
||||
"detail_id": 12345,
|
||||
"system_product_id": 67890
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 成功返回示例
|
||||
|
||||
```json
|
||||
{
|
||||
"flag": "success",
|
||||
"code": 200,
|
||||
"message": "绑定商品成功",
|
||||
"data": {
|
||||
"detail_id": 12345,
|
||||
"receiving_id": 10001,
|
||||
"system_product_id": 67890,
|
||||
"product_name": "测试商品A"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 返回字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---:|---|
|
||||
| `flag` | `string` | 固定为 `success` |
|
||||
| `code` | `number` | 业务状态码,成功为 `200` |
|
||||
| `message` | `string` | 返回说明 |
|
||||
| `data.detail_id` | `number` | 当前绑定的收货单明细 ID |
|
||||
| `data.receiving_id` | `number` | 收货单 ID |
|
||||
| `data.system_product_id` | `number` | 当前绑定的系统商品 ID |
|
||||
| `data.product_name` | `string` | 自动回填的商品名称 |
|
||||
|
||||
> 注意:该项目的 system 方法经常返回 HTTP `200`,业务是否成功请以响应体内的 `code` 和 `message` 为准。
|
||||
|
||||
---
|
||||
|
||||
## 5. 业务校验规则
|
||||
|
||||
接口内部会执行以下校验:
|
||||
|
||||
1. **当前用户必须有仓库上下文**
|
||||
- 仓库 ID 取自 `ctx.user.store_id`
|
||||
2. **收货单明细必须存在**
|
||||
3. **收货单明细必须属于当前仓库**
|
||||
4. **收货单状态必须为 `receiving`**
|
||||
- 已完成、已作废等状态不允许继续绑定或改绑
|
||||
5. **目标商品必须属于当前仓库**
|
||||
- 根据 `StockWarehouse.id + warehouse_id` 校验
|
||||
|
||||
---
|
||||
|
||||
## 6. 失败返回示例与错误码
|
||||
|
||||
### 常见失败场景
|
||||
|
||||
| `code` | `message` 示例 | 含义 |
|
||||
|---:|---|---|
|
||||
| `400` | `用户未绑定仓库` | 当前用户无仓库角色上下文 |
|
||||
| `400` | `收货单明细ID不能为空` | 未传 `detail_id` / `id` |
|
||||
| `400` | `商品ID不能为空` | 未传 `system_product_id` |
|
||||
| `400` | `收货单状态不允许绑定或改绑商品` | 当前收货单状态不允许继续操作 |
|
||||
| `404` | `收货单明细不存在` | 明细不存在或不属于当前仓库 |
|
||||
| `404` | `商品不存在或不属于当前仓库` | 商品不存在或仓库不匹配 |
|
||||
| `500` | `绑定商品失败: <error>` | 服务内部异常 |
|
||||
|
||||
### 失败响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"flag": "success",
|
||||
"code": 404,
|
||||
"message": "商品不存在或不属于当前仓库"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 推荐调用链路
|
||||
|
||||
典型前端操作顺序如下:
|
||||
|
||||
1. `storage.receiving.create`:创建收货单
|
||||
2. `storage.receiving.addDetail`:新增空白明细,拿到 `selectId`
|
||||
3. `storage.receiving.bindDetailProduct`:绑定系统商品
|
||||
4. `storage.receiving.detailChange`:补充数量、箱数、备注等字段
|
||||
5. `storage.receiving.completeReceiving`:完成收货
|
||||
|
||||
其中第 2 步新增明细后,一般会返回:
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"selectId": 12345
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
该 `selectId` 即可直接作为 `bindDetailProduct` 的 `detail_id`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 回归验证参考
|
||||
|
||||
仓库中已有接口级回归用例,可作为联调参考:
|
||||
|
||||
- `test/app/controller/system.storage.receiving.test.js`
|
||||
|
||||
已覆盖的场景包括:
|
||||
|
||||
- 新建收货单后绑定商品
|
||||
- 已绑定商品后再次改绑
|
||||
- 绑定成功后返回 `detail_id`、`system_product_id`、`product_name`
|
||||
|
||||
---
|
||||
|
||||
## 9. 实现位置(源码定位)
|
||||
|
||||
### system 方法包装层
|
||||
|
||||
- 文件:`app/service/systemMethods/storage/receiving.js`
|
||||
- 方法:`bindDetailProduct(data)`
|
||||
|
||||
### 实际业务实现
|
||||
|
||||
- 文件:`app/service/systems/storage/receiving.js`
|
||||
- 方法:`bindDetailProduct(data)`
|
||||
|
||||
---
|
||||
|
||||
## 10. 当前接口结论
|
||||
|
||||
`storage.receiving.bindDetailProduct` 当前已支持:
|
||||
|
||||
- **绑定** 收货明细商品
|
||||
- **改绑** 收货明细商品
|
||||
- 自动回填商品名称、条码、重量、箱规等信息
|
||||
- 自动刷新收货单统计数据
|
||||
|
||||
适合作为收货单明细与系统商品标准匹配接口对外说明使用。
|
||||
|
||||
---
|
||||
|
||||
## 11. 接口:storage.receiving.detailChange
|
||||
|
||||
### 11.1 接口用途
|
||||
|
||||
用于修改收货单明细(明细行)中的数量、箱规、批次与商品信息,并触发收货单统计与相关联动(例如库存/统计刷新与操作日志)。典型场景为:前端在录入收货明细后,补录实际收货数量、箱数、托盘数、批次/生产/到期信息或回写条码与商品名称等。
|
||||
|
||||
> 注意:方法在 system 层以 `POST /system?method=storage.receiving.detailChange` 调用,需包含 `Authorization: Bearer <token>`,仓库上下文来源于 `ctx.user.store_id`。
|
||||
|
||||
### 11.2 请求参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---:|---:|---|
|
||||
| `id` | `number` | 是 | 收货明细 ID(必填) |
|
||||
| `receiving_id` | `number` | 是 | 收货单 ID(必填) |
|
||||
| `actual_quantity` | `number` | 否 | 实际收货数量 |
|
||||
| `batch_number` | `string` | 否 | 批次号 |
|
||||
| `production_date` | `string` | 否 | 生产日期(ISO 或可解析的日期字符串) |
|
||||
| `expiry_date` | `string` | 否 | 到期日期(ISO 或可解析的日期字符串)。若传入的 `expiry_date` 小于当前日期,接口会拒绝并返回 400(见错误码) |
|
||||
| `box_quantity` | `number` | 否 | 箱数 |
|
||||
| `boxes_per_pallet` | `number` | 否 | 每托盘箱数 |
|
||||
| `pallet_quantity` | `number` | 否 | 托盘数 |
|
||||
| `space_id` | `number` | 否 | 目标库位 ID(可用于回写库位) |
|
||||
| `remark` | `string` | 否 | 备注 |
|
||||
| `system_product_id` | `number` | 否 | 系统商品 ID(StockWarehouse.id)。若提供,系统会回填条码、重量、箱规、商品名称与快照等;若不提供,可单独更新 `barcode`/`product_name` |
|
||||
| `barcode` | `string` | 否 | 条码(当未传 `system_product_id` 时,可单独更新) |
|
||||
| `product_name` | `string` | 否 | 商品名称(当未传 `system_product_id` 时,可单独更新) |
|
||||
| `box_width` | `number` | 否 | 箱宽(单位按系统约定) |
|
||||
| `box_height` | `number` | 否 | 箱高 |
|
||||
| `box_length` | `number` | 否 | 箱长 |
|
||||
| `box_remainder` | `number` | 否 | 箱内剩余数量/零散数量(不满箱时的件数) |
|
||||
| `box_weight` | `number` | 否 | 实测箱重(单位与系统重量一致,如 kg) |
|
||||
| `weight` | `number` | 否 | 毛重/重量 |
|
||||
|
||||
> 说明:`id` 与 `receiving_id` 为必须校验项,其他字段为可选—仅在传入时会写入/覆盖对应明细字段。传入 `system_product_id` 时,系统优先使用系统商品信息回填字段(前端可只传 `system_product_id` 来自动回填)。
|
||||
|
||||
### 11.3 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 501,
|
||||
"receiving_id": 123,
|
||||
"actual_quantity": 10,
|
||||
"batch_number": "B20260401",
|
||||
"production_date": "2026-04-01",
|
||||
"expiry_date": "2027-04-01",
|
||||
"box_quantity": 2,
|
||||
"boxes_per_pallet": 10,
|
||||
"pallet_quantity": 0,
|
||||
"space_id": 1001,
|
||||
"remark": "样例备注",
|
||||
"system_product_id": 8888
|
||||
}
|
||||
```
|
||||
|
||||
### 11.4 返回结构(成功)
|
||||
|
||||
成功时返回 `code: 200`,`message` 为 `修改成功`,`data` 中包含基础标识与关键展示字段:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "修改成功",
|
||||
"data": {
|
||||
"id": 501,
|
||||
"receiving_id": 123,
|
||||
"actual_quantity": 1,
|
||||
"product_name": "测试商品",
|
||||
"barcode": "",
|
||||
"system_product_id": null,
|
||||
"box_remainder": 0,
|
||||
"box_weight": 0.0,
|
||||
"updated_at": "2026-04-01T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
返回字段说明:
|
||||
|
||||
- `data.id`:收货明细 ID
|
||||
- `data.receiving_id`:收货单 ID
|
||||
- `data.actual_quantity`:明细当前的实际收货数量(根据实现,此处返回服务端查询到的明细值)
|
||||
- `data.product_name`:商品名称(若 `system_product_id` 回填则为系统商品名称)
|
||||
- `data.barcode`:条码
|
||||
- `data.system_product_id`:回填或当前关联的系统商品 ID
|
||||
- `data.box_remainder`:箱内剩余数量/零散数量(不满箱时的件数)
|
||||
- `data.box_weight`:实测箱重(单位与系统重量一致)
|
||||
- `data.updated_at`:明细记录的更新时间
|
||||
|
||||
### 11.5 常见错误码
|
||||
|
||||
| code | message 示例 | 含义 |
|
||||
|---:|---|---|
|
||||
| `400` | `收货明细ID不能为空` | 未传 `id` |
|
||||
| `400` | `收货单ID不能为空` | 未传 `receiving_id` |
|
||||
| `400` | `到期日期已过期,不能录入收货` | `expiry_date` 小于当前日期时返回(禁止录入已过期批次) |
|
||||
| `400` | `箱数不能为负数` / `托盘数不能为负数` | 非法的箱规数值 |
|
||||
| `404` | `收货明细不存在` | 明细不存在或不属于当前仓库/收货单状态不允许操作 |
|
||||
| `500` | `修改失败,请稍后重试` | 服务端异常 |
|
||||
|
||||
---
|
||||
|
||||
### 11.6 业务要点与实现说明
|
||||
|
||||
- 若传入 `system_product_id`,服务端尝试读取 `StockWarehouse`(同仓库)并回填:`barcode`(若前端未显式传入),`weight`,`boxes_per_pallet`、`box_height`、`box_width`、`box_length`(若启用箱规),以及 `product_snapshot` 中的货主快照信息。
|
||||
- 若未传 `system_product_id`,但传入 `barcode` 或 `product_name`,服务端仍允许更新这两个字段(并把 `system_product_id` 置为 `null`)。
|
||||
- 接口会在成功写入明细后触发收货单统计刷新(`updateReceivingStats`)并写操作日志(`RECEIVING_UPDATE_DETAIL`)。
|
||||
- 系统存在一个库存效期预警定时任务,逻辑上会扫描启用保质期管理且设置了剩余天数阈值的商品,并按库存到期日筛选候选记录后进行去重通知发送;其判断条件主要依赖 `wms_stock_warehouse.is_shelf_life_mgmt = 'Y'`、`remaining_threshold_days > 0`,以及 `wms_storage.expiry_date`(小于等于当前时间加最大阈值天数)。
|
||||
|
||||
---
|
||||
|
||||
## 12. 接口:storage.receiving.getReceivingDetail
|
||||
|
||||
## 接口:storage.receiving.get
|
||||
|
||||
### 用途
|
||||
|
||||
查询收货单完整信息(含明细 `details`、`images` 等)。
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---:|---|---|
|
||||
| `id` | `number` | 是 | 收货单 ID(source=body) |
|
||||
|
||||
### 返回字段补充
|
||||
|
||||
- `data.details.*.box_remainder`:number,可选,箱内剩余数量/零散数量(不满箱时的件数),默认 0。
|
||||
- `data.details.*.box_weight`:number,可选,实测箱重(单位与系统重量一致,如 kg),默认 0。
|
||||
|
||||
兼容性:新增字段为可选,旧客户端无需变更。
|
||||
|
||||
### 12.1 用途
|
||||
|
||||
查询单张收货单详情,返回收货单头信息与明细(`details`),用于前端展示或二次处理。
|
||||
|
||||
### 12.2 请求参数
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---:|---|---|
|
||||
| `id` | `number` | 是 | 收货单 ID |
|
||||
| `pagination` | `object` | 否 | 明细分页参数,支持 `page` / `pageSize` |
|
||||
|
||||
### 12.3 返回示例(成功)
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"receiving": {
|
||||
"id": 12345,
|
||||
"receiving_number": "RCV20260506001",
|
||||
"details": [
|
||||
{
|
||||
"id": 501,
|
||||
"product_name": "测试商品",
|
||||
"actual_quantity": 10,
|
||||
"box_quantity": 2,
|
||||
"box_remainder": 0,
|
||||
"box_weight": 5.2
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"pageSize": 20,
|
||||
"total": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 12.4 返回字段说明(新增)
|
||||
|
||||
- `receiving.details.*.box_remainder`:number,可选,箱内剩余数量/零散数量(不满箱时的件数)。
|
||||
- `receiving.details.*.box_weight`:number,可选,实测箱重(单位与系统重量一致,如 kg)。
|
||||
|
||||
## 13. 接口:storage.receiving.completeReceiving
|
||||
|
||||
### 13.1 用途
|
||||
|
||||
完成收货操作;完成后系统会发送内部通知/回调,通知中会包含收货单明细层面的箱规回写信息。
|
||||
|
||||
### 13.2 通知说明(新增字段)
|
||||
|
||||
完成收货时发送的通知 payload/metadata 将在每条明细中包含 `box_remainder` 与 `box_weight`,用于下游系统或前端展示箱内余量与实测箱重。通知示例(结构化示例,字段以实现为准):
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "storage.receiving.completed",
|
||||
"receiving_id": 12345,
|
||||
"details": [
|
||||
{
|
||||
"id": 501,
|
||||
"box_remainder": 0,
|
||||
"box_weight": 5.2
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"completed_by": 1001,
|
||||
"completed_at": "2026-05-06T12:00:00.000Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 13.3 字段说明(通知/metadata)
|
||||
|
||||
- `details[*].box_remainder`:number,可选,箱内剩余数量/零散数量。
|
||||
- `details[*].box_weight`:number,可选,实测箱重,单位同系统重量(例如 kg)。
|
||||
|
||||
兼容性:上述新增字段为可选字段,旧版消费者在未识别这些字段时可忽略。
|
||||
|
||||
---
|
||||
|
||||
## 14. 收货→入库完整流程
|
||||
|
||||
### 14.1 流程概览
|
||||
|
||||
收货完成后,商品库存的实际入库通过以下步骤完成:
|
||||
|
||||
1. **创建入库单** → `storage.entry` 系列方法(list/get/cancel/completeEntry)
|
||||
2. **匹配入库(写库存)** → `storage.inventory.matchPutaway`(**目前唯一的库存写入入库链路**)
|
||||
|
||||
> ⚠️ 注意:`storage.entry.completeEntry` 仅做入库单状态变更(PENDING → COMPLETED),**不涉及库存写入**。库存的实际写入统一由 `storage.inventory.matchPutaway` 完成。
|
||||
|
||||
### 14.2 完整推荐流程
|
||||
|
||||
```
|
||||
1. storage.receiving.create → 创建收货单
|
||||
2. storage.receiving.addDetail → 新增明细,拿到 selectId
|
||||
3. storage.receiving.bindDetailProduct → 绑定系统商品
|
||||
4. storage.receiving.detailChange → 补充数量、批次等
|
||||
5. storage.receiving.completeReceiving → 完成收货
|
||||
↓
|
||||
6. storage.entry 入库单管理 → 入库单与收货单通过 wms_entry_order_receiving 主表级关联
|
||||
7. storage.inventory.matchPutaway → 收货单与入库单匹配,完成库存写入
|
||||
8. storage.entry.completeEntry → 入库单状态标记为 COMPLETED(仅状态变更)
|
||||
```
|
||||
|
||||
### 14.3 已弃用的方法
|
||||
|
||||
以下方法已从代码中移除,**不再可用**:
|
||||
|
||||
| 已弃用方法 | 弃用原因 | 替代方案 |
|
||||
|---|---|---|
|
||||
| `storage.entry.bindReceivingDetails` | 入库单明细与收货明细逐行绑定(基于 `wms_entry_receiving_binding` 表),关系已改为 `wms_entry_order_receiving` 主表级关联 | 不再需要,入库单与收货单直接通过主表关联 |
|
||||
| `storage.entry.unbindReceivingDetails` | 同上,逐行解绑已无必要 | 不再需要 |
|
||||
| `storage.inventory.quickPutaway` | 单一收货单快捷转入库单(已重新实现):按 stock_id 合并收货明细创建入库单(SCRK,自动审批到 PENDING),写入主表级绑定 | `storage.entry.commitDirectInbound`(导入/PDA 入库完成确认) |
|
||||
|
||||
### 14.4 核心方法职责
|
||||
|
||||
| 方法 | 职责 | 备注 |
|
||||
|---|---|---|
|
||||
| `storage.inventory.matchPutaway` | **唯一库存写入入库链路**:接收多个收货单和多个入库单,按商品进行数量匹配,完成库存的实际写入 | 入库后根据来源(QM/API)自动触发回传 |
|
||||
| `storage.entry.completeEntry` | **仅状态变更**:入库单 PENDING → COMPLETED | 不涉及任何库存写入 |
|
||||
| `storage.entry.list` | 入库单列表查询 | 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED 状态筛选 |
|
||||
| `storage.entry.get` | 入库单详情查询 | 含 items 及其 bindings |
|
||||
| `storage.entry.cancel` | 作废入库单(CREATED/PENDING 可作废) | COMPLETED 不可作废 |
|
||||
|
||||
### 14.5 关键数据库表关系
|
||||
|
||||
- `wms_entry_order_receiving`:入库单与收货单的**主表级关联**(当前方案)
|
||||
- `wms_entry_receiving_binding`:**已弃用**,不再写入新数据(旧方案:明细级绑定)
|
||||
- 收货单与入库单不再需要逐明细绑定,通过主表关联即可完成匹配入库
|
||||
|
||||
@ -4673,5 +4673,47 @@
|
||||
"文档中 isNeedLogin 为 false,但代码 systemMethods/quick/waybill.js 中 _noNeedLogin 为空字符串,未将 toOrder 加入免登录列表,实际需要登录验证,修正文档以与代码一致。"
|
||||
],
|
||||
"type": "fixed"
|
||||
},
|
||||
{
|
||||
"version": "2026.07.03-system-01",
|
||||
"date": "2026-07-03",
|
||||
"summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog",
|
||||
"methods": [
|
||||
"storage.entry.getDirectInboundItems"
|
||||
],
|
||||
"notes": [
|
||||
"bindings 数组 description 中 wms_entry_receiving_binding 引用更新为 InboundDirectLog,明确旧表已弃用",
|
||||
"binding_id description 中 wms_entry_receiving_binding.id 更新为 InboundDirectLog.id",
|
||||
"allocated_quantity description 中补充来源 InboundDirectLog.quantity",
|
||||
"wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at"
|
||||
],
|
||||
"type": "updated"
|
||||
},
|
||||
{
|
||||
"version": "2026.07.03-system-02",
|
||||
"date": "2026-07-03",
|
||||
"summary": "binding 表弃用文档同步:wms_entry_receiving_binding 已弃用,功能迁移到 wms_inbound_direct_log 表;bindings 描述中表引用更新为 InboundDirectLog",
|
||||
"methods": [
|
||||
"storage.directInbound.getItems"
|
||||
],
|
||||
"notes": [
|
||||
"bindings 数组 description 中更新为来自 InboundDirectLog,明确旧表已弃用",
|
||||
"binding_id description 更新为 InboundDirectLog.id",
|
||||
"allocated_quantity description 中补充来源 InboundDirectLog.quantity",
|
||||
"wms_inbound_direct_log 表新增字段:entry_item_id、receiving_detail_id、status(ENUM: pending/committed/released)、updated_at、deleted_at"
|
||||
],
|
||||
"type": "updated"
|
||||
},
|
||||
{
|
||||
"version": "2026.07.03-system-03",
|
||||
"date": "2026-07-03",
|
||||
"summary": "binding 表弃用文档同步:commitDirectInbound 描述中 EntryReceivingBinding 更新为 InboundDirectLog",
|
||||
"methods": [
|
||||
"storage.entry.commitDirectInbound"
|
||||
],
|
||||
"notes": [
|
||||
"commitDirectInbound description 中将 pending 状态的 EntryReceivingBinding 更新为 pending 状态的 InboundDirectLog,与代码实现一致"
|
||||
],
|
||||
"type": "updated"
|
||||
}
|
||||
]
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
{
|
||||
"module": "system",
|
||||
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
|
||||
"version": "0.3.5",
|
||||
"updatedAt": "2026-07-02",
|
||||
"version": "0.3.6",
|
||||
"updatedAt": "2026-07-03",
|
||||
"headers": [
|
||||
{
|
||||
"name": "platform",
|
||||
@ -2708,6 +2708,82 @@
|
||||
"description": "订单不存在或不属于当前仓库"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"method": "reviewOrder.detail",
|
||||
"description": "查询单个订单详情,返回订单头、商品明细和运单信息",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
{
|
||||
"name": "Authorization",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "Bearer token"
|
||||
}
|
||||
],
|
||||
"params": [
|
||||
{
|
||||
"name": "ids / id / order_id / orderId",
|
||||
"type": "array|string|number",
|
||||
"required": true,
|
||||
"source": "body",
|
||||
"description": "订单ID;支持 ids 数组、逗号分隔字符串或单个 id/order_id,至少提供一项"
|
||||
},
|
||||
{
|
||||
"name": "tableType / tablePosition / type / moduleName",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "可选,指定订单表类型,支持 current/history/dispatch/outsourced/order/revieworder/pendingorder 等"
|
||||
}
|
||||
],
|
||||
"response": [
|
||||
{
|
||||
"name": "order",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "订单头对象(raw 行数据)"
|
||||
},
|
||||
{
|
||||
"name": "detail",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "等同于 order"
|
||||
},
|
||||
{
|
||||
"name": "orderItems / items",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "商品明细数组"
|
||||
},
|
||||
{
|
||||
"name": "expresses",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "运单信息数组"
|
||||
},
|
||||
{
|
||||
"name": "waybill_codes",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "去重后的运单号字符串数组"
|
||||
}
|
||||
],
|
||||
"errors": [
|
||||
{
|
||||
"code": "400",
|
||||
"message": "订单ID 为空或格式错误"
|
||||
},
|
||||
{
|
||||
"code": "404",
|
||||
"message": "订单不存在或不属于当前仓库"
|
||||
},
|
||||
{
|
||||
"code": "500",
|
||||
"message": "内部错误"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
@ -18892,9 +18968,90 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"groupName": "入库管理",
|
||||
"groupName": "入库模块",
|
||||
"module": "storage.entry",
|
||||
"list": [
|
||||
{
|
||||
"method": "storage.entry.list",
|
||||
"description": "入库单列表查询。where.order_status 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(通过 wms_entry_order_receiving 表查询实现)。quickWhere 支持模糊搜索:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
{
|
||||
"name": "Authorization",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "Bearer token"
|
||||
}
|
||||
],
|
||||
"params": [
|
||||
{
|
||||
"name": "pagination",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "分页参数,支持 page/pageSize"
|
||||
},
|
||||
{
|
||||
"name": "where",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、order_status(CREATING/CREATED/PENDING/COMPLETED/CANCELLED)、store_id、order_type、日期区间等字段。新增 expense_record(费用是否记录)筛选,支持 eq/in;值会归一化为 0/1,兼容 true/false、1/0、y/n、yes/no(大小写不敏感,含布尔/字符串/数字写法)。示例:where.expense_record={operator:eq,value:true} 等价 where.expense_record={operator:eq,value:1};where.expense_record={operator:in,value:[true,\"0\",\"yes\",\"n\"]} 会归一化为 [1,0]。若部署环境尚未完成 expense_record 字段迁移,传入该筛选可能返回 400,错误提示为\"当前环境未提供 expense_record 字段,暂不支持该筛选条件,请先完成表结构升级\"。新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(虚拟字段,不直接对应数据库列,内部通过 wms_entry_order_receiving 表查询实现)。quickWhere 模糊搜索范围:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。"
|
||||
},
|
||||
{
|
||||
"name": "sort",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "排序参数,支持 sortField/sortOrder"
|
||||
}
|
||||
],
|
||||
"response": [
|
||||
{
|
||||
"name": "list",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "入库单列表"
|
||||
},
|
||||
{
|
||||
"name": "pagination",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
|
||||
},
|
||||
{
|
||||
"name": "summary",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "状态汇总(total、pending、creating、created、completed、cancelled)"
|
||||
},
|
||||
{
|
||||
"name": "list[].receivingBindings",
|
||||
"type": "array",
|
||||
"required": false,
|
||||
"description": "收货单绑定列表(主表级关联),每项含 id、entry_order_id、receiving_id 及 receiving 对象(id、receiving_number、status、storage_status、created_at)"
|
||||
},
|
||||
{
|
||||
"name": "list[].hasReceiving",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"description": "是否存在收货单绑定"
|
||||
}
|
||||
],
|
||||
"errors": [
|
||||
{
|
||||
"code": "400",
|
||||
"message": "筛选条件格式错误",
|
||||
"description": "筛选条件格式错误"
|
||||
},
|
||||
{
|
||||
"code": "500",
|
||||
"message": "查询失败",
|
||||
"description": "查询失败"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"method": "storage.entry.get",
|
||||
"description": "查询入库单详情。返回的 entryOrder 包含顶层 receivingBindings(主表级关联,含关联的收货单信息),不再返回 items[].bindings(明细级绑定)。entryOrder.order_status 可能为 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。",
|
||||
@ -19156,175 +19313,6 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"method": "storage.entry.getDirectInboundItems",
|
||||
"description": "获取入库单的导入/PDA 入库信息(精简版)。返回入库单基本信息、明细列表(含计划数量 planned 与已完成数量 completed)、每项明细的收货绑定列表 bindings(含 detail_id、binding_id、allocated_quantity、space_id、space_name),以及收货单绑定关系 receivingBindings。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
{
|
||||
"name": "Authorization",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "Bearer token"
|
||||
}
|
||||
],
|
||||
"params": [
|
||||
{
|
||||
"name": "entry_order_code",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"source": "body",
|
||||
"description": "入库单号"
|
||||
}
|
||||
],
|
||||
"response": [
|
||||
{
|
||||
"name": "entryOrder",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "入库单基本信息",
|
||||
"children": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "入库单ID"
|
||||
},
|
||||
{
|
||||
"name": "entry_order_code",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "入库单号"
|
||||
},
|
||||
{
|
||||
"name": "order_status",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "入库单状态(CREATED/PENDING/COMPLETED/CANCELLED)"
|
||||
},
|
||||
{
|
||||
"name": "store_remask",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "货主商家备注"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "items",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "入库明细列表",
|
||||
"children": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "入库明细ID(wms_entry_items.id)"
|
||||
},
|
||||
{
|
||||
"name": "stock_id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "商品SKU ID"
|
||||
},
|
||||
{
|
||||
"name": "planned",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "计划入库数量(对应原 count 字段)"
|
||||
},
|
||||
{
|
||||
"name": "completed",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "已完成导入/PDA 入库数量(对应原 direct_inbound_quantity 字段)"
|
||||
},
|
||||
{
|
||||
"name": "stock",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "商品详情(含 item_code、item_name、sku_property、barcodes 等缓存字段)"
|
||||
},
|
||||
{
|
||||
"name": "bindings",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "该明细的收货单绑定列表(来自 wms_entry_receiving_binding + InboundDirectLog)",
|
||||
"children": [
|
||||
{
|
||||
"name": "detail_id",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "收货明细ID(wms_receiving_detail.id),无绑定时可能不存在"
|
||||
},
|
||||
{
|
||||
"name": "binding_id",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "绑定记录ID(wms_entry_receiving_binding.id),无绑定时可能不存在"
|
||||
},
|
||||
{
|
||||
"name": "allocated_quantity",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "预分配数量"
|
||||
},
|
||||
{
|
||||
"name": "space_id",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "存放库位ID(取自 InboundDirectLog)"
|
||||
},
|
||||
{
|
||||
"name": "space_name",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"description": "库位名称(取自 wms_location_space.custom_name 或 space_code)"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "receivingBindings",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "入库单层级的收货单绑定关系列表(wms_entry_order_receiving)",
|
||||
"children": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "绑定记录ID"
|
||||
},
|
||||
{
|
||||
"name": "receiving_id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "收货单ID"
|
||||
},
|
||||
{
|
||||
"name": "receiving",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "收货单信息(id、receiving_number、status、storage_status、created_at)"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"errors": [
|
||||
{
|
||||
"code": 400,
|
||||
"message": "entry_order_code 必填"
|
||||
},
|
||||
{
|
||||
"code": 404,
|
||||
"message": "入库单不存在或无权访问"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"method": "storage.entry.addDirectInboundItem",
|
||||
"description": "按商品增量添加导入/PDA 入库记录(支持单条和批量)。单条模式传 stock_id/quantity/inbound_type/remark,批量模式传 items 数组。批量模式所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。若某商品累计入库量超过计划数量则拒绝(PENDING 非绑定模式)。PENDING 状态需传 receiving_detail_id 绑定收货明细;CREATED 人工导入允许超过计划数量;传入 receiving_detail_id 时 quantity 可选(自动计算可用数量),space_id 必填。",
|
||||
@ -19532,7 +19520,7 @@
|
||||
},
|
||||
{
|
||||
"method": "storage.entry.commitDirectInbound",
|
||||
"description": "提交确认完成导入/PDA 入库。先同步奇门/API 回传,成功后在 onSuccess 回调内开启事务写入库存(wms_stock_warehouse.quantity 增量、wms_stock_transaction 流水),将 pending 状态的 EntryReceivingBinding 更新为 committed,更新入库单状态为 COMPLETED,同步 sync_status=SUCCESS。不足量提交时未入库商品跳过。",
|
||||
"description": "提交确认完成导入/PDA 入库。先同步奇门/API 回传,成功后在 onSuccess 回调内开启事务写入库存(wms_stock_warehouse.quantity 增量、wms_stock_transaction 流水),将 pending 状态的 InboundDirectLog 更新为 committed,更新入库单状态为 COMPLETED,同步 sync_status=SUCCESS。不足量提交时未入库商品跳过。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
@ -20320,458 +20308,6 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"groupName": "导入/PDA直接入库",
|
||||
"module": "storage.directInbound",
|
||||
"list": [
|
||||
{
|
||||
"method": "storage.directInbound.getItems",
|
||||
"description": "[@deprecated 已弃用,请使用 storage.entry.getDirectInboundItems 替代] 获取入库单的导入/PDA 入库信息(精简版)。返回入库单基本信息、明细列表(含计划数量 planned 与已完成数量 completed)、每项明细的收货绑定列表 bindings(含 detail_id、binding_id、allocated_quantity、space_id、space_name),以及收货单绑定关系 receivingBindings。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
{
|
||||
"name": "Authorization",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "Bearer token"
|
||||
}
|
||||
],
|
||||
"params": [
|
||||
{
|
||||
"name": "entry_order_code",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"source": "body",
|
||||
"description": "入库单号"
|
||||
}
|
||||
],
|
||||
"response": [
|
||||
{
|
||||
"name": "entryOrder",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "入库单基本信息",
|
||||
"children": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "入库单ID"
|
||||
},
|
||||
{
|
||||
"name": "entry_order_code",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "入库单号"
|
||||
},
|
||||
{
|
||||
"name": "order_status",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "入库单状态(CREATED/PENDING/COMPLETED/CANCELLED)"
|
||||
},
|
||||
{
|
||||
"name": "store_remask",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "货主商家备注"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "items",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "入库明细列表",
|
||||
"children": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "入库明细ID(wms_entry_items.id)"
|
||||
},
|
||||
{
|
||||
"name": "stock_id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "商品SKU ID"
|
||||
},
|
||||
{
|
||||
"name": "planned",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "计划入库数量(对应原 count 字段)"
|
||||
},
|
||||
{
|
||||
"name": "completed",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "已完成导入/PDA 入库数量(对应原 direct_inbound_quantity 字段)"
|
||||
},
|
||||
{
|
||||
"name": "stock",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "商品详情(含 item_code、item_name、sku_property、barcodes 等缓存字段)"
|
||||
},
|
||||
{
|
||||
"name": "bindings",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "该明细的收货单绑定列表",
|
||||
"children": [
|
||||
{
|
||||
"name": "detail_id",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "收货明细ID"
|
||||
},
|
||||
{
|
||||
"name": "binding_id",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "绑定记录ID"
|
||||
},
|
||||
{
|
||||
"name": "allocated_quantity",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "预分配数量"
|
||||
},
|
||||
{
|
||||
"name": "space_id",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "存放库位ID"
|
||||
},
|
||||
{
|
||||
"name": "space_name",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"description": "库位名称"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "receivingBindings",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "入库单层级的收货单绑定关系列表",
|
||||
"children": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "绑定记录ID"
|
||||
},
|
||||
{
|
||||
"name": "receiving_id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "收货单ID"
|
||||
},
|
||||
{
|
||||
"name": "receiving",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "收货单信息(id、receiving_number、status、storage_status、created_at)"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"errors": [
|
||||
{
|
||||
"code": 400,
|
||||
"message": "entry_order_code 必填"
|
||||
},
|
||||
{
|
||||
"code": 404,
|
||||
"message": "入库单不存在或无权访问"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"method": "storage.directInbound.addItem",
|
||||
"description": "[@deprecated 已弃用,请使用 storage.entry.addDirectInboundItem 替代] 按商品增量添加导入/PDA 入库记录(支持单条和批量)。单条模式传 stock_id/quantity/inbound_type/remark,批量模式传 items 数组。批量模式所有商品共享同一个入库单状态校验,任一商品校验失败整批拒绝。若某商品累计入库量超过计划数量则拒绝。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
{
|
||||
"name": "Authorization",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "Bearer token"
|
||||
}
|
||||
],
|
||||
"params": [
|
||||
{
|
||||
"name": "entry_order_id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"source": "body",
|
||||
"description": "入库单 ID(必填,通过主键查找入库单)"
|
||||
},
|
||||
{
|
||||
"name": "stock_id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"source": "body",
|
||||
"description": "商品SKU ID(对应 wms_stock_warehouse.id)"
|
||||
},
|
||||
{
|
||||
"name": "quantity",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"source": "body",
|
||||
"description": "本次入库数量(正整数)"
|
||||
},
|
||||
{
|
||||
"name": "inbound_type",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"source": "body",
|
||||
"description": "入库方式:import(导入入库)、pda(PDA入库)"
|
||||
},
|
||||
{
|
||||
"name": "remark",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "备注(如导入文件名、PDA操作备注等)"
|
||||
},
|
||||
{
|
||||
"name": "space_id",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "存放库位ID(单条模式),关联 wms_location_space.id;为空时 commit 默认使用库位 1"
|
||||
},
|
||||
{
|
||||
"name": "items",
|
||||
"type": "array",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "批量模式:商品列表,每项包含 stock_id(商品SKU ID, number, 必填)、quantity(入库数量, number, 必填)、inbound_type(import/pda, string, 必填)、space_id(库位ID, number, 可选)、remark(备注, string, 可选)。传入 items 时忽略顶层的 stock_id/quantity/inbound_type/remark/space_id。"
|
||||
}
|
||||
],
|
||||
"response": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "单条模式返回:新增的入库记录ID"
|
||||
},
|
||||
{
|
||||
"name": "stock_id",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "单条模式返回:商品SKU ID"
|
||||
},
|
||||
{
|
||||
"name": "quantity",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "单条模式返回:本次入库数量"
|
||||
},
|
||||
{
|
||||
"name": "inbound_type",
|
||||
"type": "string",
|
||||
"required": false,
|
||||
"description": "单条模式返回:入库方式"
|
||||
},
|
||||
{
|
||||
"name": "plan_quantity",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "单条模式返回:该商品计划入库总数"
|
||||
},
|
||||
{
|
||||
"name": "existing_before",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "单条模式返回:本次入库前已入库数量"
|
||||
},
|
||||
{
|
||||
"name": "existing_after",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "单条模式返回:本次入库后总入库数量"
|
||||
},
|
||||
{
|
||||
"name": "remaining",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "单条模式返回:剩余可入库数量"
|
||||
},
|
||||
{
|
||||
"name": "count",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "批量模式返回:成功添加的条目数"
|
||||
},
|
||||
{
|
||||
"name": "total_quantity",
|
||||
"type": "number",
|
||||
"required": false,
|
||||
"description": "批量模式返回:入库总数量"
|
||||
},
|
||||
{
|
||||
"name": "items",
|
||||
"type": "array",
|
||||
"required": false,
|
||||
"description": "批量模式返回:入库结果列表,每项包含 id/stock_id/quantity/inbound_type/space_id/plan_quantity/existing_before/existing_after/remaining"
|
||||
}
|
||||
],
|
||||
"errors": [
|
||||
{
|
||||
"code": 400,
|
||||
"message": "参数校验失败:entry_order_code 必填 / stock_id 必填 / quantity 必须为正整数 / inbound_type 必须为 import 或 pda / 已作废入库单不允许操作 / 已完成的入库单不允许操作 / 入库单中不存在该 stock_id 的商品 / 入库数量超过计划"
|
||||
},
|
||||
{
|
||||
"code": 404,
|
||||
"message": "入库单不存在或无权访问"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"method": "storage.directInbound.commit",
|
||||
"description": "[@deprecated 已弃用,请使用 storage.entry.commitDirectInbound 替代] 提交确认完成导入/PDA 入库。按实收数量写入库存(wms_storage、wms_stock_transaction),未入库商品跳过不做处理,更新入库单状态为 COMPLETED,并异步触发奇门/API 入库完成回传(按实收数量回传)。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
{
|
||||
"name": "Authorization",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "Bearer token"
|
||||
}
|
||||
],
|
||||
"params": [
|
||||
{
|
||||
"name": "entry_order_id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"source": "body",
|
||||
"description": "入库单 ID"
|
||||
}
|
||||
],
|
||||
"response": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "入库单ID"
|
||||
},
|
||||
{
|
||||
"name": "entry_order_code",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "入库单号"
|
||||
},
|
||||
{
|
||||
"name": "order_status",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "入库单状态(固定为 COMPLETED)"
|
||||
},
|
||||
{
|
||||
"name": "sync_status",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "同步状态(固定为 SUCCESS)"
|
||||
},
|
||||
{
|
||||
"name": "items_count",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "入库商品种类数"
|
||||
},
|
||||
{
|
||||
"name": "total_quantity",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "入库总数量"
|
||||
}
|
||||
],
|
||||
"errors": [
|
||||
{
|
||||
"code": 400,
|
||||
"message": "entry_order_id 必填"
|
||||
},
|
||||
{
|
||||
"code": 400,
|
||||
"message": "已作废入库单不允许完成 / 入库单已完成请勿重复提交 / 暂无导入/PDA 入库记录请先添加商品 / 入库单无明细"
|
||||
},
|
||||
{
|
||||
"code": 404,
|
||||
"message": "入库单不存在或无权访问"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"method": "storage.directInbound.removeItem",
|
||||
"description": "[@deprecated 已弃用,请使用 storage.entry.removeDirectInboundItem 替代] 移除一条导入/PDA 入库记录(仅限未提交的入库单,即状态非 CANCELLED/COMPLETED)。移除后该商品的可入库余量自动恢复。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
{
|
||||
"name": "Authorization",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "Bearer token"
|
||||
}
|
||||
],
|
||||
"params": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"source": "body",
|
||||
"description": "入库记录ID(wms_inbound_direct_log.id)"
|
||||
}
|
||||
],
|
||||
"response": [
|
||||
{
|
||||
"name": "id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "已移除的入库记录ID"
|
||||
},
|
||||
{
|
||||
"name": "stock_id",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "商品SKU ID"
|
||||
},
|
||||
{
|
||||
"name": "quantity",
|
||||
"type": "number",
|
||||
"required": true,
|
||||
"description": "移除的入库数量"
|
||||
},
|
||||
{
|
||||
"name": "inbound_type",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "入库方式"
|
||||
}
|
||||
],
|
||||
"errors": [
|
||||
{
|
||||
"code": 400,
|
||||
"message": "id 必填 / 已作废入库单不允许操作 / 已完成的入库单不允许移除记录"
|
||||
},
|
||||
{
|
||||
"code": 404,
|
||||
"message": "入库记录不存在 / 关联入库单不存在或无权访问"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"groupName": "出库单模块",
|
||||
"module": "storage.stockout",
|
||||
@ -26348,93 +25884,6 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"groupName": "入库模块",
|
||||
"module": "storage",
|
||||
"list": [
|
||||
{
|
||||
"method": "storage.entry.list",
|
||||
"description": "入库单列表查询。where.order_status 支持 CREATING/CREATED/PENDING/COMPLETED/CANCELLED。CREATED=已创建待审核(需审核后才能绑定和完成入库),PENDING=已审核(可绑定和完成入库)。where 新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(通过 wms_entry_order_receiving 表查询实现)。quickWhere 支持模糊搜索:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。",
|
||||
"isNeedAuth": false,
|
||||
"isNeedLogin": true,
|
||||
"headers": [
|
||||
{
|
||||
"name": "Authorization",
|
||||
"type": "string",
|
||||
"required": true,
|
||||
"description": "Bearer token"
|
||||
}
|
||||
],
|
||||
"params": [
|
||||
{
|
||||
"name": "pagination",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "分页参数,支持 page/pageSize"
|
||||
},
|
||||
{
|
||||
"name": "where",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "统一 where 条件对象;推荐使用 { operator, value, type } 标准结构,历史简写会在 main 中自动标准化;支持 quickWhere、order_status(CREATING/CREATED/PENDING/COMPLETED/CANCELLED)、store_id、order_type、日期区间等字段。新增 expense_record(费用是否记录)筛选,支持 eq/in;值会归一化为 0/1,兼容 true/false、1/0、y/n、yes/no(大小写不敏感,含布尔/字符串/数字写法)。示例:where.expense_record={operator:eq,value:true} 等价 where.expense_record={operator:eq,value:1};where.expense_record={operator:in,value:[true,\"0\",\"yes\",\"n\"]} 会归一化为 [1,0]。若部署环境尚未完成 expense_record 字段迁移,传入该筛选可能返回 400,错误提示为\"当前环境未提供 expense_record 字段,暂不支持该筛选条件,请先完成表结构升级\"。新增 hasReceiving 虚拟筛选字段,传 true/false 筛选已绑定/未绑定收货单的入库单(虚拟字段,不直接对应数据库列,内部通过 wms_entry_order_receiving 表查询实现)。quickWhere 模糊搜索范围:entry_order_code(入库单号)、purchase_order_code(采购单号)、supplier_name(供应商名称)、store_name(货主名称)、warehouse_name(仓库名称)、receiving_id(收货单 ID / 托盘唛头,通过 wms_entry_order_receiving 绑定表关联搜索)。"
|
||||
},
|
||||
{
|
||||
"name": "sort",
|
||||
"type": "object",
|
||||
"required": false,
|
||||
"source": "body",
|
||||
"description": "排序参数,支持 sortField/sortOrder"
|
||||
}
|
||||
],
|
||||
"response": [
|
||||
{
|
||||
"name": "list",
|
||||
"type": "array",
|
||||
"required": true,
|
||||
"description": "入库单列表"
|
||||
},
|
||||
{
|
||||
"name": "pagination",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "分页信息(page、pageSize、total、totalPages、hasPrevious、hasNext)"
|
||||
},
|
||||
{
|
||||
"name": "summary",
|
||||
"type": "object",
|
||||
"required": true,
|
||||
"description": "状态汇总(total、pending、creating、created、completed、cancelled)"
|
||||
},
|
||||
{
|
||||
"name": "list[].receivingBindings",
|
||||
"type": "array",
|
||||
"required": false,
|
||||
"description": "收货单绑定列表(主表级关联),每项含 id、entry_order_id、receiving_id 及 receiving 对象(id、receiving_number、status、storage_status、created_at)"
|
||||
},
|
||||
{
|
||||
"name": "list[].hasReceiving",
|
||||
"type": "boolean",
|
||||
"required": false,
|
||||
"description": "是否存在收货单绑定"
|
||||
}
|
||||
],
|
||||
"errors": [
|
||||
{
|
||||
"code": "400",
|
||||
"message": "筛选条件格式错误",
|
||||
"description": "筛选条件格式错误"
|
||||
},
|
||||
{
|
||||
"code": "500",
|
||||
"message": "查询失败",
|
||||
"description": "查询失败"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"groupName": "快捷操作",
|
||||
"module": "quick",
|
||||
|
||||
@ -276,8 +276,8 @@ curl -s -X POST "http://localhost:6060/system?method=storage.entry.quickInbound"
|
||||
| `wms_receiving` | 收货单主表 | id, receiving_code, status, store_id |
|
||||
| `wms_receiving_detail` | 收货单明细 | id, receiving_id, product_name, actual_quantity |
|
||||
| `wms_entry_order_receiving` | 入库单↔收货单主表绑定 | id, entry_id, receiving_id |
|
||||
| `wms_entry_receiving_binding` | 入库明细↔收货明细绑定 | id, entry_item_id, receiving_detail_id, quantity |
|
||||
| `wms_inbound_direct_log` | PDA直入记录 | id, entry_id, item_code, quantity, space_id, receiving_detail_id |
|
||||
| `wms_entry_receiving_binding` | [已弃用] 入库明细↔收货明细绑定(已迁至 InboundDirectLog) | id, entry_item_id, receiving_detail_id, quantity |
|
||||
| `wms_inbound_direct_log` | PDA直入记录 + 入库明细↔收货明细绑定 | id, entry_id, entry_item_id, item_code, quantity, space_id, receiving_detail_id, status, updated_at, deleted_at |
|
||||
| `wms_api_app` | 奇门应用绑定配置 | id, app_key, app_secret, warehouse_id, store_id |
|
||||
| `wms_operation_log` | 操作日志 | id, target_type, target_id, action, operator, created_at |
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user