# Processo obrigatório de desenvolvimento e deploy

Estas regras aplicam-se a qualquer pessoa ou agente que altere este projeto, independentemente do modelo ou ferramenta utilizada.

## Issue antes da alteração

Toda a correção, melhoria ou nova função começa numa Issue do GitHub. A Issue deve descrever o problema ou objetivo, critérios de aceitação, riscos conhecidos e forma de validação.

Não agrupar trabalho sem relação na mesma Issue. Incidentes urgentes continuam a exigir Issue, ainda que seja criada imediatamente antes da correção.

## Branch, commits e Pull Request

1. Criar uma branch a partir da `main` atualizada, usando `fix/<issue>-...`, `feature/<issue>-...` ou `chore/<issue>-...`.
2. Usar Conventional Commits, validados por Commitlint.
3. Abrir um Pull Request para `main`; nunca publicar diretamente a partir de uma branch de trabalho.
4. Mencionar a Issue na descrição do PR com `Closes #<número>` e incluir resumo, testes executados, riscos e plano de reversão.
5. Só fazer merge depois de todos os jobs obrigatórios do GitHub Actions passarem.

## Deploy controlado pelo PR

O deploy é feito apenas a partir do commit integrado na `main`. Antes de publicar, confirmar o destino exato e preservar `.env`, bases de dados, uploads e restantes dados persistentes do servidor.

### Estrutura duplicada no alojamento atual

O alojamento de `pos.pt/clientes/magilarmes2` mantém entry points mínimos na raiz e as implementações dentro de `public/`. Os caminhos de origem e destino devem ser preservados exatamente:

- `sage.php` da raiz publica para `sage.php` da raiz;
- `public/sage.php` publica apenas para `public/sage.php`;
- `sage-invoice.php` da raiz publica para `sage-invoice.php` da raiz;
- `public/sage-invoice.php` publica apenas para `public/sage-invoice.php`;
- `styles.css` da raiz continua a ser o import mínimo de `public/styles.css`.

Nunca copiar uma implementação de `public/` por cima do wrapper correspondente na raiz. Depois do upload, comparar os hashes remotos de ambos os caminhos com os respetivos ficheiros locais e confirmar que um pedido sem sessão a `sage.php` redireciona, sem devolver HTTP 500.

Depois do deploy:

- validar o health check, login administrativo e Portal do Cliente;
- validar também `sage.php` e `sage-invoice.php`, incluindo os wrappers da raiz;
- confirmar que o commit publicado corresponde ao merge do PR;
- registar no próprio PR o ambiente, data, resultado e verificações efetuadas;
- em caso de falha, reverter para o último commit publicado com sucesso e documentar o incidente na Issue.

Credenciais, tokens, DSN e ficheiros `.env` nunca podem ser incluídos em commits, Issues, PRs, logs ou artefactos de CI.