krona-front/FRONTEND-COMPLETION-TASK-FOR-AGY.md

# 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`, если их нельзя было устранить.