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

**Дата:** 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](./GRAPHQL_500_ERROR_RESOLUTION.md)

### 📈 Результаты тестирования:
- Успешно созданы 3 организации разных типов
- Подробный отчет в [TESTING_REPORT.md](./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  
**Проблема:** Создание организации и пользователя не обернуто в транзакцию  
**Решение:**
```typescript
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` (новый)  
**Назначение:** Бизнес-логика регистрации всех типов организаций
```typescript
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`
```graphql
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`
```typescript
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`
```typescript
const registerOrganization = async (input: OrganizationRegistrationInput) => {
  // Новая универсальная функция
}
```

#### 3.2 Создать новую GraphQL мутацию
**Файл:** `/src/graphql/mutations.ts`
```typescript
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 Система отката через комментарии
```typescript
// Вариант 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/`  

### Полезные ссылки
- [Архитектурная документация](../docs/ARCHITECTURE.md)
- [API документация](../docs/API.md)  
- [Deployment guide](../docs/DEPLOYMENT.md)

---

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