====== Spécification OpenAPI 3.1 ======

===== Objectif =====

Cette spécification constitue le contrat officiel entre :

  * Frontend NextJS
  * Backend NestJS
  * Applications mobiles futures
  * SDK partenaires
  * Intégrations externes

Elle permet :

  * Génération Swagger
  * Génération SDK TypeScript
  * Génération SDK Java
  * Génération SDK PHP
  * Génération SDK Flutter
  * Génération automatique des DTO

----

====== Convention API ======

===== Base URL =====

<code>
https://api.location-platform.com/api/v1
</code>

----

===== Format =====

<code>
application/json
</code>

----

===== Encodage =====

<code>
UTF-8
</code>

----

===== Versionning =====

<code>
/api/v1
/api/v2
</code>

----

====== Authentification ======

===== JWT =====

Header obligatoire :

<code>
Authorization: Bearer <access_token>
</code>

----

===== Schéma OpenAPI =====

<code yaml>
components:

  securitySchemes:

    bearerAuth:

      type: http

      scheme: bearer

      bearerFormat: JWT
</code>

----

====== Structure des réponses ======

===== Succès =====

<code json>
{
  "success": true,
  "data": {},
  "meta": {},
  "links": {}
}
</code>

----

===== Erreur =====

<code json>
{
  "success": false,
  "error": {
    "code": "PROPERTY_NOT_FOUND",
    "message": "Property not found"
  }
}
</code>

----

====== Pagination ======

===== Paramètres =====

<code>
?page=1
?pageSize=20
</code>

----

===== Réponse =====

<code json>
{
  "success": true,
  "data": [],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 245,
    "pages": 13
  }
}
</code>

----

====== Tri ======

===== Paramètres =====

<code>
?sort=createdAt

?sort=-createdAt

?sort=price

?sort=-price
</code>

----

====== Filtrage ======

===== Exemple =====

<code>
GET /properties

?city=Montpellier
&status=PUBLISHED
&minPrice=100
&maxPrice=300
</code>

----

====== DTO Standards ======

===== UUID =====

<code yaml>
Uuid:
  type: string
  format: uuid
</code>

----

===== Money =====

<code yaml>
Money:
  type: number
  format: double
</code>

----

===== Date =====

<code yaml>
Date:
  type: string
  format: date
</code>

----

===== DateTime =====

<code yaml>
DateTime:
  type: string
  format: date-time
</code>

----

====== Module Auth ======

===== Login =====

==== Request =====

<code http>
POST /auth/login
</code>

Body :

<code json>
{
  "email": "john@example.com",
  "password": "secret"
}
</code>

----

==== Response =====

<code json>
{
  "success": true,
  "data": {
    "accessToken": "...",
    "refreshToken": "...",
    "expiresIn": 3600
  }
}
</code>

----

===== Register =====

<code http>
POST /auth/register
</code>

----

===== Refresh Token =====

<code http>
POST /auth/refresh
</code>

----

===== Logout =====

<code http>
POST /auth/logout
</code>

----

====== Module Users ======

===== User DTO =====

<code yaml>
User:

  type: object

  properties:

    id:
      $ref: '#/components/schemas/Uuid'

    email:
      type: string

    status:
      type: string

    profile:
      $ref: '#/components/schemas/UserProfile'
</code>

----

===== UserProfile DTO =====

<code yaml>
UserProfile:

  type: object

  properties:

    firstName:
      type: string

    lastName:
      type: string

    phone:
      type: string
</code>

----

===== Endpoints =====

<code http>
GET    /users/me

PUT    /users/me

GET    /users/{id}

GET    /users

DELETE /users/{id}
</code>

----

====== Module Properties ======

===== Property DTO =====

<code yaml>
Property:

  type: object

  properties:

    id:
      type: string

    code:
      type: string

    title:
      type: string

    status:
      type: string

    surface:
      type: number

    roomCount:
      type: integer

    bedroomCount:
      type: integer

    bathroomCount:
      type: integer

    capacity:
      type: integer

    address:
      $ref: '#/components/schemas/PropertyAddress'
</code>

----

===== PropertyAddress DTO =====

<code yaml>
PropertyAddress:

  type: object

  properties:

    address1:
      type: string

    city:
      type: string

    postalCode:
      type: string

    country:
      type: string

    latitude:
      type: number

    longitude:
      type: number
</code>

----

===== Recherche de biens =====

<code http>
GET /properties
</code>

Paramètres :

<code>
city
status
minPrice
maxPrice
bedrooms
bathrooms
capacity
page
pageSize
sort
</code>

----

===== Création =====

<code http>
POST /properties
</code>

----

===== Consultation =====

<code http>
GET /properties/{id}
</code>

----

===== Modification =====

<code http>
PUT /properties/{id}
</code>

----

===== Suppression =====

<code http>
DELETE /properties/{id}
</code>

----

====== Module Reservations ======

===== Reservation DTO =====

<code yaml>
Reservation:

  type: object

  properties:

    id:
      type: string

    reservationNumber:
      type: string

    status:
      type: string

    startDate:
      type: string

    endDate:
      type: string

    totalAmount:
      type: number
</code>

----

===== Création réservation =====

<code http>
POST /reservations
</code>

Body :

<code json>
{
  "propertyId": "uuid",
  "startDate": "2026-07-01",
  "endDate": "2026-07-15",
  "guestCount": 4
}
</code>

----

===== Consultation =====

<code http>
GET /reservations/{id}
</code>

----

===== Modification =====

<code http>
PUT /reservations/{id}
</code>

----

===== Annulation =====

<code http>
POST /reservations/{id}/cancel
</code>

----

====== Module Contracts ======

===== Contract DTO =====

<code yaml>
Contract:

  type: object

  properties:

    id:
      type: string

    contractNumber:
      type: string

    status:
      type: string

    signedAt:
      type: string
</code>

----

===== Génération =====

<code http>
POST /contracts/generate
</code>

----

===== Signature =====

<code http>
POST /contracts/{id}/sign
</code>

----

===== Téléchargement =====

<code http>
GET /contracts/{id}/download
</code>

----

====== Module Payments ======

===== Payment DTO =====

<code yaml>
Payment:

  type: object

  properties:

    id:
      type: string

    amount:
      type: number

    status:
      type: string

    paymentDate:
      type: string
</code>

----

===== Paiement =====

<code http>
POST /payments
</code>

----

===== Historique =====

<code http>
GET /payments

GET /payments/{id}
</code>

----

===== Remboursement =====

<code http>
POST /payments/{id}/refund
</code>

----

====== Module CRM ======

===== Leads =====

<code http>
GET /crm/leads

POST /crm/leads

PUT /crm/leads/{id}

DELETE /crm/leads/{id}
</code>

----

===== Activités =====

<code http>
GET /crm/activities

POST /crm/activities
</code>

----

====== Module Messaging ======

===== Conversations =====

<code http>
GET /conversations

POST /conversations

GET /conversations/{id}
</code>

----

===== Messages =====

<code http>
GET /conversations/{id}/messages

POST /conversations/{id}/messages
</code>

----

====== Module Reporting ======

===== Dashboard =====

<code http>
GET /reports/dashboard
</code>

----

===== KPI =====

<code http>
GET /reports/kpis
</code>

----

===== Export =====

<code http>
POST /reports/export
</code>

----

====== Validation métier ======

===== Property =====

<code yaml>
title:
  minLength: 5
  maxLength: 255

surface:
  minimum: 1

capacity:
  minimum: 1
</code>

----

===== Reservation =====

<code yaml>
startDate:
  required: true

endDate:
  required: true

guestCount:
  minimum: 1
</code>

----

===== Payment =====

<code yaml>
amount:
  minimum: 0.01
</code>

----

====== Codes erreurs ======

^ Code ^ HTTP ^ Description ^
| VALIDATION_ERROR | 400 | Données invalides |
| UNAUTHORIZED | 401 | Authentification requise |
| FORBIDDEN | 403 | Accès refusé |
| NOT_FOUND | 404 | Ressource inexistante |
| CONFLICT | 409 | Conflit métier |
| INTERNAL_ERROR | 500 | Erreur serveur |

----

====== Swagger ======

===== Configuration NestJS =====

<code ts>
const config =
  new DocumentBuilder()
    .setTitle('Rental API')
    .setDescription('Rental Platform API')
    .setVersion('1.0')
    .addBearerAuth()
    .build();
</code>

----

===== URL Swagger =====

<code>
https://api.location-platform.com/docs
</code>

----

====== Volume estimé ======

^ Domaine ^ Endpoints ^
| Auth | 15 |
| Users | 20 |
| Owners | 20 |
| Properties | 40 |
| Reservations | 35 |
| Contracts | 15 |
| Payments | 20 |
| CRM | 25 |
| Messaging | 15 |
| Reporting | 20 |
| Administration | 25 |

Total estimé : environ 250 endpoints REST.

----

====== Livrables générés ======

  * Contrat OpenAPI 3.1
  * Swagger UI
  * DTO TypeScript
  * SDK Frontend
  * SDK Mobile
  * Validation JSON Schema
  * Documentation API

----

====== Étape suivante ======

À partir de cette spécification OpenAPI, nous pouvons désormais produire :

  * Architecture Frontend NextJS 15
  * Organisation des pages App Router
  * Gestion d'état (TanStack Query)
  * Génération automatique du client API
  * Design System
  * Maquettes détaillées
  * Parcours utilisateurs
  * Backlog Agile complet

Le prochain livrable recommandé est :

**Backlog Agile détaillé (Epics → Features → User Stories → Tasks)**

Ce document deviendra la base du pilotage projet et des futurs sprints Scrum.