## Гайд по репозиторию `rm.ui-kit` для ИИ‑агентов

Этот файл — «карта местности» для всего репозитория.  
Он помогает ИИ‑агенту быстро понять, **где что лежит**, **как это связано** и **куда правильнее вносить изменения**.

- Для детальной доки по самим UI‑компонентам и внутренней структуре ui‑кита см. `docs/ui-kit-for-agents.md`.

---

## 1. Общий обзор проекта

- **Назначение репо**: библиотека UI‑компонентов, бизнес‑модулей и готовых блоков для проекта `rosmigrant.online`, распространяемая как npm‑пакет `@soroka282/rm.ui-kit`.
- **Точка входа библиотеки**: `src/index.ts`
  - Импортирует глобальные стили ui‑кита.
  - Реэкспортирует:
    - базовые UI‑компоненты (`UIButton`, `UICard`, `UIModal`, `UIDetailActionsSheet`, `UISvgIcon`, `UISelect`, `UISteps`, тосты и др.);
    - типы (`UISize`, `UIColor`, и т.п.);
    - утилиты и composables;
    - плагины (включая `UIKitInstall`);
    - store’ы;
    - конфиги (`uiKitI18n`, стор настроек ui‑кита);
    - бизнес‑модули (`auth`, `documents`, `form`);
    - UI‑блоки (`UI-blocks`), которые собирают компоненты/модули в более сложные куски интерфейса.

- **Сборка**:
  - `vite.config.ts` — билд в формате библиотеки (ES + UMD), точка входа `src/index.ts`, алиас `@` → `src`.
  - `package.json`:
    - `main/module/types` смотрят в `dist/*`.
    - Скрипты: `dev`, `build`, `storybook`, `lint*`, `publish:npm` и т.д.

---

## 2. Корневая структура

Основные элементы в корне репозитория:

- `src/` — **главный код пакета**.
- `docs/` — внутренние текстовые гайды (например, `ui-kit-for-agents.md`).
- `.storybook/` — конфиг Storybook для визуальной документации компонентов.
- `vite.config.ts` — конфиг сборки.
- `tsconfig.json`, `jsconfig.json`, `.editorconfig`, `.prettierrc` и прочие конфиги.
- `README.md` — публичная документация для людей (установка, запуск, коммиты, публикация).

Если ИИ‑агент должен понять, **что экспортируется наружу**, начинать нужно с `src/index.ts`, затем смотреть `index.ts` в подпапках.

---

## 3. `src/` — ядро пакета

Главные поддиректории:

- `src/UI-kit` — **библиотека базовых UI‑компонентов и инфраструктуры** (подробно описано в `docs/ui-kit-for-agents.md`).
- `src/modules` — **бизнес‑модули**, завязанные на конкретные сценарии (auth, документы, формы).
- `src/UI-blocks` — **готовые сложные блоки**, собранные из ui‑кита и модулей.
- `src/configs` — **общие конфиги**, i18n, стор настроек ui‑кита и вспомогательные composables.
- `src/App.vue` — локальный playground/демо для разработки (не входит в публичный API пакета).

Ниже — краткое описание каждого слоя, кроме самого ui‑кита (он уже задокументирован отдельно).

---

## 4. `src/configs` — конфигурация и общие настройки

- **`configs/i18n.config.ts`**
  - Определяет `uiKitI18n` (экземпляр `vue-i18n`).
  - Собирает:
    - базовые локали ui‑кита из `src/UI-kit/constants/languages/*.ts` (`defaultLocaleRu`, `defaultLocaleKg`, `defaultLocaleUz`, `defaultLocaleTj`, включая секцию `ui.loader` с текстами лоадера для всех языков);
    - локали модуля документов (`modules/documents/constants/languages/*.ts`);
    - локали модуля авторизации (`modules/auth/constants/languages/*.ts`).
  - Структура сообщений: ключи `ru`, `kg`, `tj`, `uz` с вложенными `moduleDocuments` и `moduleAuth`.

- **`configs/store/use-ui-kit-config.store.ts`**
  - Pinia‑стор для глобальных настроек ui‑кита (`useUiKitConfigStore`):
    - `userAuthToken`, `appVersion`;
    - методы `setLocale(locale)`, `setGlobalModulesProperty(locale, token)`.
  - Используется бизнес‑модулями/блоками для установки локали и передачи auth‑токена.

- **`configs/composables`**
  - Например, `useUiKitI18n` — удобная обёртка для работы с `uiKitI18n`.
  - `useConfigConnectors` — для работы с конфигами/коннекторами.

- **`configs/index.ts`**
  - Реэкспортирует:
    - `uiKitI18n`;
    - composables;
    - типы и сторы.
  - Всё это далее реэкспортируется через `src/index.ts`.

**Рекомендация для ИИ‑агента**:
- Если нужно добавить/изменить глобальные настройки ui‑кита (локаль, конфиг коннекторов, глобальный стейт), смотри сначала сюда.

---

## 5. `src/modules` — бизнес‑модули

### 5.1. `modules/auth` — модуль авторизации

- **Файлы**:
  - `AuthModule.vue` — контейнер модуля авторизации.
  - `components/AuthForm.vue`, `components/AuthCheckCodeForm.vue` — формы ввода номера/кода.
  - `store/auth.store.ts` + `store/index.ts` — управление состоянием авторизации.
  - `composables` — логика работы с API и состоянием (`useAuthConnector`, `useInitAuthState` и др.).
  - `constants/languages/*.ts` — тексты для i18n модуля авторизации.
  - `type/*` — типы данных, которые использует модуль auth.

- **Экспорт**:
  - `modules/auth/index.ts` собирает типы, composables и сторы.
  - `AuthModule`, `AuthForm`, `AuthCheckCodeForm` дополнительно реэкспортируются в `src/index.ts`.

**Когда сюда лезть ИИ‑агенту**:
- Нужны изменения в **процессе авторизации** (UI/логика), но в рамках уже существующих сценариев.
- Требуется добавить новые тексты/локали для auth → `constants/languages` + `i18n.config.ts`.

### 5.2. `modules/documents` — модуль работы с документами

- **Файлы**:
  - `ModuleDocuments.vue`, `ModuleDocumentsList.vue` — основные контейнеры модуля.
  - `components/DocumentCard.vue`, `components/DeleteDocumentModal.vue` — UI части модуля.
  - `store/module-document.store.ts` — состояние документов.
  - `composables`:
    - `useModuleDocumentConnector`, `useDocumentModuleHandlers`, `usePrepareFields`,
    - `useDefaultFields`, `useUserImageDocument`, `useDocumentImage` и др.
    - `fields-schemes/*` — схемы полей для разных типов документов.
  - `constants`:
    - `validation/*.validation.ts` — валидации по типам документов;
    - `languages/*.ts` — тексты;
    - `directory.ts` — справочники и т.п.
  - `type/*` — типы документов, полей, опций.
  - Storybook‑файл `ModulesDocumentForm.stories.ts`.

- **Экспорт**:
  - Всё существенное собирается в `modules/documents/index.ts` и далее экспортируется из `src/index.ts`.

**Когда сюда лезть ИИ‑агенту**:
- Нужно изменить или добавить **тип документа**, его валидацию, форму, тексты или обработчики.
- Нужна логика работы с фото документов (съёмка/загрузка/удаление).

### 5.3. `modules/form` — модуль динамических форм

- **Файлы**:
  - `ModuleForm.vue` — основной компонент модуля форм.
  - `components/Field.vue` — отрисовка отдельного поля в зависимости от типа.
  - `types/input-type.type.ts` и `types/index.ts` — типизация конфигураций полей и входных данных.
  - Storybook `ModulesForm.stories.ts` — демонстрация использования формы.

- **Взаимосвязь**:
  - Модуль форм активно использует компоненты из `UI-kit` (инпуты, селекты, модалки и т.д.).

**Когда сюда лезть ИИ‑агенту**:
- Нужно завести новый тип поля или изменить схему существующих.
- Требуется обновить, как конфиг формы мапится на реальные UI‑компоненты.

---

## 6. `src/UI-blocks` — композиционные блоки

Это более «высокоуровневые» куски интерфейса, которые собирают:

- компоненты `UI-kit`,
- бизнес‑модули (`modules/*`),
- конфиги и сторы.

### Примеры

- `UI-blocks/components/BlockCard/UIBlockCardType1.vue`
  - Оборачивает `UICard`, использует `UISvgIcon`, цвета `UIColor` и иконки `UIIconsValues`.
  - Представляет готовый «карточный» блок с текстом и иконками слева/справа.

- `UI-blocks/components/BlockSavedImage/Type1/UIBlockSaveImageType1.vue`
  - Использует:
    - `UICard`, `CloseBtn` из ui‑кита;
    - composables `useCheckAppVersion`, `useIframeHandlers`;
    - константы `postMessageFromApp`, `postMessageToApp`;
    - `parentMessage` из утилит;
    - типы и коннекторы модуля документов;
    - `useUiKitConfigStore` и `useUiKitI18n` из `configs`;
    - стор модалок `useUIModalStore`.
  - Реализует сложный сценарий: показ последних фото документов, взаимодействие с приложением через `postMessage`, открытие модалок с просмотром фото.

**Рекомендации для ИИ‑агента**:
- Если нужно собрать **готовый многоразовый блок**, использующий сразу несколько модулей/компонентов —
  лучше создавать его в `src/UI-blocks`, а не в `UI-kit`.
- Следи за тем, чтобы:
  - бизнес‑логика специфического сценария оставалась в блоках/модулях, а не уезжала в базовые компоненты;
  - ui‑кит оставался переиспользуемым и не знал о конкретных документах/авторизации.

---

## 7. Storybook (`.storybook` + `*.stories.ts`)

- **`.storybook/main.ts`**
  - Подключает все истории: `../src/**/*.stories.@(ts)` и `mdx`.
  - В `viteFinal` прописывает `resolve.alias`: `@` → `../src`, чтобы компоненты могли использовать `@/UI-kit/...` в `<style lang="scss">`.

- **`.storybook/preview.ts`**
  - Импортирует `../src/UI-kit/assets/scss/index.scss` напрямую — для глобальных стилей (reset, шрифты, переменные).
  - Регистрирует плагины через `setup(app => app.use(...))`: `pinia`, `Maska`, `formatter`, `pluralEndings`, `uiKitI18n` (обязателен — без него `useI18n()` в `UIButton`/`UILoaderV2` бросает ошибку).

- **`.storybook/common.scss`** — минимальные вспомогательные классы для историй (`.d-flex`).

- **Истории компонентов** (`*.stories.ts`)
  - Лежат рядом с компонентами (`UI-kit`, `modules`, `UI-blocks`).
  - Показывают пример использования и помогают понять контракт компонента/модуля/блока.
  - Текущее покрытие: `UIButton`, `UICard`, `UIChip`, `UIDescription`, `UIDetailActionsSheet`, `UIInfo`, `UIInput`, `UILoader`, `UIModal`, `UIRadioButton`, `UISelect`, `UISteps`, `UISvgIcon`, `UISwiper`, `UITitle`, `UIToastNotification`, `ModulesForm`, `ModulesDocumentForm`, `UIBlockCardType1`, `UIBlockSaveImageType1`.

**Для ИИ‑агента**:
- При изменении API компонента/блока не забывай обновлять истории.
- Новый публичный компонент/блок — желательно сразу снабжать сторибуком.
- Если добавляешь компонент, использующий `useI18n()` или другой плагин — убедись, что он подключён в `preview.ts`.

---

## 8. Где и что править ИИ‑агенту

- **Базовые визуальные элементы, стили, общие утилиты** → `src/UI-kit`  
  (и см. подробный гайд в `docs/ui-kit-for-agents.md`).

- **Авторизация** → `src/modules/auth`
  - UI форм, тексты, валидация, состояния авторизации, взаимодействие с API.

- **Документы** → `src/modules/documents`
  - Типы документов, схемы полей, валидации, загрузка/удаление изображений, тексты.

- **Генерация форм** → `src/modules/form`
  - Типы полей, сопоставление типов с UI‑компонентами, поведение формы.

- **Сложные готовые блоки интерфейса** → `src/UI-blocks`
  - Когда сценарий использует сразу несколько модулей/компонентов и нужен как отдельный reusable‑блок.

- **Глобальные настройки, локали, токены, версия приложения** → `src/configs`
  - `i18n.config.ts`, `use-ui-kit-config.store.ts`, composables конфигов.

- **Публичный API пакета** → `src/index.ts`
  - Если сущность должна использоваться снаружи (`import { X } from '@soroka282/rm.ui-kit'`), она должна экспортироваться тут (напрямую или через промежуточные `index.ts`).

---

## 9. Краткие навигационные подсказки

- Хочешь понять, **что доступно потребителям пакета** → смотри `src/index.ts`.
- Ищешь **конкретный UI‑компонент** → `src/UI-kit/components` + его `*.stories.ts`.
- Ищешь **общую логику без привязки к экрану** → `src/UI-kit/composables` и `src/UI-kit/utils`.
- Нужны **конкретные сценарии (auth, документы)** → `src/modules/auth`, `src/modules/documents`.
- Нужен **готовый блок интерфейса** → `src/UI-blocks`.
- Нужны **локали/языки** → `src/UI-kit/constants/languages` и `src/modules/*/constants/languages`, сборка — в `src/configs/i18n.config.ts`.

