type: standard
title: "Масштабирование компонентов / Component Scale Standard"
status: active
version: 1.0.0
date: 2026-02-17
owner: architect

Масштабирование компонентов / Component Scale Standard

Проблема

Вопрос: "ты предлагаешь что бы все компоненты независом от размера были в систем? а когда мы сделаем ерп или мвс это где будет"

Ответ: Компоненты размещаются в разных папках платформы в зависимости от их масштаба.

Классификация по масштабу

4 категории размера

Категория	Размер	Характеристика	Примеры
Микрокомпонент	<1K строк	Атомарная функция	send_email, http_get, format_date
Компонент	1K-10K строк	Законченный модуль	scraper, pdf_generator, oauth_client
Подсистема	10K-100K строк	Группа модулей	PM Core, DMS, Scheduler
Система	>100K строк	Полноценное решение	ERP, CRM, E-commerce

Критерии помимо размера

Критерий	Микро	Компонент	Подсистема	Система
Независимость	✅ Да	✅ Да	⚠️ Частично	❌ Зависит от многого
API	Функция	Модуль	REST/GraphQL	Multi-API
Конфигурация	Параметры	Config file	Database	Admin panel
Документация	Docstring	README	Docs folder	Wiki/Portal
Тестирование	Unit tests	Unit+Integration	Full test suite	QA environment

Размещение в платформе

Правило размещения по масштабу

workspace/
├── system/                    ← L3-L4: Платформа
│   ├── core/                  ← Ядро (executor, scheduler)
│   ├── elements/              ← Микрокомпоненты (<1K)
│   ├── components/            ← Компоненты (1K-10K)
│   ├── services/              ← Подсистемы (10K-100K)
│   │   ├── pm/               ← PM Platform
│   │   ├── dms/              ← Document Management
│   │   └── analytics/        ← Analytics Engine
│   └── agents/                ← AI-агенты
│
├── library/                   ← L4: Переиспользуемые компоненты
│   ├── sandbox/              ← Экспериментальные
│   ├── beta/                 ← Тестируемые
│   └── stable/               ← Стабильные
│       ├── connectors/       ← API интеграции (компоненты)
│       └── services/         ← Сервисы (подсистемы)
│
├── solutions/                 ← L5: Системы (>100K)
│   ├── erp/                  ← ERP система
│   ├── crm/                  ← CRM система
│   ├── ecommerce/            ← E-commerce
│   └── wms/                  ← Warehouse Management
│
└── projects/                  ← L6: Бизнес-проекты
    └── org/{name}/           ← Конкретные внедрения

Детальное правило по папкам

system/elements/ — Микрокомпоненты

Размер: <1K строк
Тип: Атомарные функции, утилиты
Зависимости: Только stdlib или 1-2 базовые библиотеки

Примеры:

system/elements/
├── email/
│   ├── send.py              (100 строк)
│   └── validate.py          (50 строк)
├── http/
│   ├── get.py               (80 строк)
│   └── post.py              (90 строк)
└── date/
    └── format.py            (120 строк)

Когда использовать:
- Простая функция без состояния
- Не требует конфигурации
- Используется внутри других компонентов

system/components/ — Компоненты

Размер: 1K-10K строк
Тип: Законченные модули
Зависимости: elements + внешние библиотеки

Примеры:

system/components/
├── scraper/
│   ├── __init__.py          (200 строк)
│   ├── parser.py            (800 строк)
│   ├── storage.py           (500 строк)
│   └── tests/               (1K строк)
│   Total: ~2.5K строк
│
└── pdf_generator/
    ├── __init__.py          (300 строк)
    ├── template.py          (1.2K строк)
    ├── renderer.py          (900 строк)
    └── tests/               (800 строк)
    Total: ~3.2K строк

Когда использовать:
- Модуль с внутренним состоянием
- Требует config.yaml
- Имеет API (класс/функции)
- Используется в разных проектах

system/services/ — Подсистемы

Размер: 10K-100K строк
Тип: Группа взаимосвязанных компонентов
Зависимости: elements + components + БД

Примеры:

system/services/
├── pm/                       ← PM Platform
│   ├── core/                 (5K строк)
│   ├── dms/                  (8K строк)
│   ├── tasks/                (4K строк)
│   ├── workflow/             (6K строк)
│   ├── api/                  (3K строк)
│   ├── web/                  (10K строк)
│   └── tests/                (5K строк)
│   Total: ~41K строк
│
└── analytics/
    ├── collection/           (4K строк)
    ├── processing/           (8K строк)
    ├── visualization/        (12K строк)
    └── api/                  (6K строк)
    Total: ~30K строк

Когда использовать:
- Несколько взаимосвязанных модулей
- Собственная БД/схема
- REST API или веб-интерфейс
- Конфигурация через БД
- Используется как сервис

solutions/ — Системы

Размер: >100K строк
Тип: Полноценные решения
Зависимости: Всё + сторонние системы

Примеры:

solutions/
├── erp/                      ← ERP система
│   ├── finance/              (30K строк)
│   ├── hr/                   (25K строк)
│   ├── procurement/          (20K строк)
│   ├── inventory/            (35K строк)
│   ├── sales/                (28K строк)
│   ├── manufacturing/        (40K строк)
│   ├── admin/                (15K строк)
│   └── api/                  (10K строк)
│   Total: ~203K строк
│
└── crm/
    ├── contacts/             (15K строк)
    ├── deals/                (20K строк)
    ├── marketing/            (18K строк)
    ├── analytics/            (12K строк)
    └── admin/                (8K строк)
    Total: ~73K строк

Когда использовать:
- Полноценная система с UI
- Множество модулей
- Собственная инфраструктура
- Админ-панель
- Мультитенантность
- Внедряется на проекты

Миграция между уровнями

Когда переносить?

elements/ → components/
    Когда: >1K строк ИЛИ требуется конфигурация

components/ → services/
    Когда: >10K строк ИЛИ появилась БД + API

services/ → solutions/
    Когда: >100K строк ИЛИ полноценная система с UI

Пример эволюции

Этап 1: Микрокомпонент

# system/elements/email/send.py (100 строк)
def send_email(to, subject, body):
    """Отправить email через SMTP"""
    ...

Этап 2: Компонент

# system/components/email_client/ (~3K строк)
class EmailClient:
    """Email клиент с шаблонами и очередью"""
    def __init__(self, config):
        ...
    def send(self, template_id, data):
        ...

Этап 3: Подсистема

# system/services/messaging/ (~40K строк)
messaging/
├── email/           (10K)
├── sms/             (8K)
├── telegram/        (7K)
├── push/            (6K)
├── queue/           (5K)
└── admin/           (4K)

Этап 4: Система

# solutions/communication/ (~150K строк)
communication/
├── messaging/       (40K)
├── campaigns/       (30K)
├── analytics/       (25K)
├── contacts/        (20K)
├── templates/       (15K)
├── automation/      (12K)
└── admin/           (8K)

Примеры из PM анализа

MVP компоненты PM Platform (из PM-COMPONENTS-ANALYSIS.md)

Компонент	Масштаб	Размещение	Оценка строк
PM Core	Подсистема	system/services/pm/core/	~15K
— Project Lifecycle	Компонент	pm/core/lifecycle/	~3K
— Stage Gates	Компонент	pm/core/gates/	~2K
— Process Engine	Компонент	pm/core/engine/	~4K
— Status Tracking	Компонент	pm/core/status/	~2K
— Reporting	Компонент	pm/core/reports/	~4K
DMS	Подсистема	system/services/dms/	~12K
— Templates	Компонент	dms/templates/	~3K
— Assembly	Компонент	dms/assembly/	~4K
— Validation	Компонент	dms/validation/	~2K
— Storage	Компонент	dms/storage/	~3K
Tasks	Компонент	system/components/tasks/	~5K
— Task Manager	Модуль	tasks/manager.py	~2K
— Dependencies	Модуль	tasks/deps.py	~1.5K
— Scheduler	Модуль	tasks/schedule.py	~1.5K

Итого PM Platform: ~32K строк → Подсистема → system/services/pm/

Правила документации по масштабу

Масштаб	CLAUDE.md	index.yaml	README.md	Docs folder	Wiki
Микрокомпонент	✅ Обязательно	✅ Обязательно	❌ Не нужен	❌ Нет	❌ Нет
Компонент	✅ Обязательно	✅ Обязательно	✅ Обязательно	⚠️ Желательно	❌ Нет
Подсистема	✅ Обязательно	✅ Обязательно	✅ Обязательно	✅ Обязательно	⚠️ Желательно
Система	✅ Обязательно	✅ Обязательно	✅ Обязательно	✅ Обязательно	✅ Обязательно

Чеклист размещения нового компонента

При создании нового компонента пройти по чеклисту:

Шаг 1: Определить масштаб
- [ ] Оценить размер в строках кода
- [ ] Определить зависимости
- [ ] Проверить нужна ли БД
- [ ] Проверить нужен ли API

Шаг 2: Выбрать папку
- [ ] <1K + нет конфига → system/elements/
- [ ] 1K-10K + есть конфиг → system/components/
- [ ] 10K-100K + есть БД+API → system/services/
- [ ] >100K + полная система → solutions/

Шаг 3: Создать структуру
- [ ] CLAUDE.md (обязательно для всех)
- [ ] index.yaml (обязательно для всех)
- [ ] README.md (для компонента и выше)
- [ ] docs/ (для подсистемы и выше)
- [ ] tests/ (для всех)

Шаг 4: Зарегистрировать
- [ ] Добавить в architect/standards/COMPONENT_CATALOG.md
- [ ] Обновить зависимости в index.yaml

Исключения

library/ — особый случай

Назначение: Переиспользуемые компоненты в стадии разработки

library/
├── sandbox/         ← Эксперименты (любой размер)
├── beta/            ← Тестирование (любой размер)
└── stable/          ← Готовые (любой размер)
    ├── connectors/  ← API клиенты (обычно компоненты)
    └── services/    ← Готовые подсистемы

Правило: Из library/stable/ компонент может быть:
- Перенесен в system/ если стал частью платформы
- Перенесен в solutions/ если вырос в систему
- Остаться в library/stable/ если универсальный и переиспользуемый

Пример: OzonClient

library/stable/connectors/ozon/  (~4K строк)
→ Остаётся в library, т.к. переиспользуется в разных проектах

Пример: PM Platform

Начало: library/sandbox/pm/  (прототип)
→ library/beta/pm/  (тестирование)
→ system/services/pm/  (стал частью платформы)

Связи / References

[[PLATFORM_ARCHITECTURE]] — архитектура платформы (7 уровней)
[[PM-COMPONENTS-ANALYSIS]] — анализ компонентов PM
[[CODE_LIBRARY]] — работа с library/
[[COMPONENT_ARCHITECTURE]] — стандарт компонентов

Следующие шаги

Применить стандарт к существующим компонентам:
- Проверить system/scheduler/ (сейчас в system/, размер?)
- Проверить system/monitor/ (сейчас в system/, размер?)
- Создать system/services/pm/ по анализу
Создать COMPONENT_CATALOG.md:
- Реестр всех компонентов платформы
- Таблица: имя, масштаб, размещение, версия, статус
Реализовать PM MVP:
- system/services/pm/core/ (~15K)
- system/services/dms/ (~12K)
- system/components/tasks/ (~5K)

Версия: 1.0.0