Skip to content

Guia de Desenvolvimento

Padrões, ambiente e fluxo de trabalho para desenvolvedores

Guia de Desenvolvimento

Público-alvo

Desenvolvedores backend (PHP/Moodle) e frontend (JavaScript/TypeScript/Next.js).

Status

Em construção

Repositório e estrutura

  • Este repositório contém o plugin local_helico e documentação do projeto.
  • O plugin mod_unidade possui sua própria documentação (transposta em docs/ conforme aplicável).
  • Diretórios relevantes:
    • local/helico (código do plugin)
    • docs/ (documentação técnica e de produto)
    • ui/ (frontend, quando aplicável)

Padrões

  • Linguagem: PHP (Moodle), JS/TS no frontend (Next.js)
  • Estilo de código: seguir padrões do Moodle para PHP.
  • Documentação: Markdown, pt-BR, nomes kebab-case.

Convenções de nomenclatura (código)

Para reduzir ambiguidade no domínio e manter consistência no código, adotamos a seguinte regra:

  • Estrutura e UI em inglês: nomes de componentes e módulos técnicos devem usar inglês para termos arquiteturais e de interface, como Section, Card, List, Item, Header, Filters, Chart, Modal, Widget (evitar quando possível), etc.
  • Vocabulário de domínio em português (controlado): termos que representam entidades e/ou recursos centrais do sistema podem permanecer em português, de forma padronizada e sem variações.

Dicionário técnico (domínio em pt-BR)

Os termos abaixo são permitidos em nomes de código (componentes, tipos, rotas internas, hooks, etc.) quando representarem o conceito de domínio correspondente:

  • Área do Aluno
  • Seu Andamento
  • Módulo
  • Disciplina
  • Unidade
  • Trilha
  • Etapa
  • Atividade
  • Roteiro de Estudos
  • Simulado
  • Avaliações
  • Flashcards
  • Diagnóstico

Regras adicionais:

  • Não criar sinônimos (ex.: não alternar entre Disciplina e Materia, ou Simulado e ProvaSimulada).
  • Preferir PascalCase para componentes e tipos (ex.: SeuAndamentoSection, ModuloAtualCard, SimuladoChart).
  • Preferir camelCase para funções/hooks (ex.: useModuloContext, getDesempenhoPorModulo).
  • Componentes GLOBAL devem ter nomes mais genéricos (ex.: MetricCard, EmptyState, SectionHeader), evitando termos de domínio quando não forem estritamente necessários.

Exemplos:

  • SeuAndamentoSection
  • ModuloAtualCard
  • DisciplinaList
  • DesempenhoGeralSection
  • SimuladoChart
  • RoteiroDeEstudosSection
  • EtapaSection
  • AtividadeCard

Ambiente

  • PHP e extensões compatíveis com versão do Moodle utilizada.
  • Node.js LTS para frontend (se aplicável).
  • Banco de dados suportado pelo Moodle (MySQL/MariaDB, Postgres etc.).

Fluxo de trabalho

  • Planejamento e grooming no Jira.
  • Branches por feature e PRs com revisão de mantenedor.
  • Alterações grandes: abrir PR em rascunho.

Testes

  • Backend: testes unitários e integração (quando disponíveis); uso de fixtures para dados de Unidades/Trilhas.
  • Frontend: testes de componentes e e2e (a definir stack - Playwright/Cypress).

API

  • Contratos documentados em API e Integrações.
  • Versionamento de endpoints e schemas quando necessário.

Segurança e LGPD

  • Seguir boas práticas de autenticação/autorização do Moodle.
  • LGPD: políticas e logs/auditoria a definir.

Referências

Navigation

Type to search…

↑↓ navigate↵ selectEsc close