fusecore

FuseCore は、`module.json` による自動検出、SOLID 原則、モジュールごとの分離（モデル、マイグレーション、ルート、React リソース、i18n）に基づいて構築された、Laravel 13 と React 19 の統合に対応するモジュラーモノリスアーキテクチャです。 新しいモジュールの作成方法、FuseCore のディレクトリ構造とモジュール検出の仕組み、モジュールのコントラクト、トレイト（HasModule）、サービスプロバイダー、モジュール間の依存関係の宣言など、FuseCore プロジェクト内で機能を実装する方法を解説します。

FuseCore モジュラーアーキテクチャ

エージェントのワークフロー（必須）

FuseCore プロジェクトで実装を行う前に、必ず 3 つのエージェントを並行して起動してください。それぞれ個別の Agent 呼び出しで name を指定します。

1. fuse-ai-pilot:explore-codebase - /FuseCore/ 内の既存モジュールを分析します
2. fuse-ai-pilot:research-expert - Context7 を使用して Laravel 13 のパターンを検証します
3. fuse-laravel:laravel-expert - Laravel のベストプラクティスを適用します

実装後、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

FuseCore は、Laravel 13 と React 19 の統合に対応するモジュラーモノリスアーキテクチャです。

コンポーネント	目的
モジュール	独立した機能（User、Dashboard、Blog）
自動検出	module.json による自動登録
トレイト	リソース読み込み用の HasModule
コントラクト	ModuleInterface、ReactModuleInterface
React 統合	モジュールごとに分離された React
i18n	多言語サポート（FR/EN/DE/IT/ES）

---

重要なルール

1. すべてのコードは /FuseCore/{Module}/ 内に配置します - /app/ 内には配置しません
2. 各モジュールに module.json を 1 つ配置します - 検出に必須です
3. モジュールごとに ServiceProvider を用意します - HasModule トレイトを使用します
4. ファイルは FUSE_SOLID_MAX_LINES 以下にします - 長いファイルは分割します（SOLID）
5. インターフェースは /App/Contracts/ 内に配置します - コンポーネント内には配置しません
6. マイグレーションはモジュール内に配置します - /Database/Migrations/
7. ルートはモジュール内に配置します - /Routes/api.php

---

アーキテクチャの概要

FuseCore/
├── Core/                    # Infrastructure (priority 0)
│   ├── App/
│   │   ├── Contracts/       # ModuleInterface, ReactModuleInterface
│   │   ├── Services/        # ModuleDiscovery, RouteAggregator
│   │   ├── Traits/          # HasModule, HasModuleDatabase
│   │   └── Providers/       # FuseCoreServiceProvider
│   ├── Config/fusecore.php
│   └── module.json
│
├── User/                    # Auth module
│   ├── App/Models/          # User.php, Profile.php
│   ├── Config/              # Module config (sanctum.php, etc.)
│   ├── Database/Migrations/
│   ├── Resources/React/     # Isolated React
│   ├── Routes/api.php
│   └── module.json          # dependencies: []
│
└── {YourModule}/            # Your new module
    ├── App/
    │   ├── Models/
    │   ├── Http/Controllers/
    │   ├── Services/
    │   └── Providers/{YourModule}ServiceProvider.php
    ├── Config/              # Module-specific config
    ├── Database/Migrations/
    ├── Resources/React/
    ├── Routes/api.php
    └── module.json          # dependencies: ["User"]

---

リファレンスガイド

アーキテクチャ

トピック	リファレンス	参照するタイミング
概要	architecture.md	FuseCore の設計を理解するとき
モジュール構造	module-structure.md	ディレクトリ構成を確認するとき
自動検出	module-discovery.md	モジュールの読み込み方法を確認するとき
module.json	module-json.md	モジュールの設定を確認するとき

実装

トピック	リファレンス	参照するタイミング
コントラクト	contracts.md	ModuleInterface、ReactModuleInterface を確認するとき
トレイト	traits.md	HasModule、HasModuleDatabase を確認するとき
ServiceProvider	service-provider.md	モジュールの登録を確認するとき
ルート	routes.md	API ルーティングを確認するとき

リソース

トピック	リファレンス	参照するタイミング
React 統合	react-integration.md	モジュールごとのフロントエンドを確認するとき
マイグレーション	migrations.md	モジュールごとのデータベースを確認するとき
i18n	i18n.md	多言語設定を確認するとき

ガイド

トピック	リファレンス	参照するタイミング
モジュールの作成	creating-module.md	手順に沿って作成するとき

---

テンプレート（コード例）

テンプレート	目的
module.json.md	モジュール設定
ServiceProvider.php.md	モジュールのサービスプロバイダー
Controller.php.md	API コントローラー
Model.php.md	Eloquent モデル
Migration.php.md	データベースマイグレーション
ReactStructure.md	React モジュール構造
ApiRoutes.php.md	API ルートファイル
Resource.php.md	API リソース
Request.php.md	フォームリクエスト
Service.php.md	ビジネスロジックサービス

---

クイックリファレンス

新しいモジュールの作成

# 1. Create directory structure
mkdir -p FuseCore/{ModuleName}/{App/{Models,Http/Controllers,Services,Providers},Database/Migrations,Resources/React,Routes}

# 2. Create module.json
# 3. Create ServiceProvider with HasModule trait
# 4. Create routes/api.php
# 5. Run: php artisan fusecore:cache-clear

module.json

{
    "name": "ModuleName",
    "version": "1.0.0",
    "enabled": true,
    "isCore": false,
    "dependencies": ["User"]
}

ServiceProvider

class ModuleNameServiceProvider extends ServiceProvider
{
    use HasModule;

    public function boot(): void
    {
        $this->loadModuleMigrations();
    }
}

ルート

Route::middleware(['api', 'auth:sanctum'])->group(function () {
    Route::apiResource('items', ItemController::class);
});

---

モジュールのチェックリスト

• /FuseCore/{Module}/ ディレクトリを作成済み
• 名前、バージョン、依存関係を記述した module.json
• HasModule トレイトを含む {Module}ServiceProvider.php
• /Routes/api.php にルートを設定
• /Database/Migrations/ にマイグレーションを配置
• /App/Models/ にモデルを配置
• /App/Http/Controllers/ にコントローラーを配置
• /Resources/React/ に React を配置（必要な場合）
• /Resources/React/i18n/locales/ に i18n を配置

---

SOLID 準拠

ルール	FuseCore の実装
単一責任	1 つのモジュールにつき 1 つの機能
開放／閉鎖	ModuleInterface を介して拡張
リスコフの置換	ReactModuleInterface extends ModuleInterface
インターフェース分離	コントラクトを分離
依存性逆転	ServiceProvider を介して注入

ファイルの上限：すべてのファイルを FUSE_SOLID_MAX_LINES 以内に収めてください。上限に達するかなり前に分割してください。

---

命名規則

種類	規則	例
モジュールフォルダー	PascalCase	BlogPost
module.json の名前	PascalCase	"name": "BlogPost"
ServiceProvider	{Module}ServiceProvider	BlogPostServiceProvider
コントローラー	{Resource}Controller	PostController
モデル	単数形	Post
マイグレーション	create_{table}_table	create_posts_table
ルートファイル	api.php	常に api.php

---

Laravel 13 に関する注意事項

FuseCore L13 のスタック

• Laravel 13（安定版 13.33）+ 最低 PHP 8.3
• React 19 + TypeScript 7（モジュールのフロントエンド側）— TS 7.0 にはコンパイラー API がありません。typescript-eslint（peer typescript <6.1.0）にはエイリアス "typescript": "npm:@typescript/typescript6@^6.0.2" + "@typescript/native": "npm:typescript@^7.0.2" が必要です（npx tsc = 7.0）
• React とモジュール間のブリッジには Inertia 3（inertiajs/inertia-laravel ^3.0）を使用

モジュールの ServiceProvider と L13

バインディングは register() に、オブザーバー／フックは boot() に記述します。L13 に関する注意：モデルの自身の boot 中（モデルの boot() またはトレイトの boot*() 内での new static()）にモデルをインスタンス化すると、LogicException がスローされます。

public function register(): void
{
    $this->app->bind(PostRepositoryContract::class, EloquentPostRepository::class);
}

public function boot(): void
{
    Post::observe(PostObserver::class);
}

モジュールごとのキャッシュプレフィックス

L13 では、デフォルトでハイフンが使用されます。FuseCore では、module.json を介してモジュールごとにプレフィックスを設定しても、引き続き互換性があります。

{
  "name": "BlogPost",
  "cache_prefix": "blogpost-"
}

ベストプラクティス

推奨事項

• 1 つのモジュールを、FuseCore/<Module>/（Contracts/、Services/、Http/、Models/）の完全なフォルダー 1 つにまとめます
• モジュール間の依存関係はすべて Contracts を介して宣言します（具象クラスは使用しません）
• モジュールの DTO には final readonly class を使用します（PHP 8.3 以降）
• Model のロジックをすべて register() から boot() に移します
• UI を持つモジュールには Inertia 3 + React 19 を優先します

してはいけないこと

• Contract を介さずに、別のモジュールからクラスをインポートしないでください
• Controller にビジネスロジックを記述しないでください（モジュールの Service に切り出してください）
• モデル自身の boot 中にインスタンス化しないでください（boot() 内の new static() → L13 で LogicException）
• ファイルごとのフック上限 FUSE_SOLID_MAX_LINES を超えないでください（サブモジュールまたは Service に分割してください）
• モジュール間でマイグレーションを共有しないでください（各モジュールが自身のテーブルを管理します）