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