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

# Structure Bundle Deep Dive

## Ubiquitous Language

- **Structure**: tenant-like operational organization that owns users/employees/configuration.  
  Path: `src/Uriae/StructureBundle/Entity/Structure.php`
- **HeadOffice / Groupe**: grouping of structures with admin ownership.  
  Path: `src/Uriae/StructureBundle/Entity/HeadOffice.php`
- **SiaeType**: structure typology and ASP capabilities (`aspEnabled`, `aspFileEnabled`, `mesure`, `idAsp`).  
  Path: `src/Uriae/StructureBundle/Entity/SiaeType.php`
- **FormeJuridique**: legal form reference.  
  Path: `src/Uriae/StructureBundle/Entity/FormeJuridique.php`
- **Town / Department / Region**: territorial reference model.  
  Path: `src/Uriae/StructureBundle/Entity/Town.php`
- **SiteTravail**: work site linked to structure.  
  Path: `src/Uriae/StructureBundle/Entity/SiteTravail.php`
- **Sector**: operational sector linked to structure.  
  Path: `src/Uriae/StructureBundle/Entity/Sector.php`
- **PersonneContact**: structure contact person.  
  Path: `src/Uriae/StructureBundle/Entity/PersonneContact.php`
- **AnnexeFinanciere**: yearly annex identifier for structure financing context.  
  Path: `src/Uriae/StructureBundle/Entity/AnnexeFinanciere.php`
- **ChiffreCle** / **Financement**: yearly KPI and funding model.  
  Paths: `src/Uriae/StructureBundle/Entity/ChiffreCle.php`, `src/Uriae/StructureBundle/Entity/Financement.php`
- **Alerte**: threshold rule per type with display/order metadata.  
  Path: `src/Uriae/StructureBundle/Entity/Alerte.php`
- **Diary / DiaryEvent / DiaryMailer**: operational alert calendar and recipients.  
  Paths: `src/Uriae/StructureBundle/Entity/Diary.php`, `src/Uriae/StructureBundle/Entity/DiaryEvent.php`, `src/Uriae/StructureBundle/Entity/DiaryMailer.php`
- **Competence**: structure-scoped competence catalog reused by employees.  
  Path: `src/Uriae/StructureBundle/Entity/Competence.php`
- **Fusion**: merge workflow between structures with cross-context remapping.  
  Path: `src/Uriae/StructureBundle/Controller/StructureController.php`

## Domain Core

- **Likely root today: `Structure`**
  - Central owner of users, employees, sectors, sites, alerts, diary, annexes, and financial records.
  - Paths:
    - `src/Uriae/StructureBundle/Entity/Structure.php`
    - `src/Uriae/StructureBundle/Repository/StructureRepository.php`

- **Monitoring configuration cluster**
  - `Alerte`, `Diary`, `DiaryEvent`, `DiaryMailer`.
  - Paths:
    - `src/Uriae/StructureBundle/Entity/Alerte.php`
    - `src/Uriae/StructureBundle/Entity/Diary.php`
    - `src/Uriae/StructureBundle/Entity/DiaryEvent.php`
    - `src/Uriae/StructureBundle/Entity/DiaryMailer.php`

- **Profile and topology cluster**
  - Identity/legal/contact + work organization (`SiteTravail`, `Sector`).
  - Paths:
    - `src/Uriae/StructureBundle/Entity/Structure.php`
    - `src/Uriae/StructureBundle/Entity/FormeJuridique.php`
    - `src/Uriae/StructureBundle/Entity/SiaeType.php`
    - `src/Uriae/StructureBundle/Entity/SiteTravail.php`
    - `src/Uriae/StructureBundle/Entity/Sector.php`

- **Financial cluster**
  - Annex, key figures, financings.
  - Paths:
    - `src/Uriae/StructureBundle/Entity/AnnexeFinanciere.php`
    - `src/Uriae/StructureBundle/Entity/ChiffreCle.php`
    - `src/Uriae/StructureBundle/Entity/Financement.php`

- **Boundary reality**
  - Structure aggregate currently directly traverses multiple contexts (Employee/User/Suivi/Union/Asp), especially in controller workflows.

## Invariants / Concistency

- `src/Uriae/StructureBundle/Entity/Structure.php`
  - Structure name uniqueness.
  - Mandatory fields for information and characteristics contexts.
  - SIRET length and structural validation coupling.
  - Town cannot be sentinel invalid value.
  - At least one activity sector required.
  - Category activity constrained to a fixed set of values.
  - Bidirectional consistency for collections (users, employees, sectors, sites, alerts, diary).

- `src/Uriae/StructureBundle/Form/Validator/SiretValidator.php`
  - SIRET validated with Luhn checksum.

- `src/Uriae/StructureBundle/Form/Validator/AnnexeFinanciereValidator.php`
  - Annex values must match allowed patterns.

- `src/Uriae/StructureBundle/Entity/Alerte.php`
  - Alert type constrained to known constants and default behavior fields.

- `src/Uriae/StructureBundle/Entity/Diary.php`
  - Default diary event initialization and base config defaults.

- `src/Uriae/StructureBundle/Controller/CompetenceController.php`
  - Competence deletion blocked if linked to employee competences.

- `src/Uriae/StructureBundle/Controller/StructureController.php`
  - Admin-only operations for create/delete/toggle SMS.
  - On creation, default alert templates are provisioned.
  - On delete, users are disabled or reassigned depending on group role.

- `src/Uriae/StructureBundle/Repository/StructureRepository.php`
  - Soft-deleted structures excluded from normal retrieval paths.
  
## Cross-context Dependencies

- **Structure <-> User**
  - Paths:
    - `src/Uriae/StructureBundle/Entity/Structure.php`
    - `src/Uriae/UserBundle/Entity/User.php`
    - `src/Uriae/UserBundle/Security/SuccessHandler.php`

- **Structure <-> Employee**
  - Paths:
    - `src/Uriae/StructureBundle/Entity/Structure.php`
    - `src/Uriae/EmployeeBundle/Entity/Employee.php`
    - `src/Uriae/EmployeeBundle/Repository/EmployeeRepository.php`

- **Structure <-> Suivi**
  - Paths:
    - `src/Uriae/SuiviBundle/Entity/TypeAction.php`
    - `src/Uriae/SuiviBundle/Entity/CategorieSavoir.php`
    - `src/Uriae/StructureBundle/Model/EvaluationUpdater.php`
    - `src/Uriae/StructureBundle/Controller/ReferentielInsertionController.php`

- **Structure <-> Union**
  - Paths:
    - `src/Uriae/UnionBundle/Entity/Partenaire.php`
    - `src/Uriae/StructureBundle/Controller/StructureController.php`

- **Structure <-> ASP**
  - Paths:
    - `src/Uriae/StructureBundle/Entity/SiaeType.php`
    - `src/Uriae/AspBundle/Model/GeneratorFactory.php`
    - `src/Uriae/AspBundle/Manager/AbstractAspManager.php`
    - `src/Uriae/AspBundle/Entity/AbstractFichierAsp.php`


## DDD Slicing

- **Aggregates (candidate)**
  - `StructureProfile` (identity/legal/contact/territory/SIAE/head-office).
  - `StructureWorkOrganization` (sites/sectors/activity sectors).
  - `StructureMonitoringConfig` (alerts/diary/events/recipients).
  - `StructureFinancialProfile` (annexes/key figures/financing).

- **Value objects (candidate)**
  - `Siret`, `PhoneNumber`, `EmailAddress`, `PostalAddress`.
  - `ActivityCategory`.
  - `AlertThresholds` and `AlertOperand`.
  - `ApiTokenCiphertext`.

- **Domain services (candidate)**
  - `StructureMergeService`.
  - `StructureProvisioningService`.
  - `StructureAlertPolicyService`.
  - `StructureDiaryComputationService`.

- **Repository interfaces (domain-facing)**
  - `StructureRepository`.
  - `StructureMonitoringRepository`.
  - `StructureFinancialRepository`.
  - `StructureMergeReadModel`.
  - `StructureReferenceDataRepository`.

- **Domain events (candidate)**
  - `StructureCreated`.
  - `StructureMerged`.
  - `StructureSoftDeleted`.
  - `StructureMonitoringConfigured`.
  - `StructureSiaeTypeChanged`.
  - `StructureUsersReassigned`.

## Reading Order

1. `src/Uriae/StructureBundle/Entity/Structure.php`  
2. `src/Uriae/StructureBundle/Repository/StructureRepository.php`  
3. `src/Uriae/StructureBundle/Controller/StructureController.php`  
4. `src/Uriae/StructureBundle/Entity/Alerte.php`  
5. `src/Uriae/StructureBundle/Repository/AlerteRepository.php`  
6. `src/Uriae/StructureBundle/Entity/Diary.php`  
7. `src/Uriae/StructureBundle/Entity/DiaryEvent.php`  
8. `src/Uriae/StructureBundle/Entity/DiaryMailer.php`  
9. `src/Uriae/StructureBundle/Model/DiaryHandler.php`  
10. `src/Uriae/StructureBundle/Controller/AlerteController.php`  
11. `src/Uriae/StructureBundle/Entity/SiaeType.php`  
12. `src/Uriae/StructureBundle/Entity/HeadOffice.php`  
13. `src/Uriae/StructureBundle/Entity/SiteTravail.php`  
14. `src/Uriae/StructureBundle/Entity/Sector.php`  
15. `src/Uriae/StructureBundle/Entity/Competence.php`  
16. `src/Uriae/StructureBundle/Form/Validator/AnnexeFinanciereValidator.php`  
17. `src/Uriae/StructureBundle/Form/Validator/SiretValidator.php`  
18. `src/Uriae/StructureBundle/Model/EvaluationUpdater.php`  
19. `src/Uriae/EmployeeBundle/Entity/Employee.php`  
20. `src/Uriae/EmployeeBundle/Entity/Contrat.php`  
21. `src/Uriae/EmployeeBundle/Entity/Pmsmp.php`  
22. `src/Uriae/EmployeeBundle/Repository/EmployeeRepository.php`  
23. `src/Uriae/SuiviBundle/Entity/TypeAction.php`  
24. `src/Uriae/SuiviBundle/Entity/CategorieSavoir.php`  
25. `src/Uriae/AspBundle/Model/GeneratorFactory.php`  
26. `src/Uriae/UserBundle/Entity/User.php`