# Steuerkram – Entwicklungsregeln

## Tech Stack
PHP 8.3+, MySQL, PSR-4 (Namespace `Steuerkram\`), Composer, kein Framework.
MVC: `src/Controllers/`, `src/Models/`, `src/Services/`, `src/Views/`.

## Coding-Regeln
- Kein `var_dump`, kein `die()` in Produktionscode.
- Neue Libraries nur nach expliziter Rückfrage einbinden.
- Bestehenden Code-Stil beibehalten (declare strict_types, 4 Spaces).
- SQL ausschließlich über `Database::fetchAll/fetchOne/execute()` mit Prepared Statements.

## Tests
**Regel: Jedes neue Feature bekommt einen eigenen Test.**

Tests liegen in `tests/` und folgen dem Namensschema `NN_FunktionsnameTest.php`.
Jede Testklasse erweitert `TestCase` und implementiert `run()`.

```bash
php tests/run.php           # alle Tests ausführen
./scripts/run-tests.sh      # Tests + automatische Issue-Erstellung bei Fehlern
./scripts/run-tests.sh 42   # Tests; bei Fehlern Kommentar in Issue #42
```

### Neuen Test erstellen
1. Datei `tests/NN_MeinFeatureTest.php` anlegen (NN = nächste freie Nummer)
2. Klasse `MeinFeatureTest extends TestCase`
3. `protected string $testName = 'Test NN: Beschreibung';`
4. Methode `public function run(): void` mit Assertions implementieren
5. Transaktions-Isolation ist automatisch (setUp/tearDown in TestCase)

### Assertion-Methoden
```php
$this->assert(bool, 'Beschreibung');
$this->assertEquals($erwartet, $ist, 'Beschreibung');
$this->assertGreaterThan($min, $wert, 'Beschreibung');
$this->assertNotEmpty($wert, 'Beschreibung');
```

## Dokumentation aktuell halten

| Datei | Wann aktualisieren |
|---|---|
| `Changes.md` | Bei jedem Feature, Bugfix oder strukturellen Änderung (nicht bei reinen Test- oder Doku-Commits) |
| `README.md` | Wenn sich der Funktionsumfang oder der Tech Stack grundlegend ändert |
| `docs/funktionen.md` | Wenn ein neues Feature hinzukommt oder ein bestehendes wesentlich geändert wird |
| `docs/berechnungslogik.md` | Bei jeder Änderung an `EuerCalculator.php` oder `UstvaCalculator.php` (Zuordnungsregeln, neue Kennzahlen, geänderte Bedingungen) |
| `docs/anlagevermögen.md` | Bei Änderungen am Anlagevermögens-Workflow oder den Asset-Modellen |

## Datenbankmigrationen

Schemaänderungen (neue Spalten, Tabellen, Kontenanpassungen) kommen **ausschließlich** als nummerierte Migrations-Datei in `migrations/`:

- Schema: `NNN_kurze_beschreibung.sql` (NNN = nächste freie dreistellige Nummer, z.B. `011_...`)
- Migrationen werden **nie manuell** eingespielt – `scripts/migrate.php` erledigt das automatisch beim Container-Start
- Jede Migration muss idempotent sein oder mit `IF NOT EXISTS` / `ON DUPLICATE KEY` abgesichert werden

```bash
# Nächste freie Nummer ermitteln:
ls migrations/ | tail -1

# Migration manuell testen (ohne Neustart):
docker compose exec web php scripts/migrate.php
```

## Geplante Aufgaben (Cron)

Alle planmäßigen Aufgaben (z.B. Ideenagent, Automatisierungen) laufen lokal über die System-Crontab des Nutzers. Für außerplanmäßige Ausführung das jeweilige Skript direkt aufrufen:

```bash
crontab -l                                              # alle geplanten Jobs anzeigen
/home/fds/projects/Steuerkram/.claude/ideenagent-run.sh # Ideenagent manuell starten
/home/fds/projects/Steuerkram/.claude/automate-run.sh   # Automatisierung manuell starten
```

Remote Triggers (claude.ai) oder Claude Code Cron-Jobs werden **nicht** verwendet.

## Commits
```
Fix #NR: Kurze Beschreibung der Änderung
```
Keine Co-Authored-By-Zeile. Keine langen Commit-Messages.