# AGENTS.md

## Testes unitários do módulo Agent

Para que a suite unit NÃO toque produção, os testes do agente rodam contra o
banco de teste `ceon_tests`. O `tests/_bootstrap.php` só injeta as envs
`AGENT_DB_*` apontando para `ceon_tests` quando a variável
`YII_UNIT_TEST_AGENT_DB` está definida.

**SEMPRE execute com a env setada** (senão o `AgentDb` cai no host padrão e a
suite falha com `SQLSTATE[HY000] [2002] No such file or directory`):

```bash
YII_UNIT_TEST_AGENT_DB=1 vendor/bin/codecept run unit modules/agent --no-colors
```

Aguardado: green (`OK ... Tests: X, Assertions: Y`), com apenas os 2 testes de
paridade com banco real marcados como `Skipped`.

## Suíte E2E do módulo Agent

```bash
docker exec php74_apache php /var/www/html/privia-inteligente/modules/agent/scripts/teste_e2e_tools.php
```

A suite sobe o app com `config/web.php` (ambiente dev), portanto roda contra o
banco real — diferente da suite unit. Aguardado: `32/32` (todos os testes E2E
passam). Todos os `scripts/teste_e2e_*.php` tratam aviso/notice do PHP como exceção (como produção); ao criar um teste E2E novo, mantenha o `set_error_handler` logo após criar a Application.

## Catálogo de auditoria de exclusão (reindexação)

O Agente responde "quem/quando excluiu X" consultando `vw_auditoria_exclusao`
(mensagem/rota exatas de log por controller, extraídas do código — nunca
adivinhadas). Sempre que um controller for **criado ou tiver uma ação de
exclusão/inativação alterada**, reexecute o indexador (idempotente, varre todos
os controllers de novo, sem lista manual):

```bash
docker exec php74_apache php /var/www/html/privia-inteligente/modules/agent/scripts/index_auditoria_exclusao.php
```

Aguardado: `Entradas indexadas: N` (N cresce ou muda conforme os controllers).
Detalhes/origem: `docs/diariov2.md`, seção "Catálogo de auditoria de exclusão"
(2026-09-17).
## Significado dos valores codificados (reindexação)

O Agente entende colunas de códigos (`inventario_dados.tipo`, `status`, `situacao`...) a partir das
constantes/listas dos models (nada escrito à mão), gravadas em `agent_enum`. Sempre que um model **ganhar ou
alterar constantes `TIPO_*`/`STATUS_*`/`LISTA_*`**, e a cada deploy, reexecute (idempotente):

```bash
docker exec php74_apache php /var/www/html/privia-inteligente/modules/agent/scripts/index_enums.php
```

Aguardado: `Valores gravados em agent_enum: N`. Use `--relatorio` para ver o que foi ligado/descartado sem gravar.
Teste: `docker exec php74_apache php /var/www/html/privia-inteligente/modules/agent/scripts/teste_e2e_enum.php` (36/36).
O script também detecta RENOMEAÇÕES (nome da constante diverge do rótulo da tela, ex.: `TIPO_FORNECEDOR` → "Operadores de dados") e o agente é orientado a não usar o nome antigo. Rótulos visíveis ao usuário devem vir das listas dos models (`InventarioDados::LISTA_TIPO`...), nunca digitados no agente.
Detalhes: `docs/diariov2.md`, seção "Significado dos valores codificados" (2026-09-21).