@semacode/cli 1.3.1 → 1.3.2

package/exemplos/pedido.sema

@@ -0,0 +1,119 @@
+module exemplos.pedido {
+  docs {
+    resumo: "Ciclo completo de pedido com itens, aprovacao e entrega."
+  }
+
+  entity Pedido {
+    fields {
+      id: Id
+      cliente_id: Id
+      status: Texto
+      total: Decimal
+      criado_em: Timestamp
+    }
+  }
+
+  entity ItemPedido {
+    fields {
+      id: Id
+      pedido_id: Id
+      produto_id: Id
+      quantidade: Inteiro
+      preco_unitario: Decimal
+    }
+  }
+
+  task criar_pedido {
+    input {
+      cliente_id: Id required
+      itens: Lista required
+    }
+    output {
+      pedido: Pedido
+    }
+    rules {
+      itens deve_ser nao_vazio
+      cliente_id deve_ser valido
+    }
+    effects {
+      consulta Cliente por cliente_id
+      consulta Produto por cada item.produto_id
+      persistencia Pedido
+      persistencia ItemPedido
+      evento pedido_criado criticidade = media
+      auditoria criacao_pedido
+    }
+    state ciclo_pedido {
+      transitions {
+        RASCUNHO -> AGUARDANDO_PAGAMENTO
+      }
+    }
+    guarantees {
+      pedido existe
+      pedido.total > 0
+    }
+    error {
+      cliente_invalido: "Cliente nao encontrado."
+      item_invalido: "Um ou mais produtos nao existem."
+      carrinho_vazio: "O pedido deve ter ao menos um item."
+    }
+    tests {
+      caso "cria pedido valido" {
+        given { cliente_id: "cli_1"  itens: [{produto_id: "prod_1", quantidade: 2}] }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+
+  task cancelar_pedido {
+    input {
+      pedido_id: Id required
+      motivo: Texto required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      pedido_id deve_ser valido
+      pedido.status em [AGUARDANDO_PAGAMENTO, APROVADO]
+      motivo deve_ser preenchido
+    }
+    effects {
+      persistencia Pedido
+      evento pedido_cancelado criticidade = alta
+      notificacao cliente pedido_cancelado
+      auditoria cancelamento_pedido criticidade = media
+    }
+    state ciclo_pedido {
+      transitions {
+        AGUARDANDO_PAGAMENTO -> CANCELADO
+        APROVADO -> CANCELADO
+      }
+    }
+    guarantees {
+      protocolo existe
+      pedido.status == CANCELADO
+    }
+    error {
+      pedido_nao_cancelavel: "Pedido ja enviado ou entregue nao pode ser cancelado."
+    }
+    tests {
+      caso "cancela pedido pendente" {
+        given { pedido_id: "ped_1"  motivo: "Desistencia do cliente" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+
+  flow aprovacao_pedido {
+    pedido_id: Id
+    token_pagamento: Texto
+    etapa pagar usa processar_pagamento com pedido_id = pedido_id, token = token_pagamento em_sucesso reservar em_erro cancelar_por_pagamento
+    etapa reservar usa reservar_estoque com pedido_id = pedido_id depende_de pagar em_erro cancelar_por_estoque
+    etapa cancelar_por_pagamento usa cancelar_pedido com pedido_id = pedido_id, motivo = "Pagamento recusado" depende_de pagar
+    etapa cancelar_por_estoque usa cancelar_pedido com pedido_id = pedido_id, motivo = "Estoque insuficiente" depende_de reservar
+    effects {
+      auditoria fluxo_aprovacao_pedido criticidade = alta
+    }
+  }
+}

package/exemplos/permissao.sema

@@ -0,0 +1,121 @@
+module exemplos.permissao {
+  docs {
+    resumo: "Controle de acesso baseado em papeis e permissoes granulares."
+  }
+
+  entity Papel {
+    fields {
+      id: Id
+      nome: Texto
+      descricao: Texto
+    }
+  }
+
+  entity Permissao {
+    fields {
+      id: Id
+      recurso: Texto
+      acao: Texto
+      descricao: Texto
+    }
+  }
+
+  task atribuir_papel {
+    input {
+      usuario_id: Id required
+      papel_id: Id required
+    }
+    output {
+      atribuicao_id: Id
+    }
+    rules {
+      usuario_id deve_ser valido
+      papel_id deve_ser valido
+    }
+    effects {
+      consulta Usuario por usuario_id
+      consulta Papel por papel_id
+      persistencia AtribuicaoPapel
+      evento papel_atribuido criticidade = media
+      auditoria atribuicao_papel criticidade = alta
+    }
+    guarantees {
+      atribuicao_id existe
+    }
+    error {
+      usuario_nao_encontrado: "Usuario nao localizado."
+      papel_nao_encontrado: "Papel nao localizado."
+      atribuicao_duplicada: "Usuario ja possui este papel."
+    }
+    tests {
+      caso "atribui papel admin" {
+        given { usuario_id: "usr_1"  papel_id: "papel_admin" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+
+  task verificar_permissao {
+    input {
+      usuario_id: Id required
+      recurso: Texto required
+      acao: Texto required
+    }
+    output {
+      autorizado: Booleano
+    }
+    rules {
+      usuario_id deve_ser valido
+      recurso deve_ser preenchido
+      acao deve_ser preenchida
+    }
+    effects {
+      consulta AtribuicaoPapel por usuario_id
+      consulta PermissaoPapel por papel_id
+      auditoria verificacao_permissao
+    }
+    guarantees {
+      autorizado existe
+    }
+    tests {
+      caso "usuario autorizado" {
+        given { usuario_id: "usr_admin"  recurso: "relatorios"  acao: "exportar" }
+        expect { sucesso: verdadeiro }
+      }
+      caso "usuario sem permissao" {
+        given { usuario_id: "usr_basico"  recurso: "admin"  acao: "deletar" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+
+  task revogar_papel {
+    input {
+      usuario_id: Id required
+      papel_id: Id required
+      motivo: Texto required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      usuario_id deve_ser valido
+      papel_id deve_ser valido
+      motivo deve_ser preenchido
+    }
+    effects {
+      persistencia AtribuicaoPapel
+      evento papel_revogado criticidade = alta
+      auditoria revogacao_papel criticidade = alta
+    }
+    guarantees {
+      protocolo existe
+    }
+    tests {
+      caso "revoga papel" {
+        given { usuario_id: "usr_1"  papel_id: "papel_admin"  motivo: "Saida da equipe" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+}

package/exemplos/relatorio.sema

@@ -0,0 +1,93 @@
+module exemplos.relatorio {
+  docs {
+    resumo: "Geracao assincrona de relatorios com download e notificacao."
+  }
+
+  entity Relatorio {
+    fields {
+      id: Id
+      tipo: Texto
+      parametros: Objeto
+      status: Texto
+      url_download: Texto
+      solicitado_por: Id
+      criado_em: Timestamp
+      concluido_em: Timestamp
+    }
+  }
+
+  task solicitar_relatorio {
+    input {
+      tipo: Texto required
+      data_inicio: Data required
+      data_fim: Data required
+      formato: Texto
+    }
+    output {
+      relatorio_id: Id
+    }
+    rules {
+      tipo em [VENDAS, ESTOQUE, USUARIOS, FINANCEIRO]
+      data_inicio deve_ser anterior_a data_fim
+      formato em [PDF, CSV, XLSX]
+    }
+    effects {
+      persistencia Relatorio
+      evento relatorio_solicitado criticidade = baixa
+      auditoria solicitacao_relatorio
+    }
+    state ciclo_relatorio {
+      transitions {
+        PENDENTE -> EM_PROCESSAMENTO
+      }
+    }
+    guarantees {
+      relatorio_id existe
+    }
+    error {
+      tipo_invalido: "Tipo de relatorio nao suportado."
+      periodo_invalido: "Data de inicio deve ser anterior a data de fim."
+      limite_periodo: "Periodo maximo e de 12 meses."
+    }
+    tests {
+      caso "solicita relatorio de vendas" {
+        given { tipo: "VENDAS"  data_inicio: "2025-01-01"  data_fim: "2025-03-31"  formato: "PDF" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+
+  task concluir_relatorio {
+    input {
+      relatorio_id: Id required
+      url_download: Texto required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      relatorio_id deve_ser valido
+      url_download deve_ser preenchida
+    }
+    effects {
+      persistencia Relatorio
+      notificacao usuario relatorio_pronto criticidade = media
+      evento relatorio_concluido
+      auditoria conclusao_relatorio
+    }
+    state ciclo_relatorio {
+      transitions {
+        EM_PROCESSAMENTO -> CONCLUIDO
+      }
+    }
+    guarantees {
+      protocolo existe
+    }
+    tests {
+      caso "conclui relatorio" {
+        given { relatorio_id: "rel_1"  url_download: "https://storage/rel_1.pdf" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+}

package/exemplos/testes_embutidos.sema

@@ -0,0 +1,45 @@
+module exemplos.testes.embutidos {
+  task validar_documento {
+    input {
+      documento: Texto required
+    }
+    output {
+      valido: Booleano
+      motivo: Texto
+    }
+    rules {
+      documento deve_ser preenchido
+    }
+    effects {
+      auditoria validacao_documento
+    }
+    guarantees {
+      valido existe
+      motivo existe
+    }
+    tests {
+      caso "documento valido" {
+        given {
+          documento: 12345678900
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+      caso "documento vazio" {
+        given {
+          documento: ""
+        }
+
+        expect {
+          sucesso: falso
+        }
+
+        error {
+          tipo: "entrada_invalida"
+        }
+      }
+    }
+  }
+}

package/exemplos/tratamento_erro.sema

@@ -0,0 +1,157 @@
+module exemplos.tratamento.erro {
+  task executar_operacao_sensivel {
+    input {
+      chave: Texto required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      chave existe e chave deve_ser preenchida
+    }
+    effects {
+      consulta cofre
+      auditoria falha_operacao_sensivel
+    }
+    guarantees {
+      protocolo existe
+    }
+    error {
+      acesso_negado: "A chave informada nao tem permissao."
+      recurso_indisponivel: "O servico esta temporariamente indisponivel."
+      auditoria_obrigatoria: "Toda falha precisa ser registrada."
+    }
+    tests {
+      caso "falha por acesso negado" {
+        given {
+          chave: "sem_permissao"
+        }
+
+        expect {
+          sucesso: falso
+        }
+
+        error {
+          tipo: "acesso_negado"
+        }
+      }
+    }
+  }
+
+  task responder_acesso_negado {
+    input {
+      chave: Texto required
+    }
+    output {
+      protocolo_resposta: Id
+    }
+    effects {
+      notificacao cliente acesso_negado
+      auditoria acesso_negado
+    }
+    guarantees {
+      protocolo_resposta existe
+    }
+    tests {
+      caso "responde acesso negado" {
+        given {
+          chave: "sem_permissao"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task responder_retentativa {
+    input {
+      chave: Texto required
+    }
+    output {
+      protocolo_resposta: Id
+    }
+    effects {
+      notificacao cliente retentativa_programada
+      auditoria retentativa
+    }
+    guarantees {
+      protocolo_resposta existe
+    }
+    tests {
+      caso "agenda retentativa" {
+        given {
+          chave: "instavel"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task registrar_auditoria_falha {
+    input {
+      chave: Texto required
+    }
+    output {
+      auditoria_id: Id
+    }
+    effects {
+      auditoria falha_operacional
+      persistencia auditoria_falha
+    }
+    guarantees {
+      auditoria_id existe
+    }
+    tests {
+      caso "audita falha" {
+        given {
+          chave: "sem_permissao"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  task registrar_sucesso {
+    input {
+      protocolo: Id required
+    }
+    output {
+      registro_id: Id
+    }
+    effects {
+      auditoria operacao_concluida
+      evento operacao_sensivel_concluida
+    }
+    guarantees {
+      registro_id existe
+    }
+    tests {
+      caso "registra sucesso" {
+        given {
+          protocolo: "prot_1"
+        }
+
+        expect {
+          sucesso: verdadeiro
+        }
+      }
+    }
+  }
+
+  flow resposta_segura {
+    chave: Texto
+    etapa tentar usa executar_operacao_sensivel com chave = chave em_sucesso concluir em_erro registrar_falha por_erro acesso_negado = tratar_acesso_negado, recurso_indisponivel = agendar_retentativa
+    etapa tratar_acesso_negado usa responder_acesso_negado com chave = chave depende_de tentar
+    etapa agendar_retentativa usa responder_retentativa com chave = chave depende_de tentar
+    etapa registrar_falha usa registrar_auditoria_falha com chave = chave depende_de tentar
+    etapa concluir usa registrar_sucesso com protocolo = tentar.protocolo depende_de tentar
+  }
+}

package/exemplos/upload_arquivo.sema

@@ -0,0 +1,93 @@
+module exemplos.upload.arquivo {
+  docs {
+    resumo: "Upload de arquivos com validacao de tipo, tamanho e processamento."
+  }
+
+  entity Arquivo {
+    fields {
+      id: Id
+      nome: Texto
+      tipo_mime: Texto
+      tamanho_bytes: Inteiro
+      url: Texto
+      status: Texto
+      enviado_por: Id
+      criado_em: Timestamp
+    }
+  }
+
+  task iniciar_upload {
+    input {
+      nome: Texto required
+      tipo_mime: Texto required
+      tamanho_bytes: Inteiro required
+    }
+    output {
+      upload_id: Id
+      url_upload: Texto
+    }
+    rules {
+      tipo_mime em [image/jpeg, image/png, application/pdf, text/csv]
+      tamanho_bytes <= 10485760
+      nome deve_ser preenchido
+    }
+    effects {
+      consulta storage criticidade = alta
+      persistencia Arquivo
+      auditoria upload_iniciado
+    }
+    guarantees {
+      upload_id existe
+      url_upload existe
+    }
+    error {
+      tipo_nao_permitido: "Tipo de arquivo nao aceito."
+      tamanho_excedido: "Arquivo excede o limite de 10MB."
+      storage_indisponivel: "Servico de armazenamento indisponivel."
+    }
+    tests {
+      caso "inicia upload de imagem" {
+        given { nome: "foto.jpg"  tipo_mime: "image/jpeg"  tamanho_bytes: 512000 }
+        expect { sucesso: verdadeiro }
+      }
+      caso "rejeita arquivo muito grande" {
+        given { nome: "video.mp4"  tipo_mime: "video/mp4"  tamanho_bytes: 20971520 }
+        expect { sucesso: falso }
+        error { tipo: "tamanho_excedido" }
+      }
+    }
+  }
+
+  task confirmar_upload {
+    input {
+      upload_id: Id required
+    }
+    output {
+      arquivo: Arquivo
+    }
+    rules {
+      upload_id deve_ser valido
+    }
+    effects {
+      consulta storage por upload_id criticidade = alta
+      persistencia Arquivo
+      evento arquivo_disponivel criticidade = baixa
+      auditoria upload_confirmado
+    }
+    state ciclo_arquivo {
+      transitions {
+        PENDENTE -> DISPONIVEL
+      }
+    }
+    guarantees {
+      arquivo existe
+      arquivo.url existe
+    }
+    tests {
+      caso "confirma upload realizado" {
+        given { upload_id: "upl_1" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+}

package/exemplos/webhook.sema

@@ -0,0 +1,96 @@
+module exemplos.webhook {
+  docs {
+    resumo: "Recepcao, validacao e reenvio de eventos via webhook."
+  }
+
+  entity EventoWebhook {
+    fields {
+      id: Id
+      origem: Texto
+      tipo: Texto
+      payload: Objeto
+      status: Texto
+      tentativas: Inteiro
+      recebido_em: Timestamp
+      processado_em: Timestamp
+    }
+  }
+
+  task receber_webhook {
+    input {
+      origem: Texto required
+      tipo: Texto required
+      payload: Objeto required
+      assinatura: Texto required
+    }
+    output {
+      evento_id: Id
+    }
+    rules {
+      assinatura deve_ser valida para payload
+      origem deve_ser permitida
+      tipo deve_ser preenchido
+    }
+    effects {
+      persistencia EventoWebhook
+      evento webhook_recebido criticidade = media
+      auditoria recepcao_webhook
+    }
+    state ciclo_webhook {
+      transitions {
+        RECEBIDO -> EM_PROCESSAMENTO
+      }
+    }
+    guarantees {
+      evento_id existe
+    }
+    error {
+      assinatura_invalida: "Assinatura do webhook nao confere."
+      origem_nao_permitida: "Origem do webhook nao esta na lista de permitidos."
+    }
+    tests {
+      caso "recebe webhook valido" {
+        given { origem: "stripe"  tipo: "payment.succeeded"  payload: {}  assinatura: "sig_ok" }
+        expect { sucesso: verdadeiro }
+      }
+      caso "rejeita assinatura invalida" {
+        given { origem: "stripe"  tipo: "payment.succeeded"  payload: {}  assinatura: "sig_errada" }
+        expect { sucesso: falso }
+        error { tipo: "assinatura_invalida" }
+      }
+    }
+  }
+
+  task reenviar_webhook {
+    input {
+      evento_id: Id required
+    }
+    output {
+      protocolo: Id
+    }
+    rules {
+      evento_id deve_ser valido
+      evento.tentativas < 5
+      evento.status em [FALHOU, PENDENTE]
+    }
+    effects {
+      consulta EventoWebhook por evento_id
+      persistencia EventoWebhook
+      evento webhook_reenviado
+      auditoria reenvio_webhook
+    }
+    guarantees {
+      protocolo existe
+    }
+    error {
+      limite_tentativas: "Numero maximo de tentativas atingido."
+      evento_ja_processado: "Este evento ja foi processado com sucesso."
+    }
+    tests {
+      caso "reenvia evento falho" {
+        given { evento_id: "evt_1" }
+        expect { sucesso: verdadeiro }
+      }
+    }
+  }
+}