npm package: @ibdop/platform-kit
Description: Platform Kit - переиспользуемые хуки и компоненты для MF IngoBank DevOps Platform
Author: IngoBank DevOps Team
Latest version: 1.0.21

# Platform Kit

> Единый пакет для микрофронтендов IngoBank DevOps Platform

## Установка

```bash
npm install @ibdop/platform-kit --registry https://repo.dev.ingobank.ru/artifactory/api/npm/npm-local/
```

### Или настройте registry для scoped package

```bash
npm config set @ibdop:registry https://repo.dev.ingobank.ru/artifactory/api/npm/npm-local/
npm install @ibdop/platform-kit
```

### Peer Dependencies

```bash
npm install react "^18.0.0"
npm install react-dom "^18.0.0"
npm install axios "^1.0.0"
```

## Быстрый старт

```typescript
import { ErrorBoundary, useShellAuth, createApiClient } from '@ibdop/platform-kit'

export function App() {
  const auth = useShellAuth()
  const api = createApiClient()

  return (
    <ErrorBoundary mfeName="@ibdop/mf-example">
      <Dashboard auth={auth} />
    </ErrorBoundary>
  )
}
```

## Что внутри

| Модуль | Назначение | Содержимое |
|--------|------------|------------|
| **Hooks** | React хуки для работы с shell и платформой | `useShellAuth` - аутентификация из shell<br>`useInfoData` - информация о версии MF<br>`useV1Config` - V1 конфигурация<br>`useApi` - HTTP запросы с обработкой ошибок<br>`usePermissions` - проверка прав доступа<br>`useFeatures` - feature toggles пользователя<br>`useFeatureAdmin` - управление фичами (admin) |
| **Components** | React компоненты для MF | `ErrorBoundary` - перехват ошибок с отправкой в shell<br>`VersionInfo` - отображение версии MF<br>`NotificationProvider` - система уведомлений |
| **Services** | Сервисы для работы с API и логированием | `createApiClient` - HTTP клиент на axios<br>`get/post/put/del` - методы API<br>`createMfLogger` - логгер для MF |
| **Utils** | Утилиты для работы с именем MF и auth | `getMfeName/requireMfeName` - получение имени MF<br>`getShellAuth/getAccessToken` - прямой доступ к auth<br>`isAuthenticated/redirectToLogin/logout` - auth утилиты |

## Роли и claims

`usePermissions()` и связанные auth-утилиты читают роли пользователя из всех поддерживаемых claims shell-профиля:

- `realm_roles`
- `roles`
- `realm_access.roles`

Роли объединяются без дублей, поэтому микрофронты остаются совместимыми и со старым профилем shell, и с prod-токенами Keycloak.

### Назначение Platform Kit

**Platform Kit** — это единый набор инструментов для всех микрофронтендов (MF) платформы IngoBank DevOps:

- 🔐 **Единая аутентификация** — все MF получают auth из shell через `useShellAuth`
- 📊 **Информация о версиях** — централизованное отображение версий MF
- 🚦 **Feature Toggles** — управление функциями без деплоя
- 🛡️ **Error Boundaries** — перехват ошибок с отправкой в shell
- 📡 **HTTP клиент** — единый API с обработкой ошибок и прокси
- 🔔 **Уведомления** — кросс-MF система нотификаций
- 📝 **Логирование** — структурированные логи для отладки
- 🧵 **Trace propagation** — автоматическое добавление `traceparent` для `/api/*` и `/svc/*` запросов через `createApiClient`

## Документация

- **[`docs/USAGE.md`](docs/USAGE.md)** - Подключение и использование
- **[`docs/BUILD_AND_PUBLISH.md`](docs/BUILD_AND_PUBLISH.md)** - Сборка и публикация
- **[`PUBLISH_GUIDE.md`](PUBLISH_GUIDE.md)** - Руководство по публикации
- **[`CHANGELOG.md`](CHANGELOG.md)** - История изменений
- **[`PLAN.md`](PLAN.md)** - План разработки

## Публикация

Автоматическая публикация через GitLab CI/CD:

```bash
# Обновление версии и создание тега
npm version patch  # или minor/major

# Push тега - CI/CD автоматически опубликует пакет
git push origin main --tags
```

## Миграция

### Было

```typescript
import { useShellAuth } from './hooks/useShellAuth'
import ErrorBoundary from './components/ErrorBoundary'
```

### Стало

```typescript
import { useShellAuth, ErrorBoundary } from '@ibdop/platform-kit'
```

## CI/CD

- **Pipeline**: GitLab CI/CD
- **Сборка**: Docker (node-builder:24.13.0-r1)
- **Registry**: Artifactory NPM (`repo.dev.ingobank.ru`)
- **Триггер**: Git теги `v*.*.*`

## Лицензия

MIT © IngoBank DevOps Team