---
description: Phase 6 - Development prompt generation (ULTRATHINK)
agent: ba-handoff
model: opus
---

# Phase 6: Handoff Développement

> **Modèle:** OPUS (génération prompt one-shot, zéro ambiguïté)
> **Coût estimé:** ~$0.35 (one-shot) / ~$1.00-2.50 (avec ralph-loop)
> **Prérequis:** validation.json avec status "APPROVED"

---

## RALPH-LOOP INTEGRATION (OPTIONNEL)

```
╔══════════════════════════════════════════════════════════════════════════════╗
║  UTILISATION AVEC RALPH-LOOP POUR GARANTIE DE COMPLÉTUDE                     ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                                                                              ║
║  /ralph-loop "/business-analyse:6-handoff FEAT-XXX"                          ║
║              --completion-promise "COMPLETE" --max-iterations 10             ║
║                                                                              ║
║  FICHIERS RALPH (créés automatiquement):                                     ║
║  ├── prd.json        → Sections du handoff avec statut                       ║
║  └── progress.txt    → Mémoire des sections générées                         ║
║                                                                              ║
║  PROCESSUS PAR ITERATION:                                                    ║
║  1. Lire prd.json → Trouver prochaine section "passes": false                ║
║  2. Lire progress.txt → Voir sections déjà générées                          ║
║  3. Générer UNE section du handoff                                           ║
║  4. Mettre à jour 4-development-handoff.md                                   ║
║  5. Mettre à jour prd.json → "passes": true                                  ║
║  6. Ajouter résumé section à progress.txt                                    ║
║  7. Si TOUTES sections "passes": true → <promise>COMPLETE</promise>          ║
║                                                                              ║
║  SIGNAL DE FIN: <promise>COMPLETE</promise>                                  ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
```

### Structure prd.json pour Handoff

```json
{
  "feature_id": "FEAT-XXX",
  "phase": "handoff",
  "userStories": [
    { "id": "1", "title": "Section 1: Header et Contexte", "passes": false },
    { "id": "2", "title": "Section 2: Entités Domain", "passes": false },
    { "id": "3", "title": "Section 3: Configuration EF Core", "passes": false },
    { "id": "4", "title": "Section 4: Commands/Queries Application", "passes": false },
    { "id": "5", "title": "Section 5: Endpoints API avec permissions", "passes": false },
    { "id": "6", "title": "Section 6: Service API Frontend", "passes": false },
    { "id": "7", "title": "Section 7: Pages Frontend", "passes": false },
    { "id": "8", "title": "Section 8: i18n (4 langues)", "passes": false },
    { "id": "9", "title": "Section 9: Intégrations SmartStack", "passes": false },
    { "id": "10", "title": "Section 10: Checklist validation", "passes": false },
    { "id": "11", "title": "Validation: aucun TBD/? restant", "passes": false }
  ]
}
```

---

## OBJECTIF

```
╔══════════════════════════════════════════════════════════════════════════════╗
║  GÉNÉRER UN PROMPT AUTONOME POUR IMPLÉMENTATION ONE-SHOT                     ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                                                                              ║
║  Le handoff est un document AUTONOME qui permet au développeur Claude        ║
║  d'implémenter la feature SANS poser de questions.                           ║
║                                                                              ║
║  EXIGENCES:                                                                  ║
║  • Zéro ambiguïté sur les spécifications                                     ║
║  • Instructions EXPLORE pour découvrir les patterns existants                ║
║  • Checklist complète de validation                                          ║
║  • Permissions explicites avec paths complets                                ║
║                                                                              ║
║  USAGE: /implement {FEATURE_ID}                                              ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
```

---

## STEP 1: Vérifier la validation

```bash
FEATURE_ID=$1
FEATURE_DIR=$(find .business-analyse -type d -name "${FEATURE_ID}*" | head -1)
VALIDATION_FILE="$FEATURE_DIR/validation.json"

if [ ! -f "$VALIDATION_FILE" ]; then
  echo "❌ ERREUR: validation.json non trouvé"
  echo "   Lancez d'abord: /business-analyse:5-validate $FEATURE_ID"
  exit 1
fi

# Vérifier le status
STATUS=$(grep -oP '"status":\s*"\K[^"]+' "$VALIDATION_FILE")

if [ "$STATUS" != "APPROVED" ]; then
  echo "❌ ERREUR: Validation non approuvée (status: $STATUS)"
  echo "   Les spécifications doivent être validées avant le handoff."
  exit 1
fi

echo "✅ Validation approuvée - Génération du handoff..."
```

---

## STEP 2: Charger tous les documents

```bash
DISCOVERY=$(cat "$FEATURE_DIR/1-discovery.md")
BRD=$(cat "$FEATURE_DIR/2-business-requirements.md")
FRD=$(cat "$FEATURE_DIR/3-functional-specification.md")

# Extraire les informations clés
APPLICATION=$(echo $FEATURE_DIR | grep -oP 'business/\K[^/]+')
MODULE=$(echo $FEATURE_DIR | grep -oP 'modules/\K[^/]+')
FEATURE_NAME=$(echo $FEATURE_DIR | grep -oP 'FEAT-\d+-\K.*')
```

---

## STEP 3: Génération du handoff

```bash
HANDOFF_FILE="$FEATURE_DIR/4-development-handoff.md"
```

### Template 4-development-handoff.md

```markdown
# Development Handoff - {FEATURE_ID} {Feature Name}

> **Module:** business/{application}/{module}
> **Version:** 1.0 (locked)
> **Specs validées:** FRD v1.0
> **Implémentation:** `/implement {FEATURE_ID}`

---

## INSTRUCTIONS DÉVELOPPEUR CLAUDE

Ce document est un **prompt autonome** pour Claude Code.
Exécutez la commande suivante pour implémenter cette feature:

```bash
/implement {FEATURE_ID}
```

**Options disponibles:**
- `--phase=1` : Backend seulement (Domain + Application + Infrastructure)
- `--phase=2` : Frontend seulement (Pages + Services + i18n)
- `--phase=3` : Tests seulement (Unit + Integration + Postman)
- `--phase=4` : Documentation HTML seulement

---

## 1. CONTEXTE RAPIDE

| Attribut | Valeur |
|----------|--------|
| Feature ID | {FEATURE_ID} |
| Module | business/{application}/{module} |
| Permission base | `business.{application}.{module}` |
| Complexité | {Simple/Moyenne/Complexe} |
| Entités | {N} à créer |
| Endpoints | {N} à implémenter |
| Pages | {N} à créer |

---

## 2. [EXPLORE] DÉCOUVERTE DES PATTERNS

**AVANT de coder, explorer ces fichiers pour comprendre les patterns existants:**

### 2.1 Backend - Patterns à suivre

```
DOMAIN:
→ src/SmartStack.Domain/Entities/
  Explorer: Structure des entités existantes, BaseEntity, interfaces
  Pattern: Propriétés, méthodes métier, validations

→ src/SmartStack.Domain/Constants/
  Explorer: Permissions.cs pour voir le format des constantes
  Pattern: public static class {Module} { public const string View = "..."; }

APPLICATION:
→ src/SmartStack.Application/Features/
  Explorer: Structure CQRS (Commands/Queries/Handlers)
  Pattern: Un dossier par feature, DTOs séparés

→ src/SmartStack.Application/Common/
  Explorer: Interfaces, comportements, validators
  Pattern: IRepository, IUnitOfWork, FluentValidation

INFRASTRUCTURE:
→ src/SmartStack.Infrastructure/Persistence/Configurations/
  Explorer: EntityTypeConfiguration existantes
  Pattern: HasData pour seed, relations, indexes

→ src/SmartStack.Infrastructure/Persistence/Configurations/Authorization/
  Explorer: PermissionConfiguration.cs pour seed permissions
  Pattern: HasData avec GUID aléatoires

API:
→ src/SmartStack.Api/Controllers/
  Explorer: Structure des controllers Business area
  Pattern: [RequirePermission], [ProducesResponseType], routes

→ src/SmartStack.Api/Areas/Business/
  Explorer: Controllers existants dans l'area Business
```

### 2.2 Frontend - Patterns à suivre

```
PAGES:
→ web/smartstack-web/src/pages/business/
  Explorer: Structure des pages existantes
  Pattern: Liste + Détail + Modal, hooks customs

→ web/smartstack-web/src/pages/admin/
  Explorer: RolesPage, UsersPage pour patterns CRUD
  Pattern: DataTable, filtres, modals

COMPOSANTS:
→ web/smartstack-web/src/components/
  Explorer: Composants réutilisables
  Pattern: Button, Modal, DataTable, Form

SERVICES:
→ web/smartstack-web/src/services/api/
  Explorer: Services API existants
  Pattern: apiClient, endpoints, types

I18N:
→ web/smartstack-web/src/i18n/locales/fr/
  Explorer: Structure des fichiers de traduction
  Pattern: Clés hiérarchiques, pluriels

HOOKS:
→ web/smartstack-web/src/hooks/
  Explorer: Hooks customs existants
  Pattern: useApi, usePermission, useToast
```

---

## 3. ENTITÉ(S) À CRÉER

### 3.1 {EntityName}

**Description:** {description métier de l'entité}

**Attributs:**

| Attribut | Description métier | Obligatoire | Validation | Règle BR |
|----------|-------------------|-------------|------------|----------|
| Id | Identifiant unique | Oui | GUID aléatoire | - |
| {attr1} | {description} | Oui | {règle} | BR-001 |
| {attr2} | {description} | Non | {règle} | - |
| {attr3} | {description} | Oui | {règle} | BR-002 |
| Status | État de l'entité | Oui | Enum | - |
| CreatedAt | Date création | Oui | Auto | - |
| CreatedBy | Créateur | Oui | Auto (current user) | - |
| UpdatedAt | Date modification | Non | Auto | - |
| UpdatedBy | Modificateur | Non | Auto (current user) | - |

**Relations:**

| Relation | Type | Entité cible | Navigation |
|----------|------|--------------|------------|
| {rel1} | 1:N | {Entity} | Collection |
| {rel2} | N:1 | {Entity} | Reference |

**Status Enum:**

| Valeur | Description | Transitions possibles |
|--------|-------------|----------------------|
| Draft | Brouillon | → Active |
| Active | Actif | → Inactive, Archived |
| Inactive | Désactivé | → Active, Archived |
| Archived | Archivé | (terminal) |

---

## 4. PERMISSIONS À IMPLÉMENTER

### 4.1 Constantes (Permissions.cs)

**Ajouter dans `src/SmartStack.Application/Common/Constants/Permissions.cs`:**

```
Emplacement: public static class Business > public static class {Module}

Paths à créer:
• business.{application}.{module}.read
• business.{application}.{module}.create
• business.{application}.{module}.update
• business.{application}.{module}.delete
```

### 4.2 Seed EF Core (PermissionConfiguration.cs)

**Ajouter dans `PermissionConfiguration.cs` avec HasData:**

| Permission Path | Description | ModuleId |
|-----------------|-------------|----------|
| `business.{app}.{module}.read` | View {module} data | {moduleId} |
| `business.{app}.{module}.create` | Create {module} entries | {moduleId} |
| `business.{app}.{module}.update` | Modify {module} entries | {moduleId} |
| `business.{app}.{module}.delete` | Delete {module} entries | {moduleId} |

**⚠️ IMPORTANT:** Utiliser des GUIDs ALÉATOIRES (pas de patterns prévisibles)

### 4.3 Matrice Rôle-Permission

| Permission | SuperAdmin | Admin | Manager | User | ReadOnly |
|------------|------------|-------|---------|------|----------|
| `.read` | ✅ | ✅ | ✅ | ✅ | ✅ |
| `.create` | ✅ | ✅ | ✅ | ❌ | ❌ |
| `.update` | ✅ | ✅ | ✅ | ❌ | ❌ |
| `.delete` | ✅ | ✅ | ❌ | ❌ | ❌ |

---

## 5. ENDPOINTS API

| Endpoint | Méthode | Permission | Body | Response |
|----------|---------|------------|------|----------|
| `/api/business/{module}` | GET | `.read` | Query params | 200: Liste paginée |
| `/api/business/{module}` | POST | `.create` | CreateDto | 201: Entité créée |
| `/api/business/{module}/{id}` | GET | `.read` | - | 200: Entité |
| `/api/business/{module}/{id}` | PUT | `.update` | UpdateDto | 200: Entité modifiée |
| `/api/business/{module}/{id}` | DELETE | `.delete` | - | 204: No Content |
| `/api/business/{module}/{id}/activate` | PATCH | `.update` | - | 204: Activé |
| `/api/business/{module}/{id}/deactivate` | PATCH | `.update` | - | 204: Désactivé |

### 5.1 Query Parameters (GET liste)

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| page | int | 1 | Numéro de page |
| pageSize | int | 10 | Items par page (max 100) |
| sortBy | string | createdAt | Champ de tri |
| sortOrder | string | desc | asc/desc |
| search | string | - | Recherche textuelle |
| status | string | - | Filtre par status |

### 5.2 CreateDto

| Champ | Type | Requis | Validation |
|-------|------|--------|------------|
| {field1} | string | Oui | MaxLength(100) |
| {field2} | string | Oui | Enum values |
| {field3} | string | Non | MaxLength(500) |

### 5.3 UpdateDto

Identique à CreateDto.

### 5.4 ResponseDto

| Champ | Type | Description |
|-------|------|-------------|
| id | Guid | Identifiant |
| {field1} | string | {description} |
| {field2} | string | {description} |
| status | string | Status actuel |
| createdAt | DateTime | Date création |
| updatedAt | DateTime? | Date modification |

---

## 6. RÈGLES MÉTIER À IMPLÉMENTER

| BR-ID | Règle | Où implémenter |
|-------|-------|----------------|
| BR-001 | {règle} | Domain Entity / Validator |
| BR-002 | {règle} | Command Handler |
| BR-003 | {règle} | Domain Service |

### 6.1 Détail BR-001

**Règle:** {description complète}

**Implémentation:**
```
SI {condition}
ALORS {action}
SINON {erreur avec message}
```

**Message d'erreur:** `{module}.errors.br001Violation`

---

## 7. PAGES FRONTEND

### 7.1 Liste ({Module}Page.tsx)

**Route:** `/business/{application}/{module}`

**Composants requis:**
- Header avec titre + bouton Nouveau
- Filtres (status, recherche, dates)
- DataTable avec pagination
- Actions par ligne (view, edit, delete)
- Modal création/édition

**Permissions UI:**
- Bouton Nouveau: visible si `.create`
- Bouton Edit: visible si `.update`
- Bouton Delete: visible si `.delete`

### 7.2 Détail ({Module}DetailPage.tsx)

**Route:** `/business/{application}/{module}/:id`

**Composants:**
- Breadcrumb
- Card informations principales
- Actions (edit, delete, activate/deactivate)
- Historique des modifications (si audit)

---

## 8. INTERNATIONALISATION (i18n)

**Fichiers à créer/modifier:**

| Fichier | Clés à ajouter |
|---------|----------------|
| `fr/{module}.json` | Toutes les clés |
| `en/{module}.json` | Toutes les clés |
| `it/{module}.json` | Toutes les clés |
| `de/{module}.json` | Toutes les clés |

**Structure des clés:**

```json
{
  "{module}": {
    "title": "{Module Name}",
    "subtitle": "{Description}",
    "fields": {
      "{field1}": "{Label}",
      "{field2}": "{Label}"
    },
    "actions": {
      "create": "Nouveau",
      "edit": "Modifier",
      "delete": "Supprimer"
    },
    "messages": {
      "created": "{Entity} créé avec succès",
      "updated": "{Entity} modifié avec succès",
      "deleted": "{Entity} supprimé avec succès"
    },
    "errors": {
      "notFound": "{Entity} non trouvé",
      "validation": "Données invalides"
    }
  }
}
```

---

## 9. INTÉGRATIONS SMARTSTACK ⭐

> **Importé depuis FRD Section 9 - Skills à exécuter automatiquement**

### 9.1 Notifications (si requis)

| Événement | NotificationType | Destinataire | Message |
|-----------|------------------|--------------|---------|
| {Entity}Created | `{Entity}Created` | Créateur | `{module}.notifications.created` |
| {Entity}Updated | `{Entity}Updated` | Assigné | `{module}.notifications.updated` |
| {Entity}Assigned | `{Entity}Assigned` | Nouvel assigné | `{module}.notifications.assigned` |

**Skill:** `/notification add`
**Service à modifier:** `{Entity}Service.cs`

**Template intégration:**
```csharp
await _notificationService.SendNotificationAsync(
    userId: {destinataire}.Id,
    type: NotificationType.{Entity}Created,
    title: _localizer["{module}.notifications.created.title"],
    message: _localizer["{module}.notifications.created.message", entity.Name],
    relatedEntityType: nameof({Entity}),
    relatedEntityId: entity.Id,
    actionUrl: $"/{module}/{entity.Id}",
    cancellationToken: ct);
```

### 9.2 Workflows (si requis)

| Workflow Code | Trigger | Steps | Variables |
|---------------|---------|-------|-----------|
| `{workflow-code}` | `{entity}.created` | SendEmail, Wait | entityId, entityName, userEmail |

**Skill:** `/workflow create`

**Template déclenchement:**
```csharp
await _workflowService.TriggerAsync(
    "{entity}.created",
    new Dictionary<string, object>
    {
        ["entityId"] = entity.Id,
        ["entityName"] = entity.Name,
        ["userEmail"] = _currentUser.Email
    },
    language: _currentUser.Language ?? "fr",
    cancellationToken: ct);
```

### 9.3 Assistance IA (si requis)

| Prompt Code | Fonction | Input | Output | Schema |
|-------------|----------|-------|--------|--------|
| `{prompt-code}` | {génération/classification} | {context} | {format} | {schema} |

**Skill:** `/ai-prompt create`

**Template intégration:**
```csharp
var result = await _aiCompletionService.CompleteAsync<{OutputType}>(
    "{prompt-code}",
    new Dictionary<string, object>
    {
        ["context"] = context,
        ["entity"] = entity
    },
    cancellationToken: ct);
```

### 9.4 Résumé des Skills à exécuter

| Intégration | Requis | Skill | Moment d'exécution |
|-------------|--------|-------|-------------------|
| Notifications | {oui/non} | `/notification add` | Après service backend |
| Workflows | {oui/non} | `/workflow create` | Après triggers définis |
| IA | {oui/non} | `/ai-prompt create` | Pendant service backend |

**⚠️ IMPORTANT:** Ces skills sont exécutés automatiquement par `/implement` si requis=oui.

---

## 10. TESTS REQUIS

### 10.1 Tests unitaires

- [ ] Entity validation rules
- [ ] Command validators (FluentValidation)
- [ ] Business rules in handlers

### 10.2 Tests d'intégration

- [ ] GET /api/business/{module} - 200 OK
- [ ] GET /api/business/{module}/{id} - 200 OK
- [ ] GET /api/business/{module}/{id} - 404 Not Found
- [ ] POST /api/business/{module} - 201 Created
- [ ] POST /api/business/{module} - 400 Bad Request (validation)
- [ ] PUT /api/business/{module}/{id} - 200 OK
- [ ] DELETE /api/business/{module}/{id} - 204 No Content

### 10.3 Tests de permission

- [ ] GET sans permission - 403 Forbidden
- [ ] POST avec ReadOnly - 403 Forbidden
- [ ] DELETE avec User - 403 Forbidden

### 10.4 Collection Postman

Générer automatiquement avec `/controller:create`

---

## 11. CHECKLIST POST-IMPLÉMENTATION

### Backend

- [ ] Entity créée dans Domain
- [ ] Configuration EF Core créée
- [ ] Migration EF Core créée (`/efcore:migration`)
- [ ] Commands/Queries créés dans Application
- [ ] Validators FluentValidation créés
- [ ] Controller créé dans Api/Areas/Business
- [ ] Permissions ajoutées dans Permissions.cs
- [ ] Permissions seedées dans PermissionConfiguration.cs
- [ ] Build backend OK

### Frontend

- [ ] Page liste créée
- [ ] Page détail créée (si applicable)
- [ ] Service API créé
- [ ] i18n complet (4 langues)
- [ ] Routes ajoutées dans App.tsx
- [ ] Build frontend OK

### Tests

- [ ] Tests unitaires passent
- [ ] Tests intégration passent
- [ ] Collection Postman créée

### Documentation

- [ ] `/business-analyse:7-doc-html {FEATURE_ID}` exécuté

### Intégrations SmartStack

- [ ] Notifications ajoutées (si requis)
- [ ] Workflows créés (si requis)
- [ ] Prompts IA créés (si requis)
- [ ] Hooks frontend SignalR (si notifications)

---

## 12. COMMANDE D'IMPLÉMENTATION

```bash
# Implémentation complète
/implement {FEATURE_ID}

# Par phase
/implement {FEATURE_ID} --phase=1  # Backend
/implement {FEATURE_ID} --phase=2  # Frontend
/implement {FEATURE_ID} --phase=3  # Tests
/implement {FEATURE_ID} --phase=4  # Documentation HTML
```

---

## Historique des versions

| Version | Date | Auteur | Modifications |
|---------|------|--------|---------------|
| 1.0 | {date} | BA (Opus) | Création initiale (locked) |
```

---

## STEP 4: Verrouillage des documents

```bash
# Marquer les documents comme verrouillés
for doc in "1-discovery.md" "2-business-requirements.md" "3-functional-specification.md"; do
  if [ -f "$FEATURE_DIR/$doc" ]; then
    # Ajouter un header de verrouillage
    sed -i "1s/^/<!-- LOCKED: v1.0 - Validated $(date -I) -->\n/" "$FEATURE_DIR/$doc"
  fi
done
```

---

## STEP 5: Vérification de complétude (RALPH-LOOP)

Avant de terminer, vérifier que TOUS les critères sont remplis:

```
CHECKLIST COMPLÉTUDE HANDOFF:
□ Section 1 (Contexte) - Feature ID, Module, Complexité renseignés
□ Section 2 (Explore) - Tous les patterns backend/frontend listés
□ Section 3 (Entités) - Toutes les entités du FRD avec attributs complets
□ Section 4 (Permissions) - Paths explicites, matrice rôles complète
□ Section 5 (Endpoints) - Tous les UC couverts, DTOs définis
□ Section 6 (Règles métier) - Tous les BR référencés avec implémentation
□ Section 7 (Pages) - Routes, composants, permissions UI
□ Section 8 (i18n) - Structure clés pour 4 langues
□ Section 9 (Intégrations) - Notifications/Workflows/IA spécifiés (oui/non)
□ Section 10 (Tests) - Checklist unitaires + intégration
□ Section 11 (Checklist) - Tous les items listés (incluant intégrations)
□ Section 12 (Commande) - /implement documenté
□ Aucun marqueur "TBD", "?", "{...}" restant dans le document
```

---

## STEP 6: Résumé

**SI TOUS LES CRITÈRES SONT REMPLIS:**

```
================================================================================
                    HANDOFF GÉNÉRÉ - {FEATURE_ID}
================================================================================

DOCUMENT:          {FEATURE_DIR}/4-development-handoff.md
MODÈLE UTILISÉ:    Opus avec ULTRATHINK
STATUS:            Prêt pour implémentation

CONTENU:
  • Instructions EXPLORE complètes
  • {N} entité(s) spécifiée(s)
  • {N} endpoint(s) API
  • {N} permission(s) définies
  • {N} page(s) frontend
  • {N} intégration(s) SmartStack (Notif/Workflow/IA)
  • Checklist de 25+ points

DOCUMENTS VERROUILLÉS:
  ✓ 1-discovery.md v1.0
  ✓ 2-business-requirements.md v1.0
  ✓ 3-functional-specification.md v1.0
  ✓ 4-development-handoff.md v1.0

================================================================================
PROCHAINE ÉTAPE
================================================================================

Lancez l'implémentation:

  /implement {FEATURE_ID}

Ou avec ralph-loop pour one-shot complet:

  /ralph-loop "/implement {FEATURE_ID}" \
              --completion-promise "FEATURE_COMPLETE" \
              --max-iterations 25

================================================================================

<promise>COMPLETE</promise>

Contact support: support@atlshub.ch
```

**SI DES CRITÈRES MANQUENT:**

Ne pas afficher le signal de complétion. Compléter les sections manquantes en relisant les documents source (Discovery, BRD, FRD).
