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

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

1.2 Page de configuration du compte

• Page: /accounts/settings — config du profil
• Section: Profil (nom, email, avatar, mot de passe)
• Section: Connexions forges (Gitea, GitHub) — lier/délier
• 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

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

---

Phase 2 — Abstraction Multi-Forge

2.1 Adapter pattern pour les forges

• 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
• Implement: GiteaAdapter (API Gitea existante → interface unifiée)
• Implement: GitHubAdapter (API GitHub v3 → interface unifiée)
• DB: Table forge_connections (user_id, provider, token_id, instance_url)
• Config: Support GitHub Enterprise (custom URL) et Gitea self-hosted

2.2 Synchronisation des projets

• 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)
• Page: /workspace — liste TOUS les projets (built-in + Gitea + GitHub)

---

Phase 3 — Workspace & Navigation

3.1 Nouvelle page Workspace

• 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"
• Filtres: Par forge, par statut, recherche
• Carte projet: Nom, description, forge badge, dernière activité, nombre de pages

3.2 Barre de navigation projet

• Topbar: Section entre "Meetings" et la sidebar
  • Nom du projet actif (dropdown pour switcher)
  • Badge forge (icône Gitea/GitHub/built-in)
• 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
• Service: FileTreeService — construit l'arborescence depuis l'API forge
• Cache: Arborescence en cache (TTL 5 min) pour éviter les appels API à chaque page

3.3 Navigation projet

• Sidebar: Les projets apparaissent sous une section dédiée
• Breadcrumb: Workspace > Projet > Dossier > Page
• 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

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

4.2 Mode hybride

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

---

Phase 5 — Permissions & Collaboratif

5.1 Rôles workspace

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

5.2 Partage de pages

• Étendre le système Share existant pour supporter les permissions workspace
• Une page dans un workspace est visible par tous les membres
• "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