140 lines
6.6 KiB
Markdown
140 lines
6.6 KiB
Markdown
# Guide de développement
|
|
|
|
Ce document couvre les conventions de code, les règles de sécurité et la procédure de publication du package `@zen/core`.
|
|
|
|
Pour les conventions de rédaction : [LANGUE.md](./dev/LANGUE.md) et [REDACTION.md](./dev/REDACTION.md).
|
|
|
|
Pour les décisions de design et l'identité visuelle : [DESIGN.md](./DESIGN.md).
|
|
|
|
Pour l'architecture partagée (composants, icônes) : [ARCHITECTURE.md](./dev/ARCHITECTURE.md).
|
|
|
|
Pour la procédure de publication du package : [PUBLICATION.md](./dev/PUBLICATION.md).
|
|
|
|
Pour les conventions de commit : [COMMITS.md](./dev/COMMITS.md).
|
|
|
|
> **Contexte projet** : les utilisateurs finaux créent leur projet via `npx @zen/start`, qui génère automatiquement une structure Next.js avec la plateforme déjà intégré. Lors d'une assistance ou d'une revue, partez du principe que le projet cible est déjà structuré de cette façon.
|
|
|
|
---
|
|
|
|
## Standards de code
|
|
|
|
### Principes généraux
|
|
|
|
**Une fonction, une responsabilité.** Si elle fait deux choses, c'est deux fonctions. Si elle ne tient pas sur un écran, la découper.
|
|
|
|
**Le flux de contrôle se lit de haut en bas.** Pas de récursion non bornée, pas de callbacks imbriqués à plus de deux niveaux. Quelqu'un qui lit le code pour la première fois doit pouvoir suivre l'exécution sans se perdre.
|
|
|
|
**Les données entrantes sont suspectes.** On valide en entrée de fonction. On ne suppose pas que l'appelant a fait le travail.
|
|
|
|
**Les promesses ne s'ignorent pas.** Chaque `Promise` est `await`ée ou `.catch()`ée. Une promesse silencieuse qui échoue est un bug invisible.
|
|
|
|
**La portée des variables est minimale.** On déclare au plus près de l'usage. Pas de variables réutilisées pour deux rôles différents.
|
|
|
|
**ESLint passe sans avertissement.** Un warning ignoré aujourd'hui est un bug non détecté demain.
|
|
|
|
**Les variables d'environnement et la documentation se mettent à jour avec le code.** Toute variable ajoutée, renommée ou supprimée doit être reflétée dans `.env.example`. Toute décision architecturale ou convention nouvelle doit être documentée dans le fichier `docs/` concerné. Le code et sa documentation vieillissent ensemble.
|
|
|
|
**Les commentaires reflètent toujours le comportement réel du code.** Un commentaire obsolète est pire qu'un commentaire absent — il induit en erreur. Quand on modifie une fonction, on met à jour son commentaire. Un commentaire qui contredit le code est un bug de documentation.
|
|
|
|
---
|
|
|
|
## Conventions d'arborescence
|
|
|
|
Une feature (`src/features/<nom>/` ou `src/core/<nom>/`) suit la règle **flat + un barrel** :
|
|
un `index.js` qui ré-exporte, des fichiers plats côte à côte pour l'implémentation. Pas de sous-dossier `lib/`, `middleware/`, `actions/` quand il ne contient qu'un ou deux fichiers — remonter directement au niveau du dossier feature.
|
|
|
|
Les sous-dossiers sont autorisés uniquement quand ils contiennent plusieurs fichiers du même rôle : `components/`, `pages/`, `templates/`, `widgets/`.
|
|
|
|
### Suffixes de runtime
|
|
|
|
Tout fichier épinglé à une frontière Next.js porte le suffixe dans son nom :
|
|
|
|
- `.server.js` → code serveur strict (peut importer `pg`, `fs`, etc.)
|
|
- `.client.js` → débute par `'use client'`
|
|
- pas de suffixe → module neutre, utilisable des deux côtés
|
|
- `actions.js` → débute par `'use server'` (server actions Next.js)
|
|
|
|
Ces suffixes ne sont pas cosmétiques : **le build les utilise comme source de vérité**. Tout fichier `*.server.js` ou `*.client.js` est automatiquement ajouté à la config tsup non-bundlée pour préserver la frontière RSC.
|
|
|
|
---
|
|
|
|
## Build et configuration tsup
|
|
|
|
### Source de vérité
|
|
|
|
`tsup.config.js` compile **tous les fichiers `.js` et `.jsx` de `src/`** avec `bundle: false`. Chaque fichier devient un module standalone dans `dist/` ; les imports relatifs sont préservés tels quels.
|
|
|
|
- **Ajouter un module public = éditer seulement `package.json#exports`.** L'entry list se régénère au prochain build via un walk de `src/`.
|
|
- **Pas de bundling des fichiers internes** : les modules de registre (`registry.js`, etc.) sont des singletons — les bundler avec `bundle: true` dans un barrel créerait une copie inline distincte et casserait le partage d'état entre les pages et les widgets.
|
|
- Les self-imports `@zen/core/*` sont générés automatiquement à partir des clés de `exports` et restent toujours dans la liste `external`.
|
|
|
|
---
|
|
|
|
## Étendre l'admin
|
|
|
|
L'admin utilise un **registre runtime** pour permettre aux projets consommateurs d'ajouter des widgets, des entrées de navigation, et des pages sans modifier le core.
|
|
|
|
```js
|
|
// app/zen.extensions.js — projet consommateur
|
|
import {
|
|
registerWidget,
|
|
registerWidgetFetcher,
|
|
registerNavItem,
|
|
registerNavSection,
|
|
registerPage,
|
|
} from '@zen/core/features/admin';
|
|
import OrdersWidget from './admin/OrdersWidget';
|
|
import OrdersPage from './admin/OrdersPage';
|
|
import { countOrders } from './admin/orders.server';
|
|
|
|
// Widget dashboard — fetcher serveur + composant client partagent un même id.
|
|
registerWidgetFetcher('orders', async () => ({ total: await countOrders() }));
|
|
registerWidget({ id: 'orders', Component: OrdersWidget, order: 20 });
|
|
|
|
// Sidebar
|
|
registerNavSection({ id: 'commerce', title: 'Commerce', icon: 'ShoppingBag03Icon', order: 30 });
|
|
registerNavItem({ id: 'orders', label: 'Commandes', icon: 'ShoppingBag03Icon', href: '/admin/orders', sectionId: 'commerce' });
|
|
|
|
// Page — le slug correspond au segment sous /admin/.
|
|
registerPage({ slug: 'orders', Component: OrdersPage, title: 'Commandes' });
|
|
```
|
|
|
|
```js
|
|
// app/layout.js — un seul import suffit ; les side effects enregistrent tout.
|
|
import './zen.extensions';
|
|
```
|
|
|
|
---
|
|
|
|
## Sécurité
|
|
|
|
### Données entrantes
|
|
|
|
Toute donnée externe est considérée malveillante par défaut : requêtes HTTP, données formulaire, réponses d'API tierce, contenu de fichier. On valide côté serveur. Le client ne contrôle rien de critique.
|
|
|
|
### Base de données
|
|
|
|
On n'écrit jamais de SQL par concaténation de chaînes. Uniquement des requêtes paramétrées :
|
|
|
|
```ts
|
|
// ✓
|
|
await pool.query('SELECT * FROM users WHERE id = $1', [userId])
|
|
|
|
// ✗
|
|
await pool.query(`SELECT * FROM users WHERE id = '${userId}'`)
|
|
```
|
|
|
|
### Secrets
|
|
|
|
Aucun token, clé API ou mot de passe dans le code. Tout passe par des variables d'environnement. Les clés Stripe, les tokens Resend et les credentials PostgreSQL ne sont jamais commités.
|
|
|
|
```bash
|
|
# .env.local — jamais dans git
|
|
DATABASE_URL=...
|
|
STRIPE_SECRET_KEY=...
|
|
RESEND_API_KEY=...
|
|
```
|
|
|
|
### Erreurs exposées
|
|
|
|
Les messages d'erreur retournés à l'utilisateur ne contiennent pas de détails internes : pas de stack trace, pas de nom de table, pas de requête SQL. On log côté serveur, on renvoie un message générique côté client. |