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

Шаблони документів рендерять Handlebars-шаблони, привʼязані до простору імен, у згенеровані документи. Використовуються для пропозицій, листів, інвойсів, контрактів та кастомних бізнес-документів, яким потрібні дані від користувача, RAG або контрактних API.

Модель даних

Фічу складають дві Prisma-моделі:

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

Шаблони належать Namespace. departmentId у рядку шаблону опційний, але валідація простору імен тримає його узгодженим із відділом простору імен, коли він заданий.

Тіло шаблону

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

# Proposal for {{clientName}}

Scope:
{{scopeSummary}}

Total: {{amount}}

HTML-вивід використовує дефолтне екранування Handlebars. Markdown і DOCX-вивід використовують noEscape, щоб юридичний текст, bullet-и та преформатовані клаузули лишались недоторканими.

Змінні

Змінні зберігаються як JSON у полі variables. Кожна змінна може задавати:

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

Приклад:

[
  {
    "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"
  }
]

Джерела змінних

user-змінні беруться з input payload-у генерації.

rag-змінні резолвляться запуском query, description або name проти знань відділу. Дефолтний resolver використовує PostgreSQL full-text search по готових чанках і повертає фрагменти з найвищим матчем. Кастомний resolver можна інʼєктувати для тестів або багатшої RAG.

contractor_api-змінні обробляються через опційний resolver contractor-API. Якщо resolver не інʼєктовано, а змінна required — генерація падає з VariableSourceUnavailableError. Якщо змінна опційна — значення стає порожнім рядком, коли нема default або fallback.

Воркфлоу генерації

Ендпоінт:

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

Тіло запиту:

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

Flow:

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

Відсутні обовʼязкові user-змінні падають до рендеру. Некоректні числа, boolean, дати, масиви чи обʼєкти падають до повернення результату.

Вихідні формати

Підтримувані значення формату: md, html, docx, pdf.

Формат	Поведінка
md	Повертає inline Markdown з метаданими text/markdown.
html	Повертає відрендерений inline HTML з метаданими 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 дозволяє стандартним API бази знань підхопити його на завантаження та подальший ingestion. DocumentGeneration-рядок зберігає ID збереженого документа в полі outputFileId.

Дозволи

Створення, оновлення та видалення шаблонів вимагає дозволів керування шаблонами. Генерація документів вимагає дозволу на генерацію та доступу за department scope до простору імен шаблону. Неглобальні користувачі не можуть генерувати з шаблонів поза своїм ефективним scope.

Операційні нотатки

• Тримайте шаблони достатньо малими для перегляду. API відхиляє тіла понад 250 000 символів.
• Віддавайте перевагу rag-змінним для пунктів, підкріплених джерелами, замість копіювання великих policy-текстів у шаблон.
• Використовуйте preview: true для превʼю чернетки, а preview: false — лише коли результат має стати частиною історії знань.
• Тримайте document_ready-сповіщення, коли не-preview генерація створює вихідний файл, який користувач має завантажити.