orderPRO/.paul/PROJECT.md

orderPRO

What This Is

Aplikacja do zarządzania zamówieniami pobieranymi z wielu źródeł sprzedaży (Allegro, Erli, własne sklepy internetowe). Umożliwia generowanie etykiet przewozowych u kurierów oraz docelowo zarządzanie produktami i stanami magazynowymi w jednym miejscu.

Core Value

Sprzedawca może obsługiwać zamówienia ze wszystkich kanałów sprzedaży i nadawać przesyłki bez przełączania się między platformami.

Current State

Attribute	Value
Version	1.0.0
Status	v1.5 Complete
Last Updated	2026-03-25

Requirements

Validated (Shipped)

• Integracja z Allegro — pobieranie zamĂłwieĹ„
• Generowanie etykiet (InPost)
• Performance: N+1 subqueries fix, DB indexes — Phase 7
• Stability: SSL verification, cron throttle — Phase 7
• UX: orderpro-to-allegro disable, lista zamĂłwieĹ„ poprawki — Phase 7
• Unit tests: AllegroTokenManager, AllegroOrderImportService (12 testĂłw) — Phase 7
• InPost ShipX API: natywny provider niezaleĹĽny od Allegro — Phase 7
• DB Foundation: tabele receipts, receipt_configs, receipt_number_counters + company_settings extended — Phase 8
• Konfiguracja paragonĂłw (CRUD w Ustawienia > KsiÄ™gowość) — Phase 9
• Wystawianie paragonĂłw z zamĂłwienia (formularz, snapshoty, atomowe numerowanie) — Phase 10
• PodglÄ…d i wydruk paragonu (HTML+PDF, dompdf) — Phase 11
• Sekcja KsiÄ™gowość — lista paragonĂłw z filtrami, paginacjÄ…, eksportem XLSX — Phase 12
• DB Foundation: tabele email_mailboxes, email_templates, email_logs — Phase 13
• Skrzynki pocztowe SMTP (CRUD + test poĹ‚Ä…czenia) — Phase 13
• Szablony wiadomoĹ›ci e-mail (CRUD + Quill.js + system zmiennych + zaĹ‚Ä…czniki) — Phase 14
• WysyĹ‚ka e-mail z zamĂłwieĹ„ (resolwer zmiennych, zaĹ‚Ä…czniki, log) — Phase 15
• Zadania automatyczne — reguĹ‚y zdarzenie/warunki/akcje (CRUD + watcher/executor) — Phase 16
• OstrzeĹĽenie i potwierdzenie przy duplikacie paragonu — Phase 17
• Print Queue Backend: REST API + API key auth + CRUD kluczy — Phase 18
• UI Integration: przycisk Drukuj, bulk print, kolejka wydruku — Phase 19
• Windows Client: C# WinForms tray app, polling API, druk etykiet PDF — Phase 20
• WyĹ›wietlanie nazwy integracji zamiast generycznego "shopPRO" na liĹ›cie i szczegółach zamĂłwienia — Phase 21
• Naprawa zapisu REGON, BDO, KRS i logo w ustawieniach firmy — Phase 22
• Presety przesyĹ‚ek — customowe przyciski szybkiego wypeĹ‚niania formularza (CRUD + autofill + zarzÄ…dzanie) — Phase 23-25
• RÄ™czny numer przesyĹ‚ki — dodawanie tracking number bez API przewoĹşnika — Phase 26
• Tracking backend — dwupoziomowe statusy dostawy, 3 implementacje providerĂłw, cron handler — Phase 27
• Tracking UI i ustawienia crona — statusy dostawy i konfiguracja harmonogramu — Phase 28-29
• UI readability tweak - rozdzielenie koloru przyciskow akcji od naglowkow sekcji (button primary distinction) - Phase 30
• Usuniecie bulk print "Drukuj etykiety" z listy zamowien (/orders/list) wraz z endpointem bulk - Phase 40
• Ograniczenie szumu logow importu Allegro i deduplikacja wpisow activity log - Phase 41
• Automatyzacja: event shipment.status_changed + warunki statusowe przesylki - Phase 42
• Usuwanie wpisu z kolejki druku etykiet z panelu ustawien - Phase 43

Active (In Progress)

• Brak aktywnych faz w milestone v1.5 (40-43 zakonczone)

Planned (Next)

• ZarzÄ…dzanie produktami
• ZarzÄ…dzanie stanami magazynowymi

Out of Scope

• [Do zdefiniowania podczas planowania]

Target Users

Primary: Sprzedawcy wielokanałowi (Allegro, Erli, własny sklep)

• ObsĹ‚ugujÄ… zamĂłwienia z wielu platform jednoczeĹ›nie
• PotrzebujÄ… szybkiego nadawania przesyĹ‚ek
• ChcÄ… jednego miejsca do zarzÄ…dzania sprzedaĹĽÄ…

Context

Business Context: Rynek narzędzi do zarządzania sprzedażą wielokanałową (podobne rozwiązania: base.com, apilo.com). Aplikacja budowana jako własne rozwiązanie.

Technical Context: PHP (XAMPP/Laravel), integracje z API marketplace'Ăłw (Allegro, Erli) oraz API przewoĹşnikĂłw (InPost i inne).

Constraints

Technical Constraints

• PHP/XAMPP — Ĺ›rodowisko Windows lokalne
• Medoo + prepared statements (bez sklejania SQL)
• Brak natywnych alert()/confirm() — uĹĽywać window.OrderProAlerts
• Metody pomocnicze string/date/color → App\Core\Support\StringHelper (nie powielać w klasach)
• ZarzÄ…dzanie tokenami OAuth Allegro → App\Modules\Settings\AllegroTokenManager
• Kompozycja obiektĂłw crona → App\Modules\Cron\CronHandlerFactory (jedyne miejsce new AllegroIntegrationRepository i in. w kontekĹ›cie crona)
• Pole CSRF w formularzach HTTP: zawsze _token (nie _csrf_token)

Business Constraints

• [Do zdefiniowania podczas planowania]

Key Decisions

Decision	Rationale	Date	Status
Własne rozwiązanie zamiast gotowego SaaS	Pełna kontrola nad funkcjonalnością	2026-03-12	Active
AllegroTokenManager wydzielony z 4 klas OAuth	Eliminacja duplikacji logiki odświeżania tokenów	2026-03-12	Active
StringHelper jako final static class w Core/Support	Centralizacja 19 kopii helperĂłw string/date/color z 15+ klas	2026-03-12	Active
CronHandlerFactory jako jedyne miejsce kompozycji crona	Application.php i bin/cron.php były rozsynchronizowane — 2 bugi w bin/cron.php	2026-03-13	Active
Pole CSRF w formularzach: _token (nie _csrf_token)	Standardyzacja na nazwę używaną przez większość kodu (10+ kontrolerów); eliminacja ryzyka pomyłki przy nowych formularzach	2026-03-13	Active
Flash messages: Flash::set('module.type') / Flash::get('module.type', '')	Jeden wzorzec w całej aplikacji; eliminacja bezpośrednich zapisów $_SESSION	2026-03-13	Active
validateXxxInput(): ?string i validateXxxAccess(): ?Response jako wzorce helperów walidacji	Redukcja return statements do ≤3; spójny wzorzec kontrolerów	2026-03-13	Active
God class split via move-method bez zmiany logiki	ShopproOrdersSyncService 39→9 metod; AllegroIntegrationController 35→25 — czysty podział przez ekstrakcję klas	2026-03-13	Active
AllegroIntegrationController pozostaje przy 25 metodach (nie ≤15)	Pełny podział wymaga AllegroImportScheduleService — poza zakresem v0.1	2026-03-13	Active
dg/bypass-finals do testów final classes	Wszystkie klasy final — mockowanie przez bypass-finals zamiast usuwania final	2026-03-15	Active
InPost ShipX API zamiast Allegro WZA remap	InpostIntegrationRepository jest pod ShipX; niezależność od Allegro	2026-03-15	Active
vendor/ w ftp-kr ignore	Auto-upload dev deps na serwer powodował Fatal Error	2026-03-15	Active
Snapshot pattern: seller/buyer/items jako JSON w receipts	Dane zamrożone w momencie wystawienia — niezależne od przyszłych zmian źródła	2026-03-15	Active
Atomowe numerowanie paragonĂłw: INSERT ON DUPLICATE KEY UPDATE	Bezpieczne generowanie kolejnych numerĂłw bez race conditions	2026-03-15	Active
Moduł Accounting w osobnym namespace	App\Modules\Accounting — separacja od Settings	2026-03-15	Active
ATTACHMENT_TYPES jako centralna mapa typów załączników	Rozszerzalność: nowy typ = 1 linia w tablicy PHP, bez zmian DB/widoku	2026-03-16	Active
Quill.js 2.0.3 CDN dla edytora szablonĂłw	Brak build pipeline w projekcie; CDN prostszy	2026-03-16	Active

Success Metrics

Metric	Target	Current	Status
Liczba zintegrowanych źródeł zamówień	≥3	2 (Allegro, Erli)	In progress
Generowanie etykiet	Działa	InPost	In progress

Tech Stack

Layer	Technology	Notes
Framework	PHP (custom/Laravel)	XAMPP lokalnie
Frontend	HTML/CSS/JS + SCSS	jQuery Alerts module
Database	MySQL (Medoo)	Prepared statements
Auth	Sesje PHP
Integracje	Allegro API, Erli API	PrzewoĹşnicy: InPost (ShipX), Apaczka
Testing	PHPUnit 11.5 + dg/bypass-finals	Unit tests w tests/Unit/

Specialized Flows

See: .paul/SPECIAL-FLOWS.md

Quick Reference:

• /feature-dev → Nowe funkcjonalnoĹ›ci i integracje (optional)
• /code-review → PrzeglÄ…d kodu przed UNIFY (optional)
• /frontend-design → Komponenty UI i widoki (optional)
• /simplify → Refaktoryzacja po implementacji (optional)

---

PROJECT.md — Updated when requirements or context change Last updated: 2026-03-25 after Phase 40-43 completion (Operational Workflow Cleanup)