Заменяем Excel-калькулятор КП в Битрикс24 на единое приложение

# ЗАДАЧА

Собери и опубликуй на VibeCode приложение «Калькулятор КП» для отдела продаж,

которое заменяет расчёт в Excel на общем диске.

Смысл кейса: правила ценообразования и предел скидки живут на сервере, а не в

файле у менеджера. Расчёт сразу превращается в сделку и КП в CRM.

Рабочее название: «Калькулятор КП». Язык интерфейса — русский. Валюта — рубль,

цены без НДС.

# 1. БОЛЬ, КОТОРУЮ УБИРАЕМ

У каждого менеджера своя копия таблицы: версии расходятся, формулы правят под

клиента, скидки уходят за регламент, руководитель узнаёт об этом постфактум из

подписанного договора. Нужен один источник правил и один путь «расчёт → сделка».

# 2. ЧТО СТРОИМ (четыре части, не больше)

1. Каталог и расчёт. Товары из раздела каталога CRM, поиск, добавление в

   заказ, количество, стоимость позиции, сумма по заказу.

2. Предел скидки на сервере. Скидка разрешена только в пределах порога,

   который определяется суммой заказа ДО скидки. Ввод сверх предела — отказ,

   а не «тихое урезание».

3. CRM. Выбор компании и контакта из CRM, создание сделки с реальными

   товарными позициями и итоговой суммой с учётом скидки. Опционально —

   коммерческое предложение, связанное со сделкой.

4. Встройка и доступ. Приложение открывается из левого меню портала под

   учётной записью сотрудника. Политика доступа «Отдел»: калькулятором

   пользуются только сотрудники выбранного отдела.

# 3. ДАННЫЕ

Источник — REST API подключённого портала, только с сервера. Ключ в браузер не

попадает, фронт ходит только на собственные /api/*.

Читаем: товары и цены каталога, компании, контакты, стадии воронки.

Пишем: сделку, товарные позиции сделки, коммерческое предложение.

Цены не хардкодить и не держать константами: если цена изменилась в CRM,

приложение считает по новой. Справочники не дёргать на каждый запрос — собрать

снимок в фоне и отдавать из памяти с подписью «обновлено N минут назад».

Точные пути и поля брать из скилов bitrix-app-data, crm, crm-finance.

Перед реализацией проверить на живом портале, что сущность «Коммерческое

предложение» доступна и у ключа есть право. Недоступна — не изобретать обход:

создавать сделку с позициями, а про КП честно написать в отчёте.

# 4. ПРАВИЛА СКИДОК (единственное правило приложения)

Порог определяется по сумме заказа ДО скидки:

| Сумма до скидки          | Максимальная скидка |

|--------------------------|---------------------|

| до 100 000 ₽             | 5 %                 |

| от 100 000 до 299 999,99 | 10 %                |

| от 300 000 ₽             | 15 %                |

- Скидка применяется к общей стоимости заказа.

- Показывать три цифры: сумма без скидки, скидка в рублях, итог.

- Скидка выше предела: сообщение с фактическим и допустимым процентом,

  кнопки создания заблокированы.

- Порог проверяется сервером по введённому значению, а не по «зажатому».

# 5. СЕРВЕР — ИСТИНА

- Суммы и лимиты считает сервер. Сумму от клиента не принимать и не доверять ей.

- Перед созданием сделки заново прочитать цены из каталога и пересчитать сумму

  и предел. Цена изменилась — считать по новой.

- При превышении предела — 422 с понятным текстом, ничего не создавать.

- Ответственный в сделке — текущий сотрудник. Брать его только из заголовка

  шлюза X-Vibe-User-Id (проверить, что там только цифры; значения вида net_…

  и share: в REST подставлять нельзя). Не полагаться на устаревший кэш профиля

  и не ждать, что /me вернёт currentUser.

- Цены в каталоге не менять, записи не удалять.

# 6. ИДЕНТИЧНОСТЬ И ДОСТУП

- Своего логина нет: личность уже пришла от шлюза. X-Vibe-User-Id — ID

  сотрудника, X-Vibe-User-Name-Encoded — имя через decodeURIComponent,

  X-Vibe-User-Role — роль.

- Ни ID, ни отдел, ни роль из тела запроса или query не принимать никогда.

- Политика «Отдел»: проверить принадлежность сотрудника к разрешённому отделу

  через оргструктуру портала. Не входит — отказ с понятным текстом, пустого

  экрана быть не должно.

- Действия в CRM выполняются в правах сотрудника, а не общего админ-доступа.

# 7. ИДЕМПОТЕНТНОСТЬ

Ключ заказа генерируется на сервере/клиенте один раз на расчёт. Повторный клик

или ретрай возвращает уже созданную сделку, а не создаёт вторую. Во время

создания заказ помечается «в обработке», параллельный дубль получает 409.

# 8. ИНТЕРФЕЙС

Прочитай и примени скил frontend-design. Это рабочий инструмент менеджера:

плотный, быстрый, предсказуемый. Не лендинг.

- Слева — поиск и каталог, добавление в заказ.

- Справа — заказ: строки, количество, стоимость, липкая панель итогов

  (без скидки / скидка / итог), поле скидки с подсказкой о текущем пределе.

- Ниже — компания и контакт (контакты фильтруются по компании).

- Две кнопки: «Создать сделку» и «Создать сделку и КП».

- Результат — ссылки на созданную сделку и КП (домен брать из

  BITRIX_PORTAL_DOMAIN, не сочинять).

- Работать внутри Битрикс24 без горизонтальной прокрутки и конфликтов с меню.

- Данные портала выводить через textContent, без inline-обработчиков и CDN.

- Обязательные состояния: загрузка, пустой каталог, нет доступа, портал

  недоступен. Никаких вечных спиннеров.

# 9. НАДЁЖНОСТЬ И ОТКАЗЫ

- Портал отвечает десятки секунд — это норма. Таймаут портальных вызовов —

  минуты, а не секунды.

- Приложение стартует и без ключа: /api/health отвечает, интерфейс показывает

  понятное состояние «данные портала пока недоступны».

- Отказы различать по error.code: нет права у ключа, ключ только на чтение,

  нет прав у сотрудника, ограничение тарифа — разные тексты. error.userMessage

  показывать как есть.

- Никогда не советовать «переподключить Битрикс24» и не перекладывать вину на

  ключ, если он в порядке.

# 10. БЕЗОПАСНОСТЬ

- Авторизация и проверка отдела на каждом /api/*.

- Строгая валидация входа: allowlist полей, количество строк ≤ 50,

  количество — целое 1…999, скидка — число 0…50, запрет NaN/Infinity.

- Никакого универсального прокси в портал: только фиксированный набор операций.

- Ошибки наружу — код и человеческий текст. Ни стека, ни ключа, ни адреса прокси.

- Логи без ключей и токенов.

- Хранилище идемпотентности — в /data (DATA_DIR с фолбэком для локального

  запуска), запись атомарная (временный файл + rename).

- Ноль зависимостей: node:http, node:fs, node:crypto.

# 11. ВСТРОЙКА

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

страницей. Коды мест встройки и ключи placement_options брать только из скила

bitrix-app-data, не выдумывать.

Привязку встройки делает платформа при установке OAuth-приложения — не вебхук.

В отчёте перечислить, что именно нужно привязать и с какой видимостью по отделу.

# 12. ЧЕГО НЕ ДЕЛАТЬ

- Не спрашивать, откуда брать данные: портал подключён.

- Не просить ключ заранее, не предлагать мок-данные в интерфейсе.

- Не строить согласование, роли менеджер/руководитель/директор, НДС, маржу от

  себестоимости, копейки, скидки по объёму и категории клиента, журнал аудита,

  экран правил. Это следующая версия, не эта.

- Не строить вход по логину и паролю.

- Не подключать нативные модули, тяжёлые фреймворки, CDN.

- Не создавать тестовые сделки без явного подтверждения человека.

# 13. ПОРЯДОК РАБОТЫ

1. Прочитать скилы: bitrix-app-data, secure-programming, frontend-design,

   vibecode-deploy, crm, crm-finance.

2. Составить план и вести его: in_progress / completed по факту.

3. Писать тесты до кода для денежной части: границы порогов (99 999,99 /

   100 000 / 299 999,99 / 300 000), скидка ровно на пределе и на 0,01 % выше,

   сумма со скидкой, запрет отрицательного количества, идемпотентность.

4. Реализовать сервер, потом интерфейс.

5. Проверить локально: старт на process.env.PORT || 3000, /api/health,

   /api/* без ключа отвечают понятной ошибкой, статика отдаётся.

6. Пройти проверку безопасности в режиме predeploy и починить найденное.

7. Опубликовать: vibecode_deploy, vibecode.json (описание до 500 символов),

   icon.svg без скриптов и внешних ссылок, в HTML — `<link rel="icon"

   href="/_gw/icon">`.

8. После публикации проверить на живых данных портала: каталог грузится, цены

   совпадают с CRM, предел скидки считается, выбор клиента работает.

9. Попросить у человека подтверждение и только после него создать одну тестовую

   сделку — проверить позиции, сумму и привязку компании/контакта.

# 14. КРИТЕРИИ ПРИЁМКИ

- [ ] Сервер стартует без ключа, /api/health отвечает, интерфейс показывает

      понятное состояние вместо падения.

- [ ] Каталог грузится из CRM, цены меняются вслед за CRM (проверить: изменить

      цену — расчёт меняется).

- [ ] Сумма, скидка и итог считаются сервером; подмена суммы в запросе не влияет.

- [ ] Порог 5/10/15 % переключается на границах 100 000 и 300 000 ₽.

- [ ] Скидка 15 % при заказе на 50 000 ₽ блокируется с текстом, где указаны

      введённый и допустимый процент.

- [ ] Сделка создаётся с компанией, контактом и товарными позициями; сумма в

      сделке совпадает с расчётом.

- [ ] Ответственный в сделке — текущий сотрудник (не пустой, не администратор).

- [ ] Двойной клик даёт одну сделку.

- [ ] КП создаётся, связано со сделкой и содержит те же позиции.

- [ ] Приложение открывается из левого меню портала под учётной записью

      сотрудника.

- [ ] Сотрудник вне разрешённого отдела получает отказ, а не пустой экран.

- [ ] В исходниках и ответах API нет ключа.

# 15. ОТЧЁТ В КОНЦЕ

Коротко, без технического шума: что собрано, какие правила взяты, какие методы

API использованы, как устроены авторизация и доступ, что нужно привязать для

встройки, какие проверки выполнены и что осталось за рамками.

Создай для портала test.bitrix24.ru приложение «Калькулятор коммерческих предложений» с помощью Битрикс24 Вайбкод.

Приложение предназначено для отдела продаж компании, которая торгует офисной мебелью. Сейчас менеджеры рассчитывают стоимость заказов в разных копиях Excel-файла. Нужно заменить таблицы единым калькулятором, который работает с товарами и клиентами из CRM.

Главное требование: приложение должно быть встроено в интерфейс Битрикс24.

Сотрудники должны открывать калькулятор непосредственно из левого меню портала, работать в нём под своими учётными записями и создавать сделки в CRM.

Размести приложение на Black Hole, настрой OAuth-авторизацию, публикацию в каталоге приложений Битрикс24 и место встраивания в левое меню портала. Используй штатные механизмы платформы Вайбкод.

Для начала предоставь доступ выбранному отделу. Не включай публичный доступ. Если для публикации или настройки прав понадобится моё подтверждение, запроси его.

### 1. Используй подготовленные тестовые данные

На портале test.bitrix24.ru уже создан раздел каталога «Тест — офисная мебель», ID 51, в каталоге CRM ID 55.

В нём находятся шесть товаров:

- Стол письменный «Орион» — ID 133, 18 000 ₽.

- Кресло офисное «Вектор» — ID 135, 12 000 ₽.

- Шкаф для документов «Архив» — ID 137, 24 000 ₽.

- Тумба мобильная «Компакт» — ID 139, 8 000 ₽.

- Стол переговорный «Форум» — ID 141, 65 000 ₽.

- Стеллаж офисный «Модуль» — ID 143, 15 000 ₽.

Также созданы тестовые компании:

- ООО «Альфа Офис» — ID 531, контакт Иван Соколов, ID 1647.

- ООО «Северный проект» — ID 533, контакт Мария Волкова, ID 1649.

- ООО «Горизонт» — ID 535, контакт Алексей Миронов, ID 1651.

Получай товары, актуальные цены, компании и контакты через API подключённого портала. Не используй указанные цены как постоянные значения в коде: если цена изменится в CRM, приложение должно использовать новую цену.

Не создавай повторно уже подготовленные товары и компании.

### 2. Реализуй калькулятор

Пользователь должен иметь возможность:

1. Просматривать товары из раздела «Тест — офисная мебель».

2. Добавлять товары в заказ и указывать количество.

3. Видеть стоимость каждой позиции и общую сумму.

4. Устанавливать скидку с учётом ограничений компании.

5. Выбирать клиента из CRM.

6. Создавать сделку с рассчитанными товарными позициями.

7. Формировать коммерческое предложение на основании заказа, если это поддерживается доступным API.

Правила скидок:

- Сумма заказа до 100 000 ₽ — максимальная скидка 5%.

- От 100 000 до 299 999,99 ₽ — максимальная скидка 10%.

- От 300 000 ₽ — максимальная скидка 15%.

Порог определяется по сумме до скидки. Скидка применяется к общей стоимости заказа.

Если пользователь вводит скидку выше разрешённой, приложение должно показать ошибку и запретить создание сделки.

Показывай сумму без скидки, сумму скидки в рублях и итоговую стоимость. Для эксперимента считаем цены без НДС.

### 3. Интегрируй приложение с CRM

При создании сделки:

- Привязывай выбранную компанию и контакт.

- Добавляй реальные товары каталога с количеством и ценами.

- Сохраняй корректную итоговую сумму с учётом скидки.

- Показывай ссылку на созданную сделку.

- Предотвращай случайное повторное создание сделки при двойном нажатии.

Коммерческое предложение должно быть связано со сделкой, если соответствующий механизм доступен.

Пользователь должен работать в пределах своих прав Битрикс24. Не используй общий административный доступ для действий всех сотрудников.

### 4. Интерфейс

Создай современный интерфейс на русском языке.

Предусмотри:

- Каталог товаров с поиском.

- Корзину выбранных товаров.

- Поля количества и скидки.

- Блок итогового расчёта.

- Выбор компании и контакта из CRM.

- Кнопку создания сделки.

- Возможность сформировать коммерческое предложение.

Интерфейс должен нормально работать внутри Битрикс24, без горизонтальной прокрутки и конфликтов с меню портала.

### 5. Безопасность

Проверяй скидки, актуальность цен и корректность суммы на серверной стороне непосредственно перед созданием сделки.

Пользователь не должен иметь возможности обойти ограничения через изменение JavaScript или запросов из браузера.

Не изменяй цены товаров в каталоге CRM. Не удаляй существующие записи. Не создавай тестовые сделки без моего подтверждения.

### 6. Разработка и проверка

Самостоятельно выбери техническую архитектуру и необходимые методы API Битрикс24 и Вайбкода. Используй актуальную документацию.

Сначала создай работоспособную версию калькулятора, затем подключи создание сделок и коммерческих предложений.

Проверь загрузку товаров, работу расчётов, ограничения скидок и интеграцию с CRM.

После проверки опубликуй приложение на Black Hole и настрой его встраивание в левое меню Битрикс24.

Обязательно проверь, что приложение открывается именно внутри интерфейса портала под учётной записью пользователя.

Если какую-то функцию невозможно реализовать, объясни причину. Не заменяй недоступную интеграцию имитацией.

### 7. Отчёт о разработке

После выполнения сообщи:

1. Какие функции реализованы.

2. Какие методы API использованы.

3. Как устроены авторизация и разграничение доступа.

4. Какие файлы и компоненты созданы.

5. Какие ошибки возникли в ходе разработки и как ты их исправил.

6. Какие проверки выполнены.

7. Где приложение размещено и как открыть его из портала.

8. Какие функции остались нереализованными.

Сохрани исходный код и историю изменений.

Цель — получить полноценное корпоративное приложение, которым менеджеры смогут пользоваться непосредственно внутри Битрикс24.

Для разработки агент выбрал Node.js, HTML, CSS и JavaScript. Приложение получилось небольшим: один серверный файл отвечает за обработку запросов и взаимодействие с CRM, а клиентские файлы — за интерфейс и расчёты в браузере.

После создания агент самостоятельно развернул приложение на сервере Битрикс24 Black Hole — для этого даже не потребовалось отдельной команды. Серверная часть находится в файле server.js. Она написана на Node.js без внешних библиотек. 

Интерфейс состоит из трёх файлов: index.html, styles.css и app.js.

Взаимодействие устроено так:

1. При открытии калькулятора браузер запрашивает данные через /api/snapshot.

2. Сервер обращается к API подключённого Битрикс24, получает товары, компании и контакты.

3. Пользователь собирает заказ в браузере.

4. При создании сделки браузер отправляет данные на /api/deals.

5. Сервер проверяет заказ и обращается к CRM для создания записей.

Для обращения к платформе сервер использует адрес API и ключ, которые получает из переменных окружения BITRIX_API_BASE_URL и BITRIX_API_KEY. В браузер ключ не передаётся. Удобство в том, что нам как пользователям копировать и передавать ключ никуда не нужно (а раньше было нужно — это апдейт последней версии).

Для операций в контексте сотрудника сервер также использует авторизационную сессию посетителя, полученную через шлюз Вайбкод.

Коворк/Код создал небольшую функцию, которая возвращает максимальную скидку для суммы заказа:

function maxDiscountFor(base) {
  if (base < 100000) return 5;
  if (base < 300000) return 10;
  return 15;
}

Перед созданием сделки сервер получает товары заново:

const fresh = await portal("/products/search", {
  method: "POST",
  bearer: visitor.bearer,
  body: {
    filter: {
      id: { $in: [...ids] },
      active: true
    },
    select: ["id", "name", "price", "currency", "active"],
    limit: 200
  }
});

Затем пересчитывает заказ и проверяет скидку:

const { rows, base, total, discount } =
  buildRows(productsById, items, discountPercent);

const maxAllowed = maxDiscountFor(base);

if (discountPercent > maxAllowed) {
  return {
    status: 422,
    payload: {
      error: Скидка превышает допустимую ${maxAllowed}%,
      code: "DISCOUNT_LIMIT"
    }
  };
}

При нажатии кнопки клиентская часть отправляет запрос на /api/deals. В запросе передаются ID компании и контакта, перечень товаров с количеством, размер скидки и признак необходимости создать КП.

Сервер формирует запрос к API платформы:

created = await portal("/deals", {
  method: "POST",
  bearer: visitor.bearer,
  body: {
    title,
    categoryId: 0,
    stageId: dealStageId,
    amount: total,
    currency: "RUB",
    companyId,
    contactId,
    assignedById
  }
});

После получения идентификатора сделки приложение добавляет к ней товарные позиции отдельными запросами. Если пользователь выбрал создание КП, выполняется дополнительный запрос к /quotes, а затем к коммерческому предложению привязываются товары.

Для защиты от повторных операций агент предусмотрел идентификатор заказа clientRef. Сервер сохраняет его и при повторном запросе проверяет, не была ли сделка уже создана.

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

Когда сотрудник открывает встроенное приложение, шлюз Вайбкод передаёт серверу служебные заголовки, среди которых:

• X-Vibe-User-Id — идентификатор сотрудника.

• X-Vibe-User-Name-Encoded — его имя.

• X-Vibe-Authorization — авторизационная сессия.

Сервер извлекает токен и использует его при обращении к API:

if (bearer) {
  headers.Authorization = Bearer ${bearer};
}

Для создания сделки обязательно наличие пользовательской сессии.

Кроме того, в серверной части предусмотрена переменная ALLOWED_DEPARTMENT_ID, позволяющая ограничить использование калькулятора конкретным отделом.

Если переменная не настроена, это дополнительное ограничение не применяется. Поэтому фактические права сотрудников и настройки доступа к опубликованному приложению необходимо проверять отдельно.

Ещё предусмотрена работа с авторизационной сессией пользователя. При создании сделки приложение использует его идентификатор и передаёт пользовательский токен при обращениях к API.