Todos os blocos e campos

Padrões de Engenharia

Todos os blocos de Padrões de Engenharia pertencem exclusivamente ao arquivo de padrões (por convenção padroes.spell). O compilador emite ❌ ERRO se encontrá-los em qualquer outro arquivo.

Bloco	O que define	Sub-blocos
`Tecnologia`	Stack tecnológico completo	`Backend`, `Frontend`, `Autenticacao`, `Comunicacao`, `Integracao`, `Bibliotecas`
`Arquitetura`	Padrão arquitetural, pastas, erros, logging	—
`ConvencoesD`	Nomenclatura e comportamento do banco	—
`ConvencoesC`	Nomenclatura do código-fonte	—
`API`	Estilo, URLs, versionamento, envelope, CORS	—
`Interface`	Design system, temas, formulários, feedback	—
`Qualidade`	Tipos de teste, cobertura mínima	—
`Engenharia`	Branching, commits, variáveis de ambiente	`Configuracoes`
`Skills`	Capacidades esperadas do agente executor	—
`Tema`	Identidade visual e tokens de design	`Cores`, `Cores.claro`, `Cores.escuro`, `Tipografia`, `Formas`, `Componentes`, `Comportamento`
`Site`	Site institucional separado da aplicação	—

Domínio do Sistema

Bloco	O que contém	Sub-blocos / Keywords
`Dados`	Modelagem de dados do sistema	`table`, `Indices`, `Configuracao`
`Regras`	Regras de negócio explícitas	`rule`
`Endpoints`	Operações da API REST	`endpoint`, `Entrada`, `Params`, `Respostas`
`Telas`	Interfaces do usuário	`screen`, `Layout`, `Wireframes`
`Seguranca`	Políticas de segurança e acesso	`Middleware`
`Servicos`	Jobs em background e tarefas agendadas	`service`
`Comandos`	Comandos CLI — apenas em projetos com `tipo: cli`	`command`, `Args`, `Flags`, `Saida`

Tipos de campo em tabelas

Tipo	Descrição	SQL típico
`inteiro`	Número inteiro	INTEGER / BIGINT
`decimal`	Número com decimais	DECIMAL / NUMERIC
`texto(N)`	String com máximo N caracteres	VARCHAR(N)
`booleano`	Verdadeiro ou falso	BOOLEAN
`data`	Data sem hora	DATE
`data-hora`	Data e hora com fuso	TIMESTAMP WITH TIME ZONE
`hora`	Hora do dia	TIME
`arquivo`	Referência a blob/arquivo externo	VARCHAR (URL ou chave)
`json`	Objeto JSON sem esquema fixo	JSONB / JSON

Modificadores de campo

Modificador	Efeito
`chave-primaria`	PRIMARY KEY
`auto-incremento`	SERIAL / IDENTITY — gerado automaticamente
`unico`	UNIQUE constraint
`obrigatorio`	NOT NULL
`opcional`	Permite NULL (padrão quando omitido)
`privado`	Não retornado em respostas de API por padrão
`indexado`	Cria índice simples na coluna
`padrao: valor`	Valor padrão quando não informado

Campos de rule

Campo	Obrigatório	Descrição
`tipo`	Não	`validacao`, `autorizacao`, `rate-limit`, `negocio`, `auditoria`
`contexto`	Recomendado	Em que situação a regra se aplica
`condicao`	Recomendado	Quando a regra é acionada
`acao`	Recomendado	O que acontece quando a condição é verdadeira
`excecao`	Não	Casos em que a regra não se aplica
`motivo`	Não	Justificativa de negócio

Campos de endpoint

Campo / Sub-bloco	Descrição
`rota`	MÉTODO /caminho — ex: `POST /usuarios`
`autenticacao`	`obrigatoria` ou `nao-requerida`
`regras`	Lista de nomes de regras separados por vírgula
`Entrada { }`	Campos do body da requisição
`Params { }`	Parâmetros de query string
`Respostas { }`	Códigos HTTP e descrições

Campos de command (projetos CLI)

Usado dentro de Comandos { } em projetos com tipo: cli no Backend { }. Substitui endpoint / Endpoints { } para aplicações de linha de comando.

Campo / Sub-bloco	Obrigatório	Descrição
`uso`	Não	String de uso do comando — ex: `mycli build [arquivo]`
`descricao`	Não	O que o comando faz em uma linha
`Args { }`	Não	Argumentos posicionais — mesma sintaxe de campos de tabela
`Flags { }`	Não	Flags nomeadas: `--nome: descrição do flag`
`Saida { }`	Recomendado	Contrato de saída: `sucesso: descrição` e `erro: descrição`

Regras do auditor para Comandos { }:

tipo: cli + Endpoints { } presente → ⚠️ AVISO: tipo cli não usa Endpoints — use Comandos { }
tipo: cli + Telas { } presente → ⚠️ AVISO: tipo cli não usa Telas
command sem Saida { } → ⚠️ AVISO: comando sem contrato de saída declarado

Campos de service

Campo	Descrição
`periodicidade`	Frequência de execução. Texto livre.
`horario`	Horário de execução para jobs diários (HH:MM)
`ciclo-de-vida`	`singleton`, `scoped`, `transient`, `hosted-service`