Especificación del formato de schema

Todo lo que puede declarar un schema en /DataLab/config/upload_schemas/{OP_ID}. Esta es la referencia para crear o endurecer operaciones. Los cambios se propagan a los wizards en vivo (el loader usa onValue) — sin redeploy.

Estructura completa

{
  "op_id": "MOV_INT_ADMIN",             // = clave del nodo
  "area_id": "ORI",
  "title": "Movilidad internacional administrativos",
  "description": "…",

  // ── Hoja Excel ──
  "sheetName": "P_Admin_int_sal",       // pestaña REAL del template
  "sheetAliases": ["p_admin_int_sal", "datos", …],   // fuzzy match
  "headerRow": 18,                      // fila (1-indexed) de las cabeceras

  // ── Destino de datos ──
  "dataArrayField": "movilidad_int_admin",   // clave del array en el reporte
  "dataPathTemplate": "DataLab/ciclos_de_carga/ori/{cicloKey}/data/movilidad_int_admin",
  "configPath": "DataLab/config/ciclo_mov_int_admin",
  "codigoPrefix": "MIA",                // prefijo ÚNICO de certificados

  // ── Ciclo ──
  "defaultCicloKey": "2026-B",          // semestral: AAAA-A|B · mensual: AAAA-MM · anual: AAAA
  "cicloGranularity": "semestral",      // semestral | mensual | anual
  "reportNature": "acumulado",          // opcional: reportes acumulados al corte
  "reportNote": "…",

  // ── Validación ──
  "requiredColumns": ["semestre", "tipo_documento", …],  // ⚠ KEYS CANÓNICAS
  "criticalFields":  ["semestre", "tipo_documento", …],  // no pueden ir vacíos
  "dateColumns": ["fecha_inicio_movilidad"],             // reciben coerción de fecha
  "fields": [ … ],                // ver §Campos
  "fieldValidations": [ … ],      // ver §Validaciones
  "controlledValues": { … },      // ver §Catálogos
  "integrityRules": [ … ],        // ver §Reglas
  "additionalSheets": [ … ],      // ver §Multi-hoja
  "templateUrl": "https://…"      // se PRESERVA al reescribir el schema
}

Campos (fields[])

{
  "key": "numero_documento",       // snake_case canónico — así viaja a RTDB
  "label": "Número documento",     // para UI
  "type": "text",                  // text | number | date | currency | boolean
  "currency": "COP",               // solo type=currency (COP | USD)
  "required": true,                // el valor no puede faltar
  "requiredColumn": true,          // la COLUMNA debe existir en el Excel
  "min": 0, "max": 500,            // cotas para type=number
  "aliases": ["NÚMERO DOCUMENTO", "NUMERO DOCUMENTO", "IDENTIFICACIÓN"]
}

Validaciones (fieldValidations[])

type: "pattern"

{ "key": "semestre", "type": "pattern",
  "pattern": "^(20[2-3]\\d)\\s?-?\\s?(A|B|I|II|1|2|a|b|i|ii)$",
  "msg": "Formato: 2026-A, 2026-B, …",   // alineado con lo que el pattern acepta
  "nullable": false }                     // true ⇒ vacío es válido

Patrones de la casa (copiar tal cual):

type: "enum"

{ "key": "tipo_documento", "type": "enum",
  "values": ["CC", "cc", "C.C.", "CÉDULA DE CIUDADANÍA", …],
  "caseInsensitive": true,
  "nullable": false,
  "msg": "Tipo de documento debe estar en el catálogo" }

type: "date-range"

{ "key": "fecha_grado", "type": "date-range",
  "min": "2010-01-01",
  "max": "{today+30d}",      // placeholders: {today} {today±Nd} {today±Ny}
  "nullable": false, "msg": "…" }

Catálogos (controlledValues{})

Mapa key → valores permitidos. Convenciones:

• Variantes con y sin tilde, y de caja (MAYÚSCULA / Título / minúscula) para lo que los usuarios digitan.
• Booleanos SI/NO: incluir además VERDADERO/FALSO, TRUE/FALSE, 1/0, S/N (serializaciones de Excel). Nunca incluir el placeholder "SÍ / NO" del template.
• Un enum modela UNA dimensión: no mezclar dirección + modalidad + propósito en el mismo catálogo (ej. tipo_movilidad ≠ objeto_movilidad).
• Siempre incluir escapes: OTRO, N/A, NO APLICA.

Reglas de integridad (integrityRules[])

Las reglas usan severity: warning|info — advierten sin bloquear la carga.

Multi-hoja (additionalSheets[])

Para operaciones cuyo template trae más de una pestaña de datos:

• mode: "union" — misma entidad en dos hojas (ej. movilidad SALIENTE + ENTRANTE). Se declara direction e injectField (columna sintética, ej. direccion_movilidad: "ENTRANTE"). Cada hoja adicional lleva sus propios fields/validations/headerRow — pueden diferir de la principal (la hoja entrante suele añadir nombres/apellidos/sexo porque la persona es externa).
• joinKey (modo join) — hoja satélite que se une por clave a la principal (ej. beneficiarios por codigo_curso en EVENTOS_EDU_CONT).

Checklist para publicar un schema

1. Confirmar op_id EXACTO contra el catálogo (los ids largos se truncan en la UI).
2. sheetName y headerRow tomados del template REAL (varían: 18, 19, 20).
3. requiredColumns con keys canónicas, todas presentes en fields[].key.
4. Cada controlledValues con su validación enum + caseInsensitive.
5. Solo columnas identificadoras como required — el resto opcional con nullable: true.
6. Preservar templateUrl existente al reescribir (y nunca escribir undefined: RTDB lo rechaza).
7. Quitar __minimal y verificar que el chip pase a SCHEMA OK.
8. Agregar el dataArrayField a dataCandidates en procesar.html.
9. codigoPrefix único en todo el catálogo.