vvzvlad/gitmost
1
0
Fork 0
Code Issues 14 Pull Requests 12 Packages Projects Releases Activity
Files
10fe605159324ffa94ec1bed624ae5900df7339e
gitmost/docs/offline-sync-plan.md
vvzvlad e6bda21255 docs: add offline sync & PWA implementation plan 
Add docs/offline-sync-plan.md — a ready-to-implement design document for
offline editing and synchronization in gitmost.

- Describes current state: Yjs/Hocuspocus + y-indexeddb for document body
  (CRDT, offline-ready) vs REST-based structural data (online-only).
- Clarifies that PWA installability already exists (inherited from Docmost);
  the missing piece is a service worker for offline app-shell.
- Defines two sync contours (CRDT body / outbox+LWW for REST) and a staged
  plan M0..M4 with per-step files, acceptance criteria and risks.
- Includes conflict-resolution rules, pitfalls, npm deps, open questions
  and an implementation checklist.
2026-06-16 23:26:08 +03:00

394 lines
30 KiB
Markdown
Raw Blame History

# Offline-режим и синхронизация правок в gitmost
> Статус: проектный документ, готов к реализации.
> Контекст: gitmost — форк Docmost. Сейчас приложение полностью онлайн.
> Цель: дать возможность работать оффлайн (читать и редактировать) и
> синхронизироваться при возврате сети.
Документ описывает текущее устройство, целевую архитектуру и пошаговый план
реализации с привязкой к конкретным файлам. Его можно взять и реализовывать
по этапам M0…M4.
---
## 1. TL;DR
1. **Половина оффлайна уже встроена.** Тело страницы редактируется через Yjs
(CRDT) + Hocuspocus, а на клиенте уже подключён `y-indexeddb`. Правки тела
*уже открытой* страницы переживают потерю сети и **сами мёржатся** при
реконнекте — без конфликтов.
2. **«Полностью онлайн» — это всё вокруг тела документа:** загрузка самого
приложения, навигация (дерево/список), заголовки страниц, комментарии,
создание/перемещение/удаление страниц, вложения, авторизация.
3. **Оффлайн делится на два контура с разными механизмами синхронизации:**
- **Контур A — тело документа:** CRDT (Yjs). Почти готов, нужно укрепить.
- **Контур B — структурные данные (REST):** не CRDT. Нужен паттерн
*локальный кэш + outbox (очередь мутаций) + правила разрешения конфликтов*.
4. **PWA — обязательный фундамент, но это два слоя:**
- *Installability* (manifest + meta-теги) — **уже есть** в gitmost
(унаследовано от Docmost). Forkmost добавляет только косметику.
- *Service worker* (кэш app-shell, запуск без сети) — **нет нигде**, это и
есть реальная невыполненная часть. Без него установленное приложение без
сети покажет пустой экран.
---
## 2. Текущее состояние (как есть)
### 2.1. Контур A: тело документа — CRDT, почти готово
| Где | Что делает |
|---|---|
| [page-editor.tsx](../apps/client/src/features/editor/page-editor.tsx) (L131–206) | На каждую страницу создаётся `Y.Doc`, к нему цепляются `IndexeddbPersistence("page.<id>")` (локальная копия) **и** `HocuspocusProvider` (WS-синк). |
| [persistence.extension.ts](../apps/server/src/collaboration/extensions/persistence.extension.ts) | Сервер в `onStoreDocument` хранит в Postgres бинарный `ydoc` (Y state update) **плюс** отрендеренный tiptap-JSON `content` + `textContent`. В `onLoadDocument` поднимает `ydoc` обратно. |
| [collaboration/extensions/redis-sync/](../apps/server/src/collaboration/extensions/redis-sync/) | Redis-синк для горизонтального масштабирования инстансов. |
Почему это и есть оффлайн-редактирование: Yjs — CRDT, апдейты коммутативны.
Пока клиент оффлайн, изменения копятся в `Y.Doc` и в IndexedDB; при возврате
сети `HocuspocusProvider` обменивается state-векторами и **детерминированно
сливает** правки. Конфликтов «кто кого перезаписал» в теле документа нет.
### 2.2. Контур B: структурные данные — обычный REST, оффлайн недоступен
| Сущность | Где | Механизм |
|---|---|---|
| Заголовок страницы | [title-editor.tsx](../apps/client/src/features/editor/title-editor.tsx) (L48–152) | REST `/pages/update`, дебаунс 500 мс. **НЕ Yjs.** |
| CRUD страниц, move, restore | [page-service.ts](../apps/client/src/features/page/services/page-service.ts) | REST `/pages/*` |
| Комментарии | [comment-service.ts](../apps/client/src/features/comment/services/comment-service.ts) | REST `/comments/*` |
| Watchers, favorites, labels, дерево, поиск | соответствующие `features/*/services` | REST |
Состояние клиента:
- React Query: [main.tsx](../apps/client/src/main.tsx) (L26), `queryClient`
экспортируется, `retry:false`, `staleTime: 5 мин`. **Персистентности на диск
нет.** При перезагрузке без сети читать нечего.
- HTTP: [api-client.ts](../apps/client/src/lib/api-client.ts) — axios `/api`,
`withCredentials`. На `401` → `redirectToLogin()`. **Важно для оффлайна:**
редирект на логин при сетевой ошибке недопустим (см. M4).
### 2.3. PWA: что уже есть
- [manifest.json](../apps/client/public/manifest.json) — присутствует
(`display: standalone`, иконки).
- [index.html](../apps/client/index.html) (L9–16) — PWA meta-теги
(`apple-mobile-web-app-capable`, `mobile-web-app-capable`, `theme-color` и т.д.).
- **Service worker отсутствует.** Нет `vite-plugin-pwa`, Workbox, precache.
> Вывод по Forkmost (`Vito0912/forkmost`): их «PWA-наработки» — это только
> манифест и meta-теги (closing issue Docmost #328 про *устанавливаемость*).
> Service worker / оффлайн-кэша там нет. В gitmost installability уже есть,
> поэтому из Forkmost переносить нечего, кроме косметики.
### 2.4. Полезные примитивы, которые уже есть в проекте
- **Fractional indexing для позиций страниц:**
[page.service.ts](../apps/server/src/core/page/services/page.service.ts)
использует `generateJitteredKeyBetween` из `fractional-indexing-jittered`.
Позиция — это строковый ключ (`position: string`), «jittered»-вариант
специально снижает коллизии при конкурентных/оффлайн-вставках. Это готовый
offline-friendly примитив для перемещений в дереве.
- **Генерация ID:**
[nanoid.utils.ts](../apps/server/src/common/helpers/nanoid.utils.ts) —
`generateSlugId` (10 симв.) и `nanoIdGen`. ID можно генерировать на клиенте и
принимать на сервере (нужно для оффлайн-создания, см. M3).
---
## 3. Целевая архитектура
```
┌──────────────────────── Браузер (PWA) ────────────────────────┐
│ │
Тело документа │ TipTap ⟷ Y.Doc ⟷ IndexeddbPersistence (локальная копия) │
(Контур A, CRDT) │ │ │
│ └── HocuspocusProvider ──┐ │
│ │ │
Структурные данные │ React Query (read) ⟵ IndexedDB persister │ │
(Контур B, REST) │ Мутации ⟶ Outbox (IndexedDB) ──────────┐ │ │
│ │ │ │
App shell │ Service Worker (Workbox precache) │ │ │
└──────────────────────────────────────────┼────┼───────────────┘
│ │
(reconnect) ▼ ▼
┌──────────────────────── Сервер ───────────────────────────────┐
│ REST API (idempotent upsert по client-id) Hocuspocus (Yjs) │
│ │ │ │
│ └────────────── Postgres ───────────────┘ │
└────────────────────────────────────────────────────────────────┘
```
Два независимых канала синхронизации:
- **Контур A** синкается сам через Hocuspocus (Yjs). Руками конфликты не решаем.
- **Контур B** синкается через outbox: оффлайн-мутации пишутся в журнал в
IndexedDB и проигрываются на сервер при реконнекте; конфликты решаются
явными правилами (LWW / per-entity).
---
## 4. План реализации по этапам
Этапы инкрементальны: каждый даёт пользователю ощутимый результат и может быть
смёржен отдельно. Рекомендуемый порядок — строго M0 → M4.
### M0 — PWA shell (фундамент: приложение запускается без сети)
**Зачем:** без service worker установленное приложение без сети не загрузится.
Это разблокирует всё остальное.
**Что сделать:**
1. Добавить `vite-plugin-pwa` (Workbox под капотом) в
[vite.config.ts](../apps/client/vite.config.ts).
- `registerType: 'autoUpdate'` или `prompt` (см. риск R3).
- `workbox.globPatterns` — прекэш JS/CSS/wasm/шрифтов/иконок.
- `manifest: false` или генерация из существующего
[manifest.json](../apps/client/public/manifest.json) (не дублировать).
- Навигационный fallback на `index.html` для SPA-роутов.
- Runtime caching: `CacheFirst` для статики, **`NetworkOnly` для `/api/**`
и `/collab`** на этом этапе (REST-кэш появится в M2; SW не должен молча
отдавать устаревшие ответы API).
2. Зарегистрировать SW в [main.tsx](../apps/client/src/main.tsx)
(`registerSW` из `virtual:pwa-register`).
3. Перенести косметику манифеста/метатегов из Forkmost при желании (бренд,
`orientation`, `msapplication-*`). Опционально, на оффлайн не влияет.
**Файлы:** `apps/client/vite.config.ts`, `apps/client/src/main.tsx`,
`apps/client/public/manifest.json`, `apps/client/index.html`.
**Критерий приёмки:** приложение устанавливается, после первой загрузки
открывается **без сети** (виден shell/лэйаут, а не пустой экран);
обновление версии SW не ломает открытую сессию.
**Риск:** низкий. Изолированный слой, кода приложения не трогает.
---
### M1 — Укрепление оффлайна тела документа (Контур A)
**Зачем:** убрать известные грабли Yjs и сделать поведение предсказуемым.
**Что сделать:**
1. **Закрыть ловушку «rebuild ydoc из JSON».** В
[persistence.extension.ts](../apps/server/src/collaboration/extensions/persistence.extension.ts)
`onLoadDocument` при пустом `page.ydoc` пересобирает документ из
`page.content` через `TiptapTransformer.toYdoc(...)`. Если это сработает,
пока оффлайн-клиент держит свой `Y.Doc` со своими client-id, при мёрже
возможно **дублирование контента** (классическая Yjs-ловушка).
- Гарантировать, что `ydoc` всегда персистится (после первого сохранения он
есть) и ветка rebuild не выполняется для страниц, у которых живут
оффлайн-клиенты. Минимум — единожды мигрировать `content → ydoc` для всех
страниц и далее считать `ydoc` единственным источником правды для тела.
2. **Индикатор оффлайна/синка в UI.** Уже есть `yjsConnectionStatusAtom` и
`isLocalSynced/isRemoteSynced` в
[page-editor.tsx](../apps/client/src/features/editor/page-editor.tsx).
Показать состояние («оффлайн», «есть несинхронизированные правки»,
«синхронизировано»).
3. **Заголовок страницы → в Yjs (рекомендуется).**
[title-editor.tsx](../apps/client/src/features/editor/title-editor.tsx)
сохраняет заголовок REST-ом (дебаунс 500 мс) — оффлайн это не работает и
расходится с телом. Варианты:
- (a) перенести заголовок в тот же `Y.Doc` (чистое CRDT-решение), либо
- (b) тащить заголовок через outbox из M3 (LWW). Решение зафиксировать
до старта M3 (см. открытый вопрос Q1).
**Файлы:** `apps/server/src/collaboration/extensions/persistence.extension.ts`,
`apps/client/src/features/editor/page-editor.tsx`,
`apps/client/src/features/editor/title-editor.tsx` (если вариант a).
**Критерий приёмки:** правки тела уже открытой страницы, сделанные оффлайн,
после реконнекта появляются на сервере и у других клиентов без дублей и потерь;
в UI виден статус синка.
**Риск:** средний (Yjs-семантика, миграция `content → ydoc`).
---
### M2 — Оффлайн-чтение и навигация (Контур B, read-path)
**Зачем:** оффлайн нужно видеть дерево, список и метаданные, иначе некуда
переходить; и нужно префетчить страницы «на оффлайн».
**Что сделать:**
1. **Персист React Query на диск.** Обернуть экспортируемый `queryClient` из
[main.tsx](../apps/client/src/main.tsx) в
`PersistQueryClientProvider` с IndexedDB-persister
(`@tanstack/query-persist-client-core` + idb-хранилище).
- Кэшировать: дерево пространства, список страниц, метаданные страницы,
комментарии. Выставить разумный `maxAge`/`gcTime`.
- Версионировать кэш (`buster`) по версии приложения, чтобы не «залипал»
после деплоя.
2. **«Сделать доступным оффлайн».** Действие для пространства/ветки: префетч
метаданных **и** прогрев `IndexeddbPersistence` для тел страниц (открыть/
подгрузить `ydoc` каждой целевой страницы заранее), т.к. сейчас локально
лежат только *ранее открытые* страницы.
3. **Runtime caching API в SW (read-only).** Для GET-эндпоинтов навигации —
`StaleWhileRevalidate`/`NetworkFirst` с фолбэком на кэш. Мутации (POST) —
по-прежнему мимо кэша (их берёт на себя M3).
**Файлы:** `apps/client/src/main.tsx`, новый модуль
`apps/client/src/lib/offline/` (persister, prefetch), точечно — хуки списков/
дерева в `features/page/tree`.
**Критерий приёмки:** после прогрева и ухода в оффлайн пользователь видит дерево
и список, открывает заранее подготовленные страницы и читает их тело и
комментарии.
**Риск:** средний (консистентность кэша, инвалидция после деплоя).
---
### M3 — Outbox для мутаций (Контур B, write-path) — ядро оффлайн-синка
**Зачем:** дать оффлайн-создание/редактирование структурных данных с
последующим проигрыванием на сервер.
**Что сделать:**
1. **Очередь мутаций (outbox) в IndexedDB.** Журнал операций
`{ id, entity, op, payload, clientId, baseVersion, createdAt, status }`.
Использовать **offline/paused mutations TanStack Query**
(`onlineManager` + `queryClient.resumePausedMutations()` + персист пауз),
либо отдельный модуль `apps/client/src/lib/offline/outbox.ts`.
2. **Клиентская генерация ID.** Для оффлайн-создания страниц/комментариев
генерировать `id`/`slugId` на клиенте тем же алфавитом, что и
[nanoid.utils.ts](../apps/server/src/common/helpers/nanoid.utils.ts).
Для позиций в дереве — `generateJitteredKeyBetween` из
`fractional-indexing-jittered` (тот же пакет, что на сервере).
3. **Идемпотентный upsert на сервере.** Эндпоинты `/pages/create`,
`/comments/create` и т.д. должны принимать клиентский `id` и быть
идемпотентными по нему (повторная отправка из очереди не должна плодить
дубликаты). Точки входа:
[page-service.ts](../apps/client/src/features/page/services/page-service.ts),
[comment-service.ts](../apps/client/src/features/comment/services/comment-service.ts)
и соответствующие контроллеры сервера.
4. **Optimistic updates + откат.** Применять мутацию к кэшу сразу; при
неуспешном проигрывании после реконнекта — откат/пометка конфликта.
5. **Правила разрешения конфликтов** (см. §5).
6. **Проигрывание при реконнекте** в порядке `createdAt`, с экспоненциальным
backoff и идемпотентностью.
**Файлы:** новый `apps/client/src/lib/offline/outbox.ts`, обёртки над
`features/*/services/*`, серверные контроллеры/сервисы соответствующих
сущностей (idempotent upsert).
**Критерий приёмки:** оффлайн можно создать страницу, отредактировать заголовок,
оставить комментарий, переместить страницу; после реконнекта всё появляется на
сервере один раз (без дублей), конфликты разрешаются по заданным правилам.
**Риск:** высокий (это самостоятельный класс багов синхронизации; требует
серверных изменений и тестов на конфликты).
---
### M4 — Вложения и оффлайн-авторизация
**Что сделать:**
1. **Вложения/картинки оффлайн.** Очередь загрузок: blob кладётся в локальный
кэш (Cache API/IndexedDB), в документ вставляется ссылка на локальный
ресурс; при реконнекте файл доуплоадивается, ссылка переписывается на
серверную. Точка входа — `features/attachments`.
2. **Оффлайн-толерантная авторизация.** В
[api-client.ts](../apps/client/src/lib/api-client.ts) `401`/сетевые ошибки
**не должны** выкидывать на логин при отсутствии сети — отличать «нет сети»
от «реально разлогинен». Collab-токен (JWT с TTL,
[page-editor.tsx](../apps/client/src/features/editor/page-editor.tsx) L166–181)
оффлайн не обновить — синк должен просто ждать реконнекта, не ломая
локальную работу.
**Критерий приёмки:** оффлайн-вставка картинки доезжает после реконнекта;
протухший токен/нет сети не выкидывают пользователя из приложения и не теряют
локальные правки.
**Риск:** средний.
---
## 5. Правила разрешения конфликтов (Контур B)
CRDT здесь нет, правила задаём явно по типам сущностей:
| Сущность | Стратегия |
|---|---|
| **Тело документа** | Yjs (CRDT) — руками ничего не решаем. |
| **Комментарии** | Почти append-only. LWW по полю + дедуп по `clientId`. Простейший случай. |
| **Метаданные страницы** (заголовок, иконка) | Last-Write-Wins по `updatedAt`. |
| **Перемещение в дереве** | Самый сложный случай. Позиции — строковые fractional-ключи (`generateJitteredKeyBetween`), что снижает коллизии вставок. Нужен серверный реконсилер для «родитель удалён, а ребёнок перемещён» и конкурентных move: правило «удаление побеждает перемещение» (или наоборот — зафиксировать), плюс перегенерация позиции при коллизии. |
| **Удаление vs правка** | Зафиксировать политику: правка удалённой сущности → конфликт в UI либо «удаление выигрывает». |
---
## 6. Подводные камни (читать до старта)
1. **Yjs rebuild из JSON → дубли.** Ветка `content → toYdoc` в
`onLoadDocument` опасна для долго-оффлайновых клиентов. Закрыть в M1.
2. **Инвалидция кэша после деплоя.** Персист React Query и precache SW должны
версионироваться по версии приложения (`buster`/`globPatterns` хэши), иначе
пользователь застрянет на старом UI/данных.
3. **Обновление service worker.** `autoUpdate` может перезагрузить вкладку с
несохранёнными правками. Для редактора предпочтительнее `prompt`-стратегия
(показать «доступно обновление», применить по согласию).
4. **Идемпотентность обязательна.** Любая мутация из outbox может отправиться
повторно (реконнект/ретрай). Без серверного upsert по `clientId` — дубли.
5. **Рост IndexedDB.** Прогрев тел страниц «на оффлайн» и кэш блобов могут
занять много места. Нужны лимиты/очистка (LRU).
6. **Редирект на логин при сетевой ошибке.** Сейчас `401` → `redirectToLogin`.
Оффлайн это выкинет пользователя и потеряет контекст — чинить в M4.
---
## 7. Зависимости (npm)
| Пакет | Зачем | Этап |
|---|---|---|
| `vite-plugin-pwa` (+ Workbox) | SW, precache app-shell, генерация манифеста | M0 |
| `@tanstack/query-persist-client-core` | Персист React Query на диск | M2 |
| `idb` или `idb-keyval` | Обёртка над IndexedDB (persister/outbox/blob-кэш) | M2–M4 |
| `fractional-indexing-jittered` | Клиентская генерация позиций (уже есть на сервере) | M3 |
`yjs`, `y-indexeddb`, `@hocuspocus/provider` — **уже** в проекте, доустанавливать
не нужно.
---
## 8. Объём работ vs ценность (для приоритизации)
| Уровень | Этапы | Что пользователь получает |
|---|---|---|
| **Минимальный** | M0 + M1 | Приложение грузится оффлайн; уже открытые страницы редактируются и синкаются (тело + заголовок). Навигация — только по закэшированному. |
| **Средний** | + M2 + M3 | Оффлайн-навигация по подготовленным пространствам; оффлайн-создание страниц и комментариев с синком и LWW-конфликтами. |
| **Полный** | + M4 (и при необходимости — переезд на синк-движок) | Вложения оффлайн, устойчивая авторизация. Полноценный local-first. |
Прагматичный путь: довести **M0+M1** (это ~80% «редактирую то, что открыл»),
затем M2/M3 инкрементально. Полный синк-движок (RxDB / ElectricSQL / PowerSync /
Replicache / TanStack DB) рассматривать только если оффлайн станет ключевым
сценарием продукта — это существенный рефакторинг данных и бэкенда.
---
## 9. Открытые вопросы (зафиксировать до реализации)
- **Q1.** Заголовок страницы: переносим в Yjs (M1, вариант a) или гоним через
outbox (M3, вариант b)? Рекомендация — (a), меньше конфликтных правил.
- **Q2.** Политика конфликта «удаление vs правка»: «удаление выигрывает» или
явный конфликт в UI?
- **Q3.** Стратегия обновления SW для редактора: `autoUpdate` или `prompt`?
Рекомендация — `prompt`.
- **Q4.** Лимиты локального хранилища (сколько пространств/страниц/блобов
держать оффлайн, политика вытеснения).
- **Q5.** Целимся в инкрементальный путь (M0…M4) или сразу в синк-движок (уровень
«полный»)? От этого зависит, переписывать ли REST-слой.
---
## 10. Чеклист реализации
- [ ] M0: `vite-plugin-pwa` подключён, SW регистрируется, app-shell в precache,
`/api` и `/collab` — `NetworkOnly`.
- [ ] M0: приложение открывается без сети (shell виден).
- [ ] M1: ветка rebuild ydoc из JSON обезврежена; миграция `content → ydoc`.
- [ ] M1: индикатор статуса синка в UI.
- [ ] M1: заголовок переведён в Yjs (или решение Q1 принято).
- [ ] M2: React Query персистится в IndexedDB, кэш версионирован.
- [ ] M2: действие «сделать доступным оффлайн» (метаданные + прогрев `ydoc`).
- [ ] M3: outbox в IndexedDB, клиентские ID, идемпотентный upsert на сервере.
- [ ] M3: optimistic updates + откат; правила конфликтов реализованы.
- [ ] M4: очередь загрузки вложений + локальный blob-кэш.
- [ ] M4: авторизация толерантна к оффлайну (нет редиректа на логин при отсутствии сети).
Reference in New Issue View Git Blame Copy Permalink