docs(frontend): document genre drift and refactor waves
This commit is contained in:
lizerk
parent
c87901452a
commit
55f3171636
@ -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 только ради единообразия
|
||||
|
||||
@ -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-решений.
|
||||
|
||||
@ -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-поле
|
||||
|
||||
|
||||
@ -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
|
||||
- только после этого принимать решение о системной переработке
|
||||
|
||||
## Как использовать эту карту
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user