HOG Invest

Definições da Arquitetura Organização do Projeto

Resumo de Regras para GPT

• Nomes de Classes, métodos e variáveis devem sempre estar escritas em inglês e no formato de CamelCase, não utilizar _ para separar palavras;
• Ao implementar métodos e classes sempre documente a funcionalidade e detalhes dos parâmetros recebidos.

Organização do Projeto

• etc/ - Documentos e Outros arquivos relacionados ao Projeto
  • DBModel/ - Modelos do Banco de Dados
• run/ - Script para execução de comandos e rotinas por linha de comando.
• src/ - Códigos do Sistema
  • crud - Classes com código de CRUD (Core) da aplicação.
    • vo - Classes que representam objetos (Value Objetcs)
  • lib - Classes utilitárias utilizada por diversas classes do sistema, como Log, DAO, etc..
  • modules/ - Classes e módulos específicos, como os de comunicação com outro sistemas e APIs (Como comunicação com BCB, B3, WebCrawlers, etc.).
• root/ - UI do Sistema, pasta publicada pela URL

Operações do Banco de Dados

• Persistência e Exclusão - Os métodos de persistência e exclusão dos objetos devem ser concentrados dentro da classe DAO.
• Consultas - Consutla ao banco de dados deve ser feita diretamente da classe que precisar dos dados, apesar de descentralizar a manutenção, fica mais fácil e dinâmico a programação de obtenção de dados, joins, etc.

Requisitos e Defnições

Ativos stock

Requisitos

• Os ativos podem ser de diversos tipos (ações, BDRs, FIIs, etc.) desde que negociados em Bolsa, e podem ser de diversos países.
• Além do país, deve ter a referência para a bolsa de valores em que é negociado. Há países com mais de uma bolsa de valores.
• O tipo do ativo (Ação, ADR, FII, BDR, etc.) deve ser definido para realizar filtros nas carteiras.
• Data inicial e final em que o ativo foi negociado. Nada final nula indica que o ativo ainda está ativo e continua sendo negociado.
• O sistema deve salvar a data em que o registro foi criado e em que data foi atualizado pela última vez para referência e outras funcionalidades futuras.
• Uma vez que o ativo deixe de ser negociado a data fim deve ser definida para evitar lançamentos errados, além de evitar que tickers reutilizados no futuro causem confusão na carteira.
• Todos os ativos que tenham sua data fim definida devem ter seu status definido como INATIVO, para o gerenciamento desses ativos pelo código.

Arquitetura

• Campos do stock:
  • ticker: define o ticker do ativo, embora a B3 tenha um padrão de nome as americanas permitem ativos com até uma letra.
  • exchange: Enumeration com as bolsas de valores suportadas pelo sistema
    • B3 - Bolsa de Valores brasileira
  • startDate: Data de início das negociações
  • endDate: Data de fim das negociações, ou nulo se ainda for negociada.
  • fullName: Nome completo da empresa.
  • shotName: Nome curto de identificação da empresa.
  • assetType: Enumeration do tipo do ativo
    • STOCK - ação negociada na própria bolsa
    • ADR - ações de outras bolsas negociadas por recibo (identifica também os BDR quando a bolsa for 'B3')
    • REITS - ativos de fundos imobiliários
  • createAt - Data/hora de quando o registro foi criado no sistema
  • updateAt - Data/hora de quando o registro foi atualizado pela última vez

Lançamento das Operações stockOperation

Requisitos

• Deverão ser lançadas (ou importadas) as operações realizadas pelo usuário, como compra, venda, subscrição, doação (donatário ou doador), etc.. Operações compulsórias como bonificações, resgates, mudanças de tickers, incorporações, etc., deverão ser tratadas automaticamente pelo sistema com base em 'conhecimento público' e não lançadas manualmente.
• O sistema deve permitir um lançamento de 'ajuste', tanto para aumentar quanto para decrementar a quantidade de ativos da carteira, talvez para lançar operações que o sistema ainda não contemple.
• Em caso de troca de ticker, incorporação, merge e outras operações em que o ticker troque por algum motivo, o lançamento deve conter a referência para o ticker atual e para o ticker original da operação, para efeitos de rastreabilidade.

Arquitetura

• Campos do stockOperation:
  • idUser: Referência à tabela de user - Para saber de quem é o lançamento
  • idStock: Referência à tabela de stock - Deve sempre estar relacionado com o ticker em que a quantidade atual pertence, mesmo que a operação tenha sido realiza com outro ticker ou stock (casos de merge, incorporação, troca de ticker, etc)
  • idStockOriginal: Referência à tabela de stock - Segundo relacionamento para manter o relacionamento com a Stock original da operação (antes de qualquer migração). Quando não há alterações do ticker em que a operação foi realizada deve ter o mesmo valor de idStock.
  • date: Data em que a operação foi realizada.
  • operation: Enumeração que indica a operação realizada:
    • BUY - Compra
    • SELL - Venda
    • SUBSCRIPTION - Subscrições (mesmo efeito que a compra, mas registra que não há nota de corretagem)
  • quantity - Quantidade de ativos envolvidos na operação
  • grossValue - Valor Bruto (Calculado somente pela quantidade de ativos * seu preço unitário), não considera corretagem, impostos, emolumentos, etc.
  • netValue - Valor Líquido (calculado considerando o valor efetivamente movimentado, incluindo as taxas, emolumentos, etc. - NÃO DEVE INCLUIR OS IMPOSTOS DE RENDA RETIDOS)
  • irrf - Valor do Imposto de Renda retido na fonte nas operações de venda.

UI

Componentes

Toggle Theme

Para trocar o tema entre claro e escuro pode-se incluir o comando:

<button id="theme-toggle" class="btn btn-secondary" onclick="HOGInvest.toggleTheme()">Alternar Tema</button>

que chama o script dentro da biblioteca principal da aplicação hoginvest.js.

Notifications

O sistema tem 3 tipos de notificações que podem ser chamadas da seguinte forma:

showSuccess('Operação realizada com sucesso!');
showWarning('Atenção: Verifique os dados inseridos!');
showError('Erro: Algo deu errado!');

Não é necessário incluir nenhum compnente no HTML, os componentes são criados dinamicamente.

HogTable

A classe HogTable é uma biblioteca de manipulação de tabelas HTML, que permite criar tabelas dinâmicas com funcionalidades avançadas, como ordenação, seleção de linhas, colunas fixas e colunas escondíveis.

Construtor

constructor(tableId)

• Cria uma nova instância da tabela associada ao ID fornecido.

Parâmetros:

• tableId: ID do elemento no DOM.

  Exemplo:

  const table = new HogTable("myTableId");
  

  
  

  loadData(data)

  • Carrega os dados na tabela.

  Parâmetros:

  • data: Array onde a primeira linha contém os cabeçalhos e as demais linhas os dados.

  Exemplo:

  table.loadData([
      ["ID", "Nome", "Email"],
      ["1", "João Silva", "joao@example.com"],
      ["2", "Maria Oliveira", "maria@example.com"]
  ]);
  

  
  

  clearData()

  • Limpa todo o conteúdo da tabela, mantendo apenas os cabeçalhos.

  Exemplo:

  table.clearData();
  

  stickColumn(columnIndex, sticky)

  • Torna uma coluna fixa ou libera a fixação.

  Parâmetros:

  • columnIndex: Índice da coluna.
  • sticky: Booleano (true para fixar, false para liberar).

  Exemplo:

  table.stickColumn(0, true); // Fixa a primeira coluna
  table.stickColumn(0, false); // Libera a primeira coluna
  

  
  

  setIDColumn(columnIndex)

  • Define qual coluna será usada como identificador das linhas.

  Parâmetros:

  • columnIndex: Índice da coluna.

  Exemplo:

  table.setIDColumn(0); // Define a primeira coluna como identificador
  

  
  

  setSelectMode(mode)

  • Configura o modo de seleção da tabela.

  Parâmetros:

  • mode: "NONE", "SINGLE", ou "MULTI".

  Exemplo:

  table.setSelectMode("SINGLE"); // Seleção de apenas uma linha
  

  
  

  onSelectionChange(callback)

  • Define um callback a ser chamado ao alterar a seleção.

  Parâmetros:

  • callback: Função que recebe os IDs das linhas selecionadas.

  Exemplo:

  table.onSelectionChange((selectedIds) => {
      console.log("Selecionados:", selectedIds);
  });
  

  
  

  setSelection(ids)

  • Define as linhas selecionadas.

  Parâmetros:

  • ids: Array de IDs.

  Exemplo:

  table.setSelection(["1", "2"]); // Seleciona as linhas com IDs "1" e "2"
  

  
  

  clearSelection()

  • Limpa todas as seleções da tabela.

  Exemplo:

  table.clearSelection();
  

  
  

  setColumnVisible(columnIndex, visible)

  • Define a visibilidade de uma coluna.

  Parâmetros:

  • columnIndex: Índice da coluna.
  • visible: Booleano (true para mostrar, false para esconder).

  Exemplo:

  table.setColumnVisible(1, false); // Esconde a segunda coluna
  

  
  

  setHidableColumns(columnIndices)

  • Configura as colunas que podem ser escondidas pelo usuário.

  Parâmetros:

  • columnIndices: Array de índices das colunas.

  Exemplo:

  table.setHidableColumns([1, 2]); // Define as colunas 1 e 2 como escondíveis
  

  
  

  setSort(columnIndex, ascending)

  • Define o estado de ordenação de uma coluna.

  Parâmetros:

  • columnIndex: Índice da coluna.
  • ascending: Booleano (true para ascendente, false para descendente) ou null para limpar.

  Exemplo:

  table.setSort(0, true); // Ordena a primeira coluna de forma ascendente
  

  
  

  clearAllSort()

  • Remove o estado de ordenação de todas as colunas.

  Exemplo:

  table.clearAllSort();
  

  
  

  onHeaderClick(callback)

  • Define um callback a ser chamado ao clicar nos cabeçalhos.

  Parâmetros:

  • callback: Função que recebe (index, headerText, sortState).

  Exemplo:

  table.onHeaderClick((index, headerText, sortState) => {
      console.log("Cabeçalho clicado:", headerText, "Estado de ordenação:", sortState);
  });