# RUSZ Sync — инструкция пользователя

**Плагин:** RUSZ Sync MVP **0.3.5**  
**Starter:** v0.3.5  
**Sync API:** `https://sync.vor-ort-service-rusz.at`  
**Скачать Starter:** https://office.vor-ort-service-rusz.at/downloads/RUSZ-Starter-mvp-v0.3.5.tar.gz  
**Эта же инструкция онлайн:** https://office.vor-ort-service-rusz.at/downloads/RUSZ-Sync-User-Guide.md  

Документ для **администратора** (invite, реестр сотрудников, Eggent):  
`docs/INVITE_ADMIN.md` / https://office.vor-ort-service-rusz.at/downloads/RUSZ-Sync-Invite-Admin.md  

---

## Оглавление

1. [Что это](#1-что-это)  
2. [Структура vault и права](#2-структура-vault-и-права)  
3. [Установка (первое устройство)](#3-установка-первое-устройство)  
4. [Первый вход: Invite code](#4-первый-вход-invite-code)  
5. [Правила синхронизации](#5-правила-синхронизации)  
6. [Команды, hotkeys, кнопки](#6-команды-hotkeys-кнопки)  
7. [Второе (и следующие) устройство](#7-второе-и-следующие-устройство)  
8. [Удаление файлов](#8-удаление-файлов)  
9. [Типичные сценарии](#9-типичные-сценарии)  
10. [Мобильный Obsidian](#10-мобильный-obsidian)  
11. [Сообщения (Notices)](#11-сообщения-notices)  
12. [Проблемы и решения](#12-проблемы-и-решения)  
13. [Безопасность](#13-безопасность)  

---

## 1. Что это

**RUSZ Sync** — плагин Obsidian, который связывает вашу локальную базу (vault) с сервером организации:

- вы получаете **готовые папки** (KIRUSZ + RUSZ + Personal);
- **заливаете** свои `.md` на сервер (**Push**);
- **забираете** изменения с сервера (**Pull**);
- на **втором ПК/телефоне** подключаетесь **тем же аккаунтом** (не новым invite).

Важно: **автосинхронизации при каждом Save нет.**  
Каждый обмен с сервером — **явная команда** (hotkey, Command palette или кнопки в Settings).

---

## 2. Структура vault и права

После установки и Connect vault выглядит так:

```text
RUSZ-Starter/                 ← папка vault в Obsidian
├── KIRUSZ/                   ← общая работа организации
│   ├── Knowledge/
│   ├── Projects/
│   ├── Procedures/
│   ├── Tasks/
│   ├── Shared/
│   ├── Organization/
│   └── Inbox/
├── RUSZ/                     ← служебные файлы организации
│   ├── Service/
│   ├── Policies/
│   ├── Templates/
│   └── Org/
├── Personal/                 ← только ваше
│   ├── Inbox/
│   ├── Notes/
│   ├── Drafts/
│   ├── Tasks/
│   └── Archive/
├── .obsidian/
│   └── plugins/rusz-sync/    ← этот плагин
└── README.md                 ← эта инструкция
```

| Папка | Кто читает | Кто пишет (Push) | Назначение |
|--------|------------|------------------|------------|
| **Personal/** | только вы | только вы | Личные заметки, черновики |
| **KIRUSZ/** | сотрудники org | сотрудники org | Совместная работа, knowledge, проекты |
| **RUSZ/** | сотрудники org | **только** роль `director` / `admin` **или** администратор через Eggent | Служебные орг. файлы, политики, шаблоны |

**Обычный сотрудник:** в `RUSZ/` — только **чтение** (после Pull).  
Правки в `RUSZ/` сотрудником **не уйдут** на сервер (Push пропустит / 403).  
Изменения в `RUSZ/` делает **директор** в Obsidian или **ЕКС (Eggent)** через admin API.

Файлы **вне** `Personal/`, `KIRUSZ/`, `RUSZ/` плагин **не синхронизирует**.

Синхронизируются только **Markdown (`.md`)**.

---

## 3. Установка (первое устройство)

### 3.1. Desktop (Windows / macOS / Linux)

1. Скачайте **RUSZ Starter** (ссылка в шапке).  
2. Распакуйте архив.  
3. Запустите **Obsidian** → **Open folder as vault** → укажите папку `RUSZ-Starter`.  
4. **Settings → Community plugins**:  
   - отключите **Restricted mode** (Turn on community plugins);  
   - включите плагин **RUSZ Sync MVP**.  
5. **Settings → RUSZ Sync MVP** — проверьте API:

   ```text
   https://sync.vor-ort-service-rusz.at
   ```

### 3.2. Обновление плагина (уже есть vault)

1. Скачайте свежий Starter **или** скопируйте из архива файлы:

   ```text
   .obsidian/plugins/rusz-sync/main.js
   .obsidian/plugins/rusz-sync/manifest.json
   ```

2. В Obsidian: **Reload app** / выключить-включить плагин.  
3. В Settings статус плагина должен показать **0.3.5** (или новее).

**Не** удаляйте vault «чтобы обновить» — потеряете локальные заметки, если не сделали Push.

### 3.3. Invite code

Код вида `INV-XXXXXXXX` выдаёт **только администратор** (Eggent / ops).  
Самостоятельно «запросить на сайте» нельзя.

---

## 4. Первый вход: Invite code

**Invite одноразовый.** Он:

- создаёт **вашу** учётную запись (`userId`, напр. `u000004`);
- привязывает **это** устройство;
- **повторно тот же INV на втором ПК использовать нельзя** (будет 403).

### Шаги

1. Получите `INV-…` у администратора (WhatsApp / лично).  
2. **Settings → RUSZ Sync** → поле **Invite code**.  
3. Нажмите **Connect** (или Command palette → `RUSZ: Connect with Invite`).  
4. Дождитесь Notice: `Connected: u00…`.  
5. Появятся/обновятся папки `KIRUSZ/`, `RUSZ/`, `Personal/`; выполнится **initial pull**.

В Settings должно быть примерно:

```text
Connected as u00000N (kirusz-main) role=member RUSZ=read-only device=d…
```

(у директора/admin: `RUSZ=write`).

### Чего не делать

| Действие | Почему нельзя |
|----------|----------------|
| Connect тем же INV второй раз | Invite already used (403) |
| Выдать себе второй INV «для 2-го ПК» | Создастся **другой** user — **другой** Personal |
| Печатать invite в публичные чаты/git | Любой, кто redeem’ит, станет «вами» один раз |

---

## 5. Правила синхронизации

### 5.1. Две команды (не путать)

| Команда | Что делает | Когда |
|---------|------------|--------|
| **Sync now (push)** — **upload** | Загружает **локальные** `.md` из `Personal/` + `KIRUSZ/` (+ `RUSZ/` только если вам разрешена запись) **на сервер**. Также **удаляет на сервере** файлы, которых уже нет у вас локально (в разрешённых папках). | После того как **вы** изменили или удалили заметки |
| **Sync now (pull)** — **download** | Скачивает файлы **с сервера** в vault. Удаляет **локально** ранее синкавшиеся файлы, которых на сервере больше нет. | Чтобы **увидеть** чужие/серверные изменения или работу с другого своего устройства |

**Типичная ошибка:** жать только **Pull** → `0 files`, потому что на сервер ещё никто не сделал **Push**.

### 5.2. Порядок «два устройства»

```text
ПК A (писали)                         ПК B / телефон
  создать/править .md
  → PUSH  (upload)     ──сервер──►
                                      → PULL  (download)
                                      увидеть те же файлы
```

Обратно: правите на B → **Push на B** → **Pull на A**.

### 5.3. Что попадает в Push

- Только `.md`  
- Только пути:

  - `Personal/...`
  - `KIRUSZ/...`
  - `RUSZ/...` — **только** если `RUSZ=write` (director/admin)

- Заметка в корне vault или в `.obsidian/` — **не** уедет.

### 5.4. Конфликты

Сервер **главный** при устаревшем revision (HTTP 409):

- Push может подтянуть **серверную** версию;
- ваши несохранённые на сервере правки нужно **внести снова** и снова Push.

### 5.5. Нет фонового sync

- Закрыли Obsidian без Push — на сервере **старая** версия.  
- Push на A, не сделали Pull на B — на B **старая** картина.  
- Autosave Obsidian ≠ отправка на сервер.

---

## 6. Команды, hotkeys, кнопки

### 6.1. Command palette

`Ctrl+P` / `Cmd+P` → начните вводить `RUSZ`:

| Команда | Назначение |
|---------|------------|
| `RUSZ: Connect with Invite` | Первый вход (INV) |
| `RUSZ: Create code for another device` | Создать **PAIR-…** (уже connected) |
| `RUSZ: Connect with device code` | Подключить 2-е устройство (PAIR) |
| `RUSZ: Sync now (push) — upload to server` | **Выгрузить** |
| `RUSZ: Sync now (pull) — download from server` | **Скачать** |
| `RUSZ: Push current file` | Только текущий файл |
| `RUSZ: Pull current file` | Только текущий файл |

### 6.2. Кнопки в Settings → RUSZ Sync

При **Connected**:

- **Push** / **Pull** — то же, что команды sync;  
- **Create device code** — для 2-го устройства;  
- **Last device code** — последний `PAIR-…` и срок.

Пока **не** connected:

- **Connect** (invite);  
- **Connect device** (pairing code).

### 6.3. Hotkeys (Desktop)

Obsidian **сам** hotkeys не ставит — назначьте вы:

1. **Settings → Hotkeys**  
2. Поиск `RUSZ`  
3. Рекомендация:

| Команда | Пример |
|---------|--------|
| Sync now (**push**) | `Ctrl+Shift+U` (Up / upload) |
| Sync now (**pull**) | `Ctrl+Shift+D` (Down / download) |

**Обязательно две разные клавиши.**  
Если на push и pull одна клавиша — будете только качать пустой сервер.

Проверка: после hotkey в углу Notice со словом **PUSH** или **PULL**.

---

## 7. Второе (и следующие) устройство

### 7.1. Идея

| Код | Смысл |
|-----|--------|
| `INV-…` | **Новый человек** + первое устройство (один раз) |
| `PAIR-…` | **Тот же человек**, ещё одно устройство (~15 мин, один раз) |

Лимит устройств: обычно **до 5** (`maxDevices` при выдаче доступа).

### 7.2. На устройстве 1 (уже Connected)

1. **Settings → RUSZ Sync** → **Create device code**  
   *или* команда `RUSZ: Create code for another device`.  
2. Появится Notice с кодом **`PAIR-XXXXXXXX`**.  
3. Тот же код продублирован в блоке **Last device code** (удобно скопировать).  
4. Срок: около **15 минут**, код **одноразовый**.

### 7.3. На устройстве 2 (новый vault)

1. Установите Starter / плагин **той же** актуальной версии (п. 3).  
2. **Не** вводите старый `INV-…`.  
3. Settings → поле **Device pairing code** → вставьте `PAIR-…`.  
4. **Connect device** (или команда `RUSZ: Connect with device code`).  
5. Notice: `Second device connected: u00…`.  
6. Сделайте **Sync pull**, чтобы подтянуть файлы.

### 7.4. Частые ошибки multi-device

| Ошибка | Причина |
|--------|---------|
| 403 на INV | Invite уже использован — нужен **PAIR**, не второй INV |
| 410 на PAIR | Код просрочен — создайте новый на устройстве 1 |
| 403 на PAIR повторно | Код уже погашен — создайте новый |
| Разный Personal на 2 ПК | Подключились **вторым INV** → другой userId — к админу |

---

## 8. Удаление файлов

Начиная с плагина **0.3.4+**:

1. Удалите `.md` локально (в `Personal/` / `KIRUSZ/`, или `RUSZ/` если вам можно писать).  
2. **Sync PUSH** → на сервере файл удаляется  
   Notice: `… N deleted on server`.  
3. На другом устройстве **Sync PULL** → локальная копия тоже убирается  
   Notice: `… N local deleted`.

Без Push удаление **только на вашем диске** — сервер и 2-е устройство не узнают.

---

## 9. Типичные сценарии

### A. Первый день

1. Starter → vault → плагин on.  
2. INV → Connect.  
3. `Personal/Notes/hello.md` → **Push**.  
4. На 2-м устройстве: PAIR → Connect device → **Pull**.

### B. Работал на телефоне, сел за ПК

1. Телефон: **Push**.  
2. ПК: **Pull**.

### C. Правил KIRUSZ, коллега не видит

1. У вас был **Push**?  
2. У коллеги был **Pull**?  
3. Файл точно в `KIRUSZ/…` и `.md`?

### D. Хочу править служебное RUSZ/

- Роль **member** → нельзя (ожидаемо).  
- Нужен **директор** (role director/admin) или администратор / Eggent.

---

## 10. Мобильный Obsidian

Полноценных hotkeys как на ПК часто нет.

Рекомендуется **Mobile Toolbar**:

1. Settings → **Mobile** / Toolbar.  
2. Добавьте команды:

   - `RUSZ: Sync now (push) — upload to server`  
   - `RUSZ: Sync now (pull) — download from server`  
   - при необходимости Connect / device code  

3. После правок — кнопка **Push** на панели.

---

## 11. Сообщения (Notices)

| Notice (смысл) | Что значит |
|----------------|------------|
| `Connected: u00…` | Invite OK, vault привязан |
| `Second device connected…` | PAIR OK |
| `Sync PUSH done: N uploaded, M deleted…` | Выгрузка прошла |
| `Sync PUSH: 0 changes…` | Нечего грузить (нет `.md` в нужных папках) или только RUSZ read-only |
| `… RUSZ read-only (director/Eggent only)` | Попытка писать в служебное без прав |
| `Sync PULL done: N downloaded, M local deleted` | Загрузка / удаление локально |
| `Sync PULL: 0 changes…` | На сервере нет новинок — сначала Push **где правили** |
| `Connect failed: API 403` | INV/PAIR уже использован или revoke |
| `Connect failed: API 410` | Код просрочен |
| `Conflict…` | Сервер новее; правки внесите снова + Push |

---

## 12. Проблемы и решения

| Симптом | Что проверить |
|---------|----------------|
| Pull всегда 0 files | Сделали ли **Push** на устройстве с правками? Hotkey не перепутан с Pull? |
| Push 0 files | Файл в `Personal/` или `KIRUSZ/`? Это `.md`? |
| Нет синхронизации после PAIR | Оба Connected как **один** `userId`? Pull после Push? |
| Старый плагин | Обновить до **0.3.5+** (delete, RUSZ/, PAIR UI) |
| `Not connected` | Settings: есть userId? Заново Connect / device code |
| 401 после revoke | Доступ отозван админом — нужен новый процесс |

Проверка Connected: **Settings → RUSZ Sync** — строка статуса.

---

## 13. Безопасность

- Invite и PAIR **не пересылайте** в открытые каналы без нужды.  
- Token хранится в `data` плагина vault — **бэкап vault = доступ к вашей сессии**.  
- Personal **не** читают другие сотрудники по умолчанию.  
- При увольнении админ делает **revoke** — sync перестаёт работать (401).  
- Скопированные ранее файлы с диска revoke **не сотрёт** — это политика организации, не технический DLP.

---

## Краткая шпаргалка

```text
Установка:     Starter → Open vault → enable RUSZ Sync
Первый вход:   INV-… → Connect  (один раз на человека)
2-е устройство: устройство1 Create device code → PAIR-…
                устройство2 Connect device (не INV)
Писали:        PUSH (upload)
Читаем чужое:  PULL (download)
Удалили:       PUSH → на другом PULL
Служебное:     папка RUSZ/ — read-only (кроме director/admin/Eggent)
```

При сбоях: точный текст Notice + device (ПК/телефон) + сделали Push или Pull — администратору / в чат поддержки.