# Sistema de Ficha de Admissão de Funcionário

## Decisão técnica
Foi adotada uma arquitetura **MVC em PHP 8 + MySQL + Bootstrap 5**. Eu não gerei um Laravel "capado" para fingir organização; optei por um pacote MVC real, menor, legível e fácil de subir em qualquer hospedagem PHP tradicional.

## O que o projeto entrega
- formulário público responsivo
- validação front-end leve e validação back-end
- upload seguro com nome único e restrição de tipo/tamanho
- painel administrativo com login, busca, filtro, edição e status
- página de detalhe completa
- versão de impressão HTML
- exportação PDF com Dompdf quando o `composer install` for executado
- modelagem relacional com tabelas para ficha, dependentes, dados acadêmicos e anexos

## Estrutura de pastas
```text
ficha-admissao-mvc/
├── app/
│   ├── Controllers/
│   ├── Models/
│   └── Views/
├── bootstrap/
├── config/
├── core/
├── database/
├── public/
│   └── assets/
├── routes/
└── storage/
```

## Onde salvar cada arquivo
Todos os arquivos já estão organizados nas pastas corretas dentro do projeto. O servidor web deve apontar para a pasta `public/`.

## Instalação
1. copie `.env.example` para `.env`
2. ajuste as credenciais do MySQL no `.env`
3. crie o banco e rode o arquivo `database/schema.sql`
4. na raiz do projeto, rode:
   ```bash
   composer install
   ```
5. aponte o Apache/Nginx para a pasta `public/`
6. acesse a URL configurada em `APP_URL`

## Login inicial do painel
- **URL:** `/admin/login`
- **E-mail:** `admin@empresa.com`
- **Senha:** `TroqueEssaSenha123!`

Troque essa senha assim que subir. Segurança agradece, o RH também.

## Principais arquivos
- `public/index.php` → front controller e registro de rotas
- `app/Controllers/AdmissionController.php` → formulário público e gravação
- `app/Controllers/AdminAdmissionController.php` → painel RH, edição, impressão e PDF
- `app/Models/Admission.php` → entidade principal da ficha
- `app/Views/admissions/partials/form.php` → formulário completo reutilizado no público e no admin
- `database/schema.sql` → estrutura completa do banco
- `public/assets/css/app.css` → estilo principal
- `public/assets/js/app.js` → máscaras, campos condicionais, dependentes dinâmicos e DataTable

## Melhorias futuras sugeridas
- autenticação com perfis e permissões
- trilha de auditoria por alteração de status
- assinatura eletrônica do colaborador
- fila de e-mails para alertar RH/contabilidade
- antifraude de upload com antivírus/clamav
- dashboard com métricas de admissões
- API REST para integração com ERP/folha
- adequação LGPD com política de retenção e anonimização


## Testes e homologação

O projeto agora inclui um pacote de validação antes do deploy.

### 1. Pré-flight do ambiente
```bash
php scripts/preflight.php --http
```
Valida PHP, extensões, `.env`, conexão com banco, tabelas, escrita em `storage/uploads`, Dompdf e as rotas principais configuradas em `APP_URL`.

### 2. Massa fake de homologação
```bash
php scripts/seed_homologation.php --force
```
Cria admins de teste, fichas fake com cenários variados, dependentes, estágio e anexos mínimos.

### 3. Smoke test automatizado
```bash
php scripts/run_smoke.php
```
Fluxos validados automaticamente:
- login admin
- listagem de admissões
- formulário público
- validação de formulário inválido
- alteração de status
- listagem de admins

Teste com escrita também:
```bash
php scripts/run_smoke.php --with-write-tests
```

### 4. Limpeza da massa fake
```bash
php scripts/cleanup_homologation.php --force
```

### 5. Diagnóstico visual no painel
No admin existe a tela:
```text
/admin/diagnostico
```
Ela mostra um checklist vivo de ambiente, banco, uploads, autoload, rotas principais e admins ativos.

### Credenciais de homologação
- `admin@empresa.com` / `TroqueEssaSenha123!`
- `homologacao@empresa.com` / `Homologacao123!`


### Atalhos Windows / XAMPP
Dentro de `scripts/windows/` você pode rodar:
- `run-preflight.bat`
- `seed-homologation.bat`
- `run-smoke.bat`
- `test-all.bat`

### Execução completa em um comando
```bash
php scripts/test_all.php
```
Ou via Composer:
```bash
composer test:all
```


## Tipos de usuário

Após atualizar o projeto em uma base já existente, rode:

```bash
php scripts/patch_admin_roles.php --force
```

Perfis disponíveis:

- `admin` — acesso total, incluindo Diagnóstico e Usuários do painel
- `operador` — acesso às admissões e operações do RH, sem acesso a Diagnóstico e Usuários do painel


## Patch adicional dos campos internos do admin

Para bases já existentes, rode um dos scripts abaixo após atualizar os arquivos:

```bash
php scripts/patch_admission_internal_fields.php --force
# ou, se quiser apenas os novos campos de escala/horário
php scripts/patch_work_schedule_fields.php --force

Observações rápidas:
- a busca instantânea do admin continua funcionando no front e agora também é respeitada quando o filtro é reaplicado no backend;
- o patch isolado de escala/horário foi ajustado para não quebrar em bases antigas sem a coluna workload_hours.
```
