feat(04-schema-docs): annotate ensure_* compensating migrations and update DB_SCHEMA.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-13 10:15:58 +01:00
parent 9a0dbe050b
commit 2d4b52adfc
15 changed files with 735 additions and 64 deletions
--- a/.paul/phases/04-schema-docs/04-01-PLAN.md
+++ b/.paul/phases/04-schema-docs/04-01-PLAN.md
@@ -0,0 +1,221 @@
+---
+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>
--- a/.paul/phases/04-schema-docs/04-01-SUMMARY.md
+++ b/.paul/phases/04-schema-docs/04-01-SUMMARY.md
@@ -0,0 +1,112 @@
+---
+phase: 04-schema-docs
+plan: 01
+subsystem: database
+tags: [migrations, schema, documentation]
+
+requires: []
+provides:
+  - Adnotowane migracje kompensujące ensure_* (5 plików SQL)
+  - Sekcja Compensating Migrations w DOCS/DB_SCHEMA.md
+  - Usunięty concern schema drift z CONCERNS.md
+affects: []
+
+tech-stack:
+  added: []
+  patterns:
+    - "Compensating migration pattern: nagłówek -- COMPENSATING MIGRATION z polami Kompensuje/Powód/Status"
+
+key-files:
+  created: []
+  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
+
+key-decisions:
+  - "000042 nie ma poprzednika — prefiks ensure_ użyty defensywnie od początku"
+
+patterns-established:
+  - "Compensating migration: nagłówek SQL z Kompensuje/Powód/Status jako standard dokumentacji"
+
+duration: ~10min
+started: 2026-03-13T00:00:00Z
+completed: 2026-03-13T00:00:00Z
+---
+
+# Phase 4 Plan 01: Schema Docs Summary
+
+**5 migracji ensure_* zaadnotowanych jako compensating migrations; sekcja w DB_SCHEMA.md dodana; concern schema drift zamknięty.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~10 min |
+| Started | 2026-03-13 |
+| Completed | 2026-03-13 |
+| Tasks | 2 completed |
+| Files modified | 7 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Każda migracja ensure_* ma nagłówek SQL | Pass | Bloki `-- COMPENSATING MIGRATION` z polami Kompensuje/Powód/Status we wszystkich 5 plikach |
+| AC-2: DB_SCHEMA.md zawiera sekcję compensating migrations | Pass | Sekcja `## Compensating Migrations` z tabelą 5 wierszy dodana na początku pliku |
+| AC-3: Concern usunięty z CONCERNS.md | Pass | Sekcja `[MEDIUM] 5 "ensure_*" Migrations Indicate Schema Drift` usunięta |
+
+## Accomplishments
+
+- Zaadnotowano wszystkie 5 migracji `ensure_*` — każda ma nagłówek wyjaśniający którą oryginalną migrację kompensuje i dlaczego
+- Zidentyfikowano i udokumentowano kluczową różnicę: 000042 nie ma poprzednika (defensywny ensure_ od początku), pozostałe 4 kompensują konkretne nie-idempotentne oryginały
+- DOCS/DB_SCHEMA.md ma teraz trwałą sekcję `## Compensating Migrations` jako tabelę referencyjną
+
+## Task Commits
+
+Brak atomicznych commitów w tej sesji — zmiany do zacommitowania po UNIFY.
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `database/migrations/20260308_000038_ensure_order_status_mappings_table.sql` | Modified | Nagłówek COMPENSATING MIGRATION (kompensuje 000020) |
+| `database/migrations/20260308_000039_ensure_integrations_fetch_columns.sql` | Modified | Nagłówek COMPENSATING MIGRATION (kompensuje 000017, nie-idempotentny ALTER) |
+| `database/migrations/20260308_000040_ensure_shoppro_orders_import_schedule.sql` | Modified | Nagłówek COMPENSATING MIGRATION (kompensuje cron seed w 000018, koryguje interval) |
+| `database/migrations/20260308_000041_ensure_shoppro_status_sync_schedule_and_direction.sql` | Modified | Nagłówek COMPENSATING MIGRATION (kompensuje 000021, nie-idempotentny ALTER + interval) |
+| `database/migrations/20260308_000042_ensure_shoppro_payment_sync_schedule_and_columns.sql` | Modified | Nagłówek COMPENSATING MIGRATION (brak poprzednika — defensywny ensure_) |
+| `DOCS/DB_SCHEMA.md` | Modified | Sekcja `## Compensating Migrations` z tabelą 5 wierszy |
+| `.paul/codebase/CONCERNS.md` | Modified | Usunięty concern `[MEDIUM] 5 "ensure_*" Migrations Indicate Schema Drift` |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| 000042 zakwalifikowana jako "brak poprzednika" | Żadna wcześniejsza migracja nie definiuje payment_sync_status_codes_json ani shoppro_payment_status_sync | Dokładniejsza adnotacja niż ogólne "schema drift" |
+
+## Deviations from Plan
+
+None — plan wykonany dokładnie według specyfikacji.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+**Ready:**
+- Migracje compensating są w pełni udokumentowane — nowi deweloperzy rozumieją historię schematu
+- CONCERNS.md zmniejszony o jeden wpis — lista aktywna
+
+**Concerns:**
+- None
+
+**Blockers:**
+- None
+
+---
+*Phase: 04-schema-docs, Plan: 01*
+*Completed: 2026-03-13*