# Templates de Documentation SmartStack

> **Objectif:** Documentation lisible par un metier, pas seulement par des developpeurs.
> Chaque module doit repondre a: "Qu'est-ce que ca m'apporte ?"

---

## STRUCTURE OBLIGATOIRE (Type: user)

Chaque documentation de module DOIT inclure ces sections dans cet ordre:

| # | Section | Objectif | Public cible |
|---|---------|----------|--------------|
| 1 | **Valeur Metier** | Pourquoi cette fonctionnalite existe | Decideurs, Managers |
| 2 | **Cas d'usage** | Exemples concrets du quotidien | Utilisateurs finaux |
| 3 | **Benefices** | Gains mesurables (temps, argent, qualite) | Decideurs |
| 4 | **Avant/Apres** | Comparaison visuelle | Tous |
| 5 | **Fonctionnalites** | Liste detaillee des capacites | Utilisateurs |
| 6 | **Comment ca marche** | Guide pas a pas | Utilisateurs |
| 7 | **FAQ Metier** | Questions non-techniques | Tous |
| 8 | **Reference technique** | Permissions, API (optionnel) | Admins |

---

## Data-Driven Approach (Recommended)

> **Principe:** Au lieu de générer un composant TSX complet (~250 lignes) par module,
> générer uniquement un fichier de DONNÉES (`doc-data.ts`, ~50 lignes) + un wrapper minimal.
> Le rendu est assuré par le composant partagé `DocRenderer` dans `web/.../components/docs/`.

### Fichiers à générer par module

**1. Data file** (`doc-data.ts`) : Voir [data-schema.md](data-schema.md) pour le mapping complet.

**2. Page wrapper** (`index.tsx`, ~10 lignes) :
```tsx
import { DocRenderer } from '@/components/docs';
import { docData } from './doc-data';

export default function {ModuleName}DocPage() {
  return <DocRenderer data={docData} backPath="/docs/business/{app}" />;
}
```

**3. i18n FR uniquement** : Générer la langue source (FR). EN/IT/DE sont déférés.

> **Screenshots:** Chemins conventionnels `/assets/docs/{module}/step-{N}.png`.
> Le renderer affiche un placeholder "Screenshot à venir" si l'image n'existe pas.

---

## Legacy: Template TSX Complet (référence)

> **Déprécié:** Conservé pour référence. Utilisez l'approche data-driven ci-dessus.

```tsx
// web/smartstack-web/src/pages/docs/user/{ModuleName}DocPage.tsx

import { Link } from 'react-router-dom';
import { useTranslation } from 'react-i18next';
import {
  ArrowRight,
  CheckCircle,
  XCircle,
  Lightbulb,
  Target,
  Clock,
  DollarSign,
  Users,
  TrendingUp,
  Zap,
  Quote,
  ArrowRightLeft
} from 'lucide-react';

export function {ModuleName}DocPage() {
  const { t } = useTranslation('docs');

  return (
    <div className="space-y-8">
      {/* HEADER avec proposition de valeur */}
      <div>
        <h1 className="text-3xl font-bold mb-4 flex items-center gap-3">
          <ModuleIcon className="w-8 h-8 text-[var(--color-primary-600)]" />
          {t('{module}.title')}
        </h1>
        {/* PROPOSITION DE VALEUR - 1 phrase percutante */}
        <p className="text-xl text-[var(--color-primary-600)] font-medium mb-2">
          {t('{module}.valueProposition')}
        </p>
        <p className="text-lg text-[var(--text-secondary)]">
          {t('{module}.subtitle')}
        </p>
      </div>

      {/* ══════════════════════════════════════════════════════════════════ */}
      {/* SECTION 1: VALEUR METIER - Pourquoi ca existe ?                   */}
      {/* ══════════════════════════════════════════════════════════════════ */}
      <section id="valeur" className="scroll-mt-4">
        <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">1</span>
          Pourquoi ce module ?
        </h2>

        <div className="card p-6">
          {/* Probleme resolu */}
          <div className="mb-6">
            <h3 className="font-semibold mb-3 flex items-center gap-2">
              <Target className="w-5 h-5 text-red-500" />
              Le probleme que nous resolvons
            </h3>
            <p className="text-[var(--text-secondary)]">
              {t('{module}.problem')}
            </p>
          </div>

          {/* Solution apportee */}
          <div className="p-4 rounded-lg bg-green-500/10 border border-green-500/20">
            <h3 className="font-semibold mb-2 flex items-center gap-2 text-green-700">
              <Lightbulb className="w-5 h-5" />
              Notre solution
            </h3>
            <p className="text-[var(--text-secondary)]">
              {t('{module}.solution')}
            </p>
          </div>
        </div>
      </section>

      {/* ══════════════════════════════════════════════════════════════════ */}
      {/* SECTION 2: CAS D'USAGE - Exemples concrets                        */}
      {/* ══════════════════════════════════════════════════════════════════ */}
      <section id="cas-usage" className="scroll-mt-4">
        <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">2</span>
          Exemples d'utilisation
        </h2>

        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
          {/* Cas d'usage 1 - avec persona */}
          <div className="card p-6">
            <div className="flex items-center gap-3 mb-4">
              <div className="w-12 h-12 rounded-full bg-blue-500/10 flex items-center justify-center">
                <Users className="w-6 h-6 text-blue-600" />
              </div>
              <div>
                <div className="font-semibold">{t('{module}.useCases.1.persona')}</div>
                <div className="text-sm text-[var(--text-secondary)]">{t('{module}.useCases.1.role')}</div>
              </div>
            </div>
            <div className="space-y-3">
              <div className="text-sm">
                <span className="font-medium text-[var(--text-secondary)]">Situation:</span>
                <p>{t('{module}.useCases.1.situation')}</p>
              </div>
              <div className="text-sm">
                <span className="font-medium text-green-600">Avec {t('{module}.title')}:</span>
                <p>{t('{module}.useCases.1.withFeature')}</p>
              </div>
            </div>
          </div>

          {/* Cas d'usage 2 */}
          <div className="card p-6">
            <div className="flex items-center gap-3 mb-4">
              <div className="w-12 h-12 rounded-full bg-purple-500/10 flex items-center justify-center">
                <Users className="w-6 h-6 text-purple-600" />
              </div>
              <div>
                <div className="font-semibold">{t('{module}.useCases.2.persona')}</div>
                <div className="text-sm text-[var(--text-secondary)]">{t('{module}.useCases.2.role')}</div>
              </div>
            </div>
            <div className="space-y-3">
              <div className="text-sm">
                <span className="font-medium text-[var(--text-secondary)]">Situation:</span>
                <p>{t('{module}.useCases.2.situation')}</p>
              </div>
              <div className="text-sm">
                <span className="font-medium text-green-600">Avec {t('{module}.title')}:</span>
                <p>{t('{module}.useCases.2.withFeature')}</p>
              </div>
            </div>
          </div>
        </div>
      </section>

      {/* ══════════════════════════════════════════════════════════════════ */}
      {/* SECTION 3: BENEFICES MESURABLES                                   */}
      {/* ══════════════════════════════════════════════════════════════════ */}
      <section id="benefices" className="scroll-mt-4">
        <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">3</span>
          Benefices concrets
        </h2>

        <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
          {/* Benefice 1: Gain de temps */}
          <div className="card p-6 text-center">
            <div className="w-16 h-16 mx-auto mb-4 rounded-full bg-blue-500/10 flex items-center justify-center">
              <Clock className="w-8 h-8 text-blue-600" />
            </div>
            <div className="text-3xl font-bold text-blue-600 mb-2">-70%</div>
            <div className="font-semibold mb-1">Temps economise</div>
            <p className="text-sm text-[var(--text-secondary)]">
              {t('{module}.benefits.time.description')}
            </p>
          </div>

          {/* Benefice 2: Reduction des erreurs */}
          <div className="card p-6 text-center">
            <div className="w-16 h-16 mx-auto mb-4 rounded-full bg-green-500/10 flex items-center justify-center">
              <TrendingUp className="w-8 h-8 text-green-600" />
            </div>
            <div className="text-3xl font-bold text-green-600 mb-2">+95%</div>
            <div className="font-semibold mb-1">Fiabilite</div>
            <p className="text-sm text-[var(--text-secondary)]">
              {t('{module}.benefits.quality.description')}
            </p>
          </div>

          {/* Benefice 3: ROI */}
          <div className="card p-6 text-center">
            <div className="w-16 h-16 mx-auto mb-4 rounded-full bg-amber-500/10 flex items-center justify-center">
              <DollarSign className="w-8 h-8 text-amber-600" />
            </div>
            <div className="text-3xl font-bold text-amber-600 mb-2">3x</div>
            <div className="font-semibold mb-1">Retour sur investissement</div>
            <p className="text-sm text-[var(--text-secondary)]">
              {t('{module}.benefits.roi.description')}
            </p>
          </div>
        </div>
      </section>

      {/* ══════════════════════════════════════════════════════════════════ */}
      {/* SECTION 4: AVANT/APRES - Comparaison visuelle                     */}
      {/* ══════════════════════════════════════════════════════════════════ */}
      <section id="avant-apres" className="scroll-mt-4">
        <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">4</span>
          Avant / Apres
        </h2>

        <div className="card p-6">
          <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
            {/* AVANT */}
            <div className="p-4 rounded-lg bg-red-500/5 border border-red-500/20">
              <h3 className="font-semibold mb-4 flex items-center gap-2 text-red-600">
                <XCircle className="w-5 h-5" />
                Avant: Sans {t('{module}.title')}
              </h3>
              <ul className="space-y-2">
                {[1, 2, 3, 4].map((i) => (
                  <li key={i} className="flex items-start gap-2 text-sm">
                    <XCircle className="w-4 h-4 text-red-500 mt-0.5 flex-shrink-0" />
                    <span>{t(`{module}.before.${i}`)}</span>
                  </li>
                ))}
              </ul>
            </div>

            {/* APRES */}
            <div className="p-4 rounded-lg bg-green-500/5 border border-green-500/20">
              <h3 className="font-semibold mb-4 flex items-center gap-2 text-green-600">
                <CheckCircle className="w-5 h-5" />
                Apres: Avec {t('{module}.title')}
              </h3>
              <ul className="space-y-2">
                {[1, 2, 3, 4].map((i) => (
                  <li key={i} className="flex items-start gap-2 text-sm">
                    <CheckCircle className="w-4 h-4 text-green-500 mt-0.5 flex-shrink-0" />
                    <span>{t(`{module}.after.${i}`)}</span>
                  </li>
                ))}
              </ul>
            </div>
          </div>
        </div>
      </section>

      {/* ══════════════════════════════════════════════════════════════════ */}
      {/* SECTION 5: FONCTIONNALITES DETAILLEES                             */}
      {/* ══════════════════════════════════════════════════════════════════ */}
      <section id="fonctionnalites" className="scroll-mt-4">
        <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">5</span>
          Ce que vous pouvez faire
        </h2>

        <div className="space-y-4">
          {/* Feature Card avec exemple */}
          <div className="card p-6">
            <div className="flex items-start gap-4">
              <div className="w-12 h-12 rounded-lg bg-[var(--color-primary-600)]/10 flex items-center justify-center flex-shrink-0">
                <Zap className="w-6 h-6 text-[var(--color-primary-600)]" />
              </div>
              <div className="flex-1">
                <h3 className="font-semibold mb-2">{t('{module}.features.1.title')}</h3>
                <p className="text-[var(--text-secondary)] mb-3">
                  {t('{module}.features.1.description')}
                </p>
                {/* Exemple concret */}
                <div className="p-3 rounded-lg bg-[var(--bg-secondary)] text-sm">
                  <span className="font-medium text-[var(--color-primary-600)]">Exemple: </span>
                  {t('{module}.features.1.example')}
                </div>
              </div>
            </div>
          </div>

          {/* Repeter pour chaque fonctionnalite */}
        </div>
      </section>

      {/* ══════════════════════════════════════════════════════════════════ */}
      {/* SECTION 6: COMMENT CA MARCHE - Guide pas a pas                    */}
      {/* ══════════════════════════════════════════════════════════════════ */}
      <section id="guide" className="scroll-mt-4">
        <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">6</span>
          Comment demarrer
        </h2>

        <div className="card p-6">
          <div className="space-y-6">
            {/* Etape 1 */}
            <div className="flex gap-4">
              <div className="flex flex-col items-center">
                <div className="w-10 h-10 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center font-bold">
                  1
                </div>
                <div className="w-0.5 h-full bg-[var(--border-color)] mt-2"></div>
              </div>
              <div className="flex-1 pb-6">
                <h4 className="font-semibold mb-2">{t('{module}.steps.1.title')}</h4>
                <p className="text-sm text-[var(--text-secondary)] mb-3">
                  {t('{module}.steps.1.description')}
                </p>
                {/* Screenshot ou illustration */}
                <div className="p-4 rounded-lg bg-[var(--bg-secondary)] border-2 border-dashed border-[var(--border-color)] text-center text-sm text-[var(--text-tertiary)]">
                  [Capture d'ecran de l'etape 1]
                </div>
              </div>
            </div>

            {/* Repeter pour chaque etape */}
          </div>
        </div>
      </section>

      {/* ══════════════════════════════════════════════════════════════════ */}
      {/* SECTION 7: FAQ METIER                                             */}
      {/* ══════════════════════════════════════════════════════════════════ */}
      <section id="faq" className="scroll-mt-4">
        <h2 className="text-2xl font-bold mb-4 flex items-center gap-2">
          <span className="w-8 h-8 rounded-full bg-[var(--color-primary-600)] text-white flex items-center justify-center text-sm">7</span>
          Questions frequentes
        </h2>

        <div className="space-y-4">
          {/* Question metier, pas technique */}
          <div className="card p-4">
            <h3 className="font-medium mb-2">
              {t('{module}.faq.1.question')}
            </h3>
            <p className="text-sm text-[var(--text-secondary)]">
              {t('{module}.faq.1.answer')}
            </p>
          </div>
        </div>
      </section>

      {/* ══════════════════════════════════════════════════════════════════ */}
      {/* SECTION 8: REFERENCE TECHNIQUE (optionnel, pour admins)           */}
      {/* ══════════════════════════════════════════════════════════════════ */}
      <section id="reference" className="scroll-mt-4">
        <details className="card">
          <summary className="p-4 cursor-pointer hover:bg-[var(--bg-secondary)] rounded-lg font-semibold flex items-center gap-2">
            <span className="w-8 h-8 rounded-full bg-gray-500/10 text-gray-600 flex items-center justify-center text-sm">8</span>
            Reference technique (administrateurs)
          </summary>
          <div className="p-4 pt-0">
            {/* Permissions, API, etc. */}
          </div>
        </details>
      </section>

      {/* NAVIGATION */}
      <div className="flex justify-between pt-6 border-t border-[var(--border-color)]">
        <Link to="/docs/user/previous" className="flex items-center gap-2 text-[var(--text-secondary)] hover:text-[var(--color-primary-600)]">
          <ArrowRight className="w-4 h-4 rotate-180" />
          Module precedent
        </Link>
        <Link to="/docs/user/next" className="flex items-center gap-2 text-[var(--color-primary-600)]">
          Module suivant
          <ArrowRight className="w-4 h-4" />
        </Link>
      </div>
    </div>
  );
}
```

---

## Structure i18n (Business-First)

```json
{
  "{module}": {
    "title": "Nom du module",
    "valueProposition": "Une phrase qui resume la valeur (ex: 'Gerez vos prompts IA sans ecrire une ligne de code')",
    "subtitle": "Description en 1-2 phrases",

    "problem": "Description du probleme que vos utilisateurs rencontrent AVANT d'avoir cette fonctionnalite",
    "solution": "Comment ce module resout ce probleme de maniere simple",

    "useCases": {
      "1": {
        "persona": "Marie",
        "role": "Responsable RH",
        "situation": "Marie doit envoyer 50 emails personnalises aux candidats chaque semaine",
        "withFeature": "Elle selectionne un template, importe sa liste, et envoie tout en 2 clics"
      },
      "2": {
        "persona": "Thomas",
        "role": "Directeur Commercial",
        "situation": "Thomas veut suivre les performances de son equipe en temps reel",
        "withFeature": "Il consulte le dashboard qui affiche les KPIs automatiquement"
      }
    },

    "benefits": {
      "time": { "value": "-70%", "description": "Reduction du temps passe sur les taches repetitives" },
      "quality": { "value": "+95%", "description": "Moins d'erreurs grace a l'automatisation" },
      "roi": { "value": "3x", "description": "Rentabilise en moins de 3 mois" }
    },

    "before": {
      "1": "Processus manuel et chronophage",
      "2": "Risque d'erreurs humaines eleve",
      "3": "Pas de visibilite sur les performances",
      "4": "Donnees eparpillees dans plusieurs outils"
    },

    "after": {
      "1": "Automatisation des taches repetitives",
      "2": "Validation automatique des donnees",
      "3": "Tableaux de bord en temps reel",
      "4": "Centralisation de toutes les informations"
    },

    "features": {
      "1": {
        "title": "Nom de la fonctionnalite",
        "description": "Explication claire de ce que fait cette fonctionnalite",
        "example": "Par exemple, vous pouvez creer un prompt 'Reponse Support' qui sera utilise automatiquement pour tous les tickets entrants"
      }
    },

    "steps": {
      "1": {
        "title": "Accedez au module",
        "description": "Depuis le menu principal, cliquez sur 'Administration' puis 'Intelligence Artificielle'"
      }
    },

    "faq": {
      "1": {
        "question": "Dois-je etre technique pour utiliser ce module ?",
        "answer": "Non, l'interface est concue pour etre utilisee par tous. Aucune connaissance en programmation n'est requise."
      },
      "2": {
        "question": "Combien de temps faut-il pour le mettre en place ?",
        "answer": "La configuration initiale prend environ 15 minutes. Vous pouvez commencer a utiliser le module immediatement apres."
      }
    }
  }
}
```

---

## Checklist Documentation Business-First

Avant de valider une documentation, verifier:

- [ ] **Proposition de valeur** claire en 1 phrase
- [ ] **Probleme** decrit du point de vue utilisateur (pas technique)
- [ ] **2-3 cas d'usage** avec personas nommes
- [ ] **Benefices chiffres** (%, temps, argent)
- [ ] **Avant/Apres** visuel
- [ ] **Exemples concrets** pour chaque fonctionnalite
- [ ] **Guide pas a pas** avec captures d'ecran
- [ ] **FAQ metier** (pas technique)
- [ ] **Reference technique** en section repliable (optionnelle)

---

## Templates Techniques (inchanges)

Les templates pour `developer`, `database`, et `testing` restent techniques car leur public est developpeur.

(voir le contenu precedent pour ces templates)
