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

{
  "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.

---