Описание запросов и интерфейсов для работы со связями в Perxis

proto/references/references.proto

@@ -9,8 +9,9 @@ option go_package = "git.perx.ru/perxis/perxis-go/proto/references;references";
 
 package content.references;
 
-
-// Reference - ссылка на запись
+// Reference - ссылка на объект.
+// Ссылка может быть на запись в текущем пространстве, окружении или в другом пространстве. Если не указано,
+// то считается, что ссылка на запись в текущем пространстве и окружении объекта, в котором находится ссылка.
 message Reference {
   string id = 1; // ID записи
   string collection_id = 2; // ID коллекции
@@ -18,13 +19,20 @@ message Reference {
   string space_id = 4; // ID пространства, в котором находится запись (опционально, если не указано, то текущее пространство)
   string env_id = 5; // ID окружения, в котором находится запись (опционально, если не указано, то текущее окружение)
   items.Item item = 6; // Запись, на которую ссылается ссылка
+  string error = 7; // Ошибка, если запись не найдена (возвращается вместо записи)
 }
 
-// Relation - связь между двумя объектами указанными в ссылках
+// Relation - связь между двумя объектами указанными в ссылках.
+// Тип связи может быть любым, но есть зарезервированные типы, которые используются в системе:
+// - "ref" - используется для связей установленных через поля ссылок в объектах
+// - "tag" - используется для связей установленных через поля тегов в объектах, используется в таксономии
+// Расширения могут использовать свои типы связей для своих целей.
 message Relation {
   Reference to = 1; // Ссылка на объект, на который указывает связь
   Reference from = 2; // Ссылка на объект, от которого исходит связь
   string type = 3; // Тип связи
+  bool weak = 4; // Если true, то связь слабая и позволяет удалять записи, на которые она указывает
+
   // int32 weight = 4; // Вес связи
   // uint32 epoch = 5; // Используется в процессе перестроения связей
   // bool bidirectional = 6; // Если true, то связь двунаправленная
@@ -44,9 +52,9 @@ message GetResponse {
   repeated Reference notfound = 2;
 }
 
-// SetRelationRequest принимает массив отношений для установки
+// SetRelationRequest принимает массив связей для установки
 message SetRelationsRequest {
-  repeated Relation relation = 1;
+  repeated Relation relation = 1; // Список связей для установки
   bool skip_verify = 2; // Если true, то не проверять существование записей
 }
 
@@ -93,6 +101,7 @@ message RebuildRelationsRequest {
   string space_id = 1; // Если указано, то перестраиваются только связи в указанном пространстве
   string env_id = 2; // Если указано, то перестраиваются только связи в указанном окружении
   repeated string collection_ids = 3; // Если указано, то перестраиваются только связи в указанных коллекциях
+  repeated Reference from = 4; // Если указано, то перестраиваются только связи от указанной записи
 }
 
 // RebuildRelationsResponse возвращает токен, по которому можно получить статус перестроения связей
@@ -135,7 +144,7 @@ service References  {
   rpc RemoveRelations(RemoveRelationsRequest) returns(RemoveRelationsResponse) {}
 
   // Перестраивает связи
-  // Может быть долгим, поэтому выполняется асинхронно, возвращает пустой ответ
+  // Может быть долгим, поэтому возвращает токен, по которому можно получить статус перестроения связей
   rpc RebuildRelations(RebuildRelationsRequest) returns(RebuildRelationsResponse) {}
 
   // Возвращает статус перестроения связей