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`](veza-backend-api/internal/core/social/service.go)
- Social models : [`social/models.go`](veza-backend-api/internal/core/social/models.go)
- Chat handlers : [`websocket/chat/handlers.go`](veza-backend-api/internal/websocket/chat/handlers.go)
- Chat hub : [`websocket/chat/hub.go`](veza-backend-api/internal/websocket/chat/hub.go)
- Chat frontend : [`apps/web/src/features/chat/`](apps/web/src/features/chat/)
- Social frontend : [`apps/web/src/features/social/`](apps/web/src/features/social/)
- Settings : [`apps/web/src/components/settings/`](apps/web/src/components/settings/)
- User model : [`models/user.go`](veza-backend-api/internal/models/user.go)

---

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

**Migration** : `migrations/129_hashtags.sql`

```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)

```go
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`

```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

```bash
git tag v0.902
```

---

## Validation finale

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