veza/docs/PLAN_V0_902_IMPLEMENTATION.md

Plan d'implémentation v0.902 — Social Complet, Chat & Notifications

État des lieux

Feature	Backend	Frontend	Tests
Hashtags	❌	❌	❌
QR code profil	❌	❌	❌
Referral	❌	❌	❌
Profil public /u/	❌	❌	❌
Chat images	❌	❌	❌
Chat GIFs	❌	❌	❌
Chat track share	❌	❌	❌
Pin messages	❌	❌	❌
Bookmark messages	❌	❌	❌
Emails transactionnels	❌	❌	❌
Badge vérifié	❌	❌	❌
Rôles Producer/Label	❌	❌	❌

---

Fichiers existants clés

• Social service : social/service.go
• Social models : social/models.go
• Chat handlers : websocket/chat/handlers.go
• Chat hub : websocket/chat/hub.go
• Chat frontend : apps/web/src/features/chat/
• Social frontend : apps/web/src/features/social/
• Settings : apps/web/src/components/settings/
• User model : models/user.go

---

Step 1 : Hashtags (SO1-01, SO1-02)

Migration : migrations/129_hashtags.sql

CREATE TABLE IF NOT EXISTS post_hashtags (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    post_id UUID NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
    hashtag VARCHAR(100) NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_post_hashtags_tag ON post_hashtags(hashtag);
CREATE INDEX idx_post_hashtags_post ON post_hashtags(post_id);

Backend :

• Parse #hashtag regex in post content on create/update
• Insert into post_hashtags
• GET /social/hashtags/trending — top 20 by count last 7 days

Frontend :

• Render #hashtag as clickable link in post content
• Route /social/hashtags/:tag — feed filtré par hashtag

Commit : feat(social): hashtag parsing, trending hashtags, hashtag feed

---

Step 2 : QR code + Referral + Profile share (SO1-04 to SO1-06)

Backend :

• GET /users/:id/qr — génère QR code PNG (go-qrcode lib), contenu = https://veza.app/u/{username}
• POST /invitations — body { "email": "..." }, génère lien unique, envoie email via email service
• Migration 130_invitations.sql — table invitations (inviter_id, email, token, accepted_at)
• /u/:username route — middleware Go qui résout username → user, injecte Open Graph meta tags

Frontend :

• Bouton QR dans le profil, modal avec QR code image
• Page invite dans Settings, formulaire email
• Route /u/:username — affiche le profil public

Commit : feat(social): QR code profile, referral invitations, public profile /u/

---

Step 3 : Explore amélioré (SO1-03)

Frontend : Enrichir la page Explore avec sections :

• Trending Hashtags (badges cliquables)
• Recommended Users (based on follows)
• Popular Tracks (top plays 7j)
• Top Groups (by member count)

Commit : feat(social): enhanced explore page with trending, recommended, popular sections

---

Step 4 : Chat images + GIFs (CH1-01, CH1-02)

Backend :

• WebSocket message type image — upload image via HTTP POST /chat/upload-image, retourne URL, envoyé comme message content
• GET /chat/gifs?q=... — proxy vers Giphy API, retourne top 10 GIFs, cache 5min

Frontend :

• Bouton image dans chat input → file picker, upload, affichage inline
• Bouton GIF dans chat input → search modal Giphy, click to send
• Affichage images et GIFs inline dans les messages

Commit : feat(chat): image upload and Giphy GIF integration

---

Step 5 : Chat track share + Pin + Bookmark (CH1-03 to CH1-05)

Backend :

• WebSocket message type track_share — content = { "track_id": "..." }, enrichi avec track metadata
• PinMessage / UnpinMessage WebSocket commands, store is_pinned on message
• POST /chat/bookmarks/:messageId, GET /chat/bookmarks, DELETE /chat/bookmarks/:messageId

Frontend :

• Track share : embed mini player dans le message (cover, title, play button)
• Pinned messages : barre en haut de conversation avec les messages épinglés
• Bookmarks : icône bookmark sur chaque message, page bookmarks dans sidebar

Commit : feat(chat): track sharing, pin messages, bookmark messages

---

Step 6 : Email service + Templates (NF1-01 to NF1-07)

Fichier : veza-backend-api/internal/services/email_service.go (nouveau)

type EmailService struct {
    sender  EmailSender  // interface: SMTP or SendGrid
    queue   chan EmailJob
    logger  *zap.Logger
}

type EmailSender interface {
    Send(to, subject, htmlBody string) error
}

type EmailJob struct {
    To      string
    Subject string
    Template string
    Data    map[string]interface{}
}

func (s *EmailService) Start(ctx context.Context) {
    for {
        select {
        case <-ctx.Done(): return
        case job := <-s.queue:
            html := s.renderTemplate(job.Template, job.Data)
            s.sender.Send(job.To, job.Subject, html)
        }
    }
}

Templates HTML (dans internal/services/email_templates/) :

• welcome.html — envoyé après inscription
• email_confirmation.html — changement email
• password_reset.html — reset mot de passe
• new_follower.html — notification follower
• purchase_confirmation.html — confirmation achat (buyer)
• sale_notification.html — notification vente (seller)
• newsletter.html — résumé hebdomadaire

Intégration : hooker l'email service dans les handlers existants (register, follow, order completed)

Frontend : Préférences email dans Settings (toggle par type), lien unsubscribe dans chaque email

Commit : feat(notifications): email service with templates for welcome, follower, purchase, newsletter

---

Step 7 : Profils complets (PR1-01 to PR1-04)

Migration : migrations/131_user_profiles.sql

ALTER TABLE users ADD COLUMN IF NOT EXISTS is_verified BOOLEAN NOT NULL DEFAULT false;
ALTER TABLE users ADD COLUMN IF NOT EXISTS role_type VARCHAR(20) NOT NULL DEFAULT 'user';
-- role_type: user, artist, producer, label, educator

Backend :

• POST /admin/users/:id/verify — set is_verified = true (admin only)
• PUT /users/me/role — change role_type (validation: artist, producer, label)
• Open Graph middleware pour /u/:username

Frontend :

• Badge vérifié (checkmark bleu) dans profil et cards
• Sélection rôle dans Settings
• Badge rôle (Artist, Producer, Label) dans profil

Commit : feat(profiles): verified badge, producer/label roles, Open Graph meta

---

Step 8 : MSW + Tests

MSW : handlers hashtags, QR, invitations, chat image upload, GIF search, bookmarks, email preferences Tests : hashtag parsing, QR generation, invitation flow, image upload, GIF proxy, pin/bookmark, email template rendering, verification

Commit : test(social,chat,notifications): unit tests for v0.902 features

---

Step 9 : Documentation + release

Commit : docs: update documentation for v0.902

---

Step 10 : Rétrospective + archivage + tag

git tag v0.902

---

Validation finale

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