Rekeeply Specification on Rekeeply Spec

book

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

book#

Поля:

author (text) - основной автор книги.
published_year (integer) - год публикации используемого издания.
original_title (text) - название на языке оригинала.
co_authors (text или long_text) - дополнительные авторы/соавторы.
language (text) - язык конкретного издания/материала.
original_language (text) - исходный язык произведения.
publisher (text) - издательство.
publication_place (text) - город/место издания.
edition (text) - обозначение или номер издания.
isbn (text) - идентификатор ISBN.
pages_total (integer) - общее количество страниц.
translator (text) - имя(имена) переводчика.
volume (text или integer) - номер/обозначение тома для многотомных изданий.
series (text) - название книжной серии.
reference_scope (text) - уточнение scope для записей book/reference.

article

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

article#

Поля:

author (text) - основной автор статьи.
published_year (integer) - год публикации.
journal_or_source (text) - источник публикации (журнал/сайт/платформа).
publication_date (date) - точная дата публикации.
doi (text) - DOI идентификатор.
volume (text или integer) - номер/обозначение тома.
issue (text или integer) - номер/обозначение выпуска.
pages (text) - диапазон страниц (например, 97-111).
language (text) - язык статьи.
original_title (text) - название на языке оригинала.
co_authors (text или long_text) - дополнительные авторы/соавторы.
peer_reviewed (boolean) - маркер рецензируемой публикации.
publisher (text) - издатель/организация.
publication_place (text) - место публикации.

Примечания по подтипам:

Модель Raw

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

Модель Raw#

Назначение#

Raw выделен в отдельный домен, потому что часть пользовательских данных должна храниться в неструктурированном виде до последующей обработки.
Raw обеспечивает быстрый capture без обязательной классификации и без немедленного размещения в Library.

Контракт#

Реализация core ДОЛЖНА включать Raw как домен хранения уровня аккаунта для неструктурированного capture.
Raw ДОЛЖЕН поддерживать быстрое сохранение без выбора активной библиотеки.
Raw ДОЛЖЕН поддерживать разбор и отложенную обработку сохраненных элементов.
Элементы Raw ДОЛЖНЫ поддерживать явный последующий перенос в Library.

Поддерживаемые payload-типы#

Raw ДОЛЖЕН поддерживать payload-типы text, link, mixed.
Raw МОЖЕТ поддерживать file_ref как reference-only payload.
Типы image, video, audio не входят в обязательный baseline scope.

Модель хранения Raw Item#

Хранение ДОЛЖНО быть ориентировано на typed-columns-first для горячих read-path.
Реализация НЕ ДОЛЖНА опираться на JSON-only хранение для горячих list/filter-path.
Каждый RawItem ДОЛЖЕН содержать: id, account_id, payload_type, status, created_at, updated_at.
Реализация ДОЛЖНА/РЕКОМЕНДУЕТСЯ хранить легкие поля для быстрых списков (title_preview, source/type/status).

Каналы записи (capture)#

Raw ДОЛЖЕН принимать capture из ручного ввода и буфера обмена/paste.
Raw ДОЛЖЕН/МОЖЕТ принимать external share/import при поддержке клиентом/рантаймом.
Capture НЕ ДОЛЖЕН зависеть от сетевой доступности.

Обогащение метаданными#

Для link metadata enrichment МОЖЕТ выполняться асинхронно после capture.
Ошибки получения метаданных НЕ ДОЛЖНЫ блокировать завершение capture.
Если метаданные недоступны, реализация ДОЛЖНА использовать детерминированный fallback-preview.

Lifecycle и операции#

Реализация ДОЛЖНА поддерживать состояния, эквивалентные new | triaged | promoted | archived.
Реализация ДОЛЖНА поддерживать list и смену статусов для triage.
Реализация ДОЛЖНА поддерживать явную операцию promote из Raw в Library.

Требования к promote-flow#

promote ДОЛЖЕН валидировать, что target_library_id принадлежит тому же account_id.
promote ДОЛЖЕН быть идемпотентным для одного RawItem и НЕ ДОЛЖЕН создавать дубли при retry.
promote ДОЛЖЕН сохранять связь с созданной сущностью библиотеки (promoted_content_id или эквивалент origin-link).

Mapping-правила promote#

Raw:text

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

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

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

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

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

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

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

`book`#

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

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

game

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

game#

Поля:

platform (text) - основная платформа/среда запуска (например, PC, PlayStation, Xbox, Nintendo, board).
release_year (integer) - год первоначального релиза.
developer (text) - разработчик/студия.
publisher (text) - издатель игры.
distribution_source (text или enum) - источник/магазин, где игра доступна или приобретена (например, Steam, Epic Games Store, PS Store, Xbox Store, Nintendo eShop).
genre (text или multi_enum) - жанровая классификация (например, RPG, strategy, puzzle).
mode (enum или multi_enum) - режим игры (single-player, multiplayer, co-op).
playtime_hours (decimal) - оценочная или фактическая длительность игры в часах.
players_count (text или integer) - поддерживаемое/типичное количество игроков.
edition (text) - обозначение издания/версии.
region (text) - региональная версия/доступность.

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

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 расширения.

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

screen

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

screen#

Поля:

release_year (integer) - год релиза.
format (text или enum) - формат экранного контента (например, film/series/anime/animation).
original_title (text) - название на языке оригинала.
country (text) - страна производства.
director (text) - режиссер.
writers (text или long_text) - сценаристы.
cast (long_text) - основной актерский состав.
studio_or_network (text) - студия/канал/платформа.
season_number (integer) - номер сезона (особенно для screen/episode).
episode_number (integer) - номер эпизода (для screen/episode).
duration_minutes (integer) - длительность в минутах.
release_date (date) - точная дата релиза.
age_rating (text) - возрастной рейтинг.
imdb_id (text) - идентификатор IMDb.
franchise (text) - название франшизы/вселенной.

Примечания по подтипам:

Типы полей

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.

video

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

video#

Поля:

creator_or_channel (text) - основной автор/креатор или канал.
release_year (integer) - год релиза/публикации.
original_title (text) - название на языке оригинала.
duration_minutes (integer) - длительность видео в минутах.
platform (text) - платформа размещения (например, YouTube, Vimeo, Twitch).
series_name (text) - название серии/шоу, если видео серийное.
episode_label (text) - обозначение выпуска/части.
language (text) - язык контента/озвучки.
subtitles (multi_enum) - языки/наличие субтитров.
published_at (datetime) - точное время публикации.
age_rating (text) - маркер возрастных ограничений.
view_count_snapshot (integer) - сохраненный срез количества просмотров.

Примечания по подтипам:

quote

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

quote#

Поля:

quote_text (long_text) - зафиксированный текст цитаты или формулировка идеи.
quoted_author (text) - автор/персона, которой принадлежит цитата.
source_title (text) - название источника.
source_locator (text) - указатель в источнике (страница, таймкод, глава, фрагмент URL).
language (text) - язык цитаты.
original_text (long_text) - текст на языке оригинала, если используется перевод.
context_note (long_text) - пояснение контекста/интерпретации.
quote_date (date) - дата высказывания/публикации, если известна.

Примечания по подтипам:

quote/text обычно использует source_locator и quoted_author.
quote/dialogue обычно использует source_title и контекстные примечания.
quote/idea обычно использует context_note с краткой привязкой к источнику.

Теги#

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

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-режиме.

person

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

person#

Поля:

name (text) - основное имя персоны.
full_name (text) - полное имя.
aliases (long_text) - альтернативные имена/псевдонимы.
born_year (integer) - год рождения.
died_year (integer) - год смерти (если применимо).
nationality (text) - национальность/страновая принадлежность.
roles (multi_enum) - роли/профессии.
known_for (long_text) - краткое описание, чем известен.
official_site (url) - официальный сайт/профиль.
external_ids (json) - внешние идентификаторы (например, ORCID, Wikidata, IMDb).

Примечания по подтипам:

person/author обычно использует roles, known_for и ссылки на публикации.
person/speaker обычно использует медиа/профильные ссылки и тематические заметки.
person/researcher обычно использует external_ids и исследовательский контекст в заметках.
person/creator обычно использует ссылки на платформы/профили.

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

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

resource

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

resource#

Поля:

resource_name (text) - основное название ресурса.
resource_kind (text или enum) - уточняющий вид ресурса в контексте подтипа.
provider (text) - владелец/провайдер ресурса.
official_url (url) - основная ссылка на ресурс.
access_model (enum) - модель доступа (free/paid/freemium/private).
license (text) - лицензия/условия использования.
pricing_note (text) - краткое описание модели оплаты.
api_available (boolean) - признак доступности API.
repo_host (text) - хост-платформа репозитория (например, GitHub, GitLab).
language (text) - основной язык контента/интерфейса.
last_checked_at (datetime) - момент последней проверки ресурса.

Примечания по подтипам:

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

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

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

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

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

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

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

music

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

music#

Поля:

artist (text) - основной артист/исполнитель/композитор.
original_title (text) - название на языке оригинала.
album_title (text) - название родительского альбома.
release_year (integer) - год релиза.
duration_seconds (duration) - длительность трека/записи.
genre (text или multi_enum) - музыкальный жанр.
label (text) - музыкальный лейбл.
isrc (text) - идентификатор ISRC.
platform (text) - платформа/сервис прослушивания.
track_number (integer) - номер трека в альбоме/EP.
disc_number (integer) - номер диска для многодисковых релизов.

Примечания по подтипам:

audio

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

audio#

Поля:

speaker_or_author (text) - основной спикер/автор/ведущий.
original_title (text) - название на языке оригинала.
release_year (integer) - год релиза/публикации.
duration_seconds (duration) - длительность аудио.
language (text) - язык речи.
publisher_or_show (text) - издатель/шоу/сеть.
episode_label (text) - обозначение эпизода/главы.
narrator (text) - диктор/озвучивающий.
platform (text) - платформа распространения/прослушивания.
isbn_or_external_id (text) - внешний идентификатор при необходимости.

Примечания по подтипам:

audio/audiobook обычно использует narrator, publisher_or_show, isbn_or_external_id.
audio/podcast_episode обычно использует episode_label, publisher_or_show, platform.
audio/podcast_show обычно использует метаинформацию уровня шоу/платформы.
audio/lecture_audio и audio/interview_audio обычно используют speaker_or_author, duration_seconds, language.
audio/voice_note обычно использует минимальную метаинформацию и контекстные заметки.

Пресеты

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, родительская связь является только организационной.
При удалении родительского пресета дочерние пресеты РЕКОМЕНДУЕТСЯ переносить на корневой уровень.

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

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

misc

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

misc#

Поля:

kind_note (text) - короткое пояснение, что представляет запись.
external_id (text) - опциональный внешний идентификатор.
extra_metadata (json) - расширенный произвольный объект метаданных.

Примечания по подтипам:

misc не имеет подтипов по умолчанию.

Коллекции

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

Модель исполнения#

Режимы исполнения#

embedded (по умолчанию): core выполняется в одном процессе с клиентским приложением для минимальной задержки.
service: core выполняется как локальный отдельный процесс и доступен клиентам через локальный IPC-канал.
remote: клиент подключается к удаленному backend core по защищенному сетевому каналу.

Общие правила#

одна и та же доменная логика core;
обязательная аутентификация;
одна активная сессия привязана к одному аккаунту;
операции в контексте библиотеки работают только с одной активной базой;
клиент обращается к core-контракту, а не к файлу БД напрямую.

Жизненный цикл сессии#

init: первичная инициализация локального vault и создание первой базы;
unlock: аутентификация пользователя и открытие рабочей сессии;
active: выполнение команд в контексте активной сессии (library-scoped или account-scoped);
switch-library: явная смена активной базы внутри сессии;
auto-lock: автоматическая блокировка по таймауту неактивности;
manual lock/logout: ручная блокировка или завершение сессии.

Модель синхронизации (верхний уровень)#

локальная база является источником пользовательской работы по умолчанию;
синхронизация выполняется асинхронно и не блокирует пользовательские операции;
синхронизация поддерживает как данные уровня библиотеки, так и данные уровня аккаунта;
при оффлайне core продолжает работать, синхронизация откладывается;
конфликты разрешаются детерминированной политикой (уточняется отдельным разделом);
передача данных для sync выполняется только по защищенному каналу.

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

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.

Граница аутентификации

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

Граница аутентификации#

правила аутентификации определяет core;
проверку учетных данных и выпуск сессии выполняет core;
клиент только передает аутентификационные данные в core-контракт и хранит клиентские артефакты сессии;
доступ к данным без активной валидной сессии запрещен.

Модель аккаунта

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

Модель аккаунта#

Контракт#

Реализация core ДОЛЖНА включать Account как доменную сущность первого класса.
Один аккаунт ДОЛЖЕН владеть нулем или более библиотек; каждая библиотека ДОЛЖНА принадлежать ровно одному аккаунту.
Одна активная сессия ДОЛЖНА быть привязана ровно к одному аккаунту.
Операции в контексте библиотеки в одной активной сессии ДОЛЖНЫ работать ровно с одной активной библиотекой.

Атрибуты аккаунта#

id ДОЛЖЕН существовать и ДОЛЖЕН быть неизменяемым.
status ДОЛЖЕН существовать и задавать границу блокировки (locked/unlocked или эквивалент).
security_policy_ref ДОЛЖЕН существовать и НЕ ДОЛЖЕН содержать секреты в открытом виде.
default_library_id МОЖЕТ присутствовать; если задан, он ДОЛЖЕН ссылаться на библиотеку того же аккаунта.
Дополнительные метаданные МОГУТ присутствовать и являются implementation-defined.

Жизненный цикл#

init ДОЛЖЕН создавать ровно один локальный аккаунт в новом vault.
Повторный init для инициализированного vault ДОЛЖЕН отклоняться, если не запущен явный reset/force flow.
Runtime-состояния ДОЛЖНЫ быть эквивалентны uninitialized -> locked -> unlocked -> locked.

Правила сессии и доступа#

После unlock сессия ДОЛЖНА быть привязана к одному account_id.
Операции уровня Raw МОГУТ выполняться без выбора активной библиотеки.
Cross-account операции в одной активной сессии ДОЛЖНЫ отклоняться.
Операции записи в доменные сущности ДОЛЖНЫ отклоняться, пока сессия заблокирована.
Операции export/import ДОЛЖНЫ выполняться в контексте активного аккаунта.

Что не входит в модель аккаунта#

Нет требований по email/username/avatar.
Нет требований по OAuth или social identity.
Нет client/device UI-настроек в core-схеме аккаунта.

Формат переноса библиотеки

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

Формат переноса библиотеки#

Baseline#

Экспорт/импорт библиотеки ДОЛЖЕН использовать расширение *.rkl.
Контейнер *.rkl ДОЛЖЕН использовать tar.zst.
Текстовые датасеты внутри *.rkl ДОЛЖНЫ использовать кодировку UTF-8.
Базовый scope экспорта библиотеки включает только данные уровня библиотеки.
Данные Raw исключаются из baseline scope экспорта/импорта библиотеки.
Пакет переноса ДОЛЖЕН включать manifest-метаданные, версию формата и данные целостности.

Baseline структуры пакета#

manifest.json (required)
library.json (required)
taxonomy.json (required)
content.ndjson (required)
tags.json (required)
tag_links.ndjson (required)
attachments.ndjson (required)
progress.ndjson (optional)
notes.ndjson (optional)

Baseline manifest#

manifest.json ДОЛЖЕН включать: format, version, encoding, container, exported_at, library, datasets, integrity.
format ДОЛЖЕН быть rkl.
encoding ДОЛЖЕН быть utf-8.
container ДОЛЖЕН быть tar.zst.
library ДОЛЖЕН включать id и name.
datasets ДОЛЖЕН включать путь и checksum для каждого включенного датасета.
integrity ДОЛЖЕН включать алгоритм checksum и checksum manifest.

Baseline датасетов#

library.json ДОЛЖЕН включать id, name, icon.
taxonomy.json ДОЛЖЕН включать таксономию типов/подтипов и определения схем полей.
Строки content.ndjson ДОЛЖНЫ включать id, type, status, created_at, updated_at, status_changed_at.
tags.json ДОЛЖЕН включать метаданные тегов.
Строки tag_links.ndjson ДОЛЖНЫ включать content_id, tag_id.

Правило переноса таксономии#

Таксономия ДОЛЖНА переноситься вместе с библиотекой при export/import.
В scope таксономии входят: типы контента, подтипы контента, схемы полей, теги и связи тег-контент.
Импорт ДОЛЖЕН восстанавливать таксономию до или одновременно с контентными датасетами, чтобы ссылки контента оставались валидными.

Примечание по датасетам#

Формат переноса библиотеки ДОЛЖЕН поддерживать датасеты вложений (метаданные вложений и связи с контентом).

Baseline датасета вложений#

Имя файла датасета метаданных вложений: attachments.ndjson.
Каждая строка вложения ДОЛЖНА включать: id, content_id, uri.
Опциональные поля строки вложения: name, mime, size, created_at.
content_id в attachments.ndjson ДОЛЖЕН ссылаться на существующую запись контента.

Правила валидации и безопасности#

Импорт ДОЛЖЕН отклонять пакет при отсутствии любого required датасета.
Импорт ДОЛЖЕН отклонять пакет при ошибке checksum любого датасета.
Импорт ДОЛЖЕН отклонять небезопасные пути в архиве (../, абсолютные пути и эквиваленты path traversal).
Импорт ДОЛЖЕН валидировать схему и ссылки до финального commit.
Импорт ДОЛЖЕН быть атомарным: при критической ошибке валидации частичное финальное состояние не фиксируется.

Baseline порядка импорта#

Сначала выполняется проверка контейнера пакета и целостности manifest.
Затем восстанавливаются метаданные библиотеки (library.json).
Таксономия восстанавливается до контентных датасетов.
Затем восстанавливаются контентные датасеты.
Затем восстанавливаются теги и связи тег-контент.
attachments.ndjson восстанавливается после контентных датасетов.
После этого выполняется финальная проверка ссылочной целостности и атомарный commit импорта.

Модель настроек

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

Модель настроек#

Группы scope#

account-scoped
library-scoped

Настройки уровня библиотеки#

default_status_on_create (enum)
default_priority_on_create (enum|null, default null)
allow_parent_links (boolean, default true)
archived_visible_by_default (boolean)

Настройки уровня аккаунта#

default_library_id (optional)
last_active_library_restore (boolean, default true)
auto_lock_timeout_minutes (integer, default 15, 0 означает отключение)
require_unlock_on_start (boolean, default true)
sync_enabled (boolean, default false)
sync_mode (enum: manual|auto, default manual)
sync_interval_minutes (integer, default 15, используется при sync_mode=auto)
export_compression_enabled (boolean, default true)
backup_enabled (boolean, default false)
backup_interval_hours (integer, default 24, используется при включенном backup)
backup_retention_count (integer, default 10)
timezone (text, default системная таймзона)
locale (text, default locale аккаунта или fallback клиента/системы)

Правила fallback#

Если default_library_id невалиден или удален, fallback: last_active при наличии, иначе явный выбор библиотеки.

TODO

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

TODO#

TODO: команды CLI;
TODO: жизненный цикл сессии в CLI;
TODO: конфигурация и локальное хранение;
TODO: ошибки и коды выхода;
TODO: требования безопасности на уровне клиента.

Глоссарий

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

Глоссарий#

Фиксированные канонические термины, используемые в спецификации.

Account — верхнеуровневый пользовательский доменный контекст в core.
Session — аутентифицированный runtime-контекст, привязанный к одному account_id.
Library — структурированный домен хранения для организованной работы.
Raw — домен неструктурированного capture уровня аккаунта.
active_library_id — выбранная библиотека для library-scoped операций.
library-scoped — операция/данные, требующие активный контекст библиотеки.
account-scoped — операция/данные, требующие только контекст аккаунта в сессии.
unlock — открытие сессии после валидации учетных данных.
sync — асинхронная синхронизация данных между локальным и удаленным runtime.
promote — явный перенос данных из Raw в Library.

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

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

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

Scope#

Политика определяет правила версионирования для спецификации, core API и проектных репозиториев.

Домены версий#

Spec Version - версия текущей спецификации.
Core API Version - версия runtime-контракта между клиентами и core.
Project Version - версия конкретного репозитория/пакета (core, cli, другие клиенты).

Схема#

Для всех доменов версий ДОЛЖНА использоваться схема Semantic Versioning: MAJOR.MINOR.PATCH.

Правила SemVer#

MAJOR: breaking-изменение контракта.
MINOR: обратно-совместимое добавление функциональности.
PATCH: обратно-совместимый фикс/редакционное исправление.

Baseline совместимости#

Клиенты ДОЛЖНЫ объявлять поддерживаемый диапазон Core API Version.
Core runtime ДОЛЖЕН отдавать текущую Core API Version.
При старте/handshake совместимость client-core ДОЛЖНА проверяться до выполнения обычных операций.
Несовместимые версии ДОЛЖНЫ завершаться явной ошибкой совместимости.

Mapping релизов#

Spec Version МОЖЕТ развиваться независимо от версий проектных пакетов.
Breaking-изменения core-контракта в спецификации РЕКОМЕНДУЕТСЯ сопровождать повышением major-версии и Spec Version, и Core API Version.
Версии проектных пакетов МОГУТ следовать собственному релизному ритму, но НЕ ДОЛЖНЫ обходить проверки API-совместимости.

Версионирование формата RKL#

Версия формата *.rkl независима и ДОЛЖНА указываться в manifest.
Импорт ДОЛЖЕН валидировать указанную версию rkl до обработки датасетов.

История изменений

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

История изменений#

История изменений спецификации.

Rekeeply Specification on Rekeeply Spec

book

book#

article

article#

Модель Raw

Модель Raw#

Назначение#

Контракт#

Поддерживаемые payload-типы#

Модель хранения Raw Item#

Каналы записи (capture)#

Обогащение метаданными#

Lifecycle и операции#

Требования к promote-flow#

Mapping-правила promote#

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

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

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

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

book#

game

game#

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

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

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

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

system#

user_editable#

computed#

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

Правила#

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

screen

screen#

Типы полей

Типы полей#

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

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

video

video#

quote

quote#

Теги

Теги#

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

Сущность Tag#

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

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

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

person

person#

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

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

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

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

resource

resource#

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

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

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

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

music

music#

audio

audio#

Пресеты

Пресеты#

Контракт#

Операции#

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

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

misc

misc#

Коллекции

Коллекции#

Контракт#

Поля Collection#

Операции#

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

`book`#

`system`#

`user_editable`#

`computed`#