# Lote — Cargos, BI por cargo, áudio no portal e navegação do questionário (2026-05-29)

Documento para **commit / deploy** da working tree atual. Resume o trabalho feito nesta sessão (Cursor) e o lote já presente no repositório (Claude Code / sessões anteriores).

**Estado:** pendente commit em `main` (ver `git status`).

**Fonte da verdade:** `git diff HEAD`, `git status`.

---

## 1. Resumo do produto

| Área | O que entrou |
|------|----------------|
| **Cargos (`job_titles`)** | CRUD administrativo, vínculo em `trainee_profiles.job_title_id`, migração de metadata legado (`cargo` / `job_title`) |
| **Usuários** | Campo cargo no create/edit, filtro por cargo na listagem, import em lote grava `job_title_id` |
| **Onboarding Microsoft** | Tela de conclusão pede **cargo** (select) + área + grupo |
| **Dashboard BI** | Filtro **Cargo** nos relatórios; ranking pode expor cargo; queries respeitam `job_title_id` |
| **Portal — hub questionário** | Música ambiente (`VentureOficial.mp3`) + botão mutar; hint “Clima de jogo suave”; links na **mesma aba** |
| **Portal — fluxo continuar** | Questionário em progresso → splash (`/experiencia/`) em vez de ir direto para `/jogar` |
| **Experiência game — splash** | Botão mutar no canto superior direito + trilha (MP3 ou fallback sintético) |
| **Experiência game — jogar** | Mute + slider de volume no HUD (ao lado de Pausar); trilha `VentureOficial.mp3` durante as perguntas |

---

## 2. Navegação do questionário (Cursor — sessão 2026-05-29)

### Comportamento

| Situação | Antes | Depois |
|----------|--------|--------|
| Clicar **Continuar** (hub `/portal/questionario`) | Abria `/experiencia/jogar` (nova aba) | Abre `/portal/questionario/experiencia/` (splash), mesma aba |
| Clicar **Abrir** / **Ver resultado** | Nova aba (`target="_blank"`) | Mesma aba |
| Rota legada `GET /portal/questionario/responder` (`take`) | Redirect para `experience.play` | Redirect para `experience` (splash) |

### Ficheiros

| Ficheiro | Alteração |
|----------|-----------|
| `resources/views/portal/questionnaire/welcome.blade.php` | `Continuar` → `route('portal.questionnaire.experience')`; removido `target="_blank"` |
| `app/Http/Controllers/Portal/PortalQuestionnaireController.php` | `take()` redireciona para splash |
| `tests/Feature/Portal/PortalQuestionnaireTest.php` | Assert do redirect atualizado |

### Tentativas revertidas nesta sessão (não subir como “feature final”)

Durante a sessão foram testados e **desfeitos** (ou substituídos pelo Claude Code):

- Barra de volume com layout quebrado (CSS Grid / `display: contents` no form Sair)
- Sons de acerto (`acerto-1.mp3`) e erro (`fail.mp3`) no modal de resposta
- Trilha `medieval-fantasy.mp3` só no script do Cursor (versão atual usa `VentureOficial.mp3` no HUD)

---

## 3. Módulo Cargos — `job_titles` (Claude Code)

### Modelo de dados

**Migration:** `database/migrations/2026_05_28_090600_create_job_titles_and_link_profiles.php`

- Tabela `job_titles`: `company_id`, `name`, unique `(company_id, name)`
- Coluna `trainee_profiles.job_title_id` (nullable, FK `nullOnDelete`)
- Seed a partir de `trainee_profiles.metadata` (`cargo` ou `job_title`)

### Pipeline Laravel (padrão do projeto)

```
JobTitleController → JobTitleService → JobTitleRepository → JobTitle
```

| Artefacto | Caminho |
|-----------|---------|
| Model | `app/Models/JobTitle.php` |
| Policy | `app/Policies/JobTitlePolicy.php` |
| Service | `app/Services/JobTitleService.php` |
| Repository | `app/Repositories/Eloquent/JobTitleRepository.php` |
| Interface | `app/Repositories/Contracts/JobTitleRepositoryInterface.php` |
| Requests | `StoreJobTitleRequest`, `UpdateJobTitleRequest`, `DestroyJobTitleRequest` |
| Views | `resources/views/users/job-titles/*` |
| Testes | `tests/Feature/Users/JobTitleManagementTest.php` |

### Rotas (`users.job-titles.*`)

```php
Route::resource('users/job-titles', JobTitleController::class)
    ->parameters(['job-titles' => 'job_title'])
    ->names('users.job-titles');
```

Menu: **Usuários → Cargos** (`layouts/sidebar.blade.php`, `@can('viewAny', JobTitle::class)`).

### Integrações

| Módulo | Ficheiros principais |
|--------|----------------------|
| **UserService / UserRepository** | Cargo no create/update; filtro `job_title_id` na listagem |
| **UserBulkImportService** | Resolve/cria cargo e persiste `job_title_id` + metadata |
| **Formulários usuário** | `users/_form.blade.php`, `_filters.blade.php`, create/edit |
| **Microsoft onboarding** | `microsoft-portal-complete.blade.php`, `StoreMicrosoftPortalOnboardingRequest`, `MicrosoftPortalOnboardingService` |
| **TraineeProfile** | Relação `jobTitle()` |
| **Providers** | Binding `JobTitleRepositoryInterface` em `AppServiceProvider`; policy em `AuthServiceProvider` |

---

## 4. Dashboard BI — filtro e ranking por cargo (Claude Code)

| Ficheiro | Alteração |
|----------|-----------|
| `app/Http/Requests/Dashboard/DashboardRequest.php` | Valida `job_title_id` |
| `app/Http/Controllers/DashboardController.php` | Injeta `JobTitleService`; passa `jobTitles` às views |
| `app/Services/TrainingDashboardService.php` | Repasse de filtros |
| `app/Repositories/Eloquent/TrainingDashboardRepository.php` | Filtro `job_title_id` em rankings/consultas; join `job_titles` para nome |
| `resources/views/dashboard/_filters.blade.php` | Select **Cargo** |
| `resources/views/dashboard/_question-rankings.blade.php` | Ajustes de colunas/contexto |
| `resources/views/dashboard/_wrong-alternatives.blade.php` | Idem |
| `resources/views/dashboard/ranking.blade.php` | Suporte a cargo no ranking |
| `resources/views/components/portal/battery-ranking.blade.php` | Prop `showJobTitle` + exibição |
| `tests/Feature/Dashboard/TrainingDashboardTest.php` | Testes de filtro por cargo e ranking |

---

## 5. Áudio no portal / experiência game (Claude Code + Cursor)

### Assets de som (`public/sons/`)

| Ficheiro | Uso |
|----------|-----|
| `VentureOficial.mp3` | Trilha principal (hub, splash, jogar) |
| `medieval-fantasy.mp3` | Presente no repo; **não** usado na versão atual do jogar após revert |
| `acerto-1.mp3`, `fail.mp3`, `mixkit-small-group-cheer-and-applause-518.wav` | Disponíveis; **não** ligados ao fluxo de resposta no commit atual |
| Outros (`abertura.mp3`, etc.) | Já usados noutros ecrãs / legado |

Atualizar `public/sons/README.txt` se necessário após deploy.

### Hub do questionário (`welcome.blade.php`)

- Botão **mutar** (`.qhub-audio-toggle`)
- Script: tenta `VentureOficial.mp3`; fallback sintético via `AudioContext`
- CSS: `resources/css/portal-questionnaire-hub.css` (estilos do toggle)

### Splash (`experience-splash.blade.php`)

- Botão mutar fixo (`.qg-root > .qg-audio-toggle`)
- Script inline (mesmo padrão de trilha + fallback)

### Jogar (`experience-play.blade.php`)

- Bloco `.qg-audio-ctrl` no HUD: **mute** + **slider** (`#qg-volume-slider`, default 90%)
- Segundo `<script>`: `VentureOficial.mp3` em loop; mute e volume; fallback sintético
- CSS: `resources/css/questionnaire-game.css` (secção final: `.qg-audio-toggle`, `.qg-audio-ctrl`, `.qg-volume-slider`)

**Nota de layout:** o form **Sair** deve permanecer inline no flex do HUD. Se o botão **Sair** aparecer abaixo de **Pausar**, falta CSS `display: inline-flex` no form (Tailwind `class="inline"` **não** existe neste layout — só carrega `questionnaire-game.css`).

---

## 6. Outros ficheiros modificados (working tree)

| Ficheiro | Nota |
|----------|------|
| `.cursor/rules/sistema-diego.mdc` | Regras do agente — **opcional** no commit de produto |
| `public/sons/README.txt` | Documentação de sons |

---

## 7. Ficheiros untracked — o que incluir no commit

### Incluir (funcionalidade)

- Todo o módulo `JobTitle*` (controllers, models, policies, views, migration, testes)
- `database/migrations/2026_05_28_090600_create_job_titles_and_link_profiles.php`
- `public/sons/VentureOficial.mp3` (e outros MP3 referenciados no código)
- Alterações listadas nas secções 2–5

### Avaliar antes de commitar

| Ficheiro/pasta | Motivo |
|----------------|--------|
| `plataforma-treinamento-hypera.pptx` | Apresentação local — normalmente **fora** do repo |
| `.agents/`, `skills-lock.json`, `.claude/` | Config local de agentes |
| MP3/WAV extras não referenciados no código | Tamanho do repo |

---

## 8. Deploy / checklist

```bash
# 1. Dependências PHP (se necessário)
composer install --no-dev --optimize-autoloader

# 2. Migration (obrigatório para cargos)
php artisan migrate

# 3. Front-end (obrigatório — CSS/JS versionados em public/build)
npm ci
npm run build

# 4. Testes recomendados antes do push
php artisan test --filter=JobTitleManagement
php artisan test --filter=PortalQuestionnaire
php artisan test --filter=TrainingDashboard
php artisan test --filter=MicrosoftOAuthPortalLogin
```

### Pós-deploy manual

1. **Hard refresh** no browser (`Cmd+Shift+R`) — evita CSS antigo em cache.
2. Confirmar que `public/sons/VentureOficial.mp3` existe no servidor.
3. Validar fluxos:
   - Admin: **Usuários → Cargos** (CRUD)
   - Admin: criar/editar usuário com cargo
   - Dashboard: filtro **Cargo** altera ranking/relatórios
   - Portal: hub → **Continuar** → splash → **Iniciar/Continuar** → jogar
   - Portal: mute/volume no hub, splash e HUD do jogar
   - Microsoft: conclusão de cadastro com select de cargo

---

## 9. Inventário rápido (`git diff HEAD --stat`)

42 ficheiros tracked alterados (~1370 linhas); módulo JobTitle + migration + testes como **untracked** adicionais.

Principais pastas:

- `app/` — cargos, dashboard, portal, users, onboarding Microsoft
- `resources/views/portal/questionnaire/` — welcome, splash, play
- `resources/css/` — `portal-questionnaire-hub.css`, `questionnaire-game.css`
- `tests/Feature/` — Dashboard, Portal, Auth Microsoft, Users

---

## 10. Sugestão de mensagem de commit

```
feat: cargos no perfil participante, BI por cargo e áudio/navegação no portal questionário

- CRUD job_titles, migration trainee_profiles.job_title_id e integração em usuários/import/onboarding MS
- Filtro de cargo no dashboard BI e ranking
- Hub/splash/jogar com trilha VentureOficial, mute e volume no HUD
- Continuar questionário passa pela splash; links na mesma aba
```

Para commits separados (revisão mais fácil):

1. `feat: módulo job titles e integração usuários/dashboard/onboarding`
2. `feat(portal): áudio e navegação splash no questionário experiência`

---

## 11. Referências internas

- [registro-entregas.md](./registro-entregas.md) — índice histórico
- [portal-questionario-ui-game.md](./portal-questionario-ui-game.md) — UI da experiência game
- [deploy-producao-questionario-experiencia.md](./deploy-producao-questionario-experiencia.md) — deploy da experiência