moex-vibe/docs/features/broker-account-overview-html-parity/plan.md

Финальный HTML Parity брокерского overview — план реализации

Для агентных исполнителей: ОБЯЗАТЕЛЬНЫЙ SUB-SKILL: использовать superpowers:subagent-driven-development (предпочтительно) или superpowers:executing-plans для пошагового выполнения. Шаги ведутся чекбоксами - [ ].

Цель: привести /broker/:accountId к финальному HTML-эталону docs/research/frontend-overview-redesign/example.html без изменения URL-структуры счёта.

Архитектура: backend расширяет существующий broker read API минимальными агрегатами и историей стоимости. Frontend остаётся в FSD-границах entities/broker-*, widgets/broker-dashboard, widgets/broker-account-layout; dashboard-композиция меняется с промежуточной версии на финальную HTML parity структуру.

Технологии: NestJS, Prisma/T-Bank broker operations read path, Swagger/OpenAPI codegen, React 18, TanStack Query, TanStack Router, MUI + @moex-vibe/design-system, Vitest, Testing Library.

---

Canonical Research Source

• Использовать как visual source of truth: docs/research/frontend-overview-redesign/example.html.
• Не использовать как source of truth: docs/research/2026-06-27-broker-account-redesign.html, пока файл не синхронизирован с финальным макетом.
• Production UI не переносит demo-control Данные / Загрузка; этот control нужен только HTML-макету.

Файлы

Backend

• Modify: apps/backend/src/modules/tbank/dto/broker-analytics-response.dto.ts — добавить totalFees, totalTaxesPaid.
• Create: apps/backend/src/modules/tbank/dto/broker-portfolio-history-response.dto.ts — DTO для 6-месячной истории стоимости.
• Modify: apps/backend/src/modules/tbank/dto/broker-envelope.dto.ts — envelope для history endpoint.
• Modify: apps/backend/src/modules/tbank/dto/broker-operation-query.dto.ts — query categories.
• Modify: apps/backend/src/modules/tbank/services/broker-analytics.service.ts — агрегировать fee/tax.
• Create: apps/backend/src/modules/tbank/services/broker-portfolio-history.service.ts — read-model истории стоимости.
• Modify: apps/backend/src/modules/tbank/services/broker-operations.service.ts — применять category-фильтр до ответа.
• Modify: apps/backend/src/modules/tbank/tbank.controller.ts — endpoint portfolio history.
• Modify: backend tests рядом с изменёнными сервисами/controller.

Frontend data

• Modify: apps/frontend/src/shared/api/index.ts — экспорт нового BrokerPortfolioHistory.
• Create: apps/frontend/src/entities/broker-account/api/brokerPortfolioHistoryApi.ts.
• Create: apps/frontend/src/entities/broker-account/model/useBrokerPortfolioHistory.ts.
• Modify: apps/frontend/src/entities/broker-account/index.ts — экспорт hook/API.
• Modify: apps/frontend/src/entities/broker-operation/api/brokerOperationApi.ts — query categories.

Frontend UI

• Modify: apps/frontend/src/widgets/broker-account-layout/ui/BrokerAccountLayout.tsx — title yield рядом с заголовком счёта, без page-header skeleton.
• Modify: apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboard.tsx — финальный порядок блоков и источники данных.
• Replace/Remove: BrokerDashboardHero.tsx из overview-композиции; файл можно оставить только если больше используется в тестах/экспортах, но в /broker/:accountId он не рендерится.
• Create: apps/frontend/src/widgets/broker-dashboard/ui/BrokerPortfolioHistoryCard.tsx.
• Modify: BrokerDashboardAnalyticsCard.tsx, BrokerDashboardAllocationCard.tsx, BrokerDashboardEventsCard.tsx, BrokerDashboardSkeleton.tsx.
• Modify/Create helpers в apps/frontend/src/widgets/broker-dashboard/lib/ для chart points, latest event rows, analytics display и visual tones.
• Modify: apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboard.test.tsx и helper unit tests.

Docs

• Modify: docs/features/broker-account-overview-html-parity/tasks.md по факту выполнения.
• Не переписывать docs/features/broker-dashboard-redesign/*; старая фича остаётся историей промежуточной итерации.

Data Contracts

Analytics

BrokerAnalyticsDto расширяется:

totalFees: number
totalTaxesPaid: number

Расчёт:

• totalFees = сумма absolute payment values executed операций категории fee;
• totalTaxesPaid = сумма absolute payment values executed операций категории tax;
• значения возвращаются как положительные агрегаты;
• frontend отображает их со знаком минус и negative tone.

Portfolio History

Endpoint:

GET /api/v1/broker/accounts/:accountId/portfolio/history?months=6

Response data:

type BrokerPortfolioHistoryData = {
  accountId: string
  points: Array<{
    month: string
    label: string
    value: BrokerMoneyDto
  }>
  asOf: string
}

Правила v1:

• months по умолчанию 6, допустимый диапазон 2-12;
• points.length === months;
• month в формате YYYY-MM;
• label — короткое русское имя месяца;
• последняя точка равна текущей portfolio.totals.portfolio;
• предыдущие точки могут быть estimated read-model из текущей стоимости и executed операций за период;
• контракт должен позволять позже заменить estimated calculation на persisted snapshots.

Operation Categories

BrokerOperationQueryDto получает:

categories?: string

Правила:

• comma-separated значения из trade,income,tax,fee,transfer,other;
• неизвестные категории игнорировать или валидировать с 400; выбрать один вариант и покрыть тестом;
• filtering выполняется до формирования page response;
• overview Последние события запрашивает categories=income,tax,fee, state=OPERATION_STATE_EXECUTED, limit=7.

Implementation Tasks

Task 1: Docs and research alignment

Files:

• docs/features/broker-account-overview-html-parity/spec.md

• docs/features/broker-account-overview-html-parity/plan.md

• docs/features/broker-account-overview-html-parity/tasks.md

• Проверить, что docs ссылаются на docs/research/frontend-overview-redesign/example.html.

• Проверить, что docs явно запрещают использовать старый dated HTML как canonical reference.

• Зафиксировать финальный порядок блоков и отсутствие production demo-toggle.

Task 2: Backend analytics contract

Files:

• apps/backend/src/modules/tbank/dto/broker-analytics-response.dto.ts

• apps/backend/src/modules/tbank/services/broker-analytics.service.ts

• apps/backend/src/modules/tbank/services/broker-analytics.service.spec.ts

• apps/backend/src/modules/tbank/tbank.controller.spec.ts

• Добавить totalFees, totalTaxesPaid в DTO и тестовый response.

• Расширить analytics service наборами fee/tax типов через существующую категоризацию операций.

• Считать fee/tax только по executed операциям с payment.

• Возвращать округление до копеек аналогично текущим analytics агрегатам.

Task 3: Backend portfolio history endpoint

Files:

• apps/backend/src/modules/tbank/dto/broker-portfolio-history-response.dto.ts

• apps/backend/src/modules/tbank/dto/broker-envelope.dto.ts

• apps/backend/src/modules/tbank/services/broker-portfolio-history.service.ts

• apps/backend/src/modules/tbank/tbank.controller.ts

• apps/backend/src/modules/tbank/tbank.controller.spec.ts

• Добавить DTO для history point и envelope.

• Добавить service, который проверяет account access через BrokerAccountsService.

• Получить текущую стоимость через existing portfolio service или общий read path без дублирования T-Bank вызовов сверх необходимого.

• Вернуть 6 monthly points для default query.

• Покрыть default months, invalid account и shape response тестами.

Task 4: Backend operation category filtering

Files:

• apps/backend/src/modules/tbank/dto/broker-operation-query.dto.ts

• apps/backend/src/modules/tbank/services/broker-operations.service.ts

• apps/backend/src/modules/tbank/services/broker-operations.service.spec.ts

• Добавить categories query.

• Применить category filtering к mapped operations page перед отдачей response.

• Если T-Bank page может содержать меньше 7 подходящих операций после фильтрации, documented v1 поведение: endpoint возвращает подходящие операции из текущей fetched page; full backfill pagination не требуется.

• Покрыть categories=income,tax,fee и неизвестную категорию тестом.

Task 5: OpenAPI and frontend generated types

Files:

• apps/frontend/src/shared/api/types.ts

• apps/frontend/src/shared/api/index.ts

• Запустить backend dev server.

• Выполнить npm run codegen -w apps/frontend.

• Не редактировать generated types.ts вручную.

• Экспортировать новые frontend aliases из shared/api/index.ts.

• Проверить, что generated schemas содержат totalFees, totalTaxesPaid, BrokerPortfolioHistoryDataDto.

Task 6: Frontend data hooks

Files:

• apps/frontend/src/entities/broker-account/api/brokerPortfolioHistoryApi.ts

• apps/frontend/src/entities/broker-account/model/useBrokerPortfolioHistory.ts

• apps/frontend/src/entities/broker-account/index.ts

• apps/frontend/src/entities/broker-operation/api/brokerOperationApi.ts

• Добавить getBrokerPortfolioHistory(accountId, { months }).

• Добавить useBrokerPortfolioHistory(accountId, { months: 6 }) с query key ['broker', 'portfolio-history', accountId, months].

• Добавить categories в BrokerOperationQuery.

• Не менять существующие hooks detailed вкладок.

Task 7: Page title yield

Files:

• apps/frontend/src/widgets/broker-account-layout/ui/BrokerAccountLayout.tsx

• apps/frontend/src/pages/broker-account/ui/BrokerAccountOverviewPage.tsx

• apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboard.tsx

• Перенести compact yield UI рядом с Брокерский счёт.

• Убрать отдельный hero KPI из overview.

• Не показывать page-title skeleton в loading state.

• Сохранить доступность: доходность имеет aria-label="Доходность счёта" или эквивалент.

Task 8: Portfolio history card

Files:

• apps/frontend/src/widgets/broker-dashboard/ui/BrokerPortfolioHistoryCard.tsx

• apps/frontend/src/widgets/broker-dashboard/lib/dashboardPortfolioHistory.ts

• apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboard.tsx

• apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboardSkeleton.tsx

• Создать карточку Стоимость портфеля за 6 месяцев.

• Нарисовать SVG line/area chart без visible point markers.

• Использовать 6 backend points и подписи месяцев из response.

• Сделать loading chart indicator без skeleton месяцев.

• Обеспечить одинаковую min-height loaded/loading.

• Первая и последняя точки графика должны совпадать с краями области.

Task 9: Analytics card parity

Files:

• apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboardAnalyticsCard.tsx

• apps/frontend/src/widgets/broker-dashboard/lib/dashboardVisual.ts

• apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboard.test.tsx

• Summary row: Стоимость портфеля, Всего доходов.

• Detail grid: Пополнения, Выводы, Дивиденды, Купоны, Комиссия, Уплаченные налоги.

• Удалить Нетто и Всего получено из overview-card.

• Отображать totalFees и totalTaxesPaid как negative UI amounts.

• Сохранить skeleton геометрию 2 + 6 карточек.

Task 10: Allocation card parity

Files:

• apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboardAllocationCard.tsx

• apps/frontend/src/entities/broker-position/model/brokerAllocation.ts

• Переименовать карточку в Структура.

• Убрать subtitle Структура портфеля.

• Показать итоговую стоимость под заголовком.

• Отобразить только строки Акции, Облигации, Деньги для overview parity.

• Сохранить корректное поведение для отсутствующих/нулевых значений.

Task 11: Latest events card parity

Files:

• apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboardEventsCard.tsx

• apps/frontend/src/widgets/broker-dashboard/lib/dashboardEvents.ts

• apps/frontend/src/widgets/broker-dashboard/lib/dashboardVisual.ts

• apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboard.tsx

• Переключить overview source с useBrokerEvents на useBrokerOperations с categories=income,tax,fee, limit=7.

• Убрать filters toolbar, count badge, footer summary и колонку Статус.

• Переименовать карточку в Последние события.

• Отсортировать rows новые → старые.

• Инструмент: название сверху жирным, ticker/ISIN снизу серым.

• Тип: бейдж Дивиденд, Купон, Погашение, Налог, Комиссия.

• Налоговые/комиссионные/отрицательные операции отображать красным.

Task 12: Tests, build, visual QA

Files:

• apps/frontend/src/widgets/broker-dashboard/ui/BrokerDashboard.test.tsx

• backend specs из предыдущих задач

• docs/features/broker-account-overview-html-parity/tasks.md

• Backend targeted tests: npm run test -w apps/backend -- src/modules/tbank/services/broker-analytics.service.spec.ts src/modules/tbank/services/broker-operations.service.spec.ts src/modules/tbank/tbank.controller.spec.ts

• Frontend targeted tests: npm run test -w apps/frontend -- --run src/widgets/broker-dashboard

• Full checks: npm run test:frontend npm run lint -w apps/frontend npm run build:frontend

• Visual QA: desktop /broker/:accountId; mobile viewport 390x844; compare against docs/research/frontend-overview-redesign/example.html.

• Update tasks.md statuses and notes after verification.

Risks and Decisions

• History chart v1 uses estimated read-model; exact historical market value requires future snapshots.
• Category filtering after one fetched T-Bank page may underfill latest events; acceptable for v1 unless testing shows too many empty overview rows.
• The HTML mock uses static values. React must match structure and visual behavior, not literal amounts.
• Последние события is intentionally based on executed operations, not calendar events, because the final HTML shows already happened cashflow rows and removes status/forecast semantics.

Verification Matrix

• Spec requirements map to tasks 2-11.
• Backend API requirements map to tasks 2-5.
• Frontend order and visual parity map to tasks 7-11.
• Loading stability and mobile overflow are verified in task 12.