jorgemiranda-alt/cloudapper

¿Qué hace cloudapper?

CloudApper es una plataforma sin código: las aplicaciones se componen de formularios (modelo de datos), menús (navegación), roles, flujos de trabajo de UI (del lado del cliente), flujos de trabajo de backend (automatización) e informes de DevExpress, todo ello editado en App Studio (/design/... para formularios y menús, /studio/... para flujos de trabajo) y utilizado en la aplicación en tiempo de ejecución (/<clientId>/app/<appId>/...).

Este archivo contiene las reglas que se aplican a cada tarea. Lee la referencia que coincida con la tarea antes de actuar:

Tarea	Leer
Entender cómo funciona la plataforma (formularios, campos, flujos de trabajo, informes, caché)	references/platform-model.md
Llamar a las APIs (registros, flujos de trabajo, formularios, menús, roles, flujos de trabajo de UI, informes)	references/api-reference.md
Construir o cambiar un flujo de trabajo; depurar uno que "no se dispara" o es lento	references/workflow-patterns.md
Manejar el navegador con el MCP de Playwright	references/playwright-efficiency.md
Copiar funciones o una aplicación completa de una aplicación/cuenta a otra	references/copy-between-apps.md
Construir una nueva aplicación o formulario en el diseñador	references/building-apps.md
Diseñar, nombrar o revisar cualquier cosa (SOLID en CloudApper, nomenclatura, convenciones de flujo de trabajo/config/informes)	references/conventions.md
Diseñar una solución o arquitectura de integración (UKG, REST, webhooks, SFTP, middleware; escalabilidad y eficiencia)	references/architecture.md
Documentar una aplicación (guía técnica / de solución de problemas, o una guía de entrega al jefe de producto)	references/documentation.md
Revisar una aplicación o redactar sus hallazgos / recomendaciones	references/app-review-checklist.md
Trabajar con conectores de UKG (Pro, WFM, Recruiting, HRSD)	references/integrations-ukg.md
El usuario pregunta cómo trabajar contigo en CloudApper, o qué pertenece a esta habilidad	references/learning-and-prompting.md

Entornos: pregunta antes de cambiar cualquier cosa

La mayoría de los clientes de CloudApper tienen una aplicación de Producción y una de UAT (prueba), a menudo en cuentas diferentes. Antes de cualquier cambio (guardar un formulario, editar o activar/desactivar un flujo de trabajo, editar registros, importar un informe, cambiar menús), confirma para qué entorno es el cambio, a menos que el usuario ya lo haya dicho en esta conversación:

• Pregunta: "¿Es esto para Producción o UAT?" y nombra la cuenta/aplicación en la que has iniciado sesión, para que el usuario pueda detectar una discrepancia.
• Por defecto, elige UAT. Trata Producción como de solo lectura: sin cambios, sin ejecuciones de flujos de trabajo y sin inicios de sesión o lecturas a menos que el usuario solicite explícitamente esa acción específica. Copiar desde Producción es una lectura; copiar a ella es un cambio.
• Verifica el ID del cliente de la URL antes de cada escritura (/<clientId>/app/<appId>). Un script que escribe debe negarse a ejecutarse cuando la página está en el cliente incorrecto.
• Los datos del proyecto (cuentas, ID de cliente/aplicación, qué aplicación es Producción) no se almacenan en esta habilidad. Búscalos en las propias notas o documentos del proyecto y en la memoria; si faltan, pregunta al usuario.

Reglas de seguridad que se aplican a cada tarea

• Nunca ejecutes, actives o dispares un flujo de trabajo por tu cuenta. El usuario inicia las ejecuciones. Puedes guardar definiciones y activar/desactivar solo cuando te lo pidan; di claramente cuando una activación/desactivación cambia el comportamiento en vivo.
• Haz una copia de seguridad antes de editar. Guarda la definición actual de cada flujo de trabajo/formulario que vayas a cambiar en una carpeta local con fecha primero, y consérvala hasta que el usuario confirme el resultado. (Una copia de seguridad eliminada demasiado pronto impidió una vez una reversión).
• Secretos. Los conectores de flujo de trabajo contienen credenciales (UKG, otras API de proveedores, claves). Nunca los imprimas, registres o pongas en documentos. Al inspeccionar JSON de flujo de trabajo, enmascara claves como contraseña/secret/apikey/token/clientId, e imprime solo la estructura. Elimina los volcados sin procesar con secretos cuando hayas terminado, e informa al usuario qué carpetas locales aún los contienen.
• El usuario inicia sesión. Nunca escribas contraseñas. Pide al usuario que inicie sesión en el navegador de Playwright y te avise cuando haya terminado.
• Datos personales. Difumina nombres, correos electrónicos e ID en las capturas de pantalla que conserves o compartas.
• Informa fielmente. Si una prueba muestra que algo no funcionó, dilo con la evidencia (marcas de tiempo, estados, líneas de registro) antes de proponer la siguiente corrección.

Los seis hechos de la plataforma que causan la mayoría de las sorpresas

Aprendido por las malas; detalles y evidencia en references/workflow-patterns.md.

1. El orden del flujo de trabajo importa (WP-001). Un registro creado/actualizado por un flujo de trabajo solo activa flujos de trabajo que están más adelante en la lista de flujos de trabajo (Secuencia superior). Un flujo de trabajo colocado después de su objetivo no activa nada. Mantén el orden de la lista idéntico entre entornos.
2. El diseñador hace trabajo secundario oculto que la API no hace. Crear un formulario en el diseñador también otorga acceso al rol de administrador (privilegio 32655). Guardar el cuerpo de un formulario a través de la API crea el formulario y sus menús predeterminados, pero no el privilegio, por lo que los menús permanecen ocultos en el tiempo de ejecución. Los subformularios también necesitan su propia llamada de relación padre-hijo.
3. Un disparador de estado necesita un cambio real (WP-002). Los flujos de trabajo activados en Status _IsUpdated no se inician si el nuevo valor es igual al antiguo (los registros atascados en "Running" no se pueden volver a ejecutar estableciendo "Running" de nuevo).
4. Las ejecuciones activadas de un flujo de trabajo van de una en una, y un bucle no siempre las espera (WP-005). Un bucle que actualizó 24 registros terminó en segundos mientras que las 24 ejecuciones de flujo de trabajo que activó se ejecutaron durante la siguiente hora; un segundo lote iniciado mientras tanto perdió sus ejecuciones activadas. Ejecuta un lote a la vez.
5. El tiempo de ejecución almacena en caché la aplicación. Después de cambios de diseño, haz clic en el icono de actualización junto al nombre de la aplicación (o inicia sesión de nuevo); los menús de los formularios a los que el rol no puede acceder están ocultos, por lo que los formularios nuevos necesitan privilegios de rol (consulta la lista de verificación de copia).
6. Un Router ejecuta cada ruta cuya condición es verdadera (WP-009), no solo la primera. Haz que las condiciones de ruta sean exclusivas cuando solo se desee un resultado.

Cómo trabajar de manera eficiente

• Prefiere las APIs a hacer clic: son más rápidas, precisas y económicas. Usa la interfaz de usuario solo para lo que no tiene una API que conozcas, y para confirmar lo que el usuario verá.
• En Playwright, ejecuta código desde archivos (browser_run_code_unsafe con filename), sirve cargas útiles grandes desde un ayudante de localhost, y devuelve resúmenes compactos (recuentos, nombres, estados), nunca JSON completo. Consulta references/playwright-efficiency.md.
• Antes de editar un flujo de trabajo, lee su árbol de nodos (nombres, tipos de acción, formularios) desde la API en lugar de abrir el diseñador.
• Después de cada cambio, verifica leyendo de nuevo (API) y, para flujos de trabajo, abre el constructor una vez para comprobar que se renderiza.
• Tareas grandes o repetitivas: escribe un pequeño script de construcción (Python) que produzca el JSON a partir de plantillas tomadas de nodos existentes, luego un script de aplicación protegido. Mantén ambos en el proyecto para que el cambio sea repetible y revisable.

Valores predeterminados de documentación

Solo Markdown (PDF solo si se solicita), solo para audiencia interna (sin correos electrónicos de clientes), preguntas abiertas dentro del documento con el porqué/para qué, los diagramas muestran solo la aplicación en ejecución y sus usuarios/sistemas externos. Método completo: references/documentation.md. Cuando una aplicación ya tiene documentación o notas de proyecto, léelas antes de explorar la aplicación de nuevo.

Añadir conocimiento a esta habilidad

Cuando el usuario pida añadir algo a esta habilidad ("añade esto a la habilidad de cloudapper"):

1. Lee inbox/TEMPLATE.md en la carpeta de esta habilidad y escribe el borrador en inbox/<yyyy-mm-dd>-<short-name>.md con estado Hypothesis. Escríbelo de forma genérica: sin nombres de clientes, aplicaciones, formularios, flujos de trabajo o personas, ID, hosts reales o credenciales.
2. Busca en references/ entradas que el borrador confirme o contradiga, y enuméralas en las notas de revisión del borrador.
3. No edites SKILL.md o references/ tú mismo a menos que el usuario diga que es un mantenedor que aplica un cambio revisado. Indica al usuario que abra una solicitud de extracción con el borrador (CONTRIBUTING.md tiene el flujo).