- 新增 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>
331 lines
9.7 KiB
JavaScript
331 lines
9.7 KiB
JavaScript
'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,
|
||
};
|