Page bloquée

Cette page est actuellement bloquée pour modification par un autre utilisateur. Vous devez attendre que cet utilisateur ait terminé ou que le blocage de la page expire.
Actuellement bloqué par : 192.168.0.100,216.73.217.98
Le blocage expire à : 2026/09/19 17:14 (15 min)
Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
====== Phase 3 — Spécification OpenAPI 3.1 Enterprise ======

===== Objectif =====

À ce stade :

<code>
Schema Prisma
≈ 110 modèles

Architecture Hexagonale NestJS

DDD

CQRS

RBAC

Multi-Tenant

Enterprise Security

Internationalisation

IA
</code>

sont désormais définis.

La prochaine étape consiste à construire la :

<code>
Source de vérité contractuelle
</code>

du système :

<code>
openapi.yaml
</code>

qui permettra ensuite de générer automatiquement :

<code>
Swagger

DTO NestJS

Validation Zod

SDK TypeScript

Client React Query

Mocks

Tests contractuels

Documentation API
</code>

----

====== Stratégie ======

Vu la taille du projet :

<code>
100+ modèles

1000+ endpoints
</code>

nous allons procéder par domaines.

----

====== Découpage OpenAPI ======

===== Domaine 1 =====

Core & Security

<code>
/auth

/users

/roles

/permissions

/sessions

/mfa

/security
</code>

----

===== Domaine 2 =====

Owners

<code>
/owners

/owner-documents

/owner-bank-accounts
</code>

----

===== Domaine 3 =====

Properties

<code>
/properties

/property-media

/property-features

/property-rates

/property-availability
</code>

----

===== Domaine 4 =====

Customers

<code>
/customers

/customer-documents

/customer-notes
</code>

----

===== Domaine 5 =====

Reservations

<code>
/reservations

/reservation-guests

/reservation-pricing

/reservation-events
</code>

----

===== Domaine 6 =====

Contracts

<code>
/contracts

/contract-templates

/signatures
</code>

----

===== Domaine 7 =====

Finance

<code>
/payments

/refunds

/invoices

/accounting
</code>

----

===== Domaine 8 =====

CRM

<code>
/leads

/opportunities

/pipelines

/tasks

/activities
</code>

----

===== Domaine 9 =====

Messaging

<code>
/notifications

/conversations

/messages

/emails

/sms
</code>

----

===== Domaine 10 =====

Marketing

<code>
/campaigns

/segments

/marketing-events
</code>

----

===== Domaine 11 =====

Governance

<code>
/audit

/workflows

/feature-flags
</code>

----

===== Domaine 12 =====

OTA

<code>
/channels

/distributions

/channel-reservations

/syncs
</code>

----

===== Domaine 13 =====

Revenue

<code>
/pricing-rules

/dynamic-prices

/revenue-forecasts
</code>

----

===== Domaine 14 =====

Compliance

<code>
/consents

/risks

/incidents

/compliance-audits
</code>

----

===== Domaine 15 =====

Internationalisation

<code>
/countries

/currencies

/languages

/translations
</code>

----

===== Domaine 16 =====

IA

<code>
/ai/conversations

/ai/messages

/knowledge

/recommendations
</code>

----

====== Ordre recommandé ======

Pour démarrer la génération réelle du backend :

<code>
OpenAPI Domain 1
</code>

doit être produit en premier.

----

====== Phase 3-A ======

Core Security API

===== Modules =====

<code>
Auth

Users

Roles

Permissions

Sessions

MFA
</code>

----

===== Livrable =====

Premier fichier :

<code>
openapi-core-security.yaml
</code>

contenant :

  * Security Schemes
  * JWT
  * Refresh Token
  * Users API
  * Roles API
  * Permissions API
  * Pagination
  * Error Model
  * Validation Model

----

====== Exemple ======

===== Security Scheme =====

<code yaml>
components:

  securitySchemes:

    bearerAuth:

      type: http

      scheme: bearer

      bearerFormat: JWT
</code>

----

===== Endpoint =====

<code yaml>
GET /users
</code>

----

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

<code yaml>
200:

  description: Users list

  content:

    application/json:

      schema:

        $ref: '#/components/schemas/UserListResponse'
</code>

----

====== Phase 3-A.1 — OpenAPI Core Security ======

===== Objectif =====

Définir le premier contrat API officiel de la plateforme.

Ce document couvre :

<code>
Auth

Users

Roles

Permissions

Sessions

Refresh Tokens

MFA

Pagination

Filtering

Sorting

Error Handling
</code>

Compatible :

<code>
OpenAPI 3.1

NestJS

Swagger

OpenAPI Generator

Zod

React Query
</code>

----

====== Structure ======

===== Fichier =====

<code>
apps/api/openapi/openapi-core-security.yaml
</code>

----

====== En-tête OpenAPI ======

<code yaml>
openapi: 3.1.0

info:
  title: Rental Platform API
  version: 1.0.0
  description: Enterprise Rental Platform

servers:
  - url: https://api.company.com/v1
    description: Production

  - url: https://staging-api.company.com/v1
    description: Staging

tags:
  - name: Authentication
  - name: Users
  - name: Roles
  - name: Permissions
  - name: Sessions
  - name: MFA
</code>

----

====== Security ======

===== JWT =====

<code yaml>
components:

  securitySchemes:

    bearerAuth:

      type: http

      scheme: bearer

      bearerFormat: JWT
</code>

----

====== Common Schemas ======

===== UUID =====

<code yaml>
Uuid:

  type: string

  format: uuid
</code>

----

===== Timestamp =====

<code yaml>
Timestamp:

  type: string

  format: date-time
</code>

----

===== Pagination =====

<code yaml>
PaginationMeta:

  type: object

  properties:

    page:
      type: integer

    pageSize:
      type: integer

    total:
      type: integer

    totalPages:
      type: integer
</code>

----

====== Error Model ======

===== ApiError =====

<code yaml>
ApiError:

  type: object

  required:

    - code
    - message

  properties:

    code:
      type: string

    message:
      type: string

    details:
      type: object
</code>

----

===== ValidationError =====

<code yaml>
ValidationError:

  allOf:

    - $ref: '#/components/schemas/ApiError'

    - type: object

      properties:

        fields:

          type: array

          items:

            type: object

            properties:

              field:
                type: string

              message:
                type: string
</code>

----

====== Authentication ======

===== RegisterRequest =====

<code yaml>
RegisterRequest:

  type: object

  required:

    - email
    - password
    - firstName
    - lastName

  properties:

    email:
      type: string
      format: email

    password:
      type: string
      minLength: 8

    firstName:
      type: string

    lastName:
      type: string
</code>

----

===== LoginRequest =====

<code yaml>
LoginRequest:

  type: object

  required:

    - email
    - password

  properties:

    email:
      type: string
      format: email

    password:
      type: string
</code>

----

===== TokenResponse =====

<code yaml>
TokenResponse:

  type: object

  properties:

    accessToken:
      type: string

    refreshToken:
      type: string

    expiresIn:
      type: integer

    tokenType:
      type: string
      example: Bearer
</code>

----

====== POST /auth/register ======

<code yaml>
/auth/register:

  post:

    tags:
      - Authentication

    summary: Register user

    requestBody:

      required: true

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/RegisterRequest'

    responses:

      '201':

        description: User created

      '400':

        description: Validation error
</code>

----

====== POST /auth/login ======

<code yaml>
/auth/login:

  post:

    tags:
      - Authentication

    summary: Login

    requestBody:

      required: true

      content:

        application/json:

          schema:

            $ref: '#/components/schemas/LoginRequest'

    responses:

      '200':

        description: Authentication success

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/TokenResponse'
</code>

----

====== POST /auth/refresh ======

<code yaml>
/auth/refresh:

  post:

    tags:
      - Authentication

    summary: Refresh token
</code>

----

====== POST /auth/logout ======

<code yaml>
/auth/logout:

  post:

    security:

      - bearerAuth: []

    tags:

      - Authentication

    summary: Logout
</code>

----

====== Users ======

===== User =====

<code yaml>
User:

  type: object

  properties:

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

    email:
      type: string

    firstName:
      type: string

    lastName:
      type: string

    active:
      type: boolean

    createdAt:
      $ref: '#/components/schemas/Timestamp'
</code>

----

===== UserListResponse =====

<code yaml>
UserListResponse:

  type: object

  properties:

    data:

      type: array

      items:

        $ref: '#/components/schemas/User'

    meta:

      $ref: '#/components/schemas/PaginationMeta'
</code>

----

====== GET /users ======

<code yaml>
/users:

  get:

    security:

      - bearerAuth: []

    tags:

      - Users

    summary: List users

    parameters:

      - name: page
        in: query
        schema:
          type: integer

      - name: pageSize
        in: query
        schema:
          type: integer

      - name: search
        in: query
        schema:
          type: string

      - name: sort
        in: query
        schema:
          type: string

    responses:

      '200':

        description: User list

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/UserListResponse'
</code>

----

====== GET /users/{id} ======

<code yaml>
/users/{id}:

  get:

    security:

      - bearerAuth: []

    tags:

      - Users

    parameters:

      - name: id
        in: path
        required: true
        schema:
          format: uuid
          type: string

    responses:

      '200':

        description: User
</code>

----

====== POST /users ======

<code yaml>
/users:

  post:

    security:

      - bearerAuth: []

    tags:

      - Users

    summary: Create user
</code>

----

====== PATCH /users/{id} ======

<code yaml>
/users/{id}:

  patch:

    security:

      - bearerAuth: []

    tags:

      - Users
</code>

----

====== DELETE /users/{id} ======

<code yaml>
/users/{id}:

  delete:

    security:

      - bearerAuth: []

    tags:

      - Users
</code>

----

====== Roles ======

===== Role =====

<code yaml>
Role:

  type: object

  properties:

    id:
      type: string

    code:
      type: string

    name:
      type: string
</code>

----

====== Endpoints ======

<code>
GET    /roles

POST   /roles

GET    /roles/{id}

PATCH  /roles/{id}

DELETE /roles/{id}
</code>

----

====== Permissions ======

===== Permission =====

<code yaml>
Permission:

  type: object

  properties:

    id:
      type: string

    code:
      type: string

    name:
      type: string
</code>

----

====== Endpoints ======

<code>
GET /permissions

GET /permissions/{id}
</code>

----

====== User Roles ======

===== Endpoints =====

<code>
POST   /users/{id}/roles

DELETE /users/{id}/roles/{roleId}
</code>

----

====== Sessions ======

===== Session =====

<code yaml>
Session:

  type: object

  properties:

    id:
      type: string

    ipAddress:
      type: string

    userAgent:
      type: string

    lastActivityAt:
      type: string
      format: date-time
</code>

----

====== Endpoints ======

<code>
GET /sessions

DELETE /sessions/{id}
</code>

----

====== MFA ======

===== Enable MFA =====

<code>
POST /mfa/enable
</code>

----

===== Verify MFA =====

<code>
POST /mfa/verify
</code>

----

===== Disable MFA =====

<code>
POST /mfa/disable
</code>

----

====== HTTP Status Codes ======

<code>
200 OK

201 Created

204 No Content

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error
</code>

----

====== Headers ======

===== Multi Tenant =====

<code yaml>
X-Tenant-Id:
  required: true
</code>

----

===== Correlation =====

<code yaml>
X-Correlation-Id:
  required: false
</code>

----

====== Volume API ======

Phase 3-A.1 fournit :

<code>
≈ 25 endpoints

≈ 15 schemas

≈ 6 tags

≈ 3 security flows
</code>

----

====== Phase 3-A.2 — OpenAPI Owners & Properties ======

===== Objectif =====

Définir le premier domaine métier principal de la plateforme :

<code>
Owners

Properties

Property Media

Property Features

Property Availability

Property Rates
</code>

Ce domaine couvre :

<code>
Sprint 3

Catalogue Immobilier
</code>

et constitue le socle métier de :

<code>
Réservations

Contrats

Paiements

OTA

Revenue Management
</code>

----

====== Tags OpenAPI ======

<code yaml>
tags:

  - name: Owners

  - name: OwnerDocuments

  - name: OwnerBankAccounts

  - name: Properties

  - name: PropertyMedia

  - name: PropertyFeatures

  - name: PropertyAvailability

  - name: PropertyRates
</code>

----

====== Schémas ======

===== Owner =====

<code yaml>
Owner:

  type: object

  properties:

    id:
      type: string
      format: uuid

    ownerNumber:
      type: string

    firstName:
      type: string

    lastName:
      type: string

    email:
      type: string
      format: email

    phone:
      type: string

    active:
      type: boolean

    createdAt:
      type: string
      format: date-time
</code>

----

===== CreateOwnerRequest =====

<code yaml>
CreateOwnerRequest:

  type: object

  required:

    - firstName

    - lastName

    - email

  properties:

    firstName:
      type: string

    lastName:
      type: string

    email:
      type: string
      format: email

    phone:
      type: string
</code>

----

====== Endpoints Owners ======

===== Collection =====

<code>
GET    /owners

POST   /owners
</code>

----

===== Ressource =====

<code>
GET    /owners/{id}

PATCH  /owners/{id}

DELETE /owners/{id}
</code>

----

===== Recherche =====

<code>
GET /owners

?page=1

&pageSize=20

&search=dupont

&active=true

&sort=lastName
</code>

----

====== Owner Documents ======

===== Endpoints =====

<code>
GET    /owners/{id}/documents

POST   /owners/{id}/documents

DELETE /owners/{id}/documents/{documentId}
</code>

----

===== Upload =====

<code yaml>
multipart/form-data
</code>

----

===== Types =====

<code>
IDENTITY

TAX

INSURANCE

MANDATE

CONTRACT
</code>

----

====== Owner Bank Accounts ======

===== BankAccount =====

<code yaml>
BankAccount:

  type: object

  properties:

    id:
      type: string

    iban:
      type: string

    bic:
      type: string

    accountHolder:
      type: string
</code>

----

===== Endpoints =====

<code>
GET    /owners/{id}/bank-accounts

POST   /owners/{id}/bank-accounts

PATCH  /owners/{id}/bank-accounts/{accountId}

DELETE /owners/{id}/bank-accounts/{accountId}
</code>

----

====== Properties ======

===== Property =====

<code yaml>
Property:

  type: object

  properties:

    id:
      type: string
      format: uuid

    code:
      type: string

    title:
      type: string

    slug:
      type: string

    propertyType:
      type: string

    status:
      type: string

    published:
      type: boolean

    maxGuests:
      type: integer

    bedrooms:
      type: integer

    bathrooms:
      type: integer

    surface:
      type: number

    createdAt:
      type: string
      format: date-time
</code>

----

===== CreatePropertyRequest =====

<code yaml>
CreatePropertyRequest:

  type: object

  required:

    - title

    - propertyType

  properties:

    title:
      type: string

    description:
      type: string

    propertyType:
      type: string

    maxGuests:
      type: integer

    bedrooms:
      type: integer

    bathrooms:
      type: integer
</code>

----

====== Endpoints Properties ======

===== Collection =====

<code>
GET    /properties

POST   /properties
</code>

----

===== Ressource =====

<code>
GET    /properties/{id}

PATCH  /properties/{id}

DELETE /properties/{id}
</code>

----

===== Publication =====

<code>
POST /properties/{id}/publish

POST /properties/{id}/unpublish
</code>

----

===== Recherche =====

<code>
GET /properties

?search=villa

?propertyType=HOUSE

?published=true

?ownerId=xxx

?page=1

&pageSize=20
</code>

----

====== Property Address ======

===== Endpoints =====

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

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

----

====== Property Owners ======

===== Affectation =====

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

POST /properties/{id}/owners

DELETE /properties/{id}/owners/{ownerId}
</code>

----

====== Property Media ======

===== PropertyMedia =====

<code yaml>
PropertyMedia:

  type: object

  properties:

    id:
      type: string

    fileUrl:
      type: string

    title:
      type: string

    position:
      type: integer

    isCover:
      type: boolean
</code>

----

===== Endpoints =====

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

POST   /properties/{id}/media

PATCH  /properties/{id}/media/{mediaId}

DELETE /properties/{id}/media/{mediaId}
</code>

----

===== Upload =====

<code yaml>
multipart/form-data
</code>

----

====== Property Features ======

===== PropertyFeature =====

<code yaml>
PropertyFeature:

  type: object

  properties:

    id:
      type: string

    code:
      type: string

    label:
      type: string
</code>

----

===== Exemples =====

<code>
POOL

WIFI

AIR_CONDITIONING

PARKING

SEA_VIEW

JACUZZI
</code>

----

===== Endpoints =====

<code>
GET /property-features

GET /properties/{id}/features

POST /properties/{id}/features

DELETE /properties/{id}/features/{featureId}
</code>

----

====== Property Availability ======

===== Availability =====

<code yaml>
Availability:

  type: object

  properties:

    id:
      type: string

    startDate:
      type: string
      format: date

    endDate:
      type: string
      format: date

    available:
      type: boolean
</code>

----

===== Endpoints =====

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

POST /properties/{id}/availability

PATCH /availability/{id}

DELETE /availability/{id}
</code>

----

===== Recherche =====

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

?from=2026-07-01

&to=2026-07-31
</code>

----

====== Property Rates ======

===== PropertyRate =====

<code yaml>
PropertyRate:

  type: object

  properties:

    id:
      type: string

    startDate:
      type: string
      format: date

    endDate:
      type: string
      format: date

    nightlyRate:
      type: number

    minimumStay:
      type: integer
</code>

----

===== Endpoints =====

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

POST /properties/{id}/rates

PATCH /property-rates/{id}

DELETE /property-rates/{id}
</code>

----

====== Property Search API ======

===== Endpoint public =====

<code>
GET /catalog/properties
</code>

----

===== Filtres =====

<code>
destination

checkIn

checkOut

guests

priceMin

priceMax

bedrooms

features
</code>

----

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

<code yaml>
PropertySearchResponse:

  type: object

  properties:

    data:

      type: array

      items:

        $ref: '#/components/schemas/Property'

    meta:

      $ref: '#/components/schemas/PaginationMeta'
</code>

----

====== Permissions RBAC ======

===== Owners =====

<code>
owners.read

owners.create

owners.update

owners.delete
</code>

----

===== Properties =====

<code>
properties.read

properties.create

properties.update

properties.publish

properties.delete
</code>

----

====== Volume API ======

Cette phase ajoute :

<code>
≈ 42 endpoints

≈ 12 schémas OpenAPI

≈ 8 tags Swagger
</code>

----

====== Cumul OpenAPI ======

Après Phase 3-A.2 :

<code>
≈ 67 endpoints

≈ 30 schémas

≈ 14 tags
</code>

----

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

===== Phase 3-A.3 =====

OpenAPI Customers & Reservations

<code>
Customers

Reservation

ReservationGuest

ReservationPricing

ReservationEvents

ReservationStatusHistory
</code>

Cette phase ajoutera environ :

<code>
50 endpoints
</code>

et permettra de couvrir intégralement :

<code>
Sprint 4

Réservations & Calendrier
</code>