9.6 KiB
Form Metacase
Portal interno da Metacase que centraliza conteúdos de formação e ferramentas de apoio operacional numa aplicação web autenticada.
O projeto disponibiliza um Learning Hub com cursos multimédia, um assistente de IA, tradução de textos, conversão de extratos bancários e consulta de um relatório Power BI.
Funcionalidades
Autenticação
- Login por email e palavra-passe.
- Sessões com validade de oito horas e opção para manter a sessão.
- Proteção das páginas privadas através de
authGuard. - Palavras-passe armazenadas com salt e hash PBKDF2-SHA256.
Learning Hub
- Catálogo, detalhe e percurso de cursos.
- Conteúdos em texto, imagem, galeria, apresentação, vídeo, áudio e documentos.
- Navegação entre diapositivos, ampliação de imagens e indicador de progresso.
- Perguntas de validação com feedback de resposta.
Ferramentas operacionais
- Vitoria AI: chat com histórico, fontes e integração com um backend de IA.
- Conversor de extratos: conversão de PDF para Excel para ABANCA e BIC através de Python, extração de tabelas e OCR.
- Tradutor: tradução através de LibreTranslate, inversão de idiomas e cópia do resultado.
- Report Creator: consulta de um relatório publicado no Power BI Service através de
reportEmbed.
Tecnologias
| Área | Tecnologia |
|---|---|
| Frontend | Angular 21, TypeScript 5.9, HTML e CSS |
| Estado e reatividade | Angular Signals e RxJS 7.8 |
| Backend | Node.js 22 e módulos nativos http, crypto, fs e child_process |
| Processamento de PDF | Python, Camelot, PyMuPDF, pytesseract, Pillow e pandas |
| Integrações | LibreTranslate, Power BI Service e backend Bot SIBS/LLM |
| Testes | Vitest e jsdom |
| Build e deployment | Angular CLI, npm, Docker, Docker Compose e Nginx |
Arquitetura
Utilizador
|
v
Angular SPA
|
+-- Learning Hub --------> conteúdos em public/
+-- Report Creator ------> Power BI Service
|
v
API Node.js (server.js)
|
+-- Autenticação --------> server/users.json
+-- Vitoria AI ----------> backend Bot SIBS / LLM
+-- Tradutor ------------> LibreTranslate
+-- Conversor -----------> scripts Python -> XLSX
Em desenvolvimento, o Angular é executado na porta 4200 e encaminha /api para o servidor Node.js na porta 3000. Em produção, o servidor Node.js serve a aplicação compilada e a API no mesmo domínio.
Estrutura do projeto
form_metacase/
├── deploy/nginx/ # Configuração do reverse proxy
├── Metacase/ # Conversores Python ABANCA e BIC
├── public/ # Imagens, vídeos, áudio e documentos
├── server/
│ └── users.json # Utilizadores locais
├── src/app/
│ ├── auth/ # Autenticação e proteção de rotas
│ ├── conversor-extratos-page/
│ ├── course-detail-page/
│ ├── course-learning-page/
│ ├── data/ # Catálogo estático de cursos
│ ├── formacaometacase/ # Catálogo do Learning Hub
│ ├── login-page/
│ ├── pagina-principal/ # Hub principal
│ ├── report-creator-page/
│ ├── shared/ # Componentes reutilizáveis
│ ├── tradutor/
│ └── vitoria-ai-page/
├── angular.json
├── docker-compose.yml
├── Dockerfile
├── package.json
├── proxy.conf.json
└── server.js
Rotas
| Rota | Página | Acesso |
|---|---|---|
/ |
Login | Público |
/pagina-principal |
Hub principal | Autenticado |
/formacoes |
Catálogo de cursos | Autenticado |
/cursos/:slug |
Detalhe do curso | Autenticado |
/cursos/:slug/percurso |
Percurso de aprendizagem | Autenticado |
/vitoria-ai |
Assistente Vitoria AI | Autenticado |
/conversor-extratos |
Conversor PDF para Excel | Autenticado |
/tradutor |
Tradutor | Autenticado |
/report-creator |
Relatório Power BI | Autenticado |
Pré-requisitos
Aplicação base
- Node.js 22 ou superior.
- npm 10 ou superior.
Conversores de extratos
- Python 3.
pandas,camelot-py,PyMuPDF,pytesseract,Pilloweopenpyxl.- Tesseract OCR e dependências de sistema requeridas pelo Camelot.
Exemplo:
python -m pip install pandas camelot-py PyMuPDF pytesseract Pillow openpyxl
Integrações
- Instância LibreTranslate acessível pelo servidor.
- Backend compatível com a API da Vitoria AI.
- Acesso ao tenant e ao relatório configurado no Power BI Service.
Instalação
git clone
cd form_metacase
npm ci
Configuração
| Variável | Predefinição | Descrição |
|---|---|---|
PORT |
3000 |
Porta do servidor Node.js. |
AUTH_TOKEN_SECRET |
valor de desenvolvimento | Segredo de assinatura das sessões. |
BOT_SIBS_API_URL |
http://127.0.0.1:8000 |
Backend da Vitoria AI. |
BOT_SIBS_TIMEOUT_MS |
240000 |
Timeout da Vitoria AI. |
LIBRETRANSLATE_URL |
endereço interno | Instância LibreTranslate. |
PYTHON_BIN |
python |
Executável Python. |
CONVERTERS_DIR |
./Metacase |
Diretório dos conversores. |
CONVERTER_TIMEOUT_MS |
600000 |
Timeout de conversão. |
CONVERTER_MAX_UPLOAD_BYTES |
26214400 |
Limite do PDF, por defeito 25 MB. |
Exemplo em PowerShell:
$env:AUTH_TOKEN_SECRET = 'substituir-por-um-segredo-longo-e-aleatorio'
$env:BOT_SIBS_API_URL = 'http://127.0.0.1:8000'
$env:LIBRETRANSLATE_URL = 'http://127.0.0.1:5000'
$env:PYTHON_BIN = 'python'
Nunca utilize o valor predefinido de
AUTH_TOKEN_SECRETem produção. Não guarde segredos, tokens ou credenciais no repositório.
Desenvolvimento
Inicie a API num terminal:
npm run api
Inicie o Angular noutro terminal:
npm start
A aplicação fica disponível em http://localhost:4200. O proxy de desenvolvimento encaminha /api para http://127.0.0.1:3000.
Build e execução
npm run build
npm run serve:auth
A aplicação compilada e a API ficam disponíveis em http://localhost:3000.
Scripts npm
| Comando | Descrição |
|---|---|
npm start |
Angular em desenvolvimento com proxy para a API. |
npm run api |
Apenas a API Node.js. |
npm run serve:auth |
API e build Angular no mesmo servidor. |
npm run build |
Build de produção em dist/. |
npm run watch |
Build de desenvolvimento em modo watch. |
npm test |
Testes unitários com Vitest. |
API
| Método | Endpoint | Função |
|---|---|---|
POST |
/api/login |
Valida credenciais e cria a sessão. |
GET |
/api/session |
Valida o token atual. |
POST |
/api/vitoria-ai/perguntar |
Encaminha uma pergunta para a Vitoria AI. |
POST |
/api/tradutor/traduzir |
Traduz texto através do LibreTranslate. |
POST |
/api/conversor-extratos/executar |
Converte um PDF em Excel. |
O conversor recebe o PDF no corpo binário e utiliza:
X-Bank-Key: banco (abancaoubic).X-File-Name: nome original do PDF.
Utilizadores
Os utilizadores locais são mantidos em server/users.json, com nome, email, estado, salt e hash da palavra-passe. Não devem ser guardadas palavras-passe em texto simples.
Para produção ou utilização em maior escala, recomenda-se uma base de dados ou um fornecedor de identidade corporativo.
Docker
AUTH_TOKEN_SECRET=<segredo-forte> docker compose up --build
Para alterar a porta publicada:
APP_PORT=8080 AUTH_TOKEN_SECRET=<segredo-forte> docker compose up --build
A imagem atual contém o frontend e o servidor Node.js. Para executar os conversores no contentor, é ainda necessário incluir Python, a pasta
Metacasee as respetivas dependências na imagem de runtime, ou separar a conversão num serviço próprio.
O exemplo em deploy/nginx/form_metacase.conf encaminha pedidos para a porta 3000 e aceita uploads até 30 MB.
Testes
npm test
npm run build
Antes de integrar alterações, valide também os fluxos de login, formação, IA, tradução, conversão e Power BI.
Resolução de problemas
A API não responde
- Confirme que
npm run apiestá ativo. - Verifique a porta
3000eproxy.conf.json. - Confirme
BOT_SIBS_API_URLeLIBRETRANSLATE_URL.
O Power BI não aparece
- Inicie sessão na conta Microsoft correta.
- Confirme que a conta tem acesso ao relatório.
- Permita pop-ups e cookies necessários ao Power BI.
- Valide o URL
reportEmbedemreport-creator-page.ts.
A conversão falha
- Confirme que o PDF é válido e não excede o limite.
- Verifique
PYTHON_BINeCONVERTERS_DIR. - Instale as bibliotecas Python, o Tesseract e as dependências do Camelot.
O tradutor não responde
- Confirme que o LibreTranslate está acessível pelo servidor Node.js.
- Verifique
LIBRETRANSLATE_URLe o endpoint/translate.
Segurança
Antes de produção:
- utilize um segredo de autenticação forte;
- proteja todos os endpoints sensíveis;
- restrinja CORS e o acesso à rede;
- utilize HTTPS e headers de segurança;
- não faça commit de
.env, credenciais ou dados bancários; - mantenha dependências atualizadas;
- configure logs e auditoria sem informação sensível.
Contribuição no Gitea
- Crie um ramo a partir do ramo principal.
- Faça alterações pequenas e focadas.
- Execute testes e build.
- Confirme que não adicionou segredos ou dados sensíveis.
- Abra um Pull Request no Gitea com a descrição e evidências de validação.
git checkout -b feature/nome-da-funcionalidade
git add .
git commit -m "feat: descrição da alteração"
git push origin feature/nome-da-funcionalidade