moex-vibe/docs/features/architecture-quality-backlog/spec.md

Architecture Quality Backlog

Дата: 2026-06-26 Статус: выполнено

Контекст

После нескольких завершённых волн cleanup и refactor в проекте остались два типа проблем:

• часть архитектурного долга всё ещё открыта, но описана фрагментами в разных backlog-документах;
• часть документации отстаёт от фактического состояния кода и уже закрытых feature-итераций.

До этой фичи backlog был распределён между frontend-debt-audit, backend-architecture-refactor, roadmap и отдельным worktree-драфтом architecture-quality-backlog. Из-за этого было неочевидно, что уже закрыто, что требует только синхронизации docs, а что должно стать следующими отдельными refactor-фичами.

Эта фича не меняет runtime-поведение. Она фиксирует canonical architecture backlog и приводит source-of-truth документы к одному состоянию.

Цель

Собрать и опубликовать единый архитектурный backlog проекта, синхронизировать roadmap и связанные audit/refactor docs и определить нормализованный порядок следующих follow-up фич без изменения кода.

Требования

1. Инвентаризация текущего состояния

Нужно сверить:

• docs/features/frontend-debt-audit/spec.md;
• docs/features/backend-architecture-refactor/spec.md и tasks.md;
• docs/roadmap.md;
• опубликованные архитектурные документы в apps/docs/docs/frontend/ и apps/docs/docs/backend/.

2. Удаление устаревших и уже закрытых пунктов

Backlog не должен повторно открывать задачи, которые уже закрыты отдельными feature-итерациями. Минимум нужно убрать или переотнести:

• API envelope double-wrapping после api-envelope-contract;
• первичное production config/error masking hardening после backend-architecture-refactor;
• устаревшие статусы, где roadmap или spec остались в промежуточном состоянии.

3. Публикация нормализованного backlog

Оставшийся architecture backlog должен быть опубликован как пять независимых направлений, чтобы каждое можно было позже оформить отдельной feature-spec:

1. T-Bank Data Isolation and Ownership Boundaries
2. Backend Runtime and Auth Hardening
3. Local T-Bank Read Path
4. Session Model for Multiple Surfaces
5. Contract, Type-Safety, and Frontend Delivery Hardening

4. Явные границы каждого backlog item

Для каждого направления должны быть описаны:

• цель;
• риск;
• зависимости;
• ожидаемая граница follow-up фичи;
• причина, почему item не закрывается в рамках текущей docs-only фичи.

5. Никаких runtime-изменений

Фича не должна:

• менять пользовательские сценарии;
• менять API или модель данных;
• править apps/frontend/src/** или apps/backend/src/**;
• превращать backlog-публикацию в непосредственный refactor runtime-кода.

Нормализованный backlog

1. T-Bank Data Isolation and Ownership Boundaries

Цель: изолировать T-Bank accounts, positions, operations и derived views по пользователю и закрепить ownership boundary до дальнейших data-flow изменений.

Риск: без этого остаётся риск multi-tenant data leak и неявной shared ownership-модели.

Зависимости: текущая T-Bank integration, Prisma data model, auth identity boundary.

Граница follow-up фичи: backend/domain feature про ownership model, query filtering и migration-safe изоляцию данных.

Почему не закрыто сейчас: требует runtime-изменений, data model decisions и отдельной спецификации.

2. Backend Runtime and Auth Hardening

Цель: закрыть оставшиеся production-grade security/runtime policy вопросы после первичной refactor волны.

Риск: частично остаются недооформленные rate limiting, auth policy и surface-level security guards.

Зависимости: результаты backend-architecture-refactor, текущая auth/session модель, deployment/runtime env policy.

Граница follow-up фичи: backend/security feature без смешивания с multi-tenancy или session redesign.

Почему не закрыто сейчас: требует отдельной threat-model driven runtime работы, а не docs sync.

3. Local T-Bank Read Path

Цель: перевести чтение операций и истории на локальную persisted модель вместо прямого read-through в T-Bank там, где это необходимо для стабильности и контроля данных.

Риск: текущая зависимость от external read path усложняет устойчивость, latency control и auditability.

Зависимости: ownership boundary для T-Bank данных, sync model, persisted operation schema.

Граница follow-up фичи: backend data-flow feature про local persistence, sync and read model.

Почему не закрыто сейчас: требует runtime data-flow changes и, вероятно, schema/runtime planning.

4. Session Model for Multiple Surfaces

Цель: определить явную session model для web/PWA/extension-like surfaces, включая device-level sessions, rotation и reuse detection.

Риск: текущая модель остаётся слишком узкой для нескольких клиентских поверхностей и finer-grained session control.

Зависимости: auth boundary, refresh-token policy, future surface strategy.

Граница follow-up фичи: auth/session feature без смешивания с общим backend security backlog.

Почему не закрыто сейчас: требует product/security decisions и отдельного session contract.

5. Contract, Type-Safety, and Frontend Delivery Hardening

Цель: сократить остаточную type unsafety, стабилизировать frontend API/query boundaries и усилить quality/performance gates.

Риск: остаются as any, слабые boundary-contracts, нет полного покрытия performance/testing gates.

Зависимости: существующий API envelope contract, generated types, frontend routing/query architecture.

Граница follow-up фичи: набор узких quality-hardening features, начиная с type-safety и frontend delivery constraints, без смешивания с backend domain refactor.

Почему не закрыто сейчас: это уже не backlog sync, а серия отдельных implementation changes.

Ограничения

• Только docs/ и согласование опубликованных архитектурных описаний с backlog.
• Не дублировать один и тот же долг в нескольких независимых backlog-списках.
• Не создавать новый epic только ради этой docs-only нормализации.

Критерии приемки

• В основном workspace существует canonical feature docs/features/architecture-quality-backlog/.
• docs/roadmap.md отражает эту фичу и использует тот же нормализованный порядок backlog-направлений.
• frontend-debt-audit и backend-architecture-refactor больше не противоречат текущему состоянию закрытых работ.
• Для каждого backlog item указаны цель, риск, зависимости, follow-up boundary и причина defer.
• В рамках фичи не изменены runtime-файлы apps/frontend/src/** и apps/backend/src/**.

Источники

• docs/features/frontend-debt-audit/spec.md
• docs/features/backend-architecture-refactor/spec.md
• docs/features/backend-architecture-refactor/tasks.md
• docs/roadmap.md
• apps/docs/docs/frontend/overview.md
• apps/docs/docs/backend/modules.md