fusecore

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

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

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

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

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. モジュールごとに 1 つの module.json - 検出のために必須
3. モジュールごとに ServiceProvider - HasModule トレイトを使用
4. ファイルは 100 行未満 - 90 行で分割（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}/ ディレクトリを作成した
• name、version、dependencies を含む module.json がある
• HasModule トレイトを使用した {Module}ServiceProvider.php がある
• ルートが /Routes/api.php にある
• マイグレーションが /Database/Migrations/ にある
• モデルが /App/Models/ にある
• コントローラーが /App/Http/Controllers/ にある
• 必要に応じて React が /Resources/React/ にある
• i18n が /Resources/React/i18n/locales/ にある

---

SOLID 準拠

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

ファイル制限: すべてのファイルは 100 行未満。90 行で分割します。

---

命名規則

種類	規則	例
モジュールフォルダー	PascalCase	BlogPost
module.json name	PascalCase	"name": "BlogPost"
ServiceProvider	{Module}ServiceProvider	BlogPostServiceProvider
Controller	{Resource}Controller	PostController
Model	単数形	Post
Migration	create_{table}_table	create_posts_table
ルートファイル	api.php	常に api.php

---

Laravel 13 の注意点

スタック FuseCore L13

• Laravel 13 (stable 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)
• Inertia 3 (inertiajs/inertia-laravel ^3.0) を React ↔ モジュール間のブリッジとして使用

モジュール 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 モジュール = 1 つの完全な FuseCore/<Module>/ フォルダー (Contracts/、Services/、Http/、Models/)
• モジュール間のすべての依存関係は 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)
• 1 ファイルあたり 100 行を超える (サブモジュールまたは Services に分割する)
• モジュール間でマイグレーションを共有する (各モジュールが自身のテーブルを所有する)