同比环比计算

灵感：能力工具箱 rate-calculator（calculateRate）。

> 小四原创：(当期 - 基期) / 基期 * 100 → 保留精度；基期为 0 时特殊处理。
> 不实现完整 BI 看板，只提供增长率工具函数。

何时使用

• KPI 卡片显示环比 ↑/↓
• 业绩表同比列
• Demo 输入当期/上期/去年同月试算

硬约束

1. 基期 null/undefined → 返回 null（展示 -）。
2. 基期为 0：当期也为 0 → null；当期非 0 → 100（视为从零增长的约定值）。
3. 默认精度 2 位；formatRate 输出绝对值 + %，零/空为 -。
4. getRateClass：正 up、负 down、空/零 normal；可加前缀。
5. 实现要点注释标 小四原创。
6. 金额请先转 number；勿直接拿带千分位字符串做除法。

推荐实现

// 小四原创：环比
export function monthOnMonth(
  current: number,
  previous: number | null | undefined,
  precision = 2,
): number | null {
  if (previous == null) return null
  if (previous === 0) return current === 0 ? null : 100
  return Number((((current - previous) / previous) * 100).toFixed(precision))
}

// 小四原创：同比（基期换去年同月即可）
export function yearOnYear(
  current: number,
  lastYear: number | null | undefined,
  precision = 2,
): number | null {
  return monthOnMonth(current, lastYear, precision)
}

export function formatRate(value: number | null | undefined, precision = 2): string {
  if (value == null || value === 0) return '-'
  return `${Math.abs(value).toFixed(precision)}%`
}

export function rateClass(value: number | null | undefined, prefix = ''): string {
  const base =
    value == null || value === 0 ? 'normal' : value > 0 ? 'up' : 'down'
  return prefix ? `${prefix}-${base}` : base
}

Agent 步骤

1. 准备当期、上期、去年同月三个 number。
2. 算 MoM/YoY；formatRate 填单元格，rateClass 上色。
3. UI 可另加箭头符号（↑/↓），与 class 一致。
4. 自测：基期 0、基期空、负增长、精度。

不要做

• 把「环比」误算成同比基期（必须用对时间点）。
• 在本 Skill 内拉私有 KPI 接口。

附加

• README.md · reference.md · templates/usage.md