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
DisciplinaeMateria, ouSimuladoeProvaSimulada). - Preferir
PascalCasepara componentes e tipos (ex.:SeuAndamentoSection,ModuloAtualCard,SimuladoChart). - Preferir
camelCasepara 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:
SeuAndamentoSectionModuloAtualCardDisciplinaListDesempenhoGeralSectionSimuladoChartRoteiroDeEstudosSectionEtapaSectionAtividadeCard
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.