Шаблоны документов

Шаблоны документов превращают Handlebars-шаблоны, привязанные к namespace, в сгенерированные документы. Используются для предложений, писем, счетов, контрактов и других деловых документов, которым нужны данные от пользователя, RAG или API подрядчиков.

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

Фичу составляют две Prisma-модели:

Модель	Роль
DocumentTemplate	Спецификация переиспользуемого шаблона: namespace, отдел, категория, тело, переменные, формат вывода по умолчанию.
DocumentGeneration	Одна попытка рендеринга: пользовательский ввод, отрендеренный результат, статус, ошибка, опциональный сохранённый output file.

Шаблоны принадлежат Namespace. Поле departmentId в строке шаблона необязательное, но валидация namespace следит, чтобы оно совпадало с отделом namespace, если указано.

Тело шаблона

templateBody рендерится через Handlebars:

# Proposal for {{clientName}}

Scope:
{{scopeSummary}}

Total: {{amount}}

HTML-вывод использует Handlebars-экранирование. Markdown и DOCX используют noEscape, чтобы юридический текст, списки и отформатированные пункты оставались нетронутыми.

Переменные

Переменные хранятся как JSON в поле variables. Каждая переменная может задавать:

Поле	Значение
name	Ключ Handlebars (обязательно).
type	string, number, boolean, date, object или array.
required	Падает ли генерация при отсутствии значения.
source	user, rag или contractor_api.
description	Понятное человеку объяснение для форм и ревьюеров.
query	Опциональный шаблон RAG-запроса. Может ссылаться на предыдущие переменные.
default / fallback	Опциональное значение, которое используется до падения при ошибке резолвера.

Пример:

[
  {
    "name": "clientName",
    "type": "string",
    "required": true,
    "source": "user",
    "description": "Legal client name"
  },
  {
    "name": "scopeSummary",
    "type": "string",
    "required": true,
    "source": "rag",
    "query": "Summarize active contract scope for {{clientName}}"
  },
  {
    "name": "edrpou",
    "type": "string",
    "source": "contractor_api",
    "fallback": "unknown"
  }
]

Источники переменных

Переменные с source: user читаются из payload input.

Переменные с source: rag резолвятся запуском query, description или name по данным уровня отдела. Дефолтный резолвер использует PostgreSQL полнотекстовый поиск по готовым чанкам и возвращает топ-совпадения. Для тестов или более богатого RAG можно подставить кастомный резолвер.

Переменные с source: contractor_api резолвятся через опциональный contractor-API резолвер. Если резолвер не настроен, а переменная required, генерация падает с VariableSourceUnavailableError. Если переменная не required — значение становится пустой строкой (или default/fallback, если заданы).

Поток генерации

Эндпоинт:

POST /api/v1/document-templates/:id/generate

Тело запроса:

{
  "input": {
    "clientName": "Acme Corp",
    "amount": 120000
  },
  "preview": false,
  "outputFormat": "docx",
  "saveToKnowledgeBaseId": "clx..."
}

Процесс:

1. загрузить шаблон в рамках department scope вызывающего;
2. создать строку DocumentGeneration со статусом pending;
3. распарсить и провалидировать переменные;
4. подставить user-значения из input;
5. резолвить дефолты, RAG-переменные и contractor API переменные;
6. привести значения к объявленным типам;
7. отрендерить templateBody через Handlebars;
8. экспортировать результат в Markdown, HTML или DOCX (с метаданными);
9. если не preview — сохранить результат как документ в базе знаний;
10. пометить генерацию ready, либо сохранить ошибку и пометить failed.

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

Форматы вывода

Поддерживаемые форматы: md, html, docx и pdf.

Формат	Поведение
md	Возвращает inline Markdown с mime text/markdown.
html	Возвращает inline HTML с mime text/html.
docx	Собирает DOCX-файл из отрендеренных текстовых блоков и возвращает экспорт в Base64.
pdf	Заявлен в enum, но сейчас падает с UnsupportedDocumentExportError.

Если outputFormat не указан в запросе — используется outputFormat из шаблона.

Хранение и загрузка

История генераций хранится в document_generations, читается через:

GET /api/v1/document-generations
GET /api/v1/document-generations/:id

При preview: true сгенерированный результат не сохраняется как документ базы знаний, outputFileId остаётся null.

При preview: false и заданном saveToKnowledgeBaseId результат сохраняется как Document в целевой базе знаний. У документа будет сгенерированное имя файла, MIME-тип, формат вывода и статус ready — все стандартные knowledge document API могут его скачивать и использовать дальше. В строке генерации сохранённый document id пишется в outputFileId.

Права

Создание, обновление и удаление шаблонов требуют прав на управление шаблонами. Для генерации нужны права на создание документов и доступ к отделу namespace шаблона. Не-глобальные пользователи не могут генерировать из шаблона за пределами своего эффективного department scope.

Операционные заметки

• Делайте шаблоны достаточно компактными для ревью. API отклоняет тела длиннее 250 000 символов.
• Для предложений с доказательной базой лучше использовать rag-переменные, чем копировать большие куски политики прямо в шаблон.
• Используйте preview: true для проверки черновика и preview: false только когда результат должен попасть в историю знаний.
• Удерживайте уведомление document_ready, когда non-preview генерация создаёт файл, который пользователю нужно скачать.