liufumingren ec81f8b3cd feat(backend): 入库单/出库单全流程与 WMS 对接
- 入库单、出库单控制器与模型(状态流转、审核、驳回换号、作废、删除约束)
- 明细共用 stock_items:应/已数量、行级库存类型 ZP/CC、明细锁定
- lib/wms:单据类型常量(orderTypes)、奇门/openapi 客户端(qimenClient)、签名(sign)
- 库存联动:utils/stock.js、utils/completeInbound.js(入库完成加库存,幂等)
- 驳回换号:utils/rejectBillNo.js;旧 orders 模块同步调整
- 相关迁移:入库单 WMS 字段/审核/推送结果、明细计划与实际数量、单据类型落 WMS 编码、出库库存扣减标记等
2026-09-13 02:23:44 +08:00

316 lines
10 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

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

'use strict';
const { Controller } = require('egg');
const { parsePagination, buildPageResult } = require('../lib/pagination');
/**
* 状态与生命周期字段由业务事务(状态流转 updateStatus / 外部 WMS 回调 updateWmsStatus)推动,
* 禁止通过新增、更新等通用接口直接写入,避免绕过流程。
*/
const MANAGED_FIELDS = [
'status', 'submit_status', 'submit_at', 'submit_order_no', 'submit_msg',
'wms_status', 'wms_order_no', 'wms_synced_at',
];
/**
* @controller OrderController 订单管理
*/
class OrderController extends Controller {
/**
* @summary 订单列表
* @description 分页查询订单,支持按主体、订单号、主状态、WMS 状态、上交状态过滤
* @router get /api/orders
* @apikey
* @request query integer page 页码,默认 1
* @request query integer pageSize 每页条数,默认 20
* @request query integer principal_id 所属主体ID(必填,需当前账号已绑定该主体)
* @request query string order_no 业务订单号,支持模糊匹配
* @request query integer status 主状态:1待处理 2处理中 3已完成 4已取消
* @request query string wms_status 外部WMS状态,如 CREATED/PICKING/SHIPPED
* @request query integer submit_status 上交状态:0未上交 1上交中 2已上交 3上交失败
* @request query integer shop_id 店铺ID,按店铺过滤,不传则不过滤
* @response 200 orderListResponse success
*/
async index() {
const { ctx } = this;
const Op = this.app.Sequelize.Op;
const { page, pageSize, offset, limit } = parsePagination(ctx.query);
const {
order_no: orderNo,
status,
wms_status: wmsStatus,
submit_status: submitStatus,
shop_id: shopId,
} = ctx.query;
const principalId = ctx.state.principalId;
const where = {};
where.principal_id = principalId;
if (orderNo) where.order_no = { [Op.like]: `%${orderNo}%` };
if (status !== undefined && status !== '') where.status = Number(status);
if (wmsStatus) where.wms_status = wmsStatus;
if (submitStatus !== undefined && submitStatus !== '') where.submit_status = Number(submitStatus);
if (shopId) where.shop_id = Number(shopId);
const { count, rows } = await ctx.model.Order.findAndCountAll({
where,
offset,
limit,
order: [[ 'id', 'DESC' ]],
include: [
{ model: ctx.model.Shop, as: 'shop', attributes: [ 'id', 'name' ] },
],
});
ctx.body = { code: 0, message: 'success', data: buildPageResult(rows, count, { page, pageSize }) };
}
/**
* @summary 订单详情
* @description 按主键查询订单,含主状态、WMS 状态、上交状态、所属店铺与订单明细
* @router get /api/orders/{id}
* @apikey
* @request path integer *id 订单主键ID
* @response 200 baseResponse success
*/
async show() {
const { ctx } = this;
const order = await ctx.model.Order.findByPk(ctx.params.id, {
include: [
{ model: ctx.model.Shop, as: 'shop', attributes: [ 'id', 'name', 'platform' ] },
{
model: ctx.model.OrderItem,
as: 'items',
include: [
{ model: ctx.model.Product, as: 'product', attributes: [ 'id', 'item_code', 'item_name', 'sku_property' ] },
{ model: ctx.model.ComboProduct, as: 'comboProduct', attributes: [ 'id', 'code', 'name' ] },
],
},
],
});
if (!order) {
ctx.status = 404;
ctx.body = { code: 404, message: '订单不存在' };
return;
}
ctx.body = { code: 0, message: 'success', data: order };
}
/**
* @summary 新增订单
* @description 订单号 order_no 全局唯一;初始主状态默认 1(待处理);
* 可同时传入 items 数组一次性写入订单明细(明细随订单在同一事务内创建)
* @router post /api/orders
* @apikey
* @request body createOrderRequest *body
* @response 200 baseResponse success
*/
async create() {
const { ctx } = this;
const { order_no: orderNo, principal_id: principalId, items } = ctx.request.body;
if (!orderNo || !principalId) {
ctx.status = 400;
ctx.body = { code: 400, message: 'order_no 与 principal_id 为必填项' };
return;
}
const exist = await ctx.model.Order.findOne({ where: { order_no: orderNo } });
if (exist) {
ctx.status = 400;
ctx.body = { code: 400, message: '订单号已存在' };
return;
}
const payload = { ...ctx.request.body };
delete payload.items;
for (const f of MANAGED_FIELDS) delete payload[f];
const transaction = await ctx.model.transaction();
try {
const order = await ctx.model.Order.create({
status: 1,
submit_status: 0,
...payload,
}, { transaction });
if (Array.isArray(items) && items.length) {
await ctx.model.OrderItem.bulkCreate(items.map(item => ({
...item,
principal_id: principalId,
order_id: order.id,
shop_id: item.shop_id || order.shop_id || null,
parse_status: item.product_id || item.combo_product_id ? 1 : 0,
item_type: item.product_id ? 1 : (item.combo_product_id ? 2 : 0),
})), { transaction });
}
await transaction.commit();
ctx.body = { code: 0, message: 'success', data: { id: order.id } };
} catch (err) {
await transaction.rollback();
ctx.status = 500;
ctx.body = { code: 500, message: '新增订单失败,请稍后重试' };
}
}
/**
* @summary 解析订单明细
* @description 批量解析该订单下未解析/解析失败的明细,按商家编码或店铺商品绑定关系匹配系统商品与组合商品
* @router post /api/orders/{id}/parse-items
* @apikey
* @request path integer *id 订单主键ID
* @response 200 parseOrderItemsResponse success
*/
async parseItems() {
const { ctx } = this;
const order = await ctx.model.Order.findByPk(ctx.params.id);
if (!order) {
ctx.status = 404;
ctx.body = { code: 404, message: '订单不存在' };
return;
}
const items = await ctx.model.OrderItem.findAll({ where: { order_id: order.id } });
let resolved = 0;
let failed = 0;
for (const item of items) {
if (Number(item.parse_status) === 1) continue;
const data = await ctx.controller.orderItem.resolveItem(item, order.principal_id);
await item.update(data);
if (data.parse_status === 1) resolved++;
else failed++;
}
ctx.body = {
code: 0,
message: 'success',
data: { total: items.length, resolved, failed },
};
}
/**
* @summary 更新订单
* @description 未传入的字段保持原值;状态流转建议使用专用状态接口
* @router put /api/orders/{id}
* @apikey
* @request path integer *id 订单主键ID
* @request body updateOrderRequest *body
* @response 200 baseResponse success
*/
async update() {
const { ctx } = this;
const order = await ctx.model.Order.findByPk(ctx.params.id);
if (!order) {
ctx.status = 404;
ctx.body = { code: 404, message: '订单不存在' };
return;
}
delete ctx.request.body.principal_id;
for (const f of MANAGED_FIELDS) delete ctx.request.body[f];
await order.update(ctx.request.body);
ctx.body = { code: 0, message: 'success', data: { id: order.id } };
}
/**
* @summary 订单状态流转(主状态/上交状态)
* @description 更新主状态与上交(上报)状态;上交成功时自动写入 submit_at
* @router put /api/orders/{id}/status
* @apikey
* @request path integer *id 订单主键ID
* @request body updateOrderStatusRequest *body
* @response 200 baseResponse success
*/
async updateStatus() {
const { ctx } = this;
const { status, submit_status: submitStatus, submit_order_no: submitOrderNo, submit_msg: submitMsg } = ctx.request.body;
const order = await ctx.model.Order.findByPk(ctx.params.id);
if (!order) {
ctx.status = 404;
ctx.body = { code: 404, message: '订单不存在' };
return;
}
const data = {};
if (status !== undefined && status !== '') data.status = Number(status);
if (submitStatus !== undefined && submitStatus !== '') {
data.submit_status = Number(submitStatus);
data.submit_at = new Date();
}
if (submitOrderNo !== undefined) data.submit_order_no = submitOrderNo;
if (submitMsg !== undefined) data.submit_msg = submitMsg;
await order.update(data);
ctx.body = { code: 0, message: 'success', data: { id: order.id } };
}
/**
* @summary 外部WMS状态回写
* @description 由 WMS 回调调用,更新外部WMS状态、WMS单号与同步时间
* @router put /api/orders/{id}/wms-status
* @apikey
* @request path integer *id 订单主键ID
* @request body wmsStatusRequest *body
* @response 200 baseResponse success
*/
async updateWmsStatus() {
const { ctx } = this;
const { wms_status: wmsStatus, wms_order_no: wmsOrderNo, status, message } = ctx.request.body;
if (!wmsStatus) {
ctx.status = 400;
ctx.body = { code: 400, message: 'wms_status 为必填项' };
return;
}
const order = await ctx.model.Order.findByPk(ctx.params.id);
if (!order) {
ctx.status = 404;
ctx.body = { code: 404, message: '订单不存在' };
return;
}
const data = {
wms_status: wmsStatus,
wms_synced_at: new Date(),
};
if (wmsOrderNo !== undefined) data.wms_order_no = wmsOrderNo;
if (status !== undefined && status !== '') data.status = Number(status);
if (message !== undefined) data.submit_msg = message;
await order.update(data);
ctx.body = { code: 0, message: 'success', data: { id: order.id } };
}
/**
* @summary 删除订单
* @description 物理删除订单
* @router delete /api/orders/{id}
* @apikey
* @request path integer *id 订单主键ID
* @response 200 baseResponse success
*/
async destroy() {
const { ctx } = this;
const order = await ctx.model.Order.findByPk(ctx.params.id);
if (!order) {
ctx.status = 404;
ctx.body = { code: 404, message: '订单不存在' };
return;
}
await order.destroy();
ctx.body = { code: 0, message: 'success', data: { id: Number(ctx.params.id) } };
}
}
module.exports = OrderController;