Project-Pro/orderPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Jacek Pyziak
2026-03-13 10:15:58 +01:00
parent 9a0dbe050b
commit 2d4b52adfc
15 changed files with 735 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
.paul/phases/04-schema-docs/04-01-PLAN.md Normal file
View File

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