appmax-client-vue3

v5.0.6

Published

9 days ago

Este repositório de frontend faz parte da nova estrutura de cliente da AppMax. Atualmente, estamos executando um processo de desmembramento de nosso sistema monolítico, com a separação do front-end. Além disso, este repositório desempenha um papel-chave n

Downloads

1,367

0High
0Medium
0Low

appmax_npm

Appmax client Vue 3

Sumário:

SonarQube

🔍 Como executar análise local com o SonarQube

⚠️ Importante: Certifique-se de ter o SonarScanner instalado localmente no seu ambiente. Aqui você encontra as instruções.

Para rodar a análise localmente, é necessário um token de autenticação pessoal.

🚧 Atenção: Não compartilhe seu token com outras pessoas e nunca o adicione ao código-fonte, scripts ou documentação.

🔐 Gerando seu token: Acesse o SonarQube pela rede interna: https://sonarqube.appmax.io/

No canto superior direito, clique no seu nome de usuário e depois em "My Account".

Vá até a aba "Security".

Em "Generate Tokens", insira um nome (ex: token-sonar-local) e clique em "Generate".

Copie o token exibido. Você não poderá vê-lo novamente.

Você pode rodar a análise de qualidade localmente no seu projeto antes de abrir um PR, identificando possíveis problemas antecipadamente. Para isso, utilize o comando abaixo:

sonar-scanner \
  -Dsonar.projectKey=sistema \
  -Dsonar.sources=app
  -Dsonar.host.url=https://sonarqube.appmax.io \
  -Dsonar.login=SEU_TOKEN_AQUI

Opção 2 – Usando variável de ambiente (recomendado):

export SONAR_TOKEN=SEU_TOKEN_AQUI

sonar-scanner \
  -Dsonar.projectKey=meu-projeto \
  -Dsonar.sources=. \
  -Dsonar.host.url=http://<endereço_do_sonarqube> \
  -Dsonar.login=$SONAR_TOKEN

Status da ultima análise:

Tecnologias usadas

Node JS: ^v20
Vue 3: Usamos o Composition API
Vue Router 4
Typescript
Vite
Tailwind CSS
PNPM: Gerenciador de pacotes rápido e eficiente

Instalação

Comece clonando o repositório em sua máquina local:

git clone [email protected]:appmax-space/appmax-client-vue3.git

Agora você deve instalar as dependências:

pnpm i

Crie o arquivo .env

cp .env.sample .env

Como usar

Existem duas formas de rodar a aplicação: (1) usando o sistema local e servindo a aplicação dentro desse contexto, ou (2) rodando a aplicação apartada, ao qual poderá usar o backend do sistema como um serviço externo. A seguir vamos mostrar o que precisa ser feito para rodar ambos os modos:

(1) Rodando o frontend dentro do sistema local

Para rodar a aplicação dentro do sistema local, você precisa garantir que as seguintes variáveis de ambiente estejam configuradas dentro do repositório do sistema:

# /sistema/.env

# Valores necessários para o funcionamento
APP_NEW_SPA_V3=true
APP_NEW_SPA_LAYOUT_ENABLE=true
APP_NEW_SPA_VUE3_HOST=http://localhost:8182

# Outras envs que podem ser necessárias:
APP_NEW_SPA_WITHDRAW=true
APP_NEW_SPA_VUE3_ANTICIPATION=true
DASHBOARD_V2_ENABLE=true
SPA_DEFAULT_THEME='white'

Com a aplicação do sistema local devidamente configurada, execute o seguinte comando na aplicação frontend:

pnpm dev

Agora basta acessar http://sistema.local

(2) Rodando o frontend apartado

É a maneira mais performática de se trabalhar, mas requer alguns passos extras. É possível rodar a aplicação apartada consumindo o sistema local ou consumindo alguns dos ambientes sandbox da empresa, o que pode ser bastante útil por causa da base de dados disponível.

Se quiser apenas rodar apartado apontando para o sistema local, as suas variáveis de ambiente devem ter a seguinte configuração:

# .env

VITE_API_BASE_URL="http://sistema.local"

Caso queira rodar apontando para algum ambiente sandbox, você deve configurar o .env com a url do ambiente e ter uma chave de permissão. Abaixo segue um exemplo para o ambiente sandbox:

VITE_API_KEY="SECRET_HERE"
VITE_API_BASE_URL="https://dev-sandbox.appmax.com.br/"
VITE_ASSETS_BASE_URL="https://dev-sandbox.appmax.com.br/"

Entre em contato com o time para receber a chave de acesso.

Pronto, agora rode o comando abaixo para executar a aplicação em mode de desenvolvimento (apontando para dev-sandbox):

pnpm dev:local

Agora você deve acessar o ambiente de sandbox e efetuar o login, pois a aplicação irá usar o access_token gerado para o login manual. Abra a url http://localhost:8182/, se tudo der certo, você será redirecionado para uma página de login manual, clique no link Importar Access Token (Consultar aqui). Copie o valor da chave access_token, cole no campo e clique em importar. Pronto, você está autenticado com o usuário logado no ambiente de sandbox.

:warning: Atenção: O token irá expirar em algum momento, portanto é preciso acessar o link Importar Access Token (Consultar aqui) e repetir o processo anterior. Esse intervalo depende da configuração do sistema. Para o ambiente local, indicamos aumentar esse tempo mudando a seguinte variável de ambiente:

# /sistema/.env

JWT_TTL=20160

Rotas

Todas as rotas da aplicação estão disponíveis dentro do path /v2/client/integration/*, com exceção da dashboard, que está dentro de /v2/client. Isso foi definido e configurado dento do sistema, já que o ponto de entrada do frontend é instanciado dentro de um arquivo blade do sistema. O arquivo src/routes/index.ts contém a importação de todas as rotas da aplicação.

Cada módulo da aplicação deve conter o seu arquivo routes.ts, ao qual deve ser importado dentro do src/routes/index.ts. Além disso, cada rota deve ter seu título adicionado dentro da propriedade meta, conforme o exemplo abaixo:

// src/modules/meu-modulo/routes.js

import MeuModuloView from './views/MeuModuloView.vue'

export default [
  name: 'meu-modulo.home'
  path: 'meu-modulo',
  component: MeuModuloView,
  meta: {
    viewTitle: 'Meu módulo',
    // Proteção da rota
    checkProfile: true,
    permissions: [],
    redirect: '/outra-rota',
  }
]

Boas práticas

Com o Vue 3, estamos adotando algumas boas práticas que ainda não podiam ser usadas nas outras aplicações. Todos os novos componentes na aplicação devem seguir as seguintes regras de boa vizinhança:

Composition API: Usamos o SFC com <script setup />;
Typescript: Os novos componentes e helpers devem usar TypeScript;
Testes: Os novos componentes devem ter testes unitários e funcionais;
Tamanho dos componentes: Não devem passar de 300 linhas;

Recomendação para o Setup da IDE

Recomendamos o uso do seguintes plugin no VS Code:

Vue - Official