{"id":42457036,"url":"https://github.com/bitrix-tools/b24-ai-starter","last_synced_at":"2026-01-28T09:01:25.375Z","repository":{"id":327741008,"uuid":"1103861492","full_name":"bitrix-tools/b24-ai-starter","owner":"bitrix-tools","description":"Универсальный стартер приложения для разработки с помощью AI-агентов","archived":false,"fork":false,"pushed_at":"2025-12-23T14:07:43.000Z","size":858,"stargazers_count":5,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-25T03:59:07.576Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitrix-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-25T12:39:01.000Z","updated_at":"2025-12-23T14:18:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bitrix-tools/b24-ai-starter","commit_stats":null,"previous_names":["bitrix-tools/b24-ai-starter"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bitrix-tools/b24-ai-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitrix-tools%2Fb24-ai-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitrix-tools%2Fb24-ai-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitrix-tools%2Fb24-ai-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitrix-tools%2Fb24-ai-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitrix-tools","download_url":"https://codeload.github.com/bitrix-tools/b24-ai-starter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitrix-tools%2Fb24-ai-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28843111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T07:39:25.367Z","status":"ssl_error","status_checked_at":"2026-01-28T07:39:24.487Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-28T09:01:07.288Z","updated_at":"2026-01-28T09:01:25.368Z","avatar_url":"https://github.com/bitrix-tools.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Стартер-кит для разработки приложений Bitrix24 с помощью AI-агентов\n\nЭтот проект предназначен для помощи разработчикам в создании приложений для Bitrix24 с использованием AI-агентов. Он включает как готовую кодовую базу, так и набор подробных инструкций для AI-агентов.\n\nТы - эксперт-разработчик, помогающий создавать приложения для Bitrix24 на основе готового стартер-кита. Твой проект находится в репозитории: `https://github.com/bitrix-tools/b24-ai-starter`\n\n## 🎯 Что предоставляет стартер-кит:\n\n- **Три варианта бэкенда** на выбор (PHP, Python, Node.js)\n- **Готовый фронтенд** на Nuxt 3 с интеграцией Bitrix24 UI Kit\n- **Воркеры** для фоновых задач\n- **Docker-контейнеры** для быстрого развертывания\n- **Готовые SDK** и общие утилиты для работы с Bitrix24 API\n- **Makefile** для удобства разработки\n- **Документированные API endpoints**\n- **📚 Модульные инструкции** для AI-агентов в папке `instructions/`\n- **♻️ Поддержка версионности** через `scripts/create-version.sh` и расширенную инициализацию `dev-init`\n- **🔐 Готовая аутентификация и безопасность**\n- **🎨 Интеграция с Bitrix24 UI Kit и JS SDK**\n- **🐇 RabbitMQ сервис** с готовой интеграцией и инструкциями для всех стеков\n\nРазработчики могут легко добавлять собственные бэкенды, просто создав папку в `backends/` с соответствующей структурой.\n\n## 🤖 Инструкции для AI-агентов\n\n**📚 Центральный узел знаний:** [`instructions/knowledge.md`](./instructions/knowledge.md) - главная точка входа для AI-агентов с языково-агностической информацией и навигацией по специализированным разделам.\n\n**🏗️ Модульная архитектура инструкций:**\n\n```\ninstructions/\n├── knowledge.md              # 🎯 Центральный узел - начните отсюда!\n├── php/knowledge.md          # 🐘 Общие знания по PHP\n├── python/knowledge.md       # 🐍 Общие знания по Python  \n├── node/knowledge.md         # 🟢 Общие знания по Node.js\n├── queues/                   # 🐇 Очереди и фоновые задачи\n├── frontend/knowledge.md     # 🎨 Общие знания по frontend\n├── bitrix24/                 # 🏢 Платформенные инструкции\n├── versioning/               # 🏢 Инструкции для создания версий\n└── [язык]/[специфика].md     # 📋 Детальные инструкции\n```\n\n**💡 Как работать с инструкциями:**\n1. **Начните** с `knowledge.md` для общего понимания\n2. **Выберите** технологический стек  \n3. **Изучите** `[язык]/knowledge.md` для языковых особенностей\n4. **Обращайтесь** к специфическим инструкциям по мере необходимости\n\n## ♻️ Версионность проекта\n\n- 📄 **Промпт для агентов:** [`instructions/versioning/create-version-prompt.md`](./instructions/versioning/create-version-prompt.md) — описывает сценарий «создать V2», чеклист проверки и способы переключения\n- 🛠 **Создание версии:** `./scripts/create-version.sh v2` копирует текущий фронтенд/бэкенд/инфраструктуру и прописывает `APP_VERSION=v2` в `.env`\n- 📟 **Вызов через Make:** `make create-version VERSION=v2` и `make delete-version VERSION=v2` проксируют соответствующие скрипты (без `VERSION` включается интерактивный режим)\n- 🗑 **Удаление версии:** `./scripts/delete-version.sh v2` удаляет папку `versions/v2` и при необходимости убирает `APP_VERSION` из `.env`\n- 🚀 **Запуск нужной копии:** `make dev-init` автоматически предложит выбрать один из каталогов `versions/*`, либо можно явно указать `DEV_INIT_VERSION=v2 make dev-init` или `./scripts/dev-init.sh --version v2`\n- 🧹 **Работа с git:** по умолчанию `versions/` участвует в истории; если версия нужна только локально — добавьте каталог в `.gitignore` перед коммитом\n\n## 🏗️ Основные компоненты\n\n**Обязательные права доступа**: `crm`, `user_brief`, `pull`, `placement`, `userfieldconfig`\n\n**Для разработки используется:**\n- Cloudpub для публичного HTTPS доступа\n- Docker для контейнеризации\n\n## 📁 Структура проекта\n\n```text\nb24-ai-starter/\n├── frontend/                 # Nuxt 3 фронтенд с Bitrix24 UI Kit\n├── backends/                 # Три варианта бэкенда на выбор\n│   ├── php/                  # Symfony + PHP SDK\n│   ├── python/               # Django + b24pysdk\n│   └── node/                 # Express + Node.js\n├── infrastructure/\n│   └── database/             # PostgreSQL (init.sql)\n├── instructions/             # 📚 Модульные инструкции для AI-агентов\n│   ├── knowledge.md          # Центральный узел знаний\n│   ├── php/                  # PHP-специфичные инструкции\n│   ├── python/               # Python-специфичные инструкции\n│   ├── node/                 # Node.js-специфичные инструкции\n│   ├── frontend/             # Frontend-специфичные инструкции\n│   ├── versioning/           # Инструкции для версионности проекта\n│   ├── queues/               # Инструкции для сервиса очередей RabbitMQ\n│   └── bitrix24/             # Платформенные инструкции\n├── logs/                     # Логи вне контейнеров\n├── versions/                 # Версии проекта\n├── README.md                 # 🤖 Главный промпт для AI\n└── docker-compose.yml        # Docker конфигурация\n```\n\n## 🚀 Быстрый старт\n\nТекущий проект содержит полнофункциональную заготовку приложения, которую можно использовать как в качестве локального приложения, так и в качестве тиражного решения Маркетплейс.\n\nПоследовательность действий для запуска разработки:\n\n1. Воспользуйтесь нижеописанной **автоматической инициализацией** для быстрого старта. Она создаст технический домен на Cloudpub, запустит Docker контейнеры и настроит окружение. Чтобы проверить, что всё работает, надо будет открыть в браузере технический домен. Поскольку приложение должно работать внутри Битрикс24, то при открытии в браузере вы увидите сообщение об ошибке, но с комментарием, что это нормальная ситуация и надо открыть тот же URL внутри Битрикс24. Это значит, что окружение настроено правильно, но приложение пока не получило токены авторизации от Битрикс24.\n\n2. Зная технический домен, вы можете добавить его в настройки локального приложения в вашем портале Битрикс24 или в карточку приложения в кабинете разработчик https://vendors.bitrix24.ru, чтобы продолжить разработку и тестирование.\n\n- **Основной URL приложения**: `[технический-домен]/`\n- **URL установки приложения**: `[технический-домен]/install`\n- **Разрешения (скоупы)**: `crm`, `user_brief`, `pull`, `placement`, `userfieldconfig`\n\nПосле добавления приложения вы получите необходимые параметры CLIENT_ID и CLIENT_SECRET для вашего приложения. Вставьте их в соответствующие переменные окружения в файле `.env` и перезапустите Docker контейнеры командами `make down` и затем `make dev-php` (или `make dev-python` / `make dev-node` в зависимости от выбранного бэкенда).  Подробнее про [добавление локального приложения](https://apidocs.bitrix24.ru/local-integrations/serverside-local-app-with-ui.html) и про [добавление тиражного приложения](https://apidocs.bitrix24.ru/market/preparing-to-publish/how-to-add-app.html)\n\n3. Переустановите приложение в вашем портале Битрикс24.\n\nТеперь вы готовы начать разработку вашего приложения для Bitrix24 на базе текущего проекта!\n\n### Автоматическая инициализация (рекомендуется)\n\n```bash\n# Запуск интерактивного мастера настройки\nmake dev-init\n```\n\n**Мастер автоматически:**\n- Запросит API ключ CloudPub\n- Позволит выбрать бэкенд (PHP/Python/Node.js)\n- Удалит неиспользуемые папки бэкендов\n- Настроит переменные окружения\n- Получит публичный домен от CloudPub\n- Запустит Docker контейнеры\n\n### Ручная настройка (вместо автоматической настройки)\n\n```bash\n# Скопируйте и настройте переменные окружения\ncp .env.example .env\n\n# Разработка с PHP бэкендом\nmake dev-php\n\n# Разработка с Python бэкендом\nmake dev-python\n\n# Разработка с Node.js бэкендом\nmake dev-node\n\n# Остановка всех сервисов\nmake down\n\n# Продакшн с PHP\nmake prod-php\n\n# Продакшн с Python\nmake prod-python\n\n# Продакшн с Node.js\nmake prod-node\n\n# Только база данных + фронтенд (для тестирования)\nCOMPOSE_PROFILES= docker-compose up database frontend\n\n# Полный стек\nCOMPOSE_PROFILES=php,worker docker-compose up -d\n```\n\n### Запуск в production режиме\n\nДля использования в production-среде настоятельно рекомендуется внести свои значения в переменные окружения:\n\nJWT_SECRET - для шифрования JWT-токенов обмена данными между frontend и backend.\nDB_USER - имя пользователя базы данных PostgreSQL\nDB_PASSWORD - пароль пользователя базы данных PostgreSQL\nDB_NAME - имя базы данных PostgreSQL\nBUILD_TARGET установить в `production` - для сборки фронтенда в production режиме.\nDJANGO_SUPERUSER_USERNAME - имя суперпользователя Django в случае backend на Python\nDJANGO_SUPERUSER_EMAIL - email суперпользователя Django.\nDJANGO_SUPERUSER_PASSWORD - пароль суперпользователя Django.\n\n## 🛠️ Технологический стек\n\n### Frontend\n\n- **Nuxt 3** (Vue 3, TypeScript)\n- **Bitrix24 UI Kit** (`@bitrix24/b24ui-nuxt`)\n- **Bitrix24 JS SDK** (`@bitrix24/b24jssdk-nuxt`)\n- **Pinia** (управление состоянием)\n- **i18n** (многоязычность)\n- **TailwindCSS**\n\n### Backend (на выбор)\n\n- **PHP**: Symfony 7, Doctrine ORM, PHP SDK для Bitrix24\n- **Python**: Django, Python SDK для Bitrix24\n- **Node.js**: Express, pg (PostgreSQL), JWT, JS SDK для Bitrix24\n\n### Infrastructure\n\n- **Docker \u0026 Docker Compose**\n- **PostgreSQL 17**\n- **Cloudpub** (ngrok-like) для туннелирования\n- **Nginx** (production)\n\n### Особенности различных backend\n\n#### PHP\n\nЕсли вы используете Windows и api-php не запускается, попробуйте пересохранить файл `backends/php/docker/php-fpm/docker-entrypoint.sh`\n\n#### Python\n\n**Django админ-панель будет доступна по адресу**: `https://\u003cVIRTUAL_HOST\u003e/api/admin`\n    (логин: `\u003cDJANGO_SUPERUSER_USERNAME\u003e`, пароль: `\u003cDJANGO_SUPERUSER_PASSWORD\u003e`)\n\n## 🛡️ Проверка безопасности\n\n### Оркестратор security-тестов\n\n- `make security-tests` запускает `scripts/security-tests.sh`, который в Docker-окружении выполняет аудит зависимостей, статические анализаторы и общие проверки (Semgrep OWASP Top 10, Gitleaks, Trivy).\n- При запуске скрипт автоматически определяет активный backend (PHP/Python/Node) и фронтенд, поэтому разработчику не нужно вручную выбирать команды.\n- Доступны профили:\n  - `quick` (по умолчанию) — dependency audit + Semgrep.\n  - `full` — быстрый профиль + phpstan/bandit/eslint, а также Gitleaks и Trivy.\n  - `custom` — интерактивный выбор шагов.\n- В интерактивном режиме шаги с найденными уязвимостями помечаются как «предупреждение», чтобы новички видели результат, но пайплайн продолжал работу; в `--ci` режиме такие шаги считаются ошибкой.\n- Отчёты сохраняются в `reports/security/\u003ctimestamp\u003e/...`. Строгий режим CI включается флагом `--ci`, дополнительный параметр `--allow-fail` позволяет завершить скрипт с кодом `0` даже при ошибках.\n- Через `make` можно передать параметры: `make security-tests SECURITY_TESTS_ARGS=\"--profile full --allow-fail\"`.\n\n### Быстрый аудит зависимостей\n\n- Выполните `make security-scan`, чтобы вручную запустить `scripts/security-scan.sh`.\n- Скрипт проводит `composer audit --locked --format=json` внутри контейнера `php-cli`, если в проекте есть `backends/php`.\n- Для фронтенда выполняется `pnpm audit --prod --json` в контейнере `frontend`.\n- JSON-отчёты сохраняются в `reports/security/php-composer.json` и `reports/security/frontend-pnpm.json`.\n- По умолчанию скрипт завершает работу с ненулевым кодом, если одна из проверок нашла уязвимости. Включите мягкий режим через `SECURITY_SCAN_ALLOW_FAILURES=1 make security-scan` (или `./scripts/security-scan.sh --allow-fail`), чтобы всегда получать код выхода `0`.\n- Команда ничего не запускает автоматически; её можно добавлять в локальные чеклисты перед релизом или запускать в CI вручную.\n\n## 🐇 Очереди и RabbitMQ\n\n- `make dev-init` может автоматически развернуть контейнер RabbitMQ и сгенерировать учётные данные (сохраняются в `.env`).\n- Брокер доступен в профиле `queue` (AMQP `5672`, панель `15672`).\n- Для ручного старта/остановки используйте `make queue-up` и `make queue-down`.\n- Подробности и чеклисты по каждому стеку:\n  - Сервис и переменные окружения — `instructions/queues/server.md`\n  - PHP + Messenger — `instructions/queues/php.md`\n  - Python + Celery — `instructions/queues/python.md`\n  - Node.js + amqplib — `instructions/queues/node.md`\n\n## 📚 SDK документация\n\n### Bitrix24 JS SDK\n\n- Используется через `@bitrix24/b24jssdk-nuxt`\n- Документация: см. [`instructions/frontend/bitrix24-js-sdk.md`](./instructions/frontend/bitrix24-js-sdk.md) в проекте\n\n### Bitrix24 UI Kit\n\n- Компоненты через `@bitrix24/b24ui-nuxt`\n- Документация: см. [`instructions/frontend/bitrix24-ui-kit.md`](./instructions/frontend/bitrix24-ui-kit.md) в проекте\n\n### PHP SDK\n\n- Используется в `backends/php/`\n- Документация: см. [`instructions/php/bitrix24-php-sdk.md`](./instructions/php/bitrix24-php-sdk.md) в проекте\n\n### Python SDK (b24pysdk)\n\n- Используется в `backends/python/`\n- Документация: см. [`instructions/python/bitrix24-python-sdk.md`](./instructions/python/bitrix24-python-sdk.md) в проекте\n\n## 🔐 Аутентификация и безопасность\n\n### JWT токены\n\nВсе API endpoints (кроме `/api/install` и `/api/getToken`) требуют JWT токен в заголовке:\n\n```javascript\nAuthorization: `Bearer ${tokenJWT}`\n```\n\n### Процесс аутентификации\n\n1. **Установка приложения** (`/api/install`):\n   - Получает данные из Bitrix24 (`DOMAIN`, `AUTH_ID`, `REFRESH_TOKEN`, `member_id`, `user_id`, и т.д.)\n   - Сохраняет данные установки в БД\n   - **НЕ требует JWT**\n\n2. **Получение токена** (`/api/getToken`):\n   - Принимает данные аутентификации Bitrix24\n   - Генерирует JWT токен (TTL: 1 час)\n   - Сохраняет связь с Bitrix24 аккаунтом\n   - **НЕ требует JWT**\n\n3. **Защищенные endpoints**:\n   - Проверяют JWT токен через middleware/decorators\n   - Извлекают `bitrix24_account` из токена\n   - Предоставляют доступ к Bitrix24 API через SDK\n\n## 🔌 API Endpoints\n\n### Общие принципы\n\nВсе запросы (кроме `/api/install`, `/api/getToken`) передают JWT в заголовках.\n\nПример:\n\n```javascript\nconst {data, error} = await $fetch('/api/protected-route', {\n  method: 'GET',\n  headers: {\n    Authorization: `Bearer ${someJWT}`\n  }\n});\n```\n\nСервер проверяет каждый запрос (кроме `/api/install`, `/api/getToken`) на наличие действительного JWT токена.\n\nСервер возвращает ответ в формате `JSON`.\n\nПри возникновении ошибки сервер устанавливает код ответа `401`, `404` или `500` и возвращает описание ошибки в следующем формате:\n\n```json\n{\n  \"error\": \"Internal server error\"\n}\n```\n\n### `/api/health`\n\nУказывает статус бэкенда.\n\n- **Метод**: `GET`\n- **Параметры**: нет\n- **Ответ**:\n  - `status`: `string` - статус сервера\n  - `backend`: `string` - тип бэкенда (php/python/node)\n  - `timestamp`: `number` - временная метка\n\nПример ответа:\n\n```json\n{\n  \"status\": \"healthy\",\n  \"backend\": \"php\",\n  \"timestamp\": 1760611967\n}\n```\n\nТестирование:\n\n```bash\ncurl http://localhost:8000/api/health\n```\n\n### `/api/enum`\n\nВозвращает перечисление опций.\n\n- **Метод**: `GET`\n- **Параметры**: нет\n- **Ответ**: `string[]` - массив строк с опциями\n\nПример ответа:\n\n```json\n[\n  \"option 1\",\n  \"option 2\", \n  \"option 3\"\n]\n```\n\nТестирование:\n\n```bash\ncurl http://localhost:8000/api/enum\n```\n\n### `/api/list`\n\nВозвращает список элементов.\n\n- **Метод**: `GET`\n- **Параметры**: нет\n- **Ответ**: `string[]` - массив строк с элементами\n\nПример ответа:\n\n```json\n[\n  \"element 1\",\n  \"element 2\",\n  \"element 3\"\n]\n```\n\nТестирование:\n\n```bash\ncurl http://localhost:8000/api/list\n```\n\n### `/api/install`\n\nВызывается из фронтенд клиента при установке приложения.\n\n**JWT токен не передается.**\n\n- **Метод**: `POST`\n- **Параметры**:\n  - `DOMAIN`: `string` - домен портала Bitrix24\n  - `PROTOCOL`: `number` - протокол (0 - HTTP, 1 - HTTPS)\n  - `LANG`: `string` - язык интерфейса\n  - `APP_SID`: `string` - идентификатор сессии приложения\n  - `AUTH_ID`: `string` - токен авторизации\n  - `AUTH_EXPIRES`: `number` - время истечения токена\n  - `REFRESH_ID`: `string` - токен обновления\n  - `member_id`: `string` - ID участника\n  - `user_id`: `number` - ID пользователя\n  - `PLACEMENT`: `string` - размещение приложения\n  - `PLACEMENT_OPTIONS`: `object` - опции размещения\n- **Ответ**:\n  - `message`: `string` - сообщение о результате\n\nПример ответа:\n\n```json\n{\n  \"message\": \"Installation successful\"\n}\n```\n\nТестирование:\n\n```bash\ncurl -X POST http://localhost:8000/api/install \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"AUTH_ID\":\"27exx66815\",\"AUTH_EXPIRES\":3600,\"REFRESH_ID\":\"176xxxe\",\"member_id\":\"a3xxx22\",\"user_id\":\"1\",\"PLACEMENT\":\"DEFAULT\",\"PLACEMENT_OPTIONS\":\"{\\\"any\\\":\\\"6\\/\\\"}\"}'\n```\n\n### `/api/getToken`\n\nВызывается фронтендом для получения JWT токена от бэкенда.\n\nНа вход передаются данные авторизации от Bitrix24.\n\nВремя жизни токена: **1 час**.\n\n**JWT токен не передается.**\n\n- **Метод**: `POST`\n- **Параметры**:\n  - `DOMAIN`: `string` - домен портала Bitrix24\n  - `PROTOCOL`: `number` - протокол (0 - HTTP, 1 - HTTPS)\n  - `LANG`: `string` - язык интерфейса\n  - `APP_SID`: `string` - идентификатор сессии приложения\n  - `AUTH_ID`: `string` - токен авторизации\n  - `AUTH_EXPIRES`: `number` - время истечения токена\n  - `REFRESH_ID`: `string` - токен обновления\n  - `member_id`: `string` - ID участника\n  - `user_id`: `number` - ID пользователя\n- **Ответ**:\n  - `token`: `string` - JWT токен для дальнейших запросов\n\nПример ответа:\n\n```json\n{\n  \"token\": \"AIHBdxxxLLL\"\n}\n```\n\nТестирование:\n\n```bash\ncurl -X POST http://localhost:8000/api/getToken \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"AUTH_ID\":\"27exx66815\",\"AUTH_EXPIRES\":3600,\"REFRESH_ID\":\"176xxxe\",\"member_id\":\"a3xxx22\",\"user_id\":1}'\n```\n\n### Пример добавления нового endpoint\n\n**PHP (Symfony):**\n\n```php\n#[Route('/api/my-endpoint', name: 'api_my_endpoint', methods: ['GET'])]\npublic function myEndpoint(Request $request): JsonResponse\n{\n    // JWT payload доступен через:\n    $jwtPayload = $request-\u003eattributes-\u003eget('jwt_payload');\n    \n    // Bitrix24 аккаунт через:\n    // $bitrix24Account = ...\n    \n    return new JsonResponse(['data' =\u003e 'value'], 200);\n}\n```\n\n**Python (Django):**\n\n```python\n@xframe_options_exempt\n@require_GET\n@log_errors(\"my_endpoint\")\n@auth_required\ndef my_endpoint(request: AuthorizedRequest):\n    # Bitrix24 клиент доступен через:\n    client = request.bitrix24_account.client\n    \n    # Вызов Bitrix24 API:\n    response = client._bitrix_token.call_method(\n        api_method='method.name',\n        params={'param': 'value'}\n    )\n    \n    return JsonResponse({'data': 'value'})\n```\n\n**Node.js (Express):**\n\n```javascript\napp.get('/api/my-endpoint', verifyToken, async (req, res) =\u003e {\n  // JWT payload доступен через:\n  const jwtPayload = req.jwtPayload;\n  \n  // Bitrix24 API вызовы...\n  \n  res.json({ data: 'value' });\n});\n```\n\n## 🎨 Frontend структура и работа с Bitrix24\n\n### Основные директории\n\n**`app/pages/`** - Страницы приложения:\n\n- `index.client.vue` - Главная страница\n- `install.client.vue` - Страница установки\n- `*.client.vue` - Клиентские страницы (SSR отключен)\n\n**`app/stores/`** - Pinia stores:\n\n- `api.ts` - API методы и JWT управление\n- `user.ts` - Данные пользователя\n- `appSettings.ts` - Настройки приложения\n- `userSettings.ts` - Пользовательские настройки\n\n**`app/composables/`**:\n\n- `useAppInit.ts` - Инициализация приложения, загрузка данных через batch\n- `useBackend.ts` - Работа с бэкендом\n\n**`app/middleware/`**:\n\n- `01.app.page.or.slider.global.ts` - Глобальный middleware для инициализации B24Frame и обработки placement\n\n**`app/layouts/`**:\n\n- `default.vue` - Основной layout\n- `placement.vue` - Layout для placement\n- `slider.vue` - Layout для слайдеров\n- `uf-placement.vue` - Layout для user fields\n\n### Работа с Bitrix24 JS SDK\n\n```typescript\n// Получение B24Frame\nconst { $initializeB24Frame } = useNuxtApp()\nconst $b24: B24Frame = await $initializeB24Frame()\n\n// Batch запросы\nconst response = await $b24.callBatch({\n  appInfo: { method: 'app.info' },\n  profile: { method: 'profile' }\n})\nconst data = response.getData()\n\n// Одиночные вызовы\nconst result = await $b24.callMethod('method.name', { param: 'value' })\n\n// Работа с аутентификацией\nconst authData = $b24.auth.getAuthData()\n\n// Открытие слайдеров\nawait $b24.slider.openPath('/path/to/page')\n```\n\n### Работа с API store\n\n```typescript\nconst apiStore = useApiStore()\n\n// Инициализация (после инициализации B24Frame)\nawait apiStore.init($b24)\n\n// Запросы с автоматической передачей JWT\nconst data = await apiStore.getList()\nconst enumData = await apiStore.getEnum()\n\n// Добавление нового метода в store\n// В app/stores/api.ts:\nconst myMethod = async (): Promise\u003cMyType\u003e =\u003e {\n  return await $api('/api/my-endpoint', {\n    headers: {\n      Authorization: `Bearer ${tokenJWT.value}`\n    }\n  })\n}\n```\n\n### Использование Bitrix24 UI Kit\n\nКомпоненты доступны автоматически через `@bitrix24/b24ui-nuxt`:\n\n```vue\n\u003ctemplate\u003e\n  \u003cB24Card\u003e\n    \u003ctemplate #header\u003e\n      \u003ch1\u003eЗаголовок\u003c/h1\u003e\n    \u003c/template\u003e\n    \n    \u003cB24Button\n      label=\"Кнопка\"\n      color=\"air-primary\"\n      @click=\"handleClick\"\n    /\u003e\n    \n    \u003cB24Input\n      v-model=\"inputValue\"\n      placeholder=\"Введите текст\"\n    /\u003e\n    \n    \u003cB24Badge\n      label=\"Статус\"\n      color=\"air-primary-success\"\n    /\u003e\n    \n    \u003cB24Avatar\n      :src=\"photoUrl\"\n      size=\"md\"\n    /\u003e\n  \u003c/B24Card\u003e\n\u003c/template\u003e\n```\n\n## ⚠️ Встройки (Widgets), события (Events) и роботы (Robots)\n\n### Важно для AI-агентов\n\nЕсли в описании приложения упоминаются **встройки** (widgets), **события** (events) или **роботы** (robots), обязательно изучи следующую документацию:\n\n**Встройки (Widgets):**\n\n- **Онлайн:** [API Reference: Widgets](https://github.com/bitrix-tools/b24-rest-docs/tree/main/api-reference/widgets)\n- **Инструкция:** [Разработка приложения с встройками](https://github.com/bitrix-tools/ai-hackathon-starter-full/blob/main/instructions/ai-instructions-widget-app.md)\n\n**События (Events):**\n\n- **Онлайн:** [API Reference: Events](https://github.com/bitrix-tools/b24-rest-docs/tree/main/api-reference/events)\n- Регистрация через `event.bind` в процессе установки\n- Обработка через публичный endpoint `/api/app-events` (без JWT)\n- Поддержка `application/x-www-form-urlencoded` и JSON\n\n**Роботы (Robots):**\n\n- **Инструкция:** [Создание роботов для бизнес-процессов](https://github.com/bitrix-tools/ai-hackathon-starter-full/blob/main/instructions/ai-instructions-robot.md)\n- Регистрация через `bizproc.robot.add`\n- Обработка через публичный endpoint `/api/robot-handler` (без JWT)\n- Поддержка различных форматов данных от Bitrix24\n\n### Ключевые моменты реализации\n\n1. **Публичные endpoints** - События и роботы не используют JWT\n2. **Обработка форматов данных** - Поддержка form-urlencoded и JSON\n3. **Правильная структура OAuth** - Создание `OAuthPlacementData` для SDK\n4. **Регистрация в установке** - Добавление в `install.client.vue`\n\n## 📚 Дополнительные ресурсы\n\n### AI-агенты и инструкции\n\n- **📚 [Центральный узел знаний](./instructions/knowledge.md)** - главная точка входа для AI-агентов\n\n#### Модульная архитектура знаний\n\n**Backend-специфичные инструкции:**\n- **🐘 [PHP Knowledge](./instructions/php/knowledge.md)** - общие знания по PHP-разработке\n  - [PHP SDK](./instructions/php/bitrix24-php-sdk.md) - работа с PHP SDK\n  - [Code Review](./instructions/php/code-review.md) - стандарты качества\n- **🐍 [Python Knowledge](./instructions/python/knowledge.md)** - общие знания по Python-разработке  \n  - [Python SDK](./instructions/python/bitrix24-python-sdk.md) - работа с Python SDK\n  - [Code Review](./instructions/python/code-review.md) - стандарты качества\n- **🟢 [Node.js Knowledge](./instructions/node/knowledge.md)** - общие знания по Node.js-разработке\n  - [Code Review](./instructions/node/code-review.md) - стандарты качества\n\n**Frontend-специфичные инструкции:**\n- **🎨 [Frontend Knowledge](./instructions/front/knowledge.md)** - общие знания по frontend-разработке\n  - [UI Kit](./instructions/front/bitrix24-ui-kit.md) - работа с UI Kit\n  - [JS SDK](./instructions/front/bitrix24-js-sdk.md) - работа с JS SDK\n  - [Компоненты](./instructions/front/) - детальные инструкции по компонентам\n\n**Платформенные инструкции:**\n- **🏢 [Bitrix24 Platform](./instructions/bitrix24/)** - специфика платформы\n  - [CRM роботы](./instructions/bitrix24/crm-robot.md)\n  - [Виджеты](./instructions/bitrix24/widget.md)\n\n## 🚀 Рекомендации по разработке\n\n### Добавление нового функционала\n\n1. **Backend endpoint:**\n   - Добавь endpoint в соответствующий контроллер/views\n   - Используй декораторы/middleware для аутентификации\n   - Верни JSON ответ\n\n2. **Frontend API метод:**\n   - Добавь метод в `app/stores/api.ts`\n   - Используй `$api` с JWT заголовком\n   - Обработай ошибки\n\n3. **Frontend страница/компонент:**\n   - Создай `.vue` файл в `app/pages/` или `app/components/`\n   - Используй Bitrix24 UI Kit компоненты\n   - Интегрируй с API store\n\n### Лучшие практики\n\n1. **Обработка ошибок:**\n   - Используй `processErrorGlobal` из `useAppInit` для глобальных ошибок\n   - Логируй через `$logger` из composable\n   - Возвращай понятные сообщения об ошибках\n\n2. **Типизация:**\n   - Используй TypeScript для типизации\n   - Определяй интерфейсы для API ответов\n   - Используй `AuthorizedRequest` в Python, JWT payload в PHP/Node\n\n3. **Состояние:**\n   - Используй Pinia stores для глобального состояния\n   - Reactivity через Vue 3 Composition API\n   - Кэшируй данные где необходимо\n\n4. **Производительность:**\n   - Используй batch запросы где возможно\n   - Ленивая загрузка компонентов\n   - Оптимизация изображений и ассетов\n\n## 🤝 Участие в разработке\n\nЭтот стартер-кит создан для облегчения разработки приложений Bitrix24 с помощью AI-агентов. Вы можете:\n\n1. **Использовать готовые инструкции** для обучения AI-агентов\n2. **Дорабатывать существующие SDK** примеры\n3. **Добавлять новые бэкенды** в папку `backends/`\n4. **Улучшать документацию** и инструкции\n\n---\n\n**ВАЖНО:** При работе над задачей пользователя учитывай:\n\n- Архитектуру выбранного бэкенда (PHP/Python/Node.js)\n- Существующие паттерны и структуру проекта\n- Использование Bitrix24 UI Kit для фронтенда\n- Правильную обработку ошибок и типизацию\n- Соответствие стилю кода проекта\n\n## 📄 Лицензия\n\nЭтот проект распространяется под лицензией MIT. См. файл [LICENSE](./LICENSE) для подробностей.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitrix-tools%2Fb24-ai-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitrix-tools%2Fb24-ai-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitrix-tools%2Fb24-ai-starter/lists"}