openapi: 3.0.0
info:
  title: PtitsPas API
  version: 1.0.0
  description: |
    API REST pour l'application PtitsPas.
    Ce contrat définit l'interface entre le Frontend (Flutter) et le Backend (NestJS).
  contact:
    name: PtitsPas Team
    email: admin@ptits-pas.fr

servers:
  - url: https://app.ptits-pas.fr/api
    description: Production
  - url: http://localhost:3000/api
    description: Développement local

paths:
  /auth/login:
    post:
      summary: Authentification utilisateur
      operationId: loginUser
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: admin@ptits-pas.fr
                password:
                  type: string
                  format: password
                  example: "4dm1n1strateur"
      responses:
        '200':
          description: Authentification réussie
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: Token JWT d'accès
                  refresh_token:
                    type: string
                    description: Token JWT de rafraîchissement
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          description: Identifiants invalides
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users:
    get:
      summary: Liste des utilisateurs
      operationId: listUsers
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - name: role
          in: query
          schema:
            $ref: '#/components/schemas/RoleType'
        - name: statut
          in: query
          schema:
            $ref: '#/components/schemas/StatutUtilisateurType'
      responses:
        '200':
          description: Liste des utilisateurs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          description: Non authentifié
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - role
        - statut
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        email:
          type: string
          format: email
          example: "parent@ptits-pas.fr"
        prenom:
          type: string
          example: "Jean"
        nom:
          type: string
          example: "Dupont"
        role:
          $ref: '#/components/schemas/RoleType'
        statut:
          $ref: '#/components/schemas/StatutUtilisateurType'
        telephone:
          type: string
          example: "0612345678"
        adresse:
          type: string
        photo_url:
          type: string
          format: uri
        cree_le:
          type: string
          format: date-time

    RoleType:
      type: string
      enum:
        - parent
        - assistante_maternelle
        - gestionnaire
        - administrateur
        - super_admin

    StatutUtilisateurType:
      type: string
      enum:
        - en_attente
        - actif
        - suspendu

    Error:
      type: object
      required:
        - message
        - statusCode
      properties:
        message:
          type: string
          example: "Identifiants invalides"
        statusCode:
          type: integer
          example: 401
        error:
          type: string
          example: "Unauthorized"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token JWT obtenu via /auth/login