# DB Schema

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

## Status
- Projekt po resecie do trybu `users-only`.
- Aktualizuj ten plik przy kazdej zmianie migracji/schematu.
- 2026-03-02: Przywrocenie UI `Ustawienia > Baza danych` nie wprowadza zmian w schemacie.
- 2026-03-02: Dodano tabele statusow (grupy + statusy) dla nowej zakladki `Ustawienia > Statusy`.
- 2026-03-02: Przygotowano draft generycznego schematu zamowien (bez aktywnej migracji) w `database/drafts/20260302_orders_schema_v1.sql`.
- 2026-03-03: Wdrozono generyczne tabele zamowien na bazie docelowej skryptem `bin/deploy_and_seed_orders.php` (bez migratora SQL).
- 2026-03-03: Dodano UI `Zamowienia > Lista zamowien` - bez zmian schematu (wykorzystuje istniejace tabele domeny zamowien).
- 2026-03-03: Dodano UI `Zamowienia > Szczegoly zamowienia` (`GET /orders/{id}`) - bez zmian schematu.
- 2026-03-04: Dodano tabele `allegro_integration_settings` pod konfiguracje OAuth2 Allegro i tokeny dostepowe.
- 2026-03-04: Dodano harmonogram crona `allegro_token_refresh` (co 3600s, priorytet 10, max 3 proby).
- 2026-03-04: Dodano reczny import pojedynczego zamowienia Allegro - bez zmian schematu (wykorzystuje istniejace tabele domeny zamowien).
- 2026-03-04: Dodano tabele `allegro_order_status_mappings` do mapowania statusow Allegro na statusy orderPRO.
- 2026-03-04: Zmieniono `allegro_order_status_mappings.orderpro_status_code` na nullable, aby zapisac statusy pobrane z Allegro przed przypisaniem mapowania.
- 2026-03-04: Dodano rozwiazywanie miniatur pozycji zamowien z mapowania produktu orderPRO (`product_channel_map` + `product_images`) - bez zmian schematu.
- 2026-03-04: Dodano diagnostyke importu miniatur Allegro (alerty przyczyn brakow) - bez zmian schematu.
- 2026-03-04: Dodano harmonogram `allegro_orders_import` (auto-import zamowien Allegro) oraz rozszerzono `integration_order_sync_state` o kolumny kursora sync (`last_synced_order_updated_at`, `last_synced_source_order_id`, `last_success_at`) - migracja `20260304_000027_add_allegro_orders_import_schedule.sql`.
- 2026-03-04: Dodano zakladke `Ustawienia` w integracji Allegro z konfiguracja interwalu importu zamowien; zapis aktualizuje istniejacy rekord `cron_schedules` (`job_type=allegro_orders_import`) - bez zmian schematu.
- 2026-03-04: Rozszerzono zakladke `Ustawienia` integracji Allegro o kierunek synchronizacji statusow i interwal synchronizacji statusow; zapis do `app_settings` (`allegro_status_sync_direction`, `allegro_status_sync_interval_minutes`) - bez zmian schematu.
- 2026-03-04: Dodano harmonogram `allegro_status_sync` (cron synchronizacji statusow) + defaulty `app_settings` dla kierunku i interwalu status sync - migracja `20260304_000028_add_allegro_status_sync_schedule.sql`.
- 2026-03-04: Import Allegro mapuje forme wysylki do `orders.external_carrier_id` i `orders.external_carrier_account_id` - bez zmian schematu.
- 2026-03-05: Dodano tabele `order_activity_log` — uniwersalny log aktywnosci zamowien (zmiany statusow, platnosci, przesylki, faktury, wiadomosci itp.).
- 2026-03-05: Dodano tabele `apaczka_integration_settings` pod konfiguracje klucza API Apaczka.
- 2026-03-05: Dodano tabele `inpost_integration_settings` pod konfiguracje integracji InPost ShipX.
- 2026-03-06: Dodano kolumne `carrier` do tabeli `allegro_delivery_method_mappings` (default 'allegro') - umozliwia mapowanie na roznych przewoznikow (Allegro, InPost).
- 2026-03-06: Wdrozono migracje `20260302_000019_add_internal_order_number_to_orders.sql` - kolumna `internal_order_number` VARCHAR(11) UNIQUE w tabeli `orders`, format `OPXXXXXXXXX` (np. `OP000000001`); backfill istniejacych rekordow; UI: lista i szczegoly zamowien wyswietlaja numer wewnetrzny jako glowny identyfikator.
- 2026-03-04: Poprawiono prezentacje daty zamowienia na liscie (`fallback ordered_at -> source_created_at -> source_updated_at -> fetched_at`) - bez zmian schematu.
- 2026-03-08: Rozpoczeto ujednolicanie integracji - migracja `20260308_000037_unify_integrations_base_links.sql`:
  - dodano `integration_id` do tabel `allegro_integration_settings`, `apaczka_integration_settings`, `inpost_integration_settings`,
  - dodano FK/UNIQUE 1:1 z tabela `integrations`,
  - dodano/uzupelniono rekordy bazowe providerow (`allegro`, `apaczka`, `inpost`) w `integrations`.
- 2026-03-08: Dodano UI i endpointy konfiguracji `shopPRO` (wieloinstancyjnie) w oparciu o istniejaca tabele `integrations` (`type=shoppro`) - bez zmian schematu.
- 2026-03-08: Dodano mapowanie statusow dla `shopPRO` (zakladka `Statusy`) z zapisem do istniejacej tabeli `order_status_mappings` per `integration_id` - bez zmian schematu.
- 2026-03-08: Dodano migracje naprawcza `20260308_000038_ensure_order_status_mappings_table.sql` (uzupelnia brakujaca tabele `order_status_mappings` w srodowiskach z niepelna historia migracji).
- 2026-03-08: Dodano migracje naprawcza `20260308_000039_ensure_integrations_fetch_columns.sql` (uzupelnia brakujace kolumny `orders_fetch_enabled` i `orders_fetch_start_date` w `integrations`).
- 2026-03-08: Dodano migracje `20260308_000040_ensure_shoppro_orders_import_schedule.sql` (seed/naprawa harmonogramu `cron_schedules` dla joba `shoppro_orders_import`) - bez zmian schematu tabel.
- 2026-03-08: Dodano migracje `20260308_000041_ensure_shoppro_status_sync_schedule_and_direction.sql` (seed/naprawa harmonogramu `cron_schedules` dla joba `shoppro_order_status_sync` oraz uzupelnienie kolumny `integrations.order_status_sync_direction` w srodowiskach niezgodnych).
- 2026-03-08: Dodano migracje `20260308_000042_ensure_shoppro_payment_sync_schedule_and_columns.sql`:
  - uzupelnienie kolumny `integrations.payment_sync_status_codes_json` (JSON) dla konfiguracji statusow objetych kontrola platnosci,
  - seed/naprawa harmonogramu `cron_schedules` dla joba `shoppro_payment_status_sync` (domyslnie 600s, priorytet 105).
- 2026-03-08: Dodano migracje `20260308_000043_create_shoppro_delivery_method_mappings_table.sql`:
  - nowa tabela `shoppro_delivery_method_mappings` (mapowanie form dostawy per `integration_id`),
  - tabela przechowuje mapowanie formy shopPRO na usluge Allegro WZA/InPost (`allegro_delivery_method_id`, `allegro_credentials_id`, `allegro_carrier_id`, `allegro_service_name`, `carrier`).
- 2026-03-08: Poprawiono mapowanie importu zamowien shopPRO (kwoty i miniatury pozycji) - bez zmian schematu bazy.
- 2026-03-08: Poprawiono mapowanie danych wysylki shopPRO (paczkomat/punkt odbioru + kontakt klienta + koszt transportu) - bez zmian schematu bazy.
- 2026-03-08: Dodano migracje `20260308_000044_create_carrier_delivery_method_mappings_table.sql`:
  - nowa tabela `carrier_delivery_method_mappings` (wspolne mapowanie form dostawy dla roznych zrodel zamowien i providerow wysylek),
  - migracja backfilluje dane z `allegro_delivery_method_mappings` i `shoppro_delivery_method_mappings`.
- 2026-03-08: Dodano migracje `20260308_000045_extend_apaczka_credentials.sql`:
  - rozszerzenie `apaczka_integration_settings` o `app_id` i `app_secret_encrypted`,
  - migracja przenosi legacy sekret z `api_key_encrypted` do `app_secret_encrypted`.
- 2026-03-08: Poprawiono mapowanie danych faktury w imporcie shopPRO - bez zmian schematu:
  - `orders.is_invoice` jest wykrywany takze po polach firmowych (`firm_*`),
  - adres faktury jest zapisywany do istniejacej tabeli `order_addresses` (`address_type=invoice`, `company_name`, `company_tax_number`).
- 2026-03-08: Poprawiono diagnostyke tworzenia przesylek Apaczka - bez zmian schematu:
  - payload tworzenia przesylki przekazuje punkty odbioru/nadania (`receiver.point`, `sender.point`) z danych formularza,
  - komunikaty bledow tworzenia zawieraja rozszerzona diagnostyke parametrow wyceny.
- 2026-03-08: Poprawiono obsluge bledow etykiet Apaczka - bez zmian schematu:
  - przy odpowiedzi API `Label is not available for this order` rekord `shipment_packages` jest oznaczany statusem `error` i zachowuje tresc bledu.
- 2026-03-08: Poprawiono fallback danych odbiorcy dla przesylek punktowych Apaczka (Orlen/InPost) - bez zmian schematu:
  - brakujace dane adresowe odbiorcy sa uzupelniane na etapie budowania payloadu z danych zamowienia (`delivery`, `customer`) oraz metadanych punktu (`parcel_name`).
- 2026-03-08: Rozszerzono fallback adresu odbiorcy dla przesylek punktowych Apaczka - bez zmian schematu:
  - serwis probuje uzupelnic adres punktu przez API `points` po `receiver_point_id`,
  - przy dalszych brakach danych dla przesylki punktowej dopelniane jest minimum techniczne wymagane przez lokalna walidacje payloadu.
- 2026-03-08: Poprawiono przekazywanie punktow w payloadzie Apaczka (nadanie/odbior) - bez zmian schematu:
  - payload wysyla aliasy identyfikatora punktu (`point`, `foreign_address_id`, `point_id`) dla zgodnosci z wariantami API.
- 2026-03-08: Uzupelniono payload odbioru kurierem Apaczka (`pickup.date`, `pickup.hours_from`, `pickup.hours_to`) - bez zmian schematu.
- 2026-03-08: Dodano migracje `20260308_000046_extend_company_settings_contact_person.sql`:
  - rozszerzenie `company_settings` o `sender_contact_person` (osoba kontaktowa nadawcy),
  - wykorzystywane w payloadzie Apaczka jako `address.sender.contact_person`.
- 2026-03-08: Ujednolicono styl naglowkow sekcji UI (`section-title`) - bez zmian schematu bazy.
- 2026-03-14: Dodano migracje `20260314_000048_add_orders_performance_indexes.sql` — indeksy wydajnosciowe na tabeli `orders`: `source`, `external_status_id`, `ordered_at`, composite `(source, external_status_id)`.
- 2026-03-14: Dodano migracje `20260314_000049_add_cron_last_run_at_setting.sql` — seed klucza `cron_web_last_run_at` w `app_settings` (cron throttle przeniesiony z sesji do DB).
- 2026-03-14: Przemianowano migracje `20260301_000014_add_products_sku_format_setting.sql` na `20260301_000014b_add_products_sku_format_setting.sql` — deduplikacja numeru sekwencji (kolizja z `000014_create_product_integration_translations`).
- 2026-03-15: Dodano migracje `20260315_000050_create_receipt_configs_table.sql` — tabela konfiguracji paragonow (szablony numeracji, ustawienia imiennosci, zrodlo daty sprzedazy).
- 2026-03-15: Dodano migracje `20260315_000051_create_receipts_table.sql` — tabela wystawionych paragonow ze snapshotem danych (JSON seller/buyer/items), FK do orders i receipt_configs.
- 2026-03-15: Dodano migracje `20260315_000052_create_receipt_number_counters_table.sql` — liczniki numeracji paragonow per konfiguracja i okres (miesiac/rok).
- 2026-03-15: Dodano migracje `20260315_000053_extend_company_settings_extra_fields.sql` — rozszerzenie company_settings o bdo_number, regon, court_register, logo_path.
- 2026-03-15: Dodano migracje `20260315_000054_create_email_mailboxes_table.sql` — tabela skrzynek pocztowych SMTP (credentials szyfrowane IntegrationSecretCipher).
- 2026-03-15: Dodano migracje `20260315_000055_create_email_templates_table.sql` — tabela szablonow wiadomosci email z FK do email_mailboxes.
- 2026-03-15: Dodano migracje `20260315_000056_create_email_logs_table.sql` — tabela logow wyslanych wiadomosci z FK do email_templates, email_mailboxes i indeksami na order_id, status, sent_at.
- 2026-03-16: Dodano migracje `20260316_000001_add_attachment1_to_email_templates.sql` — kolumna attachment_1 VARCHAR(50) w email_templates (typ zalacznika, np. 'receipt').
- 2026-03-17: Nowa zaleznosc `phpmailer/phpmailer` v7.0.2. Modul `App\Modules\Email` — wysylka e-mail z zamowien, resolwer zmiennych, generowanie zalacznikow PDF. Tabela `email_logs` wykorzystywana do logowania wysylek (bez nowych migracji).
- 2026-03-28: Rozszerzono automatyzacje o akcje `update_order_status` (zmiana statusu zamowienia) - bez zmian schematu (wykorzystuje istniejace `order_statuses`, `orders`, `order_status_history`, `order_activity_log`).
- 2026-03-28: Hotfix Apaczka bledow niedostepnego dnia nadania (`Pickup not available for selected day` oraz `you can't place an order today`) - bez zmian schematu (retry `order_send` z automatycznym przesuwaniem `pickup.date` dla `pickup.type=COURIER`).
- 2026-03-28: Dodano publiczny endpoint triggera crona HTTPS (`/cron`) z tokenem `CRON_PUBLIC_TOKEN` - bez zmian schematu bazy.
- 2026-03-28: Dodano migracje `20260328_000072_create_automation_execution_logs_table.sql`:
  - nowa tabela `automation_execution_logs` (historia wykonan regul automatyzacji: co, kiedy, na jakim zamowieniu, wynik),
  - indeksy pod filtrowanie po czasie/zdarzeniu/statusie/regule/zamowieniu,
  - seed harmonogramu `cron_schedules` dla joba `automation_history_cleanup` (retencja historii starszej niz 30 dni).
- 2026-04-04: Hotfix trackingu Allegro Delivery (edge API) - rozszerzono mapowanie statusow EN i fallback keyword matching (`Parcel is awaiting pick-up`, `Parcel has been delivered`, itp.) w warstwie aplikacyjnej; bez zmian schematu bazy.

## Tabele

### `users`
- Uzytkownicy panelu.
- Klucz unikalny: `email`.

### `order_status_groups`
- Grupy statusow zamowien zarzadzane z UI.
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `name` (varchar 120),
  - `code` (varchar 64, UNIQUE),
  - `color_hex` (char 7, domyslnie `#64748b`),
  - `sort_order` (int, domyslnie `0`),
  - `is_active` (tinyint(1), domyslnie `1`),
  - `created_at`, `updated_at`.
- Indeksy:
  - `order_status_groups_code_unique` (UNIQUE: `code`),
  - `order_status_groups_sort_order_idx` (`sort_order`).

### `order_statuses`
- Statusy przypisane do grup statusow.
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `group_id` (FK -> `order_status_groups.id`),
  - `name` (varchar 120),
  - `code` (varchar 64, UNIQUE),
  - `sort_order` (int, domyslnie `0`),
  - `is_active` (tinyint(1), domyslnie `1`),
  - `created_at`, `updated_at`.
- Indeksy:
  - `order_statuses_code_unique` (UNIQUE: `code`),
  - `order_statuses_group_sort_idx` (`group_id`, `sort_order`, `id`).
- Klucze obce:
  - `order_statuses_group_fk`: `group_id` -> `order_status_groups.id` (`ON DELETE CASCADE`, `ON UPDATE CASCADE`).

### Domena zamowien (generyczna)
- Wdrozone tabele:
  - `orders`
  - `order_addresses`
  - `order_items`
  - `order_payments`
  - `order_shipments`
  - `order_documents`
  - `order_notes`
  - `order_status_history`
  - `order_tags_dict`
  - `order_tag_links`
  - `integration_order_sync_state`
- Charakterystyka:
  - schema neutralna wzgledem dostawcy API (pola `source_*`, `external_*`),
  - kolekcje zamowienia rozdzielone na osobne tabele 1:N,
  - `payload_json` dostepne dla diagnostyki/replay,
  - `personalization` (TEXT, nullable) w `order_items` — dane personalizacji produktu z shopPRO (custom_fields), przechowywane jako czysty tekst,
  - historia zmian statusow utrzymywana w `order_status_history`.

### `integration_order_sync_state`
- Kursor synchronizacji importu zamowien dla integracji (uzywany przez cron auto-importu Allegro i push statusow shopPRO).
- Kolumny:
  - `integration_id` (PK),
  - `last_synced_order_updated_at` (datetime, nullable) lub historycznie `last_synced_external_updated_at`,
  - `last_synced_source_order_id` (varchar, nullable) lub historycznie `last_synced_external_order_id`,
  - `last_run_at` (datetime),
  - `last_success_at` (datetime),
  - `last_status_pushed_at` (datetime, nullable) — kursor synchronizacji push statusow orderPRO -> shopPRO,
  - `last_error` (varchar 500),
  - `created_at`, `updated_at`.

### `order_status_mappings`
- Mapowanie statusow zamowien shopPRO na statusy orderPRO per instancja integracji.
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `integration_id` (int unsigned, FK -> `integrations.id`),
  - `shoppro_status_code` (varchar 64),
  - `shoppro_status_name` (varchar 128, nullable),
  - `orderpro_status_code` (varchar 64),
  - `created_at`, `updated_at`.
- Indeksy:
  - `order_status_mappings_integration_shoppro_unique` (UNIQUE: `integration_id`, `shoppro_status_code`),
  - `order_status_mappings_integration_idx` (`integration_id`),
  - `order_status_mappings_orderpro_idx` (`orderpro_status_code`).
- Klucze obce:
  - `order_status_mappings_integration_fk`: `integration_id` -> `integrations.id` (`ON DELETE CASCADE`, `ON UPDATE CASCADE`).

### `allegro_integration_settings`
- Konfiguracja OAuth i sync dla integracji Allegro per srodowisko (`sandbox|production`) zarzadzana z `Ustawienia > Integracje > Allegro`.
- Kolumny:
  - `id` (PK, tinyint unsigned),
  - `integration_id` (int unsigned, UNIQUE, FK -> `integrations.id`),
  - `environment` (varchar 16, `sandbox|production`),
  - `client_id` (varchar 128),
  - `client_secret_encrypted` (text),
  - `redirect_uri` (varchar 255),
  - `orders_fetch_enabled` (tinyint(1), domyslnie `0`),
  - `orders_fetch_start_date` (date),
  - `access_token_encrypted` (mediumtext),
  - `refresh_token_encrypted` (mediumtext),
  - `token_type` (varchar 32),
  - `token_scope` (varchar 255),
  - `token_expires_at` (datetime),
  - `connected_at` (datetime),
  - `created_at`, `updated_at`.
- Indeksy:
  - `allegro_integration_settings_environment_idx` (`environment`),
  - `allegro_integration_settings_token_expires_at_idx` (`token_expires_at`),
  - `allegro_integration_settings_integration_unique` (`integration_id`, UNIQUE).

### `allegro_order_status_mappings`
- Mapowanie kodow statusow Allegro na kody statusow orderPRO.
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `allegro_status_code` (varchar 64, UNIQUE),
  - `allegro_status_name` (varchar 120),
  - `orderpro_status_code` (varchar 64),
  - `created_at`, `updated_at`.
- Indeksy:
  - `allegro_order_status_mappings_code_unique` (UNIQUE: `allegro_status_code`),
  - `allegro_order_status_mappings_orderpro_code_idx` (`orderpro_status_code`).

### `order_payments`
- Platnosci zamowien (z importu API lub reczne).
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `order_id` (int unsigned, FK -> `orders.id`, CASCADE),
  - `source_payment_id` (varchar 64, nullable),
  - `external_payment_id` (varchar 64, nullable),
  - `payment_type_id` (varchar 64, NOT NULL) — typ: ONLINE, TRANSFER, CASH_ON_DELIVERY,
  - `payment_date` (datetime, nullable),
  - `amount` (decimal 12,2, nullable),
  - `currency` (char 3, nullable),
  - `comment` (varchar 255, nullable),
  - `payload_json` (json, nullable),
  - `created_at`, `updated_at`.
- Indeksy:
  - `order_payments_order_source_payment_unique` (UNIQUE: `order_id`, `source_payment_id`),
  - `order_payments_order_idx` (`order_id`),
  - `order_payments_date_idx` (`payment_date`).
- Migracja: `20260330_000073_create_order_payments_table.sql`

### `order_activity_log`
- Uniwersalny log aktywnosci zamowienia (zmiany statusow, platnosci, przesylki, faktury, wiadomosci itp.).
- Kolumny:
  - `id` (PK, bigint unsigned, AI),
  - `order_id` (FK -> `orders.id`, CASCADE),
  - `event_type` (varchar 32) — typ zdarzenia: `status_change`, `payment`, `invoice`, `shipment`, `message`, `document`, `import`, `note`,
  - `summary` (varchar 255) — czytelny opis zdarzenia,
  - `details_json` (json, nullable) — dodatkowe dane strukturalne,
  - `actor_type` (varchar 16, domyslnie `system`) — `system`, `user`, `import`, `api`, `sync`,
  - `actor_name` (varchar 128, nullable) — nazwa uzytkownika lub identyfikator systemu,
  - `created_at`.
- Indeksy:
  - `order_activity_log_order_created_idx` (`order_id`, `created_at`),
  - `order_activity_log_event_type_idx` (`event_type`).

### `integrations`
- Bazowa tabela wszystkich instancji integracji (model docelowy pod wielu providerow i wiele kont per provider).
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `type` (varchar 32, np. `allegro`, `apaczka`, `inpost`, `shoppro`),
  - `name` (varchar 128, unikalne w obrebie `type`),
  - `base_url` (varchar 255),
  - `api_key_encrypted` (text, nullable),
  - `timeout_seconds` (smallint unsigned),
  - `is_active` (tinyint(1)),
  - `orders_fetch_enabled` (tinyint(1)),
  - `orders_fetch_start_date` (date, nullable),
  - `order_status_sync_direction` (varchar 32),
  - `payment_sync_status_codes_json` (json, nullable; lista kodow statusow orderPRO, dla ktorych cron ma sprawdzac oplacenie zamowien),
  - pola diagnostyki testu (`last_test_status`, `last_test_http_code`, `last_test_message`, `last_test_at`),
  - `created_at`, `updated_at`.

### `shoppro_delivery_method_mappings`
- Mapowanie form dostawy shopPRO na uslugi dostawy Allegro WZA/InPost per instancja integracji.
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `integration_id` (int unsigned, FK -> `integrations.id`),
  - `order_delivery_method` (varchar 200),
  - `carrier` (varchar 50; np. `allegro`, `inpost`),
  - `allegro_delivery_method_id` (varchar 128),
  - `allegro_credentials_id` (varchar 128, nullable),
  - `allegro_carrier_id` (varchar 128, nullable),
  - `allegro_service_name` (varchar 255, nullable),
  - `created_at`, `updated_at`.
- Indeksy:
  - `shoppro_dm_mapping_unique` (UNIQUE: `integration_id`, `order_delivery_method`),
  - `shoppro_dm_mapping_integration_idx` (`integration_id`).
- Klucze obce:
  - `shoppro_dm_mapping_integration_fk`: `integration_id` -> `integrations.id` (`ON DELETE CASCADE`, `ON UPDATE CASCADE`).

### `apaczka_integration_settings`
- Tabela kompatybilnosci dla integracji Apaczka (`id = 1`); sekret API jest utrzymywany bazowo w `integrations.api_key_encrypted`.
- Kolumny:
  - `id` (PK, tinyint unsigned),
  - `integration_id` (int unsigned, UNIQUE, FK -> `integrations.id`),
  - `app_id` (varchar 128, nullable),
  - `app_secret_encrypted` (text, nullable),
  - `api_key_encrypted` (text, nullable),
  - `created_at`, `updated_at`.

### `carrier_delivery_method_mappings`
- Wspolne mapowanie form dostawy zamowien na providerow wysylek (model docelowy pod wielu kurierow: `allegro_wza`, `apaczka`, kolejne).
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `source_system` (varchar 32; np. `allegro`, `shoppro`),
  - `source_integration_id` (int unsigned; `0` dla mapowan globalnych, np. Allegro),
  - `order_delivery_method` (varchar 200),
  - `provider` (varchar 50; np. `allegro_wza`, `apaczka`),
  - `provider_service_id` (varchar 128),
  - `provider_account_id` (varchar 128, nullable),
  - `provider_carrier_id` (varchar 128, nullable),
  - `provider_service_name` (varchar 255, nullable),
  - `created_at`, `updated_at`.
- Indeksy:
  - `carrier_dm_mapping_unique` (UNIQUE: `source_system`, `source_integration_id`, `order_delivery_method`),
  - `carrier_dm_mapping_provider_idx` (`provider`),
  - `carrier_dm_mapping_source_idx` (`source_system`, `source_integration_id`).

### `inpost_integration_settings`
- Tabela ustawien specyficznych InPost ShipX (`id = 1`); token API utrzymywany bazowo w `integrations.api_key_encrypted`.
- Kolumny:
  - `id` (PK, tinyint unsigned),
  - `integration_id` (int unsigned, UNIQUE, FK -> `integrations.id`),
  - `api_token_encrypted` (text, nullable),
  - `organization_id` (varchar 50, nullable),
  - `environment` (enum: sandbox, production),
  - `default_dispatch_method` (enum: pop, parcel_locker, courier),
  - `default_dispatch_point` (varchar 50, nullable),
  - `default_insurance` (decimal 10,2, nullable),
  - `default_locker_size` (enum: small, medium, large),
  - `default_courier_length`, `default_courier_width`, `default_courier_height` (smallint unsigned),
  - `label_format` (enum: Pdf, Zpl, Epl),
  - `weekend_delivery`, `auto_insurance_value`, `multi_parcel` (tinyint 0/1),
  - `created_at`, `updated_at`.

### `company_settings`
- Ustawienia firmy/nadawcy wykorzystywane m.in. przy tworzeniu przesylek.
- Kolumny:
  - `id` (PK, tinyint unsigned),
  - `company_name` (varchar 200, nullable),
  - `person_name` (varchar 200, nullable),
  - `sender_contact_person` (varchar 200, nullable),
  - `street` (varchar 200, nullable),
  - `city` (varchar 128, nullable),
  - `postal_code` (varchar 16, nullable),
  - `country_code` (char 2, default `PL`),
  - `phone` (varchar 64, nullable),
  - `email` (varchar 128, nullable),
  - `tax_number` (varchar 64, nullable),
  - `bank_account` (varchar 64, nullable),
  - `bank_owner_name` (varchar 200, nullable),
  - `bdo_number` (varchar 20, nullable),
  - `regon` (varchar 14, nullable),
  - `court_register` (varchar 128, nullable),
  - `logo_path` (varchar 255, nullable),
  - `default_package_length_cm` (decimal 8,1),
  - `default_package_width_cm` (decimal 8,1),
  - `default_package_height_cm` (decimal 8,1),
  - `default_package_weight_kg` (decimal 8,3),
  - `default_label_format` (varchar 8),
  - `created_at`, `updated_at`.

### `receipt_configs`
- Konfiguracje paragonow (szablony numeracji, ustawienia).
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `name` (varchar 128),
  - `is_active` (tinyint(1), default 1),
  - `number_format` (varchar 64, default `PAR/%N/%M/%Y`),
  - `numbering_type` (enum: monthly, yearly; default monthly),
  - `is_named` (tinyint(1), default 0) — czy paragon imienny (dane klienta),
  - `sale_date_source` (enum: order_date, payment_date, issue_date; default issue_date),
  - `order_reference` (enum: none, orderpro, integration; default none),
  - `created_at`, `updated_at`.

### `receipts`
- Wystawione paragony ze snapshotem danych.
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `order_id` (bigint unsigned, FK -> `orders.id` CASCADE),
  - `config_id` (int unsigned, FK -> `receipt_configs.id` RESTRICT),
  - `receipt_number` (varchar 64, UNIQUE),
  - `issue_date` (datetime),
  - `sale_date` (date),
  - `seller_data_json` (json) — snapshot danych sprzedawcy,
  - `buyer_data_json` (json, nullable) — snapshot danych klienta (jesli imienny),
  - `items_json` (json) — snapshot pozycji zamowienia,
  - `total_net` (decimal 12,2),
  - `total_gross` (decimal 12,2),
  - `order_reference_value` (varchar 128, nullable),
  - `created_by` (int unsigned, nullable),
  - `created_at`.
- Indeksy:
  - `receipts_number_unique` (UNIQUE: `receipt_number`),
  - `receipts_order_idx` (`order_id`),
  - `receipts_config_idx` (`config_id`),
  - `receipts_issue_date_idx` (`issue_date`).
- Klucze obce:
  - `receipts_order_fk`: `order_id` -> `orders.id` (ON DELETE CASCADE),
  - `receipts_config_fk`: `config_id` -> `receipt_configs.id` (ON DELETE RESTRICT).

### `receipt_number_counters`
- Liczniki numeracji paragonow per konfiguracja i okres.
- Kolumny:
  - `id` (PK, int unsigned, AI),
  - `config_id` (int unsigned, FK -> `receipt_configs.id` CASCADE),
  - `year` (smallint unsigned),
  - `month` (tinyint unsigned, nullable — null dla numeracji rocznej),
  - `last_number` (int unsigned, default 0).
- Indeksy:
  - `receipt_counters_config_period_unique` (UNIQUE: `config_id`, `year`, `month`).
- Klucze obce:
  - `receipt_counters_config_fk`: `config_id` -> `receipt_configs.id` (ON DELETE CASCADE).

### `email_mailboxes`
- Skrzynki pocztowe SMTP do wysylki wiadomosci e-mail.
- Kolumny:
  - `id` INT UNSIGNED PK AUTO_INCREMENT
  - `name` VARCHAR(100) NOT NULL — nazwa wyswietlana
  - `smtp_host` VARCHAR(255) NOT NULL
  - `smtp_port` SMALLINT UNSIGNED NOT NULL DEFAULT 587
  - `smtp_encryption` ENUM('tls','ssl','none') NOT NULL DEFAULT 'tls'
  - `smtp_username` VARCHAR(255) NOT NULL
  - `smtp_password_encrypted` TEXT NOT NULL — szyfrowane IntegrationSecretCipher (AES-256-CBC+HMAC)
  - `sender_email` VARCHAR(255) NOT NULL
  - `sender_name` VARCHAR(200) DEFAULT NULL
  - `header_html` TEXT DEFAULT NULL — HTML naglowek dolaczany do kazdego e-maila z tej skrzynki
  - `footer_html` TEXT DEFAULT NULL — HTML stopka dolaczana do kazdego e-maila z tej skrzynki
  - `is_default` TINYINT(1) NOT NULL DEFAULT 0
  - `is_active` TINYINT(1) NOT NULL DEFAULT 1
  - `created_at`, `updated_at` DATETIME

### `email_templates`
- Szablony wiadomosci e-mail z systemem zmiennych.
- Kolumny:
  - `id` INT UNSIGNED PK AUTO_INCREMENT
  - `name` VARCHAR(200) NOT NULL — nazwa szablonu
  - `subject` VARCHAR(500) NOT NULL — temat (moze zawierac zmienne)
  - `body_html` TEXT NOT NULL — tresc HTML (Quill.js output)
  - `mailbox_id` INT UNSIGNED DEFAULT NULL — FK do email_mailboxes ON DELETE SET NULL
  - `attachment_1` VARCHAR(50) DEFAULT NULL — typ zalacznika nr 1 (np. 'receipt' = paragon); NULL = brak
  - `is_active` TINYINT(1) NOT NULL DEFAULT 1
  - `created_at`, `updated_at` DATETIME
- Indeksy: `idx_email_templates_mailbox` (mailbox_id)

### `email_logs`
- Log wyslanych wiadomosci e-mail.
- Kolumny:
  - `id` BIGINT UNSIGNED PK AUTO_INCREMENT
  - `template_id` INT UNSIGNED DEFAULT NULL — FK do email_templates ON DELETE SET NULL
  - `mailbox_id` INT UNSIGNED DEFAULT NULL — FK do email_mailboxes ON DELETE SET NULL
  - `order_id` INT UNSIGNED DEFAULT NULL
  - `recipient_email` VARCHAR(255) NOT NULL
  - `recipient_name` VARCHAR(200) DEFAULT NULL
  - `subject` VARCHAR(500) NOT NULL
  - `body_html` TEXT NOT NULL — tresc po rozwinieciu zmiennych
  - `attachments_json` JSON DEFAULT NULL — lista zalacznikow [{name, path, type}]
  - `status` ENUM('sent','failed','pending') NOT NULL DEFAULT 'pending'
  - `error_message` TEXT DEFAULT NULL
  - `sent_at` DATETIME DEFAULT NULL
  - `created_at` DATETIME
- Indeksy: `idx_email_logs_template`, `idx_email_logs_mailbox`, `idx_email_logs_order`, `idx_email_logs_status`, `idx_email_logs_sent_at`

### `automation_rules`
- Reguly automatyzacji (zdarzenie -> warunki -> akcje).
- Kolumny:
  - `id` INT UNSIGNED PK AUTO_INCREMENT
  - `name` VARCHAR(128) NOT NULL — nazwa reguly
  - `event_type` VARCHAR(64) NOT NULL — typ zdarzenia (np. 'receipt.created')
  - `is_active` TINYINT(1) NOT NULL DEFAULT 1
  - `created_at`, `updated_at` DATETIME
- Indeksy:
  - `auto_rules_event_active_idx` (`event_type`, `is_active`)

### `automation_conditions`
- Warunki reguly automatyzacji (laczenie logiczne AND).
- Kolumny:
  - `id` INT UNSIGNED PK AUTO_INCREMENT
  - `rule_id` INT UNSIGNED NOT NULL, FK -> `automation_rules.id` ON DELETE CASCADE
  - `condition_type` VARCHAR(64) NOT NULL — typ warunku (np. 'integration')
  - `condition_value` JSON NOT NULL — konfiguracja warunku (np. {"integration_ids": [1, 3]})
  - `sort_order` SMALLINT UNSIGNED NOT NULL DEFAULT 0
- Indeksy:
  - `auto_cond_rule_idx` (`rule_id`)
- Klucze obce:
  - `auto_cond_rule_fk`: `rule_id` -> `automation_rules.id` (ON DELETE CASCADE)

### `automation_actions`
- Akcje do wykonania po spelnieniu warunkow reguly.
- Kolumny:
  - `id` INT UNSIGNED PK AUTO_INCREMENT
  - `rule_id` INT UNSIGNED NOT NULL, FK -> `automation_rules.id` ON DELETE CASCADE
  - `action_type` VARCHAR(64) NOT NULL — typ akcji (np. 'send_email')
  - `action_config` JSON NOT NULL — konfiguracja akcji (np. {"template_id": 5, "recipient": "client"})
  - `sort_order` SMALLINT UNSIGNED NOT NULL DEFAULT 0
- Indeksy:
  - `auto_act_rule_idx` (`rule_id`)
- Klucze obce:
  - `auto_act_rule_fk`: `rule_id` -> `automation_rules.id` (ON DELETE CASCADE)

### `automation_execution_logs`
- Historia wykonan automatyzacji pokazywana w `Ustawienia > Zadania automatyczne > Historia`.
- Kolumny:
  - `id` BIGINT UNSIGNED PK AUTO_INCREMENT
  - `event_type` VARCHAR(64) NOT NULL — typ triggera (np. `receipt.created`, `shipment.created`)
  - `rule_id` INT UNSIGNED NULL — FK do `automation_rules.id` (NULL gdy regula zostala usunieta)
  - `rule_name` VARCHAR(128) NOT NULL — snapshot nazwy reguly w momencie wykonania
  - `order_id` INT UNSIGNED NOT NULL — FK do `orders.id`
  - `execution_status` VARCHAR(16) NOT NULL — wynik (`success`/`failed`)
  - `result_message` VARCHAR(500) NULL — komunikat wykonania lub bledu
  - `context_json` JSON NULL — zrzut kontekstu triggera (sanityzowany)
  - `executed_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
  - `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
- Indeksy:
  - `auto_exec_logs_executed_idx` (`executed_at`)
  - `auto_exec_logs_event_idx` (`event_type`)
  - `auto_exec_logs_status_idx` (`execution_status`)
  - `auto_exec_logs_rule_idx` (`rule_id`)
  - `auto_exec_logs_order_idx` (`order_id`)
- Klucze obce:
  - `auto_exec_logs_rule_fk`: `rule_id` -> `automation_rules.id` (`ON DELETE SET NULL`, `ON UPDATE CASCADE`)
  - `auto_exec_logs_order_fk`: `order_id` -> `orders.id` (`ON DELETE CASCADE`, `ON UPDATE CASCADE`)

## Zasady aktualizacji
- Po kazdej migracji dopisz:
  - nowe/zmienione tabele i kolumny,
  - indeksy i klucze obce,
  - wplyw na dane i kompatybilnosc wsteczna.

## Drafty (nieaktywne)
- `database/drafts/20260302_orders_schema_v1.sql`:
  - propozycja normalizacji domeny zamowien pod integracje zewnetrzne (`orders`, `order_items`, `order_status_history`, platnosci, wysylki, dokumenty, notatki, tagi, sync-state),
  - plik nie jest odpalany przez obecny migrator (`database/migrations/*.sql`).
- `bin/deploy_and_seed_orders.php`:
  - techniczny skrypt wdrozeniowy, ktory aplikuje schema z draftu i opcjonalnie seeduje dane testowe.
