2026-07-07 - Системная Google авторизация и доступ приложения к Google Drive

Статус: Задачи созданы

Источник: Дубко Олег. Требуется для публикации проекта в гугл консоли

YouGile:

Эпик: ITR-2667
Backend: ITR-2676
Frontend: ITR-2675
Backend redirect: ITR-2677

Контекст

После уменьшения прав системной Google-авторизации до ограниченного доступа к Google Drive необходимо дать администратору понятный инструмент для проверки и предоставления доступа приложению к нужным папкам и файлам.

Раньше системная учетная запись могла работать с широким доступом к Google Drive. После перехода на ограниченный доступ система должна явно видеть только те ресурсы, к которым администратор предоставил доступ.

Текущее поведение

В личном кабинете администратора есть отдельные кнопки для Google-авторизации и активации доступа.
Страница Google-авторизации показывает только результат callback: успешно или ошибка.
Нет единой страницы, где видно состояние системного Google-токена, сервисной учетной записи и доступов к обязательным Google-ресурсам.
Администратору не видно, к какому именно файлу или папке не хватает доступа и зачем этот доступ нужен.

Желаемое поведение

В личном кабинете администратора должна остаться одна кнопка: Системная Google авторизация.
Кнопка открывает отдельную страницу настройки системной Google-авторизации.
Страница при загрузке запрашивает состояние системной авторизации и доступов к Google-ресурсам.
Администратор видит:
- статус системной Google-авторизации;
- Google-аккаунт, через который выполнена системная авторизация;
- email сервисной учетной записи;
- список обязательных ресурсов Google Drive;
- назначение каждого ресурса;
- текущий статус доступа;
- действие, которое нужно выполнить для предоставления доступа.
После прохождения системной Google-авторизации callback должен возвращать пользователя на новую страницу.

Backend. Проверка системной Google-авторизации

Создать GET endpoint, доступный только администратору.

Endpoint проверяет:

наличие системного Google refresh token в Vault;
валидность системного Google refresh token;
email Google-аккаунта, для которого сохранен системный токен;
email сервисной учетной записи из service_key_json;
доступ к обязательным ресурсам, указанным в GoogleConfig.

Endpoint возвращает структурированный response.

type GoogleSystemAccessStatusResponse = {
  authStatus: 'authorized' | 'missingToken' | 'invalidToken' | 'checkFailed';
  serviceAccountEmail?: string;
  systemGoogleEmail?: string;
  resources: GoogleDriveResourceAccess[];
};

type GoogleDriveResourceAccess = {
  id: string;
  link: string;
  key: string;
  name: string;
  type: 'folder' | 'spreadsheet';
  accessGrantMethod: 'picker' | 'serviceAccountEmail';
  status: 'available' | 'missing' | 'checkFailed';
  usageDescription: string;
};

Пример ресурса:

{
  "id": "1AXtFfL_2IJwFV9lF7UzrkQNZZy55_SIv",
  "link": "https://drive.google.com/drive/folders/1AXtFfL_2IJwFV9lF7UzrkQNZZy55_SIv",
  "key": "OrdersFolderId",
  "name": "Папка заказов на производство",
  "type": "folder",
  "accessGrantMethod": "picker",
  "status": "missing",
  "usageDescription": "Используется для создания Google-таблиц заказов на производство."
}

CheckFailed использовать только когда проверку не удалось выполнить технически. Отсутствие доступа к ресурсу должно возвращаться как Missing, а не как CheckFailed.

Frontend. Страница системной Google-авторизации

Создать страницу Системная Google авторизация.

В личном кабинете администратора:

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

Верх страницы

Показать компактный статус:

Системная авторизация: выполнена / не выполнена / токен невалидный / проверка не выполнена;
Google аккаунт: email аккаунта из системного токена;
Service account: email сервисной учетной записи.

Кнопки:

Выполнить Google авторизацию;
Перепроверить доступ.

Основная часть

Показать таблицу ресурсов:

Ресурс	Для чего нужен	Доступ	Статус	Действие

В таблице отображать:

название ресурса;
описание, для чего нужен доступ;
тип ресурса: папка или таблица;
статус доступа;
ссылку на ресурс;
доступное действие.

Действия в строках

Если status === 'available':

показать зеленый статус Доступ есть;
показать кнопку Открыть.

Если status === 'available' && type === 'folder':

дополнительно показать кнопку Открыть доступ к дочерним файлам.

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

Если status === 'missing' && accessGrantMethod === 'picker':

показать кнопку Предоставить доступ;
по клику открыть Google Picker с фильтрацией по ожидаемому ресурсу;
после выбора проверить, что выбран именно ожидаемый ресурс;
после успешного выбора повторно вызвать endpoint проверки статуса.

Если status === 'missing' && accessGrantMethod === 'serviceAccountEmail':

показать текст Дайте доступ сервисной учетной записи;
показать кнопку Скопировать email;
показать кнопку Открыть ресурс.

Google Picker

Для конкретного ресурса попробовать фильтровать Picker по ожидаемому id.

const view = new google.picker.DocsView()
  .setFileIds(resource.id)
  .setIncludeFolders(resource.type === 'folder')
  .setSelectFolderEnabled(resource.type === 'folder');

После выбора:

if (picked.id !== resource.id) {
  showError('Выбран другой ресурс');
  return;
}

await refetchStatus();

Если фильтрация по id не позволит удобно выбрать ресурс, допустимо использовать поиск по названию как вспомогательный сценарий, но итоговая проверка выбранного id обязательна.

Важно: На странице нужно показывать systemGoogleEmail, чтобы администратор понимал, какой аккаунт выбирать в Google.

Backend. Redirect после системной Google-авторизации

Изменить redirect после callback системной Google-авторизации:

при успехе возвращать пользователя на новую страницу системной Google-авторизации с признаком успешной авторизации;
при ошибке возвращать на эту же страницу с текстом ошибки.

Пример:

/google-system-auth?success=true
/google-system-auth?error=...

После возврата на страницу frontend должен повторно запросить состояние авторизации и доступов.

Критерии приемки

Администратор может открыть отдельную страницу системной Google-авторизации.
Страница показывает состояние системного Google-токена.
Страница показывает Google-аккаунт системной авторизации.
Страница показывает email сервисной учетной записи.
Страница показывает список обязательных Google-ресурсов.
Для каждого ресурса видно, зачем нужен доступ.
Для каждого ресурса видно, есть доступ или нет.
Для ресурсов, доступ к которым выдается через Picker, можно открыть Google Picker и выбрать ожидаемый ресурс.
После выбора ресурса frontend проверяет, что выбранный id совпадает с ожидаемым.
После предоставления доступа страница умеет повторно проверить доступ.
Для ресурсов сервисной учетной записи можно скопировать email service account.
Callback системной Google-авторизации возвращает пользователя на новую страницу.

Открытые уточнения

Определить полный список обязательных ресурсов из GoogleConfig и для каждого ресурса указать name, usageDescription, type и accessGrantMethod.
Определить, какие ресурсы должны проверяться через системный OAuth-токен, а какие через service account.
Уточнить название маршрута новой страницы. Предварительно: /google-system-auth.
Проверить сценарий после фактического перехода scope системной авторизации на ограниченный доступ Google Drive.

Контекст​

Текущее поведение​

Желаемое поведение​

Backend. Проверка системной Google-авторизации​

Frontend. Страница системной Google-авторизации​

Верх страницы​

Основная часть​

Действия в строках​

Google Picker​

Backend. Redirect после системной Google-авторизации​

Критерии приемки​

Открытые уточнения​