LexiQuest - Vyvojarska dokumentace

Pruvodce pro vyvojare pracujici na projektu LexiQuest.

Prehled projektu

LexiQuest je webova hra pro uceni slovicek. Uzivatele se uci nova slova formou interaktivnich hernich kol, sbiranim XP, postupem v ligach a soutezenich s ostatnimi hraci v realnem case. Aplikace podporuje premium predplatne, vlastni slovniky, boss levely, tymy a dalsich pokrocile funkce.

Technologicky stack

Kategorie	Technologie
Backend	.NET 10, ASP.NET Core Web API
Frontend	Blazor WebAssembly
Databaze	SQL Server (EF Core)
Realtime komunikace	SignalR (WebSockets)
Platby	Stripe (predplatne, jednorazy)
UI komponenty	Tempo.Blazor
Validace	FluentValidation
Logování	Serilog (Console + File sink)
Autentizace	JWT Bearer tokens
Lokalizace	.resx resource soubory
Testy	xUnit, bUnit, FluentAssertions, NSubstitute
Cache	In-Memory cache (MemoryCache)

Predpoklady

.NET 10 SDK
SQL Server (LocalDB, Express nebo plna verze)
Docker (povinny pro E2E testy s Testcontainers)
Node.js 18+ (pouze pro Playwright E2E testy)
IDE: Visual Studio 2025, VS Code nebo Rider

Lokalni vyvoj - Prvni spusteni

1. Klonovani repozitare

git clone https://github.com/your-org/lexiquest.git
cd lexiquest

2. Obnoveni zavislosti

dotnet restore

3. Konfigurace

Upravte src/LexiQuest.Api/appsettings.Development.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=LexiQuest;Trusted_Connection=True;MultipleActiveResultSets=true;TrustServerCertificate=True"
  },
  "JwtSettings": {
    "SecretKey": "VaseTajneHesloProVyvojMinimalne64ZnakuDlouheAbySplnovaloPozadavkyHS256"
  }
}

Poznamka: Soubor appsettings.Development.json je v .gitignore a musi byt vytvoren lokalne.

4. Spusteni databazovych migraci

dotnet ef database update \
  --project src/LexiQuest.Infrastructure \
  --startup-project src/LexiQuest.Api

5. Spusteni API

dotnet run --project src/LexiQuest.Api

API bude dostupne na https://localhost:5000. Swagger UI: https://localhost:5000/swagger

6. Spusteni Blazor frontendu

V novem terminalu:

dotnet run --project src/LexiQuest.Blazor

Frontend bude dostupny na https://localhost:5001.

Spousteni testu

Vsechny testy

dotnet test

Pouze unit testy

dotnet test --filter "Category!=Integration"

Pouze integracni testy

dotnet test --filter "Category=Integration"

Konkretni testovy projekt

dotnet test tests/LexiQuest.Core.Tests
dotnet test tests/LexiQuest.Api.Tests
dotnet test tests/LexiQuest.Blazor.Tests
dotnet test tests/LexiQuest.Infrastructure.Tests

Playwright E2E testy

E2E sada spousti automaticky SQL Server Testcontainer, smtp4dev Testcontainer, API proces a Web proces. Nepouziva lokalni vyvojovou databazi ani realny SMTP server.

Pred prvnim spustenim nainstalujte Playwright browser:

dotnet build tests/LexiQuest.E2E.Tests/LexiQuest.E2E.Tests.csproj
pwsh tests/LexiQuest.E2E.Tests/bin/Debug/net10.0/playwright.ps1 install --with-deps chromium

Zakladni prikazy:

# Rychla sada pro PR/smoke overeni
dotnet test tests/LexiQuest.E2E.Tests/LexiQuest.E2E.Tests.csproj --filter "Category=Smoke"

# Plna aktualni E2E sada
dotnet test tests/LexiQuest.E2E.Tests/LexiQuest.E2E.Tests.csproj --filter "Category=Full"

# Screenshot/UX scenare
dotnet test tests/LexiQuest.E2E.Tests/LexiQuest.E2E.Tests.csproj --filter "Category=Visual"

# Emailove scenare pres smtp4dev
dotnet test tests/LexiQuest.E2E.Tests/LexiQuest.E2E.Tests.csproj --filter "Category=Email"

Debug promene:

E2E_HEADLESS=false
E2E_TRACE=on
E2E_SLOWMO_MS=100

Artefakty se ukladaji do artifacts/e2e/: screenshoty, metadata, videa, trace zipy a logy API/Web/containeru pri padu testu.

Testy s detailnim vystupem

dotnet test --verbosity normal --logger "console;verbosity=detailed"

Struktura projektu

LexiQuest/
├── src/
│   ├── LexiQuest.Api/              # ASP.NET Core Web API
│   │   ├── Controllers/            # REST API controllery
│   │   ├── Endpoints/              # Minimal API endpointy
│   │   ├── Hubs/                   # SignalR huby (MatchHub)
│   │   ├── Validators/             # Request validatory
│   │   └── Resources/              # Lokalizacni soubory API
│   │
│   ├── LexiQuest.Blazor/           # Blazor WebAssembly frontend
│   │   ├── Pages/                  # Stranky (routovatelne komponenty)
│   │   ├── Components/             # Znovupouzitelne komponenty
│   │   ├── Layout/                 # Layout komponenty
│   │   ├── Services/               # Frontend sluzby (HTTP klienti)
│   │   ├── Resources/              # Lokalizacni soubory
│   │   └── wwwroot/                # Staticke soubory (CSS, JS, images)
│   │
│   ├── LexiQuest.Core/             # Domenova vrstva (jadro aplikace)
│   │   ├── Domain/
│   │   │   ├── Entities/           # Domenove entity
│   │   │   ├── Enums/              # Vycty
│   │   │   └── ValueObjects/       # Value objekty
│   │   ├── Interfaces/
│   │   │   ├── Repositories/       # Repository rozhrani
│   │   │   └── Services/           # Service rozhrani
│   │   ├── Services/               # Domenove sluzby (implementace)
│   │   ├── Validators/             # Domenove validatory
│   │   └── Jobs/                   # Background joby
│   │
│   ├── LexiQuest.Infrastructure/   # Infrastrukturni vrstva
│   │   ├── Persistence/
│   │   │   ├── Configurations/     # EF Core entity konfigurace
│   │   │   └── Repositories/       # Repository implementace
│   │   ├── Auth/                   # JWT token service
│   │   ├── Services/               # Externi sluzby (Stripe, Email)
│   │   └── Caching/                # Cache implementace
│   │
│   └── LexiQuest.Shared/           # Sdilene typy
│       ├── DTOs/                   # Data Transfer Objects
│       ├── Enums/                  # Sdilene vycty
│       └── Resources/              # Sdilene lokalizacni soubory
│
├── tests/
│   ├── LexiQuest.Core.Tests/       # Unit testy domeny
│   ├── LexiQuest.Api.Tests/        # API integracni testy
│   ├── LexiQuest.Blazor.Tests/     # bUnit testy komponent
│   └── LexiQuest.Infrastructure.Tests/ # Infrastrukturni testy
│
├── docs/                           # Dokumentace
│   ├── uc/                         # Use case specifikace
│   ├── ui-ux/                      # UI/UX specifikace
│   ├── architecture/               # Architektura
│   └── deployment/                 # Nasazeni a troubleshooting
│
└── todo/                           # Implementacni plan a sledovani pokroku

Architektura a konvence

Clean Architecture

Projekt sleduje principy Clean Architecture:

Core (bez zavislosti)
  ↑
Infrastructure (zavisi na Core)
  ↑
Api / Blazor (zavisi na Infrastructure a Core)

Core nesmi referencovat zadny jiny projekt
Infrastructure referencuje pouze Core
Api referencuje Core, Infrastructure a Shared
Blazor referencuje pouze Shared
Shared je bez zavislosti (DTOs, enums)

DDD entity pattern

Vsechny domenove entity pouzivaji nasledujici vzor:

public class Entity
{
    // Privatni konstruktor - EF Core
    private Entity() { }

    // Staticka tovarni metoda
    public static Entity Create(string param1, int param2)
    {
        // Validace vstupu
        // Inicializace properties
        return new Entity { ... };
    }

    // Privatni settery
    public Guid Id { get; private set; }
    public string Name { get; private set; } = string.Empty;

    // Domenove metody pro zmenu stavu
    public void UpdateName(string newName) { ... }
}

FluentValidation

Vsechny vstupy od uzivatele musi byt validovany pomoci FluentValidation:

public class CreateEntityValidator : AbstractValidator<CreateEntityRequest>
{
    public CreateEntityValidator(IStringLocalizer<CreateEntityValidator> localizer)
    {
        RuleFor(x => x.Name)
            .NotEmpty().WithMessage(localizer["NameRequired"])
            .MaximumLength(100).WithMessage(localizer["NameTooLong"]);
    }
}

Lokalizace

Zadne hardcoded retezce v UI ani v chybovych hlasenich
Vsechny texty v .resx souborech
Struktura: Resources/Pages/NazevStranky.resx, Resources/Components/NazevKomponenty.resx

Pouziti v komponentach:

@inject IStringLocalizer<NazevKomponenty> L
<h1>@L["Nadpis"]</h1>

Scoped CSS

Kazda Blazor komponenta s vlastnimi styly pouziva scoped CSS:

Components/
  MyComponent.razor
  MyComponent.razor.css    # Scoped styly

TDD pristup

Doporuceny pracovni postup:

Napsat test (cerveny)
Napsat minimalni implementaci (zeleny)
Refaktorovat
Opakovat

API endpointy

REST controllery

Controller	Zakladni cesta	Popis
`UsersController`	`/api/users`	Registrace, prihlaseni, profil
`DictionaryController`	`/api/dictionaries`	Vlastni slovniky
`AchievementsController`	`/api/achievements`	Achievementy
`DailyChallengeController`	`/api/daily-challenge`	Denni vyzvy
`LeaguesController`	`/api/leagues`	Ligy a zebrickky
`MultiplayerController`	`/api/multiplayer`	Multiplayer funkce
`PremiumController`	`/api/premium`	Premium predplatne
`ShopController`	`/api/shop`	Obchod s predmety
`StreakProtectionController`	`/api/streak-protection`	Streak shield/freeze
`TeamsController`	`/api/teams`	Tymy a klany
`WebhookController`	`/api/webhook`	Stripe webhooky
`NotificationsController`	`/api/notifications`	Push notifikace
`AdminWordsController`	`/api/admin/words`	Administrace slov
`AdminUsersController`	`/api/admin/users`	Administrace uzivatelu
`AIChallengeController`	`/api/ai-challenge`	AI generovane vyzvy

Minimal API endpointy

Soubor	Cesta	Popis
`GameEndpoints`	`/api/game/*`	Herni smycka
`UserEndpoints`	`/api/users/*`	Doplnkove user endpointy
`GuestEndpoints`	`/api/guest/*`	Testovaci hra bez registrace

SignalR huby

Hub	Cesta	Popis
`MatchHub`	`/hubs/match`	Realtime multiplayer

Swagger UI

Swagger je dostupny v Development rezimu na: https://localhost:5000/swagger

Git workflow

Pojmenovani vetvi

feature/nazev-funkce - nova funkcionalita
fix/popis-opravy - oprava chyby
docs/popis - dokumentace
refactor/popis - refaktoring bez zmeny funkcionality
test/popis - doplneni testu

Pull Request

Kazdy PR musi obsahovat:

Popis - co se meni a proc
Test plan - jak otestovat zmeny
Vsechny testy musi prochazet - CI pipeline bezi automaticky

CI pipeline

Na kazdem PR se automaticky spusti:

dotnet restore
dotnet build --no-restore
dotnet test --no-build

Uzitecne prikazy

# Build celeho solution
dotnet build

# Spusteni API s hot reload
dotnet watch --project src/LexiQuest.Api

# Pridani nove EF Core migrace
dotnet ef migrations add NazevMigrace \
  --project src/LexiQuest.Infrastructure \
  --startup-project src/LexiQuest.Api

# Smazani posledni migrace (pokud neni aplikovana)
dotnet ef migrations remove \
  --project src/LexiQuest.Infrastructure \
  --startup-project src/LexiQuest.Api

# Generovani SQL scriptu
dotnet ef migrations script \
  --project src/LexiQuest.Infrastructure \
  --startup-project src/LexiQuest.Api \
  --idempotent

# Cisteni build artefaktu
dotnet clean

# Aktualizace NuGet balicku
dotnet outdated  # vyzaduje dotnet-outdated tool

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github/workflows		.github/workflows
docs		docs
plans		plans
scripts		scripts
src		src
tests		tests
todo		todo
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
LexiQuest.slnx		LexiQuest.slnx

Folders and files

Latest commit

History

Repository files navigation

LexiQuest - Vyvojarska dokumentace

Prehled projektu

Technologicky stack

Predpoklady

Lokalni vyvoj - Prvni spusteni

1. Klonovani repozitare

2. Obnoveni zavislosti

3. Konfigurace

4. Spusteni databazovych migraci

5. Spusteni API

6. Spusteni Blazor frontendu

Spousteni testu

Vsechny testy

Pouze unit testy

Pouze integracni testy

Konkretni testovy projekt

Playwright E2E testy

Testy s detailnim vystupem

Struktura projektu

Architektura a konvence

Clean Architecture

DDD entity pattern

FluentValidation

Lokalizace

Scoped CSS

TDD pristup

API endpointy

REST controllery

Minimal API endpointy

SignalR huby

Swagger UI

Git workflow

Pojmenovani vetvi

Pull Request

CI pipeline

Uzitecne prikazy

Dalsi dokumentace

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages