# AGENTS.md — инструкция для агентов

## О проекте

**ocStore (OpenCart) 3.0.3.7** — интернет-магазин на PHP с Twig-шаблонами.

- **Платформа:** ocStore 3.0.3.7 (форк OpenCart)
- **PHP:** >= 8.5
- **Шаблонизатор:** Twig 3.0
- **Язык:** русский (ru-ru)
- **База данных:** MySQL (драйвер mysqli)
- **Веб-сервер:** Apache с mod_rewrite

## Структура проекта

```
public/
├── admin/          # Админ-панель (MVC)
│   ├── controller/ # Контроллеры
│   ├── language/   # Языковые файлы ru-ru
│   ├── model/      # Модели
│   ├── view/       # Twig-шаблоны (.twig)
│   └── index.php
├── store/          # Витрина / каталог (MVC)
│   ├── controller/
│   ├── language/
│   ├── model/
│   └── view/theme/ # Тема оформления
├── system/         # Ядро (фреймворк, библиотеки, хелперы)
│   ├── engine/     # Роутинг, экшены, загрузчик
│   ├── library/    # Библиотеки (language, config, template, …)
│   ├── helper/     # Хелперы
│   └── config/     # Конфигурация ядра
├── image/          # Изображения товаров
├── config.php      # Конфигурация (в .gitignore!)
└── index.php       # Точка входа
storage/
├── cache/          # Кэш (в .gitignore)
├── logs/           # Логи (в .gitignore)
├── modification/   # Модификации OCMOD (в .gitignore)
├── session/        # Сессии PHP (в .gitignore)
├── upload/         # Загрузки (в .gitignore)
├── download/       # Файлы для скачивания (в .gitignore)
└── vendor/         # Composer-зависимости (в .gitignore, Twig)
```

## Важные правила

### Никогда не коммитить
- `public/config.php` и `public/admin/config.php` — содержат пароли БД
- `storage/` целиком (кроме `index.html`)
- `vendor/` — устанавливается через Composer
- Файлы кэша, логов, сессий
- `public/image/` — изображения хранятся отдельно

### Коммиты
- Сообщения коммитов — **на русском языке**
- Стиль: кратко, что сделано (пример: `"Блог в меню"`, `"Удалил googleshopping"`)

### Код-стайл
- PHP: без строгой типизации, используется `$_` суперглобальный массив для языковых переменных
- Языковые файлы — ассоциативный массив `$_['key'] = 'значение';`
- Контроллеры — классы в `Controller*` namespace
- Модели — классы в `Model*` namespace
- Шаблоны — `.twig` файлы
- Формат языковых переменных в шаблонах: `{{ text_yes }}`, `{{ button_save }}`
- Формат языковых констант: `$_['text_yes']`, `$_['button_save']` и т.д.

### OpenCart MVC (паттерн)
- URL-роутинг: `index.php?route=common/home` загружает `controller/common/home.php`
- Контроллер вызывает `$this->load->model('catalog/product')` для загрузки модели
- Контроллер вызывает `$this->load->language('product/product')` для языкового файла
- Шаблоны рендерятся через `$this->response->setOutput($this->load->view(...))`

### Модификации (OCMOD)
- OCMOD-модификации лежат в `public/system/modification.xml`
- Изменённые файлы попадают в `storage/modification/` — не трогать вручную

### Composer
- Зависимости: Twig 3.0
- Установка: `composer install` в `storage/`

## Работа с расширениями

Расширения (модули, темы, платёжные шлюзы и т.д.) устанавливаются через админ-панель или вручную:
- Модули: `public/admin/controller/extension/module/`, `public/store/controller/extension/module/`
- Темы: `public/store/view/theme/`
- Языковые файлы расширений: `public/admin/language/ru-ru/extension/`

## Полезные команды

```bash
# Очистка кэша
rm -rf storage/cache/*

# Установка зависимостей
cd storage && composer install

# Просмотр логов
tail -f storage/logs/error.log
```