# AGENTS.md

État des lieux opérationnel du projet SIRH (backend + frontend), à utiliser comme base sur les prochaines interventions.

## 1) Stack et structure

- Backend: Symfony + API Platform + Doctrine ORM
- Frontend: Nuxt 4 + Vue 3 + TypeScript + Tailwind
- Exécution locale: Docker via `makefile`

Arborescence clé:
- `src/`: domaine, API resources, state providers/processors, services
- `tests/`: TU backend (PHPUnit)
- `frontend/`: app Nuxt (pages, composants, composables, services)
- `migrations/`: migrations Doctrine

## 2) Commandes utiles

- Démarrer stack: `make start`
- Tests backend: `make test`
- Build frontend: `cd frontend && npm run build`
- Dev frontend: `make dev-nuxt`

## 3) Domaine métier (résumé)

### Contrats
- Entité: `Contract`
- Champs principaux: `name`, `trackingMode`, `weeklyHours`, `isActive`
- `trackingMode`:
  - `TIME`: suivi par heures
  - `PRESENCE`: suivi présence demi-journées/journées
- Enums backend:
  - `App\Enum\TrackingMode`
  - `App\Enum\ContractType` (`FORFAIT`, `35H`, `39H`, `INTERIM`, `CUSTOM`)
- `Contract::getType()` est exposé en API (`contract:read`, `employee:read`)

### Heures / absences
- Les absences sont découpées en enregistrements journaliers (pas de période unique stockée).
- Une ligne d’heures validée est verrouillée côté métier.
- Règles de crédit absence (`countAsWorkedHours=true`) gérées dans `WorkedHoursCreditPolicy`:
  - contrats présence: crédit en unités de présence
  - contrats temps: crédit en minutes selon règles contrat (35h, 39h, 4h, fallback)

## 4) Écrans principaux

### Page Heures (`frontend/pages/hours.vue`)
- Vue Jour + Vue Semaine (semaine réservée admin)
- Toolbar dédiée: `frontend/components/hours/HoursToolbar.vue`
- Vue jour: `frontend/components/hours/HoursDayView.vue`
- Vue semaine: `frontend/components/hours/HoursWeekView.vue`
- Logique page: `frontend/composables/useHoursPage.ts`

### Points UX déjà en place
- Toolbar semaine: raccourcis semaine précédente / actuelle / suivante
- Légende absences affichée dans la toolbar (admin + vue semaine)
- Cellules semaine avec absence: couleur du type d’absence (plus rouge fixe)
- Pour user non-admin: restrictions d’édition selon validations/absences

## 5) API / calculs hebdo

- Provider: `src/State/WorkHourWeeklySummaryProvider.php`
- DTOs:
  - `src/Dto/WorkHours/WeeklySummaryRow.php`
  - `src/Dto/WorkHours/WeeklyDaySummary.php`
- Le résumé hebdo renvoie notamment:
  - `trackingMode`
  - `contractName`
  - `contractType`
  - détails journaliers (jour/nuit/total, présence, absence label/couleur)

### Heures supp
- Règles métier:
  - contrats <= 35h: tranche 25% de 35h à 43h, puis 50% au-delà
  - contrats >= 39h: tranche 25% de 39h à 43h, puis 50% au-delà
  - contrats `INTERIM`: pas de bonus 25/50 ni récup

## 6) Conventions techniques

- Favoriser DTO explicites plutôt que tableaux associatifs bruts.
- Utiliser les interfaces repository dans providers/processors testés.
- Centraliser les règles métier dans services/providers backend plutôt que dupliquer côté front.
- Front: éviter les calculs métier lourds; consommer les champs API déjà calculés.

## 7) Tests et qualité

- Les TU backend passent actuellement via `make test`.
- Le build frontend passe via `npm run build`.
- À chaque évolution métier:
  - mettre à jour les tests provider/processor/service impactés
  - maintenir la cohérence des DTO TypeScript (`frontend/services/dto/*`)

## 8) Fichiers sensibles (à lire avant modif)

- `src/State/WorkHourWeeklySummaryProvider.php`
- `src/Service/WorkHours/WorkedHoursCreditPolicy.php`
- `src/State/AbsenceWriteProcessor.php`
- `src/State/WorkHourBulkUpsertProcessor.php`
- `frontend/composables/useHoursPage.ts`
- `frontend/components/hours/HoursWeekView.vue`

## 9) Décisions de conception actuelles

- Les absences sont stockées par jour (facilite verrouillage/édition fine).
- Les règles de calcul (crédits, majorations, récup) sont portées côté backend.
- Le front reste centré sur l’affichage/interaction et réutilise les données enrichies de l’API.