From 1e533574bac721a16b25721636b1187a89814188 Mon Sep 17 00:00:00 2001 From: majkarol Date: Thu, 25 Jun 2026 15:49:57 +0200 Subject: [PATCH] wersja 0.4 --- Koncepcja 0.2 .md | 713 ++++++++++++++++++++++ Koncepcja 0.3.md | 798 ++++++++++++++++++++++++ Koncepcja 0.4.md | 813 +++++++++++++++++++++++++ Pytania do koncepcji - uzupełnienie.md | 121 ++++ wytyczne.md | 45 ++ 5 files changed, 2490 insertions(+) create mode 100644 Koncepcja 0.2 .md create mode 100644 Koncepcja 0.3.md create mode 100644 Koncepcja 0.4.md create mode 100644 Pytania do koncepcji - uzupełnienie.md create mode 100644 wytyczne.md diff --git a/Koncepcja 0.2 .md b/Koncepcja 0.2 .md new file mode 100644 index 0000000..ef1ce32 --- /dev/null +++ b/Koncepcja 0.2 .md @@ -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`.* diff --git a/Koncepcja 0.3.md b/Koncepcja 0.3.md new file mode 100644 index 0000000..407b320 --- /dev/null +++ b/Koncepcja 0.3.md @@ -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`.* diff --git a/Koncepcja 0.4.md b/Koncepcja 0.4.md new file mode 100644 index 0000000..49ba57b --- /dev/null +++ b/Koncepcja 0.4.md @@ -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.* diff --git a/Pytania do koncepcji - uzupełnienie.md b/Pytania do koncepcji - uzupełnienie.md new file mode 100644 index 0000000..9ca9eb7 --- /dev/null +++ b/Pytania do koncepcji - uzupełnienie.md @@ -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].* diff --git a/wytyczne.md b/wytyczne.md new file mode 100644 index 0000000..493587a --- /dev/null +++ b/wytyczne.md @@ -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.