TaxasGE Backend Dev Skill

Overview

Ce skill complète le DEV_AGENT avec des patterns spécifiques backend FastAPI. Il ne remplace PAS le workflow de développement mais fournit des références techniques et templates pour l'implémentation backend.

Principe fondamental : Guide technique, pas workflow (le workflow est dans DEV_AGENT.md et DEV_WORKFLOW.md).

---

When to Use This Skill

Claude invoquera automatiquement ce skill quand :

• DEV_AGENT implémente tâche backend
• Besoin patterns FastAPI
• Questions architecture 3-tiers
• Référence technique backend

Ne PAS utiliser pour :

• Workflow développement (voir DEV_WORKFLOW.md)
• Validation (voir Go/No-Go Validator)
• Orchestration (voir Orchestrator)

---

Core Responsibilities

1. Architecture 3-Tiers Stricte

Séparation obligatoire :

Routes (API Layer)        ← Validation input, Response format, RBAC
    ↓
Services (Business Logic) ← Logique métier, Orchestration
    ↓
Repositories (Data)       ← CRUD, Queries SQL, Transactions

Règles absolues :

• ❌ Jamais de business logic dans routes
• ❌ Jamais de SQL direct dans services
• ❌ Jamais de validation métier dans repositories

2. Référence Documentation Backend

Source unique de vérité : .github/docs-internal/Documentations/Backend/

Structure :

.github/docs-internal/Documentations/Backend/
├── API_REFERENCE.md              ← Endpoints documentés
├── ARCHITECTURE.md               ← Architecture globale
├── DATABASE_SCHEMA.md            ← Schéma DB
├── ERROR_HANDLING.md             ← Gestion erreurs RFC 7807
├── AUTHENTICATION.md             ← JWT + RBAC
└── DEPLOYMENT.md                 ← Déploiement Cloud Run

Important : Toujours référencer cette documentation, ne PAS dupliquer.

3. Templates Code

Templates disponibles :

• templates/endpoint_template.py - Structure route FastAPI
• templates/service_template.py - Structure service métier
• templates/repository_template.py - Structure repository DB

Usage : Copie template → Adapte au use case → Implémente

---

Patterns Backend

Pattern 1 : Route FastAPI Standard

Template : templates/endpoint_template.py

Structure :

from fastapi import APIRouter, Depends, HTTPException
from app.services.{module}_service import {Module}Service
from app.core.auth import require_role
from app.schemas.{module} import {Module}Create, {Module}Response

router = APIRouter(prefix="/{module}", tags=["{Module}"])

@router.post("/", response_model={Module}Response, status_code=201)
@require_role("citizen")
async def create_{module}(
    data: {Module}Create,
    service: {Module}Service = Depends()
):
    """
    Créer {module}.
    
    **Source** : .github/docs-internal/Documentations/Backend/API_REFERENCE.md
    
    **Validation** :
    - Pydantic {Module}Create automatique
    - RBAC : Rôle "citizen" requis
    
    **Errors** :
    - 400 : Validation error
    - 401 : Non authentifié
    - 403 : Non autorisé
    """
    return await service.create(data)

Points clés :

1. Prefix + Tags : Organisation Swagger
2. Response model : Type-safety sortie
3. RBAC decorator : @require_role() AVANT handler
4. Dependency injection : Service via Depends()
5. Docstring complète : Source + Validation + Errors

---

Pattern 2 : Service Métier

Template : templates/service_template.py

Structure :

from app.database.repositories.{module}_repository import {Module}Repository
from app.core.errors import ValidationError, ResourceNotFoundError

class {Module}Service:
    """
    Service {module}.
    
    **Source** : .github/docs-internal/Documentations/Backend/ARCHITECTURE.md
    """
    
    def __init__(self):
        self.repo = {Module}Repository()
    
    async def create(self, data: {Module}Create) -> {Module}:
        """
        Créer {module} avec validations métier.
        
        **Business Rules** :
        1. {Règle métier 1}
        2. {Règle métier 2}
        
        **Source** : .github/docs-internal/Documentations/Backend/API_REFERENCE.md
        """
        # Validations métier
        await self._validate_business_rules(data)
        
        # Créer via repository
        result = await self.repo.create(data)
        
        # Actions post-création (emails, notifications, etc.)
        await self._post_creation_actions(result)
        
        return result
    
    async def _validate_business_rules(self, data: {Module}Create):
        """
        Validations métier spécifiques.
        
        Raises:
            ValidationError: Si validation échoue
        """
        # Exemple : Vérifier unicité
        existing = await self.repo.get_by_field(data.unique_field)
        if existing:
            raise ValidationError(
                field="unique_field",
                message="Already exists",
                value=data.unique_field
            )
    
    async def _post_creation_actions(self, entity):
        """Actions après création (async, non-bloquantes)."""
        # Exemple : Envoyer email confirmation
        pass

Points clés :

1. Injection repository : Dans __init__
2. Business logic SEULEMENT : Pas de SQL
3. Méthodes privées : _validate_*, _post_*
4. Exceptions custom : ValidationError, ResourceNotFoundError
5. Docstrings avec source : Traçabilité

---

Pattern 3 : Repository DB

Template : templates/repository_template.py

Structure :

from sqlalchemy import select, update, delete
from sqlalchemy.ext.asyncio import AsyncSession
from app.models.{module} import {Module}
from app.database.connection import get_db
from app.core.errors import ResourceNotFoundError
from fastapi import Depends

class {Module}Repository:
    """
    Repository {module}.
    
    **Source** : database/schema.sql
    """
    
    def __init__(self, db: AsyncSession = Depends(get_db)):
        self.db = db
    
    async def create(self, data: {Module}Create) -> {Module}:
        """
        Créer {module} en DB.
        
        **Source** : database/schema.sql ligne {X}
        """
        entity = {Module}(**data.dict())
        self.db.add(entity)
        await self.db.flush()  # Get ID
        await self.db.refresh(entity)
        return entity
    
    async def get_by_id(self, id: int) -> {Module}:
        """
        Récupérer {module} par ID.
        
        Raises:
            ResourceNotFoundError: Si non trouvé
        """
        query = select({Module}).where({Module}.id == id)
        result = await self.db.execute(query)
        entity = result.scalar_one_or_none()
        
        if not entity:
            raise ResourceNotFoundError(
                resource="{Module}",
                identifier=str(id)
            )
        
        return entity
    
    async def list(
        self, 
        filters: dict = None,
        limit: int = 100,
        offset: int = 0
    ) -> list[{Module}]:
        """
        Lister {module}s avec pagination.
        
        **Source** : .github/docs-internal/Documentations/Backend/API_REFERENCE.md
        """
        query = select({Module})
        
        # Filtres dynamiques
        if filters:
            for key, value in filters.items():
                if hasattr({Module}, key):
                    query = query.where(getattr({Module}, key) == value)
        
        # Pagination
        query = query.limit(limit).offset(offset)
        
        result = await self.db.execute(query)
        return result.scalars().all()
    
    async def update(self, id: int, data: {Module}Update) -> {Module}:
        """Mettre à jour {module}."""
        entity = await self.get_by_id(id)
        
        for key, value in data.dict(exclude_unset=True).items():
            setattr(entity, key, value)
        
        await self.db.flush()
        await self.db.refresh(entity)
        return entity
    
    async def delete(self, id: int) -> bool:
        """Supprimer {module}."""
        entity = await self.get_by_id(id)
        await self.db.delete(entity)
        return True

Points clés :

1. Injection DB session : Via Depends(get_db)
2. Queries SQL SEULEMENT : Pas de business logic
3. Gestion erreurs : ResourceNotFoundError si non trouvé
4. Pagination : limit + offset
5. Source schema.sql : Référence ligne exacte

---

Checklist Implémentation Backend

Avant de considérer tâche backend terminée :

Code

• Architecture 3-tiers respectée (Routes → Services → Repositories)
• Pydantic models avec validation complète
• Error handling RFC 7807 implémenté
• RBAC configuré (@require_role)
• Docstrings complètes avec sources

Sources (Règle 0)

• Schema DB vérifié (database/schema.sql)
• Documentation backend consultée (.github/docs-internal/Documentations/Backend/)
• Code existant respecté (patterns cohérents)

Tests

• Tests unitaires services écrits (>85% coverage)
• Tests endpoints écrits (>85% coverage)
• Tests repositories écrits (>90% coverage)
• Tests passent (100%)

Qualité

• Lint : 0 erreurs flake8
• Type check : 0 erreurs mypy
• Build : Réussi

Documentation

• Swagger endpoints documentés
• README module créé/mis à jour

---

Integration avec DEV_AGENT

Workflow Complet

1. DEV_AGENT reçoit tâche (ex: TASK-P2-007)
   ↓
2. DEV_AGENT lit DEV_WORKFLOW.md (9 étapes)
   ↓
3. DEV_AGENT invoque Backend Dev Skill (ce skill)
   ↓
4. Backend Dev Skill fournit :
   - Patterns 3-tiers
   - Templates code
   - Références documentation
   ↓
5. DEV_AGENT implémente selon patterns
   ↓
6. DEV_AGENT génère rapport (.agent/Reports/PHASE_X/)
   ↓
7. Go/No-Go Validator valide (invoque TEST_AGENT)

Ce skill ne fait PAS :

• ❌ Workflow développement (c'est DEV_WORKFLOW.md)
• ❌ Git operations (c'est DEV_WORKFLOW.md)
• ❌ Génération rapports (c'est DEV_AGENT)
• ❌ Validation (c'est Go/No-Go Validator)

Ce skill fait :

• ✅ Fournit patterns techniques
• ✅ Référence documentation
• ✅ Templates code
• ✅ Best practices backend

---

References

Agents & Workflows

• .claude/.agent/Tasks/DEV_AGENT.md - Agent développement
• .claude/.agent/SOP/DEV_WORKFLOW.md - Workflow 9 étapes
• .claude/.agent/SOP/CODE_STANDARDS.md - Standards code
• .claude/.agent/SOP/TEST_WORKFLOW.md - Tests

Documentation Backend

• .github/docs-internal/Documentations/Backend/API_REFERENCE.md
• .github/docs-internal/Documentations/Backend/ARCHITECTURE.md
• .github/docs-internal/Documentations/Backend/DATABASE_SCHEMA.md
• .github/docs-internal/Documentations/Backend/ERROR_HANDLING.md
• .github/docs-internal/Documentations/Backend/AUTHENTICATION.md

Templates

• templates/endpoint_template.py - Route FastAPI
• templates/service_template.py - Service métier
• templates/repository_template.py - Repository DB

Sources (Règle 0)

1. database/schema.sql - Schéma DB
2. packages/backend/.env - Configuration
3. .github/docs-internal/Documentations/Backend/ - Documentation
4. packages/backend/app/ - Code existant

---

Success Criteria

Une implémentation backend est réussie si :

• ✅ Architecture 3-tiers strictement respectée
• ✅ Pydantic validation complète
• ✅ Error handling RFC 7807
• ✅ RBAC implémenté
• ✅ Tests coverage >85%
• ✅ 0 erreurs lint/type
• ✅ Documentation Swagger complète
• ✅ Sources (Règle 0) vérifiées

---

Example Usage

Scenario : DEV_AGENT implémente TASK-P2-007 (Endpoint création déclaration)

DEV_AGENT actions :

1. Lit TASK-P2-007 définition
2. Invoque Backend Dev Skill
3. Backend Dev Skill retourne :
   • Pattern Route (template endpoint)
   • Pattern Service (template service)
   • Pattern Repository (template repository)
   • Référence .github/docs-internal/Documentations/Backend/API_REFERENCE.md
4. DEV_AGENT implémente selon patterns :
   • app/api/v1/declarations.py (route)
   • app/services/declaration_service.py (service)
   • app/database/repositories/declaration_repository.py (repository)
5. DEV_AGENT écrit tests (>85% coverage)
6. DEV_AGENT génère rapport

Backend Dev Skill n'a PAS :

• ❌ Créé fichiers (c'est DEV_AGENT)
• ❌ Exécuté tests (c'est TEST_AGENT via Go/No-Go)
• ❌ Généré rapport (c'est DEV_AGENT)

Backend Dev Skill a :

• ✅ Fourni patterns/templates
• ✅ Référencé documentation
• ✅ Guidé architecture

---

Skill created by: TaxasGE Backend Team
Date: 2025-10-31
Version: 2.0.0
Status: ✅ READY FOR USE