ujusum:3-codage:1-repository:3-spec-open-api
Ceci est une ancienne révision du document !
Table des matières
Phase 3 — Spécification OpenAPI 3.1 Enterprise
Objectif
À ce stade :
Schema Prisma ≈ 110 modèles Architecture Hexagonale NestJS DDD CQRS RBAC Multi-Tenant Enterprise Security Internationalisation IA
sont désormais définis.
La prochaine étape consiste à construire la :
Source de vérité contractuelle
du système :
openapi.yaml
qui permettra ensuite de générer automatiquement :
Swagger DTO NestJS Validation Zod SDK TypeScript Client React Query Mocks Tests contractuels Documentation API
Stratégie
Vu la taille du projet :
100+ modèles 1000+ endpoints
nous allons procéder par domaines.
Découpage OpenAPI
Domaine 1
Core & Security
/auth /users /roles /permissions /sessions /mfa /security
Domaine 2
Owners
/owners /owner-documents /owner-bank-accounts
Domaine 3
Properties
/properties /property-media /property-features /property-rates /property-availability
Domaine 4
Customers
/customers /customer-documents /customer-notes
Domaine 5
Reservations
/reservations /reservation-guests /reservation-pricing /reservation-events
Domaine 6
Contracts
/contracts /contract-templates /signatures
Domaine 7
Finance
/payments /refunds /invoices /accounting
Domaine 8
CRM
/leads /opportunities /pipelines /tasks /activities
Domaine 9
Messaging
/notifications /conversations /messages /emails /sms
Domaine 10
Marketing
/campaigns /segments /marketing-events
Domaine 11
Governance
/audit /workflows /feature-flags
Domaine 12
OTA
/channels /distributions /channel-reservations /syncs
Domaine 13
Revenue
/pricing-rules /dynamic-prices /revenue-forecasts
Domaine 14
Compliance
/consents /risks /incidents /compliance-audits
Domaine 15
Internationalisation
/countries /currencies /languages /translations
Domaine 16
IA
/ai/conversations /ai/messages /knowledge /recommendations
Ordre recommandé
Pour démarrer la génération réelle du backend :
OpenAPI Domain 1
doit être produit en premier.
Phase 3-A
Core Security API
Modules
Auth Users Roles Permissions Sessions MFA
Livrable
Premier fichier :
openapi-core-security.yaml
contenant :
- Security Schemes
- JWT
- Refresh Token
- Users API
- Roles API
- Permissions API
- Pagination
- Error Model
- Validation Model
Exemple
Security Scheme
components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT
Endpoint
GET /users
Réponse
200: description: Users list content: application/json: schema: $ref: '#/components/schemas/UserListResponse'
Phase 3-A.1 — OpenAPI Core Security
Objectif
Définir le premier contrat API officiel de la plateforme.
Ce document couvre :
Auth Users Roles Permissions Sessions Refresh Tokens MFA Pagination Filtering Sorting Error Handling
Compatible :
OpenAPI 3.1 NestJS Swagger OpenAPI Generator Zod React Query
Structure
Fichier
apps/api/openapi/openapi-core-security.yaml
En-tête OpenAPI
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
Security
JWT
components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT
Common Schemas
UUID
Uuid: type: string format: uuid
Timestamp
Timestamp: type: string format: date-time
Pagination
PaginationMeta: type: object properties: page: type: integer pageSize: type: integer total: type: integer totalPages: type: integer
Error Model
ApiError
ApiError: type: object required: - code - message properties: code: type: string message: type: string details: type: object
ValidationError
ValidationError: allOf: - $ref: '#/components/schemas/ApiError' - type: object properties: fields: type: array items: type: object properties: field: type: string message: type: string
Authentication
RegisterRequest
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
LoginRequest
LoginRequest: type: object required: - email - password properties: email: type: string format: email password: type: string
TokenResponse
TokenResponse: type: object properties: accessToken: type: string refreshToken: type: string expiresIn: type: integer tokenType: type: string example: Bearer
POST /auth/register
/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
POST /auth/login
/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'
POST /auth/refresh
/auth/refresh: post: tags: - Authentication summary: Refresh token
POST /auth/logout
/auth/logout: post: security: - bearerAuth: [] tags: - Authentication summary: Logout
Users
User
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'
UserListResponse
UserListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/User' meta: $ref: '#/components/schemas/PaginationMeta'
GET /users
/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'
GET /users/{id}
/users/{id}: get: security: - bearerAuth: [] tags: - Users parameters: - name: id in: path required: true schema: format: uuid type: string responses: '200': description: User
POST /users
/users: post: security: - bearerAuth: [] tags: - Users summary: Create user
PATCH /users/{id}
/users/{id}: patch: security: - bearerAuth: [] tags: - Users
DELETE /users/{id}
/users/{id}: delete: security: - bearerAuth: [] tags: - Users
Roles
Role
Role: type: object properties: id: type: string code: type: string name: type: string
Endpoints
GET /roles
POST /roles
GET /roles/{id}
PATCH /roles/{id}
DELETE /roles/{id}
Permissions
Permission
Permission: type: object properties: id: type: string code: type: string name: type: string
Endpoints
GET /permissions
GET /permissions/{id}
User Roles
Endpoints
POST /users/{id}/roles
DELETE /users/{id}/roles/{roleId}
Sessions
Session
Session: type: object properties: id: type: string ipAddress: type: string userAgent: type: string lastActivityAt: type: string format: date-time
Endpoints
GET /sessions
DELETE /sessions/{id}
MFA
Enable MFA
POST /mfa/enable
Verify MFA
POST /mfa/verify
Disable MFA
POST /mfa/disable
HTTP Status Codes
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
Headers
Multi Tenant
X-Tenant-Id: required: true
Correlation
X-Correlation-Id: required: false
Volume API
Phase 3-A.1 fournit :
≈ 25 endpoints ≈ 15 schemas ≈ 6 tags ≈ 3 security flows
Phase 3-A.2 — OpenAPI Owners & Properties
Objectif
Définir le premier domaine métier principal de la plateforme :
Owners Properties Property Media Property Features Property Availability Property Rates
Ce domaine couvre :
Sprint 3 Catalogue Immobilier
et constitue le socle métier de :
Réservations Contrats Paiements OTA Revenue Management
Tags OpenAPI
tags: - name: Owners - name: OwnerDocuments - name: OwnerBankAccounts - name: Properties - name: PropertyMedia - name: PropertyFeatures - name: PropertyAvailability - name: PropertyRates
Schémas
Owner
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
CreateOwnerRequest
CreateOwnerRequest: type: object required: - firstName - lastName - email properties: firstName: type: string lastName: type: string email: type: string format: email phone: type: string
Endpoints Owners
Collection
GET /owners POST /owners
Ressource
GET /owners/{id}
PATCH /owners/{id}
DELETE /owners/{id}
Recherche
GET /owners ?page=1 &pageSize=20 &search=dupont &active=true &sort=lastName
Owner Documents
Endpoints
GET /owners/{id}/documents
POST /owners/{id}/documents
DELETE /owners/{id}/documents/{documentId}
Upload
multipart/form-data
Types
IDENTITY TAX INSURANCE MANDATE CONTRACT
Owner Bank Accounts
BankAccount
BankAccount: type: object properties: id: type: string iban: type: string bic: type: string accountHolder: type: string
Endpoints
GET /owners/{id}/bank-accounts
POST /owners/{id}/bank-accounts
PATCH /owners/{id}/bank-accounts/{accountId}
DELETE /owners/{id}/bank-accounts/{accountId}
Properties
Property
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
CreatePropertyRequest
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
Endpoints Properties
Collection
GET /properties POST /properties
Ressource
GET /properties/{id}
PATCH /properties/{id}
DELETE /properties/{id}
Publication
POST /properties/{id}/publish
POST /properties/{id}/unpublish
Recherche
GET /properties ?search=villa ?propertyType=HOUSE ?published=true ?ownerId=xxx ?page=1 &pageSize=20
Property Address
Endpoints
GET /properties/{id}/address
PUT /properties/{id}/address
Property Owners
Affectation
GET /properties/{id}/owners
POST /properties/{id}/owners
DELETE /properties/{id}/owners/{ownerId}
Property Media
PropertyMedia
PropertyMedia: type: object properties: id: type: string fileUrl: type: string title: type: string position: type: integer isCover: type: boolean
Endpoints
GET /properties/{id}/media
POST /properties/{id}/media
PATCH /properties/{id}/media/{mediaId}
DELETE /properties/{id}/media/{mediaId}
Upload
multipart/form-data
Property Features
PropertyFeature
PropertyFeature: type: object properties: id: type: string code: type: string label: type: string
Exemples
POOL WIFI AIR_CONDITIONING PARKING SEA_VIEW JACUZZI
Endpoints
GET /property-features
GET /properties/{id}/features
POST /properties/{id}/features
DELETE /properties/{id}/features/{featureId}
Property Availability
Availability
Availability: type: object properties: id: type: string startDate: type: string format: date endDate: type: string format: date available: type: boolean
Endpoints
GET /properties/{id}/availability
POST /properties/{id}/availability
PATCH /availability/{id}
DELETE /availability/{id}
Recherche
GET /properties/{id}/availability
?from=2026-07-01
&to=2026-07-31
Property Rates
PropertyRate
PropertyRate: type: object properties: id: type: string startDate: type: string format: date endDate: type: string format: date nightlyRate: type: number minimumStay: type: integer
Endpoints
GET /properties/{id}/rates
POST /properties/{id}/rates
PATCH /property-rates/{id}
DELETE /property-rates/{id}
Property Search API
Endpoint public
GET /catalog/properties
Filtres
destination checkIn checkOut guests priceMin priceMax bedrooms features
Réponse
PropertySearchResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/Property' meta: $ref: '#/components/schemas/PaginationMeta'
Permissions RBAC
Owners
owners.read owners.create owners.update owners.delete
Properties
properties.read properties.create properties.update properties.publish properties.delete
Volume API
Cette phase ajoute :
≈ 42 endpoints ≈ 12 schémas OpenAPI ≈ 8 tags Swagger
Cumul OpenAPI
Après Phase 3-A.2 :
≈ 67 endpoints ≈ 30 schémas ≈ 14 tags
Étape suivante
Phase 3-A.3
OpenAPI Customers & Reservations
Customers Reservation ReservationGuest ReservationPricing ReservationEvents ReservationStatusHistory
Cette phase ajoutera environ :
50 endpoints
et permettra de couvrir intégralement :
Sprint 4 Réservations & Calendrier
ujusum/3-codage/1-repository/3-spec-open-api.1780859371.txt.gz · Dernière modification : 2026/06/07 21:09 de admin