# Руководство по интеграции системы безопасности SFERA

## 📋 Обзор

Система безопасности SFERA обеспечивает автоматическую защиту данных поставок на уровне GraphQL резолверов. Система поддерживает два способа интеграции:

1. **Автоматическая интеграция** - через middleware
2. **Ручная интеграция** - через декораторы и функции

## 🔧 Способы интеграции

### 1. Автоматическая интеграция (Рекомендуется)

Используйте функцию `wrapResolversWithSecurity` для автоматической защиты всех резолверов:

```typescript
import { wrapResolversWithSecurity } from '@/graphql/security'

// Ваши существующие резолверы
const myResolvers = {
  Query: {
    supplyOrders: async (parent, args, context) => {
      // Ваша логика
    },
    mySupplyOrders: async (parent, args, context) => {
      // Ваша логика
    },
  },
  Mutation: {
    createSupplyOrder: async (parent, args, context) => {
      // Ваша логика
    },
  },
}

// Применение безопасности
const securedResolvers = wrapResolversWithSecurity(myResolvers)

export const resolvers = securedResolvers
```

### 2. Ручная интеграция

Используйте декоратор `createSecureResolver` для отдельных резолверов:

```typescript
import { createSecureResolver } from '@/graphql/security'

const secureSupplyOrdersResolver = createSecureResolver(
  async (parent, args, context) => {
    // Ваша логика резолвера
    const orders = await context.prisma.supplyOrder.findMany(/* ... */)
    return orders
  },
  {
    resourceType: 'SUPPLY_ORDER',
    auditAction: 'VIEW_PRICE',
    enableFiltering: true,
    enableAudit: true,
  },
)
```

## 🛡️ Защищенные резолверы

Система автоматически защищает следующие резолверы:

### Query резолверы:
- `supplyOrders` - получение списка заказов поставок
- `mySupplyOrders` - получение моих заказов поставок  
- `pendingSuppliesCount` - подсчет ожидающих поставок

### Mutation резолверы:
- `createSupplyOrder` - создание заказа поставки
- `updateSupplyOrderStatus` - обновление статуса заказа
- `supplierApproveOrder` - одобрение заказа поставщиком
- `supplierRejectOrder` - отклонение заказа поставщиком
- `assignLogisticsToSupply` - назначение логистики

## 🔒 Уровни безопасности по ролям

### SELLER (Селлер)
**Видит:**
- ✅ Полную информацию по своим заказам
- ✅ Все коммерческие данные своих поставок
- ✅ Полную рецептуру своих товаров

**Не видит:**
- ❌ Заказы других селлеров
- ❌ Коммерческие данные других участников

### WHOLESALE (Поставщик)
**Видит:**
- ✅ Заказы, где есть его товары
- ✅ Свои цены на товары
- ✅ Параметры поставки (для логистики)

**Не видит:**
- ❌ Рецептуры товаров (коммерческая тайна)
- ❌ Цены на услуги фулфилмента
- ❌ Цены на логистику
- ❌ Расходники других участников

### FULFILLMENT (Фулфилмент)
**Видит:**
- ✅ Заказы, где он назначен исполнителем
- ✅ Полную рецептуру для производства
- ✅ Свои услуги и расходники с ценами
- ✅ Расходники селлера (без цен)

**Не видит:**
- ❌ Закупочные цены товаров
- ❌ Цены на расходники селлера
- ❌ Заказы других фулфилмент-центров

### LOGIST (Логистика)
**Видит:**
- ✅ Заказы, где она назначена
- ✅ Маршрутную информацию
- ✅ Параметры поставки (объем, количество мест)
- ✅ Свою стоимость доставки

**Не видит:**
- ❌ Все коммерческие данные участников
- ❌ Рецептуры товаров
- ❌ Информацию о товарах и услугах

## ⚙️ Конфигурация

### Feature Flags

Управляйте системой безопасности через переменные окружения:

```bash
# Основные настройки
ENABLE_SUPPLY_SECURITY=true          # Включить/выключить систему
ENABLE_SECURITY_AUDIT=true           # Аудит доступа к данным
SECURITY_STRICT_MODE=true            # Строгий режим (блокировка при сомнениях)

# Дополнительные настройки
SECURITY_CACHE_ENABLED=true          # Кеширование результатов фильтрации
SECURITY_REALTIME_ALERTS=true        # Real-time алерты безопасности
```

### Настройка аудита

```typescript
import { CommercialDataAudit } from '@/graphql/security'

// Получение статистики активности пользователя
const stats = await CommercialDataAudit.getUserActivityStats(
  prisma, 
  'user-id', 
  '24h'
)

// Получение активных алертов
const alerts = await CommercialDataAudit.getActiveAlerts(prisma, 50)
```

## 📊 Мониторинг и аудит

### Логирование

Система автоматически логирует:
- 🔍 Все обращения к коммерческим данным
- 🚨 Попытки несанкционированного доступа
- ⚡ Производительность фильтрации
- 🔔 Подозрительную активность

### Алерты безопасности

Автоматические алерты срабатывают при:
- Превышении лимитов обращений к данным
- Попытках доступа без партнерства
- Нарушениях изоляции между конкурентами
- Подозрительных паттернах доступа

## 🧪 Тестирование

### Демонстрация функций безопасности

```typescript
import { demonstrateSecurityFeatures } from '@/graphql/resolvers/secure-integration'

// Получение статуса системы безопасности
const status = await demonstrateSecurityFeatures()
console.log(status)
```

### Тестирование фильтрации

```typescript
import { SupplyDataFilter } from '@/graphql/security'

const mockOrder = {
  id: 'test-order',
  // ... данные заказа
}

const context = {
  user: {
    id: 'user-id',
    organizationId: 'org-id',
    organizationType: 'WHOLESALE',
  },
}

const filtered = SupplyDataFilter.filterSupplyOrder(mockOrder, context)
console.log('Filtered data:', filtered.data)
console.log('Removed fields:', filtered.removedFields)
```

## 🚀 Производительность

### Кеширование

Система поддерживает кеширование результатов фильтрации:

```bash
SECURITY_CACHE_ENABLED=true
```

### Оптимизация

- Фильтрация происходит только для включенных резолверов
- Аудит можно отключить в production для повышения производительности
- Используется lazy loading для модулей безопасности

## ⚠️ Важные замечания

1. **Обратная совместимость**: Система работает параллельно с существующими резолверами
2. **Постепенное внедрение**: Можно включать защиту резолверов по одному
3. **Отключение в development**: Для отладки можно отключить всю систему
4. **Аудит в production**: Рекомендуется включить аудит для мониторинга

## 📚 API Reference

### Основные функции

- `wrapResolversWithSecurity(resolvers)` - автоматическая интеграция
- `createSecureResolver(resolver, config)` - ручная интеграция
- `SupplyDataFilter.filterSupplyOrder(order, context)` - фильтрация данных
- `ParticipantIsolation.validatePartnerAccess(...)` - проверка партнерства
- `CommercialDataAudit.logAccess(...)` - аудит доступа

### Типы

- `SecurityContext` - контекст безопасности пользователя
- `ResourceType` - типы защищаемых ресурсов
- `CommercialAccessType` - типы доступа к коммерческим данным
- `DataAccessLevel` - уровни доступа к данным

## 🆘 Устранение неполадок

### Система безопасности не работает
1. Проверьте `ENABLE_SUPPLY_SECURITY=true`
2. Убедитесь, что резолвер включен в конфигурацию
3. Проверьте, что middleware применен к резолверам

### Пользователи не видят данные
1. Проверьте роль пользователя в организации
2. Убедитесь в наличии партнерских отношений
3. Проверьте логи аудита для диагностики

### Низкая производительность
1. Включите кеширование `SECURITY_CACHE_ENABLED=true`
2. Отключите аудит в production при необходимости
3. Оптимизируйте запросы к базе данных