Krona Universal Business OS — Interactive Frontend Prototype

Автономный интерактивный референс-прототип универсальной бизнес-экосистемы «Крона» (Krona Business Platform)
Разработан в соответствии с нормативными спецификациями ochenstarik/business-platform.

---

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

Команды разработки

# Установка зависимостей
npm install

# Запуск dev-сервера (http://localhost:5173)
npm run dev

# Проверка строгой типизации TypeScript
npx tsc -b

# Проверка линтером Oxlint
npm run lint

# Запуск автоматизированных тестов Vitest (85 тестов)
npm test

# Запуск тестов в режиме наблюдения
npm run test:watch

# Сборка оптимизированного production bundle
npm run build

---

3. Архитектура слоев

Проект структурирован строго по методологии FSD-like / Layered Architecture:

src/
├── app/                  # Инициализация приложения, провайдеры, роутер, shell, guards
│   ├── guards/           # RouteGuard (RBAC + Capability + State Override)
│   ├── layouts/          # AppShell (Desktop / Tablet / Mobile адаптивный фрейм)
│   ├── providers/        # ErrorBoundary, QueryClientProvider, 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/               # Библиотека переиспользуемых компонентов и утилит
│   ├── components/       # Базовые контролы (Button, Input, Select, Badge, Drawer, Modal)
│   ├── lib/              # ULID генератор, форматирование валюты/дат, debounce
│   └── ui/               # MaturityBadge, ErrorBoundary, Skeleton, Toast
└── 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. Лицензия и авторство

Разработано для платформы «Крона». Все права защищены.