222 lines
10 KiB
Markdown
222 lines
10 KiB
Markdown
---
|
|
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>
|