workbloomerp-api/.agents/rules/main-rules.md

trigger

trigger
always_on

AGENTS.md

Workbloom ERP — Diretrizes para Agentes de IA

Este documento define as regras obrigatórias para qualquer agente que analise, altere, refatore ou implemente código no Workbloom ERP.

1. Regra principal: planejar antes de implementar

Nunca altere o projeto diretamente.

Antes de modificar qualquer arquivo, código, banco, endpoint, classe, serviço ou estrutura:

1. Analise o código existente.
2. Identifique arquivos, componentes, dependências e impactos.
3. Crie um plano objetivo.
4. Apresente o plano ao usuário.
5. Solicite autorização explícita.
6. Só implemente após a autorização.

Consultas, análises, diagnósticos, explicações e sugestões que não alterem arquivos podem ser realizadas normalmente.

Para bugs, primeiro identifique causa e sintoma, analise o fluxo e apresente o plano de correção. Não faça tentativas de correção diretamente.

Formato:

Análise concluída.

Plano:
1. ...
2. ...
3. ...

Arquivos que serão alterados:
- ...

Impacto:
- ...

Posso implementar?

Após autorização:

Implementado.

Alterações:
- ...

Validações realizadas:
- ...

Possíveis pontos de atenção:
- ...

2. Stack e arquitetura

O backend não utiliza Laravel nem CodeIgniter.

A API utiliza:

claudecio/krothiumapi v1.0

Respeite a arquitetura e as abstrações existentes no claudecio/krothiumapi. Não introduza outro framework, padrão ou arquitetura sem necessidade e autorização.

Antes de criar qualquer classe, serviço, repository, DTO, controller ou estrutura:

1. Procure uma estrutura equivalente.
2. Identifique o padrão existente.
3. Reutilize-o quando possível.
4. Crie uma nova abordagem somente quando justificado.

Não replique funcionalidades já fornecidas pelo krothiumapi.

3. Banco de dados

O banco utilizado é PostgreSQL.

O sistema possui múltiplos domínios, incluindo autenticação, multi-tenant, empresas, configurações fiscais, clientes, fornecedores, produtos, serviços, documentos fiscais, pagamentos e administração.

Antes de qualquer alteração estrutural, analise o modelo atual, dependências e impacto nos dados.

Alterações em tabelas, colunas, índices, constraints, foreign keys, enums, funções, triggers, views ou migrations exigem:

1. análise;
2. plano;
3. autorização;
4. implementação.

Nunca altere o banco diretamente sem autorização.

4. Regra absoluta de SQL

É proibido utilizar SELECT * ou qualquer variação.

Proibido:

SELECT * FROM produto;

SELECT p.* FROM produto p;

SELECT COUNT(*) FROM produto;

Prefira:

SELECT
    id,
    uuid,
    nome,
    ncm
FROM produto;

Para contagem:

SELECT COUNT(id)
FROM produto;

ou:

SELECT COUNT(1)
FROM produto;

Toda consulta deve selecionar somente as colunas necessárias.

Isso vale para repositories, queries, services, endpoints, relatórios, JOINs, subqueries e views.

Nunca concatene valores fornecidos pelo usuário no SQL. Utilize parâmetros conforme o mecanismo existente no projeto.

5. JOINs

Sempre informe explicitamente as colunas e utilize aliases quando necessário.

SELECT
    df.id,
    df.uuid,
    df.numero,
    c.id AS cliente_id,
    c.nome AS cliente_nome
FROM documento_fiscal df
INNER JOIN cliente c
    ON c.id = df.cliente_id;

6. UUID

As entidades principais utilizam UUID.

A estratégia recomendada é UUID v7 gerado pela aplicação antes do INSERT, quando essa for a convenção da tabela.

Não altere a estratégia existente sem analisar primeiro sua implementação atual.

7. Transações e integridade

Operações que modificam múltiplos registros relacionados devem respeitar o padrão transacional existente.

Exemplo:

Documento fiscal
 ├── Itens
 ├── Pagamentos
 ├── Duplicatas
 └── Série

Operações fiscais relacionadas devem manter consistência e, quando aplicável, atomicidade.

Nunca:

• desabilite foreign keys;
• ignore constraints;
• insira dados inconsistentes;
• utilize valores mágicos para contornar regras;
• duplique dados para contornar relacionamentos.

8. Precisão numérica

Respeite a precisão definida pelo domínio:

Valores monetários: NUMERIC(15,2)
Quantidades, pesos, alíquotas e fatores: NUMERIC(15,4)

Não altere a precisão sem justificativa e autorização.

9. Backend e API

Ao implementar endpoints:

1. Valide as entradas.
2. Utilize DTOs quando esse for o padrão existente.
3. Mantenha regras de negócio fora de controllers excessivamente grandes.
4. Utilize repositories quando esse for o padrão.
5. Não espalhe SQL pela aplicação.
6. Trate erros conforme o padrão existente.
7. Preserve contratos da API.

Não altere contratos existentes sem avaliar seus consumidores.

9.1. Identificadores nos endpoints

Endpoints devem utilizar exclusivamente UUID como identificador de recursos.

É proibido expor ou utilizar IDs numéricos (id) nos endpoints da API, tanto em parâmetros de rota quanto em parâmetros destinados a identificar recursos.

Exemplos proibidos:

GET /produtos/123
GET /clientes/456
GET /documentos-fiscais/789
DELETE /produtos/123
PUT /clientes/456

O padrão obrigatório é utilizar o uuid:

GET /produtos/{uuid}
GET /clientes/{uuid}
GET /documentos-fiscais/{uuid}
DELETE /produtos/{uuid}
PUT /clientes/{uuid}

Também é proibido utilizar id numérico em:

• parâmetros de rota;
• query parameters quando o parâmetro representa a identificação de um recurso;
• payloads de entrada quando o objetivo for referenciar uma entidade externamente;
• respostas da API como identificador público;
• links e relacionamentos retornados pela API;
• filtros de endpoints que tenham como finalidade localizar uma entidade específica.

Exemplo proibido:

{
    "cliente_id": 123
}

Quando a referência for necessária através do contrato da API, utilize:

{
    "cliente_uuid": "019..."
}

ou, conforme o padrão já estabelecido no projeto:

{
    "cliente": "019..."
}

A nomenclatura deve seguir o padrão existente na API. Não crie uma nova convenção sem antes verificar como os recursos relacionados já são representados.

Uso interno do id

O id numérico pode continuar sendo utilizado internamente pela aplicação e pelo banco de dados, quando essa for a estrutura existente.

Por exemplo:

API
 ↓
UUID
 ↓
Controller / DTO
 ↓
Service
 ↓
Repository
 ↓
id interno
 ↓
Banco de dados

Nesse cenário, o UUID é o identificador público e o id é apenas um identificador interno.

É permitido, por exemplo, utilizar:

SELECT
    id,
    uuid,
    nome
FROM cliente
WHERE uuid = :uuid;

e posteriormente utilizar o id internamente para relacionamentos, JOINs ou operações no banco, desde que o id não seja exposto ao consumidor da API.

Regra absoluta

id numérico é identificador interno. uuid é identificador público.

Nenhum endpoint deve exigir que o consumidor conheça ou forneça o id numérico de uma entidade.

Antes de implementar ou alterar um endpoint, verifique se todos os identificadores expostos pelo contrato da API utilizam UUID.

Caso um endpoint existente utilize id numérico, não faça a alteração automaticamente. Analise os consumidores, apresente o impacto e solicite autorização antes de alterar o contrato.

10. Alterações mínimas

Altere somente o necessário para atender à tarefa.

Não faça:

• refatorações fora do escopo;
• reorganização desnecessária;
• renomeações por preferência pessoal;
• alterações de estilo sem motivo;
• atualizações de dependências sem necessidade;
• mudanças em contratos não relacionados.

Quanto menor o escopo, melhor.

11. Remoção de código

Não remova métodos, classes, endpoints, tabelas, colunas, validações ou testes sem verificar seus consumidores e dependências.

Qualquer remoção deve ter justificativa.

12. Testes e validação

Toda alteração que modifique comportamento deve considerar testes.

Antes de finalizar:

1. Execute os testes relacionados.
2. Valide o comportamento alterado.
3. Verifique possíveis regressões.
4. Informe o que foi testado.

Não crie uma infraestrutura de testes inteira sem necessidade quando ela não existir.

13. Documentação

Quando uma alteração modificar contrato de API, comportamento importante, banco, fluxo fiscal, configuração ou integração externa, avalie a necessidade de atualizar a documentação correspondente.

14. Segurança

Nunca:

• exponha senhas;
• exponha tokens;
• exponha certificados;
• exponha chaves privadas;
• exponha credenciais;
• coloque secrets diretamente no código;
• faça commit de credenciais;
• registre dados sensíveis desnecessários.

Utilize o mecanismo de segurança já existente no projeto.

15. Logs

Logs devem auxiliar no diagnóstico sem expor informações sensíveis.

Nunca registre:

senhas
tokens
certificados
chaves privadas
credenciais
dados sensíveis desnecessários

Siga o padrão de logging existente e utilize o nível adequado.

16. Integrações fiscais

O sistema possui integrações com:

• NF-e Modelo 55;
• NFC-e Modelo 65;
• NFS-e;
• CT-e Modelo 57;
• MDF-e Modelo 58;
• eventos fiscais e serviços relacionados.

Não simplifique regras fiscais apenas para facilitar uma implementação.

Alterações devem considerar os fluxos e relacionamentos existentes.

17. Fluxos críticos

Tenha atenção especial a operações com múltiplas etapas, como:

Produto
 ↓
Documento Fiscal
 ↓
Itens
 ↓
Pagamentos
 ↓
Duplicatas
 ↓
Assinatura
 ↓
Transmissão
 ↓
Autorização
 ↓
Atualização do documento
 ↓
Numeração da série

Alterações em uma etapa podem afetar as demais.

18. Não assumir

Quando algo não estiver claro:

• procure no código;
• procure configurações;
• procure migrations;
• procure classes relacionadas;
• procure documentação;
• verifique contratos existentes.

Não invente comportamento.

Se permanecer uma ambiguidade relevante, informe a dúvida ao usuário antes de implementar.

19. Regra de escopo

Não faça alterações silenciosas.

Não implemente melhorias não solicitadas.

Não introduza arquitetura nova sem necessidade.

Não altere banco sem planejamento e autorização.

Não comprometa integridade ou segurança para "fazer funcionar".

20. Checklist obrigatório

Antes de finalizar uma implementação:

• Plano apresentado antes da implementação.
• Autorização explícita recebida.
• Alteração dentro do escopo solicitado.
• Arquitetura existente respeitada.
• Nenhum Laravel utilizado.
• Nenhum CodeIgniter utilizado.
• claudecio/krothiumapi v1.0 respeitado.
• Nenhum SELECT * utilizado.
• Colunas SQL explicitamente definidas.
• SQL parametrizado.
• Alterações de banco avaliadas.
• Testes/validações executados.
• Nenhuma refatoração desnecessária.
• Nenhum segredo ou credencial exposto.
• Resultado informado ao usuário.
• Endpoints utilizam exclusivamente UUID como identificador público.
• Nenhum id numérico é exposto ou exigido pelos endpoints.
• IDs numéricos são utilizados somente internamente, quando necessário.
• Alterações em endpoints existentes que utilizam IDs numéricos foram analisadas antes de modificar o contrato.

Regra de ouro

Use exclusivamente UUID nos endpoints. Nunca exponha ou exija IDs numéricos (id) na API. id é identificador interno; uuid é identificador público. Planeje antes de implementar. Peça autorização antes de alterar. Nunca utilize SELECT *. Nunca modificar o conteúdo da pasta vendor Respeite a arquitetura existente. Não utilize Laravel ou CodeIgniter. Respeite claudecio/krothiumapi v1.0. Não altere banco sem planejamento e autorização. Não faça alterações fora do escopo. Preserve segurança e integridade dos dados.