commit c044d9b48c7844a805649691761ccad22899d28f Author: Imugiii Date: Thu Apr 23 15:29:28 2026 +0000 docs: initial project context and methodology scaffold Bootstrap commit pour le projet Wakdo (borne de commande RNCP 37805). Contenu : - docs/PROJECT_CONTEXT.md : source de verite du projet (scope, stack, architecture 2 FQDN, mapping critere RNCP/feature, planning, conventions) - .claude/CLAUDE.md : constitution du projet (methodologie BYAN) - .claude/rules/ : protocoles applique (fact-check scientifique, ELO trust, merise-agile, hermes-dispatcher, byan-api, byan-agents) - .gitignore : scope Option C (moteur BYAN ignore, methodologie visible) Stack : PHP 8.3 + MariaDB 11 + Apache Alpine + Docker + Traefik + GitHub Actions. Strategie B unifiee (front vanilla + back POO MVC from scratch + DevOps containerise). Deadline septembre 2026. diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 0000000..7052263 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,75 @@ +# BYAN - Builder of YAN + +> Projet propulse par BYAN (Merise Agile + TDD + 64 Mantras) +> Installer: `npx create-byan-agent` +> GitHub: https://github.com/Yan-Acadenice/BYAN + +## Hermes - Dispatcher Universel + +**Hermes est le point d'entree universel de ton ecosysteme BYAN.** +Avant de chercher un agent specifique, demande a Hermes. Il connait tous les agents, +workflows et contextes, et te route vers le bon specialiste. + +Pour invoquer Hermes, tape: `@hermes` ou demande simplement "quel agent pour [ta tache]?" + +Voir @.claude/rules/hermes-dispatcher.md pour les commandes Hermes. + +## Architecture BYAN + +``` +{project-root}/ + _byan/ # Plateforme BYAN + _config/ # Manifestes (agents, workflows, tasks) + bmb/ # Module Builder (BYAN, agents, workflows) + _memory/ # Memoire persistante des agents + _output/ # Artefacts generes + .claude/ # Integration Claude Code + CLAUDE.md # Ce fichier (instructions projet) + rules/ # Regles modulaires par domaine + .github/agents/ # Agents Copilot CLI (si installe) +``` + +## Regles de Code + +- Pas d'emojis dans le code, commits, ou specs techniques (Mantra IA-23) +- Code auto-documente, commentaires uniquement pour le POURQUOI (Mantra IA-24) +- Format commits: `type: description` (feat, fix, docs, refactor, test, chore) +- Simplicite d'abord - Rasoir d'Ockham (Mantra #37) +- Challenge Before Confirm - Valider avant d'accepter (Mantra IA-16) + +## Commandes Utiles + +- `@hermes` → Dispatcher universel (recommandations, routage, pipelines) +- Agent disponibles: voir @.claude/rules/byan-agents.md +- Methodologie: voir @.claude/rules/merise-agile.md +- Systeme de confiance epistemique: voir @.claude/rules/elo-trust.md +- Protocol fact-check scientifique: voir @.claude/rules/fact-check.md +- Systeme API byan_web: voir @.claude/rules/byan-api.md + +## API byan_web + +BYAN expose une API REST via `$BYAN_API_URL` avec authentification par token (`ApiKey` ou `Bearer`). +26 tools MCP sont disponibles pour Claude Code — a preferer au curl direct. +Voir @.claude/rules/byan-api.md pour le detail. + +## ELO Trust System + +BYAN calibre l'intensite de ses challenges selon votre score ELO par domaine. +Score bas → explications pedagogiques et scaffolding. Score eleve → aller droit au but. + +Commandes CLI: +- `node bin/byan-v2-cli.js elo summary` — voir tous les scores par domaine +- `node bin/byan-v2-cli.js elo dashboard {domain}` — detail d'un domaine +- `node bin/byan-v2-cli.js elo declare {domain} {level}` — declarer son expertise (junior/mid/senior/lead/expert) + +Dans l'agent BYAN, tapez `[ELO]` pour acceder au menu ELO. + +## Fact-Check Scientifique + +BYAN applique Zero Trust sur lui-meme : tout claim doit etre demonstrable, quantifiable, reproductible. +4 types d'assertions : `[REASONING]` `[HYPOTHESIS]` `[CLAIM Ln]` `[FACT USER-VERIFIED]` +5 niveaux de preuve : L1 (spec officielle, 95%) → L5 (opinion, 20%) +Domaines stricts : security/performance/compliance → LEVEL-2 minimum sinon BLOCKED. + +Agent dédié: `@fact-checker` — analyse assertions, audits de documents, chaines de raisonnement. +Dans BYAN: tapez `[FC]` pour le sous-menu fact-check. diff --git a/.claude/rules/byan-agents.md b/.claude/rules/byan-agents.md new file mode 100644 index 0000000..c4f3c13 --- /dev/null +++ b/.claude/rules/byan-agents.md @@ -0,0 +1,74 @@ +# Agents BYAN - Ecosysteme Complet + +## Core Module (Foundation) + +| Agent | Persona | Role | +|-------|---------|------| +| **hermes** | Dispatcher | Routeur universel, point d'entree | +| **bmad-master** | Orchestrateur | Execute workflows et tasks | +| **yanstaller** | Installeur | Installation intelligente BYAN | +| **expert-merise-agile** | Expert | Conception Merise Agile + MCD/MCT | + +## BMB Module (Builders) + +| Agent | Persona | Role | +|-------|---------|------| +| **byan** | Builder | Createur d'agents via interview (12 questions, 64 mantras) — [FC] + [ELO] intégrés | +| **fact-checker** | Scientifique | Fact-check: assertions, audits de documents, chaines de raisonnement | +| **agent-builder** | Constructeur | Expert en construction d'agents | +| **marc** | Specialiste | Integration GitHub Copilot | +| **rachid** | Specialiste | Deploiement NPM/NPX | +| **carmack** | Optimiseur | Optimisation tokens | +| **patnote** | Gestionnaire | Mises a jour et conflits | + +## BMM Module (SDLC - Software Development Lifecycle) + +| Agent | Persona | Role | +|-------|---------|------| +| **analyst** | Mary | Analyse business, etude de marche, brief | +| **architect** | Winston | Design systeme, tech stack, architecture | +| **dev** | Amelia | Implementation, coding, ultra-succincte | +| **pm** | John | Product management, PRD, roadmap | +| **sm** | Bob | Scrum master, sprint planning, backlog | +| **quinn** | Quinn | QA engineer, tests, couverture | +| **tech-writer** | Paige | Documentation, guides, clarity | +| **ux-designer** | Sally | UX/UI design, empathie utilisateur | +| **quick-flow-solo-dev** | Barry | Dev rapide brownfield | + +## CIS Module (Creative Innovation & Strategy) + +| Agent | Persona | Role | +|-------|---------|------| +| **brainstorming-coach** | Carson | Ideation, "YES AND" energy | +| **creative-problem-solver** | Dr. Quinn | Resolution de problemes | +| **design-thinking-coach** | Maya | Design thinking | +| **innovation-strategist** | Victor | Strategie innovation | +| **presentation-master** | Caravaggio | Presentations, slides | +| **storyteller** | Sophia | Storytelling, narratives | + +## TEA Module (Test Engineering & Architecture) + +| Agent | Persona | Role | +|-------|---------|------| +| **tea** | Murat | Master test architect (ATDD, NFR, CI/CD) | + +## Workflows Cles + +| Workflow | Description | +|----------|-------------| +| `create-prd` | Creer un Product Requirements Document | +| `create-architecture` | Concevoir l'architecture technique | +| `create-epics-and-stories` | Decouper en epics et user stories | +| `sprint-planning` | Planifier un sprint | +| `dev-story` | Developper une story | +| `code-review` | Revoir du code | +| `quick-spec` | Spec rapide conversationnelle | +| `quick-dev` | Dev rapide (brownfield) | +| `elo-workflow` | Consulter et gerer le score ELO (via menu [ELO] du BYAN) | + +## Comment Invoquer un Agent + +Dans Claude Code, demande simplement: +- "Je veux creer une architecture" → Hermes recommande `architect` +- "Analyse ce projet" → Hermes recommande `analyst` +- "Cree un nouvel agent" → Hermes recommande `byan` diff --git a/.claude/rules/byan-api.md b/.claude/rules/byan-api.md new file mode 100644 index 0000000..3ae1e0d --- /dev/null +++ b/.claude/rules/byan-api.md @@ -0,0 +1,121 @@ +# API byan_web — Reference Compacte + +## 1. Base URL + +Base URL dans `$BYAN_API_URL` env. Dev par defaut : `http://localhost:3737`. Prod exemple : `https://byan-api.stark.a3n.fr`. Ne pas inclure `/api` dans `$BYAN_API_URL` — les endpoints le contiennent deja. + +## 2. Authentification + +| Scheme | Quand | Exemple | +|--------|-------|---------| +| `ApiKey ` | Token commence par `byan_` | `Authorization: ApiKey byan_xxx` | +| `Bearer ` | JWT recu via /api/auth/login | `Authorization: Bearer eyJ...` | + +## 3. Format reponse + +```json +{ "data": "", "total": "", "error": "", "code": "ERR_CODE" } +``` + +## 4. Codes d'erreur critiques + +| HTTP | Code | Cause | +|------|------|-------| +| 401 | AUTH_REQUIRED | Token absent ou invalide | +| 403 | FORBIDDEN | Action non autorisee | +| 403 | FORBIDDEN_RBAC | Role insuffisant | +| 404 | NOT_FOUND | Ressource introuvable | +| 409 | SLUG_EXISTS | Slug de projet deja utilise | +| 409 | USERNAME_EXISTS | Username deja pris | + +## 5. MCP tools disponibles (PREFERER ces tools au curl) + +### Tools de base + +| Tool | Usage | Auth requise | +|------|-------|--------------| +| `byan_ping` | Verifier que l'API repond | Non | +| `byan_list_projects` | Lister les projets de l'utilisateur | Oui | +| `byan_import_project` | Importer un projet local dans BYAN | Oui | + +### Projets + +| Tool | Usage | Auth requise | +|------|-------|--------------| +| `byan_api_projects_get` | Obtenir le detail d'un projet par ID/slug | Oui | +| `byan_api_projects_create` | Creer un nouveau projet | Oui | + +### Workflows + +| Tool | Usage | Auth requise | +|------|-------|--------------| +| `byan_api_workflows_list` | Lister les workflows d'un projet | Oui | +| `byan_api_workflows_get` | Detail d'un workflow par ID | Oui | +| `byan_api_workflows_run` | Declencher l'execution d'un workflow | Oui | +| `byan_api_workflow_runs_list` | Lister les executions d'un workflow | Oui | +| `byan_api_workflow_runs_get` | Detail d'une execution par ID | Oui | + +### Knowledge + +| Tool | Usage | Auth requise | +|------|-------|--------------| +| `byan_api_knowledge_list` | Lister les articles de la base de connaissance | Oui | +| `byan_api_knowledge_get` | Obtenir un article par ID | Oui | + +### Memoire + +| Tool | Usage | Auth requise | +|------|-------|--------------| +| `byan_api_memory_list` | Lister les entrees memoire d'un agent | Oui | +| `byan_api_memory_search` | Recherche semantique dans la memoire | Oui | + +### Agents personnalises + +| Tool | Usage | Auth requise | +|------|-------|--------------| +| `byan_api_custom_agents_list` | Lister les agents custom du projet | Oui | +| `byan_api_custom_agents_get` | Detail d'un agent custom par ID | Oui | +| `byan_api_custom_agents_clone_system` | Cloner un agent systeme en agent custom | Oui | + +### Sessions + +| Tool | Usage | Auth requise | +|------|-------|--------------| +| `byan_api_sessions_list` | Lister les sessions actives | Oui | +| `byan_api_sessions_get` | Detail d'une session par ID | Oui | +| `byan_api_sessions_history` | Historique des messages d'une session | Oui | + +### Chat + +| Tool | Usage | Auth requise | +|------|-------|--------------| +| `byan_api_chat_conversations_list` | Lister les conversations | Oui | +| `byan_api_chat_messages_list` | Lister les messages d'une conversation | Oui | +| `byan_api_chat_send` | Envoyer un message dans une conversation | Oui | + +### Recherche et import + +| Tool | Usage | Auth requise | +|------|-------|--------------| +| `byan_api_search` | Recherche globale (projets, agents, knowledge) | Oui | +| `byan_api_import_scan` | Scanner un dossier local avant import | Non | +| `byan_api_import_dry_run` | Simuler un import sans l'executer | Oui | + +## 6. Fallback curl (si un tool MCP manque) + +```bash +curl -H "Authorization: ApiKey $BYAN_API_TOKEN" "$BYAN_API_URL/api/projects" + +curl -X POST -H "Authorization: ApiKey $BYAN_API_TOKEN" -H "Content-Type: application/json" \ + -d '{"trigger":"..."}' "$BYAN_API_URL/api/workflows//run" +``` + +## 7. Patterns courants + +| Je veux... | Tool MCP a appeler | +|------------|--------------------| +| Lister mes projets | `byan_list_projects` | +| Detail d'un projet | `byan_api_projects_get` | +| Lancer un workflow | `byan_api_workflows_run` | +| Chercher dans la memoire | `byan_api_memory_search` | +| Importer un projet local | `byan_import_project` | diff --git a/.claude/rules/elo-trust.md b/.claude/rules/elo-trust.md new file mode 100644 index 0000000..3415515 --- /dev/null +++ b/.claude/rules/elo-trust.md @@ -0,0 +1,78 @@ +# ELO Trust System — Epistemic Trust Protocol + +## Principe + +BYAN mesure la fiabilite des assertions de l'utilisateur par domaine technique +en utilisant un algorithme Glicko-2 simplifie (echelle 0-1000). +Plus le score est eleve, moins le challenge est intense et plus la reponse est concise. + +## Domaines suportees + +| Domaine | K-factor | +|---------|----------| +| security | ×1.5 | +| compliance | ×1.5 | +| performance | ×1.2 | +| javascript, typescript, nodejs, python, rust, go | ×1.0 | +| algorithms | ×0.8 | + +## Paliers ELO + +| Plage | Label | Comportement BYAN | +|-------|-------|-------------------| +| 0-200 | Apprenti | Explications completes, analogies, scaffold maximal | +| 201-450 | Debutant | Guide pas-a-pas, verification frequente | +| 450-550 | Zone morte | Challenge intense (Dunning-Kruger peak) | +| 551-750 | Intermediaire | Challenge modere, hypotheses testees | +| 751-900 | Avance | Challenge minimal, discussion paire-a-paire | +| 901-1000 | Expert | Reponses courtes, pas d'explications basiques | + +## Routage LLM (experimental) + +| ELO max | Modele | +|---------|--------| +| 0-200 | claude-opus (raisonnement profond) | +| 201-600 | claude-sonnet (equilibre) | +| 601+ | claude-haiku (concis, expert autonome) | + +## Protocole de challenge + +Quand l'agent BYAN evalue un claim sur un domaine: +1. Recupere le score ELO du domaine via `node bin/byan-v2-cli.js elo context {domain}` +2. Applique le `promptInstructions` retourne (ton, profondeur, scaffold) +3. Ton invariant: TOUJOURS curieux, JAMAIS accusatoire ("qu'est-ce qui t'a amene a ca?" vs "c'est faux") +4. Apres echange: enregistre le resultat `VALIDATED | BLOCKED | PARTIAL` via CLI +5. Ce protocole est silencieux — l'utilisateur voit seulement le challenge, pas les mecaniques ELO + +## Mecaniques speciales (V2) + +- **Tilt detector**: 3 BLOCKED consecutifs → BYAN propose une pause pedagogique +- **First blood**: premier claim dans un domaine vierge = toujours challenge (Zero Trust) +- **Zone morte 450-550**: incertitude maximale, challenge le plus nuance +- **ELO farming protection**: claims trop faciles → K-factor reduit automatiquement +- **Hot hand**: 3 corrects consecutifs → petit boost de K (puis regression vers la moyenne) +- **Shadow challenger**: expert (750+) peut activer un alter-ego adversarial opt-in + +## Commandes CLI + +```bash +node bin/byan-v2-cli.js elo summary # tous les domaines +node bin/byan-v2-cli.js elo dashboard {domain} # detail d'un domaine +node bin/byan-v2-cli.js elo context {domain} # contexte pour un challenge +node bin/byan-v2-cli.js elo record {domain} {VALIDATED|BLOCKED|PARTIAL} +node bin/byan-v2-cli.js elo declare {domain} {junior|mid|senior|lead|expert} +``` + +## Menu BYAN + +Dans l'agent BYAN, tapez `[ELO]` pour acceder au sous-menu ELO: +- Dashboard par domaine +- Enregistrer un claim +- Declarer son expertise +- Voir le routage LLM recommande + +## Philosophie + +Le score ELO n'est pas une punition — c'est un outil de calibration. +Un score bas signifie "BYAN va t'expliquer plus, pas moins". +La pedagogie s'adapte au niveau, le ton reste constant: bienveillant et curieux. diff --git a/.claude/rules/fact-check.md b/.claude/rules/fact-check.md new file mode 100644 index 0000000..cf1d0db --- /dev/null +++ b/.claude/rules/fact-check.md @@ -0,0 +1,109 @@ +# Fact-Check Protocol — Demonstrable, Quantifiable, Reproducible + +## Principe fondateur + +Tout claim emis par un agent BYAN doit satisfaire les trois criteres : + +| Critere | Definition | Exemple | +|---------|-----------|---------| +| **Demonstrable** | Source primaire verifiable | RFC 7234, redis.io/benchmarks | +| **Quantifiable** | Precis, pas vague | "Redis > 100k ops/sec" pas "Redis est rapide" | +| **Reproductible** | L'utilisateur peut le tester | `redis-benchmark -n 100000` | + +Un claim sans ces trois criteres = opinion ou hypothese, presente comme tel. + +## Les 4 types d'assertions + +Tout output d'agent BYAN est prefixe par son type : + +``` +[REASONING] Deduction logique — pas de garantie de verite +[HYPOTHESIS] Plausible dans ce contexte — a verifier avant action +[CLAIM L{n}] Assertion sourced — niveau n (1-5) +[FACT USER-VERIFIED date] Valide par l'utilisateur avec artefact +``` + +## Les 5 niveaux de preuve + +| Niveau | Score | Sources | +|--------|-------|---------| +| LEVEL-1 | 95% | RFC, W3C, ECMAScript, POSIX, spec officielle | +| LEVEL-2 | 80% | Benchmark executable, CVE reference, docs produit officielles | +| LEVEL-3 | 65% | Article peer-reviewed, livre technique reconnu | +| LEVEL-4 | 50% | Consensus communaute (StackOverflow > 1000 votes) | +| LEVEL-5 | 20% | Opinion / experience personnelle | + +## Domaines stricts + +| Domaine | Niveau minimum | Sous le seuil | +|---------|---------------|---------------| +| security | LEVEL-2 | BLOCKED — CVE ou benchmark requis | +| performance | LEVEL-2 | BLOCKED — profiler output ou benchmark requis | +| compliance | LEVEL-1 | BLOCKED — texte reglementaire requis | + +## Bloc FACT-CHECK standard + +``` +┌─ FACT-CHECK ──────────────────────────────────────────────────┐ +│ Claim : [assertion mot pour mot] │ +│ Domain : [security | performance | javascript | general] │ +│ Verdict : [BLOCKED | CLAIM L1 | CLAIM L2 | CLAIM L3 │ +│ | HYPOTHESIS | REASONING | UNVERIFIED] │ +│ Source : [nom exact depuis _byan/knowledge/sources.md │ +│ ou "aucune — preuve requise: [type exact]"] │ +│ Confiance : [score % selon niveau] │ +│ Challenge : [question manquante — source? reproductible?] │ +└───────────────────────────────────────────────────────────────┘ +``` + +## Trust Score (audit de document) + +``` +Trust Score = (assertions CLAIM + FACT) / total × 100 +Badge : A ≥ 90% | B ≥ 75% | C ≥ 60% | D ≥ 40% | F < 40% +``` + +## Regles invariantes + +- NEVER generate a URL — cite only sources in `_byan/knowledge/sources.md` or user-provided +- ZERO TRUST ON SELF — training data = starting point, not the source +- TONE INVARIANT — always curious, never accusatory +- CHAIN WARNING — chain > 3 steps → compute multiplicative confidence; if < 60%, warn + +## Commandes CLI + +```bash +node bin/byan-v2-cli.js fc check "Redis is always faster than PostgreSQL" +node bin/byan-v2-cli.js fc parse "This is obviously the best approach" +node bin/byan-v2-cli.js fc verify "claim text" "proof artifact" +node bin/byan-v2-cli.js fc graph +node bin/byan-v2-cli.js fc sheet [session-id] +``` + +## Agent dedié + +``` +@fact-checker # Agent Copilot CLI dédié +[FC] # Sous-menu dans l'agent @byan +``` + +## Worker npm + +```javascript +const FactCheckWorker = require('./_byan/workers/fact-check-worker'); +const fc = new FactCheckWorker({ verbose: true }); + +const result = fc.check("Redis is always faster than PostgreSQL"); +// → { assertionType: 'HYPOTHESIS', level: 5, score: 20, status: 'OPINION' } + +const claims = fc.parse("This is obviously the best approach for security"); +// → [{ matched: 'obviously', ... }] +``` + +## Auto-detection patterns + +Declencheurs automatiques (patterns BYAN) : +- Mots absolus : `toujours, jamais, forcement, always, never, obviously` +- Superlatifs : `plus rapide, mieux, optimal, faster, better, superior` +- Best-practices non sourcees : `bonne pratique, best practice, industry standard` +- Affirmations certaines : `il est clair que, prouve que, it is well known that` diff --git a/.claude/rules/hermes-dispatcher.md b/.claude/rules/hermes-dispatcher.md new file mode 100644 index 0000000..e3b8618 --- /dev/null +++ b/.claude/rules/hermes-dispatcher.md @@ -0,0 +1,53 @@ +# Hermes - Dispatcher Universel BYAN + +Hermes est le routeur intelligent de l'ecosysteme BYAN. Il ne fait pas le travail +lui-meme, il invoque le bon specialiste. + +## Commandes Hermes + +| Commande | Action | +|----------|--------| +| `[LA]` | Lister tous les agents par module | +| `[LW]` | Lister les workflows disponibles | +| `[LC]` | Lister les contextes projet | +| `[REC]` | Recommandation: decris ta tache, Hermes trouve le bon agent | +| `[PIPE]` | Pipelines multi-agents pour taches complexes | +| `[?agent]` | Quick help sur un agent sans le charger | +| `[@agent]` | Invoquer directement un agent | +| `[HELP]` | Reafficher le menu | +| `[EXIT]` | Quitter Hermes | + +## Routage Intelligent + +Quand un utilisateur decrit une tache, Hermes recommande le bon agent: + +| Mots-cles | Agent recommande | +|-----------|------------------| +| analyser, requirements, brief, etude | analyst (Mary) | +| architecture, design, tech stack | architect (Winston) | +| coder, implementer, dev, feature | dev (Amelia) | +| tester, QA, coverage, bugs | quinn (QA) / tea (Murat) | +| planifier, sprint, backlog, scrum | sm (Bob) | +| documenter, guide, readme | tech-writer (Paige) | +| UX, design, mockup, interface | ux-designer (Sally) | +| PRD, produit, roadmap, specs | pm (John) | +| creer agent, workflow, module | byan (Builder) | +| brainstorm, idees, innovation | brainstorming-coach (Carson) | +| optimiser, tokens, performance | carmack (Optimizer) | + +## Pipelines Predefinies + +1. **Feature Complete**: PM → Architect → UX → SM → Dev → Tea +2. **Idea to Code**: PM → Architect → SM → Quick Flow +3. **New Agent**: BYAN (handles entire flow) +4. **Refactoring**: Architect → Dev → Tea +5. **Bug Fix**: Dev → Quinn +6. **Documentation**: Analyst → Tech Writer +7. **Quality Complete**: Tea → Quinn → code-review + +## Manifestes + +Hermes lit les manifestes CSV a l'execution: +- `_byan/_config/agent-manifest.csv` - Tous les agents installes +- `_byan/_config/workflow-manifest.csv` - Tous les workflows +- `_byan/_config/task-manifest.csv` - Toutes les tasks standalone diff --git a/.claude/rules/merise-agile.md b/.claude/rules/merise-agile.md new file mode 100644 index 0000000..ed51fa5 --- /dev/null +++ b/.claude/rules/merise-agile.md @@ -0,0 +1,48 @@ +# Methodologie Merise Agile + TDD + +BYAN utilise la methodologie Merise Agile enrichie de 64 mantras. + +## Principes Fondamentaux + +1. **Data Dictionary First** (Mantra #33): Definir les entites de donnees avant toute modelisation +2. **MCD-MCT Cross-Validation** (Mantra #34): Coherence entre modeles de donnees et traitements +3. **Bottom-Up from User Stories**: Les entites emergent des user stories +4. **Incremental Design**: Sprint 0 = MCD squelettique, enrichi sprint par sprint +5. **Test-Driven at All Levels**: Tests conceptuels avant implementation + +## Mantras Cles + +| ID | Mantra | Application | +|----|--------|-------------| +| #37 | Rasoir d'Ockham | Simplicite d'abord, approche MVP | +| #39 | Consequences | Evaluer avant d'executer | +| IA-1 | Trust But Verify | Challenger toutes les exigences | +| IA-16 | Challenge Before Confirm | Jouer l'avocat du diable | +| IA-23 | No Emoji Pollution | Zero emoji dans code, commits, specs | +| IA-24 | Clean Code | Auto-documente, commentaires minimaux | + +## Cycle de Developpement BYAN + +``` +Phase 0: Document Project (brownfield) +Phase 1: Analyse (Brief → PRD) +Phase 2: Planning (Architecture → Epics/Stories) +Phase 3: Solutioning (Sprint Planning) +Phase 4: Implementation (Dev → Test → Review) +``` + +## Niveaux de Test + +Priorite (preferer les niveaux bas): +1. **Unit** > **Integration** > **E2E** +2. Les tests API sont first-class citizens +3. Tout nouveau code necessite des tests unitaires +4. Chemins critiques: tests d'integration +5. Parcours utilisateur: tests E2E + +## Convention Commits + +Format: `type: description` +- Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` +- PAS d'emojis dans les commits +- Description claire et concise en anglais diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a9185f3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,67 @@ +# === Secrets === +.env +.env.local +.env.*.local +*.pem +*.key + +# === BYAN — plateforme (moteur), masquee === +# Le code moteur des agents n'est pas part du rendu RNCP. +# La methodologie appliquee (CLAUDE.md + rules + hooks) reste dans .claude/ +# pour transparence vis-a-vis du jury. +_byan/ +_byan-output/ + +# === Claude Code — on garde UNIQUEMENT la methodologie === +# VISIBLE : .claude/CLAUDE.md (constitution projet) +# VISIBLE : .claude/rules/ (fact-check, merise-agile, ELO trust, etc.) +# IGNORE : tout le reste (agents, skills, hooks, config perso, etat local) +.claude/* +!.claude/CLAUDE.md +!.claude/rules/ + +# === MCP config (potentiellement tokens) === +.mcp.json + +# === PHP / Composer (non utilise mais safety) === +vendor/ +composer.lock +composer.phar + +# === Tests === +.phpunit.result.cache +/tests/_output/ +/tests/_support/_generated/ + +# === OS === +.DS_Store +Thumbs.db + +# === IDE === +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# === Logs === +*.log +/logs/ + +# === Data / Uploads / Backups === +/backups/ +/src/public/uploads/ +/data/ + +# === Build artifacts === +/dist/ +/build/ +/public/build/ + +# === Node (au cas ou) === +node_modules/ +npm-debug.log +yarn-error.log + +# === Docker volumes locaux === +/docker-data/ diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md new file mode 100644 index 0000000..982b73a --- /dev/null +++ b/docs/PROJECT_CONTEXT.md @@ -0,0 +1,584 @@ +# Wakdo — Project Context + +**Source de verite du projet.** Ce document est injecte comme contexte dans tous les agents BYAN utilises pour ce projet (expert-merise-agile, architect, dev, ux-designer, tea, quinn, etc.). Il doit etre mis a jour des qu'une decision structurante change. + +--- + +## 1. Identite projet + +| Champ | Valeur | +|---|---| +| Nom du projet | **Wakdo** — borne de commande fictive (pastiche McDonald's) | +| Auteur | Corentin | +| Cadre | Epreuve RNCP 37805 — Titre Developpeur Web, B2, option **DevOps** | +| Centre | Acadenice | +| Contexte pro | Alternance en tant qu'admin sys + etudiant B2 DevOps | +| Deadline soutenance | **Septembre 2026** | +| Budget heures | 10-15 h/semaine — cible ~240 h effectives | +| Mode de travail | Solo | +| Date de creation du doc | 2026-04-23 | + +--- + +## 2. Contexte metier + +Wakdo est une **borne de commande tactile** pour un restaurant de restauration rapide. L'utilisateur final (client) compose sa commande sur ecran tactile, valide, recupere un numero, puis retire son produit au comptoir. + +### Acteurs + +| Acteur | Role | Interface | +|---|---|---| +| **Client** | Passe sa commande sur la borne | Borne tactile (Bloc 1) | +| **Accueil** | Saisit commandes au **comptoir** (client au guichet) ou au **drive** (client en voiture via intercom + casque equipier), remet les commandes livrees aux clients | Back-office (Bloc 2) | +| **Preparation** | Voit les commandes a preparer triees par heure croissante, les declare "preparees" | Back-office (Bloc 2) | +| **Administration** | CRUD sur donnees (produits, menus, prix, images) + gestion utilisateurs + stats | Back-office (Bloc 2) | + +### Processus metier cle + +``` +Client Borne (Bloc 1) API (Bloc 2) BDD + │ │ │ │ + │─compose panier──────▶│ │ │ + │ │─GET menus,produits───▶│───SELECT──────────▶│ + │ │◀──────────JSON────────│◀───────────────────│ + │─valide────────────────│ │ │ + │─saisit numero─────────│ │ │ + │ │─POST /api/orders─────▶│───INSERT──────────▶│ + │ │◀──────────201─────────│ │ + │─recupere au comptoir │ │ │ + Preparation voit commande pending + → declare "preparee" + Accueil voit commande prete + → declare "livree" +``` + +### Regles metier (MCT - a modeliser en Merise) + +- Un **menu** = burger + accompagnement (frites OU salade) + boisson + sauce +- Les **accompagnements** et **boissons** ont **2 tailles** (normale / grande) +- **Grande taille** = +0,50 € sur le prix de base +- Une **commande** a un **numero** saisi par le client (remplace le paiement dans le cadre de l'exam) +- Statuts commande : `pending` -> `preparing` -> `ready` -> `delivered` (ou `cancelled`) +- **Source commande** (trace sur chaque commande) : `kiosk` (borne autonome) | `counter` (comptoir) | `drive` (drive-thru) +- La preparation voit les commandes triees par **heure de livraison croissante** (tous canaux confondus) +- **Horaires service** : 10h00 → 01h00 du matin (service continu 15h, pas de fermeture intermediaire) +- **Pas de notion de "session de service" a modeliser** : les equipiers se relaient, chacun se connecte a sa prise de poste et se deconnecte a la fin. Pas de "shift" a tracer dans la BDD (hors scope RNCP) +- **Fenetre de maintenance systeme** : 01h30 → 09h30 (crons lourds, backups, agregations) — evite toute interference avec le service actif +- **Notion de "jour de service"** (important pour les stats et l'agregation) : + - Un jour de service J = toutes les commandes creees entre **J 10h00** et **J+1 01h00** + - Exemple : la soiree du 22/04 = commandes `22/04 10:00 → 23/04 01:00`, regroupees sous `service_day = 2026-04-22` + - Une commande creee a 23h55 le 22/04 et livree a 00h30 le 23/04 appartient au meme jour de service (22/04) + - **Implementation** : colonne `service_day` calculee sur la table `orders`, ou vue SQL : + ```sql + service_day = CASE + WHEN HOUR(created_at) < 10 THEN DATE(created_at - INTERVAL 1 DAY) + ELSE DATE(created_at) + END + ``` + - Les requetes de stats (CA jour, produits top, etc.) utilisent `service_day` et non `DATE(created_at)` brut + +--- + +## 3. Contexte academique — RNCP 37805 + +**Referentiel** : [certifpro.francecompetences.fr](https://certifpro.francecompetences.fr/api/fiches/refActivity/24345/472313) + +### Blocs couverts + +| Bloc | Nom | Statut | Activites | +|---|---|---|---| +| **Bloc 1** | Developpement Front-End | Tronc commun obligatoire | A1 (integration), A2 (fonctionnalites JS) | +| **Bloc 2** | Developpement Back-End | Tronc commun obligatoire | A3 (data/BDD), A4 (back-end) | +| **Bloc 5** | DevOps (option 3) | Option choisie | A7 (automatisation + conteneurisation + CI/CD) | + +### Validation + +- **50 % minimum par bloc** pour le valider +- **50 % moyenne globale** pour valider le titre +- **Stage** = 20 % de la note finale (couvert par l'alternance) +- **Controle continu** 30 % + **Examens jurys** 50 % + +--- + +## 4. Strategie de projet + +### Strategie B — unifiee + +**Un seul codebase, deux FQDN d'exposition publique.** Le front Bloc 1 et le back Bloc 2 coexistent dans la meme arborescence. Une bascule mode JSON-seuls (Bloc 1 isole) vs mode API-connecte doit rester possible via configuration. + +**Pourquoi pas strategie A (deux rendus isoles)** : le Bloc 5 DevOps impose une conteneurisation **unique** qui lance la stack complete avec `make init` en une commande (Cr 7.c.4). Deux codebases isolees seraient incoherentes avec cette exigence. + +### Compatibilite evaluation par bloc + +- **Jury Bloc 1** : voit le front seul ; le front peut tomber en fallback sur JSON statiques fournis (`src/public/borne/data/*.json`) si l'API est indisponible. +- **Jury Bloc 2** : voit le back-office + teste l'API via curl/Postman de maniere autonome, sans dependre du front. +- **Jury Bloc 5** : lance `make init` ou `docker compose up`, verifie la CI/CD, les crons, l'archi, les scripts. + +--- + +## 5. Architecture + +### 2 FQDN exposes + +| FQDN | Role | Bloc | Auth | +|---|---|---|---| +| `corentin-wakdo.acadenice.fr` | Borne client (kiosk tactile) | Bloc 1 | Public | +| `corentin-wakdo-admin.acadenice.fr` | Back-office + API REST (sous `/api/*`) | Bloc 2 | Sessions (back-office) + tokens (API ecriture) | + +**CORS** : la borne (`corentin-wakdo.acadenice.fr`) consomme l'API (`corentin-wakdo-admin.acadenice.fr/api/*`). Headers CORS explicites avec origine precise (pas de wildcard `*`), argumentable comme durcissement securite face au jury. + +### Services Docker + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Traefik (existant) │ +│ (admin_proxy network) │ +└──────────┬────────────────────────────┬─────────────────────────┘ + │ │ + wakdo.acadenice.fr wakdo-admin.acadenice.fr + │ │ + ▼ ▼ + ┌──────────────────────────────────────────┐ + │ wakdo-web (Apache Alpine) │ + │ Front controller + reverse vers FPM │ + └──────────┬───────────────────────────────┘ + │ FastCGI :9000 + ▼ + ┌──────────────────────────────────────────┐ + │ wakdo-app (PHP 8.3-fpm Alpine) │ + │ POO MVC — borne.php, admin.php, api.php │ + └──────────┬───────────────────────────────┘ + │ PDO MySQL + ▼ + ┌──────────────────────────────────────────┐ + │ wakdo-db (MariaDB 11) │ + │ volume persistant │ + └──────────────────────────────────────────┘ + + ┌──────────────────────────────────────────┐ + │ wakdo-cron (Alpine + PHP CLI) │ + │ crond — backup BDD, purge sessions, ... │ + └──────────────────────────────────────────┘ +``` + +Reseaux : +- `admin_proxy` (external) — expose `wakdo-web` a Traefik +- `wakdo_internal` (bridge, interne) — isole `wakdo-app`, `wakdo-db`, `wakdo-cron` + +--- + +## 6. Stack technique lockee + +| Couche | Choix | Version | Raison | +|---|---|---|---| +| Front langages | HTML5 + CSS3 + JavaScript | Standards 2024+ | Exigence Bloc 1 (vanilla) | +| Front framework | **Aucun** | — | Sujet Bloc 1 impose | +| Front dep JS | **Aucune** | — | Exigence explicite | +| Back langage | PHP | **8.3** LTS | Moderne, support jusqu'a 2027 | +| Back framework | **Aucun** | — | Sujet Bloc 2 "from scratch" | +| Autoloader | **Manuel** (spl_autoload_register, PSR-4) | — | Defend "from scratch", Cr 4.c.3 compatible | +| Tests | **PHPUnit** via `.phar` autonome | 11.x | Cr 4.g.2 sans Composer | +| Composer | **Non utilise** | — | Colle au "from scratch" | +| BDD | MariaDB | **11** LTS | Compatible MySQL, LTS 2028 | +| Driver BDD | PDO (prepared statements uniquement) | natif PHP | Cr 4.e.1 anti-injection | +| Serveur web | Apache httpd | Alpine latest | Reverse proxy vers PHP-FPM | +| Serveur app | PHP-FPM | 8.3-fpm-alpine | Contenairisation propre | +| Reverse proxy | Traefik (deja en place) | existant | `admin_proxy` network | +| TLS | Let's Encrypt via Traefik | auto | `acme.json` existant | +| Conteneurisation | Docker + docker compose | v2 | Cr 7.c | +| Orchestration locale | Makefile | — | Cr 7.b (script) + Cr 7.c.4 (une commande) | +| CI/CD | GitHub Actions | — | Cr 7.d | +| Versioning | Git + GitHub | — | Cr 4.f (collaboration) | +| Hooks Git | pre-commit + commit-msg | versionnes dans `.githooks/` | Conventional Commits | + +--- + +## 7. Scope fonctionnel + +### Bloc 1 — Borne client (Front) + +**IN scope :** +- Affichage dynamique menus + produits (charges par Ajax depuis API ou JSON fallback) +- Composition panier : produits unitaires OU menus (burger + accompagnement + boisson + sauce) +- Options taille (normale / grande, +0,50 € sur grande) pour accompagnements et boissons +- Options de personnalisation simples (ex : sans oignon, avec fromage) +- Recapitulatif panier (ajout, modification quantite, suppression) +- Validation commande + saisie numero (remplace paiement) +- Envoi POST JSON de la commande vers l'API +- Ecran de confirmation avec numero +- Responsive cible 1920x1080 portrait (borne) **+ adaptatif** autres resolutions +- **Accessibilite RGAA** : police OpenDys pour dyslexiques, navigation clavier, contrastes, alts, pas d'info via couleur seule +- **SEO / semantique** : balises HTML5 (`article`, `aside`, `nav`), schema.org, meta tags uniques, canonical, favicon + +**OUT scope :** +- Paiement reel (remplace par numero de commande) +- Authentification client (pas de compte fidelite) +- Multi-langue (FR uniquement) +- Offline mode + +### Bloc 2 — Back-office + API (Back) + +**IN scope — Back-office :** +- Authentification sessions securisees (hash bcrypt/argon2, protection CSRF, fixation session) — duree de session adaptee a un poste complet d'equipier (idle timeout 4h, absolute timeout 10h) +- 3 roles RBAC : `admin`, `preparation`, `accueil` +- **Admin** : CRUD categories, produits (nom, description, prix, image, dispo), menus (composition + options), utilisateurs +- **Preparation** : liste commandes a preparer triees par heure livraison croissante, bouton "declarer preparee" +- **Accueil** : saisir commande manuellement (comptoir ou drive-thru via casque/intercom), bouton "declarer livree" ; champ `source` enregistre sur chaque commande (`counter` ou `drive`) +- Upload images produits (validation type MIME + taille + stockage dans volume `wakdo_uploads`) +- Historique commandes par statut +- Stats de base (commandes du jour, CA jour, produits top) + +**IN scope — API REST :** +- `GET /api/categories` — liste categories produits +- `GET /api/products` — liste produits (filtrable par categorie) +- `GET /api/menus` — liste menus avec compositions et options +- `POST /api/orders` — creer une commande (body JSON, retour `{id, number, status}`) +- `GET /api/orders/{number}` — recuperer statut commande +- Headers CORS explicites pour l'origine borne +- Reponses JSON standardisees : `{data: ..., error: null}` ou `{data: null, error: {code, message}}` + +**IN scope — Transverse :** +- Architecture **MVC** stricte (Models / Views / Controllers) +- **Heritage** entre classes (ex : `BaseController` -> `AdminController` -> `ProductController`) +- **Namespaces** + autoloader PSR-4 manuel +- **Anti-injection** : PDO prepared statements exclusivement +- **RGPD** : hash mdp, droit consultation/modif/suppr user, info stockage/utilisation donnees + +**OUT scope :** +- Paiement reel, systeme comptable +- Multi-restaurants / multi-bornes +- Fidelite client +- Rapports avances / exports CSV + +### Bloc 5 — DevOps + +**IN scope :** +- Dockerfile custom PHP-FPM avec extensions +- `docker-compose.yml` orchestrant les 4 services (web, app, db, cron) +- `Makefile` avec cible `make init` qui lance tout 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) : + - `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 GitHub Actions** : lint PHP + PHPUnit sur PR -> dev +- **CD GitHub Actions** : deploy auto sur merge main (SSH + pull + `make rebuild`) +- `.env.example` documente, secrets hors du repo +- Healthcheck Traefik + readiness probes +- Logs centralises (stdout des conteneurs) +- Documentation deploiement + architecture (schemas dans `docs/`) + +**OUT scope :** +- Kubernetes / Swarm +- Monitoring complet type Prometheus/Grafana (trop chronophage) +- Multi-environnements (pre-prod, staging) +- Blue-green deployment + +--- + +## 8. Criteres RNCP — mapping feature + +### Bloc 1 + +| Critere | Libelle court | Feature Wakdo couvrant | +|---|---|---| +| Cr 1.a.1 | Integration conforme maquette | Integration HTML/CSS fidele au prototype | +| Cr 1.a.2 | Normes W3C + accessibilite | Validator W3C vert + RGAA | +| Cr 1.a.3 | Tests validator passent | Test en soutenance via W3C validator | +| Cr 1.a.4 | Code commente, indente | Conventions de code appliquees partout | +| Cr 1.a.5 | Balises semantiques | `
`, `