interview-demo-code/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

TeleCart — коммерческий модуль для OpenCart, превращающий магазин в Telegram Mini App. Это монорепозиторий из трёх частей:

• PHP-модуль OpenCart — module/oc_telegram_shop/upload/ (вся бизнес-логика и собственный фреймворк).
• SPA — frontend/spa/ (Telegram Mini App, витрина для покупателей).
• Admin — frontend/admin/ (панель управления настройками модуля).

src/ в корне — это распакованная установка OpenCart (генерируется скриптами, не редактировать; код модуля «линкуется» в неё через make link).

Где живёт код модуля

Сердце проекта — module/oc_telegram_shop/upload/oc_telegram_shop/ (далее «корень модуля»). Его структура:

Каталог	Namespace	Назначение
framework/	Openguru\OpenCartFramework\	Собственный Laravel-подобный фреймворк: Container (DI), Router, QueryBuilder, Cache, Migrations, Telegram, Http, Translator
src/	App\	API витрины/SPA (catalog). Handlers, Services, Models, DTO, Filters, ServiceProviders
bastion/	Bastion\	API админ-панели. Handlers, Services, Tasks, ScheduledTasks
console/	Console\	CLI-команды (Symfony Console), точка входа upload/cli.php
database/migrations/	—	Миграции БД
configs/	—	app.php, maintenance.php, schedule.php
tests/	Tests\	Unit/, Integration/, Telegram/

Маршрутизация. Запросы приходят через action-параметр и резолвятся по двум картам:

• src/routes.php — действия SPA (products, getCart, checkout, webhook, …)
• bastion/routes.php — действия админки (getSettingsForm, getTelegramCustomers, getDashboardStats, …)

Каждая запись — 'actionName' => [HandlerClass::class, 'method'].

Точки входа OpenCart (тонкие обёртки, грузят autoload и поднимают App\ApplicationFactory):

• module/.../upload/catalog/controller/extension/tgshop/handle.php — SPA API
• module/.../upload/admin/controller/extension/module/tgshop.php — админка

В продакшене модуль собирается в oc_telegram_shop.phar и подключается из system/library/oc_telegram_shop/; в dev — из исходников через vendor/autoload.php.

Архитектурные правила (бэкенд)

Паттерн — MVC-L поверх собственного фреймворка. Соблюдай строго:

• Совместимость с PHP 7.4. Минимальные требования OpenCart и модуля — PHP 7.4 (composer.json: ^7.4). Не используй синтаксис и функции PHP 8.0+ (named arguments, match, constructor property promotion, enum, readonly, nullsafe ?->, union types и т.п.).
• Dependency Injection через конструктор. Никогда не создавай зависимости через new внутри классов — внедряй их. Регистрация сервисов идёт в Service Providers (src/ServiceProviders/) через $this->app->singleton(...).
• Query Builder вместо сырого SQL. Используй $this->builder->newQuery()->from(...)->where(...)->get(). Прямой SQL — только в крайних случаях; никогда не конкатенируй значения в запрос (SQL injection).
• Слои: Handler (валидация + вызов сервиса + JsonResponse) → Service (бизнес-логика) → Model (доступ к данным). Не смешивай.
• Строгая типизация: declare(strict_types=1), типы аргументов и возвращаемых значений, nullable где нужно. PSR-12.
• Безопасный доступ к массивам: Arr::get($data, 'key', $default) вместо $data['key'].
• Таблицы: префикс OpenCart (oc_) + собственные таблицы модуля.

Архитектура фронтенда

Оба приложения — Vue 3, только <script setup> + Composition API, Pinia (setup-stores), Vue Router.

• SPA (frontend/spa/): Tailwind CSS, FormKit, Swiper, ofetch. Сборка → module/.../upload/image/catalog/tgshopspa/. Тесты — Vitest.
• Admin (frontend/admin/): PrimeVue (основной UI-кит), Tailwind/DaisyUI, axios, CodeMirror, vuedraggable. Сборка → module/.../upload/admin/view/javascript/telecart/.

Конвенции: компоненты — PascalCase, файлы логики — camelCase; обработчики событий с префиксом handle; computed для производных значений; ?? (не ||) для дефолтов чисел/булевых; сложную логику выносить в composables. Ошибки API ловить и показывать через toast (admin: useToast из PrimeVue).

FormBuilder (admin) — отдельная подсистема визуального конструктора форм. Единственный источник истины — FormKit Schema JSON (без промежуточных DTO). Drag-and-drop строго на vuedraggable (не @formkit/drag-and-drop). Tailwind-классы там идут с префиксом tw:.

Команды

Все make-цели выполняются внутри Docker-контейнера web — нужен запущенный docker compose.

Старт / окружение:

make setup      # первичная установка: скачать OpenCart, установить, поднять, link
make start      # поднять контейнеры
make dev        # link + параллельно vite dev для SPA и Admin
make dev-spa    # только SPA (vite)
make dev-admin  # только Admin (vite)
make link       # «слинковать» код модуля в установку OpenCart (после правок структуры)
make ssh        # шелл в контейнер в каталоге модуля

Тесты (PHP, PHPUnit в контейнере):

make test               # все тесты (--testdox)
make test-unit          # tests/Unit
make test-integration   # tests/Integration
make test-telegram      # tests/Telegram
make test-coverage      # HTML-покрытие в coverage/

Запуск одного теста — через ssh в контейнер:

make ssh
./vendor/bin/phpunit --filter testMethodName tests/Unit/SomeTest.php

Тесты фронтенда (SPA): cd frontend/spa && npm run test (Vitest), npm run test:run для однократного прогона.

Линтеры / статический анализ:

make lint     # PHPStan (level 1) по src, bastion, framework, console
make phpcs    # PHP_CodeSniffer PSR-12 (проверка)
make phpcbf   # PHP_CodeSniffer PSR-12 (автофикс)

Admin-фронтенд: cd frontend/admin && npm run lint (oxlint + eslint), npm run format (prettier).

Сборка / релиз:

make phar       # собрать oc_telegram_shop.phar (через docker/build.dockerfile)
make ocmod      # применить OCMOD-модификации
make cli ARGS="..."  # запустить console-команду модуля
make changelog  # сгенерировать CHANGELOG из conventional commits
make release    # changelog + commit релиза

Коммиты

Используются Conventional Commits (feat:, fix:, chore:, build(deps): …) — CHANGELOG и версии генерируются автоматически. Не делать git commit/git push без явного указания пользователя.