39948-vm/documentation/project-improvement-todo.ru.md

TODO по улучшению проекта

Дата исследования: 2026-06-28

Цель: строгий, но не enterprise-heavy backlog для небольшого production-проекта. Система должна стать более предсказуемой: явные boundaries, единые contracts, единая модель доступа, единый подход к server state и API validation. Улучшения выполняются маленькими PR без большого rewrite.

Принципы

• Сначала фиксируем текущее поведение тестами/чеклистами, потом рефакторим.
• Для нового кода целевые правила обязательны; старый код приводится к ним постепенно.
• Не добавляем тяжёлую инфраструктуру "на будущее", но добавляем строгие boundaries там, где уже есть production-risk.
• Для risky changes используем маленькие PR и manual verification.
• Документацию в documentation/ обновляем только когда реально меняется API, schema, workflow или deployment.

Целевые правила архитектуры

Backend:

• Route/controller layer: только auth/context, validation, вызов service, response mapping.
• Service/domain layer: business logic, permissions decisions, transactions.
• DB API/repository layer: только data access, filters, includes, pagination.
• Policy layer: вся логика доступа в одном месте, не в отдельных routes.
• Validation layer: все внешние body/query/params проходят schema validation.

Frontend:

• Redux: только client/app state.
• TanStack Query: server state, lists/details/mutations/cache invalidation.
• Feature code: новая feature-specific логика живёт рядом с feature, а не размазывается по generic folders.
• any, type assertions/casts, disabled hook rules и direct axios calls в feature components не являются целевым стандартом.

P1 - Frontend

Разделить самые большие файлы по строгим boundaries

Boundaries должны быть строгими.

TODO:

• constructor.tsx: выносить pure helpers, feature hooks и state reducers в отдельные файлы.
• RuntimePresentation.tsx: выносить navigation/media/preload helpers и state logic в отдельные files/hooks.
• Feature-specific файлы класть рядом с feature, а не в generic components.

Redux и TanStack Query

Redux не нужно удалять полностью.

Оставить Redux для:

• auth/session UI;
• theme/style;
• layout/sidebar;
• constructor UI state;
• app preferences.

Целевое правило: server data не хранится в Redux. Existing entity Redux slices считаются legacy и заменяются на TanStack Query по одному flow.

TODO:

• Зафиксировать правило: Redux для client/app state, TanStack Query для server state.
• Не создавать новые entity CRUD Redux slices.
• Пилотно мигрировать один простой entity flow (roles или permissions) на TanStack Query.
• Не удалять старый Redux slice, пока все consumers entity не мигрированы.
• API reads/mutations делать через TanStack Query hooks, не через Redux thunks.

Frontend TypeScript strictness

Цель: включить strict TypeScript как обязательный стандарт для frontend и закрыть legacy errors без сохранения JS/CommonJS как допустимого направления. Новый и изменённый код должен быть strict-compatible.

TODO:

• Посчитать текущий frontend typecheck baseline: сколько ошибок даёт strict: true.
• Включать strictness по шагам: сначала отдельный strict config для selected folders/new code, затем общий strict: true, когда baseline закрыт.
• Для новых/изменённых файлов запрещать новый any без явной причины.
• Запретить новые type assertions/casts (as, angle-bracket assertions, non-null !) в feature code. Исключения: validated external boundaries, DOM/library interop, discriminated unions после guard; исключение должно быть локальным и объяснённым.
• Вернуть no-unused-vars/unused imports как warning, затем поднять до error после cleanup.
• Добавить frontend typecheck script и включить его в minimal checks, когда baseline проходит.
• react-hooks/exhaustive-deps включать file-by-file после исправления конкретных hooks.

Auth storage

Сейчас token пишется и в sessionStorage, и в localStorage.

TODO:

• Решить, нужен ли persistent login.
• Если persistent login не нужен, оставить только sessionStorage.
• Если нужен, оставить localStorage, но осознанно и с коротким TTL/refresh policy.
• Заменить frontend jsonwebtoken decode на jwt-decode или /auth/me.

Минимальные regression checks

Начать с smoke tests/checklist:

• login;
• constructor load/save;
• save to stage;
• publish;
• public production runtime;
• private production runtime grant;
• page navigation;
• rest.

P1 - Build и зависимости

Package manager

Сейчас есть смешение lockfiles/scripts.

TODO:

• Выбрать один package manager для frontend/backend.
• Удалить лишний lockfile после проверки install/build.
• Обновить docs/deployment commands.

Dependencies LTS alignment и obsolete package replacement

Зависимости нужно обновлять осознанно, чтобы не закреплять старые toolchain limitations и устаревшие библиотеки.

TODO:

• Проверить текущие frontend/backend dependencies и devDependencies на совместимость с выбранным Node LTS.
• Обновить TypeScript, ESLint, @typescript-eslint/*, Next.js/React tooling и backend runtime tooling до актуальных LTS/stable versions.
• Найти deprecated, unsupported и obsolete packages через package manager audit/outdated/deprecation warnings, npm metadata, release notes и project documentation.
• Для deprecated/unsupported/obsolete packages выбрать actively maintained mainstream alternatives с широкой adoption, свежими releases, нормальной TypeScript/ESM support и понятным migration path.
• Для каждой замены зафиксировать причину: что именно deprecated/unsupported/obsolete, какой replacement выбран, какие breaking changes ожидаются.
• Проверить DB scripts, migrations/seeders, test runner и production start после dependency updates.
• Не делать blind major upgrades без changelog/release notes и rollback plan.

Node version

TODO:

• Зафиксировать выбранный Node LTS через backend/package.json engines.node.
• Согласовать engines.node.
• Обновить @types/node во frontend, когда будет удобно.

CI/minimal checks

Для небольшого проекта достаточно минимального gate:

• frontend build;
• frontend lint/typecheck, если проходит;
• backend lint;
• smoke checklist перед deploy.

Audit/outdated/license checks делать периодически, не обязательно blocking на каждый PR.

P2 - Security hardening

CSP

Полный CSP может быть сложным из-за embeds/media. Не вводить сразу.

TODO:

• Сначала собрать список нужных domains для assets/embeds.
• Если будет время, включить report-only CSP на stage.
• Enforced CSP делать только после проверки runtime presentations.

P2 - Документация

TODO:

• Обновить docs только для реально изменённых workflows/API/schema.

Рекомендуемый порядок

1. Добавить validation для самых рискованных endpoints и запретить новые routes без validation.
2. Проверить DB slow queries и добавить только реально нужные индексы.
3. Выбрать package manager и Node version.
4. Добавить минимальные smoke checks.
5. Постепенно выносить helpers из больших frontend/backend файлов при изменениях.
6. Пилотно перевести один entity flow с Redux на TanStack Query.
7. Делать cleanup/dependency upgrades небольшими отдельными PR.

Definition of Done

• Production workflows проверены вручную или тестом.
• Нет большого rewrite без явной выгоды.
• DB changes имеют backup/rollback plan.
• Документация обновлена только там, где изменилось поведение.