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

# 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`