chore(README): enhance project structure documentation and clarify folder purposes

- Updated README.md to provide a detailed explanation of the project structure, including descriptions for each directory and its contents. - Improved clarity on the organization of Next.js pages, API routes, components, services, and utilities.
2025-11-05 08:05:13 +01:00
parent 9fc355abad
commit 2d4c161e1d
3 changed files with 200 additions and 34 deletions
--- a/README.md
+++ b/README.md
@@ -193,31 +193,204 @@ JIRA_API_TOKEN="votre_token_api"
 ```
 towercontrol/
 ├── src/
-│   ├── app/                    # Pages Next.js 15 (App Router)
+│   ├── app/                    # Next.js 15 App Router (pages & routes)
 │   │   ├── api/               # API Routes (endpoints complexes)
-│   │   ├── daily/             # Page daily notes
-│   │   ├── tags/              # Page gestion tags
-│   │   └── settings/          # Page configuration
+│   │   │   ├── analytics/     # Endpoints d'analytics
+│   │   │   ├── auth/          # Authentification (NextAuth)
+│   │   │   ├── backups/       # Gestion des sauvegardes
+│   │   │   ├── daily/         # API daily notes
+│   │   │   ├── jira/          # API intégration Jira
+│   │   │   ├── notes/         # API notes markdown
+│   │   │   ├── tags/          # API gestion tags
+│   │   │   ├── tasks/         # API tâches
+│   │   │   ├── tfs/           # API intégration TFS
+│   │   │   └── user-preferences/ # API préférences utilisateur
+│   │   ├── daily/             # Page daily notes (/daily)
+│   │   ├── jira-dashboard/    # Dashboard Jira (/jira-dashboard)
+│   │   ├── kanban/            # Page Kanban (/kanban)
+│   │   ├── manager/           # Page manager
+│   │   ├── notes/             # Page notes (/notes)
+│   │   ├── profile/           # Page profil utilisateur
+│   │   ├── settings/          # Page configuration (/settings)
+│   │   │   ├── advanced/      # Paramètres avancés
+│   │   │   ├── backup/        # Gestion backups
+│   │   │   ├── general/       # Paramètres généraux
+│   │   │   └── integrations/  # Config intégrations
+│   │   ├── weekly-manager/    # Page weekly manager
+│   │   ├── layout.tsx         # Layout principal
+│   │   ├── page.tsx           # Page d'accueil (/)
+│   │   └── globals.css        # Styles globaux + variables CSS
+│   │
 │   ├── actions/               # Server Actions (mutations rapides)
-│   └── contexts/              # Contexts React globaux
-├── components/
-│   ├── ui/                    # Composants UI de base
-│   ├── kanban/               # Composants Kanban
-│   ├── daily/                # Composants Daily notes
-│   └── forms/                # Formulaires réutilisables
-├── services/                  # Services backend (logique métier)
-│   ├── database.ts           # Pool Prisma
-│   ├── tasks.ts              # CRUD tâches
-│   ├── tags.ts               # CRUD tags
-│   ├── daily.ts              # Daily notes
-│   ├── jira.ts               # Intégration Jira
-│   └── user-preferences.ts   # Préférences utilisateur
-├── clients/                   # Clients HTTP frontend
-├── hooks/                     # Hooks React personnalisés
-├── lib/                       # Utilitaires et types
-└── prisma/                    # Schéma et migrations DB
+│   │   ├── backup.ts         # Actions sauvegardes
+│   │   ├── daily.ts          # Actions daily notes
+│   │   ├── jira-analytics.ts # Actions analytics Jira
+│   │   ├── preferences.ts    # Actions préférences
+│   │   ├── tags.ts           # Actions tags
+│   │   ├── tasks.ts          # Actions tâches
+│   │   └── tfs.ts            # Actions TFS
+│   │
+│   ├── components/            # Composants React (UI uniquement)
+│   │   ├── ui/               # Composants UI de base réutilisables
+│   │   │   ├── Button.tsx    # Boutons
+│   │   │   ├── Input.tsx     # Inputs
+│   │   │   ├── Modal.tsx     # Modales
+│   │   │   ├── Badge.tsx     # Badges
+│   │   │   ├── Card.tsx      # Cartes
+│   │   │   └── ...           # Autres composants UI
+│   │   ├── kanban/           # Composants Kanban spécifiques
+│   │   │   ├── Board.tsx     # Board principal
+│   │   │   ├── Column.tsx    # Colonne Kanban
+│   │   │   ├── TaskCard.tsx  # Carte de tâche
+│   │   │   ├── filters/      # Composants de filtrage
+│   │   │   └── ...           # Autres composants Kanban
+│   │   ├── daily/            # Composants Daily notes
+│   │   ├── dashboard/        # Composants dashboard
+│   │   ├── forms/            # Formulaires réutilisables
+│   │   ├── jira/             # Composants intégration Jira
+│   │   ├── settings/         # Composants paramètres
+│   │   └── charts/           # Composants graphiques
+│   │
+│   ├── services/              # Services backend (logique métier)
+│   │   ├── core/             # Services core
+│   │   │   ├── database.ts   # Pool Prisma (unique point d'accès DB)
+│   │   │   ├── system-info.ts # Infos système
+│   │   │   └── user-preferences.ts # Préférences utilisateur
+│   │   ├── task-management/  # Gestion des tâches
+│   │   │   ├── tasks.ts      # CRUD tâches
+│   │   │   ├── tags.ts       # CRUD tags
+│   │   │   └── daily.ts      # Daily notes
+│   │   ├── integrations/     # Intégrations externes
+│   │   │   ├── jira/         # Intégration Jira
+│   │   │   │   ├── jira.ts   # Client Jira API
+│   │   │   │   ├── analytics.ts # Analytics Jira
+│   │   │   │   ├── scheduler.ts # Planification sync
+│   │   │   │   └── ...       # Autres services Jira
+│   │   │   └── tfs/          # Intégration TFS
+│   │   ├── analytics/        # Services d'analytics
+│   │   │   ├── analytics.ts  # Analytics générales
+│   │   │   ├── metrics.ts    # Métriques
+│   │   │   └── ...           # Autres analytics
+│   │   └── data-management/  # Gestion des données
+│   │       ├── backup.ts     # Sauvegardes
+│   │       └── backup-scheduler.ts # Planification backups
+│   │
+│   ├── clients/              # Clients HTTP frontend
+│   │   ├── base/             # Client HTTP de base
+│   │   │   └── http-client.ts # Client HTTP réutilisable
+│   │   ├── tasks-client.ts   # Client API tâches
+│   │   ├── tags-client.ts    # Client API tags
+│   │   ├── daily-client.ts   # Client API daily
+│   │   ├── jira-client.ts    # Client API Jira
+│   │   └── backup-client.ts  # Client API backups
+│   │
+│   ├── hooks/                # Hooks React personnalisés
+│   │   ├── useTasks.ts       # Hook gestion tâches
+│   │   ├── useTags.ts        # Hook gestion tags
+│   │   ├── useDaily.ts       # Hook daily notes
+│   │   ├── useDragAndDrop.ts # Hook drag & drop
+│   │   └── ...               # Autres hooks
+│   │
+│   ├── contexts/             # Contexts React globaux
+│   │   ├── ThemeContext.tsx  # Gestion thème dark/light
+│   │   ├── TasksContext.tsx  # Context tâches
+│   │   ├── UserPreferencesContext.tsx # Préférences utilisateur
+│   │   └── ...               # Autres contexts
+│   │
+│   ├── lib/                  # Utilitaires et configuration
+│   │   ├── types.ts          # Types TypeScript partagés
+│   │   ├── utils.ts          # Fonctions utilitaires
+│   │   ├── config.ts         # Configuration app
+│   │   ├── status-config.ts  # Configuration statuts Kanban
+│   │   ├── tag-colors.ts     # Configuration couleurs tags
+│   │   └── ...               # Autres utilitaires
+│   │
+│   ├── types/                # Types TypeScript spécifiques
+│   │   └── next-auth.d.ts    # Types NextAuth
+│   │
+│   └── middleware.ts         # Middleware Next.js (auth, etc.)
+│
+├── prisma/                   # Prisma ORM
+│   ├── schema.prisma         # Schéma de base de données
+│   └── migrations/           # Migrations SQL
+│
+├── scripts/                  # Scripts utilitaires
+│   ├── backup-manager.ts     # Gestion backups
+│   ├── seed-data.ts          # Données de test
+│   └── ...                   # Autres scripts
+│
+├── public/                   # Assets statiques
+│   └── icons/                # Icônes
+│
+├── data/                     # Données locales
+│   ├── dev.db               # Base SQLite développement
+│   ├── prod.db              # Base SQLite production
+│   └── backups/             # Sauvegardes automatiques
+│
+└── [fichiers racine]         # Config projet (package.json, etc.)
 ```

+### Explication détaillée des dossiers
+
+#### 📁 `src/app/` - Pages et routes Next.js
+
+- **Pages publiques** : Routes Next.js qui génèrent les pages (`page.tsx`)
+- **API Routes** : Endpoints HTTP dans `/api` pour les opérations complexes
+- **Client Components** : Composants client séparés (`*PageClient.tsx`) pour l'hydratation
+- **Layout** : Layout global avec providers (Theme, Auth, etc.)
+
+#### 📁 `src/actions/` - Server Actions
+
+- **Mutations rapides** : Actions serveur pour les mutations simples (CRUD)
+- **Cache intelligent** : Révalidation automatique avec `revalidatePath()`
+- **UX optimisée** : Utilisation avec `useTransition` pour les états de chargement
+
+#### 📁 `src/components/` - Composants React (UI uniquement)
+
+- **Règle stricte** : AUCUNE logique métier, uniquement présentation
+- **Organisation par domaine** : `kanban/`, `daily/`, `jira/`, etc.
+- **Composants UI réutilisables** : Dans `ui/` pour la cohérence visuelle
+- **Formulaires** : Dans `forms/` pour la réutilisation
+
+#### 📁 `src/services/` - Logique métier backend
+
+- **Point unique d'accès DB** : `core/database.ts` (Pool Prisma)
+- **Séparation par domaine** : `task-management/`, `integrations/`, `analytics/`
+- **Règle stricte** : TOUTE la logique métier ici, jamais dans les composants
+- **Services métier** : CRUD, calculs, validations, intégrations externes
+
+#### 📁 `src/clients/` - Clients HTTP frontend
+
+- **Client HTTP de base** : `base/http-client.ts` avec gestion erreurs/tokens
+- **Clients par domaine** : Un client par API (tasks, tags, jira, etc.)
+- **Règle stricte** : Uniquement requêtes HTTP, pas de logique métier
+
+#### 📁 `src/hooks/` - Hooks React personnalisés
+
+- **Orchestration UI** : Gestion état React, appels API via clients
+- **Logique UI uniquement** : Pas de logique métier, uniquement coordination
+
+#### 📁 `src/contexts/` - Contexts React globaux
+
+- **État global** : Thème, préférences, tâches, etc.
+- **Providers** : Utilisés dans le layout principal
+
+#### 📁 `src/lib/` - Utilitaires et configuration
+
+- **Types partagés** : `types.ts` pour la cohérence TypeScript
+- **Configurations** : Statuts Kanban, couleurs tags, etc.
+- **Helpers** : Fonctions utilitaires (dates, formatting, etc.)
+
+#### 📁 `prisma/` - Base de données
+
+- **Schéma** : Définition des modèles (`schema.prisma`)
+- **Migrations** : Historique des changements de schéma
+
+#### 📁 `scripts/` - Scripts utilitaires
+
+- **Opérations** : Backups, seeding, maintenance
+- **Exécution** : Via `pnpm run <script-name>`
+
 ### Stack technique

 - **Frontend** : Next.js 15, React 19, TypeScript, Tailwind CSS
--- a/src/components/ui/PriorityBadge.tsx
+++ b/src/components/ui/PriorityBadge.tsx
@@ -3,7 +3,7 @@
 import { getPriorityConfig } from '@/lib/status-config';

 interface PriorityBadgeProps {
-  priority: 'low' | 'medium' | 'high';
+  priority: 'low' | 'medium' | 'high' | 'urgent';
  className?: string;
 }

--- a/src/components/ui/TaskCard.tsx
+++ b/src/components/ui/TaskCard.tsx
@@ -6,6 +6,8 @@ import { TagDisplay } from './TagDisplay';
 import { formatDateForDisplay } from '@/lib/date-utils';
 import emojiRegex from 'emoji-regex';
 import { getTaskEmoji } from '@/lib/task-emoji';
+import { getPriorityColor, getPriorityColorHex } from '@/lib/status-config';
+import type { TaskPriority } from '@/lib/types';

 interface TaskCardProps extends HTMLAttributes<HTMLDivElement> {
  // Variants
@@ -206,17 +208,6 @@ const TaskCard = forwardRef<HTMLDivElement, TaskCardProps>(
      return {};
    };

-    // Couleurs de priorité
-    const getPriorityColor = (priority: string) => {
-      const colors = {
-        low: '#10b981', // green
-        medium: '#f59e0b', // amber
-        high: '#ef4444', // red
-        urgent: '#dc2626', // red-600
-      };
-      return colors[priority as keyof typeof colors] || colors.medium;
-    };
-
    // Utiliser getTaskEmoji avec les propriétés de la tâche disponibles
    const taskEmoji = getTaskEmoji(
      {
@@ -234,7 +225,9 @@ const TaskCard = forwardRef<HTMLDivElement, TaskCardProps>(
    const titleWithoutEmojis = title.replace(emojiRegex(), '').trim();

    const sourceStyles = getSourceStyles();
-    const priorityColor = getPriorityColor(priority);
+    // Utiliser les fonctions de status-config pour obtenir la couleur de priorité correcte
+    const priorityColorValue = getPriorityColor(priority as TaskPriority);
+    const priorityColor = getPriorityColorHex(priorityColorValue);

    // Vue compacte
    if (variant === 'compact') {