# nCurso — Guia de instalação no alojamento Angoweb

**Plataforma:** nCurso — cursos PIDLCP para Administrações Municipais  
**Endereço:** https://ncurso.nsanda.ao  
**Tecnologia:** PHP 8.1+ e MySQL/MariaDB. Não precisa de Composer, Node.js nem SSH, por isso funciona num alojamento partilhado com cPanel.  
**Elaborado por:** NSANDA, LDA

---

## 0. Antes de começar

| Precisa de | Onde obter |
|---|---|
| Acesso à **Área de Cliente da Angoweb** | E-mail de activação do alojamento |
| Plano de alojamento com **cPanel**, **PHP 8.1 ou superior** e **MySQL** | Plano de alojamento web Angoweb |
| Domínio **nsanda.ao** com o DNS gerido na Angoweb | Se o DNS estiver noutro fornecedor, veja o passo 2.3 |
| Ficheiro **ncurso.zip** (este pacote) | Fornecido pela NSANDA |

> Os nomes dos menus podem variar ligeiramente consoante a versão do cPanel e o tema da Angoweb (português ou inglês). Neste guia, o nome em inglês aparece entre parênteses.

### Estrutura do pacote

```
ncurso/
├── app/           ← código interno (protegido)
├── config/        ← configuração, criada pelo instalador (protegida)
├── database/      ← scripts SQL (protegido)
├── storage/       ← cópias dos BI, privadas (protegido)
└── public/        ← ÚNICA pasta visível na Internet (raiz do subdomínio)
    ├── index.php, cursos.php, registo.php ...
    ├── admin/     ← área de administração
    ├── aluno/     ← área do aluno
    └── instalar.php
```

Por segurança, só a pasta **public/** fica acessível na Internet. As cópias do Bilhete de Identidade ficam em `storage/`, fora do alcance público.

---

## 1. Entrar no cPanel

1. Abra a **Área de Cliente da Angoweb** e inicie sessão.
2. Vá a **Serviços → Os meus serviços** e escolha o plano de alojamento de **nsanda.ao**.
3. Clique em **Entrar no cPanel** (Login to cPanel).

---

## 2. Criar o subdomínio ncurso.nsanda.ao

### 2.1 Criar o subdomínio

1. No cPanel, abra **Domínios** (Domains). Em versões antigas, o menu chama-se **Subdomínios** (Subdomains).
2. Clique em **Criar um novo domínio** (Create A New Domain).
3. Em **Domínio**, escreva `ncurso.nsanda.ao`.
4. **Desmarque** a opção *Compartilhar raiz do documento* (Share document root).
5. Em **Raiz do documento** (Document Root), escreva:
   ```
   ncurso/public
   ```
6. Clique em **Enviar** (Submit).

> **Importante:** a raiz tem de terminar em **/public**. Assim, as pastas `app`, `config`, `database` e `storage` ficam fora da Internet.

### 2.2 Se o cPanel não deixar escolher a raiz

Crie o subdomínio com a raiz `ncurso`, sem `/public`. O ficheiro `.htaccess` que está na raiz do pacote encaminha automaticamente os pedidos para `public/` e bloqueia as pastas internas.

### 2.3 Se o DNS de nsanda.ao não estiver na Angoweb

No painel do fornecedor do DNS, crie este registo:

| Tipo | Nome | Valor | TTL |
|---|---|---|---|
| A | `ncurso` | IP do servidor (consulte **Endereço IP partilhado** / Shared IP Address na coluna lateral do cPanel) | 3600 |

A propagação do DNS pode demorar entre alguns minutos e 24 horas.

---

## 3. Configurar o PHP

1. No cPanel, abra **Seleccionar versão do PHP** (Select PHP Version) ou **MultiPHP Manager**.
2. Escolha **PHP 8.2** ou **8.3** para `ncurso.nsanda.ao`. O mínimo é 8.1.
3. Em **Extensões** (Extensions), confirme que estão activas:
   `pdo_mysql`, `mysqli`, `fileinfo`, `mbstring`, `gd`, `iconv`, `openssl`.
4. Em **Opções** (Options) ou **MultiPHP INI Editor**, defina:

| Directiva | Valor |
|---|---|
| `upload_max_filesize` | `8M` |
| `post_max_size` | `10M` |
| `max_execution_time` | `60` |
| `display_errors` | `Off` |

> O pacote já inclui `public/.user.ini` com estes valores. O passo 4 só é necessário se o servidor os ignorar.

---

## 4. Criar a base de dados MySQL

1. No cPanel, abra **Assistente de bases de dados MySQL** (MySQL Database Wizard).
2. **Passo 1:** nome da base de dados: `ncurso`. O cPanel acrescenta um prefixo e fica, por exemplo, `nsandaao_ncurso`.
3. **Passo 2:** crie o utilizador `ncurso` (fica, por exemplo, `nsandaao_ncurso`) e gere uma **senha forte** com o gerador.
4. **Passo 3:** marque **TODOS OS PRIVILÉGIOS** (ALL PRIVILEGES) → **Fazer alterações**.
5. **Anote** estes três dados:
   - Nome da base de dados: `nsandaao_ncurso`
   - Utilizador: `nsandaao_ncurso`
   - Senha: a que foi gerada

O servidor da base de dados é normalmente **localhost**.

---

## 5. Carregar os ficheiros

1. No cPanel, abra **Gestor de ficheiros** (File Manager).
2. Vá à pasta inicial `/home/SEU_UTILIZADOR/`. É a pasta que contém `public_html`; não entre em `public_html`.
3. Clique em **Carregar** (Upload) e envie **ncurso.zip**.
4. Volte à pasta, clique com o botão direito em `ncurso.zip` e escolha **Extrair** (Extract).
5. Confirme que o resultado é:
   ```
   /home/SEU_UTILIZADOR/ncurso/public/index.php
   ```
   Se ficar `ncurso/ncurso/public`, mova o conteúdo um nível acima.
6. Apague o `ncurso.zip`.
7. Active **Mostrar ficheiros ocultos** (Settings → Show Hidden Files) e confirme que os ficheiros `.htaccess` existem.

### Permissões

| Caminho | Permissão |
|---|---|
| Pastas | `755` |
| Ficheiros | `644` |
| `ncurso/config/` | `755` (o instalador escreve aqui) |
| `ncurso/storage/` e subpastas | `755` |
| `ncurso/public/uploads/` e subpastas | `755` |

Para alterar uma permissão, clique com o botão direito → **Alterar permissões** (Change Permissions).

---

## 6. Activar o certificado SSL (HTTPS)

1. No cPanel, abra **Estado de SSL/TLS** (SSL/TLS Status).
2. Seleccione `ncurso.nsanda.ao` e `www.ncurso.nsanda.ao` e clique em **Executar AutoSSL** (Run AutoSSL).
3. Aguarde alguns minutos, até aparecer o cadeado verde.

> O `.htaccess` da pasta `public` redirecciona automaticamente HTTP para HTTPS. Se aparecer um erro de *demasiados redireccionamentos* antes de o SSL estar activo, comente temporariamente com `#` as 4 linhas `RewriteCond`/`RewriteRule` do bloco *Forçar HTTPS*.

---

## 7. Executar o instalador

1. No navegador, abra:
   **https://ncurso.nsanda.ao/instalar.php**
2. Confirme que todos os requisitos aparecem com **✔**.
3. Preencha:
   - **Servidor:** `localhost`
   - **Nome da base de dados / Utilizador / Senha:** os dados do passo 4
   - **Endereço do site:** `https://ncurso.nsanda.ao`
   - **Super Administrador:** nome, e-mail e senha (mínimo 8 caracteres)
   - **Dados de demonstração:** deixe marcado para começar com cursos de exemplo, que depois pode editar ou apagar.
4. Clique em **Instalar**.
5. **Obrigatório:** no Gestor de ficheiros, **apague** `ncurso/public/instalar.php`. O instalador fica bloqueado de qualquer forma, mas é melhor removê-lo.

---

## 8. Primeira configuração (no painel)

Entre em **https://ncurso.nsanda.ao/login.php** com o Super Administrador e siga esta ordem:

1. **Definições:** confirme o nome do site, os contactos e quem assina os certificados pela NSANDA.
2. **Entidades:** crie ou edite cada Administração Municipal. Carregue o logótipo ou a insígnia e indique o **responsável e o cargo**, que aparecem no certificado.
3. **Utilizadores:** crie um **Gestor** para cada entidade. O gestor só vê os cursos, inscrições e alunos da sua própria entidade.
4. **Cursos:** crie os cursos, indique o n.º do procedimento e a ligação do **Portal de Compras Públicas** (compraspublicas.minfin.gov.ao), e mude o estado para **Publicado**.
5. Divulgue o endereço **https://ncurso.nsanda.ao/cursos.php** aos formandos.

### Fluxo de trabalho

| Etapa | Quem | Onde |
|---|---|---|
| Registo com cópia do BI e inscrição | Aluno | Site público → *Inscrever-me* |
| Conferir o BI e aprovar as inscrições | Gestor | Admin → Inscrições → *Aprovar* |
| Imprimir a lista de inscritos e a folha de presenças | Gestor ou formador | Admin → Inscrições → *Lista de inscritos* / *Folha de presenças* |
| Exportar para Excel | Gestor | Admin → Inscrições → *Exportar Excel (CSV)* |
| Registar a frequência e a nota, e marcar como concluída | Formador ou gestor | Admin → Inscrições → editar / *Marcar concluídas* |
| Emitir os certificados | Gestor | Admin → Inscrições → *Emitir certificados* |
| Descarregar o certificado (PDF) | Aluno | Minha área → *Certificado* → *Imprimir / Guardar em PDF* |
| Verificar a autenticidade | Qualquer pessoa | https://ncurso.nsanda.ao/verificar.php (ou leitura do QR) |

---

## 9. Cópias de segurança

- **cPanel → Cópia de segurança** (Backup) ou **JetBackup**, se o plano incluir: faça cópias semanais.
- **Base de dados:** cPanel → **phpMyAdmin** → seleccione a base → **Exportar** → *Rápido* → SQL.
- **Ficheiros:** comprima e descarregue `ncurso/storage/` (contém as cópias dos BI) e `ncurso/public/uploads/`.

> As cópias dos BI são **dados pessoais** (Lei n.º 22/11). Guarde as cópias de segurança em local seguro e não as partilhe.

---

## 10. Resolução de problemas

| Sintoma | Causa provável | Solução |
|---|---|---|
| Erro 500 / página em branco | Versão do PHP antiga ou extensão em falta | Passo 3. Consulte `ncurso/storage/logs/php-error.log` e o *Registo de erros* (Errors) do cPanel |
| "Erro de ligação à base de dados" | Dados errados em `config/config.php` | Edite o ficheiro no Gestor de ficheiros (prefixo do cPanel incluído) |
| Envio do BI falha | Limite de upload | Passo 3: `upload_max_filesize = 8M` |
| "Sessão expirada" ao enviar um formulário | A página esteve aberta muito tempo | Actualize a página e repita |
| Demasiados redireccionamentos | HTTPS forçado sem SSL activo | Passo 6 |
| O subdomínio mostra a lista de ficheiros ou o código | A raiz do documento está errada | Passo 2: a raiz deve ser `ncurso/public` |
| Esqueceu a senha do Super Admin | — | Veja o procedimento abaixo |

**Recuperar a senha do Super Admin:** abra phpMyAdmin → separador **SQL** e execute o comando abaixo, substituindo o e-mail. A senha passa a ser temporariamente `Mudar#2026`; altere-a logo a seguir em *Alterar senha*.

```sql
UPDATE utilizadores
SET senha_hash = '$2y$10$/JMtqltdwdjxiZ04dABfIuekkmKvpyNzzGaNzqlD9dJF/DgrCk9mC', ativo = 1
WHERE email = 'nsanda.lda@gmail.com';
```

Para ver os erros em detalhe, temporariamente: em `config/config.php`, mude `'debug' => false` para `true`. **Volte a pôr `false`** quando terminar.

---

## 11. Actualizações futuras

1. Faça uma cópia de segurança (passo 9).
2. Carregue os novos ficheiros **sem substituir** `config/config.php`, `storage/` e `public/uploads/`.
3. Se a versão trouxer alterações à base de dados, execute em phpMyAdmin o script `database/actualizacao-X.sql` indicado.

---

**Suporte:** NSANDA, LDA · 924 588 326 · nsanda.lda@gmail.com · nsanda.ao