README

基于 Laravel 12.0 的快速业务原型开发框架

概述

Luna Prototype 是一个基于 Laravel 12.0 和 PHP 8.4 的模块化快速业务原型开发框架。框架的核心理念是减少不必要的重复功能开发，通过提供相对原子化的组件，让开发者可以根据具体业务需求进行扩展、调整和组合使用。

设计理念

原子化组件: 每个模块都设计为功能单一、职责明确的原子化组件，可独立使用
避免重复开发: 提供常见业务场景的基础实现，减少从零开始的重复工作
灵活组合: 模块间松耦合，可根据项目需求自由组合和扩展
渐进式集成: 可以选择性地集成需要的模块，不强制使用全套功能
扩展优先: 通过处理器模式、配置系统等机制，优先支持扩展而非修改核心代码

Luna Prototype 特别适合快速原型开发、概念验证、初创项目和需要快速迭代的业务场景。

主要特性

基础架构特性

原子化模块架构: 每个模块都是独立的原子化组件，可按需选择和组合
配置管理系统: 支持版本控制的灵活配置存储和管理机制
处理器扩展模式: 基于处理器的业务逻辑扩展点，支持插件化开发
业务事件系统: 业务操作事件定义和用户友好的描述格式化机制
异常处理机制: 统一的异常定义、映射和处理框架
安装器框架: 模块化的安装流程管理
备份恢复机制: 应用状态的备份和恢复功能

业务组件特性

资产账户系统: 提供多层级账户类型、余额管理、原子化操作等功能
交易系统: 完整的交易流程管理，包括订单、支付、退款等功能
会员体系框架: 可扩展的会员等级、里程碑系统和权益管理
权限系统: 基于策略的权限管理，支持角色、用户组和灵活的权限分配
单位转换系统: 支持多种单位类型转换，包括货币、度量衡等，支持动态汇率
对象持有系统: 灵活的对象持有关系管理，支持签到、购买限制、抽奖等场景
调度任务系统: 灵活的定时任务和后台作业管理框架
UI组件抽象层: 前端无关的表单字段和数据展示组件抽象

原子化组件优势

按需使用

// 只需要账户系统
class AppServiceProvider extends LunaServiceProvider 
{
    public function customRegister(): void 
    {
        $this->registerModule(LunaAssetsAccountConfigure::create()->build());
    }
}

// 需要完整功能
class AppServiceProvider extends LunaServiceProvider 
{
    public function customRegister(): void 
    {
        $this->registerModule(LunaAssetsAccountConfigure::create()->build());
        $this->registerModule(LunaScheduleConfigure::create()->build());
        $this->registerModule(LunaMembershipConfigure::create()->build());
        $this->registerModule(LunaUnitConversionConfigure::create()->build());
        $this->registerModule(LunaTradeConfigure::create()->build());
        $this->registerModule(LunaHoldingObjectConfigure::create()->build());
        $this->registerModule(LunaPermissionConfigure::create()->build());
    }
}

灵活扩展

// 扩展账户类型处理器
$this->extendModule(function() {
    return LunaHandlerConfigure::create()
        ->group('account_handlers', '账户处理器', function($register) {
            $register->handler(CryptoWalletHandler::class);
            $register->handler(PointsHandler::class);
            $register->handler(CouponHandler::class);
        })
        ->build();
});

// 自定义业务事件格式化
$this->extendModule(function() {
    return LunaBusinessEventConfigure::create()
        ->group('payment_events', '支付事件', function($register) {
            $register->handler(PaymentEventHandler::class);
        })
        ->build();
});

核心概念

模块组件（Module）

Luna Prototype 的核心是组件化设计。每个组件都是一个完整、独立的功能单元模块，具有清晰的职责边界和标准化的结构。

组件的标准结构

每个 Luna 组件通常包含三个核心部分：

配置器（Configure） - 组件的核心，负责服务注册、依赖管理和组件配置
访问入口类（Module） - 组件的业务逻辑封装和 API 接口
服务提供者（ServiceProvider） - 资源发布器（可选）

// 组件的典型结构
namespace Dybasedev\LunaPrototype\YourComponent;

// 1. 配置器 - 处理组件的注册和启动逻辑
class LunaYourComponentConfigure extends LunaModuleConfigure { }

// 2. 访问入口类 - 提供组件的业务 API
class LunaYourComponent extends LunaModule { }

// 3. 服务提供者 - 负责资源文件的发布
class LunaYourComponentServiceProvider extends ServiceProvider { }

组件的概念

组件是 Luna Prototype 的基本构建单元，每个组件：

独立性：可以独立安装、配置和使用
原子性：专注于单一的业务领域或功能
可组合：可以与其他组件自由组合使用
可扩展：提供标准化的扩展点和配置选项

组件的配置器（Luna Module Configure）

配置器是组件的核心，继承自 LunaModuleConfigure 基类，负责：

定义组件身份

class LunaAssetsAccountConfigure extends LunaModuleConfigure
{
    public function name(): string
    {
        return 'luna.assets-account';  // 组件唯一标识
    }
    
    public function dependencies(): array
    {
        return ['luna.foo'];  // 声明依赖的其他组件，此处仅作演示
    }
}

配置选项管理

class LunaAssetsAccountConfigure extends LunaModuleConfigure
{
    // 配置属性
    protected(set) string $accountModel = AssetsAccount::class;
    protected(set) string $accountTypeModel = AssetsAccountType::class;
    
    // 配置方法（流式接口，且强烈建议使用该方式）
    public function useAccountModel(string $class): static
    {
        $this->accountModel = $class;
        return $this;
    }
}

服务注册

配置器负责组件的服务注册，这是 Luna Prototype 的一个重要设计理念：

public function register(Container $container): void
{
    // 注册单例服务
    $container->singleton('luna.assets-account', function ($app) {
        return new LunaAssetsAccount(
            $this,
            $app->make('cache.store'),
            $app->make(LunaHandler::class)
        );
    });
    
    // 注册别名
    $container->alias('luna.assets-account', LunaAssetsAccount::class);
}

重要：与传统 Laravel 包不同，Luna 组件的 register() 和 boot() 逻辑都在配置器（Configure）类中实现，而不是在服务提供者中。

服务提供者的作用

在 Luna Prototype 中，服务提供者（ServiceProvider）专注于资源文件的发布，这是它的主要职责：

class LunaAssetsAccountServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // 发布数据库迁移文件
        $this->publishesMigrations([
            __DIR__ . '/migrations' => database_path('migrations'),
        ]);
        
        // 如果组件有配置文件、语言文件等其他资源
        // $this->publishes([
        //     __DIR__ . '/config/assets-account.php' => config_path('luna/assets-account.php'),
        // ], 'luna-assets-account-config');
        
        // $this->publishes([
        //     __DIR__ . '/lang' => lang_path('luna/assets-account'),
        // ], 'luna-assets-account-lang');
    }
}

为什么要分离服务提供者？

清晰的发布管理：使用 php artisan vendor:publish 时，可以清楚地看到每个组件可发布的资源
按需发布：开发者可以选择性地发布特定组件的资源文件
保持配置器纯粹：配置器专注于组件逻辑，服务提供者专注于资源发布

使用资源发布

# 查看可发布的资源
php artisan vendor:publish

# 发布特定组件的迁移文件
php artisan vendor:publish --provider="Dybasedev\LunaPrototype\AssetsAccount\LunaAssetsAccountServiceProvider"

# 使用标签发布（如果定义了标签）
php artisan vendor:publish --tag=luna-trade-migrations

组件的访问入口类

访问入口类继承自 LunaModule 基类，提供组件的主要 API 接口：

class LunaAssetsAccount extends LunaModule
{
    // 提供业务方法
    public function createAccountType(
        string $name,
        string $handler,
        ?string $displayName = null
    ): AssetsAccountType {
        // 业务逻辑实现
    }
    
    // 获取用户账户
    public function ownerAccount(
        Model $owner,
        string $accountType
    ): AssetsAccount {
        // 业务逻辑实现
    }
}

访问组件的三种方式：

// 1. 依赖注入
public function __construct(LunaAssetsAccount $assetsAccount) { }

// 2. 服务容器
$assetsAccount = app('luna.assets-account');

// 3. 辅助函数
$assetsAccount = luna_assets_account();

组件的注册流程

Luna Prototype 采用了独特的组件注册机制，通过继承 LunaServiceProvider 来管理所有组件：

// app/Providers/AppServiceProvider.php
class AppServiceProvider extends LunaServiceProvider
{
    public function customRegister(): void
    {
        // 注册组件
        $this->registerModule(
            LunaAssetsAccountConfigure::create()
                ->useAccountModel(CustomAccount::class)  // 自定义配置
                ->build()
        );
        
        // 扩展现有组件
        $this->extendModule(function() {
            return LunaHandlerConfigure::create()
                ->group('payment', '支付处理器', function($register) {
                    $register->handler(AlipayHandler::class);
                })
                ->build();
        });
    }
}

注册流程详解

继承 LunaServiceProvider：您的 AppServiceProvider 需要继承 LunaServiceProvider 而不是 Laravel 的 ServiceProvider
配置组件：在 customRegister() 方法中使用 registerModule() 注册需要的组件
自动注册服务提供者：框架会自动注册组件配置器中声明的 ServiceProvider，无需手动添加到 config/app.php
处理依赖关系：框架自动检查组件间的依赖关系，确保正确的加载顺序
执行生命周期方法：依次执行配置器的 register() 方法、ServiceProvider 的注册、配置器的 boot() 方法

自动服务提供者注册机制

Luna Prototype 的一个重要特性是自动注册服务提供者，这大大减少了业务开发者的样板代码：

// 在组件的配置器中声明服务提供者
class LunaAssetsAccountConfigure extends LunaModuleConfigure
{
    public function serviceProvider(): ?string
    {
        return LunaAssetsAccountServiceProvider::class;
    }
}

// LunaServiceProvider 会自动注册这个服务提供者
// 无需在 config/app.php 中手动添加！

这样设计的优势：

减少配置：无需手动维护 config/app.php 中的服务提供者列表
保持一致性：组件的所有相关配置都在配置器中管理
避免遗漏：不会因为忘记注册服务提供者而导致资源无法发布

Foundation 组件概要

Foundation 是 Luna Prototype 的基础组件，所有其他组件都依赖于它。它提供了整个框架的核心基础设施。

主要功能

Handler（处理器系统）：统一的处理器注册和执行机制
Configuration（配置管理）：灵活的配置存储和版本控制
BusinessEvent（业务事件）：业务操作的事件定义和格式化
Exception（异常处理）：统一的异常定义和处理机制
Installation（安装器）：模块化的安装流程管理
Backupable（备份恢复）：应用状态的备份和恢复

→ Foundation 详细文档

核心类

// 处理器管理
$handler = luna_handler();
$handlerInstance = $handler->createHandlerInstance('payment-handler');
$result = $handlerInstance->process($data);

// 配置管理
$config = luna_configuration();
$appGroup = $config->group('app');
$appGroup->set('settings.theme', 'dark');
$appGroup->save();

// 业务事件
$event = luna_business_event();
$message = $event->eventMessage('user.login', ['user' => 'Alice']);

Foundation 组件是其他所有组件的基石，提供了标准化的扩展点和基础服务。

系统要求

PHP 8.4+
Laravel 12.0+
支持的数据库: MySQL, PostgreSQL, SQLite

安装

通过 Composer 安装：

composer require dybasedev/luna-prototype

快速开始

1. 基础配置

修改 Laravel 项目中的 AppServiceProvider 继承 LunaServiceProvider：

// app/Providers/AppServiceProvider.php
<?php

namespace App\Providers;

use Dybasedev\LunaPrototype\Foundation\LunaServiceProvider;

class AppServiceProvider extends LunaServiceProvider
{
    /**
     * 自定义模块注册
     */
    public function customRegister(): void
    {
        // 注册需要的组件
        // $this->registerModule(
        //     LunaAssetsAccountConfigure::create()->build()
        // );
    }

    /**
     * 自定义启动逻辑
     */
    public function customBoot(): void
    {
        // 自定义启动逻辑
    }
}

2. 发布和运行迁移文件

Luna Prototype 会自动注册组件的服务提供者，无需手动在 config/app.php 中添加：

# 发布组件的迁移文件
php artisan vendor:publish --provider="Dybasedev\LunaPrototype\AssetsAccount\LunaAssetsAccountServiceProvider"

# 运行迁移
php artisan migrate

3. 模块注册示例

// app/Providers/AppServiceProvider.php
use Dybasedev\LunaPrototype\AssetsAccount\LunaAssetsAccountConfigure;
use Dybasedev\LunaPrototype\Schedule\LunaScheduleConfigure;

class AppServiceProvider extends LunaServiceProvider
{
    public function customRegister(): void
    {
        // 注册资产账户模块
        $this->registerModule(
            LunaAssetsAccountConfigure::create()->build()
        );
        
        // 注册调度模块
        $this->registerModule(
            LunaScheduleConfigure::create()->build()
        );
        
        // 扩展处理器配置
        $this->extendModule(function() {
            return LunaHandlerConfigure::create()
                ->group('custom_handlers', '自定义处理器', function($register) {
                    $register->handler(CustomHandler::class);
                })
                ->build();
        });
    }
}

4. 基本使用示例

use Dybasedev\LunaPrototype\AssetsAccount\LunaAssetsAccount;

// 获取资产账户实例
$assetsAccount = app(LunaAssetsAccount::class);

// 创建账户类型
$balanceType = $assetsAccount->createAccountType(
    'balance',
    'default_handler',
    '余额账户',
    '用户主要余额账户'
);

核心模块

Foundation 模块

基础架构模块，提供：

配置管理系统
异常处理机制
业务事件定义和格式化系统
处理器模式
安装器框架
备份恢复机制
辅助函数

→ 详细文档

AssetsAccount 模块

资产账户管理模块，提供：

多层级账户类型管理
账户创建和查询
原子性账户操作
余额类型管理（可用、冻结、锁定）
变更日志记录
统计和查询功能

→ 详细文档

Schedule 模块

任务调度模块，提供：

定时任务管理
后台作业队列
任务状态监控
日志记录
任务优先级管理
失败重试机制

→ 详细文档

Membership 模块

会员体系模块，提供：

会员等级框架
里程碑系统（等级系统）
会员关系链管理
推广代理机制
权益管理接口
会员数据绑定

→ 详细文档

Showcase 模块

UI组件抽象模块，提供：

表单字段组件
数据表列组件
多前端框架适配
动态页面描述
后台面板快速扩展
前端页面装修

→ 详细文档

UnitConversion 模块

单位转换模块，提供：

单位类别和定义管理
灵活的转换处理器（固定汇率、动态汇率、条件汇率）
转换上下文和手续费计算
与资产账户系统的集成
批量转换和缓存优化
货币、度量衡等多种单位支持

→ 详细文档

Trade 模块

交易系统模块，提供：

完整的交易流程管理
可扩展的交易对象（Tradable）接口
灵活的支付方式管理
交易金额修改器（折扣、税费、运费等）
退款和撤销支持
交易编号生成器

→ 详细文档

HoldingObject 模块

对象持有系统模块，提供：

唯一对象定义和管理
灵活的持有状态（正常、禁用、释放等）
持有条件验证（数量限制、时间限制等）
常见场景支持（每日签到、购买限制、抽奖机会等）
并发控制和缓存优化
高度抽象的业务组合能力

→ 详细文档

Permission 模块

权限管理模块，提供：

基于策略（Policy）的权限定义
角色（Role）管理
用户组（UserGroup）管理
灵活的权限分配和继承
权限缓存和性能优化
与 Laravel Gate 的集成

→ 详细文档

架构设计

原子化模块设计

Luna Prototype 的模块设计遵循原子化原则，每个模块都是一个完整且独立的功能单元：

// 模块配置示例 - AssetsAccount
LunaAssetsAccountConfigure::create()
    ->model(CustomAssetsAccount::class)           // 自定义模型
    ->serviceProvider(CustomAccountProvider::class) // 自定义服务提供者
    ->build();

模块独立性

每个模块都继承自 LunaModule 基类，具有完全独立的：

配置管理: 独立的配置存储和版本控制
数据库迁移: 模块专属的数据表结构
服务注册: 独立的服务容器绑定
依赖关系: 明确的模块间依赖声明

组合使用示例

// 电商场景组合
public function customRegister(): void 
{
    // 基础账户系统
    $this->registerModule(LunaAssetsAccountConfigure::create()->build());
    
    // 会员体系
    $this->registerModule(LunaMembershipConfigure::create()->build());
    
    // 扩展支付相关处理器
    $this->extendModule(function() {
        return LunaHandlerConfigure::create()
            ->group('payment', '支付处理器', function($register) {
                $register->handler(AlipayHandler::class);
                $register->handler(WechatPayHandler::class);
                $register->handler(RefundHandler::class);
            })
            ->build();
    });
}

// 游戏场景组合  
public function customRegister(): void 
{
    // 只需要积分和道具系统
    $this->registerModule(LunaAssetsAccountConfigure::create()->build());
    
    // 游戏专用处理器
    $this->extendModule(function() {
        return LunaHandlerConfigure::create()
            ->group('game', '游戏处理器', function($register) {
                $register->handler(ExperienceHandler::class);
                $register->handler(ItemHandler::class);
                $register->handler(AchievementHandler::class);
            })
            ->build();
    });
}

处理器模式

通过继承 LunaServiceProvider 可以方便地注册和扩展处理器：

// 在 AppServiceProvider 中注册处理器
public function customRegister(): void
{
    $this->extendModule(function() {
        return LunaHandlerConfigure::create()
            ->group('payment_handlers', '支付处理器', function($register) {
                $register->handler(AlipayHandler::class);
                $register->handler(WechatHandler::class);
            })
            ->build();
    });
}

// 使用处理器
$handler = app(LunaHandler::class);
$handler->execute('payment_handler', $data);

业务事件系统

BusinessEvent模块用于管理系统中各种业务操作的事件定义和描述格式化，主要用于账户流水、操作日志等场景中记录触发操作的事件信息，并将event_id和payload转换为用户可见的描述文本：

// 创建业务事件定义
$businessEvent = app(LunaBusinessEvent::class);
$businessEvent->createBusinessEvent(
    'transfer_money',           // 事件名称
    'account_operations',       // 事件分组
    'transfer_handler',         // 处理器
    '转账操作：从 {from_account} 转出 {amount} 到 {to_account}', // 格式化模板
    '转账操作'                  // 显示名称
);

// 格式化事件消息（用于显示给用户）
$message = $businessEvent->eventMessage('transfer_money', [
    'from_account' => '张三的余额账户',
    'to_account' => '李四的余额账户', 
    'amount' => '100.00'
]);
// 输出: "转账操作：从 张三的余额账户 转出 100.00 到 李四的余额账户"

// 在账户操作中使用事件ID记录
$operation = luna_account_transfer()
    ->from($user1, 'balance')
    ->to($user2, 'balance') 
    ->event('transfer_money')  // 关联业务事件
    ->amount(100);

单位转换系统

UnitConversion 模块提供了灵活的单位转换功能，特别适合多币种、国际化等场景：

use Dybasedev\LunaPrototype\UnitConversion\LunaUnitConversion;
use Dybasedev\LunaPrototype\UnitConversion\Attributes\UnitAttributes;

// 获取单位转换实例
$unitConversion = app(LunaUnitConversion::class);

// 创建货币单位（使用参数类）
$unitConversion->createUnit('currency', 'USD', 
    UnitAttributes::create()
        ->symbol('$')
        ->displayName('美元')
        ->precision(2)
        ->asBase()  // 设为基准单位
);

$unitConversion->createUnit('currency', 'CNY',
    UnitAttributes::create()
        ->symbol('¥')
        ->displayName('人民币')
        ->baseValue(7.0)  // 相对于基准单位的汇率
);

// 简单转换
$result = $unitConversion->convert('USD', 'CNY', 100);
echo $result->getToAmount(); // 700.0

// 带上下文的转换（如手续费计算）
use Dybasedev\LunaPrototype\UnitConversion\Conversion\ConversionContext;

$context = ConversionContext::make([
    'calculate_fee' => true,
    'parameters' => [
        'user_level' => 'vip',
        'amount_tier' => 'large'
    ]
]);

$result = $unitConversion->convert('USD', 'CNY', 1000, $context);
echo $result->getToAmount();  // 转换后金额
echo $result->getFee();       // 手续费

// 与资产账户集成
use Dybasedev\LunaPrototype\UnitConversion\Integration\AssetsAccount\AssetsAccountIntegration;

$integration = new AssetsAccountIntegration($unitConversion);

// 为账户类型添加货币支持
$integration->addCurrencySupport($accountType, 'USD');

// 转换账户余额
$cnyBalance = $integration->convertBalance($account, 'CNY');
echo $cnyBalance; // 转换后的余额

// 批量转换
$conversions = [
    'usd_to_cny' => ['from' => 'USD', 'to' => 'CNY', 'amount' => 100],
    'usd_to_eur' => ['from' => 'USD', 'to' => 'EUR', 'amount' => 100],
];
$results = $unitConversion->batchConvert($conversions);

交易系统

Trade 模块提供了完整的交易流程管理，适用于电商、充值、服务购买等场景：

use Dybasedev\LunaPrototype\Trade\LunaTrade;
use Dybasedev\LunaPrototype\Trade\Payment\PaymentConfiguration;

// 配置支付方式
$paymentConfig = PaymentConfiguration::create()
    ->registerMethod('alipay', AlipayPayment::class, [
        'app_id' => 'your_app_id',
        'private_key' => 'your_private_key',
    ])
    ->registerMethod('wechat', WechatPayment::class, [
        'mch_id' => 'your_mch_id',
        'api_key' => 'your_api_key',
    ])
    ->setDefaultMethod('alipay')
    ->build();

// 创建交易
$trade = app(LunaTrade::class);
$transaction = $trade->createTransaction($buyer, $product, 100.00);

// 应用金额修改器（折扣、税费等）
$transaction->applyModifier(new DiscountModifier(0.1));  // 10% 折扣
$transaction->applyModifier(new TaxModifier(0.06));      // 6% 税费

// 发起支付
$paymentResult = $trade->pay($transaction, 'alipay', [
    'return_url' => 'https://example.com/return',
    'notify_url' => 'https://example.com/notify',
]);

// 处理支付结果
if ($paymentResult->isSuccess()) {
    // 支付成功
    $trade->completeTransaction($transaction);
} elseif ($paymentResult->isPending()) {
    // 等待支付回调
    echo $paymentResult->getRedirectUrl();
}

对象持有系统

HoldingObject 模块提供了灵活的对象持有关系管理，适用于各种业务场景：

use Dybasedev\LunaPrototype\HoldingObject\LunaHoldingObject;
use Dybasedev\LunaPrototype\HoldingObject\LunaHoldingObjectConfigure;

// 配置持有对象
$configure = LunaHoldingObjectConfigure::create()
    ->registerUniqueObject('daily-checkin', DailyCheckInObject::class)
    ->registerUniqueObject('product-limit', ProductPurchaseLimitObject::class)
    ->registerUniqueObject('lottery-chance', LotteryChanceObject::class)
    ->build();

$holdingObject = new LunaHoldingObject($configure);

// 每日签到
$checkIn = $holdingObject->createUniqueHolding(
    $user,
    'daily-checkin',
    1,  // 持有数量
    ['check_in_date' => date('Y-m-d')]
);

if ($checkIn->isSuccessful()) {
    echo "签到成功！";
} else {
    echo "今日已签到";
}

// 购买限制检查
$canPurchase = $holdingObject->checkHoldingLimit(
    $user,
    'product-limit',
    $product->id,
    $quantity
);

if (!$canPurchase) {
    echo "超出购买限制";
}

// 抽奖机会管理
$holdingObject->updateHolding(
    $user,
    'lottery-chance',
    'activity_001',
    5  // 增加5次抽奖机会
);

权限系统

Permission 模块提供了基于策略的灵活权限管理：

use Dybasedev\LunaPrototype\Permission\LunaPermission;

$permission = app(LunaPermission::class);

// 创建策略
$policy = $permission->createPolicy('article.manage', [
    [
        'effect' => 'allow',
        'actions' => ['create', 'update'],
        'resources' => ['article:*'],
    ],
    [
        'effect' => 'deny',
        'actions' => ['delete'],
        'resources' => ['article:protected:*'],
    ]
]);

// 创建角色并分配策略
$role = $permission->createRole('editor', '编辑员');
$permission->assignPolicy($policy, $role);

// 分配角色给用户
$permission->assignPolicy($role->name, $user);

// 权限检查
if ($user->hasPermission('article.manage', 'create', 'article:123')) {
    // 允许创建文章
}

// 用户组管理
$group = $permission->createUserGroup('vip-users', 'VIP用户组');
$group->addMember($user);
$permission->assignPolicy($policy, $group);

测试

项目使用 Pest 3.0 作为测试框架。

测试环境配置

在运行测试前，需要配置测试环境：

交互式配置（推荐）

# 运行配置脚本，按提示输入数据库配置
php scripts/setup-testing-env.php

快速配置（CI/自动化）

# 使用默认配置
php scripts/setup-testing-env-ci.php

# 自定义数据库配置
php scripts/setup-testing-env-ci.php \
  --db-host=localhost \
  --db-username=test_user \
  --db-password=secret \
  --db-database=luna_test

手动配置

如果您偏好手动配置，可创建 .env.testing 文件：

# 复制示例并修改
cp .env.testing.example .env.testing
# 然后编辑 .env.testing 文件

运行测试

确保测试数据库存在并可访问，然后运行测试：

# 运行所有测试
./vendor/bin/pest

# 运行特定模块测试
./vendor/bin/pest tests/Unit/Foundation/
./vendor/bin/pest tests/Unit/AssetsAccount/

# 运行测试并生成覆盖率报告
./vendor/bin/pest --coverage

CI 集成示例

GitHub Actions 配置示例：

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    services:
      mysql:
        image: mysql:8.4
        env:
          MYSQL_ROOT_PASSWORD: root
          MYSQL_DATABASE: luna_prototype_test
        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3

    steps:
      - uses: actions/checkout@v3
      
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.4
          
      - name: Install dependencies
        run: composer install --no-progress --prefer-dist --optimize-autoloader
        
      - name: Setup testing environment
        run: php scripts/setup-testing-env-ci.php --db-password=root
        
      - name: Run tests
        run: ./vendor/bin/pest

扩展开发指南

创建自定义模块

// 1. 创建模块配置
class CustomModuleConfigure extends LunaModuleConfigure 
{
    public function name(): string 
    {
        return 'custom_module';
    }
    
    public function dependencies(): array 
    {
        return ['luna_foundation']; // 声明依赖
    }
}

// 2. 在 AppServiceProvider 中注册
public function customRegister(): void 
{
    $this->registerModule(CustomModuleConfigure::create()->build());
}

扩展现有功能

// 扩展账户类型
$this->extendModule(function() {
    return LunaAssetsAccountConfigure::create()
        ->accountType('loyalty_points', PointsHandler::class, '积分账户')
        ->accountType('gift_cards', GiftCardHandler::class, '礼品卡')
        ->build();
});

// 扩展业务事件
$this->extendModule(function() {
    return LunaBusinessEventConfigure::create()
        ->group('marketing', '营销事件', function($register) {
            $register->event('coupon_used', CouponEventHandler::class);
            $register->event('promotion_applied', PromotionEventHandler::class);
        })
        ->build();
});

最佳实践

保持原子性: 每个模块只负责一个特定的业务领域
明确依赖: 通过 dependencies() 方法明确声明模块依赖
扩展优先: 优先通过处理器、配置等机制扩展，避免修改核心代码
向后兼容: 保持 API 的向后兼容性，使用新方法而非修改现有方法签名

贡献

欢迎提交 Pull Request 和 Issue。请确保：

遵循原子化组件设计原则
代码符合 PSR-12 编码标准
添加适当的测试用例
更新相关文档
提交前运行所有测试

许可证

本项目采用 Apache License 2.0 许可证。详见 LICENSE 文件。

支持

如有问题或建议，请提交 Issue 或联系开发团队。

Luna Prototype Team
基于 Laravel 的快速业务原型开发框架

dybasedev / luna-prototype

Maintainers

Details

README

概述

设计理念

主要特性

基础架构特性

业务组件特性

原子化组件优势

按需使用

灵活扩展

核心概念

模块组件（Module）

组件的标准结构

组件的概念

组件的配置器（Luna Module Configure）

定义组件身份

配置选项管理

服务注册

服务提供者的作用

为什么要分离服务提供者？

使用资源发布

组件的访问入口类

组件的注册流程

注册流程详解

自动服务提供者注册机制

Foundation 组件概要

主要功能

核心类

系统要求

安装

快速开始

1. 基础配置

2. 发布和运行迁移文件

3. 模块注册示例

4. 基本使用示例

核心模块

Foundation 模块

AssetsAccount 模块

Schedule 模块

Membership 模块

Showcase 模块

UnitConversion 模块

Trade 模块

HoldingObject 模块

Permission 模块

架构设计

原子化模块设计

模块独立性

组合使用示例

处理器模式

业务事件系统

单位转换系统

交易系统

对象持有系统

权限系统

测试

测试环境配置

交互式配置（推荐）

快速配置（CI/自动化）

手动配置

运行测试

CI 集成示例

扩展开发指南

创建自定义模块

扩展现有功能

最佳实践

贡献

许可证

支持