Добавлена документация по логике работы миграции окружения и входящих в него коллекций

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;

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) {}
 }

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