# 📜 API Contracts - PtitsPas

Ce dossier contient les **contrats d'API** qui définissent les interfaces entre les différentes couches de l'application.

## 🎯 Objectif

Garantir que **Frontend**, **Backend** et **Database** respectent des contrats stricts, permettant de les rendre **interchangeables** sans casser l'application.

---

## 📁 Structure

```
api-contracts/
├── frontend-backend/          # Contrat Frontend ↔ Backend (HTTP REST)
│   ├── openapi.yaml          # Spécification OpenAPI 3.0 (source de vérité)
│   └── generated/            # Code généré automatiquement
│       ├── dart/             # Client API pour Flutter
│       └── typescript/       # Types pour NestJS
│
└── backend-database/          # Contrat Backend ↔ Database (ORM/SQL)
    ├── schema.prisma         # Schéma Prisma (ou TypeORM entities)
    └── migrations/           # Migrations SQL versionnées
```

---

## 🔄 Workflow de Génération

### 1. Frontend ↔ Backend

**Source de vérité :** `frontend-backend/openapi.yaml`

**Génération du client Dart (Flutter) :**
```bash
cd api-contracts/frontend-backend
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i /local/openapi.yaml \
  -g dart-dio \
  -o /local/generated/dart
```

**Génération des types TypeScript (NestJS) :**
```bash
cd api-contracts/frontend-backend
npx openapi-typescript openapi.yaml --output generated/typescript/api.types.ts
```

---

### 2. Backend ↔ Database

**Source de vérité :** `backend-database/schema.prisma`

**Génération du client Prisma :**
```bash
cd api-contracts/backend-database
npx prisma generate
```

**Génération des migrations SQL :**
```bash
cd api-contracts/backend-database
npx prisma migrate dev --name <nom_migration>
```

---

## ✅ Avantages

- **Frontend interchangeable** : React, Vue, Angular → il suffit de régénérer le client API
- **Backend interchangeable** : Python, Go, Java → tant qu'il respecte `openapi.yaml`
- **Database read-only en prod** : User PostgreSQL `app_user` (pas de DDL)
- **Cohérence garantie** : Types générés = pas d'erreur de typage
- **Documentation auto** : OpenAPI = documentation interactive (Swagger UI)

---

## 📚 Documentation

- [OpenAPI 3.0 Spec](https://swagger.io/specification/)
- [Prisma Schema](https://www.prisma.io/docs/concepts/components/prisma-schema)
- [openapi-generator](https://openapi-generator.tech/)
- [openapi-typescript](https://github.com/drwpow/openapi-typescript)