cargaMasiva_api/src/excel/excel.documentation.ts

import { applyDecorators } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiConsumes, ApiBody, ApiResponse } from '@nestjs/swagger';

export class ExcelDocumentation {
  /**
   * Decorators Swagger para el endpoint POST /excel/verify
   */
  static verifyExcel() {
    return applyDecorators(
      ApiTags('Excel'),
      ApiOperation({
        summary: 'Verificar archivo Excel',
        description: 'Valida duplicados, filas en blanco y formato básico de los datos sin realizar carga en la base.'
      }),
      ApiConsumes('multipart/form-data'),
      ApiBody({
        schema: {
          type: 'object',
          properties: {
            file: {
              type: 'string',
              format: 'binary',
              description: 'Archivo Excel (.xlsx) con usuarios a validar'
            }
          }
        }
      }),
      ApiResponse({
        status: 200,
        description: 'Resultado de la validación',
        schema: {
          type: 'object',
          properties: {
            valid: { type: 'boolean', example: false },
            errors: {
              type: 'array',
              items: { type: 'string' },
              example: ['Fila 2: cuenta duplicada "42515101".', 'Fila 3: fecha de nacimiento inválida "1988051".']
            }
          }
        }
      }),
      ApiResponse({ status: 400, description: 'No se recibió archivo o formato inválido.' })
    );
  }

  /**
   * Decorators Swagger para el endpoint POST /excel/load
   */
  static loadExcel() {
    return applyDecorators(
      ApiTags('Excel'),
      ApiOperation({
        summary: 'Cargar archivo Excel',
        description: 'Valida y persiste los datos en la base de datos. Retorna el número de registros insertados.'
      }),
      ApiConsumes('multipart/form-data'),
      ApiBody({
        schema: {
          type: 'object',
          properties: {
            file: {
              type: 'string',
              format: 'binary',
              description: 'Archivo Excel (.xlsx) con usuarios a cargar'
            }
          }
        }
      }),
      ApiResponse({
        status: 201,
        description: 'Usuarios insertados correctamente',
        schema: {
          type: 'object',
          properties: {
            inserted: { type: 'number', example: 3 }
          }
        }
      }),
      ApiResponse({
        status: 400,
        description: 'Errores de validación o carga',
        schema: {
          type: 'object',
          properties: {
            errors: {
              type: 'array',
              items: { type: 'string' },
              example: ['Fila 5: rfc contiene caracteres inválidos.']
            }
          }
        }
      })
    );
  }
}