# Etapa 3 — Administração, Compatibilidade Relacional e BI de Indicadores

Esta etapa mantém o frontend React/Vite sem alteração estrutural e amplia a API PHP para cobrir telas administrativas.

## Novidades

### 1. Compatibilidade Supabase/PostgREST ampliada

`/api/v1/compat/{table}` agora possui suporte básico para select relacional usado pelo frontend, por exemplo:

```ts
supabase
  .from("usuario_municipios")
  .select("municipio_id, ativo, municipios:municipios(id, nome, uf, bloqueado)")
```

A API PHP retorna o objeto relacionado em `municipios` quando encontra a FK `municipio_id`.

Relações previstas:

- `usuario_municipios -> municipios`
- `profiles -> municipios`
- `departamentos -> secretarias`
- `setores -> departamentos`
- `grupos_trabalho -> setores`
- `municipio_modulos -> municipios`
- `municipio_modulos -> modulos`
- `permissoes -> modulos`
- `role_permissoes -> permissoes`
- `perfil_customizado_permissoes -> permissoes`
- `perfil_customizado_permissoes -> perfis_customizados`

### 2. BI de indicadores

Nova rota:

```http
GET /api/v1/bi/indicadores
```

Retorna KPIs e gráficos para a página `BIIndicadores.tsx`:

- Municípios totais, ativos e bloqueados
- Usuários totais, ativos e bloqueados
- Secretarias, departamentos, setores e grupos
- Módulos ativos
- Auditoria total e auditoria do dia
- Logins de hoje
- Tentativas falhas nas últimas 24h
- Imóveis CTM, quando a tabela existir

A rota respeita:

- visão global para `super_admin`
- visão municipal para usuários comuns, usando `municipality_id` do token

### 3. Tratamento de tabelas ausentes

Se alguma tabela ainda não existir, a API retorna `0` ou lista vazia, em vez de quebrar o sistema.

## Testes sugeridos

```powershell
Invoke-RestMethod -Uri "http://127.0.0.1:8081/api/v1/health"
```

Depois, com o frontend logado, acessar:

```text
/app/bi-indicadores
/app/municipios
/app/secretarias
/app/departamentos
/app/setores
/app/modulos
/app/branding
```

## Observação

Esta etapa ainda não implementa o BI fiscal IPTU completo nem endpoints geoespaciais avançados. Isso fica para a próxima etapa.