From 8c4815fc25ce4fa237f2b71dababa78186817ab5 Mon Sep 17 00:00:00 2001
From: Alena Petraki <alena.petraki@gmail.com>
Date: Thu, 20 Jul 2023 16:22:33 +0300
Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?=
 =?UTF-8?q?=D0=BD=D0=B0=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82?=
 =?UTF-8?q?=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BF=D0=BE=20=D0=BB=D0=BE=D0=B3?=
 =?UTF-8?q?=D0=B8=D0=BA=D0=B5=20=D1=80=D0=B0=D0=B1=D0=BE=D1=82=D1=8B=20?=
 =?UTF-8?q?=D0=BC=D0=B8=D0=B3=D1=80=D0=B0=D1=86=D0=B8=D0=B8=20=D0=BE=D0=BA?=
 =?UTF-8?q?=D1=80=D1=83=D0=B6=D0=B5=D0=BD=D0=B8=D1=8F=20=D0=B8=20=D0=B2?=
 =?UTF-8?q?=D1=85=D0=BE=D0=B4=D1=8F=D1=89=D0=B8=D1=85=20=D0=B2=20=D0=BD?=
 =?UTF-8?q?=D0=B5=D0=B3=D0=BE=20=D0=BA=D0=BE=D0=BB=D0=BB=D0=B5=D0=BA=D1=86?=
 =?UTF-8?q?=D0=B8=D0=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 proto/clients/clients.proto           |  7 +------
 proto/collections/collections.proto   | 28 ++++++++++++++++++++++++++-
 proto/environments/environments.proto |  8 ++++++++
 3 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/proto/clients/clients.proto b/proto/clients/clients.proto
index c20c5d4..8716932 100644
--- a/proto/clients/clients.proto
+++ b/proto/clients/clients.proto
@@ -36,12 +36,7 @@ message Client {
   // Приложение отключено и не может авторизоваться
   optional bool disabled = 7;
 
-//  // Приложение имеет доступ к указанным окружениям пространства (ID или Alias)
-//  repeated string environments = 8;
-//
-//  // Список правил доступа к коллекциям
-//  repeated common.Rule rules = 9;
-
+  // Идентификатор роли клиента
   string role_id = 8;
 
   OAuth oauth = 10;
diff --git a/proto/collections/collections.proto b/proto/collections/collections.proto
index c182a94..e7dd51f 100644
--- a/proto/collections/collections.proto
+++ b/proto/collections/collections.proto
@@ -20,8 +20,14 @@ message Collection {
   string space_id = 2;
   string env_id = 3;
   string name = 4;
+
+  // Коллекция может содержать ровно одну запись. При работе с записью в такой коллекции идентификатор записи в
+  // обращениях в API можно не указывать и предполагать, что запись всегда есть (ее не нужно создавать)
   optional bool single = 5;
   optional bool system = 6;
+
+  // Коллекция не содержит данных. Возможно создание таких коллекций для использования как подключаемые подсхемы в
+  // других коллекциях
   optional bool no_data = 12;
   string schema = 7;
   bool hidden = 13;
@@ -49,7 +55,7 @@ message Collection {
   StateInfo state_info = 10;
 
   repeated string tags = 16;
-  Access access = 20;
+  Access access = 20; // Возможные действия с коллекцией на основе контекста запроса
 }
 
 message CreateRequest {
@@ -110,10 +116,30 @@ message DeleteRequest {
 }
 
 service Collections  {
+
+  // Создать коллекцию. Установка схемы производится через отдельный метод `SetSchema` и методом `Create` игнорируется
   rpc Create(CreateRequest) returns(CreateResponse) {}
+
+  // Получить коллекцию. Схема коллекции возвращается полная, т.е. включая все подключаемые подсхемы, если не указано
+  // обратное в `GetRequest.options`
   rpc Get(GetRequest) returns(GetResponse) {}
+
+  // Возвращает список коллекций, отсортированных в алфавитном порядке. По умолчанию не возвращает коллекции без данных
+  // и скрытые коллекции, подробнее см. `ListRequest.filter`
   rpc List(ListRequest) returns(ListResponse) {}
+
+  // Обновить коллекцию. Установка схемы производится через отдельный метод `SetSchema` и методом `Update` игнорируется
   rpc Update(UpdateRequest) returns(google.protobuf.Empty) {}
+
+  // Установить схему коллекции. По результатам вызова метода не происходит *применение* схемы - например,
+  // не перестраиваются индексы БД коллекции, поскольку это может быть длительный процесс. После редактирования всех
+  // необходимых схем окружения необходимо их применить - выполнить миграцию путем вызова метода `Environments.Migrate`.
+  // Если схема коллекции изменена, но миграция еще не была запущена, коллекция будет находиться в состоянии `CHANGED`.
+  //
+  // Если в процессе миграции возникли ошибки, в соответствующие коллекции в поле `Collection.state_info` будет записано
+  // содержание ошибки и установлено состояние `ERROR`
   rpc SetSchema(SetSchemaRequest) returns(google.protobuf.Empty) {}
+
+  // Удалить коллекцию
   rpc Delete(DeleteRequest) returns(google.protobuf.Empty) {}
 }
diff --git a/proto/environments/environments.proto b/proto/environments/environments.proto
index 19f2e0c..2d6bb83 100644
--- a/proto/environments/environments.proto
+++ b/proto/environments/environments.proto
@@ -103,5 +103,13 @@ service Environments {
   rpc SetAlias(SetAliasRequest) returns(google.protobuf.Empty) {}
   rpc RemoveAlias(RemoveAliasRequest) returns(google.protobuf.Empty) {}
   rpc Delete(DeleteRequest) returns(google.protobuf.Empty) {}
+
+  // Выполнить миграцию окружения. По умолчанию выполняется в асинхронном режиме, для синхронного выполнения можно
+  // передать соответствующую настройку в опциях `MigrateRequest.options`
+  //
+  // При вызове миграции:
+  // - выполняются миграции для всех коллекций окружения
+  //
+  // В случае возникновения ошибок миграции они записываются в поле `Environment.state`
   rpc Migrate(MigrateRequest) returns(google.protobuf.Empty) {}
 }
\ No newline at end of file
-- 
GitLab