301 lines
31 KiB
Markdown
301 lines
31 KiB
Markdown
## Context
|
||
|
||
Шесть frontend-local документов сейчас находятся в `frontend/docs/`.
|
||
Их README перечисляет темы, а local AGENTS одновременно служит входом и кратким
|
||
пересказом отдельных правил. Общая policy, context discipline, lifecycle,
|
||
architecture и as-built сведения уже имеют владельцев в отдельном `docs`.
|
||
Подход сохраняет это разделение и использует утверждённую Delta Spec
|
||
`specs/openspec-authority-and-lifecycle/spec.md` данного change.
|
||
|
||
Адресная проверка текущих источников уточнила основания решений:
|
||
|
||
- `frontend/biome.json` задаёт ошибки для declarations named components,
|
||
default exports и порядка exports с локальными исключениями. Он не задаёт
|
||
общего запрета непереведённых JSX-строк; TypeScript такого запрета не добавляет.
|
||
- `@testing-library/user-event` не объявлен напрямую в `frontend/package.json`,
|
||
но присутствует в lockfile через Storybook. Интерактивные тесты используют
|
||
`fireEvent` из объявленного `@testing-library/react`.
|
||
- Project-local schema `wealth-ledger-sdd` имеет version 5. Отслеживаемый Git
|
||
файл `specs/openspec/.cli-version` существует и содержит `1.10.0`.
|
||
ADR 010 описывает прежние schema v3, custom verifiers и dispatcher;
|
||
текущие lifecycle и entrypoints направляют к native OpenSpec и repo gates.
|
||
- Storybook уже поставлен. Workflow summary содержит прежнее число групп,
|
||
тогда как каталог описывает актуальную структуру у собственного владельца.
|
||
|
||
Это основания для уточнения документации, а не для изменения tooling или
|
||
исправления других main-spec requirements. Planning остаётся только в store
|
||
`wealth-ledger-specs`; исторические источники не становятся объектом миграции.
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:** сохранить локальные правила при смене пути, определить единственного
|
||
владельца каждого решения о контексте и дать исполнителю точный способ отличать
|
||
обязательное чтение и review от автоматического enforcement и guidance.
|
||
Design фиксирует соответствие сохраняемого содержания конечным владельцам;
|
||
отдельный постоянный реестр для этого не нужен.
|
||
|
||
**Non-Goals:** изменение application runtime, API, auth, данных, dependencies,
|
||
schema graph или canonical gates; новый context framework, instruction layer,
|
||
checker, dispatcher, scoring либо token limit. Bundle-budget drift,
|
||
backend e2e, переносимость Completion Evidence и массовое переустройство
|
||
conventions остаются вне этого change.
|
||
|
||
## Decisions
|
||
|
||
### 1. Существующие источники сохраняют ownership
|
||
|
||
`frontend/.ai/` полностью заменяет `frontend/docs/` как место локальных правил.
|
||
В нём непосредственно лежат `README.md`, `CONVENTIONS.md`, `STRUCTURE.md`,
|
||
`API-LAYER.md`, `UI-PATTERN.md` и `TESTING.md`. Это relocation существующего
|
||
набора, без вложенного дерева, metadata, нового AGENTS или второго index.
|
||
Старые поддерживаемые копии и redirect stubs не остаются.
|
||
|
||
Frontend AGENTS направляет к `.ai/README.md` для выбора применимых документов,
|
||
сохраняет local gate и краткие boundaries. README приложения предоставляет
|
||
тот же вход и полезные прямые ссылки. Краткие pointers в AGENTS не заменяют
|
||
текст владельца и не требуют автоматически читать весь набор conventions.
|
||
|
||
Общая authority остаётся в `docs/development`: context discipline владеет
|
||
выбором и повторным определением inputs, lifecycle — входом по фазе и native
|
||
процедурой, governance — approvals, ролями и обязательностью проверок.
|
||
Architecture, ADR и as-built сведения остаются в своих текущих docs-разделах.
|
||
Frontend router ссылается на эти источники вместо копирования policy.
|
||
|
||
Альтернатива с двумя поддерживаемыми каталогами оставляет неоднозначный owner.
|
||
Новый registry или metadata layer создаёт дополнительную синхронизацию без
|
||
нового поведения; шесть существующих документов уже соответствуют границам.
|
||
|
||
### 2. Один локальный router выбирает объединение применимых тем
|
||
|
||
Таблица маршрутов принадлежит `frontend/.ai/README.md`. Она использует
|
||
содержание предстоящего решения, а не только расширение файла или название
|
||
задачи. Одновременно действующие triggers объединяются:
|
||
|
||
| Содержание изменения | Локальный документ в `.ai/` |
|
||
| --- | --- |
|
||
| Создание/перенос module или slice, cross-slice imports и public API boundaries | `STRUCTURE.md` |
|
||
| React declarations, props, exports, продуктовые строки и Zod messages | `CONVENTIONS.md` |
|
||
| Container/VM/view, формы, query states, skeleton, retry/recovery | `UI-PATTERN.md` |
|
||
| HTTP client, generated types, query/mutation, Bearer и refresh | `API-LAYER.md` |
|
||
| Изменение самих тестов либо поведения с testing risk trigger | `TESTING.md` |
|
||
|
||
Например, UI props и presentation требуют conventions и UI pattern; auth
|
||
refresh добавляет API и testing по security/concurrency risk. Наличие query
|
||
state во view само по себе не требует API rules, пока не затронуты получение
|
||
данных, query/mutation или transport boundary. Router не дублирует список
|
||
risk triggers: их полная policy остаётся в governance с указателем из TESTING.
|
||
|
||
### 3. Повторный routing расширяет существующую context discipline
|
||
|
||
В `docs/development/agent-token-efficiency.md` уточняется существующий раздел
|
||
Routing context. Фаза и affected areas определяются до supporting reads;
|
||
применимость inputs сверяется до первого зависимого решения, при новой области
|
||
или границе и перед handoff. Первая сверка работает и при отсутствии diff.
|
||
|
||
Перед handoff основанием служат фактические staged, unstaged и новые файлы
|
||
вместе с содержанием работы. Используется существующая inventory procedure
|
||
этого же документа: учитывается working content tracked и nonignored untracked
|
||
files, relevant ignored и workspace-owned inputs перечисляются явно.
|
||
Чужой concurrent diff учитывается при разграничении ownership, но не даёт
|
||
полномочий присвоить его текущему change. Второй manifest не вводится.
|
||
|
||
Новая граница в пределах approved scope означает загрузку её правил до
|
||
зависимой работы. Необходимость изменить intent, observable behavior,
|
||
architecture или Tasks означает возврат к соответствующей самой ранней
|
||
planning boundary. Само уточнение чтения не требует повторного approval;
|
||
расширение разрешённой работы следует существующей cascade policy.
|
||
|
||
В existing lifecycle достаточно коротких указателей на эту сверку в native
|
||
planning, Implementation/Validation и перед передачей результата. Отдельная
|
||
таблица фаз и контекста там не создаётся: владельцем mapping остаётся context
|
||
authority, а конкретные dependencies/contextFiles возвращает native instruction
|
||
разрешённого artifact или Apply.
|
||
|
||
При recovery восстанавливаются canonical artifacts и их approval bindings,
|
||
все обязательные native inputs, применимые risk inputs и согласованный Design
|
||
package текущей фазы. В том же контексте неизменившиеся прочитанные inputs
|
||
переиспользуются по действующей policy. Missing input, неоднозначная версия
|
||
или digest mismatch блокируют зависимое решение. Краткий handoff, внешний
|
||
каталог и число документов не заменяют обязательные источники.
|
||
|
||
### 4. Перенос сохраняет требования и действующие исключения
|
||
|
||
Следующая таблица относится только к этому Design: это соответствие исходного
|
||
содержания конечному owner для semantic review переноса. Она не становится
|
||
постоянным convention registry. Правила по возможности остаются в одноимённом
|
||
перенесённом документе; полезные краткие pointers между ними сохраняются.
|
||
|
||
| Исходное содержание | Конечный владелец | Что должно сохраниться |
|
||
| --- | --- | --- |
|
||
| `frontend/docs/README.md`: назначение набора, темы, общая policy и источник версий/scripts | `frontend/.ai/README.md` | Компактный router, ссылки на общие authorities; фактические dependencies и scripts определяет конфигурация проекта. |
|
||
| `frontend/docs/STRUCTURE.md` и FSD boundary из AGENTS | `frontend/.ai/STRUCTURE.md` | Локальные слои `app → pages → features → entities → shared`, без `widgets`; slice public API через `index.ts`, alias `@/` и запрет обхода public API. Владение theme/tokens, общий public API для app и Storybook, границы shared/ui и ссылка на дизайн-систему. |
|
||
| `frontend/docs/CONVENTIONS.md`: общие Must | `frontend/.ai/CONVENTIONS.md` | Biome style, type-only imports, правила enum/namespace, exact dependency versions, colocated tests, Conventional Commits и действующая pre-commit процедура. Public API и gate pointers сохраняют связь с владельцами. |
|
||
| `frontend/docs/CONVENTIONS.md`: i18n и Zod | `frontend/.ai/CONVENTIONS.md` | Продуктовые строки в locale через `useTranslation()`; Zod messages через `validationMessage(key)`. Обязательность сохраняется при semantic review без обещания общего автоматического запрета JSX-строк. |
|
||
| `frontend/docs/CONVENTIONS.md`: React component style | `frontend/.ai/CONVENTIONS.md` | Const-valued named components, export rules, `FC`, named props, `PropsWithChildren`, отсутствие inline props typing и destructuring parameters, читаемый нижний export block и прямые barrel re-exports. Storybook CSF default meta/direct story exports и конфигурационные default-export exceptions сохраняются в фактическом scope Biome; synthetic story data не подменяют i18n продукта. |
|
||
| File roles в `CONVENTIONS.md` и VM/view rules в `UI-PATTERN.md` | `frontend/.ai/CONVENTIONS.md` и `frontend/.ai/UI-PATTERN.md` соответственно | Container вызывает page VM; VM владеет data/auth/route inputs, state selection, domain grouping и derived presentation data; view получает props. Сохраняются запрет data/auth/router/navigation/VM hooks во view, допустимые translation/form-context/UI-only hooks и formatter одного значения. Разбиение по semantic responsibility, flat views и исключение для маленького tightly-coupled renderer не заменяются line-count rule. |
|
||
| `frontend/docs/API-LAYER.md` и API boundary из AGENTS | `frontend/.ai/API-LAYER.md` | Backend OpenAPI как authority; committed snapshot и generated types, offline generation/drift check, запрет ручного редактирования generated и дублирования transport DTO. Только typed shared clients, отсутствие прямых fetch в features/pages/entities и прямых T-Bank calls, slice ownership cache keys/policies. Bearer принадлежит shared authenticated fetch; auth endpoints исключены; single-flight refresh и один retry `UNAUTHORIZED`; query/mutation не задают Authorization. |
|
||
| `frontend/docs/UI-PATTERN.md`: формы и recovery | `frontend/.ai/UI-PATTERN.md` | React Hook Form, Zod resolver и FormProvider; form state в container/VM, context fields во view; блокирование действий при submit; field errors и сетевой Alert с сохранением ввода. Known API errors/retry локальны, непойманные route errors принадлежат route-keyed ErrorBoundary. |
|
||
| `frontend/docs/UI-PATTERN.md`: query states и skeleton | `frontend/.ai/UI-PATTERN.md` | Loading/error/empty/loaded без успешных данных; Client Cached Snapshot при refetch и его ошибке с progress, предупреждением и retry, отдельно от server stale/fallback. Page/section ownership structural skeleton, доступная busy-область, декоративные shapes без данных, интерактивности и фокуса; сохранение shell, neutral auth skeleton до ready. Mutation loading и cached-snapshot progress остаются контекстными indicators. |
|
||
| `frontend/docs/TESTING.md` | `frontend/.ai/TESTING.md` | Risk-based selection и ссылка на governance, observable behavior/AAA, validation без запроса при невалидной форме, route access/redirect и recovery cases, finance states и route-boundary reset. MSW только из Vitest setup, без browser worker/mock development mode; transport headers/retry через MSW. Один coverage-backed Vitest в gate, короткий локальный test run, coverage как anti-regression constraint без тестов ради процента. |
|
||
| Canonical gates и lifecycle safeguards в entrypoints | Local AGENTS affected repos и текущие `docs/development` authorities | Выбор Node по `.nvmrc`, repo-owned gates, fixed store, отдельные approvals, fingerprints, независимая Validation и Finalization. Их определения не копируются в новый локальный workflow. |
|
||
|
||
Неточность testing helper исправляется внутри TESTING: описывается используемый
|
||
`fireEvent` из Testing Library с ожиданием наблюдаемого async outcome.
|
||
Транзитивный `user-event` не объявляется отсутствующим на диске или напрямую
|
||
принятым проектом. Замена текста не меняет тестовую инфраструктуру и не требует
|
||
переписывания существующих тестов.
|
||
|
||
### 5. Enforcement описывается у владельца правила
|
||
|
||
В AGENTS и conventions различаются три категории: автоматическое блокирование
|
||
существующей проверкой, обязательная процедура/semantic review и guidance.
|
||
Автоматический статус указывается только для фактически проверяемого scope;
|
||
исключения описываются рядом. Component declarations и export rules сохраняют
|
||
Biome enforcement, а `FC`/props conventions и полнота i18n остаются обязательными
|
||
для review. Успех type/style checks не доказывает локализацию всех строк.
|
||
|
||
Раздел Guardrails общей governance уточняется в той же классификации:
|
||
определение Enforceable Engineering Invariant сохраняется для детерминированных
|
||
проверок, но отсутствие checker не переводит явно обязательную semantic policy
|
||
в guidance. Необязательные эстетические предпочтения остаются guidance.
|
||
Так общий owner и frontend instructions не дают противоположных указаний.
|
||
|
||
Новый автоматический запрет здесь не создаётся. Existing gates сохраняют свои
|
||
inputs и ответственность; structural validation не получает полномочий
|
||
подтверждать semantic compliance, approval или независимый PASS.
|
||
|
||
### 6. Текущая навигация обновляется без переписывания истории
|
||
|
||
Действующие входы обнаруживаются по старым путям и разрешаются относительно
|
||
файла-источника, включая локальные anchors. Текущий адресный inventory содержит
|
||
frontend AGENTS/README, UI-каталог и live ссылки на conventions/UI pattern в
|
||
remediation registry. Для registry меняются только эти адреса: Audit IDs,
|
||
dispositions, статусы, даты, формулировки findings и evidence links сохраняются.
|
||
|
||
В текущих main specs, schema и optional `.opencode/commands` ссылок на старые
|
||
frontend paths не найдено. Optional entrypoints уже направляют к lifecycle и
|
||
context authority, поэтому отдельная их редакция не нужна. Root AGENTS также
|
||
сохраняет действующий routing. При последующей адресной сверке новая активная
|
||
ссылка включается только в пределах разрешённой области; чужой approved
|
||
artifact нельзя переписывать для чистого результата поиска.
|
||
|
||
Historical OpenSpec archives, dated audits, прежнее Completion Evidence и
|
||
сохранённые датированные research/browser snapshots не редактируются.
|
||
Generated graph/cache outputs не являются поддерживаемыми instructions и не
|
||
регенерируются ради смены пути. Совпадение старого пути само по себе не означает
|
||
сломанный действующий маршрут. Отказ от redirect stub делает текущие пропуски
|
||
видимыми и сохраняет единственного владельца правил.
|
||
|
||
### 7. ADR и workflow summaries направляют к текущей процедуре
|
||
|
||
По правилу `docs/adr/README.md` замена решения оформляется новым ADR со ссылкой
|
||
на прежний. В `docs/adr` добавляется ADR 011
|
||
`011-native-openspec-lifecycle-with-repository-gates.md`, фиксирующий уже
|
||
действующий native lifecycle и repo-owned gates. Он содержит контекст, решение
|
||
и последствия этой замены, ссылки на governance/lifecycle/context authority
|
||
и на ADR 010; новый процесс или самостоятельный порядок команд не вводится.
|
||
|
||
В ADR 010 сохраняются исходное rationale и рассмотренные альтернативы, а
|
||
заменённые части про schema v3, custom verifiers и dispatcher получают явную
|
||
историческую квалификацию и ссылку на successor. Сохраняющийся выбор native
|
||
OpenSpec и независимых repo gates не объявляется отвергнутым. Index отражает
|
||
частичную замену. Такой подход предпочтительнее полного переписывания ADR 010
|
||
под сегодняшний текст или примечания без successor, нарушающего ADR policy.
|
||
|
||
Документация различает текущую schema version и наличие `.cli-version`;
|
||
удаление этого файла не утверждается. Его наличие также не выдаётся за
|
||
доказательство запуска прежнего verifier. Этот change не меняет version
|
||
contract, CLI pin, schema или untouched requirements о tooling.
|
||
|
||
Числовая структура Storybook принадлежит `docs/development/ui-catalog.md`.
|
||
`frontend-workflow.md` ссылается на этот owner без собственного числа групп.
|
||
Frontend entrypoints точно описывают уже поставленный каталог и его участие
|
||
в существующем gate. Использование каталога разрешено как существующей
|
||
инфраструктуры; ограничения на добавление новых инструментов сохраняются.
|
||
Reference каталога не заменяет отдельный Design approval и независимую Validation.
|
||
|
||
### 8. Доказательство опирается на routing scenarios и existing gates
|
||
|
||
Semantic review сопоставляет перенос с таблицей сохранения и применяет
|
||
утверждённые сценарии Delta Specs к получившимся маршрутам. Для UI-only,
|
||
API/auth, изменения тестов, структуры и строк проверяется состав применимых
|
||
документов; docs-only опечатка служит неприменимым контрпримером к обязательному
|
||
чтению всех frontend conventions.
|
||
|
||
Scope expansion рассматривается отдельно внутри approved границ и за ними;
|
||
handoff включает unstaged/new inputs, recovery — весь обязательный пакет,
|
||
а недоступный input должен оставлять явный blocker. Это проверка принятия
|
||
решений по содержанию, без unit tests, повторяющих Markdown, и без нового
|
||
checker. Ссылочная проверка и сохранение исторических bytes дополняют
|
||
canonical gates affected областей; они не подменяют независимую Validation.
|
||
|
||
## UI/UX Applicability and Package
|
||
|
||
**Applicability and scope:** `N/A`. Change меняет расположение и содержание
|
||
инженерных инструкций, не экраны, состояния, interactions или responsive
|
||
behavior приложения/каталога. Макеты, PNG/SVG exports и immutable visual reuse
|
||
inputs не нужны. Весь Design package — этот Markdown-файл.
|
||
|
||
## Delivery Map
|
||
|
||
| Area | Status | Architectural outcome or N/A reason |
|
||
| --- | --- | --- |
|
||
| frontend | `affected` | Единственный набор conventions непосредственно в `.ai/`, локальный router, точные инструкции и актуальная навигация; runtime, dependencies и gate не меняются. Область проходит свой canonical gate. |
|
||
| backend | `N/A` | Не меняются backend behavior, contract, implementation, local instructions или gate. Backend delivery и backend-only проверки не требуются этим change. |
|
||
| specs | `affected` | Canonical planning и уточнение capability `openspec-authority-and-lifecycle` по approved Delta Specs; native structural checks. Синхронизация main specs остаётся штатной completion operation, historical archives сохраняются. |
|
||
| docs | `affected` | Context discipline и lifecycle pointers, точная классификация обязательности, историческая квалификация ADR 010 с successor, workflow summary и действующие links. Общая as-built authority остаётся на месте; область проходит canonical docs gate и scoped link review. |
|
||
|
||
### Contract Gate Decision
|
||
|
||
| Gate | Status | Reason |
|
||
| --- | --- | --- |
|
||
| runtime-openapi | `N/A` | Ни backend runtime contract, ни frontend snapshot/generated types не меняются. Сохранение описания typed API и auth ownership не является изменением сторон API contract. |
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- Перенос с сокращением может потерять оговорки. Одноимённые владельцы,
|
||
ограниченные точечные редакции и таблица сохранения делают semantic diff
|
||
проверяемым; массовая консолидация текста не нужна.
|
||
- Без redirect старый live link перестанет работать. Scoped review отличает
|
||
действующую навигацию от неизменяемых исторических ссылок и проверяет targets
|
||
после relocation, в том числе переходы между независимыми repositories.
|
||
- Ручной routing может пропустить вторую тему. Объединение triggers и повторные
|
||
сверки по фактическому scope снижают риск; автоматический анализ не обещается.
|
||
- Классификация без checker может быть воспринята как ослабление. Явная
|
||
mandatory-review категория и согласованный текст общей governance сохраняют
|
||
обязательность i18n, validation и прочих semantic требований.
|
||
- ADR может смешать историческое и действующее решение. Частичная замена,
|
||
successor и точные ссылки сохраняют rationale и отделяют текущую процедуру
|
||
от старой реализации; untouched spec drift не скрывается редакцией этого Design.
|
||
|
||
Build-versus-buy trigger отсутствует: общая tooling/infrastructure не вводится
|
||
и существенно не заменяется, используются уже принятые Markdown owners,
|
||
native OpenSpec и repository gates. Формальная Solution Assessment не нужна.
|
||
|
||
## Migration Plan
|
||
|
||
После отдельных planning approvals перенос выполняется как согласованный
|
||
documentation batch: сначала сохраняется одноимённый frontend набор и его
|
||
содержание, затем переключаются локальные и межрепозиторные входы. Target paths
|
||
и активная навигация должны сходиться до передачи реализации в Validation;
|
||
промежуточное смешение старых и новых путей не является завершённой поставкой.
|
||
|
||
В том же delivery приводятся в соответствие общая context discipline,
|
||
классификация enforcement и описание действующего workflow/ADR. Это изменение
|
||
существующих owners, без дублирования правил в schema или optional adapters.
|
||
Исторические artifacts сохраняются; canonical Proposal и Delta Specs этого
|
||
change не редактируются ради переноса ссылок, описывающих исходное состояние.
|
||
|
||
Проверяемая реализация передаётся отдельной Validation с фактическим inventory.
|
||
Canonical gates всех affected областей, independent verdict, semantic sync и
|
||
Completion Evidence остаются на своих lifecycle boundaries. Ошибка ссылки или
|
||
потерянное требование устраняется в реализации; противоречие утверждённому
|
||
approach возвращается к соответствующему planning artifact.
|
||
|
||
### Rollback Contract
|
||
|
||
| Field | Decision |
|
||
| --- | --- |
|
||
| Status | `N/A` |
|
||
| Reason | Обратимая документационная relocation не меняет auth/security behavior, данные, публичный API contract или труднообратимое решение. При откате связанный набор frontend/doc navigation возвращается согласованно средствами Git; пользовательские данные и runtime migration отсутствуют. |
|