# Документация KORZILLA X

Мультисайтовая CMS на Laravel 13 + MySQL 8. Одна установка обслуживает
300–500 сайтов: общий код, общая база, разделение по `site_id`.

Документация разбита по логическим узлам — каждый файл описывает одну
подсистему: что она делает, почему устроена именно так и где у неё острые углы.

## С чего начать

| Если вам нужно | Читайте |
|---|---|
| Понять устройство системы целиком | [architecture.md](architecture.md) |
| Развернуть проект и начать писать код | [development.md](development.md) |
| Добавить новый модуль или компонент | [modules.md](modules.md), [components.md](components.md) |
| Разобраться, почему запрос попал не на тот сайт | [multitenancy.md](multitenancy.md) |
| Понять, почему страница отдаёт 301 или 404 | [structure.md](structure.md) |
| Настроить зоны и блоки, разобраться с видимостью | [layout.md](layout.md) |
| Добавить настройку в админку | [settings.md](settings.md) |
| Разобраться с экранами админки | [admin.md](admin.md) |
| Понять устройство каталога и фильтров | [catalog.md](catalog.md) |
| Разобраться со входом покупателей | [auth.md](auth.md) |
| Понять устройство корзины и кнопок покупки | [shop.md](shop.md) |
| Разобраться с импортом из 1С | [import.md](import.md) |
| Понять, почему поиск медленный | [search.md](search.md) |
| Настроить заголовки и мета-теги | [seo.md](seo.md) |
| Разобраться с формами и заявками | [forms.md](forms.md) |
| Подключить мобильное приложение | [api.md](api.md) |
| Завести сайт на установке | [platform.md](platform.md) |
| Разобраться с городами и геотаргетингом | [geo.md](geo.md) |
| Выгрузить сайт в автономную копию | [export.md](export.md) |
| Выкатить обновление, наладить бэкапы и мониторинг | [operations.md](operations.md) |
| Понять, почему изменение не видно на сайте | [cache.md](cache.md) |
| Посмотреть схему базы | [database.md](database.md) |
| Узнать, что уже готово и что дальше | [roadmap.md](roadmap.md) |

## Узлы системы

### Инфраструктура

- **[architecture.md](architecture.md)** — общая картина, слои, инварианты,
  архитектурные гейты. Начинать отсюда.
- **[modules.md](modules.md)** — модульная система: манифест, реестр,
  порядок загрузки, генератор, точки расширения.
- **[development.md](development.md)** — окружение, команды, соглашения,
  подводные камни инструментов.
- **[operations.md](operations.md)** — эксплуатация установки: деплой, очереди,
  бэкапы, мониторинг `/health`, что делать при инцидентах.

### Ядро платформы

- **[multitenancy.md](multitenancy.md)** — сайты, домены, резолв хоста,
  канонизация адреса, контекст арендатора, изоляция данных.
- **[cache.md](cache.md)** — кэш на счётчиках версий, почему не теги,
  что и как инвалидируется.
- **[settings.md](settings.md)** — типизированные настройки, декларативные
  схемы, условия видимости без `eval`, шифрование секретов.

### Контент

- **[structure.md](structure.md)** — дерево разделов, материализованные пути,
  переименование с авто-301, редиректы, резолв URL.
- **[components.md](components.md)** — компоненты («инфоблоки»), типы полей,
  шаблоны компонентов и их контексты.
- **[layout.md](layout.md)** — зоны, блоки, правила видимости,
  24-колоночная сетка на CSS Grid.
- **[catalog.md](catalog.md)** — товары, характеристики, цены по городам
  и группам, фасетный поиск и его производительность.
- **[auth.md](auth.md)** — покупатели сайта: вход по звонку, телефоны,
  внешние удостоверения, изоляция учётных записей по сайтам.
- **[shop.md](shop.md)** — корзина гостя и покупателя, режимы покупки товара,
  почему каталог работает без магазина.
- **[import.md](import.md)** — конвейер CommerceML 2: склад, слияние одним
  запросом, зачистка, возобновление после обрыва.
- **[search.md](search.md)** — общий индекс, ngram-ловушки и предел, за которым
  нужен другой движок.
- **[seo.md](seo.md)** — шаблоны заголовков с наследованием вверх по дереву,
  подстановки с падежами города, что печатает платформа, а не тема.
- **[forms.md](forms.md)** — формы из админки, защита от ботов без капчи,
  почему заявка переживает форму.
- **[api.md](api.md)** — JSON API v1: токен с меткой сайта, гвард по умолчанию,
  почему сессия сайта к API отношения не имеет.
- **[platform.md](platform.md)** — супер-админ на своём домене, почему его
  учётки не персайтовые, создание сайта.
- **[geo.md](geo.md)** — справочник городов РФ и города сайта: что из них
  чем является и почему одно не заменяет другое.
- **[export.md](export.md)** — выгрузка сайта в автономную копию: дамп
  на одной транзакции, что не уезжает клиенту и почему.

### Интерфейс

- **[admin.md](admin.md)** — админка на Vue 3 + Inertia: вход, левое меню,
  универсальный рендерер форм настроек, дерево разделов, карта зон и блоков,
  медиатека.

### Справочники

- **[database.md](database.md)** — все таблицы, ключевые индексы и почему
  они именно такие.
- **[roadmap.md](roadmap.md)** — этапы M0–M11, готовность, что отложено.
- **[gap-analysis.md](gap-analysis.md)** — сверка с ТЗ и легаси: каких полей,
  компонентов и функций ещё нет, в каком порядке их делать и что спросить
  у владельца.

## Что важно знать до чтения кода

Система переписывается с нуля; предыдущая версия (`D:\laragon\www\kzla`)
работает и переносу не подлежит — новые сайты создаются здесь, старые остаются
там. Поэтому в комментариях и документации часто встречаются ссылки на легаси:
это не ностальгия, а фиксация причины, по которой решение принято именно такое.
Почти каждое нетривиальное место здесь существует потому, что в предыдущей
версии оно было сделано иначе и это привело к конкретной проблеме.

Три инварианта нарушать нельзя ни при каких обстоятельствах —
они описаны в [architecture.md](architecture.md#инварианты).