add v2 specs

2026-07-28 09:37:05 +02:00
parent cae6c4d72d
commit 7713835739
1 changed files with 855 additions and 0 deletions
@@ -0,0 +1,855 @@
+Architecture Offline-First Multi-Device pour Application Mobile
+Version : 1.0
+
+Date : 28 juillet 2026
+
+Statut : Proposition technique
+
+1. Introduction et Objectifs
+Vision
+Application mobile permettant une lecture complète des ressources sans connexion backend. L'utilisateur peut accéder à ses photos, vidéos, documents et autres fichiers même en mode offline total. Le serveur cloud est un "device" parmi d'autres, permettant une synchronisation bidirectionnelle et une gestion intelligente de l'espace de stockage.
+Objectifs opérationnels
+Objectif	Description
+Offline complet	Lecture des ressources locales sans aucune dépendance au réseau
+Libération d'espace	Possibilité de ne posséder localement que les ressources récentes (ex: 3 derniers mois)
+Sync multi-device	Synchronisation entre appareils mobiles, desktop et serveur cloud
+Sécurité 3-2-1	Règle anti-perte : 3 copies, 2 supports différents, 1 hors-site
+Reprise après crash	Reprise des sync interrompues au redémarrage de l'app
+
+
+2. Principes Fondamentaux
+2.1 Séparation ressource / localisation
+Une ressource (photo, PDF, vidéo...) est une entité abstraite avec :
+·	Identité unique (id)
+·	Métadonnées (nom, taille, hash, dates...)
+·	Propriétaire
+Sa localisation physique est un concept séparé : sur quel device (device A, device B, serveur...) existe une copie réelle du fichier.
+Ressource (métadonnée)          Localisations physiques
+┌─────────────────┐            ┌──────────┐ ┌──────────┐ ┌──────────┐
+│ id: abc-123     │◄───────────│ iPhone   │ │ Desktop  │ │ Cloud    │
+│ name: photo.jpg │            │ ✓ local   │ │ ✓ local   │ │ ✓ cloud  │
+│ owner: user_42  │            └──────────┘ └──────────┘ └──────────┘
+└─────────────────┘
+
+2.2 Le serveur est un "device" comme les autres
+Tous les emplacements de stockage (mobile, desktop, serveur cloud, backup) sont modélisés dans une table unique storage_locations. Cela unifie la logique de synchronisation.
+2.3 Un backup est un storage_location de type backup
+·	role = 'backup' : emplacement passif, write-only, jamais source de vérité
+·	Compté dans la règle 3-2-1 pour la sécurité anti-purge
+·	Ne peut pas être supprimé par les règles de rétention standard
+
+3. Modèle de Données SQL (PostgreSQL)
+3.1 Table users — Utilisateurs et groupes
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email VARCHAR(255) UNIQUE NOT NULL,
+    display_name VARCHAR(255) NOT NULL,
+    parent_user_id UUID REFERENCES users(id),  -- pour groupes/organisations
+    storage_quota_bytes BIGINT DEFAULT 10737418240,  -- 10 Go par défaut
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW(),
+    deleted_at TIMESTAMPTZ
+);
+
+-- Index pour recherche par email et hiérarchie
+CREATE INDEX idx_users_email ON users(email) WHERE deleted_at IS NULL;
+CREATE INDEX idx_users_parent ON users(parent_user_id) WHERE deleted_at IS NULL;
+
+3.2 Table resources — Métadonnées universelles des ressources
+CREATE TABLE resources (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    type VARCHAR(20) NOT NULL CHECK (type IN ('file', 'folder')),
+    
+    -- Hiérarchie (type folder peut contenir des resources)
+    name VARCHAR(1024) NOT NULL,
+    parent_id UUID REFERENCES resources(id) ON DELETE CASCADE,
+    
+    -- Propriété et droits
+    owner_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    
+    -- Caractéristiques techniques
+    content_hash VARCHAR(128),  -- SHA-256 pour déduplication
+    size_bytes BIGINT DEFAULT 0,
+    mime_type VARCHAR(255),
+    category VARCHAR(50) CHECK (category IN (
+        'photo', 'video', 'document', 'audio', 'other'
+    )),
+    
+    -- Dates métier
+    taken_at TIMESTAMPTZ,  -- date de prise de vue (EXIF pour photos)
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW(),
+    deleted_at TIMESTAMPTZ,  -- soft delete
+    
+    -- Contrôle
+    CONSTRAINT unique_name_per_parent UNIQUE (parent_id, name)
+);
+
+-- Index pour requêtes fréquentes
+CREATE INDEX idx_resources_owner ON resources(owner_id) WHERE deleted_at IS NULL;
+CREATE INDEX idx_resources_category ON resources(category) WHERE deleted_at IS NULL;
+CREATE INDEX idx_resources_taken_at ON resources(taken_at DESC) WHERE deleted_at IS NULL;
+CREATE INDEX idx_resources_content_hash ON resources(content_hash) WHERE deleted_at IS NULL;
+CREATE INDEX idx_resources_parent ON resources(parent_id);
+
+3.3 Table resource_variants — Variantes (thumbnails, previews)
+CREATE TABLE resource_variants (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    resource_id UUID NOT NULL REFERENCES resources(id) ON DELETE CASCADE,
+    
+    -- Type de variant
+    variant_type VARCHAR(50) NOT NULL CHECK (variant_type IN (
+        'thumbnail_small',   -- 150px
+        'thumbnail_medium',  -- 300px
+        'thumbnail_large',   -- 600px
+        'preview',           -- version optimisée pour affichage rapide
+        'transcoded_video',  -- version mp4 pour streaming
+        'pdf_preview'        -- page 1 en image
+    )),
+    
+    -- Métadonnées du variant
+    size_bytes BIGINT NOT NULL,
+    width INTEGER,
+    height INTEGER,
+    content_hash VARCHAR(128),
+    mime_type VARCHAR(255) DEFAULT 'image/jpeg',
+    
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX idx_variants_resource ON resource_variants(resource_id);
+CREATE UNIQUE INDEX idx_variants_resource_type ON resource_variants(resource_id, variant_type);
+
+3.4 Table storage_locations — Emplacements de stockage
+CREATE TABLE storage_locations (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    
+    -- Type physique
+    type VARCHAR(20) NOT NULL CHECK (type IN (
+        'mobile',    -- smartphone/tablette
+        'desktop',   -- ordinateur
+        'server',    -- serveur/cloud (le "cloud" est un device comme les autres)
+        'backup'     -- serveur de backup
+    )),
+    
+    -- Identité de l'emplacement
+    name VARCHAR(255) NOT NULL,  -- ex: "iPhone de Jean", "Cloud principal"
+    device_id VARCHAR(255) UNIQUE,  -- identifiant unique du device
+    
+    -- Rôle dans la stratégie 3-2-1
+    role VARCHAR(20) NOT NULL DEFAULT 'active' CHECK (role IN (
+        'active',   -- emplacement principal, peut être source de sync
+        'backup'    -- backup passif, write-only, compte pour sécurité
+    )),
+    
+    -- Durabilité du stockage (important pour règle 3-2-1)
+    is_durable BOOLEAN DEFAULT true,  -- false = stockage éphémère (RAM, cache)
+    
+    -- Espace
+    total_bytes BIGINT,
+    used_bytes BIGINT DEFAULT 0,
+    
+    -- Statut
+    is_online BOOLEAN DEFAULT false,  -- le device est-il joignable ?
+    last_seen_at TIMESTAMPTZ,
+    
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX idx_locations_user ON storage_locations(user_id);
+CREATE INDEX idx_locations_type ON storage_locations(type);
+CREATE INDEX idx_locations_role ON storage_locations(role);
+
+3.5 Table resource_placements — Pivot ressource / localisation avec statut
+CREATE TABLE resource_placements (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    resource_id UUID NOT NULL REFERENCES resources(id) ON DELETE CASCADE,
+    location_id UUID NOT NULL REFERENCES storage_locations(id) ON DELETE CASCADE,
+    
+    -- Statut de présence locale
+    -- local_only    : existe uniquement ici, pas encore synchronisé
+    -- synced        : synchronisé, existe ici et sur le serveur cloud
+    -- cloud_only    : n'existe pas ici, uniquement sur le cloud
+    -- pending_download : téléchargement en cours (intention matérialisée)
+    -- pending_upload   : upload en cours
+    status VARCHAR(30) NOT NULL DEFAULT 'synced' CHECK (status IN (
+        'local_only', 'synced', 'cloud_only', 'pending_download', 'pending_upload'
+    )),
+    
+    -- Chemin local si présent
+    local_path VARCHAR(4096),
+    
+    -- Timestamps de sync
+    downloaded_at TIMESTAMPTZ,   -- quand la copie locale a été faite
+    uploaded_at TIMESTAMPTZ,     -- quand upload vers cloud terminé
+    verified_at TIMESTAMPTZ,     -- dernière vérification intégrité
+    
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW(),
+    
+    CONSTRAINT unique_resource_location UNIQUE (resource_id, location_id)
+);
+
+CREATE INDEX idx_placements_resource ON resource_placements(resource_id);
+CREATE INDEX idx_placements_location ON resource_placements(location_id);
+CREATE INDEX idx_placements_status ON resource_placements(status);
+CREATE INDEX idx_placements_location_status ON resource_placements(location_id, status);
+
+-- Vue materialisée pour stats par location
+CREATE MATERIALIZED VIEW mv_location_stats AS
+SELECT 
+    location_id,
+    COUNT(*) FILTER (WHERE status IN ('local_only', 'synced')) as local_count,
+    COUNT(*) FILTER (WHERE status = 'cloud_only') as cloud_only_count,
+    SUM(size_bytes) FILTER (WHERE status IN ('local_only', 'synced')) as local_bytes
+FROM resource_placements
+JOIN resources ON resources.id = resource_placements.resource_id
+GROUP BY location_id;
+
+CREATE UNIQUE INDEX idx_mv_location_stats ON mv_location_stats(location_id);
+
+3.6 Table retention_policies — Politiques de rétention déclaratives
+CREATE TABLE retention_policies (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    
+    -- Identifiant de la policy
+    name VARCHAR(255) NOT NULL,  -- ex: "3 derniers mois sur mobile"
+    
+    -- Cible : quel type de ressource et catégorie
+    target_type VARCHAR(20) CHECK (target_type IN ('file', 'folder', 'all')),
+    target_category VARCHAR(50) CHECK (target_category IN (
+        'photo', 'video', 'document', 'audio', 'other', 'all'
+    )),
+    
+    -- Règle de rétention (expressions simples, user-friendly)
+    -- Exemples :
+    --   'all'                    → tout garder localement
+    --   'last_months:3'          → garder uniquement les 3 derniers mois
+    --   'favorites_only'         → garder uniquement les favoris
+    --   'last_months:6,category:photo' → 6 derniers mois pour photos
+    retention_rule VARCHAR(255) NOT NULL,
+    
+    -- Location cible (null = toutes les locations actives)
+    target_location_id UUID REFERENCES storage_locations(id),
+    
+    -- actif ?
+    is_active BOOLEAN DEFAULT true,
+    
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX idx_policies_user ON retention_policies(user_id);
+CREATE INDEX idx_policies_active ON retention_policies(is_active) WHERE is_active = true;
+
+3.7 Table sync_queue — File de synchronisation
+CREATE TABLE sync_queue (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    resource_id UUID NOT NULL REFERENCES resources(id) ON DELETE CASCADE,
+    location_id UUID NOT NULL REFERENCES storage_locations(id),
+    
+    -- Type d'opération
+    operation VARCHAR(30) NOT NULL CHECK (operation IN (
+        'upload',      --上传到云端
+        'download',    --从云端下载
+        'delete',      --删除本地副本
+        'metadata_sync' --同步元数据
+    )),
+    
+    -- Statut
+    status VARCHAR(20) NOT NULL DEFAULT 'pending' CHECK (status IN (
+        'pending',     -- en attente
+        'in_progress', -- en cours
+        'completed',   -- terminé
+        'failed',      -- échoué
+        'cancelled'    -- annulé
+    )),
+    
+    -- Priorité (0 =最高, 100 =最低) - pour ordonner les opérations
+    priority INTEGER DEFAULT 50,
+    
+    -- Gestion des erreurs
+    retry_count INTEGER DEFAULT 0,
+    max_retries INTEGER DEFAULT 3,
+    error_message TEXT,
+    last_error_at TIMESTAMPTZ,
+    
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    started_at TIMESTAMPTZ,
+    completed_at TIMESTAMPTZ
+);
+
+CREATE INDEX idx_queue_status ON sync_queue(status) WHERE status IN ('pending', 'in_progress');
+CREATE INDEX idx_queue_resource ON sync_queue(resource_id);
+CREATE INDEX idx_queue_priority ON sync_queue(priority, created_at);
+CREATE INDEX idx_queue_pending_downloads ON sync_queue(location_id, operation, status) 
+    WHERE operation = 'download' AND status = 'pending';
+CREATE INDEX idx_queue_pending_uploads ON sync_queue(location_id, operation, status) 
+    WHERE operation = 'upload' AND status = 'pending';
+
+3.8 Tables ReBAC — Relations et droits (Relation-Based Access Control)
+-- Table des relations entre utilisateurs et entités
+CREATE TABLE entity_relations (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    
+    -- Sujet de la relation (qui)
+    subject_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    subject_type VARCHAR(20) NOT NULL DEFAULT 'user' CHECK (subject_type IN ('user', 'group')),
+    
+    -- Type de relation
+    relation VARCHAR(50) NOT NULL CHECK (relation IN (
+        'owner',       -- propriétaire (CRUD total)
+        'editor',      -- peut modifier
+        'viewer',      -- lecture seule
+        'commenter',   -- peut commenter
+        'uploader',    -- peut ajouter des fichiers
+        'member',      -- membre d'un groupe
+        'parent',      -- parent organization
+        'child'        -- enfant (sub-organisation)
+    )),
+    
+    -- Entité cible (sur quoi)
+    entity_type VARCHAR(50) NOT NULL CHECK (entity_type IN (
+        'user', 'group', 'resource', 'folder', 'collection'
+    )),
+    entity_id UUID NOT NULL,
+    
+    -- Héritage (cette relation se propage-t-elle aux enfants ?)
+    inherit BOOLEAN DEFAULT true,
+    
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    
+    CONSTRAINT unique_subject_entity_relation UNIQUE (subject_id, entity_id, relation)
+);
+
+CREATE INDEX idx_relations_subject ON entity_relations(subject_id);
+CREATE INDEX idx_relations_entity ON entity_relations(entity_type, entity_id);
+CREATE INDEX idx_relations_type ON entity_relations(relation);
+
+-- Vue pour résolution rapide des droits sur ressources
+CREATE VIEW resource_permissions_view AS
+SELECT 
+    er.subject_id,
+    er.entity_id AS resource_id,
+    er.relation,
+    r.owner_id,
+    r.parent_id,
+    er.inherit
+FROM entity_relations er
+JOIN resources r ON r.id = er.entity_id
+WHERE er.entity_type = 'resource';
+
+
+4. Fonctions et Requêtes SQL Clés
+4.1 Déterminer le statut d'affichage d'une ressource sur un device
+-- Retourne le statut visuel d'une ressource pour un device donné
+-- Utile pour l'UI : badge cloud, spinner téléchargement, miniature locale...
+CREATE OR REPLACE FUNCTION get_resource_display_status(
+    p_resource_id UUID,
+    p_location_id UUID
+) RETURNS VARCHAR(30) AS $$
+DECLARE
+    v_placement record;
+    v_resource record;
+BEGIN
+    -- Récupérer la ressource
+    SELECT * INTO v_resource FROM resources WHERE id = p_resource_id;
+    IF v_resource IS NULL THEN
+        RETURN 'not_found';
+    END IF;
+    
+    -- Vérifier si la ressource est dans la corbeille
+    IF v_resource.deleted_at IS NOT NULL THEN
+        RETURN 'deleted';
+    END IF;
+    
+    -- Récupérer le placement sur ce device
+    SELECT * INTO v_placement 
+    FROM resource_placements 
+    WHERE resource_id = p_resource_id AND location_id = p_location_id;
+    
+    IF v_placement IS NULL THEN
+        -- Pas de placement = pas sur ce device, chercher sur cloud
+        IF EXISTS (
+            SELECT 1 FROM resource_placements 
+            WHERE resource_id = p_resource_id 
+            AND status IN ('synced', 'cloud_only')
+            AND location_id IN (
+                SELECT id FROM storage_locations WHERE type = 'server'
+            )
+        ) THEN
+            RETURN 'cloud_available';  -- existe sur cloud, peut être téléchargé
+        END IF;
+        RETURN 'not_available';
+    END IF;
+    
+    -- Retourner le statut du placement
+    RETURN v_placement.status;
+    
+END;
+$$ LANGUAGE plpgsql;
+
+-- Exemple d'utilisation dans une requête
+/*
+SELECT 
+    r.id,
+    r.name,
+    r.category,
+    get_resource_display_status(r.id, 'device-uuid-here') as display_status
+FROM resources r
+WHERE r.owner_id = 'user-uuid'
+ORDER BY r.taken_at DESC;
+*/
+
+4.2 Calculer l'espace utilisé par un storage_location
+-- Calcule l'espace disque utilisé par un emplacement
+CREATE OR REPLACE FUNCTION calculate_location_used_bytes(
+    p_location_id UUID
+) RETURNS BIGINT AS $$
+BEGIN
+    RETURN COALESCE(
+        (
+            SELECT SUM(r.size_bytes)
+            FROM resource_placements rp
+            JOIN resources r ON r.id = rp.resource_id
+            WHERE rp.location_id = p_location_id
+            AND rp.status IN ('local_only', 'synced')
+            AND r.deleted_at IS NULL
+        ), 0
+    );
+END;
+$$ LANGUAGE plpgsql;
+
+-- Mise à jour automatique de used_bytes dans storage_locations
+CREATE OR REPLACE FUNCTION update_location_used_bytes()
+RETURNS TRIGGER AS $$
+BEGIN
+    UPDATE storage_locations 
+    SET used_bytes = calculate_location_used_bytes(NEW.location_id)
+    WHERE id = NEW.location_id;
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trigger_update_location_bytes
+AFTER INSERT OR UPDATE OR DELETE ON resource_placements
+FOR EACH ROW EXECUTE FUNCTION update_location_used_bytes();
+
+4.3 Appliquer une politique de rétention (proposer purge avec vérification 3-2-1)
+-- Identifie les ressources candidates à la purge locale
+-- Applique la règle 3-2-1 : ne purger que s'il existe >= 2 copies durables ailleurs
+CREATE OR REPLACE FUNCTION get_resources_for_purge(
+    p_location_id UUID,
+    p_retention_rule VARCHAR(255),
+    p_target_category VARCHAR(50) DEFAULT 'all'
+) RETURNS TABLE(
+    resource_id UUID,
+    resource_name VARCHAR(1024),
+    size_bytes BIGINT,
+    current_status VARCHAR(30),
+    can_purge BOOLEAN,
+    copies_elsewhere INTEGER,
+    durable_copies_elsewhere INTEGER
+) AS $$
+BEGIN
+    RETURN QUERY
+    WITH 
+    -- Parser la règle de rétention (ex: 'last_months:3')
+    retention_params AS (
+        SELECT 
+            COALESCE(
+                NULLIF(SPLIT_PART(p_retention_rule, ':', 2), 'all'),
+                '9999'
+            )::INTEGER as months,
+            p_retention_rule as raw_rule
+    ),
+    -- Ressources sur ce device qui ne sont pas 'cloud_only' (donc occupent de l'espace)
+    local_resources AS (
+        SELECT 
+            r.id,
+            r.name,
+            r.size_bytes,
+            r.category,
+            r.taken_at,
+            rp.status
+        FROM resources r
+        JOIN resource_placements rp ON rp.resource_id = r.id
+        WHERE rp.location_id = p_location_id
+        AND rp.status IN ('local_only', 'synced')
+        AND r.deleted_at IS NULL
+        AND (p_target_category = 'all' OR r.category = p_target_category)
+    ),
+    -- Ressources à purger selon la politique de rétention
+    candidates AS (
+        SELECT lr.*
+        FROM local_resources lr
+        CROSS JOIN retention_params rp
+        WHERE 
+            -- Si 'all', garder tout
+            rp.raw_rule != 'all'
+            AND
+            -- Sinon, vérifier l'ancienneté
+            (
+                lr.taken_at IS NULL 
+                OR lr.taken_at < NOW() - (rp.months || ' months')::INTERVAL
+            )
+    ),
+    -- Compter les copies ailleurs pour chaque candidat
+    copies_count AS (
+        SELECT 
+            c.id,
+            COUNT(DISTINCT rp.location_id) as total_copies,
+            COUNT(DISTINCT rp.location_id) FILTER (
+                WHERE sl.is_durable = true AND sl.role = 'active'
+            ) as durable_active_copies,
+            COUNT(DISTINCT rp.location_id) FILTER (
+                WHERE sl.is_durable = true AND sl.role = 'backup'
+            ) as backup_copies
+        FROM candidates c
+        JOIN resource_placements rp ON rp.resource_id = c.id
+        JOIN storage_locations sl ON sl.id = rp.location_id
+        WHERE rp.location_id != p_location_id
+        AND rp.status IN ('synced', 'cloud_only')
+        GROUP BY c.id
+    )
+    SELECT 
+        c.id as resource_id,
+        c.name as resource_name,
+        c.size_bytes,
+        c.status as current_status,
+        -- Règle 3-2-1 : on purge si >= 2 copies durables elsewhere
+        CASE 
+            WHEN cc.total_copies >= 2 THEN true
+            WHEN cc.durable_active_copies + cc.backup_copies >= 1 AND cc.total_copies >= 2 THEN true
+            ELSE false
+        END as can_purge,
+        COALESCE(cc.total_copies, 0) as copies_elsewhere,
+        COALESCE(cc.durable_active_copies + cc.backup_copies, 0) as durable_copies_elsewhere
+    FROM candidates c
+    LEFT JOIN copies_count cc ON cc.id = c.id
+    ORDER BY c.taken_at ASC NULLS LAST;  -- les plus anciennes en premier
+END;
+$$ LANGUAGE plpgsql;
+
+-- Exemple d'utilisation : identifier ce qui peut être purgé
+/*
+SELECT * FROM get_resources_for_purge(
+    'iphone-location-uuid',
+    'last_months:3',
+    'photo'
+);
+*/
+
+4.4 Récupérer les sync interrompues à reprendre au démarrage
+-- Téléchargements en attente ou en cours à reprendre
+CREATE OR REPLACE FUNCTION get_pending_downloads(p_location_id UUID)
+RETURNS TABLE(
+    queue_id UUID,
+    resource_id UUID,
+    resource_name VARCHAR(1024),
+    size_bytes BIGINT,
+    retry_count INTEGER,
+    error_message TEXT
+) AS $$
+BEGIN
+    RETURN QUERY
+    SELECT 
+        q.id as queue_id,
+        q.resource_id,
+        r.name,
+        r.size_bytes,
+        q.retry_count,
+        q.error_message
+    FROM sync_queue q
+    JOIN resources r ON r.id = q.resource_id
+    WHERE q.location_id = p_location_id
+    AND q.operation = 'download'
+    AND q.status IN ('pending', 'in_progress', 'failed')
+    AND q.retry_count < q.max_retries
+    AND r.deleted_at IS NULL
+    ORDER BY q.priority ASC, q.created_at ASC;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Uploads en attente ou en cours à reprendre
+CREATE OR REPLACE FUNCTION get_pending_uploads(p_location_id UUID)
+RETURNS TABLE(
+    queue_id UUID,
+    resource_id UUID,
+    resource_name VARCHAR(1024),
+    size_bytes BIGINT,
+    status VARCHAR(20),
+    retry_count INTEGER
+) AS $$
+BEGIN
+    RETURN QUERY
+    SELECT 
+        q.id as queue_id,
+        q.resource_id,
+        r.name,
+        r.size_bytes,
+        q.status,
+        q.retry_count
+    FROM sync_queue q
+    JOIN resources r ON r.id = q.resource_id
+    WHERE q.location_id = p_location_id
+    AND q.operation = 'upload'
+    AND q.status IN ('pending', 'in_progress', 'failed')
+    AND q.retry_count < q.max_retries
+    AND r.deleted_at IS NULL
+    ORDER BY q.priority ASC, q.created_at ASC;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Placements en 'pending_download' à finaliser
+CREATE OR REPLACE FUNCTION get_pending_download_placements(p_location_id UUID)
+RETURNS TABLE(
+    placement_id UUID,
+    resource_id UUID,
+    resource_name VARCHAR(1024)
+) AS $$
+BEGIN
+    RETURN QUERY
+    SELECT 
+        rp.id as placement_id,
+        rp.resource_id,
+        r.name
+    FROM resource_placements rp
+    JOIN resources r ON r.id = rp.resource_id
+    WHERE rp.location_id = p_location_id
+    AND rp.status = 'pending_download'
+    AND r.deleted_at IS NULL
+    ORDER BY rp.updated_at ASC;
+END;
+$$ LANGUAGE plpgsql;
+
+4.5 Requête CTE récursive pour résolution des droits ReBAC
+-- Résout tous les droits d'un utilisateur sur une ressource (et ses parents)
+-- Prend en compte :
+--   - Droits directs sur la ressource
+--   - Héritage depuis le parent (folder)
+--   - Appartenance à des groupes (parent_user_id)
+--   - Permissions inherited depuis les organisations parentes
+CREATE OR REPLACE FUNCTION resolve_user_resource_permissions(
+    p_user_id UUID,
+    p_resource_id UUID
+) RETURNS TABLE(relation VARCHAR(50), entity_id UUID, inherit BOOLEAN, source_type VARCHAR(20)) AS $$
+BEGIN
+    RETURN QUERY
+    WITH RECURSIVE 
+    -- 1. Ressource et sa hiérarchie de parents
+    resource_hierarchy AS (
+        -- Starting point
+        SELECT r.id, r.parent_id, r.owner_id, 0 as depth
+        FROM resources r
+        WHERE r.id = p_resource_id
+        
+        UNION ALL
+        
+        -- Parents récursifs
+        SELECT r.id, r.parent_id, r.owner_id, rh.depth + 1
+        FROM resources r
+        JOIN resource_hierarchy rh ON r.id = rh.parent_id
+    ),
+    
+    -- 2. Hiérarchie de groupes de l'utilisateur (via parent_user_id)
+    user_groups AS (
+        SELECT id, parent_user_id, 0 as depth
+        FROM users
+        WHERE id = p_user_id
+        
+        UNION ALL
+        
+        SELECT u.id, u.parent_user_id, ug.depth + 1
+        FROM users u
+        JOIN user_groups ug ON u.parent_user_id = ug.id
+    ),
+    
+    -- 3. Droits directs sur la ressource
+    direct_rights AS (
+        SELECT er.relation, er.entity_id, er.inherit, 'direct' as source_type
+        FROM entity_relations er
+        WHERE er.subject_id = p_user_id
+        AND er.entity_type = 'resource'
+        AND er.entity_id = p_resource_id
+    ),
+    
+    -- 4. Droits hérités depuis le parent folder
+    inherited_rights AS (
+        SELECT 
+            er.relation, 
+            er.entity_id,
+            true as inherit,  -- forcé à true pour héritage
+            'inherited' as source_type
+        FROM entity_relations er
+        JOIN resource_hierarchy rh ON er.entity_id = rh.id
+        WHERE er.subject_id = p_user_id
+        AND er.entity_type = 'resource'
+        AND er.inherit = true
+        AND rh.depth > 0  -- exclude self
+    ),
+    
+    -- 5. Droits via appartenance à un groupe
+    group_rights AS (
+        SELECT er.relation, er.entity_id, er.inherit, 'group' as source_type
+        FROM entity_relations er
+        JOIN user_groups ug ON er.subject_id = ug.id
+        WHERE ug.depth > 0  -- exclude self (already in direct_rights)
+        AND er.entity_type = 'resource'
+        AND er.entity_id = p_resource_id
+    ),
+    
+    -- 6. Droits owner (tout utilisateur est owner de ses ressources)
+    owner_rights AS (
+        SELECT 'owner' as relation, id as entity_id, false as inherit, 'owner' as source_type
+        FROM resource_hierarchy
+        WHERE owner_id = p_user_id
+    )
+    
+    -- Combinaison de tous les droits
+    SELECT relation, entity_id, inherit, source_type
+    FROM direct_rights
+    
+    UNION
+    
+    SELECT relation, entity_id, inherit, source_type
+    FROM inherited_rights
+    
+    UNION
+    
+    SELECT relation, entity_id, inherit, source_type
+    FROM group_rights
+    
+    UNION
+    
+    SELECT relation, entity_id, inherit, source_type
+    FROM owner_rights;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Vue simplifiée pour vérifier rapidement si un user peut voir une ressource
+CREATE OR REPLACE FUNCTION can_user_access_resource(
+    p_user_id UUID,
+    p_resource_id UUID,
+    p_required_relation VARCHAR(50) DEFAULT 'viewer'
+) RETURNS BOOLEAN AS $$
+DECLARE
+    v_has_access BOOLEAN;
+BEGIN
+    SELECT EXISTS(
+        SELECT 1 
+        FROM resolve_user_resource_permissions(p_user_id, p_resource_id) perms
+        WHERE perms.relation IN (
+            CASE p_required_relation
+                WHEN 'viewer' THEN ARRAY['owner', 'viewer', 'editor', 'commenter']
+                WHEN 'editor' THEN ARRAY['owner', 'editor']
+                WHEN 'owner' THEN ARRAY['owner']
+                ELSE ARRAY[p_required_relation]
+            END
+        )
+    ) INTO v_has_access;
+    
+    RETURN COALESCE(v_has_access, false);
+END;
+$$ LANGUAGE plpgsql;
+
+-- Exemple : vérifier si user peut voir une photo
+/*
+SELECT can_user_access_resource('user-uuid', 'resource-uuid', 'viewer');
+*/
+
+
+5. Features et Comportements Utilisateur
+5.1 Mode Offline Complet
+·	✅ Lecture des ressources locales sans aucune requête réseau
+·	✅ Navigation dans les dossiers avec métadonnées en local
+·	✅ Affichage des miniatures pré-générées et en cache
+·	✅ Lecture des fichiers (documents, photos, vidéos) depuis le stockage local
+·	⚠️ Limitation : création/modification de contenu nécessite une sync ultérieure
+5.2 Gestion Intelligente de l'Espace
+·	📱 Politique de rétention configurable par l'utilisateur
+o	"Garder les 3 derniers mois sur mon téléphone"
+o	"Garder uniquement les favoris"
+o	"Tout synchroniser" (mode desktop)
+·	🗑️ Purge automatique suggérée avec validation 3-2-1
+o	Ne supprime jamais une ressource qui n'aurait que 1 copie ailleurs
+o	Interface claire : "X Go peuvent être libérés"
+·	📊 Indicateur d'espace utilisé en temps réel par catégorie
+5.3 Synchronisation Multi-Device
+·	🔄 Sync bidirectionnelle : mobile ↔ cloud ↔ desktop
+·	⏸️ Reprise après interruption : au démarrage, reprend les uploads/downloads échoués
+·	🎯 Priorisation : les ressources récemment consultées sont synchronisées en priorité
+·	🔍 Détection de conflits : si même fichier modifié sur 2 devices, proposer à l'utilisateur
+5.4 Sécurité Anti-Perte (Règle 3-2-1)
+·	📦 3 copies minimum de chaque ressource importante
+·	💾 2 supports différents (ex: mobile + cloud, ou desktop + backup)
+·	☁️ 1 copie hors-site (serveur cloud ou backup distant)
+·	🚫 Protection des backups : les storage_locations avec role='backup' ne sont jamais purgés
+5.5 Variantes et Optimisation
+·	🖼️ Thumbnails multi-résolution : 150px, 300px, 600px pour affichage rapide
+·	🎬 Previews vidéo : version mp4 optimisée pour streaming
+·	📄 Aperçus PDF : première page en image
+·	💾 Cache intelligent : les variantes sont prioritaires pour la sync
+
+6. Schéma Récapitulatif des Tables
+Table	Rôle	Clé Primaire	Liens Clés
+users	Utilisateurs et groupes (orgs)	id	parent_user_id (self-ref)
+resources	Métadonnées universelles	id	owner_id, parent_id
+resource_variants	Thumbnails, previews	id	resource_id
+storage_locations	Emplacements (devices, cloud, backup)	id	user_id
+resource_placements	Pivot avec statut de présence	id	resource_id, location_id
+retention_policies	Règles de purge user-friendly	id	user_id, target_location_id
+sync_queue	File de sync en attente	id	resource_id, location_id
+entity_relations	Droits ReBAC sujet→entité	id	subject_id, entity_id
+
+Diagramme de relations simplifié
+users (1)──┬──(n) resources
+           │
+           └──(n) storage_locations (1)──(n) resource_placements (n)──(1) resources
+           │
+           └──(n) retention_policies
+           │
+           └──(n) entity_relations
+
+storage_locations ──(1) sync_queue (n)──(1) resources
+                    │
+                    └──(1) retention_policies (target)
+
+users (1)──(n) entity_relations (n)──(1) resources
+     │                │
+     └──(self-ref)    └──(target: folder, collection, group...)
+     parent_user_id
+
+
+7. Notes d'Implémentation
+Ordre de création des tables
+-- Niveau 1 : tables sans dépendances
+1. users
+
+-- Niveau 2 : tables avec FK vers niveau 1
+2. storage_locations
+3. resources
+4. entity_relations
+
+-- Niveau 3 : tables avec FK vers niveaux 1-2
+5. resource_variants
+6. resource_placements
+7. retention_policies
+8. sync_queue
+
+Considérations de performance
+·	Indexes : créés sur toutes les FK et colonnes filtrées fréquemment
+·	Materialized views : pour les stats d'espace (mv_location_stats)
+·	Soft delete : deleted_at au lieu de suppression physique pour traçabilité
+·	Batch processing : le sync_queue permet de traiter les opérations par lots
+Points à adresser en conception détaillée
+1.	Conflict resolution : stratégie quand même fichier modifié sur 2 devices
+2.	Bandwidth management : limiter la sync en mode mobile (data economy)
+3.	Encryption at rest : stockage chiffré sur les devices mobiles
+4.	Thumbnail generation : où et quand générer les variantes
+5.	Quota management : tracking et alertes quand接近存储限额
+
+Document généré le 28 juillet 2026 — Architecture v1.0