Skip to content

GROUP_CONTROLLER_OPENAPI_ANALYSIS.md

Latest commit

 

History

History
168 lines (136 loc) · 8 KB

GROUP_CONTROLLER_OPENAPI_ANALYSIS.md

File metadata and controls

168 lines (136 loc) · 8 KB

Analyse d'Alignement - GroupController et Schémas OpenAPI

Résumé Exécutif

Cette analyse examine l'alignement entre le GroupController et les schémas OpenAPI pour identifier les incohérences, les schémas inutilisés et les améliorations nécessaires pour une parfaite conformité.

📊 Méthodes du Controller et Schémas Utilisés

Endpoint du Controller Schéma de Réponse Utilisé Service Method Format de Données Retourné
createGroup GroupSuccessResponseSchema GroupService.createGroup() { id, name, description, familyId, inviteCode, createdAt, updatedAt, userRole, ownerFamily, familyCount, scheduleCount }
joinGroup GroupSuccessResponseSchema GroupService.joinGroupByInviteCode() GroupMembership object
getUserGroups GroupsSuccessResponseSchema GroupService.getUserGroups() Array<GroupResponse>
getGroupFamilies GroupsSuccessResponseSchema GroupService.getGroupFamilies() ❌ INCOHÉRENCE - Retourne tableau d'objets families, pas de groupes
updateFamilyRole FamilyGroupMemberSuccessResponseSchema GroupService.updateFamilyRole() FamilyGroupMember object
removeFamilyFromGroup SimpleSuccessResponseSchema GroupService.removeFamilyFromGroup() { success: true, message: string }
updateGroup GroupSuccessResponseSchema GroupService.updateGroup() GroupResponse object
deleteGroup SimpleSuccessResponseSchema GroupService.deleteGroup() { success: true, message: string }
leaveGroup SimpleSuccessResponseSchema GroupService.leaveGroup() { success: true, message: string }
getWeeklySchedule ScheduleSuccessResponseSchema SchedulingService.getWeeklySchedule() ❌ ERREUR - Service n'existe pas
inviteFamilyToGroup GroupInvitationSuccessResponseSchema GroupService.inviteFamilyById() GroupInvitation object
getPendingInvitations PendingInvitationsSuccessResponseSchema GroupService.getPendingInvitations() Array<GroupInvitation>
cancelInvitation SimpleSuccessResponseSchema GroupService.cancelInvitation() { success: true, message: string }
validateInviteCode GroupInvitationValidationSuccessResponseSchema GroupService.validateInvitationCode() { valid, group, invitation }
validateInviteCodeWithAuth InviteCodeValidationSuccessResponseSchema GroupService.validateInvitationCodeWithUser() { valid, family }
searchFamilies FamilySearchSuccessResponseSchema GroupService.searchFamiliesForInvitation() Array<FamilySearchResult>

🚨 Problèmes Critiques Identifiés

1. INCOHÉRENCE MAJEURE - getGroupFamilies

  • Problème: L'endpoint /groups/{groupId}/families utilise GroupsSuccessResponseSchema mais retourne des familles, pas des groupes
  • Données réelles retournées: Array d'objets avec { id, name, role, isMyFamily, canManage, admins }
  • Schéma attendu: Devrait utiliser FamilySearchSuccessResponseSchema ou créer un nouveau schéma GroupFamiliesSuccessResponseSchema

2. SERVICE MANQUANT - getWeeklySchedule

  • Problème: SchedulingService.getWeeklySchedule() n'existe pas
  • Import: import { SchedulingService } from '../services/SchedulingService'; mais le fichier n'existe pas
  • Impact: L'endpoint /groups/{groupId}/schedule échouera

3. TYPE MISMATCH - joinGroup

  • Problème: joinGroupByInviteCode() retourne un GroupMembership mais utilise GroupSuccessResponseSchema
  • Données attendues: GroupMembershipSchema avec { familyId, groupId, role, joinedAt, family?, group? }
  • Schéma utilisé: GroupResponseSchema (structure différente)

📋 Schémas de Réponse Non Utilisés

Les schémas suivants sont définis dans responses.ts mais jamais utilisés dans le GroupController:

  1. FamilyInvitationSuccessResponseSchema - Pour les invitations familiales (hors contexte groupes)
  2. InvitationCreationResponseSchema - Pour la création d'invitations génériques
  3. PermissionsSuccessResponseSchema - Pour les réponses de permissions
  4. VehicleRemovedSuccessResponseSchema - Spécifique aux véhicules

🔍 Incohérences de Types de Données

Dates vs Strings

  • Services: Retournent Date.toISOString() (ex: group.createdAt.toISOString())
  • Schémas: Utilisent z.iso.datetime() - ✅ CORRECT
  • Validation: Les schémas acceptent correctement les chaînes ISO 8601

Nombres vs Strings

  • Prisma: Retourne des nombres natifs pour familyCount, scheduleCount
  • Schémas: Utilisent z.number() - ✅ CORRECT

Enums vs Strings

  • Services: Retournent des valeurs enum (ex: userRole: 'ADMIN' | 'MEMBER')
  • Schémas: Utilisent z.enum(['ADMIN', 'MEMBER']) - ✅ CORRECT

📝 Propriétés Obligatoires vs Optionnelles

GroupResponseSchema

// Schéma actuel - Toutes les propriétés requises
{
  id: string // ✓
  name: string // ✓
  description: string | null // ✓ (nullable correct)
  familyId: string // ✓
  inviteCode: string // ✓
  createdAt: string // ✓
  updatedAt: string // ✓
  userRole: 'ADMIN' | 'MEMBER' // ✓
  ownerFamily: OwnerFamilySchema // ✓
  familyCount: number // ✓
  scheduleCount: number // ✓
}

Problèmes Identifiés:

  1. scheduleCount optionnel dans schéma mais toujours présent dans les retours de service
  2. family dans FamilyGroupMemberSchema marqué comme optionnel mais parfois inclus

🛠️ Recommandations de Corrections

1. Corriger getGroupFamilies (Priorité HAUTE)

// Créer nouveau schéma dans responses.ts
export const GroupFamiliesSuccessResponseSchema = createSuccessResponseSchema(
  z.array(z.object({
    id: z.cuid(),
    name: z.string(),
    role: z.enum(['OWNER', 'ADMIN', 'MEMBER']),
    isMyFamily: z.boolean(),
    canManage: z.boolean(),
    admins: z.array(z.object({
      name: z.string(),
      email: z.email(),
    })),
  }))
);

// Dans GroupController.ts ligne 205
sendSuccessResponse(res, 200, GroupFamiliesSuccessResponseSchema, families);

2. Corriger joinGroup (Priorité HAUTE)

// Dans GroupController.ts ligne 135
sendSuccessResponse(res, 200, GroupMembershipSuccessResponseSchema, membership);

// Ajouter dans responses.ts
export const GroupMembershipSuccessResponseSchema = createSuccessResponseSchema(
  GroupMembershipSchema
);

3. Créer SchedulingService (Priorité CRITIQUE)

// Créer fichier backend/src/services/SchedulingService.ts
export class SchedulingService {
  async getWeeklySchedule(groupId: string, week?: string) {
    // Implémenter la logique de récupération du planning hebdomadaire
  }
}

4. Nettoyer les imports (Priorité MOYENNE)

// Dans GroupController.ts, supprimer l'import manquant:
// import { SchedulingService } from '../services/SchedulingService';

5. Uniformiser les réponses d'erreur (Priorité BASSE)

Ajouter des schémas d'erreur spécifiques pour chaque type d'erreur dans les réponses OpenAPI.

✅ Points Positifs

  1. Structure cohérente: La plupart des endpoints suivent le pattern sendSuccessResponse()
  2. Validation OpenAPI: Utilisation systématique des schémas pour la validation
  3. Gestion des erreurs: Centralisée via errorHandler
  4. Logging: Exhaustif dans toutes les méthodes
  5. Sécurité: Vérification des permissions et authentification

📈 Score de Conformité

  • Endpoints totaux: 16
  • Endpoints corrects: 11 (68.75%)
  • Endpoints avec problèmes: 5 (31.25%)
  • Problèmes critiques: 2
  • Recommandations: 5

🎯 Actions Immédiates Requises

  1. Créer SchedulingService.ts - Bloquant pour l'endpoint schedule
  2. Corriger le schéma getGroupFamilies - Incohérence majeure
  3. Corriger le schéma joinGroup - Mauvais type de réponse
  4. Tests de validation post-corrections
  5. Mise à jour documentation OpenAPI après corrections