fusecore

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FuseCore Modular Architecture

FuseCore模块化架构

Agent Workflow (MANDATORY)

Agent工作流程（强制要求）

Before ANY implementation in FuseCore project, use

TeamCreate

to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Analyze existing modules in
```
/FuseCore/
```
fuse-ai-pilot:research-expert - Verify Laravel 12 patterns via Context7
fuse-laravel:laravel-expert - Apply Laravel best practices

After implementation, run fuse-ai-pilot:sniper for validation.

在FuseCore项目中进行任何开发之前，使用

TeamCreate

生成3个Agent：

fuse-ai-pilot:explore-codebase - 分析
```
/FuseCore/
```
中的现有模块
fuse-ai-pilot:research-expert - 通过Context7验证Laravel 12模式
fuse-laravel:laravel-expert - 应用Laravel最佳实践

开发完成后，运行fuse-ai-pilot:sniper进行验证。

Overview

概述

FuseCore is a Modular Monolith architecture for Laravel 12 with React 19 integration.

Component	Purpose
Module	Self-contained feature (User, Dashboard, Blog)
Auto-Discovery	Automatic registration via `module.json`
Traits	`HasModule` for resource loading
Contracts	`ModuleInterface` , `ReactModuleInterface`
React Integration	Isolated React per module
i18n	Multi-language support (FR/EN/DE/IT/ES)

FuseCore是一款针对Laravel 12的模块化单体架构，集成了React 19。

组件	用途
Module	独立封装的功能模块（如用户、仪表盘、博客）
Auto-Discovery	通过 `module.json` 自动注册模块
Traits	`HasModule` 用于资源加载
Contracts	`ModuleInterface` 、 `ReactModuleInterface`
React集成	为每个模块提供独立的React环境
i18n	多语言支持（法语/英语/德语/意大利语/西班牙语）

Critical Rules

核心规则

All code in
/FuseCore/{Module}/
- Never in
```
/app/
```
One module.json per module - Required for discovery
ServiceProvider per module - Use
```
HasModule
```
trait
Files < 100 lines - Split at 90 lines (SOLID)
Interfaces in
/App/Contracts/
- Never in components
Migrations in module -
```
/Database/Migrations/
```
Routes in module -
```
/Routes/api.php
```

所有代码必须放在
/FuseCore/{Module}/
目录下 - 严禁存放在
```
/app/
```
中
每个模块必须包含一个
module.json
文件 - 是模块自动发现的必要条件
每个模块对应一个ServiceProvider - 使用
```
HasModule
```
trait
单个文件代码行数不超过100行 - 建议在90行时拆分（遵循SOLID原则）
Interfaces必须放在
/App/Contracts/
目录下 - 严禁放在组件内部
数据库迁移文件放在模块目录内 - 路径为
```
/Database/Migrations/
```
路由定义在模块目录内 - 路径为
```
/Routes/api.php
```

Architecture Overview

架构概览

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"]

FuseCore/
├── Core/                    # 基础设施（优先级0）
│   ├── App/
│   │   ├── Contracts/       # ModuleInterface, ReactModuleInterface
│   │   ├── Services/        # ModuleDiscovery, RouteAggregator
│   │   ├── Traits/          # HasModule, HasModuleDatabase
│   │   └── Providers/       # FuseCoreServiceProvider
│   ├── Config/fusecore.php
│   └── module.json
│
├── User/                    # 认证模块
│   ├── App/Models/          # User.php, Profile.php
│   ├── Config/              # 模块配置文件（如sanctum.php等）
│   ├── Database/Migrations/
│   ├── Resources/React/     # 独立的React环境
│   ├── Routes/api.php
│   └── module.json          # dependencies: []
│
└── {YourModule}/            # 你的新模块
    ├── App/
    │   ├── Models/
    │   ├── Http/Controllers/
    │   ├── Services/
    │   └── Providers/{YourModule}ServiceProvider.php
    ├── Config/              # 模块专属配置
    ├── Database/Migrations/
    ├── Resources/React/
    ├── Routes/api.php
    └── module.json          # dependencies: ["User"]

Reference Guide

参考指南

Architecture

架构

Topic	Reference	When to consult
Overview	architecture.md	Understanding FuseCore design
Module Structure	module-structure.md	Directory organization
Auto-Discovery	module-discovery.md	How modules are loaded
module.json	module-json.md	Module configuration

主题	参考文档	适用场景
概述	architecture.md	理解FuseCore设计理念
模块结构	module-structure.md	目录组织规范
自动发现	module-discovery.md	模块加载机制说明
module.json	module-json.md	模块配置说明

Implementation

开发实现

Topic	Reference	When to consult
Contracts	contracts.md	ModuleInterface, ReactModuleInterface
Traits	traits.md	HasModule, HasModuleDatabase
ServiceProvider	service-provider.md	Module registration
Routes	routes.md	API routing

主题	参考文档	适用场景
Contracts	contracts.md	ModuleInterface、ReactModuleInterface说明
Traits	traits.md	HasModule、HasModuleDatabase说明
ServiceProvider	service-provider.md	模块注册说明
路由	routes.md	API路由配置

Resources

资源

Topic	Reference	When to consult
React Integration	react-integration.md	Frontend per module
Migrations	migrations.md	Database per module
i18n	i18n.md	Multi-language setup

主题	参考文档	适用场景
React集成	react-integration.md	模块前端React开发
数据库迁移	migrations.md	模块数据库迁移配置
i18n	i18n.md	多语言设置

Guides

实操指南

Topic	Reference	When to consult
Creating Module	creating-module.md	Step-by-step guide

主题	参考文档	适用场景
创建新模块	creating-module.md	分步创建模块指南

Templates (Code Examples)

模板（代码示例）

Template	Purpose
module.json.md	Module configuration
ServiceProvider.php.md	Module service provider
Controller.php.md	API controller
Model.php.md	Eloquent model
Migration.php.md	Database migration
ReactStructure.md	React module structure
ApiRoutes.php.md	API routes file
Resource.php.md	API Resource
Request.php.md	Form Request
Service.php.md	Business logic service

模板	用途
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	业务逻辑服务模板

Quick Reference

快速参考

Create New Module

创建新模块

bash

undefined

bash

undefined

1. Create directory structure

1. 创建目录结构

mkdir -p FuseCore/{ModuleName}/{App/{Models,Http/Controllers,Services,Providers},Database/Migrations,Resources/React,Routes}

2. Create module.json

2. 创建module.json文件

3. Create ServiceProvider with HasModule trait

3. 创建带有HasModule trait的ServiceProvider

4. Create routes/api.php

4. 创建routes/api.php文件

5. Run: php artisan fusecore:cache-clear

5. 运行：php artisan fusecore:cache-clear

undefined

undefined

module.json

module.json示例

json

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

json

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

ServiceProvider

ServiceProvider示例

php

class ModuleNameServiceProvider extends ServiceProvider
{
    use HasModule;

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

php

class ModuleNameServiceProvider extends ServiceProvider
{
    use HasModule;

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

Routes

路由示例

php

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

php

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

Module Checklist

模块检查清单

```
/FuseCore/{Module}/
```
directory created
```
module.json
```
with name, version, dependencies
```
{Module}ServiceProvider.php
```
with
```
HasModule
```
trait
Routes in
```
/Routes/api.php
```
Migrations in
```
/Database/Migrations/
```
Models in
```
/App/Models/
```
Controllers in
```
/App/Http/Controllers/
```
React in
```
/Resources/React/
```
(if needed)
i18n in
```
/Resources/React/i18n/locales/
```

已创建
```
/FuseCore/{Module}/
```
目录
已创建包含名称、版本、依赖的
```
module.json
```
文件
已创建带有
```
HasModule
```
trait的
```
{Module}ServiceProvider.php
```
文件
已在
```
/Routes/api.php
```
中定义路由
已在
```
/Database/Migrations/
```
中放置迁移文件
已在
```
/App/Models/
```
中放置模型文件
已在
```
/App/Http/Controllers/
```
中放置控制器文件
已在
```
/Resources/React/
```
中配置React（如有需要）
已在
```
/Resources/React/i18n/locales/
```
中配置多语言

SOLID Compliance

SOLID原则合规性

Rule	FuseCore Implementation
Single Responsibility	One module = one feature
Open/Closed	Extend via `ModuleInterface`
Liskov Substitution	`ReactModuleInterface extends ModuleInterface`
Interface Segregation	Separate contracts
Dependency Inversion	Inject via ServiceProvider

File limits: All files < 100 lines. Split at 90.

原则	FuseCore实现方式
单一职责原则	一个模块对应一个功能
开闭原则	通过 `ModuleInterface` 实现扩展
里氏替换原则	`ReactModuleInterface` 继承自 `ModuleInterface`
接口隔离原则	使用独立的契约接口
依赖倒置原则	通过ServiceProvider实现依赖注入

文件行数限制：所有文件代码行数不超过100行，建议在90行时拆分。

Naming Conventions

命名规范

Type	Convention	Example
Module folder	PascalCase	`BlogPost`
module.json name	PascalCase	`"name": "BlogPost"`
ServiceProvider	`{Module}ServiceProvider`	`BlogPostServiceProvider`
Controller	`{Resource}Controller`	`PostController`
Model	Singular	`Post`
Migration	`create_{table}_table`	`create_posts_table`
Routes file	`api.php`	Always `api.php`

类型	规范	示例
模块目录	大驼峰命名（PascalCase）	`BlogPost`
module.json中的name字段	大驼峰命名（PascalCase）	`"name": "BlogPost"`
ServiceProvider	`{Module}ServiceProvider`	`BlogPostServiceProvider`
控制器	`{Resource}Controller`	`PostController`
模型	单数形式	`Post`
迁移文件	`create_{table}_table`	`create_posts_table`
路由文件	固定为 `api.php`	始终使用 `api.php`