# Padronização do Backend PHP — SISPROM

## Padrão oficial da API

Todas as rotas novas devem usar o prefixo:

```txt
/api/v1
```

Exemplos oficiais:

```txt
GET  /api/v1/health
POST /api/v1/auth/login
GET  /api/v1/auth/me
GET  /api/v1/mapa/config
GET  /api/v1/bi/iptu/resumo
GET  /api/v1/debug/routes
GET  /api/v1/debug/migration-check
```

## Estrutura oficial

```txt
backend-php/
  app/
    Controllers/
    Core/
    config/
  public/
    index.php
    .htaccess
    router.php
  storage/
    logs/
  uploads/
```

O document root do domínio/subdomínio deve apontar para:

```txt
backend-php/public
```

## Testes rápidos

Servidor PHP embutido:

```bash
cd backend-php
php -S 127.0.0.1:8081 -t public public/router.php
```

Testar saúde:

```bash
curl http://127.0.0.1:8081/api/v1/health
```

Listar rotas registradas:

```bash
curl http://127.0.0.1:8081/api/v1/debug/routes
```

Diagnóstico da migração:

```bash
curl http://127.0.0.1:8081/api/v1/debug/migration-check
```

## Padrão de resposta

Respostas de sucesso devem preferir:

```json
{
  "success": true,
  "message": "OK",
  "data": {}
}
```

Respostas de erro usam:

```json
{
  "success": false,
  "message": "Mensagem do erro",
  "status": 400,
  "details": {}
}
```

Algumas rotas de compatibilidade Supabase podem continuar retornando arrays diretos para não quebrar o frontend.

## Regras para novas rotas

1. Registrar a rota em `App\Core\App::registerRoutes()`.
2. Usar controller em `app/Controllers`.
3. Usar `Request` para entrada e `Response` para saída.
4. Não criar arquivos PHP soltos fora da API, exceto legados em transição.
5. Não hardcodar município, schema ou GeoServer. Use `.env` e `/api/v1/mapa/config`.

## cPanel / Apache

O `.htaccess` da pasta `public` preserva o header Authorization e redireciona rotas amigáveis para `index.php`.

Se o subdomínio for `api-reurbtec.sisprom.com.br`, a raiz pública deve ser:

```txt
/home/usuario/backend-php/public
```

No frontend, configure:

```env
VITE_API_BASE_URL=https://api-reurbtec.sisprom.com.br
```