3. Casos de Uso, Modelo Lógico, Requisitos Funcionais do Sistema, Arquitetura de Software e Padrões de Projeto - gentil-eilison/Ankit-Backend GitHub Wiki

Diagrama de Casos de Uso

Modelo Lógico

Requisitos Funcionais (User Stories)

Relativos à conta

RF001: Criar Uma Conta Através da Plataforma

• Prioridade: 8;

• História de usuário: Como um estudante, eu quero ser capaz de criar uma conta utilizando a plataforma, para que eu possa entrar e começar a organizar minhas sessões de estudo em diferentes idiomas;

• Critérios de aceitação: Dado que eu não tenha uma conta, ao entrar no site, preencher o formulário de criação de conta e enviá-lo, eu devo ser capaz de entrar na plataforma.

RF002: Criar Uma Conta Utilizando Login Social do Google

• Prioridade: 9;

• História de usuário: Como um estudante, eu quero ter a possibilidade de criar uma conta utilizando as credenciais da minha conta Google para que eu, através dela, consiga me cadastrar no site para então estudar os idiomas que desejo, sem precisar lembrar de mais uma conta;

• Critérios de aceitação: Dado que eu não tenha conta, ao entrar no site, utilizar o botão que permita eu criar uma conta utilizando minhas credenciais Google, Para que eu consiga entrar na plataforma e estudar idiomas com o Anki de maneira prática.

RF003: Associar Uma Conta Google a Um Email Já Cadastrado de Mesmo Valor e Vice-versa

• Prioridade: 1;

• História de usuário: Como um estudante, eu quero ser capaz de vincular minha conta à minha conta Google e vice-versa, para que eu possa entrar e começar a organizar minhas sessões de estudo em diferentes idiomas com uma única conta;

• Critérios de aceitação: Dado que eu tenha um email igual ao da minha conta Google cadastrado ou que eu tenha criado uma conta usando o login social da Google, ao entrar no site de uma dessas formas, eu devo ter minhas contas ou a possibilidade de torná-las uma associada à outra e ser capaz de logar por uma ou outra.

RF004: Desassociar Uma Conta Google a Uma Conta Já Cadastrada

• Prioridade: 1;

• História de usuário: Como um estudante, eu quero ser capaz de desvincular minha conta de uma determinada conta Google previamente associada, para que eu possa, posteriormente, associar a outra conta Google;

• Critérios de aceitação: Dado que eu tenha um email igual ao da minha conta Google cadastrado e uma conta Google associada, ao desassociar essa conta, devo ser capaz de associar outra conta a ela e logar utilizando a nova conta.

RF005: Atualizar Dados Pessoais e Educativos

• Prioridade: 6;

• História de usuário: Como um estudante, eu quero poder atualizar meus dados pessoais e educacionais, como nacionalidade, grau de escolaridade, nome, dentre outros, para que a plataforma possa me ajudar de maneira mais específica.

• Critérios de aceitação: Dado que possuo uma conta e estou no sistema, ao entrar no site e modificar meus dados na plataforma, eu devo ser capaz de vê-los atualizados no meu perfil.

RF006 Visualização de Estatísticas Pessoais

• Prioridade: 7;

• História de usuário: Como um estudante, eu quero conseguir visualizar as estatísticas dos meus estudos em um determinado idioma ou considerando todos os idiomas que estudo, para que eu possa melhorar/monitorar o meu progresso dos meus estudos nos idiomas que estudo na plataforma;

• Critérios de aceitação: Dado que eu esteja logado no sistema, tenha pelo menos uma sessão de estudos cadastrada, ao navegar para a página de geração de estatísticas, eu devo ter acesso a todos os dados sobre aquele idioma ou idiomas relativos a minha conta.

RF007: Exclusão de Conta

• Prioridade: 1;

• História de usuário: Como estudante, eu desejo ter a capacidade de excluir a minha conta da plataforma caso decida que não vou mais utilizá-lá, para que eu não tenha mais uma conta ativa inutilizada;

• Critérios de aceitação: Dado que eu esteja logado no sistema, ao utilizar a interface para informar e confirmar que desejo excluir a conta, não devo mais ser capaz de logar com ela e aparecer nas estatísticas.

Relativos a Estudos

RF008: Geração de Um Arquivo CSV Com a(s) Frase(s) de Um Idioma a Serem Adicionadas

• Prioridade: 10;

• História de usuário: Como um estudante, eu quero ser capaz de gerar um arquivo CSV contendo todos os dados possíveis das frases geradas para serem adicionados no Anki para que eu possa importar esse arquivo no aplicativo do Anki e então adicionar os cards de forma automática;

• Critérios de aceitação: Dado que eu tenha requisitado N cards para um determinado idioma, ao clicar no botão de baixar todas as informações para os cards de forma organizada em um arquivo CSV, eu devo conseguir ter acesso ao arquivo e usá-lo para importação no Anki.

RF009: Criação de Uma Sessão de Estudos de Um Idioma

• Prioridade: 10;

• História de usuário: Como um estudante, eu quero iniciar uma sessão, como se fosse uma conversa com a IA, para estudar um determinado idioma, para que eu consiga fazer perguntas e ganhar conhecimento sobre determinado vocabulário;

• Critérios de aceitação: Dado que eu esteja logado no sistema, ao selecionar o idioma ativo e criar uma sessão de estudos, eu devo ser capaz de ver uma tela de conversação com a IA, indicando que a sessão foi iniciada.

RF010: Solicitar Geração de Flashcard de Um Determinado Termo

• Prioridade: 10;

• História de usuário: Como um estudante, eu quero ser capaz de solicitar ao Ankit a criação de uma preview de flashcard contendo uma frase e a definição ou tradução de um determinado termo do idioma utilizado na sessão de estudos, para que eu possa aprender sobre ele e, posteriormente, ser capaz de adicionar a informação ao meu Anki;

• Critérios de aceitação: Dado que eu esteja logado e em uma sessão de estudos, ao informar à plataforma que quero aprender uma nova palavra e informá-la, eu devo ser capaz de ver a sua definição ou tradução, indicando qual será a frente e o verso do cartão.

RF011: Solicitar Geração de Flashcards Sobre um Determinado Tópico

• Prioridade: 10;

• História de usuário: Como um estudante, eu quero ser capaz de solicitar, através de algum tópico, N flashcards com as diversas palavras que fazem parte deste tópico para que eu possa ser capaz de ter informações sobre aquele tema de forma centralizada e formatada para o meu Anki;

• Critérios de aceitação: Dado que eu esteja logado e em uma sessão de estudos, quando eu informar que quero aprender o vocabulário de um determinado tópico, o Ankit deve me retornar uma lista formatada de flashcards com vocabulário diversificado sobre o tópico informado.

RF012: Encerrar Sessão de Estudo

• Prioridade: 8;

• História de usuário: Como estudante, eu quero ser capaz de finalizar a sessão de estudos de um determinado idioma no Ankit de maneira segura, para que eu possa realizar outra tarefa na plataforma;

• Critérios de aceitação: Dado que eu esteja logado e em uma sessão de estudos ativa, ao utilizar a navegação do site para encerrar a sessão, devo ver uma confirmação de que a sessão foi encerrada e ser redirecionado para outra página.

Detalhamento de Requisitos

RF-001 (Requisito Funcional Especificado: Criação de conta do usuário por meio da plataforma)

Descrição: O sistema deve permitir que usuários consigam criar contas, a partir de um formulário, no sistema sem depender de provedores de login.

Detalhamento:

• A partir da tela de login, o usuário que não tiver uma conta poderá utilizar a interface para ser direcionado ao formulário de criação de conta;

• O usuário irá preencher seus dados pessoais e de estudos de idiomas, sendo eles: nome completo; e-mail, senha, nível de escolaridade e nacionalidade;

• A conta do usuário será criada, e ele será levado à página principal do sistema.

Critérios de Aceitação:

1. Usabilidade: O formulário deve fornecer informações suficientes para o preenchimento correto dos campos, incluindo informações sobre erros do usuário e máscaras. Além disso, o formulário deve apresentar campo de confirmação de senha;

2. Segurança: O formulário deve possuir validação na parte do cliente.

RF-002 (Requisito Funcional Especificado: Criar uma conta utilizando login social do Google)

Descrição: O sistema deve permitir que os usuários consigam criar suas contas/logar no sistema a partir de sua conta Google.

Detalhamento:

• A partir da tela de login, o usuário clica no botão de realizar login/cadastramento da conta para que haja a autenticação pela Google;

• Se ele já tiver uma conta associada ao Ankit com o mesmo e-mail do Gmail, o usuário será informado que já existe uma conta com o e-mail utilizado;

• Se não houver uma conta associada ao Ankit, a conta do usuário é criada através da API da Google.

• O usuário é redirecionado a uma página de formulário de detalhamento de sua conta do Ankit, onde irá preencher seus dados para poder acessar a plataforma, sendo estes: nome completo, nível de escolaridade e nacionalidade;

• A conta do usuário será criada, e ele será levado à página principal do sistema.

Critérios de Aceitação:

1. Usabilidade: O formulário deve fornecer informações suficientes para o preenchimento correto dos campos, incluindo informações sobre erros do usuário e máscaras. Além disso, o formulário deve apresentar campo de confirmação de senha;

2. Segurança: O formulário deve possuir validação na parte do cliente.

RF-003 (Requisito Funcional Especificado: Associação de conta Google com conta já criada)

Descrição: O sistema deve permitir que um usuário que tenha criado um conta por meio do formulário da plataforma associe essa conta à sua conta Google, tornando possível que ele consiga fazer login com as duas contas.

Detalhamento:

• A partir da tela de perfil pessoal, o usuário poderá verificar o estado de associação a alguma conta Google;

• Caso esse estado indique que não há associação, o usuário poderá utilizar a interface, através de um clique de botão, que deseja fazer uma associação;

• Uma nova janela será aberta com o formulário de autenticação da Google, possibilitando o usuário a seleção da conta;

• A conta é associada àquela criada através da plataforma.

• Caso o usuário queira desassociar a sua conta do Ankit da sua conta Google, basta clicar no botão de remover a associação.

Critérios de Aceitação:

1. Usabilidade: A indicação de estado de associação não pode ser ambígua, permitindo que o usuário veja claramente se ela existe ou não; A associação ou desassociação deve ser realizada, no máximo, por 2 cliques (excluindo os da conta Google). Além disso, devem ser exibidos feedbacks informativos sobre erros;

2. Segurança: A conta Google não pode ser associada a 2 ou mais contas criadas por meio da plataforma.

RF-004 (Requisito Funcional Especificado: Atualizar dados pessoais e educativos)

Descrição: O sistema deve permitir que, uma vez que a conta do usuário seja criada, haja a possibilidade dele alterar qualquer dado -- desde que não seja o e-mail -- em sua página do perfil. São eles: o nome; a senha; o nível de escolaridade e a nacionalidade.

Detalhamento:

• Na página do perfil, o usuário poderá ir no(s) campo(s) do formulário onde está(ão) contido(as) a(s) informação(ões) que ele deseja alterar;

• Depois disso, basta clicar no botão de salvar alterações ou, no caso de redefinição de senha, ir para o link informado no e-mail.

Critérios de Aceitação:

1. Usabilidade: o formulário deve possuir máscaras e informações suficientes em seus campos para que o usuário consiga preenchê-lo da forma correta, evitando erros;

2. Segurança: O formulário deverá ser validado pelo cliente.

RF-005 (Requisito Funcional Especificado: Visualização de dados estatísticos de estudo pessoais)

Descrição: O sistema deve permitir que o usuário visualize um apanhado geral de seus dados de estudo na plataforma, contendo diversas informações sobre sua utilização do Ankit ao longo do tempo.

Detalhamento:

• Na página do usuário, o sistema deve apresentar a ele os seus dados sobre a utilização da plataforma, com a possibilidade de filtrar por: neste mês, últimos seis meses e neste ano;

• O sistema deve apresentar dados como: quantidade de sessões por idioma estudado; estimativa de quantidade de cards adicionados para cada idioma; ofensiva de dias na plataforma; e tempo total de estudo na plataforma, que é resultado do tempo decorrido de cada sessão de estudo iniciada e terminada.

Critérios de Aceitação:

1. Performance: O tempo de atualização das informações a partir do filtro deve ser rápido;

2. Usabilidade: A disposição das informações na interface deve ser feita da maneira mais clara possível, sem sobreposição de informações e de fácil identificação e leitura por parte do usuário.

RF-006 (Requisito Funcional Especificado: Estudo de vocabulário de um determinado idioma a partir de uma sessão de estudo)

Descrição: O sistema deve permitir que o usuário crie uma sessão de estudo de um idioma informado em seu cadastro, possibilitando a ele a solicitação da criação de um ou mais flashcards para o Anki.

Detalhamento:

• A partir da página principal, o usuário deve ser capaz de criar uma sessão de estudo por meio do clique de um botão e posterior seleção do idioma e um nome para a seção de estudo;

• Ao entrar na sessão de estudo, o usuário indicará ao assistente se ele deseja aprender sobre uma palavra ou um tema específico de vocabulário;

• O usuário irá digitar a palavra ou tópico sobre o qual deseja aprender;

• O usuário também deverá informar qual tipo de flashcard ele deseja utilizar: básico, intermediário ou avançado;

• O assistente irá devolver para o usuário modelos de flashcard para o Anki;

• O usuário irá informar se deseja realizar o download do arquivo comma separated values (CSV), contendo a informação de todos os cards para adição semi-automática ao Anki;

• O usuário também pode optar por copiar e colar os modelos e os arquivos para o seu Anki.

Critérios de Aceitação:

1. Usabilidade: A interação com o assistente deve ser feita de maneira análoga ao Chat GPT, com dados mais controlados antes do usuário informar realmente algo ao assistente; A interface deve ser projetada de modo que minimize o máximo possível os erros de prompt cometidos pelo usuário; Caso haja erros com os serviços utilizados, informar o usuário de maneira adequada, mantendo-o ciente dos problemas que são da aplicação;

2. Performance: O tempo de resposta do sistema a partir do prompt do usuário deve ser de, no máximo, alguns segundos.

RF-007 (Requisito Funcional Especificado: Exclusão de conta)

Descrição: O Ankit deve permitir que um usuário consiga realizar a deleção de sua conta, desde que haja uma cadastrada no sistema -- associada a sua conta Google ou não.

Detalhamento:

• Na página de perfil do usuário, ele deve conseguir excluir sua conta através de um botão. Apertar neste botão irá abrir um modal de confirmação;

• Para que haja a deleção de conta, o usuário tem que clicar no botão de confirmação de exclusão de conta.

Critérios de Aceitação:

1. Usabilidade: é obrigatório a inclusão de um modal para confirmar a exclusão da conta, visto que o usuário pode clicar sem querer no botão de deleção.

2. Segurança: Todos os dados relacionados a esse usuário deverão ser apagados do sistema.

Processo de Software Utilizado

O processo de software utilizado foi o Kanban, que atende bem às nossas necessidades, visto que o nosso time de desenvolvimento é composto de somente duas pessoas. Ele também nos permite visualizar o andamento das tarefas de maneira clara. Ainda, o Kanban nos dá a possibilidade de trabalhar com prazos mais flexíveis e que podemos ajustar à nossa rotina de modo que adapte o fluxo de trabalho ao tempo disponível, sem a complexidade de definir intervalos de implementação bem estabelecidos de outras metodologias como o Scrum. Como a nossa rotina é puxada, pensar no tamanho das tarefas e associar elas às suas sprints de forma adequada iria levar muito tempo e seria para um projeto muito simples.

Arquitetura de Software Utilizada

A arquitetura utilizada foi a baseada em objetos, em que cada objeto que compõe o sistema pode acessar o outro através de chamadas remotas. Ele foi escolhido para ser utilizado no Ankit por não ter hierarquia entre quais objetos outros objetos podem chamar, como mostra a imagem abaixo:

Isso significa que o Ankit pode realizar uma requisição/dar resposta a um usuário com o objeto/módulo que ele quiser. Assim, a orquestração de comunicação entre os diferentes módulos é organizada da forma que a equipe achar melhor para o sistema. No caso do Ankit, a comunicação com o ChatGPT, por exemplo, sempre será entre a API do Ankit e a API do ChatGPT devido ao tratamento dos prompts e respostas do e para o usuário; o banco de dados e a API de OAuth do Google também. Perceba que não se forma uma hierarquia, mas sim um intermediador (a API do Ankit) que centraliza os outros módulos que são utilizados no sistema.

Abaixo, é possível ver a arquitetura do sistema com os componentes mais concretos.

Padrões de Projeto

Foram utilizados os padrões de projeto Facade e Singleton. O Singleton foi utilizado sendo uma instância única da biblioteca axios, utilizada para consumo de APIs com algumas possíveis configurações que podem ser colocadas, como definir a URL base apenas uma vez: em seu instanciamento. Esse objeto criado é utilizado em todas as chamadas à API do Ankit. O Facade foi utilizado para encapsular a API do ChatGPT e facilitar a comunicação com o usuário do Ankit com a criação de funções auxiliares que removem todo o trabalho de “configuração” e comunicação do ChatGPT. Isso acontece por meio da utilização de templates de prompt na classe ChatGPT que absorvem a entrada do usuário – composta por simples palavras – e devolvem uma resposta pronta em forma de card com um template também escolhido pelo usuário (básico, intermediário ou avançado). Além disso, esta classe também fornece respostas baseadas em tópicos, o que implica o envio de uma quantidade X de cards; ou baseadas em uma única palavra.