Skip to content

bitrix-tools/ai-hackathon-starter-full

BranchesTags

Repository files navigation

Bitrix24 AI Hackathon Starter Kit

🚀 Стартер-кит для разработки приложений Bitrix24 с помощью AI-агентов

Этот проект предназначен для помощи разработчикам в создании приложений для Bitrix24 с использованием AI-агентов. Он включает как готовую кодовую базу, так и набор подробных инструкций для AI-агентов.

🎯 Что предоставляет стартер-кит:

  • Три варианта бэкенда на выбор (PHP, Python, Node.js)
  • Готовый фронтенд на Nuxt 3 с интеграцией Bitrix24 UI Kit
  • Воркеры для фоновых задач
  • Docker-контейнеры для быстрого развертывания
  • Готовые SDK и общие утилиты для работы с Bitrix24 API
  • Makefile для удобства разработки
  • Документированные API endpoints
  • 📋 AI Agent Prompt Starter - подробный промпт для AI-агентов в файле AI_AGENT_PROMPT_STARTER.md
  • 📚 Набор инструкций для AI-агентов в папке instructions/

Разработчики могут легко добавлять собственные бэкенды, просто создав папку в backends/ с соответствующей структурой.

🤖 Инструкции для AI-агентов

⭐ Главный файл: AI_AGENT_PROMPT_STARTER.md - комплексный промпт для AI-агентов с пошаговыми инструкциями по развертыванию и разработке.

📁 Папка инструкций: instructions/ содержит:

  • Руководства по использованию SDK (JS, PHP, Python)
  • Инструкции по работе с Bitrix24 UI Kit
  • Примеры создания виджетов и роботов
  • Стандарты качества кода для всех языков
  • Подробные API-справочники

🏗️ Основные компоненты

Обязательные права доступа: crm, user_brief, pull, placement, userfieldconfig

Для разработки используйте:

  • Cloudpub или ngrok для публичного HTTPS доступа
  • Docker для контейнеризации

📁 Структура проекта

ai-hackathon-starter-full/
├── frontend/                    # Nuxt 3 фронтенд с Bitrix24 UI Kit
├── backends/                    # Три варианта бэкенда на выбор
│   ├── php/                    # Symfony + PHP SDK
│   ├── python/                 # Django + b24pysdk
│   └── node/                   # Express + Node.js
├── infrastructure/
│   └── database/               # PostgreSQL (init.sql)
├── instructions/               # 📚 Инструкции для AI-агентов
├── logs/                       # Логи вне контейнеров
├── AI_AGENT_PROMPT_STARTER.md  # 🤖 Главный промпт для AI
└── docker-compose.yml          # Docker конфигурация

🚀 Быстрый старт

# Скопируйте и настройте переменные окружения
cp .env.example .env

# Разработка с PHP бэкендом
make dev-php

# Разработка с Python бэкендом
make dev-python

# Разработка с Node.js бэкендом
make dev-node

# Остановка всех сервисов
make down

# Продакшн с PHP
make prod-php

# Продакшн с Python
make prod-python

# Продакшн с Node.js
make prod-node

# Только база данных + фронтенд (для тестирования)
COMPOSE_PROFILES= docker-compose up database frontend

# Полный стек
COMPOSE_PROFILES=php,worker docker-compose up -d

🛠️ Технологический стек

Frontend

  • Nuxt 3 (Vue 3, TypeScript)
  • Bitrix24 UI Kit (@bitrix24/b24ui-nuxt)
  • Bitrix24 JS SDK (@bitrix24/b24jssdk-nuxt)
  • Pinia (управление состоянием)
  • i18n (многоязычность)
  • TailwindCSS

Backend (на выбор)

  • PHP: Symfony 7, Doctrine ORM, PHP SDK для Bitrix24
  • Python: Django, b24pysdk
  • Node.js: Express, pg (PostgreSQL), JWT

Infrastructure

  • Docker & Docker Compose
  • PostgreSQL 17
  • Cloudpub (ngrok-like) для туннелирования
  • Nginx (production)

📋 Инструкция по развертыванию

Предварительные требования

  1. Скопируйте файл переменных окружения
cp -pv .env.example .env
  1. Запустите службу туннелирования

Используйте ngrok, cloudpub или другой сервис для получения публичного HTTPS URL. В этом стартере мы используем cloudpub для разработки.

  1. Создайте портал Bitrix24 и локальное приложение

Создайте новое приложение: Битрикс24 → Левое меню → Developer Resources → Other → Local Applications

  1. Заполните параметры локального приложения

Параметры:

  • Server (да)
  • Your handler path (введите URL туннелирования)
  • Initial Installation path (введите URL туннелирования + /install)
  • Menu item text (название вашего приложения)
  • Assign permissions (scope): crm, user_brief, pull, placement, userfieldconfig - минимальные права для демо-приложения

🔧 Пошаговая настройка PHP бэкенда

на macOS Перейдите в docker-compose.yml и измените image: cloudpub/cloudpub:latest на image: cloudpub/cloudpub:latest-arm64 в контейнере cloudpub

  1. Введите ваш API-ключ cloudpub в файл .env
CLOUDPUB_TOKEN=ваш_токен_здесь
  1. Укажите бэкенд в файле .env
SERVER_HOST=http://api-php:8000
  1. Запустите контейнеры разработки
make dev-php
  1. Обновите зависимости бэкенда
make composer-update
  1. Найдите URL для фронтенда и бэкенда в логах cloudpub

Пример вывода в консоли для cloudpub:

...
cloudpubApiPhp  | http://frontend:3000 -> https://inanely-muscular-wagtail.cloudpub.com:443
...

Note

Если вы используете Windows и api-php не запускается, попробуйте пересохранить файл backends/php/docker/php-fpm/docker-entrypoint.sh

Запомните этот URL.

  1. Установите URL в корневой файл .env

Эти URL используются в вашем фронтенде и бэкенде:

VIRTUAL_HOST=https://inanely-muscular-wagtail.cloudpub.com
  1. Введите их в параметры локального приложения в портале Bitrix24
  • Your handler path: https://inanely-muscular-wagtail.cloudpub.com
  • Initial Installation path: https://inanely-muscular-wagtail.cloudpub.com/install
  • Assign permissions: crm, user_brief, pull, placement, userfieldconfig

После нажатия кнопки сохранения вы увидите параметры локального приложения:

Внимание! Ваши параметры будут отличаться

Пример:

  • Application ID (client_id): local.6901c_xxxxxxx
  • Application key (client_secret): vXpv64o_xxxxxxx
  1. Инициализируйте структуру базы данных
make dev-php-init-database

  1. Перезапустите контейнеры разработки

  2. Установите ваше приложение в портале Bitrix24

🐍 Пошаговая настройка Python бэкенда

на macOS Перейдите в docker-compose.yml и измените image: cloudpub/cloudpub:latest на image: cloudpub/cloudpub:latest-arm64 в контейнере cloudpub

  1. Введите API-ключ cloudpub и учетные данные Django superuser в файл .env
CLOUDPUB_TOKEN=ваш_токен_здесь
DJANGO_SUPERUSER_USERNAME=admin
DJANGO_SUPERUSER_EMAIL=admin@example.com
DJANGO_SUPERUSER_PASSWORD=admin123
  1. Укажите бэкенд в файле .env
SERVER_HOST=http://api-python:8000
  1. Запустите контейнеры разработки
make dev-python

  1. Миграция базы данных и создание Django superuser происходят автоматически после запуска контейнера.

  2. Найдите URL для фронтенда и бэкенда в логах cloudpub

Пример вывода в консоли для cloudpub:

...
cloudpubApiPython  | http://frontend:3000 -> https://inanely-muscular-wagtail.cloudpub.com:443
...

Запомните этот URL.

  1. Установите URL в корневой файл .env
VIRTUAL_HOST=https://inanely-muscular-wagtail.cloudpub.com
  1. Введите их в параметры локального приложения в портале Bitrix24
  • Your handler path: https://inanely-muscular-wagtail.cloudpub.com
  • Initial Installation path: https://inanely-muscular-wagtail.cloudpub.com/install
  • Assign permissions: crm, user_brief, pull, placement, userfieldconfig

После сохранения вы получите параметры приложения:

Внимание! Ваши параметры будут отличаться

Пример:

  • Application ID (client_id): local.6901c_xxxxxxx
  • Application key (client_secret): vXpv64o_xxxxxxx

  1. Перезапустите контейнеры разработки

  2. Установите ваше приложение в портале Bitrix24

  3. Django админ-панель будет доступна по адресу: https://<VIRTUAL_HOST>/api/admin (логин: <DJANGO_SUPERUSER_USERNAME>, пароль: <DJANGO_SUPERUSER_PASSWORD>)

🔌 API Endpoints

Общие принципы

Все запросы (кроме /api/install, /api/getToken) передают JWT в заголовках.

Пример:

const {data, error} = await $fetch('/api/protected-route', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${someJWT}`
  }
});

Сервер проверяет каждый запрос (кроме /api/install, /api/getToken) на наличие действительного JWT токена.

Сервер возвращает ответ в формате JSON.

При возникновении ошибки сервер устанавливает код ответа 401, 404 или 500 и возвращает описание ошибки в следующем формате:

{
  "error": "Internal server error"
}

/api/health

Указывает статус бэкенда.

  • Метод: GET
  • Параметры: нет
  • Ответ:
    • status: string - статус сервера
    • backend: string - тип бэкенда (php/python/node)
    • timestamp: number - временная метка

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

{
  "status": "healthy",
  "backend": "php",
  "timestamp": 1760611967
}

Тестирование:

curl http://localhost:8000/api/health

/api/enum

Возвращает перечисление опций.

  • Метод: GET
  • Параметры: нет
  • Ответ: string[] - массив строк с опциями

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

[
  "option 1",
  "option 2", 
  "option 3"
]

Тестирование:

curl http://localhost:8000/api/enum

/api/list

Возвращает список элементов.

  • Метод: GET
  • Параметры: нет
  • Ответ: string[] - массив строк с элементами

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

[
  "element 1",
  "element 2",
  "element 3"
]

Тестирование:

curl http://localhost:8000/api/list

/api/install

Вызывается из фронтенд клиента при установке приложения.

JWT токен не передается.

  • Метод: POST
  • Параметры:
    • DOMAIN: string - домен портала Bitrix24
    • PROTOCOL: number - протокол (0 - HTTP, 1 - HTTPS)
    • LANG: string - язык интерфейса
    • APP_SID: string - идентификатор сессии приложения
    • AUTH_ID: string - токен авторизации
    • AUTH_EXPIRES: number - время истечения токена
    • REFRESH_ID: string - токен обновления
    • member_id: string - ID участника
    • user_id: number - ID пользователя
    • PLACEMENT: string - размещение приложения
    • PLACEMENT_OPTIONS: object - опции размещения
  • Ответ:
    • message: string - сообщение о результате

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

{
  "message": "Installation successful"
}

Тестирование:

curl -X POST http://localhost:8000/api/install \
  -H "Content-Type: application/json" \
  -d '{"AUTH_ID":"27exx66815","AUTH_EXPIRES":3600,"REFRESH_ID":"176xxxe","member_id":"a3xxx22","user_id":"1","PLACEMENT":"DEFAULT","PLACEMENT_OPTIONS":"{\"any\":\"6\/\"}"}'

/api/getToken

Вызывается фронтендом для получения JWT токена от бэкенда.

На вход передаются данные авторизации от Bitrix24.

Время жизни токена: 1 час.

JWT токен не передается.

  • Метод: POST
  • Параметры:
    • DOMAIN: string - домен портала Bitrix24
    • PROTOCOL: number - протокол (0 - HTTP, 1 - HTTPS)
    • LANG: string - язык интерфейса
    • APP_SID: string - идентификатор сессии приложения
    • AUTH_ID: string - токен авторизации
    • AUTH_EXPIRES: number - время истечения токена
    • REFRESH_ID: string - токен обновления
    • member_id: string - ID участника
    • user_id: number - ID пользователя
  • Ответ:
    • token: string - JWT токен для дальнейших запросов

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

{
  "token": "AIHBdxxxLLL"
}

Тестирование:

curl -X POST http://localhost:8000/api/getToken \
  -H "Content-Type: application/json" \
  -d '{"AUTH_ID":"27exx66815","AUTH_EXPIRES":3600,"REFRESH_ID":"176xxxe","member_id":"a3xxx22","user_id":1}'

📚 Дополнительные ресурсы

AI-агенты и инструкции

Стандарты качества кода

🤝 Участие в разработке

Этот стартер-кит создан для облегчения разработки приложений Bitrix24 с помощью AI-агентов. Вы можете:

  1. Использовать готовые инструкции для обучения AI-агентов
  2. Дорабатывать существующие SDK примеры
  3. Добавлять новые бэкенды в папку backends/
  4. Улучшать документацию и инструкции

📄 Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

8 stars

Watchers

2 watching

Forks

8 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages