codemeistre/docs

:page_with_curl: Mantém artefatos para fins documentativos públicos do ecossistema do CodeMeistre.

docs's Issues

Automatizar processo de atualização do conteúdo que vai pro GitHub Pages

Atualmente, o dev que quer adicionar algum diagrama documentativo neste repo, precisa:

1. desenhar um diagrama em alguma ferramenta externa;
2. baixar um arquivo que codifica esse diagrama (pra facilitar futuras alterações nele), nessa ferramenta, e adicioná-lo no diretório apropriado (vide o README.md);
3. baixar uma versão em SVG (ou PNG, como fallback) do diagrama criado, com o mesmo nome (sem a extensão) mas com o sufixo .svg (ou .png), e deixá-lo ao lado do arquivo obtido na etapa anterior;
4. atualizar o respectivo README onde o diagrama viverá, para adicionar um hiperlink para ele na listagem de diagramas.

Seria interessante ter algum script (leve e fácil) neste repo para automatizar as etapas 3 e 4, de alguma forma. Visando as ferramentas externas já conhecidas, já que a produção do SVG/PNG dependerá delas. Dessa forma, a sincronia entre o 'código' do diagrama e sua representação visual será mais confiável.

Melhor ainda: um script que usa o Git para detecar e atualizar todos as imagens (SVG ou PNG) e links nos README (se já não tiver) que foram alterados.

Usar a CLI: https://github.com/mermaid-js/mermaid-cli

Remover o diagrama do esquema corrente do BD

Uma vez que a lib typeorm-uml parece não estar mais sendo mantida, não faz mais sentido manter este diagrama já que era gerado a partir da referida biblioteca.

Contudo, há uma PR em aberto que faz a migração para o TypeORM v0.3.0:

1. eugene-manuilov/typeorm-uml#56

Podemos observá-la e verificar algum tipo de posicionamento do autor. Caso o mesmo não responda, creio que remover o diagrama do esquema corrente do BD seja o ideal.

Versionar os diagramas por meio da mensagem de commit

Motivação

Com isso, será possível comparar as modelagens desenvolvidas neste repositório.

Como fazer

Basicamente, basta obter o código gerado do diagrama pelo plantuml e colocá-lo como uma mensagem do commit.

Observação

Por motivos de segurança, seria ideal criptografar o código utilizando hash md5, por exemplo.

Melhorar a documentação dos fluxos de dados e dos fluxos de trabalhos dos sistemas do CodeMeistre

Enhancement Request

Pode-se usar este diagrama de sequência como inspiração.

Olhar o sumário das funcionalidades do CodeBench, e a lista de funcionalidades que o front-end implementou

---

Como forma de facilitar o entendimento operacional sobre o backend da plataforma, faz-se necessário documentar as seguintes operações (ou fluxos), e registrá-los neste repositório:

A lista abaixo será preenchida sob demanda

• login quando um usuário está desativado ¹
• professor envia convites de cadastro de novos alunos
• usuário recupera sua senha
• usuário define uma nova foto de perfil ²
• anônimo se cadastra como um usuário (aluno), via link de convite emitido previamente por um Staff que foi enviado para seu endereço de e-mail
• professor cria um trabalho ³
• professor adiciona um material didático em sua turma
• usuário ativa⁴ e desativa⁵ a tela de bloqueio (lockscreen)
• usuário interage com a IDE; workflow da autenticação e autorização
• aluno acessa um exercício de sua turma
• aluno submete sua solução, que está correta
• aluno invoca um teste da sua solução, que está correta
• ...

Footnotes

1. https://codemeistre.github.io/docs/mermaid-diagrams/auth/login_when_user_is_deactivated.svg ↩

2. https://codemeistre.github.io/docs/drawio-diagrams/user/upload_new_avatar.svg ↩

3. https://codemeistre.github.io/docs/mermaid-diagrams/work/staff_create_work.svg ↩

4. https://codemeistre.github.io/docs/mermaid-diagrams/auth/lock_session.svg ↩

5. https://codemeistre.github.io/docs/mermaid-diagrams/auth/unlock_session.svg ↩