version: 0.5.1
source_of_truth:
  schema_file: sql/007.sql
  notes:
    - "To jest dokumentacja robocza na podstawie aktualnego dumpa SQL i kodu modułu."
    - "Część tabel jest współdzielona z innymi modułami i starym ERP."
    - "Model kategorii towaru jest docelowo jednoznaczny: 1 towar -> 1 kategoria przez wms_stats_towar.stw_stc_id."
    - "Model towaru jest docelowo jednoznaczny: 1 towar -> 1 model przez wms_stats_towar.stw_stm_id."
    - "Model serii towaru jest docelowo jednoznaczny: 1 towar -> 1 seria przez wms_stats_towar.stw_sts_id."
    - "Aktywny runtime kosztów korzysta przede wszystkim z miesięcznego cache wms_cost_month_product."
    - "Cache miesięczny obsługuje także koszt przepisany: cmp_unit_carry_pln + cmp_is_carried + cmp_carry_source_month."
    - "Tabela wms_cost_product zasila dziś cache miesięczny podczas operacji odświeżenia; override'y zamówienia i pozycji dalej nie są wpięte do aktywnego liczenia kosztu zamówień/WZ."
    - "Tabela wms_cost_growth_index jest używana tylko przez forecast w demand; brak wpisu oznacza fallback do indeksu 1.1."

shared_external_tables:
  groups:
    - wms_dict_*
    - wms_towar*
    - wms_user
    - package_*
  key_tables:
    - name: wms_user
      purpose_for_stats: "Logowanie użytkowników modułu i role dostępu."
    - name: wms_towar
      purpose_for_stats: "Powiązanie sprzedaży i kosztów z kartoteką towarową."
    - name: package_doc_wz
      purpose_for_stats: "Tabela docelowa wykorzystywana przy generowaniu WZ z obszaru stats."

column_prefixes:
  so:
    table: wms_stats_order
    meaning: "nagłówek zamówienia sprzedażowego"
  soi:
    table: wms_stats_order_item
    meaning: "pozycja zamówienia"
  sc:
    table: wms_stats_customer
    meaning: "klient"
  ssk:
    table: wms_stats_sale_kind
    meaning: "rodzaj sprzedaży"
  ss:
    table: wms_stats_seller
    meaning: "sprzedawca / podmiot"
  dsm:
    table: wms_dict_sales_market
    meaning: "market place / rynek sprzedaży"
  cur:
    table: wms_stats_currency
    meaning: "słownik walut"
  frd:
    table: wms_stats_fx_rate_day
    meaning: "kurs waluty dzienny"
  stw:
    table: wms_stats_towar
    meaning: "towar statystyczny / oferta"
  stc:
    table: wms_stats_towar_category
    meaning: "kategoria towaru"
  psr:
    table: pim_price_symbol_registry
    meaning: "rejestr symboli technicznych cennikow / kosztow kalkulacyjnych"
  pcc:
    table: pim_price_calc_cost
    meaning: "koszt kalkulacyjny per symbol"
  pdc:
    table: pim_dict_cost_component
    meaning: "slownik skladnikow kosztu dla obszaru cennikow / PIM"
  pl:
    table: pim_price_list
    meaning: "naglowek cennika"
  pli:
    table: pim_price_list_item
    meaning: "pozycja cennika"
  plc:
    table: pim_price_list_component
    meaning: "relacja cennik -> skladniki kosztowe uwzgledniane przy kalkulacji ceny"
  wcp:
    table: wms_cost_product
    meaning: "koszt produktu"
  wcb:
    table: wms_cost_bom
    meaning: "BOM kosztowy"
  wco:
    table: wms_cost_order_override
    meaning: "override kosztu na zamówieniu"
  wci:
    table: wms_cost_item_override
    meaning: "override kosztu na pozycji"
  sar:
    table: wms_schema_audit_run
    meaning: "nagłówek uruchomienia audytu schematu"
  saf:
    table: wms_schema_audit_file
    meaning: "plik zindeksowany w audycie"
  sah:
    table: wms_schema_audit_hit
    meaning: "trafienie kolumny w pliku"

tables:
  - name: wms_stats_order
    prefix: so
    used_in_app: true
    purpose: "Główna tabela zamówień sprzedażowych, z wartościami źródłowymi, przeliczonymi do waluty bazowej oraz bezpośrednim przypisaniem kanału, marketu i podmiotu."
    used_by:
      - app/Repositories/OrdersRepository.php
      - app/Repositories/StatsRepository.php
      - app/Repositories/ReportsRepository.php
      - app/Repositories/DemandRepository.php
      - app/Controllers/HealthController.php
    key_columns:
      - so_id
      - so_source
      - so_doc_no
      - so_date
      - so_currency_code
      - so_fx_rate
      - so_total_netto
      - so_total_netto_base
      - so_total_brutto
      - so_total_brutto_base
      - so_seller_id
      - so_sales_market_id
      - so_sales_channel_id
      - so_sale_kind_id

  - name: wms_dict_sales_market
    prefix: dsm
    used_in_app: true
    purpose: "Słownik market place używany do grupowania kanałów sprzedaży i filtrowania zamówień."
    used_by:
      - app/Repositories/LookupsRepository.php
      - app/Repositories/OrdersRepository.php
      - app/Repositories/StatsRepository.php
      - app/Controllers/AdminController.php
    key_columns:
      - dsm_id
      - dsm_code
      - dsm_name
      - dsm_label
      - dsm_status

  - name: wms_stats_order_item
    prefix: soi
    used_in_app: true
    purpose: "Pozycje zamówień używane do analityki sprzedaży, kosztów i filtrów po SKU."
    used_by:
      - app/Repositories/OrdersRepository.php
      - app/Repositories/StatsRepository.php
      - app/Repositories/DemandRepository.php
      - app/Services/GeneratorWzService.php
    key_columns:
      - soi_id
      - soi_order_id
      - soi_symbol
      - soi_qty
      - soi_total_netto
      - soi_total_brutto

  - name: wms_stats_currency
    prefix: cur
    used_in_app: true
    purpose: "Słownik walut i oznaczenie waluty bazowej."
    used_by:
      - app/Repositories/LookupsRepository.php
      - app/Controllers/HealthController.php

  - name: wms_stats_fx_rate_day
    prefix: frd
    used_in_app: true
    purpose: "Kursy walut wykorzystywane do przeliczania zamówień na walutę bazową."
    used_by:
      - app/Repositories/OrdersRepository.php
      - app/Controllers/ImportController.php
      - app/Controllers/HealthController.php

  - name: wms_stats_seller
    prefix: ss
    used_in_app: true
    purpose: "Słownik sprzedawców / podmiotów używanych w filtrach i imporcie."
    used_by:
      - app/Repositories/LookupsRepository.php
      - app/Controllers/ImportController.php
      - app/Controllers/HealthController.php

  - name: wms_stats_towar
    prefix: stw
    used_in_app: true
    purpose: "Kartoteka ofert / towarów dla analityki i mapowań, z bezpośrednim przypisaniem jednej kategorii."
    used_by:
      - app/Repositories/OrdersRepository.php
      - app/Repositories/StatsRepository.php
      - app/Repositories/DemandRepository.php
      - app/Repositories/DataChecksRepository.php
      - app/Controllers/ImportController.php
    key_columns:
      - stw_id
      - stw_tw_id
      - stw_symbol
      - stw_name
      - stw_ean
      - stw_rodzaj
      - stw_unit
      - stw_weight
      - stw_stc_id
      - stw_stm_id
      - stw_sts_id

  - name: wms_stats_towar_category
    prefix: stc
    used_in_app: true
    purpose: "Słownik kategorii towarów wykorzystywany w filtrach i agregacjach sprzedaży."
    used_by:
      - app/Repositories/LookupsRepository.php
      - app/Repositories/OrdersRepository.php
      - app/Repositories/StatsRepository.php

  - name: wms_stats_towar_model
    prefix: stm
    used_in_app: true
    purpose: "Słownik modeli towarów wykorzystywany w filtrach i przypisaniach opartych o symbol produktu."
    used_by:
      - app/Repositories/LookupsRepository.php
      - app/Repositories/OrdersRepository.php
      - app/Repositories/StatsRepository.php
    key_columns:
      - stm_id
      - stm_code
      - stm_label
      - stm_active

  - name: wms_stats_towar_series
    prefix: sts
    used_in_app: true
    purpose: "Słownik serii towarów wykorzystywany przez kartotekę stats i widoki szczegółowe produktu."
    used_by:
      - app/Repositories/LookupsRepository.php
      - app/Repositories/ProductRepository.php
      - app/Controllers/ImportController.php
    key_columns:
      - sts_id
      - sts_stc_id
      - sts_code
      - sts_label
      - sts_active

  - name: pim_price_symbol_registry
    prefix: psr
    used_in_app: true
    purpose: "Rejestr symboli technicznych dla kosztow kalkulacyjnych i cennikow, mapowany do stats_towar po symbolu."
    used_by:
      - app/Repositories/PricingRepository.php
      - app/Controllers/PricingController.php
    key_columns:
      - psr_id
      - psr_symbol
      - psr_stw_id
      - psr_old_symbol
      - psr_label
      - psr_weight_brutto
      - psr_margin_factor
      - psr_pack_count
      - psr_component_count

  - name: pim_price_calc_cost
    prefix: pcc
    used_in_app: true
    purpose: "Koszty kalkulacyjne per symbol techniczny, bez historii okresowej."
    used_by:
      - app/Repositories/PricingRepository.php
      - app/Controllers/PricingController.php
    notes:
      - "Pierwszy wsad techniczny moze byc zasilony z towar_ceny_sprzedazy przez 021_pricing_calc_cost_component_1.sql."
      - "Mapowanie poczatkowe: tw_koszt_towar -> pcc_component_id = 1."
      - "Kolejny wsad techniczny moze byc zasilony przez 023_pricing_calc_cost_component_6.sql."
      - "Mapowanie: tw_koszt_operacje -> pcc_component_id = 6."
      - "Kolejny wsad techniczny moze byc zasilony przez 025_pricing_calc_cost_component_8.sql."
      - "Mapowanie: tw_koszt_operacje_detluz -> pcc_component_id = 8."
      - "Kolejny wsad techniczny moze byc zasilony przez 026_pricing_calc_cost_component_9.sql."
      - "Mapowanie: tw_koszt_operacje_hurtkpl -> pcc_component_id = 9."
      - "Kolejny wsad techniczny moze byc zasilony przez 027_pricing_calc_cost_component_10.sql."
      - "Mapowanie: tw_koszt_operacje_hurtluz -> pcc_component_id = 10."
    key_columns:
      - pcc_id
      - pcc_symbol
      - pcc_component_id
      - pcc_cost_netto
      - pcc_currency_code

  - name: pim_dict_cost_component
    prefix: pdc
    used_in_app: true
    purpose: "Wlasny slownik skladnikow kosztu dla cennikow, z hierarchia 2-poziomowa: grupa glowna -> podgrupa."
    used_by:
      - app/Repositories/LookupsRepository.php
      - app/Controllers/PricingController.php
    key_columns:
      - pdc_id
      - pdc_parent_group_id
      - pdc_group_id
      - pdc_code
      - pdc_label
      - pdc_sort
      - pdc_active
      - pdc_cost_row_count
      - pdc_symbol_count
      - pdc_group_code
      - pdc_group_label
      - pdc_group_sort
    notes:
      - "parent_group_id = NULL/0 oznacza grupe glowna."
      - "parent_group_id > 0 oznacza podgrupe i wskazuje rekord pdc_id grupy glownej."

  - name: pim_price_list
    prefix: pl
    used_in_app: true
    purpose: "Naglowek cennika z typem cennika, waluta i lista skladnikow kosztowych uwzglednianych przy kalkulacji ceny."
    used_by:
      - app/Repositories/PricingRepository.php
      - app/Controllers/PricingController.php
    key_columns:
      - pl_id
      - pl_item_count
      - pl_component_count
      - pl_code
      - pl_name
      - pl_currency_code
      - pl_vat_pct
      - pl_round_gross
      - pl_active

  - name: pim_price_list_component
    prefix: plc
    used_in_app: true
    purpose: "Tabela przypisan skladnikow kosztowych do cennika."
    used_by:
      - app/Repositories/PricingRepository.php
      - app/Controllers/PricingController.php
    key_columns:
      - plc_id
      - plc_pl_id
      - plc_pdc_id

  - name: pim_price_list_item
    prefix: pli
    used_in_app: true
    purpose: "Pozycje cennika per symbol techniczny."
    used_by:
      - app/Repositories/PricingRepository.php
      - app/Controllers/PricingController.php
    key_columns:
      - pli_id
      - pli_pl_id
      - pli_symbol
      - pli_price_netto
      - pli_price_brutto
      - pli_currency_code

  - name: wms_cost_product
    prefix: wcp
    used_in_app: true
    purpose: "Koszt produktu w czasie, z walutą i źródłem kosztu."
    used_by:
      - app/Controllers/ImportController.php
    notes:
      - "Tabela jest zapisywana przez import i ma logikę domykania okresów valid_from/valid_to."
      - "Tabela nie jest czytana bezpośrednio przez OrdersRepository, StatsRepository ani GeneratorWzService."
      - "Jej aktywna rola polega na zasilaniu cmp_unit_manual_pln w cache miesięcznym podczas operacji odświeżenia kosztów."

  - name: wms_cost_bom
    prefix: wcb
    used_in_app: true
    purpose: "Receptury i BOM-y wykorzystywane w kalkulacjach kosztowych."
    used_by:
      - app/Controllers/ImportController.php
      - app/Controllers/CostToolsController.php
    notes:
      - "Tabela jest aktywnie używana przy kalkulacji cmp_unit_calc_pln w wms_cost_month_product."
      - "Jej brak danych jest poprawny tylko wtedy, gdy nie używamy kosztu wg składników."

  - name: wms_cost_order_override
    prefix: wco
    used_in_app: true
    purpose: "Ręczne nadpisanie kosztu całego zamówienia."
    used_by:
      - app/Controllers/ImportController.php
    notes:
      - "Tabela jest obecnie zasilana wyłącznie przez importer."
      - "Na dzień przeglądu 2026-04 aktywny runtime nie czyta override'ów zamówienia."

  - name: wms_cost_item_override
    prefix: wci
    used_in_app: true
    purpose: "Ręczne nadpisanie kosztu pozycji zamówienia."
    used_by:
      - app/Controllers/ImportController.php
    notes:
      - "Tabela jest obecnie zasilana wyłącznie przez importer."
      - "Na dzień przeglądu 2026-04 aktywny runtime nie czyta override'ów pozycji."

  - name: wms_cost_import_batch
    prefix: cib
    used_in_app: true
    purpose: "Nagłówek importu wsadu PZ do analizy kosztu zakupu."
    used_by:
      - app/Controllers/ImportController.php
    notes:
      - "Tabela bierze udział tylko w imporcie typu pz_purchase."
      - "Jej brak danych oznacza zwykle brak uruchomionych importów PZ, a nie błąd modelu."

  - name: wms_cost_growth_index
    prefix: cgi
    used_in_app: true
    purpose: "Ręczny indeks wzrostu używany wyłącznie do forecastów demand."
    used_by:
      - app/Repositories/DemandRepository.php
    notes:
      - "Brak wpisu nie blokuje działania demand."
      - "Kod stosuje wtedy domyślną wartość 1.1."

  - name: wms_schema_audit_run
    prefix: sar
    used_in_app: true
    purpose: "Nagłówek przebiegu audytu schematu."
    used_by:
      - app/Services/SchemaAuditService.php
      - app/Controllers/SchemaAuditController.php

  - name: wms_schema_audit_file
    prefix: saf
    used_in_app: true
    purpose: "Lista plików objętych audytem schematu."
    used_by:
      - app/Services/SchemaAuditService.php

  - name: wms_schema_audit_hit
    prefix: sah
    used_in_app: true
    purpose: "Trafienia kolumn/tabel w plikach projektu."
    used_by:
      - app/Services/SchemaAuditService.php
      - app/Controllers/SchemaAuditController.php

current_scope_summary:
  heavily_used_tables:
    - wms_stats_order
    - wms_stats_order_item
    - wms_stats_currency
    - wms_stats_fx_rate_day
    - wms_stats_seller
    - wms_stats_towar
  cost_area:
    - wms_cost_product
    - wms_cost_bom
    - wms_cost_order_override
    - wms_cost_item_override
  admin_audit_area:
    - wms_schema_audit_run
    - wms_schema_audit_file
    - wms_schema_audit_hit

runtime_foundation_2026_04_29:
  columns:
    - wms_stats_towar.stw_tw_id
    - wms_stats_towar.stw_rodzaj
    - wms_stats_towar.stw_unit
    - wms_stats_towar.stw_weight
  tables:
    - wms_stats_towar_komplet
  notes:
    - "stats buduje wlasna warstwe produktu i BOM bez zmiany znaczenia stw_id"
    - "stw_tw_id jest mostem historycznym do legacy wms_towar.tw_id i moze pozostawac pusty dla nowych importow"
    - "wms_stats_towar_komplet przechowuje BOM po stw_id, ale pierwsze zasilenie odbywa sie po symbolach z legacy wms_towar_komplet"
    - "admin/towar-integrity sluzy do porownania relacji legacy i stats przed przepieciem aktywnego runtime"
    - "migracja 014 pozostawia slad historyczny w *_old_tw_id, ale aktywne WZ i rejestry maja juz trzymac stw_id w kolumnach *_tw_id"

text_encoding_standard:
  charset: utf8mb4
  collation: utf8mb4_unicode_ci
  notes:
    - "To jest domyslny standard dla nowych tabel i nowych kolumn tekstowych w stats."
    - "Mieszanie utf8mb4_general_ci i utf8mb4_unicode_ci moze powodowac bledy SQL przy porownaniach i joinach tekstowych."
