Гендок — техническое задание на MVP

Развёрнутое ТЗ по краткому заданию заказчика: что именно будет сделано за 14 дней, как это устроено внутри и по каким признакам принимается каждый этап.

1. Цель и границы MVP
2. Роли и сценарии
3. Страницы и маршруты
4. Модель данных
5. Мастер документа
6. ИИ-слой
7. Шаблоны, DOCX и PDF
8. Дела, сроки, напоминания
9. Вход и аккаунт
10. Оплата
11. Админка
12. Публичная часть и SEO
13. Уведомления
14. Инфраструктура
15. Нефункциональные требования
16. Этапы, приёмка, цена
17. Риски и вопросы

1Цель и границы MVP

Гендок — веб-сервис для людей без юридической подготовки. Человек описывает ситуацию своими словами или выбирает её в каталоге, отвечает на 5–10 вопросов и получает готовый документ: претензию, заявление, жалобу или обращение. Дальше сервис ведёт «дело»: помнит дату отправки и контрольный срок, напоминает о нём и предлагает следующий документ, если ответа нет.

Результат MVP — работающий на сервере заказчика сервис, в котором весь этот путь проходится без участия разработчика, а ситуации, шаблоны, анкеты, промпты, модели и тарифы меняются из админки.

Входит

• Публичная часть: главная, каталог ситуаций, страница ситуации, заготовка блога, оферта, политика обработки персональных данных.
• Мастер документа: текст или каталог → анкета → предпросмотр и правка → скачивание DOCX и PDF.
• ИИ-слой с несколькими провайдерами, приоритетами, повторами, автопереключением на резерв, учётом расходов и промптами в админке.
• Генерация DOCX по шаблонам с переменными и условными блоками, PDF из того же шаблона.
• Личный кабинет: дела, статусы, сроки; вход по коду из письма и через Telegram.
• Уведомления по e-mail и через Telegram-бота.
• Оплата через ЮKassa: карта и СБП, разовая покупка и подписка, бесплатные лимиты.
• Админка на Filament: ситуации, шаблоны, анкеты, промпты, модели ИИ, тарифы, пользователи, дела, журнал запросов к ИИ, SEO-поля.
• Инфраструктура: Docker Compose, деплой на сервер заказчика, бэкапы, Яндекс Метрика с целями.

Не входит

Мобильные приложения, бот в MAX, проверка документа живым юристом, сложный визуальный редактор шаблонов. Архитектура не мешает добавить их позже: бот в MAX — ещё один канал уведомлений, проверка юристом — ещё один статус документа.

Допущения

• Тексты шаблонов, анкеты и ссылки на нормы права готовит заказчик. В смету входит заведение до 10 ситуаций по этим материалам, остальные заводятся через админку без разработчика.
• Дизайн — аккуратный типовой на основе демо, без отдельного этапа макетов. Если у заказчика есть макеты, вёрстка идёт по ним.
• Ключи YandexGPT и GigaChat, магазин ЮKassa, бот Telegram, почтовый сервис, сервер и домен — на аккаунтах заказчика.

2Роли и сценарии

Основной сценарий

1. Человек пишет «магазин не возвращает деньги за сломанный пылесос» или открывает страницу ситуации из поиска.
2. Сервис определяет ситуацию и документ, показывает, что понял, и даёт поправить выбор.
3. Анкета на 5–10 вопросов. То, что удалось извлечь из текста, уже заполнено и подсвечено.
4. Документ собирается: реквизиты и нормы — из шаблона, описание обстоятельств — от ИИ. Сервис проверяет обязательные реквизиты и показывает, чего не хватает.
5. Предпросмотр, правка текста в браузере.
6. Скачивание DOCX и PDF: бесплатно в пределах лимита или после оплаты.
7. В кабинете появляется дело. Человек отмечает дату отправки, сервис считает контрольный срок.
8. Напоминания приходят на почту и в Telegram. По кнопке «ответ не пришёл» сервис предлагает следующий документ и переносит в него уже известные данные.

3Страницы и маршруты

4Модель данных

PostgreSQL 16. У сущностей, общих для будущих сервисов, есть поле service_id: Гендок — первая запись в таблице сервисов.

5Мастер документа

Состояния

черновик → ситуация определена → анкета → сборка → готов → скачан. Каждое состояние сохраняется: вкладку можно закрыть и вернуться по ссылке или из кабинета.

Анкета

• Типы полей: строка, текст, дата, сумма, выбор из списка, да/нет, телефон, адрес, ФИО.
• Условия показа: вопрос появляется в зависимости от предыдущих ответов (например, «дата экспертизы» только при ответе «да» на «проводилась ли экспертиза»).
• Проверка на клиенте и на сервере: обязательность, формат, дата не в будущем, сумма больше нуля.
• Данные из профиля (ФИО, адрес, телефон) подставляются сами.
• Значения, извлечённые ИИ из текста, подсвечены и помечены «проверьте».

Проверка реквизитов

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

Правка в браузере

Документ хранится как набор блоков: шапка, заголовок, абзацы, требования, подпись. Реквизиты меняются через анкету, текст абзацев — прямо в предпросмотре. Правки сохраняются как блоки, поэтому DOCX и PDF всегда собираются из актуального текста, а не из HTML. Кнопка «Собрать заново» возвращает текст модели.

Сборка без блокировки

Обращение к ИИ и сборка файлов идут в очереди. Страница опрашивает статус раз в секунду и показывает, что происходит: «определяем ситуацию», «пишем текст», «собираем файл». Запросы пользователей не занимают PHP-процессы на время ответа нейросети.

6ИИ-слой

Единый интерфейс

interface LlmDriver {
    public function complete(LlmRequest $request): LlmResponse;
}
// YandexGptDriver, GigaChatDriver, OpenAiCompatibleDriver

Резерв подключается через OpenAiCompatibleDriver: адрес, ключ и название модели задаются в админке, поэтому смена резервного провайдера не требует правки кода. Особенности провайдеров спрятаны в драйверах: у GigaChat токен доступа живёт 30 минут и кешируется в Redis, в контейнер ставятся сертификаты Минцифры; у YandexGPT — ключ сервисного аккаунта и идентификатор каталога.

Задачи

Цепочка и автопереключение

1. Задача берёт из админки список включённых моделей по приоритету.
2. Модель, у которой сработал предохранитель, пропускается.
3. Запрос уходит с таймаутом 20 секунд (5 секунд на соединение).
4. Ошибка 5xx, 429 или обрыв сети — один повтор через 1–2 секунды. Таймаут — без повтора, сразу следующая модель.
5. Ответ проверяется по JSON-схеме. Не прошёл — один повторный запрос с просьбой исправить формат, затем следующая модель.
6. Три сбоя модели за 5 минут — предохранитель выключает её на 5 минут, потом пропускает один пробный запрос.
7. Каждая попытка пишется в журнал: модель, статус, время, токены, стоимость.
8. Общий бюджет на запрос пользователя — 45 секунд. Если не ответила ни одна модель:
   • определение ситуации — поиск по ключевым словам и каталог;
   • текст обстоятельств — документ собирается по шаблону с перечислением ответов анкеты, задача возвращается в очередь с паузами 1, 5 и 15 минут, улучшенный текст приходит пользователю уведомлением.

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

Журнал и расходы

• Экран в админке с фильтрами по задаче, модели, статусу и дате; из записи видно всю цепочку попыток.
• Виджеты: расход за день и месяц, доля отказов, среднее время ответа по моделям.
• Дневной лимит расхода на модель; при превышении модель выключается, владельцу приходит сообщение в Telegram.
• Тексты запросов и ответов хранятся обезличенными 30 дней, затем удаляются; счётчики остаются.

Защита

• Перед отправкой в модель ФИО, адрес, телефон и другие поля с признаком персональных данных заменяются метками ([ФИО], [АДРЕС]) и подставляются обратно уже на сервере.
• Текст пользователя передаётся как данные, отдельно от инструкции; длина ограничена 3000 знаками.
• Ответ модели не попадает в документ без проверки по схеме и очистки от разметки.
• Ограничение частоты: для гостя — 5 сборок в час с одного адреса, дальше вход или капча.

7Шаблоны, DOCX и PDF

• Шаблон — обычный файл DOCX, который редактор готовит в Word и загружает в админке. Переменные: ${fio}, ${sum}. Условные блоки: ${expertiza}…${/expertiza}. Повторяющиеся строки таблиц — через клонирование строки. Обработка — PhpWord TemplateProcessor.
• При загрузке сервис показывает найденные переменные и сверяет их с анкетой: переменная без вопроса и вопрос без переменной видны сразу.
• Шаблоны версионируются. Документ помнит версию, по которой собран; новая версия не меняет старые документы.
• Вычисляемые поля: сумма прописью, дата в нужном формате, ФИО в родительном падеже и инициалы, число дней просрочки, неустойка по формуле из настроек ситуации.
• PDF делает Gotenberg из того же DOCX, поэтому оба файла совпадают. В контейнер ставятся шрифты, совместимые по метрикам с Times New Roman, чтобы вёрстка не «плыла».
• Файлы лежат в закрытом хранилище и отдаются по подписанной ссылке после проверки прав и лимита.
• Сборка идёт в очереди docs, цель — до 5 секунд на документ.

8Дела, сроки, напоминания

Статусы дела

документ готов → отправлено, ждём ответа → срок истёк → ответ получен (удовлетворено / отказ / частично) → закрыто. Из «срок истёк» и «отказ» доступен переход к следующему документу.

Контрольный срок

У ситуации задано число дней и способ счёта — календарные или рабочие. Срок считается от даты отправки, которую отмечает пользователь. Рабочие дни считаются по производственному календарю из таблицы holidays; календарь обновляется раз в год и правится в админке.

Напоминания

• За 3 дня до срока, в день срока и на следующий день с вопросом «ответ пришёл?». Набор и тексты настраиваются.
• Планировщик раз в 10 минут выбирает наступившие напоминания и ставит их в очередь notify. У напоминания уникальный ключ «дело + тип», повторной отправки не будет.
• Отправка с 9 до 21 часа по времени пользователя.
• Кнопки «Ответ пришёл» и «Не пришёл» работают прямо из письма (подписанная ссылка) и из Telegram (кнопки под сообщением), входить в кабинет не нужно.

Следующий шаг

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

9Вход и аккаунт

• Код из письма: 6 цифр, живёт 10 минут, 5 попыток, повторная отправка через 60 секунд, ограничение по адресу и по e-mail. В базе хранится хеш кода.
• Telegram: кнопка входа на сайте с проверкой подписи токеном бота; отдельная ссылка на бота привязывает чат для уведомлений к существующему аккаунту.
• Сессия на 30 дней, список активных сессий и выход со всех устройств.
• Профиль: ФИО, адрес, телефон, каналы уведомлений, часовой пояс.
• Согласие на обработку персональных данных — отдельная галочка, в базе фиксируются версия текста и время.
• Удаление аккаунта вместе с делами и файлами — кнопкой в профиле.

10Оплата

• Тарифы в админке: бесплатный лимит, цена одного документа, цена подписки и её период.
• Платёж создаётся в ЮKassa с ключом идемпотентности, пользователь платит картой или через СБП на стороне ЮKassa.
• Доступ открывается по входящему уведомлению payment.succeeded. Уведомление проверяется встречным запросом статуса платежа; повторное уведомление ничего не начисляет дважды.
• Если уведомление не дошло, планировщик раз в 5 минут сверяет незавершённые платежи.
• Чеки по 54-ФЗ формируются через ЮKassa: в платёж передаются позиция, e-mail покупателя и ставка НДС из настроек.
• Подписка: при первой оплате сохраняется способ оплаты, продление списывает планировщик. Отмена — одной кнопкой в кабинете, доступ остаётся до конца оплаченного периода. Три неудачных списания подряд — подписка останавливается, пользователь получает письмо.
• Возврат — из админки, полностью или частично.
• Скачивание проверяет остаток в entitlements и списывает его. Повторное скачивание того же документа бесплатно.

11Админка

Одна панель Filament на все будущие сервисы. Общее ядро — пользователи, роли, платежи, ИИ-слой, уведомления, журнал — отделено от модуля «Гендок». Новый сервис добавляет свой модуль и группу в меню, а не вторую админку.

Роли: владелец, редактор, поддержка. Вход в админку — с двухфакторной проверкой. Изменения ситуаций, шаблонов, промптов и тарифов пишутся в журнал действий: кто, что и когда поменял.

12Публичная часть и SEO

• Страницы отдаются сервером (Blade), без JS-фреймворков. Скрипты — модули ES6, стили — SCSS по БЭМ, сборка Vite.
• У каждой ситуации: title, description, H1, slug, текст, блок вопросов и ответов, canonical, разметка для соцсетей.
• Микроразметка: хлебные крошки и вопросы-ответы.
• sitemap.xml и robots.txt собираются автоматически; черновики и служебные страницы закрыты от индексации.
• Кеш публичных страниц, изображения в современных форматах с отложенной загрузкой. Цель — основной контент на телефоне быстрее 2,5 секунды.
• Вёрстка от 360 пикселей по ширине, анкета удобна с телефона.

13Уведомления

• Каналы — e-mail и Telegram-бот за общим интерфейсом; третий канал добавляется одним классом.
• События: код входа, документ готов, улучшенный текст готов, напоминание о сроке, вопрос об ответе, оплата прошла, подписка продлена или остановлена.
• Тексты правятся в админке, в них работают переменные дела.
• Бот: привязка по ссылке, список дел, кнопки ответа под напоминанием, отписка.
• Почта: домен заказчика с настроенными SPF, DKIM и DMARC, ссылка отписки в каждом письме.
• Каждая отправка записывается со статусом; ошибка доставки в одном канале не мешает другому.

14Инфраструктура

nginx       раздача статики, HTTPS
app         PHP 8.3-FPM, Laravel 12
horizon     очереди: ai, docs, notify, default
scheduler   напоминания, сверка платежей, продление подписок
postgres    PostgreSQL 16
redis       очереди, кеш, предохранители моделей
gotenberg   DOCX → PDF

• Два окружения на сервере заказчика: тестовое для приёмки этапов и боевое. Сервер — в России.
• Минимум для сервера: 2 ядра, 4 ГБ памяти, 40 ГБ диска.
• Деплой одной командой: сборка образа, миграции, перезапуск очередей без потери задач.
• Бэкапы: дамп базы и файлы каждую ночь, хранятся 14 дневных и 8 недельных копий во внешнем хранилище заказчика. Восстановление проверяется на тестовом окружении и описано в README.
• Наблюдение: панель Horizon, сообщение владельцу в Telegram при упавшей задаче или недоступной модели, ротация логов.
• Секреты — только в .env на сервере, в репозитории их нет.
• Яндекс Метрика, цели: выбрана ситуация, начата анкета, анкета завершена, документ собран, скачан DOCX, скачан PDF, начата оплата, оплата прошла, регистрация, документ отмечен отправленным, получен ответ, создан следующий документ.

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

16Этапы, приёмка, цена

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

Что нужно от заказчика

17Риски и вопросы

Вопросы к заказчику

1. Сколько ситуаций должно быть на запуске и готовы ли для них шаблоны и анкеты?
2. Какой провайдер будет резервным? Если он за пределами России — подтвердите, что ему можно отправлять обезличенный текст.
3. Что именно платно: скачивание, сборка или количество дел? Какой бесплатный лимит?
4. Есть ли юрлицо или ИП с подключённой ЮKassa, какая система налогообложения для чеков?
5. Нужна ли подписка с автосписанием через СБП или достаточно карт?
6. Есть ли макеты или фирменный стиль? Если нет — делаю в духе демо.
7. Где живёт репозиторий и нужен ли автоматический деплой по коммиту?
8. Какие характеристики у сервера и будет ли на нём что-то ещё?
9. Сколько хранить документы и дела после закрытия?
10. Какие сервисы появятся на общей админке следующими — чтобы заранее разделить ядро правильно.