SIRH/AGENTS.md

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