Перейти до основного вмісту

ADR-007: Архітектура генерації документів

  • Статус: прийнято
  • Дата: 2026-04-16
  • Автор: CTO Agent (KALA-135)

Контекст​

Клієнтським воркфлоу потрібна переваживна генерація документів для пропозицій, листів, контрактів, інвойсів і кастомних форм. Згенеровані документи мають бути переглядними, завантажувальними і опціонально переюзовуваними RAG-системою після створення.

У платформи вже є простори імен, department-scoped бази знань, document ingestion та audit-friendly API-маршрути. Генератор документів мав лягти на ці примітиви, а не стати окремим сховищем.

Рішення​

Використовуємо двоетапну модель:

DocumentTemplate -> DocumentGeneration -> optional KnowledgeBase Document

DocumentTemplate зберігає переваживну специфікацію: namespace, категорію, тіло шаблону, змінні та дефолтний вихідний формат.

DocumentGeneration зберігає кожну render-спробу: user, input, output, status, error і опціональний outputFileId.

Коли non-preview-генерація зберігається, відрендерений вивід стає звичайним Document у базі знань. Це дозволяє згенерованим документам використовувати існуючі download-, ingestion-, chunking-, embedding- і RAG retrieval-шляхи.

Розглянуті альтернативи​

Зберігати згенеровані файли поза базою знань​

Відхилено. Окреме сховище потребує власних upload-, retention-, access-правил і не бере участі у RAG.

Генерувати лише ephemeral-прев'ю​

Відхилено. Юридичні та sales-процеси потребують довготривалої історії генерацій і завантажуваних виходів.

Спочатку зробити повноцінний Office-document template-engine​

Відхилено. Handlebars над Markdown/HTML/DOCX-текстом покриває поточні потреби й набагато простіший для аудиту. Розширені бінарні шаблони додамо пізніше.

Наслідки​

Позитивні​

  • Історія генерацій запитувана.
  • Preview та збережена генерація йдуть одним render-шляхом.
  • Збережені виходи стають knowledge-документами і можуть бути retrieved через RAG.
  • Department scope успадкований з namespace- і knowledge-base-валідації.

Негативні​

  • DOCX-експорт поки що text-block-based, а не повноцінна templating-система.
  • PDF зарезервовано, але не реалізовано.
  • Якість RAG над згенерованими документами залежить від якості source-документів і запитів.

Нотатки про реалізацію​

  • src/documents/generator.ts володіє парсингом змінних, resolve-ом, рендером та export-метаданими.
  • src/routes/document-templates.ts володіє CRUD-, generation- і generation-history-ендпоінтами.
  • Змінні можуть братися з user, rag або contractor_api.
  • Обовʼязкові відсутні змінні провалюють генерацію і зберігають помилку у generation-записі.