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

# ASP Bundle Deep Dive

## Ubiquitous Language

- **FicheContratAsp**: ASP-facing contract dossier with ASP IDs, statuses, and errors.  
  Path: `src/Uriae/AspBundle/Entity/FicheContratAsp.php`
- **TypeContratAsp**: ASP contract typology (`NPT`, `I`, `R1..R99`) and renewal semantics.  
  Path: `src/Uriae/AspBundle/Entity/TypeContratAsp.php`
- **Suivi**: trace line for ASP file exchanges.  
  Path: `src/Uriae/AspBundle/Entity/Suivi.php`
- **ModificationAsp**: ASP modification request with dedicated lifecycle.  
  Path: `src/Uriae/AspBundle/Entity/ModificationAsp.php`
- **FichierEnvoiAsp / FichierRetourAsp**: outbound/inbound ASP files.  
  Paths: `src/Uriae/AspBundle/Entity/AbstractFichierAsp.php`, `src/Uriae/AspBundle/Entity/FichierRetourAsp.php`
- **SuiviMensuelEtSortieAsp**: monthly batch submission root.  
  Path: `src/Uriae/AspBundle/Entity/SuiviMensuelEtSortieAsp.php`
- **FicheSuiviMensuelEtSortieAsp**: monthly line per contract.  
  Path: `src/Uriae/AspBundle/Entity/FicheSuiviMensuelEtSortieAsp.php`
- **SortieEtSuiviAnnuel / FicheSortieEtSuiviAnnuel**: annual exit/follow-up model.  
  Paths: `src/Uriae/AspBundle/Entity/SortieEtSuiviAnnuel.php`, `src/Uriae/AspBundle/Entity/FicheSortieEtSuiviAnnuel.php`
- **Erreur**: unified internal/return error catalog by ASP domain type.  
  Path: `src/Uriae/AspBundle/Entity/Erreur.php`

## Domain Core

- **De facto root: `FicheContratAsp`**
  - Carries ASP IDs, multi-channel statuses (inscription/sortie/renewal), ASP and internal errors.
  - Hard-linked to `Contrat` (Employee context).
  - Paths:
    - `src/Uriae/AspBundle/Entity/FicheContratAsp.php`
    - `src/Uriae/EmployeeBundle/Entity/Contrat.php`

- **Monthly submission cluster**
  - Root: `SuiviMensuelEtSortieAsp`
  - Child lines: `FicheSuiviMensuelEtSortieAsp`
  - Paths:
    - `src/Uriae/AspBundle/Entity/SuiviMensuelEtSortieAsp.php`
    - `src/Uriae/AspBundle/Entity/FicheSuiviMensuelEtSortieAsp.php`

- **Annual submission cluster**
  - Root: `SortieEtSuiviAnnuel`
  - Child lines: `FicheSortieEtSuiviAnnuel`
  - Paths:
    - `src/Uriae/AspBundle/Entity/SortieEtSuiviAnnuel.php`
    - `src/Uriae/AspBundle/Entity/FicheSortieEtSuiviAnnuel.php`

- **Status behavior**
  - Generic status set in `StatusTrait`.
  - Modification flow has separate status constants.
  - Paths:
    - `src/Uriae/AspBundle/Traits/StatusTrait.php`
    - `src/Uriae/AspBundle/Entity/ModificationAsp.php`

## Invariants / Concistency

- `src/Uriae/AspBundle/Traits/StatusTrait.php`
  - Status is constrained to allowed values.

- `src/Uriae/AspBundle/Entity/FicheContratAsp.php`
  - Clearing both ASP IDs resets auto flags/dates and reverts transfer status branch.
  - Setting both ASP IDs manually marks manual provenance and transmitted status.

- `src/Uriae/AspBundle/Entity/TypeContratAsp.php`
  - Contract type codes constrained to `NPT`, `I`, `R1..R99`.
  - Renewal semantics inferred from label set.

- `src/Uriae/AspBundle/Repository/FicheContratAspRepository.php`
  - Inscription/renewal/sortie/modification candidate filtering encoded via cross-context query rules.
  - Monthly candidate contracts depend on period overlap + ASP IDs presence.

- `src/Uriae/AspBundle/Validator/ErreursInternesValidator.php`
  - EI duration <= 24 months.
  - Work hours/salary/annexe prerequisites.
  - Renewal sequence integrity and ASP ID prerequisites.
  - Aid/resource/PE/agrement consistency mapped to error catalog entries.

- `src/Uriae/AspBundle/Model/FichierRetourAsp/ProcessFichierRetourAsp.php`
  - Return-line length depends on SIAE type.

- `src/Uriae/AspBundle/Model/FichierRetourAsp/ProcessFichierRetourAspSuivieMensuelEtSortie.php`
  - Monthly return line must have expected structure and success code handling.

- `src/Uriae/AspBundle/Model/FichierRetourAsp/ProcessFichierRetourAspSortieEtSuiviAnnuel.php`
  - Annual return parsing enforces line count format and matching sent file expectations.
  
## Cross-context Dependencies

- **ASP -> Employee**
  - `FicheContratAsp` linked to `Contrat`.
  - ASP processing mutates employee-related fields.
  - Paths:
    - `src/Uriae/AspBundle/Entity/FicheContratAsp.php`
    - `src/Uriae/EmployeeBundle/Entity/Contrat.php`
    - `src/Uriae/AspBundle/Manager/AspFicheContratManager.php`

- **ASP -> Structure**
  - Depends on structure metadata (`SiaeType`, `AnnexeFinanciere`, measures, ASP IDs).
  - Paths:
    - `src/Uriae/StructureBundle/Entity/Structure.php`
    - `src/Uriae/StructureBundle/Entity/SiaeType.php`
    - `src/Uriae/StructureBundle/Entity/AnnexeFinanciere.php`

- **ASP -> Union**
  - Uses sortie/typology references for mappings and checks.
  - Paths:
    - `src/Uriae/UnionBundle/Entity/SituationSortie.php`
    - `src/Uriae/UnionBundle/Entity/TypeSituationSortie.php`

- **ASP -> Suivi (indirect reporting coupling)**
  - Aggregated reporting joins via broader employee/bilan query paths.
  - Paths:
    - `src/Uriae/EmployeeBundle/Repository/EmployeeRepository.php`
    - `src/Uriae/BilanBundle/Model/Formatter.php`

## DDD Slicing

- **Aggregates (candidate)**
  - `AspContractDossier` (replacement concept for `FicheContratAsp`).
  - `AspModificationRequest`.
  - `AspMonthlySubmission` + `MonthlySubmissionLine`.
  - `AspAnnualExitSubmission` + `AnnualExitSubmissionLine`.

- **Domain services (candidate)**
  - `AspEligibilityPolicy`.
  - `AspInternalErrorPolicy`.
  - `AspReturnFileParser` (pure parsing).
  - `AspSubmissionDomainService` (state transitions and domain decisions).

- **Repository interfaces (domain-facing)**
  - `AspContractDossierRepository`.
  - `AspMonthlySubmissionRepository`.
  - `AspAnnualExitSubmissionRepository`.
  - `AspErrorCatalogRepository`.

- **Domain events (candidate)**
  - `AspSubmissionRequested`.
  - `AspSubmissionAccepted`.
  - `AspSubmissionRejected`.
  - `AspIdsAssignedToContract`.
  - `AspInternalRuleViolationDetected`.
  - `AspMonthlyLineAccepted`.
  - `AspMonthlyLineRejected`.

- **Value objects (candidate)**
  - `AspEmployeeId`, `AspContractId`.
  - `TransmissionStatus`.
  - `AspErrorCode`.
  - `SubmissionPeriod`.
  - `AnnexeNumber`.
  - `MesureCode`.
  - `AspLineNumber`.

## Reading Order

1. `src/Uriae/AspBundle/Entity/FicheContratAsp.php`  
2. `src/Uriae/AspBundle/Traits/StatusTrait.php`  
3. `src/Uriae/AspBundle/Entity/TypeContratAsp.php`  
4. `src/Uriae/AspBundle/Repository/FicheContratAspRepository.php`  
5. `src/Uriae/AspBundle/Validator/ErreursInternesValidator.php`  
6. `src/Uriae/AspBundle/Manager/AbstractAspManager.php`  
7. `src/Uriae/AspBundle/Manager/AspFicheContratManager.php`  
8. `src/Uriae/AspBundle/Model/FichierRetourAsp/ProcessFichierRetourAsp.php`  
9. `src/Uriae/AspBundle/Model/FichierRetourAsp/ProcessFichierRetourAspRenouvellement.php`  
10. `src/Uriae/AspBundle/Model/FichierRetourAsp/ProcessFichierRetourAspModification.php`  
11. `src/Uriae/AspBundle/Controller/AbstractInscriptionRenouvellementSortieController.php`  
12. `src/Uriae/AspBundle/Controller/InscriptionController.php`  
13. `src/Uriae/AspBundle/Controller/RenouvellementController.php`  
14. `src/Uriae/AspBundle/Controller/ModificationController.php`  
15. `src/Uriae/AspBundle/Entity/SuiviMensuelEtSortieAsp.php`  
16. `src/Uriae/AspBundle/Entity/FicheSuiviMensuelEtSortieAsp.php`  
17. `src/Uriae/AspBundle/Manager/SuiviMensuelManager.php`  
18. `src/Uriae/AspBundle/Model/FichierRetourAsp/ProcessFichierRetourAspSuivieMensuelEtSortie.php`  
19. `src/Uriae/AspBundle/Entity/SortieEtSuiviAnnuel.php`  
20. `src/Uriae/AspBundle/Entity/FicheSortieEtSuiviAnnuel.php`  
21. `src/Uriae/AspBundle/Model/SortieEtSuiviAnnuelManager.php`  
22. `src/Uriae/AspBundle/Model/FichierRetourAsp/ProcessFichierRetourAspSortieEtSuiviAnnuel.php`  
23. `src/Uriae/EmployeeBundle/Entity/Contrat.php`  
24. `src/Uriae/EmployeeBundle/Controller/ContratsController.php`  
25. `src/Uriae/EmployeeBundle/Form/Type/ContratType.php`  
26. `src/Uriae/StructureBundle/Entity/SiaeType.php`  
27. `src/Uriae/UnionBundle/Entity/TypeSituationSortie.php`