# Entity Architecture Decision Reference

> **Loaded by:** step-01-cadrage (section 4d-bis)
> **Purpose:** Provide a structured decision framework for entity placement in the C/A/M/S/R hierarchy
> **Mode:** ULTRATHINK — all scoring is internal reasoning, only the recommendation is shown to the client

---

## 0. Pre-check: Person Extension

**BEFORE** running the entity architecture scoring, check if this entity represents a person role.

### Detection criteria:
1. **Name match**: Entity name is in the known person role list (Employee, Customer, Manager, Supplier, etc.)
2. **Attribute match**: Entity has 3+ attributes among (firstName, lastName, email, phoneNumber, department, jobTitle, address)

### If detected:
→ Recommend **Person Extension Pattern** (link to User via UserId FK)
→ Ask user to confirm variant: mandatory (always a User) or optional (may or may not have a User)
→ Store `personRoleConfig` in entity structure card
→ **Skip standard entity architecture scoring** for person-specific fields (they come from User)

### Known person role names:
| Variant | Entity names |
|---------|-------------|
| **Mandatory** (always a User) | Employee, Manager, Instructor, Teacher, Trainer, Technician |
| **Optional** (may have a User) | Customer, Client, Supplier, Vendor, Patient, Student, Member, Participant, Candidate, Applicant, Contact, Lead, Prospect, Volunteer, Contractor, Freelancer, Consultant |

---

## 1. Entity Scoring Grid (5 criteria, 0-3 each)

For EACH referenced entity detected during approfondissement, score silently:

| Critere | 0 (Lookup) | 1 (Composant) | 2 (Module leger) | 3 (Module complet) |
|---------|-----------|---------------|-------------------|---------------------|
| **Cycle de vie** | Statique (rarement modifie, admin-only) | CRUD basique (creer, modifier, supprimer) | CRUD + etats/transitions simples | Lifecycle complet (etats multiples, transitions, approbations, archivage) |
| **Nombre d'acteurs** | Admin seul | 1 role utilisateur | 2-3 roles distincts | 4+ roles avec permissions differenciees |
| **Relations** | Lookup (0-1 FK entrantes) | Composant (1-3 FK) | Hub (3-5 FK entrantes/sortantes) | Pivot (5+ FK, central dans le graphe de donnees) |
| **Volume prevu** | < 50 entrees stables | 50-500 entrees | 500-5000 entrees | 5000+ ou croissance continue |
| **Autonomie fonctionnelle** | Pas de sens seul (ex: code postal) | Sens uniquement dans le contexte parent | Pourrait etre utilise seul | Domaine metier independant (ex: Clients, Projets) |

### Interpretation du score total (0-15)

| Score | Classification | Action |
|-------|---------------|--------|
| **0-3** | **Config list** (lookup table) | Table de reference administrable. Pas de module, pas de section. Gere dans la config admin. |
| **4-6** | **Gere dans l'app** (sous-entite) | L'entite est geree comme composant du module parent. Accessible via un onglet dans la page detail du parent. |
| **7-10** | **Module leger** | Module avec section `list` principale. Peu de sections fonctionnelles additionnelles. |
| **11-15** | **Module complet dedie** | Module avec section `list` + sections fonctionnelles riches (dashboard, rapports, workflows). |

---

## 2. Domain Coherence Decision Tree

> **CRITICAL:** Evaluer la coherence domaine AVANT le scoring. Une entite PERIPHERAL avec un score eleve reste un risque de scope creep.

```
L'entite {E} est-elle CORE pour cette application ?
│
├── CORE (sans {E}, l'application perd son sens)
│   │   Exemples : Projets dans une app de gestion du temps,
│   │              Clients dans un CRM,
│   │              Employes dans une app RH
│   │
│   └── Score >= 7 ? → Module dedie (RECOMMANDE avec haute confiance)
│   └── Score 4-6 ? → Section/onglet dans le module principal
│   └── Score 0-3 ? → Config list (rare pour une entite CORE)
│
├── SUPPORT (utile, enrichit l'app, mais pas central)
│   │   Exemples : Departements dans une app de gestion du temps,
│   │              Fournisseurs dans un CRM orientee ventes,
│   │              Categories dans un module produits
│   │
│   ├── Deja gere ailleurs dans l'ecosysteme ? → Systeme externe (RECOMMANDE)
│   └── Pas encore gere ?
│       └── Score >= 7 ? → Module leger (confiance MOYENNE, alerter sur le scope)
│       └── Score 4-6 ? → Section/onglet du module qui en a le plus besoin
│       └── Score 0-3 ? → Config list (RECOMMANDE)
│
└── PERIPHERAL (tangentiel au domaine applicatif)
    │   Exemples : Comptabilite dans une app de gestion du temps,
    │              Logistique dans un CRM,
    │              Facturation dans une app RH (sauf si paie)
    │
    └── TOUJOURS → Config list ou Systeme externe (RECOMMANDE)
        Avertir : "Cette entite sort du perimetre applicatif.
                   Risque de scope creep si integree comme module."
```

---

## 3. Pre-classified Entity Patterns

> **Raccourcis de scoring** : ces patterns accelerent l'analyse en fournissant une classification par defaut.
> Le scoring complet reste necessaire pour confirmer ou overrider.

### 3a. Toujours Module Dedie (score typique >= 11)

| Entite | Domaines typiques | Pourquoi module dedie |
|--------|-------------------|-----------------------|
| Clients/Customers | CRM, Ventes, Facturation | Hub relationnel central, multi-acteur, lifecycle complet avec etats |
| Employes/Employees | RH, Temps, Paie | Acteur central avec donnees sensibles, multi-workflows (conges, evaluations) |
| Projets/Projects | Gestion, Temps, Facturation | Lifecycle complexe (ouvert → en cours → cloture), multi-ressources, reporting |
| Commandes/Orders | Ventes, Logistique | Workflow d'approbation, etats multiples, sous-entites (lignes) |
| Factures/Invoices | Finance, Ventes | Obligations legales, workflow complexe, etats fiscaux |
| Contrats/Contracts | Juridique, RH, Ventes | Lifecycle avec echeances, obligations, renouvellement automatique |
| Produits/Products | Commerce, Inventaire | Catalogue avec variantes, tarification, stock |

### 3b. Souvent Sous-entite du Parent (score typique 4-6)

| Entite | Module parent typique | Pourquoi sous-entite |
|--------|----------------------|-----------------------|
| Adresses | Clients, Employes | Composant du parent, pas de sens sans le parent |
| Notes/Commentaires | Tout module | Sous-objet universel, pas d'autonomie fonctionnelle |
| Pieces jointes/Documents | Tout module | Stockage lie au parent, pas de lifecycle propre |
| Lignes de commande | Commandes | Composant structurel de la commande |
| Tags/Labels | Tout module | Categorisation simple, admin-configurable |
| Contacts (d'un client) | Clients | Personnes liees a l'entite parente |

### 3c. Toujours Config List (score typique 0-3)

| Entite | Pourquoi config list |
|--------|---------------------|
| Pays, Villes | Reference geographique stable, rarement modifiee |
| Devises | Reference systeme, standard ISO |
| Statuts (types enumeres) | Enum ou lookup, admin-only, < 20 valeurs |
| Unites de mesure | Reference technique stable |
| Codes postaux | Reference externe, pas de CRUD utilisateur |
| Types/Categories simples | Flat list sans hierarchie, configurable par admin |

> **Override rule:** Une entite pre-classifiee "config list" peut etre promue en "module leger" si le client exprime un besoin de hierarchie (> 2 niveaux), de workflow, ou de permissions specifiques.

---

## 4. Section Pattern for Modules

> **REGLE FONDAMENTALE : Les sections representent des sections fonctionnelles, PAS des operations CRUD.**

### Le pattern de navigation SmartStack

```
Module
├── Section: list
│   └── Page principale avec grille/table
│   └── Action "Creer" (navigue vers la page /create avec formulaire)
│   └── Clic sur une ligne → navigation vers la page detail
│   └── Resources : {entity}-grid, {entity}-filters, {entity}-form
│
├── (detail = page de detail avec onglets, accessible depuis list)
│   └── Onglet Info → informations principales (lecture + edition)
│   └── Onglet {relation} → sous-entites liees (ex: Lignes, Contacts, Documents)
│   └── Onglet Historique → journal d'activite
│   └── Resources : {entity}-detail, {entity}-tabs, {relation}-panel
│
├── Section: dashboard (SI KPIs/reporting necessaire)
│   └── Vue d'ensemble avec cartes KPI, graphiques, activite recente
│   └── Resources : {entity}-kpi-cards, {entity}-charts, {entity}-activity
│
├── Section: approve (SI workflow d'approbation)
│   └── File d'attente d'approbation, timeline de statut
│   └── Resources : approval-queue, status-timeline
│
├── Section: import (SI import en masse)
│   └── Upload fichier, mapping colonnes, preview, execution
│   └── Resources : import-upload, import-mapping, import-preview
│
└── Section: rapport (SI reporting specifique au module)
    └── Rapports configurables, export, planification
    └── Resources : report-builder, report-export
```

### Ce qui n'est JAMAIS une section

| PAS une section | C'est quoi en realite |
|-----------------|----------------------|
| `create` | Action (bouton) dans la page `list`, navigue vers la page `/create` avec formulaire |
| `edit` | Action dans la page list/detail, navigue vers la page `/:id/edit` avec formulaire pre-rempli |
| `detail` | Page de detail accessible par navigation depuis `list` (pas une section menu) |
| `delete` | Action avec confirmation dans la page `list` ou `detail` |
| `search` | Composant de filtrage integre dans la section `list` |

### Regles de proposition de sections

| Condition detectee | Section a proposer |
|--------------------|--------------------|
| Module avec entites | `list` (TOUJOURS — section par defaut obligatoire) |
| KPIs, indicateurs, ou role manager | `dashboard` |
| Workflow de validation/approbation | `approve` |
| Volume > 100 ou import mentionne | `import` |
| Reporting specifique au module | `rapport` |
| Planification temporelle | `planning` / `calendar` |
| Visualisation geographique | `map` |

---

## 5. Architecture Proposal Template

> **Utiliser ce template quand la recommandation est "Module dedie".**

```markdown
### Architecture proposee : {ModuleName}

| Niveau | Valeur | Justification |
|--------|--------|---------------|
| Context | `business` | Contexte metier standard |
| Application | `{ApplicationCode}` | {Nom de l'application en cours d'analyse} |
| Module | `{ModuleCode}` | {Pourquoi ce decoupage : autonomie fonctionnelle, domaine distinct, cycle de vie propre} |

**Sections fonctionnelles :**

| Section | Justification | Resources |
|---------|---------------|-----------|
| `list` | Page principale de gestion des {entity_plural} | {entity}-grid, {entity}-filters, {entity}-form |
| {section_2} | {pourquoi cette section est necessaire pour CE module} | {resources} |
| ... | ... | ... |

**Onglets de la page detail :**

| Onglet | Contenu | Pourquoi |
|--------|---------|----------|
| Informations | Fiche principale de l'{entity} | Toujours present |
| {relation_1} | {sous-entites ou entites liees} | {pourquoi cet onglet} |
| Historique | Journal des modifications | Toujours present si audit requis |

**Impact sur le graphe de dependances :**
- {ModuleName} sera une dependance de : {list of modules that reference this entity}
- {ModuleName} depend de : {list of modules it references, or "aucun (module fondation)"}
- Position dans le tri topologique : couche {N}
```

---

## 6. Confidence Levels

| Confiance | Quand | Presentation au client |
|-----------|-------|------------------------|
| **HAUTE** | Pre-classification match + Score coherent + Domaine CORE | "Je recommande fortement..." + option en premier avec "(Recommande)" |
| **MOYENNE** | Score dans la zone grise (6-8) ou domaine SUPPORT | "Mon analyse suggere..." + option en premier avec "(Suggere)" |
| **BASSE** | Informations insuffisantes ou domaine PERIPHERAL | "Plusieurs options sont possibles..." + pas de recommandation, options neutres |
