// 代码说明
// 本段代码用于根据订单事件（orderEvent）进行状态分支处理，涵盖 created、paid、shipped、delivered、cancelled、refunded 六种业务事件。
// 采用严格模式与标准的 switch-case 结构，确保无 case 穿透、逻辑清晰、可维护。
// 特点：
// - 事件名大小写与空白容错（统一小写匹配）
// - 幂等处理（重复事件不重复更新状态）
// - 完整的默认处理（记录异常事件、保持原状态、通知运营介入）
// - 可插拔的服务依赖（状态更新、时间线记录、消息通知、日志、运营告警）
'use strict';
/**
* 处理订单事件的统一入口
* @param {string} orderEvent - 订单事件：created|paid|shipped|delivered|cancelled|refunded
* @param {Object} ctx - 上下文
* @param {string|number} ctx.orderId - 订单ID
* @param {string} ctx.currentStatus - 当前订单状态
* @param {Object} ctx.services - 外部服务集合
* @param {Function} ctx.services.updateStatus - (orderId, nextStatus) => Promise<void>
* @param {Function} ctx.services.addTimeline - (orderId, message) => Promise<void>
* @param {Function} ctx.services.notifyUser - (orderId, type, payload) => Promise<void>
* @param {Function} ctx.services.notifyOps - (payload) => Promise<void>
* @param {Object} ctx.services.logger - { info:Function, warn:Function, error:Function }
* @returns {Promise<{handled:boolean, orderId:string|number, prevStatus:string, nextStatus:string, event:string}>}
*/
async function handleOrderEvent(orderEvent, ctx) {
// 基本校验
if (!ctx || typeof ctx !== 'object') {
throw new TypeError('ctx is required and must be an object');
}
const { orderId, currentStatus, services } = ctx;
if (!orderId) throw new TypeError('ctx.orderId is required');
if (!services || typeof services !== 'object') {
throw new TypeError('ctx.services is required');
}
// 要求的服务依赖检查
const requiredFns = ['updateStatus', 'addTimeline', 'notifyUser', 'notifyOps'];
requiredFns.forEach(fnName => {
if (typeof services[fnName] !== 'function') {
throw new TypeError(`services.${fnName} must be a function`);
}
});
const logger = services.logger && typeof services.logger === 'object'
? services.logger
: { info: () => {}, warn: () => {}, error: () => {} };
// 归一化事件名
const event = typeof orderEvent === 'string' ? orderEvent.trim().toLowerCase() : '';
if (!event) {
logger.warn(`[Order:${orderId}] Empty or invalid orderEvent: ${String(orderEvent)}`);
}
// 使用局部可变状态，便于在一次处理内多处读取
let status = typeof currentStatus === 'string' ? currentStatus : '';
// 幂等安全的状态流转+通知封装
async function transition(nextStatus, timelineMsg, userNotify) {
if (status !== nextStatus) {
await services.updateStatus(orderId, nextStatus);
status = nextStatus;
logger.info(`[Order:${orderId}] 状态更新: ${String(currentStatus)} -> ${nextStatus}`);
} else {
logger.info(`[Order:${orderId}] 状态已为 ${nextStatus}，忽略重复事件`);
}
if (timelineMsg) {
await services.addTimeline(orderId, timelineMsg);
}
if (userNotify && userNotify.type) {
await services.notifyUser(orderId, userNotify.type, userNotify.payload || { status: nextStatus });
}
}
try {
switch (event) {
case 'created':
// 订单创建：补充时间线并给用户发送确认
await transition(
'created',
'订单已创建',
{ type: 'order_created', payload: { createdAt: Date.now() } }
);
break;
case 'paid':
// 订单支付成功：更新状态、记录支付时间、通知用户
await transition(
'paid',
'订单支付成功',
{ type: 'payment_confirmed', payload: { paidAt: Date.now() } }
);
break;
case 'shipped':
// 订单已发货：更新状态并提醒用户关注物流
await transition(
'shipped',
'订单已发货',
{ type: 'order_shipped', payload: { shippedAt: Date.now() } }
);
break;
case 'delivered':
// 订单已签收：更新状态并可以引导用户评价
await transition(
'delivered',
'订单已送达',
{ type: 'order_delivered', payload: { deliveredAt: Date.now() } }
);
break;
case 'cancelled':
// 订单取消：更新状态并说明取消原因（如有）
await transition(
'cancelled',
'订单已取消',
{ type: 'order_cancelled', payload: { cancelledAt: Date.now() } }
);
break;
case 'refunded':
// 订单退款：更新状态并告知退款进度
await transition(
'refunded',
'订单已退款',
{ type: 'order_refunded', payload: { refundedAt: Date.now() } }
);
break;
default:
// 默认处理：记录异常事件，保持原状态并通知运营介入
logger.warn(`[Order:${orderId}] 未识别的事件: ${String(orderEvent)}，保持原状态: ${String(currentStatus)}`);
await services.addTimeline(orderId, `收到异常事件: ${String(orderEvent)}，已通知运营介入`);
await services.notifyOps({
severity: 'medium',
title: '异常订单事件',
details: {
orderId,
eventReceived: orderEvent,
normalizedEvent: event,
currentStatus: currentStatus || '',
occurredAt: Date.now()
}
});
break;
}
return {
handled: ['created', 'paid', 'shipped', 'delivered', 'cancelled', 'refunded'].includes(event),
orderId,
prevStatus: currentStatus || '',
nextStatus: status || '',
event
};
} catch (err) {
// 错误处理：记录并上报运营
logger.error(`[Order:${orderId}] 处理事件(${String(orderEvent)})失败: ${err && err.message}`);
try {
await services.notifyOps({
severity: 'high',
title: '订单事件处理失败',
details: {
orderId,
eventReceived: orderEvent,
currentStatus: currentStatus || '',
error: err && err.message,
occurredAt: Date.now()
}
});
} catch (_) {
// 避免二次异常影响主流程
}
// 将错误继续抛出，方便上层感知与回滚
throw err;
}
}
// 使用示例
(async () => {
// 模拟服务
const mockServices = {
updateStatus: async (orderId, next) => console.log(`[updateStatus] ${orderId} -> ${next}`),
addTimeline: async (orderId, msg) => console.log(`[addTimeline] ${orderId} | ${msg}`),
notifyUser: async (orderId, type, payload) => console.log(`[notifyUser] ${orderId} | ${type}`, payload),
notifyOps: async (payload) => console.log(`[notifyOps]`, payload),
logger: {
info: console.log,
warn: console.warn,
error: console.error
}
};
// 1) 正常事件
const res1 = await handleOrderEvent('paid', {
orderId: 'ORD-1001',
currentStatus: 'created',
services: mockServices
});
console.log('Result1:', res1);
// 预期输出（示例）：
// [updateStatus] ORD-1001 -> paid
// [addTimeline] ORD-1001 | 订单支付成功
// [notifyUser] ORD-1001 | payment_confirmed { paidAt: 1690000000000 }
// Result1: { handled: true, orderId: 'ORD-1001', prevStatus: 'created', nextStatus: 'paid', event: 'paid' }
// 2) 重复事件（幂等）
const res2 = await handleOrderEvent('PAID', {
orderId: 'ORD-1001',
currentStatus: 'paid',
services: mockServices
});
console.log('Result2:', res2);
// 预期输出（示例）：
// 状态已为 paid，忽略重复事件
// [addTimeline] ORD-1001 | 订单支付成功
// [notifyUser] ORD-1001 | payment_confirmed {...}
// Result2: { handled: true, orderId: 'ORD-1001', prevStatus: 'paid', nextStatus: 'paid', event: 'paid' }
// 3) 异常事件（触发默认分支）
const res3 = await handleOrderEvent('unknown_event', {
orderId: 'ORD-1002',
currentStatus: 'created',
services: mockServices
});
console.log('Result3:', res3);
// 预期输出（示例）：
// 未识别的事件: unknown_event，保持原状态...
// [addTimeline] ORD-1002 | 收到异常事件: unknown_event，已通知运营介入
// [notifyOps] { severity: 'medium', ... }
// Result3: { handled: false, orderId: 'ORD-1002', prevStatus: 'created', nextStatus: 'created', event: 'unknown_event' }
})();
// 注意事项
// - 严格模式下运行，避免隐式全局变量与静默错误。
// - switch-case 不允许省略 break，且无 case 穿透；本实现每个分支均以 break 结束。
// - 事件名在进入分支前做了归一化处理（trim + toLowerCase），提高容错性。
// - 采用幂等更新：仅当目标状态与当前状态不一致时才触发 updateStatus，避免重复写入。
// - 默认分支会记录异常事件并通知运营，但不会修改订单状态，满足“记录异常事件，保持原状态并通知运营介入”的要求。
// - 外部 services 为可插拔依赖，生产环境中请确保其实现稳定、具备重试与超时控制。
// - 如需增加新事件，按照既有模式在 switch 中新增 case，并复用 transition 帮助函数即可。
