From 8eb704946035e3a9bfa0bf24f7d343c7d93d7aa6 Mon Sep 17 00:00:00 2001 From: bruno Date: Tue, 14 Jul 2026 12:07:13 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20ARCHITECTURE=20v3.0=20+=20ROADMAP=20v4.?= =?UTF-8?q?0=20=E2=80=94=20comptes,=20int=C3=A9grations,=20sidebar?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ARCHITECTURE.md: - Section 6.5: modèle de comptes (local/gitea/github) - Matrice d'intégrations & règles de déconnexion - 3 scénarios de workspace (A/B/C) - Sidebar: règles d'affichage par type de compte - Share & Publish: modale 2 tabs + schéma DB - Library: /library?tab= + filtres source - Trash local-only, édition unifiée, stockage Private - Plan de migration 5 phases ROADMAP.md: - v4.0.0 section prioritaire: Account Model, Intégrations, Sidebar rules, Share/Publish, Library, Édition unifiée --- ARCHITECTURE.md | 257 +++++++++++++++++++++++++++++++++++++++++++++++- ROADMAP.md | 41 ++++++++ 2 files changed, 295 insertions(+), 3 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 20f2168..83d6e1b 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,7 +1,7 @@ -# Architecture FlowDeck — Document Complet v2.0 +# Architecture FlowDeck — Document Complet v3.0 -> **Version:** 2.0 · **Date:** 2026-07-10 · **Auteur:** Hermes-Deepin -> **Cible:** Clone Notion intégré à Gitea avec support multi-utilisateurs +> **Version:** 3.0 · **Date:** 2026-07-14 · **Auteur:** Hermes-Deepin +> **Cible:** Clone Notion intégré à Gitea/GitHub — multi-comptes, multi-intégrations --- @@ -800,6 +800,257 @@ User authorize ──→ GET /auth/callback?code=xxx --- +## 6.5 Modèle de comptes & intégrations (v4.0) + +### 6.5.1 Types de comptes + +FlowDeck supporte 3 types de comptes, déterminés par `auth_method` dans la table `users` : + +``` +┌──────────────┬──────────────────┬─────────────────────────────────────┐ +│ auth_method │ Login via │ Identité dans le sidebar │ +├──────────────┼──────────────────┼─────────────────────────────────────┤ +│ local │ email + password │ Nom local (ex: "Draco") │ +│ gitea │ OAuth2 Gitea │ Nom Gitea + badge 🦎 Gitea │ +│ github │ OAuth2 GitHub │ Nom GitHub + badge 🐙 GitHub │ +└──────────────┴──────────────────┴─────────────────────────────────────┘ +``` + +**Règle fondamentale** : Un compte local avec intégration(s) reste un compte LOCAL. +Le badge OAuth (🦎/🐙) n'apparaît QUE pour les comptes dont `auth_method` est le provider. + +``` +Compte LOCAL avec intégrations : +┌──────────────────────────────────┐ +│ [D] Draco │ ← Nom local, PAS de badge +│ bruno.charest@gmail.com │ +└──────────────────────────────────┘ + +Compte GITEA (auth_method=gitea) : +┌──────────────────────────────────┐ +│ [B] bruno [🦎 Gitea] │ ← Badge visible +│ bruno@dracodev.net │ +└──────────────────────────────────┘ +``` + +### 6.5.2 Matrice des intégrations + +``` +Compte principal Peut ajouter Déconnexion possible +───────────────────────────────────────────────────────── +local Gitea ✅ Oui +local GitHub ✅ Oui +local Gitea + GitHub ✅ Les deux +───────────────────────────────────────────────────────── +gitea GitHub ✅ GitHub ❌ Gitea +github Gitea ✅ Gitea ❌ GitHub +``` + +**Settings → Integrations** : Affiche toutes les intégrations avec bouton +Disconnect. Le provider principal (auth_method) n'a PAS de bouton Disconnect. + +### 6.5.3 Scénarios de workspace + +``` +SCÉNARIO A : Compte local pur +───────────────────────────── +· Login email+password +· Workspaces locaux uniquement +· Section Private : CACHÉE (tout est déjà local) +· Trash : ✅ (restauration locale) + +SCÉNARIO B : Compte local + intégration(s) +────────────────────────────────────────── +· Login email+password +· Workspaces : locaux + Gitea + GitHub +· Section Private : VISIBLE si workspace distant actif +· Private : stockage DB locale, associé user+repo +· Trash : ✅ (local uniquement) + +SCÉNARIO C : Compte OAuth pur (gitea ou github) +──────────────────────────────────────────────── +· Login via OAuth +· Workspaces : distants du provider principal +· Section Private : VISIBLE (toujours) +· Trash : ❌ (pas de contenu local) +· Intégration secondaire : possible +· Déconnexion provider principal : impossible +``` + +### 6.5.4 Sidebar — règles d'affichage par section + +``` +Section Scénario A Scénario B Scénario C +───────────── ────────────── ────────────────────── ────────────── +Recents ✅ (local) ✅ (tout) ✅ (tout) +Favorites ✅ (local) ✅ (tout) ✅ (tout) +Shared ✅ (local) ✅ (tout) ✅ (tout) +Published ✅ (local) ✅ (tout) ✅ (tout) +Agents ✅ ✅ ✅ +Private ❌ CACHÉ ✅ si ws distant actif ✅ +Workspace ✅ ✅ ✅ +Trash ✅ (local) ✅ (local) ❌ +``` + +Chaque section a un bouton `→ Library` qui ouvre : +``` +/library?tab=recents|favorites|shared|published|private|workspace +``` + +### 6.5.5 Système Share & Publish + +Le bouton [Share] dans la topbar d'une page ouvre une modale à 2 tabs : + +``` +┌──────────────────────────────────────────────────────┐ +│ [ Share ] [ Publish ] │ +├──────────────────────────────────────────────────────┤ +│ Share tab : │ +│ · Invite people : [email] [Invite] │ +│ · General access : [🔒 Restricted] Copy link │ +│ · Liste des personnes/groupes avec accès │ +│ → Document listé dans sidebar "Shared" │ +├──────────────────────────────────────────────────────┤ +│ Publish tab : │ +│ · [Publish to web] → URL publique générée │ +│ · URL : https://flowdeck.draco.dev/p/ │ +│ · [Unpublish] │ +│ → Document listé dans sidebar "Published" │ +└──────────────────────────────────────────────────────┘ +``` + +### 6.5.6 Stockage des fichiers Private + +Quand un workspace distant est actif, les fichiers créés dans la section +Private sont stockés dans la **base de données locale** (table `pages` avec +`parent_section='Private'` et `workspace=gitea:/`). + +Cela permet de : +- Prendre des notes personnelles liées à un projet sans les committer +- Garder des brouillons avant de les pousser +- Avoir un espace de travail privé même sur un repo partagé + +### 6.5.7 Trash — règles + +``` +Contenu Trash ? Comportement +─────────────────────── ──────── ────────────────────────── +Workspace local ✅ Supprimé → restaurable +Dossier/fichier local ✅ Supprimé → restaurable +Fichier Gitea/GitHub ❌ Commit "delete" → pas trash +Page distante ❌ Commit "delete" → pas trash +``` + +### 6.5.8 Édition de fichiers — UI unifiée + +``` +Fichier LOCAL Fichier DISTANT (Gitea/GitHub) +┌─────────────────────────┐ ┌─────────────────────────────┐ +│ Même UI d'édition │ │ Même UI d'édition │ +│ Même rendu visuel │ │ Même rendu visuel │ +│ Sauvegarde auto DB │ │ + Bouton [Commit] │ +│ Pas de commit │ │ + Champ message commit │ +└─────────────────────────┘ └─────────────────────────────┘ +``` + +### 6.5.9 Page Library — `/library?tab=` + +``` +┌──────────────────────────────────────────────────────────────┐ +│ Library │ +│ [Recents] [Favorites] [Shared] [Published] │ +│ [Private] [Workspace] │ +├──────────────────────────────────────────────────────────────┤ +│ Filtres : [All] [Local] [Gitea] [GitHub] │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ 📄 Document X Local · modifié il y a 2h │ │ +│ │ 📄 README.md Gitea · bruno/flowdeck │ │ +│ │ 📄 Notes Local · Workspace Projet A │ │ +│ └─────────────────────────────────────────────────────────┘ │ +└──────────────────────────────────────────────────────────────┘ +``` + +### 6.5.10 Schéma DB — mises à jour pour v4.0 + +```sql +-- users : ajout auth_method +ALTER TABLE users ADD COLUMN auth_method TEXT NOT NULL DEFAULT 'local'; +-- 'local' | 'gitea' | 'github' + +-- users : colonnes OAuth existantes +-- gitea_id INTEGER (NULL si pas Gitea) +-- github_id INTEGER (NULL si pas GitHub) +-- gitea_token TEXT (token intégration, NULL si pas connecté) +-- github_token TEXT (token intégration, NULL si pas connecté) + +-- pages : ajout published +ALTER TABLE pages ADD COLUMN is_published BOOLEAN NOT NULL DEFAULT 0; +ALTER TABLE pages ADD COLUMN publish_slug TEXT; +ALTER TABLE pages ADD COLUMN is_shared BOOLEAN NOT NULL DEFAULT 0; +ALTER TABLE pages ADD COLUMN share_mode TEXT DEFAULT 'restricted'; +-- 'restricted' | 'link' | 'public' + +-- page_shares : qui a accès à quel document +CREATE TABLE page_shares ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + page_id INTEGER NOT NULL REFERENCES pages(id) ON DELETE CASCADE, + shared_with_user_id INTEGER REFERENCES users(id), + shared_with_email TEXT, + permission TEXT NOT NULL DEFAULT 'view', + -- 'view' | 'comment' | 'edit' + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + created_by INTEGER REFERENCES users(id) +); + +-- recents : historique de consultation +CREATE TABLE recents ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + user_id INTEGER NOT NULL REFERENCES users(id), + page_id INTEGER NOT NULL REFERENCES pages(id), + workspace TEXT NOT NULL, + source_type TEXT NOT NULL DEFAULT 'local', + -- 'local' | 'gitea' | 'github' + accessed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + UNIQUE(user_id, page_id) +); +``` + +### 6.5.11 Plan de migration + +``` +Phase 1 — DB & Modèles + 1. Ajouter auth_method aux users existants (auto-détecter) + 2. Ajouter is_published, is_shared, share_mode aux pages + 3. Créer table page_shares + 4. Créer table recents + +Phase 2 — Sidebar + 1. Badge OAuth (🦎/🐙) basé sur auth_method + 2. Afficher/cacher Private selon type de compte + workspace actif + 3. Boutons Library par section + 4. Trash filtré local-only + +Phase 3 — Share & Publish + 1. Modale Share à 2 tabs fonctionnelle + 2. Share via email/user → table page_shares + 3. Share via lien → share_mode='link' + 4. Publish → is_published + publish_slug + 5. Page publique servable à /p/ + +Phase 4 — Library + 1. Page /library avec tabs + 2. Filtrage par source (local/gitea/github) + 3. Recents alimentés automatiquement + +Phase 5 — Intégrations + 1. GitHub OAuth déjà fait (providers.py) + 2. Matrice de déconnexion respectée + 3. Compte local peut connecter/déconnecter Gitea+GitHub +``` + +--- + ## 7. Intégration Gitea ### 7.1 Flux de données diff --git a/ROADMAP.md b/ROADMAP.md index e98f6a0..b26daea 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -172,6 +172,47 @@ Propriétés custom, AI keywords, sync API, 12 tables DB --- +## v4.0.0 — Accounts, Integrations & Sidebar (priorité haute) + +> **Rappel** : Section 6.5 de ARCHITECTURE.md documente le design complet. + +### 4.0 Account Model +- [ ] **`auth_method`** — colonne `users.auth_method ∈ {local, gitea, github}` +- [ ] **Auto-détection** — migrer les comptes existants (gitea_token → gitea, sinon local) +- [ ] **Badge OAuth** — 🦎/🐙 dans sidebar SI `auth_method` = provider +- [ ] **Pas de badge** — un compte local avec intégration ne montre PAS de badge + +### 4.0a Intégrations & Déconnexion +- [ ] **Settings page** — montre toutes les intégrations avec bouton Connect/Disconnect +- [ ] **Matrice déconnexion** : local→déco ok · gitea→déco github ok · github→déco gitea ok +- [ ] **Provider principal** — pas de bouton Disconnect sur auth_method +- [ ] **Compte local** — peut connecter Gitea + GitHub simultanément + +### 4.0b Sidebar — règles par type de compte +- [ ] **Private visible** UNIQUEMENT si workspace actif est distant (Gitea/GitHub) +- [ ] **Private caché** pour Scénario A (local pur) +- [ ] **Trash local-only** — caché pour compte OAuth pur, restreint au contenu local +- [ ] **Boutons → Library** sur chaque section (recents, favorites, shared, published…) + +### 4.0c Share & Publish +- [ ] **Modale Share** — 2 tabs (Share + Publish) fonctionnels +- [ ] **Share tab** — inviter email/user, général access lien +- [ ] **Publish tab** — activer/désactiver, slug généré +- [ ] **Page publique** — `/p/` sert le contenu publié +- [ ] **Tables DB** — `page_shares`, colonnes `is_published`, `is_shared`, `share_mode` + +### 4.0d Library +- [ ] **Page `/library?tab=`** — tabs Recents, Favorites, Shared, Published, Private, Workspace +- [ ] **Filtres source** — All | Local | Gitea | GitHub +- [ ] **Table `recents`** — tracking automatique des documents consultés + +### 4.0e Édition unifiée +- [ ] **Même UI** pour fichiers locaux ET distants +- [ ] **Bouton Commit** — visible uniquement pour fichiers distants +- [ ] **Champ message** — pour les commits Gitea/GitHub + +--- + ## v4.0.0 — Parité Notion (Delta Analysis) > **Méthodologie**: Comparaison exhaustive de FlowDeck v3.0.1 vs Notion (2025) — 60+ fonctionnalités analysées, 45 manquantes identifiées, 30 retenues pour v4.0.0.