sfera-new/2025-09-17/REGISTER_ORGANIZATION_REFACTORING.md

ДОКУМЕНТАЦИЯ: РЕФАКТОРИНГ СИСТЕМЫ РЕГИСТРАЦИИ ОРГАНИЗАЦИЙ

Дата: 17 сентября 2025
Версия: 2.0
Статус: ✅ ЗАВЕРШЕНО
Разработчик: Claude + Veronika

📊 ИТОГОВЫЙ СТАТУС РЕАЛИЗАЦИИ

✅ Выполненные фазы:

1. ФАЗА 1 - Стабилизация и добавление транзакций ✅
2. ФАЗА 2 - Создание универсального сервиса ✅
3. ФАЗА 3 - Frontend интеграция ✅
4. ФАЗА 4 - Миграция через комментарии ✅
5. ТЕСТИРОВАНИЕ - Успешно протестировано ✅

🔧 Решенные проблемы:

• GraphQL 500 Error - исправлено добавлением обработки ошибок в route.ts
• Подробности в GRAPHQL_500_ERROR_RESOLUTION.md

📈 Результаты тестирования:

• Успешно созданы 3 организации разных типов
• Подробный отчет в TESTING_REPORT.md

📋 ОБЗОР ЗАДАЧИ

Цель рефакторинга

Упростить и объединить две разрозненные функции регистрации организаций (registerFulfillmentOrganization и registerSellerOrganization) в одну универсальную функцию registerOrganization.

Проблемы текущей системы

1. Неправильная семантика названий - registerFulfillmentOrganization регистрирует все типы бизнес-организаций (FULFILLMENT, LOGIST, WHOLESALE), не только фулфилменты
2. Дублирование логики - партнерские связи, реферальные системы повторяются в обеих функциях
3. Сложность поддержки - две функции делают похожие вещи разными способами
4. Архитектурная несогласованность - нарушение принципа единой ответственности

Целевое решение

Единая функция registerOrganization с логикой:

• Для FULFILLMENT, LOGIST, WHOLESALE: обязательный ИНН + DaData интеграция
• Для SELLER: обязательные API ключи маркетплейсов + псевдо-ИНН

---

🔍 РЕЗУЛЬТАТЫ ГЛУБОКОЙ ДИАГНОСТИКИ

Масштаб системы

• 25+ файлов связанных с регистрацией организаций
• 6 доменов затронуты изменениями
• 4 критических риска безопасности
• 3 уровня архитектуры: Domain → Service → UI

Затронутые домены

1. Organization Domain - основная логика регистрации
2. Auth Domain - аутентификация через SMS
3. External Services - DaData, SMS, маркетплейсы
4. Partnership Domain - партнерские связи и реферальная система
5. API Keys Domain - управление ключами маркетплейсов
6. User Domain - создание и связывание пользователей

Критические зависимости

1. GraphQL Schema (/src/graphql/typedefs.ts)

• Мутации: registerFulfillmentOrganization, registerSellerOrganization
• Input типы: FulfillmentRegistrationInput, SellerRegistrationInput
• Output тип: AuthResponse

2. Резолверы (/src/graphql/resolvers/domains/organization-management.ts)

• Функции: registerFulfillmentOrganization (строки 136-445), registerSellerOrganization (строки 448-750)
• DaData интеграция: строки 222-241
• Партнерская логика: строки 312-396, 550-631

3. Frontend Hook (/src/hooks/useAuth.ts)

• Функции: registerFulfillmentOrganization (строки 293-352), registerSellerOrganization (строки 354-413)
• GraphQL мутации: строки 72-83
• Обработка результатов: строки 324-351, 364-410

4. GraphQL Queries (/src/graphql/mutations.ts)

• REGISTER_FULFILLMENT_ORGANIZATION: строки 76-123
• REGISTER_SELLER_ORGANIZATION: строки 125-170

5. UI Components (10+ файлов)

Компоненты используют типы организаций и могут ссылаться на функции регистрации.

---

🚨 АНАЛИЗ РИСКОВ

Критические риски (P0)

1. Breaking Changes Frontend - изменение названий GraphQL мутаций сломает все UI формы регистрации
2. Database Integrity - ошибки в новой логике создания могут повредить существующие данные
3. Authentication Flow - нарушение регистрации = полная блокировка новых пользователей
4. Transaction Safety - отсутствие транзакций может привести к частично созданным организациям

Высокие риски (P1)

1. API Keys Validation - новая логика валидации может отклонить валидные ключи маркетплейсов
2. Partner Logic - изменения могут нарушить систему автопартнерства и реферальных связей
3. DaData Integration - изменения могут нарушить интеграцию с внешним API

Умеренные риски (P2)

1. Performance Impact - единая функция может работать медленнее из-за дополнительных проверок
2. Code Complexity - объединение двух функций может усложнить логику
3. Testing Coverage - нужно тестировать больше сценариев в одной функции

---

📋 ДЕТАЛЬНЫЙ ПЛАН РЕАЛИЗАЦИИ

ФАЗА 1: СТАБИЛИЗАЦИЯ (1-2 дня)

Устранение критических уязвимостей в существующей системе

1.1 Добавить транзакционность

Файл: /src/graphql/resolvers/domains/organization-management.ts
Строки: 244-280, 507-518
Проблема: Создание организации и пользователя не обернуто в транзакцию
Решение:

const result = await prisma.$transaction(async (tx) => {
  const organization = await tx.organization.create({...})
  const user = await tx.user.create({...})
  return { organization, user }
})

1.2 Улучшить обработку ошибок DaData

Файл: /src/services/dadata-service.ts
Строки: 124-139
Проблема: Отсутствует retry логика для внешних API
Решение: Добавить exponential backoff retry с максимум 3 попытки

1.3 Добавить rollback в useAuth

Файл: /src/hooks/useAuth.ts
Строки: 293-352, 354-413
Проблема: При частичном сбое нет отката изменений
Решение: Логирование состояния + cleanup функции

1.4 Тестирование стабильности

• Юнит-тесты для критических сценариев
• Интеграционные тесты с внешними API
• Нагрузочные тесты регистрации

ФАЗА 2: МОДУЛЬНАЯ РЕОРГАНИЗАЦИЯ (2-3 дня)

Создание новой универсальной системы

2.1 Создать OrganizationRegistrationService

Файл: /src/services/organization-registration-service.ts (новый)
Назначение: Бизнес-логика регистрации всех типов организаций

class OrganizationRegistrationService {
  async registerOrganization(input: OrganizationRegistrationInput): Promise<OrganizationRegistrationResult>
  private async validateBusinessOrganization(input: BusinessOrgInput): Promise<void>
  private async validateSellerOrganization(input: SellerOrgInput): Promise<void>  
  private async createBusinessOrganization(input: BusinessOrgInput): Promise<Organization>
  private async createSellerOrganization(input: SellerOrgInput): Promise<Organization>
}

2.2 Обновить GraphQL Schema

Файл: /src/graphql/typedefs.ts

extend type Mutation {
  registerOrganization(input: OrganizationRegistrationInput!): AuthResponse!
}

input OrganizationRegistrationInput {
  phone: String!
  type: OrganizationType!
  
  # Для бизнес-организаций (FULFILLMENT, LOGIST, WHOLESALE)
  inn: String
  kpp: String
  # ... другие бизнес поля
  
  # Для селлеров (SELLER)
  wbApiKey: String  
  ozonApiKey: String
  ozonClientId: String
  
  # Общие поля
  referralCode: String
  partnerCode: String
}

2.3 Создать новый резолвер

Файл: /src/graphql/resolvers/domains/organization-management.ts

registerOrganization: async (
  _: unknown, 
  args: { input: OrganizationRegistrationInput }, 
  context: Context
) => {
  const service = new OrganizationRegistrationService()
  return await service.registerOrganization(args.input)
}

2.4 Валидационные схемы

Файл: /src/lib/validation/organization-registration.ts (новый)

• Zod схемы для каждого типа организации
• Бизнес-правила валидации
• Кросс-проверки полей

ФАЗА 3: FRONTEND ИНТЕГРАЦИЯ (1-2 дня)

Обновление пользовательского интерфейса

3.1 Обновить useAuth hook

Файл: /src/hooks/useAuth.ts

const registerOrganization = async (input: OrganizationRegistrationInput) => {
  // Новая универсальная функция
}

3.2 Создать новую GraphQL мутацию

Файл: /src/graphql/mutations.ts

export const REGISTER_ORGANIZATION = gql`
  mutation RegisterOrganization($input: OrganizationRegistrationInput!) {
    registerOrganization(input: $input) {
      success
      message  
      token
      user { ... }
    }
  }
`

3.3 Обновить UI компоненты

• Формы регистрации для поддержки нового API
• Условная логика показа полей (ИНН vs API ключи)
• Обработка новых состояний загрузки

ФАЗА 4: МИГРАЦИЯ ЧЕРЕЗ КОММЕНТАРИИ (1 день)

Безопасное переключение с возможностью отката

4.1 Система отката через комментарии

// Вариант 1: Старые функции (для отката)
/*
registerFulfillmentOrganization: async (...) => {
  // старая логика фулфилмента
},
registerSellerOrganization: async (...) => {
  // старая логика селлеров  
}
*/

// Вариант 2: Новая универсальная функция (активная)
registerOrganization: async (...) => {
  // новая универсальная логика
}

4.2 Поэтапное переключение

1. Закомментировать старые мутации в schema
2. Закомментировать старые резолверы
3. Закомментировать старые функции в useAuth
4. Активировать новые функции
5. Тестирование в staging
6. Деплой в production с мониторингом

4.3 Команды отката

• "откати registerOrganization через комментарии" - возврат к старой системе
• "переключи на вариант 1" - активация старых функций
• "очисти комментарии registerOrganization" - удаление неактивного кода

ФАЗА 5: ФИНАЛИЗАЦИЯ (1 день)

Очистка и оптимизация

5.1 Удаление legacy кода

• Удаление закомментированных функций
• Удаление неиспользуемых типов
• Обновление документации

5.2 Оптимизация производительности

• Профилирование новой функции
• Оптимизация database queries
• Caching стратегии для DaData

5.3 Документирование

• API документация
• Архитектурная документация
• Runbook для production

---

🛡️ СТРАТЕГИЯ БЕЗОПАСНОСТИ И ОТКАТА

Система контроля версий

1. Feature branch для всех изменений
2. Пошаговые коммиты для каждой фазы
3. Rollback points перед критическими изменениями
4. Backup database перед миграцией

Мониторинг и алерты

1. Error tracking для новых функций
2. Performance monitoring времени регистрации
3. Business metrics успешности регистрации
4. Alerting при превышении error rate >1%

Откат через комментарии

Специальные команды для быстрого отката:

• "откати registerOrganization через комментарии"
• "переключи на вариант 1"
• "восстанови старую систему"

---

✅ КРИТЕРИИ УСПЕХА

Технические метрики

• Время регистрации <30 секунд в 95% случаев
• Error rate <1% для всех типов организаций
• API availability >99.9% для критических компонентов
• Database consistency 100% без orphan записей

Бизнес метрики

• Conversion rate регистрации не снижается
• User experience улучшается (меньше шагов)
• Support tickets по регистрации уменьшаются
• Partner onboarding ускоряется

Архитектурные метрики

• Code complexity уменьшается (меньше дублирования)
• Test coverage >90% для новой функции
• Documentation полное покрытие API
• Security audit проходит без критических issues

---

📞 КОНТАКТЫ И РЕСУРСЫ

Владелец проекта: Veronika Smirnova
Разработчик: Claude AI Assistant
Репозиторий: /Users/veronikasmirnova/Desktop/Projects/sfera-new
Документация: /docs/

Полезные ссылки

• Архитектурная документация
• API документация
• Deployment guide

---

Статус: 📋 Планирование завершено, готов к реализации
Последнее обновление: 17 сентября 2025, 15:15