# Deploy — Código da Estrada

## O que vai para Git

```
.gitignore
php/
├── config.php                 # lê variáveis de ambiente / config.local.php
├── config.local.php.example   # template (nunca o .local real)
├── migrate.php                # runner de migrações
├── migrations/                # ficheiros SQL versionados
│   ├── 001_initial_schema.sql
│   └── 002_question_reports.sql
├── includes/
├── api/
├── admin/
├── assets/
└── *.php                      # páginas
```

**NÃO vai para Git:**
- `php/config.local.php` — credenciais locais
- `php/images/` — gerir via FTP/rsync (binários grandes)
- `tools/` — PHP/MySQL portáteis (só para Windows local)
- `.env` / ficheiros com passwords

---

## Ambientes

### Local (desenvolvimento)
Copiar o template e ajustar:
```bash
cp php/config.local.php.example php/config.local.php
```
O ficheiro `config.local.php` sobrescreve os valores de `config.php`.
O banner **🔧 AMBIENTE LOCAL** aparece para todos os utilizadores.

### Produção
Definir variáveis de ambiente no servidor (`.htaccess`, painel de hosting, php-fpm pool):

```apacheconf
# .htaccess (Apache)
SetEnv APP_ENV  production
SetEnv DB_HOST  localhost
SetEnv DB_NAME  nome_da_base
SetEnv DB_USER  utilizador_db
SetEnv DB_PASS  password_segura
SetEnv BASE_URL https://seudominio.com
```

Ou via cPanel → PHP Environment Variables, ou num ficheiro `.env` lido por um autoloader.

Em PRD:
- Nenhum `config.local.php` existe no servidor
- O banner de ambiente **só é visível para admins** (discreto, canto superior direito)
- `session.cookie_secure` é activado automaticamente (HTTPS)

---

## Primeiro deploy (servidor vazio)

```bash
# 1. Clonar o repo
git clone https://github.com/SEU_USER/codigo-estrada.git
cd codigo-estrada

# 2. Configurar ambiente (ver secção acima)
#    Definir variáveis APP_ENV, DB_*, BASE_URL no servidor

# 3. Criar a base de dados (1x)
mysql -u USER -p -e "CREATE DATABASE IF NOT EXISTS nome_da_base CHARACTER SET utf8mb4;"

# 4. Correr migrações (cria todas as tabelas)
php php/migrate.php

# 5. Criar admin (1x)
php php/create_admin.php admin senha_segura

# 6. Subir imagens via FTP/rsync
rsync -avz php/images/ user@servidor:/path/public_html/images/
```

A raiz pública do servidor deve apontar para a pasta `php/`.

---

## Updates (deploys seguintes)

```bash
git pull

# Correr apenas as migrações novas (as já aplicadas são ignoradas)
php php/migrate.php
```

O runner de migrações regista cada ficheiro aplicado na tabela `migrations`.
Nunca apaga dados — só usa `ALTER TABLE`, `CREATE TABLE IF NOT EXISTS`, `INSERT`, etc.

---

## Migrações — como adicionar alterações à BD

Criar um ficheiro novo em `php/migrations/` com número sequencial:

```bash
# Exemplos:
003_add_user_preferences.sql
004_index_study_answers.sql
```

Regras:
- **Nunca modificar** ficheiros de migração já aplicados
- Usar sempre `IF NOT EXISTS` / `IF EXISTS` para ser idempotente
- Para alterar coluna: `ALTER TABLE x MODIFY COLUMN ...`
- Para adicionar coluna: `ALTER TABLE x ADD COLUMN IF NOT EXISTS ...`
- Para dados iniciais: `INSERT IGNORE INTO ...`

Exemplo de migração segura:
```sql
-- 003_add_user_preferences.sql
ALTER TABLE users ADD COLUMN IF NOT EXISTS lang VARCHAR(5) DEFAULT 'pt';
CREATE INDEX IF NOT EXISTS idx_lang ON users(lang);
```

---

## Imagens

- **Path local:** `php/images/`
- **Path no servidor:** mesma estrutura relativa ao `index.php`
- Referenciadas no código como `base_url('/images/FICHEIRO')`
- **Não estão no Git** — sincronizar via:

```bash
# Upload inicial ou sync incremental
rsync -avz --progress php/images/ user@host:/path/public_html/images/
```

---

## Dump da base de dados (backup / migração de dados)

```bash
# Exportar (local)
./tools/mysql/bin/mysqldump.exe -u root codigo_estrada > backup_$(date +%Y%m%d).sql

# Importar (servidor)
mysql -u USER -p nome_da_base < backup_20260419.sql
```

Para migrar **só os dados** (sem estrutura, que já vem pelas migrations):
```bash
mysqldump -u root --no-create-info codigo_estrada questions users > dados.sql
```

---

## Checklist pré-go-live

- [ ] Variáveis de ambiente configuradas no servidor
- [ ] `php php/migrate.php` sem erros
- [ ] Admin criado e testado
- [ ] Imagens sincronizadas
- [ ] HTTPS activo (`BASE_URL` começa com `https://`)
- [ ] Testar login, estudo, simulado, admin panel
- [ ] Banner "🔧 AMBIENTE LOCAL" não aparece para utilizadores normais