@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/business-analyse/references/entity-architecture-decision.md

@@ -1,218 +1,218 @@
-# 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
-
----
-
-## 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 zones 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 |
+# 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
+
+---
+
+## 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 zones 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 |