218 lines
18 KiB
Markdown
218 lines
18 KiB
Markdown
# Krona Universal Business OS — Interactive Frontend Prototype
|
||
|
||
> **Автономный интерактивный референс-прототип универсальной бизнес-экосистемы «Крона» (Krona Business Platform)**
|
||
> Разработан в соответствии с нормативными спецификациями `ochenstarik/business-platform`.
|
||
|
||
[](https://vitejs.dev/)
|
||
[-emerald.svg)](https://vitest.dev/)
|
||
[](https://www.typescriptlang.org/)
|
||
[](#дизайн-система)
|
||
|
||
---
|
||
|
||
## 1. Назначение платформы
|
||
|
||
Проект представляет собой полностью интерактивный frontend-прототип операционной системы для бизнеса (Universal Business OS). Он позволяет владельцу бизнеса, топ-менеджменту, разработчикам и дизайнерам пройти по всем ключевым сценариям продукта без подключения реального бэкенда:
|
||
- Переключать отраслевые бизнес-профили (Ресторан Зал+Доставка, Дарккитчен, Ритейл, Автомойка/СТО, Салон красоты, Опт B2B);
|
||
- Переключать ролевую модель (10 системных ролей RBAC от Владельца до Кассира, Повара и Курьера);
|
||
- Использовать полнофункциональный **Configuration Engine**: создавать пользовательские сущности, добавлять типизированные поля (39+ типов), конструировать формы, карточки и представления;
|
||
- Запускать сквозные бизнес-потоки **Pilot 1** (BF-01: Лид → Контакт → Сделка → Заказ; BF-02: Заказ → Резерв → Оплата → Отгрузка);
|
||
- Работать с целевыми модулями экосистемы (POS, KDS, Карта залов, Склад, HelpDesk, Омниканальные чаты, Задачи, CMS Page Builder, Маркетинг, Автоматизации, Аналитика, AI Center) с честной маркировкой зрелости компонентов (`Pilot 1`, `Target prototype`, `Demo only`);
|
||
- Сохранять состояние в локальной базе **IndexedDB** с версионированием, экспортом/импортом снапшотов и сбросом демо;
|
||
- Тестировать интерфейс в эмуляторе адаптивности: Desktop (1440×900), Tablet Landscape (1180×800), Tablet Portrait (820×1050), Mobile (420×880).
|
||
|
||
---
|
||
|
||
## 2. Быстрый старт
|
||
|
||
### Требования
|
||
- Node.js >= 18.x
|
||
- npm >= 9.x
|
||
|
||
### Команды разработки
|
||
```bash
|
||
# Установка зависимостей
|
||
npm install
|
||
|
||
# Установка браузера Chromium для воспроизводимого запуска Playwright E2E тестов
|
||
npx playwright install chromium
|
||
|
||
# Запуск dev-сервера (http://localhost:5173)
|
||
npm run dev
|
||
|
||
# Проверка строгой типизации TypeScript
|
||
npx tsc -b
|
||
|
||
# Проверка линтером Oxlint (0 warnings, 0 errors с флагом --deny-warnings)
|
||
npm run lint
|
||
|
||
# Запуск автоматизированных unit/integration тестов Vitest (407 тестов в 13 файлах)
|
||
npm test
|
||
|
||
# Запуск тестов в режиме наблюдения
|
||
npm run test:watch
|
||
|
||
# Сборка оптимизированного production bundle (<250 kB gzip, факт ~146 kB gzip)
|
||
npm run build
|
||
|
||
# Запуск сквозных E2E сценариев Playwright (30 тестов: 10 сценариев × 3 viewports: desktop, tablet, mobile)
|
||
npm run test:e2e
|
||
|
||
# Полный verification pipeline проекта
|
||
npm run check
|
||
```
|
||
|
||
### Комплексный контур верификации (`npm run check`)
|
||
Команда `npm run check` запускает полный цикл валидации качества:
|
||
1. `oxlint --deny-warnings` — линтинг без предупреждений и ошибок (196 файлов);
|
||
2. `tsc -b` — строгая компиляция TypeScript 5.8+ без ошибок типов;
|
||
3. `vitest run` — 407 модульных и интеграционных тестов (13 тестовых сюит, 100% pass);
|
||
4. `vite build` — production сборка с бандлом ядра ~146 kB gzip (бюджет < 250 kB gzip);
|
||
5. `playwright test` — 30 E2E сценариев в браузерном окружении Chromium на десктопе, планшете и мобильном телефоне.
|
||
|
||
---
|
||
|
||
## 3. Архитектура слоев
|
||
|
||
Проект структурирован строго по методологии FSD-like / Layered Architecture:
|
||
|
||
```text
|
||
src/
|
||
├── app/ # Инициализация приложения, провайдеры, роутер, shell, guards
|
||
│ ├── guards/ # RouteGuard (RBAC + Capability + State Override)
|
||
│ ├── layouts/ # AppShell (Desktop / Tablet / Mobile адаптивный фрейм)
|
||
│ ├── providers/ # AppProviders, TenantProvider, ToastProvider
|
||
│ ├── router/ # React Router 6 с code-splitting для каждого модуля
|
||
│ └── shell/ # Sidebar, Topbar, BottomNav, CommandPalette (Ctrl+K), AI Drawer
|
||
├── core/ # Фундаментальные реестры платформы
|
||
│ ├── capabilities/ # Реестр возможностей бизнеса (CRM, POS, KDS, Dining и т.д.)
|
||
│ ├── modules/ # Реестр 17 системных модулей платформы
|
||
│ ├── permissions/ # 10 ролей RBAC с матрицей доступных разделов
|
||
│ ├── profiles/ # 6 преднастроенных профилей бизнеса с отраслевой терминологией
|
||
│ └── theme/ # Семантические токены Krona (Green, Gold, Surface)
|
||
├── entities/ # Типы и контракты доменных сущностей (Contact, Deal, Order...)
|
||
├── features/ # Модули прикладной функциональности
|
||
│ ├── ai/ # AI Center (симуляция оркестратора, мультиагентные промпты)
|
||
│ ├── analytics/ # Аналитика (KPIs, динамические периоды, ABC-анализ)
|
||
│ ├── apps/ # Каталог расширений и интеграций
|
||
│ ├── automation/ # Конструктор бизнес-процессов с логом тестирования
|
||
│ ├── cms/ # Визуальный Page Builder (6 типов виджетов, JSON-экспорт)
|
||
│ ├── communications/ # Омниканальный Inbox (TG, WA, MAX, автоответчик)
|
||
│ ├── crm/ # CRM 360 (Лиды, Контакты, Компании, Сделки Kanban)
|
||
│ ├── dashboard/ # Динамический дашборд с виджетами под профиль бизнеса
|
||
│ ├── employees/ # Персонал и планировщик смен с контролем >12ч
|
||
│ ├── finance/ # Финансы (ДДС, P&L, статьи расходов, кассовые смены)
|
||
│ ├── helpdesk/ # Служба поддержки (тикеты, SLA таймеры, публичные/внутренние заметки)
|
||
│ ├── inventory/ # Складской учет (остатки, партии, списания, оприходования)
|
||
│ ├── marketing/ # Маркетинговые кампании и конструктор сегментов
|
||
│ ├── metadata/ # DynamicFormRenderer, DynamicCardRenderer, FieldRenderer
|
||
│ ├── operations/ # Операции (POS касса, KDS дисплей кухни, Столы/Брони)
|
||
│ ├── sales/ # Продажи и заказы (реестр заказов, статусы исполнения)
|
||
│ ├── settings/ # Настройки платформы и Configuration Engine
|
||
│ └── tasks/ # Задачи (Kanban доска, чек-листы, комментарии)
|
||
├── services/ # Сервисный слой абстракций и контрактов
|
||
│ ├── contracts/ # TypeScript интерфейсы для всех бизнес-сервисов
|
||
│ ├── mock/ # Репозитории с имитацией latency, validation, audit log
|
||
│ └── storage/ # Версионированная IndexedDB (7 stores, snapshots, reset)
|
||
├── shared/ # Библиотека переиспользуемых компонентов и утилит
|
||
│ ├── lib/ # ULID генератор, форматирование валюты/дат, debounce
|
||
│ └── ui/ # Единый UI-Kit: Button, Input, Select, Badge, Drawer, Modal, Toast, Skeleton, etc.
|
||
└── stores/ # Zustand хранилища для UI и Demo-состояния
|
||
├── demo.ts # Demo Controls (профиль, роль, ошибки, часы, latency)
|
||
├── navigation.ts # Состояние мобильного меню и аккордеонов
|
||
└── theme.ts # Переключение Light / Soft-Light / Dark c persistence
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Configuration Engine — Конструктор платформы
|
||
|
||
Раздел `Настройки → Сущности` (`/settings/entities`) представляет собой полноценный рабочий no-code конструктор платформы:
|
||
|
||
### 4.1 Каталог сущностей
|
||
- Отображение системных (`contact`, `company`, `lead`, `deal`, `order`, `product`, `warehouse`, `task`, `employee`, `ticket`) и кастомных сущностей;
|
||
- Создание новой сущности: код, названия (ед./мн. число), иконка, цвет, автонумерация, категория;
|
||
- Созданные кастомные сущности **моментально регистрируются** в боковом меню (Sidebar), Command Palette (Ctrl+K) и получают маршруты `/entities/:code` с рабочим списком и карточкой.
|
||
|
||
### 4.2 Field Builder (Редактор полей)
|
||
- Поддержка полного реестра типов (39+ типов из спецификации `docs/52-FIELD-TYPES-REFERENCE.md`):
|
||
- Примитивные: `text`, `long_text`, `rich_text`, `integer`, `decimal`, `money`, `percentage`, `boolean`, `date`, `datetime`, `time`;
|
||
- Перечисления: `select`, `multi_select`, `radio`, `checkbox_group`, `status`, `rating`;
|
||
- Контакты и медиа: `phone`, `email`, `url`, `address`, `location`, `file`, `image`, `color`;
|
||
- Отношения и связи: `entity_relation`, `one_to_one`, `one_to_many`, `many_to_many`, `user`, `employee`, `customer`, `product`;
|
||
- Вычисляемые: `formula`, `calculated`, `autonumber`, `json`;
|
||
- Настройки поля: label, machine name, required, unique, read-only, hidden, searchable, filterable, default value;
|
||
- Редактор списка вариантов (options) с возможностью назначения цвета и архивации значений;
|
||
- Защита системных инвариантов: системные поля невозможно удалить или несовместимо изменить.
|
||
|
||
### 4.3 Form Builder (Конструктор форм)
|
||
- Визуальный drag-and-drop редактор форм создания и редактирования;
|
||
- Палитра доступных полей, холст с секциями, колонками и вкладками;
|
||
- Настройка параметров каждого блока в правой инспектор-панели;
|
||
- Переключение адаптивного предпросмотра (Desktop / Tablet / Mobile).
|
||
|
||
### 4.4 Card Layout Builder (Конструктор карточки записи)
|
||
- Модульная сборка карточки: заголовок, блок полей, вкладки, связанные списки, таймлайн активности, задачи, заметки, аудит;
|
||
- Настройка первичных и вторичных полей заголовка;
|
||
- Предпросмотр на реальных demo-данных.
|
||
|
||
### 4.5 View Builder (Конструктор представлений / таблиц)
|
||
- Выбор колонок из всех доступных системных и кастомных полей;
|
||
- Drag-and-drop порядка колонок, ширина, закрепление (pinned), сортировка;
|
||
- Конструктор быстрых фильтров.
|
||
|
||
---
|
||
|
||
## 5. Сквозные сценарии Pilot 1
|
||
|
||
### Сценарий BF-01: CRM Deal → Order
|
||
1. Входящий лид регистрируется в CRM с контактами и суммой.
|
||
2. Лид конвертируется в Контакт и связанную Сделку.
|
||
3. Сделка перемещается по стадиям Kanban (Квалификация → КП → Переговоры → Успешно / Won).
|
||
4. При переходе в `Won` автоматически формируется коммерческий Заказ в модуле Продаж со спецификацией товаров и расчетом сумм.
|
||
|
||
### Сценарий BF-02: Order Lifecycle (Confirm → Reserve → Pay → Ship)
|
||
1. Черновик заказа подтверждается оператором (`Confirm`).
|
||
2. На складе автоматически создается резерв остатка товара (`Reservation`).
|
||
3. Принимается оплата (наличные, карта или сплит) — в модуле Финансы формируется проводка ДДС (Cash-flow).
|
||
4. Оформляется отгрузка (`Shipment`) — физический остаток на складе списывается, резерв снимается, статус заказа переходит в `Completed`.
|
||
|
||
---
|
||
|
||
## 6. Маркировка зрелости функций (Maturity Badges)
|
||
|
||
В шапке каждого экрана расположен компонент `<MaturityBadge />`, четко информирующий пользователя об уровне готовности:
|
||
|
||
| Бейдж | Уровень | Описание | Примеры модулей |
|
||
|---|---|---|---|
|
||
| `Pilot 1` (Зеленый) | Готово к пилоту | Полноценная архитектура данных, сквозные сценарии, валидация, проводки | Dashboard, CRM, Sales, Inventory, Finance, Configuration Engine, Settings |
|
||
| `Target prototype` (Синий) | Целевой прототип | Интерактивный макет с локальным состоянием для согласования продуктового UX | Operations (POS, KDS, Зал), Employees, Communications, HelpDesk, Tasks, CMS, Marketing, Automation, Analytics |
|
||
| `Demo only` (Фиолетовый) | Демонстрация концепта | Эмуляция сложных процессов (AI-оркестрация, сторонний маркетплейс) | AI Center, Apps Catalog |
|
||
|
||
---
|
||
|
||
## 7. Демо-контролы и управление состоянием
|
||
|
||
В верхней панели (Topbar) и правой панели Command Panel доступны средства управления прототипом:
|
||
1. **Бизнес-профили:** Ресторан Зал+Доставка, Ресторан Доставка, Ритейл, Автомойка/СТО, Салон красоты, Опт B2B. Переключение мгновенно адаптирует состав меню, терминологию и виджеты.
|
||
2. **Роли RBAC:** 10 ролей с реальным контролем прав доступа через `RouteGuard`.
|
||
3. **State Override:** Normal, Loading (скелетон), Empty, Error (`ErrorBoundary`), Permission Denied (`403 Forbidden`).
|
||
4. **Снимки базы данных:** Экспорт снимка базы в JSON, восстановление из JSON-файла, сброс до эталонного seed-состояния.
|
||
|
||
---
|
||
|
||
## 8. Руководство по интеграции с Backend (REST API)
|
||
|
||
Архитектура сервисов полностью изолирует компоненты от хранилища:
|
||
1. Все обращения к данным происходят через хуки (`useOrders`, `useCrm`, `useInventory`, `useMetadata`) и типизированные контракты в `src/services/contracts/`.
|
||
2. Текущая реализация использует репозитории в `src/services/mock/` поверх IndexedDB.
|
||
3. Для перехода на реальный backend:
|
||
- Реализовать класс `ApiCommerceService implements ICommerceService` с методами `fetch() / axios`;
|
||
- Подставить его в экспорт сервиса `src/services/mock/index.ts`;
|
||
- UI-компоненты продолжат работать без изменений.
|
||
|
||
---
|
||
|
||
## 9. Лицензия и авторство
|
||
|
||
Разработано для платформы «Крона». Все права защищены.
|