79 lines
3.5 KiB
Markdown
79 lines
3.5 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 `storage.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.
|
|
- Hono + Zod : toute route avec corps passe par un schéma Zod dédié.
|
|
- Erreurs : `AppError` + codes (`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 seul client HTTP (`frontend/src/lib/api.ts`),
|
|
`credentials: "same-origin"`. React Router 7 (`App.tsx`) + `AppShell`, contexte
|
|
de session dans `lib/session.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`.
|