# TowerControl v2.0 🗼

**Gestionnaire de tâches moderne et minimaliste** - Interface Kanban avec intégrations Jira et Daily notes

---

## 🚀 Vue d'ensemble

TowerControl est un gestionnaire de tâches **standalone** conçu pour les développeurs et équipes tech. Il combine la simplicité d'un Kanban local avec la puissance des intégrations externes (Jira) et un système de daily notes pour le suivi quotidien.

### 🎯 Philosophie

- **Local first** : Base SQLite, pas de cloud requis
- **Architecture moderne** : Next.js 15 + React 19 + TypeScript + Prisma
- **Design minimaliste** : Interface dark/light avec focus sur la productivité
- **Intégrations intelligentes** : Sync unidirectionnelle Jira sans pollution

---

## ✨ Fonctionnalités principales

### 🏗️ Kanban moderne

- **Drag & drop fluide** avec @dnd-kit (optimistic updates)
- **Colonnes configurables** : backlog, todo, in_progress, done, cancelled, freeze, archived
- **Vues multiples** : Kanban classique + swimlanes par priorité
- **Édition inline** : Clic sur titre → édition directe
- **Création rapide** : Ajout inline dans chaque colonne

### 🏷️ Système de tags avancé

- **Tags colorés** avec sélecteur de couleur
- **Autocomplete intelligent** lors de la saisie
- **Filtrage en temps réel** par tags
- **Gestion complète** avec page dédiée `/tags`

### 📊 Filtrage et recherche

- **Recherche temps réel** dans les titres et descriptions
- **Filtres combinables** : statut, priorité, tags, source
- **Tri flexible** : date, priorité, alphabétique
- **Interface intuitive** avec dropdowns et toggles

### 📝 Daily Notes

- **Checkboxes quotidiennes** avec sections "Hier" / "Aujourd'hui"
- **Navigation par date** (précédent/suivant)
- **Liaison optionnelle** avec les tâches existantes
- **Auto-création** du daily du jour
- **Historique calendaire** des dailies

### 🔗 Intégration Jira Cloud

- **Synchronisation unidirectionnelle** (Jira → local)
- **Authentification sécurisée** (email + API token)
- **Mapping intelligent** des statuts Jira
- **Style visuel distinct** pour les tâches Jira
- **Gestion des conflits** : préservation des modifications locales
- **Interface de configuration** complète

### 🎨 Interface & UX

- **Thème adaptatif** : dark/light + détection système
- **Design cohérent** : palette cyberpunk/tech avec Tailwind CSS
- **Composants modulaires** : Button, Input, Card, Modal, Badge
- **Loading states** optimisés avec Server Actions
- **Responsive design** pour tous les écrans

### ⚡ Performance & Architecture

- **Server Actions** pour les mutations rapides (vs API routes)
- **Architecture SSR** avec hydratation optimisée
- **Base de données SQLite** ultra-rapide
- **Services layer** avec séparation claire des responsabilités
- **TypeScript strict** avec types partagés

---

## 🛠️ Installation

### Prérequis

- **Node.js** 18+
- **pnpm** 9+

### Installation locale

```bash
# Cloner le repository
git clone https://github.com/votre-repo/towercontrol.git
cd towercontrol

# Installer les dépendances
pnpm install

# Configurer la base de données
pnpm prisma generate
pnpm prisma db push

# (Optionnel) Ajouter des données de test
pnpm run seed

# Démarrer en développement
pnpm run dev
```

L'application sera accessible sur **http://localhost:3000**

### 🐳 Installation avec Docker (Recommandé)

Pour un déploiement rapide en production ou pour isoler l'environnement :

```bash
# Cloner le repository
git clone https://github.com/votre-repo/towercontrol.git
cd towercontrol

# Démarrer en production (port 3006)
docker compose up -d

# Ou démarrer en mode développement (port 3005)
docker compose --profile dev up -d
```

**Accès :**

- **Production** : http://localhost:3006
- **Développement** : http://localhost:3005

**Gestion des données :**

```bash
# Utiliser votre base locale existante (décommentez dans docker-compose.yml)
# - ./prisma/dev.db:/app/data/prod.db

# Accéder aux logs
docker compose logs -f towercontrol

# Arrêter les services
docker compose down

# Supprimer tout (données incluses)
docker compose down -v
```

**Avantages Docker :**

- ✅ **Isolation complète** - Pas de pollution de l'environnement local
- ✅ **Base persistante** - Volumes Docker pour SQLite
- ✅ **Prêt pour prod** - Configuration optimisée
- ✅ **Healthcheck intégré** - Monitoring automatique
- ✅ **Hot-reload** - Mode dev avec synchronisation du code

### Configuration des variables d'environnement

Copiez le fichier d'exemple et configurez selon vos besoins :

```bash
cp env.example .env.local
```

Variables principales :

```bash
# Base de données (requis)
DATABASE_URL="file:./dev.db"

# Jira (optionnel - pour l'intégration)
JIRA_BASE_URL="https://votre-domaine.atlassian.net"
JIRA_EMAIL="votre.email@domaine.com"
JIRA_API_TOKEN="votre_token_api"
```

### Configuration Jira (optionnel)

1. **Générer un token API** :
   - Aller sur https://id.atlassian.com/manage-profile/security/api-tokens
   - Créer un nouveau token API
   - Copier le token généré

2. **Configurer dans l'app** :
   - Aller dans Settings → Jira Configuration
   - Saisir : URL de base, email, token API
   - Tester la connexion
   - Lancer une synchronisation manuelle

---

## 🏗️ Architecture

### Structure du projet

```
towercontrol/
├── src/
│   ├── app/                    # Next.js 15 App Router (pages & routes)
│   │   ├── api/               # API Routes (endpoints complexes)
│   │   │   ├── 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)
│   │   ├── 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
- **Backend** : Next.js API Routes + Server Actions, Prisma ORM
- **Base de données** : SQLite (local) → PostgreSQL (production future)
- **UI/UX** : Drag & drop (@dnd-kit), composants custom
- **Intégrations** : Jira Cloud API REST

### Principes architecturaux

1. **Séparation des responsabilités** :
   - `services/` : Toute la logique métier et accès BDD
   - `components/` : Uniquement présentation et UI
   - `clients/` : Communication HTTP avec les APIs

2. **Server Actions vs API Routes** :
   - **Server Actions** : Mutations simples et fréquentes (CRUD rapide)
   - **API Routes** : Endpoints complexes et intégrations externes

3. **Types centralisés** : `lib/types.ts` pour la cohérence

---

## 🎮 Utilisation

### Démarrage rapide

1. **Créer une tâche** :
   - Clic sur `+ Ajouter` dans une colonne
   - Ou bouton `+ Nouvelle tâche` global

2. **Organiser les tâches** :
   - Drag & drop entre colonnes pour changer le statut
   - Édition inline : clic sur le titre
   - Tags : saisie avec autocomplete

3. **Filtrer et rechercher** :
   - Barre de recherche globale
   - Filtres par statut, priorité, tags
   - Tri par date, priorité, alphabétique

4. **Daily notes** :
   - Page `/daily` pour les notes quotidiennes
   - Checkboxes "Hier" / "Aujourd'hui"
   - Navigation par date

5. **Intégration Jira** :
   - Configuration dans `/settings`
   - Synchronisation manuelle
   - Tâches Jira avec bordure distinctive

### Scripts disponibles

```bash
# Développement
pnpm run dev              # Démarrer en mode dev avec Turbopack
pnpm run build           # Build de production
pnpm run start           # Démarrer en production

# Base de données
pnpm prisma studio       # Interface graphique BDD
pnpm prisma generate     # Regénérer le client Prisma
pnpm prisma db push      # Appliquer le schema à la BDD
pnpm prisma migrate dev  # Créer une migration

# Qualité de code
pnpm run lint            # ESLint + Prettier
pnpm tsc --noEmit       # Vérification TypeScript

# Scripts utilitaires
pnpm run seed           # Ajouter des données de test
```

---

## 🔧 Configuration avancée

### Thèmes et interface

```typescript
// lib/config.ts
export const UI_CONFIG = {
  theme: 'system', // 'light' | 'dark' | 'system'
  itemsPerPage: 50, // Pagination
  enableDragAndDrop: true, // Drag & drop
  autoSave: true, // Sauvegarde auto
};
```

### Personnalisation des colonnes

Modifiez `lib/status-config.ts` pour adapter les colonnes Kanban :

```typescript
export const TASK_STATUSES = [
  { key: 'backlog', label: 'Backlog', color: 'gray' },
  { key: 'todo', label: 'À faire', color: 'blue' },
  // ... ajouter vos statuts
];
```

### Base de données

Par défaut SQLite local (`dev.db`). Pour PostgreSQL :

```bash
# .env.local
DATABASE_URL="postgresql://user:pass@localhost:5432/towercontrol"
```

---

## 🚧 Roadmap

### ✅ Version 2.0 (Actuelle)

- Interface Kanban moderne avec drag & drop
- Système de tags avancé
- Daily notes avec navigation
- Intégration Jira Cloud complète
- Thèmes dark/light
- Server Actions pour les performances

### 🔄 Version 2.1 (En cours)

- [ ] Page dashboard avec analytics
- [ ] Système de sauvegarde automatique (configurable)
- [ ] Métriques de productivité et graphiques
- [ ] Actions en lot (sélection multiple)

### 🎯 Version 2.2 (Futur)

- [ ] Sous-tâches et hiérarchie
- [ ] Dates d'échéance et rappels
- [ ] Collaboration et assignation
- [ ] Templates de tâches
- [ ] Mode PWA et offline

### 🚀 Version 3.0 (Vision)

- [ ] Analytics d'équipe avancées
- [ ] Intégrations multiples (GitHub, Linear, etc.)
- [ ] API publique et webhooks
- [ ] Notifications push et real-time

---

## 🤝 Contribution

### Guide de développement

1. **Fork** le repository
2. **Créer une branche** feature : `git checkout -b feature/ma-feature`
3. **Respecter l'architecture** : services → clients → components
4. **Tests** : Assurer la qualité avec lint + TypeScript
5. **Commit** avec convention : `feat: description de la feature`
6. **Pull Request** avec description détaillée

### Standards de code

- **TypeScript strict** obligatoire
- **ESLint + Prettier** configurés
- **Séparation des responsabilités** : pas de logique métier dans les composants
- **Naming convention** : camelCase pour les variables, PascalCase pour les composants

---

## 📄 Licence

MIT License - Voir le fichier [LICENSE](LICENSE) pour plus de détails.

---

## 🙏 Remerciements

- **Next.js** pour le framework moderne
- **Prisma** pour l'ORM élégant
- **@dnd-kit** pour le drag & drop fluide
- **Tailwind CSS** pour le styling rapide
- **Jira API** pour l'intégration robuste

---

**Développé avec ❤️ pour optimiser la productivité des équipes tech**