From a7f9564aab0aa94081b5f8d33940e71772696bd2 Mon Sep 17 00:00:00 2001
From: Aleksey Filippov <Aleksey.Filippov@erp-flowers.ru>
Date: Tue, 9 Dec 2025 13:12:36 +0300
Subject: [PATCH] =?utf8?q?ERP-499=20=D0=94=D0=BE=D1=80=D0=B0=D0=B1=D0=BE?=
 =?utf8?q?=D1=82=D0=BA=D0=B0=20=D1=81=D0=B8=D1=81=D1=82=D0=B5=D0=BC=D1=8B?=
 =?utf8?q?=20=D0=BE=D1=86=D0=B8=D1=81=D1=82=D0=BA=D0=B8=20=D0=B2=D0=BB?=
 =?utf8?q?=D0=BE=D0=B6=D0=B5=D0=BD=D0=B8=D0=B9=20=D0=B2=20=D0=B4=D0=BE?=
 =?utf8?q?=D0=BA=20=D1=81=D0=BF=D0=B8=D1=81=D0=B0=D0=BD=D0=B8=D1=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

---
 erp24/php_skills/01-php-basics.md       |   2 +
 erp24/php_skills/02-php-naming.md       |   6 +
 erp24/php_skills/10-yii2-structure.md   |  80 +++++++++++--
 erp24/php_skills/11-yii2-models.md      | 153 +++++++++++++++++++++---
 erp24/php_skills/12-yii2-controllers.md |   9 +-
 erp24/php_skills/13-yii2-views.md       |   5 +-
 erp24/php_skills/14-yii2-routing.md     |   2 +
 erp24/php_skills/15-yii2-migrations.md  |   2 +
 erp24/php_skills/16-yii2-testing.md     |   2 +
 erp24/php_skills/17-yii2-security.md    |   8 +-
 erp24/php_skills/18-yii2-performance.md |   2 +
 erp24/php_skills/19-yii2-api.md         |  15 ++-
 erp24/php_skills/20-yii2-widgets.md     |   2 +
 erp24/php_skills/README.md              |  25 ++++
 14 files changed, 281 insertions(+), 32 deletions(-)

diff --git a/erp24/php_skills/01-php-basics.md b/erp24/php_skills/01-php-basics.md
index 17cdd4d2..b2f2f904 100644
--- a/erp24/php_skills/01-php-basics.md
+++ b/erp24/php_skills/01-php-basics.md
@@ -1,5 +1,7 @@
 # PHP Basics - Основы форматирования и синтаксиса
 
+> **ВАЖНО для ERP24**: В примерах используется стандартный Yii2 namespace `app\models`. В проекте ERP24 используйте `yii_app\records` (папка `erp24/records/`).
+
 ## Кодировка и форматирование
 
 ### Кодировка файлов
diff --git a/erp24/php_skills/02-php-naming.md b/erp24/php_skills/02-php-naming.md
index 8f4e71dd..64624186 100644
--- a/erp24/php_skills/02-php-naming.md
+++ b/erp24/php_skills/02-php-naming.md
@@ -1,5 +1,11 @@
 # PHP Naming - Соглашения об именовании
 
+> **ВАЖНО для ERP24**: В проекте ERP24 используются специфичные namespaces:
+>
+> - Модели: `yii_app\records` (папка `erp24/records/`)
+> - Сервисы: `yii_app\services` (папка `erp24/services/`)
+> - Контроллеры: `yii_app\controllers` (папка `erp24/controllers/`)
+
 ## Общие правила
 
 ### Язык идентификаторов
diff --git a/erp24/php_skills/10-yii2-structure.md b/erp24/php_skills/10-yii2-structure.md
index ae2bb1d7..5a62ed13 100644
--- a/erp24/php_skills/10-yii2-structure.md
+++ b/erp24/php_skills/10-yii2-structure.md
@@ -1,9 +1,56 @@
 # Yii2 Structure - Структура приложения
 
-## Структура директорий
+> **ВАЖНО для ERP24**: Структура проекта ERP24 отличается от стандартной Yii2. Модели находятся в `erp24/records/` (не `models/`), namespace — `yii_app\records`.
+
+## Структура ERP24
+
+```text
+yii_erp24/
+├── erp24/                   # Основное приложение
+│   ├── records/             # <-- Модели ActiveRecord (387 моделей)
+│   │   ├── Admin.php
+│   │   ├── AdminGroup.php
+│   │   ├── Store.php
+│   │   ├── Users.php
+│   │   ├── *Search.php      # Search-модели для GridView
+│   │   └── ...
+│   ├── services/            # Сервисные классы (51 сервис)
+│   ├── controllers/         # Контроллеры (160+)
+│   ├── api1/                # API версия 1
+│   ├── api2/                # API версия 2
+│   ├── api3/                # API версия 3
+│   ├── actions/             # Standalone actions (40+)
+│   ├── helpers/             # Вспомогательные классы (15+)
+│   ├── forms/               # Формы (20+)
+│   ├── migrations/          # Миграции БД (278)
+│   ├── config/              # Конфигурация
+│   ├── views/               # Представления
+│   ├── widgets/             # Виджеты
+│   ├── jobs/                # Очереди
+│   └── docs/                # Документация
+├── docker/                  # Docker конфигурация
+└── tests/                   # Тесты
+```
+
+### Namespaces ERP24
+
+| Путь | Namespace |
+|------|-----------|
+| `erp24/records/` | `yii_app\records` |
+| `erp24/services/` | `yii_app\services` |
+| `erp24/controllers/` | `yii_app\controllers` |
+| `erp24/api1/controllers/` | `yii_app\api1\controllers` |
+| `erp24/api2/controllers/` | `yii_app\api2\controllers` |
+| `erp24/api3/` | `yii_app\api3` |
+| `erp24/helpers/` | `yii_app\helpers` |
+| `erp24/forms/` | `yii_app\forms` |
+| `erp24/jobs/` | `yii_app\jobs` |
+
+## Структура директорий (стандартный Yii2)
 
 ### Стандартная структура Yii2 Basic
-```
+
+```text
 project/
 ├── assets/              # Asset bundles
 ├── commands/            # Console команды
@@ -14,7 +61,7 @@ project/
 │   └── web.php          # Конфиг веб-приложения
 ├── controllers/         # Контроллеры
 ├── mail/                # Шаблоны писем
-├── models/              # Модели
+├── models/              # Модели (в ERP24: records/)
 ├── runtime/             # Временные файлы
 ├── views/               # Представления
 │   ├── layouts/         # Макеты
@@ -28,7 +75,8 @@ project/
 ```
 
 ### Структура Yii2 Advanced
-```
+
+```text
 project/
 ├── backend/             # Административная часть
 │   ├── assets/
@@ -65,7 +113,8 @@ project/
 ## Модульная структура
 
 ### Организация для больших проектов
-```
+
+```text
 project/
 ├── api/                 # REST API модуль
 │   ├── config/
@@ -140,6 +189,7 @@ $config = [
             'class' => \yii\caching\FileCache::class,
         ],
         'user' => [
+            // В ERP24: \yii_app\records\Admin::class
             'identityClass' => \app\models\User::class,
             'enableAutoLogin' => true,
             'loginUrl' => ['site/login'],
@@ -425,13 +475,15 @@ Yii::$app->notifier->send('Hello!', 'email');
 ## Сервисные классы
 
 ### Структура сервиса
+
 ```php
 <?php
-// services/payment/PaymentService.php
-namespace app\services\payment;
+// erp24/services/PaymentService.php (для ERP24)
+// или services/payment/PaymentService.php (стандартный Yii2)
+namespace yii_app\services;  // В ERP24
 
-use app\models\Order;
-use app\models\Payment;
+use yii_app\records\Order;   // В ERP24: records вместо models
+use yii_app\records\Payment;
 use yii\base\Component;
 use yii\base\InvalidConfigException;
 
@@ -735,9 +787,19 @@ Yii::endProfile('slow-operation');
 
 ## Рекомендации для Claude Code
 
+### Общие правила
+
 1. **Следуйте структуре Yii2** - используйте стандартные директории
 2. **Модульность** - разбивайте большие приложения на модули
 3. **Компоненты** - выносите переиспользуемую логику в компоненты
 4. **Сервисы** - изолируйте бизнес-логику от контроллеров
 5. **Конфигурация** - используйте переменные окружения для секретов
 6. **Логирование** - настраивайте разные targets для разных уровней
+
+### Специфика ERP24
+
+1. **Модели в `erp24/records/`** — namespace `yii_app\records`
+2. **Сервисы в `erp24/services/`** — namespace `yii_app\services`
+3. **3 уровня API**: `api1`, `api2`, `api3` со своими контроллерами
+4. **Search-модели** находятся рядом с основными моделями в `records/`
+5. **Identity Class**: `\yii_app\records\Admin` (не User)
diff --git a/erp24/php_skills/11-yii2-models.md b/erp24/php_skills/11-yii2-models.md
index 27fbc304..52e55374 100644
--- a/erp24/php_skills/11-yii2-models.md
+++ b/erp24/php_skills/11-yii2-models.md
@@ -1,12 +1,32 @@
 # Yii2 Models - Модели и ActiveRecord
 
+> **ВАЖНО для ERP24**: В проекте ERP24 модели (ActiveRecord) располагаются в папке `erp24/records/` с namespace `yii_app\records`, а не в стандартной `models/` с namespace `app\models`.
+
+## Структура проекта ERP24
+
+```text
+erp24/
+├── records/              # <-- Модели ActiveRecord (387 моделей)
+│   ├── Admin.php
+│   ├── AdminGroup.php
+│   ├── Store.php
+│   ├── Users.php
+│   └── ...
+├── services/             # Бизнес-логика
+├── controllers/          # Контроллеры
+└── ...
+```
+
 ## Структура модели
 
 ### Порядок элементов в модели
 ```php
 <?php
-namespace app\models;
+declare(strict_types=1);
 
+namespace yii_app\records;  // Namespace для ERP24
+
+use Yii;
 use yii\db\ActiveRecord;
 use yii\behaviors\TimestampBehavior;
 use yii\behaviors\BlameableBehavior;
@@ -153,21 +173,53 @@ class User extends ActiveRecord
 ### Модели и таблицы
 ```php
 <?php
-// ПРАВИЛЬНО - имя класса в единственном числе, CamelCase
-class User extends ActiveRecord {}
-class OrderItem extends ActiveRecord {}
-class ProductCategory extends ActiveRecord {}
+namespace yii_app\records;
 
-// Таблица - множественное число, snake_case
+use yii\db\ActiveRecord;
+
+// ПРАВИЛЬНО для ERP24 - имя класса в CamelCase
+class Admin extends ActiveRecord {}
+class AdminGroup extends ActiveRecord {}
+class StoreOrders extends ActiveRecord {}
+class WriteOffsProducts extends ActiveRecord {}
+
+// Таблица - возвращается через tableName()
 public static function tableName(): string
 {
-    return '{{%users}}';       // users
-    return '{{%order_items}}'; // order_items
+    return 'admin';           // Без префикса
+    return 'admin_group';     // snake_case
+    return 'store_orders';    // snake_case
 }
 
 // НЕПРАВИЛЬНО
-class Users extends ActiveRecord {}  // множественное число
-class orderItem extends ActiveRecord {} // не CamelCase
+class admin extends ActiveRecord {}      // не CamelCase
+class adminGroup extends ActiveRecord {} // не CamelCase
+```
+
+### Примеры из ERP24
+```php
+<?php
+// erp24/records/Admin.php
+namespace yii_app\records;
+
+class Admin extends ActiveRecord implements IdentityInterface
+{
+    public static function tableName(): string
+    {
+        return 'admin';
+    }
+}
+
+// erp24/records/AdminGroup.php
+namespace yii_app\records;
+
+class AdminGroup extends ActiveRecord
+{
+    public static function tableName(): string
+    {
+        return 'admin_group';
+    }
+}
 ```
 
 ## Связи (Relations)
@@ -175,6 +227,11 @@ class orderItem extends ActiveRecord {} // не CamelCase
 ### hasOne
 ```php
 <?php
+namespace yii_app\records;
+
+use yii\db\ActiveQuery;
+use yii\db\ActiveRecord;
+
 class User extends ActiveRecord
 {
     // Один к одному
@@ -202,6 +259,11 @@ class User extends ActiveRecord
 ### hasMany
 ```php
 <?php
+namespace yii_app\records;
+
+use yii\db\ActiveQuery;
+use yii\db\ActiveRecord;
+
 class User extends ActiveRecord
 {
     // Один ко многим
@@ -237,6 +299,11 @@ class User extends ActiveRecord
 ### Many-to-Many через связующую таблицу
 ```php
 <?php
+namespace yii_app\records;
+
+use yii\db\ActiveQuery;
+use yii\db\ActiveRecord;
+
 class User extends ActiveRecord
 {
     // Через промежуточную модель
@@ -267,12 +334,14 @@ class User extends ActiveRecord
     }
 }
 
-// Связующая модель
+// Связующая модель (erp24/records/UserRole.php)
+namespace yii_app\records;
+
 class UserRole extends ActiveRecord
 {
     public static function tableName(): string
     {
-        return '{{%user_roles}}';
+        return 'user_roles';  // Без префикса {{%}} для ERP24
     }
 
     public function getUser(): ActiveQuery
@@ -582,8 +651,9 @@ $user->save();
 ### Кастомный ActiveQuery
 ```php
 <?php
-// models/query/UserQuery.php
-namespace app\models\query;
+// erp24/records/query/UserQuery.php (если нужен отдельный файл)
+// Или в том же файле модели
+namespace yii_app\records;
 
 use yii\db\ActiveQuery;
 
@@ -975,9 +1045,62 @@ $transaction = \Yii::$app->db->beginTransaction(
 
 ## Рекомендации для Claude Code
 
-1. **Тонкие модели** - выносите сложную бизнес-логику в сервисы
+### Общие правила
+
+1. **Тонкие модели** - выносите сложную бизнес-логику в сервисы (`erp24/services/`)
 2. **Используйте behaviors** - для повторяющейся логики (timestamps, slugs)
 3. **Кастомные ActiveQuery** - для переиспользуемых scope-ов
 4. **Eager loading** - всегда используйте with() для связей в циклах
 5. **Валидация на уровне БД** - добавляйте constraints в миграциях
 6. **Транзакции** - оборачивайте связанные операции
+
+### Специфика ERP24
+
+1. **Расположение моделей**: все модели ActiveRecord в `erp24/records/`
+2. **Namespace**: `yii_app\records`
+3. **Без префиксов таблиц**: в `tableName()` возвращается имя таблицы без `{{%}}`
+4. **Search-модели**: `*Search.php` классы находятся рядом с основной моделью
+5. **Константы**: используются для статусов, типов, ID групп
+6. **PHPDoc**: обязательны `@property` аннотации для связей и виртуальных свойств
+
+### Примеры из проекта
+
+```php
+<?php
+// erp24/records/Admin.php - типичная структура модели ERP24
+declare(strict_types=1);
+
+namespace yii_app\records;
+
+use Yii;
+use yii\db\ActiveRecord;
+use yii\web\IdentityInterface;
+
+/**
+ * Class Admin
+ * @property AdminGroup $adminGroup
+ * @property EmployeePosition $employeePosition
+ * @property int $id
+ * @property int $group_id
+ * @property string $name
+ */
+class Admin extends ActiveRecord implements IdentityInterface
+{
+    // Константы для статусов и групп
+    public const WORK_STATUS_IS_WORK = 1;
+    public const WORK_STATUS_FIRED = 4;
+    public const CLUSTER_MANAGER_GROUP_ID = 7;
+    public const ADMINISTRATOR_GROUP_ID = 50;
+
+    public static function tableName(): string
+    {
+        return 'admin';  // Без префикса
+    }
+
+    // Связь с группой
+    public function getAdminGroup(): ActiveQuery
+    {
+        return $this->hasOne(AdminGroup::class, ['id' => 'group_id']);
+    }
+}
+```
diff --git a/erp24/php_skills/12-yii2-controllers.md b/erp24/php_skills/12-yii2-controllers.md
index 4c914f9c..92468360 100644
--- a/erp24/php_skills/12-yii2-controllers.md
+++ b/erp24/php_skills/12-yii2-controllers.md
@@ -1,13 +1,18 @@
 # Yii2 Controllers - Контроллеры
 
+> **ВАЖНО для ERP24**: Контроллеры располагаются в `erp24/controllers/` с namespace `yii_app\controllers`. Модели импортируются из `yii_app\records`.
+
 ## Структура контроллера
 
 ### Базовый контроллер
+
 ```php
 <?php
-namespace app\controllers;
+declare(strict_types=1);
+
+namespace yii_app\controllers;  // Namespace для ERP24
 
-use app\models\User;
+use yii_app\records\User;       // Модели из records
 use yii\web\Controller;
 use yii\web\NotFoundHttpException;
 use yii\filters\AccessControl;
diff --git a/erp24/php_skills/13-yii2-views.md b/erp24/php_skills/13-yii2-views.md
index eae981c9..a242ec62 100644
--- a/erp24/php_skills/13-yii2-views.md
+++ b/erp24/php_skills/13-yii2-views.md
@@ -1,9 +1,12 @@
 # Yii2 Views - Представления и шаблоны
 
+> **ВАЖНО для ERP24**: Views располагаются в `erp24/views/`. При работе с моделями используйте `yii_app\records`, assets — `yii_app\assets`.
+
 ## Структура views
 
 ### Организация директорий
-```
+
+```text
 views/
 ├── layouts/              # Макеты
 │   ├── main.php          # Основной layout
diff --git a/erp24/php_skills/14-yii2-routing.md b/erp24/php_skills/14-yii2-routing.md
index 5fc1f059..2317bf88 100644
--- a/erp24/php_skills/14-yii2-routing.md
+++ b/erp24/php_skills/14-yii2-routing.md
@@ -1,5 +1,7 @@
 # Yii2 Routing - Маршрутизация
 
+> **ВАЖНО для ERP24**: Маршрутизация настраивается в `erp24/config/`. При создании кастомных правил используйте namespace `yii_app\components`.
+
 ## Конфигурация UrlManager
 
 ### Базовая настройка
diff --git a/erp24/php_skills/15-yii2-migrations.md b/erp24/php_skills/15-yii2-migrations.md
index 81641370..90af7b55 100644
--- a/erp24/php_skills/15-yii2-migrations.md
+++ b/erp24/php_skills/15-yii2-migrations.md
@@ -1,5 +1,7 @@
 # Yii2 Migrations - Миграции базы данных
 
+> **ВАЖНО для ERP24**: Миграции располагаются в `erp24/migrations/` (278 миграций). Namespace миграций — `yii_app\migrations`.
+
 ## Основы миграций
 
 ### Создание миграции
diff --git a/erp24/php_skills/16-yii2-testing.md b/erp24/php_skills/16-yii2-testing.md
index 6662e872..8cd4c0a2 100644
--- a/erp24/php_skills/16-yii2-testing.md
+++ b/erp24/php_skills/16-yii2-testing.md
@@ -1,5 +1,7 @@
 # Yii2 Testing - Тестирование
 
+> **ВАЖНО для ERP24**: Тесты располагаются в `erp24/tests/`. При тестировании моделей используйте `yii_app\records`, fixtures в `erp24/tests/fixtures/`.
+
 ## Настройка окружения
 
 ### Codeception конфигурация
diff --git a/erp24/php_skills/17-yii2-security.md b/erp24/php_skills/17-yii2-security.md
index e9c53eb1..52fd0a08 100644
--- a/erp24/php_skills/17-yii2-security.md
+++ b/erp24/php_skills/17-yii2-security.md
@@ -1,12 +1,16 @@
 # Yii2 Security - Безопасность
 
+> **ВАЖНО для ERP24**: Identity класс — `yii_app\records\Admin` (файл `erp24/records/Admin.php`). Используйте namespace `yii_app\records` вместо `app\models`.
+
 ## Аутентификация
 
 ### Identity Interface
+
 ```php
 <?php
-// models/User.php
-namespace app\models;
+// erp24/records/Admin.php (для ERP24)
+// или models/User.php (стандартный Yii2)
+namespace yii_app\records;  // В ERP24
 
 use yii\db\ActiveRecord;
 use yii\web\IdentityInterface;
diff --git a/erp24/php_skills/18-yii2-performance.md b/erp24/php_skills/18-yii2-performance.md
index 2d6e461f..8aae0750 100644
--- a/erp24/php_skills/18-yii2-performance.md
+++ b/erp24/php_skills/18-yii2-performance.md
@@ -1,5 +1,7 @@
 # Yii2 Performance - Производительность
 
+> **ВАЖНО для ERP24**: При оптимизации запросов используйте модели из `yii_app\records`. Кэширование настраивается в `erp24/config/`.
+
 ## Кэширование
 
 ### Конфигурация кэша
diff --git a/erp24/php_skills/19-yii2-api.md b/erp24/php_skills/19-yii2-api.md
index b65540c3..d006afbd 100644
--- a/erp24/php_skills/19-yii2-api.md
+++ b/erp24/php_skills/19-yii2-api.md
@@ -1,12 +1,21 @@
 # Yii2 REST API - Построение API
 
+> **ВАЖНО для ERP24**: API контроллеры располагаются в:
+>
+> - `erp24/api1/controllers/` — namespace `yii_app\api1\controllers`
+> - `erp24/api2/controllers/` — namespace `yii_app\api2\controllers`
+> - `erp24/api3/` — namespace `yii_app\api3`
+>
+> Модели импортируются из `yii_app\records`.
+
 ## Базовая конфигурация
 
 ### ActiveController
+
 ```php
 <?php
-// controllers/api/UserController.php
-namespace app\controllers\api;
+// erp24/api1/controllers/UserController.php (для ERP24)
+namespace yii_app\api1\controllers;  // В ERP24
 
 use yii\rest\ActiveController;
 use yii\filters\auth\HttpBearerAuth;
@@ -14,7 +23,7 @@ use yii\filters\RateLimiter;
 
 class UserController extends ActiveController
 {
-    public $modelClass = \app\models\User::class;
+    public $modelClass = \yii_app\records\User::class;  // В ERP24
 
     public function behaviors(): array
     {
diff --git a/erp24/php_skills/20-yii2-widgets.md b/erp24/php_skills/20-yii2-widgets.md
index 1f3036d9..b0b0d1a6 100644
--- a/erp24/php_skills/20-yii2-widgets.md
+++ b/erp24/php_skills/20-yii2-widgets.md
@@ -1,5 +1,7 @@
 # Yii2 Widgets - Виджеты и компоненты
 
+> **ВАЖНО для ERP24**: Виджеты располагаются в `erp24/widgets/` с namespace `yii_app\widgets`. При работе с моделями используйте `yii_app\records`.
+
 ## Базовые виджеты
 
 ### GridView
diff --git a/erp24/php_skills/README.md b/erp24/php_skills/README.md
index 36bddef4..fbf59600 100644
--- a/erp24/php_skills/README.md
+++ b/erp24/php_skills/README.md
@@ -2,6 +2,31 @@
 
 Современный набор гайдлайнов для разработки на PHP 8 и Yii2, оптимизированный для использования с Claude Code и другими AI-ассистентами.
 
+## Адаптация для ERP24
+
+> **ВАЖНО**: Данные гайдлайны адаптированы под структуру проекта ERP24.
+
+### Ключевые отличия от стандартного Yii2
+
+| Компонент | Стандартный Yii2 | ERP24 |
+|-----------|------------------|-------|
+| Модели | `app\models` | `yii_app\records` |
+| Папка моделей | `models/` | `erp24/records/` |
+| Сервисы | `app\services` | `yii_app\services` |
+| Контроллеры | `app\controllers` | `yii_app\controllers` |
+| API v1 | — | `yii_app\api1\controllers` |
+| API v2 | — | `yii_app\api2\controllers` |
+| API v3 | — | `yii_app\api3` |
+| Identity Class | `User` | `Admin` |
+
+### Статистика проекта ERP24
+
+- **387** моделей ActiveRecord
+- **160+** контроллеров
+- **51** сервис
+- **278** миграций
+- **3** версии API
+
 ## Структура документации
 
 ### Основы PHP
-- 
2.39.5