WMS_MAIN/app/lib/delivery_order_summary.js
liufumingren 861c384917 feat(order): 新增配送订单每日汇总 order.deliveryOrder.summary
- 新增 order.deliveryOrder.summary:以自然日为维度汇总订单量、迁入配送表订单量、
  发货量(订单数/商品件数/金额)、拦截数量、库内确定拦截数量与取消数量
- 数据源为订单常用表 + 配送表分表(history/outsourced 不参与),日期分组按
  CONVERT_TZ 换算到服务器本地时区,避免 UTC 存储导致自然日偏移
- 缺省最近 7 个自然日、单次最多 90 天,区间内无数据日期补 0;可选 store_id 过滤
- 同步 methods/system.json(0.3.302 → 0.3.303)、变更记录与 AI_METHOD_ROUTING.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-21 17:13:40 +08:00

331 lines
9.7 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';
/**
* 配送订单每日汇总纯函数工具(无 egg / DB 依赖,可单测)。
*
* 口径约定:
* 1. 日期维度为本地时区自然日(yyyy-MM-dd),区间左闭右开 [start, end+1day);
* 2. 缺省统计区间为「结束日往前 7 个自然日」(含结束日);
* 3. 单次最多 {@link MAX_DAY_COUNT} 天,避免跨过订单归档边界(history 分表不参与统计);
* 4. 每日指标缺失时补 0,保证前端按日绘图的连续性。
*/
const DAY_MS = 24 * 60 * 60 * 1000;
const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
/** 缺省统计天数(含结束日)。 */
const DEFAULT_DAY_COUNT = 7;
/** 单次查询最大天数。 */
const MAX_DAY_COUNT = 90;
/** 每日指标字段清单(顺序即响应字段顺序)。 */
const METRIC_FIELDS = Object.freeze([
'order_count',
'dispatch_count',
'shipped_count',
'shipped_items_total',
'shipped_amount',
'intercepted_count',
'intercepted_at_warehouse_count',
'cancelled_count',
]);
/**
* 两位补零。
* @param {number} value 数值。
* @return {string} 补零字符串。
*/
function pad2(value) {
return String(value).padStart(2, '0');
}
/**
* 本地时区格式化为 yyyy-MM-dd。
* @param {Date} date 日期对象。
* @return {string} 格式化结果。
*/
function formatDate(date) {
return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
}
/**
* 构造日期偏移(按本地年月日加减,规避夏令时步进偏差)。
* @param {Date} date 基准日期。
* @param {number} days 偏移天数(可为负)。
* @return {Date} 偏移后的日期(00:00:00.000)。
*/
function addDays(date, days) {
return new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
}
/**
* 计算两个日期相差的自然日数量(按 UTC 年月日归一化,忽略时分秒)。
* @param {Date} start 开始日期。
* @param {Date} end 结束日期。
* @return {number} 相差天数(end - start)。
*/
function diffDays(start, end) {
const startDay = Date.UTC(start.getFullYear(), start.getMonth(), start.getDate()) / DAY_MS;
const endDay = Date.UTC(end.getFullYear(), end.getMonth(), end.getDate()) / DAY_MS;
return endDay - startDay;
}
/**
* 解析 yyyy-MM-dd(兼容 yyyy-MM-dd HH:mm:ss 等带时间后缀的入参)。
* @param {*} value 待解析值(字符串 / Date)。
* @return {Date|null} 本地时区 00:00:00.000 的日期;无法解析时返回 null。
*/
function parseDateOnly(value) {
if (value instanceof Date) {
return Number.isNaN(value.getTime())
? null
: new Date(value.getFullYear(), value.getMonth(), value.getDate());
}
const text = String(value === null || value === undefined ? '' : value).trim();
if (!text) {
return null;
}
const matched = DATE_PATTERN.exec(text.slice(0, 10));
if (!matched) {
return null;
}
const year = Number(matched[1]);
const month = Number(matched[2]);
const day = Number(matched[3]);
const candidate = new Date(year, month - 1, day);
if (
candidate.getFullYear() !== year
|| candidate.getMonth() !== month - 1
|| candidate.getDate() !== day
) {
return null;
}
return candidate;
}
/**
* 构造统计区间非法错误。
* @param {string} message 错误文案。
* @return {Error} 带 INVALID_SUMMARY_RANGE 错误码的异常。
*/
function buildRangeError(message) {
const error = new Error(message);
error.code = 'INVALID_SUMMARY_RANGE';
return error;
}
/**
* 解析并校验统计区间。
*
* 规则:
* - 仅传 endDate:startDate = endDate - (DEFAULT_DAY_COUNT - 1) 天;
* - 仅传 startDate:endDate = 今天;
* - 都不传:最近 DEFAULT_DAY_COUNT 个自然日(含今天);
* - startDate 晚于 endDate、区间超过 MAX_DAY_COUNT 天、格式非法均抛错。
*
* @param {Object} [options={}] 入参。
* @param {*} [options.startDate] 开始日期(yyyy-MM-dd)。
* @param {*} [options.endDate] 结束日期(yyyy-MM-dd)。
* @param {Date} [options.now=new Date()] 当前时间(便于单测注入)。
* @return {{start: Date, end: Date, endExclusive: Date, startDate: string, endDate: string, dayCount: number}} 区间信息。
*/
function resolveSummaryRange({ startDate = null, endDate = null, now = new Date() } = {}) {
const todayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate());
const hasStart = String(startDate === null || startDate === undefined ? '' : startDate).trim() !== '';
const hasEnd = String(endDate === null || endDate === undefined ? '' : endDate).trim() !== '';
const parsedStart = parseDateOnly(startDate);
const parsedEnd = parseDateOnly(endDate);
if (hasStart && !parsedStart) {
throw buildRangeError('开始日期格式不正确,应为 yyyy-MM-dd');
}
if (hasEnd && !parsedEnd) {
throw buildRangeError('结束日期格式不正确,应为 yyyy-MM-dd');
}
const end = parsedEnd || todayStart;
const start = parsedStart || addDays(end, -(DEFAULT_DAY_COUNT - 1));
if (start.getTime() > end.getTime()) {
throw buildRangeError('开始日期不能晚于结束日期');
}
const dayCount = diffDays(start, end) + 1;
if (dayCount > MAX_DAY_COUNT) {
throw buildRangeError(`汇总天数不能超过 ${MAX_DAY_COUNT} 天`);
}
return {
start,
end,
endExclusive: addDays(end, 1),
startDate: formatDate(start),
endDate: formatDate(end),
dayCount,
};
}
/**
* 生成区间内逐日日期键(含首尾)。
* @param {Date} start 开始日期。
* @param {Date} end 结束日期(含)。
* @return {Array<string>} yyyy-MM-dd 列表。
*/
function buildDateKeys(start, end) {
const total = diffDays(start, end) + 1;
const keys = [];
for (let index = 0; index < total; index += 1) {
keys.push(formatDate(addDays(start, index)));
}
return keys;
}
/**
* 创建全零的每日指标对象。
* @return {Object} 指标对象。
*/
function createEmptyMetrics() {
const metrics = {};
for (const field of METRIC_FIELDS) {
metrics[field] = 0;
}
return metrics;
}
/**
* 按日期键初始化每日指标映射。
* @param {Array<string>} dateKeys 日期键列表。
* @return {Map<string, Object>} 日期键到指标对象的映射。
*/
function buildDailyMap(dateKeys) {
const dailyMap = new Map();
for (const key of dateKeys) {
dailyMap.set(key, createEmptyMetrics());
}
return dailyMap;
}
/**
* 归一化聚合行返回的日期值(MySQL DATE() 可能返回字符串或 Date 实例)。
* @param {*} value 原始日期值。
* @return {string} yyyy-MM-dd;无法识别时返回空串。
*/
function normalizeRowDate(value) {
if (value instanceof Date) {
return Number.isNaN(value.getTime()) ? '' : formatDate(value);
}
const text = String(value === null || value === undefined ? '' : value).trim();
return text.slice(0, 10);
}
/**
* 数值安全转换。
* @param {*} value 原始值。
* @return {number} 数值;非法值按 0 处理。
*/
function toNumber(value) {
const num = Number(value);
return Number.isFinite(num) ? num : 0;
}
/**
* 金额保留两位小数。
* @param {*} value 原始值。
* @return {number} 保留两位小数的金额。
*/
function roundAmount(value) {
return Math.round(toNumber(value) * 100) / 100;
}
/**
* 合并按日计数的聚合行到每日映射(区间外日期忽略)。
* @param {Map<string, Object>} dailyMap 每日映射。
* @param {Array<Object>} rows 聚合行(date / count)。
* @param {string} field 目标指标字段。
* @return {Map<string, Object>} 同一映射。
*/
function addCountRows(dailyMap, rows, field) {
const list = Array.isArray(rows) ? rows : [];
for (const row of list) {
const target = dailyMap.get(normalizeRowDate(row && row.date));
if (target) {
target[field] += toNumber(row.count);
}
}
return dailyMap;
}
/**
* 合并发货聚合行(订单数 / 商品件数 / 金额)到每日映射。
* @param {Map<string, Object>} dailyMap 每日映射。
* @param {Array<Object>} rows 聚合行(date / count / items_total / amount)。
* @return {Map<string, Object>} 同一映射。
*/
function addShippedRows(dailyMap, rows) {
const list = Array.isArray(rows) ? rows : [];
for (const row of list) {
const target = dailyMap.get(normalizeRowDate(row && row.date));
if (!target) {
continue;
}
target.shipped_count += toNumber(row.count);
target.shipped_items_total += toNumber(row.items_total);
target.shipped_amount += toNumber(row.amount);
}
return dailyMap;
}
/**
* 按日期顺序输出每日行,金额统一保留两位小数。
* @param {Array<string>} dateKeys 日期键列表。
* @param {Map<string, Object>} dailyMap 每日映射。
* @return {Array<Object>} 每日汇总行。
*/
function finalizeDailyRows(dateKeys, dailyMap) {
return dateKeys.map(date => {
const metrics = dailyMap.get(date) || createEmptyMetrics();
return {
date,
...metrics,
shipped_amount: roundAmount(metrics.shipped_amount),
};
});
}
/**
* 汇总每日行,输出区间合计。
* @param {Array<Object>} rows 每日汇总行。
* @return {Object} 合计指标。
*/
function summarizeRows(rows) {
const summary = createEmptyMetrics();
for (const row of (Array.isArray(rows) ? rows : [])) {
for (const field of METRIC_FIELDS) {
summary[field] += toNumber(row && row[field]);
}
}
summary.shipped_amount = roundAmount(summary.shipped_amount);
return summary;
}
module.exports = {
DEFAULT_DAY_COUNT,
MAX_DAY_COUNT,
METRIC_FIELDS,
formatDate,
addDays,
parseDateOnly,
resolveSummaryRange,
buildDateKeys,
createEmptyMetrics,
buildDailyMap,
normalizeRowDate,
addCountRows,
addShippedRows,
finalizeDailyRows,
summarizeRows,
};