Skip to content

README.md

Latest commit

 

History

History
111 lines (75 loc) · 4.32 KB

README.md

File metadata and controls

111 lines (75 loc) · 4.32 KB

Logo

🌍 Read this in English

Aplicação pronta para gerar, exportar e imprimir listas de exercícios de matemática.

✅ Sobre o projeto

MathX é um gerador de exercícios matemáticos construído com Laravel. O usuário seleciona as operações (adição, subtração, multiplicação e divisão), define o intervalo de números, informa a quantidade de exercícios e o sistema gera uma lista que pode ser visualizada, impressa ou exportada para .txt.

O projeto segue uma organização simples baseada em Controller → Services → Models → Views (Blade).

🚀 Funcionalidades

  • Geração de exercícios com operações básicas: soma, subtração, multiplicação e divisão.
  • Controle do intervalo (mínimo e máximo) dos operandos.
  • Escolha da quantidade de exercícios (5 a 50).
  • Armazenamento temporário dos exercícios na sessão do Laravel.
  • Impressão direta via rota de "print".
  • Exportação para arquivo .txt via rota de export.

🛠 Tecnologias e convenções

  • PHP (recomendado 8.x)
  • Laravel (Blade para views)
  • Bootstrap (assets estáticos estão no projeto)
  • Composer para gerenciamento de dependências

Estrutura principal observada no código:

  • app/Http/Controllers/MainController.php — lógica das rotas públicas e integração com os serviços.
  • app/Services/ExerciseGeneratorService.php — gera exercícios.
  • app/Services/ExerciseExporterService.php — formata saída para .txt.
  • app/Services/ExerciseSessionService.php — valida e recupera exercícios da sessão.
  • app/Models/Exercise.php — modelo simples que representa um exercício.
  • routes/web.php — rotas (home, generateExercises, exportExercises, printExercises).
  • resources/views/ — arquivos Blade (layouts, home, operations, etc.)

📥 Instalação (passo a passo)

  1. Clone o repositório:
git clone https://github.com/jprogram-php-projects/MathX.git
cd MathX
  1. Instale dependências PHP com Composer:
composer install
  1. Copie e ajuste o arquivo de ambiente:
cp .env.example .env

Edite o .env se precisar (por exemplo: APP_NAME, APP_URL).

  1. Gere a chave de aplicação do Laravel (essencial para encriptação de sessão/cookies):
php artisan key:generate

  1. Se não estiver usando base de dados neste projeto, não é necessário rodar migrations. Caso acrescente features com DB, configure as variáveis do .env e execute php artisan migrate.

  2. Inicie o servidor local:

php artisan serve

Abra http://127.0.0.1:8000 no navegador.

⚙️ Observações importantes para rodar corretamente

  • Renomeie .env.example para .env antes de gerar a chave (php artisan key:generate).
  • O projeto usa sessão para armazenar os exercícios; certifique-se de que a configuração de sessão do Laravel funciona no seu ambiente (driver file funciona por padrão).
  • Arquivos estáticos (CSS/JS/imagens) são servidos via public/assets/... e as blades usam asset('assets/...') para referenciá-los.
  • As views são em Blade. O layout principal (layouts.main_layout) contém referências a Bootstrap e ao arquivo main.css.

🧭 Como funciona — visão rápida do fluxo

  1. Usuário acessa a rota / (home) e envia o formulário com operações, intervalo e quantidade.

  2. MainController::generateExercises valida a requisição e chama ExerciseGeneratorService.

  3. Exercícios são gerados e armazenados em sessão (session(['exercises' => $exercises])).

  4. Usuário pode:

    • Visualizar a lista gerada na view operations.
    • Baixar um .txt através de exportExercises (usa ExerciseExporterService).
    • Imprimir via printExercises, que exibe as questões e, abaixo, as soluções.

💡 Sugestões de melhorias (roadmap curto)

  • Adicionar opção de configurar casas decimais para divisões.
  • Permitir filtros por tipo de operação ao exportar/visualizar.
  • Adicionar testes unitários/feature para ExerciseGeneratorService e MainController.
  • Internacionalização (i18n) das views.
  • Melhoria atual: criação de testes com PHPUnit.

🧩 Contribuindo

  1. Fork e clone o repositório.
  2. Abra uma branch com uma feature ou correção: git checkout -b feat/nome-da-feature.
  3. Faça commits pequenos e descritivos.
  4. Abra um Pull Request explicando o que foi alterado.