majkarol/ASM_PNS_C
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

wersja 0.4

Browse source
This commit is contained in:
majkarol 2026-06-25 15:49:57 +02:00
parent 3391400f1f
commit 1e533574ba
5 changed files with 2490 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

713
Koncepcja 0.2 .md Normal file
View file

@ -0,0 +1,713 @@
# 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`.*

798
Koncepcja 0.3.md Normal file
View file

@ -0,0 +1,798 @@
# AdReactions - Koncepcja platformy v0.3
> 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.
>
> Nieliczne kwestie pozostają otwarte. Oznaczono je w tekście jako **[do doprecyzowania]**
> i zebrano w pliku `Pytania do koncepcji - uzupełnienie.md`.
---
## 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ę.
Część modeli (saliency czasowa, scanpath, Facial Coding, warunkowanie demografią) jest
w trakcie przygotowania. Ich uruchomienie planowane jest w MVP 1.0, a wykonalność zależy
od dostarczenia tych modeli i ich dokumentacji.
---
## 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 (saliency ∩ 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 |
W MVP 1.0 dostępnych jest 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.
Komponenty te są w przygotowaniu, więc dostępność pełnego zestawu metryk dla danego celu
zależy od dostarczenia odpowiednich modeli (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 w przygotowaniu (MVP 1.0): │
│ saliency czasowa 1-20 s · scanpath · │
│ Facial Coding (mapa emocji) · │
│ warunkowanie demografią │
└────────────────────┬───────────────────┘
▼
┌────────────────────────────────────────┐
│ Warstwa metryk (backend): │
│ saliency ∩ 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) | ✅ dostępne |
| 2 | Detekcja obiektów (bboxy) | Grounding DINO | ✅ dostępne |
| 3 | Predykcja saliency #1 | DeepGaze | ✅ dostępne |
| 4 | Predykcja saliency #2 | UNISAL | ✅ dostępne |
| 5 | Predykcja saliency centralna | ASM (PNS) | ✅ dostępne |
| 6 | Sugestia AOI | model lub mapowanie z obiektów | 🟡 do dostarczenia |
| 7 | Saliency czasowa (mapy dynamiczne 1-20 s) | model czasowy | 🟡 w przygotowaniu |
| 8 | Scanpath (ścieżka fiksacji) | model scanpath | 🟡 w przygotowaniu |
| 9 | Facial Coding (mapa emocji) | model publiczny przez plugin | 🟡 w przygotowaniu |
| 10 | Warunkowanie predykcji demografią | model zewnętrzny (prompt + profil) | 🟡 w przygotowaniu |
| 11 | Analiza kognitywna (rekomendacja) | model prywatny lub publiczny | 🟡 do zbudowania |
> Legenda: ✅ dostępne dziś · 🟡 zaplanowane w MVP 1.0, zależne od dostarczenia modelu.
**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
```
AnalysisResult {
image : ImageInput { bytes, base64, mime, width, height }
detection : DetectionResult { objects: [{ object_type, bbox_xyxy, score }] }
saliency : SaliencyMap[] // deepgaze, unisal, asm_detailed, asm_general
temporal : SaliencyFrame[] // mapy dla kolejnych przedziałów czasu (w przygotowaniu)
scanpath : ScanpathPoint[] // sekwencja fiksacji (w przygotowaniu)
emotion : EmotionMap // walencja, pobudzenie, frustracja... (FC, w przygotowaniu)
}
```
### 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 | ✅ dostępne |
| Rozumienie treści - obiekty, opis | LLaVA + Grounding DINO | ✅ dostępne |
| **ET czasowy** - mapy dynamiczne 1-20 s | saliency w interwałach czasu | 🟡 w przygotowaniu |
| **ET** - ścieżki fiksacji (scanpath) | model scanpath | 🟡 w przygotowaniu |
| **Facial Coding** - walencja, pobudzenie, frustracja | model emocji (publiczny przez plugin) | 🟡 w przygotowaniu |
| **Analiza kognitywna** - rekomendacja z uzasadnieniem | warstwa interpretacji nad metrykami | 🟡 do zbudowania |
| **Predykcje per grupa docelowa** | warunkowanie modelu demografią | 🟡 w przygotowaniu |
### 9.5. Warstwa metryk i lista wskaźników
Modele saliency zwracają **mapy uwagi**, a nie liczby. Wskaźniki liczbowe powstają w backendzie
przez przecięcie mapy saliency z obszarami AOI (saliency ∩ AOI). Dzięki temu model dostarcza
predykcję uwagi, a backend zamienia ją w porównywalne metryki dla wskazanych obszarów.
Lista wskaźników w MVP:
| Metryka | Źródło | Status |
|---|---|:--:|
| Udział uwagi na AOI (%) | saliency ∩ AOI | ✅ dostępne |
| Ranking AOI wg uwagi | saliency ∩ AOI | ✅ dostępne |
| Mapa cieplna statyczna | saliency | ✅ dostępne |
| Porównanie kreacji wg uwagi | saliency × N kreacji | ✅ dostępne |
| Czas do pierwszej fiksacji | scanpath | 🟡 w przygotowaniu |
| Kolejność kontaktu z AOI (ścieżka AOI) | scanpath | 🟡 w przygotowaniu |
| Liczba powrotów wzroku | scanpath | 🟡 w przygotowaniu |
| Mapy dynamiczne 1-20 s | saliency czasowa | 🟡 w przygotowaniu |
| Walencja, pobudzenie, frustracja, ambiwalencja, komfort | model emocji (FC) | 🟡 w przygotowaniu |
| Różnice metryk między segmentami | warunkowanie demografią | 🟡 w przygotowaniu |
Do czasu dostarczenia modelu scanpath "ścieżkę AOI" można przybliżyć rankingiem AOI wg
intensywności saliency (kolejność od najsilniejszego), z wyraźną adnotacją, że to heurystyka,
a nie prawdziwa sekwencja fiksacji **[do doprecyzowania]**.
---
## 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[]`, `SaliencyMap`, `EmotionMap`). 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.
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 | 🟡 w przygotowaniu |
| Ścieżki fiksacji (scanpath) | model scanpath | 🟡 w przygotowaniu |
| Ścieżka AOI | scanpath (lub przybliżenie rankingiem) | 🟡 / heurystyka |
| Mapa emocji (Facial Coding) | model emocji (publiczny przez plugin) | 🟡 w przygotowaniu |
| Analiza kognitywna (rekomendacja) | warstwa interpretacji (cel + metryki -> tekst) | 🟡 do zbudowania |
| Tabela porównawcza z metrykami | warstwa metryk (saliency ∩ 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).
### 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],
storage_path, mime)
temporal_maps(id, ai_run_id, creative_id, t_from_ms, t_to_ms, storage_path)
scanpaths(id, ai_run_id, creative_id, points jsonb)
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.
- **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.
Pełny zakres metryk ET+FC dla UC2 zależy od dostarczenia modeli saliency czasowej, scanpath
i Facial Coding (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.
Wszystkie 15 celów jest objęte zakresem MVP. Część z nich zależy od dostarczenia modeli
saliency czasowej, scanpath i Facial Coding oraz ich dokumentacji.
### Roadmapa (kolejne wersje)
- Facial Coding jako model prywatny (zamiast publicznego).
- Eksporty XLS i AVI.
- Kolejne języki UI.
- Dalsza rozbudowa warunkowania predykcji demografią po stronie modeli własnych.
---
*Dokument roboczy v0.3. Otwarte kwestie oznaczone [do doprecyzowania] zebrano w pliku
`Pytania do koncepcji - uzupełnienie.md`.*

813
Koncepcja 0.4.md Normal file
View file

@ -0,0 +1,813 @@
# 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.*

121
Pytania do koncepcji - uzupełnienie.md Normal file
View file

@ -0,0 +1,121 @@
# Uzupełnienie do pytań do koncepcji AdReactions
> Część pytań z `Pytania do koncepcji.md` wymaga doprecyzowania. Poniżej te same kwestie
> opisane prościej, z przykładami i rekomendowaną odpowiedzią do akceptacji lub zmiany.
> Na końcu zebrano nowe pytania, które wynikły z udzielonych odpowiedzi.
---
## Część 1 - pytania do wyjaśnienia (Q6, Q8, Q25)
### Q6. Gdzie liczone są wskaźniki liczbowe
**O co naprawdę pytamy.** Modele uwagi (DeepGaze, UNISAL, ASM) zwracają **obrazek**, czyli
mapę cieplną. Pokazuje ona, gdzie skupia się uwaga (jaśniej = większa uwaga). Model **nie
zwraca liczby** w stylu "CTA dostaje 35% uwagi".
**Przykład.** Załóżmy, że na kreacji jest przycisk CTA w prawym dolnym rogu. Model odda mapę
z jasną plamą w tym miejscu. Żeby powstała liczba "35%", ktoś musi wziąć zdefiniowany obszar
CTA (AOI) i policzyć, ile "jasności" mapy wpada w ten obszar w stosunku do całości. To właśnie
przecięcie mapy z obszarem AOI (saliency ∩ AOI).
**Decyzja do potwierdzenia.**
1. Czy zgadzamy się, że te wskaźniki liczy **nasz backend**, a modele oddają tylko mapy?
2. Czy akceptujemy listę wskaźników w MVP (udział uwagi na AOI, ranking AOI, mapa cieplna,
porównanie wariantów, a po dostarczeniu modeli także czas do pierwszej fiksacji, kolejność
kontaktu z AOI, liczba powrotów, mapy 1-20 s i metryki Facial Coding)?
**Odp:**
1. Modele będą zwracać dane matematyczne
2. Tak
### Q8. Gdzie i jak zarządzamy konfiguracją modeli
**O co naprawdę pytamy.** Każdy krok analizy musi wiedzieć: jaki model go wykonuje, pod jakim
adresem, z jakim kluczem i z jakimi ustawieniami. Te dane można trzymać na dwa sposoby:
zaszyte w kodzie albo edytowalne w panelu administracyjnym.
**Co proponujemy.** Konfiguracja w panelu (Super administrator). Daje to trzy rzeczy:
- zmianę modelu bez ruszania kodu aplikacji,
- przycisk "test połączenia", który sprawdza, czy model odpowiada,
- zapis, który model i w jakiej wersji policzył dany raport (gdy później podmienimy model,
nadal wiadomo, co policzyło stary raport).
Słowo **adapter / plugin** oznacza tu mały fragment kodu, który podpina konkretny model pod
dany krok. To ten sam mechanizm, który zaakceptowałeś w odpowiedzi na Q7.
**Decyzja do potwierdzenia.** Czy akceptujemy całość: konfiguracja w panelu, modele podpinane
przez adaptery i pluginy, test połączenia oraz wersjonowanie przypisania model - proces?
**Odp:** Tak.
### Q25. Ścieżka AOI w MVP
**O co naprawdę pytamy.** Prawdziwa ścieżka wzroku (scanpath) pokazuje **kolejność** patrzenia
w czasie: najpierw tu, potem tam, potem jeszcze gdzie indziej. Potrzebuje osobnego modelu
scanpath. Statyczna mapa cieplna pokazuje tylko, gdzie uwaga skupia się łącznie, bez kolejności.
"Przybliżenie rankingiem" to ustawienie obszarów AOI od najsilniej do najsłabiej przyciągającego
uwagę i pokazanie tego jako niby-kolejności. To uproszczenie, a nie prawdziwa sekwencja. Obszar,
który łącznie przyciąga najwięcej uwagi, wcale nie musi być oglądany jako pierwszy.
**Powiązanie z Q2.** W odpowiedzi na Q2 zdecydowałeś, że scanpath wejdzie do MVP 1.0. Gdy model
scanpath zostanie dostarczony, ścieżka AOI będzie prawdziwa. Pytanie zawęża się więc do okresu
przejściowego.
**Decyzja do potwierdzenia.** Zanim model scanpath będzie gotowy, czy pokazujemy przybliżenie
rankingiem (z wyraźną adnotacją, że to heurystyka), czy zostawiamy ścieżkę AOI pustą do czasu
dostarczenia modelu?
**Odp:** Modele będą dostarczać dane z informacją na temat kolejności, czasie i intensywności
---
## Część 2 - nowe pytania wynikające z odpowiedzi
### Q26. Sprzeczność przy roli "Gość"
W Q13 rezygnujesz z gościa ("Będzie to użytkownik"), ale w strukturze organizacji w Q14 nadal
jest pozycja "Posiada Gości". Koncepcja v0.3 zakłada **pełną rezygnację z gościa** (zgodnie
z Q13): organizacja ma administratora, użytkowników i projekty. Prosimy o potwierdzenie, że
to właściwa interpretacja, i że linijkę "Posiada Gości" traktujemy jako nieaktualną.
**Odp:** potwierdzam rezygnację z gościa.
### Q27. Dostępność i termin nowych modeli
Odpowiedzi na Q1, Q2 i Q5 przenoszą do MVP 1.0 Facial Coding, mapy czasowe 1-20 s, scanpath
oraz różnicowanie predykcji po grupie docelowej. Tych modeli dziś nie ma w pipeline. Żeby
zaplanować MVP i kolejność wdrożenia, potrzebujemy wiedzieć:
- kiedy będą gotowe modele (FC, scanpath, saliency czasowa, warunkowanie demografią),
- kiedy trafi do nas ich dokumentacja i kontrakty odpowiedzi (powiązane z Q22, Q23, Q24).
**Odp:** W ciągu miesiąca. Do tego czasu można te procesy zrobić z punginami w oparciu na modelach publicznych, tak aby zobaczyć jak to wygląda, poóźniej w trakcie prac będziemy zmieniać / dopracowywać.
### Q28. Facial Coding na modelu publicznym a dane kreacji
Skoro w MVP Facial Coding, analiza kognitywna i warunkowanie demografią działają na modelach
publicznych (Q3, Q5), to dla tych procesów kreacje opuszczają infrastrukturę własną i trafiają
do zewnętrznego dostawcy (np. Gemini, Opus). W Q19 zdecydowałeś, że klient nie wybiera modelu,
bo robi to Super administrator. Prosimy o potwierdzenie, że wysyłka kreacji do dostawcy
publicznego dla tych procesów jest akceptowalna jako decyzja platformy i zostanie opisana
w regulaminie oraz politykach organizacji.
**Odp:** potwierdzam, z zapisem w regulaminie i polityce prywatności.
### Q29. Zabezpieczenie rekomendacji w analizie kognitywnej
Warstwa kognitywna ma wybierać lepszą kreację na podstawie celu i metryk (Q4). Pytanie
o zabezpieczenia z Q4 pozostało bez odpowiedzi. Jak chronimy się przed rekomendacją oderwaną
od danych? Propozycja: rekomendacja musi opierać się wyłącznie na policzonych metrykach
i wskazywać metrykę, która ją uzasadnia (np. "B wygrywa, bo udział uwagi na CTA wynosi 38%
vs 22% dla A").
**Odp:** przyjąć tę zasadę jako wymóg dla warstwy kognitywnej.
---
*Po decyzjach: nanieść ustalenia na `Koncepcja 0.3.md` i usunąć znaczniki [do doprecyzowania].*

45
wytyczne.md Normal file
View file

@ -0,0 +1,45 @@
# Wytyczne
## Kolejny wersja pliku
1. Jeśli tworzysz nową wersję pliku zachowuj odpowiednie numerowanie wersji i nie dodawaj nic "dodatkowego" do nazwy pliku poza zmianą wersji.
2. Jeśli tworzysz nową wersję pliku na podstawie udzielonych odpowiedzi lub innych plików to nie odnoś się do tego, że dana zmiana została wprowadzona na podstawie pliku ... . Pisz nową wersję pliku bez takich odniesień.
## Pisownia
Pisz naturalną, współczesną polszczyzną.
Zasady nadrzędne:
- "Opiera się na" a nie "Opiera się o" jest bardziej poprawne.
- Zawsze używaj pełnych polskich znaków: ą, ć, ę, ł, ń, ó, ś, ź, ż.
- Dbaj o poprawną ortografię, interpunkcję, fleksję i składnię.
- Pisz tak, aby tekst brzmiał jak napisany przez inteligentnego człowieka, a nie przez generator treści.
- Unikaj stylu nadętego, szkolnego, korporacyjnego i sztucznie eksperckiego.
- Unikaj fraz i klisz typowych dla AI, takich jak:
„warto zauważyć”, „należy podkreślić”, „w dzisiejszych czasach”,
„poniżej przedstawiam”, „kluczowym aspektem jest”, „istotnym elementem jest”.
- Unikaj kalk z angielskiego i dosłownych tłumaczeń obcych konstrukcji.
- Zamiast ogólników wybieraj konkret.
- Używaj naturalnego rytmu zdań: mieszaj zdania krótsze i średnie.
- Nie powtarzaj tych samych słów, struktur ani otwarć zdań.
- Nie twórz sztucznych wstępów i podsumowań, jeśli nie są potrzebne.
- Jeśli temat jest prosty, pisz prosto; jeśli specjalistyczny, pisz jasno, ale bez spłycania.
- Stosuj odpowiednio wielkie litery w nagłówkach i treściach, czyli "Ważny nagłówek" a nie "Ważny Nagłówek".
- Nie stosuj długiego myślnika (em-dash) ani średniego (en-dash); zamiast nich używaj zwykłego dywizu "-".
Styl odpowiedzi:
- Brzmij naturalnie, spokojnie i pewnie.
- Pisz bez egzaltacji i bez marketingowego tonu.
- Preferuj prosty szyk zdań.
- Unikaj nadmiaru imiesłowów, strony biernej i rzeczowników odczasownikowych.
- Nie moralizuj i nie „pouczaj”.
- Nie dopisuj ozdobników tylko po to, by tekst brzmiał „ładniej”.
Autokontrola przed oddaniem odpowiedzi:
1. Sprawdź, czy wszędzie są polskie znaki.
2. Sprawdź ortografię, interpunkcję i zgodność gramatyczną.
3. Usuń powtórzenia i sztuczne frazy.
4. Uprość zdania, które brzmią mechanicznie.
5. Zachowaj sens, ale popraw naturalność.
6. Nie powtarzaj wiedzy, którą już raz podałeś. Opisuj dane zaganienie tylko raz.
7. Ważna jest synteza wiedzy i treści. Nie powielaj i nie twórz treści nadmiarowych.