# AdReactions — Koncepcja platformy v0.2 (rozszerzona)

> **Status dokumentu:** rozszerzenie i ujednolicenie „Koncepcja 0.1 [KM]".
> Łączy w spójną całość źródła projektu i dokłada warstwy, których w wersji 0.1
> brakowało: model domenowy, mapowanie *cel biznesowy → metryki → usługi AI*,
> wymienialność modeli, propozycję modelu danych oraz jawne rozgraniczenie
> **zakresu MVP 1.0 od roadmapy**.
>
> Miejsca wymagające decyzji właściciela produktu oznaczono znacznikiem **[?]**
> i zebrano w osobnym pliku **`Pytania do koncepcji.md`**.

## Źródła zintegrowane w tym dokumencie

| Dokument | Co wnosi |
|---|---|
| `Koncepcja 0.1.md` | Produkt, role, moduły, UX, kreator eksperymentu, use case'y |
| `Opis celów analiz kognitywnych.md` | 15 celów biznesowych + mapowanie na metryki ET/FC |
| `Specyfikacja-procesu-AI.md` | Logika procesu AI: kontrakty usług, orkiestracja, model danych, roadmapa |
| `info.md` | Wymaganie: wymiana modelu AI na inny (np. Gemini, Opus) z poziomu panelu |

---

## 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, subskrypcje, przestrzeń dyskowa](#13-kredyty-subskrypcje-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 samodzielnie 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:** platforma SaaS (organizacje, projekty, eksperymenty, galeria kreacji, raporty), kreator eksperymentu, panel administracyjny z **wymienialnymi modelami AI**, oraz pipeline AI obejmujący detekcję obiektów i predykcję uwagi wzrokowej (trzy modele saliency z walidacją krzyżową). Facial Coding, wizualizacje czasowe i ścieżki fiksacji są zaplanowane jako kolejne, niezależne gałęzie pipeline'u (patrz §18).

---

## 2. Wizja produktu i propozycja wartości

### 2.1. Problem

Klasyczne badania eye-trackingu i kodowania mimiki (facial coding) 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 tabeli liczb.
- **Porównywalność:** test A / AB / ABC pozwala zestawić warianty na jednej osi metryk.
- **Segmentacja:** predykcje dla zdefiniowanej grupy docelowej (demografia, profile, neuroatypowość).
- **Powtarzalność:** eksperyment można sklonować i zmodyfikować jako bazę kolejnego.

### 2.3. Kluczowa innowacja: „cel zamiast metryk"

To centralny mechanizm produktu (rozwinięty w §8). Pięć warstw 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, Positive Valence, …
            │
[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 (pitch).
- **Projektant UX / CRO** — sprawdza, czy ekran prowadzi użytkownika do celu.
- **Super administrator (operator platformy)** — zarządza organizacjami i modelami AI.

---

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

Ujednolicenie nazewnictwa używanego w dalszej części dokumentu.

| Pojęcie | Definicja |
|---|---|
| **Organizacja** | Najwyższy kontener klienta. Ma administratora, użytkowników, gości, projekty, pulę kredytów i przestrzeń dyskową. |
| **Użytkownik** | Niezależne konto osoby. Może należeć do wielu organizacji [?]. |
| **Projekt** | Kontener eksperymentów + galeria kreacji projektu. Typ pochodny: ET / FC / ET+FC. |
| **Eksperyment** | Pojedyncza analiza predykcyjna 1–3 kreacji wg zadanego celu, grupy, 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 zainteresowania o znaczeniu marketingowym (CTA, Logo, Key Visual…). Źródło: AI lub użytkownik. |
| **Metryka** | Mierzalny wskaźnik percepcji/emocji (np. udział uwagi na AOI, Positive Valence). |
| **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 realizowany przez model (np. „detekcja obiektów", „predykcja saliency"). |
| **Model AI** | Konkretny silnik realizujący proces (LLaVA, ASM, DeepGaze…), wymienny na inny (§10). |
| **Kredyt / coin** | Wewnętrzna jednostka rozliczeniowa (eksperymenty, przestrzeń dyskowa). |

### 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 (§9) — równoległe wywołania usług          │
│  • Warstwa metryk (saliency ∩ AOI → wskaźniki)                        │
│  • Warstwa interpretacji kognitywnej (cel + metryki → rekomendacja)   │
│  • Generator raportu (PDF/XLS/wizualizacje)                           │
│  • Rejestr modeli AI + router „Proces ↔ Model" (§10)                  │
└──────────────┬────────────────────────────────────┬───────────────────┘
               │                                    │ HTTP POST (multipart)
┌──────────────▼──────────────────┐   ┌─────────────▼──────────────────────┐
│  SUPABASE                       │   │  WARSTWA MODELI AI (mikroserwisy)  │
│  • PostgreSQL (model danych)    │   │  LLaVA · Grounding DINO · DeepGaze │
│  • Storage (kreacje, artefakty) │   │  UNISAL · ASM (PNS) · [Gemini/Opus]│
│  • Auth (konta, sesje, role)    │   │  Wymienne wg konfiguracji procesu  │
└─────────────────────────────────┘   └────────────────────────────────────┘
```

### 4.2. Stack technologiczny (z Koncepcji 0.1)

- **Front-end:** React / shadcn/ui + Tailwind
- **Back-end:** Node.js
- **Baza, Storage, Auth:** Supabase
- **Warstwa AI:** mikroserwisy modelowe za REST API, orkiestrowane przez backend Node.js (§9).

### 4.3. Uwaga o orkiestracji

Logika procesu AI jest opisana **niezależnie od narzędzia orkiestrującego**
(`Specyfikacja-procesu-AI.md`) 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 (§9).
Pojedyncze modele (detekcja, saliency) pozostają niezależnymi mikroserwisami za REST API.

---

## 5. Organizacje, role i uprawnienia

### 5.1. Hierarchia

- **Super administrator** — operator platformy. Dostęp do panelu administracyjnego;
  zarządza organizacjami, użytkownikami i modelami AI. Może „wejść" w dowolną organizację
  i poruszać się w niej jak administrator. Ma dostęp do logów systemowych i logów eksperymentu.
- **Administrator organizacji** — powstaje przy rejestracji organizacji; prawa zbywalne na
  innego użytkownika. Pełny dostęp do projektów, rozliczeń, planów i ustawień organizacji.
- **Użytkownik** — niezależne konto; uprawnienia nadawane na poziomie organizacji i/lub projektu.
- **Gość** — wymieniony w strukturze organizacji; zakres uprawnień do doprecyzowania **[?]**
  (proponowane: dostęp tylko do udostępnionych raportów, bez tworzenia treści).

### 5.2. Macierz uprawnień (propozycja ujednolicająca)

Uprawnienia działają na dwóch poziomach: **organizacji** i **konkretnego projektu**.

| Uprawnienie | Super Admin | Admin org. | Użytkownik (org.) | Użytkownik (projekt) | Gość |
|---|:--:|:--:|:--:|:--:|:--:|
| Panel administracyjny | ✓ | — | — | — | — |
| Zarządzanie modelami AI | ✓ | — | — | — | — |
| Tworzenie projektów | ✓ | ✓ | wg uprawnień | — | — |
| Przeglądanie wszystkich projektów | ✓ | ✓ | wg uprawnień | — | — |
| Edycja wszystkich projektów | ✓ | ✓ | wg uprawnień | — | — |
| Usuwanie projektów | ✓ | ✓ | wg uprawnień | — | — |
| Zapraszanie do projektów | ✓ | ✓ | wg uprawnień | wg roli projekt. | — |
| Rozliczenia / plany / kredyty | ✓ | ✓ | — | — | — |
| Tworzenie / konfiguracja eksperymentu | ✓ | ✓ | ✓ | Editor | — |
| Podgląd raportu | ✓ | ✓ | ✓ | Editor / Viewer | Viewer (udostępniony) |

**Role w obrębie projektu** (przy udostępnianiu): **Editor** (edycja + zapraszanie) /
**Viewer** (tylko podgląd). W Koncepcji 0.1 pojawia się też wariant „usuwanie, edycja i
zapraszanie" — ujednolicić do 2–3 ról projektowych **[?]**.

---

## 6. Moduły platformy

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

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

- **Dashboard** — KPI z dynamiką 30 dni (graficznie + liczbowo): liczba organizacji,
  użytkowników, kreacji, przeprowadzonych eksperymentów.
- **Organizacje** — lista + wyszukiwarka; wejście w organizację pozwala zarządzać danymi,
  użytkownikami, **kredytami** (globalnymi i miesięcznymi), aktywować / dezaktywować /
  archiwizować organizację.
- **Użytkownicy** — lista + wyszukiwarka (dane podstawowe).
- **Proces i modele AI** — **zamknięta lista procesów** realizowanych w eksperymentach
  oraz przypisany do każdego model AI. To miejsce wymiany modelu na inny (szczegóły §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 może: przejść do wybranej organizacji, dodać nową organizację
(limit: jedna nowa organizacja **[?]** — doprecyzować, czy dotyczy zakładania, czy członkostwa),
zmienić dane, e-mail, hasło.

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

**Sitebar:** Dashboard · Projekty · Galeria.
**Topbar:** wybór organizacji · wyszukiwarka (projekty, kreacje, eksperymenty).
**Sitebar** chowa się na mobile; **Workspace** to obszar roboczy.

- **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*. Poniżej: lista projektów z wejściem.
- **Galeria** — zarządzanie kreacjami organizacji: upload, kafelki ostatnio dodanych,
  pełna galeria (slider). Klik w kreację → **drawer** po prawej: powiększenie + lista
  eksperymentów/projektów, w których użyto kreacji (z przejściem do nich).
- **Projekty** — lista projektów (nazwa, typ ET/FC/ET+FC), przycisk *Nowy projekt*.
  - **Panel projektu** — zarządzanie: przegląd, weryfikacja konfiguracji eksperymentów,
    usuwanie projektu/eksperymentów, udostępnianie projektu.
  - **Galeria projektu** — kreacje dodane do projektu (z Galerii organizacji lub własne projektu).
    W jednym eksperymencie maks. **3 kreacje (A, B, C)**. Liczba materiałów ograniczona
    przestrzenią dyskową subskrypcji (rozszerzalną za kredyty — §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 dopiętym
mapowaniem na warstwę AI (§9) i metryki (§8).

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

- **Cel** — wybór ze słownika 15 celów (§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+) *(ujednolicić próg — patrz [?])* |
| **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) |

> **Powiązanie z AI — kluczowa uwaga:** obecny pipeline (§9) **nie przyjmuje** parametrów
> demograficznych na wejściu. Model ASM PNS ma docelowo generować predykcje różnicowane
> dla grup, jednak mechanizm warunkowania (np. przez `prompt` ASM lub osobne wagi modelu)
> wymaga decyzji. **[?]** — patrz §9.5 i `Pytania do koncepcji.md`.

### 7.2. Krok 2 — Parametry

- **Rodzaj analizy:** Eye Tracking · Facial Coding · ET+FC *(rekomendowany przez cel,
  edytowalny przez użytkownika)*.
- **Rodzaj testu:** A (1 kreacja) · AB / AC / BC (2 kreacje) · ABC (3 kreacje).
  *Uwaga: Koncepcja 0.1 w jednym miejscu podaje A/AB/ABC, a w innym A/AB/AC/BC/ABC —
  ujednolicić.* **[?]**
- **Czas obserwacji:** 1s · 3s · 5s · 10s · 15s · 20s.
  > Parametr nabiera pełnego znaczenia dopiero z **mapami czasowymi** (roadmapa). Przy
  > obecnej, statycznej saliency służy do wyboru klatek wizualizacji statycznej. **[?]**
- **Zakres raportu:** wybór komponentów raportu (lista w §11).

### 7.3. Krok 3 — Studio

Edycja warstwy semantycznej obrazu przed analizą:

- **Obiekty** — użytkownik zaznacza obszary i nazywa je **lub** korzysta z **identyfikacji
  AI** (LLaVA → Grounding DINO), a następnie koryguje/usuwa. Słownik kategorii: Architektura,
  Celebryci, Chemia, Edukacja, Elektronika, Finanse, Handel, Kosmetyki, Logistyka, Militaria,
  Motoryzacja, Osoby, Przemysł, Przyroda, Sport, Ubrania, Zwierzęta, Żywność, Inne…
- **AOI** — analogicznie: ręcznie lub AI, z korektą. 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:** obiekty to *co jest na obrazie* (detekcja treści), AOI to *obszary o
> znaczeniu marketingowym* (jednostka analizy uwagi). Pipeline pewnie wykrywa **obiekty**;
> **AOI semantyczne** wymagają albo wskazania przez użytkownika, albo dodatkowego mapowania
> obiekt→AOI. **[?]**

### 7.4. Krok 4 — Raport

Generowanie i prezentacja wyników — szczegóły w §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 i odebrane z modeli AI** (audyt
predykcji — istotne przy wymianie modeli, §10).

---

## 8. Katalog celów analiz kognitywnych

Mechanizm „cel zamiast metryk" (§2.3). Pełne opisy 15 celów znajdują się w
`Opis celów analiz kognitywnych.md`; 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) | Negative Valence + High Arousal na elemencie |
| 7 | Czy przekaz jest zrozumiały? | ET (opc. ET+FC) | logiczna ścieżka, brak chaosu/powrotów |
| 8 | Czy kreacja działa od pierwszych sekund? | ET+FC | pierwsza fiksacja + impuls emocjonalny 1–3s |
| 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ść/ambiwalencja, czytelność |
| 15 | Która kreacja najbardziej się wyróżnia? | ET+FC | siła pierwszej fiksacji + aktywacja |

**Zasada interpretacji wspólna dla wszystkich celów:** raport rozróżnia warianty
**pozytywne / neutralne / 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

Sekcja opiera się na `Specyfikacja-procesu-AI.md` — opisie logiki procesu niezależnym od
narzędzia orkiestrującego. Proces jest **bezstanowy**: jedno wejście (obraz) → jeden komplet wyników.

### 9.1. Pipeline i usługi

```
        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ż)│
                                    └─────────────────────────────┘
```

**Pięć modeli / procesów (wg specyfikacji procesu AI):**

| # | Model | Proces | Endpoint (wzorzec) | Auth |
|---|---|---|---|---|
| 1 | **LLaVA** | ekstrakcja typów obiektów (open-vocabulary) | `/llava-api/v1/get-object-types` | Bearer |
| 2 | **Grounding DINO** | detekcja / bounding boxy | `/grounding-dino-api/v1/get-objects-bboxes` | Bearer |
| 3 | **DeepGaze** | predykcja saliency | `/v1/predict-heatmap` | Bearer |
| 4 | **UNISAL** | predykcja saliency (porównawcza) | `/unisal/process-image?as_base64=true` | X-API-Key |
| 5 | **ASM (PNS)** | 2× saliency, warunkowane promptem marketingowym | `/asmModel/process-image?prompt=…` | X-API-Key |

**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** → wykonywane **równolegle**; czas ≈ najwolniejsza gałąź.
- **Odporność:** awaria jednej gałęzi nie przerywa całości — degradacja stopniowa
  (`return_exceptions` / per-task `try/except`); pozostałe artefakty powstają normalnie.

### 9.2. Model danych wyników (z §4 specyfikacji)

```
AnalysisResult {
  image     : ImageInput { bytes, base64, mime, width, height }
  detection : DetectionResult { objects: [{ object_type, bbox_xyxy, score }] }
  saliency  : SaliencyMap[]   // deepgaze, unisal, asm_detailed, asm_general
}
```

### 9.3. Artefakty wizualizacyjne (warstwa prezentacji)

1. **Overlay detekcji** — ramki per obiekt, kolor per typ, podpis `typ + score%`,
   pozycje w procentach wymiarów (responsywność).
2. **Nakładka heatmapy** — pojedyncza mapa uwagi + suwak 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).

### 9.4. Mapowanie: technologie badawcze (produkt) ↔ usługi AI (pipeline)

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

> Legenda: ✅ objęte specyfikacją procesu (modele dostępne) · 🟡 roadmapa (§11 specyfikacji) · 🔵 nowy komponent.

### 9.5. Macierz wykonalności metryk w MVP (najważniejsza sekcja inżynierska)

Większość metryk z `Opis celów…` wymaga komponentów, których **nie ma** w obecnym
pipeline. To rozgraniczenie jest krytyczne dla zakresu MVP.

| Metryka (z celów) | Czego wymaga | Wykonalne w MVP? |
|---|---|:--:|
| Udział uwagi na AOI (%) | saliency statyczna ∩ AOI | ✅ tak |
| Ranking AOI wg uwagi | saliency ∩ AOI | ✅ tak |
| Mapa cieplna statyczna | saliency | ✅ tak |
| Porównanie kreacji wg uwagi | saliency × N kreacji | ✅ tak |
| Czas do pierwszej fiksacji | scanpath (wymiar czasu) | ❌ roadmapa |
| Kolejność kontaktu z AOI / „ścieżka AOI" | scanpath | ❌ roadmapa* |
| Liczba powrotów wzroku | scanpath | ❌ roadmapa |
| Mapy dynamiczne 1–20s | saliency czasowa | ❌ roadmapa |
| Ścieżki fiksacji | model scanpath | ❌ roadmapa |
| Positive/Negative Valence, Arousal, Frustration, Ambivalence, Comfort… | model emocji (FC) | ❌ roadmapa |
| Różnice metryk między segmentami | warunkowanie demografią | ❌ do zaprojektowania |

\* „Ścieżkę AOI" można w MVP **przybliżyć** rankingiem AOI wg intensywności saliency
(kolejność „od najsilniejszego"), zaznaczając, że to heurystyka, a nie prawdziwa sekwencja
fiksacji. **[?]**

**Wniosek:** w MVP z obecnym pipeline'em wiarygodnie policzymy metryki **udziału uwagi na
AOI** i ich **porównanie między wariantami** (cele silnie ET, np. #2, #7, częściowo #1, #3).
Cele oparte na **emocjach** (#6, #9) i **wymiarze czasu** (#8) wymagają roadmapowych modeli
FC / saliency czasowej, albo świadomego **ograniczenia zakresu MVP**. → decyzja właściciela
produktu (`Pytania do koncepcji.md`).

---

## 10. Wymienialność modeli AI (Proces ↔ Model)

Wymaganie z `info.md`: w MVP 1.0 musi istnieć możliwość **zmiany modelu realizującego dany
proces** na inny (np. publiczny **Gemini**, **Opus**), z poziomu panelu administracyjnego.

### 10.1. Zasada: rozdzielenie procesu od modelu

```
PROCES (stały, zamknięta lista)        MODEL (wymienny)             USŁUGA (endpoint)
─────────────────────────────         ─────────────────            ─────────────────
Ekstrakcja typów obiektów      ──►     LLaVA            ──►   http://{LLaVA}/llava-api/...
                                ╲─►    [Gemini Vision]  ──►   adapter → API Gemini
Detekcja obiektów (boxy)       ──►     Grounding DINO   ──►   .../get-objects-bboxes
Predykcja saliency #1          ──►     DeepGaze         ──►   /v1/predict-heatmap
Predykcja saliency #2          ──►     UNISAL           ──►   /unisal/process-image
Predykcja saliency (centralna) ──►     ASM (PNS)        ──►   /asmModel/process-image
[Mapa emocji — roadmapa]       ──►     [FC model]       ──►   …
```

Każdy **proces** ma zdefiniowany **kontrakt** (wejście: obraz [+ parametry]; wyjście:
ustandaryzowany typ — `labels[]`, `bboxes[]`, `SaliencyMap`). Model jest podpięty przez
**adapter** tłumaczący kontrakt procesu na konkretne API. Dzięki temu podmiana
LLaVA→Gemini nie zmienia reszty pipeline'u.

### 10.2. Wzorzec adaptera

Aby podpiąć nowy model (np. Gemini/Opus) trzeba dostarczyć **adapter** = kod realizujący:
1. **mapowanie wejścia** procesu → format żądania modelu (multipart / JSON, prompt, parametry),
2. **wywołanie** (URL, schemat auth: Bearer vs X-API-Key vs klucz dostawcy),
3. **mapowanie wyjścia** modelu → ustandaryzowany typ procesu (np. `labels[]`).

To realizuje zdanie z `info.md`: „powinien być dodany kod, który realizuje usługę".
Każdy proces = interfejs; każdy model = jego implementacja (adapter).

### 10.3. Panel „Proces i modele AI" (rozszerzenie)

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

- wybrać **aktywny model** (z listy zarejestrowanych adapterów),
- skonfigurować **endpoint / klucze / parametry** (host, token, prompt ASM, `max_objects`,
  `temperature`…) — przechowywane jako sekrety (Supabase / vault), nie w kodzie,
- wykonać **test połączenia** (health-check) i podgląd przykładowego wyniku,
- (zalecane) **wersjonować** przypisanie model↔proces, aby logi eksperymentu wskazywały,
  którym modelem policzono dany raport (powtarzalność, audyt — §7.5).

> W MVP konfiguracja modeli (adresy URL, token/klucz, parametry) jest zarządzana z panelu
> administracyjnego i przechowywana w magazynie sekretów (Supabase / vault), nie w kodzie.

### 10.4. Modele własne vs publiczne

- **Własne (mikroserwisy):** LLaVA, Grounding DINO, DeepGaze, UNISAL, ASM (PNS) — pełna
  kontrola, model ASM jest rdzeniem przewagi produktu.
- **Publiczne (API dostawców):** Gemini, Opus (Anthropic) i inne — przydatne dla procesów
  „rozumienia treści" (opis kreacji, lista obiektów) jako alternatywa/fallback dla LLaVA.
  **Uwaga:** modele saliency (predykcja uwagi) i FC są wyspecjalizowane — publiczne LLM-y
  ogólnego przeznaczenia ich **nie zastąpią 1:1**; wymienialność ma największy sens dla
  procesów językowo-wizualnych (etykiety, opis), a nie dla rdzennej predykcji uwagi. **[?]**

---

## 11. Struktura i generowanie raportu

### 11.1. Komponenty raportu i ich źródła (macierz śledzenia)

| Komponent raportu | Źródło danych (proces/model) | Status MVP |
|---|---|:--:|
| Opis ogólny kreacji | LLaVA / opis (ew. ASM prompt) | ✅ |
| Lista obiektów | LLaVA + Grounding DINO | ✅ |
| Lista i opis AOI | użytkownik (Studio) ± mapowanie z obiektów | 🟡 częściowo |
| Mapy cieplne — statyczne (1/3/5/10/15/20s) | DeepGaze/UNISAL/ASM (1 mapa = 1 klatka) | ✅ (jedna klatka)* |
| Mapy cieplne — dynamiczne 1–20s | saliency czasowa | 🟡 roadmapa |
| Ścieżki fiksacji — statyczne/dynamiczne | model scanpath | 🟡 roadmapa |
| Ścieżka AOI | scanpath (lub przybliżenie rankingiem) | 🟡 / heurystyka |
| Analiza kognitywna (rekomendacja) | warstwa interpretacji (cel + metryki → tekst) | 🔵 do zbudowania |
| Tabela porównawcza z metrykami | warstwa metryk (saliency ∩ AOI) | ✅ (zakres ET-static) |

\* obecne modele zwracają **jedną** mapę saliency; „statyczne 1/3/5/10/15/20s" są realne
dopiero z saliency czasową — w MVP można pokazać jedną mapę zagregowaną. **[?]**

### 11.2. Warianty A / AB / ABC

- Komponenty raportu powielają się per kreacja: **AB** → 2 kreacje, **ABC** → 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).

### 11.3. Eksport i udostępnianie

- **Eksport:** PDF (raport). Use case 2 dodaje **XLS** (tabele metryk) i **AVI** (dynamiczne
  mapy/ścieżki) — zależne od roadmapy czasowej. **[?]**
- **Udostępnianie:** wg uprawnień projektu; **link do eksperymentu** (Editor / Viewer).
  Doprecyzować: link publiczny czy wymaga konta. **[?]**
- **Klonowanie:** „Zmień ten eksperyment" / „Edytuj" → prośba o nową nazwę → przekierowanie
  do Kroku 1 z prekonfiguracją z eksperymentu bazowego (wersjonowanie — §12, [?]).

---

## 12. Propozycja modelu danych (Supabase)

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

```
organizations(id, name, status[active|inactive|archived], credits_balance,
              storage_quota_mb, created_at)
users(id, email, display_name, locale, created_at)
memberships(id, org_id, user_id, role[admin|member|guest])     // M:N user↔org
projects(id, org_id, name, type[ET|FC|ET_FC], created_by, created_at)
project_permissions(id, project_id, user_id, role[editor|viewer])
creatives(id, org_id, project_id?, storage_path, mime, width, height, created_by)
experiments(id, project_id, name, goal_id, test_type[A|AB|AC|BC|ABC],
            analysis_type[ET|FC|ET_FC], observation_time_s, report_scope jsonb,
            target_group jsonb, base_experiment_id?, status, 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],
              storage_path, mime)
metrics(id, experiment_id, creative_id, aoi_id?, key, value)   // policzone wskaźniki
reports(id, experiment_id, pdf_path?, xls_path?, generated_at)
ai_processes(key, name, contract)              // zamknięta lista procesów
ai_models(key, name, kind[own|public], adapter, config_ref)    // rejestr modeli
process_model_binding(process_key, model_key, active, version) // Proces ↔ Model (§10)
audit_logs(id, org_id?, user_id?, action, target, payload jsonb, created_at)
```

Kluczowe dla wymagań:
- `ai_runs` + `process_model_binding` → realizują **wymienialność modeli** i **audyt
  predykcji** (logi eksperymentu, §7.5).
- `base_experiment_id` → realizuje **klonowanie** eksperymentu.
- `target_group jsonb` → przechowuje profil grupy (wejście dla przyszłego warunkowania).

---

## 13. Kredyty, subskrypcje, przestrzeń dyskowa

Z Koncepcji 0.1 wynika istnienie **kredytów/coinów** (globalnych i miesięcznych) oraz
**przestrzeni dyskowej** zależnej od subskrypcji i rozszerzalnej za punkty. Wymaga to
doprecyzowania modelu rozliczeń — propozycja ramowa (do potwierdzenia, **[?]**):

| Element | Propozycja |
|---|---|
| Naliczanie za eksperyment | koszt zależny od typu analizy (ET < FC < ET+FC) i liczby kreacji (A/AB/ABC) |
| Kredyty miesięczne | pula odnawialna w cyklu rozliczeniowym (zarządzana przez Super Admina) |
| Kredyty globalne | pula dokupiona, nieodnawialna |
| Przestrzeń dyskowa | limit z planu; rozszerzenie za kredyty wg cennika przestrzeni |
| Plany subskrypcji | **niezdefiniowane w źródłach** — wymagają osobnej specyfikacji |

Decyzje otwarte: cennik (ile kredytów za co), polityka wygasania kredytów, obsługa
przekroczenia limitów, fakturowanie. → `Pytania do koncepcji.md`.

---

## 14. Logi i audyt

Dwa poziomy:
- **Logi systemowe** (panel administracyjny) — filtrowanie po użytkowniku, organizacji,
  zakresie dat, typie operacji.
- **Logi eksperymentu** (Super Admin) — pełen ślad: działania i ustawienia użytkownika +
  **wszystkie dane wysłane/odebrane z modeli AI**. Powiązane z `ai_runs` (§12): każda
  predykcja zapisuje proces, model, żądanie i referencję odpowiedzi → audyt i powtarzalność,
  szczególnie po podmianie modelu (§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 na poziomie
  organizacji/projektu; izolacja danych między organizacjami (RLS w Supabase — zalecane).
- **Sekrety:** klucze i hosty modeli poza kodem (vault / zmienne środowiskowe), nie w repo.
- **Dane wysyłane do modeli publicznych:** przy podmianie na Gemini/Opus kreacje opuszczają
  infrastrukturę własną → wymagana zgoda klienta i zapis w politykach. **[?]**
- **Profile wrażliwe:** kategoria **neuroatypowość** (ASD/ADHD/depresja) to dane wrażliwe
  w warstwie *konfiguracji predykcji* (nie dotyczą realnych osób), ale komunikacja wyników
  powinna unikać sugestii diagnostycznych. **[?]**

---

## 16. Internacjonalizacja

- **Języki UI w MVP 1.0:** polski, angielski (kolejne w następnych wersjach).
- **Język raportu / interpretacji kognitywnej:** powinien podążać za locale użytkownika —
  warstwa interpretacji (LLM) generuje tekst w wybranym języku. **[?]**
- **Prompt ASM:** obecnie po angielsku (`"Describe the image in the style of a polished
  marketing ad."`) — 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/AOI z AI)

1. Rejestracja → 2. Logowanie → 3. Utworzenie organizacji → 4. Dodanie kreacji do Galerii →
5. Nowy projekt → eksperyment: cel + grupa docelowa, typ **ABC** + 3 kreacje, parametry,
**bez** zmian w Studio → 6. Generowanie raportu → 7. Eksport **PDF** → 8. Udostępnienie
(Editor/Viewer) → 9. „Zmień ten eksperyment" → nowa nazwa → Krok 1 z prekonfiguracją.

### UC2 — Eksperyment ABC ze zmianami w Studio + segment

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?", **ET+FC**, 3 kreacje,
obiekty/AOI wskazane przez AI (z możliwą korektą), eksport **PDF + XLS + AVI**, udostępnienie
1× Editor i 1× Viewer, oraz „Edytuj" jako baza kolejnego eksperymentu.

> UC2 uruchamia komponenty roadmapowe (FC, XLS metryk, AVI dynamiczne) — w MVP zrealizowany
> w zakresie dostępnych metryk ET-static, z resztą oznaczoną jako „wkrótce". **[?]**

---

## 18. Zakres MVP 1.0 vs roadmapa

### ✅ W zakresie MVP 1.0

- Platforma SaaS: organizacje, role/uprawnienia, projekty, galeria (org + projekt), eksperymenty.
- Kreator eksperymentu (4 kroki), słowniki celów / obiektów / AOI / grup docelowych.
- Studio: ręczne i AI-wspomagane obiekty/AOI (LLaVA + Grounding DINO).
- Pipeline AI: detekcja obiektów + **saliency statyczna z 3 modeli** (DeepGaze, UNISAL, ASM)
  z walidacją krzyżową i wizualizacjami (overlay, nakładka, porównanie 2×2).
- Metryki **udziału uwagi na AOI** i porównanie wariantów; raport + eksport PDF.
- Panel administracyjny: organizacje, użytkownicy, **wymiana modeli AI (Proces ↔ Model)**, logi.
- Warstwa interpretacji kognitywnej (rekomendacja z uzasadnieniem) — **do zbudowania**, ale
  należy do rdzenia wartości MVP (bez niej raport jest zbiorem liczb). **[?] priorytet.**

### 🟡 Roadmapa (kolejne wersje — §11 specyfikacji procesu AI)

- **Facial Coding / mapa emocji** (walencja, pobudzenie, frustracja, ambiwalencja, komfort…).
- **Mapy cieplne dynamiczne 1–20s** (saliency w interwałach czasu).
- **Ścieżki fiksacji (scanpath)** i pełna **„ścieżka AOI"** z sekwencją czasową.
- **Predykcje różnicowane per grupa docelowa** (warunkowanie modelu demografią).
- Eksporty **XLS / AVI**, kolejne języki UI.

### 🔑 Rekomendacja zakresowa

MVP powinno **dowieźć pętlę wartości** dla podzbioru celów silnie ET (np. #2 „Czy odbiorca
widzi przekaz?", #7 „Czy przekaz jest zrozumiały?", częściowo #1/#3) — tam obecny pipeline
daje wiarygodne metryki. Cele zależne od emocji i czasu zaprezentować jako „wkrótce", aby nie
obiecywać wyników, których pipeline jeszcze nie liczy. Ostateczna lista celów MVP →
decyzja właściciela produktu.

---

*Dokument roboczy v0.2. Miejsca [?] wymagają decyzji — zebrane w `Pytania do koncepcji.md`.*