aureuserp-api-builder

API ビルダー

共有されている AureusERP プラグインの規約に準拠した API を生成するには、次のワークフローに従ってください。

ワークフロー

1. 規約のリファレンスを読みます：references/api-conventions.md。
2. 対象のプラグインモジュールを調査します（モデル、既存のポリシー、既存のルート、Filament リソース／ページ）。
3. API クラスを生成する前に、Filament リソースを分析します：

• Filament のページとアクションから、ワークフロー／状態遷移を把握します（作成／編集／表示／一覧表示およびカスタムアクション）
• 条件付き必須項目やネストされたリピーターを含め、Filament のフォーム／コンポーネントからバリデーションルールを抽出します
• ユーザーが編集できるフィールドのみを対象に、リクエストペイロードのフィールド定義を作成します（読み取り専用／計算済み／システム管理のフィールドは除外）
• モジュールが別のプラグインのリソースを拡張している場合は、親 Filament リソース／クラスを特定します
• 任意のプラグイン依存関係を特定します：別のプラグインがインストールされている場合にのみ存在するカラム、リレーション、または機能を検出します（Schema::hasTable または Schema::hasColumn ガードを使用した条件付きマイグレーションを確認します）

4. 次の順序で API ファイルを実装します：

• routes/api.php のルートエントリ
• src/Http/Controllers/API/V1 のコントローラー
• src/Http/Requests のフォームリクエスト
• src/Http/Resources/V1 のリソース
• ソフトデリートを使用する場合はポリシーメソッド（restore、forceDelete）

5. Filament／API クラスが別のプラグインの親クラスを拡張している場合は、生成する API クラスでも同じ継承関係を再現します：

• 同じ API の概念に対応する親プラグインのリクエストクラスが利用可能な場合、生成するリクエストクラスはそれを拡張する必要があります
• 同じ API の概念に対応する親プラグインの HTTP リソースクラスが利用可能な場合、生成する HTTP リソースクラスはそれを拡張する必要があります
• 親のバリデーション／シリアライズロジックの重複を避けるため、子クラスはプラグイン固有の差分に集中させます

6. 対象プラグインの既存 API に合わせて、命名とレスポンスメッセージを統一します。
7. ルートの登録を確認し、該当するテストがあれば実行して検証します。
8. コメントは関数定義の直前にのみ記述します。関数本体内にはコメントを記述しないでください。

必須規約

• ルートグループのパターンには、Route::name('admin.api.v1.<plugin>.')->prefix('admin/api/v1/<plugin>')->middleware(['auth:sanctum'])->group(...) を使用してください。
• ソフトデリート可能なリソースには Route::softDeletableApiResource(...) を使用し、コントローラーに restore() と forceDestroy() を実装してください。
• コントローラーとエンドポイントでは、Scribe の PHP 属性（Group、Subgroup、Authenticated、Endpoint、QueryParam、UrlParam、Response、ResponseFromApiResource）を使用してください。
• 各エンドポイントで Gate::authorize(...) を使用してください。
• Spatie\QueryBuilder\QueryBuilder を使用し、allowedFilters、allowedSorts、allowedIncludes を明示してください。
• CRUD のレスポンスには API リソースを返してください。削除および完全削除の成功レスポンスには JSON { "message": "..." } を返してください。
• FormRequest では、検証ルールを常に配列で定義してください（例：['required', 'email']）。パイプ区切り文字列は使用しないでください。
• 更新処理（PUT／PATCH）では、$isUpdate = $this->isMethod('PUT') || $this->isMethod('PATCH'); を定義し、ルール変換ループの代わりに、フィールドごとの三項演算子によるルールエントリーを使用してください（例：$isUpdate ? ['sometimes', 'required'] : ['required']）。
• 'in:...' 文字列を組み立てる代わりに、ルール配列内でルールオブジェクトを使って列挙型を検証してください（例：Rule::enum(Status::class)）。
• すべての FormRequest で部分更新を一貫してサポートしてください。作成時に必須のフィールドは、意図的に変更不可とされている場合を除き、更新時には $isUpdate ? ['sometimes', 'required'] : ['required'] にしてください。
• FormRequest では、対応する Filament フォームのワークフローで書き込み可能なペイロードフィールドのみを公開してください。システムで計算される列、読み取り専用の列、非表示の列、ライフサイクルで管理される列は受け付けたり、ドキュメントに記載したりしないでください。
• ネストされた明細配列にも、同じ書き込み可能フィールドのみというルールを適用してください。ユーザーが編集できるフィールドのみを含め、Filament で明示的に編集可能でない限り、計算済み合計、マージン、ステータスフィールド、サーバー由来の関連付け列は検証またはドキュメント化しないでください。
• FormRequest のルールは、Filament を包括的に分析したうえで導出してください。ワークフロー固有の要件、条件付き検証、ネストされたペイロード構造、アクション固有の書き込み可能フィールドを含めてください。
• モジュールが別のプラグインの Filament／リソースクラスを拡張する場合、生成するリクエストクラスは、親プラグインの対応するリクエストクラスが存在すれば、それを継承してください。子プラグインでは、差分に必要なルールの追加または上書きのみを行ってください。
• ドキュメント用に bodyParameters() を含め、例には書き込み可能なフィールドのみを使用してください。
• JsonResource にはスカラーの ID／タイムスタンプと、whenLoaded(...) による条件付きのリレーションを含めてください。
• モジュールが別のプラグインの Filament／リソースクラスを拡張する場合、生成する HTTP リソースクラスは、親プラグインの対応する HTTP リソースクラスが存在すれば、それを継承してください。子クラスには、プラグイン固有のシリアライズフィールド／リレーションのみを追加してください。
• プラグイン依存関係の処理：コントローラーのアクションが任意のプラグインの機能（たとえば inventories プラグインの配送処理）に依存する場合は、Package::isPluginInstalled('<plugin>') で実行をガードし、プラグインが存在しない場合は、問題なく処理できる空またはデフォルトのレスポンスを返してください。存在しない可能性があるテーブルへのクエリにリクエストが到達しないようにしてください。

参照ファイル

• references/api-conventions.md：規約および実装チェックリストの標準資料。