jorgemiranda-alt/cloudapper

O que cloudapper faz?

CloudApper é uma plataforma no-code: os aplicativos são compostos por formulários (modelo de dados), menus (navegação), papéis, workflows de UI (lado do cliente), workflows de backend (automação) e relatórios DevExpress, tudo editado no App Studio (/design/... para formulários e menus, /studio/... para workflows) e utilizado no aplicativo de runtime (/<clientId>/app/<appId>/...).

Este arquivo contém as regras que se aplicam a todas as tarefas. Leia a referência que corresponde à tarefa antes de agir:

Tarefa	Leia
Entender como a plataforma funciona (formulários, campos, workflows, relatórios, cache)	references/platform-model.md
Chamar as APIs (registros, workflows, formulários, menus, papéis, workflows de UI, relatórios)	references/api-reference.md
Construir ou alterar um workflow; depurar um que "não dispara" ou está lento	references/workflow-patterns.md
Conduzir o navegador com o Playwright MCP	references/playwright-efficiency.md
Copiar funcionalidades ou um aplicativo inteiro de um aplicativo/conta para outro	references/copy-between-apps.md
Construir um novo aplicativo ou formulário no designer	references/building-apps.md
Projetar, nomear ou revisar qualquer coisa (SOLID no CloudApper, nomenclatura, convenções de workflow/config/relatório)	references/conventions.md
Projetar uma solução ou arquitetura de integração (UKG, REST, webhooks, SFTP, middleware; escalabilidade e eficiência)	references/architecture.md
Documentar um aplicativo (guia técnico / de troubleshooting, ou guia de passagem para PM)	references/documentation.md
Revisar um aplicativo ou escrever suas descobertas / recomendações	references/app-review-checklist.md
Trabalhar com conectores UKG (Pro, WFM, Recruiting, HRSD)	references/integrations-ukg.md
O usuário pergunta como trabalhar com você no CloudApper, ou o que pertence a esta habilidade	references/learning-and-prompting.md

Ambientes: pergunte antes de alterar qualquer coisa

A maioria dos clientes CloudApper possui um aplicativo de Produção e um de UAT (teste), frequentemente em contas diferentes. Antes de qualquer alteração (salvar um formulário, editar ou ativar/desativar um workflow, editar registros, importar um relatório, alterar menus), confirme qual ambiente é para a alteração, a menos que o usuário já tenha dito nesta conversa:

• Pergunte: "É para Produção ou UAT?" e nomeie a conta/aplicativo em que você está conectado, para que o usuário possa identificar uma incompatibilidade.
• Padrão para UAT. Trate a Produção como somente leitura: sem alterações, sem execuções de workflow, e sem logins ou leituras, a menos que o usuário solicite explicitamente essa ação específica. Copiar de Produção é uma leitura; copiar para ela é uma alteração.
• Verifique o ID do cliente na URL antes de cada escrita (/<clientId>/app/<appId>). Um script que escreve deve se recusar a executar quando a página estiver no cliente errado.
• Fatos do projeto (contas, IDs de cliente/aplicativo, qual aplicativo é Produção) não são armazenados nesta habilidade. Procure por eles nas próprias anotações ou documentos do projeto e na memória; se estiverem faltando, pergunte ao usuário.

Regras de segurança que se aplicam a todas as tarefas

• Nunca execute, ative ou dispare um workflow por conta própria. O usuário inicia as execuções. Você pode salvar definições e ativar/desativar apenas quando solicitado; diga claramente quando uma ativação altera o comportamento em tempo real.
• Faça backup antes de editar. Salve a definição atual de cada workflow/formulário que você alterará em uma pasta local datada primeiro e mantenha-a até que o usuário confirme o resultado. (Um backup excluído cedo demais já impossibilitou um rollback.)
• Segredos. Os conectores de workflow contêm credenciais (UKG, outras APIs de fornecedores, chaves). Nunca imprima, registre em log ou coloque em documentos. Ao inspecionar JSON de workflow, mascare chaves como password/secret/apikey/token/clientId e imprima apenas a estrutura. Exclua dumps brutos com segredos quando terminar e informe ao usuário quais pastas locais ainda os contêm.
• O usuário faz login. Nunca digite senhas. Peça ao usuário para fazer login no navegador Playwright e avisar quando concluir.
• Dados pessoais. Desfoque nomes, e-mails e IDs em capturas de tela que você mantiver ou compartilhar.
• Relate fielmente. Se um teste mostrar que algo não funcionou, diga com as evidências (carimbos de data/hora, status, linhas de log) antes de propor a próxima correção.

Os seis fatos da plataforma que causam mais surpresas

Aprendidos da maneira mais difícil; detalhes e evidências em references/workflow-patterns.md.

1. A ordem dos workflows importa (WP-001). Um registro criado/atualizado por um workflow só dispara workflows que estão depois na lista de workflows (Sequence maior). Um workflow colocado após seu alvo não dispara nada. Mantenha a ordem da lista idêntica entre ambientes.
2. O designer faz trabalho oculto que a API não faz. Criar um formulário no designer também concede acesso ao papel de administrador (privilégio 32655). Salvar um corpo de formulário através da API cria o formulário e seus menus padrão, mas não o privilégio, então os menus ficam ocultos no runtime. Subformulários também precisam de sua própria chamada de relação pai-filho.
3. Um disparador de status precisa de uma alteração real (WP-002). Workflows disparados em Status _IsUpdated não iniciam se o novo valor for igual ao antigo (registros travados em "Running" não podem ser reexecutados definindo "Running" novamente).
4. Execuções disparadas de um workflow vão uma de cada vez, e um loop nem sempre espera por elas (WP-005). Um loop que atualizou 24 registros terminou em segundos enquanto as 24 execuções de workflow que disparou executaram na hora seguinte; um segundo lote iniciado entretanto perdeu suas execuções disparadas. Execute um lote de cada vez.
5. O runtime armazena em cache o aplicativo. Após alterações de design, clique no ícone de atualização ao lado do nome do aplicativo (ou faça login novamente); menus para formulários que o papel não pode acessar ficam ocultos, então novos formulários precisam de privilégios de papel (veja a lista de verificação de cópia).
6. Um Router executa toda rota cuja condição é verdadeira (WP-009), não apenas a primeira. Torne as condições de rota exclusivas quando apenas um resultado for desejado.

Como trabalhar de forma eficiente

• Prefira as APIs em vez de clicar: são mais rápidas, precisas e econômicas. Use a interface apenas para o que não tem API que você conheça e para confirmar o que o usuário verá.
• No Playwright, execute código a partir de arquivos (browser_run_code_unsafe com filename), sirva grandes cargas úteis de um localhost auxiliar e retorne resumos compactos (contagens, nomes, status), nunca JSON completo. Veja references/playwright-efficiency.md.
• Antes de editar um workflow, leia sua árvore de nós (nomes, tipos de ação, formulários) da API em vez de abrir o designer.
• Após cada alteração, verifique lendo de volta (API) e, para workflows, abra o construtor uma vez para confirmar que ele renderiza.
• Tarefas grandes ou repetitivas: escreva um pequeno script de construção (Python) que produza o JSON a partir de modelos obtidos de nós existentes e, em seguida, um script de aplicação protegido. Mantenha ambos no projeto para que a alteração seja repetível e revisável.

Padrões de documentação

Apenas Markdown (PDF somente mediante solicitação), público interno apenas (sem e-mails para clientes), perguntas em aberto dentro do documento com porquê/para quê, diagramas mostram apenas o aplicativo em execução e seus usuários/sistemas externos. Método completo: references/documentation.md. Quando um aplicativo já possui documentação ou notas de projeto, leia-as antes de explorar o aplicativo novamente.

Adicionando conhecimento a esta habilidade

Quando o usuário pedir para adicionar algo a esta habilidade ("adicione isso à habilidade cloudapper"):

1. Leia inbox/TEMPLATE.md na pasta desta habilidade e escreva o rascunho em inbox/<aaaa-mm-dd>-<nome-curto>.md com status Hypothesis. Escreva de forma genérica: sem nomes de cliente, aplicativo, formulário, workflow ou pessoa, IDs, hosts reais ou credenciais.
2. Pesquise references/ por entradas que o rascunho confirma ou contradiz e liste-as nas notas de revisão do rascunho.
3. Não edite SKILL.md ou references/ por conta própria, a menos que o usuário diga que é um mantenedor aplicando uma alteração revisada. Informe ao usuário para abrir um pull request com o rascunho (CONTRIBUTING.md tem o fluxo).