SIRH/AGENTS.md

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.