---
phase: 04-schema-docs
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- 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
- DOCS/DB_SCHEMA.md
- .paul/codebase/CONCERNS.md
autonomous: true
---
## Goal
Zaadnotuj 5 migracji `ensure_*` jako migracje kompensujące — dodaj nagłówki SQL wyjaśniające co każda kompensuje i dlaczego powstała. Zaktualizuj DOCS/DB_SCHEMA.md o dedykowaną sekcję z tabelą migracji kompensujących.
## 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`
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
## 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
## AC-1: Każda migracja ensure_* ma nagłówek SQL wyjaśniający cel
```gherkin
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
```gherkin
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
```gherkin
Given .paul/codebase/CONCERNS.md
When deweloper przegląda listę concerns
Then sekcja "[MEDIUM] 5 "ensure_*" Migrations Indicate Schema Drift" nie istnieje
```
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.
Odczytaj każdy z 5 plików SQL i sprawdź czy zaczyna się od bloku
-- COMPENSATING MIGRATION z polami Kompensuje, Powód, Status.
AC-1 satisfied: wszystkie 5 plików SQL ma nagłówki COMPENSATING MIGRATION
Task 2: Dodaj sekcję Compensating Migrations do DOCS/DB_SCHEMA.md i wyczyść concern
DOCS/DB_SCHEMA.md, .paul/codebase/CONCERNS.md
**DOCS/DB_SCHEMA.md:**
Dodaj nową sekcję tuż po bloku `## Status` (przed tabelami schematu):
```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.
1. Sprawdź DOCS/DB_SCHEMA.md — sekcja `## Compensating Migrations` istnieje
z tabelą 5 wierszy.
2. Sprawdź CONCERNS.md — fraza "ensure_*" nie pojawia się w nagłówkach sekcji.
AC-2 i AC-3 satisfied: dokumentacja zaktualizowana, concern usunięty
## 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
Przed zgłoszeniem planu jako zakończonego:
- [ ] Każdy z 5 plików SQL zaczyna się od bloku -- COMPENSATING MIGRATION
- [ ] Wszystkie pola (Kompensuje, Powód, Status) są wypełnione w każdym nagłówku
- [ ] DOCS/DB_SCHEMA.md zawiera sekcję ## Compensating Migrations z tabelą 5 wierszy
- [ ] CONCERNS.md nie zawiera sekcji o ensure_* migration schema drift
- [ ] Żadna logika SQL nie została zmieniona (tylko komentarze dodane na górze)
- 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)