aureuserp-plugin-builder

プラグインビルダー

既存の plugins/webkul/* モジュールと同じ方法でプラグインを構築するには、次のワークフローに従ってください。

ワークフロー

1. まず references/plugin-patterns.md を読みます。
2. 対象のプラグインと、最も近い関連モジュール（通常は purchases、sales、projects、website、accounts）を調べます。
3. まずサービスプロバイダー（*ServiceProvider）を、PackageServiceProvider と Package チェーンを使って実装または調整します。
4. パネルに応じた登録（admin、customer）を行うプラグインクラス（*Plugin）を実装または調整します。
5. パッケージの Composer 設定があることを確認します（composer.json の PSR-4、extra.laravel.providers、プラグインのファクトリー／シーダーの名前空間）。
6. config/filament-shield.php に ACL の対象を登録します。
7. 生成された権限が正しく解決されるように、src/Policies のポリシーを追加または調整します。
8. 機能フラグや設定が必要な場合は、設定用マイグレーション、設定クラス、設定ページを追加します。
9. パネルとモジュールの範囲に応じて、ダッシュボード、ページ、ウィジェット、クラスター、リソースを追加します。
10. HasTableViews と PresetView を使って、一覧／管理ページにテーブルビューを追加します。
11. プラグインの言語フォルダーの規約とネストされたキーに従って、翻訳を追加または調整します。
12. インストールコマンドを使って、インストールと権限のライフサイクルを確認します。

必須の規約

• 各プラグインのサービスプロバイダーは、Webkul\PluginManager\PackageServiceProvider を継承します。
• Package のメソッドチェーンを使って、パッケージのメタデータを設定します。 name、hasViews、hasTranslations、hasRoute／hasRoutes、hasMigrations、runsMigrations、hasSettings、runsSettings、hasSeeder、hasDependencies、hasInstallCommand、hasUninstallCommand、icon。
• インストール時の依存関係は、次の両方に追加します。 ->hasDependencies([...]) とインストールコマンドの ->installDependencies()。
• 次のプラグインインストールコマンドのパターンを使います。 ->hasInstallCommand(fn (InstallCommand $command) => $command->installDependencies()->runsMigrations()->runsSeeders()) （プラグインにシーダーがない場合は調整します）。
• Panel::configureUsing(fn (Panel $panel) => $panel->plugin(YourPlugin::make())); を使って、プラグインを Filament に登録します。
• プラグインクラスで、インストール状態に応じてプラグインの登録を制御します。 if (! Package::isPluginInstalled($this->getId())) { return; }。
• プラグインパッケージの composer.json に、プラグインの名前空間を示す autoload.psr-4、サービスプロバイダーのエントリーを示す extra.laravel.providers、および使用する場合はプラグインのデータベースファクトリー／シーダーの名前空間が含まれていることを確認します。
• 管理画面とフロントエンドを分ける場合は、register(Panel $panel) でパネル条件を使います。 $panel->when($panel->getId() == 'admin', ...) および／または ... == 'customer'。
• パネル固有のフォルダーから Filament コンポーネントを検出します。 discoverResources、discoverPages、discoverClusters、discoverWidgets。
• リソース／ページの ACL 管理／除外エントリーを config/filament-shield.php に登録します。
• PluginManager\PermissionManager のプラグインキーの命名規則と互換性を保ち、RoleResource／Shield の処理フローを維持します。
• Spatie Laravel Settings を使って設定を管理します。 必要に応じて、database/settings/* に設定用マイグレーションを配置し、src/Settings/* にクラスを配置し、設定 UI として SettingsPage を使います。
• 一覧／管理ページでは、次のようにテーブルビューを使います。 use HasTableViews; を追加し、PresetView エントリーを返す getPresetTableViews(): array を実装します。
• resources/lang/en 以下にプラグインの翻訳構造を使い、UI の領域ごとにキーをネストします（navigation、form.sections、table.columns、table.filters、infolist.sections、actions、notifications）。

管理パネルとフロントパネルの設定

プラグインで両方のパネルが必要な場合は、purchases、website、blogs に合わせます。

• Filament のフォルダーをパネルごとに分けます。 src/Filament/Admin/... および src/Filament/Customer/...。
• プラグインの register() で、以下を行います。
• customer 条件のもとで、カスタマーパネルのリソース／ページ／クラスター／ウィジェットを設定します。
• admin 条件のもとで、管理パネルのリソース／ページ／クラスター／ウィジェットを設定します。
• パネル固有のナビゲーション項目（設定へのショートカットなど）を、表示条件のチェックとともに追加します。
• カスタマー認証の UX が独自仕様の場合（例：website）、プラグイン登録時にパネルの認証ページを設定します。
• フロント／カスタマー向けのエクスペリエンスでは、モジュールがカスタマー向けページを公開する場合、routes/web.php、フロントエンドのビュー、Livewire コンポーネントもパネルの動作に合わせます。

翻訳規約

• プラグインの翻訳ルートは plugins/<vendor>/<plugin>/resources/lang/en にします。
• Filament の配置を翻訳パスにも反映します。 filament/resources/...、filament/admin/...、filament/customer/...、filament/clusters/...、filament/pages/...、filament/widgets/... に加え、必要に応じて models、enums、トップレベルの app.php を使用します。
• リソース／ページの翻訳ファイルの配置を明示します。例：
• resources/lang/en/filament/resources/product.php（リソースレベルのラベル）
• resources/lang/en/filament/resources/product/pages/create-product.php
• resources/lang/en/filament/resources/product/pages/edit-product.php
• resources/lang/en/filament/resources/product/pages/list-products.php
• resources/lang/en/filament/resources/product/pages/view-product.php
• 管理／カスタマーを分ける場合は、パネルのパスの下に配置します。
• resources/lang/en/filament/admin/...
• resources/lang/en/filament/customer/...
• ファイル名はケバブケースにし、リソース／ページ／アクション名と一致させます。
• UI の領域ごとにグループ化した、深くネストされた予測可能な配列を優先します。
• navigation.title、navigation.group
• form.sections.<section>.title
• form.sections.<section>.fieldsets.<fieldset>.title
• form.sections.<section>.fields.<field>.label|helper-text
• table.columns、table.groups、table.filters
• table.record-actions.<action>.notifications.<state>.title|body
• table.toolbar-actions.<action>.notifications.<state>.title|body
• table.empty-state.heading|description
• infolist.sections.<section>.entries.<entry>.label|helper-text
• キーのスペルを統一します（fileters ではなく filters）。
• 翻訳キーは安定させ、コードから __('plugin::path.to.key') を使って参照します。
• __() の使用例：
• リソースラベル：__('products::filament/resources/product.navigation.title')
• ページタイトル：__('products::filament/resources/product/pages/create-product.title')
• フィールドラベル：__('products::filament/resources/product.form.sections.general.fields.name')

ベースリソースとモデルの拡張

ベースモジュールでドメインの動作がすでに定義されている場合は、重複させずに拡張することを優先します。

• ソースプラグイン（accounting、invoices、sales、purchases、contacts、recruitments など）からベース Filament リソースを拡張します。
• 子リソースは差分に絞ります。クラスターの割り当て、ページマップ、軽微なスキーマ／テーブルのオーバーライド、追加アクションなどが対象です。
• モデルでは、プラグイン内のモデル名前空間と既存のトレイト規約（HasFactory、ソフトデリート、ソート可能、該当する場合は権限トレイト）に従います。

ACL、ロール、権限のライフサイクル

• プラグインの config/filament-shield.php で、リソース／ページの権限スコープを定義します。
• クラスター／ページの除外設定を更新し、意図した権限キーだけが生成されるようにします。
• ポリシーメソッドが想定される権限キーと一致することを確認します。
• インストールのライフサイクルで権限が再生成／同期されるようにします（プラグインのインストールコマンドおよび ERP のインストールフロー）。
• ACL の対象範囲を変更する場合は、セキュリティロール管理の UI／ロジックを通じて、ロールへの権限割り当てを検証します。

設定、ダッシュボード、テーブルビュー

• 設定：
• database/settings に設定のマイグレーションを追加します。
• Spatie\LaravelSettings\Settings を継承する設定クラスを追加します。
• Filament\Pages\SettingsPage を継承する設定ページを追加します（一般的には設定の配下にまとめます）。
• ダッシュボード／ページ／ウィジェット：
• カスタムダッシュボード／ページでは、ページシールドのトレイトを使用します。
• ダッシュボードページの getWidgets()／getHeaderWidgets() でウィジェットセットを登録します。
• パネルに適したフォルダーにページ／ウィジェットを配置します。
• テーブルビュー：
• 一覧／管理ページに HasTableViews を追加します。
• PresetView::make(...)->modifyQueryUsing(...) で名前付きのプリセットタブを定義します。
• 該当する場合は、お気に入り／デフォルトのプリセットを使用します。

検証チェックリスト

1. プラグインマネージャーにプラグインが表示され、<plugin>:install --no-interaction でインストールできます。
2. 依存関係が正しい順序で自動インストールされます。
3. 管理者パネルおよび／または顧客パネルのコンポーネントが、意図したパネルにのみ表示されます。
4. Shield の権限に新しいリソース／ページが含まれ、対象外のクラスタ／ページは除外されます。
5. ポリシーが解決され、UI のアクションが認可に従います。
6. 設定が保持され、設定ページが読み込まれます。
7. 権限に関する問題を起こすことなく、ダッシュボードのページ／ウィジェットが表示されます。
8. テーブルのプリセットビューに期待どおりのクエリ動作が適用されます。