13d5cbab9d
All checks were successful
Point d'entree technique pour le jury et les contributeurs. - docs/ARCHITECTURE.md : vue d'ensemble, stack, topologie de deploiement (5 services, standalone vs prod gitignore), demarrage une commande (wakdo-migrate), structure du code, flux d'une requete, securite (security-by-design : auth/RBAC/PIN+audit/throttle/ validation/RGPD), modele de donnees (22 tables + derivations calculees), tests & CI, methodologie. Renvoie vers PROJECT_CONTEXT / merise / adr (pas de duplication). - docs/DEVELOPER.md : lancer en local (docker compose up), migrations & seed, tests (PHPUnit .phar unit+integration, jsdom, PHPStan L6), conventions de code, git & CI. Premiere PR du jeu de documentation (socle). Suivront : docs/adr/ (registre de decisions) puis la doc par domaine.
144 lines
5.3 KiB
Markdown
144 lines
5.3 KiB
Markdown
# Guide developpeur — Wakdo
|
|
|
|
Comment lancer, tester et contribuer. Pour l'architecture (stack, services, modele,
|
|
securite), voir `docs/ARCHITECTURE.md`. Pour le scope et le mapping RNCP,
|
|
`docs/PROJECT_CONTEXT.md`.
|
|
|
|
---
|
|
|
|
## 1. Prerequis
|
|
|
|
- Docker Engine + docker compose v2 (https://docs.docker.com/engine/install/).
|
|
- Node 20+ (uniquement pour les tests front borne ; pas requis pour faire tourner l'app).
|
|
|
|
Aucune installation de PHP / Composer / PHPUnit sur l'hote : tout passe par les
|
|
conteneurs et des `.phar` autonomes.
|
|
|
|
---
|
|
|
|
## 2. Lancer en local
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
docker compose up -d
|
|
```
|
|
|
|
- Borne : http://kiosk.localhost:8080
|
|
- Admin + API : http://admin.localhost:8080
|
|
|
|
`*.localhost` resout vers `127.0.0.1`. Changer le port via `HTTP_PORT` dans `.env`.
|
|
Le `.env.example` fonctionne tel quel en local (valeurs dev). Au boot, le service
|
|
`wakdo-migrate` applique migrations + seed (admin bootstrap inclus) avant que l'app
|
|
ne serve.
|
|
|
|
Commandes utiles :
|
|
|
|
```bash
|
|
docker compose ps # etat des services
|
|
docker compose logs -f wakdo-app # logs PHP-FPM
|
|
docker compose down # arret (volumes preserves)
|
|
docker compose down -v # arret + suppression des donnees
|
|
```
|
|
|
|
Deploiement derriere un reverse proxy : voir le `README.md` (section prod) +
|
|
`docker-compose.prod.yml` (gitignore, propre a l'hote).
|
|
|
|
---
|
|
|
|
## 3. Base de donnees : migrations & seed
|
|
|
|
- `db/migrations/*.sql` (DDL) et `db/seeds/*.sql` (donnees de reference) sont appliques
|
|
de maniere **idempotente** par `wakdo-migrate` (suivi `schema_migrations` /
|
|
`seeds_applied`). Relancer `docker compose up` ne rejoue que les fichiers en attente.
|
|
- **Ajouter une migration** : creer `db/migrations/000N_description.sql` (ordre
|
|
lexicographique). Appliquee au prochain `docker compose up`, ou a la main :
|
|
|
|
```bash
|
|
bash db/migrate.sh # applique les migrations en attente (hote)
|
|
bash db/migrate.sh --status # liste l'etat sans rien appliquer
|
|
```
|
|
|
|
- Idem pour un seed : `db/seeds/000N_description.sql`.
|
|
|
|
---
|
|
|
|
## 4. Tests & analyse statique
|
|
|
|
Les tests PHP tournent dans l'image applicative (PHPUnit `.phar`). La stack doit etre
|
|
demarree pour les tests d'integration (ils ciblent le service `wakdo-db`).
|
|
|
|
```bash
|
|
# Tests unitaires (sans base)
|
|
docker run --rm -v "$PWD":/app -w /app wakdo-wakdo-app \
|
|
php phpunit.phar -c phpunit.xml --testsuite unit
|
|
|
|
# Tests d'integration (vraie MariaDB ; auto-skip si WAKDO_DB_TESTS != 1)
|
|
docker run --rm --network wakdo_wakdo_internal --env-file .env -e WAKDO_DB_TESTS=1 \
|
|
-v "$PWD":/app -w /app wakdo-wakdo-app php phpunit.phar -c phpunit.xml
|
|
|
|
# Analyse statique PHPStan niveau 6
|
|
docker run --rm -v "$PWD":/app -w /app wakdo-wakdo-app \
|
|
php -d memory_limit=512M phpstan.phar analyse -c phpstan.neon --no-progress
|
|
```
|
|
|
|
Tests front borne (Node + jsdom) :
|
|
|
|
```bash
|
|
npm install # une fois (devDependency jsdom)
|
|
npm run test:js # node --test tests/js/
|
|
```
|
|
|
|
> Le nom de reseau `wakdo_wakdo_internal` et l'image `wakdo-wakdo-app` derivent du
|
|
> nom de projet compose (`name: wakdo`). Les `.phar` (phpunit, phpstan) sont
|
|
> gitignores ; les retelecharger si absents (voir `docs/journal/`).
|
|
|
|
---
|
|
|
|
## 5. Conventions de code
|
|
|
|
- **PSR-4 manuel** : namespace `App\` -> `src/app/`. Pas de framework.
|
|
- **Controleurs** : non-`final` (seam de test ; les tests sous-classent et injectent
|
|
des doubles via `db()` / `sessionManager()`). Heritent de `AdminController`
|
|
(back-office) ou `AuthenticatedController`.
|
|
- **Acces donnees** : un repository par entite, dependant de `DatabaseInterface`
|
|
(PDO en prod, `FakeDatabase` en test). Requetes preparees uniquement.
|
|
- **Mutations** : CSRF (`Csrf::validate`) + validation serveur bornee (RG-T18) +
|
|
allowlist de colonnes (RG-T16). Sorties HTML echappees (RG-T15).
|
|
- **Actions sensibles** : PIN equipier (`PinVerifier`) + `audit_log` dans la meme
|
|
transaction ; throttle PIN (`PinThrottle`). Voir `docs/ARCHITECTURE.md` section 7.
|
|
- **Statuts HTTP** : conflit -> 409 ; validation -> 422 ; CSRF/permission -> 403.
|
|
- **Pas d'emoji** dans le code, les commits, les specs (Mantra IA-23).
|
|
|
|
Detail par entite : `docs/merise/` et `docs/domaines/` (a venir).
|
|
|
|
---
|
|
|
|
## 6. Git & CI
|
|
|
|
- **Conventional Commits** (anglais) : `type(scope): description` — types `feat`, `fix`,
|
|
`docs`, `refactor`, `test`, `chore`, `ci`, `db`, `perf`, `style`.
|
|
- **Branches** depuis `dev` : `feat/*`, `fix/*`, `docs/*`, `chore/*`, `ci/*`, `db/*`,
|
|
`refactor/*`, `test/*`. Merge vers `dev` par **PR squashee**. Periodiquement
|
|
`dev -> main` avec tag semver.
|
|
- **Auto-merge** : poser le label `auto-merge` sur la PR -> fusion automatique des que
|
|
la CI Forgejo est verte (secret-scan, php-lint, static-tests, js-tests).
|
|
Script : `scripts/forgejo-pr-automerge.sh`.
|
|
- **Pas de trailer `Co-Authored-By`** : la transparence sur l'usage de l'IA vit dans le
|
|
`README.md` et `docs/PROJECT_CONTEXT.md` section 17.
|
|
|
|
---
|
|
|
|
## 7. Ou trouver quoi
|
|
|
|
| Besoin | Emplacement |
|
|
|---|---|
|
|
| Architecture, stack, securite, modele | `docs/ARCHITECTURE.md` |
|
|
| Scope metier, planning, mapping RNCP | `docs/PROJECT_CONTEXT.md` |
|
|
| Modelisation Merise (dictionnaire, MCD/MCT/MLT, regles RG-T*) | `docs/merise/` |
|
|
| Decisions d'architecture (le pourquoi) | `docs/adr/` |
|
|
| Retros par session / feature | `docs/journal/` |
|
|
| Methodologie agents | `.claude/CLAUDE.md` + `.claude/rules/` |
|
|
|
|
---
|
|
|
|
*Document vivant — mis a jour au fil de l'implementation.*
|