orderPRO/DOCS/DB_SCHEMA.md

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.

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,
  • historia zmian statusow utrzymywana w order_status_history.

integration_order_sync_state

• Kursor synchronizacji importu zamowien dla integracji (uzywany przez cron auto-importu Allegro).
• 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_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_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),
  • 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.

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.