openapi: 3.0.3

info:
  title: Fundev Backend Framework API
  description: |
    API REST basada en framework propio PHP 8.1.
    Autenticación JWT, RBAC, Rate Limit, Refresh Token.
  version: "1.0.0"

servers:
  - url: https://admin.fundevstudio.com/api/v1
    description: Producción
  - url: http://localhost/backend/public/api/v1
    description: Local

tags:
  - name: Auth
  - name: User
  - name: Admin
  - name: Permissions

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string

security:
  - BearerAuth: []
paths:
  /auth/login:
    post:
      tags: [Auth]
      summary: Login de usuario
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                password:
                  type: string
      responses:
        200:
          description: Login exitoso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        401:
          description: Credenciales inválidas

  /auth/refresh:
    post:
      tags: [Auth]
      summary: Renovar access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refresh_token]
              properties:
                refresh_token:
                  type: string
      responses:
        200:
          description: Token renovado
  /profile:
    get:
      tags: [User]
      summary: Obtener perfil del usuario autenticado
      security:
        - BearerAuth: []
      responses:
        200:
          description: Perfil del usuario
  /admin/permissions:
    get:
      tags: [Permissions]
      summary: Listar permisos
      security:
        - BearerAuth: []
      responses:
        200:
          description: Lista de permisos

    post:
      tags: [Permissions]
      summary: Crear permiso
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
      responses:
        200:
          description: Permiso creado
tags:
  - name: Guides
    description: Gestión de guías Sharkpack
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
/api/v1/guides:
  post:
    tags: [Guides]
    summary: Crear guía manual
    security:
      - BearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - sender_client_id
              - receiver_client_id
            properties:
              sender_client_id:
                type: integer
                example: 1
              receiver_client_id:
                type: integer
                example: 2
    responses:
      200:
        description: Guía creada
        content:
          application/json:
            schema:
              type: object
              properties:
                guide_number:
                  type: string
                  example: SPABC123
      401:
        description: Unauthorized
      403:
        description: Forbidden
  get:
    tags: [Guides]
    summary: Listar guías del usuario autenticado
    security:
      - BearerAuth: []
    responses:
      200:
        description: Lista de guías
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                  guide_number:
                    type: string
                  status:
                    type: string
                  created_at:
                    type: string
                    format: date-time
/api/v1/guides/{id}:
  get:
    tags: [Guides]
    summary: Ver detalle de una guía
    security:
      - BearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    responses:
      200:
        description: Detalle de guía
      404:
        description: Guía no encontrada
/api/v1/guides/track/{number}:
  get:
    tags: [Guides]
    summary: Consulta pública de guía
    parameters:
      - name: number
        in: path
        required: true
        schema:
          type: string
          example: SPABC123
    responses:
      200:
        description: Estado de la guía
        content:
          application/json:
            schema:
              type: object
              properties:
                guide_number:
                  type: string
                status:
                  type: string
                created_at:
                  type: string
                  format: date-time
      404:
        description: Guía no encontrada
/api/v1/guides/{id}/status:
  put:
    tags: [Guides]
    summary: Actualizar estado de una guía
    security:
      - BearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [status]
            properties:
              status:
                type: string
                example: IN_TRANSIT
    responses:
      200:
        description: Estado actualizado
      403:
        description: Forbidden
/api/v1/guides/{id}/assign-courier:
  put:
    tags: [Guides]
    summary: Asignar repartidor a una guía
    security:
      - BearerAuth: []
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [courier_id]
            properties:
              courier_id:
                type: integer
                example: 5
    responses:
      200:
        description: Courier asignado
      403:
        description: Forbidden
