GVFF GRC Platform - Manual Técnico

1. Arquitectura do Sistema

A plataforma GVFF GRC segue uma arquitectura cliente-servidor monolítica, com separação clara entre frontend (SPA) e backend (API REST).

Componentes Principais

Frontend (SPA): Aplicação de página única em HTML/CSS/JavaScript vanilla, servida como ficheiros estáticos
Backend (API): Servidor Express.js que expõe endpoints REST protegidos por JWT
Base de Dados: MySQL com estrutura relacional e alguns campos longos para JSON serializado
Middleware: Camada de autenticação, autorização, menu access e filtragem por país
Uploads: PDFs armazenados em uploads/ e servidos por rota dedicada

2. Stack Tecnológico

Componente	Tecnologia	Versão	Propósito
Runtime	Node.js	20.x	Ambiente de execução servidor
Framework	Express.js	4.x	Framework web e API REST
Base de Dados	MySQL	8.x / compatível	Armazenamento persistente de dados
Driver DB	mysql2/promise	3.x	Conexão à base de dados
Autenticação	jsonwebtoken (JWT)	9.x	Tokens de sessão seguros
Hashing	bcryptjs	2.x	Hashing de passwords
Uploads	multer	1.x	Upload de PDFs
Config	dotenv	17.x	Variáveis de ambiente
Frontend	Vanilla JS/HTML/CSS	-	Interface de utilizador (SPA)

Estrutura de Directórios

gvff-grc-platform/
├── index.js                 # Ponto de entrada principal do servidor
├── config/
│   └── db.js                # Configuração da pool MySQL
├── middleware/
│   ├── auth.js              # Middleware de autenticação JWT
│   ├── rbac.js              # Roles e permissões CRUD
│   ├── menuAccess.js        # Controlo de acesso a módulos/menus
│   ├── countryFilter.js     # Filtragem por país
│   └── passwordValidator.js # Política de passwords
├── models/
│   ├── User.js
│   ├── Entity.js
│   ├── Supplier.js
│   ├── Asset.js
│   ├── Risk.js
│   ├── Document.js
│   ├── AuditLog.js
│   ├── Iso27001Scope.js
│   ├── Nis2Scope.js
│   └── ComplianceScopeFactory.js
├── routes/
│   ├── auth.js
│   ├── users.js
│   ├── entities.js
│   ├── countries.js
│   ├── suppliers.js
│   ├── assets.js
│   ├── risks.js
│   ├── documents.js
│   ├── iso27001.js
│   ├── nis2.js
│   ├── complianceFactory.js
│   ├── framework.js
│   ├── reports.js
│   ├── audit.js
│   ├── platformModules.js
│   └── menuPermissions.js
├── seeds/
│   └── frameworkSeed.js
├── uploads/                 # PDFs carregados pelos utilizadores
└── public/
    ├── index.html
    ├── app.js
    ├── styles.css
    ├── manual-utilizador.html
    ├── manual-tecnico.html
    └── manual-exportacao.html

3. Base de Dados

A plataforma utiliza MySQL como sistema de gestão de base de dados relacional. A conexão é feita com mysql2/promise através de variáveis separadas de ambiente.

3.1 Variáveis de ligação

DB_HOST=localhost
DB_PORT=3306
DB_NAME=gvffpt_grc_gvff
DB_USER=gvffpt_grcgvffusr
DB_PASSWORD=********
JWT_SECRET=********
PORT=5000

3.2 Tabelas Principais

users

Armazena os utilizadores do sistema com credenciais e roles.

Coluna	Tipo	Descrição
id	INT AUTO_INCREMENT PK	Identificador único
email	VARCHAR	Email do utilizador
password_hash	VARCHAR	Hash bcrypt da password
name	VARCHAR	Nome do utilizador
role	VARCHAR	platform_owner, super_admin, admin, revisor, user
status	VARCHAR	active / inactive
phone_number	VARCHAR	Telefone
mfa_enabled	TINYINT(1)	MFA ativo

countries

Países com informação de transposição NIS2 e maturidade.

Coluna	Tipo	Descrição
id	INT AUTO_INCREMENT PK	Identificador
name, code	VARCHAR	Nome e código do país
region	VARCHAR	Região (EU/UE ou outra)
is_eu	TINYINT(1)	Indicador de UE
transposition_status	VARCHAR	Estado de transposição
implementation_phase	VARCHAR	Fase de implementação
nis2_compatible	VARCHAR	Compatibilidade fora da UE
maturity_score	INT	Pontuação de maturidade

entities

Entidades com classificação, contactos e scope operacional.

Coluna	Tipo	Descrição
id	INT AUTO_INCREMENT PK	Identificador
name	VARCHAR	Nome da entidade
type	VARCHAR	Tipo
sector, subsector	VARCHAR	Sector e subsetor
nis2_classification	VARCHAR	Classificação NIS2
country_id	INT	País associado
scope	VARCHAR	`cp` ou `local`
ip_addresses, fqdns	LONGTEXT	Dados técnicos em texto

suppliers

Fornecedores com criticidade, risco e requisitos de segurança.

Coluna	Tipo	Descrição
id	INT AUTO_INCREMENT PK	Identificador
cod	VARCHAR	Código auto-gerado (SUP-###)
supplier_name	VARCHAR	Nome do fornecedor
supplier_type	VARCHAR	Tipo
criticality	VARCHAR	Critical / High / Medium / Low
risk_classification	VARCHAR	Classificação de risco
security_requirements	LONGTEXT	JSON serializado
country_id	INT	País

assets

Ativos com informação técnica e de segurança.

Coluna	Tipo	Descrição
id	INT AUTO_INCREMENT PK	Identificador
cod	VARCHAR	Código auto-gerado (AST-###)
name	VARCHAR	Nome do ativo
asset_type	VARCHAR	Tipo de ativo
scope	VARCHAR	`governance` ou `local`
entity_id, country_id	INT	Associações
ip_address, mac_address, software_version	VARCHAR	Detalhes técnicos
mfa_enabled, encryption_*	TINYINT(1)	Controlos de segurança

risks

Registo de riscos com avaliação inerente e residual.

Coluna	Tipo	Descrição
id	INT AUTO_INCREMENT PK	Identificador
entity_id	INT	Entidade associada
title	VARCHAR	Título do risco
likelihood, impact	INT	Probabilidade e impacto (1-5)
risk_level, risk_score	VARCHAR / INT	Nível e pontuação do risco
residual_likelihood, residual_impact	INT	Risco residual
residual_risk_level, residual_risk_score	VARCHAR / INT	Nível e pontuação residual

documents

Documentos com versionamento, refs e upload de PDF.

Coluna	Tipo	Descrição
id	INT AUTO_INCREMENT PK	Identificador
code	VARCHAR	Código auto-gerado (DOC-###)
title	VARCHAR	Título do documento
doc_type	VARCHAR	Tipo
revision	VARCHAR	Revisão
status	VARCHAR	draft / review / approved / obsolete
framework_refs, doc_refs	LONGTEXT	JSON serializado
file_path, file_name	VARCHAR	Ficheiro PDF anexo

3.3 Tabelas de Conformidade

O sistema utiliza o padrão scope/items para cada framework.

Framework	Tabela de Scopes	Tabela de Items
ISO 27001	iso27001_scopes	iso27001_items
NIS2	nis2_scopes	nis2_items
ISO 27002	iso27002_scopes	iso27002_items
ENS	ens_scopes	ens_items
GDPR	gdpr_scopes	gdpr_items

3.4 Tabelas de Sistema

Tabela	Propósito
platform_modules	Módulos ativáveis da plataforma
role_menu_permissions	Permissões de menu por role
audit_logs	Registo de auditoria
framework_items	Biblioteca de referência oficial
user_countries	Associação utilizadores-países

4. API REST

Todos os endpoints, exceto autenticação, requerem o header Authorization: Bearer <token>.

4.1 Autenticação

Método	Endpoint	Descrição
POST	`/api/auth/login`	Login (retorna token JWT)
POST	`/api/auth/register`	Registo de novo utilizador
GET	`/api/auth/me`	Utilizador autenticado atual

4.2 CRUD Endpoints

Recurso	Base URL	Operações	Módulo
Utilizadores	`/api/users`	GET, POST, PUT, DELETE	users
Entidades	`/api/entities`	GET, POST, PUT, DELETE	entities
Países	`/api/countries`	GET, POST, PUT, DELETE	countries
Fornecedores	`/api/suppliers`	GET, POST, PUT, DELETE	suppliers
Ativos	`/api/assets`	GET, POST, PUT, DELETE	assets
Riscos	`/api/risks`	GET, POST, PUT, DELETE	risks
Documentos	`/api/documents`	GET, POST, PUT, DELETE	documents

4.3 Conformidade

Framework	Base URL	Módulo
ISO 27001	`/api/iso27001`	compliance_iso27001
NIS2	`/api/nis2`	compliance_nis2
ISO 27002	`/api/iso27002`	compliance_iso27002
ENS	`/api/ens`	compliance_ens
GDPR	`/api/gdpr`	compliance_gdpr

4.4 Sistema

Endpoint	Descrição
`/api/dashboard`	Dados do dashboard principal
`/api/reports/governance`	Relatório Governance
`/api/reports/country`	Relatório por país
`/api/audit`	Log de auditoria
`/api/platform-modules`	Gestão de módulos
`/api/menu-permissions`	Permissões de menu
`/api/framework`	Biblioteca de referência oficial
`/health`	Health check

5. Autenticação e Autorização

5.1 JWT (JSON Web Tokens)

O sistema utiliza tokens JWT com as seguintes características:

Algoritmo: HS256
Expiração: 24 horas
Payload: { id, email, role }
Secret: Definido pela variável JWT_SECRET

5.2 Política de Passwords

Mínimo 12 caracteres
Pelo menos 1 letra maiúscula
Pelo menos 1 letra minúscula
Pelo menos 1 número
Pelo menos 1 caracter especial
Hash com bcrypt (factor 10)

5.3 Fluxo de Autenticação

1. Cliente envia POST /api/auth/login { email, password }
2. Servidor valida credenciais com bcrypt.compare()
3. Se válido, gera JWT
4. Cliente armazena token no browser
5. Pedidos seguintes incluem Authorization: Bearer <token>
6. Middleware authenticate() valida e descodifica o token
7. Dados do utilizador ficam disponíveis em req.user

6. Controlo de Acessos (RBAC)

6.1 Hierarquia de Roles

Role	Nível	Descrição
platform_owner	Mais alto	Acesso total + gestão de módulos
super_admin	Elevado	Administração total da plataforma
admin	Operacional	Gestão de dados
revisor	Leitura/revisão	Sem eliminação
user	Básico	Acesso limitado

6.2 Níveis de controlo

JWT: valida identidade
RBAC: valida operações por role
Menu access: valida menus permitidos e módulos ativos
Country filter: restringe dados por país para utilizadores não administrativos

Nota: platform_owner, super_admin e admin não ficam limitados por país. Os restantes podem ser filtrados pela tabela user_countries.

7. Sistema de Módulos e Licenciamento

A plataforma possui módulos que podem ser ativados ou desativados ao nível da plataforma.

Módulo	Chave
Dashboard Overview	`overview`
Countries	`countries`
Entities	`entities`
Suppliers	`suppliers`
Assets	`assets`
Risks	`risks`
Compliance ISO 27001	`compliance_iso27001`
Compliance NIS2	`compliance_nis2`
Compliance ISO 27002	`compliance_iso27002`
Compliance ENS	`compliance_ens`
Compliance GDPR	`compliance_gdpr`
Documents	`documents`
Reports	`reports`
Audit	`audit`
Users	`users`
Framework Annex A	`fw_annexa`
Framework Clauses	`fw_clauses`
Framework NIS2	`fw_nis2`
Framework ISO 27002	`fw_iso27002`
Framework ENS	`fw_ens`
Framework GDPR	`fw_gdpr`

Atenção: Quando um módulo está desativado, pode desaparecer da interface e o respetivo acesso via API fica bloqueado.

8. Segurança

8.1 Medidas Implementadas

Hashing de passwords: bcrypt
JWT: sessões assinadas com secret
Queries parametrizadas: placeholders ? para evitar SQL injection
Cache-Control: headers no-cache nos ficheiros estáticos principais
Auditoria: criação, atualização e eliminação ficam registadas
Controlo por país: separação de dados consoante o utilizador
Upload controlado: apenas PDFs e com limite de tamanho

8.2 Variáveis de Ambiente

Variável	Descrição	Obrigatória
`DB_HOST`	Host MySQL	Sim
`DB_PORT`	Porta MySQL	Sim
`DB_NAME`	Nome da base de dados	Sim
`DB_USER`	Utilizador MySQL	Sim
`DB_PASSWORD`	Password MySQL	Sim
`JWT_SECRET`	Secret JWT	Sim
`PORT`	Porta da aplicação	Não

Importante: Em produção, utilize sempre um JWT_SECRET forte e não mantenha segredos hardcoded no código.

9. Motor de Conformidade

9.1 Padrão Scope / Items

Entidade → Scope → Items

Cada item tem:
- item_type
- item_ref
- item_title
- impl_status

9.2 Estados

not_implemented
on_going
implemented

9.3 Cálculo de Percentagem

Percentagem = ((implemented + on_going * 0.5) / total) * 100

- implemented = 100%
- on_going = 50%
- not_implemented = 0%

9.4 Factory de compliance

ISO 27002, ENS e GDPR utilizam um factory genérico (ComplianceScopeFactory + complianceFactory.js) para reduzir duplicação de código.

10. Arquitectura Frontend

10.1 SPA (Single Page Application)

O frontend é uma SPA em vanilla JavaScript com as seguintes características:

Navegação: menus e secções carregadas na mesma aplicação
Comunicação: chamadas à API com token JWT
Cards e formulários: renderização dinâmica por módulo
Dark theme: CSS com variáveis
Manuais: HTML estático dentro da pasta public/

10.2 Ficheiros principais

public/index.html - estrutura principal da SPA
public/app.js - lógica frontend
public/styles.css - estilos da interface
public/manual-*.html - manuais estáticos

11. Implantação e Operação

11.1 Requisitos

Node.js 20.x
MySQL acessível pela aplicação
Variáveis de ambiente configuradas
Dependências instaladas com npm install

11.2 Processo correto de deploy

Atualizar ficheiros do projeto no servidor
Confirmar .env / variáveis da app Node
Executar npm install
Reiniciar a app

11.3 Comandos

# Instalar dependências
npm install

# Iniciar servidor
npm start

# Script start
node index.js

Nota: Esta aplicação não requer npm run build. O backend corre diretamente com node index.js.

11.4 Bootstrap inicial

No arranque, a aplicação pode garantir estrutura base da plataforma, incluindo:

módulos ativos
permissões de menu por role
framework de referência
utilizadores seed, quando essa lógica estiver ativa na configuração de produção

Manual Técnico

Índice