# VILMAL — masterplan po ścieżce OSKAR

## 1. Mandat i stan wyjściowy

Właściciel zatwierdził rozpoczęcie etapów 0+1: utrwalenie planu i katalog tkanin tylko do odczytu. To powrót do `.devin/ASTRA-MASTERPLAN.md`, nie zgoda na nowe płatne generacje, publikację, eksport live ani zmianę zatwierdzonych materiałów. Kolejne etapy pozostają roadmapą. Bieżące dowody wykonania i blokery: `.devin/STAN.md`.

Źródła: `PROMPT_STARTOWY.md`, `.devin/ASTRA-MASTERPLAN.md`, `.devin/ASTRA-OFERTA-OSKAR.md`, `.devin/STAN.md`, `docs/BASE-KONTRAKT.md`, `services/recolor/STAN.md` oraz kod. Historyczne statusy nie zastępują weryfikacji.

- Stos pozostaje: Node.js zgodny z package.json (>=22.12), Fastify 5, TypeScript, SQLite WAL, React 19/Vite, zod, sharp, pdfkit, node:test/tsx. Recolor: istniejący serwis Python v7 wywoływany przez backend. Bez nowych zależności w etapie 1.
- Działają domeny produktów, faktów i historii, źródeł, tkanin, odcieni, wariantów, wersji mediów, akceptacji SHA, zadań, sesji i audytu. Istnieją galeria, przypisania referencji do ujęć, recolor, dokumenty, QA, rewizje treści, renditions i snapshoty ofertowe.
- OSKAR był eksportowany live po zgodzie przez jednorazowe skrypty, także jako kopia. Brakuje ogólnej obsługi eksportu w panelu, nie całej implementacji zapisu. Wideo pozostaje odroczone; zapis katalogowy Base nie dowodzi publikacji Allegro.
- Recolor v7 jest podłączony w `server/src/domain/recolor.ts`. Starsza notatka o integracji jako następnym kroku jest historyczna. Nie zmieniamy silnika ani jego kontraktu.
- Przed etapem 1 routing zawsze pokazywał ProductPage; Tkaniny/Zadania/Ustawienia nie miały widoków. Brak kreatora, importu URL w runtime i ogólnego orkiestratora. Większość sekcji ProductPage renderuje się niezależnie od zakładki.
- Import FUJI/SIC oraz próbników TILIA istnieje jako skrypty offline. `source_url` i `fetched_at` już istnieją. Pola `official_image_path` i `photo_path` przechowują ID source_assets; `card_path` jest ścieżką względem originalsDir. Nie zmieniamy ich znaczenia.
- Odczyt DB przed wdrożeniem: TILIA i ARENA po 17 odcieni; 34 próbki oficjalne i 17 zdjęć Vilmax. Status kolekcji w obu rekordach: confirmed. Statusy i uwagi odczytujemy z DB, bez automatycznego potwierdzania lub korygowania danych.

Selektywna adaptacja w przyszłości: parser i słowniki Bobochic z Cockpitu, wzorce payloadu Base z istniejących skryptów i wskazanych repo. Inspekcja przed adaptacją; zero runtime dependencies od sąsiednich repo. Fallback adaptera Bobochic generujący dane ze sluga nie przechodzi do produkcyjnego importu.

## 2. Docelowy UX i mapa ekranów

Start po logowaniu → NOWY PRODUKT lub PRODUKTY. Produkty → lista rzeczywistych rekordów i gotowość paczki → przestrzeń produktu. Nowy produkt można utworzyć ręcznie z materiałów hali; URL dostawcy jest opcjonalną pomocą, nie warunkiem.

Kreator/przestrzeń produktu: materiały i fakty → galeria → warianty i tkaniny → dokumenty → wideo → oferty kanałowe → wysyłka do Base. Możliwy powrót do poprzednich kroków; serwer wylicza braki, nie wymusza pozornego postępu.

Mapa docelowa (hash routing można zachować):
- `#/` — powitanie i dwa wejścia.
- `#/produkty` — lista; `#/produkty/nowy` — kreator; `#/produkty/:slug` — produkt.
- `#/tkaniny` — katalog; `#/tkaniny/:code` — odcienie, oficjalne próbki, zdjęcia Vilmax, parametry, karta i powiązane produkty.
- `#/zadania` — status, rzeczywisty postęp, błędy i wznowienia.
- `#/ustawienia` — uprawnienia i stan konfiguracji bez sekretów.

Etap 1 dodaje tylko rzeczywiste trasy tkanin, nie nowe puste moduły. Dostępne są loading/empty/error/retry, powrót i bezpośredni link do kolekcji, nawigacja klawiaturą, widok mobilny. Brak zdjęcia nie jest zastępowany jednolitym chipem jako rzekomą próbką. HEX jest orientacyjny; fotografia i monitor nie gwarantują zgodności koloru. Parametry z karty nie są certyfikatem całego mebla.

## 3. AI-orkiestrator i rejestr akcji

Warstwa serwerowa nad istniejącymi domenami, nie drugi pipeline. Każda akcja ma nazwę, schemat zod wejścia/wyjścia, uprawnienia, preconditions, tryb odczyt/zapis, wycenę, wymagane zgody, idempotency key i audit. LLM nie dostaje bezpośredniego SQL, dowolnego fetch ani sekretów.

| Akcja docelowa | Warunki i bramka |
|---|---|
| inspectProduct / suggestNextStep | Odczyt stanu; reguły zwracają krok, powód i listę braków |
| importFromUrl / importFabric | Dozwolony dostawca, safe fetcher, trwały job; wynik niepotwierdzony |
| proposeFacts | Propozycje z dowodami; potwierdza uprawniony człowiek |
| generateShot | Właściwe referencje, jawna wycena i zaakceptowany limit |
| buildRecolor | Zatwierdzony master i właściwe potwierdzone wejścia; bez zmiany silnika |
| renderCard / composeOffer | Potwierdzone fakty i wersje wybranych materiałów |
| reviewDeliverable | Werdykt doradczy przypięty do wersji/SHA |
| exportDraft | Lokalny podgląd, bez komunikacji z zapisowym API |
| submitApprovedExport | Osobna zgoda na snapshot, cel i zakres; trwały outbox |

MVP działa na regułach. Opcjonalny adapter LLM proponuje wywołania tych samych akcji; backend ponownie sprawdza uprawnienia, koszty i zgodność wersji. Nie istnieje narzędzie AI do końcowej akceptacji za człowieka.

## 4. Maciuś — nadzór jakości

Rozwijamy istniejący moduł: preflight przed generacją, ocena wyniku względem przypisanej referencji, kontrola strony/odcienia, porównanie dokumentu z faktami, zgodność treści i paczki. Każdy werdykt ma wersję kryteriów, źródło/model, SHA, wynik, uzasadnienie i audit.

Reguły deterministyczne nie są oceną vision. Niedostępny provider daje jawne „nieocenione”. Brak/negatywny werdykt jest widoczny przy decyzji; ewentualny wyjątek wymaga świadomej decyzji człowieka z uzasadnieniem. Niezgodne fakty, nieaktualne zależności i brak właściwego medium blokują eksport niezależnie od pozytywnej oceny AI. Zmiana wejścia unieważnia zależne wyniki, nie usuwa historii.

## 5. Kreator, ingest i model danych

Obecny enum faktów: `unknown | unverified | confirmed`. Słowo „proposed” w mandacie oznacza propozycję biznesową, nie istniejącą wartość enum. Import zapisuje `unverified`; historia i dowody pozostają. Nie wprowadzamy cichej migracji statusów.

Docelowy przepływ:
1. Operator tworzy produkt ręcznie lub podaje URL. Serwer sprawdza uprawnienia i dostawcę, zapisuje job przed pobraniem.
2. Safe fetcher: HTTPS, dozwolone hosty dostawcy/CDN, brak userinfo i niestandardowych portów, blokada adresów prywatnych/loopback/link-local IPv4/IPv6, kontrola DNS i przypięcie sprawdzonego adresu połączenia przeciw rebindingowi. Każdy redirect i każdy URL medium przechodzi te same kontrole. Limity czasu, bajtów po dekompresji, liczby plików i przekierowań; walidacja MIME i podpisów.
3. Adapter Bobochic parsuje pobrany snapshot, bez zastępczych danych ze sluga. Fragment URL określający wariant zapisujemy osobno od adresu HTTP. Nieznane pola lub niejednoznaczna strona wymagają decyzji.
4. Snapshot HTML/PDF i media trafiają do trwałego storage z SHA, URL, datą, wersją parsera i relacją importu. HTML nie jest uruchamiany w przeglądarce. Zdjęcia vendora pozostają referencjami z jawnym pochodzeniem/prawami, nie gotową galerią Vilmax.
5. Fakty dostawcy (`vendor.*`, `vendor_fabric.*`) nie nadpisują potwierdzonych faktów Vilmax. Osobne propozycje i konflikty z wersją bazową; decyzja człowieka zachowuje dowód. EAN/cena/cechy tkaniny vendora nie stają się danymi własnego produktu.
6. Osobny import dostawcy tkaniny/karty tworzy kolekcję, odcienie i źródła. Nie usuwa odcieni nieobecnych w kolejnej karcie. Próbki oficjalne i zdjęcia hali mają odrębne role.
7. Po wyborze kolekcji i dozwolonych stron powstaje macierz wariantów. Docelowo relacja produkt–tkanina może istnieć przed utworzeniem wariantów; dziś katalog pokazuje powiązania wynikające z variants.
8. Istniejące moduły galerii/recolora/dokumentów/oferty korzystają z potwierdzonych danych. Potwierdzenie tkaniny nie jest akceptacją mediów.

Import ma trwałe kroki i manifest pozycji, idempotencję żądania oraz osobną operację odświeżenia tworzącą nową wersję. Sam URL nie wystarcza jako wieczny klucz deduplikacji. Retry po awarii kontynuuje pozycje, nie tworzy drugiego produktu. Transakcje DB i atomowy zapis plików; odzyskiwanie przerwanych operacji. Dedup pliku po SHA nie może zgubić relacji z kolejnym produktem/źródłem (obecny globalny dedup ingest wymaga rozwiązania przy imporcie).

Gotowość sekcji: galeria wymaga właściwych referencji; recolor mastera, potwierdzonej strony/kotwicy i próbek; dokumenty kompletu wymaganych faktów; oferta właściwych zatwierdzonych wersji; eksport aktualnego snapshotu, danych celu i osobnej zgody. Brak to brak, nie wartość domyślna.

## 6. Oferta kanałowa → Base.com

Reużywamy offerContent, offerPackage, renditions i snapshoty. Jeden zatwierdzony snapshot zasila teksty, PDF, galerie i eksport. Profile kanałów nie są niezależnymi kopiami faktów. Przed generalizacją trzeba usunąć zależność treści od profili zaszytych dla OSKAR/FUJI.

Docelowo panel: podgląd wariantu/kanału → walidacja → snapshot → akceptacja paczki → osobna zgoda na cel i zakres zapisu → outbox → kontrolowany zapis → read-back per pozycja. Timeout po wysłaniu oznacza uzgadnianie wyniku, nie ślepe ponowne tworzenie. Zachowujemy zewnętrzne ID. Stan „zapisano w Base” nie jest stanem „opublikowano w Allegro”.

`BASE-KONTRAKT.md` to badanie historyczne; przed nowym eksportem ponowna walidacja kontraktu i celu. Historycznie uzupełnionych danych OSKAR nie oznaczamy automatycznie jako 17 aktualnych braków. Sekrety tylko backend; dry-run nie uruchamia dispatchu. Bez logistyki, checkoutu i bezpośredniej publikacji marketplace w Vilmal.

## 7. Roadmapa i odbiór

| Etap | Działający wycinek | Kryterium odbioru / dowód |
|---|---|---|
| 0 — plan | Ten dokument, osiem obszarów mandatu | Oddzielone stan kodu, historia i projekt; zakres 0+1 zatwierdzony |
| 1 — katalog (obecny zakres) | Uwierzytelnione GET fabrics/detail/shades, próbki i karta; trasy Tkanin | TILIA/ARENA z DB; brak pliku jawny; media bez ścieżek dyskowych; test auth/404/path escape/MIME/powiązań; brak zapisów danych i recoloru |
| 2 — bezpieczny ingest | Safe fetcher i trwałe kroki importu | Test redirect/DNS/SSRF/limity/restart/idempotencja; bez pustych produkcyjnych endpointów udających import |
| 3 — nowy produkt | Powitanie NOWY PRODUKT/PRODUKTY, lista, kreator ręczny i Bobochic, review faktów | Realny URL → lokalne źródła → unverified → decyzja → produkt; fixture parsera, konflikty, powtórzenie i odświeżenie |
| 4 — tkaniny w kreatorze | Import SIC/karty, powiązanie produktu i kolekcji, warianty | URL/karta → odcienie → potwierdzenie → macierz; stabilne ID i istniejące dane; guard wejść recolora bez przebudowy silnika |
| 5 — przestrzeń produktu | Rzeczywiste sekcje etapów, zadania, ustawienia w uzasadnionym zakresie | Brak zaszytych nazw/cen i fałszywego routingu; odświeżenie, błędy, klawiatura i mobile |
| 6 — orkiestrator i QA | Rejestr akcji, regułowy następny krok, rozszerzenie Maciusia | Akcje przechodzą te same zgody i walidację co UI; test uprawnień, kosztów, stale SHA; brak auto-approval |
| 7 — paczka i wysyłka | Ogólne oferty, outbox i panel eksportu | Suchy podgląd bez sekretów, restart/częściowy sukces/read-back; live tylko na osobną zgodę |
| 8 — wdrożenie | Samodzielny runtime, backup/restore, monitoring | Uzgodniony serwer/TLS, odtworzenie DB+mediów, restart i smoke bez sąsiednich repo |

Wideo i karta materiałów/badań pozostają jawnymi pracami przekrojowymi, nie znikają z zakresu. Wideo: adapter I2V, trwały request ID, poster/MP4 i ludzkie QA; uruchomienie dopiero po potwierdzeniu zakresu i pozostałego budżetu. Karta dowodów wymaga dokumentów i zatwierdzonych twierdzeń. Brak tych funkcji nie może być maskowany atrapą „gotowe”.

Po zmianach: `npm test`, `npx tsc --noEmit -p tsconfig.json`, `npx tsc --noEmit -p web/tsconfig.json`, `npm run build`. Regresje recoloru bez płatnych generacji; przy zmianach integracji także testy Python i kontrolowany benchmark jasny/ciemny/nasycony, L/P, master/SHA/maska/cache. Odbiór UI obejmuje realne kliknięcia i desktop/mobile, a mediów oględziny; build nie zastępuje QA. Wyniki faktycznie uruchomionych kontroli zapisujemy w STAN.

## 8. Ryzyka i granice

- Niespójne historyczne listy kandydatów OSKAR: późniejsze wpisy opisują zatwierdzenia. Nie regenerować ani nie przywracać odrzuconych na podstawie starszej listy. Etap 1 nie dotyka tych danych.
- Materiały w DB mogą być brakujące, niepotwierdzone lub zawierać uwagi ograniczające użycie parametrów. Katalog jest podglądem ewidencji, nie walidatorem certyfikacji; pokazuje uwagi bez pomijania zastrzeżeń.
- Publiczne stare endpointy mediów/produktów wymagają przeglądu bezpieczeństwa przed wdrożeniem. Nowe endpointy katalogu i jego mediów od początku wymagają sesji i kontroli ścieżek.
- Strony dostawców mogą zmienić HTML albo ograniczyć dostęp. Błąd parsera pozostaje błędem, nie danymi demonstracyjnymi. Zawartość źródeł traktujemy jako nieufną, także wobec LLM.
- Dostęp do vision, prawa do materiałów, dane handlowe/GPSR i warunki serwera wymagają aktualnej weryfikacji. Nie kopiujemy historycznych sekretów ani ID kont na ślepo.
- Nowa tkanina o innym splocie wymaga osobnej walidacji wyglądu; recolor barwy nie gwarantuje realistycznego texture-swap.
- Etap 1 nie migruje schematu, nie zapisuje mediów, nie wywołuje AI, nie zmienia jobs, fact verification ani approvals. Istniejące niezacommitowane zmiany użytkownika pozostają nietknięte.