setting

O submódulo Setting fornece um armazenamento de configuração centralizado e tipado que separa os parâmetros operacionais do código, permitindo ajustes no comportamento da aplicação em tempo de execução sem deploys. As configurações são organizadas em grupos nomeados (general, mail, security, ai), e cada configuração carrega um type que determina tanto a semântica de armazenamento quanto o widget de entrada renderizado no painel de administração.

Seis tipos de valor são suportados. String armazena texto arbitrário. Number armazena valores numéricos. Boolean controla toggle switches e checkboxes. Array gerencia listas de valores string renderizadas como tag inputs. JSON armazena objetos estruturados que são parseados no momento da leitura. Secret armazena valores sensíveis (API keys, credenciais, senhas SMTP) que são guardados criptografados e automaticamente mascarados nas respostas de listagem e nos payloads de exportação — o valor bruto só é acessível pelo setting service em tempo de execução.

Quando uma configuração tem o user_override habilitado, cada usuário pode definir seu próprio valor, que tem precedência sobre o padrão global. GET /setting/effective mescla o valor global com qualquer sobrescrita específica do usuário, retornando o valor final que deve governar o comportamento para o usuário autenticado. Seleção de tema, idioma preferido e preferências de dashboard são exemplos típicos de configurações sobrescrevíveis pelo usuário.

O endpoint público GET /setting/initial retorna um subconjunto selecionado de configurações não sensíveis necessárias para renderizar o frontend antes de o usuário se autenticar — nome da aplicação, URL do logo, locales disponíveis, provedores OAuth habilitados. Isso elimina a configuração de frontend embutida no código e permite a personalização white-label pelo painel de administração.

As configurações podem ser exportadas como JSON via GET /setting/export. A importação segue um fluxo de validação e depois confirmação em duas etapas: envie um arquivo JSON para POST /setting/import para validação e, em seguida, envie o payload validado para POST /setting/import/confirm para aplicá-lo. Isso protege contra a aplicação de configurações malformadas ou incompatíveis com o ambiente em produção. As configurações do tipo lista carregam um conjunto de opções selecionáveis gerenciadas via PUT /setting/:settingId/options, permitindo valores de dropdown personalizados sem alterações de código.