buBailai/quickform-ferramenta-de-ensino

Skill de Criação de Ferramenta de Ensino Interativa com QuickForm

Visão Geral

Esta skill ajuda professores a criar rapidamente ferramentas de ensino interativas em HTML profissionais, conectando-se automaticamente à plataforma de coleta de dados QuickForm e gerando, ao final, um painel de visualização de dados para análise. O processo completo é realizado em 8 etapas.

---

Etapa 1: Confirmar Versão e Conta do QuickForm

Perguntar ao usuário qual versão usar

Pergunte ao usuário:

"Qual versão do QuickForm você gostaria de usar?

• A. Versão Oficial (https://quickform.cn)
• B. Versão Local (versão implantada em rede local)"

Tratamento da Versão Oficial

1. Verifique se o arquivo de cache de credenciais ~/.claude/quickform_credentials.json existe:

   cat ~/.claude/quickform_credentials.json 2>/dev/null
   

2. Se o arquivo existir e contiver official.username e official.password, leia e use diretamente, sem perguntar novamente, informando ao usuário "Usando a conta salva anteriormente: xxx"
3. Se não existir, pergunte ao usuário o usuário e senha da conta oficial, obtenha e salve no arquivo de cache:

   {
     "official": {
       "username": "conta fornecida pelo usuário",
       "password": "senha fornecida pelo usuário"
     }
   }
   

   Escreva com bash: echo '{"official":{"username":"xxx","password":"xxx"}}' > ~/.claude/quickform_credentials.json

Tratamento da Versão Local

1. Conta padrão: wst, senha padrão: quickform (valores padrão de fábrica para implantação local, permanecem inalterados)

2. Obter endereço local automaticamente (tentar na seguinte ordem de prioridade):

   Primeiro passo: Verificar se já existe um endereço salvo

   cat ~/.claude/quickform_credentials.json 2>/dev/null
   

   Se o JSON já contiver o campo local.base_url, use-o diretamente, informando ao usuário "Usando o endereço local salvo anteriormente: xxx", e pule as etapas seguintes.

   Segundo passo: Detectar automaticamente o IP da máquina + porta 5001 Se não houver endereço salvo, use Python para obter o IP da rede local da máquina:

   import socket
   s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
   s.connect(("8.8.8.8", 80))
   local_ip = s.getsockname()[0]
   s.close()
   print(local_ip)
   

   Combine como http://<local_ip>:5001 e verifique se está disponível:

   curl -s -o /dev/null -w "%{http_code}" http://<local_ip>:5001/
   

   • Se retornar 200 ou 302: Informe ao usuário "Endereço local detectado automaticamente: http://<local_ip>:5001, em uso" e salve no arquivo de credenciais
   • Se a conexão falhar: Vá para o terceiro passo

   Terceiro passo: Detecção automática falhou, perguntar ao usuário para inserir manualmente

   O endereço de detecção automática http://<local_ip>:5001 não pode ser acessado. Por favor, insira manualmente o endereço de acesso do QuickForm local
   (por exemplo: http://192.168.1.100:5001):
   

   Após obter a entrada do usuário, verifique novamente e, se aprovado, salve.

   Salvar endereço no arquivo de credenciais:

   python3 -c "
   import json, os
   path = os.path.expanduser('~/.claude/quickform_credentials.json')
   try:
       d = json.load(open(path))
   except:
       d = {}
   d.setdefault('local', {})['base_url'] = 'http://endereco_final_confirmado'
   json.dump(d, open(path, 'w'), ensure_ascii=False)
   print('Endereço salvo')
   "
   

3. Pergunte ao usuário: "O serviço QuickForm local já foi iniciado? Se não, por favor, inicie-o primeiro."

Todas as referências ao endereço local nas etapas subsequentes usarão a variável LOCAL_BASE_URL (obtida do fluxo acima), não sendo permitido codificar o IP diretamente.

---

Etapa 2: Conhecer o Estilo de Design da Ferramenta de Ensino

Pergunte ao usuário (forneça opções como guia, permita descrição livre):

"Por favor, escolha o estilo de design para a ferramenta de ensino (pode ser múltipla escolha ou descrição própria):

1. 🎨 Estilo Moderno e Limpo — Layout de cartões, cores suaves, adequado para a maioria dos cenários
2. 🌈 Estilo Gradiente Vibrante — Gradientes vivos, efeitos dinâmicos, adequado para aulas animadas
3. 🌙 Estilo Escuro — Fundo escuro, cores fluorescentes, adequado para cursos com temática tecnológica
4. 🎠 Estilo Infantil — Arredondado e fofo, cartoon brilhante, adequado para séries iniciais do fundamental
5. 📊 Estilo Acadêmico Sério — Profissional e organizado, orientado a dados, adequado para ensino médio ou universidade
6. 🖌️ Personalizado — Descreva o estilo desejado"

Pergunte também:

• Faixa etária/série (ex: 3º ano do fundamental, 2º ano do ensino médio, ensino superior)
• Disciplina (ex: Português, Matemática, Inglês, Ciências, Informática, História, etc.)

---

Etapa 3: Coletar Requisitos Específicos da Ferramenta de Ensino

Esta etapa precisa coletar informações suficientemente detalhadas antes de iniciar o desenvolvimento. Deve abranger as três dimensões a seguir:

3.1 Requisitos de Interação

Deve ser claramente definido:

• Qual é a funcionalidade central da ferramenta de ensino (votação/questionário/teste/registro de experimento/envio de trabalho/discussão/exercícios gamificados, etc.)
• Como os alunos interagem com a ferramenta (clicar em opções/preencher texto/arrastar/desenhar/responder com cronômetro, etc.)
• É necessário feedback imediato (mostrar certo/errado/explicação após responder)

Se a descrição do usuário for vaga, pergunte ativamente:

"O que você espera que os alunos façam nesta página? O que eles verão após concluir?"

3.2 Campos de Submissão de Dados

Deve ser claramente definido cada campo a ser coletado:

• Nome do campo (chave em inglês, para a API)
• Significado do campo (descrição em português)
• Tipo do campo (texto/número/opção/tempo, etc.)

Se o usuário não mencionar os campos, guie-o:

"Quais informações dos alunos você gostaria de coletar? Por exemplo: nome do aluno, turma, opção de resposta, pontuação, tempo gasto, etc. Por favor, explique um por um."

Formato de exemplo de campo (para referência, o requisito real do usuário prevalece):

student_name: Nome do aluno (texto)
class: Turma (texto)
answer: Opção de resposta (A/B/C/D)
score: Pontuação (número)
duration: Tempo gasto em segundos (número)

3.3 Requisitos de Análise de Dados/Painel de Visualização

Deve ser claramente definido:

• Quais gráficos deseja ver (barras/pizza/linhas/nuvem de palavras/ranking, etc.)
• Dimensões estatísticas dos dados (comparação por turma/distribuição de respostas/taxa de acerto/média/tendência ao longo do tempo, etc.)
• Estilo geral do painel (consistente com a ferramenta de ensino/estilo independente/estilo para projeção)
• Necessita de atualização em tempo real

Se a informação for insuficiente, pergunte:

"Na sala de aula, quais dados você gostaria de mostrar para toda a turma? Espera que os alunos vejam sua posição em relação à turma?"

Confirmação das Informações

Após coletar as três dimensões acima, organize um resumo dos requisitos e mostre ao usuário para confirmação, no seguinte formato:

📋 Resumo de Confirmação dos Requisitos

【Informações Básicas】
- Versão QuickForm: Versão Oficial/Versão Local
- Estilo de Design: xxx
- Série Aplicável: xxx   Disciplina: xxx

【Interação da Ferramenta de Ensino】
- Tipo de Funcionalidade: xxx
- Método de Interação: xxx
- Feedback Imediato: Sim/Não

【Campos de Coleta de Dados】
- campo1: Significado (Tipo)
- campo2: Significado (Tipo)
...

【Requisitos do Painel de Visualização】
- Tipo de Gráfico: xxx
- Dimensões Estatísticas: xxx
- Atualização em Tempo Real: Sim/Não

Aguarde a confirmação do usuário antes de prosseguir para a Etapa 4.

---

Etapa 4: Criar Tarefa no QuickForm

Com base na versão escolhida na Etapa 1, crie a tarefa correspondente no QuickForm.

Regra de Nomenclatura da Tarefa: Nomeie com base no tema da ferramenta de ensino, de forma concisa e clara (ex: "Prática de Adição e Subtração para 3º Ano", "Quiz da Tabela Periódica para Ensino Médio")

Criação na Versão Oficial

curl -s -X POST https://quickform.cn/cli/add \
  -H "Content-Type: application/json" \
  -d '{"username":"<conta>","password":"<senha>","task_name":"<nome da tarefa>","description":"<breve descrição da ferramenta>"}'

Exemplo de resposta de sucesso: {"success":true,"apiid":"k5egb0lbzi"}

• Endpoint de Submissão de Dados: https://quickform.cn/api/<apiid>
• Endpoint de Obtenção de Dados: https://quickform.cn/api/<apiid>/all

Criação na Versão Local

A versão local não possui endpoint /cli/add. Use sessão Python para fazer login e criar, e analise o ID real da API a partir da página da tarefa:

⚠️ Importante: O endpoint da API da versão local não é o número sequencial da tarefa (ex: /api/10), mas sim um ID de string aleatório gerado pelo sistema para cada tarefa (ex: /api/C9VaWGMQEZY). É necessário fazer login e analisar o HTML da página de detalhes da tarefa para obtê-lo; não é possível usar o ID numérico diretamente para submeter dados.

import urllib.request, urllib.parse, http.cookiejar, re

cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))

# 1. Login
login_data = urllib.parse.urlencode({'username': 'wst', 'password': 'quickform'}).encode()
req = urllib.request.Request('<LOCAL_BASE_URL>/login', data=login_data)
req.add_header('Content-Type', 'application/x-www-form-urlencoded')
opener.open(req)

# 2. Criar tarefa
task_data = urllib.parse.urlencode({'title': '<nome da tarefa>', 'description': '<breve descrição da ferramenta>'}).encode()
req2 = urllib.request.Request('<LOCAL_BASE_URL>/create_task', data=task_data)
req2.add_header('Content-Type', 'application/x-www-form-urlencoded')
resp = opener.open(req2)
final_url = resp.geturl()  # Redireciona para /task/<id_numerico>
numeric_id = re.search(r'/task/(\d+)', final_url).group(1)

# 3. Analisar o ID real da API da página de detalhes (string aleatória, não numérica)
req3 = urllib.request.Request(f'<LOCAL_BASE_URL>/task/{numeric_id}')
resp3 = opener.open(req3)
html = resp3.read().decode('utf-8')
api_links = re.findall(r'/api/([a-zA-Z0-9\-_]+)', html)
real_api_id = list(set(api_links))[0]  # ID real da API

print(f"ID Numérico da Tarefa: {numeric_id}")
print(f"ID Real da API: {real_api_id}")

• Endpoint de Submissão de Dados: <LOCAL_BASE_URL>/api/<real_api_id>
• Endpoint de Obtenção de Dados: <LOCAL_BASE_URL>/api/<real_api_id>/all

O campo data retornado pelo endpoint de dados da versão local está no formato de string Python dict (com aspas simples). Ao analisar no HTML do painel, é necessário converter para JSON (substituir aspas simples por duplas).

Registrar Informações do Endpoint

Registre as seguintes informações para uso nas etapas seguintes:

• SUBMIT_URL: Endereço do endpoint de submissão de dados
• FETCH_URL: Endereço do endpoint de obtenção de dados
• TASK_NAME: Nome da tarefa

---

Etapa 5: Desenvolver a Página HTML da Ferramenta de Ensino Interativa

Com base em todos os requisitos coletados, gere um único arquivo HTML completo para a ferramenta de ensino.

Especificações Técnicas

Princípios a serem seguidos:

• Arquivo HTML único, todo CSS e JS inline
• Use CDNs acessíveis na China (veja lista abaixo)
• Endereço de submissão de dados usando SUBMIT_URL
• Após submissão bem-sucedida, forneça feedback claro ao aluno (mensagem de sucesso/pontuação/explicação)
• A página deve ser exibida corretamente tanto em dispositivos móveis quanto em computadores (responsiva)

CDNs Recomendados (acessíveis na China):

<!-- Tailwind CSS -->
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

<!-- ECharts (para página de visualização) -->
<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>

<!-- Font Awesome -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6/css/all.min.css">

<!-- Alpine.js para interatividade leve -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>

Template de Código para Submissão de Dados:

async function submitData(formData) {
  try {
    const response = await fetch('SUBMIT_URL', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(formData)
    });
    const result = await response.json();
    return result;
  } catch (error) {
    console.error('Falha na submissão:', error);
    return null;
  }
}

Requisitos de Qualidade da Ferramenta de Ensino

• Tema da página claro, alinhado com o estilo de design escolhido
• Tamanho da fonte adequado à faixa etária alvo (crianças usam fonte maior)
• Elementos interativos com feedback visual claro (efeitos hover, animações de clique)
• Botão de submissão proeminente, fluxo de submissão simples (poucos passos)
• Incluir título da ferramenta de ensino e breve instrução de uso
• Todos os campos do formulário correspondem exatamente aos campos definidos na Etapa 3.2

Salvar Arquivo

Salve o HTML gerado no diretório de trabalho atual, com a regra de nomenclatura: <nome_da_tarefa_ferramenta_de_ensino>.html (use sublinhados para espaços)

---

Etapa 6: Submeter Automaticamente 3 Dados de Teste

Com base na estrutura de campos da ferramenta de ensino, gere 3 dados de teste realistas e submeta.

Princípios dos Dados de Teste:

• Os dados devem ter diversidade (não podem ser três idênticos)
• Os dados devem ser realistas (nomes de alunos reais, distribuição de notas plausível)
• Cobrir diferentes situações (ex: aluno que acertou, aluno que errou, turmas diferentes)

Método de Submissão: Use curl para submeter um por um

curl -s -X POST "SUBMIT_URL" \
  -H "Content-Type: application/json" \
  -d '{"campo1":"valor1","campo2":"valor2",...}'

Após a conclusão, informe ao usuário: "✅ 3 dados de teste foram submetidos com sucesso"

---

Etapa 7: Desenvolver o Painel de Visualização de Dados

7.1 Obter Estrutura dos Dados de Teste

curl -s "FETCH_URL"

Leia todos os dados JSON retornados, entenda a estrutura dos dados (nomes dos campos, tipos de dados, relacionamentos aninhados).

Registre a estrutura completa dos dados como referência para o desenvolvimento.

7.2 Desenvolver o HTML do Painel de Visualização

Desenvolva com base nas seguintes informações:

• Estrutura real dos dados e campos obtidos na Etapa 7.1
• Requisitos de visualização apresentados pelo usuário na Etapa 3.3
• Tema e estilo da página da ferramenta de ensino (manter consistência)

Especificações Técnicas:

• Arquivo HTML único, todo código inline
• Use ECharts (via cdn.jsdelivr.net) para renderizar gráficos
• Ao carregar a página, busque dados automaticamente de FETCH_URL e renderize
• Se necessário atualização em tempo real, use setInterval a cada 10-15 segundos
• Layout do painel adequado para projeção (proporção 16:9, fontes grandes)

O painel deve conter:

• Topo da página: Título da ferramenta + visão geral das estatísticas atuais (número de participantes, pontuação média, etc.)
• Área principal: gráficos conforme requisitos do usuário (usando ECharts)
• Endereço da fonte de dados (pequeno texto no rodapé)

Template de Código para Obtenção de Dados:

async function fetchData() {
  const response = await fetch('FETCH_URL');
  const data = await response.json();
  // Tratar a estrutura de data conforme o conteúdo real obtido na Etapa 7.1
  return data;
}

Salvar Arquivo

Regra de nomenclatura: <nome_da_tarefa_painel_de_dados>.html

---

Etapa 8: Relatório de Conclusão

Após o desenvolvimento, apresente um breve relatório ao usuário:

🎉 Desenvolvimento da Ferramenta de Ensino QuickForm concluído!

📁 Arquivos Gerados
  - Página da Ferramenta de Ensino: <nome_do_arquivo>.html
  - Painel de Análise de Dados: <nome_do_arquivo>.html

🔗 Informações dos Endpoints
  - Submissão de Dados: SUBMIT_URL
  - Obtenção de Dados: FETCH_URL

📊 Dados de Teste
  - 3 dados de teste submetidos. Visualize os resultados na página do painel.

💡 Dicas de Uso
  1. Compartilhe a página da ferramenta de ensino com os alunos (endereço da rede local ou público)
  2. Após os alunos preencherem e submeterem, abra o painel de dados para ver os resultados em tempo real
  3. Para modificar o estilo ou campos, edite diretamente o arquivo HTML

---

Referências

• Documentação da API QuickForm: veja references/quickform-api.md
• Exemplos de Gráficos de Visualização: veja references/echarts-examples.md
• Lista de CDNs Acessíveis na China: veja references/china-cdn.md