🌍 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

2. Instale dependências PHP com Composer:

composer install

3. Copie e ajuste o arquivo de ambiente:

cp .env.example .env

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

4. Gere a chave de aplicação do Laravel (essencial para encriptação de sessão/cookies):

php artisan key:generate

5. 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.

6. 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.