veza/apps/web/dev_audit/frontend/08_technical_debt_frontend.md

# Phase H — Dette Technique Frontend

---

## H1. Complexité excessive

### Fichiers > 300 lignes (source, hors tests/generated)

| Fichier | Lignes | Raison probable | Split possible ? | Complexité |
|---------|--------|-----------------|-----------------|-----------|
| `services/api/client.ts` | 2 237 | Client HTTP + validation + caching + retry + dedup + metrics | ✅ Oui, 5 modules | 🔴 Élevée |
| `mocks/handlers.ts` | 1 716 | MSW handlers pour toutes les routes | ✅ Par feature | 🟡 Linéaire |
| `features/tracks/api/trackApi.ts` | 848 | API tracks complète | ✅ CRUD/Upload/Share/Analytics | 🟠 Moyenne |
| `utils/optimisticUpdates.ts` | 682 | Optimistic updates multi-feature | ⚠️ Difficilement | 🟠 Moyenne |
| `features/streaming/services/playbackAnalyticsService.ts` | 656 | Analytics streaming | ⚠️ Cohérent | 🟡 Linéaire |
| `features/playlists/hooks/usePlaylist.ts` | 631 | Hook playlist (CRUD + collab + analytics) | ✅ 3 hooks | 🔴 Élevée |
| `utils/apiErrorHandler.ts` | 578 | Error parsing exhaustif | ⚠️ Cohérent | 🟡 Linéaire |
| `features/streaming/hooks/usePlaybackRealtime.ts` | 496 | WebSocket + state + analytics | ⚠️ Justifié temps réel | 🟠 Moyenne |
| `services/api/auth.ts` | 493 | Auth API (login, register, 2FA, OAuth) | ⚠️ Cohérent | 🟡 Linéaire |
| `schemas/apiRequestSchemas.ts` | 476 | Zod schemas | ❌ Normal | 🟢 Faible |
| `schemas/apiSchemas.ts` | 468 | Zod schemas | ❌ Normal | 🟢 Faible |
| `features/tracks/services/trackService.ts` | 453 | Service tracks | ⚠️ Cohérent | 🟡 Linéaire |
| `features/playlists/services/playlistService.ts` | 448 | Service playlists | ⚠️ Cohérent | 🟡 Linéaire |
| `utils/sanitize.ts` | 429 | Sanitization XSS | ❌ Critique | 🟢 Faible |
| `features/chat/hooks/useChat.ts` | 360 | Hook chat | ✅ 2-3 hooks | 🟠 Moyenne |
| `features/auth/store/authStore.ts` | 330 | Store auth | ⚠️ Acceptable | 🟡 Linéaire |
| `features/dashboard/pages/DashboardPage.tsx` | 328 | Page dashboard | ✅ Extraire sections | 🟡 Moyenne |
| `features/tracks/components/TrackListRow.tsx` | 320 | Ligne de track | ✅ Sous-composants | 🟡 Moyenne |

**Priorité de split** :
1. `client.ts` (2237L) → `httpClient.ts`, `validators.ts`, `caching.ts`, `interceptors.ts`, `metrics.ts`
2. `usePlaylist.ts` (631L) → `usePlaylistCrud.ts`, `usePlaylistCollaboration.ts`, `usePlaylistAnalytics.ts`
3. `useChat.ts` (360L) → `useChatMessages.ts`, `useChatConnection.ts`

---

## H2. Props drilling

Grâce à l'utilisation de Zustand (7 stores) et React Query, le prop drilling est **minimal**. Aucune chaîne de props > 3 niveaux intermédiaires identifiée dans le code audité.

**Pattern positif** : Les stores Zustand sont accédés directement dans les composants enfants via `useAuthStore()`, `useUIStore()`, `useCartStore()`, etc. — pas besoin de passer les props à travers les composants intermédiaires.

---

## H3. Hooks complexes

### Custom hooks > 50 lignes

| Hook | Lignes | Responsabilités | Testé ? |
|------|--------|----------------|---------|
| `features/playlists/hooks/usePlaylist.ts` | 631 | CRUD + collaboration + analytics + permissions | ✅ (595L de tests) |
| `features/streaming/hooks/usePlaybackRealtime.ts` | 496 | WebSocket + state + analytics + reconnection | ✅ (490L de tests) |
| `features/chat/hooks/useChat.ts` | 360 | Messages + connection + typing + presence | ❌ Non vérifié |
| `features/tracks/hooks/useTrackList.ts` | 286 | List + filters + sort + pagination + localStorage | ✅ (761L de tests) |
| `features/playlists/hooks/usePlaylistNotifications.ts` | 264 | Notification handling + navigation | ❌ Peu testé |
| `features/player/hooks/usePlayer.ts` | 249 | Playback control + queue + history | ✅ Tests partiels |
| `hooks/useRoutePreload.ts` | 239 | Route prefetching + intersection observer | ✅ Tests |
| `features/library/hooks/useLibraryItems.ts` | 152 | Library items + filters | ❌ Non vérifié |

**Verdict** : Les 3 plus gros hooks (usePlaylist, usePlaybackRealtime, useTrackList) sont bien testés. Les hooks de taille moyenne (useChat, usePlaylistNotifications) sont moins bien couverts.

---

## H4. Duplication

### Patterns CSS les plus répétés

| Pattern | Occurrences approximatives | Action recommandée |
|---------|---------------------------|-------------------|
| `flex items-center` | ~230 | Normal (utility-first) |
| `flex flex-col` | ~230 | Normal |
| `text-muted-foreground` | ~145 | Normal (sémantique) |
| `rounded-*` | ~230 | Normal |
| `w-full h-full` | ~90 | Normal |

Ces répétitions sont **attendues** avec Tailwind utility-first et ne constituent pas de la dette technique.

### Composants dupliqués

| Duplication | Fichiers | Impact |
|------------|---------|--------|
| `layout/Sidebar.tsx` (294L) + `ui/Sidebar.tsx` (217L) | 2 fichiers | 🟠 Confusion |
| `components/player/` (14 fichiers) + `features/player/components/` (~20 fichiers) | 34 fichiers | 🟠 Migration incomplète |
| `pages/auth/` + `features/auth/pages/` | 4+ fichiers | 🟠 Legacy |
| `context/AuthContext.tsx` + `features/auth/store/authStore.ts` | 2 fichiers | 🔴 Deux sources de vérité |
| `ui/modal.tsx` + `ui/dialog/` | 2 systèmes | 🟡 Redondance |
| `ui/dropdown-menu.tsx` + `ui/dropdown-menu/` | Fichier plat + dossier | 🟡 Legacy wrapper |

### Logique métier dupliquée

- **Auth** : `authService.login()` est appelé par `authStore.login()` ET `AuthContext.login()` — deux chemins d'exécution pour la même action.
- **Toast** : `toast()` (react-hot-toast) et `addToast()` (custom) — deux APIs pour le même feedback.

---

## H5. TypeScript

### Statistiques

| Métrique | Nombre | Zone |
|----------|--------|------|
| `: any` explicites (prod) | ~82 | Code source hors tests/generated |
| `as any` casts (prod) | ~180 | Code source hors tests/generated |
| `as any` dans `generated/api.ts` | 145 | Auto-généré — acceptable |
| `@ts-ignore` / `@ts-expect-error` | 7 fichiers | Minimal ✅ |

### Fichiers avec le plus de `as any` (source)

| Fichier | `as any` | Justification |
|---------|----------|---------------|
| `services/api/client.ts` | 48 | Error handling, interceptors — type narrowing difficile |
| `utils/typeGuards.ts` | 44 | Type guards by design — acceptable |
| `utils/toast.ts` | 11 | Wrapper react-hot-toast |
| `features/playlists/services/playlistService.ts` | 9 | API response casting |
| `utils/apiErrorHandler.ts` | 7 | Error type narrowing |
| `features/tracks/services/trackListService.ts` | 7 | API response casting |

### Configuration TypeScript

- **Mode strict complet** ✅ [tsconfig.json] : `strict: true`, `noImplicitAny`, `strictNullChecks`, `strictFunctionTypes`, `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch`
- **`noUncheckedIndexedAccess: true`** — option avancée ✅ (peu de projets l'activent)
- **`@typescript-eslint/no-explicit-any: off`** — ESLint n'interdit pas `any` ⚠️

**Verdict TS** : Configuration stricte exemplaire mais `no-explicit-any` désactivé dans ESLint permet l'accumulation de `any`. Le comptage (~82 source + ~180 `as any`) est modéré pour un projet de 218K LOC.

---

## H6. Code mort

### Orphelins structurels identifiés

| Fichier/Dossier | Raison | Impact |
|----------------|--------|--------|
| `pages/auth/Login.tsx`, `pages/auth/Register.tsx` | Remplacés par `features/auth/pages/` | 🟡 Dead code |
| `context/AuthContext.tsx` | Remplacé par `features/auth/store/authStore.ts` | 🟠 Source de confusion |
| `providers/AuthProvider.tsx` | Wrapper de AuthContext — non utilisé dans App.tsx | 🟡 Dead code |
| `components/views/*.tsx` (fichiers plats) | Wrappers vers les sous-dossiers refactorés | 🟡 Indirection inutile |
| `ui/dropdown-menu.tsx`, `ui/tabs.tsx`, `ui/accordion.tsx` (plats) | Re-exports vers les dossiers refactorés | 🟢 Acceptable |

### Recommandation

Exécuter `npx ts-prune` ou `npx madge --extensions ts,tsx --circular src/` pour un rapport complet d'orphelins et de dépendances circulaires.

---

## H7. Dépendances inutilisées

### Potentiellement inutilisées

| Dépendance | Status | Raison |
|-----------|--------|--------|
| `@dnd-kit/utilities` | ⚠️ À vérifier | Peut être importé indirectement par `@dnd-kit/sortable` |
| `swagger-ui-dist` | ⚠️ À vérifier | `swagger-ui-react` pourrait l'importer en interne |
| `rollup-plugin-visualizer` | ✅ OK | Utilisé dans vite.config.ts (pas dans src/) |

[DONNÉES INSUFFISANTES — nécessite `npx depcheck` pour un rapport exhaustif]

---

## Priorisation de la dette

| Priorité | Élément | Impact | Effort | Ratio |
|----------|---------|--------|--------|-------|
| P0 | Split `client.ts` (2237L) | Maintenabilité, testabilité | L | Élevé |
| P0 | Résoudre dualité AuthContext vs authStore | Bugs auth, confusion | M | Très élevé |
| P1 | Supprimer `pages/auth/` legacy | Clarté code | S | Élevé |
| P1 | Unifier toast API (addToast vs toast) | Cohérence DX | M | Élevé |
| P1 | Split `usePlaylist.ts` (631L) | Maintenabilité | M | Moyen |
| P1 | Résoudre layout/Sidebar vs ui/Sidebar | Clarté | S | Élevé |
| P2 | Migrer z-[N] vers tokens SUMI | Cohérence design | M | Moyen |
| P2 | Ajouter `React.memo` sur les composants de liste | Performance | S | Moyen |
| P2 | Réduire `as any` dans client.ts (48 occ.) | Type safety | L | Faible |
| P2 | Nettoyer components/views/ wrappers legacy | Clarté | M | Moyen |

**Score dette technique implicite : 6/10** — Dette structurelle significative (migration incomplète) mais codebase fonctionnelle avec de bons patterns.