1Резюме

Менеджер поставщика открывает карточку заведения, у которого уже распарсено меню, нажимает «Создать КП», выбирает колонку прайса и получает черновик документа в визуальном редакторе. Черновик собран детерминированно: из матчинга меню на номенклатуру взяты ингредиенты, которые поставщик может закрыть, и блюда, которые заведение могло бы добавить; под каждый ингредиент подставлены до трёх товаров с ценой выбранной колонки. Менеджер правит текст и таблицы как в Word, нажимает «Скачать PDF», файл сохраняется и уходит заведению.

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

2Контекст

Проект ищет и раскладывает меню заведений HoReCa, чтобы поставщик продуктов мог предложить себя точечно: «вы готовите карбонару, у нас есть гуанчале, пекорино и паста». Раскладка блюд, матчинг на номенклатуру, импорт номенклатуры и прайса из 1С уже работают и лежат в app/core/nomenclature и app/core/onec.

Прежний блок КП был написан на раннем этапе, когда клиентом считался кейтеринг: он собирал «фуршет на 50 гостей» из блюд самого заведения и показывал ему его же еду с итоговой суммой. 4 сентября 2026 блок удалён целиком вместе с таблицами (миграция 0027), копия данных снята вне стенда. Задел для правильной версии сохранён: match_menu отдаёт покрытие по блюдам, список «уже можем поставлять» и блюда расширения, а resolve_price выбирает цену по колонке прайса.

Ответы Юлии от 27 августа задают рамку: история продаж на первом этапе не нужна, колонку прайса определяет потенциал клиента и его выбирает менеджер, в таблице товаров нужны девять колонок из её списка, итоговая сумма не нужна.

3Цели и не-цели

Цели

• Г1. Менеджер получает готовый к отправке PDF за одну сессию редактирования, не собирая таблицы руками.
• Г2. Каждая цифра и каждый товар в документе прослеживаются до данных системы: меню, раскладка, номенклатура, прайс.
• Г3. Заведение видит, что его меню прочитали: ингредиенты названы вместе с его блюдами, предложенные новые блюда соответствуют его кухне.
• Г4. Администратор меняет формулировки, реквизиты и логотип без релиза.
• Г5. Ни одна из девяти колонок прайса, кроме выбранной, не утекает в документ.

Не-цели

• Отправка предложения по почте или в мессенджер, статусы «открыто / прочитано». Экспорт заканчивается скачиванием файла.
• Предложение для заведений без распарсенного меню, только по кухне. Кнопка недоступна, пока меню нет.
• Генерация текста языковой моделью. Все тексты берутся из шаблона и профиля поставщика.
• Несколько шаблонов и их привязка к категориям клиентов. Шаблон один.
• Аналитика по составу отправленных предложений. Источник истины — HTML, см. docs/adr/0001.
• Кросс-селл «использует, но не покупает» и признак «действующий клиент». Отложено заказчиком до второго этапа.
• Формат DOCX. Зависимость python-docx остаётся в проекте, но экспорт только в PDF.

4Словарь

Полный словарь лежит в CONTEXT.md в корне репозитория. Здесь только термины, без которых текст ниже не читается.

5Сценарии

Персонажи выдуманы, заведение «Траттория Da Vinci» и все цифры в примерах условные. Сценарии показывают, как продукт ведёт себя от начала до конца; требования в разделах 7–12 на них ссылаются.

6Обзор решения

Путь предложения: карточка заведения → форма параметров → сборщик → HTML-черновик → редактор → экспорт → PDF в хранилище. Сборщик читает четыре источника: меню заведения, кэш раскладки блюд, номенклатуру с ценами 1С и настройки (профиль, шаблон).

flowchart LR
  A[Карточка заведения
есть меню] --> B[Форма: колонка прайса,
лимит товаров, поля профиля]
  B -->|POST /proposals| C[Сборщик]
  M[(menu_items +
dish_decomposition)] --> C
  N[(client_products +
onec_product_prices)] --> C
  S[(settings: профиль,
шаблон)] --> C
  C -->|контекст + блоки| T[Рендер шаблона
Jinja2 sandbox]
  T -->|санитайзер| D[(proposals.body_html
статус draft)]
  D --> E[Редактор TipTap]
  E -->|PATCH body_html| D
  E -->|POST export| P[WeasyPrint → PDF]
  P --> F[(MinIO
proposals/id/номер.pdf)]
  P -->|статус exported| D
  E -->|Пересобрать| B

Сборка выполняется синхронно в запросе API: на меню в 300 блюд она укладывается в секунды, потому что раскладка уже закэширована, а LLM не вызывается. Экспорт тоже синхронный: WeasyPrint на документе в 10 страниц работает единицы секунд. Очередь ARQ не задействуется.

7Документ PDF

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

7.1Разделы документа

8Сборка черновика

Сборка — чистая функция над снимком данных плюс тонкий слой ввода-вывода. Вход: заведение, параметры формы, снимок меню и матчинга, снимок номенклатуры с ценами, профиль, шаблон. Выход: HTML тела и JSON-снимок входов для отладки.

8.1Предусловия

8.2Счётчики вступления

Считаются из результата match_menu по блюдам без напитков (фильтр is_drink, как в _compute_match).

8.3Блок «Поставляем сейчас»

1. Из dishes[].ingredients[] собираем множество закрытых ингредиентов и для каждого список блюд, где он встречается (по названию блюда, без дублей).
2. Для каждого ингредиента отбираем товары по правилу 8.5 с лимитом из формы.
3. Ингредиенты без товаров с ценой отбрасываем.
4. Сортировка ингредиентов: сначала основные (вес 1.0), потом второстепенные (0.4); внутри группы по числу блюд убыв., затем по числу товаров в номенклатуре убыв., затем по алфавиту.
5. Строка «В ваших блюдах»: первые 5 названий в порядке появления в меню, дальше «и ещё N».

8.4Блок «Расширение меню»

1. Берём upsell[] из результата матчинга (до 8 блюд топ-кухни, которых нет в меню, с покрытием ≥ 0,6).
2. Для каждого закрытого ингредиента блюда отбираем один товар по правилу 8.5 с лимитом 1.
3. Блюдо остаётся, если нашлось не меньше двух товаров. Порядок как в матчинге (по доле покрытия).
4. Если после фильтра блюд не осталось или кухня не определена, блок не печатается целиком, включая заголовок и вводную фразу.

8.5Отбор товаров под ингредиент

Кандидаты: товары, у которых ingredient_canonical относится к ингредиенту по тем же правилам, что Index.classify: точное совпадение, семейство по первому слову, подстрока. Каждому кандидату резолвим цену через resolve_price с выбранной колонкой.

8.6Ячейки таблицы товаров

8.7Прочие поля

• Номер. Глобальная последовательность Postgres proposal_number_seq; номер «КП-{ГГГГ}-{NNNN}», где NNNN — значение последовательности с ведущими нулями до четырёх знаков. Последовательность по годам не сбрасывается: уникальность важнее красоты.
• Дата. Дата сборки в часовом поясе стенда, формат «ДД.ММ.ГГГГ».
• Действительно до. Дата сборки плюс validity_days из формы.
• Логотип. Файл из профиля читается из MinIO и встраивается в HTML как data:-URI, чтобы редактор и PDF не ходили в сеть. Лимит файла 300 КБ, форматы PNG, JPEG, SVG.
• Снимок сборки. В build_snapshot пишутся: параметры формы, счётчики, список ингредиентов с идентификаторами выбранных товаров и причинами цены, идентификатор контрагента, версия шаблона (хеш) и профиля. Это отладочная информация, не источник истины.

9Шаблон и плейсхолдеры

Шаблон — HTML с плейсхолдерами Jinja2, который администратор редактирует в том же визуальном редакторе, что и менеджер черновик. Скалярные плейсхолдеры подставляются с экранированием, блочные заменяются готовым HTML. Блочный плейсхолдер должен стоять в отдельном абзаце: рендерер заменяет весь абзац целиком.

9.1Скалярные плейсхолдеры

9.2Блочные плейсхолдеры

9.3Валидация шаблона

• Рендер через jinja2.sandbox.SandboxedEnvironment с autoescape=True и undefined=StrictUndefined: неизвестный плейсхолдер — ошибка с именем и позицией.
• При сохранении шаблон прогоняется на тестовом контексте (все поля заполнены условными значениями). Ошибка синтаксиса или неизвестного имени возвращается как 422 с сообщением, шаблон не сохраняется.
• Обязательных плейсхолдеров нет: администратор вправе убрать любой блок. Предупреждение в UI, если отсутствуют block.supply или manager.phone.
• Шаблон по умолчанию лежит в файле backend/app/templates/proposal_default.html (заменяет старый файл с тем же именем). Кнопка «Вернуть стандартный» удаляет ключ настройки, и система снова читает файл.

10Экраны

10.1Карточка заведения

10.2Форма «Новое предложение»

Модальное окно поверх карточки. Открывается кнопкой «Создать КП» и кнопкой «Пересобрать» в редакторе (во втором случае поля предзаполнены параметрами исходного предложения).

Под полями форма показывает предварительный расчёт из GET /proposals/preflight: «64 блюда, под 49 есть продукты, 31 ингредиент, 87 товаров с ценой по этой колонке». Расчёт обновляется при смене колонки. Если товаров с ценой ноль, кнопка «Собрать» остаётся активной, но выводится предупреждение «По этой колонке цен нет: таблицы будут пустыми».

10.3Редактор предложения

Макет редактора: панель инструментов, холст шириной A4, статус сохранения. Таблица в макете сокращена до четырёх колонок ради ширины.

10.4Список предложений

Маршрут /proposals, пункт «КП» в главном меню. Таблица: номер, заведение, статус, колонка прайса, создано (кто, когда), экспортировано. Фильтры: статус, поиск по номеру и названию заведения. Сортировка по дате создания убыв. Пагинация по 50. Строка ведёт в редактор; для экспортированных дополнительно ссылка «PDF».

10.5Настройки: профиль и шаблон

Маршрут /settings/proposal, доступен только admin, ссылка со страницы «Настройки». Две вкладки.

• Профиль поставщика. Форма с полями из 11.2, поля «о компании» и «условия» в том же визуальном редакторе без таблиц. Загрузка логотипа с превью и кнопкой «Удалить логотип». Кнопка «Сохранить».
• Шаблон. Визуальный редактор с шаблоном, справа панель «Плейсхолдеры» со списком из 9.1–9.2 и кнопкой «Вставить». Кнопки «Сохранить» (с валидацией 9.3), «Предпросмотр на примере» (выбор заведения с меню, рендер в модальном окне), «Вернуть стандартный» (с подтверждением).

10.6Роли

11Данные

11.1Таблица proposals

Миграция 0028_proposals_v2. Тип proposal_status был удалён в 0027, создаётся заново с новыми значениями.

Индексы: organization_id, status, created_at desc. Последовательность proposal_number_seq создаётся в той же миграции. Downgrade удаляет таблицу, тип и последовательность.

11.2Настройки

Хранятся в существующей таблице settings как JSON, читаются и пишутся через новые эндпоинты (раздел 12), а не через общий PUT /settings, потому что нужна валидация.

11.3Хранилище файлов

• Логотип: proposal/logo/{uuid}.{ext}. При замене старый объект удаляется.
• PDF: proposals/{proposal_id}/{number}.pdf, content-type application/pdf. При удалении предложения объект удаляется. При удалении заведения записи каскадно исчезают, файлы остаются сиротами: чистка сирот вне охвата, отмечено в разделе 19.

12API

Префикс /proposals, роутер app/api/proposals.py, подключается в main.py. Ошибки в формате остальных роутеров: {"detail": "..."}, для машинно-различимых случаев поле code.

Дополнение к существующему API: GET /organizations/{id} отдаёт menu_items_count и proposals_count, чтобы карточка знала, активна ли кнопка, без второго запроса.

13Модули и код

Принцип тот же, что в matching_core и onec/pricing: чистое ядро без БД, тонкий слой ввода-вывода, тесты на ядро без Postgres.

Зависимости

• Backend: nh3 добавить в pyproject.toml. weasyprint, jinja2, minio, pypdfium2 уже есть.
• Frontend: @tiptap/react, @tiptap/pm, @tiptap/starter-kit, @tiptap/extension-table, @tiptap/extension-table-row, @tiptap/extension-table-header, @tiptap/extension-table-cell, @tiptap/extension-image, @tiptap/extension-text-align, @tiptap/extension-underline, @tiptap/extension-link. Одна мажорная версия (2.x) для всех пакетов, версии закрепить точно.
• Docker: в backend/Dockerfile добавить fonts-liberation и fonts-dejavu-core; сейчас установлен только pango, и кириллица в PDF не гарантирована.

14Безопасность

15Нефункциональные требования

16Крайние случаи и ошибки

17Тестирование и приёмка

17.1Автотесты

Тесты в проекте не поднимают Postgres (tests/conftest.py), поэтому основная нагрузка на чистое ядро.

17.2Критерии приёмки

1. Дано заведение с распарсенным меню и выбранная колонка прайса, когда менеджер собирает КП, тогда черновик открывается в редакторе, в нём есть все разделы ДОК-01…ДОК-11, каждый ингредиент сопровождается названиями блюд из меню этого заведения, а в таблицах ровно девять колонок.
2. Дано тот же черновик, когда менеджер удаляет строку таблицы и меняет абзац, а затем скачивает PDF, тогда в PDF нет удалённой строки и есть новый текст, статус «Экспортировано», файл виден в списке.
3. Дано экспортированное предложение, когда менеджер пересобирает, тогда появляется новое предложение с новым номером, старое не изменилось.
4. Дано заведение без меню, тогда кнопка недоступна, а прямой вызов API возвращает 409.
5. Дано форма без колонки прайса, тогда кнопка «Собрать» недоступна, API возвращает 422.
6. Дано администратор изменил шаблон и профиль, когда менеджер собирает новое КП, тогда изменения видны, а старые черновики прежние.
7. Дано любой собранный документ, тогда поиском по HTML и PDF не находится ни одно название колонки прайса и слово «Итого».
8. Дано три реальных заведения из списка заказчика, тогда владелец проекта подтверждает, что документ выглядит как предложение поставщика продуктов и его можно отправить без переделки структуры.

17.3Ручной чек-лист перед сдачей

• PDF открывается в Acrobat, Chrome и Preview; кириллица, знак ₽, длинные названия товаров переносятся, таблица не выходит за поля.
• Редактор: таблица с 9 колонками помещается в холст, добавление и удаление строк, отмена, вставка текста из Word не приносит мусорных стилей.
• Тёмная тема интерфейса: холст редактора остаётся белым, как бумага.
• Роль viewer: редактор только для чтения, кнопок изменения нет, скачать PDF можно.

18План работ

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

Этапы 1–3 не зависят от фронта и могут идти параллельно с этапом 4, если разработчиков двое.

19Открытые вопросы

20Отвергнутые пути

• Структурированный состав с галочками (как в удалённой версии). Отвергнут: менеджер хочет свободно править формулировки и таблицы. Зафиксировано в docs/adr/0001.
• Текст от языковой модели во вступлении. Отвергнут владельцем: детерминизм и предсказуемость важнее, к тому же документ должен быть одинаково хорош при недоступности LLM.
• Предложение по кухне без меню. Отвергнуто: без меню персонализация превращается в общий прайс.
• Markdown-редактор. Отвергнут: таблицы с девятью колонками в Markdown править неудобно.
• Колонка прайса по умолчанию из настроек. Отложено до ответа заказчика: неверная колонка в документе хуже, чем лишний клик в форме.
• Ограничение объёма документа двумя страницами. Отвергнуто владельцем: пусть длина определяется меню, лимит регулируется числом товаров на ингредиент.
• Асинхронная сборка через ARQ. Не нужна: сборка укладывается в секунды, а очередь усложнила бы форму ожиданием и опросом.

21Источники

Структура документа опирается на практики ниже: сценарии, не-цели, открытые вопросы и оговорка из «Painless Functional Specifications»; резюме, контекст, границы, подход и удвоенная оценка из «минимально жизнеспособного» дизайн-документа; измеримые формулировки и словарь из руководств по SRS. Порядок разделов PDF взят из русских руководств по коммерческим предложениям.

• Joel Spolsky. Painless Functional Specifications, Part 2: What's a Spec?
• Joel Spolsky. Painless Functional Specifications, Part 4: Tips
• Writing «minimum viable» technical design documents
• Perforce. How to Write a Software Requirements Specification
• Archbee. How to Write a Technical Specification Document
• Software Documentation Best Practices for 2025
• Яндекс.Бизнес. Коммерческое предложение: что это и как составить
• УБРиР. Как составить коммерческое предложение
• Битрикс24. Как создать эффективное коммерческое предложение
• SendPulse. Коммерческое предложение: структура и оформление
• Offorte. Food supplier proposal template