openapi: 3.0.0
info:
  title: Color API
  description: API pour gérer les stocks des couleurs.
  version: 1.0.0
servers:
  - url: http://localhost:3000/api

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "Entrez votre token JWT (obtenu via /login)"

tags:
  - name: User
    description: Gestion des utilisateurs et authentification
  - name: Color
    description: Gestion des couleurs et du stock
  - name: Admin
    description: Fonctionnalités d'administration
paths:
  /login:
    post:
      tags:
        - User
      summary: Authentifier un utilisateur et obtenir un token JWT.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: "admin"
                password:
                  type: string
                  example: "password123"
              required:
                - username
                - password
      responses:
        '200':
          description: Authentification réussie.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
        '400':
          description: Requête invalide (données manquantes ou mal formées).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Invalid request data"
        '401':
          description: Échec de l'authentification (nom d'utilisateur ou mot de passe incorrect).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Invalid username or password"
        '500':
          description: Erreur serveur.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Server error"

  /auth:
    get:
      tags:
        - User
      summary: Vérifier l'authentification et obtenir les permissions de l'utilisateur.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Authentification réussie.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Authenticated"
                  value:
                    type: object
                    properties:
                      permissions:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: "visitor"
                            description:
                              type: string
                              example: "accede uniquement aux données en lecture seule"
        '401':
          description: Non autorisé (token manquant ou invalide).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Unauthorized"
        '500':
          description: Erreur serveur.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Server error"


  /colors/list:
    post:
      tags:
        - Color
      summary: Obtenir la liste de toutes les couleurs avec leur disponibilité de stock.
      description: |
        Récupère toutes les couleurs avec leurs informations de disponibilité.
        Les stocks sont binaires : 0 = pas disponible, 1 = disponible.
      security:
        - bearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  type: string
                  enum: ["shiny_stock", "matte_stock", "sanded_stock", "no_stock"]
                  description: "Filtre par type de disponibilité"
                  example: "shiny_stock"
      responses:
        '200':
          description: Liste des couleurs récupérée avec succès.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    type:
                      type: string
                      example: "RAL"
                    name_fr:
                      type: string
                      example: "Rouge"
                    name_en:
                      type: string
                      example: "Red"
                    name_pt:
                      type: string
                      example: "Vermelho"
                    value:
                      type: string
                      example: "RAL3000"
                    color:
                      type: string
                      example: "FF0000"
                    shiny_stock:
                      type: integer
                      enum: [0, 1]
                      description: "Disponibilité stock brillant (0 = pas de stock, 1 = en stock)"
                      example: 1
                    matte_stock:
                      type: integer
                      enum: [0, 1]
                      description: "Disponibilité stock mat (0 = pas de stock, 1 = en stock)"
                      example: 0
                    sanded_stock:
                      type: integer
                      enum: [0, 1]
                      description: "Disponibilité stock sablée (0 = pas de stock, 1 = en stock)"
                      example: 1
                    deleted:
                      type: integer
                      example: 0
        '401':
          description: Non autorisé (token manquant ou invalide).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "No token provided"
                  status:
                    type: integer
                    example: 401
        '500':
          description: Erreur serveur.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: "Server error"
  /colors/modifyStock/{id}:
    post:
      tags:
        - Color
      summary: Modifier le stock d'une couleur spécifique.
      description: |
        ⚠️ **Permissions requises** : admin ou color manager
        
        Modifie la disponibilité des stocks (shiny, matte, sanded) d'une couleur.
        Les valeurs sont binaires : 0 = pas de stock, 1 = en stock.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: "ID unique de la couleur à modifier"
          example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shiny_stock:
                  type: integer
                  enum: [0, 1]
                  description: "Disponibilité stock brillant (0 = pas de stock, 1 = en stock)"
                  example: 1
                matte_stock:
                  type: integer
                  enum: [0, 1]
                  description: "Disponibilité stock mat (0 = pas de stock, 1 = en stock)"
                  example: 0
                sanded_stock:
                  type: integer
                  enum: [0, 1]
                  description: "Disponibilité stock sablée (0 = pas de stock, 1 = en stock)"
                  example: 1
              required:
                - shiny_stock
                - matte_stock
                - sanded_stock
      responses:
        '200':
          description: Stock modifié avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Color stock updated successfully"
                  status:
                    type: integer
                    example: 200
                  valid:
                    type: boolean
                    example: true
        '400':
          description: Données invalides (ID manquant ou valeurs de stock non valides - doivent être 0 ou 1).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Stock values must be 0 or 1"
                  valid:
                    type: boolean
                    example: false
        '401':
          description: Token manquant ou invalide.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Token requis"
        '403':
          description: Permissions insuffisantes (nécessite admin ou color manager).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Permissions insuffisantes"
        '404':
          description: Couleur non trouvée.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Color not found"
                  valid:
                    type: boolean
                    example: false
        '500':
          description: Erreur serveur.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Server error"
                  status:
                    type: integer
                    example: 500

  /colors/addColor:
    post:
      tags:
        - Admin
      summary: Ajouter une nouvelle couleur.
      description: |
        ⚠️ **Permissions requises** : admin uniquement
        
        Ajoute une nouvelle couleur avec sa disponibilité de stock initiale.
        Les stocks sont binaires : 0 = pas disponible, 1 = disponible.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                nameFr:
                  type: string
                  description: "Nom de la couleur"
                  example: "Rouge Cardinal"
                nameEn:
                  type: string
                  description: "Nom de la couleur en anglais"
                  example: "Cardinal Red"
                namePt:
                  type: string
                  description: "Nom de la couleur en portugais"
                  example: "Vermelho Cardeal"
                value:
                  type: string
                  description: "Code de la couleur (ex: RAL3000)"
                  example: "RAL3000"
                type:
                  type: string
                  description: "Type de la couleur (ex: RAL, Pantone)"
                  example: "RAL"
                deleted:
                  type: integer
                  description: "Statut de suppression (0 = actif, 1 = supprimé)"
                  example: 0
                color:
                  type: string
                  description: "Code hexadécimal de la couleur"
                  example: "#FF0000"
                shiny_stock:
                  type: integer
                  enum: [0, 1]
                  description: "Disponibilité stock brillant initial (0 = pas de stock, 1 = en stock)"
                  example: 1
                matte_stock:
                  type: integer
                  enum: [0, 1]
                  description: "Disponibilité stock mat initial (0 = pas de stock, 1 = en stock)"
                  example: 0
                sanded_stock:
                  type: integer
                  enum: [0, 1]
                  description: "Disponibilité stock sablée initial (0 = pas de stock, 1 = en stock)"
                  example: 1
              required:
                - nameFr
                - nameEn
                - namePt
                - type
                - value
                - color
                - shiny_stock
                - matte_stock
                - sanded_stock
      responses:
        '201':
          description: Couleur créée avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Color added successfully"
                  status:
                    type: integer
                    example: 201
                  valid:
                    type: boolean
                    example: true
                  value:
                    type: object
                    description: "Données de la couleur créée"
        '400':
          description: Données invalides ou manquantes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Invalid data provided"
                  valid:
                    type: boolean
                    example: false
        '401':
          description: Token manquant ou invalide.
        '403':
          description: Permissions insuffisantes (admin requis).
        '500':
          description: Erreur serveur.

  /colors/deleteColor/{id}:
    post:
      tags:
        - Admin
      summary: Supprimer une couleur (suppression logique).
      description: |
        ⚠️ **Permissions requises** : admin uniquement
        
        Effectue une suppression logique de la couleur (marque comme supprimée).
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: "ID unique de la couleur à supprimer"
          example: 1
      responses:
        '200':
          description: Couleur supprimée avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Color deleted successfully"
                  valid:
                    type: boolean
                    example: true
        '400':
          description: ID invalide (doit être un entier positif).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "id must be a positive integer"
                  valid:
                    type: boolean
                    example: false
        '401':
          description: Token manquant ou invalide.
        '403':
          description: Permissions insuffisantes (admin requis).
        '404':
          description: Couleur non trouvée.
        '500':
          description: Erreur serveur.

  /users:
    get:
      tags:
        - Admin
      summary: Obtenir la liste de tous les utilisateurs.
      description: |
        ⚠️ **Permissions requises** : admin uniquement
        
        Récupère la liste de tous les utilisateurs non supprimés.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Liste des utilisateurs récupérée avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Users retrieved successfully"
                  valid:
                    type: boolean
                    example: true
                  value:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        description:
                          type: string
                          description: "Description de l'utilisateur"
                          example: "Administrateur principal"
                        username:
                          type: string
                          example: "admin"
                        created_at:
                          type: string
                          format: date-time
                          example: "2024-01-01T10:00:00Z"
                        last_connexion:
                          type: string
                          format: date-time
                          example: "2024-10-06T14:30:00Z"
        '401':
          description: Token manquant ou invalide.
        '403':
          description: Permissions insuffisantes (admin requis).
        '500':
          description: Erreur serveur.

  /addUser:
    post:
      tags:
        - Admin
      summary: Créer un nouvel utilisateur.
      description: |
        ⚠️ **Permissions requises** : admin uniquement
        
        Crée un nouveau compte utilisateur avec les informations fournies.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  minLength: 3
                  description: "Nom d'utilisateur unique"
                  example: "newuser"
                description:
                  type: string
                  description: "Description de l'utilisateur"
                  example: "Nouvel utilisateur"
                password:
                  type: string
                  minLength: 6
                  description: "Mot de passe (minimum 6 caractères)"
                  example: "securepassword123"
              required:
                - username
                - password
      responses:
        '201':
          description: Utilisateur créé avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "User created successfully"
                  status:
                    type: integer
                    example: 201
                  valid:
                    type: boolean
                    example: true
                  value:
                    type: object
                    description: "Données de l'utilisateur créé"
        '400':
          description: Données invalides ou utilisateur déjà existant.
        '401':
          description: Token manquant ou invalide.
        '403':
          description: Permissions insuffisantes (admin requis).
        '500':
          description: Erreur serveur.

  /editUser/{id}:
    post:
      tags:
        - Admin
      summary: Modifier les données d'un utilisateur.
      description: |
        ⚠️ **Permissions requises** : admin uniquement
        
        Modifie les informations, mot de passe et permissions d'un utilisateur existant.
        
        **Changement de mot de passe :**
        - Le champ `password` est optionnel
        - Si fourni et non vide, le mot de passe sera mis à jour
        - Si vide ou omis, le mot de passe reste inchangé
        - Doit respecter : 10-50 caractères alphanumériques uniquement
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: "ID unique de l'utilisateur à modifier"
          example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  minLength: 3
                  description: "Nouveau nom d'utilisateur"
                  example: "updateduser"
                description:
                  type: string
                  description: "Nouvelle description de l'utilisateur"
                  example: "Utilisateur modifié"
                password:
                  type: string
                  minLength: 10
                  maxLength: 50
                  pattern: "^[a-zA-Z0-9]{10,50}$"
                  description: "Nouveau mot de passe (optionnel). Si fourni, doit contenir 10-50 caractères alphanumériques. Laisser vide pour ne pas changer le mot de passe."
                  example: "newpassword123"
                permissions:
                  type: array
                  items:
                    type: integer
                  description: "Liste des IDs des permissions à attribuer"
                  example: [1, 2, 3]
      responses:
        '200':
          description: Utilisateur modifié avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "User updated successfully"
                  status:
                    type: integer
                    example: 200
                  valid:
                    type: boolean
                    example: true
        '400':
          description: Données invalides ou ID non valide.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Password must be 10-50 characters long and contain only letters and numbers"
                  status:
                    type: integer
                    example: 400
                oneOf:
                  - properties:
                      message:
                        example: "id is not valid"
                  - properties:
                      message:
                        example: "Password must be 10-50 characters long and contain only letters and numbers"
                  - properties:
                      message:
                        example: "Password must be a string"
        '401':
          description: Token manquant ou invalide.
        '403':
          description: Permissions insuffisantes (admin requis).
        '404':
          description: Utilisateur non trouvé.
        '500':
          description: Erreur serveur.

  /deleteUser/{id}:
    post:
      tags:
        - Admin
      summary: Supprimer un utilisateur (suppression logique).
      description: |
        ⚠️ **Permissions requises** : admin uniquement
        
        Effectue une suppression logique de l'utilisateur (marque comme supprimé).
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: "ID unique de l'utilisateur à supprimer"
          example: 1
      responses:
        '200':
          description: Utilisateur supprimé avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "User deleted successfully"
                  status:
                    type: integer
                    example: 200
                  valid:
                    type: boolean
                    example: true
        '400':
          description: ID invalide (doit être un entier positif).
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "id is not valid"
                  status:
                    type: integer
                    example: 400
        '401':
          description: Token manquant ou invalide.
        '403':
          description: Permissions insuffisantes (admin requis).
        '404':
          description: Utilisateur non trouvé.
        '500':
          description: Erreur serveur.

  /permissions:
    get:
      tags:
        - Admin
      summary: Obtenir la liste de toutes les permissions disponibles.
      description: |
        ⚠️ **Permissions requises** : admin uniquement
        
        Récupère la liste complète des permissions disponibles dans le système.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Liste des permissions récupérée avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Permissions retrieved successfully"
                  valid:
                    type: boolean
                    example: true
                  value:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: "admin"
                        description:
                          type: string
                          example: "Accès complet au système"
        '401':
          description: Token manquant ou invalide.
        '403':
          description: Permissions insuffisantes (admin requis).
        '500':
          description: Erreur serveur.

  /permissions/{id}:
    get:
      tags:
        - Admin
      summary: Obtenir les permissions d'un utilisateur spécifique.
      description: |
        ⚠️ **Permissions requises** : admin uniquement
        
        Récupère la liste des permissions attribuées à un utilisateur donné.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: "ID unique de l'utilisateur"
          example: 1
      responses:
        '200':
          description: Permissions de l'utilisateur récupérées avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "User permissions retrieved successfully"
                  value:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: "visitor"
                        description:
                          type: string
                          example: "Accès en lecture seule"
        '401':
          description: Token manquant ou invalide.
        '403':
          description: Permissions insuffisantes (admin requis).
        '404':
          description: Utilisateur non trouvé.
        '500':
          description: Erreur serveur.

  /logs:
    get:
      tags:
        - Admin
      summary: Obtenir les logs de l'application.
      description: |
        ⚠️ **Permissions requises** : admin uniquement
        
        Récupère les logs d'activité et d'erreur de l'application pour le monitoring.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Logs récupérés avec succès.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Logs retrieved successfully"
                  value:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        action:
                          type: string
                          example: "COLOR_ADDED"
                        user_id:
                          type: integer
                          example: 1
                        timestamp:
                          type: string
                          format: date-time
                          example: "2024-10-06T14:30:00Z"
                        details:
                          type: string
                          example: "Nouvelle couleur RAL3000 ajoutée"
        '401':
          description: Token manquant ou invalide.
        '403':
          description: Permissions insuffisantes (admin requis).
        '500':
          description: Erreur serveur.