` — **REQUISE** | `summary` | | Sous-titre | `
` | `subtitle` | | Ligne de stats | `
`, etc.) au besoin. En usage standard, `children` est juste un appel `t('...')`.
**Pourquoi ce design :**
- `bg-[var(--bg-secondary)]` : fond neutre cohérent avec le reste de l'app (gris clair / gris foncé selon le mode)
- `border-l-2 border-[var(--color-accent-500)]` : bordure fine **uniquement à gauche** comme accent visuel (pas une boîte encadrée flashy)
- `text-[var(--text-secondary)]` + `text-xs` : texte discret, hierarchie claire avec le contenu principal
- `px-3 py-2` : padding compact qui respecte les marges du conteneur parent (essentiel pour DocPanel)
**Utilisation:** Apres chaque bloc Mock UI, ajouter un `` contenant
les `{t('interface.annotations.icon')}
{t('interface.annotations.title')}
{t('interface.annotations.code')}
{t('interface.annotations.defaultBadge')}
{t('interface.annotations.cta')}
```
---
## Template TSX Mock UI (TYPE: user)
> **Chemin + namespace selon le mode** (extract-doc `resolved.frontendMode`) :
> - `source` : `web/smartstack-web/src/pages/docs/business/{platform|personal}/{application}/{module}/index.tsx`,
> `useTranslation('docs{App}{Module}')` (camelCase).
> - `client` : `web/{projet}-web/src/pages/docs/business/{application}/{module}/index.tsx`
> (PAS de segment `platform|personal`), `useTranslation('docs-{application}-{module}')`
> (namespace KEBAB = nom du fichier i18n — contrat moduleResources).
```tsx
// {web}/src/pages/docs/business/[{platform|personal}/]{application}/{module}/index.tsx
import { Link } from 'react-router-dom';
import { useTranslation } from 'react-i18next';
import {
ArrowLeft,
Info,
Users,
Zap,
ChevronDown,
// + icones specifiques au module
} from 'lucide-react';
// ═══════════════════════════════════════════════════
// Helper: Annotation (obligatoire pour chaque Mock UI)
// Design discret : fond neutre + bordure gauche d'accent (PAS de fond colore vif).
// ═══════════════════════════════════════════════════
function Annotation({ children }: { children: React.ReactNode }) {
return (
.* en i18n).
const accessRoles = [
{ key: 'admin' },
{ key: 'commercial' },
];
export default function {Module}DocPage() {
const { t } = useTranslation('docsAdministration{Module}');
return (
{/* BREADCRUMB + BACK */}
{/* Tagline accent — REQUISE (clé `summary`). Le gate step-03 bloque si absente. */}
{t('summary')}
{t('subtitle')}
{/* Ligne de stats — texte inline, PAS de pills. Le compteur est un noeud
texte frere (`{N} {t('header.xxx')}`), JAMAIS via la pluralisation i18n
`t('header.xxx', { count })` (si la valeur n'a pas `{{count}}`, le nombre
disparait silencieusement). 2-3 stats : regles, endpoints + 1 metier. */}
{businessRules.length} {t('header.businessRules')}
{apiEndpoints.length} {t('header.apiEndpoints')}
{/* + 1 stat specifique au module si pertinent (statuts, onglets, types…) */}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* SECTION 1: OBJECTIF — Ce que fait le module / a quoi il sert */}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* Rediger {t('objective')} COMME UN OBJECTIF : une description */}
{/* simple et factuelle de ce que permet le module (ce qu'il fait, a */}
{/* quoi il sert), du point de vue utilisateur. PAS de probleme + */}
{/* solution, PAS d'argumentaire de vente. */}
{/* ══════════════════════════════════════════════════════════════════ */}
1
{t('sections.objective')}
{t('objective')}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* SECTION 2: ACCES & ROLES — qui peut faire quoi */}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* Table Role | Peut faire | Portee construite depuis */}
{/* report.accessRoles.rows — UNIQUEMENT les lignes rapportees (le */}
{/* code fait foi ; les warnings du join sont reportes a l'utilisateur */}
{/* par le CLI, JAMAIS publies ici). Pas de breadcrumb : le doc */}
{/* s'ouvre en panneau sur la page elle-meme — seule l'URL reste. */}
{/* ══════════════════════════════════════════════════════════════════ */}
2
{t('sections.access')}
/administration/{module}
{t('access.columns.role')}
{t('access.columns.actions')}
{t('access.columns.scope')}
{accessRoles.map((r) => (
{t(`access.roles.${r.key}.name`)}
{t(`access.roles.${r.key}.actions`)}
{t(`access.roles.${r.key}.scope`)}
))}
{/* Si report.accessRoles.source === 'ba' (rbac.md seul, non verifie
contre le seed), afficher OBLIGATOIREMENT le caveat : */}
{/* {t('access.unverified')} */}
{/* Si report.accessRoles.unmappedCodePermissions est non vide,
signaler ces permissions en caveat (portees par un endpoint mais
accordees a aucun role) — jamais les passer sous silence. */}
{/* FALLBACK (report.accessRoles.source === 'none' — projet sans state
ni BA) : garder la carte simple historique — l'URL ci-dessus + une
liste "permissions requises" depuis apiEndpoints[].permission
(`{ep.permission}` par action).
Le gate n'exige alors PAS la table. */}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* SECTION 3: APERCU DE L'INTERFACE — Mock UI ANNOTE */}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* */}
{/* IMPORTANT: Le Mock UI ci-dessous doit reproduire fidelement */}
{/* la VRAIE page TSX du module. Lire le composant source d'abord. */}
{/* */}
{/* Exemples: */}
{/* - TenantsTemplatePage → 2 cartes template (Personal + Business) */}
{/* - UsersPage → tableau de gestion avec filtres */}
{/* - TicketsPage → Kanban board avec colonnes par statut */}
{/* ══════════════════════════════════════════════════════════════════ */}
3
{t('sections.interface')}
{/* Mock UI reproduisant la vraie page */}
{/* ... MOCK UI FIDELE A LA VRAIE PAGE ... */}
{/* ANNOTATIONS OBLIGATOIRES apres le Mock UI */}
{t('interface.annotations.element1')}
{t('interface.annotations.element2')}
{/* ... une annotation par element visuel important ... */}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* SECTION 4: FORMULAIRE DE CREATION — Mock UI ANNOTE */}
{/* ══════════════════════════════════════════════════════════════════ */}
4
{t('sections.createForm')}
{/* Paragraphe d'introduction */}
{t('form.desc')}
{/* Mock UI du formulaire */}
{/* Champs de formulaire adaptes au module */}
{/* ANNOTATIONS OBLIGATOIRES apres le formulaire */}
{t('form.annotations.field1')}
{t('form.annotations.field2')}
{t('form.annotations.actions')}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* SECTION 5: VUE DETAIL — Mock UI ANNOTE */}
{/* ══════════════════════════════════════════════════════════════════ */}
5
{t('sections.detailView')}
{/* Paragraphe d'introduction */}
{t('detail.desc')}
{/* Mock UI de la vue detail */}
{/* ... MOCK UI FIDELE A LA VRAIE VUE DETAIL ... */}
{/* ANNOTATIONS OBLIGATOIRES */}
{t('detail.annotations.header')}
{t('detail.annotations.tabs')}
{t('detail.annotations.stats')}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* SECTION 6: CAS D'USAGE - Exemples concrets */}
{/* ══════════════════════════════════════════════════════════════════ */}
6
{t('sections.useCases')}
{[1, 2, 3].map((i) => (
{t(`useCases.${i}.situation`)}
{/* Bloc "Avec la fonctionnalite" discret — accent gauche, pas de fond vif */}
Avec la fonctionnalite:
{t(`useCases.${i}.withFeature`)}
))}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* SECTION 7: FONCTIONNALITES DETAILLEES */}
{/* ══════════════════════════════════════════════════════════════════ */}
7
{t('sections.features')}
{[1, 2, 3, 4, 5].map((i) => (
{t(`features.${i}.title`)}
{t(`features.${i}.description`)}
Exemple:
{t(`features.${i}.example`)}
))}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* SECTION 8: FAQ */}
{/* ══════════════════════════════════════════════════════════════════ */}
8
{t('sections.faq')}
{[1, 2, 3, 4, 5].map((i) => (
{t(`faq.${i}.question`)}
{t(`faq.${i}.answer`)}
))}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* ANNEXE OPT-IN (--tech) — SECTION 9: REFERENCE TECHNIQUE */}
{/* ══════════════════════════════════════════════════════════════════ */}
{/* OFF PAR DEFAUT : cette section n'est generee qu'avec le flag */}
{/* --tech. Les permissions par ROLE vivent en Section 2 ; celle-ci */}
{/* garde la vue par ENDPOINT (colonne Permission conservee — autre */}
{/* public : les admins). Un re-run SANS --tech ne supprime JAMAIS */}
{/* une section technique existante. */}
{/* ══════════════════════════════════════════════════════════════════ */}
9
{t('sections.technicalRef')}
{/* Regles metier */}
{t('techRef.businessRules')}
ID
Regle
{businessRules.map((rule) => (
{rule.id}
{t(`techRef.rules.${rule.id}`)}
))}
{/* API Endpoints */}
{t('techRef.apiEndpoints')}
Method
Endpoint
Handler
Permission
{apiEndpoints.map((ep, i) => (
{ep.method}
{ep.path}
{ep.handler}
{ep.permission}
))}
);
}
```
---
## Structure i18n (4 langues obligatoires)
> **IMPORTANT:** Generer les 4 langues: FR (source), EN, DE, IT.
> Chaque fichier i18n est au format **PLAT** (pas de cle racine) pour les pages standalone.
### Fichier: `docs-administration-{module}.json`
```json
{
"nav": {
"backToParent": "Retour a {Parent}"
},
"title": "Nom du module",
"summary": "Une phrase accent resumant l'usage du module (tagline header — REQUISE)",
"subtitle": "Description en 1-2 phrases",
"header": {
"businessRules": "regles metier",
"apiEndpoints": "endpoints API"
},
"sections": {
"objective": "Objectif",
"access": "Acces & roles",
"interface": "Apercu de l'interface",
"createForm": "Formulaire de creation",
"detailView": "Vue detail",
"useCases": "Exemples d'utilisation",
"features": "Ce que vous pouvez faire",
"faq": "Questions frequentes",
"technicalRef": "Reference technique (administrateurs) — cle requise UNIQUEMENT avec --tech"
},
"objective": "Description simple, redigee comme un objectif, de ce que permet le module (ce qu'il fait, a quoi il sert) — sans probleme/solution ni argumentaire",
"access": {
"columns": {
"role": "Role",
"actions": "Peut faire",
"scope": "Portee"
},
"roles": {
"admin": {
"name": "Administrateur",
"actions": "Consulter, creer, modifier, supprimer",
"scope": "toutes"
},
"commercial": {
"name": "Commercial",
"actions": "Consulter, creer",
"scope": "consulter : toutes · creer : les siennes"
}
},
"unverified": "Droits declaratifs (rbac.md) — non verifies contre le seed"
},
"interface": {
"sectionTitle": "Titre de la sous-section",
"annotations": {
"element1": "Explication de l'element visuel 1 du Mock UI",
"element2": "Explication de l'element visuel 2 du Mock UI"
}
},
"form": {
"desc": "Ce formulaire permet de creer un nouveau...",
"fieldLabel1": "Label du champ",
"create": "Creer",
"cancel": "Annuler",
"annotations": {
"field1": "Explication du champ 1",
"field2": "Explication du champ 2",
"actions": "Explication des boutons d'action"
}
},
"detail": {
"desc": "La vue detail s'ouvre lorsque...",
"annotations": {
"header": "Explication de l'en-tete",
"tabs": "Explication des onglets",
"stats": "Explication des indicateurs"
}
},
"useCases": {
"1": {
"persona": "Sophie",
"role": "Administratrice plateforme",
"situation": "Sophie doit...",
"withFeature": "Elle utilise..."
}
},
"features": {
"1": {
"title": "Nom de la fonctionnalite",
"description": "Explication claire",
"example": "Exemple concret"
}
},
"faq": {
"1": {
"question": "Question non-technique ?",
"answer": "Reponse claire et concise."
}
},
"techRef": {
"businessRules": "Regles metier",
"apiEndpoints": "Points de terminaison API",
"rules": {
"BR-001": "Description de la regle metier 1",
"BR-002": "Description de la regle metier 2"
}
}
}
```
> **`access.roles.*`** : une entree par ligne de `report.accessRoles.rows`,
> UNIQUEMENT les lignes rapportees (le code fait foi — ne jamais inventer un
> droit). `name` = le libelle du role rapporte ; `actions` = les actions en
> formulation metier (read → Consulter, create → Creer, …) ; `scope` = la
> portee rapportee (ou le detail par action quand `porteeByAction` est mixte,
> ex. `"consulter : toutes · creer : les siennes"`). `access.unverified` n'est
> requis que quand `source === 'ba'`.
>
> **`techRef.*` + `sections.technicalRef`** : a generer UNIQUEMENT avec
> `--tech` (la section 9 est opt-in, OFF par defaut).
---
## Checklist Documentation (TYPE: user)
Avant de valider une documentation de module `user`, verifier:
- [ ] **Standalone TSX** (PAS DocRenderer, PAS doc-data.ts)
- [ ] **Lecture de la vraie page** TSX source AVANT generation du Mock UI
- [ ] **Mock UI Section 3: Interface** reproduisant fidelement la vraie page
- [ ] **Mock UI Section 4: Formulaire** avec champs du vrai formulaire
- [ ] **Mock UI Section 5: Vue detail** avec onglets/stats de la vraie page
- [ ] **Annotations** sur chaque section Mock UI (composant `Annotation`)
- [ ] **Header complet** : titre + **tagline accent `t('summary')`** (REQUISE — gate `missingRequired`) + sous-titre + **ligne de stats inline** (`{N} {t('header.xxx')}`, compteur en texte frere, PAS de pills, PAS de `{count}` i18n)
- [ ] **Resume descriptif** clair en 1 phrase (neutre, pas une accroche marketing)
- [ ] **Objectif** = Section 1 a part entiere (`t('sections.objective')` + `t('objective')`), decrit simplement ce qu'il fait / a quoi il sert — PAS de probleme/solution, PAS fondu dans le subtitle. (Gate step-03 : `missingRequired` doit etre vide.)
- [ ] **Section 2 Acces & roles** : table Role | Peut faire | Portee depuis `report.accessRoles.rows` UNIQUEMENT (le code fait foi, ne jamais inventer un droit) ; caveat `access.unverified` si `source === 'ba'` ; permissions `unmappedCodePermissions` signalees ; les warnings du join sont REPORTES a l'utilisateur, jamais publies. Fallback `source === 'none'` : carte simple URL + liste de permissions (comportement historique)
- [ ] **2-3 cas d'usage** avec personas nommes
- [ ] **5 fonctionnalites** avec exemples concrets
- [ ] **5 FAQ** non-techniques
- [ ] **Reference technique** (UNIQUEMENT si `--tech`) collapsible: regles metier + API endpoints reels — jamais supprimee d'un doc existant lors d'un re-run sans `--tech`
- [ ] **Theme tokens uniquement** (`var(--bg-secondary)`, `var(--color-accent-*)`, `var(--text-secondary)`, etc.) — JAMAIS de `bg-blue-50`, `border-green-200`, ni `--info-bg`/`--success-bg` pour les blocs d'emphase
- [ ] **Couleur de marque = `--color-accent-*`** (rampe thématisable qui suit l'éditeur de thème) — **JAMAIS `--color-primary-*`** (indigo figé, "flashy"). Badges/halos subtils = `bg-[var(--accent-bg)] text-[var(--accent-text)]`. Vérifier : `grep "color-primary" ` → 0 match
- [ ] **Graphiques & KPI dashboard = palette `--dataviz-*`** : séries via `--dataviz-accent`/`--dataviz-cat-N`, tendances via `--dataviz-trend-*` — jamais `--color-primary-*`/`--color-accent-*` pour les données
- [ ] **ZERO couleur Tailwind palette** : verifier `grep -E "(bg|text|border)-(blue|red|green|yellow|amber|purple|violet|gray|slate|zinc|indigo|teal|cyan|sky|orange|pink|rose|emerald|lime)-[0-9]"` → 0 match
- [ ] **Cards = pattern officiel** : `p-N bg-[var(--bg-card)] border border-[var(--border-color)] rounded-[var(--radius-card)]` — PAS `className="card"`, PAS `rounded-lg`, PAS `bg-white`/`bg-gray-*`
- [ ] **Annotation discrete** : `bg-[var(--bg-secondary)] border-l-2 border-[var(--color-accent-500)]` — pas de boite encadree flashy
- [ ] **Charts fideles + expressifs** : type recharts respecte (histogramme vertical ≠ barres horizontales), ratio max/min ≥ 5x, hauteur ≥ h-24/h-20
- [ ] **Pas d'overflow DocPanel** : `overflow-hidden` sur cards de chart, `min-w-0` sur flex children, pas de width px
- [ ] **Racine sans `px-`** : `` pour compatibilite DocPanel (~480px)
- [ ] **i18n** via `useTranslation()` — pas de texte hardcode
- [ ] **i18n 4 langues** : FR, EN, DE, IT (JSON plat, pas de cle racine)
- [ ] **PAS de section "Benefices"** ni "Avant/Apres"
---
## Types techniques (developer / database / testing)
Ces types n'ont PAS de template TSX ici : ils passent par le composant
`DocRenderer` de SmartStack.app (source mode uniquement — non exporte par
`@atlashub/smartstack`). Leur contrat de donnees (`doc-data.ts` : structure
`DocData`, wrapper de page, i18n imbrique sous la cle namespace, screenshots)
est defini dans [data-schema.md](data-schema.md).