docs(specs): archive stock card polish

2026-08-26 11:41:17 +03:00
parent 779a1e1305
commit cf6bc17611
5 changed files with 177 additions and 0 deletions
@@ -0,0 +1,8 @@
+schema: wealth-ledger-sdd
+created: 2026-08-26
+skip_specs: true
+goal: Сделать карточки акций в портфеле визуально более читаемыми без изменения данных и взаимодействий.
+affected_areas:
+  - frontend
+  - specs
+  - docs
@@ -0,0 +1,3 @@
+# polish-stock-position-cards
+
+Визуально уточнить отображение акций в портфеле без изменения состава данных и взаимодействий.
@@ -0,0 +1,109 @@
+## Context
+
+Страница Portfolio уже подготавливает presentation-model позиций во ViewModel и
+рендерит чистые view-компоненты. Акции и облигации выводятся одним широким
+вариантом Position Card: в нём есть логотип, идентификатор, стоимость,
+доходность, средняя цена и доля. Текущие требования задают состав метрик,
+одноколоночность, логотип и цветовую семантику дохода, но не закрепляют
+внутреннюю визуальную иерархию карточки.
+
+Изменение остаётся в presentation layer: состав Portfolio, ViewModel-данные,
+маршруты и интерактивные действия не меняются. У страницы нет действия для
+Position Card, поэтому клавиатурный focus-стиль должен быть только следствием
+имеющегося focusable-элемента, а не превращать карточку в контрол.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Сделать стоимость и доходность акции визуально первичными, а идентификатор и
+  служебные метрики — спокойным вторым уровнем без конкурирующих акцентов.
+- Сохранить цветовую семантику доходности без отдельного badge, фона или
+  декоративной иконки.
+- Сохранить читаемость одноколоночной карточки на узком и широком экранах.
+
+**Non-Goals:**
+
+- Изменение состава, вычисления или форматирования данных Portfolio.
+- Изменение карточек облигаций и других типов позиций, порядка секций,
+  навигации, кликабельности или API.
+- Добавление новых UI-библиотек, токенов, изображений либо интерактивных
+  состояний без существующего контролa.
+
+## Decisions
+
+### D1 — Визуальный вариант передаётся для секции акций
+
+Position Section передаёт в существующую карточку presentation-only вариант для
+`STOCK`. Это позволяет сделать акцию выразительнее и оставить карточки
+облигаций в поставленном виде без копирования разметки или расхождения метрик.
+Альтернатива — отдельная Stock Card — отклонена: она дублирует уже общий
+контент карточки и повышает риск расхождения при будущих изменениях метрик.
+
+### D2 — Две главные зоны и одна тихая мета-строка
+
+Главная строка имеет только две зоны: слева логотип, название и одна
+объединённая строка количества с ISIN; справа — текущая стоимость и доходность
+простым цветным текстом. Средняя цена и доля переходят в единую приглушённую
+мета-строку под разделителем. Локальная CSS-сетка обеспечивает устойчивое
+выравнивание, усечение длинного имени и перенос метаданных без изменения DOM
+порядка или доступных текстовых значений. Альтернатива — отдельные вложенные
+карточки/панели — отклонена: лишняя декоративная вложенность ослабляет
+плотность списка.
+
+### D3 — Доходность остаётся текстовой метрикой
+
+Доходность использует только существующие positive/negative theme colors и
+умеренную насыщенность шрифта; ни фон, ни скруглённый контейнер не создаются.
+При нулевой доходности цветной treatment не применяется. Альтернатива — новая
+палитра или иконка направления — отклонена: цвет и знак уже передают нужный
+сигнал, а дополнительный символ создаёт шум.
+
+### D4 — Hover и focus не добавляются к некликабельной карточке
+
+Карточка остаётся неинтерактивной. Допустим только ненавязчивый hover для
+визуального отклика указателя; focus-стиль не добавляется, потому что Card не
+участвует в keyboard navigation. Альтернатива — сделать карточку button/link —
+отклонена как выходящая за границы change навигационная функция.
+
+## Delivery Map
+
+| Area | Status | Architectural outcome or N/A reason |
+| --- | --- | --- |
+| frontend | `affected` | Position Card получает presentation-only вариант акции и локальные стили группировки, статуса доходности и адаптивной компоновки; существующие page tests уточняют ожидаемую разметку акций. |
+| backend | `N/A` | Контракт, data fetching и финансовые расчёты Portfolio не меняются. |
+| specs | `affected` | Change хранит утверждённые Proposal и Design с `skip_specs: true`, поскольку существующие требования уже покрывают состав и семантику карточки. |
+| docs | `affected` | As-built описание Portfolio кратко фиксирует уточнённую визуальную иерархию карточек акций после поставки. |
+
+### Contract Gate Decision
+
+| Gate | Status | Reason |
+| --- | --- | --- |
+| runtime-openapi | `N/A` | Ни backend, ни frontend API contract и generated snapshot не меняются. |
+
+## Risks / Trade-offs
+
+- Длинное имя инструмента может конкурировать с суммой на узком экране → имя
+  остаётся усечённым, а стоимость занимает приоритетную правую область.
+- Слишком заметная доходность может перегрузить список → используется только
+  существующий цвет текста без фона, badge или отдельной иконки.
+- Различие внешнего вида акций и облигаций может восприниматься как
+  несогласованность → оно ограничено явной пользовательской целью и не меняет
+  общий набор метрик, одноколоночность или логотип.
+
+## Migration Plan
+
+Поставка ограничена обратимой заменой presentation-разметки и локальных
+стилей frontend, затем обновлением as-built documentation. Данные, миграции и
+совместимость между приложениями не затрагиваются.
+
+### Rollback Contract
+
+| Field | Decision |
+| --- | --- |
+| Status | `N/A` |
+| Reason | Change не меняет security, данные, миграции, публичный контракт или другое труднообратимое решение; прежний вид возвращается обратимой правкой frontend presentation layer. |
+| Trigger | N/A |
+| Actions | N/A |
+| Data safety | N/A |
+| Verification | N/A |
@@ -0,0 +1,36 @@
+## Why
+
+Карточки акций уже показывают нужные данные, но их визуальная иерархия слабо
+подчёркивает главные для портфеля ориентиры: название инструмента, текущую
+стоимость и доходность. Второстепенные сведения конкурируют с ними за внимание,
+а строка доходности не отделена визуально от остальных метрик.
+
+## What Changes
+
+- Уточнить визуальную иерархию карточки акции: данные об инструменте, текущей
+  стоимости и доходности должны считываться как три самостоятельные группы.
+- Сделать доходность заметным компактным статусом с сохранением существующей
+  цветовой семантики положительного и отрицательного результата.
+- Привести отступы, выравнивание и состояния наведения/клавиатурного фокуса к
+  единому аккуратному виду на узких и широких экранах.
+- Не менять состав данных, порядок акций, секции портфеля, вычисления, API,
+  навигацию или кликабельность карточек.
+
+## Capabilities
+
+### New Capabilities
+
+Нет: change уточняет визуальное оформление уже поставленного отображения
+Portfolio Position и не вводит нового наблюдаемого поведения.
+
+### Modified Capabilities
+
+Нет: требования существующих capabilities не меняются; это presentation-only
+уточнение в пределах текущей реализации.
+
+## Impact
+
+- Пользователь страницы портфеля быстрее различает инструмент, его стоимость и
+  результат инвестирования в списке акций.
+- Затрагивается frontend presentation-layer карточек акций и его локальные
+  стили. Backend, API, состав и расчёт данных, а также зависимости не меняются.
@@ -0,0 +1,21 @@
+## 1. Frontend presentation
+
+- [x] 1.1 [frontend] Перестроить presentation-only вариант карточки `STOCK` в две главные зоны с единой мета-строкой, убрав badge и сохранив вид облигаций и иных позиций.
+  - **Covers:** `N/A` — change не вводит самостоятельного requirement: задача реализует утверждённое Design в пределах уже поставленного отображения Portfolio Position.
+  - **Verification:** Обновить существующий тест страницы для разметки акции и выполнить `npm run verify` в `frontend`.
+
+## 2. As-built documentation and planning verification
+
+- [x] 2.1 [docs] Обновить as-built описание Portfolio кратким описанием двухзонной визуальной иерархии карточки акции после проверенной поставки.
+  - **Covers:** `N/A` — документирует фактический результат presentation-only change, не создавая параллельную requirements specification.
+  - **Verification:** Выполнить `npm run verify` в `docs` и проверить локальную ссылочную корректность изменённого feature document.
+
+- [x] 2.2 [specs] Выполнить structural validation утверждённых planning artifacts с зафиксированным `skip_specs: true` и проверить отсутствие whitespace ошибок в SDD authority.
+  - **Covers:** `N/A` — change не имеет Delta Requirements; задача проверяет канонический SDD artifact и его delivery metadata.
+  - **Verification:** Выполнить strict change validation через `openspec validate polish-stock-position-cards --type change --strict --store wealth-ledger-specs` и `git diff --check` в `specs`.
+
+## 3. Cross-area completion
+
+- [x] 3.1 [workspace] Сверить поставленное frontend presentation behavior с Proposal и Design, затем выполнить canonical workspace dispatcher и independent read-only review перед archive.
+  - **Covers:** `N/A` — workspace владеет только межрепозиторной semantic verification и review, а не реализацией требования.
+  - **Verification:** Выполнить `bash specs/scripts/verify-workspace-change.sh polish-stock-position-cards` из workspace root и зафиксировать отсутствие Critical/Important findings в review.