// A10 Process Cycle Efficiency (execution-prompt §8.6) — Wertstrom P1.
//
// `Process Cycle Efficiency = Value-adding time / Total lead time`, named
// explicitly (Capability-Matrix A10 "PCE benannt") and shown as a percentage.

import type { MetricExplain } from './types'

export interface PceResult {
  pcePct: number | null
  explain: MetricExplain
}

const FORMULA = 'Process Cycle Efficiency [%] = Wertschöpfende Zeit ÷ Gesamtdurchlaufzeit × 100.'
const DATA_BASIS = 'Wertschöpfende Zeit (VA-Zeit) + Gesamtdurchlaufzeit (Total Lead Time) — beide aus derselben Timeline-Berechnung (A4/timeline-ladder.ts), damit Zähler und Nenner konsistent sind.'

/**
 * A10 §8.6. `totalLeadTimeSec` of `0` (a genuinely empty/instant wertstrom)
 * makes PCE undefined (division by zero) — returns `null`, not a fabricated
 * 0% or 100%.
 */
export function computePce(vaTimeSec: number | null | undefined, totalLeadTimeSec: number | null | undefined): PceResult {
  if (vaTimeSec == null || totalLeadTimeSec == null || !(totalLeadTimeSec > 0)) {
    return { pcePct: null, explain: { formula: FORMULA, dataBasis: DATA_BASIS, exclusions: ['VA-Zeit oder Gesamtdurchlaufzeit fehlt, oder Gesamtdurchlaufzeit ist 0 — nicht berechenbar.'] } }
  }
  return { pcePct: (vaTimeSec / totalLeadTimeSec) * 100, explain: { formula: FORMULA, dataBasis: DATA_BASIS, exclusions: [] } }
}