Перейти к основному содержимому

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

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

Контекст​

Клиентские флоу требуют повторяемой генерации документов — предложения, письма, контракты, счета, кастомные формы. Сгенерированные документы должны быть reviewable, скачиваемыми и, опционально, реиспользуемыми RAG-системой после создания.

В платформе уже были namespaces, knowledge bases уровня отдела, ingestion документов и audit-friendly API-маршруты. Document generator должен был вписаться в эти примитивы, а не становиться отдельным хранилищем.

Решение​

Использовать двухфазную модель:

DocumentTemplate -> DocumentGeneration -> optional KnowledgeBase Document

DocumentTemplate хранит переиспользуемую спецификацию: namespace, категория, body шаблона, переменные и дефолтный output-формат.

DocumentGeneration хранит каждую попытку рендеринга: user, input, output, статус, ошибку и опциональный outputFileId.

Когда non-preview генерация сохраняется, отрендеренный результат становится обычным Document в knowledge base. Это позволяет сгенерированным документам использовать существующие пути загрузки, ingestion, чанкинга, embeddings и RAG retrieval.

Рассмотренные альтернативы​

Хранить сгенерированные файлы вне knowledge base​

Отклонено. Отдельному хранилищу понадобились бы свои правила upload, persistence и доступа, и оно не участвовало бы в RAG.

Генерировать только временные preview​

Отклонено. Юридические и sales-процессы требуют durable-истории и скачиваемых результатов.

Сразу сделать полноценный office-шаблонизатор​

Отклонено. Handlebars поверх Markdown/HTML/DOCX закрывает текущие потребности и его сильно проще тестировать. Rich binary-шаблоны можно добавить позже.

Последствия​

Плюсы​

  • История генераций доступна для query.
  • Preview и сохранённая генерация используют один и тот же render-путь.
  • Сохранённые результаты становятся knowledge-документами и доступны для RAG-retrieval.
  • Department scope наследуется из проверок namespace и knowledge base.

Минусы​

  • DOCX-экспорт сейчас собирается из text-блоков, а не из полноценного document templating engine.
  • PDF зарезервирован, но не реализован.
  • Качество rag-переменных зависит от качества source-документов и запросов.

Заметки по реализации​

  • src/documents/generator.ts владеет парсингом переменных, резолвингом, рендерингом и export-метаданными.
  • src/routes/document-templates.ts владеет CRUD, генерацией и generation-history эндпоинтами.
  • Переменные могут быть source user, rag или contractor_api.
  • Обязательные отсутствующие переменные валят генерацию и сохраняют ошибку в generation-строке.