SISL Optima Connector — known issues

Status v0.3.5 — co działa, co nie, dlaczego

Aktualizujemy tę listę przy każdym release. Update z 12 maja 2026 (v0.3.5). Wersja angielska: English version.

Działa w produkcji (zweryfikowane na realnej Optimie 2024)

• Sync produktów Optima → Magento — kod, nazwa, EAN, jednostka miary, cena z wybranego cennika.
• Sync stanów multi-warehouse → Magento MSI — mapowanie magazynów Optimy na MSI sources.
• Multi-store: cennik per website — różne ceny dla `detal.sklep.pl` vs `hurt.sklep.pl` z jednej Optimy.
• Auto-faktury (Optima → Magento Invoice) — operator wystawia FA z opisem `MG-100000123`, Magento sam tworzy Invoice z poprawnymi qty. Partial documents obsługiwane (1 z 5 sztuk = 1 sztuka w Magento, nie 5).
• Sync klientów (KntKarty → customer_entity) — kontrahenci Optimy lądują w Magento po email + websiteId.
• HMAC-SHA256 + Ed25519 + manifest anti-tamper — bezpieczna komunikacja Magento ↔ .NET, signed licence verification.
• Cron locks — concurrent crony nie nadpisują kursora.

⛔ NIE działa w v0.3.5 (TBD v0.4.0 — czerwiec 2026)

• Order forward Magento → Optima — Magento poprawnie wysyła payload, ale po stronie .NET OptimaSqlClient.ForwardOrderAsync jest stubem ("not implemented"). Faktury w Optimie z zamówień Magento nie powstają automatycznie. Plan v0.4.0: XML drop folder + operator klika "Import dokumentów z XML" w Optimie. Toggle sync/orders_enabled w admin defaultowo OFF żeby nie wprowadzać w błąd.
• VAT mismatch — Magento przelicza tax wg własnych reguł, ignoruje kwoty z Optimy. Może generować różnice groszowe między Magento Invoice a Optima FA. Plan v0.4.0: override total fields po prepareInvoice() na podstawie net/vat/gross zwracanych z .NET.
• Brak credit memos / korekt FK/WZK — Optima fakturę korygującą tworzy operator, Magento nie wie. Plan v0.5.0: rozpoznawanie typu doc + tworzenie Magento Credit Memo.
• Shipping cost full na pierwszej fakturze partial — Magento dolicza pełen koszt wysyłki do pierwszej faktury niezależnie od jej rozmiaru. Plan v0.4.0 (razem z VAT parity).

⚠️ Znane ograniczenia (workaround dostępny)

• Idempotency edycji dokumentu Optimy — jeśli operator edytuje zatwierdzony dokument w Optimie (zmienia opis), jego TrN_TS_Mod się zmienia i F2 zobaczy go ponownie → próba utworzenia drugiego Magento Invoice dla tego samego doc'a Optimy.
  Workaround: nie edytuj zatwierdzonych dokumentów Optimy.
  Roadmap v0.4.0/v0.5.0: mapping table optima_doc_id ↔ magento_invoice_id.
• Time zone CET vs UTC drift przy DST — Optima przechowuje datetime bez strefy, .NET używa UTC, w noc zmiany czasu (marzec + październik) dokumenty mogą zostać zgubione lub zduplikowane na ±1h.
  Workaround: nie wystawiaj FA o 2:00-3:00 w noc zmiany czasu (raz na pół roku).
  Roadmap v0.3.6: AT TIME ZONE w SQL + config TZ w appsettings.
• License hostname unstable w k8s/Docker Swarm — Dns.GetHostName() zwraca losowy hostname kontenera; każdy restart = licencja unieważniana.
  Workaround: deploy .NET service na 1 VPS z fixed hostname (najczęstszy setup).
  Roadmap v0.3.6: Sisl:License:CanonicalHost w appsettings.
• Configurable / bundle / grouped products w Magento — Optima zna tylko proste SKU; ProductSync pomija nieprostych z warningiem, nie próbuje przerobić struktury parent-child.
  Workaround: w Optimie używaj prostych SKU (matching simple products w Magento); configurable parent buduj w Magento ręcznie.

Naprawione w 3 rundach code review przed releaseem (24 bugi)

Pełny changelog wszystkich wersji z type-tagami (NEW / FIX / SECURITY / BREAKING) → /sisl-optima/changelog. Plany na v0.4.0 i dalej → /sisl-optima/roadmap. Best-of fixów przed v0.3.5:

• v0.3.1 #1: F1 multi-store cichy no-op gdy catalog/price/scope=Global — teraz wymusza Website scope, error message z linkiem do admin.
• v0.3.1 #5: F3 schema referował Knt_TS_Mod które nie istnieje na realnej Optima 2024 — przepisane na full-sync (KntKarty nie ma datetime column).
• v0.3.1 #6: F2 schema referował TrN_DataOst które nie istnieje — przepisane na TrN_TS_Mod.
• v0.3.2 #7: InvoiceManagementInterface::prepareInvoice w Magento 2.4.7 chce Order obj, nie entity_id — naprawione przejściem na InvoiceService.
• v0.3.3 #1+2: partial WZ/FA tworzyły pełną wysyłkę/fakturę → poprawione przez TraElem join + buildItemQtysMap.
• v0.3.4 #5: duplicate SKU w jednym order (custom options) — fixed przez FIFO queue per SKU.
• v0.3.4 #7: HMAC + polskie znaki (Brzęczyszczykiewicz w order forward) — fixed explicit UTF-8 w StreamReader.

Każdy bug znaleziony i naprawiony zanim mógł uderzyć w klienta. Stabilność jest priorytetem.

Jak zgłosić bug

Mail na [email protected] z opisem:

• wersja modułu (zobacz app/code/Sisl/Optima/etc/module.xml);
• wersja .NET service (zobacz /healthz endpoint);
• kroki repro;
• logi Magento (var/log/system.log) + .NET service (logs/).

Krytyczne bugi naprawiamy w ciągu 24 godzin roboczych — to gwarancja w cenie 300 zł/mies.

Pełen kontekst projektu (co synchronizować, jak wybrać architekturę, KSeF, etapy wdrożenia) opisaliśmy w przewodniku integracji Magento ↔ Comarch Optima.