cargaMasiva_api/src/excel/excel.documentation.ts

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

export class ExcelDocumentation {
  static getMovimientos() {
    return applyDecorators(
      ApiBearerAuth(),
      ApiOperation({
        summary: 'Obtener movimientos',
        description:
          'Obtiene un listado paginado de movimientos según el origen del usuario autenticado.',
      }),
      ApiQuery({
        name: 'page',
        required: false,
        type: Number,
        example: 1,
        description: 'Número de página',
      }),
      ApiQuery({
        name: 'limit',
        required: false,
        type: Number,
        example: 10,
        description: 'Cantidad de registros por página',
      }),
      ApiResponse({
        status: 200,
        description: 'Listado de movimientos obtenido correctamente',
      }),
      ApiResponse({
        status: 401,
        description: 'No autorizado',
      }),
    );
  }

  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.'],
            },
          },
        },
      }),
    );
  }

  static downloadExcel() {
    return applyDecorators(
      ApiTags('Excel'),
      //ApiBearerAuth('bearer'),
      ApiOperation({
        summary: 'Descargar usuarios',
        description:
          'Exporta todos los usuarios en un archivo TSV (o CSV) y registra el movimiento.',
      }),
      ApiResponse({
        status: 200,
        description: 'TSV generado correctamente',
        content: {
          'text/tab-separated-values': {
            schema: {
              type: 'string',
              example: 'num_cuenta\\tnombre\\t...\\n...',
            },
          },
        },
      }),
      ApiResponse({ status: 401, description: 'No autorizado' }),
      ApiResponse({ status: 500, description: 'Error al generar descarga' }),
    );
  }

  static servAct() {
    return applyDecorators(
      ApiTags('Excel'),
      ApiOperation({
        summary: 'Obtener servicios activos',
        description:
          'Devuelve la lista de servicios activos registrados en el sistema',
      }),
      ApiResponse({
        status: 200,
        description: 'Lista de servicios activos',
        // type: ServActivoDto, // si tienes DTO
        // isArray: true,
      }),
      ApiResponse({
        status: 401,
        description: 'No autorizado',
      }),
    );
  }
}