oms/backend/app/controller/warehouseExpressMapping.js
liufumingren 39c19a4de7 feat(backend): 出入库记录与库存锁定链路、出库单快递/收件人与推送队列
- 出入库记录(库存流水):新增 stock_records 表/模型/只读接口(列表 + 业务动作选项)与「出入库记录」菜单;
  库存变动统一收敛到 app/utils/stockRecord.js#applyStockChange,与流水写入同事务(含变动前后总/锁定/可用数量)
- 发货单:审核(1→2) 按明细锁定库存、发货确认(3→4) 扣减、推送失败退回/驳回/取消/作废释放(新增 stock_locked 列);
  恢复(9→1) 时曾推送过的单据换号(WMS 取消后原单号仍被占用,沿用旧号重推会被判「订单已存在」)
- 出库单:新增快递(express_code/express_name)、收件人(receiver_*) 与多运单号(express_codes) 字段;
  推送报文补齐 logisticsCode/receiverInfo;新增出库单推送服务与定时任务
- 快递:多运单号回填、仓库快递映射(warehouse_express_mappings) 与快递字典补录等迁移
- 契约:补充出入库记录、出库单快递/收件人等定义(swagger.json 为本地生成、不入库)
2026-09-14 00:59:23 +08:00

253 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');
/**
* 编码归一化:去空白 + 转大写(字典 code 与外部传入编码比对均按大写口径)
* @param {*} value 原值
* @return {string} 归一化后的编码
*/
function normalizeCode(value) {
return value === undefined || value === null ? '' : String(value).trim().toUpperCase();
}
/**
* @controller WarehouseExpressMappingController 仓库快递映射
* 配置「外部传入的快递编码(自定义编码)→ OMS 默认快递编码」的映射,按仓库维度维护;
* 供 WMS 出库确认 / 发货确认回传时解析快递编码使用(映射优先 → 字典兜底 → 都没有报错)。
*
* 表格展示:快递名称(express_companies 派生)、默认快递编码(express_code)、自定义编码(custom_code)。
*/
class WarehouseExpressMappingController extends Controller {
/**
* @summary 仓库快递映射列表
* @description 分页查询映射,支持按仓库、默认/自定义编码与状态过滤;附快递名称(字典派生)
* @router get /api/warehouse-express-mappings
* @apikey
* @request query integer page 页码,默认 1
* @request query integer pageSize 每页条数,默认 20
* @request query integer principal_id 所属主体ID(必填,需当前账号已绑定该主体)
* @request query integer warehouse_id 仓库ID
* @request query string express_code 默认快递编码(模糊匹配)
* @request query string custom_code 自定义编码(模糊匹配)
* @request query integer status 状态:1启用 0禁用
* @response 200 warehouseExpressMappingListResponse success
*/
async index() {
const { ctx } = this;
const Op = this.app.Sequelize.Op;
const { page, pageSize, offset, limit } = parsePagination(ctx.query);
const { warehouse_id: warehouseId, express_code: expressCode, custom_code: customCode, status } = ctx.query;
const where = { principal_id: ctx.state.principalId };
if (warehouseId) where.warehouse_id = Number(warehouseId);
if (expressCode) where.express_code = { [Op.like]: `%${normalizeCode(expressCode)}%` };
if (customCode) where.custom_code = { [Op.like]: `%${normalizeCode(customCode)}%` };
if (status !== undefined && status !== '') where.status = Number(status);
const { count, rows } = await ctx.model.WarehouseExpressMapping.findAndCountAll({
where,
offset,
limit,
order: [[ 'warehouse_id', 'ASC' ], [ 'id', 'DESC' ]],
include: [
{ model: ctx.model.Warehouse, as: 'warehouse', attributes: [ 'id', 'code', 'name' ] },
{ model: ctx.model.ExpressCompany, as: 'expressCompany', attributes: [ 'id', 'code', 'name' ] },
],
});
const list = rows.map(row => {
const plain = row.get({ plain: true });
// 快递名称:优先取字典关联结果(字典被删除时回退为空),保证表格「快递名称」列始终可用
plain.express_name = (plain.expressCompany && plain.expressCompany.name) || '';
delete plain.expressCompany;
return plain;
});
ctx.body = { code: 0, message: 'success', data: buildPageResult(list, count, { page, pageSize }) };
}
/**
* @summary 仓库快递映射详情
* @router get /api/warehouse-express-mappings/{id}
* @apikey
* @request path integer *id 映射主键ID
* @response 200 warehouseExpressMappingItem success
*/
async show() {
const { ctx } = this;
const row = await ctx.model.WarehouseExpressMapping.findOne({
where: { id: ctx.params.id, principal_id: ctx.state.principalId },
include: [
{ model: ctx.model.Warehouse, as: 'warehouse', attributes: [ 'id', 'code', 'name' ] },
{ model: ctx.model.ExpressCompany, as: 'expressCompany', attributes: [ 'id', 'code', 'name' ] },
],
});
if (!row) {
ctx.status = 404;
ctx.body = { code: 404, message: '仓库快递映射不存在' };
return;
}
const plain = row.get({ plain: true });
plain.express_name = (plain.expressCompany && plain.expressCompany.name) || '';
delete plain.expressCompany;
ctx.body = { code: 0, message: 'success', data: plain };
}
/**
* @summary 新增仓库快递映射
* @description 校验仓库属于当前主体、默认快递编码存在于快递公司字典、同仓库内自定义编码不重复
* @router post /api/warehouse-express-mappings
* @apikey
* @request body createWarehouseExpressMappingRequest *body
* @response 200 baseResponse success
*/
async create() {
const { ctx } = this;
const body = { ...ctx.request.body };
const principalId = ctx.state.principalId;
const checked = await this._validate(ctx, {
principalId,
warehouseId: body.warehouse_id,
expressCode: body.express_code,
customCode: body.custom_code,
});
if (!checked.ok) {
ctx.status = 400;
ctx.body = { code: 400, message: checked.message };
return;
}
const item = await ctx.model.WarehouseExpressMapping.create({
principal_id: principalId,
warehouse_id: checked.warehouseId,
express_code: checked.expressCode,
custom_code: checked.customCode,
status: body.status === undefined || body.status === '' ? 1 : Number(body.status) === 1 ? 1 : 0,
remark: body.remark || null,
});
ctx.body = { code: 0, message: 'success', data: { id: item.id } };
}
/**
* @summary 更新仓库快递映射
* @description 仅更新传入字段;同样校验仓库归属、字典存在性与编码唯一性(排除自身)
* @router put /api/warehouse-express-mappings/{id}
* @apikey
* @request path integer *id 映射主键ID
* @request body updateWarehouseExpressMappingRequest body
* @response 200 baseResponse success
*/
async update() {
const { ctx } = this;
const item = await ctx.model.WarehouseExpressMapping.findOne({
where: { id: ctx.params.id, principal_id: ctx.state.principalId },
});
if (!item) {
ctx.status = 404;
ctx.body = { code: 404, message: '仓库快递映射不存在' };
return;
}
const body = { ...ctx.request.body };
delete body.principal_id;
const warehouseId = body.warehouse_id === undefined ? item.warehouse_id : body.warehouse_id;
const expressCode = body.express_code === undefined ? item.express_code : body.express_code;
const customCode = body.custom_code === undefined ? item.custom_code : body.custom_code;
const checked = await this._validate(ctx, {
principalId: item.principal_id,
warehouseId,
expressCode,
customCode,
excludeId: item.id,
});
if (!checked.ok) {
ctx.status = 400;
ctx.body = { code: 400, message: checked.message };
return;
}
const patch = {
warehouse_id: checked.warehouseId,
express_code: checked.expressCode,
custom_code: checked.customCode,
};
if (body.status !== undefined && body.status !== '') patch.status = Number(body.status) === 1 ? 1 : 0;
if (body.remark !== undefined) patch.remark = body.remark || null;
await item.update(patch);
ctx.body = { code: 0, message: 'success', data: { id: item.id } };
}
/**
* @summary 删除仓库快递映射
* @router delete /api/warehouse-express-mappings/{id}
* @apikey
* @request path integer *id 映射主键ID
* @response 200 baseResponse success
*/
async destroy() {
const { ctx } = this;
const item = await ctx.model.WarehouseExpressMapping.findOne({
where: { id: ctx.params.id, principal_id: ctx.state.principalId },
});
if (!item) {
ctx.status = 404;
ctx.body = { code: 404, message: '仓库快递映射不存在' };
return;
}
await item.destroy();
ctx.body = { code: 0, message: 'success' };
}
/**
* 校验映射入参(仓库归属主体 + 默认快递编码在字典中 + 自定义编码同仓库唯一)
* @param {Object} ctx egg context
* @param {Object} params 校验参数
* @param {Number} params.principalId 主体ID
* @param {*} params.warehouseId 仓库ID
* @param {*} params.expressCode 默认快递编码
* @param {*} params.customCode 自定义编码
* @param {Number} [params.excludeId] 更新时排除的自身ID
* @return {Promise<{ok: Boolean, message?: String, warehouseId?: Number, expressCode?: String, customCode?: String}>}
*/
async _validate(ctx, { principalId, warehouseId, expressCode, customCode, excludeId }) {
const id = Number(warehouseId);
if (!id) return { ok: false, message: 'warehouse_id(仓库)为必填项' };
const warehouse = await ctx.model.Warehouse.findOne({ where: { id, principal_id: principalId }, attributes: [ 'id' ] });
if (!warehouse) return { ok: false, message: '仓库不存在或不属于当前主体' };
const code = normalizeCode(expressCode);
if (!code) return { ok: false, message: 'express_code(默认快递编码)为必填项' };
const company = await ctx.model.ExpressCompany.findOne({ where: { code }, attributes: [ 'id', 'code', 'name' ] });
if (!company) {
return { ok: false, message: `默认快递编码 ${code} 不在快递公司字典中,请先在「快递公司」中维护` };
}
const custom = normalizeCode(customCode);
if (!custom) return { ok: false, message: 'custom_code(自定义编码)为必填项' };
if (custom === code) {
return { ok: false, message: '自定义编码不能与默认快递编码相同(相同即无需映射)' };
}
const Op = this.app.Sequelize.Op;
const duplicate = await ctx.model.WarehouseExpressMapping.findOne({
where: {
warehouse_id: id,
custom_code: custom,
...(excludeId ? { id: { [Op.ne]: excludeId } } : {}),
},
attributes: [ 'id' ],
});
if (duplicate) {
return { ok: false, message: `该仓库下自定义编码 ${custom} 已存在映射(同仓库内唯一),请直接编辑原记录` };
}
return { ok: true, warehouseId: id, expressCode: code, customCode: custom };
}
}
module.exports = WarehouseExpressMappingController;