# Scope v0.303 — Phase 3 Social (suite)

**Version cible** : v0.303 (X=3, Y=3)  
**Prérequis** : v0.302 taguée et mergée dans main  
**Objectif** : Chat appels WebRTC 1-to-1 (Lot C2 reporté depuis v0.302)  
**Dernière mise à jour** : février 2026  
**Effort estimé** : 1-2 semaines de développement

---

## 1. Principe directeur

> **v0.303 = Lot C2 (Chat appels WebRTC).**
>
> Un axe principal :
> 1. **Chat appels (Lot C2)** : Appels audio/vidéo 1-to-1 via WebRTC, signalisation via WebSocket
>
> Objectif : appel audio 1-to-1 fonctionnel entre deux utilisateurs dans une conversation DM.

---

## 2. Contexte — État post v0.302

### 2.1 Livré en v0.302

| Lot | Feature | Statut |
|-----|---------|--------|
| S2 | Groupes avancés (request join, invite, rôles, feed groupes, mes groupes) | ✅ |
| N1 | Notifications push Web (subscription, envoi, préférences, badge) | ✅ |
| P2 | Présence enrichie (rich presence, mode invisible) | ✅ |

### 2.2 Fondation existante (à enrichir)

| Domaine | Existant | À ajouter v0.303 |
|---------|----------|-------------------|
| **Chat** | WebSocket (veza-chat-server), DM, rooms, typing, read receipts, delivered | Signalisation WebRTC (CallOffer, CallAnswer, ICECandidate, CallHangup) |
| **Frontend Chat** | ChatPage, ConversationView, messages, typing indicators | CallButton, IncomingCallModal, ActiveCallBar, useWebRTC |

### 2.3 Composants techniques

| Composant | État | Action v0.303 |
|-----------|------|---------------|
| veza-backend-api | ✅ | Aucune modification (signalisation via Chat Server) |
| veza-chat-server | ✅ | Ajouter types et handlers CallOffer, CallAnswer, ICECandidate, CallHangup |
| apps/web | ✅ | useWebRTC, CallButton, IncomingCallModal, ActiveCallBar |
| Stream Server | ⚠️ | Hors scope (pas nécessaire pour appels) |

### 2.4 Types WebSocket existants

Les types `IncomingMessage` et `OutgoingMessage` sont définis dans [veza-chat-server/src/websocket/mod.rs](veza-chat-server/src/websocket/mod.rs). Ils incluent déjà SendMessage, Typing, MarkAsRead, Delivered, etc. Il faut y ajouter les variants pour la signalisation WebRTC.

---

## 3. Features IN SCOPE v0.303

### 3.1 Lot C2 — Chat appels (WebRTC)

**Objectif** : Appels audio/vidéo 1-to-1 via WebRTC.  
**Effort** : L (5-7 jours)  
**Référence** : Module 5, Video chat intégré (full_features 487)

| # | Feature | Tâche détaillée | Chat Server | Frontend | Critère de sortie |
|---|---------|-----------------|-------------|----------|-------------------|
| C2.1 | **Signalisation** | SDP/ICE via WebSocket | Messages CallOffer, CallAnswer, ICECandidate, CallHangup, CallReject | Échange WebRTC via WS | Connexion peer-to-peer établie |
| C2.2 | **UI appel** | Bouton appeler, modal appel entrant/sortant | — | CallButton, IncomingCallModal, ActiveCallBar | Appel initié, accepté, refusé |
| C2.3 | **Audio uniquement (MVP)** | Appel audio 1-to-1 | — | getUserMedia audio, RTCPeerConnection | Appel audio fonctionnel |
| C2.4 | **Vidéo (optionnel)** | Activer caméra | — | getUserMedia video | Appel vidéo si temps |

#### C2.1 Détail technique — Chat Server

**IncomingMessage** (à ajouter dans `websocket/mod.rs`) :
- `CallOffer { conversation_id, target_user_id, sdp, call_type }` — initier un appel
- `CallAnswer { conversation_id, caller_user_id, sdp }` — accepter l'appel
- `ICECandidate { conversation_id, target_user_id, candidate }` — échange ICE
- `CallHangup { conversation_id, target_user_id }` — raccrocher
- `CallReject { conversation_id, caller_user_id }` — refuser l'appel

**OutgoingMessage** (à ajouter) :
- `CallOffer { ... }` — relayé au destinataire
- `CallAnswer { ... }` — relayé à l'appelant
- `ICECandidate { ... }` — relayé au pair
- `CallHangup { ... }` — notifier la fin d'appel
- `CallRejected { conversation_id, user_id }` — notifier le refus

**WebSocketManager** : ajouter `send_to_user(user_id, message, exclude_client_id)` pour livraison 1-to-1 (les messages d'appel ne doivent pas être broadcast à toute la room).

**Handler** : match arms dans [handler.rs](veza-chat-server/src/websocket/handler.rs) pour chaque type ; vérifier que la conversation est un DM (2 participants) ; `RateLimitAction::CallSignaling` dans [rate_limiter.rs](veza-chat-server/src/security/rate_limiter.rs).

**Fichiers clés** :
- `veza-chat-server/src/websocket/mod.rs` — types
- `veza-chat-server/src/websocket/handler.rs` — handlers
- `veza-chat-server/src/websocket/broadcast.rs` ou équivalent — send_to_user
- `veza-chat-server/src/security/rate_limiter.rs` — CallSignaling

#### C2.2-C2.4 Détail technique — Frontend

**useWebRTC** (`apps/web/src/features/chat/hooks/useWebRTC.ts`) :
- Gestion RTCPeerConnection (création, setRemoteDescription, addIceCandidate)
- Échange SDP/ICE via WebSocket (envoi CallOffer, réception CallAnswer, échange ICECandidate)
- getUserMedia pour audio (et optionnellement vidéo)
- États : idle, calling, ringing, connected, ended, error

**CallButton** (`apps/web/src/features/chat/components/CallButton.tsx`) :
- Bouton à côté du header de conversation (DM uniquement)
- Clic → envoi CallOffer via WebSocket

**IncomingCallModal** (`apps/web/src/features/chat/components/IncomingCallModal.tsx`) :
- Modal affichée quand CallOffer reçu
- Boutons Accepter / Refuser
- Accepter → création RTCPeerConnection, CallAnswer, échange ICE

**ActiveCallBar** (`apps/web/src/features/chat/components/ActiveCallBar.tsx`) :
- Barre pendant l'appel (mute, hangup)
- Mute → mute local stream
- Hangup → envoi CallHangup, fermeture RTCPeerConnection

**chatStore** (Zustand) : états `incomingCall`, `activeCall`, `callState` pour orchestrer l'UI.

**Fichiers clés** :
- `apps/web/src/features/chat/hooks/useWebRTC.ts`
- `apps/web/src/features/chat/components/CallButton.tsx`
- `apps/web/src/features/chat/components/IncomingCallModal.tsx`
- `apps/web/src/features/chat/components/ActiveCallBar.tsx`
- Store chat (Zustand ou existant)

**Flow** : Clic CallButton → envoi CallOffer → callee reçoit → IncomingCallModal → accept → CallAnswer → ICE exchange → ActiveCallBar. Refus → CallReject → CallRejected.

---

## 4. Récapitulatif par lot

| Lot | Priorité | Effort | Dépendances |
|-----|----------|--------|-------------|
| C2 | Haute | L (5-7 j) | Chat Server stable, conversation DM |

**Ordre recommandé** : C2.1 (signalisation) → C2.2-C2.4 (UI + audio + vidéo optionnel).

---

## 5. Features HORS SCOPE v0.303

| Feature | Raison | Version cible |
|---------|--------|---------------|
| Appels de groupe (3+ participants) | Complexité WebRTC (SFU/MCU) | v0.304+ |
| Chiffrement E2E messages | Effort majeur | v0.304+ |
| FCM / APNs (mobile) | Infra externe, apps natives | v0.304+ |
| Forum de discussion par groupe | Scope S2 suffit, priorité moindre | v0.304 |
| Événements de groupe | Priorité moindre | v0.304 |

---

## 6. Migrations et schémas

Aucune migration backend prévue pour v0.303. La signalisation WebRTC transite uniquement via le WebSocket du Chat Server. Aucune table supplémentaire requise.

---

## 7. Critères de livraison v0.303

- [ ] Lot C2.1 : Signalisation CallOffer, CallAnswer, ICECandidate, CallHangup, CallReject dans Chat Server
- [ ] Lot C2.2 : CallButton, IncomingCallModal, ActiveCallBar
- [ ] Lot C2.3 : Appel audio 1-to-1 fonctionnel (getUserMedia, RTCPeerConnection)
- [ ] Lot C2.4 : Appel vidéo (optionnel, si temps)
- [ ] Tests : `cargo build --release` (Chat Server), `npm run build` (Frontend)
- [ ] Documentation : FEATURE_STATUS, PROJECT_STATE, CHANGELOG mis à jour

---

## 8. Checklist pré-merge

- [ ] Lot C2 terminé ou reporté (avec ticket)
- [ ] Pas de régression sur v0.302
- [ ] SCOPE_CONTROL.md référence V0_303_RELEASE_SCOPE.md
- [ ] FEATURE_STATUS.md mis à jour
- [ ] CHANGELOG v0.303
- [ ] Stories Storybook pour CallButton, IncomingCallModal, ActiveCallBar (Loading, Error, Empty selon STORYBOOK_CONTRACT)

---

## 9. Transition vers v0.304

À l'issue de v0.303 :
- Chat appels 1-to-1 opérationnel
- Prochaine version : **v0.304** — à définir (appels groupe, E2E, FCM, forum groupes, etc.)
- Document de scope : `V0_304_RELEASE_SCOPE.md` (à créer après tag v0.303)

---

## Références

- [V0_302_RELEASE_SCOPE.md](V0_302_RELEASE_SCOPE.md) — Version précédente
- [SCOPE_CONTROL.md](SCOPE_CONTROL.md) — Processus anti-scope-creep
- [FEATURE_STATUS.md](FEATURE_STATUS.md) — Statut des features
- [PROJECT_STATE.md](PROJECT_STATE.md) — État actuel du projet
- [veza-chat-server/src/websocket/mod.rs](../veza-chat-server/src/websocket/mod.rs) — Types IncomingMessage, OutgoingMessage
- [STORYBOOK_CONTRACT.md](../apps/web/docs/STORYBOOK_CONTRACT.md) — Contrat Storybook