openapi: 3.0.0
info:
  title: Activity
  description: 'API del módulo Activity de TransCend. Este módulo es responsable del
    registro y consulta de actividades de usuario dentro del sistema TransCend.


    **Propósito principal:**

    - Registrar todas las actividades realizadas por usuarios en el sistema

    - Proporcionar consultas paginadas de actividades por usuario

    - Facilitar auditoría y análisis de comportamiento de usuarios

    - Soporte para debugging y monitoreo de uso del sistema


    **Tipos de actividades registradas:**

    - C: Create (Creación de recursos)

    - R: Read (Lectura/Consulta de recursos)

    - U: Update (Actualización de recursos)

    - D: Delete (Eliminación de recursos)


    **Características principales:**

    - Autenticación JWT opcional (permite consultas públicas limitadas)

    - Paginación automática con mongoose-paginate-v2

    - Filtros por fecha (startDate/endDate)

    - Validación estricta de tipos de actividad y sistemas operativos

    '
  version: 1.0.0
  contact:
    email: support@cargoffer.com
  license: Private API - Access by agreement only
servers:
- url: https://api.pro.cargoffer.com
  description: Producción
components:
  schemas:
    UserActivity:
      type: object
      properties:
        _id:
          type: string
          description: ID único de MongoDB para la actividad
          example: 507f1f77bcf86cd799439011
        idUser:
          type: string
          description: ID del usuario que realizó la actividad
          example: 63d7907cbe76403b35da63df
        environment:
          type: string
          description: Entorno donde se realizó la actividad (development, staging,
            production)
          example: production
        type:
          type: string
          enum:
          - C
          - R
          - U
          - D
          description: 'Tipo de actividad realizada:

            - C: Create (Creación)

            - R: Read (Lectura)

            - U: Update (Actualización)

            - D: Delete (Eliminación)

            '
          example: C
        feature:
          type: string
          description: Nombre de la funcionalidad o módulo donde se realizó la actividad
          example: user_management
        origin:
          type: string
          description: Origen de la solicitud (web, mobile, api, etc.)
          example: web
        ip:
          type: string
          description: Dirección IP del usuario que realizó la actividad
          example: 192.168.1.100
        o_system:
          type: string
          enum:
          - android
          - linux
          - windows
          - apple
          - etc
          description: Sistema operativo del dispositivo del usuario
          example: windows
        timestamp:
          type: string
          format: date-time
          description: Fecha y hora exacta cuando se realizó la actividad
          example: '2025-01-13T10:30:00.000Z'
        url:
          type: string
          description: URL completa donde se realizó la actividad
          example: /api/users/63d7907cbe76403b35da63df
        createdAt:
          type: string
          format: date-time
          description: Fecha de creación del registro en la base de datos
          example: '2025-01-13T10:30:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Fecha de última actualización del registro
          example: '2025-01-13T10:30:00.000Z'
      required:
      - idUser
      - environment
      - type
      - feature
      - origin
      - ip
      - o_system
      - timestamp
      - url
    ActivityResponse:
      type: object
      properties:
        docs:
          type: array
          items:
            $ref: '#/components/schemas/UserActivity'
          description: Array de actividades encontradas
        total:
          type: integer
          description: Número total de actividades encontradas (sin paginación)
          example: 150
        limit:
          type: integer
          description: Número de actividades por página
          example: 25
        page:
          type: integer
          description: Página actual
          example: 1
        pages:
          type: integer
          description: Número total de páginas disponibles
          example: 6
    CreateActivityRequest:
      type: object
      properties:
        idUser:
          type: string
          description: ID del usuario (opcional si viene del JWT)
          example: 63d7907cbe76403b35da63df
        environment:
          type: string
          required: true
          description: Entorno de la actividad
          example: production
        type:
          type: string
          required: true
          enum:
          - C
          - R
          - U
          - D
          description: Tipo de actividad
          example: C
        feature:
          type: string
          required: true
          description: Funcionalidad utilizada
          example: user_profile
        origin:
          type: string
          required: true
          description: Origen de la solicitud
          example: web
        ip:
          type: string
          description: IP del usuario (opcional, se obtiene automáticamente)
          example: 192.168.1.100
        o_system:
          type: string
          required: true
          enum:
          - android
          - linux
          - windows
          - apple
          - etc
          description: Sistema operativo
          example: windows
        url:
          type: string
          required: true
          description: URL de la actividad
          example: /api/users/profile
      required:
      - environment
      - type
      - feature
      - origin
      - o_system
      - url
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
          description: Estado del servicio
          example: ok
        dbStatus:
          type: string
          enum:
          - connected
          - disconnected
          description: Estado de la conexión a la base de datos
          example: connected
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Mensaje descriptivo del error
          example: idUser is required
  parameters:
    Authorization:
      name: authorization
      in: header
      description: 'Token JWT de autenticación (opcional para consultas limitadas).

        Si no se proporciona, solo se permiten consultas básicas sin filtros de usuario.

        Formato: Bearer {token}

        '
      schema:
        type: string
        example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
    UserId:
      name: idUser
      in: query
      description: 'ID del usuario para filtrar actividades. Si no se proporciona
        y hay autenticación JWT,

        se usa automáticamente el ID del usuario autenticado.

        '
      schema:
        type: string
        example: 63d7907cbe76403b35da63df
    Page:
      name: page
      in: query
      description: Número de página para paginación (empieza en 1)
      schema:
        type: integer
        minimum: 1
        default: 1
        example: 1
    PageSize:
      name: pageSize
      in: query
      description: 'Número de actividades por página. Valores permitidos: 10, 25,
        50, 100.

        Si se proporciona un valor no permitido, se ajusta automáticamente al más
        cercano.

        '
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
        example: 25
    StartDate:
      name: startDate
      in: query
      description: 'Fecha de inicio para filtrar actividades (formato ISO 8601).

        Si no se proporciona, se usa 30 días atrás desde la fecha actual.

        '
      schema:
        type: string
        format: date-time
        example: '2025-01-01T00:00:00.000Z'
    EndDate:
      name: endDate
      in: query
      description: 'Fecha de fin para filtrar actividades (formato ISO 8601).

        Si no se proporciona, se usa la fecha actual.

        '
      schema:
        type: string
        format: date-time
        example: '2025-01-13T23:59:59.999Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token JWT obtenido del servicio de autenticación IAM
paths:
  /test:
    get:
      tags:
      - Health
      summary: Health check básico
      description: 'Endpoint simple de verificación de estado del servicio.

        No requiere autenticación y siempre retorna un estado "ok".

        '
      operationId: healthCheckBasic
      responses:
        '200':
          description: Servicio funcionando correctamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                    example: ok
  /health:
    get:
      tags:
      - Health
      summary: Health check con estado de base de datos
      description: 'Verificación completa del estado del servicio incluyendo la conexión
        a la base de datos MongoDB.

        Útil para monitoreo y load balancers.

        '
      operationId: healthCheckFull
      responses:
        '200':
          description: Servicio y base de datos funcionando correctamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '500':
          description: Error interno del servidor o problema con la base de datos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/:
    get:
      tags:
      - Activities
      summary: Obtener actividades de usuario
      description: 'Consulta las actividades realizadas por un usuario específico
        con soporte para paginación y filtros por fecha.


        **PARÁMETROS OBLIGATORIOS:**

        - `idUser`: ID del usuario cuyas actividades quieres consultar


        **PARÁMETROS OPCIONALES:**

        - `page`: Número de página (por defecto: 1)

        - `pageSize`: Actividades por página (10, 25, 50, 100 - por defecto: 25)

        - `startDate`: Fecha inicio filtro (formato ISO 8601, ej: "2025-01-01T00:00:00.000Z")

        - `endDate`: Fecha fin filtro (formato ISO 8601, ej: "2025-01-13T23:59:59.999Z")


        **COMPORTAMIENTO DE AUTENTICACIÓN:**

        - Si se proporciona JWT válido: Se pueden consultar actividades de cualquier
        usuario

        - Si no hay JWT: Solo se permiten consultas sin especificar idUser (retorna
        error)


        **FILTROS AUTOMÁTICOS:**

        - Si no se especifica startDate/endDate: Se filtra por los últimos 30 días

        - pageSize se ajusta automáticamente a valores permitidos (10, 25, 50, 100)


        **EJEMPLOS DE USO:**

        - Consultar actividades recientes: `GET /api/?idUser=63d7907cbe76403b35da63df`

        - Página específica: `GET /api/?idUser=63d7907cbe76403b35da63df&page=2&pageSize=50`

        - Rango de fechas: `GET /api/?idUser=63d7907cbe76403b35da63df&startDate=2025-01-01T00:00:00Z&endDate=2025-01-31T23:59:59Z`

        '
      operationId: getUserActivities
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/StartDate'
      - $ref: '#/components/parameters/EndDate'
      responses:
        '200':
          description: 'Actividades recuperadas exitosamente. La respuesta incluye:

            - `docs`: Array de actividades encontradas

            - `total`: Número total de actividades (sin paginación)

            - `limit`: Número de actividades por página

            - `page`: Página actual

            - `pages`: Número total de páginas disponibles

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityResponse'
        '400':
          description: 'Parámetros inválidos. Posibles causas:

            - idUser no proporcionado y sin autenticación JWT

            - Fechas en formato incorrecto (debe ser ISO 8601)

            - pageSize fuera del rango permitido

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Token JWT inválido o expirado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - Activities
      summary: Registrar nueva actividad
      description: "Registra una nueva actividad realizada por un usuario en el sistema.\n\
        \n**CAMPOS OBLIGATORIOS EN EL BODY:**\n- `environment`: Entorno (\"development\"\
        , \"staging\", \"production\")\n- `type`: Tipo de actividad (\"C\"=Create,\
        \ \"R\"=Read, \"U\"=Update, \"D\"=Delete)\n- `feature`: Nombre del módulo/funcionalidad\
        \ (ej: \"user_management\", \"dashboard\")\n- `origin`: Origen de la solicitud\
        \ (\"web\", \"mobile\", \"api\")\n- `o_system`: Sistema operativo (\"android\"\
        , \"linux\", \"windows\", \"apple\", \"etc\")\n- `url`: URL completa donde\
        \ se realizó la actividad\n\n**CAMPOS OPCIONALES:**\n- `idUser`: ID del usuario\
        \ (se obtiene automáticamente del JWT si está presente)\n\n**CAMPOS AUTOMÁTICOS\
        \ (NO INCLUIR EN REQUEST):**\n- `timestamp`: Se establece automáticamente\
        \ con la fecha/hora actual\n- `ip`: Se obtiene automáticamente de la solicitud\
        \ (soporte para proxies)\n\n**VALIDACIONES:**\n- `type` debe ser exactamente:\
        \ \"C\", \"R\", \"U\", o \"D\"\n- `o_system` debe ser uno de: \"android\"\
        , \"linux\", \"windows\", \"apple\", \"etc\"\n- Todos los campos requeridos\
        \ deben estar presentes y no vacíos\n\n**EJEMPLOS DE USO:**\n\n*Crear usuario:*\n\
        ```json\n{\n  \"environment\": \"production\",\n  \"type\": \"C\",\n  \"feature\"\
        : \"user_management\",\n  \"origin\": \"web\",\n  \"o_system\": \"windows\"\
        ,\n  \"url\": \"/api/users\"\n}\n```\n\n*Ver dashboard:*\n```json\n{\n  \"\
        environment\": \"production\",\n  \"type\": \"R\",\n  \"feature\": \"dashboard\"\
        ,\n  \"origin\": \"mobile\",\n  \"o_system\": \"android\",\n  \"url\": \"\
        /dashboard\"\n}\n```\n"
      operationId: createUserActivity
      parameters:
      - $ref: '#/components/parameters/Authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateActivityRequest'
            examples:
              CreateUser:
                summary: Registro de creación de usuario
                value:
                  idUser: 63d7907cbe76403b35da63df
                  environment: production
                  type: C
                  feature: user_management
                  origin: web
                  o_system: windows
                  url: /api/users
              UpdateProfile:
                summary: Actualización de perfil de usuario
                value:
                  environment: production
                  type: U
                  feature: user_profile
                  origin: mobile
                  o_system: android
                  url: /api/users/profile
              ViewDashboard:
                summary: Acceso al dashboard principal
                value:
                  environment: production
                  type: R
                  feature: dashboard_main
                  origin: web
                  o_system: linux
                  url: /dashboard
      responses:
        '200':
          description: 'Actividad registrada exitosamente. Retorna el objeto completo
            de la actividad creada

            incluyendo el ID generado por MongoDB y los campos automáticos (timestamp,
            ip, etc.)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserActivity'
        '400':
          description: 'Datos inválidos en la solicitud. Posibles causas:

            - Campos requeridos faltantes (environment, type, feature, origin, o_system,
            url)

            - Valores enum inválidos (type debe ser C/R/U/D, o_system debe ser válido)

            - Formato de datos incorrecto

            - Campos vacíos o nulos

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Token JWT inválido o expirado (si se requiere autenticación)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error interno del servidor (problemas de base de datos, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
security:
- BearerAuth: []