orderPRO/.paul/docs/DB_SCHEMA.md

DB_SCHEMA

Zakres i zrodlo prawdy

• Schemat wynika z migracji SQL w database/migrations.
• Dokument odzwierciedla stan repo na 2026-04-18 (migracje do 20260413_000100).

Ostatnie istotne migracje

• 20260413_000100_ensure_orders_delivery_payment_columns.sql
• 20260412_000099_add_requires_photo_to_project_mappings.sql
• 20260412_000098_rename_external_status_id_to_status_code.sql
• 20260412_000097_add_project_generation.sql
• 20260410_000081_add_remember_token_to_users.sql
• 20260408_000090_backfill_delivery_price.sql
• 20260407_000083_allegro_pull_status_mappings.sql
• 20260407_000080_backfill_personalization_message.sql
• 20260407_000079_pull_status_mappings.sql
• 20260407_000078_reverse_status_mapping_keys.sql

Kompensacyjne migracje ensure_

• 000038 - naprawa brakujacej tabeli order_status_mappings.
• 000039 - uzupelnienie brakujacych kolumn fetch w integrations.
• 000040 - seed/naprawa harmonogramu shoppro_orders_import.
• 000041 - seed/naprawa harmonogramu shoppro_order_status_sync + direction.
• 000042 - seed/naprawa shoppro_payment_status_sync + kolumny payment sync.
• 000100 - kompensacja brakujacych kolumn orders.payment_method i orders.delivery_method.

Kluczowe tabele

users

• Uzytkownicy panelu.
• Wazne kolumny:
• id, email (UNIQUE), password_hash, remember_token (od 000081), is_active, created_at, updated_at.

orders

• Glowna tabela zamowien (model neutralny wzgledem zrodla).
• Wazne kolumny:
• id, source, integration_id, source_order_id, internal_order_number (UNIQUE),
• status_code (rename z external_status_id w 000098),
• payment_status, total_paid, payment_method,
• delivery_method, delivery_price (dodane/backfill 000090),
• daty zrodlowe i techniczne, payload_json, preferences_json.
• Wydajnosc:
• indeksy na source, status_code, ordered_at, (source, status_code).

order_items

• Pozycje zamowienia.
• Wazne kolumny:
• order_id, source_item_id, name, quantity, price_gross, media_url, payload_json,
• personalization (000075, backfill 000080),
• project_generated, project_generated_at (000097).

order_payments

• Platnosci zamowien (import i reczne).
• Wazne kolumny:
• order_id, source_payment_id, payment_type_id, payment_date, amount, currency, payload_json.
• Klucz unikalny:
• (order_id, source_payment_id).

order_status_history

• Historia zmian statusow zamowienia.
• Wazne kolumny:
• order_id, from_status_id, to_status_id, change_source, changed_by, changed_at.

order_activity_log

• Uniwersalny log aktywnosci (status_change, payment, shipment, import, itd.).
• Wazne kolumny:
• order_id, event_type, summary, details_json, actor_type, actor_name, created_at.

order_status_groups i order_statuses

• Slownik statusow biznesowych i grup statusow.
• Relacja:
• order_statuses.group_id -> order_status_groups.id (ON DELETE CASCADE).

integrations

• Bazowa tabela instancji integracji.
• Wazne kolumny:
• type, name, base_url, api_key_encrypted, is_active,
• orders_fetch_enabled, orders_fetch_start_date,
• order_status_sync_direction, payment_sync_status_codes_json,
• pola diagnostyczne testu polaczenia.

integration_order_sync_state

• Kursor synchronizacji per integracja.
• Wazne kolumny:
• integration_id (PK), last_synced_order_updated_at, last_synced_source_order_id,
• last_success_at, last_status_pushed_at, last_error.

order_status_mappings

• Mapowania push statusow dla shopPRO.
• Po 000078 klucz unikalny:
• (integration_id, orderpro_status_code).
• Dodatkowe indeksy:
• (integration_id, shoppro_status_code).

order_status_pull_mappings

• Dedykowane mapowanie pull shopPRO -> orderPRO (000079).
• Klucz unikalny:
• (integration_id, shoppro_status_code).

allegro_order_status_mappings

• Mapowania statusow Allegro dla kierunku push.
• Po 000078 klucz unikalny:
• orderpro_status_code.
• Indeks lookup:
• allegro_status_code.

allegro_order_status_pull_mappings

• Dedykowane mapowanie pull Allegro -> orderPRO (000083).
• Klucz unikalny:
• allegro_status_code.

allegro_integration_settings

• OAuth i tokeny Allegro per srodowisko/integracja.
• Wazne kolumny:
• integration_id (UNIQUE FK), environment, client_id, client_secret_encrypted,
• redirect_uri, access_token_encrypted, refresh_token_encrypted, token_expires_at,
• orders_fetch_enabled, orders_fetch_start_date.

apaczka_integration_settings i inpost_integration_settings

• Ustawienia providerow wysylek, powiazane 1:1 z integrations przez integration_id.

company_settings

• Dane firmy/nadawcy, parametry domyslnych paczek i pola ksiegowe.

receipt_configs, receipts, receipt_number_counters

• Konfiguracja numeracji, wystawione paragony i liczniki numerow.

email_mailboxes, email_templates, email_logs

• Skrzynki SMTP, szablony i log wysylki.

automation_rules, automation_conditions, automation_actions, automation_execution_logs

• Definicje regul i historia ich wykonan.

shipment_packages

• Rekordy przesylek i etykiet.
• Wazne kolumny trackingowe (od 000060):
• delivery_status, delivery_status_raw, delivery_status_updated_at.

delivery_status_mappings

• Mapowanie statusow przewoznikow na status biznesowy (provider + raw_status UNIQUE).

carrier_delivery_method_mappings

• Wspolne mapowanie form dostawy na providerow wysylki.

shipment_presets

• Presety nadania wykorzystywane przez API presetow przesylek.

print_api_keys

• Klucze API dla klienta desktop druku.
• Kolumny:
• key_hash (UNIQUE), key_prefix, is_active, last_used_at.

print_jobs

• Kolejka wydruku etykiet.
• Kolumny:
• order_id, package_id, label_path, status, created_by, created_at, completed_at.

project_mappings

• Mapowanie produktu na skrypt generujacy projekt (000097).
• Wazne kolumny:
• product_name_pattern, script_name, output_dir, requires_photo (000099), is_active.

Harmonogram cron (cron_schedules)

• Wykorzystywane typy jobow:
• allegro_token_refresh
• allegro_orders_import
• allegro_status_sync
• shoppro_orders_import
• shoppro_order_status_sync
• shoppro_payment_status_sync
• shipment_tracking_sync
• automation_history_cleanup
• order_status_aged

Notatki kompatybilnosci

• Migracje ensure_ i 000100 sa idempotentne i kompensuja roznice miedzy srodowiskami.
• Rename orders.external_status_id -> status_code wymaga, aby nowe query i dokumentacja uzywaly tylko status_code.
• delivery_price jest backfillowane z JSON payloadow importu (Allegro/shopPRO).