flowdeck/docs/ROADMAP.md

# ROADMAP — FlowDeck v3.0 : Multi-User, Multi-Forge, Standalone

> **Début**: 2026-07-10 | **Cible**: v3.0 | **Auteur**: Bruno + Hermes-Deepin
> **Objectif**: Transformer FlowDeck d'un outil personnel lié à Gitea en une plateforme collaborative multi-utilisateur, multi-forge (Gitea/GitHub), fonctionnant avec ou sans forge Git.

---

## Vue d'ensemble

```
┌─────────────────────────────────────────────────────────────┐
│                     FLOWDECK v3.0                            │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌────────────────────────┐    │
│  │ Comptes  │  │ Forges   │  │ Workspaces & Projets    │    │
│  │ locaux   │  │ Gitea    │  │ (built-in, Gitea,       │    │
│  │ + OAuth  │  │ GitHub   │  │  GitHub)                │    │
│  └──────────┘  └──────────┘  └────────────────────────┘    │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ Navigation: Topbar avec arborescence projet         │    │
│  │ [Workspace] [Projet ▾] [Meetings] [Shared]          │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

---

## Phase 1 — Authentification Multi-Mode

### 1.1 Comptes locaux avec mot de passe
- [x] **DB**: Ajouter `password_hash` (hash) à la table `users`
- [x] **DB**: Ajouter `is_active`, `is_admin`, `last_login`, `login_attempts`, `locked_until`
- [x] **API**: `POST /auth/register` — création de compte local (email + password)
- [x] **API**: `POST /auth/login` — login local (email + password → session)
- [x] **Page**: `/login` — formulaire login/register
- [x] **Sécurité**: Rate limiting (5 tentatives → lock 15 min)
- [x] **Sécurité**: CSRF sur toutes les routes auth
- [x] **Session**: Détachée de Gitea — session valide sans OAuth

### 1.2 Page de configuration du compte
- [x] **Page**: `/accounts/settings` — config du profil
- [x] **Section**: Profil (nom, email, avatar, mot de passe)
- [x] **Section**: Connexions forges (Gitea, GitHub) — lier/délier
- [x] **Section**: Préférences (langue, thème, notifs)
- [ ] **Section**: Tokens API (générer/révoquer des clés API)
- [ ] **Section**: Sessions actives (voir et révoquer)

### 1.3 OAuth multi-forge
- [x] **Refactor**: `GiteaOAuth` → `OAuthProvider` (classe abstraite)
- [ ] **Implement**: `GitHubOAuthProvider` (OAuth2 GitHub)
- [x] **Implement**: `GiteaOAuthProvider` (existant, refactoré)
- [x] **DB**: Table `user_oauth_tokens` (user_id, provider, access_token, refresh_token, expires_at)
- [x] **API**: `GET /auth/{provider}/login` — redirige vers OAuth
- [x] **API**: `GET /auth/{provider}/callback` — callback OAuth
- [x] **Page**: `/accounts/settings` → boutons "Connect GitHub" / "Connect Gitea"
- [x] **Fallback**: L'utilisateur peut utiliser FlowDeck SANS lier aucune forge

---

## Phase 2 — Abstraction Multi-Forge

### 2.1 Adapter pattern pour les forges
- [x] **Interface**: `ForgeAdapter` (classe abstraite)
  - `list_repos(token) → List[Repo]`
  - `get_repo(token, owner, repo) → RepoDetail`
  - `list_issues(token, owner, repo) → List[Issue]`
  - `get_file_tree(token, owner, repo, path) → TreeNode`
  - `get_file_content(token, owner, repo, path) → str`
  - `create_webhook(token, owner, repo, url) → Webhook`
- [x] **Implement**: `GiteaAdapter` (API Gitea existante → interface unifiée)
- [ ] **Implement**: `GitHubAdapter` (API GitHub v3 → interface unifiée)
- [x] **DB**: Table `forge_connections` (user_id, provider, token_id, instance_url)
- [x] **Config**: Support GitHub Enterprise (custom URL) et Gitea self-hosted

### 2.2 Synchronisation des projets
- [x] **Service**: `ProjectSyncService` — sync projets depuis les forges liées
- [ ] **DB**: Table `projects` avec type (`builtin`, `gitea`, `github`)
- [ ] **DB**: `projects.forge_id` — référence externe (repo ID)
- [ ] **DB**: `projects.clone_url`, `projects.default_branch`, `projects.language`
- [ ] **Cron**: Sync périodique des projets (configurable, défaut: chaque heure)
- [x] **Page**: `/workspace` — liste TOUS les projets (built-in + Gitea + GitHub)

---

## Phase 3 — Workspace & Navigation

### 3.1 Nouvelle page Workspace
- [x] **Page**: `/workspace` — dashboard central
  - Section "My Projects" (built-in)
  - Section "Gitea Projects" (si connecté)
  - Section "GitHub Projects" (si connecté)
  - Bouton "Create Project" (built-in)
  - Bouton "Import from Gitea/GitHub"
- [x] **Filtres**: Par forge, par statut, recherche
- [x] **Carte projet**: Nom, description, forge badge, dernière activité, nombre de pages

### 3.2 Barre de navigation projet
- [x] **Topbar**: Section entre "Meetings" et la sidebar
  - Nom du projet actif (dropdown pour switcher)
  - Badge forge (icône Gitea/GitHub/built-in)
- [x] **Arborescence**: Sous le projet dans la sidebar gauche
  - Dossiers et fichiers du repo Git (lecture seule si forge externe)
  - Pages FlowDeck liées au projet
  - Bouton "+" pour créer nouvelle page dans le projet
- [x] **Service**: `FileTreeService` — construit l'arborescence depuis l'API forge
- [x] **Cache**: Arborescence en cache (TTL 5 min) pour éviter les appels API à chaque page

### 3.3 Navigation projet
- [x] **Sidebar**: Les projets apparaissent sous une section dédiée
- [x] **Breadcrumb**: Workspace > Projet > Dossier > Page
- [x] **Contexte projet**: Toute nouvelle page créée depuis un projet y est liée
- [ ] **Quick switch**: Ctrl+K → chercher et switcher de projet

---

## Phase 4 — Fonctionnement sans forge

### 4.1 Mode standalone
- [x] **Config**: `FLOWDECK_STANDALONE=true` — démarre sans aucune forge
- [x] **UI**: Pas de sections Gitea/GitHub si non configuré
- [x] **Workspace**: Uniquement projets built-in
- [x] **Auth**: Login local uniquement (pas de boutons OAuth)
- [x] **Pages**: Création/édition 100% locale, pas de synchro externe

### 4.2 Mode hybride
- [x] Un utilisateur peut avoir Gitea lié, un autre GitHub, un troisième rien
- [x] Chaque utilisateur voit SES projets de forge dans SA workspace
- [x] Les projets built-in sont partagés selon les permissions workspace

---

## Phase 5 — Permissions & Collaboratif

### 5.1 Rôles workspace
- [x] **DB**: Table `workspace_members` avec rôles: owner, admin, editor, viewer
- [x] **API**: `POST /workspace/{id}/members` — inviter un utilisateur
- [x] **API**: `DELETE /workspace/{id}/members/{user_id}` — retirer
- [x] **API**: `PUT /workspace/{id}/members/{user_id}` — changer rôle
- [x] **Middleware**: `PermissionMiddleware` — vérifie les droits avant chaque action

### 5.2 Partage de pages
- [x] Étendre le système Share existant pour supporter les permissions workspace
- [x] Une page dans un workspace est visible par tous les membres
- [x] "Anyone with the link" crée un lien public indépendant du workspace

---

## Phase 6 — UI/UX Polishing

### 6.1 Design system
- [ ] Unifier les couleurs, espacements, typographie dans un fichier `design-tokens.css`
- [ ] Composants réutilisables: boutons, inputs, modales, dropdowns, toasts
- [ ] Responsive: adapter la sidebar et topbar pour écrans < 1024px

### 6.2 Onboarding
- [ ] Page `/welcome` au premier lancement
- [ ] Wizard: créer compte → lier forges (optionnel) → créer premier projet
- [ ] Templates de projets (vide, kanban, wiki, documentation)

---

## Phase 7 — Infrastructure

### 7.1 Base de données
- [ ] Migrations versionnées (Alembic ou script maison avec table `schema_version`)
- [ ] Backup automatique (cron daily → fichier daté)
- [ ] Index manquants (users.email, projects.forge_id, forge_connections.user_id)

### 7.2 Tests
- [ ] Tests d'intégration auth (login local, OAuth mock)
- [ ] Tests des adapters forge (mock HTTP responses)
- [ ] Tests multi-user (2 utilisateurs, permissions croisées)
- [ ] Tests standalone (sans forge configurée)
- [ ] Cible: 100+ tests

### 7.3 CI/CD
- [ ] Linting (ruff, eslint)
- [ ] Tests parallèles (pytest-xdist)
- [ ] Build Docker multi-stage (optimiser la taille d'image)

---

## Dépendances et points critiques

| Dépendance | Impact | Bloque |
|-----------|--------|--------|
| **Auth locale** | Fondation — tout le reste en dépend | Phases 2-7 |
| **Abstraction forge** | Permet GitHub + standalone | Phases 3-4 |
| **Permission system** | Nécessaire pour le multi-user réel | Phase 5 |
| **Migration DB** | Les données existantes doivent survivre | Phase 1 |
| **Session refactor** | Actuellement couplée à Gitea OAuth | Phase 1 |

---

## Chronologie estimée

| Phase | Effort | Priorité |
|-------|--------|----------|
| Phase 1 — Auth | 🔴🔴🔴 | Critique |
| Phase 2 — Multi-forge | 🔴🔴 | Haute |
| Phase 3 — Workspace/Nav | 🔴🔴 | Haute |
| Phase 4 — Standalone | 🔴 | Moyenne |
| Phase 5 — Permissions | 🔴🔴 | Haute |
| Phase 6 — UI/UX | 🔴 | Moyenne |
| Phase 7 — Infra | 🔴 | Continue |

---

*Dernière mise à jour: 2026-07-13 — phases 1-5 majoritairement complétées*