> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/rules-engine/builds-artifacts-and-deployment.md).
# Compilações e Implementação
Compile, nomeie e implemente artefactos de regras do Kilo IoT — valide o diagrama, produza um artefacto e depois inicie o processamento.
Guardar uma regra preserva o seu trabalho. Compilar uma regra valida-a e produz um artefacto passível de implementação. Implementar um artefacto inicia o processamento da regra a partir do sensor ou origem de acionamento selecionado. Estes são passos deliberados e separados — a plataforma nunca executa lógica de automação que não tenha sido explicitamente compilada e implementada.
Esta separação é crítica para ambientes de produção. Significa que pode iterar sobre uma regra ao longo de várias sessões de edição sem afetar o que está atualmente em execução. Quando estiver satisfeito com o design, compile-a e, quando estiver pronto para a colocar em produção, implemente-a.
## Compilar uma regra
### Iniciando uma compilação
No editor da regra, clique no **Compilar** botão na barra de cabeçalho. A barra lateral de resultados da compilação abre-se no lado direito do editor.
### A barra lateral de resultados da compilação
A barra lateral é um formulário onde dá nome e anota a compilação antes de a criar:
| Campo | Descrição |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome** | Um nome obrigatório para este artefacto de compilação. Escolha algo que identifique a alteração — por exemplo, "Atualização do limite de humidade" ou "Adicionada ramificação de escalonamento." |
| **Comentário** | Uma área de texto opcional para contexto adicional. Utilize-a para anotar por que motivo a compilação foi criada, o que mudou desde a última compilação ou quaisquer instruções de implementação para a sua equipa. |
Na parte inferior da barra lateral:
* **Guardar e compilar** — Guarda o estado atual da regra como uma nova versão e, em seguida, cria um artefacto de compilação a partir dele.
* Uma ligação para a lista de artefactos: *"Pode gerir contentores na lista de artefactos."* Clique aqui para navegar diretamente para o separador Artefactos.
### Resultados da compilação
**Em caso de sucesso:** Uma notificação confirma *"Compilação criada com sucesso"* e a barra lateral fecha-se. O artefacto de compilação aparece no separador Artefactos, pronto para implementação.
**Em caso de erro:** Se a compilação encontrar erros de validação — como expressões CEL inválidas, ligações em falta ou problemas estruturais no diagrama — o feedback de erro é apresentado diretamente na barra lateral. Corrija os problemas reportados no editor e tente novamente a compilação. Consulte [Resolução de problemas](/kilo-docs-pt/kilo-iot-server/rules-engine/troubleshooting.md) para uma lista completa dos erros de compilação e de como os resolver.
### O que faz uma compilação
A etapa de compilação:
1. Guarda a regra atual como uma nova versão (para que o estado compilado fique sempre registado no histórico de versões)
2. Valida todo o diagrama: estrutura, ligações, configurações dos nós e todas as expressões CEL
3. Produz um artefacto — um pacote passível de implementação que contém a lógica da regra validada
## O separador Artefactos
### Como chegar lá
Na página do motor de regras em `/rules`, clique no **separador Artefactos** (o segundo separador, entre Regras e Lixo).
### Pesquisar
Uma barra de pesquisa no topo do separador filtra os artefactos pelo nome da regra. Escreva para refinar a lista quando gerir muitas regras.
### Agrupamento de artefactos
Os artefactos são agrupados pela definição da regra. Cada regra que tenha pelo menos uma compilação aparece como uma linha recolhível que mostra o nome e a descrição da regra. Clique numa linha de regra para a expandir e ver todas as compilações dessa regra.
### Estado vazio
Se ainda não existirem compilações, o separador mostra: *"Sem artefactos"* com a mensagem *"Os artefactos aparecerão aqui quando as regras os gerarem."*
### Detalhes da compilação
Cada grupo expandido lista compilações individuais com as seguintes colunas:
| Coluna | Descrição |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome da compilação** | O nome que deu à compilação. Codificado por cores segundo o estado: verde para Em execução, laranja para Parado, vermelho para Forçado a parar. |
| **Origem** | Uma ligação que abre a vista só de leitura da regra, para que possa inspecionar a definição da regra que produziu este artefacto. |
| **Data e hora** | Quando a compilação foi criada, formatado como "dd MMM yyyy, HH:mm" |
| **ID do utilizador** | O membro da equipa que criou a compilação. Na interface atual, isto normalmente mostra o nome do utilizador resolvido juntamente com o ID do utilizador. |
| **Comentário** | O comentário introduzido durante a compilação. Clique para editar no local — prima Enter para guardar ou Escape para cancelar. |
### Estados dos artefactos
| Estado | Cor | Significado |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Em execução** | Verde | O artefacto está implementado e à espera do seu sensor selecionado ou fonte de acionamento |
| **Parado** | Laranja | O artefacto foi parado manualmente. Pode ser novamente implementado. |
| **Forçado a parar** | Vermelho | O sistema parou automaticamente o artefacto devido a erros de execução persistentes. Consulte [Segurança de emergência](#emergency-safety) abaixo. |
## Implementar um artefacto
Implementar inicia um artefacto compilado para que processe dados de sensores em tempo real.
### Como implementar
1. Abra o **separador Artefactos** separador na página do motor de regras.
2. Expanda o grupo da regra que contém a compilação que pretende implementar.
3. Clique em **Implementar** na linha da compilação.
O estado do artefacto muda para **Em execução** (verde). A regra está agora a avaliar ativamente cada nova leitura do seu sensor associado e a executar a lógica de automação.
### Restrições de implementação
* Apenas **uma compilação por regra** pode estar em execução ao mesmo tempo.
* Se uma regra já tiver um artefacto em execução e implementar uma compilação diferente, a plataforma para automaticamente o artefacto em execução e inicia o novo numa única operação. Não há necessidade de parar primeiro o artefacto em execução — a transição é tratada por si.
## Parar uma regra em execução
Parar é uma ação deliberada de pausa — utilize-a quando quiser que uma regra deixe de responder à sua origem selecionada sem implementar uma versão diferente.
### Como parar
1. Abra o **separador Artefactos** separador.
2. Encontre o artefacto em execução (estado verde).
3. Clique em **Parar**.
O estado muda para **Parado** (laranja). A regra deixa imediatamente de aceitar novos arranques. Os sensores continuam a reportar e os acionadores continuam a monitorizar, mas a regra parada não é executada a partir de nenhuma das origens.
Um artefacto parado pode ser reiniciado a qualquer momento clicando em **Implementar** novamente.
## Eliminar um artefacto de compilação
Para remover um artefacto de compilação de que já não precisa:
1. Abra o **separador Artefactos** separador.
2. Encontre o artefacto a eliminar. Tem de estar em **Parado** ou **Forçado a parar** estado — não pode eliminar um artefacto em execução.
3. Clique em **Eliminar** na linha da compilação.
Os artefactos em execução têm de ser parados antes de poderem ser eliminados.
## Segurança de emergência
A plataforma monitoriza a saúde de execução de cada regra em execução. Se uma regra encontrar erros persistentes durante a execução — por exemplo, um sensor referenciado foi eliminado, uma expressão falha consistentemente com dados em tempo real ou um alvo de enriquecimento deixa de estar permanentemente disponível — o sistema para automaticamente a regra para evitar falhas em cascata.
Quando isto acontece:
* O estado do artefacto muda para **Forçado a parar** (vermelho) no separador Artefactos.
* A regra deixa de responder a novas leituras de sensores ou ativações de acionadores.
* Não são gerados mais alarmes ou notificações por essa regra.
### Recuperar de uma paragem forçada
1. **Investigue a causa.** Revise a lógica da regra no editor. Verifique se os sensores referenciados continuam ativos, se as expressões são válidas para as formas reais dos dados e se os alvos de enriquecimento são acessíveis.
2. **Corrija o problema.** Edite a regra para resolver a causa raiz.
3. **Construa uma nova versão.** Crie um novo artefacto de compilação a partir da regra corrigida.
4. **Implemente a nova compilação.** Inicie o artefacto corrigido a partir do separador Artefactos.
Não se limite a voltar a implementar o artefacto forçado a parar sem corrigir o problema subjacente — os mesmos erros voltarão a ocorrer e a regra será parada novamente.
## Boas práticas
* **Dê nomes às compilações de acordo com a alteração que contêm.** Ao analisar o separador Artefactos às 3 da manhã durante um incidente, "Adicionada alternativa para humidade" é mais útil do que "Compilação 7."
* **Adicione comentários às compilações.** Os comentários podem ser editados após a criação, para que possa anotar as compilações com notas de implementação, referências de incidentes ou instruções de reversão.
* **Implemente diretamente sobre a compilação em execução.** Apenas uma compilação por regra é executada de cada vez, e implementar uma nova substitui-a numa única operação — não há necessidade de parar primeiro o artefacto atual. Utilize Parar quando quiser que a regra deixe de ser avaliada por completo, e não como passo anterior à implementação.
* **Considere as paragens forçadas como incidentes.** Uma regra com paragem forçada significa que a monitorização em tempo real dessa regra parou. Investigue e resolva prontamente.
* **Construa a partir de uma versão limpa.** Se tem vindo a iterar sobre uma regra, guarde manualmente e dê nome à versão antes de compilar. Isto garante que o artefacto de compilação mapeia para uma versão claramente identificada no histórico.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/rules-engine/builds-artifacts-and-deployment.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
