Witaj w projekcie
Skinso

Co to jest Skinso? #

Skinso to platforma społecznościowa dedykowana branży beauty. Jej cel jest prosty: połączyć klientów, modelki, właścicieli salonów i specjalistów beauty w jednym ekosystemie — zamiast rozsianych po social media i komunikatorach.

Platforma rozwiązuje konkretny problem: branża beauty działa chaotycznie. Klient szuka polecenia na Facebooku. Modelka wysyła portfolio Instagramem. Salon rekrutuje przez formularz Google. Skinso konsoliduje to wszystko.

Dla kogo jest ten poradnik #

Ten dokument zakłada, że:

• Wiesz, czym jest JavaScript i jak działa react/Next.js na podstawowym poziomie
• Możliwe, że dopiero dołączyłeś/-aś do projektu lub wracasz po dłuższej przerwie
• Chcesz zrozumieć dlaczego decyzje zostały podjęte, nie tylko jak coś działa

Jak czytać ten dokument #

Jeśli zaczynasz od zera — czytaj liniowo. Jeśli wracasz po przerwie lub masz konkretne pytanie — użyj nawigacji po lewej. Każda sekcja jest niezależna i możesz do niej wrócić w dowolnej chwili.

Trzy przestrzenie #

Skinso nie jest jedną aplikacją dla wszystkich. To trzy oddzielne doświadczenia pod jednym dachem, zbudowane wokół roli użytkownika. To najważniejszy koncept w projekcie — zrozum go jako pierwszy.

Persony użytkowników #

Każda decyzja projektowa powinna być weryfikowana przez pryzmat tych trzech person. Kiedy masz wątpliwość — zapytaj: „Co zrobi Anna/Karolina/Piotr?"

Zakres MVP #

MVP jest ograniczony celowo. Trzeba wiedzieć, co jest w grze, a co nie.

Jeśli widzisz coś oznaczonego jako P2 lub // future w kodzie — to jest właśnie ta lista. Nie implementuj tego w MVP, chyba że właściciel produktu to potwierdzi.

Struktura projektu #

Repozytorium jest zorganizowane wielowersyjnie. Główna wersja produkcyjna to 03_skinso_final/ — tutaj trafia gotowy kod. Wersja robocza i prototypy żyją w 02_app_ver_2.0.0/.

Główne katalogi #

Ważne pliki — gdzie szukać #

Stack technologiczny #

Setup środowiska #

Wymagania #

• Node.js ≥ 20.x (zalecane: 22.x LTS)
• pnpm ≥ 9.x — szybszy od npm, używany w projekcie
• PostgreSQL ≥ 15 lokalnie lub dostęp do Railway instance
• Git — oczywiste, ale warto wspomnieć

node --version   # powinna być >= 20.x
pnpm --version   # powinna być >= 9.x
psql --version   # powinna być >= 15.x

Pierwsze kroki #

cd 03_skinso_final
pnpm install

cp .env.example .env.local

pnpm prisma migrate dev --name init
pnpm prisma db seed   # opcjonalnie — seed z testowymi danymi

pnpm dev
# Aplikacja dostępna na http://localhost:3000

Zmienne środowiskowe #

Nigdy nie commituj .env.local do repozytorium. Plik jest w .gitignore — ale uważaj na inne pliki .env.*.

Onboarding i routing przestrzeni #

Onboarding to moment, kiedy nowy użytkownik odpowiada na pytania i zostaje przypisany do jednej z trzech przestrzeni. To krytyczna ścieżka — błąd tutaj oznacza, że użytkownik trafia w złe miejsce.

Logika routingu

function determineSpace(answers) {
  // Q00 — bezpośredni wybór roli
  if (answers.Q00 === 'klient')   return 'KLIENT'
  if (answers.Q00 === 'modelka')  return 'MODELKA'
  if (answers.Q00 === 'salon')    return 'BIZNES'

  // Q00 === 'nie wiem' — routing pośredni
  if (answers.Q02 === 'tak')                     return 'BIZNES'
  if (answers.Q01.includes('rekrutować'))         return 'BIZNES'
  if (answers.Q01.includes('promować salon'))     return 'BIZNES'
  if (answers.Q01.includes('budować portfolio'))  return 'MODELKA'
  if (answers.Q01.includes('szukać współprac'))   return 'MODELKA'

  return 'KLIENT'  // domyślne
}

Pytania onboardingowe — skrót

Design system #

Skinso ma spójny design system oparty na ciepłej, beauty-themed palecie. Zawsze używaj zmiennych z konfiguracji Tailwind — nie wpisuj wartości hex bezpośrednio w kodzie.

Kolory #

Typografia #

Przykład użycia:

<!-- Poprawnie -->
<h2 class="font-heading text-2xl font-semibold text-skinso-charcoal">
  Moje portfolio
</h2>
<p class="font-body text-sm text-skinso-charcoal/70">
  Opis portfolio...
</p>

<!-- ❌ Błędnie - nie rób tak -->
<h2 style="font-family: Poppins; color: #32373C">Moje portfolio</h2>

Kluczowe funkcje (MVP) #

To jest lista funkcji z priorytetem P0/P1 — rzeczy, które MUSZĄ działać przed pierwszym publicznym uruchomieniem.

Workflow developerski #

Kilka zasad, które pomogą utrzymać projekt w porządku:

Zanim zaczniesz kodować

Zawsze zacznij od przeczytania odpowiedniej części PRD (01_plan/PRD_PL.md). Zrozumiej wymagania biznesowe przed napisaniem pierwszej linii kodu. Oszczędzi ci to refactoru.

Branches

# Nowa funkcja
feature/onboarding-routing
feature/portfolio-upload

# Bugfix
fix/dark-mode-text-contrast
fix/profile-image-upload

# Refactor
refactor/auth-middleware

Jak testować UI

Wiele ekranów jest dostępnych jako statyczne HTML w 02_app_ver_2.0.0/community/. Otwórz je bezpośrednio w przeglądarce — są pełnoprawnymi prototypami:

02_app_ver_2.0.0/community/
├── ai-assistant.html      # AI doradca pielęgnacji skóry
├── profile.html           # Profil użytkownika
├── jobs.html              # Lista ofert pracy
└── messages.html          # Wiadomości bezpośrednie

Commit messages

Używaj konwencji Conventional Commits:

# Format: type(scope): opis
feat(onboarding): add space routing logic
fix(profile): correct avatar upload validation
style(design-system): update bronze token to match brandbook
docs(readme): add setup instructions for Railway deployment

Kiedy pytać o pomoc

Jeśli utkniesz na więcej niż 30 minut — zapytaj. Projekt ma zaległy kontekst w 41_autocoder/ który może pomóc zrozumieć wcześniejsze decyzje. Sprawdź też CUSTOM_UPDATES.md w tym katalogu.

Częste błędy i antypateny #

Lista rzeczy, które zostały już zrobione źle i naprawione. Ucz się na naszych błędach.

❌ Hardkodowane kolory w CSS

Problem: color: #B6713E w komponentach łamie dark mode i utrudnia aktualizację brandbooku.

Rozwiązanie: Używaj wyłącznie klas Tailwind z customowej konfiguracji: text-skinso-bronze, bg-skinso-cream.

❌ Logika biznesowa w komponentach presentational

Problem: useState i fetch w komponentach, które powinny tylko renderować UI, tworzą chaos trudny do testowania.

Rozwiązanie: Przechowuj logikę w page-level componentach lub custom hookach. Komponenty w /components/ui/ powinny być czyste — tylko props IN, JSX OUT.

❌ Implementowanie P2 features przed MVP

Problem: Temptacja zaimplementowania czegoś "skoro już tu jestem" — np. panel analityczny albo grupy czatowe.

Rozwiązanie: Wszystko oznaczone P2 w PRD lub // future w kodzie jest poza zakresem. Zostaw to, dopóki właściciel produktu nie zmieni priorytetu.

❌ Mieszanie języków w UI

Problem: UI ma być po polsku. Nie ma wyjątków dla "bo angielski jest prostszy".

Rozwiązanie: Wszystkie texty w UI po polsku. Tylko kod, komentarze i nazwy zmiennych mogą być po angielsku.

❌ Brak weryfikacji wieku w ścieżkach Modelki/Biznesie

Problem: Wymaganie 18+ jest prawnym wymogiem dla tych ścieżek. Pominięcie go to poważny błąd compliance.

Rozwiązanie: Q06 w onboardingu musi zawierać checkbox 18+ i być walidowany przed ukończeniem rejestracji.

❌ Upload plików bez walidacji

Problem: Akceptowanie plików bez weryfikacji type/size prowadzi do ataków i przepełnienia storage.

Rozwiązanie: Portfolio: max 50 zdjęć, każde ≤ 10MB, tylko JPEG/PNG/WebP. Wideo: max 2 min, ≤ 100MB, tylko MP4/WebM.

Roadmap #

Co i kiedy planujemy zbudować. To żywy dokument — aktualizowany przy każdym sprincie.

Masz pytania? Sprawdź 01_plan/PRD_PL.md lub zapytaj właściciela projektu.
Ostatnia aktualizacja: 14 marca 2026 · v202603141018_v1