Robotail/Corp
Robotail/Corp
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Corp/docs/reports/SCSS_ARCHITECTURE_AUDIT.md

14 KiB
Raw Blame History

Аудит архитектуры backend/static/scss

Дата: 15 января 2026
Аудитор: GitHub Copilot
Статус: ⚠️ Требуется улучшение

📊 Общая оценка: 7/10

✅ Сильные стороны (7 баллов)

  1. Хорошая структура папок (9/10)

    • ✅ Логичное разделение: abstracts, layout, components, utilities
    • ✅ Подпапка chat для chat компонентов
    • ✅ Понятная организация

  2. Именование файлов (8/10)

    • ✅ Префикс _ для partials
    • ✅ Kebab-case naming
    • ✅ Понятные имена

  3. Документация (7/10)

    • ✅ Есть BUTTONS_README.md
    • ✅ Комментарии в main.scss
    • ⚠️ Нет общего README в scss/

  4. Модульность (9/10)

    • ✅ 30 компонентов в components/
    • ✅ 10 chat модулей в components/chat/
    • ✅ Разделение abstracts

⚠️ Проблемы и недостатки (3 балла снижения)

🔴 Критические проблемы

1. Дублирование импортов компонентов (CRITICAL)

Проблема: Многие компоненты импортируются дважды:

  • Один раз в main.scss → компилируется в app.css
  • Второй раз в custom-bootstrap.scss → компилируется в bootstrap-custom.css

Дублированные импорты:

// В main.scss:
@import 'components/common';
@import 'components/navbar';
@import 'components/sidebar';
@import 'components/page-header';
@import 'components/cards';
@import 'components/modals';
@import 'components/comments';

// И ЕЩЕ РАЗ в custom-bootstrap.scss:
@import "components/common";
@import "components/navbar";
@import "components/sidebar";
@import "components/page-header";
@import "components/cards";
@import "components/modals";
@import "components/comments";

Последствия:

  • ❌ Эти стили дублируются в app.css И bootstrap-custom.css
  • ❌ Увеличенный размер файлов
  • ❌ Повторяющиеся селекторы
  • ❌ Потенциальные конфликты специфичности

Затронутые компоненты:

  1. common
  2. navbar
  3. sidebar
  4. page-header
  5. cards
  6. badges-bem
  7. modals
  8. comments

Размер дублирования: ~1,500-2,000 строк SCSS дублируются!

2. Chat компоненты ТОЛЬКО в bootstrap-custom.css

Проблема: Все 10 chat компонентов импортируются ТОЛЬКО в custom-bootstrap.scss:

// Чат компоненты (в подпапке chat/)
@import "components/chat/message-inputs";
@import "components/chat/chat-detail";
@import "components/chat/chat-date-groups";
@import "components/chat/chat-list-enhanced";
@import "components/chat/chat-enhanced";
@import "components/chat/chat-polls";
@import "components/chat/chat-new-messages-indicator";
@import "components/chat/message-selection";
@import "components/chat/message-context-menu";
@import "components/chat/message-reactions";

Последствия:

  • ❌ Chat стили попадают в bootstrap-custom.css (301 KB)
  • ❌ Нелогично - chat не относится к Bootstrap
  • ❌ Сложнее поддерживать - непонятно где искать

3. Устаревший TODO комментарий

В custom-bootstrap.scss строки 197-199:

// Остальные компоненты (загружаются напрямую из CSS - не мигрировано)
// TODO: Мигрировать buttons, card-list, document-list, request-list,
// ios-search, feed-specific, base-app, request-detail

Проблема: Эти компоненты УЖЕ мигрированы и импортируются в main.scss!

🟡 Средние проблемы

4. Пустая папка utilities/

scss/utilities/ - ПУСТО

В main.scss закомментированы импорты:

// @import 'utilities/spacing-utils';
// @import 'utilities/index';

Проблема:

  • Папка существует но не используется
  • spacing-utils лежит в components/, а не utilities/
  • Запутанная структура

5. Нет главного README.md в scss/

Отсутствует: backend/static/scss/README.md

Есть только:

  • components/BUTTONS_README.md - документация одного компонента
  • Нет общего описания архитектуры

6. Layout компоненты в custom-bootstrap.scss

// Layout
@import "layout/chat-layout";

И в main.scss:

@import 'layout/base-app';
@import 'layout/chat-layout'; // ДУБЛЬ!

chat-layout импортируется дважды!

🟢 Мелкие замечания

7. Несогласованность комментариев

В main.scss:

// 4. UTILITIES - Вспомогательные классы
// @import 'utilities/spacing-utils';
// @import 'utilities/index';

Но _spacing-utils.scss находится в components/, не в utilities/!

8. Размер custom-bootstrap.scss

202 строки, из них:

  • ~70 строк - переопределения переменных Bootstrap
  • ~30 строк - импорты компонентов (многие дублируются)
  • ~100 строк - комментарии

Файл становится перегруженным.

📈 Статистика

Размеры

  • Всего SCSS файлов: 51
  • Всего строк SCSS: 11,394
  • Компонентов в components/: 30
  • Компонентов в components/chat/: 10
  • Layout файлов: 2
  • Abstracts файлов: 4

Импорты

  • Импортов в main.scss: 30
  • Импортов в custom-bootstrap.scss: 25
  • Дублированных импортов: 8 компонентов

Compiled размеры

  • app.css: 95 KB
  • bootstrap-custom.css: 301 KB
  • Дубликаты в обоих: ~15-20 KB

🎯 Рекомендации по улучшению

Приоритет 1: Устранить дублирование (CRITICAL)

Решение A: Разделить компоненты по назначению

app.css (main.scss):

  • Все application-specific компоненты
  • Layout (base-app, chat-layout)
  • Components (buttons, cards, modals, etc.)
  • Chat components
  • Spacing utilities

bootstrap-custom.css (custom-bootstrap.scss):

  • ТОЛЬКО переопределения Bootstrap переменных
  • ТОЛЬКО импорт Bootstrap
  • CSS variables (abstracts/css-variables)
  • Убрать ВСЕ импорты компонентов

Решение B: Создать отдельный chat.css

chat.css (новый entry point):

  • Все chat компоненты
  • Chat layout
  • Подключать только на страницах чата

Приоритет 2: Очистить custom-bootstrap.scss

Удалить из custom-bootstrap.scss:

// ❌ УДАЛИТЬ ВСЕ ЭТО:
@import "layout/chat-layout";
@import "components/common";
@import "components/navbar";
@import "components/sidebar";
@import "components/page-header";
@import "components/cards";
@import "components/badges-bem";
@import "components/chat/...";  // все 10 импортов
@import "components/comments";
@import "components/modals";

Оставить только:

// 1. Переопределение Bootstrap переменных
$spacer: 1rem;
$spacers: (...);
// и т.д.

// 2. Импорт наших abstracts
@import "abstracts/variables";
@import "abstracts/mixins";

// 3. Импорт Bootstrap
@import "../node_modules/bootstrap/scss/bootstrap";

// 4. CSS переменные
@import "abstracts/css-variables";

// ВСЕ! Никаких компонентов!

Приоритет 3: Переместить spacing-utils

# Переместить из components/ в utilities/
mv scss/components/_spacing-utils.scss scss/utilities/
mv scss/components/_layout-spacing.scss scss/utilities/

Раскомментировать в main.scss:

// 4. UTILITIES - Вспомогательные классы
@import 'utilities/layout-spacing';
@import 'utilities/spacing-utils';

Приоритет 4: Документация

Создать scss/README.md:

# SCSS Architecture

## Structure
- abstracts/ - Variables, mixins, functions
- layout/ - Page layouts
- components/ - Reusable components
- utilities/ - Utility classes

## Build
- main.scss → app.css (application styles)
- bootstrap-custom.scss → bootstrap-custom.css (Bootstrap only)

## Components
[список всех компонентов]

Приоритет 5: Удалить устаревшие TODO

Удалить из custom-bootstrap.scss:

// Остальные компоненты (загружаются напрямую из CSS - не мигрировано)
// TODO: Мигрировать buttons, card-list, document-list, request-list,
// ios-search, feed-specific, base-app, request-detail

Все эти компоненты УЖЕ в main.scss!

📋 План действий (по шагам)

Шаг 1: Backup текущего состояния

cp scss/custom-bootstrap.scss scss/custom-bootstrap.scss.backup
cp scss/main.scss scss/main.scss.backup

Шаг 2: Очистить custom-bootstrap.scss

Удалить все импорты компонентов, оставить только:

  • Переопределения переменных Bootstrap
  • Импорт abstracts
  • Импорт Bootstrap
  • Импорт css-variables

Шаг 3: Переместить chat в main.scss

Добавить в main.scss все chat компоненты:

// Chat компоненты
@import 'components/chat/message-inputs';
@import 'components/chat/chat-detail';
// ... все 10 компонентов

Шаг 4: Переместить spacing в utilities

mv scss/components/_spacing-utils.scss scss/utilities/
mv scss/components/_layout-spacing.scss scss/utilities/

Шаг 5: Обновить импорты в main.scss

// Utilities
@import 'utilities/layout-spacing';
@import 'utilities/spacing-utils';

Шаг 6: Пересобрать CSS

npm run build:app
npm run build:bootstrap

Шаг 7: Проверить размеры

ls -lh css/app.css css/bootstrap-custom.css

Ожидаемый результат:

  • app.css: увеличится на ~15-20 KB (добавятся chat компоненты)
  • bootstrap-custom.css: уменьшится на ~15-20 KB (удалятся дубли)

Шаг 8: Создать документацию

Создать scss/README.md с описанием архитектуры

Шаг 9: Тестирование

  1. Проверить главную страницу
  2. Проверить страницы с чатом
  3. Проверить все компоненты

📊 Ожидаемые улучшения

После рефакторинга:

До:

app.css: 95 KB (без chat, с дублями)
bootstrap-custom.css: 301 KB (с chat, с дублями)
Дублирование: ~15-20 KB

После:

app.css: ~110 KB (с chat, без дублей)
bootstrap-custom.css: ~280 KB (только Bootstrap, без дублей)
Дублирование: 0 KB
Экономия: ~6-7% от общего размера

Преимущества:

  • ✅ Нет дубликатов кода
  • ✅ Чистое разделение ответственности
  • ✅ Логичная структура
  • ✅ Легче поддерживать
  • ✅ Меньший итоговый размер

🎓 Best Practices нарушения

❌ Текущие нарушения:

  1. DRY (Don't Repeat Yourself) - дублирование 8 компонентов
  2. Separation of Concerns - chat компоненты в bootstrap файле
  3. Single Responsibility - custom-bootstrap делает слишком много
  4. Clear Architecture - utilities/ пуста, spacing в components/

✅ После рефакторинга:

  1. DRY - каждый компонент импортируется один раз
  2. Separation of Concerns - четкое разделение: Bootstrap отдельно, app отдельно
  3. Single Responsibility - каждый файл имеет одну четкую цель
  4. Clear Architecture - логичная структура папок

💡 Дополнительные рекомендации

1. Рассмотреть переход на @use/@forward

SCSS @import deprecated, современный подход:

@use 'abstracts/variables' as vars;
@use 'components/buttons';

2. Создать index.scss в папках

// components/chat/_index.scss
@forward 'message-inputs';
@forward 'chat-detail';
// ...

// Использование:
@import 'components/chat';  // импортирует все

3. Добавить linter

npm install -D stylelint stylelint-config-sass-guidelines

4. Создать style guide

Документировать:

  • Naming conventions
  • File organization
  • Import order
  • Variables usage

🏁 Заключение

Текущая архитектура: 7/10 - Хорошая база, но есть критические проблемы

Основные проблемы:

  1. Дублирование импортов (CRITICAL)
  2. Chat компоненты в bootstrap-custom (HIGH)
  3. Неиспользуемая utilities/ папка (MEDIUM)

Действия:

  1. Срочно устранить дублирование
  2. Переорганизовать структуру
  3. Создать документацию

После рефакторинга ожидается: 9/10 - Чистая, поддерживаемая архитектура

Дата: 15 января 2026
Статус: Требуется рефакторинг
Приоритет: HIGH