package com.nexussoftware.bibliotech.servei;

import com.nexussoftware.bibliotech.model.Prestec;
import com.nexussoftware.bibliotech.repositori.PrestecRepository;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.net.http.HttpClient;   // que hi fa, aixo, aqui?

@Service
public class GestorPrestecs {

    private final PrestecRepository repositori;
    private final HttpClient http;   // un servei de negoci amb un client HTTP a dins
    // ...
}

// PRESENTACIO: converteix la peticio HTTP en una crida al servei. Res mes.
@PostMapping("/api/prestecs/{id}/devolucio")
public ResponseEntity<FitxaPrestec> retornar(@PathVariable Long id) {
    return ResponseEntity.ok(gestorPrestecs.retornar(id));
}

// APLICACIO: orquestra, delimita la transaccio, no decideix regles.
@Transactional
public FitxaPrestec retornar(Long id) {
    Prestec prestec = repositori.findById(id)
        .orElseThrow(() -> new PrestecNoTrobatException(id));
    Diner multa = prestec.registrarDevolucio(LocalDate.now(rellotge));  // la regla viu al domini
    avisos.notificarDevolucio(prestec);
    return FitxaPrestec.desDe(prestec);
}

// DOMINI: la regla de negoci. Sense Spring, sense JPA visible, sense HTTP.
public Diner registrarDevolucio(LocalDate data) {
    if (this.dataDevolucio.isPresent()) {
        throw new PrestecJaRetornatException(this.id);
    }
    this.dataDevolucio = Optional.of(data);
    this.estat = EstatPrestec.RETORNAT;
    return CalculadoraMultes.calcular(this.dataVenciment, data);
}

// AL DOMINI: una interficie que el domini defineix perque el domini la necessita.
package com.nexussoftware.bibliotech.domini.port;

public interface RepositoriPrestecs {
    Optional<Prestec> cercarPerId(Long id);
    Prestec guardar(Prestec prestec);
    List<Prestec> vencutsA(LocalDate data);
}

// A LA INFRAESTRUCTURA: la implementacio, que si que coneix JPA.
package com.nexussoftware.bibliotech.infraestructura.persistencia;

@Repository
class RepositoriPrestecsJpa implements RepositoriPrestecs {

    private final PrestecSpringDataRepository delegat;   // Spring Data, modul 11

    RepositoriPrestecsJpa(PrestecSpringDataRepository delegat) {
        this.delegat = delegat;
    }

    @Override
    public Optional<Prestec> cercarPerId(Long id) {
        return delegat.findById(id);
    }
    // ...
}

@Test
void retornarAmbRetardGeneraMulta() {
    var repositori = new RepositoriPrestecsEnMemoria();   // adaptador de prova
    var notificador  = new NotificadorSilencios();
    var rellotge = Clock.fixed(Instant.parse("2026-03-20T10:00:00Z"), ZoneId.of("Europe/Madrid"));
    var gestor = new GestorPrestecs(repositori, notificador, rellotge);

    repositori.guardar(unPrestecDe("978-0000000001", "Marta Ruiz")
        .ambVenciment(LocalDate.of(2026, 3, 10)));

    Diner multa = gestor.retornar(1L).multa();

    assertThat(multa).isEqualTo(Diner.euros("5.00"));   // 10 dies x 0,50 EUR
}

com.nexussoftware.bibliotech
├── controlador
├── servei
├── domini
└── repositori

com.nexussoftware.bibliotech
├── cataleg
├── prestecs
├── reserves
└── empleats

package com.nexussoftware.bibliotech.prestecs;

// package-private: NINGU de fora de la funcionalitat "prestecs" pot tocar aixo.
class CalculadoraMultes { ... }

src/main/java/com/nexussoftware/bibliotech/
├── BiblioTechApplication.java
├── controlador/
│   ├── PrestecController.java
│   ├── CatalegController.java
│   └── ReservaController.java
├── servei/
│   ├── GestorPrestecs.java
│   ├── ProcessadorReserves.java
│   ├── ServeiAvisos.java
│   ├── EstadistiquesBiblioTech.java
│   └── EnriquidorCataleg.java
├── domini/
│   ├── Material.java
│   ├── Llibre.java
│   ├── Revista.java
│   ├── Dvd.java
│   ├── Prestec.java
│   ├── Reserva.java
│   ├── Empleat.java
│   ├── EstatPrestec.java
│   └── Gravetat.java
├── repositori/
│   ├── PrestecRepository.java
│   ├── MaterialRepository.java
│   └── ReservaRepository.java
└── dto/
    ├── FitxaMaterialDto.java
    └── CrearPrestecDto.java

src/main/java/com/nexussoftware/bibliotech/
├── BiblioTechApplication.java
├── compartit/                        ← nomes el genuinament transversal
│   ├── Diner.java
│   ├── Isbn.java
│   ├── Gravetat.java
│   └── BiblioTechException.java
├── cataleg/
│   ├── Material.java                 (package-private on es pot)
│   ├── Llibre.java
│   ├── Revista.java
│   ├── Dvd.java
│   ├── TipusMaterial.java
│   ├── CatalegService.java           ← API publica de la funcionalitat
│   ├── CatalegController.java
│   ├── MaterialRepository.java
│   └── metadades/
│       ├── PassarelaMetadades.java   (port)
│       └── ClientMetadades.java      (adaptador HTTP)
├── prestecs/
│   ├── Prestec.java
│   ├── EstatPrestec.java
│   ├── CalculadoraMultes.java        (package-private)
│   ├── GestorPrestecs.java           ← API publica
│   ├── PrestecController.java
│   └── PrestecRepository.java
├── reserves/
│   ├── Reserva.java
│   ├── ProcessadorReserves.java
│   └── ReservaRepository.java
├── empleats/
│   ├── Empleat.java
│   └── EmpleatRepository.java
└── avisos/
    ├── NotificadorAvisos.java        (port)
    └── ServeiAvisos.java             (adaptador)

bibliotech/
├── pom.xml                       ← POM pare (packaging: pom)
├── mvnw / mvnw.cmd / .mvn/
├── bibliotech-domini/
│   ├── pom.xml
│   └── src/{main,test}/java/...
├── bibliotech-aplicacio/
│   ├── pom.xml
│   └── src/{main,test}/java/...
├── bibliotech-infraestructura/
│   ├── pom.xml
│   └── src/{main,test}/{java,resources}/...
├── bibliotech-consola/
│   ├── pom.xml
│   └── src/{main,test}/{java,resources}/...
└── bibliotech-web/
    ├── pom.xml
    └── src/{main,test}/{java,resources}/...

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <!-- Heretem de Spring Boot: ens dona el BOM amb les versions compatibles
       de mes de 400 llibreries, i la configuracio per defecte dels plugins. -->
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.4</version>
    <relativePath/>
  </parent>

  <groupId>com.nexussoftware</groupId>
  <artifactId>bibliotech</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>pom</packaging>            <!-- clau: agregador, no produeix jar -->
  <name>BiblioTech</name>
  <description>Gestio de la biblioteca tecnica interna de Nexus Software</description>

  <!-- L'ordre aqui es irrellevant: Maven ordena els moduls per les seves dependencies. -->
  <modules>
    <module>bibliotech-domini</module>
    <module>bibliotech-aplicacio</module>
    <module>bibliotech-infraestructura</module>
    <module>bibliotech-consola</module>
    <module>bibliotech-web</module>
  </modules>

  <properties>
    <java.version>21</java.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <picocli.version>4.7.6</picocli.version>
    <mapstruct.version>1.6.2</mapstruct.version>
    <springdoc.version>2.6.0</springdoc.version>
  </properties>

  <dependencyManagement>
    <dependencies>
      <!-- Els nostres propis moduls: els fills els faran servir sense repetir la versio. -->
      <dependency>
        <groupId>com.nexussoftware</groupId>
        <artifactId>bibliotech-domini</artifactId>
        <version>${project.version}</version>
      </dependency>
      <dependency>
        <groupId>com.nexussoftware</groupId>
        <artifactId>bibliotech-aplicacio</artifactId>
        <version>${project.version}</version>
      </dependency>
      <dependency>
        <groupId>com.nexussoftware</groupId>
        <artifactId>bibliotech-infraestructura</artifactId>
        <version>${project.version}</version>
      </dependency>

      <!-- Externes que Spring Boot no gestiona -->
      <dependency>
        <groupId>info.picocli</groupId>
        <artifactId>picocli-spring-boot-starter</artifactId>
        <version>${picocli.version}</version>
      </dependency>
      <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>${springdoc.version}</version>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <!-- Aquestes si que les hereta TOTHOM, perque tothom fa proves. -->
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.assertj</groupId>
      <artifactId>assertj-core</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

<project ...>
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>com.nexussoftware</groupId>
    <artifactId>bibliotech</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>bibliotech-domini</artifactId>
  <name>BiblioTech :: Domini</name>

  <!-- Fixa-t'hi be: NO HI HA <dependencies> de produccio.
       Ni Spring, ni Hibernate, ni Jackson, ni HttpClient de tercers.
       Nomes la biblioteca estandard de Java 21.
       Aixo no es un adorn: es la regla de dependencia, feta complir per Maven. -->
</project>

<project ...>
  <parent>
    <groupId>com.nexussoftware</groupId>
    <artifactId>bibliotech</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>bibliotech-infraestructura</artifactId>
  <name>BiblioTech :: Infraestructura</name>

  <dependencies>
    <dependency>
      <groupId>com.nexussoftware</groupId>
      <artifactId>bibliotech-aplicacio</artifactId>   <!-- versio heretada del pare -->
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
      <groupId>org.flywaydb</groupId>
      <artifactId>flyway-core</artifactId>
    </dependency>
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <scope>runtime</scope>
    </dependency>
  </dependencies>
</project>

# Construeix els cinc moduls en l'ordre correcte (Maven ho dedueix del graf)
./mvnw clean install

# Nomes el domini i el que necessita per compilar (-am = also make)
./mvnw -pl bibliotech-domini -am test

# L'arbre de dependencies del domini: ha de ser practicament buit
./mvnw -pl bibliotech-domini dependency:tree

package com.nexussoftware.bibliotech.domini.prestecs;

import org.springframework.stereotype.Service;   // dins de bibliotech-domini

@Service
public class CalculadoraMultes { ... }

$ ./mvnw -pl bibliotech-domini compile
[ERROR] /.../CalculadoraMultes.java:[3,32] package org.springframework.stereotype does not exist
[ERROR] /.../CalculadoraMultes.java:[5,2] cannot find symbol: class Service
[INFO] BUILD FAILURE

[ERROR] The projects in the reactor contain a cyclic reference:
        bibliotech-domini -> bibliotech-infraestructura -> bibliotech-domini

@AnalyzeClasses(packages = "com.nexussoftware.bibliotech")
class ReglesArquitecturaTest {

    @ArchTest
    static final ArchRule elDominiNoDepenDeSpring =
        noClasses().that().resideInAPackage("..domini..")
            .should().dependOnClassesThat().resideInAnyPackage("org.springframework..");

    @ArchTest
    static final ArchRule elDominiNoDepenDeJpa =
        noClasses().that().resideInAPackage("..domini..")
            .should().dependOnClassesThat().resideInAnyPackage("jakarta.persistence..");

    @ArchTest
    static final ArchRule senseCicles =
        slices().matching("com.nexussoftware.bibliotech.(*)..").should().beFreeOfCycles();
}

package com.nexussoftware.bibliotech.web.dto;

/**
 * El que l'API RETORNA d'un prestec. Contracte public, estable,
 * independent de com estigui modelada l'entitat per dins.
 */
public record PrestecResponse(
        Long id,
        String titolMaterial,
        String isbn,
        String nomEmpleat,
        LocalDate dataPrestec,
        LocalDate dataVenciment,
        LocalDate dataDevolucio,   // null si encara esta prestat: JSON no te Optional
        String estat,
        long diesRestants,         // camp calculat que l'entitat no te
        BigDecimal multa) {

    public static PrestecResponse desDe(Prestec p, LocalDate avui) {
        return new PrestecResponse(
            p.getId(),
            p.getMaterial().getTitol(),
            p.getMaterial().getIsbn().valor(),
            p.getEmpleat().getNom(),
            p.getDataPrestec(),
            p.getDataVenciment(),
            p.getDataDevolucio().orElse(null),
            p.getEstat().name(),
            ChronoUnit.DAYS.between(avui, p.getDataVenciment()),
            p.multaAcumulada(avui).quantitat());
    }
}

/**
 * El que l'API ACCEPTA per crear un prestec. Nomes els camps que
 * el client te dret a decidir. Ni id, ni version, ni estat.
 */
public record CrearPrestecRequest(
        @NotBlank @Isbn String isbn,
        @NotNull Long idEmpleat,
        @Positive @Max(30) Integer dies) {
}

@Mapper(componentModel = "spring")
public interface PrestecMapper {
    @Mapping(target = "titolMaterial", source = "material.titol")
    @Mapping(target = "nomEmpleat", source = "empleat.nom")
    PrestecResponse aResponse(Prestec prestec);
}

spring:
  application:
    name: bibliotech
  jpa:
    open-in-view: false            # desactiva-ho SEMPRE: evita consultes a la capa de vista (11-03)
    properties:
      hibernate:
        jdbc.batch_size: 25
  threads:
    virtual:
      enabled: true                # fils virtuals de Java 21 (10-06), s'explica a 12-04

server:
  port: 8080
  shutdown: graceful               # aturada ordenada, es desenvolupa a 12-06

bibliotech:                        # les nostres propietats, tipades a PropietatsBiblioTech
  prestec:
    dies-per-defecte: 15
    maxim-per-empleat: 3
  multa:
    euros-per-dia: 0.50
    maxima: 20.00
  metadades:
    url: https://api.metadades.exemple/v1
    temps-espera: 3s

logging:
  level:
    com.nexussoftware.bibliotech: INFO

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/bibliotech
    username: bibliotech
    password: bibliotech            # local, exhaurible, mai reutilitzada fora
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: validate            # mai 'update': l'esquema el governa Flyway (12-06)
  flyway:
    enabled: true

logging:
  level:
    com.nexussoftware.bibliotech: DEBUG
    org.hibernate.SQL: DEBUG

spring:
  datasource:
    url: ${BIBLIOTECH_DB_URL}       # sense valor per defecte: si falta, l'app NO arrenca
    username: ${BIBLIOTECH_DB_USER}
    password: ${BIBLIOTECH_DB_PASSWORD}
    hikari:
      maximum-pool-size: 20
  jpa:
    show-sql: false
    hibernate:
      ddl-auto: validate

server:
  error:
    include-stacktrace: never       # mai filtrar traces al client (12-04, 12-07)
    include-message: never

logging:
  level:
    root: WARN
    com.nexussoftware.bibliotech: INFO

# En desenvolupament
./mvnw -pl bibliotech-web spring-boot:run -Dspring-boot.run.profiles=dev

# En produccio (variable d'entorn, no argument)
SPRING_PROFILES_ACTIVE=prod java -jar bibliotech-web.jar

# Cercar secrets a TOT l'historial, no nomes a l'arbre actual
gitleaks detect --source . --verbose

# Com a enganxall de pre-commit, perque no hi arribi ni a entrar
pre-commit run --all-files

# --- Maven ---
target/
!.mvn/wrapper/maven-wrapper.jar
.mvn/timing.properties
dependency-reduced-pom.xml

# --- Java ---
*.class
*.jar
*.war
hs_err_pid*.log
replay_pid*.log

# --- IDE: IntelliJ ---
.idea/
*.iml
*.iws

# --- IDE: Eclipse ---
.classpath
.project
.settings/
bin/

# --- IDE: VS Code (es versiona launch.json si l'equip el comparteix) ---
.vscode/*
!.vscode/launch.json
!.vscode/settings.json

# --- Sistema operatiu ---
.DS_Store
Thumbs.db

# --- Local i secrets ---
.env
*.local.yml
application-local.yml
/config/secrets/
*.p12
*.jks
*.pem

feat(api)!: eliminar el camp `disponible` de MaterialResponse

BREAKING CHANGE: els clients han de fer servir `unitatsDisponibles`, que es un
enter, en lloc del booleà `disponible`. El camp antic va estar marcat
com a obsolet des de la versió 1.4.0.

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 4
max_line_length = 120

[*.{xml,yml,yaml,json}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false   # dos espais finals = salt de linia a Markdown

[*.{sh,bash}]
indent_size = 2

<build>
  <pluginManagement>
    <plugins>
      <plugin>
        <groupId>com.diffplug.spotless</groupId>
        <artifactId>spotless-maven-plugin</artifactId>
        <version>2.43.0</version>
        <configuration>
          <java>
            <palantirJavaFormat/>          <!-- o <googleJavaFormat/> -->
            <removeUnusedImports/>
            <importOrder>
              <order>java,javax,jakarta,org,com,com.nexussoftware,</order>
            </importOrder>
            <licenseHeader>
              <content>/* BiblioTech - Nexus Software */</content>
            </licenseHeader>
          </java>
          <pom>
            <sortPom/>
          </pom>
        </configuration>
        <executions>
          <execution>
            <goals>
              <!-- 'check' fa fallar la construccio; 'apply' ho arregla.
                   A CI volem que falli. -->
              <goal>check</goal>
            </goals>
            <phase>validate</phase>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </pluginManagement>
</build>

./mvnw spotless:apply    # formata tot el projecte
./mvnw spotless:check    # nomes comprova: aixo es el que corre a CI

# .git-blame-ignore-revs
# Reformatacio inicial amb Spotless (sense canvis funcionals)
a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

git config blame.ignoreRevsFile .git-blame-ignore-revs

# BiblioTech

Sistema de gestió de la biblioteca tècnica interna de Nexus Software.
Gestiona el catàleg de materials (llibres, revistes, DVD), els préstecs
a empleats, les reserves i les multes per retard.

## Requisits

| Eina | Versió | Comprovació |
|---|---|---|
| JDK | 21+ | `java -version` |
| Docker | 24+ | `docker --version` |
| Maven | No cal: fes servir `./mvnw` | — |

## Arrencada ràpida

Comprovació:

Documentació de l'API: <http://localhost:8080/swagger-ui.html>

## Ordres habituals

| Objectiu | Ordre |
|---|---|
| Compilar-ho tot | `./mvnw clean install` |
| Només proves unitàries | `./mvnw test` |
| Proves d'integració | `./mvnw verify` |
| Informe de cobertura | `./mvnw verify` → `target/site/jacoco/index.html` |
| Formatar el codi | `./mvnw spotless:apply` |
| CLI | `java -jar bibliotech-consola/target/bibliotech-consola.jar cataleg llistar` |

## Estructura

| Mòdul | Responsabilitat |
|---|---|
| `bibliotech-domini` | Entitats i regles de negoci. Sense dependències externes |
| `bibliotech-aplicacio` | Casos d'ús |
| `bibliotech-infraestructura` | JPA, HTTP, correu, configuració de Spring |
| `bibliotech-consola` | CLI amb Picocli |
| `bibliotech-web` | API REST |

Decisions d'arquitectura: [`docs/adr/`](docs/adr/).

## Configuració

Totes les propietats pròpies estan sota `bibliotech.*` a `application.yml`.
En producció s'injecten per variables d'entorn (vegeu `docs/desplegament.md`).
**Mai** no s'afegeixen secrets al repositori.

## Contribuir

1. Branca des de `main`: `feature/descripcio-curta`
2. Commits amb [Conventional Commits](https://www.conventionalcommits.org/)
3. `./mvnw verify` i `./mvnw spotless:check` en verd
4. Pull Request; requereix una aprovació i CI en verd

# ADR-004: Renunciar a `sealed` a la jerarquia Material

- **Estat:** Acceptada
- **Data:** 2026-06-18
- **Decisors:** Marta Ruiz, Diego Alonso

## Context

`Material` era una interfície `sealed` (Java 17, mòdul 10) amb `Llibre`, `Revista`
i `Dvd` com a úniques implementacions permeses, cosa que habilitava pattern
matching exhaustiu sense `default`.

En passar a JPA amb estratègia `SINGLE_TABLE`, Hibernate necessita crear proxies
per subclasse i les entitats no poden pertànyer a una jerarquia segellada
gestionada d'aquesta manera.

## Decisió

Convertir `Material` en classe abstracta no segellada, amb `@Inheritance(SINGLE_TABLE)`
i `@DiscriminatorColumn(name = "tipus")`.

## Conseqüències

**Positives:** persistència polimòrfica amb una sola consulta; sense JOIN per tipus.

**Negatives:** es perd l'exhaustivitat del `switch`; cal mantenir una branca
`default` que llanci `IllegalStateException`. Qualsevol pot heretar de `Material`
sense que el compilador ho impedeixi.

**Mitigació:** una prova d'ArchUnit comprova que les subclasses de `Material`
són exactament tres.

## Alternatives descartades

- **`TABLE_PER_CLASS`:** mantindria el model, però les consultes polimòrfiques
  es converteixen en `UNION` i el rendiment del catàleg es degrada.
- **Model de domini separat del de persistència:** conserva `sealed`, a canvi
  de duplicar nou classes i els seus mapatges. Desproporcionat per a aquest projecte.

# compose.yaml -- nomes dependencies, NO l'aplicacio.
# En desenvolupament l'app corre a l'IDE, amb recarrega en calent i depurador.
services:
  postgres:
    image: postgres:16-alpine
    container_name: bibliotech-db
    environment:
      POSTGRES_DB: bibliotech
      POSTGRES_USER: bibliotech
      POSTGRES_PASSWORD: bibliotech
    ports:
      - "5432:5432"
    volumes:
      - bibliotech-dades:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U bibliotech"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  bibliotech-dades:

docker compose up -d        # aixecar
docker compose logs -f      # veure registres
docker compose down         # parar (les dades sobreviuen al volum)
docker compose down -v      # parar i ESBORRAR les dades

#!/usr/bin/env bash
set -euo pipefail          # -e: falla al primer error; -u: variable sense definir es error;
                           # -o pipefail: una fallada al mig d'una canonada compta

cd "$(dirname "$0")/.."    # executable des de qualsevol directori

echo "==> Aixecant dependencies"
docker compose up -d --wait     # --wait espera que el healthcheck estigui en verd

echo "==> Construint"
./mvnw -q clean install -DskipTests

echo "==> Arrencant BiblioTech (perfil dev)"
exec ./mvnw -pl bibliotech-web spring-boot:run -Dspring-boot.run.profiles=dev

bibliotech/
├── .editorconfig                       # estil comu a tots els editors
├── .gitignore
├── .git-blame-ignore-revs              # ignora el commit de reformatacio
├── .github/
│   └── workflows/
│       └── ci.yml                      # s'escriu a 12-05
├── compose.yaml                        # PostgreSQL local
├── mvnw, mvnw.cmd, .mvn/               # wrapper: mateixa versio de Maven per a tothom (11-05)
├── pom.xml                             # POM pare: moduls + dependencyManagement
├── README.md
├── docs/
│   ├── adr/
│   │   ├── 0001-arquitectura-per-capes-amb-ports.md
│   │   ├── 0002-projecte-multimodul-maven.md
│   │   ├── 0003-postgresql-en-lloc-de-h2.md
│   │   └── 0004-renunciar-a-sealed-a-material.md
│   └── desplegament.md                 # 12-06
├── scripts/
│   ├── dev.sh
│   └── bibliotech                      # llancador de la CLI (12-03)
│
├── bibliotech-domini/                  # -- SENSE DEPENDENCIES EXTERNES --
│   ├── pom.xml
│   └── src/main/java/com/nexussoftware/bibliotech/domini/
│       ├── compartit/
│       │   ├── Diner.java
│       │   ├── Isbn.java
│       │   ├── Gravetat.java
│       │   └── BiblioTechException.java        # jerarquia del modul 6
│       ├── cataleg/
│       │   ├── Material.java
│       │   ├── Llibre.java  Revista.java  Dvd.java
│       │   ├── TipusMaterial.java
│       │   └── port/
│       │       ├── RepositoriMaterials.java
│       │       └── PassarelaMetadades.java
│       ├── prestecs/
│       │   ├── Prestec.java
│       │   ├── EstatPrestec.java
│       │   ├── CalculadoraMultes.java
│       │   ├── ReglaTarifa.java                # Estrategia, es formalitza a 12-02
│       │   └── port/RepositoriPrestecs.java
│       ├── reserves/
│       │   ├── Reserva.java
│       │   └── port/RepositoriReserves.java
│       └── empleats/
│           ├── Empleat.java
│           └── port/RepositoriEmpleats.java
│
├── bibliotech-aplicacio/               # -- casos d'us --
│   ├── pom.xml                         # depen NOMES de domini
│   └── src/main/java/com/nexussoftware/bibliotech/aplicacio/
│       ├── prestecs/
│       │   ├── GestionarPrestecs.java          # port d'entrada
│       │   └── GestorPrestecs.java             # implementacio
│       ├── cataleg/
│       │   ├── ConsultarCataleg.java
│       │   ├── CatalegService.java
│       │   └── EnriquidorCataleg.java
│       ├── reserves/ProcessadorReserves.java
│       ├── avisos/ServeiAvisos.java
│       └── estadistiques/EstadistiquesBiblioTech.java
│
├── bibliotech-infraestructura/         # -- adaptadors de sortida --
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/nexussoftware/bibliotech/infraestructura/
│       │   ├── persistencia/
│       │   │   ├── RepositoriPrestecsJpa.java
│       │   │   ├── PrestecSpringDataRepository.java
│       │   │   ├── RepositoriMaterialsJpa.java
│       │   │   └── convertidor/IsbnConverter.java
│       │   ├── metadades/ClientMetadades.java        # HttpClient (modul 9)
│       │   ├── avisos/NotificadorCorreu.java
│       │   ├── sockets/ServidorCataleg.java          # el del modul 9, segueix viu
│       │   └── config/
│       │       ├── PropietatsBiblioTech.java
│       │       ├── ConfiguracioRellotge.java         # Clock injectable (10-05)
│       │       └── AspecteCronometre.java            # AOP (11-02)
│       └── resources/db/migration/                   # Flyway (12-06)
│           ├── V1__esquema_inicial.sql
│           └── V2__indexs_cataleg.sql
│
├── bibliotech-consola/                 # -- adaptador d'entrada: CLI (12-03) --
│   ├── pom.xml
│   └── src/main/java/com/nexussoftware/bibliotech/consola/
│       ├── BiblioTechCli.java
│       └── ordres/…
│
└── bibliotech-web/                     # -- adaptador d'entrada: REST (12-04) --
    ├── pom.xml
    └── src/main/
        ├── java/com/nexussoftware/bibliotech/web/
        │   ├── BiblioTechApplication.java
        │   ├── prestecs/PrestecController.java
        │   ├── cataleg/CatalegController.java
        │   ├── dto/…
        │   └── error/GestorGlobalErrors.java
        └── resources/
            ├── application.yml
            ├── application-dev.yml
            ├── application-prod.yml
            └── logback-spring.xml                    # SLF4J + MDC (11-07)

$ ./mvnw -pl bibliotech-domini dependency:tree
[INFO] com.nexussoftware:bibliotech-domini:jar:1.0.0-SNAPSHOT
[INFO] +- org.springframework.boot:spring-boot-starter-test:jar:3.3.4:test
[INFO] \- org.assertj:assertj-core:jar:3.25.3:test

package com.nexussoftware.bibliotech.domini.avisos;

import com.nexussoftware.bibliotech.domini.prestecs.Prestec;
import com.nexussoftware.bibliotech.infraestructura.correu.ServidorSmtp;
import org.springframework.stereotype.Service;

@Service
public class ServeiAvisos {

    private final ServidorSmtp smtp = new ServidorSmtp("smtp.nexussoftware.com", 587);

    public void avisarVenciment(Prestec prestec) {
        String cos = "Hola " + prestec.getEmpleat().getNom()
                   + ", el prestec de \"" + prestec.getMaterial().getTitol()
                   + "\" venc el " + prestec.getDataVenciment() + ".";
        smtp.enviar(prestec.getEmpleat().getCorreu(), "Avis de venciment", cos);
    }
}

spring:
  datasource:
    url: jdbc:postgresql://db-produccio.nexussoftware.com:5432/bibliotech
    username: admin
    password: Nexus2026!
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
server:
  port: 8080
  error:
    include-stacktrace: always
bibliotech:
  metadades:
    api-key: sk-live-9f3a2b1c8d7e6f5a
logging:
  level:
    root: DEBUG

// bibliotech-domini/…/domini/avisos/port/NotificadorAvisos.java
package com.nexussoftware.bibliotech.domini.avisos.port;

import com.nexussoftware.bibliotech.domini.avisos.Avis;

/**
 * Port de sortida: el domini declara QUE necessita (notificar),
 * sense dir COM (correu, SMS, consola, cua de missatges).
 */
public interface NotificadorAvisos {
    void notificar(Avis avis);
}

// bibliotech-domini/…/domini/avisos/Avis.java
package com.nexussoftware.bibliotech.domini.avisos;

public record Avis(String destinatari,
                   TipusAvis tipus,
                   String nomEmpleat,
                   String titolMaterial,
                   LocalDate data) {

    public static Avis perVenciment(Prestec prestec) {
        return new Avis(
            prestec.correuDeLempleat(),            // metode del mateix Prestec: sense cadena de getters
            TipusAvis.VENCIMENT,
            prestec.nomDeLempleat(),
            prestec.titolDelMaterial(),
            prestec.getDataVenciment());
    }
}

// bibliotech-aplicacio/…/aplicacio/avisos/ServeiAvisos.java
package com.nexussoftware.bibliotech.aplicacio.avisos;

public class ServeiAvisos {

    private final NotificadorAvisos notificador;   // el PORT, no la implementacio
    private final RepositoriPrestecs prestecs;
    private final Clock rellotge;                  // 10-05: mai LocalDate.now() a pel

    public ServeiAvisos(NotificadorAvisos notificador,
                        RepositoriPrestecs prestecs,
                        Clock rellotge) {
        this.notificador = notificador;
        this.prestecs = prestecs;
        this.rellotge = rellotge;
    }

    public int avisarVencimentsProxims(int diesAntelacio) {
        LocalDate limit = LocalDate.now(rellotge).plusDays(diesAntelacio);
        List<Prestec> proxims = prestecs.vencutsA(limit);
        proxims.forEach(p -> notificador.notificar(Avis.perVenciment(p)));
        return proxims.size();
    }
}

// bibliotech-infraestructura/…/infraestructura/avisos/NotificadorCorreu.java
package com.nexussoftware.bibliotech.infraestructura.avisos;

@Component
class NotificadorCorreu implements NotificadorAvisos {

    private static final Logger log = LoggerFactory.getLogger(NotificadorCorreu.class);

    private final JavaMailSender correu;
    private final PropietatsBiblioTech props;      // host, port i remitent venen d'aqui

    NotificadorCorreu(JavaMailSender correu, PropietatsBiblioTech props) {
        this.correu = correu;
        this.props = props;
    }

    @Override
    public void notificar(Avis avis) {
        var missatge = new SimpleMailMessage();
        missatge.setFrom(props.avisos().remitent());
        missatge.setTo(avis.destinatari());
        missatge.setSubject("BiblioTech: avis de venciment");
        missatge.setText("""
                Hola %s,

                El prestec de "%s" venc el %s.

                -- BiblioTech, Nexus Software
                """.formatted(avis.nomEmpleat(), avis.titolMaterial(), avis.data()));
        try {
            correu.send(missatge);
        } catch (MailException e) {
            // Frontera d'errors (06-07): traduir a l'excepcio del domini
            log.warn("No s'ha pogut enviar l'avis a {}", avis.destinatari(), e);
            throw new NotificacioFallidaException(avis.destinatari(), e);
        }
    }
}

// bibliotech-infraestructura/…/infraestructura/config/ConfiguracioAvisos.java
@Configuration
class ConfiguracioAvisos {

    @Bean
    ServeiAvisos serveiAvisos(NotificadorAvisos notificador,
                              RepositoriPrestecs prestecs,
                              Clock rellotge) {
        return new ServeiAvisos(notificador, prestecs, rellotge);
    }
}

// DOMINI: les dades de l'informe. Sense PDF, sense fitxers, sense dates de servidor.
package com.nexussoftware.bibliotech.domini.informes;

public record InformeMensual(YearMonth periode,
                             List<LiniaMaterial> mesPrestats,
                             List<LiniaEmpleat> mesMultats,
                             double percentatgeDevolucionsAmbRetard) {

    public String nomSuggerit() {
        return "bibliotech-%s.pdf".formatted(periode);   // yyyy-MM
    }
}

// PORT: convertir l'informe en bytes. El domini no sap que existeix el PDF.
package com.nexussoftware.bibliotech.domini.informes.port;

public interface GeneradorInforme {
    byte[] generar(InformeMensual informe);
    String tipusMime();    // "application/pdf", "text/csv"...
}

// PORT: on es desa. El domini no sap si es disc, S3 o base de dades.
public interface MagatzemInformes {
    URI guardar(String nom, byte[] contingut, String tipusMime);
}

// PORT: d'on surten els agregats. El domini no sap que es JPQL.
public interface RepositoriEstadistiques {
    List<LiniaMaterial> materialsMesPrestats(YearMonth periode, int limit);
    List<LiniaEmpleat> empleatsMesMultats(YearMonth periode, int limit);
    double percentatgeAmbRetard(YearMonth periode);
}

// APLICACIO
package com.nexussoftware.bibliotech.aplicacio.informes;

public interface EmetreInformeMensual {           // port d'ENTRADA
    ResultatInforme emetre(YearMonth periode, boolean enviarPerCorreu);
}

public class ServeiInformeMensual implements EmetreInformeMensual {

    private final RepositoriEstadistiques estadistiques;
    private final GeneradorInforme generador;
    private final MagatzemInformes magatzem;
    private final NotificadorAvisos notificador;
    private final Clock rellotge;

    // constructor amb els cinc ports...

    @Override
    public ResultatInforme emetre(YearMonth periode, boolean enviarPerCorreu) {
        var informe = new InformeMensual(
                periode,
                estadistiques.materialsMesPrestats(periode, 10),
                estadistiques.empleatsMesMultats(periode, 10),
                estadistiques.percentatgeAmbRetard(periode));

        byte[] contingut = generador.generar(informe);
        URI ubicacio = magatzem.guardar(informe.nomSuggerit(), contingut, generador.tipusMime());

        if (enviarPerCorreu) {
            notificador.notificar(Avis.informeDisponible(periode, ubicacio));
        }
        return new ResultatInforme(periode, ubicacio, contingut.length);
    }
}

// infraestructura: automatic el dia 1 a les 06:00
@Component
class PlanificadorInformes {
    private final EmetreInformeMensual cas;
    @Scheduled(cron = "0 0 6 1 * *")
    void mensual() { cas.emetre(YearMonth.now().minusMonths(1), true); }
}

// consola (12-03)
@Command(name = "informe", description = "Genera l'informe mensual d'us")
class OrdreInforme implements Callable<Integer> { … }

// web (12-04)
@PostMapping("/api/informes/{periode}")
ResponseEntity<InformeResponse> generar(@PathVariable YearMonth periode) { … }

spring:
  application:
    name: bibliotech
  jpa:
    open-in-view: false
    hibernate:
      ddl-auto: validate        # l'esquema el governa Flyway; validate detecta descuadres
  flyway:
    enabled: true

server:
  port: ${SERVER_PORT:8080}     # amb valor per defecte: no es un secret
  shutdown: graceful
  error:
    include-stacktrace: never
    include-message: never

bibliotech:
  metadades:
    url: https://api.metadades.exemple/v1
    temps-espera: 3s
    # api-key NO es aqui: arriba per variable d'entorn

logging:
  level:
    root: INFO
    com.nexussoftware.bibliotech: INFO

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/bibliotech
    username: bibliotech
    password: bibliotech        # acceptable: base local en un contenidor efimer
  jpa:
    show-sql: true

server:
  error:
    include-stacktrace: on_param   # ?trace=true, comode en depurar

bibliotech:
  metadades:
    api-key: ${METADADES_API_KEY:clau-de-desenvolupament}

logging:
  level:
    com.nexussoftware.bibliotech: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.orm.jdbc.bind: TRACE   # veure els parametres lligats: nomes a dev

spring:
  datasource:
    url: ${BIBLIOTECH_DB_URL}
    username: ${BIBLIOTECH_DB_USER}         # usuari amb permisos minims, NO admin
    password: ${BIBLIOTECH_DB_PASSWORD}
    hikari:
      maximum-pool-size: 20
  jpa:
    show-sql: false

bibliotech:
  metadades:
    api-key: ${METADADES_API_KEY}           # sense defecte: si falta, no arrenca

logging:
  level:
    root: WARN
    com.nexussoftware.bibliotech: INFO