module-development

name: module-development description: "OBLIGATOIRE pour: tout travail structurel dans src/modules/* — créer/étendre un module, ModuleDefinition, routes, sidebar, permissions, clients API frontend, hooks TanStack Query, settings tab, README de module. Déclencheurs: nouveau module, nouvelle page, nouvelle route, permission, hook, client API. NE PAS utiliser pour: style/apparence pure (ui-design), endpoints côté serveur (backend-fastapi)."

Développement de module — RadioManager Modular

PRIMARY RESPONSIBILITY

Structure et câblage des modules métier frontend : ModuleDefinition, routes, sidebar, permissions, couche données (api/hooks/types), documentation de module.

USE THIS SKILL WHEN

• On crée un module ou on ajoute une page, route, item sidebar, permission, settings tab.
• On ajoute/modifie un client API frontend, un hook TanStack Query, des types de module.
• On refactore la structure d'un module ou on met à jour son README.

DO NOT USE THIS SKILL WHEN

• Le travail est purement visuel : layout, couleurs, états, responsive (→ skill ui-design).
• Le travail est côté serveur : endpoint, modèle, migration (→ skill backend-fastapi).
• On modifie src/shared/ sans toucher aux modules (lire directement les fichiers concernés).

TRIGGERS

module, ModuleDefinition, route, sidebar, permission, page, hook, client API, settings tab, src/modules, Launchpad, README de module.

OWNED DIRECTORIES

• src/modules/<nom>/ (tous les modules métier)
• src/config/modules.ts (enregistrement)

REQUIRED DEPENDENCIES

• src/shared/types/module.ts — types ModuleDefinition, ModuleRoute, SidebarItem (lire avant édition)
• src/shared/types/permissions.ts — si ajout/usage de permissions
• Le README.md et index.ts du module cible (lire avant édition)

OPTIONAL DEPENDENCIES

• Skill ui-design — dès que la tâche inclut du rendu visuel
• Skill backend-fastapi — si l'endpoint consommé n'existe pas encore côté serveur
• Skill release-version — au moment de committer

RELATED DOCUMENTATION

• MODULE_GUIDE.md — flow canonique de création de module
• docs/modules/MODULE_README_TEMPLATE.md — template README (12 sections)
• docs/reference/BACKEND_API.md — routes backend disponibles

Frontières de modules (CRITIQUES)

• Un module peut importer depuis @/shared/*.
• Un module ne doit JAMAIS importer depuis un autre module.
• src/shared/ ne doit JAMAIS importer depuis src/modules/.
• Communication inter-modules : eventBus uniquement.
• Enregistrement uniquement dans src/config/modules.ts.

Structure attendue

src/modules/<module>/
  index.ts        # ModuleDefinition
  README.md       # obligatoire, 12 sections du template
  api/            # clients API
  components/
  hooks/          # TanStack Query
  pages/
  types/
  stores/         # optionnel
  docs/           # obligatoire pour modules fonctionnels (API_GUIDE, DATA_MODELS, GUIDE_JUNIOR)

Checklist ModuleDefinition

• id stable et unique ; name, description, icon, color, basePath, order définis.
• requiredPermission pour l'accès Launchpad/module.
• sidebarItems : icônes Lucide PascalCase, permission par item.
• routes couvrent chaque page avec sa permission.
• settingsTab seulement si le module a des paramètres.
• getBadgeCount attrape les erreurs et retourne 0 en cas d'échec.

Couche données

• Clients API dans api/, hooks TanStack Query dans hooks/, types dans types/.
• Axios partagé : @/shared/api/axios.
• Mappers explicites snake_case (backend) → camelCase (UI).
• Invalider les queries concernées après mutation.
• Firebase uniquement là où le module l'utilise déjà ; null au lieu de undefined pour Firestore.

Permissions — 4 niveaux

Module (requiredPermission) → Route (ModuleRoute.permission) → Sidebar (SidebarItem.permission) → Composant (hasPermission('can_xxx')).

Documentation après modification

Mettre à jour le README.md du module (12 sections). Modules fonctionnels : docs/API_GUIDE.md, DATA_MODELS.md, GUIDE_JUNIOR.md. Rédaction niveau junior.

Validation

npx tsc -b --noEmit puis npm run build ; module visible dans le Launchpad.