From 55f3171636d0ae0da0ee1149eff3e145ddc3a64d Mon Sep 17 00:00:00 2001 From: lizerk Date: Mon, 13 Apr 2026 14:05:47 +0300 Subject: [PATCH] docs(frontend): document genre drift and refactor waves --- docs/guides/frontend/01-OVERVIEW.md | 19 ++ docs/guides/frontend/05-MIGRATION.md | 32 ++++ docs/guides/frontend/07-DEVELOPER-WORKFLOW.md | 15 +- docs/guides/frontend/09-FRONTEND-AUDIT-MAP.md | 173 ++++++++++++++++-- docs/guides/frontend/README.md | 17 ++ 5 files changed, 237 insertions(+), 19 deletions(-) diff --git a/docs/guides/frontend/01-OVERVIEW.md b/docs/guides/frontend/01-OVERVIEW.md index ab291c20..d56dadae 100644 --- a/docs/guides/frontend/01-OVERVIEW.md +++ b/docs/guides/frontend/01-OVERVIEW.md @@ -112,8 +112,27 @@ Guide не покрывает: - дрейф карточек по визуальному весу - разный dropdown affordance у похожих полей - локальные ad-hoc решения в feature-страницах +- расхождение по типу экранов: часть страниц живёт как рабочие модули системы, часть как showcase/profile/dashboard из другого продукта Следствие: - карточки и геометрию можно и нужно нормализовать системно - формы нужно оценивать уже после этого, индивидуально по UX-паттернам + +## Экранные жанры + +Перед рефакторингом нужно определить не только набор компонентов, но и жанр экрана. + +Базовые типы в этом проекте: + +- operational workspace: плотные рабочие страницы со status/actions/list/detail flow +- profile-like page: hero + секции + персональные или справочные блоки +- dashboard/feed: обзорные экраны с несколькими контентными зонами +- auth/legal flow: изолированные страницы вне основного app-shell сценария + +Правило: + +- рефакторинг должен приводить все жанры к одной продуктовой системе +- но не должен насильно превращать один жанр в другой +- удачный operational screen нельзя без причины перепридумывать как showcase-layout +- удачный profile-screen нельзя механически уплотнять до вида request list только ради единообразия diff --git a/docs/guides/frontend/05-MIGRATION.md b/docs/guides/frontend/05-MIGRATION.md index d55f2822..10ade507 100644 --- a/docs/guides/frontend/05-MIGRATION.md +++ b/docs/guides/frontend/05-MIGRATION.md @@ -28,6 +28,20 @@ Legacy не означает “удалить немедленно”. Это - drawer-like и workspace-like интерфейсов - экранов, где геометрия тесно завязана на сценарий использования +## Что нельзя делать механически + +Без отдельного обоснования нельзя: + +- брать удачный экран и переделывать его под другой визуальный жанр только ради декомпозиции +- считать, что выравнивание `rounded-*` автоматически решает проблему согласованности системы +- копировать успешный local layout в другие зоны без проверки, совпадает ли у экранов тип сценария + +Особенно важно: + +- `requests` сейчас ближе к общему operational style проекта +- `users/profile` визуально неплох, но местами ощущается как screen из другого продукта +- это означает, что refactor должен сначала фиксировать продуктовый character экрана, а уже потом править geometry/detail-level debt + ## Приоритет рефакторинга Рекомендуемый порядок: @@ -54,6 +68,11 @@ Legacy не означает “удалить немедленно”. Это Хороший кандидат для следующей волны нормализации крупных panel-контейнеров и detail cards. +С оговоркой: + +- зона крупная и функционально богатая, но в ней заметно смешение app-style и gray/white legacy fragments +- refactor должен идти не только по page-level layout, но и по дочерним panels/forms + ### `equipment` Подходит для рефакторинга secondary cards и form blocks, потому что там много повторяющейся геометрии. @@ -62,6 +81,19 @@ Legacy не означает “удалить немедленно”. Это Сильный ориентир по primary/secondary surface hierarchy, но там ещё встречаются кастомные радиусы, которые нужно сокращать. +### `users/profile` + +Использовать как ориентир по profile anatomy: + +- hero +- section stack +- contacts/info/timeline decomposition + +С оговоркой: + +- профиль нельзя считать полным stylistic reference для всего приложения +- эту зону нужно подтянуть ближе к общему product feel без потери profile-specific anatomy + ### `documents` Ключевая зона для аудита legacy-геометрии: заметно смешение `rounded-md`, `rounded-lg`, `rounded-xl` и локальных utility-решений. diff --git a/docs/guides/frontend/07-DEVELOPER-WORKFLOW.md b/docs/guides/frontend/07-DEVELOPER-WORKFLOW.md index 07439aa6..8882ef32 100644 --- a/docs/guides/frontend/07-DEVELOPER-WORKFLOW.md +++ b/docs/guides/frontend/07-DEVELOPER-WORKFLOW.md @@ -6,12 +6,13 @@ Рекомендуемый порядок: -1. понять, это новый паттерн или существующий -2. найти ближайшие shared primitives -3. определить уровень поверхности и геометрии -4. собрать layout из существующих слоёв -5. вынести тяжёлые feature-блоки из page-level файла, если экран уже растёт за счёт list row / detail modal / compose workspace -6. только потом добавлять локальные override +1. определить жанр экрана: operational workspace, profile-like page, dashboard/feed или auth/legal flow +2. понять, это новый паттерн или существующий +3. найти ближайшие shared primitives +4. определить уровень поверхности и геометрии +5. собрать layout из существующих слоёв +6. вынести тяжёлые feature-блоки из page-level файла, если экран уже растёт за счёт list row / detail modal / compose workspace +7. только потом добавлять локальные override Неправильный порядок: @@ -23,6 +24,7 @@ Перед началом нового экрана: - определить, это обычная app-page или отдельный auth/legal flow +- определить, это рабочий модуль, profile-like page или обзорный dashboard/feed - понять, нужен ли `AppShell` - определить основной primary panel - определить, сколько secondary blocks реально нужно @@ -80,6 +82,7 @@ - если внутри одной зоны уже несколько leaf-компонентов, стоит ввести feature container вроде `*Section` или `*Panel`, а не возвращать всё обратно в page-level JSX - если экран уже визуально удачный, первый шаг рефакторинга должен сохранять внешний контракт и чистить структуру под капотом, а не навязывать новый layout только ради декомпозиции - если у toolbar/filter block пропсы начинают расползаться, можно группировать их локально, но это не должно само по себе заставлять перепридумывать успешный внешний вид блока +- если экран ощущается как “из другого проекта”, причина чаще всего не в одном radius или цвете, а в несовпадении screen genre; это нужно решать на уровне hierarchy, density и panel semantics, а не точечными utility-правками ## 5. Как делать dropdown-поле diff --git a/docs/guides/frontend/09-FRONTEND-AUDIT-MAP.md b/docs/guides/frontend/09-FRONTEND-AUDIT-MAP.md index b1b3ccb3..fb514239 100644 --- a/docs/guides/frontend/09-FRONTEND-AUDIT-MAP.md +++ b/docs/guides/frontend/09-FRONTEND-AUDIT-MAP.md @@ -9,31 +9,178 @@ - `needs refactor` — зона должна попасть в один из следующих refactor pass - `legacy-heavy` — много технического долга и старых паттернов +## Что именно показывает audit + +Этот audit нужен не только для поиска `rounded-md` или `bg-white`. + +Он должен отвечать на три вопроса: + +- насколько экран совпадает с общей visual system проекта +- не уехал ли экран в другой визуальный жанр по сравнению с соседними app-страницами +- где рефакторинг даст наибольший эффект без риска сломать уже удачный UI + ## Карта зон | Зона | Статус | Что уже хорошо | Основные проблемы | Рекомендуемый следующий шаг | | --- | --- | --- | --- | --- | | `requests` | `mixed` | визуально удачный экран, compose-настроение, participant-only логика, UI вокруг `can_decide`, compose/list/detail/controls/preview разведены по feature components, screen orchestration вынесена в hook, list/swipe flow собраны в feature containers, avatar/preview media contract выровнен через local wrapper | зона полезна как проверка guide, но не должна автоматически становиться полным visual-reference; здесь важнее бережный structural refactor без насильственного редизайна | использовать как ориентир по декомпозиции насыщенного экрана и осторожной нормализации уже хорошего UI, а не как шаблон для жёсткой пересборки dense list-паттернов | -| `settings` | `mixed` | сильная surface hierarchy, хорошие primary sections | встречаются custom radii и локальная геометрическая неоднородность | рефакторить карточки и кастомные радиусы без смены общего layout | -| `documents` | `needs refactor` | богатый набор сценариев, detail/upload/comment patterns уже выделены в компоненты | смешение `rounded-md`, `rounded-lg`, `rounded-xl`, разные уровни visual density | сделать отдельный pass по карточкам и metadata/upload flows | -| `equipment` | `needs refactor` | понятные формы и вторичные блоки | много локальных card/form решений, геометрия плавает | после `documents` пройтись по secondary cards и action forms | -| `procurement` | `mixed` | крупные панели и часть detail blocks уже читаются неплохо | остаются старые form fragments и неоднородные локальные поля | нормализовать page panels и supplier/request forms | +| `settings` | `mixed` | сильная surface hierarchy, хорошие primary sections, в целом совпадает с app-shell language | встречаются custom radii, page-level файл очень большой, часть hero/media решений выбивается по геометрии | резать controller/view-model слои и точечно сокращать custom geometry без смены общего layout | +| `documents` | `needs refactor` | богатый набор сценариев, detail/upload/comment patterns уже выделены в компоненты | смешение `rounded-md`, `rounded-lg`, `rounded-xl`, заметный gray-legacy в editor/viewer/tags, слишком много modal-heavy page-logic | сделать отдельный pass по карточкам, metadata/upload flows и documents subcomponents, не ограничиваться только page-level | +| `equipment` | `needs refactor` | понятные формы, hooks уже вынесены, основные списки и модалки покрывают богатый сценарий | большой page-file, смешение app-style и gray/white fragments, detail/comments/forms ещё не сведены к одному contract | после documents пройтись по secondary cards, detail blocks и action forms | +| `procurement` | `needs refactor` | крупные панели и часть detail blocks уже читаются неплохо, есть shared-like detail content | большой page-file, gray/white legacy в stats/suppliers/forms, смешение operational page и старых local panels | нормализовать page panels, suppliers/stats/forms и только потом решать дальнейшую декомпозицию | | `calendar` | `legacy-heavy` | богатая функциональность, много reusable доменных компонентов | historical layering, legacy-термины и неоднородные модалки | отдельный audit до системного refactor | -| `messages` | `mixed` | зрелая interaction model, сильный composer и message item | очень доменно-специфичный UX, не всё переносимо как общий стандарт | использовать выборочно как reference, без механического копирования в другие зоны | -| `users/profile` | `mixed` | хорошие profile sections и hero-like patterns | часть экранов ещё может дрейфовать по локальным решениям | держать как reference для profile contract и точечно упрощать | +| `messages` | `mixed` | зрелая interaction model, сильный composer и message item, app-style в основных экранах в целом выдержан | очень доменно-специфичный UX, крупные page-files, часть settings/create/chat-experiment flows ещё шумят по state/legacy dialogs | использовать выборочно как reference, без механического копирования в другие зоны; дальше резать state-heavy pages | +| `users/profile` | `needs refactor` | хорошие profile sections, hero-like anatomy, action timeline, переиспользуемые section-level components | профиль визуально ощущается как screen из другого проекта, `/profile` и `/users/[id]` архитектурно несимметричны, модалки и часть users-list screens живут в gray/white legacy language | держать как reference по profile anatomy, но сделать отдельный alignment-pass по people/profile cluster без превращения его в request-like layout | +| `users/directory` | `needs refactor` | простые сценарии, понятные employee/user navigation flows | `users/page.tsx` и часть directory screens всё ещё в white/gray card language, визуально выпадают из app surfaces | после profile cluster пройтись по user/employee lists и привести их к общему app-shell contract | +| `home/feed` | `mixed` | сильный app-shell fit, хорошая operational density, уже много app primitives | page очень большой, комментарии и post-compose logic перегружены, встречаются legacy `rounded-md` fragments | использовать как reference по feed density, но разрезать modal/comments/post flows и дочистить geometry | +| `notifications` | `mixed` | близок к operational app-style, фильтры и list hierarchy уже читаются системно | page-level logic пока монолитная, нет выделенного feature controller, есть место для уплотнения и симметрии с messages/requests | после people cluster сделать короткий structural pass без крупного редизайна | +| `departments` | `mixed` | page/detail screens небольшие и уже живут в app-shell language | не хватает единых richer patterns между list/detail, зона выглядит недоразвитой по сравнению с остальными модулями | low-cost pass после крупных зон: выровнять richness и reuse | +| `auth/legal` | `mixed` | изолированные flows уже отделены от app-shell, общая подача аккуратная | `rounded-[2rem]` и локальная hero-card геометрия образуют мини-систему отдельно от app shell | не смешивать с operational refactor; сделать отдельный compact pass по auth/legal geometry | | `documents/dashboard` | `legacy-heavy` | есть готовые data blocks | заметны старые rounded patterns и мелкие utility-решения | включить в documents refactor pass | ## Порядок следующего рефакторинга -Рациональный порядок: +Рациональный порядок после текущего audit: -1. `settings` -2. `documents` -3. `equipment` -4. `procurement` -5. отдельный audit по `calendar` +1. `users/profile` + `users/directory` +2. `home/feed` + `notifications` +3. `documents` + `documents/dashboard` +4. `equipment` +5. `procurement` +6. `messages` +7. `settings` +8. отдельный audit по `calendar` +9. `departments` +10. `auth/legal` -`requests` лучше использовать как проверочную зону для guide: сначала сохранять удачный внешний контракт и чистить структуру, а уже потом решать, какие визуальные паттерны действительно стоит поднимать в общие правила. +Логика порядка: + +- сначала устранять самые заметные genre-mismatch зоны, которые визуально выбиваются из остального продукта +- потом идти в крупные operational pages, где уже есть app-style foundation, но слишком много structural debt +- затем чистить heavy business-modules с большим объёмом legacy fragments +- calendar оставлять отдельным спец-аудитом, а не вписывать в механическую волну + +## Детальный план волн + +### Волна 1. Product alignment + +Зоны: + +- `users/profile` +- `users/directory` + +Цель: + +- подтянуть people/profile cluster к общему product feel без потери profile anatomy + +Что делать: + +- вынести controller для `/profile` по аналогии с `useUserDetailPage` +- убрать gray/white modal/forms debt из `EditUserProfileModal` и `EmployeeActionModal` +- нормализовать `ProfileSections` по геометрии без уничтожения hero/section contract +- привести `users/page.tsx` к app-surface language + +### Волна 2. Operational pages with high leverage + +Зоны: + +- `home/feed` +- `notifications` + +Цель: + +- укрепить самые частые рабочие экраны, уже близкие к target state + +Что делать: + +- разрезать большие page-level controllers +- дочистить legacy `rounded-md` в feed/comments actions +- выровнять controls/list/detail semantics между feed, notifications и requests + +### Волна 3. Documents system + +Зоны: + +- `documents` +- `documents/dashboard` + +Цель: + +- убрать самый заметный geometry/token drift внутри document flows + +Что делать: + +- tags, metadata, folder tree, viewer, related documents, upload/detail flows +- сократить `rounded-md` и gray-legacy +- проверить modal/viewer/editor contracts отдельно от page shell + +### Волна 4. Asset/workflow modules + +Зоны: + +- `equipment` +- `procurement` + +Цель: + +- привести тяжёлые operational modules к одному panel/detail/form contract + +Что делать: + +- пройтись по stats/suppliers/detail/comments/forms в `procurement` +- пройтись по equipment detail/history/comments/QR/forms +- только после этого решать, где нужна дополнительная декомпозиция page-level файлов + +### Волна 5. Messages + +Зоны: + +- `messages` +- `messages/[chatId]` +- `messages/[chatId]/settings` + +Цель: + +- сохранить сильный доменный UX, но снять лишний state/dialog debt + +Что делать: + +- не трогать core chat UX механически +- отдельно проходить list/settings/create-chat/dialog states +- использовать как reference выборочно, а не как global standard + +### Волна 6. Settings and supportive modules + +Зоны: + +- `settings` +- `departments` +- `auth/legal` + +Цель: + +- дочистить крупные secondary zones после выравнивания основных рабочих сценариев + +Что делать: + +- у `settings` сначала резать size/structure page, затем geometry +- у `departments` поднять богатство patterns до общего уровня app +- у `auth/legal` выровнять isolated geometry отдельно от app-shell жанра + +### Волна 7. Calendar special audit + +Зона: + +- `calendar` + +Цель: + +- перед любым большим refactor сначала зафиксировать фактическую архитектуру и legacy boundary + +Что делать: + +- отдельная карта модалок, cards, subscriptions/import/export/event flows +- только после этого принимать решение о системной переработке ## Как использовать эту карту diff --git a/docs/guides/frontend/README.md b/docs/guides/frontend/README.md index 8869560f..b2ef8222 100644 --- a/docs/guides/frontend/README.md +++ b/docs/guides/frontend/README.md @@ -60,9 +60,26 @@ Guide не предназначен для: - affordance dropdown-полей - повторяющиеся card patterns - разные form contracts для похожих сценариев +- визуальный жанр экранов: часть страниц выглядит как operational workspace, часть как showcase/dashboard из другого продукта Именно поэтому этот раздел фиксирует target state заранее, даже если кодовая база ещё не полностью к нему приведена. +## Почему этот refactor вообще нужен + +Цель refactor не в том, чтобы механически проставить одинаковые `rounded-*` по всему проекту. + +Главная причина: + +- соседние app-страницы иногда решены в разных визуальных жанрах +- из-за этого даже качественный локальный экран может выглядеть “как из другого проекта” +- если исправлять только токены, но не учитывать жанр экрана, можно легко сломать удачную страницу + +Практический вывод: + +- сначала нужно понять, что за экран перед нами: operational workspace, profile-like page, dashboard/feed, auth/legal flow +- потом сохранять удачный внешний контракт этого типа экрана +- и только после этого выравнивать геометрию, surfaces, controls и shared affordance + ## Источники истины Ключевые frontend primitives, на которые опирается весь guide: