From cce3e9dec2450cc66c1def04f4ac82dd1b3de56d Mon Sep 17 00:00:00 2001 From: Imugiii Date: Mon, 22 Jun 2026 06:41:20 +0000 Subject: [PATCH] docs: aligner PROJECT_CONTEXT et README sur l'etat reel (CD, cron, hooks, mapping RNCP, FQDN, statuts) --- README.md | 82 +++++++++++++++++++++++------------------ docs/PROJECT_CONTEXT.md | 33 +++++++++-------- 2 files changed, 64 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index a2a8a7d..0cb57fe 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Trois canaux de prise de commande : - `counter` — comptoir (un equipier saisit pour le client au guichet) - `drive` — drive-thru (equipier saisit via intercom + casque) -Quatre statuts commande : `pending` -> `preparing` -> `ready` -> `delivered` (ou `cancelled`). +Statuts commande (machine a 4 etats) : `pending_payment` -> `paid` -> `delivered`, plus `cancelled` (atteignable depuis `pending_payment` ou `paid`). La saisie du numero tient lieu de paiement : la creation passe atomiquement de `pending_payment` a `paid`. La cuisine voit la file des commandes `paid` en lecture seule ; la remise est un geste unique `paid` -> `delivered`. Scope metier complet, regles, horaires de service et fenetre de maintenance : voir `docs/PROJECT_CONTEXT.md`. @@ -82,7 +82,7 @@ Detail et justifications : `docs/PROJECT_CONTEXT.md` section 6. v wakdo-db (MariaDB 11.4) - wakdo-cron (backup BDD + purge sessions + stats) + wakdo-cron (backup BDD + purge audit-log + purge throttle) ``` Reseaux, volumes, services et decoupage reseau interne / reseau proxy : voir `docs/PROJECT_CONTEXT.md` section 5. @@ -92,8 +92,8 @@ Reseaux, volumes, services et decoupage reseau interne / reseau proxy : voir `do ## Quickstart (local) ```bash -git clone git@github.com:AcadeNice/wakdo_corentin.git -cd wakdo_corentin +git clone https://git.acadenice.com/AcadeNice/corentin_wakdo.git +cd corentin_wakdo cp .env.example .env docker compose up -d ``` @@ -125,7 +125,7 @@ Avec un `.env` adapte : `APP_ENV=prod`, `APP_DEBUG=false`, mots de passe forts, `APP_HOST_*` / `APP_URL_*` / `CORS_ALLOWED_ORIGIN` en vrais FQDN HTTPS, et `REVERSE_PROXY_NETWORK` = reseau Docker du Traefik de l'hote (doit exister avant le up). -*Section mise a jour au fil de l'implementation (migrations reelles, seed, CI/CD deploiement).* +*Deploiement detaille : section Deploiement plus bas et `scripts/deploy.sh`.* --- @@ -134,36 +134,34 @@ Avec un `.env` adapte : `APP_ENV=prod`, `APP_DEBUG=false`, mots de passe forts, ``` . |-- .claude/ # Methodologie BYAN (visible jury : CLAUDE.md + rules/) -|-- .forgejo/ -| `-- workflows/ # CI Forgejo Actions (ci.yml : secret-scan, php-lint, static-tests, js-tests, auto-merge) -|-- .githooks/ # pre-commit + commit-msg [a venir] +|-- .forgejo/workflows/ # CI Forgejo Actions (ci.yml : secret-scan, php-lint, static-tests, js-tests) +|-- .githooks/ # pre-commit (refus main/dev + php -l) + commit-msg (Conventional Commits) |-- docker/ # Dockerfiles customs par service -| |-- apache/ -| |-- php-fpm/ -| `-- cron/ +| |-- apache/ # httpd + vhosts kiosk / admin +| |-- php-fpm/ # PHP 8.3-fpm + php.ini durci +| `-- cron/ # dcron + scripts (backup, restore, purges) |-- db/ -| |-- migrations/ # DDL MariaDB versionnes [a venir] -| `-- seeds/ # Donnees de demo [a venir] +| |-- init/ # init BDD (scope du user applicatif, moindre privilege) +| |-- migrations/ # DDL MariaDB versionnes (0001_init_schema, 0002_pin_throttle, ...) +| |-- seeds/ # donnees de reference + demo (idempotents) +| `-- *.sh # runners migrate / seed |-- docs/ -| |-- PROJECT_CONTEXT.md # Source de verite projet (scope, stack, RNCP mapping) -| |-- journal/ # Retros par session et par feature (oral RNCP) -| `-- merise/ # MCD, MCT, MLD [a venir] -|-- scripts/ # backup-db, install-hooks, ... [a venir] -|-- src/ # Code applicatif [a venir] -| |-- Core/ # Router, Autoloader, DB -| |-- Controllers/ -| |-- Models/ -| |-- Views/ -| |-- Services/ -| |-- public/ # DocumentRoot Apache -| `-- bootstrap.php +| |-- PROJECT_CONTEXT.md # source de verite projet (scope, stack, mapping RNCP) +| |-- ARCHITECTURE.md # vue technique (deploiement, stack, securite) +| |-- merise/ # dictionnaire, MCD, MCT, MLD, MLT (+ diagrammes) +| |-- uml/ # use-cases, sequences, machine a etats +| `-- adr/ api/ domaines/ design/ journal/ _ref/ +|-- scripts/ # deploy, install-hooks, forgejo-* (branch-protection, pr-automerge) +|-- src/ +| |-- app/ # namespace App\ : Core, Controllers, Auth, Catalogue, Order, Views +| `-- public/ # DocumentRoots Apache : borne/ (kiosk) + admin/ (back-office + API) |-- tests/ -| |-- Unit/ # [a venir] -| `-- Integration/ # [a venir] -|-- .env.example -|-- .dockerignore -|-- .gitignore -|-- docker-compose.yml +| |-- Unit/ Integration/ # PHPUnit (.phar autonome, sans Composer ; integration sur vraie MariaDB) +| |-- js/ # node:test + jsdom (front borne) +| |-- e2e/ # Playwright (parcours borne + admin, lance a la main) +| `-- Support/ # doubles de test (Fake* / Spy*) +|-- .env.example .gitleaks.toml phpstan.neon phpunit.xml +|-- docker-compose.yml # standalone local ; prod = docker-compose.prod.yml (gitignore, par hote) `-- README.md ``` @@ -178,19 +176,32 @@ Avec un `.env` adapte : `APP_ENV=prod`, `APP_DEBUG=false`, mots de passe forts, - `main` et `dev` sont proteges cote Forgejo (PR requise, force push bloque, checks requis : secret-scan / php-lint / static-tests). - Pas d'emoji dans le code, les commits ou les specs techniques (Mantra IA-23). -*Sections detaillees (setup env de dev, lint, tests) : a completer au fil de l'implementation.* +- **Hooks Git** : `scripts/install-hooks.sh` active `pre-commit` (refus de commit direct sur `main`/`dev`, `php -l` des fichiers indexes) et `commit-msg` (format Conventional Commits, refus emoji). +- **Verification locale** : voir la section Tests ci-dessous (PHPUnit + PHPStan via le conteneur applicatif, tests JS via node, E2E Playwright). --- ## Tests -*Section a completer. Strategie globale : PHPUnit via `.phar` autonome (sans Composer), priorite Unit > Integration > E2E, voir `docs/PROJECT_CONTEXT.md` section 6 et mantras Merise Agile.* +Trois niveaux, sans dependance Composer cote PHP (priorite Unit > Integration > E2E). + +- **PHP (PHPUnit `.phar`)** — unit + integration sur vraie MariaDB, via le conteneur applicatif : + + ```bash + docker run --rm -v "$PWD":/app -w /app wakdo-wakdo-app php phpunit.phar -c phpunit.xml + docker run --rm -v "$PWD":/app -w /app wakdo-wakdo-app php -d memory_limit=-1 phpstan.phar analyse + ``` + +- **JS (node:test + jsdom)** — modules du front borne : `npm run test:js` +- **E2E (Playwright)** — parcours borne + admin, lances a la main contre une stack jetable : `tests/e2e/run.sh` + +La CI Forgejo execute secret-scan, php-lint, static-tests (PHPStan niveau 6 + PHPUnit avec service MariaDB) et js-tests sur chaque PR. --- ## Deploiement -*Strategie : CI Forgejo Actions sur PR vers `dev`/`main` (secret-scan gitleaks, php-lint, static-tests PHPStan+PHPUnit, js-tests) avec auto-merge sur label + CI verte. CD : declenchement humain, redeploiement par `docker compose pull && docker compose up -d`. Voir `docs/PROJECT_CONTEXT.md` section 7 Bloc 5.* +*CI Forgejo Actions sur PR vers `dev`/`main` (secret-scan gitleaks, php-lint, static-tests PHPStan + PHPUnit, js-tests), avec auto-merge sur CI verte. Deploiement a declenchement humain via `scripts/deploy.sh` (ff-only puis `docker compose -f docker-compose.prod.yml pull && up -d` ; le one-shot `wakdo-migrate` applique migrations + seed). Un veritable CD automatique sur merge `main` reste a armer avec un secret de connexion (choix exploitant). Voir `docs/PROJECT_CONTEXT.md` section 7 Bloc 5.* --- @@ -200,7 +211,8 @@ Avec un `.env` adapte : `APP_ENV=prod`, `APP_DEBUG=false`, mots de passe forts, |---|---| | `docs/PROJECT_CONTEXT.md` | Source de verite projet (17 sections : scope, stack, architecture, mapping critere RNCP, planning, risques, conventions) | | `docs/journal/` | Retrospectives par session et par feature (preparation de l'oral RNCP) | -| `docs/merise/` *(a venir)* | Modelisation Merise : dictionnaire, MCD, MCT, MLD | +| `docs/merise/` | Modelisation Merise : dictionnaire, MCD, MCT, MLD, MLT (+ diagrammes) | +| `docs/ARCHITECTURE.md` / `docs/adr/` | Vue technique + decisions d'architecture (ADR) | | `.claude/CLAUDE.md` | Constitution du projet pour les agents Claude Code | | `.claude/rules/` | Protocoles appliques : fact-check, merise-agile, elo-trust, hermes-dispatcher, byan-api, byan-agents | diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md index 73f16db..d8168db 100644 --- a/docs/PROJECT_CONTEXT.md +++ b/docs/PROJECT_CONTEXT.md @@ -142,7 +142,7 @@ Client Borne (Bloc 1) API (Bloc 2) BDD │ (admin_proxy network) │ └──────────┬────────────────────────────┬─────────────────────────┘ │ │ - wakdo.acadenice.fr wakdo-admin.acadenice.fr + corentin-wakdo.stark.a3n.fr corentin-wakdo-admin.stark.a3n.fr │ │ ▼ ▼ ┌──────────────────────────────────────────┐ @@ -196,7 +196,7 @@ Reseaux : | Orchestration locale | docker compose (service wakdo-migrate) | — | Cr 7.b (script) + Cr 7.c.4 (une commande) | | CI/CD | Forgejo Actions (act_runner auto-heberge) | — | Cr 7.d | | Versioning | Git + Forgejo auto-heberge (push-mirror GitHub) | — | Cr 4.f (collaboration) | -| Hooks Git | pre-commit + commit-msg | versionnes dans `.githooks/` | Conventional Commits | +| Hooks Git | pre-commit (refus main/dev + php -l) + commit-msg (format Conventional Commits) | versionnes dans `.githooks/`, actives via `scripts/install-hooks.sh` | Conventional Commits | --- @@ -262,15 +262,16 @@ Reseaux : **IN scope :** - Dockerfile custom PHP-FPM avec extensions -- `docker-compose.yml` orchestrant les 4 services (web, app, db, cron) +- `docker-compose.yml` orchestrant 5 services : 4 longs (web, app, db, cron) + 1 one-shot (`wakdo-migrate`) - `docker compose up` lance toute la stack (service one-shot `wakdo-migrate` : migrations + seed idempotents) en une commande (Cr 7.c.4) -- Scripts Bash d'automatisation (backup, deploy, migrate) -- **Cron tab** avec au moins 3 jobs planifies dans la fenetre de maintenance (01h30-09h30) : +- Scripts Bash d'automatisation (backup, restore, deploy, migrate) +- **Cron tab** avec 3 jobs actifs planifies dans la fenetre de maintenance (01h30-09h30) : - `0 3 * * *` — backup BDD quotidien a 03h00 (entre fin service 01h et ouverture 10h) - - `*/15 * * * *` — purge sessions expirees toutes les 15 min (leger, peut tourner en service) - - `30 4 * * *` — agregation stats commandes a 04h30 sur le **jour de service** ecoule (10h J-1 → 01h J) -- **CI Forgejo Actions** (act_runner auto-heberge) : lint PHP + PHPStan + PHPUnit + secret-scan (gitleaks) sur PR -> dev -- **CD Forgejo Actions** : deploy auto sur merge main (SSH + `docker compose pull && docker compose up -d`) + - `15 4 * * *` — purge du journal d'audit au-dela de la fenetre de retention (~12 mois) + - `45 4 * * *` — purge des compteurs de throttle expires + - Differes (templates commentes dans `docker/cron/crontab`, a activer plus tard) : purge des sessions expirees, agregation des stats sur le jour de service +- **CI Forgejo Actions** (act_runner auto-heberge) : lint PHP + PHPStan + PHPUnit + secret-scan (gitleaks) + js-tests sur PR -> dev +- **CD : deploiement scripte a declenchement humain** (`scripts/deploy.sh` : ff-only puis `docker compose -f docker-compose.prod.yml pull && up -d`). Choix solo dev sur un environnement de prod unique. Un veritable deploiement continu (job Forgejo sur push main -> SSH -> `deploy.sh`) reste a armer avec un secret de connexion (decision exploitant) - `.env.example` documente (parametres securite : argon2id, lockout, seuils throttle, retention RGPD), secrets hors du repo - `php.ini` durci (expose_php off, session cookies httponly/secure/samesite, upload limite) - Healthcheck Traefik + readiness probes @@ -303,21 +304,21 @@ Reseaux : | Cr 2.a.1-5 | JS ES6+ + DOM + animations | Modules ES6, classes, async/await, pas de jQuery | | Cr 2.b.1-3 | Validation formulaires | Validation client temps reel (regex) + validation serveur | | Cr 2.c.1-4 | Ajax async | `fetch()` avec gestion erreurs, pas d'exposition donnees sensibles | -| Cr 2.d.1-3 | Librairies externes | **Non applicable** (zero dep JS) — argumenter "developpement sans lib externe" | +| Cr 2.d.1-3 | Librairies externes | Choix de stack assume : **zero lib JS** (vanilla). Cr 2.d.1-3 restent du tronc commun evaluable -> a argumenter a l'oral ; ce n'est pas une dispense du referentiel | ### Bloc 2 | Critere | Libelle court | Feature Wakdo couvrant | |---|---|---| -| Cr 3.a.1-4 | Analyse + modele donnees | Dictionnaire + MCD + cardinalites | +| Cr 3.a.2-4 | Analyse + modele donnees (3 criteres ; le referentiel ne contient PAS de Cr 3.a.1) | Dictionnaire + MCD + cardinalites | | Cr 3.a.3 | Exploiter donnees externes d'API | API interne consommee par le front (auto-consommation) | | Cr 3.b.1-3 | Construction BDD | MCD → MLD → DDL MariaDB, FK + typage coherent | | Cr 3.c.1-3 | Requetes SQL optimisees | PDO prepared, index sur FK, LIMIT/tri explicites | | Cr 3.d.1-4 | RGPD | hash mdp, droit acces/modif/suppr, info utilisation donnees | | Cr 4.a.1-4 | Conceptualisation | Schema fonctionnel des vues + interactions | | Cr 4.b.1-6 | Syntaxe + indentation + erreurs | PSR-12 style, try/catch cibles, logs | -| Cr 4.c.1-3 | POO + heritage + namespaces | `BaseModel` -> `Product`, `BaseController` -> `AdminController`, PSR-4 | -| Cr 4.d.1-3 | MVC | `src/Models/`, `src/Views/`, `src/Controllers/`, separation stricte | +| Cr 4.c.1-3 | POO + heritage + namespaces | heritage de controleurs (`Controller` -> `AuthenticatedController` -> `AdminController` -> ...), couche modele en Repository pattern, autoloader PSR-4 manuel | +| Cr 4.d.1-3 | MVC | `src/app/Controllers/`, `src/app/Views/`, couche modele = Repositories (`*Repository`) + `Core/Database` ; separation stricte (pas de dossier `Models/` : Repository pattern) | | Cr 4.e.1-3 | Securite | PDO prepared (anti-SQLi), sessions regeneration, role-based middleware | | Cr 4.f.2 | Maitrise outil collaboratif (artefact) | Commits Conventional, branches `feat/*`, PR descriptions, squash merge, hooks Git | | Cr 4.f.1, 4.f.3, 4.f.4 | Soft skills (evalues a l'oral) | Partage de savoir-faire (4.f.1), auto-evaluation avant PR (4.f.3), compte-rendu de la participation individuelle (4.f.4) — demontres pendant la soutenance | @@ -333,11 +334,11 @@ Reseaux : | Cr 7.b.3 | **Cron tab** | `wakdo-cron` service avec crontab : backup BDD, purge sessions, stats | | Cr 7.c.1 | VM operationnelle | Serveur existant Acadenice | | Cr 7.c.2 | OS conteneur installe | Docker Engine | -| Cr 7.c.3 | App conteneurisee complete | 4 services (web, app, db, cron) | +| Cr 7.c.3 | App conteneurisee complete | 5 services : 4 longs (web, app, db, cron) + 1 one-shot (wakdo-migrate) | | Cr 7.c.4 | **Une ligne de commande** | `docker compose up` lance toute la stack + migrate + seed | | Cr 7.d.1 | Architecture serveur | Traefik reverse + reseaux segmentes documentes | | Cr 7.d.2 | Tests avant deploy | CI PHPUnit + PHPStan + secret-scan sur PR (Forgejo Actions) | -| Cr 7.d.3 | Integration/deploiement continus | Forgejo Actions deploy automatique sur merge main | +| Cr 7.d.3 | Integration/deploiement continus | CI complete sur PR ; deploiement scripte a declenchement humain (`scripts/deploy.sh`). Auto-CD sur merge main non arme (choix solo dev, a argumenter) | --- @@ -680,7 +681,7 @@ Ces regles tiennent lieu de garde-fous pendant toute la duree du projet. Les enf 6. **Zero requete SQL sans prepared statement** (anti-SQLi) 7. **Zero hash mdp en clair** (bcrypt ou argon2) 8. **Zero CORS `*`** (origine explicite uniquement) -9. **Zero deployment manuel** en condition normale (CI/CD) +9. **Deploiement scripte et trace** (`scripts/deploy.sh`), declenche par l'exploitant ; pas de modification manuelle ad hoc en prod 10. **Zero feature hors scope** sans mise a jour de ce document ---