Skip to content
/ b24-ai-starter Public

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

License

MIT license
5 stars 5 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

bitrix-tools/b24-ai-starter

BranchesTags

Repository files navigation

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

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

Ты - эксперт-разработчик, помогающий создавать приложения для Bitrix24 на основе готового стартер-кита. Твой проект находится в репозитории: https://github.com/bitrix-tools/b24-ai-starter

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

  • Три варианта бэкенда на выбор (PHP, Python, Node.js)
  • Готовый фронтенд на Nuxt 3 с интеграцией Bitrix24 UI Kit
  • Воркеры для фоновых задач
  • Docker-контейнеры для быстрого развертывания
  • Готовые SDK и общие утилиты для работы с Bitrix24 API
  • Makefile для удобства разработки
  • Документированные API endpoints
  • 📚 Модульные инструкции для AI-агентов в папке instructions/
  • ♻️ Поддержка версионности через scripts/create-version.sh и расширенную инициализацию dev-init
  • 🔐 Готовая аутентификация и безопасность
  • 🎨 Интеграция с Bitrix24 UI Kit и JS SDK
  • 🐇 RabbitMQ сервис с готовой интеграцией и инструкциями для всех стеков

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

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

📚 Центральный узел знаний: instructions/knowledge.md - главная точка входа для AI-агентов с языково-агностической информацией и навигацией по специализированным разделам.

🏗️ Модульная архитектура инструкций:

instructions/
├── knowledge.md              # 🎯 Центральный узел - начните отсюда!
├── php/knowledge.md          # 🐘 Общие знания по PHP
├── python/knowledge.md       # 🐍 Общие знания по Python  
├── node/knowledge.md         # 🟢 Общие знания по Node.js
├── queues/                   # 🐇 Очереди и фоновые задачи
├── frontend/knowledge.md     # 🎨 Общие знания по frontend
├── bitrix24/                 # 🏢 Платформенные инструкции
├── versioning/               # 🏢 Инструкции для создания версий
└── [язык]/[специфика].md     # 📋 Детальные инструкции

💡 Как работать с инструкциями:

  1. Начните с knowledge.md для общего понимания
  2. Выберите технологический стек
  3. Изучите [язык]/knowledge.md для языковых особенностей
  4. Обращайтесь к специфическим инструкциям по мере необходимости

♻️ Версионность проекта

  • 📄 Промпт для агентов: instructions/versioning/create-version-prompt.md — описывает сценарий «создать V2», чеклист проверки и способы переключения
  • 🛠 Создание версии: ./scripts/create-version.sh v2 копирует текущий фронтенд/бэкенд/инфраструктуру и прописывает APP_VERSION=v2 в .env
  • 📟 Вызов через Make: make create-version VERSION=v2 и make delete-version VERSION=v2 проксируют соответствующие скрипты (без VERSION включается интерактивный режим)
  • 🗑 Удаление версии: ./scripts/delete-version.sh v2 удаляет папку versions/v2 и при необходимости убирает APP_VERSION из .env
  • 🚀 Запуск нужной копии: make dev-init автоматически предложит выбрать один из каталогов versions/*, либо можно явно указать DEV_INIT_VERSION=v2 make dev-init или ./scripts/dev-init.sh --version v2
  • 🧹 Работа с git: по умолчанию versions/ участвует в истории; если версия нужна только локально — добавьте каталог в .gitignore перед коммитом

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

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

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

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

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

b24-ai-starter/
├── 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-агентов
│   ├── knowledge.md          # Центральный узел знаний
│   ├── php/                  # PHP-специфичные инструкции
│   ├── python/               # Python-специфичные инструкции
│   ├── node/                 # Node.js-специфичные инструкции
│   ├── frontend/             # Frontend-специфичные инструкции
│   ├── versioning/           # Инструкции для версионности проекта
│   ├── queues/               # Инструкции для сервиса очередей RabbitMQ
│   └── bitrix24/             # Платформенные инструкции
├── logs/                     # Логи вне контейнеров
├── versions/                 # Версии проекта
├── README.md                 # 🤖 Главный промпт для AI
└── docker-compose.yml        # Docker конфигурация

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

Текущий проект содержит полнофункциональную заготовку приложения, которую можно использовать как в качестве локального приложения, так и в качестве тиражного решения Маркетплейс.

Последовательность действий для запуска разработки:

  1. Воспользуйтесь нижеописанной автоматической инициализацией для быстрого старта. Она создаст технический домен на Cloudpub, запустит Docker контейнеры и настроит окружение. Чтобы проверить, что всё работает, надо будет открыть в браузере технический домен. Поскольку приложение должно работать внутри Битрикс24, то при открытии в браузере вы увидите сообщение об ошибке, но с комментарием, что это нормальная ситуация и надо открыть тот же URL внутри Битрикс24. Это значит, что окружение настроено правильно, но приложение пока не получило токены авторизации от Битрикс24.

  2. Зная технический домен, вы можете добавить его в настройки локального приложения в вашем портале Битрикс24 или в карточку приложения в кабинете разработчик https://vendors.bitrix24.ru, чтобы продолжить разработку и тестирование.

  • Основной URL приложения: [технический-домен]/
  • URL установки приложения: [технический-домен]/install
  • Разрешения (скоупы): crm, user_brief, pull, placement, userfieldconfig

После добавления приложения вы получите необходимые параметры CLIENT_ID и CLIENT_SECRET для вашего приложения. Вставьте их в соответствующие переменные окружения в файле .env и перезапустите Docker контейнеры командами make down и затем make dev-php (или make dev-python / make dev-node в зависимости от выбранного бэкенда). Подробнее про добавление локального приложения и про добавление тиражного приложения

  1. Переустановите приложение в вашем портале Битрикс24.

Теперь вы готовы начать разработку вашего приложения для Bitrix24 на базе текущего проекта!

Автоматическая инициализация (рекомендуется)

# Запуск интерактивного мастера настройки
make dev-init

Мастер автоматически:

  • Запросит API ключ CloudPub
  • Позволит выбрать бэкенд (PHP/Python/Node.js)
  • Удалит неиспользуемые папки бэкендов
  • Настроит переменные окружения
  • Получит публичный домен от CloudPub
  • Запустит 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

Запуск в production режиме

Для использования в production-среде настоятельно рекомендуется внести свои значения в переменные окружения:

JWT_SECRET - для шифрования JWT-токенов обмена данными между frontend и backend. DB_USER - имя пользователя базы данных PostgreSQL DB_PASSWORD - пароль пользователя базы данных PostgreSQL DB_NAME - имя базы данных PostgreSQL BUILD_TARGET установить в production - для сборки фронтенда в production режиме. DJANGO_SUPERUSER_USERNAME - имя суперпользователя Django в случае backend на Python DJANGO_SUPERUSER_EMAIL - email суперпользователя Django. DJANGO_SUPERUSER_PASSWORD - пароль суперпользователя Django.

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

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, Python SDK для Bitrix24
  • Node.js: Express, pg (PostgreSQL), JWT, JS SDK для Bitrix24

Infrastructure

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

Особенности различных backend

PHP

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

Python

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

🛡️ Проверка безопасности

Оркестратор security-тестов

  • make security-tests запускает scripts/security-tests.sh, который в Docker-окружении выполняет аудит зависимостей, статические анализаторы и общие проверки (Semgrep OWASP Top 10, Gitleaks, Trivy).
  • При запуске скрипт автоматически определяет активный backend (PHP/Python/Node) и фронтенд, поэтому разработчику не нужно вручную выбирать команды.
  • Доступны профили:
    • quick (по умолчанию) — dependency audit + Semgrep.
    • full — быстрый профиль + phpstan/bandit/eslint, а также Gitleaks и Trivy.
    • custom — интерактивный выбор шагов.
  • В интерактивном режиме шаги с найденными уязвимостями помечаются как «предупреждение», чтобы новички видели результат, но пайплайн продолжал работу; в --ci режиме такие шаги считаются ошибкой.
  • Отчёты сохраняются в reports/security/<timestamp>/.... Строгий режим CI включается флагом --ci, дополнительный параметр --allow-fail позволяет завершить скрипт с кодом 0 даже при ошибках.
  • Через make можно передать параметры: make security-tests SECURITY_TESTS_ARGS="--profile full --allow-fail".

Быстрый аудит зависимостей

  • Выполните make security-scan, чтобы вручную запустить scripts/security-scan.sh.
  • Скрипт проводит composer audit --locked --format=json внутри контейнера php-cli, если в проекте есть backends/php.
  • Для фронтенда выполняется pnpm audit --prod --json в контейнере frontend.
  • JSON-отчёты сохраняются в reports/security/php-composer.json и reports/security/frontend-pnpm.json.
  • По умолчанию скрипт завершает работу с ненулевым кодом, если одна из проверок нашла уязвимости. Включите мягкий режим через SECURITY_SCAN_ALLOW_FAILURES=1 make security-scan (или ./scripts/security-scan.sh --allow-fail), чтобы всегда получать код выхода 0.
  • Команда ничего не запускает автоматически; её можно добавлять в локальные чеклисты перед релизом или запускать в CI вручную.

🐇 Очереди и RabbitMQ

  • make dev-init может автоматически развернуть контейнер RabbitMQ и сгенерировать учётные данные (сохраняются в .env).
  • Брокер доступен в профиле queue (AMQP 5672, панель 15672).
  • Для ручного старта/остановки используйте make queue-up и make queue-down.
  • Подробности и чеклисты по каждому стеку:
    • Сервис и переменные окружения — instructions/queues/server.md
    • PHP + Messenger — instructions/queues/php.md
    • Python + Celery — instructions/queues/python.md
    • Node.js + amqplib — instructions/queues/node.md

📚 SDK документация

Bitrix24 JS SDK

Bitrix24 UI Kit

PHP SDK

Python SDK (b24pysdk)

🔐 Аутентификация и безопасность

JWT токены

Все API endpoints (кроме /api/install и /api/getToken) требуют JWT токен в заголовке:

Authorization: `Bearer ${tokenJWT}`

Процесс аутентификации

  1. Установка приложения (/api/install):

    • Получает данные из Bitrix24 (DOMAIN, AUTH_ID, REFRESH_TOKEN, member_id, user_id, и т.д.)
    • Сохраняет данные установки в БД
    • НЕ требует JWT

  2. Получение токена (/api/getToken):

    • Принимает данные аутентификации Bitrix24
    • Генерирует JWT токен (TTL: 1 час)
    • Сохраняет связь с Bitrix24 аккаунтом
    • НЕ требует JWT

  3. Защищенные endpoints:

    • Проверяют JWT токен через middleware/decorators
    • Извлекают bitrix24_account из токена
    • Предоставляют доступ к Bitrix24 API через SDK

🔌 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}'

Пример добавления нового endpoint

PHP (Symfony):

#[Route('/api/my-endpoint', name: 'api_my_endpoint', methods: ['GET'])]
public function myEndpoint(Request $request): JsonResponse
{
    // JWT payload доступен через:
    $jwtPayload = $request->attributes->get('jwt_payload');
    
    // Bitrix24 аккаунт через:
    // $bitrix24Account = ...
    
    return new JsonResponse(['data' => 'value'], 200);
}

Python (Django):

@xframe_options_exempt
@require_GET
@log_errors("my_endpoint")
@auth_required
def my_endpoint(request: AuthorizedRequest):
    # Bitrix24 клиент доступен через:
    client = request.bitrix24_account.client
    
    # Вызов Bitrix24 API:
    response = client._bitrix_token.call_method(
        api_method='method.name',
        params={'param': 'value'}
    )
    
    return JsonResponse({'data': 'value'})

Node.js (Express):

app.get('/api/my-endpoint', verifyToken, async (req, res) => {
  // JWT payload доступен через:
  const jwtPayload = req.jwtPayload;
  
  // Bitrix24 API вызовы...
  
  res.json({ data: 'value' });
});

🎨 Frontend структура и работа с Bitrix24

Основные директории

app/pages/ - Страницы приложения:

  • index.client.vue - Главная страница
  • install.client.vue - Страница установки
  • *.client.vue - Клиентские страницы (SSR отключен)

app/stores/ - Pinia stores:

  • api.ts - API методы и JWT управление
  • user.ts - Данные пользователя
  • appSettings.ts - Настройки приложения
  • userSettings.ts - Пользовательские настройки

app/composables/:

  • useAppInit.ts - Инициализация приложения, загрузка данных через batch
  • useBackend.ts - Работа с бэкендом

app/middleware/:

  • 01.app.page.or.slider.global.ts - Глобальный middleware для инициализации B24Frame и обработки placement

app/layouts/:

  • default.vue - Основной layout
  • placement.vue - Layout для placement
  • slider.vue - Layout для слайдеров
  • uf-placement.vue - Layout для user fields

Работа с Bitrix24 JS SDK

// Получение B24Frame
const { $initializeB24Frame } = useNuxtApp()
const $b24: B24Frame = await $initializeB24Frame()

// Batch запросы
const response = await $b24.callBatch({
  appInfo: { method: 'app.info' },
  profile: { method: 'profile' }
})
const data = response.getData()

// Одиночные вызовы
const result = await $b24.callMethod('method.name', { param: 'value' })

// Работа с аутентификацией
const authData = $b24.auth.getAuthData()

// Открытие слайдеров
await $b24.slider.openPath('/path/to/page')

Работа с API store

const apiStore = useApiStore()

// Инициализация (после инициализации B24Frame)
await apiStore.init($b24)

// Запросы с автоматической передачей JWT
const data = await apiStore.getList()
const enumData = await apiStore.getEnum()

// Добавление нового метода в store
// В app/stores/api.ts:
const myMethod = async (): Promise<MyType> => {
  return await $api('/api/my-endpoint', {
    headers: {
      Authorization: `Bearer ${tokenJWT.value}`
    }
  })
}

Использование Bitrix24 UI Kit

Компоненты доступны автоматически через @bitrix24/b24ui-nuxt:

<template>
  <B24Card>
    <template #header>
      <h1>Заголовок</h1>
    </template>
    
    <B24Button
      label="Кнопка"
      color="air-primary"
      @click="handleClick"
    />
    
    <B24Input
      v-model="inputValue"
      placeholder="Введите текст"
    />
    
    <B24Badge
      label="Статус"
      color="air-primary-success"
    />
    
    <B24Avatar
      :src="photoUrl"
      size="md"
    />
  </B24Card>
</template>

⚠️ Встройки (Widgets), события (Events) и роботы (Robots)

Важно для AI-агентов

Если в описании приложения упоминаются встройки (widgets), события (events) или роботы (robots), обязательно изучи следующую документацию:

Встройки (Widgets):

События (Events):

  • Онлайн: API Reference: Events
  • Регистрация через event.bind в процессе установки
  • Обработка через публичный endpoint /api/app-events (без JWT)
  • Поддержка application/x-www-form-urlencoded и JSON

Роботы (Robots):

Ключевые моменты реализации

  1. Публичные endpoints - События и роботы не используют JWT
  2. Обработка форматов данных - Поддержка form-urlencoded и JSON
  3. Правильная структура OAuth - Создание OAuthPlacementData для SDK
  4. Регистрация в установке - Добавление в install.client.vue

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

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

Модульная архитектура знаний

Backend-специфичные инструкции:

Frontend-специфичные инструкции:

Платформенные инструкции:

🚀 Рекомендации по разработке

Добавление нового функционала

  1. Backend endpoint:

    • Добавь endpoint в соответствующий контроллер/views
    • Используй декораторы/middleware для аутентификации
    • Верни JSON ответ

  2. Frontend API метод:

    • Добавь метод в app/stores/api.ts
    • Используй $api с JWT заголовком
    • Обработай ошибки

  3. Frontend страница/компонент:

    • Создай .vue файл в app/pages/ или app/components/
    • Используй Bitrix24 UI Kit компоненты
    • Интегрируй с API store

Лучшие практики

  1. Обработка ошибок:

    • Используй processErrorGlobal из useAppInit для глобальных ошибок
    • Логируй через $logger из composable
    • Возвращай понятные сообщения об ошибках

  2. Типизация:

    • Используй TypeScript для типизации
    • Определяй интерфейсы для API ответов
    • Используй AuthorizedRequest в Python, JWT payload в PHP/Node

  3. Состояние:

    • Используй Pinia stores для глобального состояния
    • Reactivity через Vue 3 Composition API
    • Кэшируй данные где необходимо

  4. Производительность:

    • Используй batch запросы где возможно
    • Ленивая загрузка компонентов
    • Оптимизация изображений и ассетов

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

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

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

ВАЖНО: При работе над задачей пользователя учитывай:

  • Архитектуру выбранного бэкенда (PHP/Python/Node.js)
  • Существующие паттерны и структуру проекта
  • Использование Bitrix24 UI Kit для фронтенда
  • Правильную обработку ошибок и типизацию
  • Соответствие стилю кода проекта

📄 Лицензия

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

About

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

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

5 stars

Watchers

1 watching

Forks

5 forks
Report repository

Releases 1

Новый тест безопасности Latest
Dec 23, 2025

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages