---
name: application
description: |
  Crée des applications/modules SmartStack full-stack.
  Utiliser ce skill quand:
  - L'utilisateur demande de créer une application, un module, ou un context
  - L'utilisateur mentionne "nouveau module", "nouvelle application", "ajouter une fonctionnalité"
  - L'utilisateur veut étendre la navigation avec de nouvelles entrées
  Scope: Context → Application → Module → Section (tous niveaux)
---

## STRATÉGIE MODÈLES

| Phase | Modèle | Coût estimé |
|-------|--------|-------------|
| Analyse & Planning | **Opus** | ~$0.15 |
| Génération code | **Sonnet** | ~$0.25 |
| Validation architecture | **Opus** | ~$0.10 |
| **Total** | | **~$0.50** |

---

# Skill Application SmartStack

> **Synergie Skill/Commande:**
> - **Skill** (`.claude/skills/application/`) → Invocation automatique par Claude
> - **Commande** (`/application:create`) → Invocation manuelle par l'utilisateur
> - Templates partagés dans `.claude/skills/application/templates-*.md`

## QUAND CE SKILL S'ACTIVE

Claude invoque automatiquement ce skill quand il détecte :

| Déclencheur | Exemple |
|-------------|---------|
| Demande explicite | "Crée un module pour gérer les produits" |
| Nouvelle fonctionnalité | "Il faut ajouter la gestion des commandes" |
| Extension navigation | "Ajoute une application CRM dans business" |
| Mots-clés | "nouveau module", "nouvelle application", "ajouter un context" |

---

## ARCHITECTURE EN COUCHES (OBLIGATOIRE)

```
┌─────────────────────────────────────────────────────────────────┐
│                    ARCHITECTURE SMARTSTACK                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐                                               │
│  │   WEB (React) │ ← Pages, Components, Hooks, i18n             │
│  └──────┬───────┘                                               │
│         │ HTTP (API calls via apiClient)                        │
│         ▼                                                        │
│  ┌──────────────┐                                               │
│  │   API (.NET)  │ ← Controllers, DTOs, Validation              │
│  └──────┬───────┘                                               │
│         │ DI (Services)                                          │
│         ▼                                                        │
│  ┌──────────────┐                                               │
│  │  Application  │ ← Interfaces, Models, Commands/Queries       │
│  └──────┬───────┘                                               │
│         │ DI (Implementations)                                   │
│         ▼                                                        │
│  ┌──────────────┐                                               │
│  │Infrastructure │ ← EF Core, Services, Configurations          │
│  └──────┬───────┘                                               │
│         │ EF Core                                                │
│         ▼                                                        │
│  ┌──────────────┐                                               │
│  │   Database    │ ← SQL Server (schemas: nav, auth, usr, etc.) │
│  └──────────────┘                                               │
│                                                                  │
│  ❌ INTERDIT: WEB → Infrastructure (accès DB direct)            │
│  ❌ INTERDIT: WEB → Domain (manipulation directe)               │
│  ✅ OBLIGATOIRE: WEB → API → Application → Infrastructure      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### Validation Architecture Active

Le skill **DOIT** vérifier que le code généré ne viole pas l'architecture :
- Aucun import de `SmartStack.Infrastructure` dans les fichiers React
- Aucun appel SQL direct depuis le frontend
- Tous les appels API passent par `apiClient`

---

## WORKFLOW AUTOMATIQUE

### ÉTAPE 1: DÉTECTION DU NIVEAU

| Indice | → Niveau |
|--------|----------|
| "context", "espace", "workspace" | Context |
| "application", "app", "module principal" | Application |
| "module", "fonctionnalité", "page" | Module |
| "section", "sous-menu", "onglet" | Section |

### ÉTAPE 2: EXTRACTION DES PARAMÈTRES

| Paramètre | Source | Exemple |
|-----------|--------|---------|
| `$LEVEL` | Détection | `context`, `application`, `module`, `section` |
| `$PARENT` | Context existant | `platform`, `business`, `personal` |
| `$CODE` | Nom kebab-case | `products`, `order-management` |
| `$LABEL_FR` | Libellé français | `Produits`, `Gestion des commandes` |
| `$ICON` | Icône Lucide | `Package`, `ShoppingCart` |

### ÉTAPE 3: GÉNÉRATION FULL-STACK

```
POUR chaque niveau créé:
  1. DB SEED (Navigation + Translations 4 langues)
  2. PERMISSIONS - 2 FICHIERS OBLIGATOIRES:
     a. Permissions.cs (constantes C#)
     b. PermissionConfiguration.cs (seed data DB - HasData)
  3. API (Controller + DTOs via /controller:create)
  4. SERVICES (Interface + Implementation)
  5. FRONTEND (Page + Components + Hooks)
  6. I18N (4 fichiers JSON: fr, en, it, de)
  7. ROUTES (App.tsx - routes imbriquées obligatoires)
  8. PREFERENCES (Template complet)
  9. MIGRATION (via /efcore:migration)
  10. TESTS (via /controller:create)
```

> ⚠️ **ATTENTION:** L'étape 2 (PERMISSIONS) requiert la modification de 2 fichiers.
> Si PermissionConfiguration.cs n'est pas mis à jour, les permissions n'existeront pas en base de données !

### ÉTAPE 4: CHAÎNAGE AUTOMATIQUE

Le skill appelle automatiquement :
- `/controller:create` pour les controllers API
- `/efcore:migration` pour les migrations DB
- `/ui-components` pour les pages avec listes/grilles (EntityCard, DataTable)

### ⚠️ RÈGLE UI-COMPONENTS (OBLIGATOIRE)

Lors de la création de pages avec affichage d'entités :
1. **TOUJOURS** utiliser `EntityCard` pour les cards d'entités
2. **TOUJOURS** utiliser `DataTable` pour les tableaux
3. **JAMAIS** créer de cards manuelles avec des divs

Voir le skill `/ui-components` pour les patterns détaillés.

---

## PRÉFÉRENCES UTILISATEUR (OBLIGATOIRE)

Chaque module **DOIT** implémenter le template complet de préférences :

| Préférence | Description | Stockage |
|------------|-------------|----------|
| `pageSize` | Taille de page par défaut | `user.preferences.{module}.pageSize` |
| `sortColumn` | Colonne de tri par défaut | `user.preferences.{module}.sortColumn` |
| `sortDirection` | Direction du tri (asc/desc) | `user.preferences.{module}.sortDirection` |
| `filters` | Filtres actifs par défaut | `user.preferences.{module}.filters` |
| `visibleColumns` | Colonnes affichées | `user.preferences.{module}.visibleColumns` |
| `viewMode` | Mode d'affichage (list/grid) | `user.preferences.{module}.viewMode` |

### Hook Pattern

```typescript
// hooks/use{Module}Preferences.ts
export function use{Module}Preferences() {
  const { preferences, updatePreference } = useUserPreferences();

  return {
    pageSize: preferences.{module}?.pageSize ?? 10,
    sortColumn: preferences.{module}?.sortColumn ?? 'createdAt',
    sortDirection: preferences.{module}?.sortDirection ?? 'desc',
    filters: preferences.{module}?.filters ?? {},
    visibleColumns: preferences.{module}?.visibleColumns ?? DEFAULT_COLUMNS,
    viewMode: preferences.{module}?.viewMode ?? 'list',

    setPageSize: (size: number) => updatePreference('{module}.pageSize', size),
    setSortColumn: (col: string) => updatePreference('{module}.sortColumn', col),
    // ... autres setters
  };
}
```

---

## TRADUCTIONS (4 LANGUES OBLIGATOIRES)

### Base de données (nav.Translations)

```csharp
// Pour CHAQUE entité créée (Context, Application, Module, Section)
translations.Add(new {
    Id = GenerateGuid(index++),
    EntityType = NavigationEntityType.Module,
    EntityId = moduleId,
    LanguageCode = "fr",
    Label = "Produits",
    Description = "Gestion des produits",
    CreatedAt = seedDate
});
translations.Add(new { /* ... en */ });
translations.Add(new { /* ... it */ });
translations.Add(new { /* ... de */ });
```

### Frontend (i18n)

```
web/smartstack-web/src/i18n/locales/
├── fr/{module}.json
├── en/{module}.json
├── it/{module}.json
└── de/{module}.json
```

---

## COMPOSANTS RÉUTILISABLES

Emplacement : `components/common/`

| Type | Pattern | Exemple |
|------|---------|---------|
| Liste avec pagination | `{Module}ListView` | `ProductsListView` |
| Formulaire CRUD | `{Module}Form` | `ProductForm` |
| Détail | `{Module}Detail` | `ProductDetail` |
| Filtres | `{Module}Filters` | `ProductFilters` |

---

## PERMISSIONS (2 FICHIERS OBLIGATOIRES)

### ⚠️ RÈGLE CRITIQUE: DOUBLE ENREGISTREMENT DES PERMISSIONS

Les permissions doivent être ajoutées dans **2 fichiers distincts** :

| Fichier | Contenu | Obligatoire |
|---------|---------|-------------|
| `Permissions.cs` | Constantes C# | ✅ OUI |
| `PermissionConfiguration.cs` | Seed data DB (HasData) | ✅ OUI |

**Si l'un des deux manque, les permissions ne fonctionneront pas !**

### Fichier 1: Permissions.cs (Application Layer)

```csharp
// src/SmartStack.Application/Common/Authorization/Permissions.cs

public static class Business
{
    public static class $APPLICATION_PASCAL
    {
        public const string Access = "$CONTEXT.$APPLICATION";

        public static class $MODULE_PASCAL
        {
            public const string View = "$CONTEXT.$APPLICATION.$MODULE.read";
            public const string Create = "$CONTEXT.$APPLICATION.$MODULE.create";
            public const string Update = "$CONTEXT.$APPLICATION.$MODULE.update";
            public const string Delete = "$CONTEXT.$APPLICATION.$MODULE.delete";
            public const string Execute = "$CONTEXT.$APPLICATION.$MODULE.execute"; // Si workflow
        }
    }
}
```

### Fichier 2: PermissionConfiguration.cs (Infrastructure Layer)

```csharp
// src/SmartStack.Infrastructure/Persistence/Configurations/Navigation/PermissionConfiguration.cs
// Dans la méthode GetSeedData()

// Déclarer les IDs (doivent correspondre à NavigationModuleConfiguration.cs)
var $moduleModuleId = Guid.Parse("$MODULE_GUID");

// Ajouter dans le tableau de permissions:

// Wildcard Module
new {
    Id = Guid.Parse("$PERM_WILDCARD_GUID"),
    Path = "$CONTEXT.$APPLICATION.$MODULE.*",
    Level = PermissionLevel.Module,
    IsWildcard = true,
    ModuleId = $moduleModuleId,
    Description = "Full $MODULE_LABEL access",
    CreatedAt = seedDate
},
// CRUD Actions
new {
    Id = Guid.Parse("$PERM_READ_GUID"),
    Path = "$CONTEXT.$APPLICATION.$MODULE.read",
    Level = PermissionLevel.Module,
    Action = PermissionAction.Read,
    IsWildcard = false,
    ModuleId = $moduleModuleId,
    Description = "View $MODULE_LABEL",
    CreatedAt = seedDate
},
// ... create, update, delete, execute
```

### Checklist Permissions

| Vérification | Status |
|--------------|--------|
| ☐ Constantes dans Permissions.cs | |
| ☐ Seed data dans PermissionConfiguration.cs | |
| ☐ Module ID correspond à NavigationModuleConfiguration | |
| ☐ GUIDs aléatoires (pas séquentiels) | |
| ☐ Wildcard + actions CRUD | |

---

## VALIDATION FINALE

### Build + Lint + Tests

```bash
# Backend
dotnet build
dotnet test

# Frontend
cd web/smartstack-web
npm run build
npm run lint
npm run test
```

### Checklist Automatique

| Vérification | Commande |
|--------------|----------|
| ✅ Compilation backend | `dotnet build` |
| ✅ Compilation frontend | `npm run build` |
| ✅ Lint TypeScript | `npm run lint` |
| ✅ Tests unitaires | `npm run test` |
| ✅ Architecture valide | Analyse imports |
| ✅ 4 langues i18n | Vérification fichiers |
| ✅ Préférences impl. | Vérification hook |
| ✅ Permissions.cs | Constantes ajoutées |
| ✅ PermissionConfiguration.cs | Seed data ajouté |
| ✅ Routes imbriquées | Pas de flat siblings |
| ✅ EntityCard utilisé | Pas de divs manuels |

---

## FICHIERS ASSOCIÉS

- **Templates Backend:** [templates-backend.md](templates-backend.md)
- **Templates Frontend:** [templates-frontend.md](templates-frontend.md)
- **Templates i18n:** [templates-i18n.md](templates-i18n.md)
- **Templates DB Seed:** [templates-seed.md](templates-seed.md)
- **Commande:** `.claude/commands/application-create.md`

---

## RÈGLES ABSOLUES

1. **TOUJOURS** 4 langues (FR, EN, IT, DE) - jamais moins
2. **TOUJOURS** respecter l'architecture en couches
3. **TOUJOURS** implémenter les préférences utilisateur
4. **TOUJOURS** utiliser `apiClient` pour les appels API
5. **TOUJOURS** chaîner avec `/controller:create` et `/efcore:migration`
6. **TOUJOURS** utiliser des routes imbriquées (nested routes) - voir templates-frontend.md
7. **TOUJOURS** utiliser `EntityCard` pour les cards d'entités - voir `/ui-components`
8. **TOUJOURS** utiliser `DataTable` pour les tableaux de données - voir `/ui-components`
9. **JAMAIS** d'import Infrastructure dans le frontend
10. **JAMAIS** de SQL direct dans le code frontend
11. **JAMAIS** de GUIDs séquentiels - utiliser `GenerateGuid(index)`
12. **JAMAIS** de routes plates (flat siblings) pour les applications multi-modules
13. **JAMAIS** de cards manuelles avec divs (utiliser EntityCard)
14. **TOUJOURS** ajouter les permissions dans Permissions.cs ET PermissionConfiguration.cs (2 fichiers)
15. **JAMAIS** oublier le seed data des permissions dans PermissionConfiguration.cs

---

## ROUTING (CRITIQUE - REACT ROUTER V7)

### Pattern obligatoire pour les applications multi-modules

```tsx
// ✅ CORRECT - Routes imbriquées avec index
<Route path="$APPLICATION">
  <Route index element={<Navigate to="$DEFAULT_MODULE" replace />} />
  <Route path="$MODULE1" element={<Module1Page />} />
  <Route path="$MODULE2" element={<Module2Page />} />
</Route>

// ❌ INTERDIT - Routes plates (causent des redirections vers Home)
<Route path="$APPLICATION" element={<Navigate to="..." replace />} />
<Route path="$APPLICATION/$MODULE1" element={<Module1Page />} />
```

### Raisons techniques

| Problème routes plates | Impact |
|------------------------|--------|
| Matching ambigu | React Router peut matcher la mauvaise route |
| Navigate absolu | Peut échouer si le contexte de route est mal résolu |
| Pas d'Outlet | Impossible d'avoir des layouts partagés |
| Redirect vers Home | Bug fréquent quand le matching échoue |

---

## INTEGRATIONS SMARTSTACK

### Skills Complementaires

Ce skill s'integre avec les skills suivants pour une experience complete :

| Skill | Quand l'utiliser | Action |
|-------|------------------|--------|
| `/notification` | Module avec alertes utilisateur | Notifications in-app + SignalR |
| `/workflow` | Module avec emails automatiques | Workflows + Email templates |
| `/ai-prompt` | Module avec assistance IA | Prompts + Validation schema |
| `/feature-full` | Feature complete oneshot | Orchestration de tous les skills |

### Integration Notifications

Quand le module necessite des notifications :

```csharp
// Dans le service, injecter INotificationService
public class {Module}Service : I{Module}Service
{
    private readonly INotificationService _notificationService;

    public async Task<{Entity}Dto> CreateAsync(...)
    {
        // ... creation ...

        // Notification
        await _notificationService.SendNotificationAsync(
            _currentUser.Id,
            NotificationType.{Entity}Created,
            "{Entity} creee",
            $"{entity.Name} a ete cree avec succes",
            relatedEntityType: nameof({Entity}),
            relatedEntityId: entity.Id,
            actionUrl: $"/{module}/{entity.Id}");

        return result;
    }
}
```

```typescript
// Dans le hook frontend, ajouter SignalR
import { useSignalR } from '@/hooks/useSignalR';

export function use{Module}() {
  const queryClient = useQueryClient();

  useSignalR({
    onNotification: (notification) => {
      if (notification.relatedEntityType === '{Entity}') {
        queryClient.invalidateQueries(['{module}']);
        toast.info(notification.title);
      }
    },
  });
}
```

### Integration Workflows

Quand le module necessite des emails automatiques :

```csharp
// Dans le service, injecter IWorkflowService
public class {Module}Service : I{Module}Service
{
    private readonly IWorkflowService _workflowService;

    public async Task<{Entity}Dto> CreateAsync(...)
    {
        // ... creation ...

        // Declencher workflow email
        await _workflowService.TriggerAsync(
            "{entity}.created",
            new Dictionary<string, object>
            {
                ["entityId"] = entity.Id,
                ["entityName"] = entity.Name,
                ["creatorEmail"] = _currentUser.Email
            });

        return result;
    }
}
```

### Integration IA

Quand le module necessite une assistance IA :

```csharp
// Dans le service, injecter IAiCompletionService
public class {Module}Service : I{Module}Service
{
    private readonly IAiCompletionService _aiService;

    public async Task<{Entity}AnalysisResult?> AnalyzeAsync(Guid id, CancellationToken ct)
    {
        var entity = await _context.{Entity}s.FindAsync(id);

        var result = await _aiService
            .ExecutePromptByCodeWithValidationAsync<{Entity}AnalysisResult>(
                "{entity}-analyzer",
                new Dictionary<string, object>
                {
                    ["entityName"] = entity.Name,
                    ["entityDescription"] = entity.Description ?? ""
                },
                cancellationToken: ct);

        return result.Success && result.IsValid ? result.Data : null;
    }
}
```

### Checklist Integrations

```
□ Module necessite des notifications ?
  □ Ajouter NotificationType dans l'enum
  □ Injecter INotificationService
  □ Envoyer notifications aux moments cles
  □ Ajouter useSignalR dans le hook frontend

□ Module necessite des emails automatiques ?
  □ Creer le trigger (WorkflowTriggerConfiguration.cs)
  □ Creer le workflow (WorkflowConfiguration.cs)
  □ Creer le template email
  □ Injecter IWorkflowService
  □ Declencher avec TriggerAsync

□ Module necessite une assistance IA ?
  □ Creer le prompt (via /ai-prompt)
  □ Creer le schema de validation
  □ Injecter IAiCompletionService
  □ Appeler ExecutePromptAsync
  □ Ajouter bouton IA dans le frontend
```

---

## SKILLS ET COMMANDES ASSOCIES

| Type | Nom | Usage |
|------|-----|-------|
| Skill | `/application` | Creation module (ce skill) |
| Skill | `/controller` | Generation controller API |
| Skill | `/ui-components` | Composants UI (EntityCard, DataTable) |
| Skill | `/notification` | Integration notifications |
| Skill | `/workflow` | Integration workflows/emails |
| Skill | `/ai-prompt` | Integration IA |
| Skill | `/feature-full` | Feature complete oneshot |
| Commande | `/efcore:migration` | Migration EF Core |
| Commande | `/efcore:db-deploy` | Deploiement migrations |
