Códice Cotalker: El sello de tres letras que rescata tus formularios del olvido (parte 1)
Heredas un grimorio de Cotalker que no escribiste tú (o tal vez sí, pero hace tantos eones atrás que olvidaste tus propios conjuros). Abres la lista de hechizos del libro (más conocido como formularios) y te encuentras con esto:
Enviar a tienda
Aprobar solicitud
Recepción de mercadería
Confirmación de pago
Aprobar solicitud
Recepción de mercaderíaDos "Aprobar solicitud" y cuatro formularios más sin contexto. Ningún indicio de a qué flujo pertenece cada uno, ni cuál es startform, ni cuál es survey+survey. Por lo general, esto se vería algo así:
Lo único que nos queda es intentar filtrar por code, pero ¿Qué es 'aprobar_solicitud' y en qué se diferencia de 'aprobar_solicitud_2'? Puede que parezca un caso burdo, pero ocurre más seguido de lo que crees.
Para descubrirlo tienes dos caminos: abrir cada formulario y revisar el flujo asociado o invocar al mismísimo oráculo del prefijo.
El oráculo es una convención de dos a tres letras entre paréntesis que nos permite saber a qué flujo hace referencia el formulario. Pero te advierto, una vez que lo adoptas no vuelves atrás.
Capítulo 1: el prefijo del flujo
En todo grimorio bien escrito, cada hechizo lleva el sello de su escuela. Cotalker no es la excepción: todo formulario lleva al inicio de su display un prefijo de 2 a 3 caracteres entre paréntesis que identifica al flujo al que pertenece.
Si el flujo se llama "Flujo de Inventario", el prefijo es (INV). Si el formulario se llama "Enviar a tienda", su display pasa a ser:
✅ (INV) Enviar a tienda
Tres caracteres, dos paréntesis, un espacio. Aplicado de forma consistente en cada formulario del flujo. La lista de antes, con la convención aplicada:
(INV) Enviar a tienda
(INV) Recepción de mercadería
(VAC) Aprobar solicitud
(PAG) Confirmación de pago
(COM) Aprobar solicitud
(INV) Recepción de mercadería
Ahora cada nombre te dice de qué flujo viene. Las dos "Aprobar solicitud" se distinguen sin abrir nada: una es de Vacaciones, otra de Compras.
Si ahora vemos la lista de formularios, es mucho más fácil entender a qué flujo pertenece cada uno.
Capítulo 2: el prefijo no vive solo en el formulario
Acá viene la parte que mucha gente pasa por alto. El sello no vive solo en el nombre del hechizo: marca a toda la orden mágica y a cada cosa que orbita el flujo, incluyendo aulas, libros y sigilos de invocación.
Donde debe aparecer el (INV):
- El nombre del flujo → "(INV) Flujo de Inventario"
- El display de cada formulario del flujo → "(INV) Enviar a tienda"
- El
codedel formulario →inv_enviando_a_tienda(sin paréntesis, todo minúscula) - Las colecciones del flujo → "(INV) Productos", "(INV) Bodegas"
$VALUE, cada llamada de red, cada rutina. Un hechizo con nombre marcado pero sigilo limpio sigue siendo un hechizo a medias.Capítulo 3: prefijos por tipo de formulario
Hasta acá tenemos un solo prefijo. Pero los formularios en Cotalker no son todos iguales: hay startforms, surveys, surveys+surveys, formularios masivos. Así que con esto viene la segunda capa.
El segundo prefijo va siempre a la derecha del prefijo de flujo y nunca al revés.
| Tipo de formulario | Segundo prefijo | Ejemplo |
|---|---|---|
| Survey + Survey | (SS) |
(INV) (SS) Ingresar Productos |
| Startform | (SF) |
(INV) (SF) Enviar a tienda |
| Formulario masivo (bulk) | (BLK) |
(INV) (BLK) Enviar a tienda |
| Formulario simple | (sin prefijo) | (INV) Enviar a tienda |
El orden importa: el prefijo del flujo siempre primero, el del tipo después.
(INV) (SF)✅(SF) (INV)❌
La razón es práctica: la lista de formularios se ordena de forma alfabética, por lo que se terminarán ordenando primero por flujo y después por tipo.
Capítulo 4: el caso típico, el oráculo en acción
Acá es donde la convención se paga sola. Llega el caso real:
"Ve a revisar el formulario del startform en el flujo de inventario."
Sin convención, esa frase es una expedición. Tienes que ir al administrador del flujo, buscarlo entre la lista, entrar a su configuración, buscar el startform y ahora que tienes su nombre, ir a la lista de formularios y encontrarlo. Bastantes clicks para algo tan simple, más si el flujo es grande.
Con convención, la traducción es automática:
- "Startform" →
(SF) - "Flujo de inventario" →
(INV) - Búsqueda →
(INV) (SF)
Vas a la lista de formularios, escribes (INV) (SF) en el buscador y aparece exactamente el formulario que necesitas. Cero clics de exploración.
Lo mismo sirve cuando alguien te dice "el survey+survey de aprobaciones del flujo de compras": (COM) (SS) y listo. La convención convierte una frase ambigua en una clave de búsqueda.
Capítulo 5: el segundo regalo, migraciones sin sufrir
Antes de esta convención, era mucho más complejo migrar entre ambientes si el cliente quería pasar solo un flujo en específico, ya que esto implicaba buscar a mano los formularios, colecciones, questions, entre otros. Por suerte para todos, ahora existe la convención del prefijo.
¿Cómo ayuda esto a migrar un flujo? Una búsqueda de la colección de surveys (formularios) en Mongodb se soluciona con un simple regex:
^inv_
Esa expresión regular es la invocación más corta del grimorio. Aplicada sobre los code de los formularios, permite migrar todo el flujo. Lo mismo sobre las questions (que heredan el prefijo del formulario).
Ahora imagina la migración sin convención:
- Abres el flujo en origen.
- Anotas a mano cada formulario asociado.
- Anotas cada colección que cada formulario consulta.
- Anotas cada question dentro de cada formulario.
- Repites la búsqueda dos o tres veces porque alguna question se te escapó.
Una migración que con prefijo me tomó 20 minutos, sin prefijo se vuelve una tarde entera de búsqueda y verificación. Eso sin contar que cada elemento olvidado es un bug en producción esperando salir.
inv_ y ^inv_ es la diferencia entre traerte 200 elementos irrelevantes o solo los que empiezan con ese prefijo. Una hora invertida en regex se paga en la primera migración.Capítulo 6: cuándo la convención se siente rígida (y por qué igual la sigo)
Con esto, podrías creer que para proyectos chicos que tengan un solo flujo y tres formularios, la convención se siente innecesaria. ¿Para qué prefijar si nunca voy a tener dos "Aprobar solicitud"? ¿Para qué cargar el display con (INV) (SF) si no hay confusión posible?
La respuesta es la que aprendí a la mala: al igual que el desarrollo de software, los proyectos, por más chicos que sean, siempre crecen. Lo que empezó como un flujo de vacaciones termina con seis flujos enlazados, dos integraciones, un bot y tres surveys. Y para entonces, retroactivar la convención es mucho más costoso que haberla aplicado desde el día uno.
Prefiero ser práctico: aunque el proyecto tenga un solo flujo, aplico la convención. Es un costo bajísimo (escribir tres letras más) que me asegura que el día que el cliente pida un segundo flujo, no tenga que rebautizar nada. Quizá al inicio cueste acordarse, pero ya a la tercera vez sale natural.
Capítulo 7: La conclusión del oráculo
El prefijo no es decoración. Es un índice de búsqueda incrustado en el nombre, una pista para el implementador que llegue después de ti, y la diferencia entre encontrar un formulario en 5 segundos o en 5 minutos. Y cuando llega la hora de migrar, es la diferencia entre 20 minutos y una tarde entera.
Tres letras, dos paréntesis, una convención. El oráculo no falla cuando todos hablan su idioma.
Pero el oráculo solo te ha mostrado el primer círculo. Más adentro del grimorio viven las questions (las palabras menores que componen cada hechizo) y obedecen a una ley más severa: una regla que se aplica a toda la biblioteca arcana, un lenguaje secreto que aparece en sus nombres ([PRL], [HIDE] y [DEP]), y la técnica del sello acortado. Eso lo veremos en la parte 2.
¿En tus proyectos de Cotalker manejan alguna convención de naming distinta? ¿O cargan con flujos donde "Aprobar solicitud" aparece tres veces sin contexto? Cuéntamelo en los comentarios.
Member discussion