Files
Gitea ActionsandEsiah f689ab4d57
CD — Deployment / deploy (push) Successful in 34s
refactor: restructure frontend and backend by domain services (#26)
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.

---------

Co-authored-by: xEsiah <[email protected]>
Reviewed-on: #26
Reviewed-by: Esiah <[email protected]>
Co-authored-by: Gitea Actions <-[email protected]>
2026-11-13 09:13:27 +00: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`.