EKT Space

Локальное приложение: ИИ-ассистент по данным компании, карта товаров со скидками, аккаунты менеджеров и гостевой просмотр. Аккаунты, объявления, импортированные товары и корзины аккаунтов сохраняются в SQLite. Это рабочий MVP; он не опубликован в интернете и не подключён к действующему магазину EKT.

Запуск

На Windows можно дважды нажать start.cmd. Для обновления исходных шести книг в том же формате: python scripts/import_systemelectric.py "C:\папка\с\таблицами" при остановленном сервере. Сначала создаётся новая база, затем заменяется снимок источников.

Нужен Python 3.11+. Откройте PowerShell в папке проекта:

powershell -ExecutionPolicy Bypass -File .\start.ps1

Скрипт создаёт локальную .venv, устанавливает зависимости в неё, копирует .env.example в .env, если файла ещё нет, и запускает сервер. При первом запуске нужен интернет. Скрипт проверяет установленный Python; при его отсутствии может использовать существующий Python из Codex. Глобальные пакеты не меняются.

Откройте приложение, документацию HTTP API или проверку сервера. Остановка — Ctrl+C. Другой порт: powershell -ExecutionPolicy Bypass -File .\start.ps1 -Port 8001.

Ручной запуск:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
# Следующая команда нужна только при отсутствии .env:
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000

На Linux/macOS используйте python3 и .venv/bin/python.

ИИ и геолокация

Настройки в локальном .env:

Переменная	Назначение
OPENAI_API_KEY	Ключ разговорного ИИ. Без него работает локальный поиск и ограниченный помощник.
OPENAI_MODEL	Имя модели; значение по умолчанию указано в .env.example.
GEOAPIFY_API_KEY	Необязательный ключ поиска адресов. Выбор точки и геолокация браузера работают без него.
EKT_DATABASE_PATH	База аккаунтов, объявлений, товаров и корзин; по умолчанию data/ekt.sqlite3.
EKT_SEED_DEMO	true добавляет 4 учебных товара и 3 помеченных объявления при первоначальном наполнении. false отключает наполнение новой базы; существующие данные не удаляет.
PUBLIC_ORIGIN	Точный внешний HTTPS-адрес при размещении за обратным прокси. Локально оставьте пустым.

Не присылайте ключи в чат и не публикуйте .env. Ключи используются сервером. При включённом ИИ вопрос, ограниченная история и найденные фрагменты передаются OpenAI для ответа; пароль и поля аккаунта в контекст модели не включаются. Карта загружает тайлы OpenStreetMap через интернет. Геолокация требует разрешения браузера, а на внешнем домене — HTTPS.

Подключённые данные

В data/sources.sqlite3 уже подготовлены все шесть книг:

Файл	Непустых строк, включая заголовки
MOQ SystemElectric.xlsx	556
Динамика продаж_Syseme Electric_2025-2026.xlsx	77 314
Ежемесячные остатки SystemElectric 2024-2026.xlsx	702
Ежемесячные продажи в кол-м выражении SystemElectric 2024-2026.xlsx	576
Сезонность SystemElectric 2024-2026.xlsx	19
Товар в пути_SystemElectric на 22.09.2026.xlsx	518

Всего 79 685 строк и 9 815 документов для поиска. Движения продаж агрегированы для ответов по артикулам и подразделениям. Состав источников: data/sources-manifest.json.

Это исторические выгрузки по состоянию на сентябрь 2026 года, а не текущие остатки. Проверенных продажных цен и точных координат складов в книгах нет. Строки не превращаются автоматически в реальные предложения со скидкой: менеджер публикует цену, количество и точку отдельно.

Используется RAG — поиск подходящих фрагментов и передача их модели при ответе. Веса модели не дообучались. Ответы содержат ссылки на доступные источники. Примеры: «Что известно об артикуле …?», «Какие есть данные по MOQ?», «Найди предложения со скидкой рядом со мной».

Работа с картой и аккаунтами

Гость просматривает карту, объявления и использует помощника. Регистрация создаёт аккаунт менеджера: можно публиковать и удалять свои объявления, импортировать данные. Укажите товар, количество, исходную цену и цену со скидкой, выберите точку на карте. Сервер проверяет координаты, цену и владельца записи. Объявления видны всем менеджерам; расстояние считается по прямой.

Демо-точки в Алматы — условные адреса и товары. Добавление в локальную корзину требует подтверждения и повторной проверки цены и остатка; оплата и оформление в реальном магазине не подключены. История чата хранится в памяти сервера. Корзина аккаунта сохраняется между входами и перезапусками; гостевая корзина привязана к временной сессии.

Импорт новых данных

Войдите и загрузите CSV в UTF-8, JSON или XLSX в разделе данных. Выберите «Товары» либо «База знаний». Лимиты: 5 МБ, 10 000 строк, первый лист XLSX, до 100 столбцов. Файл проверяется целиком до сохранения. SQL и SQLite напрямую не исполняются: экспортируйте таблицу в поддерживаемый формат.

Пример товаров:

sku,name_ru,category,price_kzt,stock
WIRE-001,Кабель ВВГнг 3x2.5,cable,500,120

Обязательны sku, name_ru (или name), category, price_kzt — целая неотрицательная цена в тенге, stock — целый неотрицательный остаток. Необязательны name_kk, specifications, compatibility, certificate_url. Характеристики и совместимость — JSON-объекты; сертификат — проверенный вами URL HTTP/HTTPS. Повторный импорт артикула обновляет его данные, включая остаток. Совместимость должна быть подтверждена.

Пример базы знаний:

[{"title":"Режим работы склада","content":"По будням с 09:00 до 18:00."}]

Поддерживаются также question / answer и text вместо content. JSON — массив или объект {"products":[...]} / {"knowledge":[...]}. В CSV/XLSX названия полей находятся в первой строке. Знание с тем же именем файла и заголовком обновляется. Данные доступны поиску и ИИ сразу. Первоначальные шесть книг подготовлены отдельно; простой импорт рассчитан на указанную структуру.

Рекомендации

Вкладка «Рекомендации» рассчитывает ориентиры по 497 товарам из снимка на 22.09.2026: излишки, пополнение и позиции для проверки. Доступны поиск по артикулу/названию, фильтр и целевой запас в месяцах. Пополнение учитывает товар в пути и округляется до MOQ; отсутствующие и отрицательные данные отмечаются отдельно. Каждая карточка показывает расчёт и исходную строку таблицы. Для избытка можно подготовить объявление, самостоятельно указав актуальную цену, адрес и координаты.

Это расчёт по исторической выгрузке: перед заказом или публикацией проверьте актуальные остатки, ожидаемые поставки и спрос. При стандартном запасе 3 месяца: 226 кандидатов на избыток, 193 на пополнение, 78 требуют проверки. Интерфейс, карта и формы оформлены в чёрно-белой тёмной теме.

HTTP API и тесты

Интерактивная схема всех маршрутов — /docs после запуска. Основные API: /api/auth/*, /api/offers, /api/recommendations, /api/geo/search, /api/chat, /api/products, /api/knowledge, /api/sources/{id}, /api/data/status, /api/data/import, /api/cart/*.

GET /api/offers принимает q, category, lat, lng, radius_km, mine. Импорт — multipart file и kind=products/knowledge. Чат — JSON message, locale (ru/kk) и необязательная пара lat/lng.

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -q

68 тестов проверяют изоляцию аккаунтов, отзыв сессий, владельцев объявлений, координаты, импорт, сохранение данных, конкурентное резервирование, рекомендации и помощника. Форма регистрации проверяет повтор пароля; есть переключатель видимости пароля. Дополнительно в браузере проверены регистрация, неверный пароль, вход, обновление страницы и выход.

Размещение

Для внешнего доступа нужны сервер и HTTPS. Укажите PUBLIC_ORIGIN и сохраняйте резервные копии data/ekt.sqlite3. В MVP регистрация менеджеров открыта, нет подтверждения email, восстановления пароля и модерации; объявления и знания доступны гостям. Перед публикацией внутренних выгрузок добавьте необходимые компании права доступа. SQLite рассчитана на один сервер. Внешние каталог, оплата и доставка подключаются отдельно. Настоящие API-ключи в поставку не входят.