datacat/documentation/local-setup.md

# Lancer Datacat en local (sans Docker)

## Prérequis

| Outil | Version | Lien |
|-------|---------|------|
| Node.js | 22 LTS | https://nodejs.org |
| pnpm | 10.33.0 | `npm install -g pnpm@10.33.0` |
| PostgreSQL | 17 | https://www.postgresql.org/download/ |
| git | toute version récente | https://git-scm.com |

> **git** est requis par le CLI AsyncAPI pour installer ses templates.

---

## Installation rapide (script)

```bash
bash scripts/setup-local.sh
```

Le script :
1. Vérifie les prérequis
2. Crée la base PostgreSQL `datacat`
3. Installe `@asyncapi/cli` et `@redocly/cli` globalement
4. Installe les dépendances npm des trois packages

---

## Installation manuelle

### 1. Base de données PostgreSQL

```bash
# Linux
sudo -u postgres psql << 'SQL'
CREATE DATABASE datacat;
CREATE USER datacat WITH PASSWORD 'datacat';
GRANT ALL PRIVILEGES ON DATABASE datacat TO datacat;
ALTER DATABASE datacat OWNER TO datacat;
SQL

# macOS (Homebrew)
psql postgres << 'SQL'
CREATE DATABASE datacat;
CREATE USER datacat WITH PASSWORD 'datacat';
GRANT ALL PRIVILEGES ON DATABASE datacat TO datacat;
ALTER DATABASE datacat OWNER TO datacat;
SQL

# Windows (PowerShell — depuis le dossier bin de PostgreSQL)
psql -U postgres -c "CREATE DATABASE datacat;"
psql -U postgres -c "CREATE USER datacat WITH PASSWORD 'datacat';"
psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE datacat TO datacat;"
psql -U postgres -c "ALTER DATABASE datacat OWNER TO datacat;"
```

### 2. CLIs de génération de docs

```bash
npm install -g @asyncapi/cli@6.0.0
npm install -g @redocly/cli
```

### 3. Dépendances Node.js

```bash
cd shared       && pnpm install
cd ../back      && pnpm install
cd ../front-public && pnpm install
```

---

## Démarrage

Ouvrir **deux terminaux** depuis la racine du projet :

**Terminal 1 — Backend**
```bash
cd back
pnpm run start:dev
# API disponible sur http://localhost:3000
# Health check : http://localhost:3000/health
```

**Terminal 2 — Frontend**
```bash
cd front-public
pnpm run start
# Application disponible sur http://localhost:4200
```

---

## Configuration

Les variables d'environnement ont des valeurs par défaut. Aucun fichier `.env` n'est nécessaire si la base PostgreSQL est créée avec les identifiants par défaut (`datacat`/`datacat`).

Pour surcharger, créer `back/.env` :

```env
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=datacat
DATABASE_USER=datacat
DATABASE_PASSWORD=datacat

# Répertoire de sortie des docs générées
DOCS_OUTPUT_DIR=./docs-output

# Port du backend (défaut : 3000)
PORT=3000
```

---

## Vérification

| URL | Attendu |
|-----|---------|
| http://localhost:3000/health | `{"status":"ok"}` |
| http://localhost:3000/api/apis | `{"items":[], "total":0, ...}` |
| http://localhost:4200 | Page d'accueil Datacat |
| http://localhost:4200/browse | Arborescence des dossiers |
| http://localhost:4200/upload | Formulaire d'import YAML |

---

## Fichiers YAML de test

Des exemples sont disponibles dans `documentation/` :

| Fichier | Type | Description |
|---------|------|-------------|
| `files-samples-oas/petstore.yaml` | OpenAPI 3.0 | CRUD animaux |
| `files-samples-asyncapi/user-events.yaml` | AsyncAPI 3.0 | Événements utilisateurs |

---

## Fixtures & re-seed

Les données de démo (catégories + APIs) sont définies dans `back/src/modules/seeder/seeder.service.ts`.

### Structure des fixtures

```
E-commerce          (racine)
  └─ Produits
  └─ Commandes
  └─ Notifications
Infrastructure      (racine)
  └─ Événements
Identité & Accès    (racine)
  └─ Authentification
```

5 APIs de démo y sont rattachées (Petstore, Streetlights Kafka, Account Service, Orders, Auth JWT).

### Modifier les fixtures

Éditer directement `back/src/modules/seeder/seeder.service.ts` :

- **Catégories** : bloc `categoryRepo.save(categoryRepo.create({...}))` dans la méthode `seed()`. Utiliser `parentId: null` pour une racine, ou `parentId: autreCategorie.id` pour un enfant.
- **APIs** : tableau passé à `apiRepo.save([...])`. Chaque entrée référence une catégorie via `categoryId`.
- **YAML** : les constantes en haut du fichier (`PETSTORE_YAML`, `ORDERS_YAML`, etc.) contiennent le YAML inliné de chaque API.

### Régénérer la base de données

Le seeder est **idempotent** : il ne s'exécute pas si la table `api_entries` contient déjà des lignes.

Pour forcer un re-seed complet (vide tout et recrée), utiliser la variable `FORCE_RESEED=true` :

**Avec Docker :**
```bash
docker compose -f infra/docker-compose.yml stop backend
docker compose -f infra/docker-compose.yml run --rm -e FORCE_RESEED=true backend
```

**Sans Docker (local) :**
```bash
cd back
FORCE_RESEED=true pnpm run start:dev
```

Ou via `back/.env` :
```env
FORCE_RESEED=true
```
> Penser à retirer `FORCE_RESEED=true` du `.env` après le redémarrage, sinon la base sera réinitialisée à chaque démarrage.

Le seeder supprime toutes les entrées `api_entries` et `categories`, nettoie le répertoire `docs-output`, puis recrée tout depuis `seed()`. Les logs confirment l'opération :
```
[Seeder] Reset complet — données supprimées, docs nettoyées.
[Seeder] 8 catégories et 5 APIs de démo créées — génération docs en cours...
```

---

## Notes

- **Schéma DB** : TypeORM crée et synchronise automatiquement les tables au démarrage (mode `synchronize: true` hors production). Aucune migration manuelle nécessaire.
- **Génération de docs** : asynchrone — après l'upload, le statut passe de `PENDING` à `GENERATED` une fois le CLI terminé.
- **Proxy Angular** : le fichier `front-public/proxy.conf.json` redirige `/api` vers `http://localhost:3000`. Ne pas modifier.