---
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
---

<objective>
## 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`
</objective>

<context>
## 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
</context>

<acceptance_criteria>

## 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
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Dodaj nagłówki COMPENSATING MIGRATION do 5 plików SQL</name>
  <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
  </files>
  <action>
    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.
  </action>
  <verify>
    Odczytaj każdy z 5 plików SQL i sprawdź czy zaczyna się od bloku
    -- COMPENSATING MIGRATION z polami Kompensuje, Powód, Status.
  </verify>
  <done>AC-1 satisfied: wszystkie 5 plików SQL ma nagłówki COMPENSATING MIGRATION</done>
</task>

<task type="auto">
  <name>Task 2: Dodaj sekcję Compensating Migrations do DOCS/DB_SCHEMA.md i wyczyść concern</name>
  <files>DOCS/DB_SCHEMA.md, .paul/codebase/CONCERNS.md</files>
  <action>
    **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.
  </action>
  <verify>
    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.
  </verify>
  <done>AC-2 i AC-3 satisfied: dokumentacja zaktualizowana, concern usunięty</done>
</task>

</tasks>

<boundaries>

## 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

</boundaries>

<verification>
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)
</verification>

<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>

<output>
Po zakończeniu utwórz `.paul/phases/04-schema-docs/04-01-SUMMARY.md`
</output>
