LEVBOT — полное руководство

Для владельца, технического специалиста и AI-агента

Версия: 2026-09-01
Статус: canonical product manual для текущего релиза.
Формат: единый документ для release archive и полной Wiki.

Назначение

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

Документ состоит из двух больших частей.

Часть I отвечает на вопрос: как превратить реальные материалы бизнеса — описания, правила, прайсы, CSV/XLSX, каталоги, варианты товаров и цены — в понятный и безопасный data contract LEVBOT.

Часть II отвечает на вопрос: как провести подготовленный Green через RED и Preview, установить его через LEVBOT DEPLOY на Linux-сервер, активировать, подключить каналы, обновлять и диагностировать.

Главный маршрут владельца:

исходные документы бизнеса
        ↓
Часть I
        ↓
подготовленные BotContent / pricing / Knowledge / configured prices
        ↓
RED → Apply → Preview
        ↓
Часть II
        ↓
DEPLOY → Linux server → activation → health
        ↓
реальный клиентский канал
        ↓
Reconfigure при следующих изменениях

Если этот файл читает внешний AI-агент

Не начинайте с изменения кода. Сначала определите, какая задача относится к данным клиента, какая — к deployment/configuration, а какая действительно является product bug или новой функцией.

Для подготовки документов используйте Часть I. Для установки и диагностики — Часть II.

Один canonical текст

Полная Wiki и файл docs/LEVBOT_MANUAL.md в release archive должны содержать один и тот же смысловой manual. Wiki не должна быть сокращённым рекламным пересказом: внешний агент должен иметь возможность изучить весь product contract без доступа к исходному коду.

Содержание

Часть I. Бизнес, документы, Knowledge, цены и вариативность

Введение к Части I. Зачем существует эта часть

LEVBOT не требует от каждого бизнеса отдельной разработки Python-кода. Чтобы бот хорошо продавал в конкретной компании, в первую очередь нужно правильно описать сам бизнес: что он продаёт, как различаются товары, какие данные являются фактами, где лежат цены, какие параметры влияют на цену, какие варианты являются просто характеристиками, а какие уже образуют отдельную продаваемую позицию.

Эта часть руководства отвечает именно на эти вопросы.

Она рассчитана сразу на двух читателей:

владельца или сотрудника компании, который готовит LEVBOT;
GPT/LLM-ассистента, которому владелец передаст свои прайсы, каталоги, описания, инструкции и это руководство со словами: «подготовь мои данные для LEVBOT».

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

Главная идея:

LEVBOT не должен угадывать структуру бизнеса там, где её можно один раз нормально зафиксировать в данных.

И вторая, не менее важная:

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

Магазин на 5000 уникальных SKU может быть проще для точного поиска, чем один лак с 300 цветами, пятью фасовками, тремя базами и разными правилами цены.

1. LEVBOT в двух словах: где здесь данные

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

Настройка выполняется через RED. RED существует в облачном и настольном варианте. Для этой части важна общая логика: RED помогает превратить исходные материалы бизнеса в структуру, которую затем использует Green.

У LEVBOT есть несколько разных классов данных. Их нельзя считать взаимозаменяемыми.

BotContent

BotContent отвечает на вопросы:

кто мы;
что мы продаём;
как разговаривать;
какие правила продаж соблюдать;
что уточнять;
когда передавать менеджеру;
что можно обещать;
чего обещать нельзя;
какие факты о компании считать основными;
как вести клиента после первого ответа или цены.

Это смысл и политика бизнеса.

Knowledge

Knowledge — структурированные большие данные, прежде всего CSV/XLSX:

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

Knowledge сохраняет исходные данные и позволяет runtime извлекать только релевантные строки.

Configured prices

Configured prices — отдельный структурированный слой точных ценовых записей.

Он полезен, когда нужны явно заданные самостоятельные price identities: готовые предложения, пакеты, фиксированные варианты, заранее рассчитанные конфигурации или другой набор точных цен, который удобнее хранить не как обычный текст.

Configured prices не обязателен для каждого бизнеса.

Cards и информационные данные

Карточки и медиа помогают показывать товар, изображения и связанные материалы. Они не должны становиться случайным вторым прайсом, если цена уже поддерживается в другом authoritative source.

Главная граница

В текущем LEVBOT действует model-first принцип:

RUNTIME INFORMS. RUNTIME RECOMMENDS. MODEL DECIDES. MODEL SPEAKS.

На каждом customer turn runtime сначала использует историю разговора и доступные business data, выполняет retrieval, собирает релевантные facts, exact/near candidates и короткую sales guidance. Только после завершения этого шага вызывается модель.

Модель получает эту опору, сама понимает намерение покупателя, выбирает тактику продажи и пишет весь customer-facing ответ. Runtime не подменяет продавца готовой business-фразой, не требует обязательного уточнения при ambiguity и не превращает not-found в остановку разговора.

Evidence в этой архитектуре — фактическая опора и рекомендация для модели, а не отдельный автор ответа клиенту.

Из этого следуют два практических правила:

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

Если в разных sources лежат противоречащие цены одной sellable identity, конфликт лучше исправить в данных: model-first логика не заменяет чистый business source.

2. Два основных сценария бизнеса

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

2.1. Сценарий A: небольшой и относительно однозначный ассортимент

Типичные признаки:

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

Примеры:

салон с 20 услугами;
небольшой магазин с 50–100 товарами;
студия с фиксированными пакетами;
сервис с простым прайсом;
компания, где основная сложность — правила общения, а не каталог.

Для такого бизнеса обычно достаточно:

BotContent + обычный pricing.md, иногда плюс небольшой Knowledge.

Не нужно превращать каждую цену в RECORD, придумывать сложную схему ID или строить каталог инженерного уровня просто потому, что LEVBOT это умеет.

Базовая рекомендация

Если человек может открыть прайс глазами и быстро однозначно ответить:

«Вот эта строка — именно тот товар, который спросил клиент, и вот его цена»,

то начинать нужно с простого сценария.

2.2. Сценарий B: большой или высоковариативный ассортимент

Признаки:

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

Для такого бизнеса основной инструмент — Knowledge, а для некоторых задач дополнительно используются configured prices.

Хороший пример — каталог на 5000 уникальных SKU. Другой хороший пример — всего 30 семейств товара, но каждое имеет десятки или сотни вариантов.

Ключевая мысль

Сложность — это не ROW_COUNT.

Сложность возникает там, где появляются конкурирующие identities и price-driving dimensions.

Поэтому:

5000 строк с уникальными SKU и чистыми полями могут работать хорошо;
50 строк с одинаковыми названиями и непонятно где записанной ценой могут работать плохо;
один товар с 300 цветами может быть простым, если цвет не меняет цену;
тот же товар становится сложным, если цвет, фасовка и база меняют цену.

3. Сначала разделите факты, правила и каталоги

Одна из самых частых ошибок — положить всё в один огромный документ: описание компании, прайс, правила продавца, каталог, инструкции, FAQ, старые цены, картинки, исключения и тестовые вопросы.

Человеку такой файл иногда ещё понятен. Модели и runtime приходится сначала угадывать, какая часть документа чем является.

Лучше разделить информацию по назначению.

3.1. Что относится к `company.md`

Сюда относятся устойчивые факты о компании:

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

Не превращайте company.md в прайс на пять тысяч строк.

3.2. Что относится к `behavior.md`

Это инструкции продавцу:

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

Хорошее правило: если фраза начинается со смысла «бот должен делать так», это чаще всего behavior/business logic, а не факт каталога.

3.3. Что относится к `pricing.md`

pricing.md предназначен для обычных простых цен, когда прайс достаточно мал и однозначен.

Пример хорошей простой структуры:

Кофе Арабика 250 г — 450 RUB
Кофе Арабика 500 г — 790 RUB
Доставка по городу — 500 RUB
Подарочная упаковка — 250 RUB

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

pricing.md не требует от обычного клиента structured JSON, source hash, SCOPE, DEFAULT_FOR или других advanced-полей.

3.4. Что относится к Knowledge

Knowledge используется, когда данные становятся настоящим массивом:

SKU | Наименование | Производитель | Объём | Цвет | Цена | Валюта | Ед.

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

Главное преимущество: весь файл не приходится отправлять модели на каждый вопрос. Runtime ищет релевантные строки.

3.5. Что относится к configured prices

Configured prices стоит использовать, когда вы хотите явно зафиксировать самостоятельные structured price records.

Пример:

RECORD=SERVICE-PREMIUM
TITLE=Пакет Premium
PRICE=25000
CURRENCY=RUB
UNIT=комплект
END_RECORD

Это уже не «модель прочитала абзац и поняла, что примерно стоит 25 тысяч». Это отдельная ценовая запись с собственной identity.

Но configured prices — не автоматически более правильный прайс и не «старший источник», который всегда перебивает остальные данные.

4. Какие документы можно передавать RED

Нужно различать два понятия: обычные вложения RED и Knowledge source. Это не одно и то же.

4.1. Обычные вложения Desktop RED

Текущий Desktop RED принимает как обычные материалы:

.png
.jpg
.jpeg
.webp
.xlsx
.csv
.pdf
.txt
.md
.docx

Текущий лимит одного такого вложения — 20 MiB.

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

Но:

PDF или DOCX, загруженный как обычный материал, не становится автоматически Knowledge.

Knowledge имеет отдельный контракт.

4.2. Изображения

Изображения могут анализироваться Vision-моделью. Из них можно извлекать наблюдаемые сведения: видимый текст, название товара, SKU, размеры, материал, конфигурацию, видимую цену и другие действительно наблюдаемые признаки.

Но важное правило:

Цена, увиденная только на картинке, не должна автоматически превращаться в authoritative price.

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

4.3. Небольшой CSV/XLSX как обычный материал

Текущий Desktop RED имеет границу для обычной обработки structured attachments.

Небольшой структурированный файл может обрабатываться обычным путём, когда в нём:

не более 200 строк;
не более 2400 непустых ячеек.

Это техническая граница существующего пути, а не определение «малого бизнеса».

Файл на 150 строк может логически быть очень сложным. Файл на 5000 чистых SKU — большим, но хорошо структурированным.

4.4. Knowledge принимает CSV/XLSX

В раздел Knowledge непосредственно добавляются CSV и XLSX.

Knowledge хранит исходный файл, нормализованное представление и manifest с проверкой исходных и нормализованных данных. Исходные байты файла сохраняются. Внутреннее представление не заменяет оригинал.

5. Как правильно оформить CSV

CSV — хороший формат для больших каталогов, если он действительно табличный.

5.1. Кодировки

Текущий parser пробует:

UTF-8 с BOM;
UTF-8;
Windows-1251.

Лучший выбор для нового файла — UTF-8.

5.2. Разделители

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

5.3. Первая непустая строка — заголовки

Это очень важное правило.

Хорошо:

ITEM_ID;TITLE;VOLUME;PRICE;CURRENCY;UNIT
A001;Лак X;1 л;1000;RUB;л
A002;Лак Y;1 л;1200;RUB;л

Плохо:

ПРАЙС НА 31 АВГУСТА 2026

ITEM_ID;TITLE;VOLUME;PRICE;CURRENCY;UNIT
...

Первая непустая строка используется как header row. Для машинного каталога не нужно добавлять декоративный заголовок над таблицей.

5.4. Пустые строки

Полностью пустые body-строки пропускаются. Пустая отдельная ячейка остаётся пустым значением.

Это нормально, если поле действительно неприменимо. Но не оставляйте критически важный идентификатор или цену пустыми в строке, от которой ожидается точный ценовой ответ.

5.5. Разная ширина строк

Parser ориентируется на самую широкую строку. Если заголовков не хватает, для отсутствующих названий колонок могут появиться технические имена вида column_N. Для клиента это сигнал, что CSV лучше исправить.

6. Как правильно оформить XLSX

XLSX удобен для сотрудников бизнеса, но хороший XLSX для LEVBOT должен оставаться таблицей, а не визуальной презентацией.

6.1. Листы

Runtime сохраняет все непустые sheets. Каждый непустой sheet обрабатывается как собственная табличная структура. Первый непустой ряд sheet используется как заголовок.

Поэтому лучше:

Sheet: Каталог

ITEM_ID | TITLE | PRICE | CURRENCY | UNIT
...

а не:

ООО «Компания»
Прайс-лист
действует с 01.08.2026

ITEM_ID | TITLE | PRICE | ...

6.2. Формулы

LEVBOT не является Excel calculation engine.

Нельзя строить контракт на предположении: «В ячейке есть формула, значит LEVBOT обязательно сам пересчитает её».

Parser читает значения, представленные внутри XLSX. Вычисление Excel-формул не является гарантированной функцией продукта. Если цена критична, передавайте уже материализованное актуальное значение.

6.3. Merged cells

Сложная семантика объединённых ячеек не является гарантированным контрактом.

Плохо:

[объединённая ячейка "Лак X"]
  красный   1000
  синий     1000
  золотой   1400

Лучше:

PRODUCT | COLOR | PRICE
Лак X   | красный | 1000
Лак X   | синий   | 1000
Лак X   | золотой | 1400

6.4. Один логический объект — одна понятная строка

Лучший базовый принцип для Knowledge:

Одна строка должна описывать одну понятную evidence identity.

Но «одна identity» не всегда означает «одна строка на каждый визуальный вариант». Ниже мы подробно разберём, когда варианты надо объединять, а когда разделять.

7. Поля большого каталога

У Knowledge нет обязательной отраслевой схемы вроде COLOR / MATERIAL / SIZE / BRAND. Runtime работает с generic header/value pairs.

Тем не менее некоторые семейства заголовков имеют специальный смысл для поиска и ценового evidence.

7.1. Stable ID

Распознаются, в частности:

ITEM_ID
SKU
Артикул
Article
Код
Code
ID

Для большого каталога stable ID настоятельно рекомендуется.

Хороший stable ID уникален, не меняется при обновлении цены той же позиции, не зависит от номера строки и позволяет сделать exact lookup.

Плохо: ROW=148, если после сортировки товар станет строкой 205.

Хорошо: SKU=LK-X-1L-STD, если этот код действительно стабилен в системе бизнеса.

7.2. Название

Runtime распознаёт семейства заголовков вроде: наименование, название, товар, title, модель, model.

У товара должно быть нормальное человекочитаемое имя.

7.3. Цена

Типичные price-маркеры: цена, стоимость, price, cost, руб, RUR, RUB.

Плохо:

VALUE=1250

если неизвестно, цена это, вес, объём или технический параметр.

7.4. Валюта

Типичные маркеры: currency, валюта, curr.

В табличных каталогах лучше указывать валюту явно, если возможно несколько валют или файл будет жить долго.

7.5. Единица продажи

Типичные маркеры: ед., единиц, unit, measure.

UNIT не обязательное поле для всех данных, но если источник его содержит, единица становится частью строгого сравнения цены.

Примеры: шт, л, кг, м², комплект, упаковка.

Лучше явно различать 1000 RUB/л и 1000 RUB/упаковка.

7.6. Остальные характеристики

Другие нетехнические колонки могут использоваться для поиска и сопоставления: бренд, производитель, цвет, объём, серия, материал, толщина, размер, класс, назначение, фасовка, совместимость и другие реально полезные признаки.

Они не становятся price-driving автоматически.

7.7. Технические поля

URL, URI, JSON, properties, payload, internal, XML, image/photo и похожие поля не должны становиться основной поисковой поверхностью вместо нормальных бизнес-полей.

8. Маленький бизнес: как сделать просто и правильно

Допустим, компания продаёт 20 услуг:

Замер — 1500 RUB
Монтаж — 12000 RUB
Выезд за город — 50 RUB/км
Пакет сопровождения — 25000 RUB

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

Рекомендуемая структура:

company.md — кто вы и что важно знать;
behavior.md — как продавать;
pricing.md — небольшой актуальный прайс;
Knowledge — только при необходимости;
configured prices — только если действительно нужны отдельные structured records.

Не надо параллельно записывать одну и ту же цену в pricing.md, Knowledge и configured prices просто «для надёжности». Такое дублирование создаёт будущий конфликт версий.

9. Большой каталог: что меняется

Для 1000–5000 SKU главной становится идентификация.

Хорошая строка:

ITEM_ID=LK-401
TITLE=Лак Premium
BRAND=Example
VOLUME=1 л
COLOR_CLASS=standard
PRICE=1000
CURRENCY=RUB
UNIT=л

В CSV/XLSX это отдельные колонки.

При exact ID runtime может использовать deterministic exact lookup. При обычном человеческом запросе используется поиск по содержимому полей и отбор кандидатов.

Если в каталоге четыре строки Лак Premium, но нигде не видно, чем они отличаются, проблема находится в данных, а не в отсутствии ещё одного промпта.

10. Sellable identity

Sellable identity — конкретная продаваемая сущность, для которой можно безопасно закрепить факт и цену.

Это может быть SKU, услуга, пакет, фасовка, готовая конфигурация, комбинация параметров или другой самостоятельный вариант.

Главный вопрос:

Если изменить этот параметр, изменится ли то, что именно покупатель покупает или сколько это стоит?

Если нет — возможно, это просто attribute.

Если да — скорее всего, это уже отдельная identity или отдельное price evidence.

11. Attribute и price-driving dimension

11.1. Обычный attribute

Attribute описывает товар, но сам по себе не создаёт новую цену.

Например:

Лак X
Цена: 1000 RUB/л
Доступно 300 цветов

если все 300 цветов имеют одинаковую цену.

Для вопроса «Сколько стоит литр?» цвет не влияет на ответ.

11.2. Price-driving dimension

Price-driving dimension — характеристика, изменение которой может изменить цену, валюту, billing unit, продаваемую SKU/identity, состав продаваемой единицы или другой параметр, необходимый для точного ценового evidence.

Типичные примеры, если конкретный бизнес действительно так устроен: объём, фасовка, размер, материал, серия, конфигурация, класс цвета, исполнение, комплектность.

COLOR, SIZE или MATERIAL не являются price-driving по определению. Они становятся такими только тогда, когда фактические данные бизнеса делают их ценовым различием.

12. Сквозной пример: лак и 300 цветов

Этот пример показывает почти всю логику подготовки каталога.

12.1. 300 цветов, одна цена

Есть:

Лак X
1000 RUB/л
300 доступных цветов

Цена не зависит от цвета.

Нужна одна ценовая identity:

PRODUCT=Лак X
PRICE=1000
CURRENCY=RUB
UNIT=л

или одна соответствующая Knowledge row.

Не нужно создавать 300 строк одной цены только потому, что существует 300 цветов.

Клиент спрашивает: «Сколько стоит литр?» Если других price-driving параметров нет, LEVBOT может назвать 1000 RUB/л и уже после этого помочь выбрать цвет.

Он не должен заставлять клиента сначала выбрать один из 300 цветов только ради одинаковой цены.

Где хранить 300 цветов

Одна гигантская ячейка со всеми цветами не лучший вариант. Текущий runtime ограничивает длину одного значения, попадающего в candidate/context, поэтому огромный перечень не гарантирует полного перечисления.

Лучше отдельная информационная структура:

PRODUCT_ID | COLOR_CODE | COLOR_NAME
LX         | C001       | Красный
LX         | C002       | Бордо
LX         | C003       | Алый
...

Это рекомендованная структура, а не обязательная schema LEVBOT.

12.2. Две ценовые группы

Теперь:

standard colors — 1000 RUB/л
special colors — 1200 RUB/л

Цветовая группа стала price-driving dimension.

Безопасная структура — две самостоятельные ценовые identities:

PRODUCT=Лак X
COLOR_CLASS=standard
PRICE=1000
CURRENCY=RUB
UNIT=л

и:

PRODUCT=Лак X
COLOR_CLASS=special
PRICE=1200
CURRENCY=RUB
UNIT=л

Для запроса «Сколько стоит литр?» одного окончательного ответа уже нет.

Текущий runtime передаёт модели найденные релевантные варианты и отмечает ценовую неоднозначность в evidence/sales guidance. Модель сама решает, как вести продажу: может сразу показать оба варианта, сравнить их по доступным данным, задать полезный вопрос или выбрать другой естественный ход. Ambiguity не является обязательной командой «сначала уточни».

Например модель может естественно ответить: «Есть standard за 1000 RUB/л и special за 1200 RUB/л. Что из них ближе?» — но эта формулировка не зашита в runtime и не является обязательным шаблоном.

Не надо автоматически превращать две цены в специальный structured range 1000–1200: такого price shape current runtime не имеет.

12.3. Каждый цвет может иметь свою цену

Если из 300 цветов многие имеют собственную цену и покупатель может спросить «Сколько стоит RAL XXXX?», то нужна явная связь:

конкретный цвет
→ конкретная sellable identity
→ конкретная цена

Runtime не должен найти цвет в одной информационной строке, отдельно найти правило «Special +20%», сам склеить их и объявить новый результат authoritative. Такого универсального rules engine нет.

12.4. Серия + база + объём + класс цвета

Допустим, цена определяется SERIES + BASE + VOLUME + COLOR_CLASS.

Если комбинации имеют готовые цены, безопаснее хранить готовые price identities:

SKU=P-A-B1-1L-STD
SERIES=A
BASE=B1
VOLUME=1 л
COLOR_CLASS=standard
PRICE=1000

SKU=P-A-B1-1L-SPC
SERIES=A
BASE=B1
VOLUME=1 л
COLOR_CLASS=special
PRICE=1200

LEVBOT не строит автоматически новую цену из нескольких partial records.

13. Один ряд или несколько

Ситуация	Рекомендация	Почему
Один продукт, 300 цветов, цена одна	Одна price row; цвета отдельно	Цвет не меняет ценовую identity
Один продукт, 300 цветов, разные цены	Несколько rows/records	Цвет/класс меняет цену
Разные объёмы, одна unit price, объём только справочный	Может быть одна price identity	Если объём не отдельная продаваемая упаковка
Разные фасовки/SKU, даже при одинаковой цене за литр	Отдельные rows	Упаковка — отдельная sellable identity
Разные объёмы и разные package prices	Отдельные rows	Разные exact prices
Разные SKU	Отдельные rows	Exact ID должен вести к своей позиции
Одинаковое название, разные производители	Отдельные rows	Производитель различает identity
Только informational attributes	Одна price identity или отдельный non-price source	Не надо размножать price evidence

14. Когда использовать Knowledge

Knowledge рекомендуется, если есть большой CSV/XLSX, поиск по сотням/тысячам строк, много технических характеристик, точные SKU, одинаковые названия, большой справочник или варианты, которые клиент называет по нескольким признакам.

Практические ориентиры:

Бизнес	Рекомендация
20 простых услуг	`pricing.md`, Knowledge optional
100 простых товаров	можно просто; Knowledge уже полезен
1000 уникальных SKU	Knowledge
5000 уникальных SKU	Knowledge + stable ID
1 товар × 300 одинаково стоящих цветов	одна price identity + informational data
1 товар × 300 разных по цене вариантов	Knowledge/structured identities
100 товаров × 10 фасовок	Knowledge
одинаковые названия разных брендов	Knowledge + manufacturer + stable ID
большая справочная база без цен	Knowledge

15. Как Knowledge хранит данные

При добавлении CSV/XLSX Knowledge хранит:

оригинальные байты source;
нормализованное JSON-представление;
knowledge/manifest.json.

Источник идентифицируется по SHA-256 исходных байтов. Одинаковый source может быть дедуплицирован.

Для владельца важен вывод:

Внутренний индекс — производное представление. Исходный CSV/XLSX остаётся первичным бизнесовым материалом.

Не надо вручную править normalized JSON.

Если прайс изменился: обновить исходный CSV/XLSX → применить его через Knowledge → проверить данные → прогнать контрольные вопросы.

16. Configured prices: точный формат

Configured prices — TXT с явными RECORD-блоками.

Минимум:

RECORD=SERVICE-001
PRICE=25000
END_RECORD

RECORD обязателен.

Цена задаётся как PRICE=25000 или, например, PRICE_RUB=25000.

Число может содержать пробелы; запятая или точка принимаются как decimal separator; поддерживается максимум две цифры после разделителя.

Не используйте в PRICE значения вроде от 1250, примерно 1250, 1250-1800, по запросу, +20%.

CURRENCY

Опционально:

CURRENCY=RUB

Если не задана, configured contract использует suffix из PRICE_<currency> либо RUB.

UNIT

Опционально:

UNIT=л

Если UNIT указан, он участвует в строгой проверке claim.

PRICE_TYPE

PRICE_TYPE сохраняется как metadata, но не является встроенным rules engine. PRICE_TYPE=from не даёт полноценной автоматической семантики «цена от».

Остальные поля

Остальные FIELD=value сохраняются как generic attributes.

Пример:

RECORD=LACQUER-STD
TITLE=Лак X
COLOR_CLASS=standard
PRICE=1000
CURRENCY=RUB
UNIT=л
END_RECORD

COLOR_CLASS здесь — полезный attribute бизнеса, а не зарезервированное магическое поле.

SCOPE и DEFAULT_FOR

Не являются обязательными полями LEVBOT. Если присутствуют, current generic parser хранит их как обычные attributes.

17. Какие формы цены реально безопасны

Exact price

1000 RUB — поддерживается безопасно.

Цена за единицу

1000 RUB/л — поддерживается безопасно, если unit закреплён в evidence.

Цена упаковки/комплекта

5000 RUB/упаковка — поддерживается безопасно, если exact package price и unit указаны явно.

«От 1000»

Число может быть подтверждено, но отдельного structured price type «FROM» с проверкой нижней границы нет.

Диапазон 1000–1500

Отдельного range evidence нет. Безопаснее материализовать реальные варианты.

Базовая цена + процентная наценка

Current runtime не является percentage price engine. Для точной цены лучше материализовать конечную сумму.

Формула

Произвольная формула не является обычным supported pricing contract. Specification multiplication — отдельный сценарий, а не универсальный калькулятор.

«По запросу»

Может быть информационным текстом, но не numeric price evidence.

Разные валюты

Валюта сохраняется; автоматической FX-конвертации нет.

18. Самая опасная ошибка: противоречащие цены в разных источниках

У current runtime нет общего правила:

configured_prices > Knowledge > pricing.md > card

Он может одновременно собрать evidence из Knowledge, configured prices, pricing.md, card facts и некоторых conversation facts.

Runtime передаёт найденные facts/candidates и отмечает конфликт в sales guidance до model call. Модель после этого сама выбирает, как вести разговор. В обычном customer flow нет отдельного price/evidence gate, который после ответа модели переписывает её фразу или подставляет deterministic business fallback.

Пусть:

pricing.md: Лак X = 1000
Knowledge:  Лак X = 1100
configured: Лак X = 1200

Если запрос находит все три, current runtime не обязан выбрать 1200 и не считает configured price автоматически «главнее».

Практический вывод:

Для одной sellable identity не храните одновременно разные актуальные цены в нескольких sources и не рассчитывайте, что LEVBOT сам выберет правильную.

Нужно либо выбрать один authoritative business source, либо явно разделить реальные варианты, либо убрать устаревший источник.

Не всякое дублирование плохо. behavior.md может содержать правило «после цены предложи выбрать цвет», а Knowledge — список цветов. Это разные типы информации, а не конфликт.

19. Query-specific ambiguity

Один каталог не бывает просто «конфликтным» навсегда. Неоднозначность зависит от запроса.

300 цветов, цена одна:

«Сколько стоит литр?» — цвет может быть неважен;
«Какие цвета есть?» — цвет центральный параметр;
«Есть красный?» — нужна color information.

Standard 1000, special 1200:

«Сколько стоит литр?» — ценовая неоднозначность;
«Сколько литр standard?» — может стать однозначно;
«Сколько красный?» — нужна явная связь красного с правильной ценовой identity.

Runtime не должен тайно знать hidden mapping, которой нет в данных.

20. Уровни конфликта

Уровень 0 — NO CONFLICT

Один запрос → одна подходящая price identity → одна подтверждённая цена.

Уровень 1 — BENIGN VARIATION

Вариантов много, но они не меняют запрошенный факт. Пример: 300 цветов, одна цена.

Уровень 2 — IDENTITY AMBIGUITY

Есть разные продаваемые сущности, но данные плохо различают их. Например Фильтр X — производитель A и Фильтр X — производитель B.

Даже если цена совпадает, identity разные. Current runtime не имеет полного универсального identity engine, поэтому данные должны явно различать такие строки.

Уровень 3 — PRICE AMBIGUITY

Несколько подходящих catalog facts имеют разные (price, currency, unit). Runtime должен передать модели релевантные варианты и явно отметить неоднозначность. Модель сама решает sales move: показать несколько вариантов, сравнить их, задать вопрос или продолжить иначе. Неоднозначность не должна автоматически превращаться в mandatory clarification и не должна порождать третью придуманную «точную» цену.

Уровень 4 — SPECIFICATION

Покупатель явно задаёт несколько позиций и quantities.

Уровень 5 — UNSUPPORTED DERIVATION

Для ответа надо изобрести расчёт: percentage formula, инженерную геометрию, скрытое правило из двух таблиц, FX conversion, quantity из размеров или другую произвольную калькуляцию.

Тогда решение — нормализация данных или отдельная функция продукта.

21. Specification: что runtime действительно умеет считать

Specification — специальный сценарий.

Пример:

12 × ITEM_ID A
1 × ITEM_ID B
5 × ITEM_ID C

Для каждой позиции runtime получает подтверждённую unit price.

component_total = explicit_quantity × authorized_unit_price

После проверки компонентов:

calculated_total = сумма component_total

Quantity должна быть явно задана. LEVBOT не должен выводить количество из геометрии, длинного описания или инженерного предположения.

Specification подходит для списка SKU и явных количеств. Не является универсальным проектировочным калькулятором.

22. Хорошие и плохие данные

Одинаковое название, разные цены, нет различия

Плохо:

Лак X | 1000
Лак X | 1200

Хорошо:

Лак X | standard | 1000
Лак X | special  | 1200

Цена только в description

Плохо:

DESCRIPTION=обычный 1000, спец 1200, 5л дешевле...

Хорошо: реальные price identities вынесены в поля/строки.

Несколько смыслов в одной колонке

Плохо:

PARAMS="1л; красный; матовый; 1000руб; склад"

Лучше: VOLUME, COLOR, FINISH, PRICE, AVAILABILITY отдельными понятными полями. Это рекомендуемые бизнес-поля, не обязательные зарезервированные имена.

Разные units без маркировки

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

300 одинаковых price records без необходимости

Если цвет не влияет на цену, это лишний шум.

300 разных цен в одном абзаце

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

Duplicate stable IDs

Stable ID должен быть однозначным.

Старый прайс рядом с новым

Runtime не знает, какой из них «свежее по смыслу».

23. Как выбирать SIMPLE / KNOWLEDGE / CONFIGURED PRICES

Шаг 1

Ассортимент маленький и однозначный? Начните с BotContent + pricing.md.

Шаг 2

Есть большой CSV/XLSX или поиск по attributes? Используйте Knowledge.

Шаг 3

Есть отдельные готовые structured price identities? Configured prices может быть полезен.

Шаг 4

Нужны и каталог, и отдельные готовые предложения? Можно использовать Knowledge + configured prices, но не создавайте конфликт одной identity.

Шаг 5

Варианты меняют цену/identity?

NO → не плодить price records;
YES → сделать различие явным.

Шаг 6

Для цены нужна неподдерживаемая формула? Не поручать модели изобретать цену. Материализовать конечные значения или реализовать отдельную функцию продукта.

24. Stable ID

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

25. Обновление цен и каталогов

Простое pricing

Обновить pricing.md → Apply → Preview → контрольные вопросы.

Knowledge

Обновить исходный CSV/XLSX.
Добавить/заменить source через Knowledge.
Apply.
Проверить exact ID.
Проверить natural queries.
Проверить неоднозначные товары.
Проверить цены.
Для уже установленного Green дальше используется штатный Reconfigure из Части II.

Не редактировать вручную knowledge/manifest.json и normalized JSON.

Configured prices

Обновить raw structured TXT и проверить количество records, stable IDs, price, currency, unit и attributes.

26. Прямая инструкция GPT: как начать работу

Не начинай с генерации файлов. Сначала инвентаризируй исходники.

Для каждого:

FILE:
TYPE:
WHAT IT CONTAINS:
BUSINESS PURPOSE:
IS IT CURRENT:
AUTHORITATIVE FACTS:
POSSIBLE CONFLICTS:
RECOMMENDED DESTINATION:
ACTION:

Классифицируй:

BotContent candidate — описание, правила общения, FAQ, ограничения, handoff, стиль;
Simple pricing candidate — короткий актуальный прайс с понятными ценами;
Knowledge candidate — CSV/XLSX, сотни/тысячи rows, SKU, большой справочник;
Configured price candidate — готовые самостоятельные structured prices;
Validation material — тестовые запросы и expected results. Не превращать тесты в рабочий прайс.

27. Алгоритм GPT для таблиц

1. Найти настоящие headers

Убрать декоративную шапку, проверить merged layout.

2. Найти identity

SKU, ITEM_ID, артикул, код, manufacturer, model и другие различающие поля.

Если stable ID отсутствует, не выдумывать случайный, который развалится при следующей выгрузке. Лучше спросить владельца, есть ли устойчивый код в учётной системе.

3. Найти цену

Определить exact numeric price, currency, unit, package semantics.

4. Найти price-driving dimensions

Для каждого варианта спросить: «Если этот параметр изменится, изменится цена или sellable identity?» Если неизвестно — спросить владельца.

5. Найти non-price dimensions

Не превращать их автоматически в price records.

6. Найти конфликты

same ID, different product;
same identity, different price;
old/current price;
same name without distinguishing attribute;
package vs unit ambiguity;
different currencies.

7. Выбрать структуру

SIMPLE / KNOWLEDGE / CONFIGURED / KNOWLEDGE + CONFIGURED и объяснить почему.

28. Какие уточнения задавать владельцу

Хороший GPT сначала анализирует материалы и спрашивает только там, где ответ меняет структуру.

Хорошие вопросы:

У этих 300 цветов цена одинаковая?

Фасовки 1 л и 5 л — отдельные SKU или продажа идёт просто по цене за литр?

Здесь две строки с одинаковым названием и разной ценой. Чем они отличаются?

Какой прайс актуальный?

1250 — за литр, банку или комплект?

Красный относится к standard или special?

Этот процент — справочная информация или вы ожидаете автоматический расчёт?

Цена в Excel уже рассчитана или существует только формула?

Плохой вопрос — «Опишите всю структуру бизнеса», если её уже можно понять из файла.

29. Decision tree для GPT

START
  ↓
Есть короткий однозначный прайс?
  ├─ YES → SIMPLE pricing.md
  └─ NO
       ↓
Есть большой CSV/XLSX / много строк / поиск по attributes?
  ├─ YES → KNOWLEDGE
  └─ NO → возможно BotContent/simple data

Есть отдельные готовые structured price identities?
  ├─ YES → CONFIGURED PRICES может быть полезен
  └─ NO

Есть варианты?
  ↓
Вариант меняет цену / SKU / sellable identity?
  ├─ NO → не размножать price records
  └─ YES → сделать distinction явным

Есть разные цены одной identity в разных sources?
  ├─ YES → STOP: устранить конфликт
  └─ NO

Для цены нужна неподдерживаемая формула?
  ├─ YES → материализовать цены / отдельная product feature
  └─ NO

READY FOR PREVIEW

30. Пример: магазин красок

Владелец передал:

company.docx
rules.txt
price.xlsx
colors.xlsx
photos/

company.docx с историей, географией, преимуществами → BotContent/company.

rules.txt с правилами консультации → behavior.

price.xlsx → проверить SKU, товар, фасовку, цену, currency, unit, class/color relation; большой прайс → Knowledge.

colors.xlsx:

если цвета не меняют цену → informational Knowledge;
если цветовая группа меняет цену → должна быть явная связь с ценовой identity.

photos/ → media/cards/visual context по назначению. Изображение не должно быть единственным authoritative price source.

31. Пример: магазин на 5000 SKU

Хороший исходник:

SKU
TITLE
BRAND
CATEGORY
MODEL
SIZE
MATERIAL
PRICE
CURRENCY
UNIT

Названия могут отличаться.

GPT должен сохранить все rows, не делать prose-summary вместо каталога, проверить unique stable IDs, дубли, price field, units, одинаковые names, useful attributes, загрузить source как Knowledge и создать exact-ID/natural-query tests.

32. Пример: один товар, десять фасовок

Есть 0.5 л, 1 л, 2.5 л, 5 л, 10 л.

Первый вопрос: это справочные варианты объёма при одной цене за литр или отдельные продаваемые упаковки?

Если готовые банки имеют отдельные SKU и package prices — отдельные rows.

Если бизнес реально продаёт любое количество по одной цене за литр и фасовка не формирует отдельную identity — структура может быть проще.

Не выводите эту бизнесовую семантику только из чисел в Excel.

33. Aliases и синонимы

У current runtime нет обязательного специального поля ALIASES, но generic attributes могут участвовать в поиске.

Если товар называют ПФ-115, эмаль ПФ115, эмаль 115, алкидная ПФ-115, эти сведения полезно сделать явно доступными в searchable business fields.

Не прячьте всё в технический JSON.

34. Наличие и другие независимые факты

Если цена и наличие меняются независимо, не смешивайте:

PRICE="1000, есть"

Лучше:

PRICE=1000
AVAILABILITY=есть

Но произвольное поле не получает автоматически специальную бизнес-семантику. Конкретное поведение задаётся данными и BotContent.

Отдельно важно различать ассортимент и текущее складское наличие. Строка товара в каталоге подтверждает, что позиция присутствует в этом source, но сама по себе не доказывает, что она прямо сейчас есть на складе. И наоборот: отсутствие строки в конкретной retrieval-выборке не доказывает, что бизнес вообще не продаёт такой товар. Если наличие важно для продажи, храните его отдельным понятным фактом/source.

35. Если исходник плохой

Иногда правильное решение — не импортировать файл как есть.

Признаки:

таблица для печати;
несколько header rows;
merged cells;
формулы вместо materialized prices;
цена в комментариях;
один товар занимает пять строк без ID;
JSON содержит половину характеристик;
одинаковые SKU;
старые и новые цены вперемешку;
несколько currencies без currency field;
package/unit semantics неясны.

Правильный workflow:

ORIGINAL SOURCE
    ↓
analysis
    ↓
clarifying questions
    ↓
NORMALIZED BUSINESS SOURCE
    ↓
LEVBOT

Исходник нужно сохранить отдельно. Нормализованный файл должен быть воспроизводимым результатом.

36. Что GPT не должен выдумывать

GPT не имеет права:

придумывать отсутствующие цены;
назначать цвету ценовую группу без данных;
угадывать currency;
притворяться, что случайный ID существовал в системе клиента;
превращать «примерно» в exact price;
удалять строки без объяснения;
объединять разные позиции только из-за похожего названия;
выбирать конфликтующий прайс «по ощущениям»;
объявлять формульный расчёт authoritative, если он не является согласованным источником.

Если данных не хватает — точный вопрос владельцу лучше красивой догадки.

37. Отчёт GPT после подготовки

BUSINESS MODE:
SIMPLE / LARGE / HIGH-VARIABILITY

FILES ANALYZED:
...

BOTCONTENT:
...

SIMPLE PRICING:
...

KNOWLEDGE:
...

CONFIGURED PRICES:
...

SOURCE ROWS:
...

OUTPUT ROWS:
...

STABLE IDS:
PASS / PROBLEMS

DUPLICATE IDS:
...

PRICE FIELDS:
...

CURRENCIES:
...

UNITS:
...

PRICE-DRIVING DIMENSIONS:
...

NON-PRICE DIMENSIONS:
...

CONFLICTING PRICES:
...

AMBIGUOUS IDENTITIES:
...

FORMULA/RANGE/FROM PRICES:
...

OWNER QUESTIONS:
...

READY FOR LEVBOT:
YES / NO

Если было 5000 source rows, нельзя молча вернуть 4370 rows без объяснения.

38. Тесты до установки

Подготовка данных заканчивается проверкой поведения.

Минимум:

обычный вопрос без цены;
exact ID;
unique natural query;
ambiguous query;
non-price variation;
specific attribute;
not found;
price-driving parameter missing;
specification, если используется;
ordinary follow-up после цены.

Если price-aware retrieval превращает обычный разговор в технический тупик, заставляет клиента искать SKU вместо продавца или обрывает продажу при ambiguity/not-found, конфигурация или runtime требуют проверки. Evidence должен помогать модели продавать, а не заменять её.

39. Чек-лист качества каталога

Перед Apply:

[ ] понятно, что является sellable identity;
[ ] stable IDs уникальны там, где нужны;
[ ] одинаковые названия имеют distinguishing attributes;
[ ] price-driving dimensions явны;
[ ] non-price variants не размножили цены без причины;
[ ] exact price находится в понятном поле;
[ ] currency понятна;
[ ] unit понятен;
[ ] package price не спутан с unit price;
[ ] нет разных актуальных цен одной identity в разных sources;
[ ] старые прайсы исключены;
[ ] формулы не считаются гарантированным XLSX contract;
[ ] merged layout заменён таблицей;
[ ] source rows не потеряны;
[ ] большие CSV/XLSX идут в Knowledge;
[ ] configured records действительно нужны;
[ ] SCOPE/DEFAULT_FOR не объявлены обязательными;
[ ] range/from/percentage не выданы за built-in rules engine;
[ ] созданы exact/unique/ambiguous/not-found tests.

40. Что владельцу полезно сообщить GPT заранее

какой прайс актуальный;
какой устарел;
какая валюта;
цена за штуку/литр/кг/упаковку/комплект;
какой field является SKU;
какие варианты меняют цену;
какие только информационные;
есть ли формулы;
хотите ли вы называть цену сразу или уточнять параметр;
какие реальные вопросы задают покупатели.

41. Где начинается product bug

Сначала проверяем данные.

Кандидат на product bug появляется, если при корректном data contract:

valid rows теряются;
exact stable ID выбирает другую строку;
существующая exact price/позиция не попадает в retrieval/evidence, хотя source корректен;
runtime evidence/guidance помечает как фактическую сумму, которой нет в source;
explicit currency подменяется;
specification принимает неправильный total;
данные теряются после штатного Apply/Reconfigure;
packaged runtime ведёт себя иначе, чем canonical.

Тогда нужен минимальный reproduction, а не отраслевой Python patch.

42. Что не является багом

Нормально:

при реальной ambiguity модель сама выбирает: показать варианты, уточнить параметр или продолжить продажу другим уместным способом;
отсутствие подтверждённой exact price как catalog/source fact, если такой цены действительно нет в данных; при этом разговор не обязан останавливаться;
отсутствие автоматического сложения разных currencies;
отсутствие автоматического вывода quantity из инженерного описания;
отсутствие percentage engine;
необходимость материализовать final prices;
необходимость исправить плохую таблицу;
необходимость добавить distinguishing attribute;
невозможность гарантированно перечислить 300 значений из одной огромной ячейки;
необходимость убрать конфликтующий старый price source.

43. Главная инструкция внешнему GPT/агенту

Если ты AI-агент и получил этот документ вместе с файлами бизнеса:

Не меняй код LEVBOT.
Инвентаризируй документы.
Отдели business facts от business rules.
Отдели маленький прайс от большого каталога.
Большой CSV/XLSX готовь как Knowledge.
Найди stable identities.
Найди exact prices, currencies и units.
Найди price-driving dimensions.
Найди non-price variations.
Проверь duplicate IDs.
Проверь одинаковые названия.
Проверь противоречащие prices между sources.
Не рассчитывай на автоматический precedence.
Не превращай PRICE_TYPE, SCOPE, DEFAULT_FOR в магическую обязательную schema.
Не рассчитывай ranges, percentages и formulas как built-in price engine.
Задай только вопросы, меняющие структуру.
Сохрани structured facts lossless.
Создай normalized source.
Объясни выбор SIMPLE / KNOWLEDGE / CONFIGURED.
Создай regression cases.
Только после этого считай данные готовыми к Preview.

44. Краткая модель принятия решения

Бизнесовые документы
        ↓
правила?
        → BotContent

небольшой однозначный прайс?
        → pricing.md

большой structured catalog?
        → Knowledge

отдельные готовые structured price identities?
        → configured prices

        ↓
для sellable identity:
stable ID?
exact price?
currency?
unit?

        ↓
варианты?

не меняют цену/identity
        → attribute / information

меняют
        → separate price identity

        ↓
разные актуальные цены одной identity?
        → исправить данные

        ↓
неподдерживаемая формула?
        → материализовать цену или отдельная product feature

        ↓
Preview / regression tests

45. Главное, что нужно запомнить

Первое. Маленький бизнес не надо насильно превращать в enterprise-каталог.

Второе. Большой каталог надо хранить как данные, а не как огромный prompt.

Третье. Stable ID особенно полезен при большом ассортименте.

Четвёртое. Не каждый вариант товара — новая ценовая позиция.

Пятое. Параметр price-driving только тогда, когда реально меняет цену или sellable identity.

Шестое. Если цена зависит от комбинации параметров, готовая exact price должна быть материализована там, где current runtime не имеет rules engine.

Седьмое. Не храните разные актуальные цены одной identity в нескольких sources и не ждите автоматического precedence.

Восьмое. Хороший GPT сначала ищет границы неопределённости, потом задаёт точные вопросы владельцу.

Девятое. Нормализация должна сохранять факты, а не придумывать их.

Десятое. Если каждый новый клиент требует патчить runtime, сначала нужно проверить структуру входных документов.

Часть II. RED, DEPLOY, Green, лицензия, каналы и эксплуатация

Введение к Части II. Что предполагается к началу этой части

Часть I отвечает на вопрос: как правильно описать бизнес для LEVBOT.

К началу Части II желательно уже иметь:

понятное описание компании;
правила поведения продавца;
актуальный простой прайс либо подготовленный большой каталог;
при необходимости Knowledge;
при необходимости configured prices;
понятные stable ID для большого ассортимента;
устранённые противоречащие цены;
несколько реальных контрольных вопросов покупателей.

Теперь задача меняется. Нужно провести подготовленные данные через RED, проверить их в Preview, скачать персональный пакет, установить Green на сервер и подключить рабочие каналы.

Коротко весь путь выглядит так:

Подготовленные данные бизнеса
        ↓
RED
        ↓
Apply
        ↓
Preview
        ↓
персональный Green
        ↓
LEVBOT DEPLOY на Windows
        ↓
SSH/SFTP
        ↓
Linux-сервер клиента
        ↓
активация лицензии
        ↓
systemd + nginx + Green
        ↓
health
        ↓
Сайт / Telegram / Bitrix24 / amoCRM / Avito / MAX
        ↓
рабочие диалоги
        ↓
Reconfigure при следующих изменениях

Главная мысль этой части:

Пользователь должен управлять LEVBOT через RED и DEPLOY. Ручное редактирование runtime, manifests, systemd, базы истории или activation receipt не является штатным способом работы.

46. Из каких частей состоит установленный LEVBOT

Чтобы не путаться в интерфейсах, полезно один раз разделить систему на несколько компонентов.

46.1. Cloud RED

Cloud RED — облачный конфигуратор и рабочее пространство подготовки персонального Green.

Он отвечает за:

пользовательское workspace;
RED-диалог;
загруженные материалы;
черновую и применённую конфигурацию;
создание BotContent;
Cloud Preview;
формирование персонального downloadable package;
связь пользовательского потока с покупкой/лицензией.

Cloud RED не является тем Green, который потом принимает клиентов на вашем сервере.

46.2. Cloud Preview

Cloud Preview — отдельный тестовый процесс внутри среды RED.

Он нужен, чтобы проверить:

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

Но Preview не является тестом вашего Linux-сервера.

Успешный Preview сам по себе не доказывает:

SSH-доступ;
готовность сервера;
установку Python/nginx;
домен и HTTPS;
регистрацию внешнего connector;
наличие activation receipt на сервере клиента;
реальную работу systemd-службы;
сетевые особенности площадки.

Эта граница принципиальна.

46.3. Desktop RED

Desktop RED входит в Windows-приложение LEVBOT DEPLOY.

Он работает с локальной персональной папкой Green и позволяет:

редактировать BotContent;
работать с обычными материалами;
управлять Knowledge;
управлять structured configured prices;
работать с карточками и связанными настройками;
запускать локальный Preview;
сохранять изменения в выбранный Green;
готовить последующий install/reconfigure.

Cloud RED и Desktop RED решают похожую задачу, но это разные среды.

46.4. LEVBOT DEPLOY

DEPLOY — Windows-приложение, которое переводит подготовленный Green из состояния «готовые файлы» в состояние «работающий бот на сервере».

Он:

проверяет выбранный Green;
принимает настройки модели;
принимает параметры Linux-сервера;
подключается по SSH/SFTP;
подготавливает сервер;
устанавливает зависимости;
размещает Green;
записывает конфигурацию;
активирует лицензию;
настраивает systemd;
устанавливает webchat-часть;
настраивает nginx;
запускает Green;
выполняет health-check;
затем умеет делать controlled Reconfigure.

46.5. Customer Green

Customer Green — это уже рабочий LEVBOT на сервере владельца.

Именно он:

принимает клиентские сообщения;
хранит историю;
читает BotContent;
использует Knowledge;
использует configured prices;
работает с карточками/медиа;
до вызова модели собирает релевантные facts, candidates, bounded topic trail и sales guidance;
только после этого вызывает модель;
оставляет модели финальное решение по тактике продажи и весь customer-facing текст;
подключён к внешним каналам;
хранит рабочее состояние;
проверяет локальную signed license receipt.

Штатная директория установки:

/opt/levbot-green

Штатная systemd-служба:

levbot-green.service

Внутренний health endpoint:

http://127.0.0.1:8080/health

47. Правильный путь нового клиента

Ниже — рекомендуемый порядок без лишних обходных действий.

Шаг 1. Подготовить данные

Используйте Часть I. До установки должны быть понятны компания, поведение, прайс, большой каталог, stable IDs, price-driving dimensions и актуальность sources.

Шаг 2. Настроить через RED

Передайте материалы RED и примените подготовленные изменения.

Шаг 3. Проверить Preview

Не ограничивайтесь вопросом «Привет». Проверяйте реальные продажи.

Шаг 4. Получить персональный download

Скачайте актуальный пакет LEVBOT после того, как ваша конфигурация готова.

Шаг 5. Распаковать на Windows

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

Шаг 6. Запустить `LEVBOT DEPLOY.exe`

DEPLOY должен увидеть расположенную рядом персональную папку Green либо выбранную вами корректную папку Green.

Шаг 7. Настроить модель, сервер и нужные каналы

Не включайте connector «на будущее», если пока не готовы его данные.

Шаг 8. Выполнить установку

DEPLOY сам проводит штатную последовательность.

Шаг 9. Проверить health и реальный канал

После PASS внутреннего health задайте реальный вопрос через тот канал, которым будут пользоваться покупатели.

Шаг 10. Сохранить исходники и не править runtime руками

Изменения бизнеса дальше делаются через RED и Reconfigure.

48. Cloud RED: что происходит при Apply

Когда вы применяете подготовленную конфигурацию в Cloud RED, рабочая логика должна оставаться простой для пользователя:

ваши материалы
→ проверка/подготовка
→ Apply
→ персонализированный Green
→ Preview

Cloud RED использует canonical Green как основу и накладывает только данные конкретного workspace. Ваш персональный Green не строится копированием чужого установленного сервера.

48.1. Первый build

Новый workspace получает текущую canonical v3-базу Green. На неё накладываются данные вашего бизнеса и связанные customer-specific материалы.

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

48.2. Что делает Apply

Apply должен:

собрать актуальный BotContent;
записать customer-specific data;
обновить mutable-content integrity metadata;
проверить целостность;
подготовить/перезапустить Preview;
при контролируемом обновлении иметь snapshot/rollback.

Если применение не удалось, не надо считать полусобранное состояние успешной конфигурацией.

48.3. Что Cloud RED не переносит в персональный download

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

В него не копируются как часть portable customer package:

deployed .env;
серверные SSH credentials;
runtime database/history;
activation receipt с другой машины;
серверные логи;
живые connector secrets из уже установленного окружения.

Это нормальная граница между персональной конфигурацией и конкретной установкой на Linux-машине.

49. Preview: как им пользоваться правильно

Preview — acceptance test бизнесовой конфигурации.

49.1. Что обязательно проверить

Перед download задайте хотя бы:

обычный вопрос о компании;
вопрос о товаре без цены;
простой вопрос о цене;
exact SKU/ID, если есть большой каталог;
естественный запрос без артикула;
неоднозначный запрос;
несуществующий товар;
вопрос после названной цены;
вопрос, на который бот не должен обещать лишнее;
specification, если она используется.

49.2. Проверяйте не только правильность факта

Хороший бот должен:

не выдавать неподтверждённый controlled business fact за подтверждённый source fact;
при этом оставаться инициативным и живым продавцом;
использовать историю коротких follow-up, а не трактовать каждый вопрос как новый isolated lookup;
получать retrieval/evidence/sales guidance до своего ответа;
при ambiguity и неточном совпадении уметь предлагать реальные близкие варианты, если runtime их нашёл;
говорить естественно;
не засыпать клиента внутренними терминами;
не показывать raw JSON;
не рассказывать про catalog_match_status;
не отправлять клиента в технический тупик там, где может продолжить продажу;
задавать уточнение только тогда, когда сама модель считает его полезным;
после цены вести разговор дальше.

49.3. Что Preview не доказывает

Preview PASS
≠
Server deployment PASS

После DEPLOY нужен отдельный реальный smoke на customer Green.

50. Персональный download

Персональный package нужен для переноса подготовленного Green в Desktop DEPLOY.

Текущий принцип:

canonical runtime
+
ваши customer-specific data
=
ваш portable Green

Внутри Green есть две независимые области целостности:

mutable customer content;
immutable product runtime.

О manifests подробно — ниже.

50.1. Не используйте старый архив по привычке

Если Cloud RED предлагает новый актуальный download, используйте его. Не стройте рабочий процесс вокруг случайно сохранённого old_final_final2.zip, если продукт уже выдал новый package.

50.2. Распаковка

Рекомендуемый путь на Windows — понятная локальная папка, например:

C:\LEVBOT\

Важно не конкретное имя каталога, а то, чтобы:

файлы были реально распакованы;
у пользователя были права на чтение/запись;
антивирус или облачная синхронизация не блокировали изменения;
не было нескольких одинаковых распакованных версий, между которыми легко перепутать Green.

51. Desktop RED: основные разделы

В текущем интерфейсе BOT-навигация включает:

Общее
Поведение
Товары и цены
Знания

51.1. Общее

Здесь находится общая конфигурация бота, включая поле:

Имя бота

Имя является частью customer configuration. Если имя специально не задано, продукт имеет собственное значение по умолчанию.

51.2. Поведение

Здесь находятся правила разговора, продажи и customer-specific инструкции.

51.3. Товары и цены

Используется для обычных товаров/цен и связанных настроек.

Помните границу из Части I: большой каталог не надо превращать в огромный обычный prompt.

51.4. Знания

Раздел:

БОТ → Знания

предназначен для CSV/XLSX Knowledge. Используйте его для настоящих больших structured sources.

52. Выбор Green в Desktop

Кнопка:

Выбрать папку

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

До edit/install/reconfigure Green должен пройти штатную проверку целостности.

Если приложение сообщает об integrity mismatch, не надо:

удалять manifest;
переписывать hash;
заменять Python-файл случайной копией;
«чинить» проверку вручную.

Нужно выяснить, почему выбранная папка не соответствует ожидаемому состоянию.

53. Настройка модели

Текущий Desktop имеет поля:

Yandex API Key
Yandex Folder ID
Модель диалогов
Модель изображений
ПРОВЕРИТЬ И АКТИВИРОВАТЬ LLM

53.1. API Key

Это secret.

Не публикуйте его:

в документации;
скриншотах;
Git;
открытом чате;
customer-facing логах.

53.2. Folder ID

Используется текущим provider flow вместе с ключом/выбранными моделями.

53.3. Модель диалогов

Используется для основного общения.

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

53.4. Модель изображений

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

53.5. Проверка перед install

Лучше подтвердить model configuration ещё до SSH-install. Если provider key неверен, бессмысленно искать проблему в nginx.

54. Параметры сервера в DEPLOY

Текущий интерфейс использует:

Поле	Смысл
`IP или сервер`	SSH target
`SSH-порт`	SSH port, обычно 22
`Пользователь`	Linux SSH user
`Доступ`	password или key mode
`Пароль`	SSH password
`SSH-ключ`	путь к private key
`Passphrase`	пароль encrypted private key

54.1. Пароль

SSH-пароль используется в процессе подключения и не должен превращаться в обычную customer setting, лежащую открытым текстом в проекте.

54.2. SSH key

Если используется key-auth, указывайте правильный private key.

Не отправляйте private key в чат технической поддержки, если для диагностики достаточно текста ошибки.

54.3. Пользователь

DEPLOY должен работать с пользователем, которому разрешены необходимые операции штатным образом.

Не меняйте server hardening только потому, что ввели неправильный SSH user.

55. Домен и webchat

Текущие поля:

Домен
Путь чата
Email для HTTPS

Default chat path:

/site/levbot

55.1. Домен

Нужен для публичного webchat/nginx-flow. DNS должен указывать на сервер, если вы ожидаете публичный HTTPS.

55.2. Путь чата

Штатный default:

/site/levbot

Не меняйте его без необходимости, если не понимаете, зачем нужен другой route.

55.3. Email для HTTPS

Используется в flow получения/обслуживания публичного сертификата там, где это требуется.

56. Что DEPLOY делает на Linux

DEPLOY не является произвольной SSH-консолью. У него есть детерминированный installation plan.

Упрощённо последовательность такая:

validate
→ SSH
→ OS check
→ license preflight
→ target directory
→ activation receipt
→ privacy assets
→ upload Green
→ connector/settings patches
→ actions config
→ .env
→ Python venv/dependencies
→ systemd
→ webchat
→ nginx
→ service start
→ internal health
→ public URL check
→ connector checks/registration
→ install marker

56.1. Целевая директория

/opt/levbot-green

56.2. Python environment

DEPLOY создаёт/обслуживает Python virtual environment и ставит зависимости из canonical Green.

Не надо вручную ставить случайные версии библиотек в system Python для «лечения» ошибки.

56.3. `.env`

Рабочая конфигурация Green хранится в server-side .env.

DEPLOY записывает её с ограниченными правами:

Не редактируйте deployed .env как обычный текстовый блок в случайном SSH-сеансе, если изменение уже поддерживается DEPLOY/Reconfigure.

56.4. systemd

Служба:

levbot-green.service

Она отвечает за запуск Green как server process.

56.5. Webchat assets

Штатная директория:

/var/www/levbot-green-site

56.6. nginx

DEPLOY создаёт/обновляет необходимую конфигурацию и выполняет штатные проверки.

Перед изменением server block предусмотрено backup-состояние nginx.

56.7. Health

Внутренний endpoint:

http://127.0.0.1:8080/health

Успешный install не должен считаться завершённым, если service не прошёл health.

57. Поддерживаемое server environment

Текущий server-preparation flow ориентирован на Ubuntu/Debian-подобную Linux-среду.

DEPLOY устанавливает/использует базовый набор, в который входят:

Python 3;
venv;
pip;
nginx;
curl;
CA certificates;
snapd в соответствующем HTTPS flow.

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

58. Лицензия: понятная модель для владельца

Лицензирование отделено от бизнесовых данных.

Основная модель:

Account
→ Entitlement
→ License
→ Installation

Для обычного клиента используется STANDARD license.

Текущая продуктовая политика STANDARD предусматривает:

срок лицензии 5 лет;
одну одновременно активную server installation на одну single-installation license;
учётную запись, которая может владеть лицензиями;
отдельную лицензию для дополнительной независимой установки.

На момент этой версии manual текущий Cloud RED содержит server-side цену продукта 8000 RUB. Если официально отображаемая цена/условия в актуальном интерфейсе покупки изменились, источником истины является текущая offer/payment configuration, а не сохранённая старая копия manual.

58.1. Одна активная установка

Лицензия привязывается к конкретной Linux-машине через производный fingerprint.

Нельзя использовать одну single-installation license одновременно на двух разных серверах.

58.2. Повторная активация той же машины

Штатный retry той же installation должен быть идемпотентным: тот же корректный fingerprint не должен создавать новую параллельную installation.

58.3. Второй сервер

Другая машина при уже занятой single-installation license должна быть отклонена.

Для второго одновременно активного сервера нужна отдельная подходящая лицензия либо штатная операция освобождения/переноса installation, если она доступна в текущем account/admin flow.

58.4. Не путайте Windows и Linux fingerprint

Лицензия рабочего Green относится к server installation, а не к случайному Windows-компьютеру, на котором открыт DEPLOY.

59. Activation receipt

После успешной активации Green получает signed local receipt.

Штатный путь:

/opt/levbot-green/.deploy/activation-receipt.json

Green проверяет receipt при запуске.

Для пользователя важно:

receipt нужен рабочему Green;
его не надо вручную редактировать;
его не надо копировать с другого сервера;
его не надо генерировать самому;
private signing key никогда не должен находиться в DEPLOY или customer Green.

Receipt — служебный licensing artifact. Штатно им управляет product flow.

60. Покупка и download

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

Практические правила архитектуры:

browser не должен сам определять цену;
browser не должен сам определять product/license duration;
заказ создаётся server-side;
повторный callback одного и того же order не должен размножать лицензии;
отдельная новая успешная покупка может дать отдельную лицензию;
email — account identity, а не «одна лицензия навсегда».

Для владельца всё сводится к простому правилу:

Покупайте через штатный интерфейс RED/downloads и не пытайтесь вручную собирать payment URL или license artifacts.

61. После install: первый реальный smoke

Сразу после успешного DEPLOY проверьте не только health.

Минимум:

levbot-green.service active;
внутренний health PASS;
публичный webchat открывается, если включён;
обычный вопрос о компании;
простой товар;
цена;
большой Knowledge query, если используется;
ambiguity;
not found;
реальный подключённый канал.

Если Preview был хорош, а deployed Green отвечает иначе, это отдельная диагностическая задача: environment, package, provider, connector или install state.

62. Каналы: общий принцип

Connector — это транспорт.

Бизнесовая логика не должна жить отдельно внутри каждого канала.

Идеальная модель:

Входящее сообщение
      ↓
connector
      ↓
Green
      ↓
единая бизнесовая логика / history / evidence
      ↓
ответ
      ↓
connector

Это позволяет не создавать «отдельного бота для Telegram» и «другого бота для сайта» с разными мозгами.

63. Состояния connector в Desktop

Текущий интерфейс использует понятные состояния:

отключён → ПОДКЛЮЧИТЬ;
подключён → ОТКЛЮЧИТЬ;
операция ожидается → ОТМЕНИТЬ.

Важный принцип:

Отключённый connector не должен требовать credentials только потому, что вы когда-то открывали его форму.

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

64. Сайт

Website chat — самый прямой путь проверить customer Green без внешней CRM.

Основной runtime endpoint:

POST /chat

Также Green имеет:

GET /
GET /health

64.1. Защита webchat

Current Green имеет ограничения:

на session;
на IP;
global minute/hour rate;
concurrent requests;
размер body;
размер текста;
параметры image URL.

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

64.2. Public route

Default:

/site/levbot

Публичный path обслуживается через nginx/webchat layer, а внутренний Green остаётся на localhost.

65. Telegram

Текущий Desktop поддерживает Telegram.

В интерфейсе есть:

Подключить Telegram
Маршрут: Напрямую / Через Bitrix24
Bot Token
Проверить

65.1. Direct

Green принимает Telegram webhook через:

POST /telegram/webhook

65.2. Через Bitrix24

Если Telegram уже является частью Bitrix24 communication flow, можно использовать соответствующий route через Bitrix вместо отдельной прямой схемы.

65.3. Сетевое ограничение

Текущий UI предупреждает, что Telegram с российских серверов может работать медленнее или нестабильно в зависимости от текущей сети/доступности.

Это внешний transport-factor, а не обязательно ошибка модели или BotContent.

66. Bitrix24

Текущий Desktop имеет настройки:

Подключить Bitrix24
REST webhook
BOT_ID
CLIENT_ID
Application token

и связанные lead/action controls.

Green принимает Bitrix inbound через:

POST /bitrix

66.1. Application token

Текущий UI предусматривает ситуацию, когда Application token появляется автоматически после первого Bitrix24 message.

Он не обязан существовать до первого запуска Green.

Не создавайте себе блокер, требуя заполнить поле, которое штатно формируется позже.

66.2. Имя бота

При Reconfigure и корректной существующей Bitrix configuration DEPLOY может синхронизировать изменённое имя существующего Bitrix bot.

66.3. Права и внешний Bitrix setup

Точные инструкции по permissions конкретного Bitrix24 аккаунта могут меняться со стороны Bitrix.

Если внешний API/кабинет изменился, следуйте актуальной документации площадки; LEVBOT manual описывает собственный product contract, а не гарантирует неизменность чужого UI.

67. Instagram

В текущем Desktop UI Instagram Direct указан как работающий через Bitrix24.

Это не отдельный полностью независимый Green connector с отдельным новым бизнесовым runtime.

Если Instagram не используется, его не нужно включать ради полноты.

68. MAX

Текущий Desktop поддерживает MAX.

Основные поля:

Подключить MAX
Маршрут: Напрямую / Через Bitrix24
Токен бота

Green имеет MAX endpoint:

POST /max

Как и у Telegram, внешний transport может иметь собственные требования и ограничения площадки.

69. amoCRM

Текущий Desktop имеет:

Подключить amoCRM
Адрес аккаунта
Долгосрочный токен
Воронка
Этап сделки
Создавать задачу менеджеру

и связанные Salesbot/outbox controls.

Green имеет:

POST /amocrm/inbound
GET /amo/oauth/callback

69.1. Архитектурный принцип

Salesbot/connector — транспортный слой.

Контекст разговора принадлежит Green, а не отдельному бесконечному amoCRM bot-сценарию.

69.2. Защита от неправильного inbound

Current Green имеет pre-model guard: некорректный/non-positive contact ID либо invalid/missing outbox field не должны запускать бессмысленный model call.

Если amoCRM message не доходит до модели, сначала проверяется transport/configuration, а не переписывается prompt.

70. Avito

Текущий Desktop поддерживает Avito configuration.

В ней предусмотрены:

enabled state;
route напрямую либо через Bitrix24/amoCRM в поддерживаемом flow;
client ID;
client secret;
webhook secret/configuration.

Avito runtime отделён от общей бизнесовой логики Green.

Точные действия во внешнем кабинете Avito могут зависеть от текущего API и прав аккаунта. Не используйте старую инструкцию внешней площадки как product contract LEVBOT.

71. Actions

actions.json описывает action/channel policy.

Desktop умеет настраивать общий или channel-specific набор действий.

Типовые customer-facing действия могут включать:

lead;
ссылку;
handoff;
payment-related action;
booking/form-related action;
другие поддерживаемые действия.

Runtime хранит action-state, чтобы необратимое действие не выполнялось многократно из-за внутренних retries.

Это важная граница:

Model может решить по смыслу, что нужно передать клиента менеджеру. Runtime должен не дать одному физическому сообщению породить бесконечное число одинаковых side effects.

72. Персональные данные и privacy

Desktop имеет отдельную privacy-конфигурацию.

Основной control:

Включить работу с персональными данными

Также есть опция запрашивать согласие перед сбором/передачей контактов.

Текущие operator fields:

тип оператора;
полное наименование или ФИО;
ИНН;
ОГРН/ОГРНИП;
адрес;
email для обращений и отзыва согласия.

Документы доступны по routes вроде:

/site/levbot/legal/privacy
/site/levbot/legal/consent

Desktop умеет:

СГЕНЕРИРОВАТЬ ДОКУМЕНТЫ
ОТКРЫТЬ ПРЕДПРОСМОТР

72.1. Что проверить перед production

operator data актуальны;
email существует;
документы открываются;
consent включён там, где он требуется вашей схеме;
business behavior не просит у покупателя лишние данные.

Этот manual не является юридической консультацией по конкретной компании. Он описывает product controls.

73. Cards и media

Green поддерживает карточки с изображениями:

JPG;
JPEG;
PNG;
WEBP.

Модель может вернуть marker карточки, а runtime покажет только реально существующий asset.

73.1. Внутренние поля не показываются покупателю

Модель не должна рассказывать клиенту внутреннее имя card_views.json или служебный marker. Для покупателя это обычная карточка товара.

73.2. Цена на изображении

Цена, распознанная Vision-моделью, не должна автоматически становиться сильнее актуального structured price source.

Если карточка содержит цену, а Knowledge/configured price содержит другую актуальную цену, это data conflict, который нужно устранить.

74. Vision

Vision — опциональный слой.

Он полезен, когда клиент отправляет изображение товара/объекта.

Но:

Vision может ошибаться;
он не должен придумывать невидимые параметры;
при неудачной обработке runtime не должен выдумывать описание изображения;
Vision не превращает фотографию в универсальный инженерный измеритель;
цена с картинки не должна становиться произвольным authoritative numeric fact.

75. История и состояние

Customer Green хранит conversation/runtime state в SQLite:

lev_state.db

рядом с runtime source.

История загружается/сохраняется по chat identity соответствующего transport flow.

Cloud Preview хранит свою тестовую историю отдельно, в памяти preview process.

Следовательно:

История Cloud Preview и история работающего customer Green — не одна и та же база.

Это нормальная и намеренная граница.

76. Reconfigure: зачем он нужен

Reconfigure — штатный способ изменить уже установленный Green без ручной полной переустановки.

Используйте его, когда изменились:

BotContent;
прайс;
Knowledge;
configured prices;
cards;
provider settings;
connector settings;
домен/часть deploy config;
поддерживаемая runtime-версия;
другие параметры, которые DEPLOY умеет обновлять.

Не удаляйте /opt/levbot-green и не ставьте всё заново каждый раз.

77. Что происходит при Reconfigure

Упрощённая последовательность:

validate local Green
→ SSH
→ license ensure
→ read existing server env
→ controlled canonical runtime update if needed
→ connector/settings patches
→ actions/content update
→ atomic env update
→ nginx update if needed
→ restart
→ health
→ connector checks/registration

Если возникает exception, Reconfigure имеет backup/rollback path для тех областей, которые он изменяет.

78. Что Reconfigure должен сохранять

Текущий product contract разделяет customer-specific state и runtime update.

Данные	Ожидаемое поведение
`company.md`	сохранить/обновить по применённой customer configuration
`behavior.md`	сохранить/обновить
`pricing.md`	сохранить/обновить
`tenant.json`	сохранить customer config
`actions.json`	сохранить customer action config
`card_views.json`	сохранить
`cards/`	сохранить
`knowledge/`	сохранить
`configured_prices/`	сохранить
`.env`	сохранить действующие server/customer settings с controlled update нужных полей
state/history	не уничтожать runtime update
activation receipt	не терять при обычном Reconfigure
connector credentials	сохранять по штатному config contract

Главная идея:

Runtime update и customer data — разные слои.

79. Rollback при Reconfigure

Если новая конфигурация не проходит staging, validation, restart или health, Reconfigure должен попытаться вернуть backup-состояние изменённых областей.

Практический вывод:

Не надо после первой ошибки сразу вручную переписывать remote files. Сначала дайте DEPLOY завершить штатный rollback и прочитайте итоговый статус.

80. MANIFEST.json

MANIFEST.json — authoritative integrity contract для mutable BotContent.

Он относится к изменяемым customer files.

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

Нормальный flow:

изменение через RED
→ save/apply
→ manifest обновлён штатно

81. RUNTIME_MANIFEST.json

RUNTIME_MANIFEST.json — отдельный strict contract для product runtime.

Он контролирует набор runtime-managed файлов.

Текущий canonical runtime содержит 13 таких файлов.

Смысл:

MANIFEST.json
→ customer mutable content

RUNTIME_MANIFEST.json
→ immutable product engine/runtime

Эти contracts нельзя смешивать.

82. CHECKSUMS.sha256

Исторический CHECKSUMS.sha256 больше не является authoritative mutable-content contract.

В текущем Desktop:

CHECKSUMS REQUIRED: NO

Новый Cloud personal package также не должен создавать его как обязательный state.

Если в старой папке остался legacy checksum file, сам факт его наличия не делает его источником истины.

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

83. Что пользователь не должен редактировать руками

Не используйте ручное редактирование как штатный путь для:

RUNTIME_MANIFEST.json;
13 runtime-managed files;
MANIFEST.json;
activation receipt;
deployed .env;
lev_state.db;
Knowledge manifests/normalized JSON;
configured-prices manifests/normalized JSON;
nginx/systemd, если изменение поддерживается DEPLOY;
connector runtime Python.

Если нужно поменять бизнес — меняйте business data.

Если нужно поменять deployment config — используйте DEPLOY/Reconfigure.

Если product contract реально не покрывает правильный бизнесовый сценарий — это отдельный feature/bug, а не повод создать клиентский fork.

84. Диагностика: сначала определить слой

Очень полезное правило:

Не лечите модель, если сломан SSH. Не лечите nginx, если отсутствует price evidence.

Разделите проблемы.

Слой A — данные бизнеса

Симптомы:

неправильная цена;
ambiguity;
not found;
неправильный variant;
бот не знает факт.

Проверять:

BotContent;
Knowledge;
configured prices;
stable ID;
source conflict.

Слой B — model provider

Симптомы:

auth error;
provider unavailable;
model request failing.

Проверять:

API key;
Folder ID;
model configuration;
network/provider status.

Слой C — DEPLOY/SSH

Симптомы:

connection refused;
auth failed;
permission denied;
upload impossible.

Проверять server fields и права.

Слой D — Linux runtime

Симптомы:

service failed;
health fail;
dependency issue.

Проверять DEPLOY output/service health.

Слой E — connector

Симптомы:

сайт работает, Telegram/CRM нет;
message не приходит;
wrong account/field/webhook.

Проверять connector-specific config.

85. Ошибка SSH

Проверить:

правильный IP/host;
SSH port;
user;
password/key mode;
правильный private key;
passphrase;
firewall/provider access;
работает ли обычный SSH с теми же credentials.

Не надо:

отключать все server security controls;
включать root/password login только ради одной опечатки;
отправлять private key в чат.

86. Ошибка модели

Проверить:

Yandex API Key;
Yandex Folder ID;
model selection;
provider check;
server/desktop network.

Permanent auth/config error не должен маскироваться бесконечными retries.

87. Recovery при model/provider failure

Current Green имеет общий turn budget:

до 120 секунд wall-clock;
до 20 generation attempts в пределах recovery contract.

Это верхние границы внутреннего recovery, а не обещание, что каждый ответ будет ждать две минуты.

Permanent provider/auth/config ошибки должны завершаться раньше, а не бессмысленно использовать все attempts.

Физическое входящее сообщение клиента сохраняется один раз; внутренние retries не должны создавать десять одинаковых user turns.

88. Технический emergency fallback

В обычном business dialogue Green не использует deterministic customer-facing fallback для not found, ambiguity, отсутствия exact match или ценового retrieval. Эти состояния превращаются в evidence и sales guidance, после чего модель сама выбирает продолжение разговора и пишет ответ.

Fallback остаётся только для настоящего технического отказа, когда после предусмотренного recovery budget модель/provider/transport физически не смогли вернуть нормальный ответ. Такой emergency message должен быть коротким и человеческим и не должен притворяться результатом поиска по каталогу.

То есть технический fallback нельзя использовать как скрытую замену продавца:

NOT_FOUND / AMBIGUITY / NO_EXACT_PRICE
→ не runtime-фраза клиенту
→ evidence + guidance
→ model-authored continuation

Главная цель emergency fallback — не показывать клиенту traceback, raw JSON, transport exception или внутреннюю техническую ошибку. Как только модель доступна, бизнесовый ответ снова полностью принадлежит ей.

89. Ошибка Knowledge

Если большой catalog question не находится:

проверить, что source реально добавлен в БОТ → Знания;
проверить Apply;
проверить stable ID;
проверить human-readable fields;
проверить, что searchable fact не спрятан только в technical JSON;
проверить дубли;
проверить актуальность source.

Не добавляйте весь XLSX в behavior.md как workaround.

90. Ошибка цены и evidence

Если Green называет не ту цену, не видит ожидаемую позицию или плохо ведёт себя вокруг цены, сначала диагностируйте данные и retrieval, а не добавляйте новый customer-facing gate/fallback.

Проверить:

существует ли нужная цена в актуальном source;
правильный ли source попал в retrieval;
совпадает ли record/row identity;
правильные ли currency и unit;
нет ли конфликтующей цены той же identity в другом source;
дошли ли до модели нужные exact/near candidates;
корректно ли runtime описал найденные facts и ambiguity в evidence/sales guidance;
не перепутано ли наличие строки в каталоге с фактом текущего складского наличия;
не требуется ли неподдерживаемая произвольная формула вместо готового business fact.

В текущем model-first customer flow runtime не должен после model call переписывать ответ, требовать JSON/claims protocol или подставлять deterministic business recovery. Если проблема повторяется на корректных данных, нужен reproduction retrieval/guidance/model context.

Часть I подробно описывает data-design contract.

91. MANIFEST mismatch

Mutable manifest mismatch означает, что current customer-content state отличается от ожидаемого integrity contract.

Не исправляйте это удалением проверки.

Проверьте:

файл менялся вручную?
был скопирован из другой версии?
применился ли RED save?
выбран ли правильный Green?

После штатного RED Apply manifest должен быть обновлён самим продуктом.

92. Runtime mismatch

Runtime mismatch — более серьёзная граница.

Это означает, что один или несколько managed runtime files не совпадают с canonical contract.

Не копируйте «похожий lev_server.py» из старой папки.

Правильный путь — canonical runtime update через product flow.

93. Connector не отвечает

Если website chat работает, а один connector нет, это хороший сигнал: business/model/runtime core, вероятно, жив.

Дальше проверяйте:

enabled state;
credentials;
route direct/CRM;
webhook;
account URL;
required IDs;
external API permission;
current provider availability.

Не меняйте Green business prompt из-за ошибки webhook.

94. Что хранится где: практическая карта

Сущность	Где/какой слой	Кто должен менять
`company.md`	Green BotContent	RED
`behavior.md`	Green BotContent	RED
`pricing.md`	Green BotContent	RED
`tenant.json`	Green customer config	RED
`actions.json`	actions policy	RED/DEPLOY
`card_views.json`	card mapping	RED
`cards/`	media	RED/customer content flow
`knowledge/`	big structured data	Desktop RED
`configured_prices/`	structured prices	Desktop RED
`MANIFEST.json`	mutable integrity	продукт автоматически
`RUNTIME_MANIFEST.json`	runtime integrity	release/product
`.env`	deployed secrets/config	DEPLOY/Reconfigure
`lev_state.db`	deployed runtime state/history	Green
activation receipt	deployed license state	activation flow
nginx	web transport	DEPLOY
systemd unit	service lifecycle	DEPLOY

95. Backup-мышление владельца

LEVBOT имеет внутренние snapshot/rollback механизмы для controlled operations, но владелец всё равно должен разумно относиться к исходникам.

Храните отдельно:

исходные бизнес-документы;
актуальный каталог;
normalized source, если его подготовил агент;
актуальный portable download;
свои server credentials в безопасном месте;
собственный SSH private key;
информацию о домене/DNS;
текущие connector credentials согласно политике компании.

Не надо делать backup чужого customer Green или server-side private signing key License Server.

96. Как обновлять бизнес без хаоса

Предположим, поменялось:

200 цен;
список товаров;
инструкция продавца.

Правильный flow:

обновить source
→ Desktop RED
→ Knowledge/pricing/behavior
→ Apply
→ Preview
→ контрольные вопросы
→ Reconfigure
→ deployed health
→ real channel smoke

Неправильный:

SSH
→ nano pricing.md
→ случайно поменять Python
→ перезапустить systemd
→ забыть manifest
→ через месяц не понимать, откуда взялась версия

97. Как обновлять только каталог

Если BotContent не менялся:

обновить исходный CSV/XLSX;
заменить Knowledge source;
Apply;
проверить row count/stable IDs;
Preview;
Reconfigure;
проверить несколько SKU на deployed Green.

Не надо пересоздавать всю компанию с нуля.

98. Как обновлять только правила разговора

Если прайс и каталог не менялись:

изменить behavior через RED;
Apply;
Preview на нескольких диалогах;
Reconfigure;
real channel smoke.

Это не повод трогать Knowledge runtime.

99. Как менять модель/provider settings

Используйте предусмотренные поля DEPLOY.

После изменения:

проверить provider;
Reconfigure;
health;
обычный диалог;
price query;
Vision query, если менялась image model.

Не надо править settings.py под конкретный API key.

100. Как менять домен

Домен затрагивает:

DNS;
nginx;
HTTPS;
public webchat URL.

Поэтому после Reconfigure:

проверить DNS;
nginx config;
public page;
HTTPS;
privacy routes;
chat route.

Изменение домена не должно менять business Knowledge/prices.

101. Что считать успешной установкой

Не только зелёную кнопку в DEPLOY.

Успешный production installation имеет несколько доказательств:

SSH install completed
+
license valid
+
service active
+
internal health PASS
+
public path PASS if enabled
+
model response PASS
+
business question PASS
+
price/Knowledge PASS if used
+
real connector PASS

102. Чек-лист перед DEPLOY

[ ] данные прошли Part I;
[ ] Cloud/Desktop Preview PASS;
[ ] используется актуальный personal Green;
[ ] model API key готов;
[ ] Folder ID готов;
[ ] model выбран;
[ ] Linux server доступен;
[ ] SSH credentials проверены;
[ ] домен указывает на server, если нужен сайт;
[ ] email для HTTPS указан, если нужен;
[ ] нужные connectors определены;
[ ] ненужные connectors выключены;
[ ] лицензия доступна;
[ ] старый архив не перепутан с актуальным.

103. Чек-лист после DEPLOY

[ ] levbot-green.service active;
[ ] /health PASS;
[ ] public chat открывается;
[ ] обычный вопрос PASS;
[ ] company fact PASS;
[ ] simple price PASS;
[ ] exact SKU PASS, если используется;
[ ] natural Knowledge query PASS;
[ ] ambiguity остаётся живым sales dialogue и даёт модели реальные варианты;
[ ] not found не превращается в deterministic тупик;
[ ] specification PASS, если используется;
[ ] card/media PASS, если используется;
[ ] privacy documents открываются, если включены;
[ ] реальный connector получает сообщение;
[ ] ответ возвращается в тот же канал;
[ ] manager action/handoff не дублируется;
[ ] после restart бот снова healthy.

104. Чек-лист после Reconfigure

[ ] health PASS;
[ ] BotContent актуален;
[ ] Knowledge не потерян;
[ ] configured prices не потеряны;
[ ] cards сохранены;
[ ] .env действующий;
[ ] license receipt на месте;
[ ] history/state не уничтожены;
[ ] connector credentials работают;
[ ] changed behavior применился;
[ ] один старый контрольный query всё ещё PASS;
[ ] один новый query PASS.

105. Что передать техническому агенту при диагностике

Если другой GPT/Codex помогает с проблемой, дайте ему:

эту полную документацию;
точную стадию: RED / Preview / DEPLOY / deployed Green / connector;
текст ошибки;
релевантный лог без secrets;
какой action выполнялся;
expected result;
actual result;
минимальный reproduction;
актуальный source file, если проблема в данных.

Не давайте:

SSH password;
API key;
private SSH key;
license-server private signing key;
CRM long-lived tokens в открытом виде;
полный production .env.

106. Что внешний агент может делать

Агент может:

анализировать логи;
анализировать customer data;
готовить CSV/XLSX/TXT;
проверять structured records;
предлагать regression tests;
объяснять DEPLOY fields;
помогать диагностировать слой ошибки;
сравнивать expected/actual;
подготовить bug report.

Без отдельной задачи разработчика продукта он не должен:

переписывать canonical Green runtime;
отключать manifest validation;
создавать license bypass;
подменять receipt;
менять connector implementation;
создавать «особый Green для одного клиента»;
исправлять production server хаотическими SSH-командами, если штатный DEPLOY уже покрывает операцию.

107. Граница между customer configuration и product development

Пример customer configuration:

Для этого товара сначала уточняй материал.

Это BotContent.

Пример product feature:

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

Это изменение продукта.

Пример customer configuration:

Вот 5000 SKU.

Это Knowledge.

Пример product feature:

Нам нужен parser нового proprietary binary format.

Это изменение продукта.

Такая граница помогает не превращать каждую установку LEVBOT в заказную разработку.

108. Глоссарий

RED

Конфигуратор персонального Green.

Cloud RED

Облачная среда настройки/workspace/download.

Desktop RED

Локальная среда редактирования внутри LEVBOT DEPLOY.

Preview

Тест разговора до customer deployment. Не заменяет server smoke.

Green

Рабочий AI-продавец на customer Linux server.

DEPLOY

Windows-приложение установки и Reconfigure.

BotContent

Бизнесовые факты и правила разговора.

Knowledge

Большие structured CSV/XLSX sources и retrieval по ним.

Configured prices

Явные structured price records.

Sellable identity

Однозначная продаваемая сущность.

Stable ID

Устойчивый identifier товара/позиции.

Evidence

Фактическая опора, которую runtime извлёк из business data и передал модели до ответа: source, row/record, цена, unit, attributes, candidates или другой релевантный факт. Evidence помогает модели отличать найденные данные от собственной разговорной гипотезы, но само по себе не диктует customer-facing формулировку.

Ambiguity

Ситуация, когда текущих данных недостаточно для одного однозначного результата. Runtime сообщает неоднозначность и варианты модели; модель сама решает sales move.

Specification

Явный набор идентифицированных позиций и quantities с валидируемой арифметикой.

MANIFEST.json

Integrity contract mutable BotContent.

RUNTIME_MANIFEST.json

Strict integrity contract product runtime.

Activation receipt

Подписанный локальный artifact, подтверждающий server installation license.

Reconfigure

Штатное изменение уже установленного Green с сохранением customer state.

Connector

Transport между внешней площадкой и Green.

109. Финальная модель эксплуатации

Владелец
   ↓
готовит бизнес
   ↓
RED
   ↓
BotContent / Knowledge / prices / cards / actions
   ↓
Preview
   ↓
personal Green
   ↓
DEPLOY
   ↓
Linux server
   ↓
activation
   ↓
systemd + nginx
   ↓
Green
   ↓
connector
   ↓
покупатель

Изменения бизнеса:
source
   ↓
RED
   ↓
Preview
   ↓
Reconfigure
   ↓
health
   ↓
real-channel smoke

110. Десять правил эксплуатации

Первое. Сначала проверяйте данные в Preview, потом ставьте на сервер.

Второе. Preview и deployed Green — разные среды; после DEPLOY нужен отдельный smoke.

Третье. Не редактируйте runtime под бизнес.

Четвёртое. Не правьте manifests вручную.

Пятое. Не копируйте activation receipt между серверами.

Шестое. Не лечите connector через prompt и не лечите price evidence через nginx.

Седьмое. Для последующих изменений используйте Reconfigure.

Восьмое. Проверяйте не только health, но и реальный бизнесовый вопрос через реальный channel.

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

Десятое. Если штатный правильный customer flow требует изменить canonical Python runtime, отделите product bug/feature от конфигурации клиента.

Приложение A. Техническая карта runtime и deployment boundaries

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

A.1. Runtime-controlled files

Current Green имеет отдельный runtime manifest, который контролирует 13 product files:

actions_runtime.py
avito_runtime.py
config_check.py
green_conversation.py
knowledge_runtime.py
lead_delivery.py
lev_server.py
levbot_entrypoint.py
license_receipt.py
media_runtime.py
privacy_runtime.py
requirements.txt
settings.py

Их смысл — product engine.

Customer RED не должен менять их при обычной настройке.

Если вы меняете company.md, это настройка бизнеса.

Если вы меняете knowledge_runtime.py, это уже разработка продукта.

A.2. Mutable business layer

К customer layer относятся, в частности:

company.md
behavior.md
pricing.md
tenant.json
actions.json
card_views.json
cards/
knowledge/
configured_prices/
privacy.json
legal/

Конкретная обязательность optional paths зависит от включённых функций.

A.3. Server-specific layer

К конкретной Linux installation относятся:

.env
lev_state.db
activation receipt
systemd service
nginx config
webchat files
connector/server state
install marker

Portable personal Green не должен переносить server-specific state с другой машины.

Приложение B. Нормальный порядок расследования «бот не работает»

Используйте diagnostic tree сверху вниз.

1. Открывается ли DEPLOY?
   NO → Windows/package problem
   YES ↓

2. Проходит ли local Green integrity?
   NO → wrong/corrupt Green
   YES ↓

3. Работает ли provider check?
   NO → API/model config
   YES ↓

4. Работает ли Preview?
   NO → business/model/config
   YES ↓

5. Есть ли SSH?
   NO → server/network/auth
   YES ↓

6. Завершился ли installer?
   NO → server preparation/install
   YES ↓

7. levbot-green.service active?
   NO → deployed runtime/service
   YES ↓

8. /health PASS?
   NO → runtime/env/dependency
   YES ↓

9. Website chat PASS?
   NO → nginx/domain/webchat
   YES ↓

10. Business question PASS?
    NO → content/Knowledge/evidence
    YES ↓

11. External connector PASS?
    NO → connector/external platform
    YES → installation healthy

Этот порядок экономит время, потому что исключает целые классы причин сверху вниз.

Приложение C. Acceptance-сценарий нового владельца

После установки можно сохранить себе такой набор тестов.

TEST 1 — COMPANY
Кто вы и чем занимаетесь?

TEST 2 — SIMPLE PRODUCT
Расскажи про <реальный товар>.

TEST 3 — PRICE
Сколько стоит <однозначный товар>?

TEST 4 — KNOWLEDGE EXACT
Сколько стоит SKU <реальный ID>?

TEST 5 — KNOWLEDGE NATURAL
Нужен <товар человеческими словами>.

TEST 6 — AMBIGUITY
Сколько стоит <семейство, где есть два варианта>?

TEST 7 — NOT FOUND
Сколько стоит <несуществующий SKU>?

TEST 8 — FOLLOW-UP
А доставка/следующий шаг?

TEST 9 — HANDOFF
<вопрос, который должен передаваться менеджеру>

TEST 10 — CONNECTOR
Повторить один реальный вопрос через production channel.

Expected result — не дословный текст. Проверяются:

runtime успел собрать релевантные evidence/candidates/guidance до model call;
контекст предыдущих коротких реплик не потерян;
модель сама выбрала тактику и написала весь видимый ответ;
подтверждённые source facts не перепутаны между товарами/вариантами;
неподтверждённая сумма не выдана за подтверждённую catalog/source price;
при ambiguity/неточном совпадении используются разумные реальные варианты, если они найдены;
not found не превращается в generic runtime refusal;
human-readable ответ;
delivery обратно в нужный канал.

Приложение D. Что фиксировать перед обращением в поддержку

Хороший bug report:

PRODUCT STAGE:
Cloud RED / Desktop RED / Preview / DEPLOY / Green / Connector

ACTION:
что нажали/отправили

INPUT:
минимальный безопасный пример

EXPECTED:
что должно было произойти

ACTUAL:
что произошло

ERROR:
точный текст

HEALTH:
PASS/FAIL

SERVICE:
active/failed/not applicable

CHANNEL:
site / Telegram / Bitrix24 / amoCRM / Avito / MAX

DATA SOURCE:
pricing / Knowledge / configured / none

REPRODUCIBLE:
YES/NO

SECRETS REMOVED:
YES

Если проблема в данных, приложите минимальный anonymized row/record.

Если проблема в system/service — приложите релевантный кусок лога без secrets.

Приложение E. Что должна давать внешняя Wiki

Публичная Wiki должна содержать не маркетинговую страницу «ИИ-продавец для бизнеса», а полный product manual.

Внешний агент после чтения Wiki должен суметь ответить как минимум:

LEVBOT self-hosted или SaaS?
где живёт customer Green?
зачем нужен RED?
зачем нужен DEPLOY?
что такое Preview?
какие business documents поддерживаются?
как устроен большой каталог?
может ли LEVBOT работать с тысячами SKU?
что делать с высокой вариативностью?
как защищаются цены от выдумывания?
что умеет specification?
какие pricing shapes не поддерживаются автоматически?
какие connectors есть?
где хранится история?
что сохраняется при Reconfigure?
как устроена server license?
что является customer data, а что product runtime?
где заканчивается настройка и начинается новая разработка?

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

Приложение F. Финальная памятка владельцу

1. Не начинай с сервера — начни с данных.
2. Не начинай с тысячи полей — выбери простейшую достаточную структуру.
3. Большой каталог → Knowledge.
4. Варианты цены → явные identities.
5. Preview до install.
6. DEPLOY вместо ручного SSH-deployment.
7. License привязана к server installation.
8. Health после каждого install/reconfigure.
9. Реальный channel smoke обязателен.
10. Source-файлы храни отдельно.
11. Runtime руками не правь.
12. Если не понимаешь слой ошибки — используй diagnostic tree.

Финальная граница документа

LEVBOT должен настраиваться данными и штатными инструментами, а не ручными патчами runtime под каждого клиента.

Если задача решается подготовкой business data — используйте Часть I. Если она относится к установке, конфигурации, каналам или обновлению — используйте Часть II. Если корректный customer contract требует менять canonical runtime, это уже отдельная задача разработки продукта.

Canonical publication rule: полная версия этого файла публикуется в release archive и в Wiki без смысловых сокращений.

Полное руководство LEVBOT

LEVBOT — полное руководство

Для владельца, технического специалиста и AI-агента

Назначение

Если этот файл читает внешний AI-агент

Один canonical текст

Содержание

Часть I. Бизнес, документы, Knowledge, цены и вариативность

Часть II. RED, DEPLOY, Green, лицензия, каналы и эксплуатация

Приложения

Часть I. Бизнес, документы, Knowledge, цены и вариативность

Введение к Части I. Зачем существует эта часть

1. LEVBOT в двух словах: где здесь данные

BotContent

Knowledge

Configured prices

Cards и информационные данные

Главная граница

2. Два основных сценария бизнеса

2.1. Сценарий A: небольшой и относительно однозначный ассортимент

Базовая рекомендация

2.2. Сценарий B: большой или высоковариативный ассортимент

Ключевая мысль

3. Сначала разделите факты, правила и каталоги

3.1. Что относится к company.md

3.2. Что относится к behavior.md

3.3. Что относится к pricing.md

3.4. Что относится к Knowledge

3.5. Что относится к configured prices

4. Какие документы можно передавать RED

4.1. Обычные вложения Desktop RED

4.2. Изображения

4.3. Небольшой CSV/XLSX как обычный материал

4.4. Knowledge принимает CSV/XLSX

5. Как правильно оформить CSV

5.1. Кодировки

5.2. Разделители

5.3. Первая непустая строка — заголовки

5.4. Пустые строки

5.5. Разная ширина строк

6. Как правильно оформить XLSX

6.1. Листы

6.2. Формулы

6.3. Merged cells

6.4. Один логический объект — одна понятная строка

7. Поля большого каталога

7.1. Stable ID

7.2. Название

7.3. Цена

7.4. Валюта

7.5. Единица продажи

7.6. Остальные характеристики

7.7. Технические поля

8. Маленький бизнес: как сделать просто и правильно

9. Большой каталог: что меняется

10. Sellable identity

11. Attribute и price-driving dimension

11.1. Обычный attribute

11.2. Price-driving dimension

12. Сквозной пример: лак и 300 цветов

12.1. 300 цветов, одна цена

Где хранить 300 цветов

12.2. Две ценовые группы

12.3. Каждый цвет может иметь свою цену

12.4. Серия + база + объём + класс цвета

13. Один ряд или несколько

14. Когда использовать Knowledge

15. Как Knowledge хранит данные

16. Configured prices: точный формат

CURRENCY

UNIT

PRICE_TYPE

Остальные поля

SCOPE и DEFAULT_FOR

17. Какие формы цены реально безопасны

Exact price

Цена за единицу

Цена упаковки/комплекта

«От 1000»

Диапазон 1000–1500

3.1. Что относится к `company.md`

3.2. Что относится к `behavior.md`

3.3. Что относится к `pricing.md`