From cd2fa5e4c7e2284bdae35fbd17d8b17ec3127197 Mon Sep 17 00:00:00 2001 From: kl3z Date: Mon, 24 Aug 2026 21:33:36 +0000 Subject: [PATCH] Modificar README.md --- README.md | 298 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 270 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 0e60e26c..17f91fd5 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,301 @@ -# FormMetacase +# Form Metacase -This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.2.1. +Portal interno da Metacase que centraliza conteúdos de formação e ferramentas de apoio operacional numa aplicação web autenticada. -## Development server +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. -To start a local development server, run: +## Funcionalidades -```bash -ng serve +### 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 ``` -Once the server is running, open your browser and navigate to `http://localhost:4200/`. The application will automatically reload whenever you modify any of the source files. +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. -## Code scaffolding +## Estrutura do projeto -Angular CLI includes powerful code scaffolding tools. To generate a new component, run: - -```bash -ng generate component component-name +```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 ``` -For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run: +## 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 -ng generate --help +python -m pip install pandas camelot-py PyMuPDF pytesseract Pillow openpyxl ``` -## Building +> Confirme que o Python, Tesseract e restantes executáveis necessários estão disponíveis no `PATH`. -To build the project run: +### 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 -ng build +git clone +cd form_metacase +npm ci ``` -This will compile your project and store the build artifacts in the `dist/` directory. By default, the production build optimizes your application for performance and speed. +## Configuração -## Running unit tests +| 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. | -To execute unit tests with the [Vitest](https://vitest.dev/) test runner, use the following command: +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 -ng test +npm run api ``` -## Running end-to-end tests - -For end-to-end (e2e) testing, run: +Inicie o Angular noutro terminal: ```bash -ng e2e +npm start ``` -Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs. +A aplicação fica disponível em `http://localhost:4200`. O proxy de desenvolvimento encaminha `/api` para `http://127.0.0.1:3000`. -## Additional Resources +## Build e execução -For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page. +```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 +```