xpeditis2.0/PRD.md

# PRD — Xpeditis (MVP)

**Produit** : Xpeditis — plateforme B2B SaaS de réservation et gestion de fret maritime (équivalent maritime de WebCargo).

**Auteur** : Architecte logiciel senior (Hexagonal) — NextTs

**Objectif du document** : Décrire les besoins produit, les exigences fonctionnelles et techniques, les critères d'acceptation et la feuille de route pour livrer le MVP sous 4–6 mois.

---

## 1. Contexte & vision

Xpeditis fournit aux transitaires (freight forwarders) une interface unique pour :

* Rechercher et comparer des tarifs maritimes en temps réel
* Réserver des conteneurs en ligne
* Gérer le cycle de vie des expéditions depuis un dashboard centralisé

**Vision MVP** : Livrer un produit minimal mais professionnel capable d'absorber 50–100 réservations/mois pour 10–20 transitaires early adopters et valider l'adéquation marché.

---

## 2. Objectifs business & KPI du MVP

**Objectifs** :

* Onboard 10–20 transitaires pilotes en 4–6 mois
* Traiter 50–100 réservations/mois
* Taux de conversion recherche→réservation ≥ 3%
* SLA recherche tarifs : 95% des requêtes < 1s (caching inclus)

**KPI** :

* Nombre d’utilisateurs actifs (DAU/MAU)
* Nombre de bookings / mois
* Taux d’erreurs API carriers
* Temps moyen pour créer une réservation
* Taux de rétention clients à 3 mois

---

## 3. Périmètre du MVP (Fonctionnalités critiques)

Priorités : CRITIQUE (Recherche tarifs, Réservation, Intégration carriers) ; HAUT (Auth, Dashboard). Modules détaillés ci‑dessous reprennent et transforment les spécifications fournies en exigences mesurables.

### MODULE 1 — Recherche de tarifs (CRITIQUE)

**Fonctionnalités** :

* Endpoint API : `POST /api/v1/rates/search` (payload JSON, voir *Schemas*)
* UI responsive : formulaire recherche + résultats en **cards** et en **tableau**
* Critères : origine, destination (autocomplete 10k+ ports), conteneur, mode (FCL/LCL), date départ, poids/volume (LCL), marchandises dangereuses (classe IMO)
* Résultats : carrier (logo), prix all-in (USD/EUR), surcharges détaillées, transit time (jours), ETD/ETA estimés, route (escales), disponibilité conteneurs, fréquence service, type navire, CO2 par conteneur
* Filtrage & tri (prix, transit time, CO2), pagination (>20 résultats), export PDF/Excel

**Contraintes techniques** :

* Cache Redis (TTL = 15 min pour tarifs spot)
* Préchargement tarifs top 100 trade lanes (batch ou préfetch on startup)
* Timeout API carriers = 5s, gestion des erreurs gracieuse
* Retry / circuit breaker pour connectors

**Livrables** :

* `POST /api/v1/rates/search` + tests unitaires
* UI responsive (NextTs + React) résultats cards/table
* OpenAPI/Swagger
* Export PDF/Excel

**Critères d'acceptation** :

* Requête type (origine/destination/contener/date) retourne < 2s 90% du temps (avec cache)
* Tests unitaires couvrant comportements clé (cache hit/miss, fallback carriers)

### MODULE 2 — Réservation (CRITIQUE)

**Workflow multi‑étapes (≤4 étapes)** :

1. Sélection de l'offre (vérif dispo temps réel)
2. Informations expéditeur/destinataire
3. Détails conteneur
4. Confirmation + T&C

**Comportement post-booking** :

* Génération booking number `WCM-YYYY-XXXXXX`
* Email confirmation HTML (MJML)
* Notification push (si appli mobile)
* Dashboard : entrée avec statut `Pending Confirmation`

**API** :

* `POST /api/v1/bookings` (création)
* `GET /api/v1/bookings/:id` (détail)

**Livrables** :

* Formulaire multi‑étapes (validation front + back)
* Template email MJML
* PDF booking confirmation
* Tests end-to-end (E2E)

**Critères d'acceptation** :

* Processus de booking complet testé E2E (happy path + 3 erreurs courantes)
* Booking créé et visible en dashboard avec PDF généré et email envoyé

### MODULE 3 — Gestion des utilisateurs (HAUT)

**Auth & sécurité** :

* Inscription email+pwd (pwd ≥12 chars, complexité)
* Verification email par token
* Login OAuth2 (Google Workspace, Microsoft 365)
* JWT access 15 min / refresh 7 jours
* TOTP 2FA optionnel
* Reset password sécurisé
* Session auto logout 2h inactivité

**Organisation & RBAC** :

* Profils entreprise (company metadata, logo, documents compliance)
* Roles : Admin, Manager, User, Viewer (RBAC)

**Livrables** :

* Routes `/auth/register`, `/auth/login`, `/auth/logout`, `/auth/refresh`
* Middleware d'auth pour protéger routes API
* Admin panel pour gestion users
* Onboarding flow
* Tests de sécurité (OWASP Top10 checklist)

**Critères d'acceptation** :

* Inscription + vérif email fonctionnelles
* OAuth login testés sur GSuite
* RBAC empêche accès non autorisé (tests)

### MODULE 4 — Dashboard transitaire (HAUT)

**Vue d’ensemble** :

* KPI cards (bookings/mois, TEUs, revenus estimés, pending)
* Charts (6 mois bookings, top trade lanes)
* Alertes (retards, confirmations)

**Liste bookings** :

* Table interactive (search fuzzy, filtres, tri, pagination)
* Détail booking : timeline, docs, audit log, notes internes
* Actions : view, edit, cancel, download

**Livrables** :

* Dashboard responsive (Recharts/Chart.js)
* Table (react-table) avec performance <1s load sur 1000 bookings

**Critères d'acceptation** :

* Dashboard charge <1s pour dataset MVP (jusqu’à 5k rows backend)

### MODULE 5 — Intégration carriers (CRITIQUE)

**Phase 1 (MVP)** : intégrations natives 3–5 carriers prioritaires : Maersk, MSC, CMA CGM, Hapag‑Lloyd, ONE

**Pattern** :

* Connecteur par carrier (Strategy pattern)
* Normalisation -> schéma interne commun (Rates, Surcharges, ETD/ETA, Equipment availability)
* Retry, circuit breaker, logs et métriques
* Rate limiting respecté
* Tests d’intégration

**Livrables** :

* 3 connecteurs opérationnels (au minimum Maersk + 2 autres)
* Mapping data -> schéma interne
* Tests d'intégration automatiques

**Critères d'acceptation** :

* Chaque connecteur répond dans 5s ou bascule sur fallback
* Logs détaillés pour debugging

---

## 4. Architecture technique (haut niveau)

### Principes

* Architecture hexagonale (ports & adapters)
* Backend API-first (OpenAPI), séparation claire domaine / infra
* Frontend NextJS (TypeScript) — SSR/ISR selon besoin
* Base de données relationnelle (Postgres) + Redis cache
* Files/objects : S3-compatible (AWS S3 / MinIO)
* Auth : OAuth + JWT
* Deploy : Docker + orchestrator (k8s) ou Vercel (frontend) + managed backend

### Composants & responsabilités

* **API Layer (Adapters externes)** : Controllers, validation, auth middleware
* **Application Layer (Ports)** : Use cases (searchRates, createBooking, confirmBooking)
* **Domain Layer (Core)** : Entities (Booking, RateQuote, Carrier, Organization, User)
* **Infrastructure Adapters** : DB repository (typeorm/prisma), carrier connectors, email (SES/Sendgrid), storage, Redis cache

### Diagramme simplifié (textuel)

* NextJS (UI) ↔ API Gateway (Node/Next API routes or Express) ↔ Application Services ↔ Repositories ↔ Postgres
* Carrier APIs ↔ Carrier Connectors ↔ Application Services
* Redis cache pour rates
* S3 pour documents

### Data model (extraits)

* `Organization { id, name, type, scac, address, logo_url, documents[] }`
* `User { id, org_id, role, email, pwd_hash, totp_secret }`
* `RateQuote { id, origin, destination, carrier_id, price_currency, price_value, surcharges[], etd, eta, transit_days, route, availability }`
* `Booking { id, booking_number, user_id, org_id, rate_quote_id, shipper, consignee, containers[], status, created_at, updated_at }`
* `Container { id, booking_id, type, container_number, vgm, temp, seal_number }`

---

## 5. API Design — exemples clés

### `POST /api/v1/rates/search` (résumé)

**Payload (exemple)** :

```json
{
  "origin": "NLRTM",
  "destination": "CNSHA",
  "container_type": "40'HC",
  "mode": "FCL",
  "departure_date": "2025-11-01",
  "weight_kg": null,
  "volume_m3": null,
  "hazmat": false
}
```

**Réponse (résumé)** : retourne liste `RateQuote` paginée avec champs demandés (carrier, price, surcharges[], etd, eta, transit_days, route[], availability, frequency, vessel_type, co2_kg)

> *OpenAPI spec complète à générer : inclure schémas, codes d'erreur, exemples.*

---

## 6. Sécurité & conformité

* Chiffrement TLS 1.2+ pour tout trafic
* Hashage mots de passe (Argon2id ou bcrypt≥12)
* Stockage sécurisé des documents compliance (ACL S3)
* Protection contre OWASP Top 10 (rate limiting, input validation, CSP headers)
* Logs d'audit pour actions sensibles

---

## 7. Tests, monitoring et qualité

**Tests** :

* Unit tests (coverage ciblée sur domain & use cases)
* Integration tests (carrier connectors, DB)
* E2E tests (workflow booking happy path + erreurs)

**Monitoring** :

* Metrics (Prometheus) : latence API, error_rate, cache hit ratio
* Traces (OpenTelemetry) pour request flow et debugging
* Alerting (PagerDuty/Slack) pour erreurs critiques

---

## 8. Déploiement & infrastructure MVP

**Environnements** : dev / staging / production
**CI/CD** : pipelines GitHub Actions (lint, unit tests, build, deploy)
**Infra** :

* Frontend : Vercel (NextJS) ou déploiement Docker sur k8s
* Backend : Kubernetes (EKS/GKE) ou managed containers
* Postgres managé (RDS/Cloud SQL)
* Redis managé (Elasticache/MemoryDB)
* S3 (AWS) ou équivalent

**Backup & DR** : backups quotidiens DB, snapshots S3, runbooks

---

## 9. Roadmap & jalons (4–6 mois)

**Sprint 0 (2 semaines)** : Setup repo, infra dev, charte tech, OpenAPI skeleton, ports/adapters scaffolding.

**Phase 1 (6–8 semaines)** :

* Module Recherche (API rates search, UI basic, Redis cache, préchargement top100 lanes)
* 1–2 connecteurs carriers (Maersk + 1)
* Auth basique (email/password)

**Phase 2 (6–8 semaines)** :

* Workflow Réservation (multi-step), génération booking, email template
* Dashboard basique (liste bookings)
* RBAC et organisation

**Phase 3 (4–6 semaines)** :

* Intégrations carriers additionnelles (2–3)
* Export PDF/Excel, E2E tests, monitoring, sécurité

**Go-to-market (2 semaines)** :

* Onboarding early adopters, support, collecte feedback, KPIs tracking

**Total estimé** : 16–24 semaines (4–6 mois)

---

## 10. Risques & mitigations

* **Accès aux APIs carriers** : risque d’obtention tardive d’accès — Mitigation : commencer avec 1‑2 partenaires prêts + fallback pricing (aggregated/spot data) et mock connectors.
* **Latence / disponibilité** : Mitigation : Redis cache, timeouts, circuit breakers.
* **Sécurité des docs** : Mitigation : chiffrement at-rest, ACLs, revue sécurité.
* **Adoption UX** : Mitigation : tests utilisateurs rapides, onboarding guidé, support dédié aux early adopters.

---

## 11. Backlog priorisé (MVP → Post‑MVP)

**MVP** (priorité haute) : Rates search, Booking workflow, 3 carrier connectors, Auth & RBAC, Dashboard de base, Email confirmations, PDF generation.

**Post‑MVP** : Tarification contractuelle (contract rates), multi-currency invoicing, payments, optimisation CO2 reporting, SLA contracts carriers, advanced analytics, mobile app.

---

## 12. Annexes

* **Format booking number** : `WCM-YYYY-XXXXXX` (XXXXXX = alphanumeric 6 chars unique)
* **TTL cache tarifs** : 15 minutes (spot). Possibilité d’override pour contract rates.
* **Timeout carriers** : 5s (configurable)
* **Port autocomplete** : dataset 10k+ (IATA/UN LOCODE) — API local + fallback remote

---

## 13. Prochaines actions (immédiates)

1. Valider le périmètre MVP et les 3 carriers prioritaires avec stakeholders.
2. Kickoff technique — définir tech stack final (Prisma vs TypeORM, choice message broker éventuel).
3. Créer le repo monorepo (apps/frontend / apps/backend / libs/domain / infra) et pipelines CI.
4. Implémenter le contrat OpenAPI minimal pour `POST /api/v1/rates/search` et `POST /api/v1/bookings`.

---