deep-dive-ming/docs/deep-dive-employee-domain.md

# Employee Bundle Deep Dive

## Ubiquitous Language

- **Employee / Salarie / Employe**: central person lifecycle record.  
  Path: `src/Uriae/EmployeeBundle/Entity/Employee.php`
- **TypeEmployee**: profile category driving workflows/filters.  
  Paths: `src/Uriae/EmployeeBundle/Entity/Employee.php`, `src/Uriae/EmployeeBundle/Repository/EmployeeRepository.php`
- **Employee state** (`Postulant`, `En contrat`, `Sorti`): lifecycle projection from contracts/sortie.  
  Paths: `src/Uriae/EmployeeBundle/Entity/Employee.php`, `src/Uriae/EmployeeBundle/Model/EmployeeStateUpdater.php`
- **Contrat**: contract period + métier + site + ASP bridge.  
  Path: `src/Uriae/EmployeeBundle/Entity/Contrat.php`
- **ParcoursInsertion**: insertion timeline + sortie segments.  
  Path: `src/Uriae/EmployeeBundle/Entity/ParcoursInsertion.php`
- **SituationSortie**: exit segment with dates/type.  
  Path: `src/Uriae/UnionBundle/Entity/SituationSortie.php`
- **FirstHome**: intake/prescriber/resource/mutuelle context.  
  Path: `src/Uriae/EmployeeBundle/Entity/FirstHome.php`
- **AdministrativeInformation**: civil/admin identity block (NIR/NTT, nationality, birth info).  
  Path: `src/Uriae/EmployeeBundle/Entity/AdministrativeInformation.php`
- **PersonnalDetail**: address/contact block.  
  Path: `src/Uriae/EmployeeBundle/Entity/PersonnalDetail.php`
- **HiringStatus**: eligibility and social condition matrix (RSA, AAH, RQTH, etc.).  
  Path: `src/Uriae/EmployeeBundle/Entity/HiringStatus.php`


## Domain Core

- **De facto root: `Employee`**
  - Owns/coordinates personal, admin, intake, insertion, contracts, jobs, medical visits, receipts, competencies.
  - Path: `src/Uriae/EmployeeBundle/Entity/Employee.php`

- **Contract lifecycle cluster**
  - `Contrat` + ASP contract dossier + sortie semantics.
  - Paths:
    - `src/Uriae/EmployeeBundle/Entity/Contrat.php`
    - `src/Uriae/AspBundle/Entity/FicheContratAsp.php`
    - `src/Uriae/UnionBundle/Entity/SituationSortie.php`

- **Insertion timeline cluster**
  - `ParcoursInsertion` with associated sortie segments.
  - Path: `src/Uriae/EmployeeBundle/Entity/ParcoursInsertion.php`

- **Profile/intake clusters**
  - `PersonnalDetail`, `AdministrativeInformation`, `HiringStatus`, `FirstHome`.
  - Paths:
    - `src/Uriae/EmployeeBundle/Entity/PersonnalDetail.php`
    - `src/Uriae/EmployeeBundle/Entity/AdministrativeInformation.php`
    - `src/Uriae/EmployeeBundle/Entity/HiringStatus.php`
    - `src/Uriae/EmployeeBundle/Entity/FirstHome.php`

## Invariants / Concistency

- `src/Uriae/EmployeeBundle/Entity/Employee.php`
  - State constrained to known values.
  - `civility` drives derived sex.
  - Sortie considered complete only when both date + type are present.
  - Contract timeline helpers (first/last/previous/initial logic).

- `src/Uriae/EmployeeBundle/Model/EmployeeStateUpdater.php`
  - Recomputes state from contracts/sortie chronology.

- `src/Uriae/EmployeeBundle/Entity/Contrat.php`
  - Contract date ordering constraints.
  - ROME validity constraints.
  - ASP-specific duration-in-months rounding behavior.

- `src/Uriae/EmployeeBundle/Form/Validator/DateEffectiveContratValidator.php`
  - Prevents new/update contract when previous relevant contract has no effective end date.

- `src/Uriae/EmployeeBundle/Form/Validator/CodeRomeValidator.php`
  - Rejects expired ROME codes at contract start.
  - Adds date-threshold behavior around 2022 policy.

- `src/Uriae/EmployeeBundle/Entity/ParcoursInsertion.php`
  - Agreement number format constraints.
  - First/last sortie determination rules by entry dates.

- `src/Uriae/UnionBundle/Entity/SituationSortie.php`
  - Sortie type/date consistency (both required together).

- `src/Uriae/EmployeeBundle/Model/SituationSortieUpdater.php`
  - Rebuilds contract-sortie mapping.
  - Removes empty sorties.
  - Creates sortie for orphan contracts.
  - Triggers state refresh.

- `src/Uriae/EmployeeBundle/Entity/AdministrativeInformation.php`
  - Birth date required and validated.
  - NIR/NTT consistency via validators.

- `src/Uriae/EmployeeBundle/Form/Validator/SocialSecurityNumberValidator.php`
  - NIR shape + civility constraints.
  - NTT fallback requirement when NIR absent in specific cases.

- `src/Uriae/EmployeeBundle/Form/Validator/TemporaryTechnicalNumberValidator.php`
  - NIR/NTT mutual exclusivity.

- `src/Uriae/EmployeeBundle/Entity/HiringStatus.php`
  - Coherence between social flags (RSA/ayant-droit, sans-ressources, AAH-handicap linkage).
  - Young-in-difficulty age window logic based on DOB + first contract.

- `src/Uriae/EmployeeBundle/Entity/PersonnalDetail.php`
  - At least one phone required.
  - Phone/address/town/zip consistency checks.

- `src/Uriae/EmployeeBundle/Entity/FirstHome.php`
  - PE inscription-dependent fields required conditionally.
  - PE identifier formatting.
  - Conventionneur-only partner constraint.
  
## Cross-context Dependencies

- **Employee -> Suivi**
  - Paths:
    - `src/Uriae/EmployeeBundle/Entity/Employee.php`
    - `src/Uriae/SuiviBundle/Entity/Accompagnement.php`
    - `src/Uriae/SuiviBundle/Entity/Evaluation.php`
    - `src/Uriae/SuiviBundle/Entity/Problematique.php`
    - `src/Uriae/SuiviBundle/Entity/Potentiel.php`
  - DDD direction idea: Suivi consumes Employee identity/reference, not full object graph.

- **Employee -> ASP**
  - Paths:
    - `src/Uriae/EmployeeBundle/Entity/Contrat.php`
    - `src/Uriae/AspBundle/Entity/FicheContratAsp.php`
    - `src/Uriae/AspBundle/Manager/AspFicheContratManager.php`
  - DDD direction idea: ASP as downstream integration context reacting to contract events.

- **Employee -> Union**
  - Paths:
    - `src/Uriae/EmployeeBundle/Entity/ParcoursInsertion.php`
    - `src/Uriae/UnionBundle/Entity/SituationSortie.php`
  - DDD direction idea: shared kernel or ACL around sortie taxonomy.

- **Employee <-> Structure**
  - Paths:
    - `src/Uriae/EmployeeBundle/Entity/Employee.php`
    - `src/Uriae/StructureBundle/Entity/Structure.php`
  - DDD direction idea: explicit IDs/reference objects instead of deep bidirectional graph.


## DDD Slicing
- **Aggregates (candidate)**
  - `EmployeeProfile` (identity + personal/admin + hiring status).
  - `EmploymentLifecycle` (contracts + state projection + timeline fields).
  - `InsertionJourney` (parcours + sortie segments).
  - `IntakeContext` (first home/resources/mutuelle data).
  - `EmployeeCompetency` (employee-competence assignment).

- **Domain services (candidate)**
  - `EmployeeStatePolicy` (from `EmployeeStateUpdater`).
  - `SituationSortieRebuilder` (from `SituationSortieUpdater`).
  - `ContractTimelineCalculator` (first/last contract rules).
  - `HiringStatusPolicy` (coherence rules currently scattered in entity callbacks/validators).

- **Repository interfaces (domain-facing)**
  - `EmployeeRepository` (aggregate retrieval only).
  - `ContractRepository` (active/last/chronology views).
  - `InsertionJourneyRepository`.
  - Separate read-model queries for reporting/export/bilan.

- **Domain events (candidate)**
  - `ContractAdded`, `ContractUpdated`, `ContractRemoved`.
  - `EmployeeStateChanged`.
  - `SituationSortieRecomputed`.
  - `AspSubmissionAcknowledged` (integration side).

- **Value objects (candidate)**
  - `EmployeeState`, `EmployeeTypeSlug`.
  - `ContractPeriod`.
  - `SocialSecurityNumber`, `TemporaryTechnicalNumber`.
  - `AgreementNumber`, `PoleEmploiId`.
  - `PhoneNumber`, `PostalAddress`, `ZipCode`.

`src/Uriae/EmployeeBundle/Entity/Employee.php`

## Reading Order (Employee domain deep dive)

1. `src/Uriae/EmployeeBundle/Entity/Employee.php`  
2. `src/Uriae/EmployeeBundle/Entity/Contrat.php`  
3. `src/Uriae/EmployeeBundle/Entity/ParcoursInsertion.php`  
4. `src/Uriae/UnionBundle/Entity/SituationSortie.php`  
5. `src/Uriae/EmployeeBundle/Model/SituationSortieUpdater.php`  
6. `src/Uriae/EmployeeBundle/Model/EmployeeStateUpdater.php`  
7. `src/Uriae/EmployeeBundle/EventSubscriber/ContratChangeSubscriber.php`  
8. `src/Uriae/EmployeeBundle/Entity/AdministrativeInformation.php`  
9. `src/Uriae/EmployeeBundle/Entity/HiringStatus.php`  
10. `src/Uriae/EmployeeBundle/Entity/PersonnalDetail.php`  
11. `src/Uriae/EmployeeBundle/Entity/FirstHome.php`  
12. `src/Uriae/EmployeeBundle/Entity/Pmsmp.php`  
13. `src/Uriae/EmployeeBundle/Form/Validator/DateEffectiveContratValidator.php`  
14. `src/Uriae/EmployeeBundle/Form/Validator/CodeRomeValidator.php`  
15. `src/Uriae/EmployeeBundle/Form/Validator/SocialSecurityNumberValidator.php`  
16. `src/Uriae/EmployeeBundle/Form/Validator/TemporaryTechnicalNumberValidator.php`  
17. `src/Uriae/EmployeeBundle/Repository/EmployeeRepository.php`  
18. `src/Uriae/EmployeeBundle/Repository/ContratRepository.php`  
19. `src/Uriae/EmployeeBundle/Controller/ContratsController.php`  
20. `src/Uriae/EmployeeBundle/Controller/InsertionController.php`  
21. `src/Uriae/AspBundle/Entity/FicheContratAsp.php`  
22. `src/Uriae/AspBundle/Manager/AspFicheContratManager.php`  
23. `src/Uriae/SuiviBundle/Entity/Accompagnement.php`  
24. `src/Uriae/SuiviBundle/Entity/Evaluation.php`  
25. `src/Uriae/StructureBundle/Entity/Structure.php`