# AdReactions - Koncepcja platformy v0.4

> Status dokumentu: robocza koncepcja produktu. Spina w jedną całość model domenowy,
> mapowanie cel biznesowy -> metryki -> usługi AI, zasady wymienialności modeli,
> propozycję modelu danych oraz zakres MVP 1.0.

---

## Spis treści

1. [Streszczenie wykonawcze](#1-streszczenie-wykonawcze)
2. [Wizja produktu i propozycja wartości](#2-wizja-produktu-i-propozycja-wartości)
3. [Słownik pojęć (model domenowy)](#3-słownik-pojęć-model-domenowy)
4. [Architektura logiczna platformy](#4-architektura-logiczna-platformy)
5. [Organizacje, role i uprawnienia](#5-organizacje-role-i-uprawnienia)
6. [Moduły platformy](#6-moduły-platformy)
7. [Cykl życia eksperymentu (kreator 4 kroków)](#7-cykl-życia-eksperymentu-kreator-4-kroków)
8. [Katalog celów analiz kognitywnych](#8-katalog-celów-analiz-kognitywnych)
9. [Warstwa AI - proces analizy](#9-warstwa-ai---proces-analizy)
10. [Wymienialność modeli AI (Proces <-> Model)](#10-wymienialność-modeli-ai-proces---model)
11. [Struktura i generowanie raportu](#11-struktura-i-generowanie-raportu)
12. [Propozycja modelu danych (Supabase)](#12-propozycja-modelu-danych-supabase)
13. [Kredyty, plany, przestrzeń dyskowa](#13-kredyty-plany-przestrzeń-dyskowa)
14. [Logi i audyt](#14-logi-i-audyt)
15. [Bezpieczeństwo, prywatność, zgodność](#15-bezpieczeństwo-prywatność-zgodność)
16. [Internacjonalizacja](#16-internacjonalizacja)
17. [Przepływy użytkownika (use case'y)](#17-przepływy-użytkownika-use-casey)
18. [Zakres MVP 1.0 vs roadmapa](#18-zakres-mvp-10-vs-roadmapa)

---

## 1. Streszczenie wykonawcze

**AdReactions** to aplikacja SaaS do predykcyjnego badania percepcji i emocji wobec kreacji
reklamowych, bez udziału realnych respondentów. Zamiast organizować kosztowne badania
eye-trackingowe na ludziach, użytkownik wgrywa kreację (reklamę, baner, opakowanie, ekran UI)
i otrzymuje syntetyczny eye-tracking oraz predykcję reakcji emocjonalnej generowane przez
modele AI, w tym autorski model **ASM PNS**.

Cechą wyróżniającą produkt jest odwrócenie perspektywy. Użytkownik nie konfiguruje metryk,
tylko wybiera **cel biznesowy** ("Która kreacja lepiej sprzedaje?", "Czy CTA działa?"),
a system sam dobiera technologię analizy (Eye Tracking, Facial Coding, ET+FC), zestaw metryk
i sposób interpretacji wyniku. Raport nie podaje surowych liczb, lecz **rekomendację
z uzasadnieniem** ("Wariant B lepiej realizuje cel sprzedażowy, ponieważ...").

**Zakres MVP 1.0** obejmuje pełną platformę SaaS (organizacje, projekty, eksperymenty,
galeria kreacji, raporty), kreator eksperymentu, panel administracyjny z wymienialnymi
modelami AI oraz pipeline analizy złożony z:

- detekcji obiektów i predykcji uwagi wzrokowej (saliency statyczna z trzech modeli
  z walidacją krzyżową),
- wizualizacji czasowych i map dynamicznych 1-20 s,
- ścieżek fiksacji (scanpath),
- Facial Coding (mapa emocji),
- predykcji różnicowanych dla grupy docelowej,
- warstwy interpretacji kognitywnej, która zamienia metryki w rekomendację.

Procesy, dla których model własny nie jest jeszcze gotowy (saliency czasowa, scanpath,
Facial Coding, warunkowanie demografią, analiza kognitywna), startują na modelach publicznych
podpiętych przez plugin. Modele własne zastępują je w kolejnym kroku, w najbliższym czasie.
Dzięki temu pełen zakres MVP działa od startu, a jakość predykcji rośnie wraz z wdrażaniem
modeli własnych.

---

## 2. Wizja produktu i propozycja wartości

### 2.1. Problem

Klasyczne badania eye-trackingu i kodowania mimiki są drogie, czasochłonne i wymagają
rekrutacji respondentów oraz sprzętu. Decyzje o wyborze wariantu kreacji zapadają więc
często "na wyczucie", już po poniesieniu kosztów produkcji.

### 2.2. Propozycja wartości

- **Szybkość i koszt** - predykcja w minutach zamiast tygodni, bez respondentów.
- **Decyzyjność** - wynik prowadzi do konkretnej rekomendacji ("wybierz B"), a nie do tabeli liczb.
- **Porównywalność** - test A / AB / ABC zestawia warianty na jednej osi metryk.
- **Segmentacja** - predykcje dla zdefiniowanej grupy docelowej (demografia, profile).
- **Powtarzalność** - eksperyment można sklonować i zmodyfikować jako bazę kolejnego.

### 2.3. Kluczowa innowacja: cel zamiast metryk

To centralny mechanizm produktu, rozwinięty w sekcji 8. Pięć warstw prowadzi od wyboru celu
do rekomendacji:

```
[1] Użytkownik wybiera CEL BIZNESOWY        np. "Która kreacja lepiej sprzedaje?"
            |
[2] System pokazuje OPIS POMOCNICZY         "Sprawdź, który wariant prowadzi uwagę do CTA..."
            |
[3] System rekomenduje TYP ANALIZY          ET+FC (z możliwością zmiany przez użytkownika)
            |
[4] System dobiera METRYKI "pod spodem"     udział uwagi na CTA, walencja pozytywna, ...
            |
[5] Raport zwraca REKOMENDACJĘ Z UZASADNIENIEM  "Wariant B..., ponieważ..."
```

### 2.4. Odbiorcy (persony)

- **Marketer / brand manager** - wybiera wariant kampanii, potrzebuje rekomendacji.
- **Agencja kreatywna** - testuje koncepty przed prezentacją klientowi.
- **Projektant UX / CRO** - sprawdza, czy ekran prowadzi użytkownika do celu.
- **Super administrator (operator platformy)** - zarządza organizacjami, planami i modelami AI.

---

## 3. Słownik pojęć (model domenowy)

| Pojęcie | Definicja |
|---|---|
| **Organizacja** | Najwyższy kontener klienta. Ma administratora, użytkowników, projekty, plan, pulę kredytów i przestrzeń dyskową. |
| **Użytkownik** | Niezależne konto osoby. Zakłada maksymalnie jedną własną organizację, ale przez zaproszenia może należeć do wielu. |
| **Projekt** | Kontener eksperymentów wraz z galerią kreacji projektu. Typ pochodny: ET / FC / ET+FC. |
| **Eksperyment** | Pojedyncza analiza predykcyjna 1-3 kreacji wg zadanego celu, grupy i parametrów. |
| **Kreacja** | Materiał graficzny (PNG/JPEG): reklama, baner, opakowanie, ekran. Jednostka wejściowa analizy. |
| **Galeria** | Zbiór kreacji na poziomie organizacji (współdzielona) i projektu (podzbiór roboczy). |
| **Obiekt** | Rozpoznany element treści obrazu (osoba, butelka, logo) z ramką (bbox). Źródło: AI lub użytkownik. |
| **AOI** (Area of Interest) | Obszar o znaczeniu marketingowym (CTA, Logo, Key Visual). Źródło: AI (sugestia) lub użytkownik. |
| **Metryka** | Mierzalny wskaźnik percepcji lub emocji (np. udział uwagi na AOI, walencja pozytywna). |
| **Cel** | Pytanie biznesowe wybrane przez użytkownika. Mapuje się na typ analizy i zestaw metryk. |
| **Grupa docelowa** | Profil odbiorcy (wiek, płeć, miejsce, wykształcenie, dochód, neuroatypowość, preset). |
| **Raport** | Złożenie wizualizacji, metryk i interpretacji kognitywnej dla eksperymentu. |
| **Proces AI** | Pojedynczy krok analizy (np. detekcja obiektów, predykcja saliency, Facial Coding). |
| **Model AI** | Silnik realizujący proces (LLaVA, ASM, DeepGaze, Gemini, Opus), wymienny na inny (sekcja 10). |
| **Plugin / adapter** | Kod, który podpina dany model pod proces i tłumaczy kontrakt procesu na API modelu. |
| **Plan** | Pakiet przypisany organizacji: kredyty startowe, kredyty miesięczne, przestrzeń dyskowa. |
| **Kredyt / coin** | Wewnętrzna jednostka rozliczeniowa pobierana za eksperymenty i rozszerzenie dysku. |

### Diagram relacji encji (uproszczony)

```
Organizacja 1───* Użytkownik           Organizacja 1───* Projekt
     │                                       │
     │ 1                                     │ 1
     *                                       *
  Galeria(org) *───* Kreacja            Eksperyment
     ▲                  │ *                   │ 1
     │                  │                     ├──* Kreacja (1-3: A/B/C)
  Galeria(projekt) *────┘                     ├──* Obiekt
                                              ├──* AOI
                                              ├──1 Cel + Grupa docelowa + Parametry
                                              └──1 Raport ──* WynikModelu / Metryka
```

---

## 4. Architektura logiczna platformy

### 4.1. Warstwy

```
┌──────────────────────────────────────────────────────────────────────┐
│  FRONTEND  - React + shadcn/ui + Tailwind                            │
│  Panele: Administracyjny · Użytkownika · Organizacji                 │
│  Kreator eksperymentu (4 kroki) · Studio (obiekty/AOI) · Raport      │
└───────────────────────────────┬──────────────────────────────────────┘
                                │ REST / RPC
┌───────────────────────────────▼───────────────────────────────────────┐
│  BACKEND  - Node.js                                                   │
│  • API platformy (CRUD: org, projekty, eksperymenty, galeria)         │
│  • Orkiestrator analizy AI (sekcja 9) - równoległe wywołania usług    │
│  • Warstwa metryk (dane modeli + AOI -> wskaźniki)                    │
│  • Warstwa interpretacji kognitywnej (cel + metryki -> rekomendacja)  │
│  • Generator raportu (PDF + wizualizacje)                             │
│  • Rejestr modeli AI + router "Proces <-> Model" + pluginy (sekcja 10)│
└──────────────┬────────────────────────────────────┬───────────────────┘
               │                                    │ HTTP POST (multipart)
┌──────────────▼──────────────────┐   ┌─────────────▼──────────────────────┐
│  SUPABASE                       │   │  WARSTWA MODELI AI                 │
│  • PostgreSQL (model danych)    │   │  Własne (API): LLaVA · Gr. DINO ·  │
│  • Storage (kreacje, artefakty) │   │  DeepGaze · UNISAL · ASM (PNS)     │
│  • Auth (konta, sesje, role)    │   │  Publiczne (plugin): Gemini · Opus │
└─────────────────────────────────┘   └────────────────────────────────────┘
```

### 4.2. Stack technologiczny

- **Front-end:** React, shadcn/ui, Tailwind.
- **Back-end:** Node.js.
- **Baza, Storage, Auth:** Supabase.
- **Warstwa AI:** modele własne wystawione za REST API oraz modele publiczne podpięte przez
  pluginy, orkiestrowane przez backend Node.js (sekcja 9).

### 4.3. Orkiestracja

Logika procesu AI jest opisana niezależnie od narzędzia orkiestrującego i przeznaczona
do implementacji jako komponent backendu Node.js: równoległe wywołania usług modelowych,
agregacja wyników i obsługa błędów (sekcja 9). Pojedyncze modele pozostają niezależnymi
usługami za REST API, a modele publiczne są podpinane przez pluginy (sekcja 10).

---

## 5. Organizacje, role i uprawnienia

### 5.1. Hierarchia

Organizacja ma administratora, użytkowników i projekty. Role w systemie:

- **Super administrator** - operator platformy. Ma dostęp do panelu administracyjnego,
  w którym zarządza organizacjami, użytkownikami, modelami AI oraz planami. Może wejść
  w dowolną organizację i poruszać się w niej tak jak administrator. Ma dostęp do logów
  systemowych i logów eksperymentu.
- **Administrator organizacji** - powstaje podczas rejestracji organizacji. Może przekazać
  swoje prawa innemu użytkownikowi. Ma uprawnienia do każdego projektu, rozliczeń, planów
  i ustawień organizacji. Tworzy projekty i eksperymenty bez ograniczeń.
- **Użytkownik** - każdy użytkownik ma własne, niezależne konto. Uprawnienia otrzymuje
  na poziomie organizacji oraz na poziomie konkretnego projektu.

### 5.2. Uprawnienia użytkownika

Uprawnienia działają na dwóch poziomach.

**Poziom organizacji** - administrator może nadać użytkownikowi prawa:

- tworzenia nowych projektów,
- przeglądania wszystkich projektów,
- edytowania wszystkich projektów,
- usuwania wszystkich projektów,
- zapraszania użytkowników do wszystkich projektów.

**Poziom projektu** - użytkownik może też dostać uprawnienia w obrębie pojedynczego projektu:

| Poziom w projekcie | Zakres |
|---|---|
| Zarządzanie | usuwanie, edycja i zapraszanie użytkowników |
| Edycja | edycja i zapraszanie użytkowników |
| Przeglądanie | tylko podgląd |

### 5.3. Macierz uprawnień

| Uprawnienie | Super Admin | Administrator | Użytkownik |
|---|:--:|:--:|:--:|
| Panel administracyjny | ✓ | - | - |
| Zarządzanie organizacjami, użytkownikami, modelami, planami | ✓ | - | - |
| Wejście w dowolną organizację (jak administrator) | ✓ | - | - |
| Rozliczenia, plany, kredyty, ustawienia organizacji | ✓ | ✓ | - |
| Tworzenie projektów | ✓ | ✓ | wg nadanych uprawnień |
| Przeglądanie wszystkich projektów | ✓ | ✓ | wg nadanych uprawnień |
| Edycja wszystkich projektów | ✓ | ✓ | wg nadanych uprawnień |
| Usuwanie wszystkich projektów | ✓ | ✓ | wg nadanych uprawnień |
| Zapraszanie do wszystkich projektów | ✓ | ✓ | wg nadanych uprawnień |
| Uprawnienia w obrębie pojedynczego projektu | ✓ | ✓ | wg roli w projekcie |

---

## 6. Moduły platformy

### 6.1. Panel administracyjny (tylko Super Administrator)

**Sitebar:** Dashboard · Organizacje · Użytkownicy · Plany · Proces i modele AI · Logi.

- **Dashboard** - KPI z dynamiką 30 dni (graficznie i liczbowo): liczba organizacji,
  użytkowników, kreacji i przeprowadzonych eksperymentów.
- **Organizacje** - lista z wyszukiwarką. Wejście w organizację pozwala zarządzać jej danymi,
  użytkownikami, kredytami (startowymi i miesięcznymi), aktywować, dezaktywować
  i archiwizować organizację.
- **Użytkownicy** - lista z wyszukiwarką (dane podstawowe).
- **Plany** - definiowanie planów subskrypcji: nazwa, opis, liczba kredytów na start,
  liczba kredytów miesięcznie, przestrzeń dyskowa. Plan przypisuje się do organizacji
  (szczegóły w sekcji 13).
- **Proces i modele AI** - zamknięta lista procesów realizowanych w eksperymentach
  i przypisany do każdego z nich model AI. To miejsce wymiany modelu na inny (sekcja 10).
- **Logi** - logi całego systemu z filtrowaniem (użytkownik, organizacja, zakres dat, typ operacji).

### 6.2. Panel użytkownika (po zalogowaniu)

Z tego miejsca użytkownik przechodzi do wybranej organizacji, zakłada nową organizację
(maksymalnie jedną własną) oraz zmienia swoje dane, e-mail i hasło. Do pozostałych
organizacji dołącza przez zaproszenia.

### 6.3. Panel organizacji (Administrator i użytkownicy)

**Sitebar:** Dashboard · Projekty · Galeria.
**Topbar:** wybór organizacji · wyszukiwarka (projekty, kreacje, eksperymenty).
Sitebar chowa się na urządzeniach mobilnych, a obszarem roboczym jest Workspace.

- **Dashboard** - KPI: liczba kreacji w galerii, liczba projektów, liczba eksperymentów.
  Przyciski szybkich akcji: *Dodaj kreację do galerii*, *Utwórz nowy projekt*,
  *Przejdź do ostatniego eksperymentu*. Niżej lista projektów z wejściem.
- **Galeria** - zarządzanie kreacjami organizacji: upload, kafelki ostatnio dodanych,
  pełna galeria (slider). Klik w kreację otwiera drawer po prawej: powiększenie oraz lista
  eksperymentów i projektów, w których użyto kreacji, z przejściem do nich.
- **Projekty** - lista projektów (nazwa, typ ET/FC/ET+FC) i przycisk *Nowy projekt*.
  - **Panel projektu** - przegląd, weryfikacja konfiguracji eksperymentów, usuwanie
    projektu i eksperymentów, udostępnianie projektu.
  - **Galeria projektu** - kreacje dodane do projektu (z galerii organizacji lub własne
    projektu). W jednym eksperymencie maksymalnie **3 kreacje (A, B, C)**. Liczbę
    materiałów ogranicza przestrzeń dyskowa planu, rozszerzalna za kredyty (sekcja 13).
  - **Galeria eksperymentów** - wszystkie eksperymenty projektu z kluczowymi parametrami
    (technologia ET/FC/ET+FC, typ testu, autor).

---

## 7. Cykl życia eksperymentu (kreator 4 kroków)

Każdy eksperyment przechodzi przez czterostopniowy kreator. Poniżej rozszerzenie
z mapowaniem na warstwę AI (sekcja 9) i metryki (sekcja 8).

### 7.1. Krok 1 - Cel i grupa docelowa

- **Cel** - wybór ze słownika 15 celów (sekcja 8) lub opis własny. Cel determinuje
  rekomendowany typ analizy i zestaw metryk.
- **Grupa docelowa** - cechy metryczkowe lub gotowe presety:

| Kategoria | Wartości |
|---|---|
| **Wiek** | Młodzież (do 25) · Dorośli (26-64) · Seniorzy (65 i więcej) |
| **Płeć** | Kobieta · Mężczyzna |
| **Miejsce zamieszkania** | do 19 tys. · 20-50 tys. · 50-100 tys. · 100-500 tys. · >500 tys. |
| **Wykształcenie** | Podstawowe · Zasadnicze zawodowe · Średnie · Wyższe · Wyższe / tytuł naukowy |
| **Dochód** | Niski (≤MK) · Średni (MK-ŚK) · Wysoki (>ŚK) |
| **Neuroatypowość** | Brak / Neurotypowy · ASD · ADHD · Zaburzenia depresyjne |
| **Profile opisowe (presety)** | NT (Neurotypowy) · DE (Wykluczony cyfrowo) · SE (Silver Economy) · GZ (Gen-Z / Digital Native) |

Profil grupy docelowej wpływa na predykcję. Dane profilowe wykorzystują modele zewnętrzne
podpięte przez plugin (np. Gemini), które przyjmują je jako część promptu. Modele wewnętrzne
(saliency) nie różnicują wyniku po demografii. Kategoria neuroatypowości pozostaje
w profilu jako metadana, ale w MVP nie różnicuje predykcji i nie służy do sugerowania
diagnozy (sekcja 15).

### 7.2. Krok 2 - Parametry

- **Rodzaj analizy:** Eye Tracking · Facial Coding · ET+FC. Typ jest rekomendowany przez
  cel i edytowalny przez użytkownika.
- **Rodzaj testu:** A (1 kreacja) · AB (2 kreacje) · ABC (3 kreacje).
- **Czas obserwacji:** 1 s · 3 s · 5 s · 10 s · 15 s · 20 s. Parametr steruje mapami
  czasowymi i klatkami wizualizacji (saliency czasowa, sekcja 9).
- **Zakres raportu:** wybór komponentów raportu (lista w sekcji 11).

### 7.3. Krok 3 - Studio

Edycja warstwy semantycznej obrazu przed analizą.

- **Obiekty** - użytkownik korzysta z identyfikacji AI (LLaVA -> Grounding DINO), a następnie
  koryguje lub usuwa wskazania, albo zaznacza i nazywa obszary ręcznie. Słownik kategorii:
  Architektura, Celebryci, Chemia, Edukacja, Elektronika, Finanse, Handel, Kosmetyki,
  Logistyka, Militaria, Motoryzacja, Osoby, Przemysł, Przyroda, Sport, Ubrania, Zwierzęta,
  Żywność, Inne.
- **AOI** - na wejściu użytkownik dostaje AOI wskazane automatycznie przez AI. Może je
  zmienić, usunąć lub dodać własne. Słownik AOI: CTA, Dowód społeczny, Key Visual, Kod QR,
  Kolorystyka, Kontakt, Korzyści, Kupon, Layout, Logo, Mapa, Nagłówek, Narracja, Numer
  katalogowy, Regulaminy, Slogan, Ton komunikacji, Treść, Typografia, Tło.

> **Obiekt vs AOI:** obiekt to *co jest na obrazie* (detekcja treści), a AOI to *obszar
> o znaczeniu marketingowym* (jednostka analizy uwagi). Automatyczne AOI powstają z osobnego
> procesu sugestii (sekcja 9), a użytkownik zatwierdza je lub zmienia w Studio.

### 7.4. Krok 4 - Raport

Generowanie i prezentacja wyników, szczegóły w sekcji 11.

### 7.5. Logi eksperymentu

Super administrator po wejściu w eksperyment widzi pełne logi: wszystkie działania
i ustawienia użytkownika oraz wszystkie dane wysłane do modeli AI i od nich odebrane.
To audyt predykcji, istotny przy wymianie modeli (sekcja 10).

---

## 8. Katalog celów analiz kognitywnych

Mechanizm "cel zamiast metryk" (sekcja 2.3). Pełne opisy 15 celów znajdują się w dokumencie
celów analiz kognitywnych. Poniżej tabela zbiorcza jako referencja konfiguracyjna (źródło
prawdy dla domyślnego doboru typu analizy i metryk).

| # | Cel (nazwa UI) | Rekom. analiza | Sygnał kluczowy |
|---|---|:--:|---|
| 1 | Która kreacja lepiej sprzedaje? | ET+FC | uwaga na produkt/benefit/CTA + niskie napięcie |
| 2 | Czy odbiorca widzi najważniejszy przekaz? | ET (opc. ET+FC) | zauważalność i czas dotarcia do komunikatu |
| 3 | Czy CTA działa? | ET+FC | widoczność CTA + brak oporu emocjonalnego |
| 4 | Która kreacja zostaje w pamięci? | ET+FC | uwaga + pobudzenie (high arousal) |
| 5 | Która kreacja najlepiej buduje markę? | ET+FC | uwaga na logo + pozytywna walencja |
| 6 | Czy kreacja budzi negatywne reakcje? | FC (opc. ET+FC) | walencja negatywna + high arousal na elemencie |
| 7 | Czy przekaz jest zrozumiały? | ET (opc. ET+FC) | logiczna ścieżka, brak chaosu i powrotów |
| 8 | Czy kreacja działa od pierwszych sekund? | ET+FC | pierwsza fiksacja + impuls emocjonalny 1-3 s |
| 9 | Czy kreacja angażuje, czy jest obojętna? | FC (opc. ET+FC) | aktywacja vs low arousal / neutral |
| 10 | Który styl komunikacji działa lepiej? | ET+FC | rozkład uwagi tekst/obraz + profil emocji |
| 11 | Które opakowanie lepiej przyciąga klienta? | ET+FC | marka/wariant/benefit + atrakcyjność |
| 12 | Czy ekran prowadzi użytkownika do celu? | ET+FC | ścieżka do akcji + komfort/frustracja |
| 13 | Która kreacja najlepiej pasuje do grupy docelowej? | ET+FC | różnice między segmentami |
| 14 | Która kreacja jest najbezpieczniejsza? | ET+FC | niska negatywność i ambiwalencja, czytelność |
| 15 | Która kreacja najbardziej się wyróżnia? | ET+FC | siła pierwszej fiksacji + aktywacja |

MVP 1.0 udostępnia wszystkie 15 celów. Cele oparte na emocjach (np. 6, 9) korzystają
z Facial Coding, a cele wrażliwe na kolejność i czas (np. 7, 8) z map czasowych i scanpath.
Procesy te startują na modelach publicznych przez plugin, a modele własne zastępują je
w najbliższym czasie (sekcja 9).

**Zasada interpretacji wspólna dla wszystkich celów:** raport rozróżnia warianty pozytywne,
neutralne i ryzykowne (np. "wyróżnialność pozytywna" vs "ryzykowna"), a rekomendacja zależy
od kontekstu kampanii (performance vs wizerunek) i grupy docelowej.

---

## 9. Warstwa AI - proces analizy

Proces jest bezstanowy: jedno wejście (obraz) daje jeden komplet wyników.

### 9.1. Pipeline i procesy

```
        Wejście: obraz (PNG/JPEG)
                  │  preprocessing -> bytes + base64 + mime + (w,h)
   ┌──────────────┼───────────────┬───────────────┬───────────────┐
   ▼ (łańcuch A, sekwencyjny)     ▼ (B)           ▼ (C)           ▼ (D)
┌──────────┐                  ┌──────────┐   ┌──────────┐   ┌──────────────┐
│ LLaVA    │ etykiety         │ DeepGaze │   │ UNISAL   │   │ ASM (PNS)    │
│ (VLM)    │───┐              │(saliency)│   │(saliency)│   │ 2× saliency  │
└──────────┘   ▼              └────┬─────┘   └────┬─────┘   └──────┬───────┘
        ┌─────────────┐            │              │                │
        │ Grounding   │            └──────────────┴────────────────┘
        │ DINO (boxy) │                          │ agregacja saliency
        └─────┬───────┘                          ▼
              ▼                     ┌──────────────────────────────┐
        detekcja obiektów           │ Artefakty: overlay boxów ·   │
              │                     │ nakładka heatmapy (suwak) ·  │
              ▼                     │ porównanie 2×2 (walid. krzyż)│
        sugestia AOI                └──────────────┬───────────────┘
                                                   ▼
                              ┌────────────────────────────────────────┐
                              │ Procesy na pluginie (MVP 1.0):         │
                              │ saliency czasowa 1-20 s · scanpath ·   │
                              │ Facial Coding (mapa emocji) ·          │
                              │ warunkowanie demografią                │
                              └────────────────────┬───────────────────┘
                                                   ▼
                              ┌────────────────────────────────────────┐
                              │ Warstwa metryk (backend):              │
                              │ dane modeli + AOI -> wskaźniki         │
                              └────────────────────┬───────────────────┘
                                                   ▼
                              ┌─────────────────────────────────────────┐
                              │ Analiza kognitywna (model + cel):       │
                              │ metryki -> rekomendacja z uzasadnieniem │
                              └─────────────────────────────────────────┘
```

**Zamknięta lista procesów:**

| # | Proces | Model (domyślny) | Status |
|---|---|---|:--:|
| 1 | Ekstrakcja typów obiektów | LLaVA (lub publiczny przez plugin) | ✅ |
| 2 | Detekcja obiektów (bboxy) | Grounding DINO | ✅ |
| 3 | Predykcja saliency #1 | DeepGaze | ✅ |
| 4 | Predykcja saliency #2 | UNISAL | ✅ |
| 5 | Predykcja saliency centralna | ASM (PNS) | ✅ |
| 6 | Sugestia AOI | model publiczny / mapowanie z obiektów | 🔁 |
| 7 | Saliency czasowa (mapy dynamiczne 1-20 s) | model czasowy | 🔁 |
| 8 | Scanpath (ścieżka fiksacji) | model scanpath | 🔁 |
| 9 | Facial Coding (mapa emocji) | model publiczny przez plugin | 🔁 |
| 10 | Warunkowanie predykcji demografią | model zewnętrzny (prompt + profil) | 🔁 |
| 11 | Analiza kognitywna (rekomendacja) | model publiczny lub prywatny | 🔁 |

> Legenda: ✅ działa na modelu własnym · 🔁 w MVP na modelu publicznym (plugin), model własny
> w najbliższym czasie.

**Zależności i równoległość:**

- Łańcuch A jest sekwencyjny (Grounding DINO potrzebuje etykiet z LLaVA).
- Gałęzie A, B, C, D są niezależne i wykonują się równolegle. Czas to czas najwolniejszej gałęzi.
- Awaria jednej gałęzi nie przerywa całości. Degradacja jest stopniowa (per-task try/except),
  a pozostałe artefakty powstają normalnie.
- Warstwa metryk i analiza kognitywna działają po zebraniu wyników saliency, FC i scanpath.

### 9.2. Model danych wyników

Modele zwracają dane matematyczne (liczbowe), nie tylko obrazy. Na ich podstawie powstają
zarówno wskaźniki, jak i wizualizacje.

```
AnalysisResult {
  image     : ImageInput { bytes, base64, mime, width, height }
  detection : DetectionResult { objects: [{ object_type, bbox_xyxy, score }] }
  saliency  : SaliencyData[]  // intensywność uwagi (liczbowo) + mapa; deepgaze, unisal, asm
  temporal  : SaliencyFrame[] // przedziały czasu: intensywność uwagi w czasie
  scanpath  : ScanpathPoint[] // sekwencja fiksacji: kolejność, czas, intensywność
  emotion   : EmotionData     // walencja, pobudzenie, frustracja, ambiwalencja, komfort (wartości)
}
```

### 9.3. Artefakty wizualizacyjne

1. **Overlay detekcji** - ramki per obiekt, kolor per typ, podpis `typ + score%`,
   pozycje w procentach wymiarów (responsywność).
2. **Nakładka heatmapy** - mapa uwagi z suwakiem przezroczystości 0-100%.
3. **Porównanie 2×2** - DeepGaze / UNISAL / ASM detailed / ASM general; wspólny suwak,
   technika inwersji (blend luminancji: biel = wysoka uwaga, efekt reflektora).
4. **Mapy dynamiczne 1-20 s** - sekwencja klatek saliency w czasie.
5. **Scanpath** - ścieżka fiksacji z kolejnością kontaktu z AOI.
6. **Mapa emocji** - wizualizacja metryk Facial Coding na kreacji.

### 9.4. Mapowanie: technologie badawcze (produkt) <-> procesy AI (pipeline)

| Warstwa produktu | Realizacja w AI | Status |
|---|---|:--:|
| **Eye Tracking** - mapy uwagi, udział uwagi na AOI | DeepGaze · UNISAL · ASM | ✅ |
| Rozumienie treści - obiekty, opis | LLaVA + Grounding DINO | ✅ |
| **ET czasowy** - mapy dynamiczne 1-20 s | saliency w interwałach czasu | 🔁 |
| **ET** - ścieżki fiksacji (scanpath) | model scanpath | 🔁 |
| **Facial Coding** - walencja, pobudzenie, frustracja | model emocji (publiczny przez plugin) | 🔁 |
| **Analiza kognitywna** - rekomendacja z uzasadnieniem | warstwa interpretacji nad metrykami | 🔁 |
| **Predykcje per grupa docelowa** | warunkowanie modelu demografią | 🔁 |

### 9.5. Warstwa metryk i lista wskaźników

Modele zwracają dane matematyczne: dla uwagi liczbową intensywność w obszarach kreacji,
dla scanpath i map czasowych dodatkowo kolejność, czas i intensywność kontaktu, a dla
Facial Coding wartości emocji. Wskaźniki produktowe powstają w backendzie przez zestawienie
tych danych z obszarami AOI zdefiniowanymi w Studio: dane uwagi w granicach AOI dają udział
uwagi, a dane scanpath kolejność i czas kontaktu z AOI. Mapy cieplne i pozostałe wizualizacje
renderują się z tych samych danych.

Lista wskaźników w MVP:

| Metryka | Źródło | Status |
|---|---|:--:|
| Udział uwagi na AOI (%) | dane uwagi w granicach AOI | ✅ |
| Ranking AOI wg uwagi | dane uwagi w granicach AOI | ✅ |
| Mapa cieplna statyczna | dane uwagi | ✅ |
| Porównanie kreacji wg uwagi | dane uwagi × N kreacji | ✅ |
| Czas do pierwszej fiksacji | scanpath | 🔁 |
| Kolejność kontaktu z AOI (ścieżka AOI) | scanpath | 🔁 |
| Liczba powrotów wzroku | scanpath | 🔁 |
| Mapy dynamiczne 1-20 s | saliency czasowa | 🔁 |
| Walencja, pobudzenie, frustracja, ambiwalencja, komfort | model emocji (FC) | 🔁 |
| Różnice metryk między segmentami | warunkowanie demografią | 🔁 |

Ścieżka AOI opiera się na danych scanpath (kolejność, czas, intensywność), a nie na
przybliżeniu rankingiem. Procesy oznaczone 🔁 startują na modelach publicznych przez plugin,
a po dostarczeniu modeli własnych ich przypisanie zmienia się w panelu bez zmian w reszcie
pipeline'u.

---

## 10. Wymienialność modeli AI (Proces <-> Model)

W MVP 1.0 musi istnieć możliwość zmiany modelu realizującego dany proces na inny (np. publiczny
Gemini lub Opus) z poziomu panelu administracyjnego.

### 10.1. Zasada: rozdzielenie procesu od modelu

```
PROCES (stały, zamknięta lista)        MODEL (wymienny)             USŁUGA
─────────────────────────────         ─────────────────            ─────────────────
Ekstrakcja typów obiektów      ──►     LLaVA            ──►   API LLaVA (bez pluginu)
                                ╲─►    Gemini Vision    ──►   plugin -> API Gemini
Detekcja obiektów (boxy)       ──►     Grounding DINO   ──►   API (bez pluginu)
Predykcja saliency             ──►     DeepGaze/UNISAL  ──►   API (bez pluginu)
Predykcja saliency centralna   ──►     ASM (PNS)        ──►   API (bez pluginu)
Facial Coding                  ──►     model publiczny  ──►   plugin -> API dostawcy
Analiza kognitywna             ──►     prywatny/publiczny──►  API lub plugin
```

Każdy proces ma zdefiniowany kontrakt (wejście: obraz i parametry; wyjście: ustandaryzowany
typ, np. `labels[]`, `bboxes[]`, `SaliencyData`, `EmotionData`). Model jest podpięty przez kod
realizujący ten kontrakt, więc podmiana modelu nie zmienia reszty pipeline'u.

### 10.2. Wymiana modelu wymaga wymiany kodu kroku

Wymienić można model dla każdego procesu. Wymiana modelu pociąga jednak za sobą wymianę kodu,
który realizuje dany krok, tak aby zachować spójność całego procesu. Dla modeli publicznych
ten kod ma postać **pluginu**:

- **Model prywatny** dostępny przez API - bez pluginu (np. ASM, DeepGaze, UNISAL, Grounding
  DINO, LLaVA).
- **Model publiczny Gemini** - plugin (np. wskazanie obiektów dla modeli publicznych, FC,
  analiza kognitywna).
- **Model publiczny Opus** - plugin (analogicznie).

Plugin realizuje trzy rzeczy:

1. mapowanie wejścia procesu na format żądania modelu (multipart / JSON, prompt, parametry),
2. wywołanie (URL, schemat auth: Bearer, X-API-Key lub klucz dostawcy),
3. mapowanie wyjścia modelu na ustandaryzowany typ procesu.

### 10.3. Panel "Proces i modele AI"

Ekran administracyjny prezentuje zamkniętą listę procesów i dla każdego pozwala:

- wybrać aktywny model z listy zarejestrowanych modeli i pluginów,
- skonfigurować endpoint, klucze i parametry (host, token, prompt ASM, `max_objects`,
  `temperature`), przechowywane jako sekrety (Supabase / vault), nie w kodzie,
- wykonać test połączenia (health-check) i podejrzeć przykładowy wynik,
- wersjonować przypisanie model <-> proces, aby logi eksperymentu wskazywały, którym modelem
  policzono dany raport (powtarzalność, audyt, sekcja 7.5).

Konfiguracja modeli (adresy, klucze, parametry) jest zarządzana z panelu administracyjnego
i nie jest zaszyta w kodzie ani w konfiguracji testowej.

### 10.4. Modele własne vs publiczne

- **Własne (mikroserwisy za API):** LLaVA, Grounding DINO, DeepGaze, UNISAL, ASM (PNS).
  ASM jest rdzeniem przewagi produktu.
- **Publiczne (przez plugin):** Gemini, Opus i inne. Używane do procesów rozumienia treści
  (opis kreacji, lista obiektów), Facial Coding, analizy kognitywnej oraz warunkowania
  predykcji demografią. W MVP Facial Coding realizujemy jako model publiczny, nawet jeśli
  model prywatny nie będzie jeszcze dostępny.

Procesy, dla których model własny nie jest jeszcze gotowy (saliency czasowa, scanpath,
Facial Coding, warunkowanie demografią, analiza kognitywna), startują na modelach publicznych
przez plugin. Po dostarczeniu modeli własnych wystarczy zmienić przypisanie model <-> proces
w panelu, bez zmian w pozostałej części pipeline'u. To wprost pokazuje wartość rozdzielenia
procesu od modelu.

O tym, jaki model i plugin obsługuje dany proces, decyduje Super administrator. Klient nie
wybiera modelu, na którym pracuje jego eksperyment (sekcja 15).

---

## 11. Struktura i generowanie raportu

### 11.1. Komponenty raportu i ich źródła

| Komponent raportu | Źródło danych (proces/model) | Status MVP |
|---|---|:--:|
| Opis ogólny kreacji | LLaVA / opis (ew. prompt ASM) | ✅ |
| Lista obiektów | LLaVA + Grounding DINO | ✅ |
| Lista i opis AOI | sugestia AI + korekta użytkownika (Studio) | ✅ |
| Mapy cieplne statyczne | DeepGaze / UNISAL / ASM | ✅ |
| Mapy cieplne dynamiczne 1-20 s | saliency czasowa | 🔁 |
| Ścieżki fiksacji (scanpath) | model scanpath | 🔁 |
| Ścieżka AOI | scanpath (kolejność, czas, intensywność) | 🔁 |
| Mapa emocji (Facial Coding) | model emocji (publiczny przez plugin) | 🔁 |
| Analiza kognitywna (rekomendacja) | warstwa interpretacji (cel + metryki -> tekst) | 🔁 |
| Tabela porównawcza z metrykami | warstwa metryk (dane modeli + AOI) | ✅ |

### 11.2. Warianty A / AB / ABC

- Komponenty raportu powielają się per kreacja: AB to 2 kreacje, ABC to 3 kreacje.
- Sednem jest zestawienie porównawcze i rekomendacja "który wariant wygrywa i dlaczego",
  z rozbiciem na zwycięzcę ogólnego i zwycięzcę dla grupy docelowej (cel 13).
- Rekomendacja opiera się wyłącznie na policzonych metrykach i wskazuje metrykę, która ją
  uzasadnia (np. "B wygrywa, bo udział uwagi na CTA wynosi 38% vs 22% dla A"). Warstwa
  kognitywna nie formułuje wniosków bez pokrycia w danych.

### 11.3. Eksport i udostępnianie

- **Eksport:** PDF (raport).
- **Udostępnianie:** raport można udostępnić linkiem publicznym, bez wymogu logowania.
  Niezależnie działa udostępnianie wewnątrz organizacji wg uprawnień projektu (sekcja 5).
- **Klonowanie:** "Zmień ten eksperyment" lub "Edytuj" prowadzi do prośby o nową nazwę
  i przekierowania do Kroku 1 z prekonfiguracją z eksperymentu bazowego (sekcja 12).

---

## 12. Propozycja modelu danych (Supabase)

Szkic encji do walidacji (nazwy robocze). Klucze obce uproszczone.

```
plans(id, name, description, start_credits, monthly_credits, storage_quota_mb, created_by)
organizations(id, name, status[active|inactive|archived], plan_id, credits_balance,
              storage_quota_mb, created_at)
users(id, email, display_name, locale, created_at)
memberships(id, org_id, user_id, role[admin|member],
            org_permissions jsonb)   // create/view_all/edit_all/delete_all/invite_all
projects(id, org_id, name, type[ET|FC|ET_FC], created_by, created_at)
project_permissions(id, project_id, user_id, level[manage|edit|view])
creatives(id, org_id, project_id?, storage_path, mime, width, height, created_by)
experiments(id, project_id, name, goal_id, test_type[A|AB|ABC],
            analysis_type[ET|FC|ET_FC], observation_time_s, report_scope jsonb,
            target_group jsonb, base_experiment_id?, status, credits_cost, created_by, created_at)
experiment_creatives(id, experiment_id, creative_id, slot[A|B|C])
aois(id, experiment_id, creative_id, name, category, polygon jsonb, source[ai|user])
objects(id, experiment_id, creative_id, object_type, bbox_xyxy jsonb, score, source)
ai_runs(id, experiment_id, process_key, model_key, request jsonb, response_ref,
        status, duration_ms, created_at)        // audyt: który model, jaki wynik
saliency_maps(id, ai_run_id, source[deepgaze|unisal|asm_detailed|asm_general],
              data jsonb, storage_path, mime)   // dane matematyczne + mapa
temporal_maps(id, ai_run_id, creative_id, t_from_ms, t_to_ms, data jsonb, storage_path)
scanpaths(id, ai_run_id, creative_id, points jsonb)   // kolejność, czas, intensywność
emotion_maps(id, ai_run_id, creative_id, valence, arousal, frustration,
             ambivalence, comfort, storage_path?)
metrics(id, experiment_id, creative_id, aoi_id?, key, value)   // policzone wskaźniki
reports(id, experiment_id, pdf_path?, generated_at)
public_links(id, experiment_id, token, created_by, created_at, revoked_at?)
ai_processes(key, name, contract)              // zamknięta lista procesów
ai_models(key, name, kind[own|public], adapter, config_ref)    // rejestr modeli + pluginy
process_model_binding(process_key, model_key, active, version) // Proces <-> Model (sekcja 10)
credit_pricing(id, test_type, analysis_type, cost_credits)     // koszt eksperymentu
audit_logs(id, org_id?, user_id?, action, target, payload jsonb, created_at)
```

Kluczowe dla wymagań:

- `ai_runs` i `process_model_binding` realizują wymienialność modeli oraz audyt predykcji
  (logi eksperymentu, sekcja 7.5).
- `base_experiment_id` realizuje klonowanie eksperymentu.
- `target_group jsonb` przechowuje profil grupy, który modele zewnętrzne biorą pod uwagę
  przy warunkowaniu predykcji.
- `plans`, `credit_pricing` i `credits_balance` realizują rozliczenia (sekcja 13).

---

## 13. Kredyty, plany, przestrzeń dyskowa

Super administrator definiuje w panelu plany subskrypcji. Plan obejmuje:

- nazwę,
- opis,
- liczbę kredytów na start,
- liczbę kredytów miesięcznie,
- przestrzeń dyskową.

Plan przypisuje się do całej organizacji. Kredyty są pobierane za poszczególne eksperymenty,
a koszt zależy od typu testu (i docelowo od typu analizy). Przykładowe stawki dla kreacji
graficznej:

| Eksperyment | Koszt |
|---|---|
| A | 5 kredytów |
| AB | 10 kredytów |
| ABC | 15 kredytów |

Przestrzeń dyskowa wynika z planu i jest rozszerzalna za kredyty. Pula kredytów miesięcznych
odnawia się w cyklu rozliczeniowym, a kredyty dokupione zasilają pulę globalną.

---

## 14. Logi i audyt

Dwa poziomy:

- **Logi systemowe** (panel administracyjny) - filtrowanie po użytkowniku, organizacji,
  zakresie dat i typie operacji.
- **Logi eksperymentu** (Super Administrator) - pełen ślad: działania i ustawienia
  użytkownika oraz wszystkie dane wysłane do modeli AI i od nich odebrane. Powiązane
  z `ai_runs` (sekcja 12): każda predykcja zapisuje proces, model, żądanie i referencję
  odpowiedzi. To podstawa audytu i powtarzalności, szczególnie po podmianie modelu (sekcja 10).

---

## 15. Bezpieczeństwo, prywatność, zgodność

- **Brak danych respondentów:** produkt generuje predykcje AI, nie zbiera danych od realnych
  osób. To istotnie obniża ryzyko RODO względem klasycznego eye-trackingu. Dane osobowe
  ograniczają się do kont użytkowników (auth Supabase).
- **Własność treści:** kreacje klientów to materiały chronione. Kontrola dostępu działa
  na poziomie organizacji i projektu, z izolacją danych między organizacjami (RLS w Supabase).
- **Sekrety:** klucze i hosty modeli poza kodem (vault / zmienne środowiskowe), nie w repo.
- **Modele publiczne:** o tym, który proces korzysta z modelu publicznego, decyduje Super
  administrator przez konfigurację procesu i pluginu. Klient nie wybiera modelu. Część analiz
  (Facial Coding, analiza kognitywna, warunkowanie demografią) korzysta z modeli publicznych,
  więc dla tych procesów kreacje opuszczają infrastrukturę własną na czas predykcji.
  Korzystanie z dostawców zewnętrznych jest opisane w regulaminie i polityce prywatności.
- **Neuroatypowość:** w MVP predykcje nie różnicują się po neuroatypowości, a komunikacja
  wyników nie sugeruje diagnozy.

---

## 16. Internacjonalizacja

- **Języki UI w MVP 1.0:** polski i angielski (kolejne w następnych wersjach).
- **Język raportu i interpretacji kognitywnej:** podąża za językiem wybranym przez
  użytkownika. Warstwa interpretacji generuje tekst w tym języku.
- **Prompt ASM:** traktowany jako parametr konfigurowalny (nie stała), niezależny od języka UI.

---

## 17. Przepływy użytkownika (use case'y)

### UC1 - Eksperyment ABC bez zmian w Studio (obiekty i AOI z AI)

1. Rejestracja. 2. Logowanie. 3. Utworzenie organizacji. 4. Dodanie kreacji do galerii.
5. Nowy projekt i eksperyment: cel, grupa docelowa, typ ABC z 3 kreacjami, parametry,
bez zmian w Studio. 6. Generowanie raportu. 7. Eksport PDF. 8. Udostępnienie linkiem
publicznym lub zaproszeniem z uprawnieniami projektu. 9. "Zmień ten eksperyment", nowa nazwa,
Krok 1 z prekonfiguracją.

### UC2 - Eksperyment ABC ze zmianami w Studio i segmentem

Jak UC1, z konkretną grupą docelową (np. Młodzież / Kobieta / miasto do 19 tys. / wyższe /
dochód średni / neurotypowy), celem "Która kreacja lepiej sprzedaje?", analizą ET+FC,
3 kreacjami, obiektami i AOI wskazanymi przez AI z korektą w Studio, eksportem PDF,
udostępnieniem (link publiczny lub zaproszenie) oraz "Edytuj" jako bazą kolejnego eksperymentu.

W pierwszej iteracji metryki ET+FC dla UC2 liczą modele publiczne podpięte przez plugin,
a modele własne zastępują je w najbliższym czasie (sekcja 9).

---

## 18. Zakres MVP 1.0 vs roadmapa

### W zakresie MVP 1.0

- Platforma SaaS: organizacje, role i uprawnienia, projekty, galeria (org + projekt), eksperymenty.
- Kreator eksperymentu (4 kroki), słowniki celów, obiektów, AOI i grup docelowych.
- Studio: automatyczne i ręczne obiekty oraz AOI (LLaVA + Grounding DINO + sugestia AOI).
- Pipeline AI: detekcja obiektów oraz saliency statyczna z 3 modeli (DeepGaze, UNISAL, ASM)
  z walidacją krzyżową i wizualizacjami (overlay, nakładka, porównanie 2×2).
- Saliency czasowa i mapy dynamiczne 1-20 s.
- Ścieżki fiksacji (scanpath) i ścieżka AOI.
- Facial Coding (mapa emocji) realizowany jako model publiczny.
- Predykcje różnicowane dla grupy docelowej (przez modele zewnętrzne).
- Warstwa interpretacji kognitywnej (rekomendacja z uzasadnieniem).
- Metryki udziału uwagi na AOI i porównanie wariantów. Raport i eksport PDF.
- Udostępnianie raportu linkiem publicznym.
- Panel administracyjny: organizacje, użytkownicy, plany, wymiana modeli AI
  (Proces <-> Model) i logi.

MVP obejmuje wszystkie 15 celów. Procesy, których modele własne nie są jeszcze gotowe,
startują na modelach publicznych przez plugin, a modele własne zastępują je w najbliższym
czasie. Wymiana sprowadza się do zmiany przypisania model <-> proces w panelu.

### Roadmapa (kolejne wersje)

- Eksporty XLS i AVI.
- Kolejne języki UI.

---

*Dokument roboczy v0.4.*