Documents

Назначение

Сервис управления документами в мультитенантных пространствах (spaces). Обеспечивает полный жизненный цикл документов: создание, иерархическая деревевидная организация, избранное, soft/hard удаление, дублирование, перемещение, автоматическое создание при создании пространства.

Порты

• HTTP: 8093
• БД: documents_db

Ключевые возможности

• CRUD документов с иерархической деревевидной структурой (parent_id — self-referential FK)
• Типы документов: wysiwyg (по умолчанию), markdown, case-diagram, custom
• Tree endpoint: вложенная JSON-структура всех документов
• Breadcrumb path при получении одного документа (путь от корня)
• Soft delete (с deleted_at timestamp) + hard delete (каскадно с дочерними)
• Восстановление soft-deleted документов
• Дублирование с автогенерацией имён: "Name (1)", "Name (2)"
• Перемещение между родителями (или в корень)
• Избранное: per-user, per-space, уникальный constraint (user_id, document_id)
• Event-driven: подписка на spaces.created-with-user-creation → автосоздание дефолтного документа
• HTTP event endpoint: POST /api/v1/events для внешних событий
• Аутентификация: JWT Bearer + app-user-id + app-space-id headers

Required Headers (все /api/v1 endpoints)

Header	Описание
app-user-id	UUID пользователя
app-space-id	UUID пространства
Authorization	Bearer <JWT token>

Mindmap-документы (type: case-diagram)

Документы с type = "case-diagram" рендерятся в Notes как майнд-карты (MindMup-подобный редактор), а не как TipTap-текст. Тело документа (body) — JSON структуры:

{
  "version": 1,
  "root": {
    "id": "uuid", "text": "Корень",
    "children": [
      { "id": "uuid", "text": "Ветка", "collapsed": false,
        "style": { "color": "blue", "priority": 1, "icon": "lucideFlag" },
        "note": "заметка узла", "children": [] }
    ]
  },
  "links": [ { "id": "uuid", "from": "uuid", "to": "uuid", "label": "связь" } ]
}

• children — дерево веток; links — произвольные связи между узлами (не часть дерева, рисуются пунктиром).
• Узел может нести ref: { kind, id } — ссылку на сущность платформы (command, flow, env, service, ai_provider, document); зарезервировано для графов зависимостей.
• Экспорт/импорт — Mermaid mindmap; кросс-связи сохраняются в хвостовом блоке %% link: <узел> -> <узel> [| метка] и восстанавливаются при импорте.

Реалтайм: совместное редактирование идёт поверх Centrifugo-канала documents:mindmap:<documentId> (Yjs, namespace documents, client publish включён). Текстовые документы используют соседний канал documents:doc:<id> — форматы состояния разные и не пересекаются.

Сохранение: тот же PATCH /documents/{spaceId}/{id}; клиент дебаунсит снапшоты карты (~800 мс) и пишет их в body как строку JSON. Создание — обычный POST с type: "case-diagram" и seed-телом.

Структура БД

Таблица documents

Колонка	Описание
id	UUID PK
name	Название (varchar 255)
body	Содержимое (text)
type	Тип (wysiwyg/markdown/case-diagram/custom)
space_id	UUID пространства (indexed)
parent_id	UUID родителя (self-ref FK, CASCADE delete, indexed)
deleted_at	Soft delete timestamp (indexed)

Таблица favorites

Колонка	Описание
id	UUID PK
user_id	UUID пользователя (indexed)
document_id	UUID документа (FK, CASCADE delete, indexed)
space_id	UUID пространства (indexed)
UNIQUE	(user_id, document_id)