08 - Documentazione Professionale con Claude

Documentazione Professionale con Claude

La documentazione è spesso trascurata nei progetti personali, ma è fondamentale per la manutenibilità a lungo termine. Claude eccelle nella generazione di documentazione tecnica chiara, strutturata e professionale.

In questo articolo vedremo come usare Claude per creare README professionali, documentazione API, Architecture Decision Records (ADR) e guide per sviluppatori.

README Professionale

<role>Sei un Technical Writer esperto</role>

<context>
Progetto: Order Management Service
Stack: Spring Boot 3.2, PostgreSQL, Kafka
Tipo: Microservizio per e-commerce
</context>

<task>
Genera un README.md professionale che includa:
1. Descrizione progetto
2. Architettura (con diagramma Mermaid)
3. Quick Start (Docker)
4. API endpoints principali
5. Configurazione ambiente
6. Testing
7. Contributing guidelines
</task>

# Order Management Service

Microservizio per la gestione ordini di una piattaforma e-commerce.

## Architettura

```mermaid
graph TB
    Client[Frontend] --> API[Order API]
    API --> Service[Order Service]
    Service --> DB[(PostgreSQL)]
    Service --> Kafka[Kafka]
    Kafka --> Notification[Notification Service]
```

## Quick Start

### Prerequisiti
- Docker e Docker Compose
- Java 21 (per sviluppo locale)

### Avvio con Docker

```bash
# Clone repository
git clone https://github.com/company/order-service.git
cd order-service

# Avvia tutti i servizi
docker compose up -d

# Verifica stato
docker compose ps
```

L'API sarà disponibile su `http://localhost:8080`

## API Endpoints

| Metodo | Endpoint | Descrizione |
|--------|----------|-------------|
| POST | /api/v1/orders | Crea nuovo ordine |
| GET | /api/v1/orders/{id} | Ottieni ordine |
| GET | /api/v1/orders | Lista ordini (paginata) |
| PATCH | /api/v1/orders/{id}/status | Aggiorna stato |

Documentazione completa: [Swagger UI](http://localhost:8080/swagger-ui.html)

## Configurazione

| Variabile | Descrizione | Default |
|-----------|-------------|---------|
| DATABASE_URL | Connection string PostgreSQL | - |
| KAFKA_BOOTSTRAP_SERVERS | Kafka brokers | localhost:9092 |
| JWT_SECRET | Chiave firma JWT | - |

## Testing

```bash
# Unit tests
./mvnw test

# Integration tests
./mvnw verify -P integration-tests

# Con Testcontainers
./mvnw test -Dspring.profiles.active=test
```

## Contributing

1. Fork del repository
2. Crea branch feature (`git checkout -b feature/nuova-feature`)
3. Commit changes (`git commit -m 'feat: aggiungi nuova feature'`)
4. Push al branch (`git push origin feature/nuova-feature`)
5. Apri Pull Request

Architecture Decision Records (ADR)

Gli ADR documentano le decisioni architetturali importanti con il contesto che ha portato a quella scelta.

<task>
Scrivi un ADR per la decisione di usare Event Sourcing
per la gestione degli ordini.

Contesto:
- Requisito di audit trail completo
- Possibilità di ricostruire stato storico
- Team con esperienza limitata in event sourcing
- Database PostgreSQL già in uso
</task>

# ADR-001: Event Sourcing per la Gestione Ordini

## Status
Accettato

## Data
2025-02-01

## Contesto
Il sistema di gestione ordini richiede:
- Audit trail completo di tutte le modifiche
- capacità di ricostruire lo stato a qualsiasi punto nel tempo
- Tracciabilita per compliance normativa
- Debug efficace di problemi in produzione

## Decisione
Adottiamo Event Sourcing per il dominio Order con le seguenti caratteristiche:
- Ogni modifica viene salvata come evento immutabile
- Lo stato corrente viene ricostruito applicando gli eventi
- Snapshot periodici per performance
- Proiezioni per query ottimizzate

## Conseguenze

### Positive
- Audit trail "gratis" e completo
- Ricostruzione stato storico per debug
- Facile implementazione di undo/replay
- Natural fit per event-driven architecture

### Negative
- Complessità maggiore rispetto a CRUD tradizionale
- Query più complesse (necessità di proiezioni)
- Storage maggiore (tutti gli eventi)
- Curva di apprendimento per il team

### Mitigazioni
- Formazione team su event sourcing patterns
- Implementazione graduale (solo dominio Order inizialmente)
- Snapshot ogni 100 eventi per performance
- Proiezioni dedicate per query frequenti

## Alternative Considerate

### 1. CRUD con Audit Log separato
- Pro: Più semplice, familiare
- Contro: Audit log può divergere, ricostruzione difficile

### 2. Temporal Tables (PostgreSQL)
- Pro: Supporto nativo database
- Contro: Limitato a record-level, no business events

Documentazione API

/**
 * Controller REST per la gestione degli ordini.
 *
 * <p>Fornisce endpoint per CRUD ordini e gestione stati.
 * Tutti gli endpoint richiedono autenticazione JWT.</p>
 *
 * @see OrderService
 * @since 1.0
 */
@RestController
@RequestMapping("/api/v1/orders")
@Tag(name = "Orders", description = "Gestione ordini")
public class OrderController {

    /**
     * Crea un nuovo ordine.
     *
     * <p>Valida la disponibilità dei prodotti e inizializza
     * il processo di pagamento.</p>
     *
     * @param request dati del nuovo ordine
     * @return ordine creato con status PENDING_PAYMENT
     * @throws ProductNotAvailableException se prodotto esaurito
     * @throws InvalidOrderException se dati non validi
     */
    @PostMapping
    @Operation(
        summary = "Crea nuovo ordine",
        description = "Crea un ordine e inizializza il pagamento"
    )
    @ApiResponses({
        @ApiResponse(responseCode = "201", description = "Ordine creato"),
        @ApiResponse(responseCode = "400", description = "Dati non validi"),
        @ApiResponse(responseCode = "409", description = "Prodotto non disponibile")
    })
    public ResponseEntity<OrderResponse> createOrder(
            @Valid @RequestBody CreateOrderRequest request) {
        // ...
    }
}

Developer Guide

# Guida per Sviluppatori

## Setup Ambiente Locale

### 1. Prerequisiti
- Java 21 (consigliato: SDKMAN)
- Docker Desktop
- IDE con supporto Lombok (IntelliJ IDEA consigliato)

### 2. Clona e Configura

```bash
git clone https://github.com/company/order-service.git
cd order-service

# Avvia dipendenze
docker compose up -d postgres kafka

# Configura environment
cp .env.example .env
# Modifica .env con i tuoi valori

# Avvia applicazione
./mvnw spring-boot:run
```

## Struttura Progetto

```
src/main/java/com/company/orders/
├── order/          # Feature: gestione ordini
├── payment/        # Feature: integrazione pagamenti
├── shared/         # Codice condiviso
└── config/         # Configurazioni Spring
```

## Convenzioni Codice

### Commit Messages
Usiamo Conventional Commits:
- `feat:` nuova funzionalità
- `fix:` bug fix
- `docs:` documentazione
- `refactor:` refactoring
- `test:` aggiunta/modifica test

### Branch Naming
- `feature/nome-feature`
- `bugfix/descrizione-bug`
- `hotfix/fix-critico`

## Testing

### Unit Test
```bash
./mvnw test
```

### Integration Test
```bash
./mvnw verify -P integration-tests
```

I test di integrazione usano Testcontainers per PostgreSQL e Kafka.

## Code Review Checklist

- [ ] Test unitari aggiunti/aggiornati
- [ ] Javadoc per metodi pubblici
- [ ] Nessun warning del compiler
- [ ] Formattazione corretta (./mvnw spotless:apply)
- [ ] Nessun secret hardcoded

Checklist Documentazione

Conclusione

La documentazione è un investimento che ripaga nel tempo. Claude può accelerare drasticamente la creazione di documentazione professionale.

Nel prossimo articolo, vedremo come usare Claude per il Deploy e DevOps: containerizzazione, CI/CD, monitoring e logging.