[Institucional] Framework de Mentorias

endersonmenezes commented 5 months ago

DoD: Planilha + Tema + Descrição

nome
dia
ela/veio ou nao
assunto
- Framework - Treinar novos mentores.
- Controle Geral de Mentorias Realizadas
- Controle de cada mentorado

Google Drive (Banco de Dados) -> Sheets / Data -> Resumo Mensal

causticsudo commented 5 months ago

Contexto

Entrando em uma discussão mais técnica... Estive refletindo sobre a necessidade de uma API ou qualquer outro entrypoint complexo para isso. Tenho boas ideias, mas não quero usar um canhão para matar uma formiga... Portanto, vou apresentar algumas dúvidas que tenho, com o objetivo de esboçar a solução de forma simples (mas não simplista) e suficientemente manutenível para que outras pessoas possam contribuir. A ideia aqui também é compreender melhor qual é o problema e como desejamos resolvê-lo, afinal, para evitar criar uma solução que não atenda às necessidades reais ou que não seja fácil de manter. Com isso em mente, separei algumas dúvidas e ideias iniciais:

Dúvidas:

Por onde quem realizará o cadastro da mentoria deve acessar isso? Pelo site da Codaqui? Com um DNS próprio? Na nuvem? No desktop, etc...
Preciso de alguma interface gráfica?
É necessário ter algum tipo de controle para quem ingere os dados através do app?
Onde desejo emitir esse relatório? Em qual formato?
Preciso deste framework apenas para gerar métricas ou também para melhorar a qualidade de vida do fluxo de mentoria? Notificações, integrações, adaptações, controle...

Ideia maneira hipermegacomplexa:

Ter uma API, CRUD básico integrado com o Google Sheets.
É possível criar uma camada de repositório que lide com N fontes de dados, utilizando cache, banco lógico e outras soluções de planilhas em nuvem, etc. Aqui é fácil generalizar.
Ter um contêiner que funcione como um tipo de worker, escutando e disparando webhooks: notificando celular, e-mail (por exemplo: SendGrid), etc.
- Evoluir isso para uma observabilidade madura é fácil, basta emitir os eventos para uma interface genérica de APM que lida com qualquer provedor: Datadog, Prometheus, Grafana, etc.
Ter outro contêiner que também funcione como worker, desta vez lidando com jobs e agendamentos para: gerar relatórios na virada do mês e notificar canais de comunicação: Telegram, Slack, etc.; expor métricas, etc.

Vantagens da implementação:

Escalável, pode ser conectado a qualquer outra solução ou fornecer funcionalidades mais complexas.
Solução interna da organização, tende a se tornar um produto interno.
Fácil de manter, tudo em um só lugar.
Aumenta a maturidade dos processos internos.
Tende a gerar menos retrabalho no médio/longo prazo.
Pode evoluir gradualmente, começando com uma versão inicial mais simples e amadurecendo conforme a necessidade dos mentores.

Desafios da implementação:

Se hospedado em um cluster, haverá custos, mesmo que mínimos (servless, function, etc.), tanto na infraestrutura quanto no aplicativo.
Se hospedado localmente, exige esforço do usuário para cadastrar a connectionString para o Google Sheets, executar o aplicativo e depender de variáveis internas do ambiente (sistema operacional) local, por exemplo: internet, poder de processamento, etc.
O protocolo HTTP é delicado, então deve ser executado em uma rede/nuvem interna da Codaqui. No caso de um DNS público, é necessário se preocupar com DDoS e autenticação, entre outros.
Mais tempo necessário para desenvolver.

Ideia simplona

Google Apps Script gerando relatórios, provavelmente em formato de tabela (tipo datalake). Não tenho certeza sobre a parte visual, talvez seja algo mais objetivo. Ou talvez a própria planilha consiga fazer isso, bastando mudar o intervalo e aplicar a fórmula do gráfico.
Google Forms para popular o Google Sheets.
Boa e velha planilha.

Vantagens da implementação:

Menos tempo necessário para desenvolver.
Não requer frontend ou políticas restritivas complexas.
Qualquer pessoa pode realizar a manutenção.
Custo zero ou quase zero (creio que já deve estar incluído no pacote do Google).
Curva de aprendizado menor.

Desafios da implementação:

Qualquer pessoa pode realizar a manutenção 😆.
Não tende a escalar e é difícil manter um bom versionamento.
Operações mais básicas.
Altamente substituível por soluções mais genéricas, baratas ou gratuitas do mercado.
Não agrega valor a médio/longo prazo para a organização.
Grande esforço necessário para migrar para outra plataforma.

@endersonmenezes dá uma olhadinha aqui pra vê se eu tô viajando muito

endersonmenezes commented 5 months ago

Fala @causticsudo !

Acredito que você nos deu o caminho da perfeição.

Respondendo suas dúvidas

Por onde quem realizará o cadastro da mentoria deve acessar isso? Pelo site da Codaqui? Com um DNS próprio? Na nuvem? No desktop, etc...

O mentor e o mentadora vão continuar usando e-mail/calendário, acho que isso é um ponto legal que ensinamos. As mentorias podem ser realizadas via Meeting ou via Discord, conforme ambos preferirem.

Preciso de alguma interface gráfica?

Como vamos criar o processo imagino que não, eu pensei em um Sheets onde todos os mentores têm acesso e precisam colocar alguns dados de suas mentorias para que a gente que se reúne com mais frequência tenha noção do que está acontecendo, e quero voltar a termos acompanhamento de um(a) pedagogo.

É necessário ter algum tipo de controle para quem ingere os dados através do app?

Talvez no Sheets em abas, sendo a aba que tem informações confidenciais somente acessada pelo proprio mentor e o "conselho".

Onde desejo emitir esse relatório? Em qual formato?

Manualmente sendo feito buscas mesmo, conforme ficar padrão o relatório a gente coloca no nosso projeto de dados. Uma extração limpa de dados pessoais.

Preciso deste framework apenas para gerar métricas ou também para melhorar a qualidade de vida do fluxo de mentoria? Notificações, integrações, adaptações, controle... Por enquanto não, mas legal pensar nisso por que creio que vai surgir.

Será que o Google Apps Script é gratuito no plano Education?
A Ideia maneira hipermegacomplexa não se encaixaria no projeto do Tutor que estamos montando?
Como temos Desafios da implementação: o caso de Não tende a escalar e é difícil manter um bom versionamento., será que com um repositório privado, não conseguimos nos organizar?

causticsudo commented 4 months ago

Será que o Google Apps Script é gratuito no plano Education?

Deve ter algum ratelimit, mas é gratuito pra geral

A Ideia maneira hipermegacomplexa não se encaixaria no projeto do Tutor que estamos montando?

Batemos no sync, mas aqui eu acho eu não. Acho que o tutor tá num nível mais de acesso conjunto, pensei inicialmente em algo mais administrativo um worflow pra gente conseguir coletar métricas, fornecer funcionalidade pro processo em si. Mas assim, acho completamente plausível uma ferramenta plugar na outra, ou funcionarem do forma conjunta... Mas por segregação de responsabilidade, talvez faça mais sentido ser separado, pelo menos agora.

Como temos Desafios da implementação: o caso de Não tende a escalar e é difícil manter um bom versionamento., será que com um repositório privado, não conseguimos nos organizar?

Talvez isso seja uma complexidade a mais, tu garantir o versionamento "saudável" de algo que está espalhado pela plataforma do google dentro de um repo deve ser algo chatão de fazer, e com pouco ganho também. Agora, a ideia do que a gente quer fazer aqui sim, de fato conseguimos organizar no gh, dá até pra trabalha com merges reativos, que disparam functions e atualizam algum valor em algum lugar, por aí vaí (mas isso só sobre os cenários onde é feito pelo fluxo certinho, abrindo pr, aprovando, mergeando, changelog e zás).

Bom, pra gente sair do zero, eu criei uma planilha no sheets pra gente ter uma noção de informação e o que que a gente quer fazer com elas. @endersonmenezes Depois dá uma bizóiada lá e vai comentando/ajustando no que for necessário.

Quanto a PoC, fiz uma apizinha, simplona, recebendo um valor e jogando numa planilha qualquer do sheets, man molezinha. Hospedar n é um problema, tem uns raspberry em algum lugar por aqui :laughing:. Vou passar a PoC pra uma solution organizada, ou um repo e depois a gente vê onde vai deixar isso ai.

Enquanto a poc está em andamento, é tranquilão deixar uma v0 rodando no appScripts. só precisamos bater o que é necessário pra essa v0.

causticsudo commented 4 months ago

causticsudo commented 2 months ago

@endersonmenezes Vamos precisar ver a parte de autenticação com essa API dos caras: https://developers.google.com/workspace/guides/configure-oauth-consent?hl=pt-br

Em paralelo à isso, eu já vou ir criando o repo aqui do nosso lado, pq já tem coisa que dá pra colocar em vigor.

causticsudo commented 2 months ago

Infelizmente, parece que não é de graça essa api do sheets :/

https://console.cloud.google.com/projectselector2/apis/dashboard?authuser=2&hl=pt-br&organizationId=96659947336&supportedpurview=project

Acredito que vamos ter que mudar a abordagem, por hora vamos manter local (versionando no repo mesmo) eu vou deixar um csv ou arquivo parecido e gente depois importa pro sheets via appScript, vou pensar numa maracutaia boa mas isso não trava a gente.

causticsudo commented 2 months ago

@endersonmenezes Depois dá uma olha na doc desse pr:https://github.com/codaqui/mentoria-framework/pull/1 Vamos começar a dar mais contexto pra isso pra eu ir definindo os entregáveis.

Se puder depois dá uma olhada nas configs do repo em si e vê se falta fazer alguma coisa

renanceratto commented 2 months ago

@endersonmenezes @causticsudo , gostaria de contribuir com isso:

Para interface, não poderíamos usar o AppSheet? Ele dá uma interface e a base de dados é uma planilha. É melhor do que deixar o acesso direto à planilha.

Sobre o controle de dados é importante ressaltar, até onde eu sei, não é possível controlar acesso à abas de planilhas no Google Sheets. Você pode controlar permissão de edição de cada aba, mas não consegue definir quem poderá ver uma aba. Quem vê a planilha, vê tudo. Por este motivo sugiro que dados sensíveis sejam armazenados em arquivos específicos.

Sobre os relatórios, podemos usar o Looker Studio, conectando no Sheets e gerando os indicadores. É possível agendar envio dos indicadores por email, definindo os remetentes e os filtros que serão usados.

Exemplo do looker que fiz aqui Captura de tela de 2024-08-26 23-08-14

renanceratto commented 2 months ago

Abri o appsheet com aquela planilha. Ele já montou uns campos automaticos. Podemos personalizar se acharem que faz sentido partir pra esse lado Exemplo aqui

causticsudo commented 2 months ago

@renanceratto Fala aí, man! Beleza? Muito obrigado pelas sugestões; ajudaram bastante no desenvolvimento da ideia!

Acredito que a ideia é boa, especialmente no curto prazo. O bom é que tudo está próximo, o que facilita a configuração. A maneira como esses dados serão consumidos não é um problema; podemos transitar entre várias soluções nesse aspecto.

A vantagem de ter todo o seu workflow no Google é que é muito fácil integrar as ferramentas. No entanto, como não existe almoço grátis, há um limite considerável de extensão. Sempre que precisamos expandir um pouco mais, isso implica em "$$$$". Portanto, a médio e longo prazo, eu consideraria migrar para uma solução baseada em funções, scripts, etc., algo que ofereça mais controle e escalabilidade em termos de comportamento. Mas, por enquanto, acho que o caminho é esse mesmo. Inclusive, se não me engano o @endersonmenezes já tinha comentado sobre isso comigo.

Sobre a ideia do Looker, achei muito bacana. Eu não conhecia muito bem, mas vai ajudar bastante nos envios, especialmente se pudermos enviar para outros canais além do e-mail (Discord, por exemplo). No entanto, isso não é um problema, já que é possível criar schedulers no AppScript também.

Quanto ao ponto de segurança, eu também havia pensado em algo semelhante. Atualmente, o acesso à planilha está liberado para todos porque estávamos definindo quais informações seriam necessárias, e o esquema ainda não está 100% fechado. Estou fazendo alguns testes para determinar o que será possível utilizar como info. Mais para frente, a planilha será bem restritiva em todas as páginas. Se precisarmos de uma visualização ou algo mais editável, podemos replicar os dados em outro bucket sem alterar a fonte da verdade, criando algo semelhante a projeções. No entanto, também não vejo o armazenamento dessas informações no Sheets por muito tempo; há vários problemas nessa abordagem, especialmente quando o volume de dados é alto e quando é necessário realizar alguma migração.

@renanceratto Quando eu finalizar o workflow de inserção e manipulação de dados na planilha, acho que poderemos começar a focar na parte de dashboard. Se você quiser, podemos marcar uma conversa nas próximas semanas para discutir isso. O que acha?

renanceratto commented 2 months ago

@causticsudo bora. Prefere durante o dia ou fora do horário de expediente? (por mim tanto faz) Combinamos lá pelo whatsapp

causticsudo commented 2 months ago

@causticsudo bora. Prefere durante o dia ou fora do horário de expediente? (por mim tanto faz) Combinamos lá pelo whatsapp

@renanceratto Pra mim funciona melhor no período da noite, ultimamente tá pegado pra mim lá no trampo :c

@endersonmenezes Man, tive estudando as formas de versionar o script e mantê-lo dentro do repositório e, até agora, encontrei duas abordagens. Ainda não fiz PoC de nenhuma delas; é mais em prol da discussão mesmo.

Usando o Github Actions

Para chegar ao resultado esperado, será necessário:

Criar um Workflow no Actions que seja reativo a merges com alterações em arquivos .js
Importar o clasp para fazer a chamada no AppsScript depois do merge
Configurar as credenciais no Google Cloud Console. Eles geram um JSON e é esse que precisamos colocar no Github Secrets
Sempre que tiver um merge na main, a action vai atualizar o AppsScript.

Pontos positivos dessa abordagem:

Mais seguro e fácil de dar manutenção na camada de segurança; também é possível versionar essas alterações de credenciais.
É extensível e pode ser usada para realizar outras tarefas dentro do nosso workspace.
Versionamento dos próprios arquivos .js
Flexibilidade de rollback
Podemos criar um esquema de "aprovações", colocamos apenas adms do repo pra ter permissão de aprovar ou recusar a execução da action. Fiz isso em um repo privado meu, acho que dá pra usar como exemplo.
Possibilidade de encaixar Quality Gate; podemos estender a action para rodar testes unitários, validadores de YAML, lint, etc.
Facilidade para migração, trocar de nuvem, mudar de plataforma, soluções, e por aí vai.

Problemas dessa abordagem:

Demanda mais tempo para implementar, testar e documentar. Mesmo não sendo uma diferença gritante de complexidade, tem uma curva de implementação consideravelmente mais extensa.
Estender o workflow para funções mais complexas pode exigir custos adicionais no GCP
Lógica mais granular
Para bater no Google Console, existe um rate limit de chamadas, o que também pode gerar custo. No nosso caso, pode ser algo bem pontual e que vai mudar talvez de mês em mês, mas um único deslize pode acabar gerando custo acidentalmente.
Se não me engano, também existe um limite de execuções no Actions; não lembro se é por minuto ou por execução.

Fazendo checkout do .js e fazendo o eval

Para chegar ao resultado esperado, será necessário:

Ajustar o AppsScript para fazer uma chamada HTTP no arquivo .js da main
Fazer o eval() no arquivo carregado
Chamar o método para a respectiva necessidade: fazer uma inserção na linha ou mudar o estado de uma existente para cancelado

Pontos positivos dessa abordagem:

Mais fácil de implementar; demanda menos tempo de estudo e teste.
Risco nulo ou quase nulo de gerar custos adicionais
Lógica centralizada

Problemas dessa abordagem:

O eval por si só é muito problemático; inclusive, muitas documentações alertam isso como "enorme risco de segurança"
É mais complicado de rastrear e consolidar informações para auditar as versões.
Mais esforço para manter e supervisionar a camada de segurança.
Lógica não reaproveitável
Não tem muitas possibilidades de extensão :c
Fácil de alterar, menos etapas de validações, e a visibilidade das mudanças também não é muito boa.

endersonmenezes commented 2 months ago

TL;DR

Sheets -> Banco de Dados Workflow GitHub -> CI/CD AppSheet -> Frontend Looker -> Relatórios

https://github.com/codaqui/mentoria-framework/pull/1

renanceratto commented 1 month ago

Painel de indicadores

Filtros:

Período (Datas De-Até)
Status (Por padrão, considerar apenas status de mentoria concluída)

Indicadores

Mentorias: [Número] Quantidade de mentorias realizadas
Horas de mentoria: [Número] Soma do tempo das mentorias realizadas
Mentores: [Número] Total de mentores que realizaram mentoria
Mentorados: [Número] Total de participantes das mentorias
Horas de mentoria e pessoas mentoradas por tempo: [Gráfico de barras/linha] 2 séries mostrando a quantidade de horas e a quantidade de pessoas mentoradas por mês
Taxa de Ocupação: [Número] % de horários ocupados

causticsudo commented 1 month ago

tl; dr

Avançamos bastante no fluxo de upsert na planilha com a ajuda do @renanceratto. Já está funcionado certinho. Vou precisar fazer algum ajuste pois estamos inserindo as calls de segunda tb.

Quanto ao funcionamento da action, estou enfrentando um problema de autenticação com o clasp, o erro é de contrato do json. Ainda to pesquisando como é o contrato esse troço. Mas já atualizei o pr com as evidências de configuração.

renanceratto commented 1 month ago

Sobre a call de segunda, contanto que o calendar da mentoria não esteja na call de segunda, não vai ter problema. Imagino que o mentoria@codaqui.dev não esteja como convidado dessa call Precisamos, na verdade, ver como colocamos o calendar do mentoria no acionador do app script. mentoria é um grupo, certo? Posso pesquisar como fazer isso

endersonmenezes commented 1 month ago

Mentoria é uma conta, pode pegar a senha comigo ou com o @causticsudo também!

causticsudo commented 3 weeks ago

Trazendo um update mais atual do status do fluxo de via gh actions:

Na quarta-feira consegui falar com um chapinha que encontrei por aqui pelo gh. Vi que ele já tinha usado a ferramenta em um repo dele, e pedi uma ajudinha. O que está rolando é que não consigo fazer a auth apenas com o RefreshToken, infelizmente vamos ter que usar alguma api pra gerar esse token de acesso temporário, e isso era o que eu temia, é a partir de comportamentos assim que começam a vir custos.

tl;dr - precisamos mudar a abordagem de auth via actions e adicionar mais uma api no projeto da codaqui pra consegui gerar esse token de acesso. A ferramenta não está aceitando o refresh token (token que é gerado uma vez só)

AppSheets - ainda não consegui olhar pra isso

@renanceratto Tb ainda não consegui ler com calma seu comentário, mas tá no radar!

endersonmenezes commented 3 weeks ago

@causticsudo @renanceratto quais as pendências.

renanceratto commented 3 weeks ago

@causticsudo @renanceratto quais as pendências.

@endersonmenezes na parte do script de inserção do evento basta apenas tratar o cancelamento do evento.

Pretendo trabalhar com isso após o dia 25/10 quando acaba a feira e volto pra Maringá.

renanceratto commented 1 week ago

@endersonmenezes @causticsudo App criado e sendo possível ver/editar os meus mentorados e as minhas agendas. Dentro da agenda tem o link das mentorias, sendo possível criar registros de mentoria. Cada mentoria tem o campo de anotações https://www.appsheet.com/start/5f848f70-92e3-49d9-9e7c-838acd3e7b99

causticsudo commented 1 week ago

Foi mal, galera. Fico atualizando o pr lá e esqueço da issue aqui. Mas basicamente deu mt bom o fluxo via ci/cd, inclusive já está funcional.

Tl;dr:

Políticas de branch protection do repositório e v0 de quality gate :heavy_check_mark:
Configuração do projeto / google console :heavy_check_mark:
Implantação do AppScript e configuração com os acionadores :heavy_check_mark:
Configuração de autenticação da Apps Script Api com o Google Console :heavy_check_mark:
Workflow de ci/cd com versionamento, deployment e aprovação :heavy_check_mark:
Fluxo de Upsert/Persistência funcional, com algumas brechas para melhoria :heavy_check_mark:
Export e consumo de dados via dashboard, com algum indicadores em progresso, mas o core já está funcional :heavy_check_mark:

Pull request aguardando revisão para seguir com merge:

https://github.com/codaqui/mentoria-framework/pull/1/files

Status:

No momento eu tô repaginando toda a doc, mas tô pensando em quebrar isso em uma issue a parte, mas já está em progresso, vai nesse pr ainda.
Agora que consegui sair mais da integração dos componentes em si, vou colar com o @renanceratto pra ver com oq eu posso contribuir com os indicadores do dash, mas acredito a estrutura tá basicamente pronta pelo oq eu vi, é mais aprimorar mesmo =)

codaqui / institucional