Files
Gitea Actions 723b68ea80
deploy / deploy (push) Successful in 1m24s
feat: migrate showcase to Next.js and overhaul CRM UI
rebuild the public site on the Next.js App Router with static export,

per-section SEO pages, metadata, sitemap, robots and a generated OG image

add full-screen scroll-snap regions, staged scroll reveals, a hash-free

tab navigation with a sliding indicator and region-by-region menu scrolling

replace the theme text toggle with animated sun/moon icons

restructure the CRM API into config, middleware, models, routes, services

and utils layers

redesign the CRM shell with a single surface, tab rail, full-width blurred

DataTable, record dialogs and mask-based icons

update Docker/Nginx publishing, Makefile targets, shared UI polish and docs

Co-authored-by: Gitea Actions <-[email protected]>
2026-11-16 00:08:17 +00:00

160 lines
7.8 KiB
Markdown

# Standards — CoHaiSe Web
Conventions à respecter pour que ce dépôt reste cohérent avec les deux autres
(`CoHaiSe-CLOUD`, `CoHaiSe-CRM`), qui partagent le même design system.
## Formatage
`.editorconfig` fait foi :
| Réglage | Valeur |
| --- | --- |
| Charset | UTF-8, fin de ligne LF |
| Indentation | 2 espaces (pas de tabs) |
| `trim_trailing_whitespace` | `false` pour `*.md`, vrai ailleurs |
Aucun Prettier n'est installé : l'éditeur et l'`.editorconfig` sont la seule
norme mécanique. ESLint a été retiré de `frontend/web` : `typescript-eslint`
ne supporte pas encore TypeScript 7.0. Ne pas le réintroduire tant que ce
support n'existe pas.
## Palette
Source unique : `frontend/shared/src/styles/tokens.css`.
| Jeton | Rôle | Valeur |
| --- | --- | --- |
| `--cohaise-accent` | accent de marque (liens, focus, éléments primaires) | carmin `#b71c1c` (`crimson-700`) |
| `--cohaise-destructive` | suppression, erreurs, champs invalides | `#d32f2f` clair / `#ef4444` sombre |
| `--cohaise-destructive-foreground` | texte posé dessus | `#ffffff` clair / `#1a0505` sombre |
| `--cohaise-warning` | avertissement, badges d'état | jaune `yellow-500` |
| `--cohaise-surface`, `--cohaise-background` | fonds | gris chaud `#f7f5f4` / `#050000` |
Règles :
- **L'orange n'existe plus** : `--cohaise-amber-*` a été retiré. Ne pas le
réintroduire — le rouge a remplacé l'ambre sur le bouton destructif pour des
raisons de contraste (≥4.5:1 en clair comme en sombre).
- Ne pas dériver la palette dans un seul dépôt : `tokens.css` doit rester
identique partout.
- Toute nouvelle couleur doit être lisible **comme texte** sur le fond
d'application ET comme fond avec un texte posé dessus. Vérifier les deux cas.
## Typographies
Chargées en local (`frontend/shared/fonts/*.woff2`), jamais par CDN :
| Usage | Police |
| --- | --- |
| Texte courant | Poppins 400/600 |
| Titres display | Orbitron, Cinzel |
| Code / monospace | JetBrains Mono |
## Composants
`@cohaise/ui` expose `Button`, `Card` (+ sous-composants), `Input`, `Skeleton`,
`Spinner` et l'utilitaire `cn`.
- Un composant partagé ne doit pas connaître le métier d'une app.
- Une variante visuelle propre à une app se développe **dans cette app**, pas
dans `frontend/shared`.
- `Skeleton` et `Spinner` sont prévus pour les états de chargement ; ne pas
réinventer un spinner.
## Thème
- Bascule clair/sombre par la classe `.dark` sur `<html>`.
- Script inline dans `frontend/web/app/layout.tsx` (avant le bundle) : lit
`localStorage["cohaise-theme"]`, sinon `prefers-color-scheme`. C'est lui qui
évite le flash de thème.
- `color-scheme: light dark` déclaré pour les contrôles natifs.
- Toute règle sombre va dans le bloc `.dark` de `tokens.css`, pas en
`@media (prefers-color-scheme: dark)` : la préférence utilisateur prime.
## Next.js (vitrine)
- Tout fichier qui utilise un hook, un événement ou une API navigateur porte
`"use client"` ; les pages et le layout restent des Server Components.
- Les métadonnées SEO vont dans `export const metadata` (page ou layout), pas
dans un composant client. Une page = une entrée dans `app/lib/site.ts` pour
rester alignée avec le sitemap.
- Les données statiques vivent dans `app/data/`. Un objet contenant des
fonctions ou des icônes React ne doit jamais traverser la frontière
serveur → client : le composant importe la donnée lui-même.
- Une section = une région plein écran : `<Section>` pose `data-region` et
`min-h-dvh`. Ne pas créer de section hors de ce composant, sinon elle
échappe au scroll-snap.
- Les reveals passent par `data-reveal` / `data-reveal-delay` et
`useScrollReveal` (délai par région via `data-region-delay`) ; ne pas
animer un élément sans prévoir son état sans JS.
- `next build` produit `out/` (`output: "export"`). Ne pas ajouter de route
dynamique sans vérifier la compatibilité avec l'export statique.
- Le menu de l'en-tête est une barre d'onglets, pas une liste d'ancres : aucun
`#` n'est écrit dans l'URL. Sur l'accueil, clic → séquence GSAP région par
région et pastille qui glisse vers l'onglet ; ailleurs, la cible passe par
`setPendingSection`/`sessionStorage` puis est rejointe après le retour à `/`.
`scrollToSection` suspend le snap (`data-scroll-anim`) le temps de la
séquence, sinon le navigateur saute directement à la destination ; la durée
renvoyée prolonge le verrou d'onglet. L'onglet actif suit la région visible
(bande centrale) sauf pendant le défilement déclenché par un clic, où il
reste sur l'entrée choisie. Une cible imbriquée (About dans la région Stack)
est ramenée à sa région par `scrollToSection`, car le snap opère par région.
- Les pages SEO autonomes (`/services`, `/about`, …) réutilisent une seule
région sans pied de page et tiennent dans le viewport (règle
`section[data-region]:only-child` dans `globals.css`). Ne pas les laisser
défiler : le menu est justement là pour ramener aux régions de l'accueil.
## Front CRM
- La page ne défile **jamais** : le shell est en `h-dvh overflow-hidden`, et les
zones de contenu (`DataTable`, dialogue) portent `min-h-0` + `overflow-auto`.
Ne pas retirer `min-h-0` d'un parent flex, sinon le tableau repousse la page.
- Toute liste passe par `components/DataTable.tsx` : colonnes triables,
recherche, actions de ligne, squelette et cartes sous `md`. Ne pas recréer un
`<table>` dans une page.
- Les formulaires de création/édition passent par `RecordDialog` ; seul son
corps défile. Les boutons d'action de ligne utilisent `RowActionButton`.
- Les pictogrammes viennent des WebP du dépôt, rendus par `MaskIcon` dans
`components/icons.tsx` : `FolderMaskIcon`/`UsersMaskIcon`/`ActivityMaskIcon`
pour le rail, `PenMaskIcon`, `TrashMaskIcon`, `SearchMaskIcon`,
`CloseMaskIcon`, `LogoutMaskIcon` pour les actions. Le masque CSS +
`background-color: currentColor` permet au survol de les teinter en accent ou
en destructif sans filtre. Ne pas revenir à un `<img>` : les fichiers sont
blancs et disparaîtraient sur fond clair. `components/glyphs.tsx` ne garde que
les flèches (`ChevronDownGlyph`, `ArrowUpGlyph`).
- L'en-tête du CRM porte `.glass` (défini dans `theme.css`, commun à la vitrine
et au CRM) ; la surface de travail reste sans flou et `DataTable` porte son
propre fond translucide (`bg-surface/80 backdrop-blur-xl`), avec un en-tête
sticky à `/90` pour garder le texte lisible quand les lignes passent dessous.
- Les champs (`Input` partagé, selects, recherche) réagissent au survol par un
bord accent ; le bouton de déconnexion est une icône seule
(`LogoutMaskIcon`) avec `aria-label` et `title`, jamais un libellé visible.
## Backend CRM
- Une route valide l'entrée (Zod), appelle un service, renvoie le statut HTTP.
Aucune requête SQL directement dans `routes/`.
- Un service reçoit `db` et des données déjà typées ; il lève `AppError` pour
les cas métier (404, 409, 422) et laisse remonter le reste.
- Les noms de colonnes SQL restent dans les services et `models/types.ts` ;
l'API expose ses propres champs.
- Les erreurs de contrainte MariaDB passent par `utils/dbErrors.ts` (1062,
1451, 1452), jamais par une comparaison de message.
## Git
- Branche `main` unique, remote `origin` sur `git.cohaise.dev`.
- Pas de convention de message imposée par l'historique (dépôt neuf).
- N'exclure de git que : `.env*` (sauf `.env.example`), `node_modules/`,
`dist/`, `.next/`, `out/`, `*.log`, `backups/`.
- `docs/` est **versionné** (la ligne `docs/` de `.gitignore` a été retirée).
## Interdépôts
| Élément | Attendu |
| --- | --- |
| `frontend/shared/src/styles/tokens.css` | identique (même `md5sum`) |
| Composants `@cohaise/ui` | dupliqués, **peuvent diverger** |
| Ports | web `8080`, CRM `8082`, Cloud `8083` |
| Remotes | un dépôt Git autonome par app, aucun lien de code entre eux |