# 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 ```text 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 ```text 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`, `Pillow` e `openpyxl`. - Tesseract OCR e dependências de sistema requeridas pelo Camelot. Exemplo: ```bash python -m pip install pandas camelot-py PyMuPDF pytesseract Pillow openpyxl ``` > Confirme que o Python, Tesseract e restantes executáveis necessários estão disponíveis no `PATH`. ### 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 ```bash 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: ```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_SECRET` em produção. Não guarde segredos, tokens ou credenciais no repositório. ## Desenvolvimento Inicie a API num terminal: ```bash npm run api ``` Inicie o Angular noutro terminal: ```bash 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 ```bash 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 (`abanca` ou `bic`). - `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 ```bash AUTH_TOKEN_SECRET= docker compose up --build ``` Para alterar a porta publicada: ```bash APP_PORT=8080 AUTH_TOKEN_SECRET= 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 `Metacase` e 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 ```bash 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 api` está ativo. - Verifique a porta `3000` e `proxy.conf.json`. - Confirme `BOT_SIBS_API_URL` e `LIBRETRANSLATE_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 `reportEmbed` em `report-creator-page.ts`. ### A conversão falha - Confirme que o PDF é válido e não excede o limite. - Verifique `PYTHON_BIN` e `CONVERTERS_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_URL` e 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 1. Crie um ramo a partir do ramo principal. 2. Faça alterações pequenas e focadas. 3. Execute testes e build. 4. Confirme que não adicionou segredos ou dados sensíveis. 5. Abra um Pull Request no Gitea com a descrição e evidências de validação. ```bash 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 ```