# Entity

> Entity is an Agent Skill for development published in the EC-CUBE/ec-cube repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

EC-CUBE 4.4 の Doctrine エンティティを実装・改修するときの規約。「エンティティを作って」「テーブルを追加して」「Entityにフィールドを足して」「リレーションを定義して」「マスタを追加して」などと言われたとき、または src/Eccube/Entity・app/Customize/Entity 配下を作成・編集するときに使用する。

- Skill name: `entity`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/EC-CUBE/ec-cube/blob/HEAD/.claude/skills/entity/SKILL.md
- Repository: EC-CUBE/ec-cube (789 GitHub stars when collected)

## SKILL.md

# Entity 規約（EC-CUBE 4.4）

**対象**: `src/Eccube/Entity/**/*.php`, `app/Customize/Entity/**/*.php`
**前提**: Doctrine ORM 3.x / PHP 8.2+（マッピングは **PHP8 属性**）

## 基本ルール

- 名前空間 `Eccube\Entity`（マスタは `Eccube\Entity\Master`）。
- 通常エンティティは `Eccube\Entity\AbstractEntity` を、**マスタ系は `AbstractMasterEntity`** を継承する。
- **マッピングは PHP8 属性 `#[ORM\...]`**（XML・アノテーションは使わない）。
- PHP ファイル先頭に EC-CUBE ライセンスヘッダを付ける。
- プロパティ・getter / setter に型宣言を付ける。setter は `$this` を返す（fluent）。
  nullable は DB カラムの nullable と一致させる。

## プロキシ拡張に対応するクラスラッパ

コアのエンティティは、プラグイン/カスタマイズによる trait 追加（プロキシ生成）に対応するため
`if (!class_exists(X::class)) { ... }` で囲う。

```php
namespace Eccube\Entity;

use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
use Eccube\Repository\ExampleRepository;

if (!class_exists(Example::class)) {
    #[ORM\Table(name: 'dtb_example')]
    #[ORM\Index(columns: ['create_date'], name: 'dtb_example_create_date_idx')]
    #[ORM\HasLifecycleCallbacks]
    #[ORM\Entity(repositoryClass: ExampleRepository::class)]
    class Example extends AbstractEntity
    {
        #[ORM\Id]
        #[ORM\Column(type: Types::INTEGER, options: ['unsigned' => true])]
        #[ORM\GeneratedValue(strategy: 'IDENTITY')]
        private ?int $id = null;

        #[ORM\Column(length: 255, nullable: true)]
        private ?string $name = null;

        // getId() の戻り値が ?int（nullable）なのは、IDENTITY 採番のため
        // 永続化（flush）されるまで ID が未採番（null）だから。意図的な nullable で、
        // 「まだ DB に保存されていない新規エンティティ」を表現できる。
        public function getId(): ?int
        {
            return $this->id;
        }

        public function setName(?string $name): self
        {
            $this->name = $name;

            return $this;
        }
    }
}
```

## 命名・その他

- テーブル名: データ系は `dtb_`、マスタ系は `mtb_`、プラグインは `plg_` を前置する。
- リレーションは `#[ORM\OneToMany]` / `#[ORM\ManyToOne]` 等の属性で定義。コレクションは
  コンストラクタで `ArrayCollection` を初期化する。
- ライフサイクルコールバックは `#[ORM\PrePersist]` / `#[ORM\PreUpdate]` 等（クラスに `#[ORM\HasLifecycleCallbacks]` が必要）。

## エンティティに置く「状態ロジック」と、外に出す「処理」の線引き

「業務ロジックをエンティティに書きすぎない」は雑な言い方で、実際には**何を置いてよいか**の区別が重要。

- **置いてよい（自身の状態から導く計算・判定）**: そのエンティティ自身のプロパティだけから決まる値や状態。
  - 例: `OrderItem::getTotalPrice()`（単価 × 数量）、`Order` の各種金額の合算、
    `Customer` の表示名の組み立て、ステータス定数の判定メソッドなど。
  - 副作用を持たず、外部（Repository・EntityManager・他サービス）に依存しない純粋な計算/判定はエンティティの責務。
  - **金額プロパティ（`Types::DECIMAL`）は Doctrine ORM 3.x で `?string`**（getter は `string` 戻り、setter も `string` 引数）。
    `Order` の `total` / `subtotal` / `payment_total` 等（`src/Eccube/Entity/Order.php`）が実例。
    計算は **float で四則演算せず `bcmath`**（`bcadd` / `bcmul` / `bccomp` 等、スケール 2）で行う。
    実例: `OrderItem::getTotalPrice()` = `bcmul($this->getPriceIncTax(), $this->getQuantity(), 2)`（`src/Eccube/Entity/OrderItem.php`）。
- **外に出す（副作用・横断・採番を伴う「処理」）**: 永続化や複数エンティティ・外部リソースを巻き込む処理。
  - **在庫引当・注文番号の採番・ポイント付与・値引き適用などの受注処理は PurchaseFlow（Skill `service` 参照）パイプラインへ**。
  - DB アクセス（クエリ）は Repository、トランザクションを伴う業務操作は Service へ（Skill `service`）。

## スキーマ変更時

- **スキーマの源泉は Entity の属性（`#[ORM\...]`）**。カラムの追加・変更は属性を編集するだけでよい。
  新規インストールは `doctrine:schema:create`、既存環境へのアップデートは `doctrine:schema:update --force` が
  属性から差分を反映する（**単純なカラム追加に ALTER マイグレーションは不要**）。
- マイグレーションを書くのは、`schema:update` で扱えないもの（**マスタ/初期データの INSERT、型変更・リネーム等の構造変更**）に限る。
  → 詳細は Skill `migration` に従う。

## カスタマイズ（app/Customize）

- 既存エンティティへのフィールド追加は **コアを書き換えず trait で行い**、`app/Customize/Entity/` に置く。
- 反映には `bin/console eccube:generate:proxies` でプロキシを再生成する。

## よくある間違い

- ❌ XML / アノテーションでマッピング → ✅ PHP8 属性
- ❌ カラムを足したので ALTER マイグレーションを書く → ✅ 属性を足すだけ（`schema:update` が反映）。マイグレーションは INSERT・型変更等に限る
- ❌ 在庫引当・採番・ポイント付与などの受注処理をエンティティに書く → ✅ PurchaseFlow / Service へ。エンティティは自身の状態から導く計算/判定まで
- ❌ `class_exists` ラッパなしでコアエンティティを定義 → ✅ プロキシ拡張に対応するラッパで囲う
- ❌ プロパティ/戻り値の型宣言省略 → ✅ 型を付け、PHPStan level 6 を通す
- ❌ 金額 getter（`Order::getTotal()`・`OrderItem::getTotalPrice()` 等）の戻り値を int/float 扱い → ✅ DECIMAL は `?string`（getter は `string`）。型宣言・代入もこれに合わせる
- ❌ 金額を float で四則演算（丸め誤差）→ ✅ `bcmath`（`bcadd` / `bcmul` / `bccomp`、スケール 2）で計算する
- ❌ `create_date` / `update_date` を自前の `#[ORM\PrePersist]`（＋`#[ORM\HasLifecycleCallbacks]`）でセット → ✅ コアの `SaveEventSubscriber`（グローバル Doctrine prePersist/preUpdate）が `method_exists` で `setCreateDate`/`setUpdateDate`/`setCreator` を自動セットする（`src/Eccube/Doctrine/EventSubscriber/SaveEventSubscriber.php`）。setter さえ生やせばよく、自前 PrePersist は二重実装になるので書かない
- ❌ 他エンティティ（特にコアの `Product`/`Customer` 等、自分で制御できない親）への関連で親削除時の挙動を未決定 → ✅ FK は既定で削除を止める（RESTRICT 相当）。未指定だと**退会・商品削除が FK 違反で失敗**したり孤児化する。`onDelete`（`SET NULL`／`CASCADE`）を指定するか、Service・プラグイン disable 等で後始末する（コアは `onDelete` を限定使用し[95 JoinColumn 中 2 件]、多くは Service 側で関連を整理している）

---

Source: https://www.openparable.com/skill/development/entity (OpenParable). Cite the canonical URL above.
