feat: update README for TowerControl v2.0

- Revamped README to reflect the new version, including a comprehensive overview of features, installation instructions, and architecture details. - Added sections for Kanban functionality, advanced tagging system, daily notes, and Jira integration. - Included Docker installation instructions and environment variable configuration for enhanced usability. - Emphasized the project's modern tech stack and architectural principles.
2025-09-18 11:38:34 +02:00
parent 8c88322823
commit ec634add04
1 changed files with 377 additions and 20 deletions
--- a/README.md
+++ b/README.md
@@ -1,36 +1,393 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# TowerControl v2.0 🗼

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

-First, run the development server:
+---
+
+## 🚀 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+ 
+- **npm** ou **yarn**
+
+### Installation locale

 ```bash
+# Cloner le repository
+git clone https://github.com/votre-repo/towercontrol.git
+cd towercontrol
+
+# Installer les dépendances
+npm install
+
+# Configurer la base de données
+npx prisma generate
+npx prisma db push
+
+# (Optionnel) Ajouter des données de test
+npm run seed
+
+# Démarrer en développement
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
 ```

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+L'application sera accessible sur **http://localhost:3000**

-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+### 🐳 Installation avec Docker (Recommandé)

-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+Pour un déploiement rapide en production ou pour isoler l'environnement :

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

-To learn more about Next.js, take a look at the following resources:
+# Démarrer en production (port 3006)
+docker compose up -d

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+# Ou démarrer en mode développement (port 3005)
+docker compose --profile dev up -d
+```

-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+**Accès :**
+- **Production** : http://localhost:3006
+- **Développement** : http://localhost:3005

-## Deploy on Vercel
+**Gestion des données :**
+```bash
+# Utiliser votre base locale existante (décommentez dans docker-compose.yml)
+# - ./prisma/dev.db:/app/data/prod.db

-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+# Accéder aux logs
+docker compose logs -f towercontrol

-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+# 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"
+
+# Interface (optionnel)
+NEXT_PUBLIC_THEME="system"           # light | dark | system
+NEXT_PUBLIC_ITEMS_PER_PAGE="50"
+
+# 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/                    # Pages Next.js 15 (App Router)
+│   │   ├── api/               # API Routes (endpoints complexes)
+│   │   ├── daily/             # Page daily notes
+│   │   ├── tags/              # Page gestion tags
+│   │   └── settings/          # Page configuration
+│   ├── 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
+```
+
+### 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
+npm run dev              # Démarrer en mode dev avec Turbopack
+npm run build           # Build de production
+npm run start           # Démarrer en production
+
+# Base de données
+npx prisma studio       # Interface graphique BDD
+npx prisma generate     # Regénérer le client Prisma
+npx prisma db push      # Appliquer le schema à la BDD
+npx prisma migrate dev  # Créer une migration
+
+# Qualité de code
+npm run lint            # ESLint + Prettier
+npx tsc --noEmit       # Vérification TypeScript
+
+# Scripts utilitaires
+npm 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**