# Instalacja lokalna (komputer deweloperski, Windows)

**To jest instrukcja do uruchomienia projektu na Twoim komputerze do testów
i pracy nad kodem -- nie do produkcji.** Serwer produkcyjny to osobny temat,
opisany w `VPS.md`. Na tym etapie LiveKit (serwer do dźwięku/obrazu na żywo)
nie jest jeszcze potrzebny -- uruchamiasz tylko backend i frontend, żeby
sprawdzić panel, logikę, bazę danych.

## Czego będziesz potrzebować (zainstalować raz)

| Narzędzie | Do czego | Skąd wziąć |
|---|---|---|
| **.NET 8 SDK** | Uruchamia backend (ASP.NET Core 8) | dotnet.microsoft.com, wersja 8.x |
| **Node.js 20+** | Uruchamia frontend (React + Vite) | nodejs.org, wersja LTS 20 lub nowsza |
| **PostgreSQL** | Baza danych, lokalnie na Twoim komputerze | postgresql.org, lub Docker jeśli już go używasz |
| **Git** (opcjonalnie) | Do wersjonowania kodu -- w tym projekcie na razie nie jest wymagany | git-scm.com |

Sprawdzenie, czy masz już zainstalowane:

```powershell
dotnet --version
node --version
```

Jeśli `dotnet --version` pokaże `8.x.x`, a `node --version` pokaże `v20.x.x`
lub wyżej -- jesteś gotowy.

## Krok 1: Baza danych PostgreSQL

Musisz mieć uruchomiony serwer PostgreSQL lokalnie (domyślny port 5432) oraz
pustą bazę danych dla SameBeat, np. `samebeat_dev`. Zanotuj sobie:

- adres serwera (zwykle `localhost`),
- port (zwykle `5432`),
- nazwę bazy,
- użytkownika i hasło.

Te dane wpiszesz w kroku 3, w connection stringu (czyli "adresie do bazy
danych" -- jeden tekst z wszystkimi powyższymi informacjami razem).

## Krok 2: Backend (ASP.NET Core)

Backend leży w katalogu `SameBeat.Api` (wewnątrz katalogu `backend`).

```powershell
cd M:\Codex\SameBeat\backend\SameBeat.Api
dotnet restore
dotnet run
```

- `dotnet restore` -- ściąga zależności (biblioteki, których backend
  używa). Robisz to raz, potem tylko gdy dojdą nowe zależności.
- `dotnet run` -- odpala backend. W konsoli zobaczysz, na jakim adresie
  nasłuchuje (zwykle coś w stylu `https://localhost:5001` albo podobny port).

Zostaw to okno konsoli otwarte -- backend musi cały czas działać, żeby
frontend miał się z czym łączyć.

## Krok 3: Konfiguracja lokalna backendu

Backend czyta ustawienia z pliku `appsettings.Development.json` w katalogu
`SameBeat.Api`. **Ten plik jest tylko na Twoim komputerze do testów -- nigdy
nie trafia na produkcję i nie powinien lądować w repozytorium z prawdziwymi
hasłami.**

Przykładowa zawartość (dopasuj dane bazy do tego, co ustawiłeś w kroku 1):

```json
{
  "ConnectionStrings": {
    "BazaDanych": "Host=localhost;Port=5432;Database=samebeat_dev;Username=TWOJ_UZYTKOWNIK;Password=TWOJE_HASLO"
  },
  "KontoHostaDev": {
    "Nick": "host_test",
    "Haslo": "haslo_testowe_123"
  }
}
```

### Co to jest `KontoHostaDev`

To specjalne konto do testów lokalnych -- "reżyser imprezy" (host), którym
możesz się od razu zalogować bez przechodzenia całego procesu rejestracji.
Klucze:

- `KontoHostaDev:Nick` -- login konta hosta na dev.
- `KontoHostaDev:Haslo` -- hasło konta hosta na dev.

**Uwaga -- to jest wyłącznie mechanizm deweloperski.** Nie ma prawa istnieć
w konfiguracji produkcyjnej (`appsettings.Production.json` na serwerze VPS).
Jeśli backend zostanie tak napisany, żeby honorować `KontoHostaDev` tylko
gdy środowisko to `Development` -- to jest poprawne i bezpieczne zachowanie.
Jeśli zauważysz, że to konto działa też poza trybem deweloperskim, zgłoś to
jako błąd bezpieczeństwa (patrz `BEZPIECZENSTWO.md`).

## Krok 4: Migracje bazy danych (Entity Framework Core)

Migracje to sposób, w jaki backend "opowiada" bazie danych, jak mają
wyglądać tabele -- bez ręcznego pisania SQL-a. Narzędzie do tego to
`dotnet ef`.

### Instalacja narzędzia (raz, na cały komputer)

```powershell
dotnet tool install --global dotnet-ef
```

Jeśli już masz zainstalowane, ale w starszej wersji:

```powershell
dotnet tool update --global dotnet-ef
```

### Utworzenie bazy / zastosowanie migracji

Z katalogu `SameBeat.Api`:

```powershell
cd M:\Codex\SameBeat\backend\SameBeat.Api
dotnet ef database update
```

To polecenie tworzy w bazie `samebeat_dev` wszystkie potrzebne tabele
zgodnie z aktualnym stanem kodu.

### Dodanie nowej migracji (gdy zmienia się struktura danych)

To robi programista przy zmianie modelu danych, nie jest to codzienna
czynność:

```powershell
dotnet ef migrations add NazwaZmiany
dotnet ef database update
```

`NazwaZmiany` to krótki opis w stylu `DodanieTabeliImprez` -- bez spacji i
polskich znaków.

## Krok 5: Frontend (React + Vite)

W osobnym oknie konsoli (backend musi w tym czasie dalej działać):

```powershell
cd M:\Codex\SameBeat\frontend
npm install
npm run dev
```

- `npm install` -- ściąga zależności frontendu. Raz, potem przy zmianach
  w zależnościach.
- `npm run dev` -- odpala serwer deweloperski Vite. W konsoli pokaże się
  adres, zwykle `http://localhost:5173`.

Otwórz ten adres w przeglądarce -- to jest Twoja lokalna wersja SameBeat.

## Podsumowanie -- codzienne uruchamianie

Gdy wszystko jest już raz skonfigurowane (baza, `appsettings.Development.json`,
migracje), do codziennej pracy wystarczą dwa okna konsoli:

```powershell
# Okno 1 -- backend
cd M:\Codex\SameBeat\backend\SameBeat.Api
dotnet run

# Okno 2 -- frontend
cd M:\Codex\SameBeat\frontend
npm run dev
```

## Test lokalny `/join` (dołączanie do imprezy)

Żeby lokalnie sprawdzić `/join`, host musi mieć aktywne "Wydarzenie" --
inaczej backend nie ma do czego przypisać wpisu w poczekalni. W środowisku
`Development` takie wydarzenie jest **seedowane automatycznie** (czyli
backend sam je tworzy przy starcie), więc `/join` działa od razu po
uruchomieniu backendu -- nie trzeba nic ręcznie zakładać w bazie.

Uwaga: token LiveKit wydawany przez `/join` w tym trybie jest tylko do
oglądania (bez prawa nadawania kamery) -- to jest zamierzone zachowanie
opisane w `ARCHITEKTURA.md`, nie błąd.

## Czego tu brakuje celowo

Ta instrukcja **nie** opisuje uruchomienia LiveKit lokalnie (serwer do
dźwięku/obrazu) ani Coturn/TURN -- to jest potrzebne dopiero, gdy testujesz
faktyczne przekazywanie mikrofonu między uczestnikami. Jeśli/gdy to będzie
potrzebne w pracy lokalnej, dopiszemy osobną sekcję albo osobny plik.

## Powiązane dokumenty

- `ARCHITEKTURA.md` -- jak to wszystko działa razem.
- `VPS.md` -- plan wdrożenia na serwer produkcyjny (Contabo).
- `BEZPIECZENSTWO.md` -- podstawowe zasady bezpieczeństwa.