items.proto

/**
 * # Items
 *
 * API Сервиса работы с пользовательским записями (Items)
 *
 * Предоставляет доступ к записям пользовательских коллекций
 *
 */
syntax = "proto3";

import "google/protobuf/empty.proto";
import "common/common.proto";
import "common/error.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/struct.proto";

option go_package = "git.perx.ru/perxis/perxis-go/proto/items;items";

package content.items;

message Error {
	string message = 1; // Сообщение об ошибке
	string field = 2; // Поле в котором произошла ошибка

}

message DecodeError {
  repeated Error errors = 2;
}

message ValidationError {
  repeated Error errors = 2;
}

message ModificationError {
  repeated Error errors = 2;
}

message Permissions {
  bool edit = 1;
  bool archive = 2;
  bool publish = 3;
  bool soft_delete = 4;
  bool hard_delete = 5;
}

/**
 * Пользовательская запись
 */
message Item {
  enum State {
    DRAFT = 0;
    PUBLISHED = 1;
    CHANGED = 2;
    ARCHIVED = 3;
  }
  string id = 1;
  string space_id = 2;
  string env_id = 3;
  string collection_id = 4;
  State state = 5;
  google.protobuf.Timestamp created_rev_at = 6; // дата создания текущей ревизии
  string created_by = 7;                        // id пользователя создавшего первую ревизию
  google.protobuf.Timestamp created_at = 8;     // дата создания первой ревизии
  string updated_by = 9;                       // id пользователя обновившего текущую ревизию
  google.protobuf.Timestamp updated_at = 10;     // дата обновления текущей ревизии
  google.protobuf.Struct data = 11;
  map<string, google.protobuf.Struct> translations = 12;
  string revision_id = 13;
  string revision_description = 14;
  string locale = 18;
  bool deleted = 19;
  bool hidden = 20;
  bool template = 21;
  Permissions permissions = 22;
}

/**
 * Объекты, описывающие произошедшие в сервисе события
 */

message EventCreate {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  string item_id = 4;
}

message EventUpdate {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  string item_id = 4;
}

message EventPublish {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  string item_id = 4;
}

message EventUnpublish {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  string item_id = 4;
}

message EventDelete {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  string item_id = 4;
}

message Filter {
  repeated string id = 1; // Список ID записей кото
  repeated common.Filter data = 2; // Список фильтров
  repeated string q = 3; // Список выражений для фильтрации
}

message CreateOptions {
  bool update_attrs = 1; // позволяет обновить системные поля: created_by, created_at, created_rev_at, updated_by, updated_at
}

message FindOptions {
  common.FindOptions options = 2;
  bool deleted = 3;
  bool regular = 4;
  bool hidden = 5;
  bool templates = 6;
}

message UpdateOptions {
  bool update_attrs = 1; // позволяет обновить системные поля: created_by, created_at, created_rev_at, updated_by, updated_at
}

message GetPublishedOptions {
  string locale_id = 1;
}

message DeleteOptions {
  bool update_attrs = 1; // позволяет обновить системные поля: created_by, created_at, created_rev_at, updated_by, updated_at
  bool erase = 2; // полное удаление без сохранения удаленной версии объекта
}

message UndeleteOptions {
  bool update_attrs = 1; // позволяет обновить системные поля: created_by, created_at, created_rev_at, updated_by, updated_at
}

message PublishOptions {
  bool update_attrs = 1; // позволяет обновить системные поля: created_by, created_at, created_rev_at, updated_by, updated_at
}

message UnpublishOptions {
  bool update_attrs = 1; // позволяет обновить системные поля: created_by, created_at, created_rev_at, updated_by, updated_at
}

message FindPublishedOptions {
  common.FindOptions options = 2;
  string locale_id = 3;
  bool regular = 4;
  bool hidden = 5;
  bool templates = 6;
}

message FindArchivedOptions {
  common.FindOptions options = 2;
}

message ListRevisionsOptions {
  common.FindOptions options = 2;
}

// Fields - поля которые должны быть возвращены или вычислены в результате.
// Ключ (string) - имя поля под которым будет добавляться результат.
// Значение (string) - является выражением, вычисление которого сформирует результат
// Функции для выражений (для поля F, типа T):
// - distinct(F) - все значения поля, тип результат []T
// - min(F) - минимальное значение поля, тип результат T
// - max(F) - максимальное значение поля, тип результат T
// - avg(F) - среднее значения поля, тип результат T
// - sum(F) - сумма значений поля, тип результат T
// - count() - число записей, тип результат int
// Пример: {'average of C': 'avg(a.b.c)'}
message  AggregateOptions {
  map<string, string> fields = 1;
}

message  AggregatePublishedOptions {
  map<string, string> fields = 1;
}

message CreateRequest {
  Item item = 1;
  CreateOptions options = 2;
}
message CreateResponse {
  Item created = 1;
}

message IntrospectRequest {
  Item item = 1;
}
message IntrospectResponse {
  Item item = 1;
  string schema = 2;
  repeated common.Error.BadRequest.FieldViolation validation_errors = 3;
}

message GetRequest {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  string item_id = 4;
}
message GetResponse {
  Item item = 1;
}

message FindRequest {
  string space_id = 1; // ID Пространства
  string env_id = 2; // ID окружения
  string collection_id = 3; // ID коллекции
  Filter filter = 4;
  FindOptions options = 5; // Дополнительные параметры поиска
}
message FindResponse{
  repeated Item items = 1;
  int32 total = 2;
}

message UpdateRequest {
  Item item = 1;
  UpdateOptions options = 2;
}

message DeleteRequest {
  Item item = 1; // важны только переданные внутри идентификаторы или, если указана опция update_attrs, поля которые изменяются: created_by, created_at, created_rev_at, updated_by, updated_at
  DeleteOptions options = 2;
}

message UndeleteRequest {
  Item item = 1;
  UndeleteOptions options = 2;
}

message PublishRequest {
  Item item = 1;
  PublishOptions options = 2;
}

message UnpublishRequest {
  Item item = 1;
  UnpublishOptions options = 2;
}

message GetPublishedRequest {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  string item_id = 5;
  GetPublishedOptions options = 10;
}
message GetPublishedResponse {
  Item item = 1;
}

message FindPublishedRequest {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  Filter filter = 4;
  FindPublishedOptions options = 10;
}
message FindPublishedResponse{
  repeated Item items = 1;
  int32 total = 2;
}

message AggregateRequest {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  Filter filter = 4;
  AggregateOptions options = 10;
}
/**
 * Содержит в себе набор `название:значение`. Название соответствует переданному в AggregateOptions ключу.
 */
message  AggregateResponse{
  google.protobuf.Struct result = 1;
}

message AggregatePublishedRequest {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  Filter filter = 4;
  AggregatePublishedOptions options = 10;
}
message  AggregatePublishedResponse{
  google.protobuf.Struct result = 1;
}

message GetRevisionRequest {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  string item_id = 4;
  string revision_id = 5;
}
message GetRevisionResponse {
  Item item = 1;
}

message ListRevisionsRequest {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  string item_id = 4;
  ListRevisionsOptions options = 10;
}
message ListRevisionsResponse {
  repeated Item items = 1;
}

/**
 * Запрос на архивирование элемента
 */
message ArchiveRequest {
  Item item = 1; // Элемент для архивации
}

message UnarchiveRequest {
  Item item = 1;
}

message FindArchivedRequest {
  string space_id = 1;
  string env_id = 2;
  string collection_id = 3;
  Filter filter = 4;
  FindArchivedOptions options = 6;
}
message FindArchivedResponse{
  repeated Item items = 1;
  int32 total = 2;
}

/**
 * Сервис API элементов
 */
service Items {
  /**
   * Создать запись
   */
  rpc Create(CreateRequest) returns(CreateResponse) {}

  /**
   * Валидация данных записи
   */
  rpc Introspect(IntrospectRequest) returns(IntrospectResponse) {}

  /**
   * Получение записи по идентификатору
   */
  rpc Get(GetRequest) returns(GetResponse) {}

  /**
   * Поиск по текущим записям
   */
  rpc Find(FindRequest) returns(FindResponse) {}
  rpc Update(UpdateRequest) returns(google.protobuf.Empty) {}
  rpc Delete(DeleteRequest) returns(google.protobuf.Empty) {}
  rpc Undelete(UndeleteRequest) returns(google.protobuf.Empty) {}

  rpc Publish(PublishRequest) returns(google.protobuf.Empty) {}
  rpc Unpublish(UnpublishRequest) returns(google.protobuf.Empty) {}
  rpc GetPublished(GetPublishedRequest) returns(GetPublishedResponse) {}
  rpc FindPublished(FindPublishedRequest) returns(FindPublishedResponse) {}

  /**
   * Расчет значений по существующим данным. Например, получение среднего значения поля
   */
  rpc Aggregate(AggregateRequest) returns(AggregateResponse) {}


  /**
   * Расчет значений по существующим **опубликованным** данным.
   */
  rpc AggregatePublished(AggregatePublishedRequest) returns(AggregatePublishedResponse) {}

  rpc GetRevision(GetRevisionRequest) returns(GetRevisionResponse) {}
  rpc ListRevisions(ListRevisionsRequest) returns(ListRevisionsResponse) {}

  rpc Archive(ArchiveRequest) returns(google.protobuf.Empty) {}
  rpc FindArchived(FindArchivedRequest) returns(FindArchivedResponse) {}
  rpc Unarchive(UnarchiveRequest) returns(google.protobuf.Empty) {}
}