新增 stock.transaction.list API:商品出入库流水查询(仓库/货主侧自适应),含 system.json 文档注册

This commit is contained in:
liufumingren 2026-07-06 22:07:02 +08:00
parent df1bd38601
commit 9c6d984ebc
3 changed files with 988 additions and 0 deletions

View File

@ -0,0 +1,146 @@
'use strict';
const MainService = require('../../main');
/**
* 系统方法层:stock.transaction(商品出入库流水查询包装层)。
*/
class StockTransactionMethodService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'list,storeList';
const _noNeedLog = 'list,storeList';
const _noNeedAuth = 'list,storeList';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
/**
* 仓库侧商品出入库流水列表查询。
* 按当前用户仓库(ctx.user.store_id)限定数据范围。
* @param {Object} data 请求体
* @param {Object} [data.pagination] 分页参数
* @param {Object} [data.where] 查询条件
* @param {Object} [data.sort] 排序参数
* @return {Promise<Object>} 统一 success 包装
*/
async list(data = {}) {
const { service } = this;
const warehouseId = Number(this.ctx.user && this.ctx.user.store_id);
const { pagination } = data;
const { whereValue = {} } = this.prepareWhereContext(data);
const {
start_time: startTime,
end_time: endTime,
store_ids: storeIds,
stock_ids: stockIds,
transaction_type: transactionType,
order_type: orderType,
order_no: orderNo,
batch_no: batchNo,
entry_order_id: entryOrderId,
receiving_id: receivingId,
order_id: orderId,
} = whereValue;
const { sort = {} } = data;
const {
sort_field: sortFieldSnake,
sortField: sortFieldCamel,
sort_order: sortOrderSnake,
sortOrder: sortOrderCamel,
} = sort || {};
const sortOption = {
sortField: sortFieldCamel || sortFieldSnake,
sortOrder: sortOrderCamel || sortOrderSnake,
};
const result = await service.systems.stockTransaction.queryList({
warehouseId,
startTime,
endTime,
storeIds,
stockIds,
transactionType,
orderType,
orderNo,
batchNo,
entryOrderId,
receivingId,
orderId,
sort: sortOption,
pagination,
});
return this.success('ok', result);
}
/**
* 货主侧商品出入库流水列表查询。
* 按货主 store_id 限定数据范围。
* @param {Object} data 请求体
* @param {number} data.store_id 货主ID(必传)
* @param {Object} [data.pagination] 分页参数
* @param {Object} [data.where] 查询条件
* @param {Object} [data.sort] 排序参数
* @return {Promise<Object>} 统一 success 包装
*/
async storeList(data = {}) {
const { service } = this;
const storeId = Number(data.store_id);
if (!Number.isInteger(storeId) || storeId <= 0) {
return this.failure('store_id 不能为空');
}
const { pagination } = data;
const { whereValue = {} } = this.prepareWhereContext(data);
const {
start_time: startTime,
end_time: endTime,
warehouse_ids: warehouseIds,
stock_ids: stockIds,
transaction_type: transactionType,
order_type: orderType,
order_no: orderNo,
batch_no: batchNo,
entry_order_id: entryOrderId,
receiving_id: receivingId,
order_id: orderId,
} = whereValue;
const { sort = {} } = data;
const {
sort_field: sortFieldSnake,
sortField: sortFieldCamel,
sort_order: sortOrderSnake,
sortOrder: sortOrderCamel,
} = sort || {};
const sortOption = {
sortField: sortFieldCamel || sortFieldSnake,
sortOrder: sortOrderCamel || sortOrderSnake,
};
const result = await service.systems.stockTransaction.queryList({
storeId,
startTime,
endTime,
warehouseIds,
stockIds,
transactionType,
orderType,
orderNo,
batchNo,
entryOrderId,
receivingId,
orderId,
sort: sortOption,
pagination,
});
return this.success('ok', result);
}
}
module.exports = StockTransactionMethodService;

View File

@ -307,6 +307,251 @@ class StockTransactionService extends Service {
},
};
}
/**
* 查询商品出入库流水列表(原始记录,不做聚合)。
* 仓库侧:按 warehouseId 限定;货主侧:按 storeId 限定。
* @param {Object} options 查询参数
* @param {number} [options.warehouseId] 仓库ID(仓库侧必传)
* @param {number} [options.storeId] 货主ID(货主侧必传)
* @param {string|Date|null} [options.startTime] 开始时间
* @param {string|Date|null} [options.endTime] 结束时间
* @param {Array<number|string>} [options.storeIds] 货主ID数组(仓库侧筛选)
* @param {Array<number|string>} [options.warehouseIds] 仓库ID数组(货主侧筛选)
* @param {Array<number|string>} [options.stockIds] 商品库存ID数组
* @param {string} [options.transactionType] 流水类型
* @param {string} [options.orderType] 单据类型
* @param {string} [options.orderNo] 单据号
* @param {string} [options.batchNo] 批次号
* @param {number} [options.entryOrderId] 入库单ID
* @param {number} [options.receivingId] 收货单ID
* @param {number} [options.orderId] 发货单ID
* @param {Object} [options.sort] 排序参数
* @param {Object} [options.pagination] 分页参数
* @return {Promise<Object>} { list, pagination }
*/
async queryList(options = {}) {
const { ctx, app } = this;
const {
warehouseId,
storeId,
startTime,
endTime,
storeIds,
warehouseIds,
stockIds,
transactionType,
orderType,
orderNo,
batchNo,
entryOrderId,
receivingId,
orderId,
sort = {},
pagination = {},
} = options;
const whereClauses = [];
const replacements = {};
// 数据范围限定:仓库侧或货主侧
if (warehouseId !== undefined && warehouseId !== null) {
whereClauses.push('t.warehouse_id = :warehouseId');
replacements.warehouseId = Number(warehouseId);
}
if (storeId !== undefined && storeId !== null) {
whereClauses.push('t.store_id = :storeId');
replacements.storeId = Number(storeId);
}
// 时间范围
if (startTime !== undefined && startTime !== null && startTime !== '') {
const startMs = new Date(startTime).getTime();
if (!Number.isNaN(startMs)) {
whereClauses.push('t.created_at >= :startTime');
replacements.startTime = startTime;
}
}
if (endTime !== undefined && endTime !== null && endTime !== '') {
const endMs = new Date(endTime).getTime();
if (!Number.isNaN(endMs)) {
whereClauses.push('t.created_at <= :endTime');
replacements.endTime = endTime;
}
}
// 货主筛选(仓库侧)
const normalizedStoreIds = Array.isArray(storeIds)
? storeIds.map(item => Number(item)).filter(item => Number.isInteger(item) && item > 0)
: [];
if (normalizedStoreIds.length > 0) {
whereClauses.push('t.store_id IN (:storeIds)');
replacements.storeIds = normalizedStoreIds;
}
// 仓库筛选(货主侧)
const normalizedWarehouseIds = Array.isArray(warehouseIds)
? warehouseIds.map(item => Number(item)).filter(item => Number.isInteger(item) && item > 0)
: [];
if (normalizedWarehouseIds.length > 0) {
whereClauses.push('t.warehouse_id IN (:warehouseIds)');
replacements.warehouseIds = normalizedWarehouseIds;
}
// 商品筛选
const normalizedStockIds = Array.isArray(stockIds)
? stockIds.map(item => Number(item)).filter(item => Number.isInteger(item) && item > 0)
: [];
if (normalizedStockIds.length > 0) {
whereClauses.push('t.stock_id IN (:stockIds)');
replacements.stockIds = normalizedStockIds;
}
// 流水类型
if (transactionType) {
whereClauses.push('t.transaction_type = :transactionType');
replacements.transactionType = String(transactionType).trim();
}
// 单据类型
if (orderType) {
whereClauses.push('t.order_type = :orderType');
replacements.orderType = String(orderType).trim();
}
// 单据号(模糊匹配)
if (orderNo) {
whereClauses.push('t.order_no LIKE :orderNo');
replacements.orderNo = `%${String(orderNo).trim()}%`;
}
// 批次号
if (batchNo) {
whereClauses.push('t.batch_no = :batchNo');
replacements.batchNo = String(batchNo).trim();
}
// 入库单ID
if (entryOrderId !== undefined && entryOrderId !== null) {
const eid = Number(entryOrderId);
if (Number.isInteger(eid) && eid > 0) {
whereClauses.push('t.entry_order_id = :entryOrderId');
replacements.entryOrderId = eid;
}
}
// 收货单ID
if (receivingId !== undefined && receivingId !== null) {
const rid = Number(receivingId);
if (Number.isInteger(rid) && rid > 0) {
whereClauses.push('t.receiving_id = :receivingId');
replacements.receivingId = rid;
}
}
// 发货单ID
if (orderId !== undefined && orderId !== null) {
const oid = Number(orderId);
if (Number.isInteger(oid) && oid > 0) {
whereClauses.push('t.order_id = :orderId');
replacements.orderId = oid;
}
}
const whereSQL = whereClauses.length > 0
? `WHERE ${whereClauses.join(' AND ')}`
: '';
// 排序
const SORT_FIELD_WHITELIST = new Set([ 'created_at', 'quantity', 'stock_id', 'store_id', 'warehouse_id' ]);
const sortFieldRaw = String(sort.sortField || 'created_at').trim();
const sortField = SORT_FIELD_WHITELIST.has(sortFieldRaw) ? sortFieldRaw : 'created_at';
const sortOrderRaw = String(sort.sortOrder || 'DESC').trim().toUpperCase();
const sortOrder = sortOrderRaw === 'ASC' ? 'ASC' : 'DESC';
// 分页
const page = Math.max(1, Number(pagination.page) || 1);
const pageSize = Math.min(200, Math.max(1, Number(pagination.pageSize) || 20));
const offset = (page - 1) * pageSize;
// 查询总数
const countResult = await ctx.model.query(
`SELECT COUNT(*) AS total FROM wms_stock_transaction t ${whereSQL}`,
{
replacements,
type: app.Sequelize.QueryTypes.SELECT,
}
);
const total = countResult && countResult[0] ? Number(countResult[0].total) : 0;
// 查询列表
const rows = await ctx.model.query(
`SELECT
t.id,
t.created_at,
t.transaction_type,
t.warehouse_id,
t.store_id,
t.stock_id,
t.quantity,
t.before_quantity,
t.after_quantity,
t.before_locked_quantity,
t.after_locked_quantity,
t.batch_no,
t.order_type,
t.order_no,
t.order_id,
t.receiving_id,
t.entry_order_id,
t.operator_name,
t.remark
FROM wms_stock_transaction t
${whereSQL}
ORDER BY t.${sortField} ${sortOrder}, t.id ${sortOrder}
LIMIT :limit OFFSET :offset
`,
{
replacements: { ...replacements, limit: pageSize, offset },
type: app.Sequelize.QueryTypes.SELECT,
}
);
const safeRows = Array.isArray(rows) ? rows : [];
const list = safeRows.map(item => ({
id: Number(item.id),
created_at: item.created_at ? app.formatDate(item.created_at) : '',
transaction_type: item.transaction_type || '',
warehouse_id: Number(item.warehouse_id) || 0,
store_id: Number(item.store_id) || 0,
stock_id: Number(item.stock_id) || 0,
quantity: Number(item.quantity) || 0,
before_quantity: Number(item.before_quantity) || 0,
after_quantity: Number(item.after_quantity) || 0,
before_locked_quantity: Number(item.before_locked_quantity) || 0,
after_locked_quantity: Number(item.after_locked_quantity) || 0,
batch_no: item.batch_no || '',
order_type: item.order_type || '',
order_no: item.order_no || '',
order_id: Number(item.order_id) || 0,
receiving_id: Number(item.receiving_id) || 0,
entry_order_id: Number(item.entry_order_id) || 0,
operator_name: item.operator_name || '',
remark: item.remark || '',
}));
return {
list,
pagination: {
page,
pageSize,
total,
totalPages: Math.ceil(total / pageSize),
},
};
}
}
module.exports = StockTransactionService;

View File

@ -16441,6 +16441,520 @@
}
],
"errors": []
},
{
"method": "stock.transaction.list",
"description": "商品出入库流水列表查询(wms_stock_transaction),支持 where 条件筛选与分页",
"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 条件对象,支持以下字段:",
"children": [
{
"name": "start_time",
"type": "string",
"required": false,
"description": "开始时间(闭区间下限),created_at >= start_time"
},
{
"name": "end_time",
"type": "string",
"required": false,
"description": "结束时间(闭区间上限),created_at <= end_time"
},
{
"name": "store_ids",
"type": "array",
"required": false,
"description": "货主ID数组,为空或未传表示不筛选"
},
{
"name": "stock_ids",
"type": "array",
"required": false,
"description": "商品库存ID数组,为空或未传表示不筛选"
},
{
"name": "transaction_type",
"type": "string",
"required": false,
"description": "流水类型:INBOUND=入库 / OUTBOUND=出库 / TRANSFER_OUT=移库出 / TRANSFER_IN=移库入 / LOCK=锁定"
},
{
"name": "order_type",
"type": "string",
"required": false,
"description": "单据类型筛选"
},
{
"name": "order_no",
"type": "string",
"required": false,
"description": "单据号筛选(支持模糊匹配)"
},
{
"name": "batch_no",
"type": "string",
"required": false,
"description": "批次号筛选"
},
{
"name": "entry_order_id",
"type": "number",
"required": false,
"description": "入库单ID筛选"
},
{
"name": "receiving_id",
"type": "number",
"required": false,
"description": "收货单ID筛选"
},
{
"name": "order_id",
"type": "number",
"required": false,
"description": "发货单ID筛选"
}
]
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数对象,支持 sortField / sortOrder 与 sort_field / sort_order 下划线别名兼容",
"children": [
{
"name": "sortField",
"type": "string",
"required": false,
"description": "排序字段,白名单:created_at、quantity、stock_id、store_id。非法字段回退默认排序(created_at DESC)"
},
{
"name": "sort_field",
"type": "string",
"required": false,
"description": "排序字段下划线别名(兼容 sort.sort_field),规则同 sortField"
},
{
"name": "sortOrder",
"type": "string",
"required": false,
"description": "排序方向,ASC / DESC(大小写不敏感),非法值回退 DESC"
},
{
"name": "sort_order",
"type": "string",
"required": false,
"description": "排序方向下划线别名(兼容 sort.sort_order),规则同 sortOrder"
}
]
}
],
"response": [
{
"name": "list",
"type": "array",
"description": "流水记录列表",
"children": [
{
"name": "id",
"type": "number",
"description": "流水记录ID"
},
{
"name": "created_at",
"type": "string",
"description": "流水创建时间"
},
{
"name": "transaction_type",
"type": "string",
"description": "流水类型:INBOUND / OUTBOUND / TRANSFER_OUT / TRANSFER_IN / LOCK"
},
{
"name": "store_id",
"type": "number",
"description": "货主ID"
},
{
"name": "stock_id",
"type": "number",
"description": "商品库存ID"
},
{
"name": "quantity",
"type": "number",
"description": "变动数量"
},
{
"name": "before_quantity",
"type": "number",
"description": "变更前库存"
},
{
"name": "after_quantity",
"type": "number",
"description": "变更后库存"
},
{
"name": "before_locked_quantity",
"type": "number",
"description": "变更前锁定库存"
},
{
"name": "after_locked_quantity",
"type": "number",
"description": "变更后锁定库存"
},
{
"name": "batch_no",
"type": "string",
"description": "批次号"
},
{
"name": "order_type",
"type": "string",
"description": "单据类型"
},
{
"name": "order_no",
"type": "string",
"description": "单据号"
},
{
"name": "order_id",
"type": "number",
"description": "发货单ID"
},
{
"name": "receiving_id",
"type": "number",
"description": "收货单ID"
},
{
"name": "entry_order_id",
"type": "number",
"description": "入库单ID"
},
{
"name": "operator_name",
"type": "string",
"description": "操作人名称"
},
{
"name": "remark",
"type": "string",
"description": "备注"
}
]
},
{
"name": "pagination",
"type": "object",
"description": "分页信息,包含 page、pageSize、total"
}
],
"errors": [
{
"code": 400,
"message": "start_time 不合法"
},
{
"code": 400,
"message": "end_time 不合法"
},
{
"code": 400,
"message": "start_time 不能大于 end_time"
}
]
},
{
"method": "stock.transaction.storeList",
"description": "货主侧商品出入库流水列表查询(wms_stock_transaction),按货主 store_id 限定数据范围,支持 where 条件筛选与分页",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "store_id",
"type": "number",
"required": true,
"source": "body",
"description": "货主ID,必传;用于限定查询的货主范围"
},
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数,包含 page / pageSize"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "统一 where 条件对象,支持以下字段:",
"children": [
{
"name": "start_time",
"type": "string",
"required": false,
"description": "开始时间(闭区间下限),created_at >= start_time"
},
{
"name": "end_time",
"type": "string",
"required": false,
"description": "结束时间(闭区间上限),created_at <= end_time"
},
{
"name": "warehouse_ids",
"type": "array",
"required": false,
"description": "仓库ID数组,为空或未传表示不按仓库筛选(但仅返回当前货主有权限的仓库数据)"
},
{
"name": "stock_ids",
"type": "array",
"required": false,
"description": "商品库存ID数组,为空或未传表示不筛选"
},
{
"name": "transaction_type",
"type": "string",
"required": false,
"description": "流水类型:INBOUND=入库 / OUTBOUND=出库 / TRANSFER_OUT=移库出 / TRANSFER_IN=移库入 / LOCK=锁定"
},
{
"name": "order_type",
"type": "string",
"required": false,
"description": "单据类型筛选"
},
{
"name": "order_no",
"type": "string",
"required": false,
"description": "单据号筛选(支持模糊匹配)"
},
{
"name": "batch_no",
"type": "string",
"required": false,
"description": "批次号筛选"
},
{
"name": "entry_order_id",
"type": "number",
"required": false,
"description": "入库单ID筛选"
},
{
"name": "receiving_id",
"type": "number",
"required": false,
"description": "收货单ID筛选"
},
{
"name": "order_id",
"type": "number",
"required": false,
"description": "发货单ID筛选"
}
]
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序参数对象,支持 sortField / sortOrder 与 sort_field / sort_order 下划线别名兼容",
"children": [
{
"name": "sortField",
"type": "string",
"required": false,
"description": "排序字段,白名单:created_at、quantity、stock_id、warehouse_id。非法字段回退默认排序(created_at DESC)"
},
{
"name": "sort_field",
"type": "string",
"required": false,
"description": "排序字段下划线别名(兼容 sort.sort_field),规则同 sortField"
},
{
"name": "sortOrder",
"type": "string",
"required": false,
"description": "排序方向,ASC / DESC(大小写不敏感),非法值回退 DESC"
},
{
"name": "sort_order",
"type": "string",
"required": false,
"description": "排序方向下划线别名(兼容 sort.sort_order),规则同 sortOrder"
}
]
}
],
"response": [
{
"name": "list",
"type": "array",
"description": "流水记录列表",
"children": [
{
"name": "id",
"type": "number",
"description": "流水记录ID"
},
{
"name": "created_at",
"type": "string",
"description": "流水创建时间"
},
{
"name": "transaction_type",
"type": "string",
"description": "流水类型:INBOUND / OUTBOUND / TRANSFER_OUT / TRANSFER_IN / LOCK"
},
{
"name": "warehouse_id",
"type": "number",
"description": "仓库ID"
},
{
"name": "store_id",
"type": "number",
"description": "货主ID"
},
{
"name": "stock_id",
"type": "number",
"description": "商品库存ID"
},
{
"name": "quantity",
"type": "number",
"description": "变动数量"
},
{
"name": "before_quantity",
"type": "number",
"description": "变更前库存"
},
{
"name": "after_quantity",
"type": "number",
"description": "变更后库存"
},
{
"name": "before_locked_quantity",
"type": "number",
"description": "变更前锁定库存"
},
{
"name": "after_locked_quantity",
"type": "number",
"description": "变更后锁定库存"
},
{
"name": "batch_no",
"type": "string",
"description": "批次号"
},
{
"name": "order_type",
"type": "string",
"description": "单据类型"
},
{
"name": "order_no",
"type": "string",
"description": "单据号"
},
{
"name": "order_id",
"type": "number",
"description": "发货单ID"
},
{
"name": "receiving_id",
"type": "number",
"description": "收货单ID"
},
{
"name": "entry_order_id",
"type": "number",
"description": "入库单ID"
},
{
"name": "operator_name",
"type": "string",
"description": "操作人名称"
},
{
"name": "remark",
"type": "string",
"description": "备注"
}
]
},
{
"name": "pagination",
"type": "object",
"description": "分页信息,包含 page、pageSize、total"
}
],
"errors": [
{
"code": 400,
"message": "store_id 不能为空"
},
{
"code": 400,
"message": "start_time 不合法"
},
{
"code": 400,
"message": "end_time 不合法"
},
{
"code": 400,
"message": "start_time 不能大于 end_time"
}
]
}
]
},
@ -23081,6 +23595,89 @@
}
]
},
{
"groupName": "仓库-货主签约模块",
"module": "storeWarehouse.warehouse",
"list": [
{
"method": "storeWarehouse.warehouse.list",
"description": "仓库侧查询当前仓库可见的货主签约列表",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [
{
"name": "Authorization",
"type": "string",
"required": true,
"description": "Bearer token"
}
],
"params": [
{
"name": "page",
"type": "number",
"required": false,
"source": "body",
"description": "页码,默认 1"
},
{
"name": "page_size",
"type": "number",
"required": false,
"source": "body",
"description": "每页条数,默认 20,最大 200"
},
{
"name": "keyword",
"type": "string",
"required": false,
"source": "body",
"description": "搜索关键字,模糊匹配货主备注名、仓库备注名、货主公司名、仓库公司名"
},
{
"name": "auth_status",
"type": "string",
"required": false,
"source": "body",
"description": "授权状态筛选"
}
],
"response": [
{
"name": "list",
"type": "array",
"description": "签约列表"
},
{
"name": "total",
"type": "number",
"description": "总条数"
},
{
"name": "page",
"type": "number",
"description": "当前页码"
},
{
"name": "page_size",
"type": "number",
"description": "每页条数"
},
{
"name": "current_subject",
"type": "object",
"description": "当前主体信息,含 store_id、company_name、role(warehouse/store)"
}
],
"errors": [
{
"code": 500,
"message": "获取签约列表失败"
}
]
}
]
},
{
"groupName": "用户模块",
"module": "user",