Nikita Kiselev
7f73343f3f
Migrate project guidance from .cursor/ to a single CLAUDE.md covering architecture, backend/frontend conventions, commands and PHP 7.4 constraint. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
137 lines
9.3 KiB
Markdown
137 lines
9.3 KiB
Markdown
# 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`.
|
||
|
||
**Старт / окружение:**
|
||
|
||
```bash
|
||
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 в контейнере):**
|
||
|
||
```bash
|
||
make test # все тесты (--testdox)
|
||
make test-unit # tests/Unit
|
||
make test-integration # tests/Integration
|
||
make test-telegram # tests/Telegram
|
||
make test-coverage # HTML-покрытие в coverage/
|
||
```
|
||
|
||
Запуск одного теста — через ssh в контейнер:
|
||
|
||
```bash
|
||
make ssh
|
||
./vendor/bin/phpunit --filter testMethodName tests/Unit/SomeTest.php
|
||
```
|
||
|
||
**Тесты фронтенда (SPA):** `cd frontend/spa && npm run test` (Vitest), `npm run test:run` для однократного прогона.
|
||
|
||
**Линтеры / статический анализ:**
|
||
|
||
```bash
|
||
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).
|
||
|
||
**Сборка / релиз:**
|
||
|
||
```bash
|
||
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` без явного указания пользователя.**
|