Formula System Documentation¶

// Beispiel: Formel "A+B-C"
// A = Feld mit int_sortierung = 0 (z.B. "D/A-Note")
// B = Feld mit int_sortierung = 1 (z.B. "E/B-Note")
// C = Feld mit int_sortierung = 2 (z.B. "Abzug")

-- tfx_disziplinen
int_formelid → Referenz zu tfx_formeln
var_formel   → Falls int_formelid = NULL (benutzerdefiniert)

-- tfx_disziplinen_felder
int_sortierung → Bestimmt A, B, C, ... Position
var_name       → Feldname (z.B. "D/A-Note")
bol_endwert    → TRUE für Endwert-Feld

// Formel: A+B+C+D+E (benötigt 5 Felder)
// DB hat nur: D/A-Note (A), E/B-Note (B), Ausgangswert (C)
// System erstellt automatisch: "Field D", "Field E"

// Beispiel: Formel "(((1000/x)-2,158)/0,006)/49"
// x = Einziges Eingabefeld "X"
// Ergebnis = Automatisch berechnet
// ⚠️ Deutsche Dezimalkommas (2,158 statt 2.158) werden automatisch normalisiert

const variableMap = ['x', 'y', 'z', 'a', 'b', 'c']; // Max. 6 Felder

// Eingabe: "5,5"
// Normalisiert zu: "5.50" (bei Mask 0.00)
// Für Berechnung: 5.5 (parseFloat)

parseTimeToSeconds("00:05.55") 
// → 5.55 Sekunden (5*1 + 0.55)

parseTimeToSeconds("01:30.25") 
// → 90.25 Sekunden (60*1 + 30 + 0.25)

// Beispiel: InputMask "0.00"
handleFieldChange(id, "5,5")    // Roh-Eingabe
→ handleFieldBlur(id)            // Trigger Normalisierung
→ normalizeScoreInput("5.5", "0.00")  // Komma→Punkt intern
→ Display: "5.50"                // Formatiert mit 2 Dezimalstellen
→ Calculation: 5.5               // parseFloat für Formel

client/src/
├── utils/
│   ├── formulaCalculator.ts    # Client Engine: 13 Core Functions (CSP-safe)
│   └── inputMaskUtils.ts       # InputMask Parsing & Normalisierung
├── hooks/
│   ├── useFormulaFields.ts     # State Management Hook (nutzt formulaCalculator)
│   └── useFormulaCalculation.ts # Display/Evaluation (nutzt shared Engine)
└── components/
    ├── FormulaInput.tsx         # Wiederverwendbare UI (Management)
    └── DisciplineConfigTester.tsx  # Legacy Wrapper

shared/src/
└── formulaUtils.ts             # Shared Engine: calculateFormula, formatFormula (expr-eval)

jury-portal/src/components/
└── FormulaInput.tsx             # Jury-Portal FormulaInput (nutzt shared Engine)

// Operator-Precedence:
parseExpression()  // +, - (niedrigste Priorität)
  → parseTerm()    // *, / (höhere Priorität)
    → parseFactor() // Zahlen, Klammern, Negation

// Beispiel: "5+3*2"
// 1. parseExpression → 5 + parseTerm()
// 2. parseTerm → 3 * 2 = 6
// 3. Result → 5 + 6 = 11 ✓ (korrekte Operator-Precedence)

// Nur erlaubte Zeichen: Ziffern, Punkt, Operatoren, Klammern
/^[\d\.\+\-\*\/\(\)]+$/.test(formula)

// Fehler bei:
// - Buchstaben übrig: "1+5+D" ❌
// - Ungültige Zeichen: "5&3" ❌
// - Division durch 0: "5/0" ❌

interface UseFormulaFieldsOptions {
  formula?: string;              // Direkte Formel
  formulaId?: number | null;     // Formel aus DB
  disciplineId?: number;         // Für Field-Loading
  inputMask?: string;            // Format (0.00, 00:00.00)
  onFieldsLoaded?: (fields) => void;
  onCalculationComplete?: (result) => void;
}

interface UseFormulaFieldsResult {
  fields: FormulaField[];        // Alle Felder inkl. Werte
  calculatedResult: number | null;
  formulaError: string | null;
  loadingFormula: boolean;
  effectiveFormula: string;
  updateFieldValue: (id, value) => void;
  normalizeFieldValue: (id) => void;
  getFieldOperator: (index) => string;
  getFieldLetterLabel: (index) => string;
}

1. Mount
   ↓
2. Load Formula (wenn formulaId gesetzt)
   ↓
3. Detect Formula Type (letter vs variable)
   ↓
4. Load Fields
   ├─ Letter: API /discipline-fields
   │  └─ Check missing fields → create
   └─ Variable: Extract variables → create
   ↓
5. User Input (updateFieldValue)
   ↓
6. Blur (normalizeFieldValue)
   ↓
7. Auto-Calculate (wenn alle Felder gefüllt)
   ↓
8. onCalculationComplete Callback

// Formel: A+B+C+D+E
// DB-Felder: 3 (A, B, C)
// Fehlende: 2 (D, E)

const maxLetterIndex = getMaxLetterIndex("A+B+C+D+E"); // → 4 (E)
const missingCount = (4 + 1) - 3; // → 2

for (let i = 3; i <= 4; i++) {
  fields.push({
    id: 1000 + i,
    name: `Field ${getFieldLetter(i)}`, // "Field D", "Field E"
    value: '',
    isFinalScore: false
  });
}

interface FormulaInputProps {
  inputMask?: string;
  formula?: string;
  formulaId?: number | null;
  calculationType?: number;      // 2 = 2 Dezimalen, 3 = 3 Dezimalen
  unit?: string;                 // "Pkt.", "Sek."
  disciplineId?: number;
  showTitle?: boolean;           // "Formula Calculation Test" Header
  className?: string;
  onFieldsLoaded?: (fields) => void;
  onCalculationComplete?: (result) => void;
}

┌─────────────────────────────────────────────┐
│ 🧪 Formula Calculation Test                │ (optional)
├─────────────────────────────────────────────┤
│  (A)        (B)        (C)        = (EW)    │
│ D/A-Note  E/B-Note  Ausgangswert  Endwert   │
│ [5.00]  + [5.00]  + [7.00]      = [ ? ]     │
│                                   (grün)     │
│                               Pkt.           │
└─────────────────────────────────────────────┘

import DisciplineConfigTester from '../components/DisciplineConfigTester';

<DisciplineConfigTester
  inputMask="0.00"
  formula="A+B-C"
  formulaId={3}
  calculationType={3}
  unit="Pkt."
  disciplineId={74}
/>

import { FormulaInput } from '../components/FormulaInput';

<FormulaInput
  formula="A+B-C"
  disciplineId={74}
  inputMask="0.00"
  calculationType={3}
  unit="Pkt."
  showTitle={false}  // Kein Header
  onCalculationComplete={(result) => {
    // Speichere Ergebnis direkt
    saveScoreToDatabase(result);
  }}
/>

import { useFormulaFields } from '../hooks/useFormulaFields';

const TeamScore = () => {
  const {
    fields,
    updateFieldValue,
    normalizeFieldValue,
    calculatedResult
  } = useFormulaFields({
    formula: "A+B+C",
    disciplineId: 31,
    inputMask: "0.00",
    onCalculationComplete: (result) => {
      console.log('Team Score:', result);
    }
  });

  return (
    <div>
      {fields.filter(f => !f.isFinalScore).map(field => (
        <input
          key={field.id}
          value={field.value}
          onChange={(e) => updateFieldValue(field.id, e.target.value)}
          onBlur={() => normalizeFieldValue(field.id)}
        />
      ))}
      <div>Ergebnis: {calculatedResult}</div>
    </div>
  );
};

import { calculateFormulaResult } from '../utils/formulaCalculator';

const { result, error } = calculateFormulaResult(
  "A+B-C",
  ["5.00", "5.00", "0.30"], // Feldwerte
  "letter"                  // Formel-Typ
);

console.log(result); // 9.7

Eingabe: D/A-Note = 5.00, E/B-Note = 8.50, Abzug = 0.30
Formel:  A + B - C
       = 5.00 + 8.50 - 0.30
       = 13.20

Eingabe: x = "00:05.55"
Konvertierung: 00:05.55 → 5.55 Sekunden
Formel:  (((1000/x)-2.158)/0.006)/49
       = (((1000/5.55)-2.158)/0.006)/49
       = (((180.18)-2.158)/0.006)/49
       = ((178.022)/0.006)/49
       = (29670.33)/49
       = 605.52

// System erkennt: Formel braucht 5 Felder (A bis E)
// DB hat nur: 3 Felder
// System erstellt: "Field D", "Field E"

Felder:
(A) D/A-Note     → DB
(B) E/B-Note     → DB
(C) Ausgangswert → DB
(D) Field D      → Auto-generiert
(E) Field E      → Auto-generiert
(EW) Endwert     → Ergebnis

Eingabe: A=1, B=5, C=5, D=3, E=2
Formel:  A + B + C + D + E
       = 1 + 5 + 5 + 3 + 2
       = 16

// 1. Division durch Null
evaluateArithmetic("5/0") 
// → Error: "Division by zero"

// 2. Ungültige Zeichen
evaluateArithmetic("1+5+D") 
// → Error: "Invalid characters in expression: 1+5+D"

// 3. Ungültiger Wert
calculateFormulaResult("A+B", ["5", "abc"], "letter")
// → { result: null, error: "Invalid value: abc" }

// 4. Unvollständige Eingabe
// → calculatedResult bleibt null (keine Error)

// ❌ UNSICHER (alte Methode):
const result = eval(formula.replace('A', '5'));

// ✅ SICHER (aktuelle Methode):
const result = evaluateArithmetic(
  replaceVariablesInFormula(formula, [5], 'letter')
);
// → Nur Zahlen und Operatoren erlaubt

// Alles in einer Komponente
// - Formula Loading
// - Field Management
// - Calculation
// - UI Rendering

// 1. Utils (formulaCalculator.ts) - 13 Funktionen
// 2. Hook (useFormulaFields.ts) - State Management
// 3. Component (FormulaInput.tsx) - UI Only
// 4. Wrapper (DisciplineConfigTester.tsx) - 42 Zeilen

// Alte Verwendung (funktioniert weiterhin):
<DisciplineConfigTester {...props} />

// Neue Verwendung (empfohlen):
<FormulaInput {...props} />

// Oder direkt Hook:
const { fields, calculatedResult } = useFormulaFields(options);

useEffect(() => {
  // ...
}, [disciplineId, effectiveFormula]); // ← effectiveFormula hinzufügen

if (maskInfo.type === 'decimal' && value.includes(',')) {
  value = value.replace(',', '.'); // ← VOR normalizeScoreInput
}

const timeMatch = value.match(/^(\d+):(\d+)[.,](\d+)$/);
//                                ^^    ^^     ^^    ^^
//                                MM    SS    .oder,  ms

if (op === '/') {
  if (right === 0) throw new Error('Division by zero');
  result /= right;
}

(((1000/x)-2,158)/0,006)/49          ← 1000m-Lauf
12*(((100/(1,2*(15*x-16,5)))-0,3))   ← 10m Streckentauchen

// ALT: Komma nicht erlaubt → Formel wird abgelehnt → return null
if (!/^[0-9+\-*/.() ]+$/.test(evalFormula)) return null;

// Deutsche Dezimalkommas normalisieren BEVOR Validierung
// Nur zwischen Ziffern ersetzen (z.B. "2,158" → "2.158")
evalFormula = evalFormula.replace(/(\d),(\d)/g, '$1.$2');

// Validierung erfolgt danach mit normalisierten Punkten
if (!/^[0-9+\-*/.() ]+$/.test(evalFormula)) return null;

// ALT: Immer ersetzen
evalFormula = evalFormula.replace(/^(\d+(\.\d+)?)/, startValue.toString());
// "1*x" mit startValue=0 → "0*x" → 0 ❌

// Custom-Formeln (lowercase vars: x, y, z) → kein startValue ersetzen
const hasLowercaseVars = /\b[a-z]\b/.test(formula);

if (startValue !== undefined && !hasLowercaseVars) {
  evalFormula = evalFormula.replace(/^(\d+(\.\d+)?)/, startValue.toString());
}
// "1*x" → bleibt "1*x" → mit x=5 → "1*5" → 5 ✓
// "10+A-B" mit startValue=15 → "15+A-B" ✓ (letter-based, kein lowercase var)

const hasLowercaseVars = /\b[a-z]\b/.test(formula);
if (replaceStartValue && startValue !== undefined && !hasLowercaseVars) {
  displayFormula = displayFormula.replace(/^(\d+(\.\d+)?)/, startValue.toString());
}

// ALT: Inline arrow erstellt neue Referenz bei jedem Render
useEffect(() => {
  onScoreChange(result, fieldValues);
}, [fieldValues, formula, startValue, onScoreChange]); // ← neue Referenz → re-render → neue Ref → ...

const onScoreChangeRef = useRef(onScoreChange);
onScoreChangeRef.current = onScoreChange;

useEffect(() => {
  const result = calculateFormula(formula, fieldValues, startValue);
  setCalculatedScore(result);
  onScoreChangeRef.current(result, fieldValues);
}, [fieldValues, formula, startValue]); // ← stabile Referenz, kein Loop

Test 1: 1*x mit x=5             → 5   ✓ (war 0 vor Fix)
Test 2: (((1000/x)-2,158)/0,006)/49 mit x=300 → 3.998 ✓ (war null vor Fix)
Test 3: (10+A)-B mit {A:6, B:3.5}             → 12.5  ✓ (unverändert)