# Validación de campos

## Resumen

Este documento define una nueva estructura de validación simple y estandarizada para todos los _agentFields_.

**Principio Clave**: Todas las validaciones se definen directamente en el archivo `agent-fields.json`. No se necesitan archivos externos de reglas de validación.

## Estructura Estándar de Validación

**Todas las validaciones deben estar contenidas en un _array_ `validations` :**

Es aquí donde se contiene las diferentes reglas que se validan para el campo. Se define el tipo de validación, el valor que se debe validar y el mensaje de error que se muestra cuando rompe la regla.

{
  "id": "receiverAccountNumber",
  "label": "Número de cuenta",
  "placeholder": "Ingrese su número de cuenta",
  "type": "input",
  "validations": [
    {
      "type": "regex",
      "value": "^[0-9]{13,14}$",
      "message": "El número de cuenta debe tener 13-14 dígitos"
    }
  ]
}

## Tipos de Reglas Estándar

Inicialmente se considera la implementación de reglas comunes, permitiendo la escalabilidad mediante la expansión de ellas adicionando nuevas reglas a futuro según sea necesario.

### 1. Validación Regex

{
  "type": "regex",
  "value": "^[0-9]{13,14}$",
  "message": "Debe tener 13-14 dígitos"
}

### 2. Longitud Mínima

{
  "type": "min",
  "value": 6,
  "message": "Debe tener al menos 6 caracteres"
}

### 3. Longitud Máxima

{
  "type": "max",
  "value": 12,
  "message": "Debe tener como máximo 12 caracteres"
}

### 4. Requerido

{
  "type": "required",
  "message": "Este campo es requerido"
}

### 5. Email

{
  "type": "email",
  "message": "Debe ser una dirección de email válida"
}

### 6. Numérico

{
  "type": "numeric",
  "message": "Debe contener solo números"
}

## Proceso de estandarización

### Utilizando los formatos actuales

Actualmente se utiliza validaciones con diferentes estructuras, persiguiendo un mismo objetivo que es validar entradas en campos ya sea mediante formularios o al momento de validar los datos enviados en el servidor.
A cotinuación se entregan ejemplos de estandarización para las diferentes validaciones utilizadas actualmente.

#### Formato Actual 1 (String Simple)

// ❌ Actual
"validation": "^[0-9]{13,14}$"

// ✅ Estandarizado
"validations": [
  {
    "type": "regex",
    "value": "^[0-9]{13,14}$",
    "message": "Debe tener 13-14 dígitos"
  }
]

#### Formato Actual 2 (Array con Mensajes)

// ❌ Actual
"validation": [
  {
    "message": "Debe comenzar por 591",
    "pattern": "^591.*$"
  },
  {
    "message": "Debe tener 11 dígitos",
    "pattern": "^[0-9]{11}$"
  }
]

// ✅ Estandarizado
"validations": [
  {
    "type": "regex",
    "value": "^591.*$",
    "message": "Debe comenzar por 591"
  },
  {
    "type": "regex",
    "value": "^[0-9]{11}$",
    "message": "Debe tener 11 dígitos"
  }
]

#### Formato Actual 3 (Objeto con Pattern/Message)

// ❌ Actual
"validation": {
  "pattern": "^[0-9]{9}$|^[0-9]{10}$",
  "message": "Debe tener 9 o 10 dígitos"
}

// ✅ Estandarizado
"validations": [
  {
    "type": "regex",
    "value": "^[0-9]{9}$|^[0-9]{10}$",
    "message": "Debe tener 9 o 10 dígitos"
  }
]

### Validación de Campos Cruzados (fieldToValidate)

Para campos que validan otros campos, usa la misma estructura en las opciones:

{
  "id": "accountType",
  "fieldToValidate": "receiverAccountNumber",
  "options": [
    {
      "label": "CUENTA AHORRO",
      "value": "CA",
      "validations": [
        {
          "type": "regex",
          "value": "^[0-9]{13,14}$",
          "message": "La cuenta debe tener 13-14 dígitos"
        }
      ]
    }
  ]
}

### Ejemplo de Múltiples Reglas

"validations": [
  {
    "type": "required",
    "message": "El número de teléfono es requerido"
  },
  {
    "type": "regex",
    "value": "^591.*$",
    "message": "Debe comenzar con 591"
  },
  {
    "type": "regex",
    "value": "^[0-9]{11}$",
    "message": "Debe tener exactamente 11 dígitos"
  },
  {
    "type": "min",
    "value": 11,
    "message": "Debe tener al menos 11 caracteres"
  },
  {
    "type": "max",
    "value": 11,
    "message": "Debe tener como máximo 11 caracteres"
  }
]

## Atributos de Campo

### Atributo Placeholder

El atributo `placeholder` es un string que se muestra como texto de ayuda en los controles del frontend/mobile para guiar al usuario sobre qué información debe ingresar.

**Reglas por tipo de campo:**

- **Para campos `input`**: Usar ejemplos específicos cuando sea posible (ej: "59167890123" para teléfonos)
- **Para campos `select`**: Priorizar el uso de usar "Seleccione una opción"

**Buenas prácticas para placeholders:**

- Mantener el texto corto y descriptivo
- Usar formato consistente
- En el caso de _selects_ priorizar el uso del texto "Seleccione una opción" por defecto (salvo que sea necesaria una especificación más detallada)

**Consideraciones:**
Considerar como **necesaria** la definición del campo _placeholder_ con la intención de estandarizar los mensajes que se muestra al usuario en los diferentes clientes y que se entregue el texto definido desde el servidor, siendo agnóstico de la implementación en la vista de presentación.

### Estructura Completa de un Campo de agente (_agentField_)

Cada campo puede incluir los siguientes atributos:

{
  "id": "receiverAccountNumber",
  "afexId": "receiverProviderCode", // Opcional para mapeo con afexFields
  "label": "Número de cuenta",
  "placeholder": "Ingrese el número de cuenta del beneficiario",
  "type": "input|select",
  "fieldToValidate": "otherFieldId", // Opcional para validaciones cruzadas
  "options": [...], // Solo para type: "select" (placeholder: "Seleccione una opción")
  "validations": [...]
}

## Transformación hacia nueva estructura

Actualmente se presentan diferentes estructuras para definir validaciones, mencionadas en la seccion [Proceso de estandarización ](#Proceso-de-estandarización). Para realizar la migración hacia la nueva estructura de validaciones, se debe seguir los siguientes pasos:

1. **Encontrar todas las validaciones actuales** en agent-fields.json
2. **Convertir cada validación** al formato estándar:
- Cambiar de `{"validation": "..."` a `{"validations": [...]}`
- Cambiar `"pattern"` por `"type": "regex", "value"`
- Mantener/modificar mensajes existentes
- Agregar nuevas validaciones con sus correspondientes mensajes
3. **Agregar atributo placeholder** a todos los campos:
- Para campos `input`: Agregar placeholders descriptivos con ejemplos específicos
- Para campos `select`: Agregar `"placeholder": "Seleccione una opción"`
- Si no se desea mostrar placeholder, omitir la propiedad (el control no mostrará placeholder)
4. **Probar exhaustivamente** para asegurar que no hay cambios que rompan funcionalidad se debe generar un plan de pruebas riguroso

### Ejemplo de Migración Completa

// ❌ Formato Actual
{
  "id": "receiverAccountNumber",
  "label": "Número de cuenta",
  "type": "input",
  "validation": "^[0-9]{13,14}$"
}

// ✅ Formato Estandarizado con Placeholder
{
  "id": "receiverAccountNumber",
  "label": "Número de cuenta",
  "placeholder": "Ej: 12345678901234",
  "type": "input",
  "validations": [
    {
      "type": "required",
      "message": "El número de cuenta es requerido"
    },
    {
      "type": "regex",
      "value": "^[0-9]{13,14}$",
      "message": "El número de cuenta debe tener 13-14 dígitos"
    }
  ]
}

// ❌ Formato Actual (Select)
{
  "id": "receiverBankCode",
  "label": "Banco",
  "type": "select",
  "options": [
    {
      "label": "BANCO EJEMPLO",
      "value": "BE"
    }
  ]
}

// ✅ Formato Estandarizado con Placeholder
{
  "id": "receiverBankCode",
  "label": "Banco",
  "placeholder": "Seleccione una opción",
  "type": "select",
  "options": [
    {
      "label": "BANCO EJEMPLO",
      "value": "BE"
    }
  ],
  "validations": [
    {
      "type": "required",
      "message": "El banco es requerido"
    }
  ]
}

## Beneficios

- **Simple**: Solo una estructura de validación para recordar
- **Consistente**: Todos los campos usan el mismo formato
- **Flexible**: Múltiples reglas por campo
- **Claro**: Fácil de leer y entender
- **Mantenible**: Fácil agregar nuevos tipos de reglas

## Algunos ejemplos con casos actuales

[
  {
    "id": "BC-PE-1",
    "fields": [
      {
        "id": "receiverBankCode",
        "afexId": "receiverProviderCode",
        "label": "Banco",
        "placeholder": "Seleccione una opción",
        "options": [
          {
            "label": "BANCO DE CREDITO PERU",
            "value": "BC",
            "afexValue": "ADFW"
          }
        ],
        "type": "select",
        "validations": [
          {
            "type": "required",
            "message": "El banco es requerido"
          }
        ]
      },
      {
        "id": "accountType",
        "label": "Tipo de cuenta",
        "placeholder": "Seleccione una opción",
        "fieldToValidate": "receiverAccountNumber",
        "options": [
          {
            "label": "CUENTA AHORRO",
            "value": "CA",
            "validations": [
              {
                "type": "regex",
                "value": "^[0-9]{13,14}$",
                "message": "El número de cuenta debe tener 13-14 dígitos"
              }
            ]
          },
          {
            "label": "CUENTA CORRIENTE",
            "value": "CC",
            "validations": [
              {
                "type": "regex",
                "value": "^[0-9]{13,14}$",
                "message": "El número de cuenta debe tener 13-14 dígitos"
              }
            ]
          },
          {
            "label": "CUENTA MAESTRA",
            "value": "CM",
            "validations": [
              {
                "type": "regex",
                "value": "^[0-9]{13,14}$",
                "message": "El número de cuenta debe tener 13-14 dígitos"
              }
            ]
          }
        ],
        "type": "select",
        "validations": [
          {
            "type": "required",
            "message": "El tipo de cuenta es requerido"
          }
        ]
      },
      {
        "id": "receiverAccountNumber",
        "label": "Número de cuenta",
        "placeholder": "Ingrese el número de cuenta del beneficiario",
        "type": "input",
        "validations": [
          {
            "type": "required",
            "message": "El número de cuenta es requerido"
          }
        ]
      }
    ]
  },
  {
    "id": "BG-BO-1",
    "fields": [
      {
        "id": "receiverBankCode",
        "afexId": "receiverProviderCode",
        "label": "Banco",
        "placeholder": "Seleccione una opción",
        "options": [
          {
            "label": "BANCO GANADERO S.A.",
            "value": "BG",
            "afexValue": "ADSU"
          }
        ],
        "type": "select",
        "validations": [
          {
            "type": "required",
            "message": "El banco es requerido"
          }
        ]
      },
      {
        "id": "accountType",
        "label": "Tipo de cuenta",
        "placeholder": "Seleccione una opción",
        "options": [
          {
            "label": "CUENTA MAESTRA",
            "value": "0"
          }
        ],
        "type": "select",
        "validations": [
          {
            "type": "required",
            "message": "El tipo de cuenta es requerido"
          }
        ]
      },
      {
        "id": "receiverAccountNumber",
        "label": "Número de cuenta",
        "placeholder": "Ej: 1234567890123456789",
        "type": "input",
        "validations": [
          {
            "type": "required",
            "message": "El número de cuenta es requerido"
          },
          {
            "type": "regex",
            "value": "^[0-9]{10,20}$",
            "message": "El número de cuenta debe tener 10-20 dígitos"
          }
        ]
      }
    ]
  },
  {
    "id": "PHONE-BO-1",
    "fields": [
      {
        "id": "receiverPhoneNumber",
        "label": "Número de teléfono",
        "placeholder": "Ej: 59167890123",
        "type": "input",
        "validations": [
          {
            "type": "required",
            "message": "El número de teléfono es requerido"
          },
          {
            "type": "regex",
            "value": "^591.*$",
            "message": "Debe comenzar por 591"
          },
          {
            "type": "regex",
            "value": "^591[67].*$",
            "message": "Debe comenzar por 591 seguido de 6 o 7"
          },
          {
            "type": "regex",
            "value": "^[0-9]{11}$",
            "message": "Debe tener 11 dígitos en total"
          }
        ]
      }
    ]
  },
  {
    "id": "ID-CO-1",
    "fields": [
      {
        "id": "idType",
        "label": "Tipo de identificación",
        "placeholder": "Seleccione una opción",
        "fieldToValidate": "receiverIdCode",
        "options": [
          {
            "label": "NIT",
            "agentValue": "TXID",
            "value": "5",
            "validations": [
              {
                "type": "regex",
                "value": "^[0-9]{9,10}$",
                "message": "El NIT debe tener 9-10 dígitos"
              }
            ]
          },
          {
            "label": "PASAPORTE",
            "agentValue": "CCPT",
            "value": "1",
            "validations": [
              {
                "type": "regex",
                "value": "^[a-zA-Z0-9]{5,12}$",
                "message": "El pasaporte debe tener 5-12 caracteres alfanuméricos"
              }
            ]
          },
          {
            "label": "CEDULA DE CIUDADANIA",
            "agentValue": "NIDN",
            "value": "7",
            "validations": [
              {
                "type": "regex",
                "value": "^[0-9]{6,10}$",
                "message": "La cédula debe tener 6-10 dígitos"
              }
            ]
          }
        ],
        "type": "select",
        "validation": {
          "rules": [
            {
              "type": "required",
              "message": "El tipo de identificación es requerido"
            }
          ]
        }
      },
      {
        "id": "receiverIdCode",
        "label": "Número de identificación",
        "placeholder": "Ingrese el número de identificación",
        "type": "input",
        "validation": {
          "rules": [
            {
              "type": "required",
              "message": "El número de identificación es requerido"
            },
            {
              "type": "regex",
              "value": "^([1-9]|[a-zA-Z]).*$",
              "message": "No puede iniciar con 0"
            },
            {
              "type": "min",
              "value": 6,
              "message": "Debe tener al menos 6 caracteres"
            },
            {
              "type": "max",
              "value": 12,
              "message": "Debe tener como máximo 12 caracteres"
            }
          ]
        }
      }
    ]
  },
  {
    "id": "EMAIL-EJEMPLO",
    "fields": [
      {
        "id": "receiverEmail",
        "label": "Correo electrónico",
        "placeholder": "[e-mail]",
        "type": "input",
        "validation": {
          "rules": [
            {
              "type": "required",
              "message": "El correo electrónico es requerido"
            },
            {
              "type": "email",
              "message": "Debe ser una dirección de correo válida"
            }
          ]
        }
      }
    ]
  },
  {
    "id": "BANCO-COMPLEJO-1",
    "fields": [
      {
        "id": "receiverBankCode",
        "label": "Banco",
        "placeholder": "Seleccione una opción",
        "options": [
          {
            "label": "BBVA COLOMBIA",
            "value": "1013",
            "afexValue": "ADDX",
            "validation": {
              "rules": [
                {
                  "type": "regex",
                  "value": "^[0-9]{9}$|^[0-9]{10}$|^[0-9]{16}$|^[0-9]{18}$|^[0-9]{20}$",
                  "message": "Debe tener 9, 10, 16, 18 o 20 dígitos"
                }
              ]
            }
          }
        ],
        "type": "select",
        "validation": {
          "rules": [
            {
              "type": "required",
              "message": "El banco es requerido"
            }
          ]
        }
      }
    ]
  }
]