veza/docs/PLAN_V0_802_IMPLEMENTATION.md

Plan d'implémentation v0.802 — Cloud Complet, Fichiers & Gear Avancé

État des lieux

Feature	Backend	Frontend	Tests
Cloud CRUD	✅	✅ CloudView	❌
File versioning	❌	❌	❌
File sharing	❌	❌	❌
Backup auto	❌	❌	❌
Export GDPR	❌	❌	❌
Upload single	✅	✅	❌
Upload batch	❌	❌	❌
Pause/resume	❌	❌	❌
Tags auto-suggest	❌	❌	❌
Gear CRUD	✅	✅	❌
Gear warranty	❌	❌	❌
Gear documents	❌	❌	❌
Gear repairs	❌	❌	❌

---

Fichiers existants clés

• Cloud service : cloud_service.go
• Cloud handler : cloud_handler.go
• Cloud frontend : apps/web/src/features/cloud/
• Gear handler : gear_handler.go
• Gear service : gear_service.go
• Gear model : gear.go
• Gear frontend : apps/web/src/features/inventory/
• Upload handler : existing upload components in apps/web/src/components/upload/

---

Step 1 : Migrations (CL1-01, GR1-01 to GR1-03)

Fichier : migrations/119_cloud_file_versions.sql (nouveau)

CREATE TABLE IF NOT EXISTS cloud_file_versions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    file_id UUID NOT NULL REFERENCES cloud_files(id) ON DELETE CASCADE,
    version INTEGER NOT NULL DEFAULT 1,
    storage_key TEXT NOT NULL,
    size_bytes BIGINT NOT NULL DEFAULT 0,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_file_versions_file_id ON cloud_file_versions(file_id);

Fichier : migrations/120_gear_warranty.sql (nouveau)

ALTER TABLE gear ADD COLUMN IF NOT EXISTS warranty_start DATE;
ALTER TABLE gear ADD COLUMN IF NOT EXISTS warranty_end DATE;
ALTER TABLE gear ADD COLUMN IF NOT EXISTS warranty_notes TEXT DEFAULT '';

Fichier : migrations/121_gear_documents.sql (nouveau)

CREATE TABLE IF NOT EXISTS gear_documents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    gear_id UUID NOT NULL REFERENCES gear(id) ON DELETE CASCADE,
    type VARCHAR(50) NOT NULL DEFAULT 'invoice',
    storage_key TEXT NOT NULL,
    filename VARCHAR(255) NOT NULL,
    uploaded_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_gear_documents_gear_id ON gear_documents(gear_id);

Fichier : migrations/122_gear_repairs.sql (nouveau)

CREATE TABLE IF NOT EXISTS gear_repairs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    gear_id UUID NOT NULL REFERENCES gear(id) ON DELETE CASCADE,
    repair_date DATE NOT NULL,
    description TEXT NOT NULL DEFAULT '',
    cost_cents INTEGER NOT NULL DEFAULT 0,
    currency VARCHAR(3) NOT NULL DEFAULT 'EUR',
    provider VARCHAR(255) DEFAULT '',
    notes TEXT DEFAULT '',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_gear_repairs_gear_id ON gear_repairs(gear_id);

Commit : feat(db): add migrations 119-122 for cloud versions, gear warranty/documents/repairs

---

Step 2 : Cloud versioning + sharing backend (CL1-02 to CL1-06)

Fichier : veza-backend-api/internal/models/cloud.go — ajouter modèles CloudFileVersion, CloudFileShare

Fichier : veza-backend-api/internal/services/cloud_service.go — ajouter :

• CreateVersion(fileID) — copie storage_key actuel dans cloud_file_versions, increment version
• ListVersions(fileID) — retourne versions triées par version DESC
• RestoreVersion(fileID, version) — swap storage_key avec la version sélectionnée
• ShareFile(fileID, permissions, expiresAt) — génère token unique, sauvegarde share record
• GetSharedFile(token) — retourne fichier si token valide et non expiré

Fichier : veza-backend-api/internal/handlers/cloud_handler.go — ajouter handlers :

• GET /cloud/files/:id/versions
• POST /cloud/files/:id/restore/:version
• POST /cloud/files/:id/share
• GET /cloud/shared/:token (public, pas d'auth)

Commit : feat(cloud): file versioning, restore, and sharing

---

Step 3 : Export GDPR + Backup auto (CL1-07, CL1-08)

Fichier : veza-backend-api/internal/services/cloud_backup.go (nouveau) — cron goroutine qui copie les fichiers vers un bucket S3 backup

Fichier : veza-backend-api/internal/handlers/user_handler.go — ajouter POST /users/me/export :

• Background job qui collecte : profil, tracks, playlists, messages (30 derniers jours), gear, cloud files metadata
• Génère un ZIP, upload vers S3, retourne un lien temporaire (1h)
• Notification quand prêt

Commit : feat(cloud): GDPR data export and automatic backup cron

---

Step 4 : Batch upload + Pause/Resume (FM1-01, FM1-02)

Fichier : apps/web/src/components/upload/BatchUploader.tsx (nouveau) — multi-file input, parallel queue (max 3), individual progress bars, cancel individual

Fichier : veza-backend-api/internal/handlers/upload_handler.go — ajouter support chunked upload :

• POST /upload/chunk — accepte chunk avec Content-Range header
• POST /upload/complete — finalise l'upload multi-chunk
• Stockage temporaire des chunks, assemblage final

Commit : feat(upload): batch upload with parallel queue, chunked pause/resume

---

Step 5 : Tags auto-suggest + Formats (FM1-03, FM1-04)

Fichier : veza-backend-api/internal/handlers/ — ajouter GET /tags/suggest?q=... :

• Query distinct tags sur tracks et products, ILIKE prefix, ORDER BY frequency DESC, LIMIT 10

Fichier : config validation — ajouter MIME types audio/ogg, audio/aiff, audio/x-aiff, audio/mp4, audio/x-m4a

Commit : feat(upload): tags auto-suggest endpoint and additional audio formats

---

Step 6 : Gear warranty, documents, repairs backend (GR1-04 to GR1-06)

Fichier : veza-backend-api/internal/models/gear.go — ajouter champs warranty + modèles GearDocument, GearRepair

Fichier : veza-backend-api/internal/services/gear_service.go — CRUD documents, CRUD repairs, warranty check

Fichier : veza-backend-api/internal/handlers/gear_handler.go — ajouter :

• POST /gear/:id/documents — upload facture/PDF (multipart)
• GET /gear/:id/documents — lister documents
• POST /gear/:id/repairs — créer réparation
• GET /gear/:id/repairs — lister réparations
• DELETE /gear/:id/documents/:docId — supprimer document
• DELETE /gear/:id/repairs/:repairId — supprimer réparation

Fichier : veza-backend-api/internal/services/gear_warranty_notifier.go (nouveau) — cron goroutine, query gear.warranty_end <= NOW() + 30 days, envoie notification

Commit : feat(gear): warranty tracking, document upload, repair history

---

Step 7 : Frontend Cloud + Gear (CL1-09, GR1-07)

Fichier : apps/web/src/features/cloud/ — ajouter dans CloudView :

• Onglet "Versions" sur un fichier sélectionné
• Bouton "Restore" sur chaque version
• Bouton "Share" → modal avec lien + permissions
• Toast confirmation partage

Fichier : apps/web/src/features/inventory/ — ajouter dans la fiche gear :

• Onglet "Documents" — liste + upload PDF
• Onglet "Réparations" — liste + formulaire ajout
• Badge "Warranty expires in X days" si warranty_end dans < 30j
• Champs warranty_start / warranty_end dans le formulaire edit gear

Commit : feat(ui): cloud versioning/sharing UI, gear documents/repairs tabs

---

Step 8 : MSW handlers + Stories (CL1-10, GR1-08)

Fichier : apps/web/src/mocks/handlers-cloud.ts (nouveau ou modifier) — mock GET versions, POST restore, POST share, GET shared Fichier : apps/web/src/mocks/handlers-gear.ts (nouveau ou modifier) — mock documents CRUD, repairs CRUD

Commit : feat(mocks): MSW handlers for cloud versions/share and gear documents/repairs

---

Step 9 : Tests backend (CL1-11, FM1-05, GR1-09)

Tests unitaires :

• Cloud versioning : create version, list, restore, max 10 limit
• Cloud sharing : create share, get by token, expired token
• Tags suggest : prefix match, frequency order
• Gear warranty : dates, notification trigger
• Gear documents : upload, list, delete
• Gear repairs : CRUD, cost calculation

Commit : test(cloud,gear): unit tests for versioning, sharing, warranty, documents, repairs

---

Step 10 : Documentation + release

Fichier : docs/API_REFERENCE.md — sections Cloud, Upload, Gear Fichier : CHANGELOG.md — section v0.802 Fichier : docs/PROJECT_STATE.md, docs/FEATURE_STATUS.md

Commit : docs: update documentation for v0.802

---

Step 11 : Rétrospective + archivage + tag

# Rétrospective, placeholder v0.803, SCOPE_CONTROL, .cursorrules
# Archive V0_802_RELEASE_SCOPE.md
git tag v0.802

---

Validation finale

cd veza-backend-api && go build ./... && go test ./... -v
cd apps/web && npm run build
git tag v0.802