# Manutenção — Banco de Talentos (Laravel 9)

Guia rápido para quem for dar manutenção, corrigir bugs ou fazer deploy.  
Documentação detalhada fica em `docs/talent-bank/` e `docs/api-sso-conta-angra.md`.

---

## Visão geral

| Item | Detalhe |
|------|---------|
| Projeto | `banco-de-talentos-laravel-9` — portal público BT (candidatos e empresas) |
| Framework | Laravel 9, PHP 8.1+ |
| Identidade | **Conta Angra** (`angra.rj.gov.br`) — OAuth + SSO popup |
| Banco | MySQL; em homolog compartilha `homolog_siati_app` com o portal Angra |
| Legado | `legacy/` — API e front antigos (referência; não é o runtime atual) |

O BT **não é autônomo**: login, cadastro na Conta Angra e parte do admin PAM dependem do portal Angra com variáveis pareadas no `.env`.

---

## Onde está o quê

```
app/Http/Controllers/Web/TalentBank/   # Controllers web (páginas públicas e área logada)
app/Http/Services/TalentBank/          # Regras de negócio
app/Models/TalentBank/                 # Models (candidates, companies, job_listings…)
app/Http/Middleware/                   # SSO, perfil completo, permissões
routes/web.php                         # Rotas públicas e área candidato/empresa
config/talent_bank.php                 # Config do módulo
public/css/  public/js/                # Assets (sem CSS/JS inline nas views)
resources/views/talent-bank/           # Views principais do módulo
resources/views/pages/               # Páginas estáticas (sobre, cadastro…)
```

**Integração SSO:** `app/Http/Controllers/Web/TalentBank/AuthWebController.php`, `docs/api-sso-conta-angra.md`.

**Provisionamento Conta Angra:** `app/Services/AngraSsoProvisioning.php` (sync candidato/empresa no banco do Angra).

---

## Ambiente local (Laragon)

1. Copiar `.env.example` → `.env`, `php artisan key:generate`
2. Banco: `DB_DATABASE=laravel_site` (mesmo schema do Angra local, se possível)
3. URLs `.test` típicas:
   - BT: `http://banco-de-talentos-laravel-9.test`
   - Angra: `http://angra.rj.gov.br.test`

### Variáveis locais importantes

```env
TALENT_BANK_LOCAL_REGISTER=true
ANGRA_SSO_LOGIN_URL=http://angra.rj.gov.br.test/login
ANGRA_SSO_EXCHANGE_URL=http://angra.rj.gov.br.test/api/sso/exchange
ANGRA_SSO_ORIGIN=http://angra.rj.gov.br.test
ANGRA_SSO_SECRET=<igual SSO_BRIDGE_SECRET no .env do Angra>
AUTH_SERVICE_URL=http://angra.rj.gov.br.test/api
```

No **Angra** local, parear:

```env
SSO_BRIDGE_SECRET=<mesmo valor>
SSO_BRIDGE_ALLOWED_ORIGINS=http://banco-de-talentos-laravel-9.test
BT_DB_DATABASE=laravel_site
```

### E-mail local

Usar **Mailpit** (só desenvolvimento):

```env
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_ENCRYPTION=null
```

Interface: `http://127.0.0.1:8025` — iniciar `laragon/bin/mailpit/mailpit.exe` antes de testar.

### Comandos úteis local

```bash
composer install
php artisan migrate
php artisan optimize:clear
php artisan serve   # se não usar Laragon virtual host
```

---

## Deploy homolog

Resumo operacional (detalhes: `docs/talent-bank/checklist-migracao-homolog.md` e `../homolog-deploy.md` na raiz do workspace).

| Sistema | Diretório típico |
|---------|------------------|
| BT | `/var/www/html/homologBancodetalentos` |
| Conta Angra | `/var/www/html/portalHomolog` |

### Rotina padrão (após `git pull`)

**Banco de Talentos:**
```bash
git pull && php artisan migrate && php artisan optimize:clear
```

**Conta Angra** (quando o deploy afeta SSO ou tabelas compartilhadas):
```bash
git pull && php artisan migrate && php artisan optimize:clear
```

### Setup homolog (primeira vez ou após migração legado)

```bash
# No Angra
cd /var/www/html/portalHomolog
php artisan banco-talentos:homolog-setup --force

# No BT
cd /var/www/html/homologBancodetalentos
php artisan talent-bank:homolog-setup --force
```

### Uma vez — empresas legadas com perfil “completo”

```bash
php artisan tinker --execute="DB::table('companies')->whereNotNull('corporate_name')->whereNull('profile_completed_at')->update(['profile_completed_at' => now()]); echo 'done';"
```

### `.env` homolog — BT

```env
DB_DATABASE=homolog_siati_app
ANGRA_SSO_LOGIN_URL=https://homolog.angra.rj.gov.br/login
ANGRA_SSO_EXCHANGE_URL=https://homolog.angra.rj.gov.br/api/sso/exchange
ANGRA_SSO_ORIGIN=https://homolog.angra.rj.gov.br
ANGRA_SSO_SECRET=<igual SSO_BRIDGE_SECRET do Angra>
```

### `.env` homolog — Angra

```env
DB_DATABASE_SIATI_APP=homolog_siati_app
SSO_BRIDGE_SECRET=<igual ANGRA_SSO_SECRET do BT>
SSO_BRIDGE_ALLOWED_ORIGINS=https://homolog-bt.angra.rj.gov.br
BT_DB_DATABASE=homolog_siati_app
```

Homolog usa **SMTP real** (`webmail.angra.rj.gov.br`) — não Mailpit.

---

## Comandos Artisan do módulo

| Comando | Uso |
|---------|-----|
| `talent-bank:homolog-setup` | Prepara schema/dados em homolog |
| `talent-bank:legacy-dry-run` | Simula migração legado → BT (conflitos) |
| `talent-bank:legacy-migrate` | Migração efetiva do legado |
| `talent-bank:validate-migration` | Valida integridade pós-migração |
| `talent-bank:deactivate-inactive-company-jobs` | Desativa vagas de empresas inativas |

No Angra: `banco-talentos:homolog-setup` (tabelas admin BT no banco compartilhado).

---

## Fluxos críticos (para debug)

| Fluxo | Rotas / arquivos |
|-------|------------------|
| Login formulário | `POST /entrar` → `AuthWebController@login` |
| Login SSO popup | `POST /entrar/sso-callback` + `ANGRA_SSO_*` |
| Detecção conta legada | `GET /auth/check-legacy` → `legacy` \| `angra_only` \| `none` |
| Candidato novo pós-SSO | redirect → `/concluir-cadastro` |
| Empresa nova pós-SSO | redirect → `/area-empresa/alterar-cadastro?new_account=1` |
| Perfil incompleto | middleware `profile.complete` (candidato) / `company.profile.complete` (empresa) |
| Recuperação de senha | `/esqueci-senha` — ver `docs/talent-bank/password-recovery.md` |

Logs: `storage/logs/laravel.log` — buscar por correlation id, `TalentBank`, `SSO`, `AngraSso`.

---

## Problemas comuns

| Sintoma | Causa provável | Ação |
|---------|----------------|------|
| Popup SSO não fecha / sem sessão | `SSO_BRIDGE_SECRET` ≠ `ANGRA_SSO_SECRET` ou origem fora de `SSO_BRIDGE_ALLOWED_ORIGINS` | Conferir `.env` nos dois projetos |
| `Unknown database 'laravel'` ao criar empresa | Falta `BT_DB_DATABASE` no `.env do Angra` | Definir apontando para o banco do BT |
| “Usuário não está ativo” | Conta criada com `status=DESATIVADO` | `UPDATE users/empresas SET status='ATIVADO'` (homolog) |
| Erro `NCA-*` ao concluir Conta Angra | Schema `users` diferente entre ambientes | Deploy do fix em `NovaContaAngraService` no Angra |
| E-mail não chega em homolog | `MAIL_*` incorreto no servidor | SMTP `webmail.angra.rj.gov.br` + `php artisan config:cache` |
| Admin PAM 500 em vagas/relatórios | Tabelas BT ausentes no banco compartilhado | Rodar `banco-talentos:homolog-setup` no Angra |
| 404 / assets quebrados | `public/` desatualizado ou vhost errado | Conferir deploy e `APP_URL` |

### Reativar conta travada (homolog)

```bash
php artisan tinker --execute="DB::table('users')->where('email','EMAIL')->update(['status'=>'ATIVADO']); DB::table('companies')->where('email','EMAIL')->update(['status'=>'ATIVADO']); echo 'done';"
```

---

## Convenções de código

- Views Blade + Bootstrap; **CSS e JS em arquivos separados** (`public/css`, `public/js`) — não usar inline.
- Textos visíveis com `{{ __('...') }}` quando aplicável.
- Regras de negócio em `app/Http/Services/TalentBank/`, não em controllers gordos.
- Novas migrations: sempre testar em cópia do banco homolog antes de produção.

---

## Mapa da documentação

| Documento | Conteúdo |
|-----------|----------|
| `docs/api-sso-conta-angra.md` | Contrato SSO e OAuth com Conta Angra |
| `docs/talent-bank/runbook-operacional.md` | Deploy, rollback, incidentes |
| `docs/talent-bank/checklist-migracao-homolog.md` | Migração legado em homolog |
| `docs/talent-bank/password-recovery.md` | Esqueci senha |
| `docs/talent-bank/observability.md` | Métricas e logs |
| `docs/talent-bank/api-compatibility-matrix.md` | API legado × novo |
| `docs/tests/qa-banco-de-talentos.md` | Checklist QA |
| `../homolog-deploy.md` | Deploy rápido homolog (workspace raiz) |

---

## Checklist antes de merge/deploy

1. `php artisan migrate` sem erro em ambiente de teste
2. Login formulário e SSO popup (se tocou em auth)
3. Cadastro candidato e empresa (se tocou em provisioning)
4. Área empresa / candidato com middleware de perfil completo
5. Variáveis `ANGRA_SSO_*` e bridge documentadas se mudaram
6. Sem credenciais reais commitadas no `.env`

---

*Última revisão: jun/2026 — manter este arquivo atualizado quando mudar fluxo de deploy, SSO ou schema compartilhado.*