---
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:

```text
Análise concluída.

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

Arquivos que serão alterados:
- ...

Impacto:
- ...

Posso implementar?
```

Após autorização:

```text
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:

```text
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:

```sql
SELECT * FROM produto;

SELECT p.* FROM produto p;

SELECT COUNT(*) FROM produto;
```

Prefira:

```sql
SELECT
    id,
    uuid,
    nome,
    ncm
FROM produto;
```

Para contagem:

```sql
SELECT COUNT(id)
FROM produto;
```

ou:

```sql
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.

```sql
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:

```text
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:

```text
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:

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

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

```text
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:

```json
{
    "cliente_id": 123
}
```

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

```json
{
    "cliente_uuid": "019..."
}
```

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

```json
{
    "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:

```text
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:

```sql
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:

```text
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:

```text
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.**