API: Библиотеки документов и файлы

Требуется авторизация. Права наследуются от узла-родителя (nodeId).

Библиотеки — /api/v1/libraries

Метод	Путь	Право на узел	Описание
GET	/libraries?nodeId={uuid}	view	Библиотеки узла
POST	/libraries	edit	Создать библиотеку
GET	/libraries/{id}	view	Одна библиотека
PATCH	/libraries/{id}	edit	Обновить
DELETE	/libraries/{id}	delete	Удалить в корзину узла (снимок библиотеки целиком)
POST	/libraries/{id}/recycle-content	delete	Переместить все корневые файлы/папки в корзину (библиотека остаётся)

DELETE /libraries/{id} — мягкое удаление: одна запись корзины с представлениями и текущим содержимым. Файлы этой библиотеки, уже лежавшие в корзине, purge. Восстановление — POST /nodes/{nodeId}/recycle-bin/{entryId}/restore. См. Корзина.

Тело создания:

{
  "nodeId": "uuid",
  "title": "Документы",
  "slug": "dokumenty",
  "description": ""
}

В ответе GET / после PATCH также: search_enabled (по умолчанию true) — участие библиотеки и файлов в глобальном поиске портала.

Участие в глобальном поиске

Настройки библиотеки → Общие → Участвует в поиске, либо:

PATCH /api/v1/libraries/{libraryId}
Content-Type: application/json

{ "searchEnabled": false }

Изменение searchEnabled — только администратор портала. При выключении библиотека и файлы сразу убираются из индекса. См. Поиск.

Файлы и папки — /api/v1/libraries/{libraryId}/files

Метод	Путь	Право	Описание
GET	/files?parentId={uuid}	view	Содержимое папки (без parentId — корень)
POST	/files/folders	add	Создать папку
POST	/files/upload	add	Загрузить файл (multipart, поле file, опц. parentId)
PATCH	/files/{fileId}	edit	Переименовать / переместить
DELETE	/files/{fileId}	delete	Удалить файл или папку (рекурсивно)
GET	/files/{fileRef}/permission-settings	view	Настройки наследования прав (inheritsPermissions, parentLabel)
PATCH	/files/{fileRef}/permission-settings	admin	Включить/отключить наследование: { "inheritFromParent": true|false }
GET / HEAD	/files/{fileRef}/thumbnail	view	Миниатюра изображения для сетки и колонки «Предпросмотр»

Для fileRef допускается числовой id или guid. Управление наследованием — только администратор портала. Явные права на файл/папку — через /api/v1/permissions с resourceType=file и libraryId.

Ответ GET /files включает meta.breadcrumb — цепочка папок до текущей. Каждый элемент содержит inherits_permissions и permissions (canEdit, canDelete, canManagePermissions).

Выборка файлов (GET)

GET /api/v1/libraries/{libraryId}/files?parentId={uuid}&page=1&limit=50&viewId={uuid}&sort=...&orderBy=...&filter=...&q=...

Параметр	Описание
parentId	UUID папки (без параметра — корень библиотеки)
page	Номер страницы (по умолчанию 1)
limit	Размер страницы (1–500; иначе из pageSize представления)
viewId	UUID представления (иначе — default view)
sort	Override сортировки: JSON-массив или column:asc,column2:desc
orderBy	То же, что sort (приоритет у orderBy, если указаны оба)
filter	Override фильтра (JSON); объединяется с фильтром представления через AND
q	Текстовый поиск (OR по колонкам, без учёта регистра)

Ответ meta: page, limit, total, totalPages, totalInView, groups, columns, view, breadcrumb, officeEnabled.

Фильтрация и сортировка по поддерживаемым условиям выполняются на уровне PostgreSQL (library_files). Сценарии с groupBy используют in-memory fallback.

Колонки фильтра

name, item_type, file_size, mime_type, updated_at, created_at, uploaded_by, version_number, item_number.

Формат фильтра — тот же JSON, что у списков:

{
  "logic": "and",
  "conditions": [
    { "column": "item_type", "operator": "eq", "value": "file" },
    { "column": "name", "operator": "contains", "value": "договор" }
  ]
}

Пример — только PDF в корне библиотеки:

GET /api/v1/libraries/{libraryId}/files?filter={"logic":"and","conditions":[{"column":"item_type","operator":"eq","value":"file"},{"column":"mime_type","operator":"eq","value":"application/pdf"}]}&limit=50

Сортировка и представления

По умолчанию папки всегда отображаются выше файлов; внутри каждой группы — сортировка по алфавиту (name). Дополнительные правила сортировки из config.sort применяются после группировки по типу.

Дефолтный config представления библиотеки:

{
  "columns": ["item_number", "name", "file_size", "updated_at"],
  "sort": [
    { "column": "item_type", "direction": "desc" },
    { "column": "name", "direction": "asc" }
  ],
  "selectionMode": "multiple",
  "showActionsColumn": true,
  "pageSize": 50
}

selectionMode: none | single | multiple — чекбоксы в табличном режиме и массовое удаление (клиент вызывает DELETE для каждого выбранного fileRef). При удалении папки весь вложенный subtree уходит в корзину узла одной операцией.

showActionsColumn: true | false — показывать колонку контекстного меню (⋮) в таблице (по умолчанию true). Порядок колонок: при выборе — чекбокс → действия → …; без выбора — действия → ….

Если в папке есть изображения, доступен режим сетки (?display=grid|table в URL): картинки — превью, папки и остальные файлы — крупные иконки по типу. Чекбоксы и массовое удаление — только в табличном режиме (display=table). Превью картинок в сетке и таблице запрашивает /files/{fileRef}/thumbnail (маленький JPEG), а не оригинал.

Скачивание — /api/v1/files/{id}/download

Прокси через API. Клиент не получает прямых URL S3.

Максимальный размер файла: 4 ГБ.

По умолчанию ответ отдаётся с Content-Disposition: attachment (сохранение файла). Для встроенного превью/плеера передайте ?inline=1 — тогда Content-Disposition: inline. Без inline аудио и видео тоже скачиваются как вложение (как пункт Скачать в меню ⋮ библиотеки), а не открываются как превью.

Миниатюры — /api/v1/libraries/{libraryId}/files/{fileRef}/thumbnail

Для сетки и колонки «Предпросмотр» клиент запрашивает этот маршрут, а не /download. Полноразмерный файл открывается только в просмотрщике по клику (/download).

Метод	Путь	Право	Описание
GET / HEAD	/libraries/{libraryId}/files/{fileRef}/thumbnail	view	JPEG-миниатюра (длинная сторона 320px) или оригинал SVG

Поведение:

• те же права, что у скачивания (view на библиотеку и файл);
• ответ Content-Disposition: inline, Cache-Control: private, max-age=86400;
• SVG отдаётся как есть (без растеризации);
• не-изображение, слишком большой растр (>40 Мп) или неподдерживаемый формат — 404;
• миниатюра кэшируется в объектном хранилище рядом с оригиналом (…/_thumb.jpg) и строится при загрузке файла (и при новой версии / restore);
• если миниатюры ещё нет (старые файлы, сбой при загрузке), GET /thumbnail строит её при первом открытии папки.

Версионирование — /api/v1/libraries/{libraryId}/files/{fileId}/versions

Метод	Путь	Право	Описание
GET	/files/{fileId}/versions	view	Текущая версия и история
POST	/files/{fileId}/versions	edit	Загрузить новую версию (multipart: file, опц. comment)
GET	/files/{fileId}/versions/{versionId}/download	view	Скачать архивную версию
POST	/files/{fileId}/versions/{versionId}/restore	edit	Восстановить версию как текущую

При загрузке новой версии предыдущее содержимое сохраняется в library_file_versions. Текущая версия — в library_files.version_number.

Portal Office (WOPI) — онлайн-просмотр и редактирование

Требуется PORTAL_OFFICE_ENABLED=true и запущенный Portal Office (portal/office, см. Portal Office).

Метод	Путь	Право	Описание
GET	/libraries/{libraryId}/files/{fileId}/office/session?mode=view|edit	view / edit	URL iframe Portal Office + WOPI token (accessToken, accessTokenTtl)
POST	/libraries/{libraryId}/files/{fileId}/office/session/refresh?mode=view|edit	view / edit	Новый WOPI token для открытой сессии (фронт → Reset_Access_Token)
GET	/wopi/files/{fileId}?access_token=...	WOPI	CheckFileInfo
GET	/wopi/files/{fileId}/contents?access_token=...	WOPI	GetFile
POST	/wopi/files/{fileId}/contents?access_token=...	WOPI	PutFile (сохранение)
POST	/wopi/files/{fileId}?access_token=...	WOPI	LOCK / UNLOCK / REFRESH_LOCK

WOPI JWT живёт 8 часов; пока открыт редактор, frontend периодически вызывает session/refresh и передаёт новый токен в iframe через postMessage Reset_Access_Token, поэтому сессия может длиться дольше (пока жива cookie Portal).

Ответ GET /files для каждого файла включает:

{
  "is_office_file": true,
  "permissions": { "canEdit": true, "canDelete": false }
}

В meta — officeEnabled (глобальный флаг Portal Office).

При сохранении из редактора создаётся новая версия через UploadVersionAsync с комментарием "Portal Office".

Поддерживаемые расширения: .docx, .xlsx, .pptx, .doc, .xls, .ppt, .odt, .ods, .odp, .csv, .rtf, .txt и др. (см. OfficeDocumentTypes).

События

• file.uploaded
• file.versionCreated
• file.versionRestored
• file.folderCreated
• file.deleted

Подписчики (Event Receivers) — в фазе 6.