bagisto-api-develop

Bagisto API パッケージの開発

bagisto-api パッケージ（packages/Webkul/BagistoApi、名前空間 Webkul\BagistoApi）内で作業する場合に使用します。インストール、削除、エンドポイントやリソースの追加・変更、パッケージの動作の修正が対象です。これは作業の指針です。正式な仕様がどこにあるか、破ってはならないルール、詳細なリファレンスへの案内を示します。

重大 — 指示があった場合のみインストール／削除する

パッケージのインストールや削除を自動で行ってはいけません。 パッケージのファイル、composer.json、または Bagisto プロジェクトを検出しても、インストール、再インストール、最適化、アンインストールを行う理由にはなりません。インストール（reference/install.md）または削除（reference/uninstall.md）は、クライアントから明示的に依頼された場合に限り実行してください。また、インストールの場合は、まず Composer（安定版） と Manual（最新版） のどちらの方法を希望するか確認してください。

正式な情報源 — まずこちらを読む

このパッケージには、独自の完全なドキュメントが含まれています。コードを書く前に、該当する箇所を読んでください。ほぼすべてのメニュー／リソースについて、正確な動作、バリデーション、イベント、特記事項がすでに定められています。

情報源	内容
CLAUDE.md（パッケージのルート）	正式な規約と、すべてのエンドポイントのカバレッジ表。リソースごとの判断や特記事項が記載されています。作業対象のリソースについて、まずここを読んでください。
docs/superpowers/specs/	大規模な機能の設計仕様。
CHANGELOG.md	[Unreleased] に記載された、リリース済みの利用者向け変更。
PERFORMANCE.md	キャッシュ／IRI／スキーマ構築のパフォーマンスに関するメモ。
GitHub bagisto/bagisto-api	正式なコードです。パターンを一から書くのではなく、最も近い既存リソースを参考にしてください。
https://api-docs.bagisto.com（および /llms.txt）	利用者向けのリクエスト／レスポンス形式と、全エンドポイントの一覧。

ルール：CLAUDE.md にすでに定められている動作を独自に考案しないでください。 まず、該当するリソース／メニューを検索してください。

リファレンス一覧 — 必要なものを開く

トピック	リファレンスファイル	使用する場面
パッケージのインストール	reference/install.md	クライアントから API のインストール／セットアップを依頼された場合
パッケージの削除	reference/uninstall.md	クライアントからパッケージの削除／アンインストールを依頼された場合
ファイルの配置場所	reference/structure.md	ファイルを追加するとき、適切なディレクトリや基底クラスを探すとき
サーフェス、トランスポート、リソースの宣言	reference/api-structure.md	新しいエンドポイントの設計時、5 ファイルのパターンや機能サーフェスの理解時
コーディング規約とチェックリスト	reference/conventions.md	規約に沿ってリソースを作成／レビューするとき
つまずきやすい点	reference/precautions.md	リリース前に、気付かないうちに問題を引き起こす項目を確認するとき
API で対応すること／しないこと	reference/limitations.md	機能の範囲を決めるとき、「これをサポートするか」を判断するとき
テストとキャッシュサイクル	reference/testing.md	テストを実行／追加するとき、キャッシュ関連のコマンドを確認するとき

5 ファイルのパターン（すべてのリソースの中核）

Model（#[ApiResource] — REST + GraphQL の操作 + OpenAPI ブロック）→ DTO（型付き入力）→ Provider（読み取りパス）→ Processor（書き込みパス）→ lang（src/Resources/lang/en/app.php）。ストアフロントのリソースは src/ 配下、管理者向けリソースは src/Admin/ 配下に配置します。すべての Provider／Processor を BagistoApiServiceProvider::register() でタグ付けしてください。 タグのないものは通知なしに迂回され、404 や誤ったデータにつながります。詳細は reference/api-structure.md と reference/structure.md を参照してください。

2 つの絶対条件

1. REST の変更で GraphQL が壊れることがあります — REST と GraphQL は同じ Provider/Processor を共有しています。**必ずリソースの GraphQL テストを REST テストより先に実行し、変更完了と判断する前にテストが成功していることを確認してください。**これが最も重要なルールです。
2. **Bagisto の管理パネルとの同等性を保ち、機能を上乗せしないでください。**管理 UI の動作をそのまま反映し、コアに機能がない場合は中途半端に拡張せず、わかりやすいエラーでその制限を示してください。reference/limitations.md を参照してください。

それ以外の内容 — 詳細なチェックリスト、優先度順の注意点、テスト／キャッシュ関連のコマンド — は上記のリファレンスに記載されています。推測せず、リファレンスを開いて確認してください。