511 lines
34 KiB
Markdown
511 lines
34 KiB
Markdown
# Repository Audit: WealthLedger Frontend
|
||
|
||
**Дата:** 2026-08-31
|
||
**Session ID:** `01a05590-9243-7df0-9664-508acc5fc3e9`
|
||
**Invoked skills:** `repository-audit`
|
||
**Supporting skills invoked:** none
|
||
**External research performed:** no
|
||
|
||
## Scope and Confidence
|
||
|
||
**Target:** `frontend/`, Git branch `main`.
|
||
**Target commit:** `7ab043dce63a3fbacbfc9ac7d15b00dd714a541f`
|
||
(`docs: remove useless`).
|
||
**Initial target state:** `git status --porcelain=v1 --untracked-files=all` был
|
||
пуст; целевой репозиторий не содержал tracked или untracked изменений.
|
||
|
||
**Reference:** `references/frontend-ai-template/`. Директория не является
|
||
Git-репозиторием, поэтому commit identity недоступна. Идентичность
|
||
зафиксирована SHA-256 checksum аудируемого содержимого:
|
||
`7fced9c6906bdc846847eec40e05aac7c2c59f9fe593acc298eaab4bb29e2a9a`.
|
||
Checksum получен как SHA-256 отсортированного списка per-file SHA-256 и
|
||
относительных путей. Из scope исключены `node_modules` на любой глубине,
|
||
`.idea`, `.playwright-mcp`, cache-, build- и coverage-директории. Эталон
|
||
использовался только для сравнения эквивалентных обязанностей, не как authority.
|
||
|
||
Аудит standalone и read-only: OpenSpec/SDD workflow не запускался. Единственная
|
||
запись — этот отчёт вне `frontend/` и reference. В inventory вошли все 145
|
||
tracked-файлов target (117 под `src`, 22 test-файла) и 220 релевантных файлов
|
||
reference после исключения локальных зависимостей и ephemeral artifacts.
|
||
Углублённо проверены manifests/lockfile, TypeScript/Vite/Vitest/Biome/Knip/
|
||
dependency-cruiser/Husky configuration, repository instructions и frontend
|
||
docs, auth/session и API seams, routing/error boundary, representative finance
|
||
pages, entities, ViewModels, tests и эквивалентные reference responsibilities.
|
||
По всему `src` выполнены searches импортов, network calls, generated types,
|
||
tests и крупных modules; не каждый CSS-файл и не весь generated OpenAPI файл
|
||
читались построчно.
|
||
|
||
Выполненные проверки:
|
||
|
||
- `npm run deps` — exit 0; 136 modules и 484 dependency edges, нарушений нет;
|
||
- `npm run knip` — exit 0, findings отсутствуют;
|
||
- offline generation `openapi-typescript` во временный файл — текущий
|
||
`schema.d.ts` байтово совпадает со snapshot;
|
||
- controlled invalid-date probe под Node 22 —
|
||
`RangeError: Invalid time value`, подтверждающий F-03.
|
||
|
||
Полный `npm run verify`, `test:coverage`, build, Storybook и E2E не запускались:
|
||
они создают или могут изменять `coverage`, `dist`, reports и caches, что не
|
||
соответствует read-only контракту аудита. Также не выполнялись install,
|
||
dependency advisory scan, backend runtime contract test и browser-based visual/
|
||
accessibility checks. Поэтому выводы о текущем полном gate, supply-chain
|
||
уязвимостях, реальном backend и визуальном поведении не заявляются.
|
||
|
||
**Общая confidence:** high для статической архитектуры, tooling и найденных
|
||
расхождений; medium для production/release risk из-за локальной границы системы
|
||
и отсутствия runtime/browser evidence.
|
||
|
||
**Preservation check:** после всех inspection/validation commands target
|
||
остался на том же commit с пустым porcelain status; повторный reference checksum
|
||
совпал с исходным. Временный generated artifact удалён. Единственное
|
||
сохранённое изменение сессии — этот Markdown report.
|
||
|
||
## Executive Summary
|
||
|
||
Репозиторий в целом находится в хорошем состоянии: небольшой React/Vite client
|
||
имеет строгий TypeScript, один typed HTTP boundary, risk-oriented Vitest/MSW
|
||
tests, coverage floors, dead-code analysis и более сильные dependency rules,
|
||
чем reference. Критических findings нет.
|
||
|
||
Наибольшую ценность дадут F-01 и F-02: восстановить детерминированную проверку
|
||
generated OpenAPI artifact и закрыть реальный login journey существующим test
|
||
stack. F-03 — небольшой, но уже воспроизводимый trust-boundary defect в URL date
|
||
validation. F-04 уточняет существенное ограничение заявленного public-API gate:
|
||
он не видит type-only dependencies и уже пропускает семь внутренних imports.
|
||
Остальная архитектурная стоимость сосредоточена в двух ownership seams (F-05,
|
||
F-08) и в документации, которая местами описывает удалённые либо избыточно
|
||
жёсткие guardrails (F-06, F-07).
|
||
|
||
Эталон полезен как подтверждение ценности OpenAPI drift check, но его Storybook,
|
||
browser MSW, Playwright harness, локальный OpenSpec и 17 agent skills не должны
|
||
переноситься в target: текущая система локальна, а эти поверхности не решают
|
||
наблюдаемую проблему пропорционально своей стоимости.
|
||
|
||
## Priority Findings
|
||
|
||
| Severity | Finding | Category | Action | Effort |
|
||
| --- | --- | --- | --- | --- |
|
||
| high | F-01. Generated OpenAPI types не защищены от drift | Tooling / API Contract | add | small |
|
||
| high | F-02. Основной auth journey не проверяется | Testing / Security | add | small |
|
||
| medium | F-03. Некорректная календарная дата бросает исключение | Correctness / Validation | change | small |
|
||
| medium | F-04. Type-only dependencies обходят public-API guardrail | Architecture / Tooling | change | small |
|
||
| medium | F-05. Ubiquitous Money formatting принадлежит Portfolio | Architecture / Ownership | change | medium |
|
||
| medium | F-06. Entry-point docs обещают отсутствующие проверки | AI Readiness / Documentation | change | small |
|
||
| low | F-07. File-splitting rule создаёт ложный hard invariant | Complexity / AI Readiness | simplify | small |
|
||
| low | F-08. T-Bank status обходит общий authenticated-query seam | Architecture / Maintainability | change | small |
|
||
|
||
## Findings
|
||
|
||
### F-01. Generated OpenAPI types не защищены от drift
|
||
|
||
**Category:** Tooling / API Contract
|
||
**Severity:** high
|
||
**Confidence:** high
|
||
**Action:** add
|
||
**Effort:** small
|
||
|
||
**Observed:** Frontend хранит и OpenAPI snapshot, и generated
|
||
`schema.d.ts`, но canonical `verify` не проверяет, что второй детерминированно
|
||
получен из первого. Workflow полагается на ручное выполнение
|
||
`npm run openapi:generate` после копирования snapshot.
|
||
|
||
**Evidence:** `frontend/package.json:17-20` содержит `openapi:generate`, но
|
||
`verify` состоит только из typecheck, Biome, coverage, Knip,
|
||
dependency-cruiser и build. `frontend/docs/API-LAYER.md:3-5` прямо описывает
|
||
ручные два шага. Backend `test:openapi-contract` сравнивает runtime contract с
|
||
frontend snapshot, но не snapshot с `frontend/src/shared/api/generated/schema.d.ts`.
|
||
Текущий controlled check с генерацией в `/private/tmp` показал
|
||
`OPENAPI_GENERATED_MATCH yes`, то есть finding относится к отсутствующему
|
||
guardrail, а не к текущему рассинхрону. TypeScript и build являются
|
||
counter-evidence только для внутренней согласованности кода со stale generated
|
||
типами; происхождение этих типов они доказать не могут.
|
||
|
||
**Why it matters:** Изменение snapshot без генерации может одновременно пройти
|
||
frontend `verify` и backend runtime-contract check, оставив приложение
|
||
скомпилированным против старого публичного контракта. Для auth и финансовых
|
||
response shapes это даёт silent contract risk в главном typed boundary.
|
||
|
||
**Reference repository:** **adopt from reference — capability only.** Reference
|
||
имеет `scripts/check-openapi.mjs`, `openapi:check` и включает его в `verify` и
|
||
pre-commit (`reference/package.json:13-28`,
|
||
`reference/scripts/check-openapi.mjs:1-32`). Это узкий guardrail с прямой
|
||
проблемой и без новой dependency. Остальной reference toolchain для него не
|
||
нужен.
|
||
|
||
**Recommended direction:** Добавить один non-mutating offline check: с помощью
|
||
уже установленного `openapi-typescript` генерировать temp artifact, сравнивать
|
||
его с committed `schema.d.ts` и включить сравнение в canonical `verify`.
|
||
Не синхронизировать backend и не переписывать tracked files внутри gate.
|
||
|
||
### F-02. Основной auth journey не проверяется
|
||
|
||
**Category:** Testing / Security
|
||
**Severity:** high
|
||
**Confidence:** high
|
||
**Action:** add
|
||
**Effort:** small
|
||
|
||
**Observed:** Test suite хорошо покрывает восстановление session, Bearer retry,
|
||
очистку cache, anonymous redirects и одну отрицательную registration validation,
|
||
но ни один тест не выполняет успешный login/register/logout через public UI/
|
||
provider boundary. В частности, untested остаётся связка `AuthForm` →
|
||
`AuthProvider.authenticate` → auth endpoint → in-memory access token → переход
|
||
на protected route.
|
||
|
||
**Evidence:** Поиск по всем 22 test-файлам нашёл auth assertions только в
|
||
`src/shared/api/client.test.ts`, `src/shared/api/authenticated-query.test.tsx`,
|
||
`src/features/auth/model/auth.test.tsx`, `src/features/auth/ui/AuthForm.test.tsx`
|
||
и `src/app/routes/AppRoutes.test.tsx`. `auth.test.tsx:11-102` проверяет три
|
||
refresh/401 сценария; `AuthForm.test.tsx:16-41` — только несовпадающее
|
||
подтверждение пароля; route test восстанавливает session через refresh.
|
||
Tests не вызывают `login`, `register` или `logout`, не отправляют валидную
|
||
форму и не проверяют `LoginForm`/`RegisterForm` navigation. Это проверено
|
||
repository-wide search, а не выводом из отсутствия отдельного filename.
|
||
|
||
**Why it matters:** Auth — security-sensitive и critical user journey по
|
||
действующей risk-based testing policy. Независимо покрытые низкоуровневые seams
|
||
не обнаружат поломку их композиции: неверный endpoint/body, потерянное session
|
||
state update, неработающий `returnTo`, navigation до завершения auth или
|
||
неочищенный UI после logout.
|
||
|
||
**Reference repository:** **reference approach is unnecessary.** Reference
|
||
имеет Playwright и browser MSW, но его E2E покрывает Todo demo, не auth. Перенос
|
||
всего browser harness ради этого риска добавит больше lifecycle cost, чем
|
||
существующий Vitest + Testing Library + MSW boundary.
|
||
|
||
**Recommended direction:** Добавить минимальный risk-focused integration test
|
||
на существующем stack, который вводит валидные credentials, проходит реальный
|
||
`AuthProvider`/MSW login и наблюдает protected landing/session outcome. Logout
|
||
или failure следует добавлять только там, где их риск не покрыт уже имеющимися
|
||
provider/client tests; Playwright для этого finding не требуется.
|
||
|
||
### F-03. Некорректная календарная дата бросает исключение
|
||
|
||
**Category:** Correctness / Validation
|
||
**Severity:** medium
|
||
**Confidence:** high
|
||
**Action:** change
|
||
**Effort:** small
|
||
|
||
**Observed:** `isDate` сначала проверяет только форму `YYYY-MM-DD`, затем без
|
||
проверки validity вызывает `toISOString()`. Строка вроде `2026-99-99` проходит
|
||
regex и приводит к `RangeError`, а не к validation result `false`.
|
||
|
||
**Evidence:** `src/pages/account-income/ui/AccountIncomePage.vm.ts:35-46` подаёт
|
||
`isDate` в Zod refinements; `:51-71` читает даты из untrusted URL search params;
|
||
`:114-132` использует `new Date(...).toISOString()` в `isDate` и затем снова в
|
||
`validPeriod`. Controlled Node 22 probe над этой же операцией вернул
|
||
`INVALID_DATE_THROW RangeError: Invalid time value`. Existing income tests
|
||
покрывают analytics, empty bucket, chart и recoverable server error, но не
|
||
malformed URL/form dates. Общий `RouteErrorBoundary` ограничивает blast radius,
|
||
но превращает validation error в аварийный route state.
|
||
|
||
**Why it matters:** Пользователь или внешняя ссылка может сломать income route
|
||
одним syntactically-shaped query parameter. Это доступность и корректность на
|
||
trust boundary; exception bypasses предусмотренное восстановление default
|
||
period и field-level validation.
|
||
|
||
**Reference repository:** **neither reflects a directly comparable case.**
|
||
Reference валидирует numeric route params через Zod `safeParse`, но не содержит
|
||
эквивалентной календарной логики, поэтому переносить его hook не нужно.
|
||
|
||
**Recommended direction:** Сделать date predicate total: проверить parsed date
|
||
до `toISOString` либо валидировать год/месяц/день безопасным стандартным
|
||
преобразованием, затем зафиксировать malformed query/form date регрессионным
|
||
тестом. Новая date library не нужна.
|
||
|
||
### F-04. Type-only dependencies обходят public-API guardrail
|
||
|
||
**Category:** Architecture / Tooling / AI Readiness
|
||
**Severity:** medium
|
||
**Confidence:** high
|
||
**Action:** change
|
||
**Effort:** small
|
||
|
||
**Observed:** Dependency-cruiser проверяет cycles, layer direction и public
|
||
entrypoints только для dependencies, существующих после TypeScript compilation.
|
||
Type-only edges не входят в graph, хотя repository docs формулируют public-API
|
||
правило без такого исключения. В результате семь consumers импортируют
|
||
внутренний generated module `@/shared/api/generated/schema` напрямую.
|
||
|
||
**Evidence:** В `frontend/dependency-cruiser.cjs:45-48` задан `tsConfig`, но нет
|
||
`tsPreCompilationDeps`; установленный dependency-cruiser 18.2.0 устанавливает
|
||
его default в `false` (`node_modules/dependency-cruiser/src/main/options/defaults.mjs:9`).
|
||
`frontend/docs/CONVENTIONS.md:9` и `frontend/docs/STRUCTURE.md:11-13` требуют
|
||
cross-slice imports через `index.ts`, а `frontend/AGENTS.md:34` называет это
|
||
dependency-cruiser-enforced boundary. При этом прямые type-only imports
|
||
`@/shared/api/generated/schema` находятся в пяти entity API hooks,
|
||
`features/auth/model/auth.tsx` и
|
||
`features/tbank-connection/ui/TbankConnectionSection.tsx`;
|
||
`frontend/src/shared/api/index.ts` не реэкспортирует `paths`. Успешный
|
||
`npm run deps` не является counter-evidence: эти edges отсутствуют в
|
||
анализируемом graph. Counter-evidence по масштабу риска — остальные найденные
|
||
type-only imports идут через public APIs в разрешённом направлении, а текущие
|
||
семь generated imports не создают runtime coupling.
|
||
|
||
**Why it matters:** Заявленный machine-enforced invariant фактически не
|
||
распространяется на compile-time architecture. Новый type-only upward import,
|
||
type cycle или обращение к внутренностям другого slice сможет пройти canonical
|
||
gate; существующий generated seam уже демонстрирует расхождение code и policy.
|
||
Severity остаётся medium, потому что текущие edges стираются при compilation и
|
||
не создают runtime cycle или bundle dependency.
|
||
|
||
**Reference repository:** **adopt from reference — capability, not exception.**
|
||
Reference включает `tsPreCompilationDeps: true`, но исключает generated subtree
|
||
из dependency analysis. Target может сохранить более строгий и ясный public API,
|
||
не копируя это исключение.
|
||
|
||
**Recommended direction:** Реэкспортировать generated `paths` как type из
|
||
`shared/api/index.ts`, перевести семь consumers на `@/shared/api` и включить
|
||
`tsPreCompilationDeps: true` в существующем dependency-cruiser config. Если
|
||
generated path действительно должен быть публичным исключением, сначала
|
||
зафиксировать его явно и всё равно проверять остальные type-only edges. Новая
|
||
dependency или второй architecture checker не нужны.
|
||
|
||
### F-05. Ubiquitous Money formatting принадлежит Portfolio
|
||
|
||
**Category:** Architecture / Ownership
|
||
**Severity:** medium
|
||
**Confidence:** high
|
||
**Action:** change
|
||
**Effort:** medium
|
||
|
||
**Observed:** Общий display formatter `formatMoney` типизирован через
|
||
`Portfolio["totalsByCurrency"][number]` и экспортируется из Portfolio entity,
|
||
хотя используется для Brokerage Account, Ledger Entry, Income Analytics и
|
||
Future Cash Event. `formatSnapshotTime` и instrument logo helper также частично
|
||
разделяются через тот же Portfolio public API.
|
||
|
||
**Evidence:** Canonical domain glossary определяет Money как самостоятельный
|
||
ubiquitous value `{ currency, value }`, который frontend форматирует для
|
||
отображения (`docs/architecture/domain-glossary.md:20-28`). Реализация в
|
||
`src/entities/portfolio/model/display.ts:1-18` выводит Money type из Portfolio.
|
||
Repository-wide usage показывает импорт Portfolio formatter из
|
||
`src/entities/brokerage-account/ui/BrokerageAccountList.tsx`,
|
||
`src/entities/broker-operation/ui/LedgerEntryRow.tsx`, account/events/income
|
||
pages и их section views. `npm run deps` проходит, потому что текущие rules
|
||
контролируют direction/public entrypoints, но не смыслового владельца peer
|
||
entities. Counter-evidence: formatter один, протестирован и не дублируется;
|
||
проблема именно в owner/type dependency, а не в реализации форматирования.
|
||
|
||
**Why it matters:** Изменение Portfolio transport shape или реорганизация
|
||
Portfolio заставляет менять несвязанные account, ledger и income consumers.
|
||
Граница утверждает, что общий Money concern принадлежит одной product entity,
|
||
и легализует entity-to-entity coupling, которое dependency tool не различает.
|
||
|
||
**Reference repository:** **reference approach is unnecessary.** Todo-only
|
||
reference не моделирует shared Money value и не предлагает применимого owner.
|
||
|
||
**Recommended direction:** Переместить только действительно ubiquitous
|
||
display primitives (в первую очередь Money formatting и, при подтверждении
|
||
общего смысла, date formatting) в нейтральный существующий lower-level owner.
|
||
Оставить `formatShare` и portfolio error behavior в Portfolio. Не вводить Money
|
||
service, interface hierarchy или новую domain layer ради одного formatter.
|
||
|
||
### F-06. Entry-point docs обещают отсутствующие проверки
|
||
|
||
**Category:** AI Readiness / Documentation
|
||
**Severity:** medium
|
||
**Confidence:** high
|
||
**Action:** change
|
||
**Effort:** small
|
||
|
||
**Observed:** Человеческий entrypoint сообщает, что `verify` отклоняет неверный
|
||
Node runtime и проверяет repository hygiene, а conventions утверждают, что
|
||
pre-commit запускает OpenAPI check. Ни одной из этих команд в текущих scripts/
|
||
hook нет.
|
||
|
||
**Evidence:** `frontend/README.md:25-27` перечисляет runtime и hygiene;
|
||
`frontend/docs/CONVENTIONS.md:14` перечисляет pre-commit OpenAPI check.
|
||
Фактически `frontend/package.json:9-22` не содержит `runtime:check`,
|
||
`hygiene:check` или `openapi:check`, а `.husky/pre-commit` выполняет только
|
||
`npx lint-staged` и `npm run deps`. Counter-evidence: `.nvmrc`,
|
||
`engines.node = 22.x` и repository-local `AGENTS.md` корректно требуют
|
||
`nvm use --silent`; canonical config остаётся discoverable. Расхождение
|
||
ограничено двумя stale prose claims, а не всей документацией.
|
||
|
||
**Why it matters:** Новый разработчик или coding agent получает ложное
|
||
completion evidence и может считать runtime, env hygiene или generated artifact
|
||
проверенными. Особенно опасно сочетание с F-01: docs называют guardrail, которого
|
||
больше нет.
|
||
|
||
**Reference repository:** **both are acceptable only where config and prose
|
||
agree.** Reference действительно включает свой `openapi:check`, но его намного
|
||
больший documentation surface не нужен target. Target уже лучше как concise,
|
||
canonical entrypoint; ему требуется синхронизация нескольких утверждений, а не
|
||
перенос reference docs.
|
||
|
||
**Recommended direction:** Привести README и CONVENTIONS к фактическим scripts:
|
||
описать manual Node activation и реальные hook/gate stages. Если F-01 добавлен,
|
||
упомянуть только реально включённый OpenAPI check. Не возвращать отдельные
|
||
runtime/hygiene scripts без нового конкретного failure mode.
|
||
|
||
### F-07. File-splitting rule создаёт ложный hard invariant
|
||
|
||
**Category:** Complexity / AI Readiness
|
||
**Severity:** low
|
||
**Confidence:** high
|
||
**Action:** simplify
|
||
**Effort:** small
|
||
|
||
**Observed:** UI docs объявляют обязательным отдельный file для каждого
|
||
top-level state и каждого именуемого page section, но несколько текущих modules
|
||
сознательно хранят cohesive presentation рядом. Самый заметный пример —
|
||
388-line `AccountIncomePage.view.tsx` с loading/error/loaded и шестью semantic
|
||
section components.
|
||
|
||
**Evidence:** `frontend/docs/CONVENTIONS.md:12-13` и
|
||
`frontend/docs/UI-PATTERN.md:30-35` формулируют правило как Must/«нельзя».
|
||
`src/pages/account-income/ui/AccountIncomePage.view.tsx:29-380` содержит
|
||
`AccountIncomePageLoading`, `AccountIncomePageError`, loaded view, summary,
|
||
comparisons, trend, breakdown и forecast. Подобная colocated state structure
|
||
есть в `AccountsPage.view.tsx` и небольшом T-Bank view. Counter-evidence:
|
||
важная граница container → VM → props-only view в проверенных finance pages
|
||
соблюдается; большой income view читается последовательно и покрыт одним
|
||
behavior-level page test. Поэтому само количество components/files не является
|
||
failure mode.
|
||
|
||
**Why it matters:** Непроверяемое и уже нарушенное Must заставляет agents либо
|
||
игнорировать authority, либо создавать file/ barrel sprawl без улучшения
|
||
ownership. Оно также маскирует действительно важный invariant — views не должны
|
||
владеть data fetching и collection derivation.
|
||
|
||
**Reference repository:** **reference approach is unnecessary.** Reference
|
||
часто создаёт отдельную директорию и file для каждого Todo state; это полезно
|
||
для component catalog demo, но увеличивает navigation cost для текущего product
|
||
client и не должно становиться механической нормой.
|
||
|
||
**Recommended direction:** Оставить VM/view ownership rule обязательным, а
|
||
file splitting сделать locality-based guidance: выделять section, когда у неё
|
||
есть самостоятельная responsibility, reuse, test/change cadence или она мешает
|
||
пониманию owner. Не добавлять line-count checker и не требовать one-component-
|
||
per-file.
|
||
|
||
### F-08. T-Bank status обходит общий authenticated-query seam
|
||
|
||
**Category:** Architecture / Maintainability
|
||
**Severity:** low
|
||
**Confidence:** high
|
||
**Action:** change
|
||
**Effort:** small
|
||
|
||
**Observed:** Все entity queries используют shared `useAuthenticatedQuery`,
|
||
который подписывается на session snapshot. T-Bank connection status вместо
|
||
этого импортирует `useAuth` из соседней feature и вручную задаёт
|
||
`enabled: Boolean(accessToken)` обычному `useQuery`.
|
||
|
||
**Evidence:** `src/shared/api/authenticated-query.ts:13-33` владеет session
|
||
gating; его используют brokerage account, operation, event, income и portfolio
|
||
hooks. `src/features/tbank-connection/ui/TbankConnectionSection.vm.ts:1-15`
|
||
создаёт второй механизм и feature → feature dependency на `features/auth`.
|
||
`dependency-cruiser.cjs` не запрещает peer-feature dependencies, поэтому
|
||
успешный `npm run deps` не является counterexample. Counter-evidence: текущее
|
||
поведение функционально совпадает, access token обновляется через AuthProvider,
|
||
а mutations всё равно идут через общий authenticated fetch.
|
||
|
||
**Why it matters:** Изменение определения authenticated readiness,
|
||
`configureAuthClient` или session clearing может примениться ко всем entity
|
||
queries, но не к T-Bank status. Соседняя feature становится зависимой от auth
|
||
implementation detail при уже существующей lower-level seam.
|
||
|
||
**Reference repository:** **not comparable.** Reference не имеет auth/session
|
||
boundary.
|
||
|
||
**Recommended direction:** Переиспользовать existing authenticated-query seam
|
||
для status query и убрать feature-to-feature dependency. Новая abstraction или
|
||
расширение dependency rules ради единственного случая не нужны.
|
||
|
||
## Missing Practices
|
||
|
||
- F-01 — отсутствует доказательство происхождения committed generated API
|
||
types из committed snapshot.
|
||
- F-02 — отсутствует risk-focused integration proof главного auth journey.
|
||
- F-03 — trust-boundary date validation не total и не имеет malformed-input
|
||
regression coverage.
|
||
- F-04 — type-only dependencies не входят в заявленный public-API/layer gate;
|
||
уже существуют семь direct generated-internal imports.
|
||
|
||
Отсутствие CI/CD и deployment automation не считается finding: canonical
|
||
`docs/architecture/system-overview.md` явно ограничивает текущую поставку
|
||
локальной системой, а `frontend/AGENTS.md` требует отдельного approved change
|
||
для CI, Playwright или Storybook.
|
||
|
||
## Over-engineering / Simplification Opportunities
|
||
|
||
- F-07 — сузить file-splitting Must до правила ownership/locality, сохранив
|
||
важную VM/view границу.
|
||
- Не переносить из reference Storybook, browser MSW mode, Playwright harness,
|
||
локальный `openspec/` и 17 repository-provided skills: для target нет
|
||
наблюдаемой проблемы, оправдывающей этот context и maintenance surface.
|
||
- F-05 следует исправлять переносом маленьких shared primitives, не созданием
|
||
Money service/interface/factory.
|
||
- Не добавлять второй FSD framework или checker: текущий dependency-cruiser уже
|
||
проверяет cycles, public entrypoints и layer direction лучше reference.
|
||
|
||
## AI Readiness
|
||
|
||
AI readiness выше средней: `AGENTS.md` короткий, различает hard guardrails и
|
||
review guidance, направляет к специализированным docs и canonical multi-repo
|
||
authority; scripts и public APIs предсказуемы; generated seam явно помечена;
|
||
dependency-cruiser и Knip снижают необходимость загружать длинные инструкции.
|
||
Главные ухудшения — F-04 (type-only blind spot), F-06 (несовпадение prose с
|
||
executable truth) и F-07 (непроверяемый structural Must). Reference agent
|
||
surface значительно больше и для target был бы регрессом context locality.
|
||
|
||
## What Is Already Good
|
||
|
||
- Строгая и воспроизводимая основа: Node 22 contract, npm lockfile, exact direct
|
||
dependency versions, strict TypeScript и Biome.
|
||
- `npm run deps` подтверждает отсутствие cycles/layer/public-API violations в
|
||
анализируемых runtime edges; target имеет отдельные cycle/public-API rules,
|
||
которых нет в reference, но F-04 ограничивает полноту этого доказательства.
|
||
- Один HTTP owner: repository-wide search не нашёл прямой network access вне
|
||
`src/shared/api/client.ts`; transport types выводятся из OpenAPI.
|
||
- Auth design соответствует system/domain authority: access token остаётся в
|
||
memory, refresh использует cookie и single-flight behavior; Bearer exclusion,
|
||
refresh retry и cache clearing имеют focused tests.
|
||
- 22 colocated test-файла покрывают loading/error/empty/cached snapshot,
|
||
finance display, filtering/pagination, route boundary и T-Bank mutations.
|
||
- Coverage floors, Knip, dependency checks и production build собраны в одном
|
||
canonical local gate; controlled Knip/dependency runs успешны.
|
||
- UI resilience и доступные loading/error regions не только описаны, но и
|
||
представлены в code/tests; общий route error boundary ограничивает failures.
|
||
- Текущий OpenAPI snapshot и generated types фактически синхронны; F-01 —
|
||
prevention gap, не текущая поломка.
|
||
|
||
## Recommended Order
|
||
|
||
### Do now
|
||
|
||
1. F-01 — добавить non-mutating OpenAPI generated-artifact equivalence в
|
||
canonical gate.
|
||
2. F-02 — закрыть успешный auth journey существующим Vitest/MSW stack.
|
||
3. F-03 — сделать date validation total и закрепить malformed-input case.
|
||
4. F-04 — включить type-only edges и провести generated types через public API.
|
||
5. F-06 — синхронизировать README/CONVENTIONS с фактическими scripts и hooks.
|
||
|
||
### Do next
|
||
|
||
1. F-05 — вернуть ubiquitous Money display primitive нейтральному owner без
|
||
нового service layer.
|
||
|
||
### Consider later
|
||
|
||
1. F-08 — устранить единичный bypass authenticated-query seam при ближайшем
|
||
изменении T-Bank connection.
|
||
2. F-07 — упростить file-splitting guidance до решения по locality/ownership.
|
||
|
||
### Do not add
|
||
|
||
- Storybook, browser MSW mode или Playwright только потому, что они есть в
|
||
reference; F-02 дешевле и надёжнее закрывается текущим integration stack.
|
||
- Локальный OpenSpec store или копии reference agent skills: canonical SDD
|
||
authority уже находится вне target и entrypoint достаточно короткий.
|
||
- CI/CD, deployment или release platform вне отдельного approved scope:
|
||
as-built system явно локальна.
|
||
- Runtime validation каждого OpenAPI response без конкретного наблюдаемого
|
||
trust-boundary failure; это существенно расширит runtime и schema ownership.
|
||
- Новый FSD framework, line-count gate, one-component-per-file rule, Money
|
||
service/interface или dependency ради findings, которые решаются текущими
|
||
tools и небольшими ownership corrections.
|