PR — Ouverture automatique / create-pr (push) Successful in 3s
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.
83 lines
3.8 KiB
Markdown
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`.
|