hack-438cc0d4-kazakh-alem-ai

Hackathon team repository for KAZAKH ALEM AI

AI Sana Challenge Hub

HackAlem AI хакатонына арналған KAZAKH ALEM AI командасының жобасы.

Қазіргі күйі: frontend-тің 2-кезеңдік демосы және бөлек іске қосылатын бастапқы Express API бар. Frontend backend-ке қосылмаған. OpenAI шақыруы, есептелетін рейтинг, жариялау, каталог және команда ұсыныстары негізгі қосымшада әлі іске асырылмаған.

Бұл README репозиторий түбіріндегі жұмыс көшірмесін сипаттайды. review-output/ai-sana-challenge-hub/ — бөлек өңделіп жатқан нұсқа; оның мүмкіндіктері негізгі қосымшаның мүмкіндіктері ретінде есептелмейді. README дайындалған кезде frontend өзгерістері commit жасалмаған, ал server.js, src/, data/, .env.example Git бақылауына әлі қосылмаған. Сондықтан GitHub-тан жаңадан көшірілген нұсқа осы жергілікті жұмыс көшірмесіне толық сәйкес келмеуі мүмкін.

1. Жоба туралы

AI Sana Challenge Hub — бизнес өкілдеріне қысқа және толық емес бизнес тапсырмасын студенттік командаларға түсінікті, құрылымдалған тапсырмаға айналдыруға көмектесуге арналған платформа.

Қазір браузерде жұмыс істейтін ағын:

Сала және бизнес сипаттамасы
→ 3 тұрақты нақтылаушы сұрақ
→ Барлық сұраққа жауап енгізу
→ «Жауаптарды сақтау»
→ Өңделетін Task Card
→ 65/100 тестілік рейтинг және бос өрістер тізімі
→ Карточканы осы бетте растау

Бөлек backend ағыны:

POST /api/analyze
→ analyzeTask(description, industry)
→ missingFields + 3 тұрақты сұрақ + summary

Жобаның көздеген толық ағыны — Business description → AI Agent → 3 нақтылаушы сұрақ → Task Card → 0–100 рейтинг → Publish → Catalog → Team Proposal → Business Accept / Reject. Бұл толық ағын әзірге негізгі кодта іске асырылмаған.

2. Қандай мәселені шешеді

Бизнес тапсырмалары көбіне тым қысқа беріледі. Студенттік командаға шешімнің кімге арналғаны, қандай деректер бар екені, қандай нәтиже күтілетіні, табыс қалай өлшенетіні және қандай шектеулер бар екені түсініксіз болуы мүмкін.

Қазіргі прототип қолданушылар, деректер және күтілетін нәтиже туралы үш сұрақ қойып, жауаптарды құрылымдалған карточкаға көшіреді. Қалған ақпаратты бизнес өкілі қолмен толықтырады.

3. AI Agent

Негізгі модуль: src/aiAgent.js. Оның экспорттайтын функциясы — analyzeTask(description, industry).

Бұл нұсқада агент ережеге негізделген fallback ретінде жұмыс істейді:

• description және industry бос емес мәтін болуын тексереді;
• сипаттамадан users, data, expectedResult өрістерінің нақты белгіленген мәндерін іздейді;
• анықталмаған өрістерді missingFields массивіне енгізеді;
• үш тұрақты сұрақ пен қысқа summary қайтарады.

Мысалы, мына мәтіндегі үш өріс танылады:

Қолданушылар: студенттер; Деректер: CSV кестесі; Күтілетін нәтиже: прототип

Мәтінде Өріс: мән түріндегі белгі болмаса, fallback еркін сөйлемнің мағынасын түсініп қорытынды жасамайды. Мысалы, «Студенттерге платформа керек» дегенде users әлі нақтылауды қажет етеді деп көрсетіледі. белгісіз, unknown, tbd сияқты арнайы белгісіз мәндер толтырылған ақпарат деп саналмайды. industry тек тексеріледі; ол сұрақтарды өзгертпейді.

Қайтарылатын сұрақтар:

1. Шешімді нақты кімдер қолданады?
2. Қандай деректер немесе материалдар қолжетімді?
3. Команда жұмысының соңында қандай нәтиже күтіледі?

Барлық өріс танылса да, осы үш сұрақ қайтарылады. Сұрақтар динамикалық генерацияланбайды.

Нақты шекарасы: бұл модуль Task Card жасамайды, improvement tips бермейді және OpenAI API шақырмайды. Карточканы public/app.js браузерде жасайды. Белгісіз мәліметтер бос қалады; жаңа бизнес фактілері қосылмайды. Команданы немесе жеңімпазды автоматты таңдау жоқ.

4. Task Card

Үш сұраққа да бос емес жауап беріп, «Жауаптарды сақтау» батырмасын басқанда карточка ашылады. Тек бос орын енгізу жауап болып саналмайды.

Өріс	Мағынасы	Алғашқы толтырылуы
title	Тапсырма атауы	Сипаттаманың алғашқы 100 таңбасы
context	Контекст	Толық сипаттама
need	Бизнес қажеттілігі	Бос; қолмен толтырылады
users	Қолданушылар	Бірінші жауап
data	Қолжетімді деректер	Екінші жауап
constraints	Шектеулер	Бос; қолмен толтырылады
expectedResult	Күтілетін нәтиже	Үшінші жауап
successCriteria	Табыс критерийлері	Бос; қолмен толтырылады
contact	Байланыс ақпараты	Бос; қолмен толтырылады
interactionFormat	Өзара әрекеттесу форматы	Бос; қолмен толтырылады

Барлық 10 өріс өңделеді. industry бастапқы формада таңдалады, бірақ осы 10 карточка өрісінің құрамына кірмейді.

Өзгермеген жауаптарды қайта сақтау қолмен түзетілген өрістерді сақтайды. Жауап өзгерсе, оған сәйкес карточка өрісі жаңарады; сипаттама өзгерсе, context жаңарады.

Бастапқы сипаттама, сала немесе жауап өзгергенде растау үшін жауаптарды қайта сақтау қажет. Карточканы өңдеу бұрынғы растауды алып тастайды. Растау серверге жібермейді және жарияламайды. Барлық қосымша карточка өрісін толтыру растаудың міндетті шарты емес.

Деректер тек ашық беттің жадында сақталады. Бетті жаңартқанда немесе жапқанда енгізілген мәліметтер жоғалады.

5. Рейтинг жүйесі

Қазіргі кодта салмақтарға негізделген 100 балдық формула жоқ.

Орны	Нақты логика
Frontend, updateRating()	Карточка жасалғанша 0/100; жасалғаннан кейін тұрақты 65/100
Frontend деңгейі	Алдымен «Әзірге бағаланбаған», кейін Workable
Backend, calculateRating(task)	Әрқашан 0 қайтаратын бастапқы функция

Frontend логикасы:

const score = cardCreated ? 65 : 0;

Карточка өңделген сайын бос өрістер тізімі жаңарады. Progress bar рейтинг мәнін көрсетеді, бірақ балл 65 болып қалады. Барлық өріс толтырылса да, балл 100 болмайды.

Контекстке 20, деректерге 20 және басқа өрістерге жеке балл беру, сондай-ақ 0–39 / 40–69 / 70–89 / 90–100 деңгейлерін есептеу негізгі кодта жоқ. «Рейтингті қайта есептеу» батырмасы мен рейтинг API endpoint-і де жоқ.

6. Каталог

Негізгі қосымшада каталог беті, тапсырманы жариялау, жарияланған тапсырмалар тізімі, рейтинг бойынша сұрыптау және сала/дайындық сүзгілері іске асырылмаған.

data/tasks.json файлы бар, бірақ ол бос. GET /api/tasks endpoint-і жоқ. Сондықтан төмен рейтингті тапсырмаларды көрсету немесе жасыру ережесі әзірге қолданылмайды.

7. Команда ұсыныстары

Негізгі нұсқада ұсыныс жіберу формасы, команда таңдау, идея/жоспар/мерзім/прототип сілтемесін жіберу және бизнес тарапынан Accept / Reject жасау жоқ.

data/teams.json және data/proposals.json болашақ деректерге арналған бос файлдар ретінде дайындалған. Оларды өзгертуге арналған API жоқ. AI жеңімпазды таңдамайды.

8. Технологиялар

Қабат	Нақты қолданылуы
Frontend	HTML, CSS, Vanilla JavaScript; framework және build қадамы жоқ
Backend	Node.js, Express; JSON сұрауларын қабылдайды
Талдау	JavaScript тұрақты өрнектері және тұрақты сұрақтар
Деректер	JSON файлдары; node:fs/promises арқылы оқу
Орта айнымалылары	dotenv
OpenAI SDK	package.json ішінде тәуелділік ретінде бар, негізгі кодта қолданылмайды

package.json тәуелділіктері: express ^5.2.1, dotenv ^18.0.3, openai ^7.23.0. Орнатылатын нақты нұсқалар package-lock.json ішінде бекітілген.

9. Архитектура

Негізгі қосымша файлдары:

hack-438cc0d4-kazakh-alem-ai/
├── public/
│   ├── index.html
│   ├── style.css
│   └── app.js
├── src/
│   ├── aiAgent.js
│   ├── rating.js
│   └── store.js
├── data/
│   ├── tasks.json
│   ├── teams.json
│   └── proposals.json
├── .github/agents/kazakh-alem-hackathon.agent.md
├── server.js
├── .env.example
├── .gitignore
├── package.json
├── package-lock.json
├── README.md
└── review-output/ai-sana-challenge-hub/  # Бөлек жұмыс нұсқасы

Файл	Қызметі
public/index.html	Қазақша форма, сұрақтар, карточка және рейтинг блоктарын орналастырады.
public/style.css	Экран өлшеміне бейімделетін интерфейс пен күйлерді безендіреді.
public/app.js	Тексеру, тестілік сұрақтар, карточканы өңдеу, демо рейтинг және растауды басқарады.
src/aiAgent.js	Backend үшін нақты белгіленген ақпаратты іздеп, үш fallback сұрақ қайтарады.
src/rating.js	Болашақ рейтингке арналған, әзірге 0 қайтаратын функцияны сақтайды.
src/store.js	readCollection(name) арқылы tasks, teams, proposals JSON массивтерін оқиды.
data/tasks.json	Тапсырмаларға арналған бос массив.
data/teams.json	Командаларға арналған бос массив.
data/proposals.json	Ұсыныстарға арналған бос массив.
server.js	Health және талдау endpoint-терін іске қосып, JSON қателерін өңдейді.
.env.example	OPENAI_API_KEY және PORT параметрлерінің үлгісін береді.
.gitignore	node_modules/ пен .env файлдарын Git бақылауынан шығарады.
package.json	Жоба метадеректері мен тәуелділіктерін сипаттайды.
package-lock.json	Тәуелділіктердің нақты нұсқаларын бекітеді.
.github/agents/kazakh-alem-hackathon.agent.md	Әзірлеуге арналған агент нұсқаулығы; қосымшаның runtime бөлігі емес.
README.md	Негізгі нұсқаны іске қосу мен тексеру жолын түсіндіреді.

server.js ішінде express.static(...) жоқ. public/app.js ішінде backend-ке fetch сұрауы жоқ. Сондықтан frontend пен API бөлек тексеріледі. Негізгі сервер review-output/ кодын жүктемейді.

10. Орнату

Қажет: Git, Node.js 22 немесе одан жаңа нұсқа, npm және заманауи браузер. Node.js 22 талабы lock-файлдағы OpenAI SDK тәуелділігіне байланысты; осы жұмыс көшірмесі Node.js 22.20.0 ортасында тексерілді.

1. Репозиторийді көшіру

git clone https://github.com/BAITC-Hacks/hack-438cc0d4-kazakh-alem-ai.git
cd hack-438cc0d4-kazakh-alem-ai

Жоғарыдағы жұмыс көшірмесінің күйі туралы ескертуді ескеріңіз: commit жасалмаған өзгерістер git clone арқылы келмейді. API-ді тексеру үшін берілген көшірмеде server.js, src/, data/ және .env.example бар екеніне көз жеткізіңіз. README жаңа backend кодын өздігінен қоспайды.

2. Тәуелділіктерді орнату

npm install

Windows PowerShell npm.ps1 іске қосылуына тыйым салса:

npm.cmd install

3. .env дайындау

Жоба түбірінде .env.example файлын .env атымен көшіріңіз. Бұрыннан бар .env файлын алмастырмаңыз.

Қазіргі демо үшін жеткілікті мазмұн:

OPENAI_API_KEY=
PORT=3000

Нақты кілт қажет емес: негізгі код оны қолданбайды. Кейін кілт қосылса, оны кодқа немесе Git-ке енгізбеңіз.

4. Backend-ті іске қосу

Барлық команданы репозиторийдің түбірінен, review-output/ ішіне кірмей орындаңыз:

node server.js

Балама:

npm start

Windows-та:

npm.cmd start

package.json ішінде жеке start script жоқ. Түбірде server.js болғанда npm әдепкі түрде node server.js орындайды. Негізгі тексеру үшін тікелей node server.js командасын қолдануға болады.

Консольде AI Sana API: http://localhost:3000 жазуы шығуы керек. Порт бос болмаса, іске қосылған басқа серверді тоқтатыңыз немесе .env ішіндегі PORT мәнін өзгертіңіз. Тоқтату: Ctrl+C.

5. Браузерде ашу

• Frontend: public/index.html файлын браузерде ашыңыз; бұл демоға backend қажет емес.
• API health: http://localhost:3000/api/health.
• http://localhost:3000/ сайтты ашпайды: негізгі сервер HTML таратпайды, сондықтан түбірлік URL үшін 404 — қазіргі кодқа сәйкес нәтиже.

11. OpenAI API болмаса

Қазіргі негізгі нұсқа OpenAI API-ге мүлде сұрау жібермейді. Сондықтан кілтсіз режим — осы нұсқаның қалыпты жұмыс режимі; сыртқы API қатесінен кейін ауысатын бөлек AI режимі әзірге жоқ.

Frontend үш тестілік сұрақты өзі көрсетеді. Backend сол үш сұрақты fallback функциясы арқылы береді. .env ішіне кілт жазу нақты AI интеграциясын іске қоспайды.

12. Қалай тексеруге болады

Frontend сценарийі

1. public/index.html файлын браузерде ашыңыз. Рейтинг 0/100, карточка бос болуы керек.
2. Сала мен сипаттаманы бос қалдырып, «AI арқылы талдау» басыңыз: екі өрістің қатесі көрінуі керек.
3. «Білім беру» саласын таңдаңыз.
4. «Студенттерге арналған оқу платформасы керек.» деп жазыңыз.
5. «AI арқылы талдау» басыңыз: үш нақтылаушы сұрақ шығады.
6. Бір жауапты бос қалдырып, «Жауаптарды сақтау» басыңыз: карточка жасалмауы керек.
7. Үш жауапты толтырыңыз, мысалы: «Студенттер мен оқытушылар», «Оқу материалдары және CSV кестелері», «Оқу платформасының прототипі».
8. «Жауаптарды сақтау» басыңыз: 10 өңделетін өрісі бар карточка ашылып, жауаптар тиісті өрістерге көшуі керек.
9. 65/100, Workable және бос өрістер тізімін тексеріңіз.
10. «Шектеулер» өрісін толтырыңыз: ол бос өрістер тізімінен жоғалуы керек; балл 65 болып қалады.
11. «Карточканы растау» басыңыз: осы бетте расталғаны және серверге жіберілмегені туралы хабар көрінеді.
12. Бір жауапты өзгертіңіз: қайта растау үшін «Жауаптарды сақтау» қажет болуы керек.
13. Бетті жаңартыңыз: бастапқы бос күйге оралады.

Жариялау, каталог және proposal қадамдары негізгі кодта болмағандықтан, осы сценарийге кірмейді.

Backend сценарийі

Серверді іске қосып, екінші PowerShell терезесінде орындаңыз:

Invoke-RestMethod -Uri 'http://localhost:3000/api/health'

$payload = @{
  description = 'Студенттерге арналған оқу платформасы керек.'
  industry = 'education'
} | ConvertTo-Json

Invoke-RestMethod -Uri 'http://localhost:3000/api/analyze' `
  -Method Post `
  -ContentType 'application/json; charset=utf-8' `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($payload)) | ConvertTo-Json -Depth 5

Health жауабы:

{ "status": "ok" }

Талдау жауабы:

{
  "missingFields": ["users", "data", "expectedResult"],
  "questions": [
    "Шешімді нақты кімдер қолданады?",
    "Қандай деректер немесе материалдар қолжетімді?",
    "Команда жұмысының соңында қандай нәтиже күтіледі?"
  ],
  "summary": "Fallback талдауында кейбір маңызды мәліметтер нақты анықталмады. Оларды сұрақтар арқылы нақтылау қажет."
}

Қосымша тексерулер:

Сұрау	Күтілетін нәтиже
POST /api/analyze, бос/мәтін емес description немесе industry	400, түсінікті қате
Дұрыс емес JSON	400
32 KB шегінен асатын JSON body	413
Сипаттама: Қолданушылар: студенттер; Деректер: CSV; Күтілетін нәтиже: прототип	missingFields: [], бірақ үш сұрақ сақталады
GET / немесе GET /api/tasks	404, мұндай маршрут жоқ

Негізгі package.json ішіндегі npm test — «Error: no test specified» шығарып, қате кодымен аяқталатын placeholder. Автоматты тест жиынтығы негізгі нұсқаға қосылмаған. Бөлек review-output/ нұсқасындағы тесттер негізгі нұсқаны тексермейді.

13. Тестілік деректер

Негізгі data/ ішіндегі нақты күй:

Файл	Жазба саны	Мазмұны
data/tasks.json	0	[]
data/teams.json	0	[]
data/proposals.json	0	[]

Алдын ала енгізілген команда, тапсырма немесе ұсыныс жоқ. Frontend-тегі әрекеттер бұл файлдарға жазылмайды. src/store.js тек оқу функциясын ұсынады.

14. Шектеулер

• Frontend пен backend өзара қосылмаған; негізгі сервер frontend файлдарын таратпайды.
• Нақты OpenAI талдауы, динамикалық сұрақтар және improvement tips жоқ.
• Backend жауаптардан карточка жасамайды және карточканы сақтамайды.
• Frontend рейтингі — тұрақты демо мәні; backend рейтингі — бастапқы 0 функциясы.
• Жариялау, каталог, сүзгілер, команда ұсыныстары және Accept / Reject жоқ.
• Тіркелу, кіру, рөлдер және production authentication жоқ.
• Realtime чат пен хабарландырулар жоқ.
• Дерекқор, JSON-ға жазу және браузерде тұрақты сақтау жоқ.
• Негізгі қосымшада автоматты тесттер жоқ.
• Commit жасалмаған және Git бақылауына кірмеген жергілікті файлдар қазылардың таза clone көшірмесінде болмайды.

15. Hackathon demo

Қазіргі жұмыс істейтін мүмкіндіктерге арналған 5 минуттық көрсетілім:

Уақыт	Әрекет
0:00–1:00	Мәселені түсіндіріп, сала мен қысқа сипаттама енгізіңіз; бастапқы 0/100 күйін көрсетіңіз.
1:00–2:00	Үш тестілік сұрақты көрсетіп, бір бос жауап карточка жасауға жол бермейтінін тексеріңіз.
2:00–3:00	Барлық жауапты сақтап, өңделетін Task Card пен 65/100 · Workable демо рейтингін көрсетіңіз.
3:00–4:00	Бос карточка өрісін толтырып, тізімнің жаңаруын, растауды және қайта өңдегендегі күйді көрсетіңіз.
4:00–5:00	Бөлек /api/health пен /api/analyze сұрауларын орындап, fallback шекаралары мен әзірге жоқ мүмкіндіктерді түсіндіріңіз.

Қазылар бұл нұсқада карточка дайындау интерфейсін және бастапқы API-ді тексере алады. Толық жариялау → каталог → ұсыныс → шешім ағыны осы негізгі нұсқаның дайын мүмкіндігі ретінде көрсетілмейді.