Modificar README.md
This commit is contained in:
@@ -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 <URL_DO_REPOSITORIO_GITEA>
|
||||
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=<segredo-forte> docker compose up --build
|
||||
```
|
||||
|
||||
Para alterar a porta publicada:
|
||||
|
||||
```bash
|
||||
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 `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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user