@coopenomics/desktop 2025.7.3 → 2025.11.8-alpha-2

package/INSTALLATION_SCENARIOS.md

@@ -0,0 +1,297 @@
+# Сценарии установки кооператива
+
+Данный документ описывает все возможные сценарии установки и инициализации кооператива в системе.
+
+## Статусы системы
+
+Система проходит через следующие статусы в процессе установки:
+
+1. **`null` (дефолт)** — документ `mono` не существует в БД (первый запуск)
+2. **`install`** — установлен приватный ключ, создан `install_code`
+3. **`initialized`** — созданы данные организации и платежный метод
+4. **`active`** — система полностью установлена (совет + переменные)
+5. **`maintenance`** — режим технического обслуживания (отдельный процесс, не для установки)
+
+---
+
+## Сценарий 1: Стандартная установка через фронтенд
+
+### Описание
+Владелец организации самостоятельно устанавливает систему через веб-интерфейс, вводя все данные вручную.
+
+### Последовательность действий
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ШАГ 1: Ввод ключа доступа                                   │
+│                                                              │
+│ 1. Пользователь вводит wif (приватный ключ)                │
+│ 2. Вызывается: startInstall(wif)                            │
+│    - Сохраняет wif в Vault                                  │
+│    - Создает install_code (UUID, срок действия 30 дней)    │
+│    - Устанавливает статус: 'install'                        │
+│    → Возвращает: { install_code, coopname }                 │
+│                                                              │
+│ 3. Вызывается: getInstallationStatus(install_code)        │
+│    - Проверяет валидность install_code                      │
+│    - Проверяет наличие organization_data                    │
+│    → Возвращает: { has_private_account: false, ... }       │
+│                                                              │
+│ 4. Переход на шаг 'init' (инициализация)                    │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│ ШАГ 2: Инициализация данных организации                     │
+│                                                              │
+│ 1. Пользователь заполняет форму с данными организации:      │
+│    - Название, ИНН, ОГРН, КПП                               │
+│    - Адрес, контакты                                         │
+│    - Банковские реквизиты                                   │
+│    - Представитель организации                              │
+│                                                              │
+│ 2. Вызывается: initSystem(install_code, organization_data)   │
+│    - Требует: статус ≠ 'active' (разрешена реинициализация) │
+│    - Создает/обновляет organization_data                    │
+│    - Создает/обновляет payment_method                       │
+│    - Устанавливает статус: 'initialized'                    │
+│                                                              │
+│ 3. Переход на шаг 'soviet' (члены совета)                  │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│ ШАГ 3: Добавление членов совета                             │
+│                                                              │
+│ 1. Пользователь добавляет членов совета:                    │
+│    - Председатель совета (обязательно)                       │
+│    - Члены совета (по необходимости)                        │
+│                                                              │
+│ 2. Для каждого члена указывается:                            │
+│    - ФИО, паспортные данные                                 │
+│    - Электронная почта                                      │
+│    - Адрес                                                  │
+│                                                              │
+│ 3. Переход на шаг 'vars' (переменные)                       │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│ ШАГ 4: Установка переменных системы                         │
+│                                                              │
+│ 1. Пользователь заполняет переменные:                        │
+│    - Наименование организации (без ОПФ)                     │
+│    - Полная ОПФ в разных падежах                            │
+│    - Контактные данные (email, ссылки)                     │
+│    - Настройки (запрос паспорта и т.д.)                     │
+│    - Протоколы соглашений                                   │
+│                                                              │
+│ 2. Вызывается: installSystem(soviet, vars)                   │
+│    - Требует: статус 'initialized'                          │
+│    - Создает совет                                          │
+│    - Создает переменные                                     │
+│    - Устанавливает статус: 'active'                         │
+│                                                              │
+│ 3. Установка завершена!                                     │
+│    - Отправляются приглашения членам совета                 │
+│    - Система готова к работе                                │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Ключевые особенности
+- Все данные вводятся пользователем вручную
+- Требуется валидный `install_code` на каждом шаге
+- Ключ `wif` устанавливается только один раз в начале процесса
+- Последовательность шагов строгая: `key` → `init` → `soviet` → `vars`
+
+---
+
+## Сценарий 2: Предустановка через бэкенд (server_secret)
+
+### Описание
+Администратор предустанавливает данные организации через бэкенд с использованием `server_secret`, а владелец организации завершает установку через фронтенд.
+
+### Последовательность действий
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ШАГ 1: Предустановка данных администратором (бэкенд)        │
+│                                                              │
+│ 1. Администратор вызывает: initSystem(server_secret, ...)   │
+│    - Требует: заголовок 'server-secret' в запросе            │
+│    - Разрешено при: статус ≠ 'active' (разрешена реинициализация) │
+│    - Создает/обновляет organization_data                    │
+│    - Создает/обновляет payment_method                       │
+│    - Устанавливает статус: 'initialized'                    │
+│                                                              │
+│ 2. Система готова к дальнейшей установке владельцем         │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│ ШАГ 2: Ввод ключа доступа владельцем (фронтенд)             │
+│                                                              │
+│ 1. Владелец организации вводит wif (приватный ключ)        │
+│ 2. Вызывается: startInstall(wif)                            │
+│    - Разрешено при: статус 'initialized'                    │
+│    - Сохраняет wif в Vault                                  │
+│    - Создает install_code (UUID, срок действия 30 дней)    │
+│    - Статус остается: 'initialized' (не меняется!)          │
+│    → Возвращает: { install_code, coopname }                 │
+│                                                              │
+│ 3. Вызывается: getInstallationStatus(install_code)          │
+│    - Проверяет валидность install_code                      │
+│    - Находит предустановленные данные                        │
+│    → Возвращает: { has_private_account: true, ... }        │
+│                                                              │
+│ 4. Переход на шаг 'init' для просмотра данных               │
+│    - Данные организации отображаются в режиме readonly      │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│ ШАГ 3: Добавление членов совета                             │
+│                                                              │
+│ 1. Пользователь добавляет членов совета                     │
+│    (аналогично Сценарию 1, Шаг 3)                            │
+│                                                              │
+│ 2. Переход на шаг 'vars' (переменные)                       │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│ ШАГ 4: Установка переменных системы                         │
+│                                                              │
+│ 1. Пользователь заполняет переменные                        │
+│    (аналогично Сценарию 1, Шаг 4)                           │
+│                                                              │
+│ 2. Вызывается: installSystem(soviet, vars)                  │
+│    - Устанавливает статус: 'active'                         │
+│                                                              │
+│ 3. Установка завершена!                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Ключевые особенности
+- Данные организации предустанавливаются администратором
+- Владелец организации видит данные в режиме readonly
+- Шаг `init` не пропускается, но данные отображаются в readonly режиме
+- Ключ `wif` устанавливается владельцем организации
+- Последовательность: `key` → `init` → `soviet` → `vars`
+
+---
+
+## Сценарий 3: Обработка истекшего install_code
+
+### Описание
+В случае, если `install_code` истек или стал невалидным, система автоматически возвращает пользователя на шаг ввода ключа.
+
+### Последовательность действий
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Ситуация: Пользователь на шаге 'init' или 'soviet'           │
+│                                                              │
+│ 1. Вызывается: getInstallationStatus(install_code)           │
+│    - Проверяется валидность install_code                    │
+│    - Проверяется срок действия (30 дней)                    │
+│                                                              │
+│ 2. Ошибка: "Неверный или истекший код установки"            │
+│                                                              │
+│ 3. Автоматическая обработка:                                 │
+│    - Показывается сообщение:                                 │
+│      "Код установки истек или невалиден.                    │
+│       Пожалуйста, введите ключ заново."                    │
+│    - installStore.current_step = 'key'                      │
+│    - installStore.install_code = undefined                  │
+│                                                              │
+│ 4. Пользователь повторно вводит wif                         │
+│    - Создается новый install_code                           │
+│    - Продолжение установки с нового кода                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Ключевые особенности
+- Автоматический возврат на шаг ввода ключа
+- Очистка устаревшего `install_code`
+- Создание нового `install_code` при повторном вводе
+- Сохранение прогресса не критично (можно начать заново)
+
+---
+
+## Сравнительная таблица сценариев
+
+| Параметр | Сценарий 1 | Сценарий 2 | Сценарий 3 |
+|----------|-----------|-----------|-----------|
+| **Инициализация данных** | Пользователь | Администратор | Пользователь |
+| **Шаг init** | Обязателен | Показывается readonly (без редактирования) | Обязателен |
+| **Установка ключа** | В начале | После инициализации | В начале |
+| **install_code** | Создается при startInstall | Создается при startInstall | Пересоздается при истечении |
+| **Статус после init** | `initialized` | `initialized` | `initialized` |
+| **Статус после install** | `active` | `active` | `active` |
+
+---
+
+## Важные замечания
+
+### Безопасность
+- `install_code` имеет срок действия 30 дней
+- `install_code` проверяется на каждом шаге установки
+- `server_secret` используется только для предустановки администратором
+- Ключ `wif` хранится в зашифрованном виде в Vault
+
+### Последовательность статусов
+- Статусы меняются строго по порядку: `null` → `install` → `initialized` → `active`
+- Статус `maintenance` не участвует в процессе установки
+- Невозможно пропустить статусы (например, сразу `active` без `initialized`)
+- **Реинициализация разрешена**: повторный вызов `initSystem` возможен пока статус ≠ 'active'
+- **Права на редактирование**: пользователь может редактировать только данные, введенные им самим; серверные данные доступны только для чтения
+
+### Валидация
+- Каждый шаг проверяет наличие необходимых данных предыдущего шага
+- При ошибке пользователь получает понятное сообщение
+- Система автоматически возвращает на правильный шаг при ошибках
+
+### Хранение данных
+- `install_code` сохраняется в localStorage (persist: true)
+- При перезагрузке страницы процесс может быть продолжен
+- При истечении `install_code` требуется повторный ввод ключа
+
+---
+
+## API методы
+
+### startInstall
+- **Вход**: `{ wif: string }`
+- **Выход**: `{ install_code: string, coopname: string }`
+- **Статусы**: `null`, `install`, `initialized` → `install` или `initialized`
+
+### getInstallationStatus
+- **Вход**: `{ install_code: string }`
+- **Выход**: `{ has_private_account: boolean, private_account?: PrivateAccount }`
+- **Требования**: валидный `install_code`
+
+### initSystem
+- **Вход**: `{ organization_data: OrganizationData }`
+- **Выход**: `SystemInfo`
+- **Статусы**: `install` или `null` → `initialized`
+- **Альтернатива**: может быть вызван с `server_secret` (без `install_code`)
+
+### installSystem
+- **Вход**: `{ soviet: SovietMember[], vars: Vars }`
+- **Выход**: `SystemInfo`
+- **Статусы**: `initialized` → `active`
+- **Важно**: не требует `wif` (уже установлен в `startInstall`)
+
+---
+
+## Логирование ошибок
+
+Все ошибки логируются с понятными сообщениями:
+- `"MONO уже инициализирован"` — попытка инициализации при неправильном статусе
+- `"Установка уже завершена"` — попытка установки при статусе `active`
+- `"Неверный или истекший код установки"` — проблема с `install_code`
+- `"Организация уже инициализирована"` — дублирование данных организации
+
+---
+
+## Дата создания документа
+2025-01-04
+
+## Последнее обновление
+2025-01-04
+