> ## 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.

# Conventions

> Les règles qui gardent le code cohérent

## Code

* **Anglais partout dans le code** : identifiants, commentaires, messages de commit, descriptions de PR.
  Les discussions et cette doc sont en français.
* **Les schémas Zod sont la source de vérité** : les types d'entrée/sortie des routes remontent
  automatiquement dans OpenAPI. Ne jamais éditer une spec à la main.
* **Pas de `any`** : un vrai type, ou un `unknown` explicitement rétréci.
* **Échouer fort** : aucune erreur avalée en silence ; la traiter à la bonne frontière.
* **Biome** impose le format et le lint : `yarn lint:fix` avant de pousser.

## Commentaires : quasi interdits

Une fonction, un composant, une prop, un champ de schéma ne portent **aucun** commentaire. Si un
commentaire semble nécessaire, c'est le code qui est faux : renommer, découper, ou donner un type.

Trois exceptions seulement, la première étant la seule courante :

1. Un **piège**, dont le texte **nomme le bug que le prochain dev introduirait** — pas le « pourquoi »,
   l'erreur elle-même : `// Reorder these two and the transaction is lost.`
2. `TODO(KARE-123)`, actionnable, avec un ticket.
3. Un en-tête légal exigé par une dépendance ou une politique.

À supprimer à vue : JSDoc sur autre chose qu'un export de package, tout commentaire qui répète un nom
ou un type, la prose de conception (elle va dans `docs/`), les explications du comportement de React,
Zod, Prisma, Fastify ou TypeScript, la narration de process (« modelled on X », « per review »), le code
commenté.

Le test avant d'en écrire un : **le supprimer, et nommer le bug concret que quelqu'un livre sans lui.**
Pas de bug nommable, pas de commentaire.

## Git

Conventional commits : `type(scope): description`

```
feat(rs): add template archiving endpoint
fix(bo): correct pagination offset on org list
chore(deps): bump prisma to 7.x
```

Types : `feat` `fix` `docs` `refactor` `test` `chore` `style`

Le titre de PR suit la même règle — `pr-quality` échoue sinon.

## Ajouter une fonctionnalité

<Steps>
  <Step title="Le module">
    Créer `src/audiences/<audience>/modules/<nom>/v1/` et l'enregistrer dans l'`app.ts` de l'audience.
  </Step>

  <Step title="Les schémas">
    Définir entrée et sortie en Zod — la page OpenAPI se génère.
  </Step>

  <Step title="Les tests">
    Un test d'intégration Vitest contre la vraie base, sans mock.
  </Step>

  <Step title="La spec">
    `yarn docs:openapi` dans `apps/api`, et commiter `openapi/`.
  </Step>
</Steps>

## Variables d'environnement

* Jamais de secret commité : `.env` est gitignoré, `.env.example` est la référence à tenir à jour.
* Le schéma d'env est validé au démarrage : le serveur crashe fort sur une variable manquante, plutôt
  qu'en silence à l'exécution.

## i18n

Les fronts utilisent Lingui. `yarn lingui:compile` est branché en `predev` / `prebuild`, donc les
catalogues compilés sont toujours régénérés depuis les `.po`. Le job `Checks` de la CI lance
`lingui:check --strict` sur les quatre fronts et échoue sur toute traduction manquante.

## Base de données

* Toujours générer une migration : `yarn workspace @kare/database migrate:dev --name <description>`.
* Ne jamais éditer une migration commitée.
* Migrations de données : `apps/api/database/data-migrations/`, scripts autonomes.
* Tout nouveau modèle scopé organisation doit être ajouté au manifeste `clear` du seeder — voir
  [Seed — référence](/onboarding/seed/reference#maintenance).