fs
2e73cb98b4
Existing systems used to have no automatic mechanism for the db/updates/*.sql idempotent updates after `git pull` — devs had to remember which files were already applied and run new ones manually with `mariadb < ...`. Mirror module:migrate to fix this: - New `bin/console db:migrate` walks db/updates/*.sql in alphabetical order, skipping anything already recorded in the new core_migrations tracking table. Each file runs in its own transaction; failure rolls back so the file is retried on the next run. - New `db:migrate --status` lists applied vs. pending files without running anything. Useful for ops debugging "schema seems stale" symptoms. - module:sync now runs db:migrate as its first step, so the standard post-pull command stays a single invocation. README's 3-step setup is unchanged — module:sync now also covers core schema updates. CoreMigrationRepository owns its own mysqli connection (using the same DB credentials as MintyPHP\DB) and runs raw `$mysqli->query()` instead of going through DB::query's prepared statement path — MariaDB rejects some DDL (e.g. ALTER TABLE … ADD CONSTRAINT CHECK) in the prepared protocol, which the existing 18 db/updates files trip on. ModuleMigrationRepository is left untouched (no module migration uses such DDL today and changing the vendor pattern is out of scope). End-to-end verified: against an existing DB the first run applies all 19 idempotent files as no-ops and records them, second run reports "all updates already applied". Against a freshly init'd DB the same thing happens — no double work, no surprises. All encrypted seed secrets keep decrypting because APP_CRYPTO_KEY is unchanged. Tests: tests/Console/CoreCommandsTest covers success/failure/status output shapes against a FakeModuleRunner (mirror of the existing ModuleCommandsTest pattern). 5 stale baseline entries in phpstan-baseline removed (covered by the new @api annotation on the test fixture class). Docs: CLAUDE.md and docs/reference-cli-commands.md document the new command + --status flag; docs/howto-fehlerbehebung.md gains a "schema seems stale after git pull" section pointing at db:migrate --status. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
120 lines
3.0 KiB
Markdown
120 lines
3.0 KiB
Markdown
# Fehlerbehebung
|
|
|
|
Letzte Aktualisierung: 2026-04-29
|
|
|
|
## Schema scheint veraltet nach `git pull`
|
|
|
|
### Symptom
|
|
|
|
Nach einem Pull schlagen Queries fehl, weil eine Spalte/Tabelle fehlt — oder der Doctor meldet inkonsistentes Schema.
|
|
|
|
### Lösung
|
|
|
|
```bash
|
|
docker compose exec php php bin/console db:migrate --status # zeigt was fehlt
|
|
docker compose exec php php bin/console module:sync # wendet alles an (db:migrate + module:migrate + ...)
|
|
```
|
|
|
|
`db:migrate` wendet idempotente Updates aus `db/updates/*.sql` an und trackt sie in `core_migrations`. Auch nach manuellem `mariadb < db/updates/...sql` sicher: jeder Lauf ist idempotent.
|
|
|
|
## App reagiert nicht wie erwartet
|
|
|
|
### Symptom
|
|
|
|
UI zeigt alte Daten/Assets oder Verhalten wirkt stale.
|
|
|
|
### Lösung
|
|
|
|
```bash
|
|
docker compose restart php nginx
|
|
```
|
|
|
|
## Erstdiagnose mit Doctor
|
|
|
|
### Symptom
|
|
|
|
Unklar, ob das Problem aus ENV, DB, Storage, RBAC oder Scheduler kommt.
|
|
|
|
### Lösung
|
|
|
|
```bash
|
|
docker compose exec php php bin/console doctor
|
|
```
|
|
|
|
Bei `FAIL` zuerst diese Punkte beheben, danach erneut ausführen.
|
|
|
|
## Login/API verhalten sich unerwartet
|
|
|
|
### Symptom
|
|
|
|
401/403 bei API trotz gültigem Token.
|
|
|
|
### Checks
|
|
|
|
1. Für geschützte Endpunkte Authorization Header korrekt gesetzt (`Bearer <selector:secret>`)
|
|
2. Ausnahme: `/api/v1/auth/login` ist public und benötigt keinen Bearer-Header
|
|
3. Token nicht revoked/abgelaufen
|
|
4. Token hat erforderliche Permission
|
|
5. Bei tenant-scoped Token: Zugriff nur auf passende Tenant-Ressourcen
|
|
|
|
## Migration oder Schema-Probleme
|
|
|
|
### Symptom
|
|
|
|
Neue Felder/Features fehlen lokal.
|
|
|
|
### Lösung
|
|
|
|
1. Aktuelles Schema in `db/init/init.sql` prüfen
|
|
2. Für Bestandsumgebung idempotentes SQL-Update ausführen
|
|
3. Danach Container neu starten:
|
|
|
|
```bash
|
|
docker compose restart php
|
|
```
|
|
|
|
### Hinweis (Hard Cut 2026-03-14)
|
|
|
|
Das Update `db/updates/2026-03-14-user-bookmarks.sql` entfernt `user_saved_filters` bewusst ohne Migration nach `user_bookmarks`.
|
|
Zusätzlich wurde der alte Bookmark-Icon-Ansatz pro Eintrag entfernt: Icons gelten nur noch auf Gruppenebene (`user_bookmark_groups.icon`), bestehende Bookmark-Icons werden nicht übernommen.
|
|
Wenn gespeicherte Filter noch benötigt werden, vor dem Update ein DB-Backup erstellen.
|
|
|
|
## i18n Fehler
|
|
|
|
### Symptom
|
|
|
|
Fehlende Translation-Keys oder Mixed-Language UI.
|
|
|
|
### Lösung
|
|
|
|
```bash
|
|
docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php tests/I18n/TranslationKeysTest.php
|
|
```
|
|
|
|
## PHPStan/Tests schlagen plötzlich fehl
|
|
|
|
### Symptom
|
|
|
|
Fehler nach Refactor, obwohl Seite lädt.
|
|
|
|
### Lösung
|
|
|
|
```bash
|
|
docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
|
|
docker compose exec php vendor/bin/phpunit --bootstrap vendor/autoload.php
|
|
```
|
|
|
|
Dann gezielt betroffene Datei/Service prüfen.
|
|
|
|
## Swagger UI lädt ungestylt oder inkonsistent
|
|
|
|
### Symptom
|
|
|
|
API docs sehen nicht nach App-Theme aus.
|
|
|
|
### Lösung
|
|
|
|
1. Prüfen, dass `Buffer::set('style_groups', json_encode(['api-docs']))` gesetzt ist
|
|
2. Prüfen, dass `css/vendor-overrides/swagger-ui.css` über `config/assets.php` eingebunden ist
|
|
3. Hard-Reload im Browser
|