tristan
f493ea237b
Some checks failed
Auto Tag Develop / tag (push) Has been cancelled
| Numéro du ticket | Titre du ticket | |------------------|-----------------| | | | ## Description de la PR ## Modification du .env ## Check list - [ ] Pas de régression - [ ] TU/TI/TF rédigée - [ ] TU/TI/TF OK - [ ] CHANGELOG modifié Reviewed-on: #6 Co-authored-by: tristan <tristan@yuno.malio.fr> Co-committed-by: tristan <tristan@yuno.malio.fr>
139 lines
5.1 KiB
Markdown
139 lines
5.1 KiB
Markdown
# 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`
|