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>
3.0 KiB
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
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
docker compose restart php nginx
Erstdiagnose mit Doctor
Symptom
Unklar, ob das Problem aus ENV, DB, Storage, RBAC oder Scheduler kommt.
Lösung
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
- Für geschützte Endpunkte Authorization Header korrekt gesetzt (
Bearer <selector:secret>) - Ausnahme:
/api/v1/auth/loginist public und benötigt keinen Bearer-Header - Token nicht revoked/abgelaufen
- Token hat erforderliche Permission
- Bei tenant-scoped Token: Zugriff nur auf passende Tenant-Ressourcen
Migration oder Schema-Probleme
Symptom
Neue Felder/Features fehlen lokal.
Lösung
- Aktuelles Schema in
db/init/init.sqlprüfen - Für Bestandsumgebung idempotentes SQL-Update ausführen
- Danach Container neu starten:
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
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
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
- Prüfen, dass
Buffer::set('style_groups', json_encode(['api-docs']))gesetzt ist - Prüfen, dass
css/vendor-overrides/swagger-ui.cssüberconfig/assets.phpeingebunden ist - Hard-Reload im Browser