An IA assisted dive into domain from legacy code

docs/deep-dive-union-domain.md

@@ -0,0 +1,147 @@
+# Union Bundle Deep Dive
+
+## Ubiquitous Language
+
+- **Union**: federation-level identity (sigle, organisme, address, contact) stored in `union_informations`.  
+  Path: `src/Uriae/UnionBundle/Entity/Union.php`
+- **Partenaire**: partner actor (moral/physical), typed via `TypePartenaire`, optionally scoped to a `Structure`.  
+  Path: `src/Uriae/UnionBundle/Entity/Partenaire.php`
+- **TypePartenaire**: partner role label (ordered list).  
+  Path: `src/Uriae/UnionBundle/Entity/TypePartenaire.php`
+- **Conventionnement**: ordered conventionnement catalog entry.  
+  Path: `src/Uriae/UnionBundle/Entity/Conventionnement.php`
+- **ButFormation**: ordered training-goal catalog entry.  
+  Path: `src/Uriae/UnionBundle/Entity/ButFormation.php`
+- **TypeSituationSortie**: exit typology with ASP codes per SIAE type and category constants (`Durable`, `Transition`, etc.).  
+  Path: `src/Uriae/UnionBundle/Entity/TypeSituationSortie.php`
+- **SituationSortie**: employee insertion exit segment (dates, type, contracts grouping) tied to `ParcoursInsertion`.  
+  Path: `src/Uriae/UnionBundle/Entity/SituationSortie.php`
+- **HomepageMessage**: union-wide homepage banner text.  
+  Path: `src/Uriae/UnionBundle/Entity/HomepageMessage.php`
+
+## Domain Core
+
+- **Union profile aggregate (catalog root)**
+  - Single-row style configuration for the federation.
+  - Depends on `StructureBundle` `Town` for city reference.
+  - Path: `src/Uriae/UnionBundle/Entity/Union.php`
+
+- **Partner directory**
+  - `Partenaire` + `TypePartenaire` (many-to-many typing).
+  - Optional `Structure` scope blurs pure “union referential” vs “structure-local partner”.
+  - Paths: `src/Uriae/UnionBundle/Entity/Partenaire.php`, `src/Uriae/UnionBundle/Entity/TypePartenaire.php`
+
+- **Ordered catalogs**
+  - `Conventionnement`, `ButFormation` with `position` ordering.
+  - Paths: `src/Uriae/UnionBundle/Entity/Conventionnement.php`, `src/Uriae/UnionBundle/Entity/ButFormation.php`
+
+- **Exit taxonomy + lifecycle segment (boundary anomaly)**
+  - `TypeSituationSortie` is clearly union-level referential.
+  - `SituationSortie` is **employee insertion state**: links `ParcoursInsertion`, `Contrat[]`, and exit type. It lives in Union bundle but behaves as **Employee / insertion journey** domain.
+  - Paths: `src/Uriae/UnionBundle/Entity/TypeSituationSortie.php`, `src/Uriae/UnionBundle/Entity/SituationSortie.php`
+
+- **Admin referential UI (not Union-owned data)**
+  - Controllers under Union manage `SuiviBundle` taxonomies (`AxeTypeAction`, `CategorieTypeAction`, `TypeAction`) and evaluation grid (`TypeSavoir`, `CategorieSavoir`, `Savoir`) using `StructureBundle` form types.
+  - Paths:
+    - `src/Uriae/UnionBundle/Controller/ReferentielInsertionController.php`
+    - `src/Uriae/UnionBundle/Controller/GrilleEvaluationController.php`
+
+## Invariants / Concistency
+
+- `src/Uriae/UnionBundle/Entity/Union.php`
+  - Sigle, adresse, code postal (length 5), telephone constraints (via `@Telephone` from Structure bundle).
+
+- `src/Uriae/UnionBundle/Entity/Partenaire.php`
+  - Libellé not blank.
+
+- `src/Uriae/UnionBundle/Entity/TypePartenaire.php`, `Conventionnement.php`, `ButFormation.php`
+  - Name not blank; position field for ordering.
+
+- `src/Uriae/UnionBundle/Entity/TypeSituationSortie.php`
+  - Libellé not blank; ASP code fields length-capped per SIAE column.
+
+- `src/Uriae/UnionBundle/Entity/SituationSortie.php`
+  - Callback `isSituationSortieValid`: if `dateSortie` set then `typeSituationSortie` required.
+  - Callback `isDateSortieValid`: if `typeSituationSortie` set then `dateSortie` required.
+  - `setParcoursInsertion` / `addContrat` maintain bidirectional graph with Employee entities.
+
+- `src/Uriae/UnionBundle/Controller/NatureEmploisController.php`
+  - Metier delete allowed only when no contract references that metier.
+
+- `src/Uriae/UnionBundle/Controller/SituationsSalariesController.php`
+  - Position assignment on add for `ProblemeInsertion` / `DureeAide` (via Employee repositories).
+  
+## Cross-context Dependencies
+
+- **Union -> Structure**
+  - `Union` uses `Town`.  
+  - `Partenaire` optional `Structure`.  
+  - Paths: `src/Uriae/UnionBundle/Entity/Union.php`, `src/Uriae/UnionBundle/Entity/Partenaire.php`
+
+- **Union (entity) -> Employee**
+  - `SituationSortie` -> `ParcoursInsertion`, `Contrat`.  
+  - Path: `src/Uriae/UnionBundle/Entity/SituationSortie.php`
+
+- **Union (controllers) -> Employee**
+  - Metier, resource categories, problem types, aide durations.  
+  - Paths: `src/Uriae/UnionBundle/Controller/NatureEmploisController.php`, `src/Uriae/UnionBundle/Controller/SituationsSalariesController.php`
+
+- **Union (controllers) -> Suivi**
+  - Insertion referential + evaluation grid.  
+  - Paths: `src/Uriae/UnionBundle/Controller/ReferentielInsertionController.php`, `src/Uriae/UnionBundle/Controller/GrilleEvaluationController.php`
+
+- **Downstream consumers**
+  - Employee (`ParcoursInsertion`, `Contrat`, `FirstHome`), Suivi (`Partenaire`, `ButFormation`), Asp (`TypeSituationSortie` codes), Bilan/reporting.
+
+## DDD Slicing
+
+Treat **Union** as two conceptual areas:
+
+### A) Federation referential (true Union BC)
+
+- **Aggregates (candidate)**
+  - `UnionOrganizationProfile` (current `Union` entity).
+  - `PartnerDirectory` (`Partenaire` + types; clarify global vs structure-scoped partners as separate AR or explicit `PartnerScope` VO).
+  - `ConventionnementCatalog`, `ButFormationCatalog`.
+  - `ExitTypeCatalog` (`TypeSituationSortie` only).
+
+- **Value objects (candidate)**
+  - `PartnerLabel`, `ExitTypeCode`, `AspExitCodeBySiae` (wrap per-SIAE code columns).
+
+- **Domain services**
+  - `PartnerTypingPolicy` (conventionneur-only rules currently enforced in Employee `FirstHome` should align with Union vocabulary).
+
+### B) Relocate out of Union (employee insertion)
+
+- **SituationSortie** as part of **Employee / InsertionJourney** aggregate (or its own AR owned by Employee context), with Union only providing `ExitTypeId` / published catalog.
+
+- **Application layer**
+  - “Union admin” use cases that today edit Suivi/Employee referentials should become explicit **application services** in the owning BC, callable from Union UI via APIs or shared kernel interfaces—not direct entity manipulation from Union controllers.
+
+## Reading Order
+
+1. `src/Uriae/UnionBundle/Entity/Union.php`  
+2. `src/Uriae/UnionBundle/Repository/UnionRepository.php`  
+3. `src/Uriae/UnionBundle/Controller/InformationsController.php`  
+4. `src/Uriae/UnionBundle/Entity/Partenaire.php`  
+5. `src/Uriae/UnionBundle/Entity/TypePartenaire.php`  
+6. `src/Uriae/UnionBundle/Repository/PartenaireRepository.php`  
+7. `src/Uriae/UnionBundle/Controller/PartenairesController.php`  
+8. `src/Uriae/UnionBundle/Entity/Conventionnement.php`  
+9. `src/Uriae/UnionBundle/Entity/ButFormation.php`  
+10. `src/Uriae/UnionBundle/Repository/ConventionnementRepository.php`  
+11. `src/Uriae/UnionBundle/Repository/ButFormationRepository.php`  
+12. `src/Uriae/UnionBundle/Controller/FormationsController.php`  
+13. `src/Uriae/UnionBundle/Entity/TypeSituationSortie.php`  
+14. `src/Uriae/UnionBundle/Entity/SituationSortie.php`  
+15. `src/Uriae/UnionBundle/Repository/SituationSortieRepository.php`  
+16. `src/Uriae/UnionBundle/Controller/SituationsSortiesController.php`  
+17. `src/Uriae/UnionBundle/Entity/HomepageMessage.php`  
+18. `src/Uriae/UnionBundle/Controller/HomepageMessageController.php`  
+19. `src/Uriae/UnionBundle/Controller/ReferentielInsertionController.php`  
+20. `src/Uriae/UnionBundle/Controller/GrilleEvaluationController.php`  
+21. `src/Uriae/UnionBundle/Controller/NatureEmploisController.php`  
+22. `src/Uriae/UnionBundle/Controller/SituationsSalariesController.php`  
+23. `src/Uriae/UnionBundle/Controller/TypologieSiaeController.php`  
+24. `src/Uriae/EmployeeBundle/Entity/ParcoursInsertion.php`  
+25. `src/Uriae/EmployeeBundle/Model/SituationSortieUpdater.php`