Skip to main content

Guia de desenvolupament

Aquesta guia explica com treballar al projecte LDP a nivell pràctic:

  • arrencar el projecte en local,
  • provar l’API,
  • entendre el flux de treball amb Git,
  • seguir unes normes bàsiques de codi,
  • mantenir la documentació al dia.

Públic objectiu: desenvolupadors que volen arrencar el projecte en local, provar l’API i començar a contribuir.

1. Prerequisits​

Abans de començar, assegura’t de tenir instal·lat:

Verificació ràpida:

java -version
mvn -version
docker --version
git --version

Per requisits específics del backend:

  • consulta dev/backend-setup.

2. Arrencar el projecte en local (vista ràpida)​

2.1. Backend​

  1. Assegura’t que PostgreSQL està actiu (Docker o instal·lació local).

  2. Configura variables d’entorn i perfils segons dev/backend-setup.

  3. Des de la carpeta backend/:

    mvn spring-boot:run
    # o, amb perfil local:
    # mvn spring-boot:run -Dspring-boot.run.profiles=local

Per més detall:

  • revisa dev/backend-setup.

2.2. Frontend (quan estigui definit)​

Quan el frontend estigui creat al monorepo:

  1. Ves a la carpeta frontend/.

  2. Instal·la dependències:

    npm install

  3. Arrenca el frontend:

    npm run dev

  4. Obre’l al navegador (per exemple):

    http://localhost:5173

3. Flux de treball amb Git​

3.1. Branques​

  • main
    • branca estable, preparada per desplegar.
  • Branques de feature:
    • nom recomanat: feat/nom-curt
    • exemples:
      • feat/dance-crud-improvements
      • feat/import-csv-basic
  • Branques de fix:
    • nom recomanat: fix/nom-curt
    • exemples:
      • fix/fix-cors-config
      • fix/login-redirect

3.2. Procés recomanat​

  1. Actualitza la branca principal:

    git checkout main
    git pull

  2. Crea una branca nova a partir de main:

    git checkout -b feat/nom-curt

  3. Fes els canvis:

    • codi,
    • tests,
    • documentació (si cal).

  4. Comprova que tot compila i que els tests passen.

  5. Fes commit amb un missatge clar:

    git commit -m "feat: improve dance filters on admin list"

  6. Puja la branca i crea la Pull Request (si es fa servir PR).

4. Normes de codi​

4.1. Backend (Java / Spring Boot)​

  • Noms en anglès:
    • classes, mètodes, entitats (Dance, Song, OwnershipRequest, etc.).
  • Lògica:
    • evitar lògica pesada als controllers,
    • delegar la lògica de negoci a serveis (service).
  • Validació:
    • utilitzar anotacions Bean Validation als DTOs (@NotNull, @Size, etc.),
    • fer validacions de domini als serveis si cal.
  • Errors:
    • utilitzar excepcions específiques per cada cas,
    • tenir un handler global (@ControllerAdvice) per retornar respostes d’API coherents.

4.2. Frontend (React / TypeScript)​

  • Components en anglès:
    • per exemple: DanceListPage, SongForm, ImportCsvPage.
  • Tipatge:
    • evitar any,
    • definir tipus i DTOs per a respostes de l’API.
  • Formularis:
    • utilitzar React Hook Form (o la llibreria acordada),
    • afegir validació amb Zod (o similar) quan sigui possible.
  • Estructura:
    • separar components de presentació i lògica quan tingui sentit,
    • mantenir fitxers raonablement curts i llegibles.

5. Afegir una nova funcionalitat (checklist)​

5.1. Pas 1 – Disseny ràpid​

Abans de tocar codi:

  • Pregunta’t:
    • Afecta backend? frontend? tots dos?
    • Toca model de dades (taules, entitats)?
  • Si toca model de dades:
    • revisa architecture/db-redesign-plan.

Documents d’arquitectura relacionats que pots consultar:

  • architecture/architecture-overview
  • architecture/import-system
  • architecture/security
  • architecture/ownership-workflow (si aplica)

5.2. Pas 2 – Backend​

  1. Ajusta o crea entitats i DTOs si cal.
  2. Afegeix migracions Flyway per als canvis de base de dades.
  3. Actualitza:
    • repositoris,
    • serveis,
    • controllers.
  4. Afegeix tests:
    • de servei,
    • de controller (si té sentit).
  5. Verifica:
    • que les migracions funcionen en una BD neta,
    • que els endpoints fan el que diu la documentació.

5.3. Pas 3 – Frontend​

  1. Actualitza clients d’API i tipus de dades.
  2. Afegeix o modifica pàgines, components i formularis.
  3. Afegeix validacions al client (formularis).
  4. Prova el flux complet:
    • UI → API → BD → resposta.

5.4. Pas 4 – Documentació​

En funció del tipus de canvi:

  • Arquitectura:
    • actualitza architecture/architecture-overview o el document específic.
  • Model de dades:
    • actualitza architecture/db-redesign-plan.
  • Import/staging:
    • actualitza architecture/import-system.
  • Roadmap i backlog:
    • marca tasques com fetes o en curs a roadmap/backlog,
    • si cal, ajusta l’estat de la fase a roadmap/roadmap-global.
  • Històric:
    • afegeix una entrada a history/changelog amb:
      • data,
      • resum del canvi,
      • referències (issue, PR, etc.).

6. Treballar amb la documentació (docs-web)​

6.1. Arrencar la doc en local​

Des de la carpeta docs-web/:

npm install    # primera vegada
npm run start

La documentació s’obrirà (o la pots obrir) a:

http://localhost:3000

6.2. Actualitzar documents​

  1. Localitza el fitxer adequat, per exemple:
    • architecture/security.md
    • roadmap/backlog.md
    • dev/backend-setup.md
  2. Edita el text:
    • en català,
    • mantenint estructura de títols, llistes i taules.
  3. Desa i comprova al navegador.
  4. Fes commit:
    • junt amb el codi relacionat, o en un commit separat però clar.

Per regles generals de documentació:

  • consulta meta/docs-guide.

7. Relació amb roadmap, backlog i changelog​

Documents clau:

  • Roadmap global:
    • roadmap/roadmap-global
  • Detall tècnic per fase:
    • roadmap/roadmap-technical-details
  • Backlog viu:
    • roadmap/backlog
  • Històric de canvis:
    • history/changelog

Quan tanquis una tasca o bloc rellevant:

  1. Actualitza roadmap/backlog (estat: pendent, en curs, fet).
  2. Si afecta una fase, ajusta roadmap/roadmap-global.
  3. Afegeix una entrada a history/changelog amb data i resum.

8. Ús d’IA (ChatGPT, Copilot, etc.)​

Pots utilitzar IA per:

  • refactoritzar codi,
  • generar snippets,
  • ordenar notes i convertir-les en documentació.

Bones pràctiques:

  • Dona sempre prou context:
    • fitxer,
    • fragment de codi,
    • objectiu.
  • Revisa sempre el resultat:
    • que respecti el model de dades real,
    • que segueixi les convencions del projecte.

Veure també:

  • ai/ai-roles

9. On començar si ets nou al projecte​

  1. Llegeix:
    • overview/vision
    • overview/tech-stack
  2. Mira:
    • architecture/architecture-overview
  3. Repassa:
    • roadmap/roadmap-global
    • roadmap/backlog
  4. Segueix:
    • dev/backend-setup per arrencar el backend en local.
  5. Arrenca docs-web i utilitza aquesta web com a punt de navegació principal.

A partir d’aquí, utilitza aquesta guia com a referència mentre vas treballant.