Przejdź do treści

Dokumentacja dla developerów

Witaj w sekcji dokumentacji technicznej systemu Masaku.

Dla kogo jest ta sekcja?

Ta część dokumentacji jest przeznaczona dla:

  • Frontend developerów - pracujących z Angular/Nx
  • Backend developerów - pracujących z .NET C#
  • Full-stack developerów - pracujących z całym systemem
  • DevOps engineers - zarządzających infrastrukturą i CI/CD

Przegląd techniczny

Architektura systemu

System Masaku składa się z dwóch głównych komponentów:

Frontend: masaku-portal - Angular 14 z TypeScript - Nx monorepo (32+ bibliotek) - NGXS state management - Material Design - Multi-region support (DE/AT)

Backend: masaku-api - .NET C# ASP.NET Core - Layered architecture - Entity Framework - SQL Server database - Azure cloud hosting

Tematy techniczne

Architektura

Szczegółowy opis architektury systemu, wzorców projektowych i decyzji technicznych.

Frontend

Biblioteki projektu

Dokumentacja 32 bibliotek w workspace Nx, ich celów i wzajemnych zależności.

Kluczowe koncepty frontend: - Struktura Nx workspace i library projects - NGXS state management z immer - Routing i lazy loading - Abstrakcyjne klasy bazowe - Komponenty form i walidacja - Internacjonalizacja (i18n) - Multi-region builds

Backend

Warstwy aplikacji

Opis warstw architektury backend: API, Services, Repository, Domain.

Kluczowe koncepty backend: - Layered architecture pattern - Dependency Injection - Entity Framework migrations - Authentication & Authorization - Background jobs & message queues - Exception handling

Baza danych

Schemat bazy danych, migracje Liquibase, optymalizacja zapytań.

Integracje

Integracje z systemami zewnętrznymi: Azure AD, email, storage, płatności.

Deployment

Procesy CI/CD, Azure Pipelines, konfiguracja środowisk.

Testowanie

Strategie testowania: unit tests, integration tests, E2E tests.

Quick Start dla developerów

Setup środowiska lokalnego

Wymagania

# Frontend
Node.js 16+
npm 8+
Angular CLI 14

# Backend
.NET SDK 6.0+
Docker Desktop
SQL Server (via Docker)

Uruchomienie frontend

cd masaku-portal
npm install
npm start              # http://localhost:4200

Uruchomienie backend

# 1. Uruchom lokalne serwisy
cd masaku-api/docker
docker-compose up      # SQL Server, Azurite, MailHog

# 2. Uruchom API
cd ../
dotnet restore
dotnet run --project Masaku.API

Typowy workflow

Praca nad nową funkcją

# 1. Utwórz branch
git checkout -b feature/nazwa-funkcji

# 2. Frontend: wygeneruj komponent
nx g component nazwa --project=nazwa-biblioteki

# 3. Backend: dodaj endpoint
# Edytuj Controllers/, Services/, Repository/

# 4. Testy
npm test                    # Frontend
dotnet test                 # Backend

# 5. Commit i push
git add .
git commit -m "feat: opis funkcji"
git push origin feature/nazwa-funkcji

# 6. Utwórz Pull Request

Konwencje i standardy

Nazewnictwo

Frontend: - Komponenty: PascalCase (np. BudgetListComponent) - Serwisy: PascalCase z sufixem Service (np. BudgetService) - State: PascalCase z sufixem State (np. BudgetState) - Pliki: kebab-case (np. budget-list.component.ts)

Backend: - Klasy: PascalCase (np. BudgetController) - Metody: PascalCase (np. GetBudgetById) - Zmienne: camelCase (np. budgetId) - Namespace: hierarchiczny (np. Masaku.Services.Budget)

Git workflow

  • main - branch produkcyjny
  • develop - branch developerski
  • feature/* - nowe funkcjonalności
  • bugfix/* - poprawki błędów
  • hotfix/* - pilne poprawki na produkcji

Code review

Pull Requesty wymagają: - ✅ Wszystkie testy przechodzą - ✅ Brak błędów lintingu - ✅ Code review przez min. 1 developera - ✅ Aktualizacja dokumentacji (jeśli dotyczy)

Narzędzia deweloperskie

Frontend

  • IDE: VS Code / WebStorm
  • Debugowanie: Chrome DevTools + Angular DevTools
  • Testy: Jest
  • Bundle analysis: npm run bundle:analyze
  • Linting: ESLint

Backend

  • IDE: Visual Studio / Rider / VS Code
  • Debugowanie: Visual Studio Debugger / .NET CLI
  • Testy: xUnit / NUnit
  • DB Management: DBeaver, Azure Data Studio
  • API Testing: Postman, Swagger UI

DevOps

  • CI/CD: Azure Pipelines
  • Monitoring: Application Insights
  • Logs: Azure Monitor
  • Containers: Docker

Zasoby

Dokumentacja zewnętrzna

Repozytoria

  • masaku-portal: Angular frontend
  • masaku-api: .NET backend
  • masaku-docs: Ta dokumentacja

Komunikacja

  • Slack/Teams: Kanał #masaku-dev
  • Jira/Azure Boards: Trackowanie tasków
  • Confluence/Wiki: Notatki techniczne

Wersja dokumentacji: 1.0 Ostatnia aktualizacja: 2025-10-24