diff --git a/docs/features/table-migration/plan.md b/docs/features/table-migration/plan.md new file mode 100644 index 0000000..df45cd1 --- /dev/null +++ b/docs/features/table-migration/plan.md @@ -0,0 +1,89 @@ +# Миграция таблиц на дизайн-систему — Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development +> (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use +> checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Перевести legacy-таблицы frontend на единый дизайн-системный слой без изменения бизнес-логики +и без отказа от `TanStack Table`. + +**Architecture:** `packages/design-system/src/components/DataTable` становится общим UI-каркасом для +таблиц, а приложение продолжает владеть `TanStack Table` instance, колонками и доменными cell renderers. +Вся предметная логика остаётся в `apps/frontend`, а дизайн-система забирает только переиспользуемую +табличную оболочку и связанные presentation-состояния. + +**Tech Stack:** React 18, TanStack Table, `@moex-vibe/design-system`, Vitest, Testing Library. + +**Связанные документы:** + +- Spec: `docs/features/table-migration/spec.md` +- DS foundation: `docs/features/design-system-foundation/spec.md` +- DS migration precedent: `docs/features/broker-account-sections-ds-migration/spec.md` + +--- + +## Task 1: Уточнить API `DataTable` + +Подготовить минимальное расширение API `DataTable`, которое покрывает реальные кейсы существующих таблиц. + +- Проверить текущий `DataTable` в `packages/design-system/src/components/DataTable/DataTable.tsx`. +- Зафиксировать минимально необходимую поддержку: + - `table` / table model from `TanStack Table`; + - empty state; + - loading state / skeleton mode; + - row actions column or slot; + - controlled pagination / pagination slot; + - cell alignment. +- Не добавлять API, которое не подтверждено текущими 4 таблицами. +- Не добавлять MUI table-компоненты в код приложения. + +## Task 2: Мигрировать `DividendsTable` + +Сделать `DividendsTable` первым и самым простым потребителем общего DS-слоя. + +- Перевести сырой HTML table на `DataTable`. +- Сохранить текущие колонки и форматирование. +- Убедиться, что пустое состояние и базовый layout совпадают по смыслу с текущим экраном. + +## Task 3: Мигрировать `ScreenerTable` + +Перевести табличную оболочку `ScreenerTable` на `DataTable`, сохранив текущее поведение. + +- Оставить sorting и pagination под контролем существующей логики. +- Сохранить кастомные ячейки и действия над строками. +- Не менять query/data-flow скринера. + +## Task 4: Мигрировать `SharePositionTable` + +Заменить локальную табличную разметку на `DataTable`, не вынося доменную логику в DS. + +- Сохранить row/cell renderers в приложении. +- Сохранить update/delete actions. +- Не менять вычисления и форматтеры, если это не требуется для миграции UI. + +## Task 5: Мигрировать `BondPositionTable` + +Перевести наиболее сложную таблицу позиций облигаций на DS-каркас. + +- Сохранить предметно-специфичные bond columns и rendering. +- Сохранить все row actions. +- Не менять финансовую логику, сортировку и представление данных сверх UI-слоя. + +## Task 6: Очистка legacy-слоя и документация + +После миграции проверить связанные legacy-компоненты и документацию. + +- Проверить судьбу `apps/frontend/src/shared/ui/Table/*` и `TableSkeleton`. +- Удалить или сократить helper-код, если он остаётся без потребителей. +- Обновить `apps/docs/docs/design-system/components.md` и `apps/docs/docs/frontend/styling.md`: + - явно зафиксировать, что `DataTable` построен на `TanStack Table`; + - отразить ожидаемый способ миграции legacy-таблиц. + +## Task 7: Верификация + +Подтвердить, что миграция не сломала текущие контракты frontend. + +- Запустить frontend-тесты для затронутых областей. +- Запустить lint для frontend и design-system. +- Запустить build frontend и design-system. +- Проверить, что во frontend не появились новые запрещённые MUI table imports. diff --git a/docs/features/table-migration/spec.md b/docs/features/table-migration/spec.md new file mode 100644 index 0000000..f713449 --- /dev/null +++ b/docs/features/table-migration/spec.md @@ -0,0 +1,70 @@ +# Миграция таблиц на дизайн-систему + +Дата: 2026-06-21 +Статус: запланировано + +## Контекст + +Во frontend уже есть дизайн-система `@moex-vibe/design-system` и компонент `DataTable`, но часть экранов +по-прежнему использует legacy-таблицы на сыром HTML и локальных helper-компонентах. Основные зоны +миграции: `DividendsTable`, `ScreenerTable`, `SharePositionTable`, `BondPositionTable`, а также связанные +legacy-элементы вроде `shared/ui/Table` и `TableSkeleton`. + +При этом сложные таблицы проекта должны и дальше опираться на `TanStack Table` как на источник +модели данных, сортировки и состояния. Цель фичи — не заменить `TanStack Table`, а стандартизировать +табличный UI через единый дизайн-системный слой. + +## Связанные фичи + +- Базовая фича дизайн-системы: `docs/features/design-system-foundation/spec.md` +- Связанная DS-миграция: `docs/features/broker-account-sections-ds-migration/spec.md` +- Frontend styling docs: `apps/docs/docs/frontend/styling.md` +- DS docs: `apps/docs/docs/design-system/components.md` + +## Цель + +Перевести legacy-таблицы frontend на единый дизайн-системный табличный слой, построенный поверх +`TanStack Table`, без изменения бизнес-логики, API-контрактов и доменной модели данных. + +## In scope + +- Уточнить и при необходимости расширить API `DataTable` в `@moex-vibe/design-system` под реальные + сценарии проекта. +- Мигрировать существующие таблицы frontend на `DataTable`. +- Сохранить текущие сценарии сортировки, пагинации, кастомных ячеек и row actions. +- Унифицировать loading / empty / error presentation вокруг дизайн-системных компонентов. +- Сократить использование legacy table helpers в `apps/frontend/src/shared/ui`. + +## Out of scope + +- Изменение бизнес-логики портфелей, скринера, дивидендов, акций и облигаций. +- Перенос предметно-специфичных row/cell-компонентов в дизайн-систему. +- Изменение backend API, query-keys, маршрутизации или структуры доменных данных. +- Замена `TanStack Table` на другой табличный движок. +- Полная миграция всех форм и page sections вне областей, напрямую затронутых таблицами. + +## Требования + +- `DataTable` должен оставаться обёрткой над `TanStack Table`, а не отдельной несовместимой таблицей. +- Табличный слой должен поддерживать: + - sortable columns; + - выравнивание ячеек; + - custom cell renderers; + - empty state; + - loading state / skeleton state; + - row actions; + - controlled pagination или pagination slot. +- Доменные таблицы должны сохранять собственные описания колонок и кастомный рендеринг ячеек. +- В приложении нельзя добавлять новые legacy table helpers взамен миграции на DS. +- Во frontend не должны появляться новые прямые MUI table-компоненты. + +## Acceptance Criteria + +- `DividendsTable`, `ScreenerTable`, `SharePositionTable` и `BondPositionTable` используют + дизайн-системный табличный слой. +- Сортировка, пагинация и действия над строками работают так же, как до миграции. +- `DataTable` документирован как компонент на базе `TanStack Table`. +- Legacy table helpers не расширяются; после миграции их количество сокращается или они удаляются, + если остаются без потребителей. +- Изменение не требует корректировки backend-контрактов. +- Для затронутых пакетов проходят тесты, lint и build. diff --git a/docs/features/table-migration/tasks.md b/docs/features/table-migration/tasks.md new file mode 100644 index 0000000..8678de0 --- /dev/null +++ b/docs/features/table-migration/tasks.md @@ -0,0 +1,55 @@ +# Миграция таблиц на дизайн-систему — Tasks + +Дата: 2026-06-21 +Статус: запланировано + +Связанные документы: + +- [Spec](spec.md) +- [Plan](plan.md) + +## Task 1: Уточнить API `DataTable` + +- [ ] Проверить текущее API `DataTable` +- [ ] Зафиксировать минимальный список поддерживаемых сценариев из существующих таблиц +- [ ] Подготовить изменения API только под подтверждённые кейсы +- [ ] Убедиться, что `TanStack Table` остаётся source of truth + +## Task 2: Мигрировать `DividendsTable` + +- [ ] Перевести HTML table на `DataTable` +- [ ] Сохранить текущие колонки и форматирование +- [ ] Проверить empty/loading presentation + +## Task 3: Мигрировать `ScreenerTable` + +- [ ] Перевести табличную оболочку на `DataTable` +- [ ] Сохранить сортировку и пагинацию +- [ ] Сохранить row actions и кастомные ячейки + +## Task 4: Мигрировать `SharePositionTable` + +- [ ] Перевести таблицу на `DataTable` +- [ ] Сохранить доменные row/cell renderers в приложении +- [ ] Сохранить update/delete сценарии + +## Task 5: Мигрировать `BondPositionTable` + +- [ ] Перевести таблицу на `DataTable` +- [ ] Сохранить bond-specific rendering и действия +- [ ] Не менять предметную финансовую логику + +## Task 6: Очистка legacy и документация + +- [ ] Проверить использование `shared/ui/Table` +- [ ] Проверить использование `TableSkeleton` +- [ ] Обновить docs по `DataTable` и `TanStack Table` +- [ ] Удалить legacy helper'ы, если они больше не нужны + +## Task 7: Верификация + +- [ ] Запустить frontend tests +- [ ] Запустить frontend lint +- [ ] Запустить design-system lint/tests при необходимости +- [ ] Запустить frontend и design-system build +- [ ] Проверить отсутствие новых запрещённых MUI table imports diff --git a/docs/inbox.md b/docs/inbox.md index eed5561..bebddb9 100644 --- a/docs/inbox.md +++ b/docs/inbox.md @@ -186,6 +186,11 @@ cash flow, бюджеты, аналитика, прогнозы и автома - Определить, нужна ли дизайн-система только внутри monorepo или как отдельный npm-пакет. - Предусмотреть accessibility, визуальные regression-тесты и каталог компонентов (например, Storybook) как темы исследования. +- Подготовить отдельную migration-фичу для перевода legacy-таблиц на дизайн-системный `DataTable`, + построенный поверх `TanStack Table`, без переноса доменной логики таблиц в DS. +- Для миграции таблиц использовать поэтапный порядок: `DividendsTable` → `ScreenerTable` → + `SharePositionTable` → `BondPositionTable`, сначала уточнив минимальный API `DataTable` на основе + реальных кейсов. ### Исследовать Backend-Driven UI diff --git a/docs/roadmap.md b/docs/roadmap.md index 1296abf..591892a 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -18,3 +18,8 @@ Roadmap отражает порядок продуктовой работы, н 1. [x] Проверить и утвердить `spec.md` для планирования. 2. [x] Проверить и утвердить подготовленные `plan.md` и `tasks.md`. 3. [x] Получить отдельное подтверждение пользователя перед началом реализации. + +## Кандидаты следующих фич + +- [ ] [Миграция таблиц на дизайн-систему](features/table-migration/spec.md) — перевести legacy-таблицы + frontend на `DataTable` поверх `TanStack Table` без изменения бизнес-логики.