ochenstarik/krona-front
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
krona-front/FRONTEND-COMPLETION-TASK-FOR-AGY.md

28 KiB
Raw Permalink Blame History

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