Códice Cotalker: el bestiario final (parte 4)

Ya vimos que el Oráculo del prefijo gobierna formularios, questions, colecciones y elementos. Pero alrededor de ellos vive un ecosistema entero, y cada especie tiene sus propias costumbres: flujos, cargos, bots, pbscripts, webhooks, roles de acceso y API tokens. Cada una carga (o no) el sello del flujo según su naturaleza.

En esta cuarta y última parte abrimos el bestiario completo para cerrar la saga: qué criatura lleva sello, cuál no, y por qué.

Capítulo 1: la regla maestra que ya conoces

Antes de entrar al bestiario, te recomiendo refrescar la memoria con las partes anteriores:

Cómo nombrar formularios en Cotalker: la convención del prefijo

La convención del prefijo entre paréntesis para formularios en Cotalker: cómo organizar tu workspace y migrar flujos entre ambientes sin perder el contexto.

Esteban Tejeda DevEsteban Tejeda

Codes de questions únicos en Cotalker: la convención

En Cotalker los codes de questions son únicos por company, no por formulario. La convención de prefijos acortados y marcas de display para no chocar jamás.

Esteban Tejeda DevEsteban Tejeda

Cómo nombrar colecciones en Cotalker: la convención del prefijo

En Cotalker las colecciones y sus elementos tienen codes únicos por company. La regla del singular y por qué tu data maestra necesita un buen code

Esteban Tejeda DevEsteban Tejeda

De todas formas, aquí va el resumen rápido de la ley que rige todo el grimorio:

• El prefijo del flujo identifica a qué flujo pertenece un elemento ((INV), (COM), (VAC)).
• Importa en el nombre cuando un usuario o implementador busca el elemento desde una lista visible.
• Importa en el code cuando un desarrollador lo invoca desde un snippet, una rutina o una integración.
• No lleva prefijo cuando es transversal (pertenece a varios flujos o a ninguno en particular).

Con esa regla en la cabeza, el resto del bestiario se ordena solo.

Capítulo 2: flujos de trabajo, solo importa el code

Empecemos por la base. El workflow es la entidad raíz, casi todo conlleva a tener una referencia a esta.

• ❌ El nombre del flujo no necesita seguir una convención estricta. Puedes llamarlo "Flujo de Inventario", "Inventario 2026", "Gestión de Stock", lo que tenga sentido para el cliente.
• ✅ El code sí lleva un identificador que se replica en todo lo relacionado al flujo: inv (o el prefijo que elijas para representarlo).

¿Por qué el nombre del flujo es laxo y el code estricto? Porque el flujo se ve una vez, en una sola lista. Los formularios, colecciones y rutinas que pertenecen al flujo se ven decenas de veces. El esfuerzo de naming se invierte donde más se replica.

Capítulo 3: cargos, solo importa el code con una excepción

Los cargos siguen la misma lógica que los flujos.

• ❌ El nombre del cargo no necesita prefijo. Llámalo como el cliente lo conoce: "Bodeguero", "Aprobador de Compras", "Gerente de Operaciones".
• ✅ El code lleva el prefijo del flujo si el cargo pertenece a un flujo específico: inv_bodeguero, com_aprobador.

La razón de fondo por la que el code sí lleva prefijo aunque el nombre no lo necesite: en una empresa real, distintos flujos repiten los mismos nombres de cargo. Es de lo más normal tener un "Administrador" en el flujo de Inventario y otro "Administrador" en el de Compras; mismo nombre en pantalla, responsabilidades distintas. Si ambos codes fueran administrador a secas, el sistema lanzaría error porque ese code ya estaría en uso. El prefijo los separa sin ambigüedad: inv_administrador y com_administrador.

La excepción: si el cargo es general (un cargo transversal usado por varios flujos, o uno administrativo que no pertenece a ningún flujo en particular), no lleva prefijo.

✅ inv_bodeguero => cargo del flujo de inventario
✅ com_aprobador => cargo del flujo de compras
✅ auditor => cargo general, sin prefijo
✅ rrhh_supervisor => cargo del flujo de RRHH

Capítulo 4: roles de acceso, la excepción sin convención de prefijos

Aquí la convención se invierte: los roles de acceso no llevan prefijo de flujo.

¿Por qué el rol no lleva prefijo? Porque su nombre ya hace referencia directa al flujo, con el flujo escrito completo y no como sigla: "Órdenes de Compra: Solicitante", "Inventario: Bodeguero". El flujo ya está en el nombre, así que agregar (INV) sería redundante.

No me extiendo más porque los roles y los permisos tienen su propia saga: cómo se diseñan, cómo se nombran los permisos y qué hace el rol Manager están aquí:

Roles y permisos en Cotalker: guía con convención de nombres

Cómo estandarizar permisos, roles y cargos en flujos de Cotalker usando RBAC. Incluye plantillas listas para usar.

Esteban Tejeda DevEsteban Tejeda

Rol Manager en Cotalker: bypasses en formularios y questions

Cómo usar el rol Manager en Cotalker para bypasses en developer mode, preloads de questions y cambios de estado manuales. Con código de ejemplo.

Esteban Tejeda DevEsteban Tejeda

Aquí lo importante es esto: en el bestiario del prefijo, los roles son la criatura que no lo lleva.

Capítulo 5: bots que importan en el nombre y en el code

Los bots son los familiares del flujo: pequeñas criaturas que ejecutan encargos por su cuenta. Y son la primera excepción interesante, porque a diferencia de los cargos, los bots importan en el nombre.

• ✅ El nombre lleva el prefijo del flujo: "(INV) Bot de Recepción".
• ✅ El code lleva el prefijo del flujo y un prefijo extra bot: bot_inv_recepcion.

¿Por qué el code lleva un bot_ extra? Simplemente para que se entienda que es un bot. Cuando lo ves en una lista o en un snippet, el bot_ al inicio te dice de un vistazo que estás frente a un bot y nada más.

✅ Nombre:  (INV) Bot de Recepción
✅ Code:    bot_inv_recepcion

La excepción: muchos bots son genéricos y no pertenecen a ningún flujo en particular (un bot notificador, uno que corre tareas de mantención, uno que integra con un servicio externo). En esos casos no llevan prefijo de flujo ni en el nombre ni en el code; solo el bot_ que los marca como bots.

✅ Nombre:  Bot Notificador
✅ Code:    bot_notificador

Capítulo 6: pbscripts, solo importa el code (mismo patrón que cargos)

Las rutinas (pbscripts) son los conjuros del flujo: fragmentos de lógica que invocas cuando los necesitas. En cuanto al sello, siguen la misma lógica que los cargos.

• ❌ El nombre de la rutina puede ser descriptivo libre: "Calcular total de stock", "Validar formulario antes de envío".
• ✅ El code lleva el prefijo del flujo si la rutina es exclusiva de un flujo: inv_calcular_stock, com_validar_envio.
• ✅ Si la rutina es general (utilidades transversales: formateo de fechas, validaciones genéricas), no lleva prefijo: format_fecha, check_endpoint_rut.

✅ inv_calcular_stock => rutina del flujo de inventario
✅ com_validar_envio => rutina del flujo de compras
✅ format_fecha => rutina general, sin prefijo
✅ check_endpoint_rut => rutina general, sin prefijo

Capítulo 7: webhooks, importan en el nombre y en el code

Los webhooks son portales hacia afuera: puertas por donde el flujo habla con el mundo. Por eso vuelven a la regla estricta:

• ✅ El nombre lleva el prefijo del flujo: "(INV) Webhook de actualización de stock".
• ✅ El code lleva el prefijo del flujo: inv_webhook_actualizacion_stock.

✅ Nombre: (INV) Webhook de actualización de stock
✅ Code: inv_webhook_actualizacion_stock

Capítulo 8: API tokens, nombra el display y el resto cae solo

Los API tokens cierran el bestiario. Son las llaves del grimorio: abren la puerta desde afuera. Tienen una particularidad: en Cotalker los tokens hacen referencia a un usuario bot. Por eso tienen tres campos, no uno:

• Display: el nombre visible. Es lo único que nombras tú.
• Code: lo genera Cotalker automáticamente, "slugificando" el display (minúsculas, sin paréntesis, espacios a guiones bajos). No lo editas a mano.
• Nombre de usuario bot: es el code con _bot al final. También automático.

Aquí está la diferencia con el bot del Capítulo 5: allí fijabas el code a mano (por eso podías forzar el bot_ adelante). En un API token no lo editas, sale del slugify del display. Esto nos da una ventaja: solo tienes que nombrar bien el display. El code y el usuario bot se derivan solos.

• Si es de propósito general (una integración que cruza varios flujos, acceso desde un sistema externo), el display va sin prefijo.
• Si pertenece a un flujo específico, el display lleva el prefijo del flujo, igual que todo lo demás.

Display:  API Facturación
Code:     api_facturacion          (slugify automático)
Usuario:  api_facturacion_bot      (code + _bot)

Display:  (INV) Recepción
Code:     inv_recepcion            (slugify automático)
Usuario:  inv_recepcion_bot        (code + _bot)

Capítulo 9: Cierre

Tres letras, dos paréntesis, una convención. Eso fue lo que te prometí en la parte 1. Pero la saga termina con una verdad más grande: el prefijo no es un tag, es un sistema. Cuando todos los elementos de tu company siguen la convención, el flujo se vuelve buscable, navegable y migrable.

La prueba final está en la regex. Cuando puedes traer el flujo de inventario completo (flujo, formularios, questions, colecciones, elementos, cargos, bots, rutinas, webhooks y API tokens) con cuatro o cinco búsquedas de regex, sabes que la convención está pagando.

El oráculo no es magia, es disciplina y buenas prácticas que se han estandarizado por medio de distintas generaciones que están y han pasado por Cotalker.

¿Aplicas alguna convención de naming distinta en tus proyectos de Cotalker? ¿Hay algún elemento que dejé fuera y crees que debería tener su propia regla ?Cuéntamelo en los comentarios.