formulosity

يعد التركيب تطبيقًا مستضيفًا ذاتيًا لبناء ونشر الدراسات الاستقصائية باستخدام التعليمات البرمجية بدلاً من بناة المسح التقليدية.

يوفر هذا النهج عددًا من المزايا ، بما في ذلك:

• التحكم في الإصدار : يمكن تخزين ملفات المسح في مستودع GitHub ، مما يجعل من السهل تتبع التغييرات والتعاون مع الآخرين.
• استنساخ : يمكن مشاركة ملفات المسح واستنساخها بسهولة ، مما يجعل من السهل إعادة استخدام الدراسات الاستقصائية أو إنشاء اختلافات في الدراسات الاستقصائية الموجودة.
• الأتمتة : يمكن استخدام ملفات المسح لأتمتة إنشاء ونشر الدراسات الاستقصائية ، والتي يمكن أن توفر الوقت والجهد.

يستخدم الصيغة لغة إعلانية قابلة للقراءة الإنسان.

سمات

• إدارة API
• UI للمسح: للمستخدمين النهائيين (المجيبين)
• وحدة التحكم في وحدة التحكم: إدارة الدراسات الاستقصائية
• تكوين مسح YAML
• أنواع الأسئلة الأساسية
• الموضوع الافتراضي
• دعم الموضوعات المخصصة
• خيارات شخصية: مقدمة ، outro ، إلخ.
• ملف تعريف الارتباط/IP حماية الاستجابة
• مصادقة مستخدم المسؤول
• خيارات قاعدة بيانات مختلفة: SQLITE و POSTGRES
• تابع المكان الذي توقفت فيه
• قواعد التحقق المتقدمة
• اكتشف تغييرات المسح في الوقت الفعلي
• استجابات التصدير في واجهة المستخدم أو عبر API
• أنواع الأسئلة المتقدمة
• يجيب الأنابيب في الأسئلة التالية

أراها في العمل!

لوحة المسؤول

ملاحظة: استخدم user / pass لتسجيل الدخول إلى وحدة التحكم في وحدة التحكم.

هيكل المسح

كل دليل في SURVEYS_DIR هو مسح. يمكنك تكوين مصدر الدراسات الاستقصائية الخاصة بك عن طريق تعيين SURVEYS_DIR مختلفة env var.

surveys/
├── survey1/
│   ├── metadata.yaml
│   ├── questions.yaml
│   ├── security.yaml
│   ├── variables.yaml
│   └── ...
└── survey2/
    ├── metadata.yaml
    ├── questions.yaml
    └── ...

للبدء ، تحقق من مجلد ./surveys مع أمثلة متعددة.

ملفات المسح

بيانات التعريف

هذا الملف مطلوب! يتكون الملف من كائن Yaml مع خصائص محددة تصف المسح.

• العنوان : هذا هو العنوان الرئيسي المعروض للمستخدمين في بداية المسح.
• الموضوع : هذا يحدد السمة المرئية المطبقة على المسح. الموضوعات المدعومة حاليًا هي: الافتراضي.
• مقدمة : يظهر هذا النص كمقدمة قبل السؤال الأول.
• outro : يظهر هذا النص كنتائج بعد السؤال الأخير.

 title : Survey Title
theme : default # or custom
intro : |
  This is the introduction to the survey.
  It can be multiple lines long.
outro : |
  Thank you for taking the survey.
  Your feedback is important to us.

أسئلة. yaml

هذا الملف مطلوب! يتكون الملف من قائمة الأسئلة ، يتم تعريف كل منها ككائن YAML مع خصائص محددة.

• النوع : هذا يحدد نوع السؤال الذي يتم طرحه.
• معرف : هذا يوفر معرفًا فريدًا للسؤال. من المفيد الرجوع إلى أسئلة محددة في منطق المتفرعة أو تحليل البيانات. يجب أن تكون المعرفات فريدة من نوعها في جميع الأسئلة في الاستطلاع.
• التسمية : هذا هو النص المعروض للمستخدم باعتباره السؤال نفسه.
• الوصف : يوفر هذا معلومات إضافية حول السؤال للمستخدم ، مثل التوضيح أو التعليمات.
• الخيارات : تحدد هذه القائمة خيارات الإجابة المتاحة لأنواع الأسئلة مثل single-choice multiple-choice ranking .
• OptionsFromVariable : تشير هذه الخاصية إلى متغير محدد في ملف متغيرات منفصل. يجب أن يحتوي المتغير على قائمة بالخيارات المراد استخدامها للسؤال. هذا يسمح بإعادة الاستخدام والإدارة المركزية لقوائم الخيارات.
• التحقق من الصحة : يتم استخدام هذه الخاصية لتحديد قواعد التحقق من صحة أنواع أسئلة محددة.

 questions :
  - type : single-choice
    id : question1 # optional ID, must be unique across all questions
    label : What is the capital of Germany?
    description : You can select multiple options
    optionsFromVariable : german-city-options # defined in variables.yaml
    options :
      - Berlin
      - Munich
      - Paris
      - London
      - Hamburg
      - Cologne
    validation :
      min : 1
      max : 3

Security.yaml

هذا الملف اختياري. يتكون الملف من كائن YAML مع خصائص محددة لإعدادات أمان المسح.

• DecplicateProtection : تحدد هذه الخاصية كيفية تعامل النظام الأساسي مع التكرار من الاستجابات من نفس المستخدم.

 duplicateProtection : cookie # cookie | ip

المتغيرات

هذا الملف اختياري. يتكون الملف من قائمة المتغيرات ، يتم تعريف كل منها ككائن YAML مع خصائص محددة.

• المعرف : يشير هذا المعرف الفريد إلى المتغير ضمن الأسئلة. يجب أن تكون المعرفات فريدة من نوعها عبر جميع المتغيرات المحددة في الملف.
• النوع : هذا يحدد نوع البيانات المخزنة في المتغير. الأنواع المدعومة حاليًا هي: قائمة.

 variables :
  - id : german-city-options # must be unique
    type : list
    options :
      - Berlin
      - Munich
      - Hamburg
      - Cologne 

أنواع الأسئلة

نص قصير

يطالب المستخدمين بإجابة مكتوبة موجزة.

- type : short-text
  label : What is the capital of Germany?
  # set min/max characters
  validation :
    min : 10
    max : 100

نص طويل

يطالب المستخدمين للحصول على إجابة مكتوبة مفصلة.

- type : long-text
  label : What is the capital of Germany?
  # set min/max characters
  validation :
    min : 10
    max : 100

اختيار واحد

يقدم سؤالًا مع إجابة واحدة صحيحة فقط من قائمة الخيارات.

- type : single-choice
  label : What is the capital of Germany?
  options :
    - Berlin
    - Munich
    - Paris
    - London
    - Hamburg
    - Cologne

الاختيار من متعدد

يقدم سؤالاً حيث يمكن للمستخدمين تحديد إجابات متعددة (مع قيود). يمكنك تخصيص الحد الأدنى والحد الأقصى للاختيارات المسموح بها في قسم التحقق من الصحة.

- type : multiple-choice
  label : Which of the following are cities in Germany?
  description : You can select multiple options
  validation :
    min : 1
    max : 3
  options :
    - Berlin
    - Munich
    - Paris
    - London
    - Hamburg
    - Cologne

تاريخ

يطلب من المستخدمين إدخال تاريخ محدد.

- type : date
  label : When was the Berlin Wall built?

تصنيف

يقدم مقياسًا للمستخدمين لتقييم شيء ما على نطاق محدد مسبقًا.

- type : rating
  label : How much do you like Berlin?
  min : 1
  max : 5

تصنيف

يطلب من المستخدمين ترتيب الخيارات بناءً على معايير معينة.

- type : ranking
  label : Rank the following cities by population
  optionsFromVariable : german-city-options

نعم/لا

يقدم سؤالاً حيث لا يمكن للمستخدمين الإجابة إلا على "نعم" أو "لا".

- type : yes-no
  label : Is Berlin the capital of Germany?

بريد إلكتروني

يطالب المستخدم بإدخال بريده الإلكتروني

- type : email
  label : Please enter your email.

ملف

يطالب المستخدم بتحميل ملفه بناءً على تنسيقات معينة وحجم التحميل القصوى.

- type : file
  label : Upload a Berlin Image
  validation :
    formats :
      - .jpg
      - .png
    max_size_bytes : 5*1024*1024 # 5 MB 

ردود

يمكن إظهار الردود في واجهة المستخدم وتصديرها على أنها JSON. بدلاً من ذلك ، يمكنك استخدام REST API للحصول على Resposnes للمسح:

curl -XGET 
http://localhost:9900/app/surveys/{SURVEY_ID}/sessions ? limit=100 & offset=0 & sort_by=created_at & order=desc

حيث {SURVEY_ID} معرف uuid من مسح معين.

لقطات الشاشة

التثبيت والنشر

 docker-compose up -d --build

ويجب أن تكون قادرًا على الوصول إلى واجهة المستخدم على http: // localhost: 3000 (الافتراضي الأساسي المصادقة: user:pass ).

يمكنك نشر الخدمات الفردية على أي مزود سحابي أو استضافها ذاتيًا.

• العودة. يتم تعبئتها كحاوية مرصقة ويمكن نشرها في أي مكان.
• Next.js الواجهة. يتم تعبئتها أيضًا كحاوية Docker ، ولكن يمكن أيضًا نشرها على Vercel على سبيل المثال.
• [اختياري] قاعدة بيانات postgres. يمكنك استخدام خدمات Postgres المدارة أو نشرها بنفسك.

يتم نشر الخدمة التجريبية (الروابط أعلاه) إلى Fly.io (Go ، SQLite) و Vercel (Next.js) وهي تحت المستويات المجانية.

إعداد التنمية الخلفية

تثبيت الهواء محليا من هنا

قم بتشغيل الأمر التالي بعد تثبيت الهواء

 cd api
air

سيساعد هذا الأمر في إعادة التحميل المباشر كلما تم إجراء التغييرات في واجهات برمجة التطبيقات باستخدام air . يمكن تعيين التكوينات المخصصة عن طريق تعديل ملف air.toml

متغيرات البيئة

API:

• DATABASE_TYPE - sqlite أو postgres
• DATABASE_URL - سلسلة اتصال postgres أو sqlite
• LOG_LEVEL - مستوى السجل ، على سبيل info
• SURVEYS_DIR - دليل مع الدراسات الاستقصائية ، على سبيل المثال /root/surveys . يُقترح استخدام وحدة التخزين المكونة لهذا الدليل.

واجهة المستخدم:

• CONSOLE_API_ADDR - العنوان العام لـ GOND Backend. يجب أن تكون متاحة من المتصفح.
• CONSOLE_API_ADDR_INTERNAL - العنوان الداخلي للرجوع ، على سبيل المثال http://api:8080 (يمكن أن يكون هو نفسه CONSOLE_API_ADDR ).
• IRON_SESSION_SECRET - سر تشفير الجلسة
• HTTP_BASIC_AUTH - التنسيق: user:pass للحصول على المصادقة الأساسية (اختياري)

مكدس التكنولوجيا

• الواجهة الخلفية: اذهب ، (postgres أو sqlite)
• واجهة المستخدم: next.js ، Tailwind CSS

قم بإنشاء ترحيل SQLite/Postgres جديد

تأكد من تثبيت go-migrate أولاً.

 cd api
migrate create -dir migrations/postgres -ext sql -seq name
migrate create -dir migrations/sqlite -ext sql -seq name

تشغيل اختبارات الذهاب

 cd api
make test

الإرشادات المساهمة

يتم الترحيب بطلبات السحب وتقارير الأخطاء وجميع أشكال المساهمة الأخرى وتشجيعها بشدة!