architect/standards/5-format/format-index-py.md

type: standard
aspect: format
title: "Индекс решения (index.py)"
version: 1.0.0
date: 2026-02-19
status: active

Индекс решения (index.py)

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

ПРИНЦИП

ОДИН ФАЙЛ = ВСЯ ИНФОРМАЦИЯ О РЕШЕНИИ
Компоненты + Сайты + Инфраструктура + Зависимости

Зачем: index.py — единая точка для понимания структуры решения.

ЧТО ТАКОЕ index.py

index.py — Python файл с структурированными данными о решении:
- Зависимости (dependencies)
- Компоненты (themes, modules)
- Сайты (sites)
- Инфраструктура (infra)
- Метаданные (meta)

Формат: Python dictionary (не YAML!)

Преимущества:
- ✅ Наследование через Python import
- ✅ Автоматический merge данных
- ✅ Читается и людьми, и Claude
- ✅ Можно валидировать (Pydantic)

БАЗОВАЯ СТРУКТУРА

"""
Описание решения
"""

INDEX = {
    "level": "solution",      # уровень (solution/direction/it)
    "type": "SOLUTION",       # тип
    "name": "cscart",         # имя решения
    "path": "it/web/cscart/", # путь

    "dependencies": {...},    # зависимости
    "app": {...},             # дистрибутив
    "sites": {...},           # сайты
    "components": {...},      # компоненты (themes, modules)
    "infra": {...},           # инфраструктура
    "lib": {...},             # vendor
    "structure": [...],       # структура папок
    "meta": {...}             # метаданные
}

КАСКАДНОЕ НАСЛЕДОВАНИЕ

Концепция

Каждый уровень наследует от родителя:

it/index.py              ← L1: базовые зависимости
  └── web/index.py       ← L2: наследует L1 + свои
      └── cscart/index.py ← L3: наследует L1+L2 + свои

Пример

Уровень 1: it/index.py

"""Индекс IT направления"""

INDEX = {
    "level": "it",
    "type": "TYPE",
    "path": "it/",

    "dependencies": {
        "system": {
            "php": "8.1+",
            "nginx": "1.20+",
            "mysql": "8.0+"
        }
    },

    "infra": {
        "path": "it/infra/",
        "server": "it/infra/server/",
        "domains": "it/infra/domains/"
    }
}

Уровень 2: it/web/index.py

"""Индекс WEB направления"""

import sys
from pathlib import Path

# Импорт родителя
sys.path.insert(0, str(Path(__file__).parent.parent))
from index import INDEX as PARENT

# Наследование
INDEX = {
    **PARENT,  # клон всего от родителя

    "level": "direction",
    "name": "web",
    "path": "it/web/",

    # Наследуем dependencies + добавляем свои
    "dependencies": {
        **PARENT["dependencies"],
        "web": {
            "nodejs": "18+",
            "npm": "9+"
        }
    }
}

Результат в web/index.py:

{
    "dependencies": {
        "system": {         # from it/
            "php": "8.1+",
            "mysql": "8.0+"
        },
        "web": {            # own
            "nodejs": "18+"
        }
    }
}

Уровень 3: it/web/cscart/index.py

"""Индекс CS-Cart решения"""

import sys
from pathlib import Path

# Импорт родителя
sys.path.insert(0, str(Path(__file__).parent.parent))
from index import INDEX as PARENT

INDEX = {
    **PARENT,

    "level": "solution",
    "name": "cscart",
    "path": "it/web/cscart/",

    # Наследуем dependencies (уже содержит system + web)
    "dependencies": {
        **PARENT.get("dependencies", {}),
        "platform": {
            "cscart": "4.19.1"
        }
    },

    "sites": {
        "lideravto.ru": {
            "env": "prod",
            "url": "https://lideravto.ru"
        }
    }
}

Результат в cscart/index.py:

{
    "dependencies": {
        "system": {...},    # from it/
        "web": {...},       # from web/
        "platform": {...}   # own
    },
    "sites": {...}          # own
}

БЛОКИ ДАННЫХ

metadata

Что: Метаданные уровня

{
    "level": "solution",        # solution/direction/it
    "type": "SOLUTION",         # SOLUTION/DIRECTION/TYPE
    "name": "cscart",           # имя решения
    "path": "it/web/cscart/",   # путь
    "project": "lideravto"      # проект (опционально)
}

dependencies

Что: Зависимости (наследуются каскадно)

{
    "dependencies": {
        "system": {             # системные (from it/)
            "php": "8.1+",
            "nginx": "1.20+",
            "mysql": "8.0+",
            "redis": "6.0+"
        },
        "web": {                # веб (from web/)
            "nodejs": "18+",
            "npm": "9+"
        },
        "platform": {           # платформа (own)
            "cscart": "4.19.1",
            "mysql_extensions": ["mysqli", "pdo_mysql"],
            "php_extensions": ["gd", "mbstring", "zip"]
        }
    }
}

Как читать:
- system — от it/index.py
- web — от web/index.py
- platform — от cscart/index.py

app

Что: Дистрибутив платформы

{
    "app": {
        "version": "4.19.1",
        "path": "app/4.19.1/",
        "source": "https://www.cs-cart.com/"
    }
}

sites

Что: Установки сайтов/инстансы

{
    "sites": {
        "work.lideravto.ru": {
            "env": "dev",
            "url": "https://work.lideravto.ru",
            "path": "sites/work.lideravto.ru/",
            "status": "active",

            "infra": {
                "nginx": "infra/nginx/work.lideravto.ru.conf",
                "db": "infra/db/dev/",
                "db_name": "lideravto_dev",
                "cron": "infra/cron/dev.cron"
            },

            "components": {
                "themes": ["dev/lideravto"],
                "modules": ["dev/lider_import", "dev/lider_setup"]
            }
        },

        "lideravto.ru": {
            "env": "prod",
            "url": "https://lideravto.ru",
            "path": "sites/lideravto.ru/",
            "status": "active",

            "infra": {
                "nginx": "infra/nginx/lideravto.ru.conf",
                "db": "infra/db/prod/",
                "db_name": "lideravto_prod",
                "cron": "infra/cron/prod.cron",
                "ssl": "infra/ssl/lideravto.ru/",
                "backup": "infra/backup/lideravto.ru/"
            },

            "components": {
                "themes": ["prod/lideravto-v1.0.0"],
                "modules": ["prod/lider_import-v2.0.0"]
            }
        }
    }
}

Связь: Сайт → инфра → компоненты

components

Что: Компоненты решения (темы, модули)

{
    "components": {
        "themes": {
            "lib": [],      # чужие
            "dev": [        # в разработке
                {
                    "name": "lideravto",
                    "version": "1.0.0-dev",
                    "status": "active",
                    "path": "themes/dev/lideravto/"
                }
            ],
            "test": [],     # на тестировании
            "prod": [       # готовые
                {
                    "name": "lideravto",
                    "version": "1.0.0",
                    "status": "stable",
                    "path": "themes/prod/lideravto-v1.0.0/"
                }
            ],
            "archive": []   # устаревшие
        },

        "modules": {
            "lib": [],
            "dev": [
                {
                    "name": "lider_import",
                    "version": "2.0.0-dev",
                    "status": "active",
                    "path": "modules/dev/lider_import/",
                    "description": "Импорт товаров из BAZON"
                },
                {
                    "name": "lider_setup",
                    "version": "1.0.0-dev",
                    "status": "active",
                    "path": "modules/dev/lider_setup/"
                }
            ],
            "test": [],
            "prod": [
                {
                    "name": "lider_import",
                    "version": "2.0.0",
                    "status": "stable",
                    "path": "modules/prod/lider_import-v2.0.0/"
                }
            ],
            "archive": []
        }
    }
}

Стадии: lib/dev/test/prod/archive (см. CODE_STAGES.md)

infra

Что: Инфраструктура решения

{
    "infra": {
        "path": "infra/",

        "nginx": {
            "path": "infra/nginx/",
            "configs": [
                "work.lideravto.ru.conf",
                "lideravto.ru.conf"
            ]
        },

        "db": {
            "path": "infra/db/",
            "environments": ["dev", "prod"],
            "schema": "infra/db/schema/"
        },

        "cron": {
            "path": "infra/cron/",
            "jobs": ["dev.cron", "prod.cron"]
        },

        "ssl": {
            "path": "infra/ssl/",
            "sites": ["lideravto.ru"]
        },

        "backup": {
            "path": "infra/backup/",
            "sites": ["lideravto.ru"]
        }
    }
}

lib

Что: Vendor библиотеки

{
    "lib": {
        "path": "lib/",
        "composer": "lib/composer/",
        "vendor_modules": "lib/vendor-modules/"
    }
}

structure

Что: Структура решения (список папок)

{
    "structure": [
        "app",       # дистрибутив
        "themes",    # темы (lib/dev/test/prod/archive)
        "modules",   # модули (lib/dev/test/prod/archive)
        "sites",     # установки
        "infra",     # инфраструктура
        "lib"        # vendor
    ]
}

meta

Что: Метаданные (версия, история)

{
    "meta": {
        "version": "1.0.0",
        "created": "2026-02-03",
        "updated": "2026-02-03",
        "migration": "ORG structure + stages (2026-02-03)"
    }
}

ИСПОЛЬЗОВАНИЕ

Чтение index.py

Python:

from it.web.cscart.index import INDEX

# Получить зависимости (все: system + web + platform)
deps = INDEX["dependencies"]

# Получить информацию о сайте
site = INDEX["sites"]["lideravto.ru"]
print(site["url"])  # https://lideravto.ru
print(site["infra"]["nginx"])  # infra/nginx/lideravto.ru.conf

# Получить компоненты
modules_dev = INDEX["components"]["modules"]["dev"]
for module in modules_dev:
    print(f"{module['name']} {module['version']}")

Claude (в промпте):

# Claude автоматически читает index.py для понимания структуры
# Пример: "Какие модули в разработке?"
# Claude: читает INDEX["components"]["modules"]["dev"]

ШАБЛОНЫ

Минимальный index.py

"""Индекс решения"""

INDEX = {
    "level": "solution",
    "type": "SOLUTION",
    "name": "my-solution",
    "path": "it/web/my-solution/",

    "structure": [
        "app",
        "themes",
        "modules",
        "sites",
        "infra",
        "lib"
    ],

    "meta": {
        "version": "1.0.0",
        "created": "2026-02-03"
    }
}

С наследованием

"""Индекс решения с наследованием"""

import sys
from pathlib import Path

# Импорт родителя
sys.path.insert(0, str(Path(__file__).parent.parent))
from index import INDEX as PARENT

INDEX = {
    **PARENT,  # наследуем всё

    "level": "solution",
    "name": "my-solution",

    # Наследуем dependencies + добавляем свои
    "dependencies": {
        **PARENT.get("dependencies", {}),
        "platform": {
            "my-platform": "1.0.0"
        }
    }
}

ПРАВИЛА

Обязательно

  1. Файл называется index.py (не INDEX.py, не config.py)
  2. Переменная INDEX (не CONFIG, не DATA)
  3. Python dict (не YAML, не JSON)
  4. Docstring в начале (описание решения)

Наследование

  1. import from index (не from parent, не from ../index)
  2. PARENT переменная для родительского индекса
  3. **PARENT для клонирования (не manual copy)
  4. .get("dependencies", {}) для безопасного доступа

Структура данных

  1. dependencies каскадно (system → web → platform)
  2. sites с инфрой (nginx, db, cron)
  3. components со стадиями (lib/dev/test/prod/archive)
  4. meta с версией (version, created, updated)

Запрещено

ПРОВЕРКА

Чеклист index.py

Обязательные поля:
- [ ] level определён (solution/direction/it)
- [ ] type определён (SOLUTION/DIRECTION/TYPE)
- [ ] name определён
- [ ] path определён

Наследование:
- [ ] Родитель импортирован (from index import INDEX as PARENT)
- [ ] Данные клонированы (**PARENT)
- [ ] dependencies merged (**PARENT.get("dependencies", {}))

Компоненты:
- [ ] components.themes имеет стадии (lib/dev/test/prod/archive)
- [ ] components.modules имеет стадии
- [ ] Каждый компонент имеет: name, version, status, path

Сайты:
- [ ] Каждый сайт имеет: env, url, path
- [ ] Каждый сайт имеет infra (nginx, db)
- [ ] Каждый сайт имеет components (themes, modules)

ПРИМЕРЫ

Полный пример (CS-Cart)

См. $WORKSPACE/projects/org/lideravto/it/web/cscart/index.py

Полный пример (Drupal)

"""Индекс Drupal решения"""

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent.parent))
from index import INDEX as PARENT

INDEX = {
    **PARENT,

    "level": "solution",
    "name": "drupal",
    "path": "it/web/drupal/",

    "dependencies": {
        **PARENT.get("dependencies", {}),
        "platform": {
            "drupal": "10.2.0",
            "drush": "12.0+"
        }
    },

    "app": {
        "version": "10.2.0",
        "path": "app/10.2.0/"
    },

    "sites": {
        "dev.example.com": {
            "env": "dev",
            "url": "https://dev.example.com",
            "path": "sites/dev.example.com/",
            "infra": {
                "nginx": "infra/nginx/dev.example.com.conf",
                "db": "infra/db/dev/"
            }
        }
    },

    "components": {
        "themes": {
            "lib": [{"name": "bootstrap", "version": "5.3.0"}],
            "dev": [{"name": "custom_theme", "version": "1.0.0-dev"}],
            "test": [],
            "prod": [],
            "archive": []
        },
        "modules": {
            "lib": [
                {"name": "views", "version": "10.2.0"},
                {"name": "pathauto", "version": "1.12.0"}
            ],
            "dev": [{"name": "custom_import", "version": "1.0.0-dev"}],
            "test": [],
            "prod": [],
            "archive": []
        }
    }
}

МИГРАЦИЯ

Из CACHE.yaml → index.py

Было (CACHE.yaml):

dependencies:
  php: 8.1+
  cscart: 4.19.1

modules:
  - lider_import
  - lider_setup

Стало (index.py):

INDEX = {
    "dependencies": {
        "system": {"php": "8.1+"},
        "platform": {"cscart": "4.19.1"}
    },
    "components": {
        "modules": {
            "dev": [
                {"name": "lider_import", "version": "2.0.0-dev"},
                {"name": "lider_setup", "version": "1.0.0-dev"}
            ]
        }
    }
}

Преимущества:
- ✅ Наследование (CACHE.yaml не наследовался)
- ✅ Структурированные данные
- ✅ Python типизация (можно валидировать)

ССЫЛКИ

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