# QA: Code Analysis Summary

**Last Updated:** 2026-01-05

## Overview

This document compiles code analysis findings across all 17 tools, documenting patterns, best practices, and architectural insights.

## Code Organization Patterns

### Modular Structure

**Tools with Modular JavaScript:**

1. ✅ **Minijob-Rechner:** `v2/js/minijob/`

   - `constants.js` - Constants and rates
   - `utils.js` - Formatting and validation
   - `helpers.js` - Calculation helpers
   - `calculator.js` - Main Alpine.js component
   - `export.js` - Export functionality

2. ✅ **Arbeitslosengeld-Rechner:** `v2/js/arbeitslosengeld/`
   - `constants.js` - ALG 1 constants
   - `utils.js` - Formatting utilities
   - `helpers.js` - Calculation helpers
   - `calculator.js` - Main Alpine.js component
   - `export.js` - PDF/Excel export

**Tools with External JavaScript:**

3. ✅ **Zuschlagsrechner:** `v2/js/tools-zuschlags-calculator.js`
4. ✅ **Arbeitszeitrechner:** `v2/js/tools-arbeitszeit-calculator.js`
5. ✅ **Stundenlohnrechner:** `v2/js/tools-stundenlohn-calculator.js`
6. ✅ **Midijob-Rechner:** `v2/js/tools-midijob-calculator.js`
7. ✅ **PayPal Gebührenrechner:** `v2/js/tools-paypal-calculator.js` + `v2/api/paypal_fees_config.json`
8. ✅ **Prozentrechner:** `v2/js/tools-prozentrechner-calculator.js`

**Tools with Inline JavaScript:**

9. ✅ **Industrieminuten-Rechner:** Inline Alpine.js in PHP
10. ✅ **Kostenrechner:** Inline Alpine.js in PHP
11. ✅ **ROI-Rechner Schichtplanung:** Inline Alpine.js in PHP
12. ✅ **Arbeitstage-Rechner:** Inline Alpine.js in PHP
13. ✅ **Urlaubsanspruch-Rechner:** Inline Alpine.js in PHP
14. ✅ **Mehrwertsteuer-Rechner:** Inline Alpine.js in PHP
15. ✅ **Zinseszinsrechner:** Inline Alpine.js in PHP
16. ✅ **Brutto-Netto-Rechner:** Inline Alpine.js in PHP
17. ✅ **TVöD-SuE Gehaltsrechner:** Inline Alpine.js in PHP

**Pattern Analysis:**

- **Modular:** 2 tools (Minijob, Arbeitslosengeld) - Best for complex tools
- **External JS:** 6 tools - Good for medium complexity
- **Inline:** 9 tools - Acceptable for simple tools

**Recommendation:** Consider extracting inline JS to external files for better maintainability.

## Alpine.js Patterns

### Component Registration

**Pattern 1: Global Function (Most Common)**

```javascript
function toolCalculator() {
  return {
    /* component */
  };
}
window.toolCalculator = toolCalculator;
Alpine.data("toolCalculator", toolCalculator);
```

**Pattern 2: Modular Export**

```javascript
// In calculator.js
function toolCalculator() {
  return {
    /* component */
  };
}
window.toolCalculator = toolCalculator;
```

**Pattern 3: Inline Registration**

```javascript
// In PHP file
Alpine.data("toolCalculator", function () {
  return {
    /* component */
  };
});
```

**Best Practice:** Use Pattern 1 or 2 for better code organization.

### State Management

**Common Patterns:**

1. **Reactive Data Properties:**

   - Input values (x-model)
   - Results (computed)
   - UI state (showResults, hasError)

2. **Watchers:**

   - Debounced calculations (300ms for numbers, 100ms for toggles)
   - Mode switching (clear cache, recalculate)

3. **Caching:**
   - Calculation result cache (Map)
   - Cached formatters (Intl.NumberFormat)

**Best Practice:** Use debouncing for performance, caching for repeated calculations.

## Calculation Patterns

### Formula Implementation

**Pattern 1: Direct Calculation**

```javascript
calculate() {
    const result = input * rate;
    this.result = result;
}
```

**Pattern 2: Helper Functions**

```javascript
calculate() {
    const result = this.HELPERS.calculateValue(input, rate);
    this.result = result;
}
```

**Pattern 3: Step-by-Step**

```javascript
calculate() {
    const step1 = this.calculateStep1(input);
    const step2 = this.calculateStep2(step1);
    const step3 = this.calculateStep3(step2);
    this.result = step3;
}
```

**Best Practice:** Use Pattern 2 or 3 for complex calculations.

### Validation Patterns

**Common Pattern:**

```javascript
validateInputs() {
    const validation = this.HELPERS.validateIncome(this.income);
    if (!validation.isValid) {
        this.hasError = true;
        this.errorMessage = validation.error;
        return false;
    }
    return true;
}
```

**Best Practice:** Use helper functions for validation, consistent error handling.

## Performance Optimizations

### Debouncing

**Pattern:**

```javascript
debouncedCalculate() {
    clearTimeout(this.calculateTimeout);
    this.calculateTimeout = setTimeout(() => {
        this.calculate();
    }, 300);
}
```

**Usage:** All tools use debouncing for input changes.

### Caching

**Pattern:**

```javascript
calculationCache: new Map(),
getCacheKey(mode) {
    return `${mode}-${JSON.stringify(inputs)}`;
},
calculate() {
    const cacheKey = this.getCacheKey(this.mode);
    if (this.calculationCache.has(cacheKey)) {
        return this.calculationCache.get(cacheKey);
    }
    // Calculate and cache
}
```

**Usage:** Minijob-Rechner uses caching for performance.

### RequestAnimationFrame

**Pattern:**

```javascript
calculate() {
    if (this.rafPending) return;
    this.rafPending = true;
    requestAnimationFrame(() => {
        this.rafPending = false;
        // Perform calculation
    });
}
```

**Usage:** Minijob-Rechner uses RAF for DOM updates.

**Best Practice:** Use debouncing, caching, and RAF for optimal performance.

## Export Patterns

### Email Gating

**Common Pattern:**

```javascript
async exportPDF() {
    if (!this.emailCollected) {
        this.showEmailModal = true;
        this.exportFormat = 'PDF';
        return;
    }
    // Generate export
}
```

**Usage:** All tools with exports use email gating.

### PDF Generation

**Pattern:**

```javascript
async exportPDF() {
    await loadPDFLibraries();
    const { jsPDF } = window.jspdf;
    const doc = new jsPDF();
    // Generate PDF content
    doc.save(filename);
}
```

**Usage:** Tools with PDF export use jsPDF library.

### Excel Generation

**Pattern:**

```javascript
async exportExcel() {
    const response = await fetch('/v2/api/export-tool-excel.php', {
        method: 'POST',
        body: JSON.stringify({ toolName, data })
    });
    const blob = await response.blob();
    // Download blob
}
```

**Usage:** Tools with Excel export use API endpoint.

**Best Practice:** Use lazy-loaded libraries, email gating, consistent API patterns.

## Constants Management

### Pattern 1: Separate Constants File

**Example:** `v2/js/minijob/constants.js`

```javascript
window.minijobConstants = {
  MINIJOB_GRENZE: 556.0,
  MINDESTLOHN: 12.82,
  // ...
};
```

**Usage:** Minijob-Rechner, Arbeitslosengeld-Rechner

### Pattern 2: Embedded Constants

**Example:** Inline in Alpine.js component

```javascript
const RATES_2025 = {
  MINDESTLOHN: 12.82,
  // ...
};
```

**Usage:** Stundenlohnrechner, Arbeitszeitrechner

### Pattern 3: JSON Config File

**Example:** `v2/api/paypal_fees_config.json`

```json
{
  "lastUpdated": "2025-10-13",
  "paypalPdfVersion": "13. Oktober 2025",
  "paypalPdf": {
    /* fee structures */
  }
}
```

**Usage:** PayPal Gebührenrechner

**Best Practice:** Use Pattern 1 for complex tools, Pattern 3 for frequently updated data.

## Error Handling Patterns

### Validation Errors

**Pattern:**

```javascript
validateInputs() {
    const validation = this.HELPERS.validateIncome(this.income);
    if (!validation.isValid) {
        this.hasError = true;
        this.errorMessage = validation.error;
        this.showResults = false;
        return false;
    }
    return true;
}
```

**Usage:** All tools use consistent validation error handling.

### Calculation Errors

**Pattern:**

```javascript
calculate() {
    try {
        // Calculation logic
    } catch (error) {
        this.hasError = true;
        this.errorMessage = 'Fehler bei der Berechnung.';
        this.showResults = false;
    }
}
```

**Usage:** Some tools use try-catch for error handling.

**Best Practice:** Consistent error handling, user-friendly messages.

## Code Quality Patterns

### Function Documentation

**Pattern:**

```javascript
/**
 * Calculate base ALG 1 amount
 * @param {number} nettoIncome - Netto income amount
 * @param {boolean} hasChildren - Whether applicant has children
 * @returns {number} Base ALG 1 amount (before capping)
 */
calculateBaseALG: function(nettoIncome, hasChildren) {
    // Implementation
}
```

**Usage:** Modular tools have JSDoc comments.

**Best Practice:** Document all functions with JSDoc.

### Code Organization

**Best Practices Found:**

- ✅ Separation of concerns (constants, helpers, utils, calculator)
- ✅ Consistent naming conventions
- ✅ Modular structure (where applicable)
- ✅ Clear function responsibilities

**Areas for Improvement:**

- ⚠️ Some tools have inline JS (consider extraction)
- ⚠️ Some tools lack JSDoc comments (consider adding)

## Summary

**Code Quality Score:** High ✅

**Strengths:**

- ✅ Consistent Alpine.js patterns
- ✅ Good performance optimizations
- ✅ Modular structure (where applicable)
- ✅ Consistent error handling
- ✅ Good separation of concerns

**Patterns Identified:**

- ✅ Debouncing for input changes
- ✅ Caching for repeated calculations
- ✅ Email gating for exports
- ✅ Consistent validation patterns
- ✅ Modular constants management

**Recommendations:**

- ✅ Continue using modular structure for complex tools
- ✅ Consider extracting inline JS to external files
- ✅ Add JSDoc comments to all functions
- ✅ Maintain consistent patterns across tools

**Next Steps:**

1. ✅ Code analysis summary complete
2. → Update README