fusecore

FuseCore 是一种面向 Laravel 13 并集成 React 19 的模块化单体架构，基于自动发现（module.json）、SOLID 原则和模块级隔离（模型、迁移、路由、React 资源、i18n）。 涵盖如何创建新模块、理解 FuseCore 的目录结构和模块发现机制，以及如何在 FuseCore 项目中实现功能，包括模块契约、特征（HasModule）、服务提供者和跨模块依赖声明。

FuseCore 模块化架构

Agent 工作流（必须遵循）

在 FuseCore 项目中进行任何实现之前，必须并行启动 3 个 Agent，每个 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 的模块化单体架构。

组件	用途
Module	自包含功能（User、Dashboard、Blog）
Auto-Discovery	通过 module.json 自动注册
Traits	用于加载资源的 HasModule
Contracts	ModuleInterface、ReactModuleInterface
React Integration	每个模块隔离的 React
i18n	多语言支持（FR/EN/DE/IT/ES）

---

关键规则

1. 所有代码都放在 /FuseCore/{Module}/ 中 - 绝不要放在 /app/ 中
2. 每个模块一个 module.json - 发现模块所必需
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 包含名称、版本和依赖项
• {Module}ServiceProvider.php 使用 HasModule trait
• /Routes/api.php 中包含路由
• /Database/Migrations/ 中包含迁移文件
• /App/Models/ 中包含模型
• /App/Http/Controllers/ 中包含控制器
• /Resources/React/ 中包含 React（如需要）
• /Resources/React/i18n/locales/ 中包含 i18n

---

SOLID 合规性

规则	FuseCore 实现
单一职责	一个模块对应一个功能
开闭原则	通过 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）
• Inertia 3（inertiajs/inertia-laravel ^3.0）用于 React ↔ 模块桥接

模块 ServiceProvider 与 L13

在 register() 中绑定，在 boot() 中注册观察者/钩子。L13 提醒：在模型自身的启动过程中实例化模型（在模型的 boot() 或 trait 的 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-"
}

最佳实践

应做

• 一个模块对应一个完整的 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() 中使用 new static() → L13 中的 LogicException）
• 不要超过每个文件的钩子上限 FUSE_SOLID_MAX_LINES（拆分为子模块或 Service）
• 不要在模块之间共享迁移（每个模块自行管理其表）