# Agenda

**Équivalent** : Google Calendar
**Statut** : Partiel (API proxy CalDAV)

---

## Résumé

Calendrier reproduisant rigoureusement le comportement et l'interface de Google Calendar, potentiellement comme frontend pour la solution CalDAV de Nextcloud.

## État d'implémentation réel (mai 2026)

### Déjà implémenté

- API backend montée sous `/api/v1/calendar` (si Nextcloud activé).
- Endpoints list calendriers, list événements, create/update/delete événement.
- Gestion ETag/If-Match sur update événement.
- Endpoint free/busy.
- Invitations/réponses participants (ATTENDEE/PARTSTAT).
- Création lien Meet depuis événement.
- Client CalDAV Nextcloud intégré côté serveur.

### Partiel / incomplet

- Recherche globale events pas encore branchée.

### Non commencé

- Automatisations événements (webhooks complets, actions programmées).
- Expérience agenda frontend de production branchée backend réel.
- Intégration avancée meeting/ressources/salles.

## Approche technique

Même logique qu'Ultidrive : on reproduit l'UX Google Calendar à l'identique, mais le backend calendrier peut être délégué.

### Option "frontend Nextcloud"

L'approche la plus simple : Agenda = **frontend custom pour le backend CalDAV de Nextcloud** :
- Nextcloud Calendar gère le stockage, la sync CalDAV, les invitations, la récurrence
- Agenda = interface identique à Google Calendar (même stack que le reste de la suite)
- Avantage : interopérable avec tout client CalDAV standard (Thunderbird, Apple Calendar, etc.)

### Backend alternatif

Si besoin de découpler de Nextcloud :
- Serveur CalDAV dédié (Radicale, Baikal, sabre/dav)
- Même API CalDAV, juste un backend différent

## Points de différenciation vs Google Calendar

- Interface identique à Google Calendar (migration sans friction)
- CalDAV natif (interopérable avec tout client standard)
- Auto-hébergeable, données sous contrôle
- Créneaux de disponibilité partagés publiquement (style Calendly intégré)
- Automatisations à la création/modification d'événements (webhooks, notifications custom)
- Planification assistée par IA (suggestion de créneaux optimaux selon habitudes)

## Fonctionnalités

### Core
- [ ] Événements (titre, description, lieu, participants, récurrence)
- [ ] Multi-agendas (perso, pro, partagés)
- [ ] Vues jour / semaine / mois / planning
- [ ] Invitations et réponses (accepter, refuser, peut-être)
- [ ] Rappels et notifications
- [ ] Fuseaux horaires

### Collaboration
- [ ] Agendas partagés (lecture / écriture / admin)
- [ ] Créneaux de disponibilité publics (booking)
- [ ] Recherche de créneaux libres entre participants
- [ ] Salles et ressources

### Intégration suite
- [ ] Événements depuis les mails (invitations .ics dans Ultimail)
- [ ] Création automatique de lien Ultimeet
- [ ] Pièces jointes depuis Ultidrive
- [ ] Contacts comme participants (autocomplétion)

### Automatisations
- [ ] Webhooks à la création/modif/suppression d'événements
- [ ] Actions programmées (rappels, envoi de docs avant réunion)

## Intégration Nextcloud — étude technique

### APIs CalDAV disponibles (confirmé)

Nextcloud utilise sabre/dav comme serveur CalDAV. Les endpoints :

| Opération | Méthode | Endpoint |
|-----------|---------|----------|
| Lister calendriers | PROPFIND | `/remote.php/dav/calendars/{user}/` |
| Lister événements | REPORT (calendar-query) | `/remote.php/dav/calendars/{user}/{calendar}/` |
| Créer événement | PUT | `.../calendars/{user}/{calendar}/{uid}.ics` |
| Modifier événement | PUT | Même (avec If-Match etag) |
| Supprimer événement | DELETE | Même |
| Sync incrémentale | REPORT (sync-collection) | Via sync-token |
| Événements à venir | GET | `/ocs/v2.php/apps/dav/api/v1/events/upcoming` |
| Free/busy | POST | `/remote.php/dav/calendars/{user}/outbox/` |

### Fonctionnement

- Les événements sont stockés au format iCalendar (.ics)
- Support natif : récurrence (RRULE), invitations (ATTENDEE + iMIP), rappels (VALARM)
- Sync-token pour synchronisation incrémentale efficace (le client ne recharge que les changements)
- Partage de calendriers via OCS ou CalDAV ACL

### Avantages de cette approche

1. **Interopérable immédiatement** — tout client CalDAV (Thunderbird, Apple Calendar, DAVx5 sur Android) fonctionne avec le même backend
2. **Pas de logique calendrier à recoder** — récurrence, fuseaux horaires, invitations : tout est géré par sabre/dav
3. **Notifications serveur** — Nextcloud push notifications pour les rappels même si le frontend n'est pas ouvert
4. **Même instance** que celle utilisée pour Ultidrive → un seul backend à maintenir

### Architecture cible

```
┌──────────────┐     CalDAV (REPORT, PUT, DELETE)     ┌──────────────┐
│   Agenda     │─────────────────────────────────────▶│  Nextcloud   │
│  (frontend)  │     OCS (upcoming events, sharing)   │  (PHP-FPM)   │
└──────────────┘                                      └──────────────┘
                                                             │
                                                      Même instance que
                                                      celle d'Ultidrive
```

Le frontend Agenda parse les réponses CalDAV (XML/iCalendar) et les affiche dans une UI identique à Google Calendar. Librairie JS recommandée pour parser iCalendar : `ical.js` ou `tsdav` (client CalDAV TypeScript).

## Briques technologiques envisagées

| Besoin | Option retenue | Alternatives |
|--------|----------------|--------------|
| Backend CalDAV | Nextcloud sabre/dav (même instance qu'Ultidrive) | Radicale, Baikal |
| Client CalDAV (JS) | tsdav (TypeScript) | ical.js + fetch custom |
| Parsing iCalendar | ical.js | — |
| Récurrence | rrule.js (expansion côté client) | — |
| Auth | Partagée via Ulti Suite (OIDC → NC) | — |
| Notifications/rappels | NC push + Service Worker | — |