# 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` 中添加：
```php
'providers' => [
    // ...
    App\Module\Mex\Providers\MexServiceProvider::class,
],
```

### 2. 发布配置文件
```bash
php artisan vendor:publish --tag=mex-config
```

### 3. 执行数据库迁移
```bash
# 执行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` 文件中添加：
```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
```

## 使用方法

### 创建订单
```php
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'
);
```

### 配置价格保护
```php
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,
]);
```

### 执行撮合
```bash
# 手动执行撮合
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索引

## 安全考虑

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

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

## 测试

运行测试：
```bash
php artisan test app/Module/Mex/Tests/
```

## 注意事项

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