kknongchang_2506/app/Module/Mex

Mex模块 - 农贸市场系统

Mex模块是一个完整的农贸市场交易系统，支持用户买卖农产品，具有自动撮合、价格保护、仓库管理等功能。

模块概述

核心功能

• 订单管理: 支持买入/卖出订单创建、撮合、完成
• 价格配置: 商品价格区间保护和数量限制
• 仓库管理: 自动化的物品和资金流转
• 成交记录: 完整的交易历史记录
• 管理员操作: 市场调控和干预功能

业务规则

• 仓库账户: USER_ID为15，负责与用户进行物品和资金交换
• 调控账户: USER_ID为16，用于市场调控操作
• 用户卖出: 物品转入仓库，资金从仓库转出给用户
• 用户买入: 资金转入仓库，物品从仓库转出给用户
• 总量守恒: 确保系统内物品和资金总量不变

目录结构

app/Module/Mex/
├── AdminControllers/           # 后台管理控制器
│   ├── Helper/                # 控制器助手类
│   ├── MexOrderController.php
│   ├── MexPriceConfigController.php
│   ├── MexTransactionController.php
│   ├── MexWarehouseController.php
│   └── MexAdminOperationController.php
├── Commands/                   # 命令行工具
│   └── MexMatchCommand.php
├── Config/                     # 配置文件
│   └── mex.php
├── Controllers/               # API控制器
│   └── Admin/
├── Databases/                 # 数据库相关
│   ├── GenerateSql/          # SQL文件
│   └── Repositories/         # 仓库类
├── Enums/                     # 枚举类
│   ├── AdminOperationType.php
│   ├── OrderStatus.php
│   ├── OrderType.php
│   └── TransactionType.php
├── Events/                    # 事件类
│   ├── OrderCreatedEvent.php
│   ├── OrderCompletedEvent.php
│   └── TransactionCreatedEvent.php
├── Listeners/                 # 事件监听器
│   ├── OrderCreatedListener.php
│   └── TransactionCreatedListener.php
├── Logic/                     # 业务逻辑层
│   ├── MexAccountLogic.php
│   ├── MexAdminLogic.php
│   ├── MexMatchLogic.php
│   ├── MexOrderLogic.php
│   ├── MexTransactionLogic.php
│   └── MexWarehouseLogic.php
├── Models/                    # 数据模型
│   ├── MexAdminOperation.php
│   ├── MexOrder.php
│   ├── MexPriceConfig.php
│   ├── MexTransaction.php
│   └── MexWarehouse.php
├── Providers/                 # 服务提供者
│   └── MexServiceProvider.php
├── Repositories/              # 数据仓库
│   ├── MexAdminOperationRepository.php
│   ├── MexOrderRepository.php
│   ├── MexPriceConfigRepository.php
│   ├── MexTransactionRepository.php
│   └── MexWarehouseRepository.php
├── Services/                  # 服务层
│   ├── MexAdminService.php
│   ├── MexMatchService.php
│   ├── MexOrderService.php
│   ├── MexPriceConfigService.php
│   ├── MexTransactionService.php
│   └── MexWarehouseService.php
├── Tests/                     # 测试文件
│   └── MexAccountLogicTest.php
└── README.md                  # 本文件

数据库表

核心表

• kku_mex_orders - 订单表
• kku_mex_transactions - 成交记录表
• kku_mex_price_configs - 价格配置表
• kku_mex_warehouse - 仓库统计表
• kku_mex_admin_operations - 管理员操作记录表

安装配置

1. 注册服务提供者

在 config/app.php 中添加：

'providers' => [
    // ...
    App\Module\Mex\Providers\MexServiceProvider::class,
],

2. 发布配置文件

php artisan vendor:publish --tag=mex-config

3. 执行数据库迁移

# 执行SQL文件创建表结构
mysql -u username -p database_name < app/Module/Mex/Databases/GenerateSql/mex_orders.sql
mysql -u username -p database_name < app/Module/Mex/Databases/GenerateSql/mex_transactions.sql
# ... 其他SQL文件

4. 配置环境变量

在 .env 文件中添加：

# Mex模块配置
MEX_WAREHOUSE_USER_ID=15
MEX_REGULATION_USER_ID=16
MEX_DEFAULT_FUND_TYPE=1
MEX_MATCHING_ENABLED=true
MEX_MATCHING_INTERVAL=60

使用方法

创建订单

use App\Module\Mex\Services\MexOrderService;

// 创建卖出订单
$result = MexOrderService::createSellOrder(
    userId: 1001,
    itemId: 10001,
    quantity: 10,
    price: '2.50000'
);

// 创建买入订单
$result = MexOrderService::createBuyOrder(
    userId: 1001,
    itemId: 10001,
    quantity: 5,
    price: '8.00000'
);

配置价格保护

use App\Module\Mex\Services\MexPriceConfigService;

$result = MexPriceConfigService::createConfig([
    'item_id' => 10001,
    'min_price' => '1.00000',
    'max_price' => '10.00000',
    'protection_threshold' => 1000,
    'is_enabled' => true,
]);

执行撮合

# 手动执行撮合
php artisan mex:match

# 指定商品撮合
php artisan mex:match --item-id=10001

# 试运行模式
php artisan mex:match --dry-run

事件系统

订单事件

• OrderCreatedEvent - 订单创建时触发
• OrderCompletedEvent - 订单完成时触发

交易事件

• TransactionCreatedEvent - 成交记录创建时触发

监听器

• OrderCreatedListener - 处理订单创建后的缓存清理和统计更新
• TransactionCreatedListener - 处理成交后的市场统计和异常检测

后台管理

访问后台管理界面：

• 订单管理: /admin/mex-orders
• 价格配置: /admin/mex-price-configs
• 成交记录: /admin/mex-transactions
• 仓库管理: /admin/mex-warehouse
• 操作记录: /admin/mex-admin-operations

监控和日志

日志文件

• storage/logs/mex-match.log - 撮合任务日志
• storage/logs/laravel.log - 一般业务日志

监控指标

• 仓库资金余额监控
• 价格异常波动检测
• 频繁交易检测
• 大额交易预警

性能优化

缓存策略

• 价格配置缓存（1小时）
• 仓库统计缓存（5分钟）
• 市场统计缓存（10分钟）

数据库优化

• 订单表按状态和时间索引
• 交易记录表按商品和时间索引
• 仓库表按商品ID索引

安全考虑

限制措施

• 单用户每分钟最大订单数限制
• 单笔订单最大金额限制
• 价格保护机制防止异常价格

审计功能

• 所有管理员操作记录
• 异常交易自动检测和报警
• 完整的资金和物品流转记录

测试

运行测试：

php artisan test app/Module/Mex/Tests/

注意事项

1. 数据一致性: 所有交易操作都在数据库事务中执行
2. 并发控制: 使用数据库锁防止并发问题
3. 错误处理: 完善的异常处理和回滚机制
4. 日志记录: 详细的操作日志便于问题排查
5. 配置管理: 通过配置文件灵活控制系统行为