ADR-023: Las reglas de formato del documento de identidad viven en el catálogo
Date: 2026-10-07 Status: Accepted — decisión D3-15 (a) de Carlos (2026-10-05) y valor por defecto de QC-30, implementado el 2026-10-07 en la entrega G11 del plan de ajustes v3 (G11.1 a G11.6, más la lista de países de G10 que comparte el ABM). Qué está hecho: las cuatro columnas y sus tres CHECK, la migración de datos con los formatos del cliente, la regla FormatoDeIdentificacion en datosPago() y pay(), el ABM (validación y auditoría), el combo /catalogos con las reglas, los números de la demo, el formulario del pago (que lee las reglas y no las duplica), el aviso de los datos viejos y el editor de reglas en Catálogos. Qué queda abierto: la confirmación del cliente de QC-30 (separadores del DPI), con su comportamiento por defecto ya implementado y reversible (§4). El plan de ajustes v3 llama a este ADR «ADR-019» (numeración provisoria): la definitiva es 023. Extends: ADR-011 (los datos del pago se validan al guardar y al pagar; este ADR agrega el formato del número de identificación) y ADR-016 (ningún dato personal en mensajes ni en Auditoría).
Context
El cliente (Magaly, CIS-EC, 2026-10-02, hoja «Catálogo Tipos ID») definió un formato y un país emisor para cada tipo de identificación que la herramienta tiene que respetar al cargar el pago (RV3-79 a 82):
| Tipo | Formato | País emisor |
|---|---|---|
| DPI | 13 caracteres, solo números | GT, siempre |
| Pasaporte | de 7 a 13 caracteres, letras y números | cualquiera |
Hasta G11 no existía ninguna regla: identification_number era nullable|string|max:60 e identification_country solo pedía 2 letras que existieran en la lista, así que se podía guardar un DPI de 4 dígitos o uno emitido por Ecuador. Los tipos de identificación son datos del catálogo (catalog_items, A4): un Admin los crea y los edita desde Catálogos, no son una lista fija del código. Eso condiciona dónde puede vivir la regla.
Decision
1. Cuatro columnas nullable en catalog_items, solo para ID_TYPE (G11.1)
| Columna | Valores | null significa |
|---|---|---|
id_charset | numeric (solo dígitos) · alphanumeric (letras y dígitos) | cualquier carácter |
id_min_length | entero ≥ 1 | sin mínimo |
id_max_length | entero ≥ 1 | sin máximo |
id_issuing_country | código de 2 letras de la lista de países | cualquier país |
Todo null es «sin reglas». Los ítems que ya existían quedan así y siguen sin validarse (D9: los datos y los tipos viejos no se tocan). Tres CHECK a nivel base, porque el ABM no es la única puerta a la tabla y la regla de pago confía en lo que lee: (a) solo un ID_TYPE puede traer reglas (catalog_items_id_rules_only_for_id_type), (b) el conjunto de caracteres es uno de los dos conocidos (catalog_items_id_charset_valid), (c) los largos son ≥ 1 y el mínimo no supera al máximo (catalog_items_id_length_valid). Las cotas que un CHECK no puede expresar o que necesitan un mensaje las valida el ABM: el máximo de 60 (el largo de transactions.identification_number: un mínimo mayor no se cumpliría nunca) y que el país emisor exista y esté activo en la lista global —es un dato de otra fila de la misma tabla—.
2. Sin expresiones regulares que escriba el Admin
El Admin elige entre un conjunto cerrado de caracteres y dos números; el backend arma el chequeo (App\Rules\FormatoDeIdentificacion: ctype_digit para numeric, \A[A-Za-z0-9]+\z para alphanumeric, y el largo en caracteres). Una expresión escrita por una persona puede colgar el servidor (ReDoS) o rechazar todos los pagos de un país con un error de tipeo, y la regla pasa por un ABM que cualquiera con abm_catalogos:write puede abrir. Son ASCII a propósito (un dígito arábigo, uno de ancho completo o una letra con tilde no son lo que el cliente definió) y con \z y no $ (que acepta un salto de línea final).
3. Cuándo se valida, y cuándo no (G11.3)
datosPago() y pay() validan identification_number e identification_country contra el tipo efectivo: el de identification_type en ESTE request —aunque sea para cambiarlo— o, si no viene, el que la transacción ya tiene guardado (el mismo patrón que la provincia efectiva de la ciudad). Se resuelve contra el ítem activo del catálogo del país de la transacción —nunca uno que mande el request—.
- Sin tipo resoluble, o con un tipo sin reglas, no se valida nada (D9): una transacción sin tipo, con un texto libre de antes de los combos, con un tipo desactivado, o con un tipo que un Admin acaba de crear sin reglas. Los datos viejos quedan como están y solo se rompe lo que alguien vuelve a mandar.
PAIDyCANCELLEDno se validan: se contestan con el 409 de siempre (PAYMENT_DATA_LOCKEDendatosPago(),INVALID_STATUS_TRANSITIONenpay()), no con un 422 de formato sobre una transacción cerrada. El número que quedó guardado en una pagada es inmutable (ADR-011) y el reporte de Cumplimiento lo exporta tal cual, aunque hoy no pasara la regla: un test lo fija.- Una
ACCEPTEDcon un número viejo fuera de formato no se puede pagar así:pay()recibe siempre el estado completo del formulario, y el número que reenvía se valida como cualquier valor nuevo (422 con el mensaje). El operador lo corrige. - El país emisor se compara con el código exacto (
GT≠gt): es el de la lista de países, y la reglaexistsya exige que el país esté activo. Un Pasaporte (id_issuing_country = null) acepta cualquier país.
4. Estricto, sin separadores (QC-30, valor por defecto)
El servidor exige el número limpio: 2999 99999 0101 y 2999-99999-0101 dan 422. El formulario (G11.5) quita espacios y guiones al tipear o pegar, así que quien lo usa nunca ve el rechazo; la regla literal del cliente («13 caracteres numéricos») queda cumplida en el servidor. Si el cliente pidiera aceptar separadores, se normaliza en el backend antes de validar y se cambia este punto: la regla (\A…\z) ya no tendría que tocarse. No se valida el dígito verificador del DPI: no lo pidieron.
5. El mensaje y la Auditoría no repiten lo que se tipeó (ADR-016)
El texto del 422 dice la regla y nada del valor, ni siquiera su largo. Nombra al tipo con su etiqueta entera (FormatoDeIdentificacion interpola $tipo->label): con la etiqueta que dejó G10 sale «El número de DPI (Documento Personal de Identificación) tiene que tener 13 dígitos, solo números.»; «… Pasaporte tiene que tener entre 7 y 13 caracteres, solo letras y números.»; «DPI (Documento Personal de Identificación) lo emite Guatemala: el país de la identificación tiene que ser Guatemala.». El formulario dice lo mismo con el nombre corto del tipo («El número de DPI tiene que tener 13 dígitos, solo números.», §8): son dos textos para la misma regla, el del servidor es el que decide y el que se lee cuando el rechazo llega de allá. Lo que llega a un 422 acaba en pantallas, en el log de la aplicación y en lo que copie el operador, y un número de documento es un dato personal. La Auditoría de los datos del pago ya guarda solo los nombres de los campos que cambiaron (TRANSACTION_PAYMENT_DATA_UPDATED): no cambia.
6. Quién edita las reglas, y cómo queda registrado (G11.4)
Las edita el Admin desde Catálogos (abm_catalogos:write), sin deploy: un formato mal pensado (un pasaporte real de 6 caracteres) no debe obligar a un deploy para poder pagar. El ABM rechaza con 422: reglas sobre un ítem que no es ID_TYPE, un conjunto de caracteres desconocido, un largo fuera de 1 a 60, un mínimo mayor que el máximo (se compara contra el valor ya guardado cuando el request manda solo uno de los dos) y un país emisor que no está en la lista o está desactivado. Mandar null en los cuatro vacía la regla. CATALOG_ITEM_CREATED y CATALOG_ITEM_UPDATED suman los cuatro campos —antes y después— solo para un ID_TYPE (en un país o un municipio serían cuatro null de relleno); no son datos personales, y son justo lo que cambia qué número puede pagar un Cajero.
El código de un país de la lista (G10.4, H3-07). El ABM de la lista global exige que el código de un COUNTRY sea de exactamente 2 letras mayúsculas (\A[A-Z]{2}\z): el pago valida identification_country con size:2 y id_issuing_country es el código de un ítem de esa lista, así que un país con otro código se podía dar de alta y después no se podía elegir ni ser emisor de nada. XK y AN entran; xk, XKX, X1 dan 422 (tanto en el alta como en la edición). Los demás tipos siguen con códigos de hasta 20 caracteres. El formulario pasa a mayúsculas lo que se tipea. Es la única restricción nueva de la lista global y es parte del contrato de POST y PUT /admin/catalogos.
7. Cómo llegan los formatos del cliente (G11.2)
Una migración de datos fija el DPI (numeric, 13/13, GT) y el Pasaporte (alphanumeric, 7/13, sin emisor) de Guatemala solo si sus cuatro columnas siguen en null: un ítem que un Admin ya tocó, aunque sea en una sola columna, no se pisa. Busca el país por iso_code, no crea ni activa ni renombra nada, es idempotente y deja un evento de Auditoría sin usuario con los códigos que fijó. El seeder de desarrollo los toma de la sección reglas_de_identificacion de catalogo_guatemala.php —aparte de tipos_identificacion, que sigue siendo código → etiqueta porque la migración de B1.2 lo lee así—, y un test cruza los dos.
8. El frontend lee las reglas, no las duplica (G11.5 y G11.6)
GET /catalogos?type=ID_TYPE devuelve las cuatro columnas junto con el tipo. El formulario de Pago (DatosPagoForm.vue) arma con esos valores su aviso en línea, el maxlength, el teclado numérico y el bloqueo del país: no hay un «13» ni un «GT» escritos en la pantalla, así que un tipo nuevo o una regla que el Admin edita funcionan sin tocar el código, y un tipo sin reglas no valida nada. Si el front y el back derivaran la regla por separado, se desalinearían. Lo que hace el formulario y el servidor no:
- Quita espacios y guiones al tipear, pegar o insertar un texto entero (QC-30), y solo cuando el tipo trae un conjunto de caracteres cerrado: sin él un guion puede ser parte del número y no se toca.
- Completa y bloquea el país emisor («El DPI lo emite Guatemala.») y lo desbloquea, conservando el valor, al pasar a un tipo sin emisor fijo.
- Avisa debajo del campo y bloquea «Guardar datos» mientras el número no cumpla. Los mensajes espejan los del servidor, con el nombre corto del tipo («DPI», «pasaporte») en lugar de la etiqueta entera; el servidor sigue siendo quien decide.
- Datos viejos (CAT-12). Una
ACCEPTEDcon un número ya guardado que no cumple muestra el aviso apenas se abre y deja «Iniciar pago» deshabilitado con el motivo escrito. El formulario le avisa a la pantalla (formatoInvalido) como ya hacía con los cambios sin guardar. Es un bloqueo de pantalla:pay()lo rechaza igual con 422 (§3), y si llega a ese 422 (la regla cambió con Pago abierto) la pantalla cierra el modal de confirmación y dice el motivo de cada campo (identification_numbereidentification_country), no el mensaje general de Laravel, que trae solo el primero y un «(and 1 more error)» en inglés. Mismo criterio que «Guardar datos». - Al cambiar el país de la transacción con el formulario montado (Pago pasa de una coincidencia a otra sin desmontarlo), los tipos del país anterior se sueltan apenas empieza la carga de los del nuevo —y si no cargan, quedan sueltos—: ahora deciden si «Guardar datos» e «Iniciar pago» se bloquean, y un tipo con el mismo código en dos países se juzgaría con la regla del otro. Sin tipos el formulario no valida; el servidor repite el control.
Consequences
- Un tipo nuevo, o uno con el código editado, nace sin reglas y no se valida en silencio: es lo contrario de lo que pasaría con la regla en el código por
code(alternativa b), pero igual hay que cargarla. El editor de Catálogos (G11.6) muestra una columna «Formato» para que se vea quién no la tiene. - Rechazar un pago por un formato demasiado estricto frena el mostrador. Mitigado: las reglas son editables y quedan auditadas.
- Si un Admin desactiva
GTen la lista de países, ningún DPI se puede guardar (identification_countryno pasaexists, y el emisor del DPI esGT), tampoco el de una transacción que espera el pago. El ABM no lo impide: desactivar un país de la lista es una decisión que no le toca a esta regla. Lo que sí hace es no callarlo: el diálogo de confirmación de desactivar un país avisa que, si algún tipo de identificación lo tiene como país emisor, dejará de poder guardarse y pagarse con ese tipo. Se evaluó que el backend rechace con 422 desactivar (o cambiar el código de) un país que es emisor de un tipo activo y se descartó por ahora: sería una restricción nueva sobre un ABM que el plan no pidió tocar, y desactivar es reversible en un clic. Si pasara en Staging, se revisa. - Lo mismo si se le cambia el
codea un país de la lista.id_issuing_countryy lo que guardan los pagos son el código de texto, sin clave foránea: al recodificarGT, el DPI sigue exigiendoGTy ningún país de la lista lo es, y los pagos viejos se imprimen con el código viejo (GT) en lugar del nombre del país (EtiquetasDeCatalogodevuelve el código cuando no lo encuentra). Es peor que desactivar porque no tiene diálogo: el editor del código de un país trae un aviso junto al campo, y no hay migración que lo arregle sola (se vuelve a poner el código). - Los pagos ya hechos con un número fuera de formato salen así en Cumplimiento (inmutables, ADR-011): la consulta de solo lectura que cuenta cuántos hay es la 8 de G0.6.
- No se valida el dígito verificador del DPI. El cliente definió el largo y los caracteres, no el algoritmo; un DPI de 13 dígitos con un verificador equivocado se acepta. Sumarlo después es una regla más en
FormatoDeIdentificacion, sin tocar el modelo de datos ni las columnas. - Cuatro columnas por tipo no escalan si más adelante se necesitan atributos por ítem de catálogo (por ejemplo, formas de pago, D3-5): ahí hay que evaluar un
jsonbuna sola vez para todos los casos. Hoy son cuatro columnas tipadas con CHECK, que la base valida y el ORM no tiene que parsear.
Alternatives considered
- (b) Un archivo de configuración en el código, por
codede tipo. Descartada: un formato mal pensado obligaría a un deploy, y un tipo nuevo —o uno cuyo código el Admin editó— quedaría sin validar en silencio. - (c) Una columna
jsonbgenérica. Descartada por ahora: sin esquema, la base no puede garantizar nada de lo que guarda; solo tendría sentido si D3-5 resultara en un catálogo con atributos por ítem. - Una expresión regular que escriba el Admin. Descartada por el §2: ReDoS y reglas que rompen el pago.
- Normalizar separadores en el servidor (aceptar
2999 99999 0101y guardar los 13 dígitos). Es la otra lectura de QC-30; queda como evolución si el cliente la pide (§4).

