@semacode/cli 1.5.16 → 1.5.18

package/exemplos/pagamento.sema

@@ -0,0 +1,434 @@
+module exemplos.pagamento {
+  docs {
+    resumo: "Vertical oficial de pagamento IA-first: contrato operacional para agente governar cobranca, estado, erro, efeito, seguranca e retry sem inventar comportamento."
+  }
+
+  use exemplos.pagamento.dominio
+
+  task processar_pagamento {
+    input {
+      pagamento_id: Id required
+      valor: Decimal required
+      token: Texto required
+    }
+    output {
+      pagamento: Pagamento
+      status: StatusPagamento
+    }
+    authz {
+      escopo: pagamentos.processar
+      tenant: obrigatorio
+    }
+    dados {
+      classificacao_padrao: financeiro
+      redacao_log: obrigatoria
+      input {
+        pagamento_id: interno
+        valor: financeiro
+        token: segredo
+      }
+      output {
+        pagamento: financeiro
+        status: interno
+      }
+    }
+    audit {
+      evento: pagamento.processado
+      ator: auth.usuario
+      correlacao: request_id
+      retencao: "180d"
+      motivo: obrigatorio
+    }
+    segredos {
+      gateway_pagamento_token {
+        origem: vault
+        escopo: runtime
+        acesso: gateway_pagamento
+        rotacao: "30d"
+        nao_logar: verdadeiro
+        nao_retornar: verdadeiro
+        mascarar: verdadeiro
+      }
+    }
+    forbidden {
+      shell.exec
+      log.segredo
+      retorno.credencial
+    }
+    rules {
+      valor > 0
+      token existe
+      token deve_ser valido
+    }
+    effects {
+      consulta gateway_pagamento criticidade = alta
+      persistencia Pagamento criticidade = alta
+      evento pagamento_autorizado criticidade = media
+      notificacao cliente comprovante_pagamento criticidade = media
+      auditoria pagamento criticidade = alta
+    }
+    vinculos {
+      recurso: gateway_pagamento
+      tabela: pagamentos
+      evento: pagamento_autorizado
+    }
+    execucao {
+      idempotencia: verdadeiro
+      timeout: "15s"
+      retry: "2x exponencial"
+      compensacao: "registrar_falha_pagamento"
+      criticidade_operacional: alta
+    }
+    state ciclo_pagamento {
+      transitions {
+        PENDENTE -> AUTORIZADO
+        AUTORIZADO -> PROCESSADO
+      }
+    }
+    guarantees {
+      pagamento existe
+      status em [AUTORIZADO, PROCESSADO]
+      pagamento.status == status
+    }
+    error {
+      autorizacao_negada: "A operacao foi recusada pelo gateway."
+      saldo_insuficiente: "O saldo nao cobre o valor da cobranca."
+      timeout_gateway: "O gateway nao respondeu em tempo habil."
+    }
+    tests {
+      caso "pagamento autorizado" {
+        given {
+          pagamento_id: "pag_1"
+          valor: 199.9
+          token: "tok_ok"
+        }
+
+        expect {
+          sucesso: verdadeiro
+          status: "AUTORIZADO"
+          pagamento: "pag_1"
+        }
+      }
+      caso "pagamento recusado por autorizacao" {
+        given {
+          pagamento_id: "pag_erro"
+          valor: 10
+          token: "tok_recusado"
+        }
+
+        expect {
+          sucesso: falso
+        }
+
+        error {
+          tipo: "autorizacao_negada"
+        }
+      }
+      caso "pagamento falha por timeout" {
+        given {
+          pagamento_id: "pag_timeout"
+          valor: 10
+          token: "tok_timeout"
+        }
+
+        expect {
+          sucesso: falso
+        }
+
+        error {
+          tipo: "timeout_gateway"
+        }
+      }
+    }
+  }
+
+  task confirmar_pagamento {
+    input {
+      pagamento_id: Id required
+    }
+    output {
+      status: StatusPagamento
+    }
+    authz {
+      escopo: pagamentos.confirmar
+      tenant: obrigatorio
+    }
+    dados {
+      classificacao_padrao: financeiro
+      redacao_log: obrigatoria
+      input {
+        pagamento_id: interno
+      }
+      output {
+        status: interno
+      }
+    }
+    audit {
+      evento: pagamento.confirmado
+      ator: sistema.pagamentos
+      correlacao: request_id
+      retencao: "180d"
+      motivo: obrigatorio
+    }
+    forbidden {
+      shell.exec
+      log.segredo
+    }
+    rules {
+      pagamento_id existe
+    }
+    effects {
+      consulta gateway_pagamento criticidade = alta
+      persistencia Pagamento criticidade = alta
+      evento pagamento_confirmado criticidade = media
+      auditoria conciliacao_pagamento criticidade = alta
+    }
+    vinculos {
+      recurso: gateway_pagamento
+      tabela: pagamentos
+      evento: pagamento_confirmado
+    }
+    execucao {
+      idempotencia: verdadeiro
+      timeout: "15s"
+      retry: "2x exponencial"
+      compensacao: "registrar_timeout_pagamento"
+      criticidade_operacional: alta
+    }
+    state ciclo_pagamento {
+      transitions {
+        AUTORIZADO -> PROCESSADO
+      }
+    }
+    guarantees {
+      status == PROCESSADO
+    }
+    tests {
+      caso "confirma pagamento autorizado" {
+        given {
+          pagamento_id: "pag_1"
+        }
+
+        expect {
+          sucesso: verdadeiro
+          status: "PROCESSADO"
+        }
+      }
+    }
+  }
+
+  task notificar_falha_pagamento {
+    input {
+      pagamento_id: Id required
+      motivo: Texto required
+    }
+    output {
+      protocolo_notificacao: Id
+    }
+    authz {
+      escopo: pagamentos.notificar_falha
+      tenant: obrigatorio
+    }
+    dados {
+      classificacao_padrao: interno
+      redacao_log: obrigatoria
+      input {
+        pagamento_id: interno
+        motivo: interno
+      }
+      output {
+        protocolo_notificacao: interno
+      }
+    }
+    audit {
+      evento: pagamento.falha_notificada
+      ator: sistema.pagamentos
+      correlacao: request_id
+      retencao: "180d"
+      motivo: obrigatorio
+    }
+    forbidden {
+      shell.exec
+      log.segredo
+    }
+    effects {
+      notificacao cliente falha_pagamento criticidade = alta
+      auditoria falha_pagamento criticidade = media
+    }
+    vinculos {
+      evento: falha_pagamento
+      recurso: canal_notificacao
+    }
+    execucao {
+      idempotencia: verdadeiro
+      timeout: "10s"
+      retry: "3x exponencial"
+      compensacao: "registrar_auditoria_falha"
+      criticidade_operacional: alta
+    }
+    guarantees {
+      protocolo_notificacao existe
+    }
+    tests {
+      caso "notifica falha por recusa" {
+        given {
+          pagamento_id: "pag_erro"
+          motivo: "autorizacao_negada"
+        }
+
+        expect {
+          sucesso: verdadeiro
+          protocolo_notificacao: "notif_1"
+        }
+      }
+    }
+  }
+
+  task registrar_timeout_pagamento {
+    input {
+      pagamento_id: Id required
+    }
+    output {
+      auditoria_id: Id
+    }
+    authz {
+      escopo: pagamentos.registrar_timeout
+      tenant: obrigatorio
+    }
+    dados {
+      classificacao_padrao: interno
+      redacao_log: obrigatoria
+      input {
+        pagamento_id: interno
+      }
+      output {
+        auditoria_id: interno
+      }
+    }
+    audit {
+      evento: pagamento.timeout_registrado
+      ator: sistema.pagamentos
+      correlacao: request_id
+      retencao: "180d"
+      motivo: obrigatorio
+    }
+    forbidden {
+      shell.exec
+      log.segredo
+    }
+    effects {
+      auditoria timeout_gateway criticidade = alta
+      persistencia incidente_pagamento criticidade = media
+    }
+    vinculos {
+      tabela: incidentes_pagamento
+      evento: timeout_gateway
+    }
+    execucao {
+      idempotencia: verdadeiro
+      timeout: "10s"
+      retry: "nenhum"
+      compensacao: "notificar_operacao"
+      criticidade_operacional: alta
+    }
+    guarantees {
+      auditoria_id existe
+    }
+    tests {
+      caso "registra timeout" {
+        given {
+          pagamento_id: "pag_timeout"
+        }
+
+        expect {
+          sucesso: verdadeiro
+          auditoria_id: "aud_1"
+        }
+      }
+    }
+  }
+
+  flow orquestracao_pagamento {
+    pagamento_id: Id
+    valor: Decimal
+    token: Texto
+    etapa autorizar usa processar_pagamento com pagamento_id = pagamento_id, valor = valor, token = token em_sucesso confirmar em_erro registrar_falha por_erro autorizacao_negada = notificar_falha, timeout_gateway = registrar_timeout
+    etapa confirmar usa confirmar_pagamento com pagamento_id = pagamento_id depende_de autorizar
+    etapa notificar_falha usa notificar_falha_pagamento com pagamento_id = pagamento_id, motivo = "autorizacao_negada" depende_de autorizar
+    etapa registrar_timeout usa registrar_timeout_pagamento com pagamento_id = pagamento_id depende_de autorizar
+    etapa registrar_falha usa registrar_timeout_pagamento com pagamento_id = pagamento_id depende_de autorizar
+    effects {
+      auditoria fluxo_pagamento criticidade = alta
+      evento pagamento_em_processamento criticidade = media
+    }
+  }
+
+  route processar_pagamento_publico {
+    metodo: POST
+    caminho: /pagamentos/processar
+    task: processar_pagamento
+    auth {
+      modo: obrigatorio
+      principal: usuario
+      origem: publica
+    }
+    authz {
+      escopo: pagamentos.processar
+      tenant: obrigatorio
+    }
+    dados {
+      classificacao_padrao: financeiro
+      redacao_log: obrigatoria
+      input {
+        pagamento_id: interno
+        valor: financeiro
+        token: segredo
+      }
+      output {
+        pagamento: financeiro
+        status: interno
+      }
+    }
+    audit {
+      evento: pagamento.processado.publico
+      ator: auth.usuario
+      correlacao: request_id
+      retencao: "180d"
+      motivo: obrigatorio
+    }
+    segredos {
+      gateway_pagamento_token {
+        origem: vault
+        escopo: runtime
+        acesso: gateway_pagamento
+        rotacao: "30d"
+        nao_logar: verdadeiro
+        nao_retornar: verdadeiro
+        mascarar: verdadeiro
+      }
+    }
+    forbidden {
+      shell.exec
+      log.segredo
+      retorno.credencial
+    }
+    input {
+      pagamento_id: Id required
+      valor: Decimal required
+      token: Texto required
+    }
+    output {
+      pagamento: Pagamento required
+      status: StatusPagamento required
+    }
+    effects {
+      auditoria pagamento_publico criticidade = alta
+      evento pagamento_requisitado criticidade = media
+    }
+    error {
+      autorizacao_negada: "Erro publico quando o gateway recusa a operacao."
+      saldo_insuficiente: "Erro publico quando nao ha saldo suficiente."
+      timeout_gateway: "Erro publico quando o gateway nao responde."
+    }
+  }
+}

package/exemplos/pagamento_dominio.sema

@@ -0,0 +1,35 @@
+module exemplos.pagamento.dominio {
+  docs {
+    resumo: "Contratos de dominio compartilhados pelo vertical oficial de pagamento da Sema 0.5."
+  }
+
+  entity Pagamento {
+    fields {
+      id: Id
+      valor: Decimal
+      status: StatusPagamento
+    }
+  }
+
+  enum StatusPagamento {
+    PENDENTE,
+    AUTORIZADO,
+    RECUSADO,
+    PROCESSADO
+  }
+
+  state ciclo_pagamento {
+    fields {
+      status: StatusPagamento
+      conciliado: Booleano
+    }
+    invariants {
+      status existe
+    }
+    transitions {
+      PENDENTE -> AUTORIZADO
+      AUTORIZADO -> PROCESSADO
+      PENDENTE -> RECUSADO
+    }
+  }
+}

package/exemplos/pedido.sema

@@ -0,0 +1,255 @@
+module exemplos.pedido {
+  docs {
+    resumo: "Ciclo completo de pedido IA-first com dependencias explicitas para pagamento e estoque."
+  }
+
+  use exemplos.pagamento
+  use exemplos.estoque
+
+  enum StatusPedido {
+    RASCUNHO,
+    AGUARDANDO_PAGAMENTO,
+    APROVADO,
+    CANCELADO,
+    ENVIADO,
+    ENTREGUE
+  }
+
+  state ciclo_pedido {
+    fields {
+      status: StatusPedido
+    }
+    invariants {
+      status em [RASCUNHO, AGUARDANDO_PAGAMENTO, APROVADO, CANCELADO, ENVIADO, ENTREGUE]
+    }
+    transitions {
+      RASCUNHO -> AGUARDANDO_PAGAMENTO
+      AGUARDANDO_PAGAMENTO -> APROVADO
+      AGUARDANDO_PAGAMENTO -> CANCELADO
+      APROVADO -> CANCELADO
+      APROVADO -> ENVIADO
+      ENVIADO -> ENTREGUE
+    }
+  }
+
+  entity Pedido {
+    fields {
+      id: Id
+      cliente_id: Id
+      status: StatusPedido
+      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
+      status: StatusPedido
+    }
+    authz {
+      escopo: pedidos.criar
+      tenant: obrigatorio
+    }
+    dados {
+      classificacao_padrao: interno
+      redacao_log: obrigatoria
+      input {
+        cliente_id: pii
+        itens: interno
+      }
+      output {
+        pedido: financeiro
+        status: interno
+      }
+    }
+    audit {
+      evento: pedido.criado
+      ator: auth.usuario
+      correlacao: request_id
+      retencao: "180d"
+      motivo: obrigatorio
+    }
+    forbidden {
+      shell.exec
+      log.segredo
+      retorno.credencial
+    }
+    rules {
+      itens deve_ser nao_vazio
+      cliente_id deve_ser valido
+    }
+    effects {
+      consulta Cliente por cliente_id criticidade = media
+      consulta Produto por cada item.produto_id criticidade = media
+      persistencia Pedido criticidade = alta
+      persistencia ItemPedido criticidade = alta
+      evento pedido_criado criticidade = media
+      auditoria criacao_pedido criticidade = media
+    }
+    vinculos {
+      tabela: pedidos
+      tabela: itens_pedido
+      evento: pedido_criado
+    }
+    execucao {
+      idempotencia: verdadeiro
+      timeout: "10s"
+      retry: "nenhum"
+      compensacao: "cancelar_pedido"
+      criticidade_operacional: alta
+    }
+    state ciclo_pedido {
+      transitions {
+        RASCUNHO -> AGUARDANDO_PAGAMENTO
+      }
+    }
+    guarantees {
+      pedido existe
+      status == AGUARDANDO_PAGAMENTO
+    }
+    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: "prod_1:2"
+        }
+
+        expect {
+          sucesso: verdadeiro
+          status: "AGUARDANDO_PAGAMENTO"
+          pedido: "ped_1"
+        }
+      }
+    }
+  }
+
+  task cancelar_pedido {
+    input {
+      pedido_id: Id required
+      status_atual: StatusPedido required
+      motivo: Texto required
+    }
+    output {
+      protocolo: Id
+      status: StatusPedido
+    }
+    authz {
+      escopo: pedidos.cancelar
+      tenant: obrigatorio
+    }
+    dados {
+      classificacao_padrao: interno
+      redacao_log: obrigatoria
+      input {
+        pedido_id: interno
+        status_atual: interno
+        motivo: interno
+      }
+      output {
+        protocolo: interno
+        status: interno
+      }
+    }
+    audit {
+      evento: pedido.cancelado
+      ator: auth.usuario
+      correlacao: request_id
+      retencao: "180d"
+      motivo: obrigatorio
+    }
+    forbidden {
+      shell.exec
+      log.segredo
+    }
+    rules {
+      pedido_id deve_ser valido
+      status_atual em [AGUARDANDO_PAGAMENTO, APROVADO]
+      motivo deve_ser preenchido
+    }
+    effects {
+      persistencia Pedido criticidade = alta
+      evento pedido_cancelado criticidade = alta
+      notificacao cliente pedido_cancelado criticidade = media
+      auditoria cancelamento_pedido criticidade = media
+    }
+    vinculos {
+      tabela: pedidos
+      evento: pedido_cancelado
+    }
+    execucao {
+      idempotencia: verdadeiro
+      timeout: "10s"
+      retry: "nenhum"
+      compensacao: "notificar_operacao"
+      criticidade_operacional: alta
+    }
+    state ciclo_pedido {
+      transitions {
+        AGUARDANDO_PAGAMENTO -> CANCELADO
+        APROVADO -> CANCELADO
+      }
+    }
+    guarantees {
+      protocolo existe
+      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"
+          status_atual: "AGUARDANDO_PAGAMENTO"
+          motivo: "Desistencia do cliente"
+        }
+
+        expect {
+          sucesso: verdadeiro
+          protocolo: "cancel_1"
+          status: "CANCELADO"
+        }
+      }
+    }
+  }
+
+  flow aprovacao_pedido {
+    pedido_id: Id
+    valor: Decimal
+    produto_id: Id
+    quantidade: Inteiro
+    token_pagamento: Texto
+    itens_reservados: Texto
+    status_cancelamento: StatusPedido
+    motivo_pagamento_recusado: Texto
+    motivo_estoque_insuficiente: Texto
+    etapa pagar usa processar_pagamento com pagamento_id = pedido_id, valor = valor, token = token_pagamento em_sucesso reservar em_erro cancelar_por_pagamento
+    etapa reservar usa reservar_estoque com produto_id = produto_id, quantidade = quantidade, pedido_id = pedido_id depende_de pagar em_sucesso aprovar em_erro cancelar_por_estoque
+    etapa aprovar usa criar_pedido com cliente_id = pedido_id, itens = itens_reservados depende_de reservar
+    etapa cancelar_por_pagamento usa cancelar_pedido com pedido_id = pedido_id, status_atual = status_cancelamento, motivo = motivo_pagamento_recusado depende_de pagar
+    etapa cancelar_por_estoque usa cancelar_pedido com pedido_id = pedido_id, status_atual = status_cancelamento, motivo = motivo_estoque_insuficiente depende_de reservar
+    effects {
+      auditoria fluxo_aprovacao_pedido criticidade = alta
+    }
+  }
+}