# 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.
- Документация обновлена только там, где изменилось поведение.