| name | architecture-standards |
| description | Универсальные архитектурные стандарты проекта. Правила создания новых модулей (UI/Logic) и декомпозиции существующих. Гарантирует чистоту кода через использование composables, разделение ответственности и соблюдение соглашений об именовании. |
Архитектурные стандарты и декомпозиция
Обзор
Этот навык определяет, как структурировать код в проекте. Мы придерживаемся принципа разделения ответственности (Separation of Concerns): UI-компоненты отвечают за отображение, Composables — за состояние и бизнес-логику, Helpers — за чистые вычисления. Применим как для создания нового функционала, так и для рефакторинга существующего.
1. Проектирование нового функционала
При создании новых фич следуйте иерархии:
- Domain Layer: Логика в
src/entities/ (типы, фабрики, валидация).
- Logic Layer: Composables (
use-*.ts) для управления состоянием и эффектами.
- UI Layer: Vue-компоненты. Крупные блоки делятся на родительский (оркестратор) и дочерние (leaf) компоненты.
2. Стратегия декомпозиции (для существующего кода)
Если компонент или модуль становится слишком сложным (более 300 строк или более 3 обязанностей):
- Identify: Составьте список обязанностей и зафиксируйте жесткие инварианты.
- Extract Constants: Вынесите метаданные и константы.
- Extract Helpers: Вынесите чистые функции (stateless).
- Extract Logic: Перенесите
ref, computed, watch и хуки жизненного цикла в composables.
- 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)
- Код проходит
pnpm -s vue-tsc --noEmit и eslint.
- Сохранены все UX-инварианты (выделение, прокрутка, персистентность, drag-and-drop).
- Соблюдена обратная совместимость Props/Emits (если не указано иное).
- Проверен Round-trip: Export JSON -> Import JSON дает идентичный результат.
Формат вывода
При выполнении задач:
- Перечислите созданные/измененные файлы и их зоны ответственности.
- Укажите сохраненные инварианты.
- Сообщите о результатах проверки (Typecheck/Lint).
