# 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.