@jjlmoya/utils-motor 1.1.0 → 1.2.0

package/src/tool/realFuelConsumptionCalculator/i18n/zh.ts

@@ -0,0 +1,119 @@
+import { createLocalizedContent } from './factory';
+
+export const content = createLocalizedContent({
+  locale: 'zh',
+  slug: 'real-fuel-consumption-calculator',
+  title: '汽车与摩托车实际油耗·电耗计算器',
+  description: '根据行驶里程和加油/充电量，精准计算燃油车或电动车的实际油耗与电耗。对比每百公里费用，并与官方标称数据作参照。',
+  faqTitle: '常见问题解答',
+  bibliographyTitle: '参考文献与依据',
+  ui: {
+    fuelTypeLabel: '能源类型',
+    gasolineLabel: '汽油',
+    dieselLabel: '柴油',
+    electricLabel: '纯电 (EV)',
+    currencyLabel: '货币',
+    currencyRateLabel: '1 EUR =',
+    resetLabel: '重置',
+    measurementTitle: '您的实测行程',
+    intakeQuestion: '本次行程实际消耗了多少能源？',
+    distanceLabel: '行驶里程',
+    distanceHint: '测量期间行驶的总公里数',
+    distanceUnit: 'km',
+    usedLabel: '消耗总量',
+    gasolineUsedLabel: '加注汽油量',
+    gasolineUsedHint: '加油站加满时补充的升数',
+    dieselUsedLabel: '加注柴油量',
+    dieselUsedHint: '加油站加满时补充的升数',
+    electricUsedLabel: '充入电量',
+    electricUsedHint: '充电桩充入的度数 (kWh)',
+    fuelUnit: 'L',
+    energyUnit: 'kWh',
+    fuelConsumptionUnit: 'L/100 km',
+    energyConsumptionUnit: 'kWh/100 km',
+    priceLabel: '能源单价',
+    priceHint: '实际支付的每单位价格',
+    gasolinePriceLabel: '每升汽油价格',
+    dieselPriceLabel: '每升柴油价格',
+    electricPriceLabel: '每度电 (kWh) 价格',
+    optionalDetails: '添加官方标称值与对比车型',
+    ratedLabel: '官方标称能耗',
+    gasolineRatedLabel: '官方汽油标称油耗',
+    dieselRatedLabel: '官方柴油标称油耗',
+    electricRatedLabel: '官方纯电标称电耗',
+    ratedHint: '请输入您车辆的工况/WLTC申报数据',
+    readingTitle: '您的实际能耗',
+    comparisonTitle: '用车成本对比',
+    comparisonQuestion: '哪种动力每百公里花费更低？',
+    comparisonHint: '柱状图越长，代表百公里能耗费用越高。',
+    comparisonCostLabel: '费用 / 100 km',
+    comparisonNotSet: '请在下方添加数据',
+    comparisonReady: '已具备对比条件',
+    comparisonCheapest: '最省钱',
+    comparisonMostExpensive: '费用最高',
+    comparisonPunchline: '柱状图最短的选项，即为日常行驶成本最低的动力方案。',
+    comparisonSettingsTitle: '能耗换算比例设置',
+    comparisonSettingsHint: '每一行均与您的实测数据联动。您可以修改比例来模拟不同车型。',
+    rememberComparisonsLabel: '在本设备上保存比率设置',
+    resetComparisonsLabel: '重置比率',
+    compareConsumptionLabel: '能耗数值',
+    compareRatioLabel: '对比汽油比率',
+    comparePriceLabel: '单价',
+    efficiencyLabel: '单位能耗行驶距离',
+    mpgLabel: '美制 MPG',
+    tripCostLabel: '本次行程总花费',
+    costPer100Label: '百公里行驶花费',
+    savedLabel: '节省金额',
+    extraLabel: '额外支出',
+    gasolineStatusBetter: '本次行程汽油消耗低于官方申报油耗。',
+    gasolineStatusClose: '本次行程汽油消耗接近官方申报油耗。',
+    gasolineStatusHigher: '本次行程汽油消耗高于官方申报油耗。',
+    dieselStatusBetter: '本次行程柴油消耗低于官方申报油耗。',
+    dieselStatusClose: '本次行程柴油消耗接近官方申报油耗。',
+    dieselStatusHigher: '本次行程柴油消耗高于官方申报油耗。',
+    electricStatusBetter: '本次充电电耗低于官方申报电耗。',
+    electricStatusClose: '本次充电电耗接近官方申报电耗。',
+    electricStatusHigher: '本次充电电耗高于官方申报电耗。',
+    formulaLabel: '计算公式',
+    fuelFormula: '升数 ÷ 公里数 × 100',
+    electricFormula: '度数 ÷ 公里数 × 100',
+    localNotice: '所有测量数据仅保存在您的本地浏览器中。',
+  },
+  faq: [
+    { question: '如何计算车辆的实际油耗/电耗？', answer: '将加满补充的升数（或充入的度数kWh）除以行驶公里数，再乘以100。例如：600公里消耗了45升汽油，实际油耗即为 7.5 L/100 km。' },
+    { question: '单价栏应该输入什么？', answer: '输入您实际支付的每升油价或每度电价。选择对应的货币后，计算器会自动算出本次行程总支出及百公里费用。' },
+    { question: '可以同时对比汽油车、柴油车和电动车吗？', answer: '可以。计算器将不同动力形式的能耗与当地单价结合，统一换算为百公里花费金额，从而实现直观公平的对比。' },
+    { question: '为什么实际能耗通常高于官方工况（如WLTC/CLTC）数据？', answer: '官方数据是在标准实验室环境测得的。实际驾驶中的路况拥堵、车速变化、地形起伏、载重、胎压以及空调开闭等均会增加能耗。' },
+  ],
+  howTo: [
+    { name: '选择能源类型', text: '点击汽油、柴油或纯电，计算器会自动切换对应计量单位。' },
+    { name: '输入实测行程数据', text: '填入小计里程表显示行驶公里数，以及跳枪/充满时补充的油量或电量。' },
+    { name: '输入实际单价', text: '填入每升或每度的单价，并选择您所使用的货币。' },
+    { name: '查看计算结果', text: '实时获取 L/100km 或 kWh/100km 实际能耗、行程总油费/电费及百公里成本。' },
+    { name: '添加参考对比数据', text: '展开可选设置区，输入官方工况申报值或其他动力车型的对比参数。' },
+  ],
+  seo: {
+    calcTitle: '精准计算爱车真实用车成本与百公里花费',
+    calcText: '本计算器解答加油/充电后的实用疑问：<strong>我的车这次到底消耗了多少，这趟行程花了多少钱？</strong> 只需里程、加油量和单价，即可得出真实平均油耗、行程总开销和百公里用车成本。',
+    stat1Value: '3项输入',
+    stat1Label: '里程、加油量与单价',
+    stat2Value: 'L/100 km',
+    stat2Label: '汽油与柴油',
+    stat3Value: 'kWh/100 km',
+    stat3Label: '纯电动汽车 (EV)',
+    measureTitle: '如何用二次加满法精准测量实际油耗',
+    measureText: '先将油箱加满（或电量充至100%），将小计里程归零，正常行驶至下一次加油。再次加满并记录里程与加注升数。计算公式为：<strong>加注量 ÷ 行驶里程 × 100</strong>。',
+    tableHeaders: ['已知数据', '计算公式', '得出结果'],
+    tableRows: [
+      ['加注升数与公里数', '升数 ÷ 公里数 × 100', 'L/100 km (实际油耗)'],
+      ['充入度数与公里数', 'kWh ÷ 公里数 × 100', 'kWh/100 km (实际电耗)'],
+      ['加注量与单位单价', '加注量 × 单价', '行程总费用'],
+      ['实际能耗与单价', '实际能耗 × 单价', '百公里行驶成本'],
+    ],
+    compareTitle: '横向对比汽油、柴油与纯电能耗费用',
+    compareText: '对比卡片可一目了然地分析不同动力形式的日常花费。用百公里资金支出进行对比，比单纯比较升数与度数更为精准，能将不同能源放在同一基准线上评测。',
+    versusTitle: '实际能耗与官方工况标称值的差异',
+    tipTitle: '设置爱车官方申报值作为参考基准',
+    tipText: '在折叠面板中输入您爱车的官方工况申报数值。受实际路况、气温与驾驶习惯影响，日常行驶能耗通常高于实验室测得的申报数据。',
+  },
+});

package/src/tool/realFuelConsumptionCalculator/index.ts

@@ -0,0 +1,10 @@
+import { realFuelConsumptionCalculator } from './entry';
+
+export * from './entry';
+
+export const REAL_FUEL_CONSUMPTION_CALCULATOR_TOOL = {
+  entry: realFuelConsumptionCalculator,
+  Component: () => import('./component.astro'),
+  SEOComponent: () => import('./seo.astro'),
+  BibliographyComponent: () => import('./bibliography.astro'),
+};

package/src/tool/realFuelConsumptionCalculator/logic.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import { amountUnit, calculateFuelLog, consumptionUnit, currencyConversionFactor, currencySymbol } from './logic';
+
+const comparisons = {
+  gasoline: { ratio: 1, price: 1.8 },
+  diesel: { ratio: 0.82, price: 1.72 },
+  electric: { ratio: 2.6, price: 0.22 },
+};
+
+describe('fuel log logic', () => {
+  it('calculates gasoline consumption and cost', () => {
+    const result = calculateFuelLog({ distance: 400, used: 24, price: 1.8, rated: 5.2, mode: 'gasoline', currency: 'EUR', comparisons });
+
+    expect(result.realPer100).toBeCloseTo(6, 6);
+    expect(result.distancePerUnit).toBeCloseTo(16.6667, 4);
+    expect(result.usMpg).toBeCloseTo(39.2, 1);
+    expect(result.tripCost).toBeCloseTo(43.2, 6);
+    expect(result.differencePercent).toBeCloseTo(15.3846, 4);
+    expect(result.amountDelta).toBeCloseTo(-3.2, 6);
+  });
+
+  it('calculates electric consumption without MPG', () => {
+    const result = calculateFuelLog({ distance: 250, used: 42.5, price: 0.22, rated: 16, mode: 'electric', currency: 'EUR', comparisons });
+
+    expect(result.realPer100).toBeCloseTo(17, 6);
+    expect(result.usMpg).toBeNull();
+    expect(result.tripCost).toBeCloseTo(9.35, 6);
+    expect(result.ratedAmount).toBe(40);
+  });
+
+  it('protects calculations from invalid readings', () => {
+    const result = calculateFuelLog({ distance: Number.NaN, used: -1, price: Number.NaN, rated: 0, mode: 'diesel', currency: 'RUB', comparisons });
+
+    expect(result.distance).toBe(1);
+    expect(Number.isFinite(result.realPer100)).toBe(true);
+    expect(Number.isFinite(result.tripCost)).toBe(true);
+  });
+
+  it('returns a cost comparison for each configured energy type', () => {
+    const result = calculateFuelLog({ distance: 100, used: 6.5, price: 1.8, rated: 5.8, mode: 'gasoline', currency: 'EUR', comparisons });
+
+    expect(result.comparisons.gasoline?.costPer100).toBeCloseTo(11.7, 6);
+    expect(result.comparisons.diesel?.costPer100).toBeCloseTo(9.1676, 6);
+    expect(result.comparisons.electric?.costPer100).toBeCloseTo(3.718, 6);
+  });
+
+  it('converts the active diesel reading back to the gasoline baseline', () => {
+    const result = calculateFuelLog({ distance: 100, used: 5.33, price: 1.72, rated: 5.8, mode: 'diesel', currency: 'EUR', comparisons });
+
+    expect(result.realPer100).toBeCloseTo(5.33, 6);
+    expect(result.comparisons.gasoline?.consumption).toBeCloseTo(6.5, 1);
+    expect(result.comparisons.gasoline?.costPer100).toBeGreaterThan(result.comparisons.diesel?.costPer100 ?? 0);
+  });
+
+  it('uses currency factors that match the scale of each local currency', () => {
+    expect(currencyConversionFactor('EUR')).toBe(1);
+    expect(currencyConversionFactor('RUB')).toBeCloseTo(96.73, 2);
+    expect(currencyConversionFactor('JPY')).toBeCloseTo(185.66, 2);
+    expect(currencyConversionFactor('IDR')).toBeCloseTo(20659.38, 2);
+  });
+
+  it('exposes the units and currency symbols used by the interface', () => {
+    expect(amountUnit('gasoline')).toBe('L');
+    expect(amountUnit('electric')).toBe('kWh');
+    expect(consumptionUnit('diesel')).toBe('L/100 km');
+    expect(consumptionUnit('electric')).toBe('kWh/100 km');
+    expect(currencySymbol('EUR')).toBe('€');
+    expect(currencySymbol('USD')).toBe('$');
+    expect(currencySymbol('RUB')).toBe('₽');
+    expect(currencySymbol('JPY')).toBe('¥');
+  });
+});

package/src/tool/realFuelConsumptionCalculator/logic.ts

@@ -0,0 +1,142 @@
+export type EnergyMode = 'gasoline' | 'diesel' | 'electric';
+export type Currency = 'EUR' | 'USD' | 'IDR' | 'JPY' | 'KRW' | 'PLN' | 'RUB' | 'SEK' | 'TRY' | 'CNY';
+
+export interface ComparisonInput {
+  ratio: number;
+  price: number;
+}
+
+export interface FuelLogInput {
+  distance: number;
+  used: number;
+  price: number;
+  rated: number;
+  mode: EnergyMode;
+  currency: Currency;
+  comparisons: Record<EnergyMode, ComparisonInput>;
+}
+
+export interface FuelComparisonResult {
+  mode: EnergyMode;
+  consumption: number;
+  price: number;
+  costPer100: number;
+}
+
+export interface FuelLogResult {
+  distance: number;
+  used: number;
+  price: number;
+  rated: number;
+  mode: EnergyMode;
+  currency: Currency;
+  realPer100: number;
+  distancePerUnit: number;
+  usMpg: number | null;
+  tripCost: number;
+  costPer100: number;
+  differencePercent: number;
+  ratedAmount: number;
+  amountDelta: number;
+  comparisons: Record<EnergyMode, FuelComparisonResult | null>;
+}
+
+const KM_TO_MILES = 0.621371192;
+const LITRES_TO_US_GALLONS = 0.264172052;
+
+const CURRENCY_PER_EUR: Record<Currency, number> = {
+  EUR: 1, USD: 1.1699, IDR: 20659.38, JPY: 185.66, KRW: 1619.41,
+  PLN: 4.3078, RUB: 96.73, SEK: 11.0625, TRY: 56.2318, CNY: 7.8624,
+};
+
+function positive(value: number, fallback: number): number {
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function nonNegative(value: number): number {
+  return Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+function comparison(mode: EnergyMode, input: ComparisonInput, gasolineBase: number): FuelComparisonResult | null {
+  if (!Number.isFinite(input.ratio) || input.ratio <= 0) return null;
+  const price = nonNegative(input.price);
+  const consumption = gasolineBase * input.ratio;
+  return { mode, consumption, price, costPer100: consumption * price };
+}
+
+interface NormalizedFuelInput {
+  distance: number;
+  used: number;
+  price: number;
+  rated: number;
+}
+
+function normalizedInput(input: FuelLogInput): NormalizedFuelInput {
+  return {
+    distance: positive(input.distance, 1),
+    used: positive(input.used, 0.001),
+    price: nonNegative(input.price),
+    rated: positive(input.rated, 0.1),
+  };
+}
+
+function fuelMetrics(input: NormalizedFuelInput, mode: EnergyMode): Pick<FuelLogResult, 'realPer100' | 'distancePerUnit' | 'usMpg' | 'tripCost' | 'costPer100' | 'differencePercent' | 'ratedAmount' | 'amountDelta'> {
+  const { distance, used, price, rated } = input;
+  const realPer100 = (used / distance) * 100;
+  const ratedAmount = (distance / 100) * rated;
+  const usMpg = mode === 'electric' ? null : (distance * KM_TO_MILES) / (used * LITRES_TO_US_GALLONS);
+  return {
+    realPer100,
+    distancePerUnit: distance / used,
+    usMpg,
+    tripCost: used * price,
+    costPer100: realPer100 * price,
+    differencePercent: ((realPer100 - rated) / rated) * 100,
+    ratedAmount,
+    amountDelta: ratedAmount - used,
+  };
+}
+
+export function calculateFuelLog(input: FuelLogInput): FuelLogResult {
+  const { distance, used, price, rated } = normalizedInput(input);
+  const metrics = fuelMetrics({ distance, used, price, rated }, input.mode);
+  const activeRatio = positive(input.comparisons[input.mode].ratio, 1);
+  const gasolineBase = input.mode === 'gasoline' ? metrics.realPer100 : metrics.realPer100 / activeRatio;
+  const comparisons = {
+    gasoline: comparison('gasoline', input.comparisons.gasoline, gasolineBase),
+    diesel: comparison('diesel', input.comparisons.diesel, gasolineBase),
+    electric: comparison('electric', input.comparisons.electric, gasolineBase),
+  };
+
+  comparisons[input.mode] = { mode: input.mode, consumption: metrics.realPer100, price, costPer100: metrics.costPer100 };
+
+  return {
+    distance,
+    used,
+    price,
+    rated,
+    mode: input.mode,
+    currency: input.currency,
+    ...metrics,
+    comparisons,
+  };
+}
+
+export function currencyConversionFactor(currency: Currency): number {
+  return CURRENCY_PER_EUR[currency];
+}
+
+export function currencySymbol(currency: Currency): string {
+  const symbols: Record<Currency, string> = {
+    EUR: '€', USD: '$', IDR: 'Rp', JPY: '¥', KRW: '₩', PLN: 'zł', RUB: '₽', SEK: 'kr', TRY: '₺', CNY: '¥',
+  };
+  return symbols[currency];
+}
+
+export function amountUnit(mode: EnergyMode): string {
+  return mode === 'electric' ? 'kWh' : 'L';
+}
+
+export function consumptionUnit(mode: EnergyMode): string {
+  return mode === 'electric' ? 'kWh/100 km' : 'L/100 km';
+}