architecture-standards

name	architecture-standards
description	Универсальные архитектурные стандарты проекта. Правила создания новых модулей (UI/Logic) и декомпозиции существующих. Гарантирует чистоту кода через использование composables, разделение ответственности и соблюдение соглашений об именовании.

Архитектурные стандарты и декомпозиция

Обзор

Этот навык определяет, как структурировать код в проекте. Мы придерживаемся принципа разделения ответственности (Separation of Concerns): UI-компоненты отвечают за отображение, Composables — за состояние и бизнес-логику, Helpers — за чистые вычисления. Применим как для создания нового функционала, так и для рефакторинга существующего.

1. Проектирование нового функционала

При создании новых фич следуйте иерархии:

1. Domain Layer: Логика в src/entities/ (типы, фабрики, валидация).
2. Logic Layer: Composables (use-*.ts) для управления состоянием и эффектами.
3. UI Layer: Vue-компоненты. Крупные блоки делятся на родительский (оркестратор) и дочерние (leaf) компоненты.

2. Стратегия декомпозиции (для существующего кода)

Если компонент или модуль становится слишком сложным (более 300 строк или более 3 обязанностей):

1. Identify: Составьте список обязанностей и зафиксируйте жесткие инварианты.
2. Extract Constants: Вынесите метаданные и константы.
3. Extract Helpers: Вынесите чистые функции (stateless).
4. Extract Logic: Перенесите ref, computed, watch и хуки жизненного цикла в composables.
5. Extract Components: Разделите шаблон на мелкие функциональные части.

3. Правила именования и файлов

• Vue-компоненты: PascalCase (TheHeader.vue, BlockSettings.vue).
• TS-файлы: kebab-case (use-auth-logic.ts, canvas-tree-utils.ts).
• Composables: префикс use-, экспорт функции в camelCase. Называйте файлы по ответственности (use-tree-insertion.ts).
• Идентификация компонентов: Используйте атрибут data-slot="имя-компонента-в-kebab-case" на корневом элементе каждого компонента.
• Инварианты: Никогда не удаляйте и не переименовывайте data-* атрибуты, используемые для тестов, прокрутки или Drag-and-Drop.

4. Меры предосторожности (Guardrails)

• State Authority: Не создавайте дублирующееся состояние. Используйте существующие синглтоны-композаблы из src/features/editor/model/.
• Domain in UI: Не пишите сложную логику мутаций данных прямо в <template>.
• Email Compatibility: В UI-компонентах для писем используйте только табличную верстку и inline-стили через @mysigmail/vue-email-components.
• Shadow DOM: Проверяйте, что технические префиксы стилей p- используются корректно и стили не текут наружу.

5. Чек-лист проверки (Validation)

1. Код проходит pnpm -s vue-tsc --noEmit и eslint.
2. Сохранены все UX-инварианты (выделение, прокрутка, персистентность, drag-and-drop).
3. Соблюдена обратная совместимость Props/Emits (если не указано иное).
4. Проверен Round-trip: Export JSON -> Import JSON дает идентичный результат.

Формат вывода

При выполнении задач:

1. Перечислите созданные/измененные файлы и их зоны ответственности.
2. Укажите сохраненные инварианты.
3. Сообщите о результатах проверки (Typecheck/Lint).