architect/standards/1-structure/structure-solution.md

type: standard
aspect: structure
title: "Структура решения (Solution Structure)"
version: 1.0.0
date: 2026-02-19
status: active

Структура решения (Solution Structure)

Версия: 1.0.0
Дата: 2026-02-03
Статус: ОБЯЗАТЕЛЬНО

ПРИНЦИП

ОДНО РЕШЕНИЕ = УНИФИЦИРОВАННАЯ СТРУКТУРА
Независимо от платформы (CS-Cart, Drupal, Next.js)

Зачем: Единая структура для всех решений упрощает навигацию и понимание.

УНИВЕРСАЛЬНАЯ СТРУКТУРА

solution/                   ← SOLUTION (cscart, drupal, nextjs, ...)
├── index.py                ← индекс решения (компоненты, сайты, инфра)
├── CLAUDE.md               ← контекст решения
├── README.md               ← описание решения
│
├── app/                    ← дистрибутив платформы
├── themes/                 ← темы оформления
├── modules/                ← модули функционала
├── sites/                  ← установки/инстансы
├── infra/                  ← инфраструктура решения
└── lib/                    ← vendor (composer, npm)

Компоненты со стадиями

themes/ и modules/ всегда имеют стадии:

themes/                     modules/
├── lib/                    ├── lib/
├── dev/                    ├── dev/
├── test/                   ├── test/
├── prod/                   ├── prod/
└── archive/                └── archive/

См.: CODE_STAGES.md — подробно про стадии

КОМПОНЕНТЫ РЕШЕНИЯ

app/ — Дистрибутив платформы

Что: Исходный код платформы/движка (CS-Cart, Drupal, Next.js)

Примеры:

app/
└── 4.19.1/         ← CS-Cart 4.19.1
    ├── app/
    ├── js/
    ├── design/
    └── ...

Правила:
- ❌ НЕ модифицировать код платформы напрямую
- ✅ Модификации — через modules/ и themes/
- ✅ Версионирование: app/X.Y.Z/

Для разных платформ:

# CS-Cart
app/4.19.1/

# Drupal
app/10.2.0/

# Next.js (исходники приложения)
app/src/

themes/ — Темы оформления

Что: Визуальное оформление (CSS, шаблоны, дизайн)

Структура:

themes/
├── lib/                ← чужие темы (купленные, скачанные)
│   └── vendor-theme-v1.0.0/
├── dev/                ← наши в разработке
│   └── lideravto/
├── test/               ← на тестировании
│   └── lideravto-v1.0.0-rc1/
├── prod/               ← готовые
│   ├── lideravto-v1.0.0/
│   └── lideravto-v0.9.0/
└── archive/            ← устаревшие

Для разных платформ:

CS-Cart:

themes/dev/lideravto/
├── templates/
├── css/
├── styles.less
└── manifest.json

Drupal:

themes/dev/custom_theme/
├── templates/
├── css/
├── custom_theme.info.yml
└── custom_theme.theme

Next.js:

themes/dev/main/
├── components/
├── styles/
└── theme.config.ts

modules/ — Модули функционала

Что: Функциональные расширения (фичи, интеграции, бизнес-логика)

Структура:

modules/
├── lib/                ← чужие модули
├── dev/                ← наши в разработке
│   ├── lider_import/
│   └── lider_setup/
├── test/               ← на тестировании
├── prod/               ← готовые
│   └── lider_import-v2.0.0/
└── archive/            ← устаревшие

Для разных платформ:

CS-Cart:

modules/dev/lider_import/
├── addon.xml
├── func.php
├── init.php
└── schemas/

Drupal:

modules/dev/custom_import/
├── custom_import.info.yml
├── custom_import.module
└── src/

Next.js:

modules/dev/analytics/
├── package.json
├── src/
└── tests/

sites/ — Установки/инстансы

Что: Конкретные сайты/приложения (инстансы решения)

Примеры:

sites/
├── work.lideravto.ru/      ← dev окружение
└── lideravto.ru/           ← prod окружение

Что внутри:
- Конфигурация сайта
- База данных (путь/настройки)
- Активные темы/модули
- Загруженные файлы (медиа)

Для разных платформ:

CS-Cart (мультисайт):

sites/
├── work.lideravto.ru/
│   ├── config.local.php
│   ├── var/
│   └── images/
└── lideravto.ru/
    ├── config.local.php
    └── ...

Drupal:

sites/
├── dev.example.com/
│   ├── settings.php
│   └── files/
└── www.example.com/
    ├── settings.php
    └── files/

Next.js (env-based):

sites/
├── .env.development
└── .env.production

infra/ — Инфраструктура решения

Что: Конфигурация специфичная для решения (nginx, БД, cron, SSL)

Структура:

infra/
├── nginx/              ← nginx конфиги для сайтов
│   ├── work.lideravto.ru.conf
│   └── lideravto.ru.conf
├── db/                 ← схема БД, миграции
│   ├── dev/
│   ├── prod/
│   └── schema/
├── cron/               ← cron задачи
│   ├── dev.cron
│   └── prod.cron
├── ssl/                ← SSL сертификаты
│   └── lideravto.ru/
└── backup/             ← настройки бэкапа
    └── lideravto.ru/

Отличие от it/infra/:

Уровень Что Примеры
it/infra/ Общая инфраструктура Nginx server, PHP-FPM, MySQL server, Домены
solution/infra/ Специфичная для решения Vhost конфиги, схема БД решения, cron сайтов

Для разных платформ:

CS-Cart:

infra/nginx/lideravto.ru.conf:
server {
    server_name lideravto.ru;
    root /var/www/cscart/sites/lideravto.ru;
    # CS-Cart специфичные настройки
}

Drupal:

infra/nginx/example.com.conf:
server {
    server_name example.com;
    root /var/www/drupal/sites/example.com;
    # Drupal специфичные настройки
}

lib/ — Vendor библиотеки

Что: Внешние библиотеки (composer, npm, bower)

Структура:

lib/
├── composer/           ← PHP зависимости
│   └── vendor/
├── node_modules/       ← NPM зависимости
└── vendor-modules/     ← модули не через пакетный менеджер

Правила:
- Управляется пакетными менеджерами (composer.json, package.json)
- В .gitignore (не коммитим vendor/)
- Восстанавливается через composer install, npm install

ПРИМЕРЫ ДЛЯ ПЛАТФОРМ

CS-Cart

cscart/
├── index.py
├── CLAUDE.md
├── README.md
│
├── app/
│   └── 4.19.1/                 ← дистрибутив CS-Cart
│
├── themes/
│   ├── lib/                    ← купленные темы
│   ├── dev/
│   │   └── lideravto/          ← наша тема в разработке
│   ├── test/
│   ├── prod/
│   │   └── lideravto-v1.0.0/   ← готовая тема
│   └── archive/
│
├── modules/
│   ├── lib/                    ← купленные модули
│   ├── dev/
│   │   ├── lider_import/       ← импорт BAZON
│   │   └── lider_setup/        ← настройка
│   ├── test/
│   ├── prod/
│   │   └── lider_import-v2.0.0/
│   └── archive/
│
├── sites/
│   ├── work.lideravto.ru/      ← dev
│   │   ├── config.local.php
│   │   └── var/
│   └── lideravto.ru/           ← prod
│       └── config.local.php
│
├── infra/
│   ├── nginx/
│   │   ├── work.lideravto.ru.conf
│   │   └── lideravto.ru.conf
│   ├── db/
│   │   ├── dev/
│   │   └── prod/
│   ├── cron/
│   └── ssl/
│
└── lib/
    └── composer/
        └── vendor/

Drupal

drupal/
├── index.py
├── CLAUDE.md
│
├── app/
│   └── 10.2.0/                 ← Drupal core
│
├── themes/
│   ├── lib/
│   ├── dev/
│   │   └── custom_theme/
│   ├── test/
│   ├── prod/
│   └── archive/
│
├── modules/
│   ├── lib/                    ← contrib модули
│   │   ├── views/
│   │   └── pathauto/
│   ├── dev/
│   │   └── custom_import/      ← наш модуль
│   ├── test/
│   ├── prod/
│   └── archive/
│
├── sites/
│   ├── dev.example.com/
│   │   ├── settings.php
│   │   └── files/
│   └── www.example.com/
│       ├── settings.php
│       └── files/
│
├── infra/
│   ├── nginx/
│   ├── db/
│   └── drush/                  ← Drush скрипты
│
└── lib/
    └── composer/

Next.js

nextjs/
├── index.py
├── CLAUDE.md
│
├── app/
│   └── src/                    ← исходники приложения
│       ├── app/
│       ├── components/
│       └── lib/
│
├── themes/
│   ├── lib/
│   ├── dev/
│   │   └── main/
│   │       ├── components/
│   │       └── styles/
│   ├── test/
│   ├── prod/
│   └── archive/
│
├── modules/
│   ├── lib/
│   ├── dev/
│   │   ├── analytics/
│   │   └── auth/
│   ├── test/
│   ├── prod/
│   └── archive/
│
├── sites/                      ← deployments
│   ├── dev.example.com/
│   │   └── .env.local
│   └── example.com/
│       └── .env.production
│
├── infra/
│   ├── nginx/
│   ├── docker/
│   │   └── docker-compose.yml
│   └── vercel/
│       └── vercel.json
│
└── lib/
    └── node_modules/

ПРАВИЛА

Обязательно

  1. Структура едина для всех решений (CS-Cart, Drupal, Next.js)
  2. Стадии обязательны в themes/ и modules/ (lib/dev/test/prod/archive)
  3. index.py обязателен (связывает компоненты, сайты, инфру)
  4. infra/ специфична для решения (НЕ дублирует it/infra/)

Необязательно

Запрещено

НАВИГАЦИЯ

Как найти компонент?

# Все темы
ls themes/*/

# Темы в разработке
ls themes/dev/

# Готовые темы
ls themes/prod/

# Все модули
ls modules/*/

# Модули в разработке
ls modules/dev/

Как найти сайт?

# Все сайты
ls sites/

# Dev сайт
ls sites/work.*/

# Prod сайт
ls sites/*.ru/

Как найти инфру сайта?

# Nginx конфиг
cat infra/nginx/lideravto.ru.conf

# БД конфиг
cat infra/db/prod/config.cnf

# Cron задачи
cat infra/cron/prod.cron

СВЯЗЬ С index.py

index.py связывает всё:

INDEX = {
    "app": {"version": "4.19.1", "path": "app/4.19.1/"},

    "sites": {
        "lideravto.ru": {
            "env": "prod",
            "path": "sites/lideravto.ru/",
            "infra": {
                "nginx": "infra/nginx/lideravto.ru.conf",
                "db": "infra/db/prod/"
            },
            "components": {
                "themes": ["prod/lideravto-v1.0.0"],
                "modules": ["prod/lider_import-v2.0.0"]
            }
        }
    },

    "components": {
        "themes": {"dev": [...], "prod": [...]},
        "modules": {"dev": [...], "prod": [...]}
    }
}

См.: INDEX_PY.md — формат index.py

МИГРАЦИЯ

Из старой структуры

Было:

project/
├── modules/
│   ├── module1/
│   └── module2/
└── themes/
    └── theme1/

Стало:

project/
├── index.py
├── app/
├── themes/
│   ├── lib/
│   ├── dev/
│   │   └── theme1/         ← переместили
│   ├── test/
│   ├── prod/
│   └── archive/
├── modules/
│   ├── lib/
│   ├── dev/
│   │   ├── module1/        ← переместили
│   │   └── module2/
│   ├── test/
│   ├── prod/
│   └── archive/
├── sites/
├── infra/
└── lib/

Шаги:
1. Создать структуру (app/, themes/, modules/, sites/, infra/, lib/)
2. Создать стадии в themes/ и modules/
3. Переместить существующие компоненты в dev/
4. Создать index.py
5. Обновить документацию (CLAUDE.md, README.md)

ПРОВЕРКА

Чеклист структуры

Обязательные элементы:
- [ ] index.py существует
- [ ] CLAUDE.md актуален
- [ ] themes/ имеет стадии (lib/dev/test/prod/archive)
- [ ] modules/ имеет стадии (lib/dev/test/prod/archive)
- [ ] infra/ содержит конфиги решения (nginx, db, cron)

Опциональные:
- [ ] app/ содержит дистрибутив платформы
- [ ] sites/ содержит инстансы
- [ ] lib/ содержит vendor

Запрещено:
- [ ] ❌ Модифицированный код в app/
- [ ] ❌ lib/vendor в git
- [ ] ❌ Смешение компонентов разных стадий в одной папке

ССЫЛКИ

Версия: 1.0.0
Дата: 2026-02-03