'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} 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} dateKeys 日期键列表。 * @return {Map} 日期键到指标对象的映射。 */ 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} dailyMap 每日映射。 * @param {Array} rows 聚合行(date / count)。 * @param {string} field 目标指标字段。 * @return {Map} 同一映射。 */ 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} dailyMap 每日映射。 * @param {Array} rows 聚合行(date / count / items_total / amount)。 * @return {Map} 同一映射。 */ 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} dateKeys 日期键列表。 * @param {Map} dailyMap 每日映射。 * @return {Array} 每日汇总行。 */ 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} 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, };