1. Жарияланымды жасау («Негізгі» экраны): сауалнаманың атауын және болашақ веб-мекенжайын (Slug) көрсетіңіз.
2. Сұрақтарды құрастыру («Конструктор» экраны): өрістер құрылымын жинаңыз, міндеттілікті, кеңестер мен көрсету логикасын параметрлеңіз.
3. Брендинг және локализация («Дизайн» және «Аудармалар» экрандары): компания шапкасын (header) және подвалын (footer) параметрлеңіз, қазақ/ағылшын тілдеріне аударманы қосыңыз.
4. Алдын ала көру және тексеру («Алдын ала көру» экраны): тестілік сауалнаманы толтырып, есептеулер мен валидацияның дұрыстығына көз жеткізіңіз.
5. Белсендіру және жауаптарды жинау: «Статус: Белсенді» ажыратқышын қосыңыз және нәтижелерді «Есептілік» экранында немесе Webhooks/API арқылы талдаңыз.

Басқару элементтері

• «Жаңа жарияланым» түймесі: Жасау формасын тазартып, менеджерді жаңа мекенжай тіркеу режиміне ауыстырады.
• Іздеу (Тік сүзгі): Жарияланымдар тізімін атауы немесе слагы бойынша лезде сүзеді.
• «Жарияланым тақырыбы» өрісі: Пайдаланушыларға браузер қойындысының тақырыбында және сауалнама шапкасында (header) көрсетілетін атау.
• «URL (Мекенжай)» өрісі / Slug: Латин әліпбиімен жазылған бірегей жол (мысалы, anketa-2026). Формаға түпкі сілтеме: https://domain/f/anketa-2026.
• «Статус: Белсенді» ажыратқышы: Өшірулі болса, пайдаланушылар толтыруға әрекеттенгенде жауап қабылдау аяқталған экраны көрсетіледі (Inactive Screen).
• Ревизиялар тарихы және қайтару (Rollback): Карточканың төменгі бөлігінде күні мен авторы бар сақталған барлық нұсқалардың таймлайы көрсетіледі. Ревизияны басу конструкторға форманың тарихи нұсқасын лезде жүктейді.

Жарияланымдардың әкімшілік тізімі

Әкімшілерге платформаның барлық сауалнамаларын, оның ішінде басқа пайдаланушылар жасағандарын да қамтитын «Жарияланымдар» тізімі қолжетімді:

• Іздеу: жарияланым атауы, slug немесе форма атауы бойынша.
• Сүзгілер: күй (белсенді/белсенді емес), қолжетімділік түрі (ашық, жабық, рөлдер бойынша) және иесі.
• Әрекеттер: кез келген жарияланымды редакциялауға өту, белсендіру/өшіру; кестеде жауаптар саны мен қабылдау аяқталу күні көрінеді.
• Әкімші рөлі жоқ жасаушылар «Негізгі» бөлімінде тек өз жарияланымдарын көреді.

Жұмыс ортасының құрылымы

• Сол жақ компонент палитрасы: Негізгі өрістер (Мәтін, Сан, Құсбелгі, Файлдар) және разметка элементтері (Панельдер, Бағандар) бар. Оларды тышқанмен оң жақтағы жұмыс аймағына сүйреп әкеліңіз. Барлық компоненттердің толық анықтамалығы — конструктор нұсқаулығында.
• Жұмыс кенебі: Болашақ форманың интерактивті макетін көрсетеді. Кез келген компонентке курсор апарғанда жылдам әрекеттер панелі қолжетімді:
  • Параметрлер: Валидация, API-кілті мен кеңестердің параметрлері бар диалог ашады.
  • Көшіру: Өрісті барлық ішкі ережелерімен бірге клондау.
  • Төменге қою: Бұрын көшірілген компонентті қояды.
  • JSON: Өріс схемасын тікелей редакциялау (Кеңейтілген режимде қолжетімді).
  • Жылжыту: Компонентті кенепте басқа орынға қолмен жылжыту.
  • Жою: Компонентті схемадан жояды.

Теңшеу мүмкіндіктері

• Дайын үлгілерді (Ассеттер) таңдау: Орталықтандырылған ассеттер анықтамалығынан корпоративтік шапканы (header), подвальді (footer) немесе белсенді емес экранды жылдам қосу.
• Код редакторы (Ace Editor): Өз безендіруін жазуға арналған HTML/CSS синтаксисін түрлендіретін кірістірілген редактор.
• Тік алдын ала көру панелі (Preview Box): Код енгізіле тұрып верстканы нақты уақыт режимінде көрсетеді.
• Тақырыпты безендіру: Жарық тақырыпты (Corporate Light) және жоғары контрастты қараңғы тақырыпты (Dark Enterprise) қолдау.

Сауалнаманы басқа сайтқа ендіру

Жарияланымды сыртқы сайтқа — мысалы, корпоративтік порталға — фрейм ретінде ендіруге болады: респонденттер сауалнаманы әдеттегі сайттан кетпей толтырады.

1. «Дизайн» қойындысында «Ендіру (Embed)» карточкасындағы «Сауалнаманы сыртқы сайттарға ендіруге рұқсат беру» ауыстырғышын қосыңыз.
2. Рұқсат етілген домендерді көрсетіңіз — бір жолда біреу, https://www.ktz.kz форматында. Сауалнаманы тек тізімде домені бар сайтқа ғана ендіуге болады (CSP frame-ancestors арқылы кез келген ресурсқа ендіруден қорғау), 10 доменге дейін.
3. «Дизайнды сақтау» түймесін басыңыз — теңшеу бірнеше секундтан кейін күшіне енеді.
4. «Кодты көшіру» түймесімен дайын ендіру кодын көшіріп, сайт иесіне беріңіз. Код фреймді және биіктікті автоматты реттеу скриптін қамтиды.

Хост-сайт жағынан ештеңе қажет емес: әзірлеуші алған кодты бетке қана қояды — кілттер, токендер мен тіркелу талап етілмейді. Сауалнама мекенжайына өз фреймін жазу да жұмыс істейді, бірақ сниппеттегі скриптсіз биіктікті бекітілген етіп көрсету керек. Ретін сақтаңыз: сайт домені олардың жағында код жарияланғанға дейін тізімге енуі керек, әйтпесе браузер фреймді блоктайды.

Шектеулер:

• Рөлдік қолжетімділіктегі сауалнамалар да ендіріле алады: фрейм ішінде «Кіру» түймесі пайда болады, кіру жеке терезеде (брендтелген біртұтас кіру беті) ашылады, кіргеннен кейін форма автоматты түрде жүктеледі — хост-бет қайта жүктелмейді.
• Міндетті қолтаңбамен (NCALayer) сауалнамалар браузер шектеулеріне байланысты (Private Network Access) фреймнен қолтаңба бағдарламасына қол жеткізе алмауы мүмкін. Мұндай жағдайда форма «Жаңа қойындыда ашу» ұсынысын көрсетеді — жеке қойындыда қолтаңба жұмыс істейді. Мақсатты сайтта тексеріңіз.
• Ауыстырғыш қосулы, бірақ домендер тізімі бос болса, ендіруге тыйым салынады — сауалнама фреймге орналастырылудан сақталады.

«ҚТЖ Forms by SuraqHub» тұжырымдамасы

«Қазақстан темір жолы» ҰК» АҚ корпоративтік ортасына енгізу үшін жүйе ко-брендинг режімінде бапталған: қызметкерлер мен филиалдар үшін сервис «ҚТЖ Forms» ішкі сенімді корпоративтік жүйесі ретінде, ал негізгі қозғалтқышы «by SuraqHub» белгісімен ұсынылады.

• Форктарсыз және кодты қайталамау: SuraqHub біртұтас бастапқы коды стандартты орнатуларды да, брендтелген арнайы инстанстарды да бірдей қамтамасыз етеді.
• Қайта құрастырусыз жылдам конфигурация: брендинг параметрлері Kubernetes ConfigMap (suraqhub-frontend-env) және env.js файлы арқылы басқарылады.
• Zero Downtime & Лездік жаңарту: конфигурация no-cache тақырыптарымен қорғалған, өзгерістер Docker бейнесін қайта жинаусыз бірден қолданысқа енеді.

Брендинг элементтері

Локализация қалай жұмыс істейді

1. Қойындыға өткенде жүйе форманың ағымдағы схемасын автоматты түрде талдап, барлық мәтіндік жолдарды табады: өріс белгілерін, кеңестерді (placeholder), сипаттамалар мен қате мәтіндерін.
2. Интерактивті кестеде тілдер бойынша бағандар шығады: Орыс (RU), Қазақ (KK) және Ағылшын (EN).
3. CSV-ге экспорт: Кестені кәсіби аудармашыларға беру үшін файлға шығарып алуға болады.
4. Сауалнаманы толтқан кезде респондент ажыратқыштан ыңғайлы тілді таңдайды және форманың барлық сұрақтары бетті қайта жүктемей лезде аударылады.

Тізілім және редактор

• Анықтамалықтар тізілімі: күйі, өндірістік нұсқасы және жаңарту күні бар барлық анықтамалықтар кестесі. Жаңа анықтамалық жасау түймесі арқылы тіркеледі.
• Кірістірілген редактор: жазбаларды кестеде редакциялау — жол қосу, кесте бойынша тік іздеу, ячейканы қос шертіп редакциялау.
• Импорт және экспорт: мәндерді Excel/CSV файлынан жаппай жүктеу, ағымдағы жобаны Excel-ге шығару, буфер алмасуы арқылы жол қосу (Excel-де Ctrl+C → кестені шертіңіз → Ctrl+V).
• Жоба және жариялау: түзетулер «Жобаны сақтау» түймесімен жобаға сақталады; «Жариялау» жобаны формалар мәндерді оқитын өндірістік нұсқаға айналдырады.
• Сыртқы анықтамалықтар: бұлт белгісі бар жолда соңғы синхрондау күйі көрсетіледі, найзағай түймесі қолмен синхрондауды іске қосады.

Сыртқы анықтамалықтар (автосинхрондау)

Анықтамалық мәндерді сыртқы дереккөзден автоматты ала алады: платформа деректерді өзі алады (server-to-server), анықтамалық келісімшартына салып, жаңа өндірістік нұсқаны жариялайды — деректер шын өзгерген жағдайда ғана. Тән жағдай — сыртқы онтологиялық API жүргізетін көлік анықтамалықтары (станциялар, пойыз санаттары).

• Баптау: бұлт түймесі дереккөз карточкасын ашады — ресурс URL-і, трансформер (өрістерді салыстыру), тіркелгі деректері бар орта айнымалысы (Basic), жаңарту аралығы (минут), қосу/өшіру.
• Қолмен синхрондау: тізілім жолындағы (немесе дереккөз карточкасындағы) найзағай түймесі аралықты күтпей қосымша жаңарту жүргізеді.
• Жаңарту журналы: дереккөз карточкасында соңғы әрекеттер журналы көрінеді — уақыты, күйі, HTTP коды, алынған және өзгертілген жазбалар саны, жарияланған ревизия.
• Ревизиялар және дәйектілік: дереккөздің әрбір өзгерісі сыртқы деректер жиынының нұсқасы белгіленген жаңа өзгермейтін ревизия ретінде жазылады. Сыртқы дереккөз қолжетімсіз болса да, формалар мәндерді оқи береді — соңғы жарияланған нұсқа қолданылады. Сыртқы анықтамалықтың жобасын қолмен редакциялау тыйылады: келесі синхрондау оның үстінен жазады.
• Қайтару: жариялау тарихы арқылы кез келген бұрынғы ревизияға бірден оралуға болады — қарапайым анықтамалықтардағыдай.

Поляларды пайдаланушы бойынша авто толтыру (префилл)

Форманың өрістерін форманы ашқан пайдаланушының профилінен автоматты толтыруға болады: аты-жөні — тіркелгіден (Keycloak), нысандар (участкілер, станциялар) — «Тағайындаулар» қойындысында жүргізілетін жеке тағайындаулардан.

• Қалай жұмыс істейді: форманың өрісі prefill қасиетін алып жүреді — форма ашылғанда мән профильден толтырылады (аты-жөні редакциялаудан бұғатталады), ал ашылмалы тізім опциялары пайдаланушыға тағайындалған нысандарға дейін сүзгіленеді.
• Сервердегі кепілдік: анкета жіберілгенде сервер деректерді браузерге тәуелсіз тексереді — аты-жөні әрқашан тіркелгі мәнімен алмастырылады, нысан таңдауы тағайындаулармен салыстырылады. DevTools арқылы бұрмалау мүмкін емес.
• Тағайындаулар жоқ болса: нысандар тізімі толық қалады (fallback режимі), пайдаланушының таңдауы қолмен таңдалған деп белгіленеді. Мұндай мәндер «Тағайындаулар» қойындысына кандидат ретінде түседі — әкімші мақұлдаған соң өрістер келесі жолы автоматты толтырылады.
• «Тағайындаулар» қойындысы: қолмен тағайындау (email арқылы пайдаланушыны іздеу), белсенді тағайындаулар мен кандидаттар тізімі, мақұлдау және жою. Кандидаттар пайдаланушы нысанды қолмен таңдаған сабмиттерден автоматты жасалады.

Экран респондент көретін нақты интерфейстің дәл көшірмесін барлық қосылған стильдер, қаріптер, шапка (header) және подвалмен (footer) көрсетеді. Форманы жіберу, міндетті өрістер, телефон маскалары, файлдарды тіркеу және сұрақтардың тармақталу логикасын тексеріп көруге мүмкіндік береді.

Аналитика мүмкіндіктері

• Нақты уақыттағы санағыштар: Жіберілген сауалнамалардың (сабмишндердің) жалпы саны және соңғы жауаптың күні.
• «Жауаптар динамикасы» графигі: Сауалнаманың күндер бойынша толтырылу уақыт шкаласы.
• Жауаптардың географиялық картасы: Сауалнамалар жіберілген нүктелерді кластерлеуі бар Қазақстанның интерактивті картасы (геолокация жинайтын формалар үшін).
• Өрістер бойынша детализация: Ашылмалы тізімнен бір немесе бірнеше сұрақты таңдаңыз — жүйе жауап нұсқаларының таралуының дөңгелек және бағандық диаграммаларын автоматты түрде құрастырады.
• Excel-ге асинхронды экспорт (XLSX): «Excel жүктіп алу» түймесін бассаңыз, тапсырма RabbitMQ воркерлеріне беріледі. Дайын есеп лезде жүктіп алынады, интерфейс жұмысын блоктамайды.

Жүйелік параметрлер

• Жүктеудің максималды өлшемі: Формаларға тіркеуге рұқсат етілген файлдардың өлшем шектеуі (МБ).
• Платформа уақыт белдеуі: Аналитика мен Excel экспорттарында таймстемптердің дұрыс есептелуін анықтайды.
• Формалар аудармаларының тілдері: «Аудармалар» қойындысында және жарияланған формаларда қолжетімді тілдерді басқарады. Орыс тілі негізгі болып қалады; қазақ, қырғыз, ағылшын және өзбек тілдерін қосуға/өшіруге болады.
• Антивирустық сканер (ClamAV): Файлдарды вирустарға тексеруді қосу және сервис мекенжайы.
• Keycloak рөлдерінің анықтамалығы: Платформаның жүйелік рөлдерін (Admin, Creator, Viewer) Keycloak токендерімен сәйкестендіру.
• Диагностика пакеті: Микросервистік логтарды, RabbitMQ кезектерінің күйін және DLQ қате кезегін қамтитын біртұтас архивті құрастырады — жылдам техникалық қолдау үшін.

«Жүйе күйі» панелі

«Қызмет көрсету» бөлімінде инфрақұрылымның жанды көрсеткіштері көрсетіледі. Панель «Жаңарту» түймесімен және қойындыны әр ашқан сайын жаңартылады. Көрсеткіштерді қалай оқу керек:

API-токендердің қауіпсіздігі

• Префикс whsec_: Токен криптографиялық тұрақты генератормен жасалады және жасалған кезде тек бір рет көрсетіледі.
• SHA-256 хэштеу: Платформа деректер базасында токеннің тек хэші сақталады. База қауіпке ұшыраған жағдайдың өзінде бастапқы кілтті қалпына келтіру мүмкін емес.
• Көрініс шектеуі (Scopes): Кілтті глобалды етіп жасауға немесе тек таңдалған жарияланымдарға қол жеткізумен шектеуге болады.

cURL арқылы GraphQL-сұрау мысалы

curl -X POST https://suraqhub.domain.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: whsec_your_secret_api_key_here" \
  -d '{
    "query": "query GetPubStats($id: UUID!) { publicationStats(publicationId: $id) { totalSubmissions lastSubmissionDate } }",
    "variables": { "id": "16a5ff0e-f1ff-4b8a-9887-c5f907912ea1" }
  }'

Оқиға түрлері:

• submission.created — пайдаланушы форманы толтырып, сәтті жіберді.
• form.saved — форманың сұрақтар құрылымы өзгертілді немесе сақталды.
• publication.saved — жарияланым өзгертілді немесе белсендірілді.

JSON Payload спецификациясы:

{
  "event": "submission.created",
  "event_id": "9f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f",
  "timestamp": "2026-09-02T15:30:00.000Z",
  "publication_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "form_id": "f5e4d3c2-b1a0-9876-5432-10fedcba9876",
  "submission_id": "77aa88bb-99cc-00dd-11ee-22ff33aa44bb",
  "data": {
    "fullName": "Алексей Смирнов",
    "phoneNumber": "+77015554433",
    "score": 5,
    "comment": "Отличная скорость работы!"
  }
}

HMAC-SHA256 қолтаңбасын тексеру (X-SuraqHub-Signature тақырыбы)

Әр сұрау сіздің жазылу құпиясыңызбен қолтаңбаланады. Сервер-қабылдағыш өңдеу алдында қолтаңбаны тексеруі міндетті:

Python мысалы (FastAPI / Flask):

import hmac, hashlib
from fastapi import FastAPI, Request, HTTPException, Header

app = FastAPI()
WEBHOOK_SECRET = "whsec_your_secret_key"

@app.post("/webhook")
async def receive_webhook(request: Request, x_suraqhub_signature: str = Header(None)):
    raw_body = await request.body()
    expected = hmac.new(WEBHOOK_SECRET.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()

    if not x_suraqhub_signature or not hmac.compare_digest(expected, x_suraqhub_signature):
        raise HTTPException(status_code=403, detail="Invalid HMAC signature")

    payload = await request.json()
    print(f"✅ Успешно получено событие {payload['event']}")
    return {"status": "ok"}

Сенімділік кепілдіктері (SRE Retry Policy):

• Manual ACK: Хабарлама RabbitMQ-да тек сіздің серверіңізден 200 OK HTTP-коды қабылданғаннан кейін ғана расталады.
• Экспоненциалды Retry: Желілік қате немесе 5xx коды кезінде платформа жіберуді өсіп отыратын аралықпен 5 рет қайталайды.
• Dead Letter Queue (DLQ): Фаталды қателер кезінде (404, 403) хабарлама қолмен талдау үшін suraqhub.webhooks.failed бұзылғандар кезегіне қауіпсіз сақталады.

Бұл арна вебхуктардан және API кілттерінен неге өзгеше:

• Вебхуктар — автоматтандыру жүйелері үшін лездік push-хабарламалар (оқиғаға секунд ішінде реакция).
• API кілттері — сыртқы сервистерге арналған GraphQL API-ға синхронды сұраулар (нақты сауалнаманың деректері, бизнес-логика).
• analytics схемасы — адамға арналған тарих: Power BI-дағы дашбордтар, воронкалар, кесте бойынша жаңартылатын жиынтық есептер.

Деректер моделі:

• vw_submissions — сауалнама шапқылары: қашан, қай жарияланым, тіл, қолтаңбаның бар-жоғы. Жауап мазмұнынсыз.
• vw_submission_answers — «ұзын» форматтағы жауаптар (бір жол = бір жауап). Кез келген формаға әмбебап: Power BI-да жиынтық кесте (Pivot) арқылы кең кестеге айналады.
• vw_submission_geo — құрылғылар координаталары (ендік, бойлық, дәлдік) геолокация жинайтын формалар үшін.
• vw_publications — жарияланымдар анықтамалығы: атаулары, жіберу саясаттары, қолтаңба мен геолокация, белсенділік кезеңдері.

Қауіпсіздік және құпиялық:

• Қосу арнайы read-only powerbi_reader рөлімен жүргізіледі, оған тек analytics схемасы қолжетімді. Платформаның қызметтік кестелеріне (API кілттері, жазылыстар, аудит) рөлдің қол жеткізуі жоқ.
• Жеке деректер берілмейді: ЖСН, криптографиялық қолтаңбалар мен шикі метадеректер вьюларға кірістірілмеген.
• Жазу мүмкін емес — рөлде тек оқу құқығы бар.

Қосу:

Power BI Desktop-та: Деректерді алу → PostgreSQL, сервер мен suraqhub деректер базасының мекенжайын көрсетіңіз, авторизация — powerbi_reader тіркелгісімен (платформа әкімшісі береді). Жарияланған дашбордтар үшін сол дереккөзді жергілікті Data Gateway-ге қосыңыз.

Жоғары жүктемелі орналастырулар үшін платформа деректер базасының read-only репликасын қарастырады: әкімші аналитикалық есептер мен BI-қосылымдарды база көшірмесіне (DATABASE_RO_URL) бағыттап, негізгі базаны тек сауалнамаларды қабылдауға қалдыра алады. Толығырақ — suraqhub-docs/analytics_powerbi.md құжатында.