1SanTi/survey-design-collector

Gerador de Sistema de Design de Questionários e Coleta Online

Transforme "uma necessidade de questionário" em um pacote triplo pronto para uso:

1. Questionário Word (formatação padronizada, imprimível, distribuível)
2. Site de respostas online (responda escaneando o QR code pelo celular, zero dependências, duplo clique para executar)
3. Painel de resumo de dados (gráficos estatísticos automáticos de cada pergunta + detalhamento + exportação Excel com um clique + QR code das respostas)

Fluxo completo com zero dependências de terceiros (apenas biblioteca padrão Python), o produto pode ser copiado para qualquer computador e executado diretamente.

---

Quando usar

• O usuário fornece uma gravação/áudio/texto e solicita "projetar um questionário" ou "projetar um questionário baseado na gravação".
• O usuário já tem perguntas e deseja criar um questionário online / site de respostas por QR code com coleta automática de dados.
• O usuário deseja uma solução completa de "questionário de pesquisa + estatísticas administrativas".

---

Fluxo de execução (SOP)

Passo 1 Obter e compreender a necessidade

• Gravação: primeiro, converta a gravação em texto usando fala para texto (skills como speech-to-text ou fetch do arquivo de áudio), extraia: tema do questionário, público-alvo, quantas seções (dimensões), perguntas específicas em cada dimensão, preferência de tipo (única/múltipla/escala/preenchimento).
• Texto: leia diretamente o esboço fornecido pelo usuário.
• Pontos incertos (como adicionar seção "Informações básicas", para qual unidade) complete por padrão e explique na entrega ou confirme com o usuário.

Passo 2 Escrever a especificação do questionário questions.json

Siga rigorosamente o formato de references/spec-format.md e escreva o questionário como JSON:

• Nível superior: title (título), subtitle, intro (mensagem inicial), footer, scale_options (cinco níveis da escala), sections.
• Em cada seção, questions[]: cada pergunta contém id, type, title, required; perguntas de opções contêm options.
• Tipos de pergunta: single (escolha única) ｜ multi (múltipla escolha) ｜ scale (escala, opções vindas de scale_options) ｜ text (preenchimento).
• allow_other: true adiciona automaticamente "Outro (especifique)"; exclusive: ["nunca usou"] indica que essa opção é mutuamente exclusiva com as outras.
• Sugestão: questionários formais geralmente incluem uma seção simplificada de "Informações básicas" (série / disciplina / tempo de ensino) para facilitar análises cruzadas posteriores.

Pontos de design: usar frases declarativas, evitar indução; opções exaustivas e mutuamente exclusivas; escala unificada; número de perguntas controlado para ser respondido em 3-5 minutos.

Passo 3 Gerar o pacote triplo com um clique

python3 scripts/build_survey.py --spec questions.json --out <diretório_de_saída>
# Se o URL final da página de respostas for conhecido, adicione --url http://xxx/ para gerar o QR code diretamente

Produto:

<diretório_de_saída>/
├── <Título do questionário>.docx          Questionário Word formatado
└── Sistema de questionário online/
    ├── server.py                          Página de respostas + painel + API (zero dependências)
    ├── questions.json                     Perguntas do questionário
    ├── Iniciar_Windows.bat / Iniciar_Mac_Linux.sh    Iniciar com um clique
    ├── make_qr.py                         Gerar QR code separadamente
    ├── vendor/qrcode/                     Geração de QR code embutida
    └── Manual de uso.md

Passo 4 Autoteste (obrigatório)

• Abra o arquivo Banco de perguntas/Sistema de questionário online/questions.json e confirme se perguntas, opções e marcações obrigatórias estão corretas.
• Execute o sistema uma vez para teste de fumaça:

  cd Sistema de questionário online && PORT=8123 python3 server.py &
  curl -s http://127.0.0.1:8123/ | head            # Página de respostas acessível
  curl -s -X POST http://127.0.0.1:8123/submit --data-urlencode "q1=..." # Enviar e armazenar
  curl -s http://127.0.0.1:8123/api/stats | head   # Estatísticas normais
  

• Verifique se no Word, cada pergunta e suas opções não foram quebradas por quebra de página (o script já definiu manter-junto).

Passo 5 Entrega e instruções de implantação

Explique ao usuário:

• Como usar cada um dos três componentes; o QR code é exibido automaticamente na página administrativa (http://IP_do_computador:8000/admin).
• Como os professores acessam: na mesma rede Wi-Fi, basta escanear o QR code (mais comum na escola); para acesso pela internet pública, é necessário colocar em um servidor com IP público.
• Consulte references/deploy-guide.md para texto que pode ser reutilizado diretamente.
• Use provide_file para entregar ao usuário o questionário Word e o pacote compactado do "Sistema de questionário online" para download.

Passo 6 (opcional) Arquivamento

Se necessário, use a skill upload-to-kb para armazenar o questionário Word e o pacote compactado do sistema no knowledge base especificado pelo usuário.

---

Pontos-chave e experiências

• Zero dependências é o diferencial principal: usa apenas biblioteca padrão Python + vendor/qrcode embutido; o usuário não precisa instalar nada com pip; A geração do Word requer python-docx (o ambiente de geração precisa tê-lo).
• A página de respostas é formulário HTML puro + pouco JS: o envio usa POST /submit; o servidor valida campos obrigatórios (itens faltantes são exibidos com o conteúdo preenchido e destacados em vermelho).
• QR code gerado em tempo real no servidor como SVG (/api/qr.svg?url=...); a página administrativa gera automaticamente o código com base no URL de acesso atual. Se o professor mudar de rede/URL, o código é regenerado, sem necessidade de reempacotar.
• Dados salvos em disco em data/responses.db (SQLite); backup = copiar o arquivo; limpar = deletar o arquivo.
• Se não for possível acessar pela rede local, 90% das vezes é porque o firewall do computador não permitiu o Python; avise o usuário para permitir.
• Se a porta estiver ocupada, use PORT=8080 python3 server.py para mudar a porta.

---

Estrutura de diretórios

survey-design-collector/
├── SKILL.md
├── scripts/
│   ├── build_survey.py    Geração com um clique (lê spec → Word + site + QR code)
│   ├── spec_to_word.py    Gera questionário Word a partir de `questions.json`
│   └── make_qr.py         Gera PNG QR code a partir de URL
├── assets/app/            Modelo do sistema de questionário online (server.py / scripts de inicialização / vendor/qrcode)
└── references/
    ├── spec-format.md     Especificação de `questions.json` + método de conversão de gravação para questionário
    └── deploy-guide.md    Modelo de implantação e instruções externas