ваше сообщение коммита

backend/docs/migration_guide.md

@@ -0,0 +1,74 @@
+# Руководство по миграциям базы данных
+
+## Общая информация
+
+Система миграций базы данных предназначена для поддержания структуры базы данных в актуальном состоянии и обеспечения возможности обновления между версиями приложения.
+
+## Структура миграций
+
+Миграции размещены в папке `backend/db/migrations/` и именуются по схеме `XXX_descriptive_name.sql`, где XXX - порядковый номер миграции.
+
+### Категории миграций
+
+1. **Основные структурные миграции** (001-013) - создание базовых таблиц и первоначальной структуры
+2. **Функциональные миграции** - изменения, связанные с конкретными функциями
+3. **Рефакторинг и оптимизация** (019+) - улучшение существующей структуры
+
+## Важные миграции
+
+### 019_identity_system_refactor.sql
+
+Комплексная миграция, объединяющая несколько предыдущих миграций (014-018) для улучшения системы идентификации пользователей:
+
+- Создание таблицы `guest_user_mapping` для связи гостевых идентификаторов с пользователями
+- Добавление прямой связи между сообщениями и пользователями через поле `user_id`
+- Очистка дублирующихся данных между таблицами `users` и `user_identities`
+- Нормализация формата идентификаторов (приведение к нижнему регистру)
+- Добавление ограничений и триггеров для поддержания целостности данных
+
+## Применение миграций
+
+При развертывании новой версии приложения миграции применяются автоматически через скрипт `backend/db/run-migrations.js`. Порядок применения определяется порядковым номером в имени файла.
+
+## Создание новых миграций
+
+1. **Именование**: Используйте следующий свободный порядковый номер и описательное имя
+2. **Идемпотентность**: Миграции должны быть безопасны для повторного выполнения
+3. **Проверки**: Добавляйте проверки существования объектов перед их созданием
+4. **Тестирование**: Проверяйте миграцию на тестовой базе данных перед применением
+
+Пример правильной идемпотентной миграции:
+
+```sql
+-- Создание таблицы, если она не существует
+CREATE TABLE IF NOT EXISTS example_table (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255) NOT NULL
+);
+
+-- Добавление колонки, если она отсутствует
+DO $$ 
+BEGIN 
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns 
+    WHERE table_name = 'example_table' AND column_name = 'new_column'
+  ) THEN
+    ALTER TABLE example_table ADD COLUMN new_column INTEGER;
+  END IF;
+END $$;
+```
+
+## Архивация устаревших миграций
+
+Устаревшие миграции, объединенные в более новые версии, перемещаются в папку `backend/db/migrations/archive/`. Для архивации используйте скрипт `backend/scripts/cleanup_migrations.sh`.
+
+## Диагностические функции
+
+Для проверки состояния базы данных и корректности миграций созданы следующие диагностические функции SQL:
+
+- `verify_identity_system()` - проверка состояния системы идентификации пользователей
+
+Пример использования:
+```sql
+SELECT * FROM verify_identity_system();
+```