# Передача проекта

Вход для того, кто принимает KORZILLA X: где проект, в каком он состоянии,
как поднять, как выкатить и какие долги за ним числятся.

Всё остальное — в [README.md](README.md): документация разбита по узлам,
и каждый файл объясняет не только «как сделано», но и «почему именно так»,
обычно со ссылкой на проблему легаси, из-за которой решение принято.

## Состояние на 12 октября 2026

| | |
|---|---|
| Репозиторий | `git@github.com:korzilla-ru/korzillaX.git`, ветка `main`, всё запушено |
| Этапы | M0 — M10 собраны, идёт M11 «первый живой сайт» ([roadmap.md](roadmap.md)) |
| Стенд | http://test.krzx.ru, хост платформы — `krzx.ru` |
| Боевой сервер | **нет**, и это главное, во что упирается M11 |
| Гейты | зелёные: deptrac — 0 нарушений и 0 непокрытых, pint чисто, 851 PHP-тест, 78 JS-тестов |

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

## Порядок чтения

| Сначала | Файл | Что даёт |
|---|---|---|
| 1 | [architecture.md](architecture.md) | слои, точки расширения и **три инварианта**, которые нельзя нарушать |
| 2 | [development.md](development.md) | окружение, команды, гейты, подводные камни инструментов |
| 3 | [roadmap.md](roadmap.md) | что сделано в каждом этапе, что отложено сознательно, таблица долга |
| 4 | [gap-analysis.md](gap-analysis.md) | сверка с ТЗ и легаси: чего не хватает компонентам, порядок работ, ответы владельца |
| 5 | этот файл | долги, доступы, стенд |

Дальше — по узлу, с которым предстоит работать: таблица в начале
[README.md](README.md) отвечает на вопрос «мне нужно X — куда смотреть».

## Доступы, которые нужно получить у владельца

- **GitHub** — `korzilla-ru/korzillaX`.
- **Сервер стенда** — `root@201.51.7.92`; проект лежит
  в `/home/korzillax/web/krzx.ru/private/korzillax` и работает от пользователя
  `korzillax`.
- **Админка стенда** — учётная запись владельца сайта `test`. Общего пароля
  платформы в системе нет вообще: он открывал бы админку любого сайта
  установки ([admin.md](admin.md#вход)).
- **Супер-админ платформы** (`krzx.ru`) — отдельная учётка, заводится консолью.
- **Ключи интеграций** (ЮKassa, дозвон, SMTP) лежат в настройках сайта
  и зашифрованы `APP_KEY`; при переезде на другой сервер вводятся заново.

## Локально

Подробно — [development.md](development.md#первый-запуск). Коротко:

```bash
composer install && npm ci
cp .env.example .env && php artisan key:generate
php artisan migrate && php artisan db:seed --class=DemoSitesSeeder
php artisan module:discover
php artisan serve --host=127.0.0.1 --port=8123
```

Админка живёт на `/admin` домена сайта; как добавить сайту домен `localhost`
и завести владельца — там же. Перед коммитом — `composer gate`
(deptrac + pint + phpunit + vitest), все четыре обязаны быть зелёными.

## Стенд test.krzx.ru

Один сайт (`test`), на нём и проверяются доработки.

```bash
# выкат: тянет main, ставит зависимости только если менялся composer.lock,
# пересобирает кэш модулей, гонит миграции, чистит кэши
ssh root@201.51.7.92 "runuser -u korzillax -- /home/korzillax/web/krzx.ru/private/korzillax/deploy.sh"

# бандл админки скрипт НЕ собирает — он уезжает готовым
scp -r public/build/* root@201.51.7.92:/home/korzillax/web/krzx.ru/private/korzillax/public/build/
ssh root@201.51.7.92 "chown -R korzillax:korzillax /home/korzillax/web/krzx.ru/private/korzillax/public/build"
```

Копия скрипта — [deploy/stand.sh](../deploy/stand.sh); на сервере он лежит
в корне проекта. Node на стенде есть (v22), так что сборку бандла можно
перенести в скрипт — просто руки не дошли.

- `APP_ENV=production`, `APP_DEBUG=false`, `KZ_MODE=platform`,
  `KZ_PLATFORM_HOST=krzx.ru`.
- MySQL 8.4 на порту 3307 (панель хостинга рядом держит свою MariaDB —
  не перепутайте), кэш файловый, очередь в базе, Redis нет.
- Разовый скрипт удобно гонять так; без `< /dev/null` tinker ждёт ввода
  и висит до таймаута:

```bash
scp script.php root@201.51.7.92:/tmp/ && ssh root@201.51.7.92 \
  "cd /home/korzillax/web/krzx.ru/private/korzillax && timeout 90 runuser -u korzillax -- php artisan tinker /tmp/script.php < /dev/null"
```

- Журнал — `storage/logs/laravel.log`. По нему находились ошибки, которых
  не видел ни один тест: 500 на хосте платформы от ботов и «контекст сайта
  не установлен» ([platform.md](platform.md#отдельный-домен)).

## Долги

### 1. Площадка — то, во что упирается M11

| Что | Подробности |
|---|---|
| Боевого сервера нет | нагрузочный тест, ротация журналов, проверка бэкапов восстановлением ждут площадку ([operations.md](operations.md#чего-в-регламенте-ещё-нет)) |
| Гейт M10 не закрыт до конца | выгруженный сайт поднят локально и прошёл смоук-набор; остаётся прогон на обычном php/mysql-хостинге клиента ([export.md](export.md)) |
| `predis` вместо `phpredis` | в сборке PHP нет расширения; на продакшене переключается одной строкой `.env` |
| Админка на домене сайта | XSS на домене дёргает `/admin` тем же источником; кука своя, хост общий. `KZ_ADMIN_HOST` в конфиге зарезервирован, развязка не сделана |
| Двухфакторной аутентификации платформы нет | пароль супер-админа открывает доступ ко всем сайтам установки |
| Журнала действий супер-админа нет | создание сайтов и правка персайтового кода не записываются |

### 2. Стенд — найдено при передаче

| Что | Чем грозит |
|---|---|
| Нет `cron` с `schedule:run` | сторож импорта (`catalog:import-watchdog`) не работает: умерший прогон запрёт обмен с 1С навсегда ([import.md](import.md#сторож)) |
| Нет воркера очереди | разбор пакета 1С и прочее из очереди просто не выполнится; сейчас в `jobs` пусто, и только поэтому не болит |
| Журнал 22 МБ без ротации | растёт с августа |
| Бэкапов нет | содержимое стенда одноразовое, но знать об этом лучше заранее |

Готовые куски конфигурации (supervisor, cron) — в
[operations.md](operations.md#очереди-и-расписание).

### 3. Функциональные

| Что | Где | Когда |
|---|---|---|
| Поиск не держит сотню тысяч документов | ngram + булев режим: два слова — 41 с. **Гейт M7 не пройден** | Meilisearch за интерфейсом `SearchEngine`, отложен решением владельца ([search.md](search.md)) |
| Социальные сети | последний невыполненный пункт шага 2 из [gap-analysis.md](gap-analysis.md#7-предлагаемый-порядок-работ) | ближайшее |
| Экрана городов сайта нет | справочник городов РФ есть, не хватает экрана выбора ([geo.md](geo.md)) | ближайшее |
| Долги компонентов | поля новостей, контактов, сотрудников, отзывов, документов — раздел 3 gap-analysis | шаг 3 |
| Витрина и карточка каталога | сортировка, «показывать по N», аналоги, «с этим покупают», лейблы, габариты | шаги 4–5 |
| Корзина | свои поля формы заказа есть; нет промокодов, минимальной суммы, счётчика ± | шаг 6 |
| Сравнение, избранное, «вы смотрели» | одна механика на три функции | шаг 7 |
| Пересчёт витрины фасетов из админки синхронный | импорт считает их в очереди, правка товара — нет | по мере надобности |
| Связи товара и цены вариантов без экранов | таблицы есть | по мере надобности |
| Блоки и провайдеры поиска отключённого модуля не спрятаны | ключ модуля помнят только кнопки покупки и меню | когда появится модуль со своим блоком в продаже |
| Нет типа блока «создатель сайта» | нужны платформенные настройки | по мере надобности |

### 4. Админка

| Что | Состояние |
|---|---|
| Страница Blade внутри оболочки админки | не начата. Нужна для экранов клиента, которые пишет верстальщик: персайтовый код умеет меню, схемы настроек и адреса, но собрать свой экран ему не из чего. Оценка — около полутора дней вместе с набором CSS-классов. **Владелец ещё не сказал «делаем»** |
| Свои Vue-экраны клиента | решено: только под конкретный заказ, в общий механизм не выносим |
| Мастер создания раздела в два шага | как в легаси: сначала тип страницы плитками, потом название и картинка, плюс «Создать и открыть настройки». Предложено владельцу, ответа нет |
| Свёрнутые ветки дерева разделов | сейчас дерево раскрыто целиком; на каталоге с сотнями категорий это простыня. Предложено владельцу, ответа нет |
| Нумерация страниц рисует все номера | на сотнях страниц список номеров станет длинным; нужен сокращённый вид |

### 5. Зависимости и мелочи

- **`npm audit`: 32 уязвимости** (27 средних, 5 высоких) — `vue`
  (через `@vue/server-renderer`) и `@tiptap/*` (через `@tiptap/core`
  и `prosemirror-view`). `npm audit fix` обещает обойтись без ломающих
  обновлений, но после него обязательно проверить руками редактор текста
  и пересобрать бандл.
- **Мусор в базе разработки** — супер-админ платформы, сайты `probnyj`,
  `kopiya`, `kopiya2`, форма с заявкой, SEO-шаблоны на разделах 1 и 5.
  Остатки живых прогонов, удаляются без сожаления (CLAUDE.md, «Состояние базы
  разработки»).
- **Экраны админки проверялись не входом в неё.** Пароля от админки стенда
  у автора не было, и вёрстка экранов проверялась прогоном собранного бандла
  с поддельным ответом Inertia. Получив доступ, стоит пройти экраны руками —
  особенно дерево разделов, формы и заявки, баннеры, шаблоны карточки.

### 6. Вопросы владельцу, на которые нет ответа

Полный список и то, что уже решено, — в
[gap-analysis.md](gap-analysis.md#8-вопросы-владельцу). Открыты:

- **В4.** «Тэги» и «Теги» у новости легаси — это две разные сущности?
- **В7.** Нужны ли цена «от», договорная и торг, или хватает «цены по запросу»?
- **В11.** Нужны ли водяные знаки на загружаемых фотографиях?
- **В12.** Что из 74 живых компонентов легаси вообще не нужно переносить?
  Ответ сэкономит больше времени, чем любая оптимизация.

## Правила, которых держался автор

Их стоит сохранить: на них держатся и документация, и порядок в коде.

1. **Комментарий объясняет причину, а не действие.** Почти в каждом
   нетривиальном месте написано, что было в легаси и чем это кончилось, —
   это защита от «упрощения» обратно.
2. **Три инварианта** ([architecture.md](architecture.md#инварианты)):
   `site_id` в каждой пользовательской таблице с объявлением в `TenantTables`;
   относительные пути медиа; site-модуль не ссылается на platform-модуль.
   Первый и третий проверяются тестом и Deptrac.
3. **Никакого `eval`** — ни в правах, ни в условиях видимости настроек,
   ни в персайтовом коде клиента.
4. **Массовые операции — через writer** (`SectionWriter`, `LayoutWriter`,
   `RedirectWriter`): `Model::query()->delete()` не поднимает событий Eloquent,
   и кэш остаётся протухшим ([cache.md](cache.md)).
5. **`Cache::tags()` не использовать никогда**: автономная копия сайта работает
   на файловом драйвере, который тегов не умеет.
6. **Документация обновляется тем же коммитом**, что и код узла.
7. **Каждая доработка выкатывается на стенд** и проверяется там же: половина
   найденных ошибок пришла из живых прогонов, а не из тестов.
