pf1e-simulator/docs/architecture/index.md

Architecture & Plan d'implémentation

Vue d'ensemble

• Architecture technique — modules, flux de données, interfaces
• Plan Phase 2 (LLM) — étapes P5.1–P5.3, décisions, risques
• Conformité SRD — écarts documentés, corrigés, hors périmètre
• Feuille de route — Phases 0, 1, 2, 3 et au-delà

Structure du code

src/pf1e_simulator/
├── combat.py          # CombatEngine, résolution attaques, actions, states
├── dice.py            # parseur notation dés (2d4+1)
├── rng.py             # SeededRng, ScriptedRng
├── models.py          # schémas Pydantic v2 (Combatant, AttackSpec, etc.)
├── map.py             # MapSpec, chargement YAML, validation
├── grid.py            # grille 5-10-5, Dijkstra, airborne_view
├── los.py             # ligne d'effet, couvert (règle des coins)
├── areas.py           # cône, ligne, burst (géométrie zones)
├── effects.py         # StatModifier, resolve_modifiers (empilement bonus)
├── conditions.py      # 29 conditions PF1e + flags comportementaux
├── abilities.py       # dons (Weapon Focus, Power Attack, etc.)
├── spells.py          # SpellSpec, effets, scalage, métamagie
├── metrics.py         # win_rate, win_rate_sigma, win_rate_band
├── runner.py          # EncounterSpec, run_encounter, EncounterReport
├── objectives.py      # primitives Phase 2 (P(survie), P(TPK), etc.)
├── phase2_spike.py    # politique "focus fire", danger cartography
├── cli.py             # argparse, rapport FR, flags LLM
├── loaders/
│   ├── combatant.py   # chargeur PJ + monstres + dons/sorts
│   └── foundry.py     # migration Foundry (one-shot, incomplet)
└── report.py          # LLM report writer (Phase 3)

Décisions clés (D-table)

ID	Domaine	Décision
D1	Économie d'action	Résolue par deux étages (budget général + filtres spécialisés)
D2	Cartographie danger	Non exhaustive : région d'échec + frontière + sensibilité
D3	Priorité v1	Cartographie d'abord, puis optimiseur (mêmes briques)
D4	Fournisseur/modèle	Client agnostique ; implémentation distante d'abord, locale ensuite ; mode JSON/schéma requis
D5	Budget	Plafonds petits (≤ 50 appels/campagne, ≤ 20 combats vitrine) + coupe-circuit
D6	Reproductibilité	Cache obligatoire ; clé composite incluant le modèle ; replay call_seq
D7	Prompts	Externes / dépôt séparé (voir §14)

Gate de validation

uv run pytest -q
uv run ruff check src tests
uv run basedpyright src

• Ruff : select = ["ALL"], longueur ligne 100
• Basedpyright : typeCheckingMode = "strict" sur src et tests
• Transcripts épinglés + assertions statistiques (matchup symétrique dans bande 3σ)

Feuille de route

• Phase 0 ✅ — socle combat (initiative, attaques, critiques, RD, états, déplacement, mêlée/distance)
• Phase 1 ✅ — magie/états (108 sorts, DD/sauvegardes, concentration, invocation, conditions, manœuvres, dons, capacités de classe)
• Phase 2 ✅ — couche tactique LLM (few-shot, réparation bornée, contrat Observation/LLMPolicy)
• Phase 3 ✅ — rapporteur LLM local (agrégation stats + rédaction FR, report.py, --llm-report)
• Phase 4 (futur) — optimiseur de scénarios, campagnes multi-rencontres