# AGY-FE-01 — Полностью интерактивный frontend-прототип Krona Business Platform ## Статус и назначение **Тип:** крупная frontend-задача / product prototype / integration-ready foundation **Репозиторий исполнения:** `ochenstarik/krona-front` **Нормативный источник:** `ochenstarik/business-platform`, ветка `main` **Backend:** не требуется, кроме абстракций сервисов и mock-реализации **Главный результат:** владелец продукта может пройти по фронту все основные и целевые сценарии Krona, настроить систему, создать поля и сущности, менять layouts и представления drag-and-drop, обновить страницу и продолжить работу с сохранённым demo-состоянием. ## 1. Контекст `krona-front` уже содержит визуальный прототип React/Vite с модулями Dashboard, Operations, CRM, Sales, Inventory, Finance, Employees, Communications, HelpDesk, Tasks, CMS, Marketing, Analytics, Automation, AI, Apps и Settings. Однако это набор частично связанных demo-экранов: значительная часть кнопок декоративна, данные распределены между локальным Zustand store и отдельным mock API, нет устойчивого хранения, route guards, metadata-driven UI, полноценного Configuration Engine и тестового контура. Основной `business-platform` задаёт целевую архитектуру и уже содержит Pilot 1 реализацию в `apps/admin`, общий UI-kit в `packages/ui`, сервисные контракты и нормативную документацию. Не копировать основной проект вслепую. Использовать его как источник сущностей, терминов, полей, состояний, ролей, UI-контрактов и будущей интеграции. Ключевые источники перед началом работы: - `BUSINESS-PLATFORM-SPECIFICATION.md` - `docs/36-FRONTEND-ARCHITECTURE.md` - `docs/37-DESIGN-SYSTEM.md` - `docs/51-CONFIGURATION-ENGINE.md` - `docs/52-FIELD-TYPES-REFERENCE.md` - `docs/56-MODULE-CATALOG-UI.md` - `docs/22-CRM.md` - `docs/23-CRM-BUILDER.md` - `docs/20-PAGE-BUILDER.md` - `docs/107-ENTITY-MODULE-BUILDER.md` - `docs/109-PLATFORM-BLOCK-CONTRACT.md` - `docs/47-MVP.md` - `docs/pilot1/PILOT-1-RBAC-MATRIX.md` - `docs/pilot1/PILOT-1-STATE-MACHINES.md` - `apps/admin/src/**` и `packages/ui/src/**` как reference implementation Если текущее поведение `krona-front` противоречит нормативному `business-platform`, приоритет имеет `business-platform`. Не создавать таблицу или сущность `Customer`: клиент — роль `Contact | Company`. Денежные значения в модели хранить в minor units как integer плюс ISO 4217 currency code. Demo ID генерировать ULID, не `Math.random()` и не короткими случайными номерами. ## 2. Цель задачи Превратить `krona-front` в автономный, визуально цельный и полностью интерактивный frontend reference prototype, который: 1. показывает весь продукт, а не только Pilot 1; 2. демонстрирует реальные взаимосвязанные пользовательские потоки; 3. позволяет редактировать данные и конфигурацию без backend; 4. сохраняет данные и настройки между перезагрузками; 5. отделяет UI от источника данных и готов к замене mock services на REST API; 6. корректно работает на desktop, tablet и mobile; 7. имеет тесты ключевых сквозных сценариев; 8. не выдаёт декоративные элементы за работающие функции. Это frontend-прототип целевой архитектуры, поэтому разрешено визуально реализовать deferred-модули. В интерфейсе необходимо маркировать зрелость функций: `Pilot 1`, `Target prototype`, `Demo only`. Эти статусы не должны смешиваться. ## 3. Обязательные архитектурные изменения ### 3.1 Слои Перестроить frontend по слоям: - `app/` — providers, router, shell, error boundaries; - `entities/` — типы и metadata сущностей; - `features/` — пользовательские операции; - `pages/` — композиция экранов; - `shared/ui/` — дизайн-система; - `shared/lib/` — форматирование, ULID, DnD, storage; - `services/contracts/` — интерфейсы сервисов; - `services/mock/` — mock implementations; - `demo/fixtures/` — связанные сценарные данные; - `stores/` — только UI/session state, без дублирования серверного состояния. Запретить компонентам напрямую импортировать массивы fixtures. Любые CRUD-операции выполняются через typed service contracts. Mock service должен имитировать latency, validation errors, not found, conflicts и permissions. ### 3.2 Локальное хранение Реализовать versioned persistence через IndexedDB (предпочтительно) либо обоснованно через localStorage: - бизнес-данные; - metadata и custom fields; - layouts и saved views; - настройки пользователя и темы; - порядок dashboard widgets; - активированные модули; - demo-аудит изменений. Добавить миграции версии demo-схемы, seed/reset, экспорт и импорт JSON snapshot. Кнопка «Сбросить демо» должна требовать подтверждение. ### 3.3 Роутинг и доступ - Lazy loading всех route-level модулей. - Route guard по активным модулям, capabilities и текущей роли. - Страницы 403 и 404. - Error boundary на уровне приложения и маршрута. - Breadcrumbs и deep links для карточек сущностей. - Прямой URL закрытого модуля не должен обходить RBAC. ### 3.4 Единая модель UI-состояний Каждый экран обязан иметь и визуально поддерживать: - loading/skeleton; - empty state; - populated state; - validation error; - recoverable service error с retry; - permission denied; - success feedback; - destructive confirmation; - optimistic action либо явный progress. Добавить Demo Controls для переключения этих состояний без изменения кода. ## 4. Configuration Engine — центральный результат Создать полноценный раздел `Настройки → Сущности`. Это не статическая страница, а работающий frontend-конструктор. ### 4.1 Каталог сущностей Показывать системные и пользовательские сущности. Минимум: - Contact, Company, Lead, Deal; - Product, Category, Price List; - Order, Order Item, Payment, Shipment, Return; - Warehouse, Stock Item, Goods Receipt, Reservation; - Task, Employee; - пользовательские сущности. Для каждой сущности: название, множественное название, иконка, цвет, статус, системная/custom, число полей, layouts, views, relations и последнее изменение. ### 4.2 Field Builder Реализовать CRUD полей и изменение порядка drag-and-drop с клавиатурной альтернативой. Поддержать в UI полный реестр типов из `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; - user, employee, team, company, customer, product; - entity_relation, one_to_one, one_to_many, many_to_many; - formula, calculated, autonumber; - json только в administrator/developer mode. Редактор поля обязан включать: - label и immutable machine name; - тип, описание, placeholder, default value; - required, unique, read-only, hidden, searchable, filterable, sortable; - validation по типу: min/max, length, regex, precision, allowed file types/size; - options editor для списков: добавление, цвет, архивирование и drag-and-drop; - conditional visibility builder; - conditional required builder; - field-level permissions по ролям: view/edit; - analytics/search flags; - preview поля в create/edit/read-only состояниях; - предупреждение о влиянии изменения типа; - soft delete, список удалённых полей и restore; - индикатор использования поля в layouts, views, formulas и automations. Системные инвариантные поля нельзя удалить или несовместимо изменить. UI должен объяснять причину. ### 4.3 Form Builder Рабочий drag-and-drop редактор create/edit forms: - палитра доступных полей; - canvas с sections, tabs, columns и collapsible groups; - перенос поля из палитры и между контейнерами; - resize колонок в допустимой сетке; - свойства выбранного блока справа; - required/read-only/visibility override на уровне layout; - live preview desktop/tablet/mobile; - undo/redo минимум на 30 действий; - dirty state, save, discard, duplicate, restore default; - запрет потери несохранённых изменений при переходе; - keyboard-accessible reorder. ### 4.4 Card Layout Builder Позволить собирать карточку сущности из блоков: - header, fields, tabs, related list, timeline, tasks, notes, files, metrics, actions; - секции и колонки; - drag-and-drop, hide/show, resize; - настройка primary/secondary fields; - preview на реальной demo-записи; - варианты layout по роли при сохранении общей базовой схемы. ### 4.5 View / List Builder Для любого списка реализовать: - column selector со всеми system/custom fields; - drag-and-drop порядка колонок; - ширину, закрепление, видимость, сортировку; - quick filters и advanced filter builder с AND/OR groups; - grouping и aggregates; - density и pagination; - saved views: создать, переименовать, duplicate, сделать default, удалить; - shareable state через URL query; - inline edit для разрешённых полей; - multi-select и bulk edit; - export текущего представления в CSV. ### 4.6 Relation и Entity Builder - Создание relation с направлением, cardinality, labels и delete behavior только как demo-конфигурацией. - Создание custom entity: names, icon, color, primary field, autonumber, базовые permissions. - После сохранения custom entity автоматически появляется в навигации, Command Palette и доступна как список, форма и карточка. - Удаление сущности только soft delete с dependency impact preview. ## 5. Настройки платформы Раздел Settings должен содержать полностью работающие demo-настройки: 1. **Организация:** название, юр. данные, контакты, логотип, валюта, locale, timezone, начало недели, формат даты/времени. 2. **Филиалы и склады:** CRUD, адрес, timezone, часы работы, кассы/зоны как mock-настройки. 3. **Пользователи и команды:** CRUD, приглашение как demo, статус, роль, филиалы, команды. 4. **Роли и права:** матрица module/entity/action/field, clone role, сравнение ролей, preview «увидеть систему как роль». 5. **Сущности:** полный Configuration Engine из раздела 4. 6. **Воронки и статусы:** CRUD pipeline/stages, цвет, probability, required fields и drag-and-drop порядка. 7. **Нумераторы:** визуальная настройка prefix/pattern/next number с preview. 8. **Справочники:** единицы, категории, причины отмены/возврата, способы оплаты, источники лидов, теги. 9. **Уведомления:** матрица событий и каналов, quiet hours, шаблоны как demo. 10. **Интеграции:** каталог карточек, configure/test/disable в mock mode, никакого запроса реальных секретов. 11. **Импорт/экспорт:** CSV wizard с upload, mapping, preview, validation report и simulated import. 12. **Audit log:** фильтры, before/after diff, actor, timestamp, entity link. 13. **Темы и интерфейс:** 3 темы, плотность, reduced motion, sidebar, сохранение предпочтений. 14. **Demo data:** seed profile, reset, export/import snapshot, имитация ошибок и задержки. ## 6. Обязательные продуктовые сценарии Все перечисленные сценарии должны быть сквозными: изменение в одном модуле отражается в связанных модулях. ### 6.1 Pilot 1 - Contact/Company → Deal → Won → Order. - Order → Confirm → Reservation → Payment → Shipment. - Отмена и возврат с понятной визуальной историей. - Создание товара, категории, цены и складского остатка. - Goods receipt изменяет остаток. - Finance cash-flow показывает mock-проводки, возникшие из оплаты/возврата. - CSV import контактов и товаров с частично ошибочными строками. ### 6.2 CRM - Таблицы Contacts, Companies, Leads, Deals. - Полные create/edit/detail формы. - Kanban сделок с drag-and-drop, правилами допустимого перехода и rollback при mock-ошибке. - Activities, tasks, notes, files и timeline. - Customer 360: связанные сделки, заказы, оплаты, обращения и коммуникации. - Custom field, созданное в Settings, немедленно появляется в форме, карточке, фильтрах и column selector. ### 6.3 Commerce и Operations - Catalog, orders, order details, payments, returns. - POS demo с корзиной, скидками, клиентом, split payment mock и receipt. - Dining/table map, KDS, delivery, bookings, work orders и purchasing как связанные target prototypes. - Для deferred-функций показывать badge `Target prototype`, а не создавать впечатление готового backend. ### 6.4 Inventory и Finance - Остатки по складам, движения, резервы, приёмки, списания, инвентаризация. - Ledger-like timeline; резерв отображать отдельно от stock movement. - P&L/cash-flow/transactions/budgets в согласованных денежных форматах. ### 6.5 Tasks, Communications, HelpDesk, Employees - Kanban/list/calendar задач с drag-and-drop и detail drawer. - Unified inbox с выбором диалога, отправкой mock-сообщений и unread counters. - HelpDesk queue, карточка обращения, SLA, assignment и status transitions. - Employees, teams, schedule/shift planner с drag-and-drop и conflict indication. ### 6.6 CMS, Marketing, Automation, Analytics, AI - Page Builder: widgets palette, canvas, navigator tree, properties, drag-and-drop, responsive preview, undo/redo и сохранение JSON canvas. - Marketing: campaigns, segments и campaign builder mock. - Automation: trigger-condition-action builder с соединяемыми шагами либо последовательным workflow editor; test run log. - Analytics: dashboard widgets, filters, date ranges, reorder/resize widgets и сохранение layout. - AI Center: заранее подготовленные сценарии, tool-call-like progress и ссылки на изменённые объекты; явно маркировать как simulated AI. ## 7. Общие UX-требования - Сохранить визуальную основу Krona: Light/Soft Light, natural Green primary, Gold accent, Graphite text, Warm Beige surfaces; dark theme поддерживается. - Убрать raw colors из компонентов и свести их к semantic tokens. - Единые Button, IconButton, Input, Select, Checkbox, Radio, Switch, Tabs, DataTable, Modal, Drawer, Popover, Dropdown, Tooltip, Toast, Skeleton, Empty/Error states. - Все icon-only buttons имеют accessible name. - Modal/Drawer: focus trap, Escape, return focus, scroll lock, `aria-labelledby`. - Полная keyboard navigation для меню, таблиц, tabs, dialogs и DnD. - Respect `prefers-reduced-motion`. - Контраст WCAG AA для текста и контролов. - Не использовать browser breakpoints для эмуляции устройства внутри desktop-контейнера. Demo viewport должен менять настоящий preview iframe/viewport либо использовать container queries. - Mobile: никаких горизонтальных обрезаний; bottom nav ограничена viewport приложения. - Все кнопки либо работают, либо disabled с tooltip «будет доступно…». Никаких молча неработающих элементов. ## 8. Demo-сценарии и данные Создать не набор независимых случайных fixtures, а связанный demo tenant товарного бизнеса/e-commerce согласно Pilot 1. Дополнительно разрешён переключаемый ресторанный профиль для показа Operations/POS/KDS. Обязательно: - 2 tenant profiles, но одновременно активен один; - 2–3 филиала/склада; - не менее 30 contacts, 10 companies, 20 deals, 40 products, 25 orders; - данные покрывают все статусы, empty/error/edge cases; - единые ссылки между сущностями; - даты генерируются относительно фиксированного demo clock, чтобы snapshots были стабильными; - команда «Reset demo» воспроизводит идентичный seed. Добавить Scenario Switcher: - нормальная работа; - новый tenant / пустая система; - дефицит товара; - просроченные сделки и задачи; - платёжная ошибка; - недостаточно прав; - slow network/offline simulation. ## 9. Техническое качество - TypeScript strict без `any` в прикладном коде. - React-компоненты не должны выполнять нечистые функции во время render. - Никаких синхронных derived-state updates в effects. - Route-level code splitting; установить измеримый budget для initial bundle. - Крупные экраны разбить на feature-компоненты и hooks. - Не добавлять глобальный state без необходимости; memoized selectors для Zustand. - Все таймеры очищаются при unmount. - Sanitization для rich text preview. - Не хранить реальные PII, ключи или credentials. - Обновить README: назначение, запуск, архитектура, demo controls, test commands, интеграция с REST. ## 10. Тесты Настроить Vitest + React Testing Library + Playwright. Минимально обязательные automated tests: 1. build, typecheck, lint без warnings; 2. CRUD custom field и persistence после reload; 3. field появляется в dynamic form/card/table/filter; 4. drag-and-drop поля и сохранение порядка; 5. form/card/view builder save, undo, discard; 6. создание custom entity и появление в navigation; 7. CRM deal drag между стадиями; 8. Contact/Company → Deal → Order; 9. Order → reservation → payment → shipment; 10. RBAC route denial по прямому URL; 11. modal focus trap и keyboard DnD; 12. desktop 1440×900, tablet 768×1024, mobile 390×844 без horizontal overflow; 13. theme persistence и reduced motion; 14. reset/export/import demo snapshot; 15. smoke navigation по каждому зарегистрированному маршруту без console errors. Добавить визуальные snapshots ключевых экранов для трёх viewport и трёх тем. Не принимать snapshots с обрезанным контентом, перекрывающимися fixed-панелями или пустыми графиками. ## 11. Порядок реализации ### Этап A — стабилизация - устранить текущие lint warnings и ошибки мобильного preview; - добавить tests, error boundaries, route guards, code splitting; - унифицировать UI primitives и semantic tokens. ### Этап B — data/service foundation - service contracts, mock database, persistence, migrations; - связанный seed, demo clock, audit log, scenario switcher; - перенести существующие модули на общий data layer. ### Этап C — Configuration Engine - entities, fields, relations; - dynamic renderers; - form/card/view builders; - saved views и column management. ### Этап D — Pilot 1 end-to-end - CRM, catalog, orders, inventory, finance, import; - связать lifecycle и timeline. ### Этап E — target prototype modules - operations, people, communications, helpdesk, CMS, marketing, automation, analytics, AI; - реализовать честные mock interactions и maturity badges. ### Этап F — hardening - accessibility, responsive, performance, test matrix; - README, route inventory, feature coverage report; - финальный visual/functional audit. Не выполнять задачу одним огромным непроверяемым изменением. Каждый этап должен завершаться зелёной сборкой и отдельным отчётом о покрытии. ## 12. Definition of Done Задача завершена только когда одновременно выполнено следующее: - все маршруты открываются и имеют содержательный экран; - все видимые primary/secondary actions работают или явно disabled с объяснением; - Configuration Engine создаёт и изменяет поля, формы, карточки, views, relations и custom entities; - drag-and-drop работает мышью/тачем и имеет keyboard alternative; - изменения metadata немедленно отражаются на рабочих экранах; - demo-состояние сохраняется после reload и может быть экспортировано/сброшено; - сквозные BF-01 и BF-02 проходятся целиком без backend; - RBAC влияет на навигацию, маршруты, actions и fields; - mobile/tablet/desktop проверены реальным viewport; - lint, typecheck, unit/component/e2e tests проходят без warnings; - в браузерной консоли нет ошибок; - начальный bundle разделён по маршрутам и соответствует установленному budget; - README и `FEATURE-COVERAGE.md` описывают сделанное, demo-only ограничения и будущую замену mocks на API; - приложен финальный отчёт со списком сценариев, командами проверки и screenshot matrix. ## 13. Не входит в задачу - production backend и база данных; - реальные платежи, фискализация, сообщения и внешние интеграции; - хранение настоящих API keys; - реальный AI inference; - серверная tenant isolation; - миграция этого frontend в `business-platform/apps/admin`. При этом frontend обязан иметь адаптеры и типы, позволяющие позднее заменить mock services на REST без переписывания страниц. ## 14. Формат отчёта AGY В финальном отчёте указать: 1. что реализовано по каждому этапу A–F; 2. какие исходные файлы были существенно переработаны; 3. таблицу маршрутов и их readiness; 4. таблицу сущностей и поддерживаемых metadata-функций; 5. команды и фактические результаты build/lint/typecheck/test/e2e; 6. размеры initial и route chunks; 7. screenshot matrix desktop/tablet/mobile × themes; 8. известные ограничения и что остаётся для backend-интеграции; 9. подтверждение, что все видимые действия проверены; 10. отдельный список расхождений с нормативным `business-platform`, если их нельзя было устранить.