# AGENTS.md

État des lieux opérationnel du projet SIRH (backend + frontend), mis à jour après les évolutions sur heures/absences/validations.

## 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
- `doc/`: documentation fonctionnelle et règles métier de référence

## 1.1) Référentiel Fonctionnel (obligatoire)

- Référence principale des règles métier: `doc/functional-rules.md`
- Toute intervention doit commencer par une vérification de cohérence avec cette documentation.
- Règle permanente: à chaque développement qui modifie le fonctionnel, la documentation dans `doc/` doit être mise à jour automatiquement dans la même intervention (pas de report).

## 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`, `type`
- `trackingMode`:
  - `TIME`: suivi en heures
  - `PRESENCE`: suivi en demi-journées/journées
- Enums backend:
  - `App\Enum\TrackingMode`
  - `App\Enum\ContractType` (`FORFAIT`, `THIRTY_FIVE_HOURS`, `THIRTY_NINE_HOURS`, `INTERIM`, `CUSTOM`)
- Historique de contrat par employé:
  - table `employee_contract_periods`
  - résolu par `App\Service\Contracts\EmployeeContractResolver`

### Heures / absences
- Les absences sont stockées en **lignes journalières** (découpage automatique dans `AbsenceWriteProcessor`).
- Les absences `countAsWorkedHours=true` créditent:
  - minutes (contrats TIME)
  - unités de présence (contrats PRESENCE)
- Les absences AM/PM effacent les plages horaires concernées.

## 4) Validations (important)

### Validation RH (admin)
- Champ: `work_hours.is_valid`
- Endpoint API Platform standard: `PATCH /api/work_hours/{id}`
- Gérée côté front par `updateWorkHourValidation`.

### Validation site (chef de site)
- Champ: `work_hours.is_site_valid`
- Endpoint dédié: `PATCH /api/work_hours/{id}/site-validation`
- Processor: `src/State/WorkHourSiteValidationProcessor.php`
- Autorisé uniquement aux utilisateurs "Sites" (ni `ROLE_ADMIN`, ni `ROLE_SELF`) dans leur scope site.

### Règles de verrouillage
- `is_valid=true`: ligne verrouillée pour tout le monde (admin inclus pour saisie heures/absence; peut toujours décocher validation RH).
- `is_site_valid=true`:
  - non-admin: ligne verrouillée (heures + absences)
  - admin: ligne éditable
- Toute modification de ligne (heures/présence/absence) remet:
  - `is_site_valid=false`
  - `is_valid=false`

## 5) Page Heures (front)

- Page: `frontend/pages/hours.vue`
- Composable principal: `frontend/composables/useHoursPage.ts`
- Composants:
  - `frontend/components/hours/HoursToolbar.vue`
  - `frontend/components/hours/HoursDayView.vue`
  - `frontend/components/hours/HoursWeekView.vue`

### Comportement par profil (vue jour)
- Admin:
  - colonne RH avec checkbox
  - badge `Site validé` affiché près du site
- Chef de site:
  - colonne `Validation site` avec checkbox
  - colonne RH en lecture (`Validé`/`-`)
- Employé:
  - colonne `Validation site` en lecture
  - colonne RH en lecture

## 6) Résumé hebdo / calculs

- Provider: `src/State/WorkHourWeeklySummaryProvider.php`
- DTOs:
  - `src/Dto/WorkHours/WeeklySummaryRow.php`
  - `src/Dto/WorkHours/WeeklyDaySummary.php`
- Inclut: contrat résolu par jour, absences, crédits, jour/nuit/total, majorations, récup.

Règles majorations:
- Contrats <= 35h: +25% de 35h à 43h, +50% au-delà
- Contrats >= 39h: +25% de 39h à 43h, +50% au-delà
- `INTERIM`: pas de 25% / 50% / récup

## 7) Migrations sensibles

- `migrations/Version20260226183000.php`
  - ajoute `work_hours.is_site_valid BOOLEAN NOT NULL DEFAULT FALSE`
  - non destructive (pas de perte de données)

## 8) Points de vigilance prod

- Toujours exécuter migration avant déploiement code backend/front lié.
- Après déploiement backend, si route manquante côté runtime:
  - `php bin/console cache:clear && php bin/console cache:warmup`
- Vérifier présence route:
  - `/api/work_hours/{id}/site-validation` (PATCH)

## 9) Conventions techniques

- Favoriser DTO explicites plutôt que tableaux associatifs.
- Garder règles métier dans backend (providers/processors/services), front orienté affichage/interaction.
- Maintenir alignement backend DTO PHP / frontend DTO TS (`frontend/services/dto/*`).
- Mettre à jour TU si signature constructor/service change.

## 10) Fichiers à lire avant modification

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