triad-assets
Itens e containers · Lua 5.4
Não existe criar, dar ou destruir item nesta API. A ausência é deliberada e está documentada como decisão.
- Lua
- 1.285 linhas
- Superfície pública
- 8 exports
- Migrations de itens
- 3
- Chamadas do cliente
- nenhuma
é primitiva de servidor
Fonte verificada no repositório interno em 08/09/2026
O que faz
Em uso
O núcleo de itens define classe, definição e container, e move quantidade entre containers. O que ele deliberadamente não faz é mais interessante do que o que faz.
Não existe criar, dar, destruir ou ajustar quantidade. Não é esquecimento: item nasce e morre por operação nomeada, com motivo e trilha — a mesma razão pela qual não existe somar dinheiro no núcleo. E hoje não há motivo de domínio concreto para nenhuma criação específica: saque, compra, fabricação e criação administrativa pertencem a sistemas que ainda não existem. Criar a API antes do motivo seria decidir o desenho dela sem conhecer o caso, e ela nasceria genérica — que é exatamente o que se quer evitar.
Também não há nenhuma chamada do cliente. Quando existir inventário, ele terá o próprio contrato e a própria autoridade, e será ele a falar com o cliente.
Evidência
Como o sistema aparece
Capturas da interface real, renderizada com payload de demonstração derivado dos contratos do resource — organizações, cargos, pessoas e identificadores são sintéticos. Onde não existe interface, entra visualização técnica, rotulada como tal.
Visualização técnica As duas ausências deliberadas, e a invariante que impede a duplicação de item.
Por dentro da engenharia
Decisões de implementação
Um bloco por decisão de implementação. Abra o que interessa.
A verificação mora na cláusula da operação
Problema
Conferir container e slot com uma consulta e depois mover é a forma clássica de duplicar item: entre "conferi" e "movi" existe uma janela, e é nela que duas requisições simultâneas passam.
Solução
Container e slot são verificados dentro da própria cláusula da operação de movimento, nunca num select anterior.
Por que foi feito assim
A janela deixa de existir. É a mesma razão pela qual a saída de estoque de um sistema hospitalar valida a quantidade no próprio comando de atualização.
Não se confia no chamador, nem sendo da casa
Problema
Se peso, teto de pilha e definição viessem no argumento, um consumidor poderia declarar que a arma pesa zero e cabe 999 por slot — e a operação obedeceria, porque o banco não conhece definição de item.
Solução
Esses valores são derivados da instância no banco e do registro em código. A quantidade é validada como inteiro positivo antes de chegar ao SQL.
Por que foi feito assim
Confiança entre resources da mesma casa é a que mais custa a recuperar: quando o consumidor errado existir, ninguém vai suspeitar dele.
Criação de itens somente por operações de domínio específicas
Problema
Uma porta genérica de criar valor é a porta que todo exploit procura. E ela não fica mais segura por ganhar validação — o problema é existir.
Solução
Nenhuma operação genérica de criação existe. Quando houver motivo de domínio concreto, a operação entra nomeada — vender, fabricar, saquear —, cada uma justificando a própria existência e deixando trilha própria.
Por que foi feito assim
Adiar a API até existir o caso de uso produz uma API específica em vez de uma genérica. Genérica é o que se lamenta depois.
Stack
O que foi usado
Runtime
- Lua 5.4
- CfxLua
Dados
- MariaDB
- 3 migrations de itens
- Operação em cláusula única
Testes
- Catálogo
- Itens
- Esquema
- Integração com banco