Files
CoHaiSe-CLOUD/docs/agents.md
T
Esiah 68d4d5dea0
PR — Ouverture automatique / create-pr (push) Successful in 3s
refactor: restructure frontend and backend by domain services
Split the monolithic backend (lib/, routes/, access.ts, storage.ts, media.ts)
into a layered structure inspired by JeanXXIII-CRM:
- config/: appConfig, db
- middleware/: auth (session, roles, cookies)
- models/: shared types
- routes/: *Routes.ts (thin HTTP handlers)
- services/: *Service.ts (business logic, one per domain)
- utils/: errors, http, migrate, ratelimit, validators, service bootstrap

Frontend likewise: services/*Service.ts + apiClient, contexts/, types/, utils/format.
Route files now carry the "Routes" suffix; service files are named
authService.ts, ratelimit.ts, etc. and live in their own files, frontend and
backend separated.

Updated docs and READMEs to reflect the new layout. Typecheck and builds pass.
2026-11-13 09:45:21 +01:00

83 lines
3.8 KiB
Markdown

# Agents — CoHaiSe Cloud
Conventions pour reprendre ce dépôt seul. Démarrage rapide : `README.md`.
Détails : `architecture.md`, `api.md`, `deployment.md`, `security.md`.
## Commandes
| Action | Commande |
| --- | --- |
| Lever l'ensemble | `make up` |
| Dev front | `make dev` (Vite 5174 → proxy 3101) |
| Vérifier | `make check` (typecheck + build) |
| Republier le front | `make front` |
| Migrations | `make migrate` / `--check` via `docker compose run --rm migrate …` |
| Sauvegarder | `make backup` |
| Comptes | `make admin ARGS="--email … --first … --last …"` |
| Journal / état | `make logs`, `make ps` |
| Santé | `curl -I http://localhost:8083/healthz` |
`make check` est le seul filet de sécurité automatique (ni linter, ni tests, ni
CI). L'exécuter avant de déclarer un travail fini.
## Règles du dépôt
1. **Ne pas lire `.env`** : secrets de production. Écrire un `SESSION_SECRET`
manquant est autorisé ; le diffuser, non.
2. **Ne pas committer ni pousser** sans demande explicite.
3. **Pas de `down -v`, pas de suppression de volume** : la base et les médias
sont des bind mounts hôte (`$CLOUD_DB_DIR`, `$CLOUD_MEDIA_DIR`) — ne pas
effacer ces dossiers.
4. **Ne jamais modifier une migration déjà appliquée** : nouveau fichier numéroté
seulement. Le checksum bloquerait le démarrage.
5. **API admin** : les routes `/api/cloud/admin/*` existent (UI Administration).
La CLI (`make admin`) reste pour l'amorçage et les cas hors ligne.
6. **Chemin disque** : toujours via `services/storageService.ts` (`resolveInside`),
jamais par concaténation depuis une entrée utilisateur.
7. **404 plutôt que 403** sur une ressource non accessible : ne pas introduire
d'énumération.
8. **CSP stricte** : pas de script en ligne dans `index.html` (utiliser un
fichier dans `public/`, comme `theme.js`).
## Conventions
- TypeScript strict, project references racine.
- Back : `routes/*Routes.ts` (HTTP fin) appellent `services/*Service.ts`
(métier) ; le socle vit dans `config/`, `middleware/`, `utils/`, les types
partagés dans `models/types.ts`.
- Hono + Zod : toute route avec corps passe par un schéma Zod dédié.
- Erreurs : `AppError` + codes (`utils/errors.ts`) — jamais `throw` brut, jamais
de détail de schéma dans une 500.
- SQL : requêtes préparées uniquement, pas de `raw()` hors DDL.
- Front : un client HTTP (`frontend/src/services/apiClient.ts`), puis un service
par domaine (`services/*Service.ts`), `credentials: "same-origin"`. React
Router 7 (`App.tsx`) + `AppShell`, contexte de session dans
`contexts/SessionContext.tsx`.
- `.editorconfig` : 2 espaces, LF, UTF-8.
## Design system
Le design system vit dans `frontend/src/ui`.
- `tokens.css` est la source unique des couleurs et typographies ; ne pas coder
de couleur en dur ailleurs.
- Un composant propre à une page se développe dans `frontend`, pas dans le
design system.
- Palette : accent carmin `#b71c1c`, destructif rouge `#d32f2f`/`#ef4444`,
avertissement jaune. Aucune orange.
- **Aucun commit** : rien n'est encore historié, tout est untracked.
## Pièges
- **`.env` ≠ `.env.example`** : comparer avant de conclure à un bug de port.
- **README de paquet périmés** — utiliser ce dossier `docs/`.
- **Build Docker et DNS** : les `build:` utilisent le réseau Docker par défaut.
`network: host` est évité : Compose 5.6 / Buildx 0.38 refuse alors le build
(`additional privileges requested`), sans transmettre `--allow=network.host`.
Si `npm ci` échoue par `EAI_AGAIN`, corriger le DNS du démon Docker.
- **Limitation de débit active** (applicatif + nginx) : un test en rafale peut
recevoir `419`/`503` côté API ou `503` nginx — ce n'est pas un bug.
- Après `make up`, vérifier l'ordre : `migrate` doit être `exited (0)` avant que
`api` ne devienne `healthy`.