# COCKPIT · instalação em cPanel

Plataforma de gestão dos estágios remotos do Nexaris Ecosystem: tarefas, horários e horas, check-ins, reuniões, perfis com análise de CV por IA. Interface em português, espanhol e inglês.

Versão 1.0.0 · PHP 8.1+ · MySQL 5.7+ ou MariaDB 10.3+

---

## Conteúdo do pacote

```
public/            → pasta pública do subdomínio (a única visível na Internet)
  index.html       → a aplicação
  .htaccess        → HTTPS, encaminhamento da API, cabeçalhos de segurança
  api/index.php    → ponto de entrada da API
app/               → lógica do servidor e dados privados (fora da pasta pública)
  cockpit.php      → API (autenticação, dados, ficheiros, IA)
  config.sample.php→ modelo de configuração
  storage/files    → CVs e logótipos carregados
  storage/sessions → sessões de utilizador
install/schema.sql → estrutura da base de dados
```

## Onde ficam os dados

Tudo fica no vosso servidor, sem depender do Google Drive nem de outros serviços:

| Informação | Onde fica |
|---|---|
| Pessoas, horários, tarefas, horas, check-ins, reuniões, perfis | Base de dados MySQL |
| CVs (PDF) e logótipos | `app/storage/files`, fora da pasta pública |
| Contas e palavras-passe (cifradas) | Base de dados MySQL |

Os CVs só podem ser abertos por tutores e administradores com sessão iniciada. O único serviço externo é a API da Anthropic, chamada pelo servidor apenas quando um tutor pede a análise de um CV.

---

## Instalação passo a passo

### 1. Criar o subdomínio
cPanel → **Domínios** → **Criar um novo domínio**
- Domínio: `cockpit.nexaris.pt`
- Desmarque "Compartilhar raiz do documento" e defina a raiz como `cockpit.nexaris.pt/public`

### 2. Carregar os ficheiros
cPanel → **Gestor de ficheiros** → pasta `/home/UTILIZADOR/cockpit.nexaris.pt/`
- Carregue o `cockpit.zip` e use **Extrair**
- Deve ficar com `cockpit.nexaris.pt/public`, `cockpit.nexaris.pt/app` e `cockpit.nexaris.pt/install`

### 3. Configurar o PHP
- **MultiPHP Manager**: escolha PHP 8.1 ou superior para o subdomínio
- **Selecionar versão do PHP** → extensões: confirme `pdo_mysql`, `curl`, `fileinfo`, `mbstring`
- **MultiPHP INI Editor** (para o subdomínio):
  - `upload_max_filesize = 16M`
  - `post_max_size = 20M`
  - `max_execution_time = 180` (a análise de um CV pode demorar até um minuto)

### 4. Criar a base de dados
cPanel → **Bases de dados MySQL**
1. Crie a base de dados `cockpit` (fica `UTILIZADOR_cockpit`)
2. Crie um utilizador com palavra-passe forte
3. Adicione o utilizador à base de dados com **Todos os privilégios**

cPanel → **phpMyAdmin** → selecione a base de dados → **Importar** → `install/schema.sql`

### 5. Configurar a aplicação
No Gestor de ficheiros, em `app/`:
1. Copie `config.sample.php` para `config.php`
2. Edite `config.php`:
   - `db_dsn`, `db_user`, `db_pass` com os dados do passo 4
   - `admin_emails`: os emails que entram como administradores
   - `anthropic_api_key`: a chave da API da Anthropic (ver passo 9). Sem chave, a análise de CVs fica desativada e o resto funciona normalmente.

### 6. Ativar o HTTPS
cPanel → **Status SSL/TLS** → selecione `cockpit.nexaris.pt` → **Executar AutoSSL**

### 7. Verificar a instalação
Abra `https://cockpit.nexaris.pt/api/health`. Todos os itens devem estar a `true`, exceto `ai_key` se ainda não configurou a IA.

| Item a `false` | O que fazer |
|---|---|
| `config` | Falta o `app/config.php` |
| `database` | Verifique os dados de acesso e se importou o `schema.sql` |
| `files_writable` / `sessions_writable` | Permissões 755 nas pastas `app/storage/files` e `app/storage/sessions` |
| `ext_…` | Ative a extensão em "Selecionar versão do PHP" |

### 8. Primeiro acesso
1. Abra `https://cockpit.nexaris.pt` → **Criar conta** com um dos emails de `admin_emails`
2. Em **Equipa → Adicionar pessoa**, registe-se a si como tutor (com o mesmo email) e adicione tutores e trainees, com email e horário semanal
3. Para dar acesso a cada pessoa, há duas formas:
   - **Gerar acesso** na ficha da pessoa: cria uma palavra-passe temporária para enviar por um canal seguro. Ao entrar, a pessoa define a sua.
   - A pessoa cria a conta sozinha em **Criar conta**, com o email que registou na Equipa.

A conta fica associada automaticamente ao perfil com o mesmo email. Os tutores registados na Equipa entram com permissões de tutor; os trainees, com permissões de trainee.

### 9. Ativar a análise de CVs por IA
1. Em `console.anthropic.com`, crie uma chave em **API Keys** e defina um limite de gasto mensal
2. Coloque a chave em `anthropic_api_key` no `config.php`
3. Confirme no Console o identificador do modelo e ajuste `anthropic_model` se necessário

---

## Permissões

| Ação | Administrador / Tutor | Trainee |
|---|---|---|
| Ver painel, tarefas, reuniões, perfis | ✓ | ✓ |
| Registar horas e check-ins próprios | ✓ | ✓ |
| Validar horas | ✓ | — |
| Criar tarefas, mudar o estado das suas | ✓ | ✓ |
| Apagar tarefas, gerir equipa, grupos, projetos, reuniões | ✓ | — |
| Adicionar funções e competências ao próprio perfil | ✓ | ✓ |
| Carregar e analisar CVs, abrir CVs | ✓ | — |

As permissões são aplicadas pelo servidor, não apenas pela interface.

## Segurança
- `app/` e `config.php` ficam fora da pasta pública e têm também um `.htaccess` de bloqueio
- Palavras-passe guardadas com hash; limite de 10 tentativas de entrada por 15 minutos
- Sessão em cookie `HttpOnly`, `Secure`, `SameSite=Lax`, e cabeçalho próprio obrigatório em todas as alterações
- A IA só é acessível a tutores, com limite de 40 análises por hora por pessoa

## Cópias de segurança
Inclua nas cópias do cPanel a base de dados e a pasta `app/storage/files`.

## Atualizar
Substitua apenas `public/index.html` e `app/cockpit.php`. Mantenha `app/config.php` e `app/storage/`.

## Problemas comuns
- **Erro 500 em todas as páginas**: confirme a versão do PHP e veja o `error_log` na pasta do subdomínio
- **A API devolve 404**: confirme que a raiz do subdomínio aponta para `public/` e que o `.htaccess` foi extraído (ficheiros ocultos visíveis no Gestor de ficheiros)
- **Upload de CV falha**: aumente `upload_max_filesize` e `post_max_size`
- **A análise de CV termina sem resultado**: aumente `max_execution_time` e verifique o limite de gasto no Console da Anthropic