Модель библиотеки on Rekeeply Spec

Типизация контента

Mon, 01 Jan 0001 00:00:00 +0000

Типизация контента#

Базовые правила#

content_type является обязательным полем; создание записи без типа НЕ ДОПУСКАЕТСЯ.
content_subtype является необязательным полем.
При ручном создании записи выбор начинается с content_type.
После выбора типа подтип и остальные поля могут быть заполнены позже.

Набор по умолчанию и рекомендуемый набор#

Следующий набор типов/подтипов доступен в системе по умолчанию и рекомендуется на основе практического личного опыта использования.

`book`#

Назначение: длинные письменные материалы и справочные книги.

Поля: см. Поля по типам.

Поля контента

Mon, 01 Jan 0001 00:00:00 +0000

Поля контента#

Классы полей#

Поля класса system управляются core и НЕ ДОЛЖНЫ редактироваться пользователем вручную.
Поля класса user_editable видимы и редактируемы пользователем.
Поля класса computed вычисляются core и ДОЛЖНЫ рассматриваться как read-only.

Базовый набор общих полей#

`system`#

id - неизменяемый идентификатор записи.
library_id - идентификатор библиотеки-владельца.
created_at - момент создания.
updated_at - момент последнего изменения.
status_changed_at - момент последней смены статуса.

`user_editable`#

content_type - обязательный ключ типа.
content_subtype - опциональный ключ подтипа.
title - заголовок записи.
status - inbox | todo | in_progress | skimmed | done | dropped.
priority - low | medium | high.
rating - опциональная целочисленная оценка в диапазоне 1..10.
recommendation - опциональный маркер рекомендации: recommended | neutral | not_recommended.
favorite - независимый флаг избранного.
archived - независимый флаг архивирования.
parent_content_id - опциональная родительская связь.
source_url - опциональная ссылка на источник.
summary - опциональное краткое описание.

`computed`#

search_text - нормализованный текстовый индекс для быстрого поиска.
last_activity_at - вычисляемое время последней активности.
is_completed - вычисляемый флаг завершенности по статусу.

Модель вложений#

Записи контента МОГУТ иметь несколько связанных вложений.
Связи вложений моделируются как связанные сущности, а не как единичные фиксированные поля.
Базовые поля вложения: id, content_id, uri, name (optional), mime (optional), size (optional), created_at.
Baseline файл датасета для export/import вложений: attachments.ndjson.

Правила#

Клиенты ДОЛЖНЫ запрещать редактирование полей классов system и computed.
Core ДОЛЖЕН поддерживать консистентность всех computed полей.
При создании записи status РЕКОМЕНДУЕТСЯ автоматически устанавливать в inbox.
При создании записи priority РЕКОМЕНДУЕТСЯ оставлять пустым по умолчанию, если значение явно не задано.
При смене статуса ДОЛЖЕН обновляться status_changed_at, при этом updated_at НЕ ДОЛЖЕН обновляться.
При изменении флага favorite поле updated_at НЕ ДОЛЖНО обновляться.
При изменении флага archived поле updated_at НЕ ДОЛЖНО обновляться.
Если rating задан, значение ДОЛЖНО находиться в диапазоне 1..10.
Пользовательские поля, кроме content_type и status, не обязательны в момент создания и могут заполняться позже.
Type-specific поля не являются обязательными в baseline и становятся обязательными только если пользовательская схема помечает их как required.
Реализация МОЖЕТ добавлять дополнительные поля любого класса как implementation-defined расширения.

Связанные разделы#

Типы полей

Mon, 01 Jan 0001 00:00:00 +0000

Типы полей#

Область действия#

Раздел фиксирует разрешенные значения field_type для пользовательских полей.
Для всех типов полей параметр required настраиваемый (true | false).
Значения по умолчанию настраиваются там, где это поддерживается типом поля.

Разрешенные типы полей#

text - короткий текст.
- Валидация: min_length (опционально), max_length (опционально), pattern (опционально), trim_on_save (опционально).
- По умолчанию: default_value (опциональная строка).
long_text - длинный многострочный текст.
- Валидация: min_length (опционально), max_length (опционально), trim_on_save (опционально).
- По умолчанию: default_value (опциональная строка).
boolean - логическое значение true/false.

Теги#

Место в модели#

Tag является отдельной сущностью уровня библиотеки и НЕ является field_type.
Записи контента связываются с тегами через ассоциацию many-to-many.

Сущность Tag#

id (system) - неизменяемый идентификатор тега.
library_id (system) - библиотека-владелец.
key (system или managed) - стабильный внутренний ключ.
label (user_editable) - отображаемое пользователю имя тега.
color (user_editable, optional) - визуальный цветовой маркер.
icon (user_editable, optional) - визуальный икон-маркер.
created_at (system) - момент создания.
updated_at (system) - момент обновления.

Связь с контентом#

Связь контента с тегами ДОЛЖНА поддерживать несколько тегов на одну запись.
Core ДОЛЖЕН поддерживать назначение существующих тегов записям и снятие тегов с записей.
Core РЕКОМЕНДУЕТСЯ поддерживать создание тега и его назначение в рамках одной логической операции.

Правила редактирования#

Переименование тега обновляет label без переписывания записей контента.
Удаление тега ДОЛЖНО удалять связи с контентом, но НЕ ДОЛЖНО удалять контент.
Объединение тегов МОЖЕТ поддерживаться и ДОЛЖНО сохранять связи с контентом.

Import/Export и синхронизация#

Таксономия тегов ДОЛЖНА переноситься вместе с экспортом/импортом библиотеки.
Данные тегов и связи тег-контент ДОЛЖНЫ синхронизироваться в sync-режиме.

Действия библиотеки

Mon, 01 Jan 0001 00:00:00 +0000

Действия библиотеки#

Область действия#

Действия определяют baseline операций для записей библиотеки и тегов библиотеки.

Действия для записей#

create
- Начинается с выбора content_type.
- Core автоматически заполняет системные поля (id, library_id, created_at, updated_at).
- Core устанавливает status=inbox и пустой priority по умолчанию.
edit
- Обновляет пользовательские поля.
- Обновляет updated_at.
set-subtype
- Устанавливает или очищает content_subtype.
- НЕ ДОЛЖЕН менять content_type.
- Обновляет updated_at.
set-status
- Устанавливает status из разрешенного набора.
- Переходы свободные (без жесткой state-machine).
- ДОЛЖЕН обновлять status_changed_at.
- НЕ ДОЛЖЕН обновлять updated_at.
set-priority

Действия схемы

Mon, 01 Jan 0001 00:00:00 +0000

Действия схемы#

Область действия#

Действия определяют lifecycle-операции для library-scoped сущностей схемы: пользовательские типы, пользовательские подтипы и пользовательские поля.
Сущности схемы используют внутренние стабильные key, уникальные в рамках одной библиотеки.

Действия для типов#

create-type
- Создает пользовательский тип контента в текущей библиотеке.
- Внутренний key ДОЛЖЕН быть уникальным в библиотеке.
edit-type
- Обновляет редактируемые свойства типа.
- Внутренний key ДОЛЖЕН оставаться неизменяемым.
archive-type / unarchive-type
- Отключает/включает тип для активного использования в новых записях.
- Существующие записи с этим типом остаются валидными.
delete-type

Пресеты

Mon, 01 Jan 0001 00:00:00 +0000

Пресеты#

Контракт#

Preset — это сохраненное определение поиска в scope библиотеки.
Preset хранит только условия поиска.
Preset НЕ ДОЛЖЕН хранить сортировку и layout отображаемых полей.
Preset МОЖЕТ быть вложенным через parent_preset_id.
Preset МОЖЕТ задавать inherit_query (true|false) для наследования запроса родителя.
Preset МОЖЕТ включать визуальные метаданные (color, icon).

Операции#

create-preset
update-preset
rename-preset
delete-preset
run-preset

Правила иерархии#

Циклы в иерархии пресетов запрещены.
Если inherit_query=true, итоговый запрос объединяется с запросом родителя через baseline-композицию AND.
Если inherit_query=false, родительская связь является только организационной.
При удалении родительского пресета дочерние пресеты РЕКОМЕНДУЕТСЯ переносить на корневой уровень.

Управление пользователем#

Пользователь может задавать и менять названия пресетов.
Пользователь может задавать порядок пресетов.

Коллекции

Mon, 01 Jan 0001 00:00:00 +0000

Коллекции#

Контракт#

Collection — ручная группировка записей в scope библиотеки.
Collection НЕ хранит условия поиска.
Одна запись контента МОЖЕТ входить в несколько коллекций.

Поля Collection#

id (system) - неизменяемый идентификатор коллекции.
library_id (system) - библиотека-владелец.
name (user_editable) - название коллекции.
description (user_editable, optional) - описание коллекции.
color (user_editable, optional) - визуальный цветовой маркер.
icon (user_editable, optional) - визуальный икон-маркер.
parent_collection_id (user_editable, optional) - родительская коллекция для иерархии.
created_at (system) - момент создания.
updated_at (system) - момент обновления.

Операции#

create-collection
rename-collection
delete-collection
add-to-collection
remove-from-collection
reorder-collections

Правила иерархии#

Родительская коллекция МОЖЕТ иметь несколько дочерних.
Одна коллекция МОЖЕТ иметь не более одного родителя.
Циклы в иерархии коллекций запрещены.

Поведение поиска

Mon, 01 Jan 0001 00:00:00 +0000

Поведение поиска#

Базовое правило#

Search и Preset ДОЛЖНЫ использовать один и тот же query-движок и одинаковую семантику.

Search vs Preset#

Search по умолчанию является временным (ephemeral) и не сохраняется, пока пользователь явно его не сохранит.
Preset — явно сохраненное определение поиска.
При изменении текущего поиска или перезапуске сессии библиотеки предыдущий временный результат поиска удаляется.
Между сессиями сохраняются только явно сохраненные пресеты.

Измерения поиска#

Поиск ДОЛЖЕН поддерживать структурные условия по status, priority, rating, recommendation, favorite, archived, content_type, content_subtype.

Lifecycle библиотеки

Mon, 01 Jan 0001 00:00:00 +0000

Lifecycle библиотеки#

Атрибуты библиотеки#

id - уникальный неизменяемый идентификатор.
name - редактируемое название библиотеки.
icon - редактируемый визуальный маркер.

Lifecycle-операции#

create-library
- Создает новую библиотеку с id, name, icon.
rename-library
- Обновляет только name.
- id остается неизменяемым.
update-library-icon
- Обновляет только icon.
archive-library / unarchive-library
- Архивная библиотека НЕ ДОЛЖНА выбираться как активная до восстановления.
delete-library
- Hard delete требует явного подтверждения.
- Перед удалением система РЕКОМЕНДУЕТСЯ показывать сводку объема связанных данных.
- Если удаляемая библиотека активна:
  - активная библиотека переключается на fallback при наличии;
  - иначе активная библиотека очищается до следующего выбора/создания.

Инварианты#

Lifecycle-операции являются account-scoped.
Cross-account lifecycle-операции запрещены.
id библиотеки стабилен и не переиспользуется в рамках одного account scope.

Модель библиотеки on Rekeeply Spec

Типизация контента

Типизация контента#

Базовые правила#

Набор по умолчанию и рекомендуемый набор#

book#

Поля контента

Поля контента#

Классы полей#

Базовый набор общих полей#

system#

user_editable#

computed#

Модель вложений#

Правила#

Связанные разделы#

Типы полей

Типы полей#

Область действия#

Разрешенные типы полей#

Теги

Теги#

Место в модели#

Сущность Tag#

Связь с контентом#

Правила редактирования#

Import/Export и синхронизация#

Действия библиотеки

Действия библиотеки#

Область действия#

Действия для записей#

Действия схемы

Действия схемы#

Область действия#

Действия для типов#

Пресеты

Пресеты#

Контракт#

Операции#

Правила иерархии#

Управление пользователем#

Коллекции

Коллекции#

Контракт#

Поля Collection#

Операции#

Правила иерархии#

Поведение поиска

Поведение поиска#

Базовое правило#

Search vs Preset#

Измерения поиска#

Lifecycle библиотеки

Lifecycle библиотеки#

Атрибуты библиотеки#

Lifecycle-операции#

Инварианты#

`book`#

`system`#

`user_editable`#

`computed`#