10 KiB
10 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous
| phase | plan | type | wave | depends_on | files_modified | autonomous | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 04-schema-docs | 01 | execute | 1 |
|
true |
Purpose
Eliminuje dwuznaczność schematu: aktualnie nie wiadomo z samych plików SQL dlaczego istnieją migracje ensure_* ani które wcześniejsze migracje zawodzą. Po adnotacji deweloper czytający historię migracji natychmiast rozumie kontekst.
Output
- 5 plików SQL z komentarzami nagłówkowymi
COMPENSATING MIGRATION - DOCS/DB_SCHEMA.md z sekcją
## Compensating Migrations(tabela 5 wpisów) - .paul/codebase/CONCERNS.md z usuniętym concern
[MEDIUM] 5 "ensure_*" Migrations Indicate Schema Drift
Source Files
@database/migrations/20260308_000038_ensure_order_status_mappings_table.sql @database/migrations/20260308_000039_ensure_integrations_fetch_columns.sql @database/migrations/20260308_000040_ensure_shoppro_orders_import_schedule.sql @database/migrations/20260308_000041_ensure_shoppro_status_sync_schedule_and_direction.sql @database/migrations/20260308_000042_ensure_shoppro_payment_sync_schedule_and_columns.sql @database/migrations/20260302_000017_add_shoppro_orders_fetch_settings_to_integrations.sql @database/migrations/20260302_000018_create_orders_tables_and_schedule.sql @database/migrations/20260302_000020_create_order_status_mappings_table.sql @database/migrations/20260302_000021_add_order_status_sync_direction_and_schedule.sql @DOCS/DB_SCHEMA.md @.paul/codebase/CONCERNS.md
<acceptance_criteria>
AC-1: Każda migracja ensure_* ma nagłówek SQL wyjaśniający cel
Given plik SQL migracji ensure_* (jeden z 5)
When deweloper otwiera plik
Then widzi blok komentarzy nagłówkowych zawierający:
- "COMPENSATING MIGRATION" jako tytuł
- informację która oryginalna migracja jest kompensowana
- powód powstania (co było nie-idempotentne / jakie środowisko)
- aktualny status środowiska (środowisko zsynchronizowane po 2026-03-08)
AC-2: DOCS/DB_SCHEMA.md zawiera sekcję migracji kompensujących
Given plik DOCS/DB_SCHEMA.md
When deweloper szuka informacji o ensure_* migracjach
Then na początku pliku (w sekcji Status lub jako osobna sekcja ## Compensating Migrations)
widzi tabelę z 5 wierszami: plik | kompensuje | powód | status
AC-3: Concern usunięty z CONCERNS.md
Given .paul/codebase/CONCERNS.md
When deweloper przegląda listę concerns
Then sekcja "[MEDIUM] 5 "ensure_*" Migrations Indicate Schema Drift" nie istnieje
</acceptance_criteria>
Task 1: Dodaj nagłówki COMPENSATING MIGRATION do 5 plików SQL database/migrations/20260308_000038_ensure_order_status_mappings_table.sql, database/migrations/20260308_000039_ensure_integrations_fetch_columns.sql, database/migrations/20260308_000040_ensure_shoppro_orders_import_schedule.sql, database/migrations/20260308_000041_ensure_shoppro_status_sync_schedule_and_direction.sql, database/migrations/20260308_000042_ensure_shoppro_payment_sync_schedule_and_columns.sql Na początku każdego pliku SQL dodaj blok komentarzy według poniższego wzorca:```sql
-- =============================================================
-- COMPENSATING MIGRATION
-- Kompensuje: {nazwa pliku oryginalnej migracji}
-- Powód: {co było nie-idempotentne lub jakie środowisko zawiodło}
-- Status: Środowisko zsynchronizowane po 2026-03-08. Migracja
-- idempotentna — bezpieczna do ponownego uruchomienia.
-- =============================================================
```
Dla każdego pliku wypełnij pola Kompensuje / Powód:
**000038_ensure_order_status_mappings_table.sql**
- Kompensuje: 20260302_000020_create_order_status_mappings_table.sql
- Powód: Oryginalna migracja 000020 zawiera identyczne CREATE TABLE IF NOT EXISTS,
ale nie dotarła do środowiska produkcyjnego. Migracja 000038 jest
bezpiecznym powtórzeniem — idempotentna dzięki IF NOT EXISTS.
**000039_ensure_integrations_fetch_columns.sql**
- Kompensuje: 20260302_000017_add_shoppro_orders_fetch_settings_to_integrations.sql
- Powód: Oryginalna migracja 000017 używa prostego ALTER TABLE bez sprawdzenia
istnienia kolumn (nie-idempotentna). Na środowisku, gdzie kolumny
orders_fetch_enabled i orders_fetch_start_date już istniały, 000017 zawiodła.
Migracja 000039 dodaje kolumny warunkowo przez information_schema.
**000040_ensure_shoppro_orders_import_schedule.sql**
- Kompensuje: 20260302_000018_create_orders_tables_and_schedule.sql (cron seed)
- Powód: Oryginalna migracja 000018 seeda shoppro_orders_import z interval=60s
i ON DUPLICATE KEY UPDATE nadpisującym wartości. Migracja 000040 koryguje
interval na 300s i używa IFNULL (nie nadpisuje istniejącego rekordu).
Dotyczy środowisk, gdzie 000018 nie uruchomiła się lub ustawiła zły interval.
**000041_ensure_shoppro_status_sync_schedule_and_direction.sql**
- Kompensuje: 20260302_000021_add_order_status_sync_direction_and_schedule.sql
- Powód: Oryginalna migracja 000021 używa prostego ALTER TABLE (nie-idempotentna)
oraz seeda shoppro_order_status_sync z interval=3600s z nadpisywaniem.
Migracja 000041 dodaje kolumnę warunkowo + koryguje interval na 900s z IFNULL.
**000042_ensure_shoppro_payment_sync_schedule_and_columns.sql**
- Kompensuje: brak ścisłego odpowiednika (pierwsza migracja dla payment sync)
- Powód: Kolumna payment_sync_status_codes_json i job shoppro_payment_status_sync
nie miały wcześniejszej migracji. Prefiks ensure_ zastosowano defensywnie
na wypadek ręcznego nakładania schematu na środowiskach testowych przed
sformalizowaniem migracji.
Nie zmieniaj żadnej logiki SQL — tylko dodaj komentarze na górze każdego pliku.
```markdown
## Compensating Migrations
Migracje z prefiksem `ensure_` to migracje kompensujące — zostały dodane
2026-03-08 aby naprawić rozbieżności schematu między środowiskami.
Środowisko jest zsynchronizowane od 2026-03-08. Migracje są idempotentne.
| Plik migracji | Kompensuje | Powód |
|---------------|------------|-------|
| 000038_ensure_order_status_mappings_table | 000020_create_order_status_mappings_table | Tabela nie dotarła do env produkcyjnego |
| 000039_ensure_integrations_fetch_columns | 000017_add_shoppro_orders_fetch_settings | ALTER TABLE w 000017 nie-idempotentny; kolumny już istniały |
| 000040_ensure_shoppro_orders_import_schedule | 000018_create_orders_tables_and_schedule (cron seed) | Koryguje interval z 60s na 300s; używa IFNULL zamiast nadpisywania |
| 000041_ensure_shoppro_status_sync_schedule_and_direction | 000021_add_order_status_sync_direction_and_schedule | ALTER TABLE nie-idempotentny; koryguje interval z 3600s na 900s |
| 000042_ensure_shoppro_payment_sync_schedule_and_columns | brak (pierwsza migracja payment sync) | Prefiks ensure_ użyty defensywnie — brak wcześniejszej migracji dla payment sync |
```
**CONCERNS.md:**
Usuń całą sekcję `### [MEDIUM] 5 "ensure_*" Migrations Indicate Schema Drift`
(od linii z tym nagłówkiem do pustej linii przed kolejnym `---` lub sekcją).
Nie modyfikuj żadnej innej sekcji w CONCERNS.md.
DO NOT CHANGE
- Logika SQL w migracjach ensure_* (tylko komentarze na górze)
- Oryginalne migracje 000017, 000018, 000020, 000021 (nie modyfikuj istniejących migracji)
- Pozostałe sekcje CONCERNS.md (tech debt, security, performance, architectural, itp.)
- Żadne pliki PHP ani widoki
SCOPE LIMITS
- Nie dodawaj nowych migracji SQL
- Nie zmieniaj kolejności ani numeracji żadnych plików migracji
- Nie naprawiaj innych concerns z CONCERNS.md w tym planie
<success_criteria>
- Wszystkie zadania ukończone
- Wszystkie 5 plików SQL zaadnotowanych
- DOCS/DB_SCHEMA.md zaktualizowany
- Concern usunięty z CONCERNS.md
- Brak błędów składniowych SQL (komentarze -- są zawsze bezpieczne) </success_criteria>