Skip to content

Latest commit

 

History

History
228 lines (179 loc) · 17.4 KB

CONTRIBUTING.md

File metadata and controls

228 lines (179 loc) · 17.4 KB
Raw

Contribuindo com a Plataforma PEA Pescarte

🎉 Primeiro de tudo, agradecemos por despender tempo em contribuir com esse projeto! Espero que tenha uma experiência incível! 🎉

Requisitos e Ambiente de Desenvolvimento

Siga os passos descritos na seção de Setup, no README!

Estrutura da Aplicação

.
├── config/
├── guides/
├── lib/
├── mix.exs
├── mix.lock
├── priv/
├── rel/
└── test/
  • config - neste diretório se encontra toda a configuração do projeto, o arquivo config/config.exs é a porta de entrada da config e no final dele são importadas as configurações específicas de ambiente como dev, test ou prod. Essa configuração é executada em tempo de compilação. Por fim, o arquivo config/runtime.exs é executado; este arquivo é ideal para pegar valores dinâmicos, de variáveis de ambiente, por exemplo. Como o nome do arquivo diz, essa configuração é processada em tempo de execução.
  • guides - neste diretório se encontra os guias para diferentes formas de configuração do ambiente de desenvolvimento local, guias de padronização de código como formatado dos testes automatizados, dentre outras recomendações e padrões utilizados no projeto.
  • lib - diretório onde se encontra o código fonte da aplicação. Dentro dele existem dois subdiretórios, lib/pescarte e lib/pescarte_web. O diretório lib/pescarte é responsável por denominar e guardar a implementação das regras de negócio e domínios de negócio da aplicação. Geralmente é onde se comunica com a base de dados. Já lib/pescarte_web é responsável por expor o domínio de negócio para o externo, geralmente sendo uma aplicação web, e mais especificamente, uma API GraphQL.
  • mix.exs - arquivo de configuração do projeto como um todo! Entenda como se fosse um package.json dentro do ecossistema JavaScript. Aqui definimos o nome da aplicação, listamos suas dependências, configuramos como a aplicação deve ser compilada e gerada sua versão final e também configuramos os dados para gerar documentação do projeto.
  • mix.lock - arquivo onde é guardado as versões atuais das dependências baixadas, gerando reprodutibilidade no ambiente. Entenda como um yarn.lock ou package-lock.json do ecossistema JavaScript.
  • rel - diretório onde são definidos scripts que serão executados quando a aplicação for gerar sua versão final
  • test - diretório onde se encontram todos os testes automatizados, sejam eles unitários ou de integração. Geralmente sua estrutura interior replica a subestrutura encontrada em lib

Diretório lib/pescarte

lib/pescarte
├── application.ex
├── database.ex
├── domains/
├── helpers.ex
├── http_client.ex
├── http_client_behaviour.ex
├── release.ex
├── repo.ex
└── types/
  • application.ex - este arquivo representa o ponto de inicío da nossa aplicação! É onde são definidas as aplicações que nosso projeto depende, como conexão com banco de dados, cliente HTTP distribuído, entre outros. Cada aplicação listada aqui é uma aplicação Elixir e e gerenciada por Supervisors, que fornece a tolerância a falhas pra nossa aplicação como um todo e suas dependências.
  • database.ex - é uma abstração sobre as funções do Ecto.Repo, centralizando todas as chamandas ao banco em 1 (um) único arquivo. Assim torna-se mais fácil de testar e isolar os efeitos colaterais da aplicação.
  • domains - diretório onde se encontra os domínios de negócio da aplicação! Será melhor explicado na próxima seção
  • helpers.ex - neste arquivo são definidas funções comuns e puras que transformam dados da aplicação e padronizão os retornos
  • http_client_behaviour.ex - comportamento que define as funções necessárias para implementar um cliente HTTP, para realizar requisições a outros serviços e APIs externas! Entenda como uma interface do TypeScript ou Java. Para ler mais sobre comportamentos, siga a documentação oficial da linguagem Elixir
  • http_client.ex - arquivo no qual o comportamento http_client_behaviour é implementado, permite realizar requições HTTP externas a aplicação

Diretório lib/pescarte/domains

lib/pescarte/domains
└── modulo_pesquisa
    ├── repository.ex
    ├── models
    ├── handlers
    └── services

Neste diretório se encontra os domínios de negócio da aplicação. Em outras palavras, cada domínio representa um contexto fechado no qual necessita de uma solução na vida real. Cada domínio é dividido em "camadas", onde a camada mais interna só pode ser acessada pela a camada superior direta. A imagem a seguir exemplifica isso:

Cada domínio de negócio possui os seguintes componentes:

  • repository - neste arquivo é implementado as funções específicas de cada entidade para o CRUD (create, read, update e delete). Cada domínio possui seu próprio repositório com funções específicas e construções de queries (consultas)
  • models - diretório que representa os modelos de negócio, as entidades do domínio! Por exemplo, no caso do domínio modulo_pesquisa, temos as entidades Pesquisador e Relatorio. Os modelos são os componentes mais importantes dentro de um domínio e não podem ser acessados diretamente por outros domínios nem mesmo por outros componentes do mesmo domínio
  • handlers - esse é o ponto de entrada do domínio/contexto da aplicação! Aqui é exposta a API pública dos serviços internos desse domínio e é a única forma de se comunicar com outros domínios ou outros pontos da aplicação, como a camada web. Cada handler deve atender à um sub-domínio do contexto e a um comportamento único. Para melhor entendimento, veja o handler do sub-domínio mídias, que expõe funções que resolvem as solicitações vindas da nossa API GraphQL
  • services - neste diretório se encontra os serviços que modificam os modelos/entidades do domínio. É a única camada que pode modificar os modelo de forma direta e é importante ressaltar que os serviços de domínio podem apenas implementar funções puras, sem efeitos colaterais. Um serviço de domínio pode modificar uma ou mais entidades

Diretório lib/pescarte_web

lib/pescarte_web
├── authentication.ex
├── authorization.ex
├── controllers
├── design_system
├── design_system.ex
├── endpoint.ex
├── graphql
├── layouts
├── live
├── plugs
├── templates
└── router.ex
  • authentication.ex - este arquivo abriga funções relacionadas à autenticação de usuários na parte interna da plataforma, com exceção da API GraphQL. Serve tanto para views comuns quanto live views
  • authorization.ex - este arquivo abriga funções de autorização e permissionamento dentro da parte interna da plataforma, com exceção da API GraphQL. Permite ou não que usuários de tipos diferentes acessem determinadas páginas internas
  • controllers - neste diretório se encontram arquivos que mapeam as rotas da plataforma para as determinadas "dead views". Caso a view a ser desenvolvida não dependa tanto de interatividade e portanto não irá usar live view, deve-se usar os controllers e templates comuns
  • design_system.ex - arquivo onde se encontra as definições e implementações dos componentes especificados no Design System da plataforma que pode ser encontrato no Figma do projeto. Caso o componente seja muito complexo ou seja um live component, crie um arquivo separado no diretório design_system e use defdelegate/2 para redirecionar as chamadas, como foi feito com o componente de navbar
  • endpoint.ex - este arquivo é o ponto de entrada da camada web da aplicação! Nele é configurado o reteador da aplciação, opções de sessão web, diferentes leitores de formatos como JSON ou HTML, dentre outras opções
  • layouts - diretório onde se encontram layouts da aplicação, que são templates que vão encapsular todas as páginas da plataforma
  • live - neste diretório são implementadas as telas que precisam de interatividade real-time ou possuem um estado inerente
  • graphql - neste diretório é implementado os esquemas, entidades e mutações possíveis da API GraphQL da aplicação. O mesmo será explicado em mais detalhes na próxima seção
  • graphql - neste diretório é implementado os esquemas, entidades e mutações possíveis da API GraphQL da aplicação. O mesmo será explicado em mais detalhes na próxima seção
  • plugs - neste diretório se encontra arquivos que modificam a componentes da conexão durante o fluxo da requisição na aplicação. Entenda como um middleware! Porém os Plugs dentro do framework Phoenix podem ser adicionados em qualquer ponto do ciclo de vida de uma requição, como no início, meio (middleware) ou no fim, antes de ser enviada uma resposta ao cliente. Para mais informações, leia a documentação de Plugs
  • templates - diretório onde os templates comuns são implementados
  • router.ex - neste arquivo são definidas as rotas que podem ser acessadas na aplicação!

Diretório lib/pescarte_web/graphql

lib/pescarte_web/graphql
├── context.ex
├── middlewares
├── resolvers
├── schema.ex
└── types
  • context.ex - arquivo onde se implementa informações que precisam estar disponível de forma "global" para as requisições GraphQL, por exemplo, uma pessoa usuária caso autenticada é disponibilizada neste arquivo e inserida no contexto de toda requisição, assim sendo possível implementar autorização
  • middlewares - neste diretório se encontra middlewares específicos para as requisições GraphQL
  • resolvers - neste diretório são implementadas as resoluções para cada entidade do esquema GraphQL da aplicação. Entenda uma resolução como um Controller em APIs REST
  • schema.ex - este arquivo implementa o esquema público que será exposto na API GraphQL. Nele é especificado quais entidades e quais consultas e mutações estão disponíveis para modificar as entidades
  • types - neste diretório é implementado os tipos de cada entidade e esquemas de como os argumentos de cada entidade devem ser recebidos. Leia mais na documentação sobre esquemas

Como contribuir?

Serão abertas issues de diferente escopos, como:

  • implementar novos contextos e entidades
  • refatorar contextos e excluir partes desnecessárias
  • corrigir bugs de algum fluxo existente
  • expor as queries e mutations necessárias para alimentar o frontend

Em adição as issues, existem dois projetos do GitHub com as tarefas atuais, distribuídas num quadro estilo Kaban.

Um projeto é específico para os componentes do Design System e o outro é um projeto para tarefas gerais da plataforma, incluindo correção de bugs e implementação de telas.

Passos para pegar uma tarefa

Após encontrar uma tarefa do seu interesse na seção de issues, adicione um comentário na issue da mesma, informando que irá trabalhar nela!

Crie uma branch no formato <user-github>/tarefa, exemplo:

  • Usuário no github: zoedsoupe
  • Tarefa: Criar componente de botão

Nome da branch: zoedsoupe/cria-componente-botao

Abrindo a PR

Com a tarefa implementada, abra uma PR diretamente para a branch main. A mesma deve seguir o formato do template.

Assim que possível a @zoedsoupe irá revisar sua PR que poderá ser aprovada ou ter solicitação de refatoração.

Lembre-se que é que não é obrigatório testes unitários para uma PR ser aberta! Caso não saiba como implementar os mesmo, a @zoedsoupe irá te ajudar no processo!

Documentos

Modelagem do banco de dados (07/04/2023)

Regras de Negócio

Em construção...

Links para referência e estudo

Elixir e programação

Tenho um servidor no Discord onde centralizei dezenas de links não apenas sobre Elixir mas sobre programação web para backend como um todo, tendo banco de dados, APIs, git w github, sistemas operacioanis e muito mais.

Entrem no servidor por esse link e sigam as trilhas dos canais "fullstack" e "backend".

Ferramentas para desenvolvimento backend