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).

Документация по фичам (docs/features/)

Контекстная документация хранится в docs/features/ — по одной поддиректории на фичу, внутри индексный CLAUDE.md. Вложенные CLAUDE.md Claude Code подхватывает автоматически при чтении файлов из их директории, поэтому индекс фичи читается «по требованию», когда работа касается этой фичи.

Перед тем как трогать незнакомую часть системы — загляни в её папку в docs/features/. Конвенции, шаблон новой фичи и реестр всех фич с прямыми путями — в docs/features/CLAUDE.md. Шаблон для новой фичи — docs/features/_TEMPLATE.md. При изменении фичи поддерживай её доку в актуальном состоянии (код — источник истины; при расхождении правь доку).

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

Сердце проекта — 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 без явного указания пользователя.