Loading documentation...
Preparing Ring Platform content
Концепції, цінність і типові сценарії
Концепції, цінність і типові сценарії
Preparing Ring Platform content
Preparing Ring Platform content
Preparing Ring Platform content
Ring Platform використовує Firebase у двох окремих напрямках — серверний Admin SDK для FCM push і серверних операцій, та клієнтський браузерний SDK для реєстрації push-токенів і відображення сповіщень. Ці напрямки використовують різні стратегії облікових даних і різні версії SDK.
У режимах k8s-postgres-fcm і supabase-fcm Firebase Admin використовується лише для FCM push. Абстракція бази даних (DatabaseService) маршрутизує до PostgreSQL, а не до Firestore. Лише DB_BACKEND_MODE=firebase-full активує Firestore як основне сховище даних.
| Файл | Призначення | Стратегія облікових даних |
|---|---|---|
lib/firebase-admin.server.ts | Singleton Firebase Admin SDK — FCM, Auth, Firestore, RTDB | Завжди явний cert() — потребує AUTH_FIREBASE_CLIENT_EMAIL + AUTH_FIREBASE_PRIVATE_KEY |
lib/database/adapters/FirebaseAdapter.ts | Абстракція бази даних для Firestore (активний лише в режимі firebase-full) | ADC-first — резервний cert() за наявності облікових даних у конфігурації |
lib/services/firebase-service-manager.ts | Кешовані читання Firestore з використанням React 19 cache(), пакетні операції, транзакції | Делегує до firebase-admin.server.ts |
lib/firebase/build-mock.server.ts | Імітація сервісів під час SSG-збірки Next.js — запобігає 22+ зайвим ініціалізаціям | Повертає імітації без підключення |
| Файл | Призначення |
|---|---|
public/firebase-messaging-sw.js | Service worker — Firebase compat SDK v12.9.0 завантажується з CDN, обробляє push-події та фонові повідомлення |
Файл lib/firebase.ts відсутній — клієнтський Firebase ініціалізується виключно всередині service worker через importScripts() з CDN. Реєстрація FCM-токена в браузері відбувається в React-компонентах за допомогою хука use-fcm.ts всередині FCMProvider.
Ваш Ring-клон потребує облікових даних Firebase у двох контекстах:
DB_BACKEND_MODE. Firebase є лише транспортним засобом доставки push; ваші дані додатку залишаються в основній базі даних (PostgreSQL або Firestore).DB_BACKEND_MODE=firebase-full. Firebase Admin SDK слугує основною базою даних.Якщо вам не потрібні push-сповіщення, ви можете опустити всі змінні середовища Firebase. Платформа працює на одному PostgreSQL.
/api/entities/upload)firebase-admin.server.ts, але не використовується в режимі firebase-full)lib/firebase.ts відсутній)Ring Platform використовує Firebase у двох окремих напрямках — серверний Admin SDK для FCM push і серверних операцій, та клієнтський браузерний SDK для реєстрації push-токенів і відображення сповіщень. Ці напрямки використовують різні стратегії облікових даних і різні версії SDK.
У режимах k8s-postgres-fcm і supabase-fcm Firebase Admin використовується лише для FCM push. Абстракція бази даних (DatabaseService) маршрутизує до PostgreSQL, а не до Firestore. Лише DB_BACKEND_MODE=firebase-full активує Firestore як основне сховище даних.
| Файл | Призначення | Стратегія облікових даних |
|---|---|---|
lib/firebase-admin.server.ts | Singleton Firebase Admin SDK — FCM, Auth, Firestore, RTDB | Завжди явний cert() — потребує AUTH_FIREBASE_CLIENT_EMAIL + AUTH_FIREBASE_PRIVATE_KEY |
lib/database/adapters/FirebaseAdapter.ts | Абстракція бази даних для Firestore (активний лише в режимі firebase-full) | ADC-first — резервний cert() за наявності облікових даних у конфігурації |
lib/services/firebase-service-manager.ts | Кешовані читання Firestore з використанням React 19 cache(), пакетні операції, транзакції | Делегує до firebase-admin.server.ts |
lib/firebase/build-mock.server.ts | Імітація сервісів під час SSG-збірки Next.js — запобігає 22+ зайвим ініціалізаціям | Повертає імітації без підключення |
| Файл | Призначення |
|---|---|
public/firebase-messaging-sw.js | Service worker — Firebase compat SDK v12.9.0 завантажується з CDN, обробляє push-події та фонові повідомлення |
Файл lib/firebase.ts відсутній — клієнтський Firebase ініціалізується виключно всередині service worker через importScripts() з CDN. Реєстрація FCM-токена в браузері відбувається в React-компонентах за допомогою хука use-fcm.ts всередині FCMProvider.
Ваш Ring-клон потребує облікових даних Firebase у двох контекстах:
DB_BACKEND_MODE. Firebase є лише транспортним засобом доставки push; ваші дані додатку залишаються в основній базі даних (PostgreSQL або Firestore).DB_BACKEND_MODE=firebase-full. Firebase Admin SDK слугує основною базою даних.Якщо вам не потрібні push-сповіщення, ви можете опустити всі змінні середовища Firebase. Платформа працює на одному PostgreSQL.
/api/entities/upload)firebase-admin.server.ts, але не використовується в режимі firebase-full)lib/firebase.ts відсутній)Ring Platform використовує Firebase у двох окремих напрямках — серверний Admin SDK для FCM push і серверних операцій, та клієнтський браузерний SDK для реєстрації push-токенів і відображення сповіщень. Ці напрямки використовують різні стратегії облікових даних і різні версії SDK.
У режимах k8s-postgres-fcm і supabase-fcm Firebase Admin використовується лише для FCM push. Абстракція бази даних (DatabaseService) маршрутизує до PostgreSQL, а не до Firestore. Лише DB_BACKEND_MODE=firebase-full активує Firestore як основне сховище даних.
| Файл | Призначення | Стратегія облікових даних |
|---|---|---|
lib/firebase-admin.server.ts | Singleton Firebase Admin SDK — FCM, Auth, Firestore, RTDB | Завжди явний cert() — потребує AUTH_FIREBASE_CLIENT_EMAIL + AUTH_FIREBASE_PRIVATE_KEY |
lib/database/adapters/FirebaseAdapter.ts | Абстракція бази даних для Firestore (активний лише в режимі firebase-full) | ADC-first — резервний cert() за наявності облікових даних у конфігурації |
lib/services/firebase-service-manager.ts | Кешовані читання Firestore з використанням React 19 cache(), пакетні операції, транзакції | Делегує до firebase-admin.server.ts |
lib/firebase/build-mock.server.ts | Імітація сервісів під час SSG-збірки Next.js — запобігає 22+ зайвим ініціалізаціям | Повертає імітації без підключення |
| Файл | Призначення |
|---|---|
public/firebase-messaging-sw.js | Service worker — Firebase compat SDK v12.9.0 завантажується з CDN, обробляє push-події та фонові повідомлення |
Файл lib/firebase.ts відсутній — клієнтський Firebase ініціалізується виключно всередині service worker через importScripts() з CDN. Реєстрація FCM-токена в браузері відбувається в React-компонентах за допомогою хука use-fcm.ts всередині FCMProvider.
Ваш Ring-клон потребує облікових даних Firebase у двох контекстах:
DB_BACKEND_MODE. Firebase є лише транспортним засобом доставки push; ваші дані додатку залишаються в основній базі даних (PostgreSQL або Firestore).DB_BACKEND_MODE=firebase-full. Firebase Admin SDK слугує основною базою даних.Якщо вам не потрібні push-сповіщення, ви можете опустити всі змінні середовища Firebase. Платформа працює на одному PostgreSQL.
/api/entities/upload)firebase-admin.server.ts, але не використовується в режимі firebase-full)lib/firebase.ts відсутній)build-mock.server.tsОчищення змінних середовища (важливо):
SDK агресивно очищає вхідні дані змінних середовища — видаляє зовнішні лапки, перетворює \\n на реальні нові рядки, обрізає пробіли. Узгодженість подвійних лапок у env.local.template для AUTH_FIREBASE_PRIVATE_KEY є навмисною:
FirebaseAdapter.ts)FirebaseAdapter реалізує IDatabaseService і використовується лише коли DB_BACKEND_MODE=firebase-full. За замовчуванням він використовує Application Default Credentials (ADC):
Адаптер надає стандартний контракт DatabaseService:
firebase-service-manager.ts)Надає кешовані операції Firebase з використанням React 19 cache() для дедуплікації на один запит. Використовується лише коли getAdminDb() повертає реальний (не імітований) екземпляр Firestore.
Ключові експорти:
| Експорт | Опис |
|---|---|
getCachedDocument(collection, docId) | Одиничний документ з дедуплікацією через cache() |
getCachedCollection(collection, options) | Запит колекції з кешуванням |
getCachedDocumentBatch(requests) | Пакетне отримання кількох документів |
getCachedCollectionAdvanced(collection, queryConfig) | Складні запити (where, orderBy, paginate) |
getCachedSubcollection(parentCol, parentId, subCol, options) | Запити вкладених колекцій |
getCachedCollectionGroup(collectionId, options) | Міжколекційні запити |
createDocument, updateDocument, deleteDocument | Операції запису (без кешування) |
createBatchWriter / executeBatch | Пакетний запис |
runTransaction | Атомні транзакції |
getCacheMetrics / logCachePerformance | Налагоджувальні метрики (лише для розробки) |
Оптимізація на етапі збірки: Усі кешовані функції викликаються лише коли getAdminDb() повертає реальний Firestore. Під час збірки (SSG) методи імітованого Firestore повертають порожні результати, а шар cache() дедуплікує в межах кожного запиту.
build-mock.server.ts)Під час статичної генерації Next.js (NEXT_PHASE=phase-production-build) виклики Firebase Admin перехоплюються імітованими сервісами:
Це запобігає приблизно 22 зайвим ініціалізаціям Firebase Admin під час SSG і скорочує час збірки приблизно на 31%.
Service worker за адресою public/firebase-messaging-sw.js завантажує Firebase compat SDK v12.9.0 з Google CDN:
Service worker підтримує впроваджену під час виконання конфігурацію Firebase через змінні self.* (встановлюються заповнювачами env.local.template на етапі збірки або впроваджуються в розгортаннях k8s).
Процес реєстрації FCM-токена:
'use client' викликає Notification.requestPermission()getToken(messaging, { vapidKey })upsertFcmToken до основної бази даних (PostgreSQL або Firestore залежно від DB_BACKEND_MODE)useAuth().signOut() викликає unregisterCurrentDeviceFcmToken(), яка запускає deleteToken Firebase + інвалідацію на стороні сервера| Аспект | Admin SDK (firebase-admin.server.ts) | Адаптер (FirebaseAdapter.ts) |
|---|---|---|
| Облікові дані | Завжди явний cert() | ADC-first, резервний cert() |
| Змінні середовища | Усі 3 AUTH_FIREBASE_* обов'язкові | Лише AUTH_FIREBASE_PROJECT_ID для ADC |
| Активний у | Усі значення DB_BACKEND_MODE (FCM) | Лише firebase-full |
| Імітація у postgres-primary | Так — повертає імітовані Firestore/Auth | Ні — адаптер не зареєстровано |
| Шлях імпорту | firebase-admin/app, firebase-admin/firestore | Те саме |
| Версія | v14 (іменовані підшляхи імпорту) | v14 |
AUTH_FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----\n"
# Обов'язкові для FCM + ініціалізації Firebase Admin (усі три):
AUTH_FIREBASE_PROJECT_ID=your_firebase_project_id
AUTH_FIREBASE_CLIENT_EMAIL=your_firebase_client_email
AUTH_FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
# Опціонально:
FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com
FIREBASE_PRIVATE_KEY_ID=your_firebase_private_key_id
FIREBASE_CLIENT_ID="your_firebase_client_id"
FIREBASE_FIRESTORE_DEBUG=true
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_firebase_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-YCZKPV315E
NEXT_PUBLIC_FIREBASE_VAPID_KEY=your_vapid_keybuild-mock.server.tsОчищення змінних середовища (важливо):
SDK агресивно очищає вхідні дані змінних середовища — видаляє зовнішні лапки, перетворює \\n на реальні нові рядки, обрізає пробіли. Узгодженість подвійних лапок у env.local.template для AUTH_FIREBASE_PRIVATE_KEY є навмисною:
FirebaseAdapter.ts)FirebaseAdapter реалізує IDatabaseService і використовується лише коли DB_BACKEND_MODE=firebase-full. За замовчуванням він використовує Application Default Credentials (ADC):
Адаптер надає стандартний контракт DatabaseService:
firebase-service-manager.ts)Надає кешовані операції Firebase з використанням React 19 cache() для дедуплікації на один запит. Використовується лише коли getAdminDb() повертає реальний (не імітований) екземпляр Firestore.
Ключові експорти:
| Експорт | Опис |
|---|---|
getCachedDocument(collection, docId) | Одиничний документ з дедуплікацією через cache() |
getCachedCollection(collection, options) | Запит колекції з кешуванням |
getCachedDocumentBatch(requests) | Пакетне отримання кількох документів |
getCachedCollectionAdvanced(collection, queryConfig) | Складні запити (where, orderBy, paginate) |
getCachedSubcollection(parentCol, parentId, subCol, options) | Запити вкладених колекцій |
getCachedCollectionGroup(collectionId, options) | Міжколекційні запити |
createDocument, updateDocument, deleteDocument | Операції запису (без кешування) |
createBatchWriter / executeBatch | Пакетний запис |
runTransaction | Атомні транзакції |
getCacheMetrics / logCachePerformance | Налагоджувальні метрики (лише для розробки) |
Оптимізація на етапі збірки: Усі кешовані функції викликаються лише коли getAdminDb() повертає реальний Firestore. Під час збірки (SSG) методи імітованого Firestore повертають порожні результати, а шар cache() дедуплікує в межах кожного запиту.
build-mock.server.ts)Під час статичної генерації Next.js (NEXT_PHASE=phase-production-build) виклики Firebase Admin перехоплюються імітованими сервісами:
Це запобігає приблизно 22 зайвим ініціалізаціям Firebase Admin під час SSG і скорочує час збірки приблизно на 31%.
Service worker за адресою public/firebase-messaging-sw.js завантажує Firebase compat SDK v12.9.0 з Google CDN:
Service worker підтримує впроваджену під час виконання конфігурацію Firebase через змінні self.* (встановлюються заповнювачами env.local.template на етапі збірки або впроваджуються в розгортаннях k8s).
Процес реєстрації FCM-токена:
'use client' викликає Notification.requestPermission()getToken(messaging, { vapidKey })upsertFcmToken до основної бази даних (PostgreSQL або Firestore залежно від DB_BACKEND_MODE)useAuth().signOut() викликає unregisterCurrentDeviceFcmToken(), яка запускає deleteToken Firebase + інвалідацію на стороні сервера| Аспект | Admin SDK (firebase-admin.server.ts) | Адаптер (FirebaseAdapter.ts) |
|---|---|---|
| Облікові дані | Завжди явний cert() | ADC-first, резервний cert() |
| Змінні середовища | Усі 3 AUTH_FIREBASE_* обов'язкові | Лише AUTH_FIREBASE_PROJECT_ID для ADC |
| Активний у | Усі значення DB_BACKEND_MODE (FCM) | Лише firebase-full |
| Імітація у postgres-primary | Так — повертає імітовані Firestore/Auth | Ні — адаптер не зареєстровано |
| Шлях імпорту | firebase-admin/app, firebase-admin/firestore | Те саме |
| Версія | v14 (іменовані підшляхи імпорту) | v14 |
AUTH_FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----\n"
# Обов'язкові для FCM + ініціалізації Firebase Admin (усі три):
AUTH_FIREBASE_PROJECT_ID=your_firebase_project_id
AUTH_FIREBASE_CLIENT_EMAIL=your_firebase_client_email
AUTH_FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
# Опціонально:
FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com
FIREBASE_PRIVATE_KEY_ID=your_firebase_private_key_id
FIREBASE_CLIENT_ID="your_firebase_client_id"
FIREBASE_FIRESTORE_DEBUG=true
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_firebase_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-YCZKPV315E
NEXT_PUBLIC_FIREBASE_VAPID_KEY=your_vapid_keybuild-mock.server.tsОчищення змінних середовища (важливо):
SDK агресивно очищає вхідні дані змінних середовища — видаляє зовнішні лапки, перетворює \\n на реальні нові рядки, обрізає пробіли. Узгодженість подвійних лапок у env.local.template для AUTH_FIREBASE_PRIVATE_KEY є навмисною:
FirebaseAdapter.ts)FirebaseAdapter реалізує IDatabaseService і використовується лише коли DB_BACKEND_MODE=firebase-full. За замовчуванням він використовує Application Default Credentials (ADC):
Адаптер надає стандартний контракт DatabaseService:
firebase-service-manager.ts)Надає кешовані операції Firebase з використанням React 19 cache() для дедуплікації на один запит. Використовується лише коли getAdminDb() повертає реальний (не імітований) екземпляр Firestore.
Ключові експорти:
| Експорт | Опис |
|---|---|
getCachedDocument(collection, docId) | Одиничний документ з дедуплікацією через cache() |
getCachedCollection(collection, options) | Запит колекції з кешуванням |
getCachedDocumentBatch(requests) | Пакетне отримання кількох документів |
getCachedCollectionAdvanced(collection, queryConfig) | Складні запити (where, orderBy, paginate) |
getCachedSubcollection(parentCol, parentId, subCol, options) | Запити вкладених колекцій |
getCachedCollectionGroup(collectionId, options) | Міжколекційні запити |
createDocument, updateDocument, deleteDocument | Операції запису (без кешування) |
createBatchWriter / executeBatch | Пакетний запис |
runTransaction | Атомні транзакції |
getCacheMetrics / logCachePerformance | Налагоджувальні метрики (лише для розробки) |
Оптимізація на етапі збірки: Усі кешовані функції викликаються лише коли getAdminDb() повертає реальний Firestore. Під час збірки (SSG) методи імітованого Firestore повертають порожні результати, а шар cache() дедуплікує в межах кожного запиту.
build-mock.server.ts)Під час статичної генерації Next.js (NEXT_PHASE=phase-production-build) виклики Firebase Admin перехоплюються імітованими сервісами:
Це запобігає приблизно 22 зайвим ініціалізаціям Firebase Admin під час SSG і скорочує час збірки приблизно на 31%.
Service worker за адресою public/firebase-messaging-sw.js завантажує Firebase compat SDK v12.9.0 з Google CDN:
Service worker підтримує впроваджену під час виконання конфігурацію Firebase через змінні self.* (встановлюються заповнювачами env.local.template на етапі збірки або впроваджуються в розгортаннях k8s).
Процес реєстрації FCM-токена:
'use client' викликає Notification.requestPermission()getToken(messaging, { vapidKey })upsertFcmToken до основної бази даних (PostgreSQL або Firestore залежно від DB_BACKEND_MODE)useAuth().signOut() викликає unregisterCurrentDeviceFcmToken(), яка запускає deleteToken Firebase + інвалідацію на стороні сервера| Аспект | Admin SDK (firebase-admin.server.ts) | Адаптер (FirebaseAdapter.ts) |
|---|---|---|
| Облікові дані | Завжди явний cert() | ADC-first, резервний cert() |
| Змінні середовища | Усі 3 AUTH_FIREBASE_* обов'язкові | Лише AUTH_FIREBASE_PROJECT_ID для ADC |
| Активний у | Усі значення DB_BACKEND_MODE (FCM) | Лише firebase-full |
| Імітація у postgres-primary | Так — повертає імітовані Firestore/Auth | Ні — адаптер не зареєстровано |
| Шлях імпорту | firebase-admin/app, firebase-admin/firestore | Те саме |
| Версія | v14 (іменовані підшляхи імпорту) | v14 |
AUTH_FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQ...\n-----END PRIVATE KEY-----\n"
# Обов'язкові для FCM + ініціалізації Firebase Admin (усі три):
AUTH_FIREBASE_PROJECT_ID=your_firebase_project_id
AUTH_FIREBASE_CLIENT_EMAIL=your_firebase_client_email
AUTH_FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
# Опціонально:
FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com
FIREBASE_PRIVATE_KEY_ID=your_firebase_private_key_id
FIREBASE_CLIENT_ID="your_firebase_client_id"
FIREBASE_FIRESTORE_DEBUG=true
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_firebase_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-YCZKPV315E
NEXT_PUBLIC_FIREBASE_VAPID_KEY=your_vapid_key