1SanTi/survey-design-collector

Generador de encuestas y sistema de recolección en línea

Convierte una "necesidad de encuesta" en un trío de herramientas listo para usar:

1. Encuesta en Word (formato profesional, imprimible y distribuible)
2. Sitio web de respuesta en línea (responder escaneando un código QR, sin dependencias, doble clic y listo)
3. Panel de resumen de datos (gráficos estadísticos automáticos por pregunta + detalles + exportación a Excel con un clic + código QR de respuesta)

Todo el proceso sin dependencias de terceros (solo biblioteca estándar de Python). El resultado se puede copiar a cualquier computadora y ejecutar directamente.

---

Cuándo usar

• El usuario proporciona una grabación / dictado / texto y solicita "diseñar una encuesta", "diseñar una encuesta a partir de una grabación".
• El usuario ya tiene preguntas y quiere convertirlas en una encuesta en línea / sitio web para responder con código QR con resumen automático de datos.
• El usuario necesita una solución completa de "encuesta + estadísticas de administración".

---

Flujo de trabajo (Procedimiento Estándar)

Paso 1: Obtener y comprender los requisitos

• Grabación: Primero, convierte la grabación en texto (puedes usar la habilidad speech-to-text o directamente fetch el archivo de audio). Extrae: tema de la encuesta, público objetivo, número de secciones (dimensiones), preguntas específicas de cada dimensión, preferencia de tipo de pregunta (opción única / múltiple / escala / relleno).
• Texto: Lee directamente el esquema proporcionado por el usuario.
• Si hay dudas (por ejemplo, si agregar una sección de "información básica", a qué unidad va dirigida) decide por convención y explica en la entrega, o confirma con el usuario.

Paso 2: Redactar la especificación de la encuesta questions.json

Sigue estrictamente el formato de references/spec-format.md y escribe la encuesta como JSON:

• Nivel superior: title (título), subtitle (subtítulo), intro (introducción), footer (pie de página), scale_options (cinco niveles de la escala), sections.
• Cada sección tiene questions[], cada pregunta contiene id, type, title, required; las preguntas con opciones contienen options.
• Tipos de pregunta: single (única) | multi (múltiple) | scale (escala, las opciones se toman de scale_options) | text (relleno).
• allow_other: true agrega automáticamente "Otro (especifique)"; exclusive: ["ninguna usada"] indica que esa opción es mutuamente excluyente.
• Recomendación: Una encuesta formal generalmente incluye una sección breve de "información básica" (nivel educativo / materia / años de experiencia) para facilitar el análisis cruzado posterior.

Nota de diseño: Las preguntas deben redactarse en forma declarativa, evitando inducir respuestas; las opciones deben ser exhaustivas y mutuamente excluyentes; la escala debe tener niveles uniformes; el número de preguntas debe ser respondible en 3–5 minutos.

Paso 3: Generar el trío de herramientas con un solo comando

python3 scripts/build_survey.py --spec questions.json --out <directorio_de_salida>
# Si se conoce la URL final de respuesta, se puede añadir --url http://xxx/ para generar directamente el código QR

Resultado:

<directorio_de_salida>/
├── <título_de_encuesta>.docx          Encuesta en Word con formato profesional
└── Sistema_encuesta_en_linea/
    ├── server.py                      Página de respuesta + panel + interfaz (sin dependencias)
    ├── questions.json                 Preguntas de esta encuesta
    ├── Iniciar_Windows.bat / Iniciar_Mac_Linux.sh   Inicio con un clic
    ├── make_qr.py                     Generar código QR por separado
    ├── vendor/qrcode/                 Código QR incorporado
    └── Instrucciones_de_uso.md

Paso 4: Autoverificación (obligatorio)

• Abre el archivo Banco_de_preguntas/Sistema_encuesta_en_linea/questions.json y confirma que las preguntas, opciones y marcas de obligatoriedad sean correctas.
• Inicia el sistema una vez para realizar una prueba de humo:

  cd Sistema_encuesta_en_linea && PORT=8123 python3 server.py &
  curl -s http://127.0.0.1:8123/ | head            # La página de respuesta debe abrirse
  curl -s -X POST http://127.0.0.1:8123/submit --data-urlencode "q1=..." # Enviar y guardar
  curl -s http://127.0.0.1:8123/api/stats | head   # Las estadísticas deben ser normales
  

• Confirma que en el Word las preguntas y opciones no se dividan entre páginas (el script ya ha configurado keep-with-next).

Paso 5: Entrega e instrucciones de implementación

Explica al usuario:

• Cómo usar cada uno de los tres componentes; el código QR se muestra automáticamente en la página de administración (http://IP_del_equipo:8000/admin).
• ¿Cómo acceden los profesores?: Con el mismo WiFi, escanean el código QR y responden (más común en escuelas); para acceso público en Internet, se debe colocar en un servidor con IP pública.
• Consulta references/deploy-guide.md, cuyo contenido se puede reutilizar directamente.
• Puedes usar provide_file para entregar al usuario el archivo Word y el paquete comprimido del "Sistema de encuesta en línea" para su descarga.

Paso 6 (opcional) Archivo y almacenamiento

Si se requiere archivar, usa la habilidad upload-to-kb para guardar el archivo Word y el paquete comprimido del sistema en la base de conocimientos especificada por el usuario.

---

Puntos clave y experiencia

• La ausencia de dependencias es la ventaja principal: solo usa la biblioteca estándar de Python + vendor/qrcode incorporado; el usuario no necesita instalar nada con pip. Para generar el Word se necesita python-docx (el entorno de generación debe tenerlo).
• La página de respuesta es un formulario HTML puro con poco JS: el envío se realiza mediante POST /submit, el servidor valida las preguntas obligatorias (si faltan, se muestra el contenido ya rellenado y se marcan en rojo).
• El código QR se genera en tiempo real en el servidor en formato SVG (/api/qr.svg?url=...), la página de administración genera automáticamente el código según la URL de acceso actual. Si el profesor cambia de red o modifica la URL, el código se regenera sin necesidad de reempaquetar.
• Los datos se almacenan en data/responses.db (SQLite); para hacer una copia de seguridad, copia ese archivo; para borrar, elimínalo.
• Si la red local no se puede abrir, en el 90% de los casos es porque el cortafuegos de la computadora no permite Python; informa al usuario que lo permita.
• Si el puerto está ocupado, se puede cambiar con PORT=8080 python3 server.py.

---

Estructura de directorios

survey-design-collector/
├── SKILL.md
├── scripts/
│   ├── build_survey.py    Generación con un clic (lee spec → Word + sitio web + código QR)
│   ├── spec_to_word.py    Genera encuesta en Word a partir de questions.json
│   └── make_qr.py         Genera código QR PNG a partir de una URL
├── assets/app/            Plantilla del sistema de encuesta en línea (server.py / script de inicio / vendor/qrcode)
└── references/
    ├── spec-format.md     Especificación de questions.json + método para convertir grabación en encuesta
    └── deploy-guide.md    Plantilla de instrucciones de implementación y comunicación externa