📝 MarqueiCerto

Geração e correção óptica de questões de múltipla escolha

---

✨ Funcionalidades

• 📋 Cadastro de questões — múltipla escolha, V/F, associação, lacunas
• 📄 Geração de provas — preview HTML + exportação PDF (Typst / LaTeX / Pandoc)
• 🔍 Correção óptica — upload de gabarito escaneado, detecção automática com OpenCV
• 🌐 Multilíngue — interface e conteúdo em português e inglês
• 📱 PWA — aplicativo instalável com suporte offline
• 🔗 API REST — integração com frontends externos via JWT
• 📖 Documentação — MkDocs Material com diagramas e docstrings

---

🚀 Quickstart

Pré-requisitos

• Python >= 3.12
• Poetry >= 2.0
• OpenCV (instalado via Poetry)

Instalação

git clone https://github.com/user/marqueicerto.git
cd marqueicerto
poetry install
cp .env.example .env
poetry run flask --app marqueicerto.interfaces.web.app run

Acesse em http://localhost:5000

Para popular o banco com dados de exemplo:

poetry run flask --app marqueicerto.interfaces.web.app cli seed

---

🏗️ Build

Desenvolvimento

# Instalar com dependências de desenvolvimento
poetry install --extras dev

# Rodar linter e type checker
poetry run ruff check src/
poetry run mypy src/

# Rodar testes com cobertura
poetry run pytest

Documentação

poetry install --extras docs
poetry run mkdocs serve -f docs/mkdocs.yml    # http://localhost:8000
poetry run mkdocs build --strict -f docs/mkdocs.yml  # output em site/

Docker

docker compose up --build

---

📖 Exemplos

Criar uma questão via API

curl -X POST http://localhost:5000/api/v1/questions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "type": "multiple_choice",
    "difficulty": "easy",
    "tags": ["matematica", "algebra"],
    "title": { "pt-BR": "Quanto é 2 + 2?", "en": "What is 2 + 2?" },
    "explanation": { "pt-BR": "A soma de 2 e 2 é 4.", "en": "The sum of 2 and 2 is 4." },
    "alternatives": [
      { "text": { "pt-BR": "3", "en": "3" }, "is_correct": false, "position": 0 },
      { "text": { "pt-BR": "4", "en": "4" }, "is_correct": true, "position": 1 },
      { "text": { "pt-BR": "5", "en": "5" }, "is_correct": false, "position": 2 }
    ]
  }'

Gerar prova em PDF

# 1. Criar prova (seleção automática via filtros)
curl -X POST http://localhost:5000/api/v1/exams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": { "pt-BR": "Prova de Matemática", "en": "Math Exam" },
    "locale": "pt-BR",
    "selector": { "type": "multiple_choice", "difficulty": "easy", "limit": 5 }
  }'

# 2. Exportar PDF com Typst
curl -X POST http://localhost:5000/api/v1/exams/1/export \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "format": "typst" }' \
  --output prova.pdf

Corrigir gabarito escaneado

curl -X POST http://localhost:5000/api/v1/exams/1/correct \
  -H "Authorization: Bearer $TOKEN" \
  -F "scanned=@gabarito_escaneado.png" \
  -F "template_id=1"

# Resposta:
# {
#   "data": {
#     "score": 8.0,
#     "total": 10,
#     "responses": { "1": "A", "2": "C", ... },
#     "details": { "correct": [1,2,4,...], "wrong": [3,5] }
#   }
# }

---

🧪 Testes

# Todos os testes
poetry run pytest

# Com cobertura
poetry run pytest --cov=marqueicerto --cov-report=term-missing --cov-report=html

# Apenas unitários
poetry run pytest tests/unit/

# Apenas integração
poetry run pytest tests/integration/

# Testes específicos
poetry run pytest tests/unit/domain/test_models.py -k "test_question_creation"

Estrutura de testes

tests/
├── unit/
│   └── domain/           # Regras de negócio (models, services)
└── integration/          # Fluxos completos (geração → correção)

---

🔧 Stack

Camada	Tecnologia
Backend	Flask 3.0+
Banco	SQLAlchemy 2.0 + SQLite / PostgreSQL
Frontend	HTML + CSS + JS (SPA vanilla) + PWA
Visão	OpenCV 4.9+
PDF	Typst / LaTeX / Pandoc (Strategy Pattern)
API	REST + JWT (Flask-JWT-Extended)
i18n	Flask-Babel + mkdocs-static-i18n
Docs	MkDocs Material + mkdocstrings
Testes	pytest + pytest-cov + factory-boy
Qualidade	Ruff + mypy

---

🤝 Como Contribuir

1. Leia o guia — veja docs/pt-BR/desenvolvimento/contribuindo.md
2. Crie uma branch — git checkout -b feat/minha-feature
3. Siga os padrões:
   • TDD — escreva teste antes do código
   • Ports & Adapters — domínio puro, infra plugável
   • i18n desde o início — toda string passa por gettext() / t()
4. Rode as verificações:

   poetry run ruff check src/
   poetry run mypy src/
   poetry run pytest

5. Commit — mensagens claras no imperativo:

   git commit -m "feat: adiciona suporte a exportação LaTeX"

6. Abra um Pull Request — descreva o que mudou e por quê

Padrões de commit

Prefixo	Uso
feat:	Nova funcionalidade
fix:	Correção de bug
docs:	Documentação
refactor:	Refatoração de código
test:	Adição ou correção de testes
i18n:	Traduções
style:	Formatação (Ruff, whitespace)

---

📄 Licença

MIT © 2026 MarqueiCerto

---

🌐 Documentação completa

Acesse https://marqueicerto.dev para documentação completa com guias, referência da API e diagramas de arquitetura.

# Ou rode localmente
poetry run mkdocs serve -f docs/mkdocs.yml