> ## Documentation Index
> Fetch the complete documentation index at: https://api-documentation.kare-app.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Seed — référence

> Tous les flags CLI, leur équivalent workflow, l'architecture et les règles de maintenance

## Source des données

Exactement un des deux, sur `account` comme sur `reset`.

| Flag CLI            | Entrée workflow                  | Effet                                                                      |
| ------------------- | -------------------------------- | -------------------------------------------------------------------------- |
| `--blueprint=<nom>` | `source=blueprint` + `blueprint` | un dossier de `src/seed/demo`, avec son `blueprint.ts` et ses `documents/` |
| `--archetype=<clé>` | `source=archetype` + `archetype` | blueprint généré depuis le catalogue                                       |
| `--size=s\|m\|l`    | `size`                           | taille du blueprint généré ; défaut `s`                                    |

Archétypes : `hotel`, `centre_commercial`, `ehpad`, `logistique`, `bureaux`,
`etablissement_scolaire`. Tailles : `s` = 1 établissement, `m` = 3, `l` = 8.

## Options de run

| Flag CLI                | Entrée workflow | Effet                                                      |
| ----------------------- | --------------- | ---------------------------------------------------------- |
| `--seed=N`              | `seed`          | reproduit le contenu généré ; affiché si omis              |
| `--as-of=YYYY-MM-DD`    | `as_of`         | ancre toutes les dates relatives, en UTC                   |
| `--assets=upload\|none` | `assets`        | upload des fichiers, ou aucun stockage                     |
| `--e2e`                 | `e2e`           | overlay de couverture des enums ; `--archetype` uniquement |
| `--dry-run`             | `dry_run`       | résout, valide et affiche le plan sans écrire              |

## Cibles et identité

| Flag CLI                               | Entrée workflow           | Effet                                                                 |
| -------------------------------------- | ------------------------- | --------------------------------------------------------------------- |
| `--email=<addr>`                       | `email`                   | `account` : la connexion à créer. `reset` : la connexion propriétaire |
| `--org=<uuid>`                         | `org`                     | `reset` : cible l'organisation directement                            |
| `--confirm-organization-id=<uuid>`     | `confirm_organization_id` | requis par `reset` hors dry run                                       |
| `--password` / `--name` / `--org-name` | `name` / `org_name`       | identité, sur `account`                                               |

## Architecture

```
apps/api/src/seed/
  catalogue/     le métier en données : installations, règles, anomalies, prestataires, archétypes
  blueprint/     le contrat typé Blueprint + sa validation
  generator/     archétype × taille × seed → Blueprint
  engine/        rejoue un Blueprint à travers le domaine, phase par phase
  invariants/    contrôles de cohérence sur toute organisation seedée
  demo/<nom>/    blueprints écrits à la main + leurs PDF
  factories/     defineFactory par modèle, aussi utilisé par les fixtures de tests de routes
  account/       provisioning d'une connexion RS et d'un admin backoffice
  orchestration/ clear d'un tenant, manifeste des modèles, upload des assets
```

Le moteur avance par phases — organisation, labels, installations, prestataires, structure, équipe,
règles, responsabilités, chronologie, rétrodatage, assets — et chaque phase appelle les `db-access`
du domaine sous un acteur système, jamais dans une transaction externe.

## Maintenance

* Les tests de routes API utilisent les fixtures `rsFixture`, `boFixture`, `adFixture`, `prFixture` —
  pas le seeder.
* **Nouvelle valeur d'enum visible** : la classer dans `invariants/checks/coverage.ts`. Une valeur
  qu'aucun chemin d'écriture ne produit va dans la liste `UNREACHABLE`, avec le commentaire qui dit
  pourquoi.
* **Nouveau modèle Prisma scopé organisation** : l'ajouter au manifeste de `clear`
  (`orchestration/tenant-models.ts`), sinon son test unitaire échoue. S'il porte un `createdAt`
  historique, l'ajouter aussi à `engine/backdate.ts` et enregistrer ses lignes via `ctx.state.record`.
* **Nouveau cas métier** : un type d'événement dans `blueprint/types.ts`, son contrôle dans
  `blueprint/validate.ts`, son handler dans `engine/events/`, et son émission dans
  `generator/timeline.ts`. Ne pas écrire un statut ou une échéance à la main : appeler la policy du
  domaine.
* **Nouvelle règle métier ou installation** : le catalogue (`catalogue/rules.ts`,
  `catalogue/installations.ts`) est la seule source ; le générateur n'invente aucun libellé.
* **Nouvel archétype** : une entrée dans `catalogue/archetypes.ts` suffit, plus son ajout aux choix
  du workflow.

## Comportements du domaine tolérés

Le moteur hérite des hypothèses d'horloge du domaine. Trois sont assumées et documentées dans
`docs/features/seed-engine.md` du monorepo :

* une règle à workflow **calendrier** n'avance pas son échéance après une visite en retard ;
* les **formations** ne portent pas de `verifiedAt`, elles sont validées par leurs preuves de présence ;
* une règle de **session** ne produit une échéance que par le seuil de capacité du site.