HACKALEM AI / ekt-ai-assistant

AI/Agent модулі

AI/Agent тапсырмасы TypeScript түрінде packages/ai ішіне қосылды. Іске қосу: npm ci --ignore-scripts, npm run typecheck, npm test, npm run demo:ai (Node.js 24+).

11.txt қосылды: 2 беттегі 40 тауар және бір толық detail. npm run demo:ai осы файлдан импортталған каталогты қолданады. Бұл онлайн API емес; файлда жоқ қалдықтар белгісіз болып қалады, 160А/250 А қайшылығы көрсетіледі. Каталог деректері. Синтетикалық демо: npm run demo:synthetic.

Толық нұсқаулық, backend/frontend contract-тері және KZ/RU мысалдар: packages/ai/README.md. Модульде intent/context, аналог түсіндіру, бөлек растаумен single/bulk cart, файл спецификациясының есебі, injection қорғанысы, freshness және feedback бар. Нақты EKT API, LLM провайдері және binary файл extractor-ы интеграция интерфейстері арқылы қосылады.

Төмендегі бұрынғы архитектура мәтіні өзгертілмеді; онда аталған Frontend/ файлдары осы жұмыс ағашында жоқ. Қазіргі орындалатын AI модулінің нұсқаулығы жоғарыдағы сілтемеде.

Жоба архитектурасы

Жоба ekt.kz интернет-дүкеніне арналған ЖИ-ассистент ретінде құрылған. Жүйенің негізгі мақсаты — пайдаланушыға қажетті электротехникалық тауарды табуға, оның техникалық сипаттамаларын көруге, қоймадағы бар-жоғын тексеруге, аналогтарын таңдауға және тауарды себетке қосуға көмектесу.

Жүйе бірнеше негізгі компоненттен тұрады: ┌──────────────────────────────┐ │ Пайдаланушы │ │ ekt.kz сайтының клиенті │ └──────────────┬───────────────┘ │ │ Сұраныс ▼ ┌──────────────────────────────┐ │ Frontend │ │ │ │ Website + AI Chat UI │ │ • Чат интерфейсі │ │ • Тауарларды көрсету │ │ • Аналогтарды көрсету │ │ • Себет │ └──────────────┬───────────────┘ │ │ HTTP / API ▼ ┌──────────────────────────────┐ │ Backend API │ │ │ │ Сұраныстарды қабылдау │ │ және сервистерге бағыттау │ └──────────────┬───────────────┘ │ ┌───────┼─────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ AI │ │ Product │ │ Cart │ │Assistant │ │ Service │ │ Service │ │ │ │ │ │ │ │ Сұрақты │ │ Каталог │ │ Растау │ │ түсіну │ │ Іздеу │ │ Себет │ │ │ │ Қалдық │ │ Саны │ │ Жауап │ │ Аналог │ │ │ │ құру │ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ └────────────┼────────────┘ │ ▼ ┌───────────────────┐ │ Database │ │ │ │ • Products │ │ • Categories │ │ • Stock │ │ • Certificates │ │ • Cart │ └───────────────────┘

Frontend

Frontend — пайдаланушы көретін және қолданатын интерфейс.

Пайдаланушы сайттағы чат арқылы ЖИ-ассистентке сұрақ қоя алады.

Мысалы:

"ABB C16 автоматы бар ма?"

немесе:

"Осы тауарға аналог тауып бер."

Frontend пайдаланушының сұранысын Backend API-ге жібереді және алынған жауапты экранда көрсетеді.

Frontend негізгі мүмкіндіктері:

• ЖИ-ассистентпен чат;
• тауар туралы ақпаратты көрсету;
• техникалық сипаттамаларды көрсету;
• баға мен қоймадағы қалдықты көрсету;
• аналогтарды көрсету;
• тауарды себетке қосу;
• себетке немесе тапсырысты рәсімдеу бетіне өту.

Backend API

Backend API — Frontend пен жүйенің ішкі сервистері арасындағы негізгі байланыс қабаты.

Backend келесі міндеттерді орындайды:

• пайдаланушы сұранысын қабылдау;
• сұранысты AI Assistant-ке жіберу;
• каталогтан қажетті ақпаратты алу;
• қоймадағы қалдықты тексеру;
• аналогтарды іздеу;
• себет операцияларын орындау;
• нәтижені Frontend-ке қайтару.

Жалпы сұраныс ағыны:

Frontend │ ▼ Backend API │ ├── AI Assistant ├── Product Service └── Cart Service

AI Assistant

AI Assistant — жүйенің интеллектуалды бөлігі.

Ол пайдаланушының еркін түрде жазылған сұрағын түсініп, қандай әрекет қажет екенін анықтайды.

Мысалы:

Пайдаланушы: "Маған 16 амперлік автомат керек."

AI Assistant сұранысты талдап, Product Service арқылы сәйкес тауарларды іздейді.

AI Assistant келесі сұраныстарды өңдей алады:

• тауар іздеу;
• тауар сипаттамасын сұрау;
• сертификатты сұрау;
• қоймадағы қалдықты тексеру;
• аналог іздеу;
• сатып алу шарттарын сұрау;
• тауарды себетке қосуға дайындық.

AI Assistant каталогтағы нақты деректерге сүйеніп жауап беруі тиіс. Product Service

Product Service — каталогтағы тауарлармен жұмыс істейтін компонент.

Ол келесі ақпаратты өңдейді:

Product ├── ID / Артикул ├── Атауы ├── Санаты ├── Бағасы ├── Техникалық сипаттамалары ├── Сертификат ├── Қоймадағы саны └── Қолжетімділік мәртебесі

Product Service келесі операцияларды орындайды:

• артикул бойынша іздеу;
• атауы бойынша іздеу;
• санаты бойынша іздеу;
• техникалық параметрлер бойынша іздеу;
• қоймадағы қалдықты тексеру;
• тауардың аналогтарын іздеу.

Егер пайдаланушы сұраған тауар қоймада болмаса, жүйе техникалық сипаттамалары ұқсас тауарларды тауып, аналог ретінде ұсынады.

Мысалы: Сұралған тауар: ABB S201 C16

Қалдық: 0 дана

Ұсынылған аналог: Schneider Electric C16

Себебі: Номиналды ток және негізгі техникалық параметрлері ұқсас.

Cart Service

Cart Service — пайдаланушы себетін басқаруға арналған компонент.

Жүйенің маңызды ережесі:

Тауар пайдаланушының нақты растауынсыз себетке қосылмайды.

Мысалы:

User: "Осы тауардан 2 дана керек."

AI Assistant: "2 данасын себетке қосайын ба?"

User: "Иә, қос."

AI Assistant: "Тауар себетке қосылды."

Растау алынғаннан кейін жүйе:

User Confirmation │ ▼ Stock Check │ ▼ Quantity Check │ ▼ Cart Service │ ▼ Add to Cart │ ▼ Checkout Link

Егер пайдаланушы 10 дана сұрап, қоймада тек 5 дана болса, жүйе 10 дананы себетке қоспайды және қолжетімді сан туралы хабарлайды.

Database

Database — жүйенің каталогы мен қажетті деректерін сақтау үшін қолданылады.

Негізгі деректер:

Database │ ├── Products │ ├── id │ ├── article │ ├── name │ ├── category │ ├── price │ └── specifications │ ├── Stock │ ├── product_id │ ├── warehouse │ └── quantity │ ├── Certificates │ ├── product_id │ └── certificate_url │ └── Cart ├── product_id └── quantity

Хакатон прототипінде тестілік немесе синтетикалық каталог деректерін пайдалануға болады.

Кейін жүйені нақты ekt.kz каталог API-іне қосуға болады.

Жүйенің жұмыс істеу логикасы

Қарапайым сұраныс:

User │ │ "ABB C16 бар ма?" ▼ Frontend │ ▼ Backend API │ ▼ AI Assistant │ ▼ Product Service │ ▼ Database │ ▼ Product Service │ ▼ AI Assistant │ ▼ Backend │ ▼ Frontend │ ▼ User

Тауар болмаған жағдайда

text User Request │ ▼ Product Search │ ▼ Stock = 0 │ ▼ Alternative Search │ ▼ Similar Products │ ▼ AI Explanation │ ▼ User

Себетке қосу кезінде

text User │ │ "2 дана себетке қос" ▼ AI Assistant │ │ "2 дана қосайын ба?" ▼ User Confirmation │ │ "Иә" ▼ Stock Check │ ▼ Cart Service │ ▼ Add to Cart │ ▼ Checkout Link

Ұсынылатын жоба құрылымы text project/ │ ├── frontend/ │ ├── index.html │ ├── css/ │ └── js/ │ ├── backend/ │ ├── app.py │ │ │ ├── routes/ │ │ ├── chat.py │ │ ├── products.py │ │ └── cart.py │ │ │ └── services/ │ ├── ai_service.py │ ├── product_service.py │ └── cart_service.py │ ├── data/ │ ├── products.json │ └── certificates/ │ ├── README.md ├── requirements.txt └── .gitignore

 Қауіпсіздік принциптері

Жүйеде келесі шектеулер сақталады:

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

Осы архитектура жүйені жеке компоненттерге бөліп, әр компонентті бөлек дамытуға және тестілеуге мүмкіндік береді.

## Прототиптің қазіргі мүмкіндіктері

`Frontend/` ішіндегі прототип кейс талаптарының негізгі демонстрациялық сценарийін іске асырады:

* синтетикалық каталогтан артикул, атау, санат және техникалық сипаттама бойынша іздеу;
* қоймадағы нақты санды, қойманы және тауардың қолжетімділік мәртебесін көрсету;
* каталогта бар сертификаттың сілтемесін қайтару;
* қалдығы нөл позицияға санаты, ортақ техникалық параметрлері және бағасы бойынша аналог ұсыну, себебін түсіндіру;
* төлем, жеткізу және ең аз партия туралы жауап беру;
* Excel, Word, PDF және JPEG/PNG тіркемесін чатқа қабылдау интерфейсі;
* тауар саны қойма қалдығынан аспаса ғана және пайдаланушы растағаннан кейін ғана себетке қосу;
* қосқаннан кейін `#cart` тікелей сілтемесін беру;
* төлем деректерін чатта сұрамау және сақтамау;
* белгісіз немесе күрделі сұрақты менеджерге жіберу туралы хабарлау.

## Іске қосу

`Frontend/start.bat` файлын екі рет басыңыз. Ол Python тәуелділіктерін дайындап, FastAPI серверін іске қосады. Немесе терминалда:

```powershell
Set-Location Frontend
.\start.bat

Браузерде http://127.0.0.1:8000 мекенжайын ашыңыз. Толық нұсқаулық: Frontend/README.md.

SQLite дерекқоры: Frontend/data/app.sqlite3. Бөлек MySQL/PostgreSQL орнату қажет емес. Базаны дайындау/тексеру: Frontend/init-db.bat. SQL схемасы: Frontend/data/schema.sql. База тауарларды, сессияларды, себеттерді, растау ұсыныстарын және чат тарихын сақтайды.

Демонстрациялық тесттер

Чатта мына сұраныстарды тексеруге болады:

• ABB-S201-C16 сертификаты бар ма? — баға, сипаттама, қалдық және сертификат сілтемесі;
• IEK C25 жоқ болса, аналог бер — қалдығы нөл позиция және ұқсас аналогтың негіздемесі;
• Төлем, жеткізу және ең аз партия қандай? — сатып алу шарттары;
• ABB C16 автоматтан 2 дана керек — қойма тексеруі, растау модалы және растаудан кейін #cart сілтемесі.

Деректер және production келесі қадамдары

SQLite базасында 24 демо тауар (Frontend/data/products.json) және пайдаланушының JSON файлдарынан импортталған 20 EKT тауары (Frontend/data/ekt-products.json) бар. Негізгі каталог әдепкіде EKT деректерін көрсетеді. Қайта импорт: Frontend/import-ekt.bat. 3414970344526 штрихкодымен Legrand тауарын тексеруге болады: файлдағы бағасы 64 920 ₸, қалдығы 23 дана. Қалған 19 тауардың қалдығы берілмеген және белгісіз деп көрсетіледі. Деректер онлайн жаңартылмайды; себет пен жеткізу жергілікті прототип ретінде жұмыс істейді. API кілті серверде ғана сақталады.