---
name: opencart-3-workflow
description: "Краткая практическая инструкция: как работать с OpenCart 3, его архитектурой и OCMOD (модификации)."
---

# OpenCart 3 — Быстрый навигатор для разработчика

Цель: дать понятную, повторяемую процедуру для разработки, отладки и развёртывания изменений в OpenCart 3 и управления модификациями через OCMOD.

1) Структура и роли
- `catalog/` — фронтенд (клиентская часть).
- `admin/` — панель администратора (контроллеры, модели, виды).
- `system/` — ядро: библиотека, storage, modification, config.
- MVC-L: контроллеры (`controller/*`), модели (`model/*`), шаблоны/виды (`view/*` — Twig/OC template).
- Языковые файлы в `language/*`.

2) Где правим исходники
- Разработку модулей вести в `dev-modules/<имя_модуля>/upload` (структура в `upload` должна повторять `catalog/` и `admin/`).
- НЕЛЬЗЯ править файлы напрямую в `opencart` (root OpenCart) — можно только просматривать для понимания.

3) OCMOD (модификации)
- OCMOD — XML-патчи, которые модифицируют поведение без правки ядра.
- Места хранения применённых модификаций: `system/storage/modification`.
- Для создания/обновления OCMOD: положите XML в модуль или загрузите через админ-панель, затем очистите кеш модификаций и примените.
 - Для создания/обновления OCMOD: положите XML в модуль или загрузите через админ-панель, затем очистите кеш модификаций и примените.
 - OCMOD-файлы также можно размещать в `system/` (например `system/<имя_модуля>.ocmod.xml`) или в `dev-modules/<имя_модуля>/upload/system/` — при установке/развёртывании модуля такие файлы будут доступны для установки. Всё равно после добавления/обновления нужно выполнить Refresh модификаций.

4) Локальная проверка и развёртывание модуля
- В папке модуля выполните `ocm install` (если в проекте есть утилита `ocm`) — это применит/скопирует файлы из `dev-modules/<имя_модуля>/upload` в рабочий OpenCart.
- После установки обновите кеш модификаций и шаблонов в админке (Extensions → Modifications → Refresh, and Dashboard → Gear → Refresh Cache).
- Проверяйте результат в `system/storage/modification` и логах (`system/storage/logs/`).

5) Отладка и полезные приёмы
- Для поиска точек входа используйте структуру маршрутов: контроллер → модель → view.
- При ошибках OCMOD смотрите логи модификаций и временные файлы в `system/storage/modification`.

5.a) `system/library` — назначение и неймспейсы
- `system/library` содержит общие библиотеки и классы ядра OpenCart. По умолчанию OpenCart не следует PSR-4/именованным пространствам для своих core-классов — он использует собственный загрузчик (`Loader`/`Registry`).
- Рекомендации:
	- Не изменяйте напрямую файлы в корневом `system/library` — это приводит к коллизиям и потерям при обновлении.
	- Если нужен общий класс/библиотека для модуля, размещайте её внутри модуля: `dev-modules/<имя_модуля>/upload/system/library/<vendor>/<package>/...` и загружайте через стандартный `load->library()` или регистрируйте автозагрузчик.
	- При использовании неймспейсов предпочитайте Composer/автозагрузчик: добавьте зависимости в `vendor/` и регистрируйте автозагрузку, либо используйте уникальный префикс/неймспейс, чтобы избежать конфликтов с ядром и другими модулями.
	- Избегайте переопределения core-классов в `system/library`; вместо этого создавайте отдельные namespaced-классы и инжектируйте их через registry/DI.

6) Практические правила команды
- Все исходные правки модулей — только в `dev-modules/<имя_модуля>/upload`.
- Не дублируйте изменения в `opencart` — модуль или OCMOD должен обеспечивать изменение.
- Для PR включайте только файлы из `dev-modules/<имя_модуля>/upload` и OCMOD (если требуется), указывайте в описании: "Изменения через модуль <имя_модуля>".

7) Контроль качества перед PR
- Запустите `git status` и убедитесь, что изменения лежат только в `dev-modules/<имя_модуля>`.
- Протестируйте сценарии: установка модуля, применение OCMOD, ключевые пользовательские пути (checkout, product view и т.д.).

8) Частые ошибки и как их избегать
- Прямая правка ядра — приводит к утрате изменений при обновлении. Решение: OCMOD или модуль.
- Несовпадение путей в `upload` и OpenCart — файл не применяется. Решение: повторяйте точную структуру (`admin/controller/...`, `catalog/view/...`).

Примеры команд
- Установить/обновить модуль (в папке модуля):

```
ocm install
```

- Очистить кеш и применить модификации — через админку (Modifications → Refresh) или вручную удалить кеш в `system/storage/cache` и `system/storage/modification` где применимо.

Подсказки для Copilot / агентов:
- Предлагай изменения и новые файлы только внутри `dev-modules/<имя_модуля>/upload`.
- Если нужен пример OCMOD — генерируй валидный XML с описанием цели и точками вставки, и указывай, что файл нужно положить в модуль и установить через админку или `ocm install`.

Если нужно — расширим этот навигатор чеклистом для PR или шаблоном OCMOD XML.