oms/backend/app/lib/orderStatus.js
liufumingren 6c03a20364 feat(backend): 订单状态分表、WMS 推送与归档
- 新增 order_index 索引表 + 6 张同构状态表(待审核/异常/委外中/配送/已作废/已取消)与历史表,
  订单 ID 全局唯一,状态由业务事务推动:审核、驳回、取消、作废、恢复、归档
- 明细表 order_status_items、收件人文本智能解析、批量切换仓库/店铺并刷新快照
- WMS deliveryorder.create 推送(单条/批量)、推送失败定时重试、订单归档定时任务
- 迁移:建表、旧发货单数据迁入新表、菜单合并与迁移记录清理
- routes / swagger contract 补充订单状态接口

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-30 23:06:18 +08:00

190 lines
5.9 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 { copyColumnNames } = require('./orderFields');
/**
* 订单状态与「所在表」口径的唯一来源。
*
* 订单按状态分表存储,订单 ID 全局唯一(取自 order_index):
* - order_index 订单索引表:current_table / current_status 记录订单当前所在表与状态
* - order_status_pending 待审核
* - order_status_queued 待推送(审核通过、已锁定库存,等待推送仓库)
* - order_status_exception 异常
* - order_status_outsourcing 委外中(推送仓库成功,等仓库回传发货确认)
* - order_status_delivery 配送
* - order_status_void 已作废(侧路:审核后不再走履约)
* - order_status_canceled 已取消(侧路:可恢复回待审核)
* - order_status_history 历史(多 archived_at 归档时间 / transferred_at 转入时间)
* - order_status_items 明细表(各状态表共用,字段为发货单明细 ∪ 原订单明细的超集)
*
* 生命周期:待审核 →(审核+锁库存)待推送 →(推送仓库成功)委外中 →(仓库回传确认)配送
* →(创建时间超 3 个月)历史;
* 侧路状态:异常(推送仓库失败进入,可回流转正)、已作废、已取消(可恢复)。
*/
/** 状态枚举(同时也是 current_table / current_status 的取值与页面 tab 的 key) */
const ORDER_STATUS = {
PENDING: 'pending',
QUEUED: 'queued',
EXCEPTION: 'exception',
OUTSOURCING: 'outsourcing',
DELIVERY: 'delivery',
VOID: 'void',
CANCELED: 'canceled',
HISTORY: 'history',
};
/** 状态 → 中文标签 */
const ORDER_STATUS_LABELS = {
[ORDER_STATUS.PENDING]: '待审核',
[ORDER_STATUS.QUEUED]: '待推送',
[ORDER_STATUS.EXCEPTION]: '异常',
[ORDER_STATUS.OUTSOURCING]: '委外中',
[ORDER_STATUS.DELIVERY]: '配送',
[ORDER_STATUS.VOID]: '已作废',
[ORDER_STATUS.CANCELED]: '已取消',
[ORDER_STATUS.HISTORY]: '历史',
};
/** 页面左侧 tab 顺序(也是状态展示顺序;历史(归档)放最后) */
const ORDER_STATUS_ORDER = [
ORDER_STATUS.PENDING,
ORDER_STATUS.QUEUED,
ORDER_STATUS.EXCEPTION,
ORDER_STATUS.OUTSOURCING,
ORDER_STATUS.DELIVERY,
ORDER_STATUS.VOID,
ORDER_STATUS.CANCELED,
ORDER_STATUS.HISTORY,
];
/** 活动状态(非历史,各自一张状态表) */
const ORDER_ACTIVE_STATUSES = [
ORDER_STATUS.PENDING,
ORDER_STATUS.QUEUED,
ORDER_STATUS.EXCEPTION,
ORDER_STATUS.OUTSOURCING,
ORDER_STATUS.DELIVERY,
ORDER_STATUS.VOID,
ORDER_STATUS.CANCELED,
];
/** 状态表统一前缀:表名 = `${ORDER_TABLE_PREFIX}${status}` */
const ORDER_TABLE_PREFIX = 'order_status_';
/** 订单索引表表名 */
const ORDER_INDEX_TABLE = 'order_index';
/** 订单明细表表名(各状态表共用) */
const ORDER_ITEM_TABLE = 'order_status_items';
/** 订单明细表模型名 */
const ORDER_ITEM_MODEL = 'OrderStatusItem';
/** 状态 → 所在表名 */
const ORDER_TABLE_BY_STATUS = ORDER_STATUS_ORDER.reduce((acc, status) => {
acc[status] = `${ORDER_TABLE_PREFIX}${status}`;
return acc;
}, {});
/** 状态 → 模型名(ctx.model.xxx,对应 app/model 下的文件名) */
const ORDER_MODEL_BY_STATUS = {
[ORDER_STATUS.PENDING]: 'OrderStatusPending',
[ORDER_STATUS.QUEUED]: 'OrderStatusQueued',
[ORDER_STATUS.EXCEPTION]: 'OrderStatusException',
[ORDER_STATUS.OUTSOURCING]: 'OrderStatusOutsourcing',
[ORDER_STATUS.DELIVERY]: 'OrderStatusDelivery',
[ORDER_STATUS.VOID]: 'OrderStatusVoid',
[ORDER_STATUS.CANCELED]: 'OrderStatusCanceled',
[ORDER_STATUS.HISTORY]: 'OrderStatusHistory',
};
/**
* 流转时需要整体搬运的业务列名(由字段定义派生,新增字段自动纳入,避免漏搬)
* @param {Object} Sequelize sequelize 构造函数
* @return {Array<String>} 列名数组
*/
function orderCopyFields(Sequelize) {
return copyColumnNames(Sequelize);
}
/** 超期归档阈值(月):创建时间超过该月数的订单由定时任务归档到历史表 */
const ORDER_ARCHIVE_MONTHS = 3;
/** 枚举列表(下拉/提示用,按 tab 顺序) */
const ORDER_STATUS_LIST = ORDER_STATUS_ORDER.map(value => ({
value,
label: ORDER_STATUS_LABELS[value],
}));
/**
* 是否为合法状态值
* @param {*} value 原值
* @return {Boolean} 合法返回 true
*/
function isValidOrderStatus(value) {
return Object.prototype.hasOwnProperty.call(ORDER_STATUS_LABELS, String(value));
}
/**
* 归一化状态值
* @param {*} value 原值
* @param {String} [fallback] 非法值兜底(默认返回 null)
* @return {String|null} 合法状态值
*/
function normalizeOrderStatus(value, fallback) {
const status = String(value == null ? '' : value).trim().toLowerCase();
return isValidOrderStatus(status) ? status : (fallback || null);
}
/**
* 状态对应的中文标签
* @param {*} value 状态值
* @return {String} 中文标签(未知状态原样返回)
*/
function orderStatusLabel(value) {
const status = normalizeOrderStatus(value);
return status ? ORDER_STATUS_LABELS[status] : String(value == null ? '' : value);
}
/**
* 状态对应的表名
* @param {*} value 状态值
* @return {String|null} 表名
*/
function orderTableOf(value) {
const status = normalizeOrderStatus(value);
return status ? ORDER_TABLE_BY_STATUS[status] : null;
}
/**
* 状态对应的模型名
* @param {*} value 状态值
* @return {String|null} 模型名
*/
function orderModelName(value) {
const status = normalizeOrderStatus(value);
return status ? ORDER_MODEL_BY_STATUS[status] : null;
}
module.exports = {
ORDER_STATUS,
ORDER_STATUS_LABELS,
ORDER_STATUS_ORDER,
ORDER_ACTIVE_STATUSES,
ORDER_TABLE_PREFIX,
ORDER_INDEX_TABLE,
ORDER_ITEM_TABLE,
ORDER_ITEM_MODEL,
ORDER_TABLE_BY_STATUS,
ORDER_MODEL_BY_STATUS,
ORDER_STATUS_LIST,
ORDER_ARCHIVE_MONTHS,
orderCopyFields,
isValidOrderStatus,
normalizeOrderStatus,
orderStatusLabel,
orderTableOf,
orderModelName,
};