# Architecture & Plan d'implémentation

## Vue d'ensemble

- [Architecture technique](technical-architecture.md) — modules, flux de données, interfaces
- [Plan Phase 2 (LLM)](phase-2-llm-architecture.md) — étapes P5.1–P5.3, décisions, risques
- [Conformité SRD](conformance-srd.md) — écarts documentés, corrigés, hors périmètre
- [Feuille de route](roadmap.md) — 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

```bash
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