# 农贸市场匹配交易系统文档

## 概述

Mex模块是一个完整的农贸市场匹配交易系统，实现了基于系统仓库的商品交易撮合机制。系统采用价格优先、时间优先的撮合原则，通过计划任务定时执行交易匹配，确保交易的公平性和系统的稳定性。



## 系统特点

- **非用户间交易**：所有交易通过系统仓库进行，避免用户间直接转移
- **挂单无价格验证**：最低价和最高价仅作参考，撮合时才验证价格
- **整单成交原则**：订单不拆分，要么全部成交要么等待
- **数量保护机制**：大额用户买入物品订单保护阈值防止市场操控
- **分离撮合任务**：用户买入物品和用户卖出物品分别处理
- **管理员调控**：支持市场供需调节和价格稳定机制
- **账户体系设计**：仓库账户和调控账户确保资金物品流转安全
- **冻结机制**：所有订单挂单时都冻结资金或物品，不受保护阈值影响

## 核心交易规则

### 1. 价格限制机制

#### 最低价（保底价）
- **撮合验证**：用户卖出物品价格必须 **等于或低于** 系统设置的最低价才能成交
- **挂单阶段**：挂单时不验证价格，所有订单都可以挂单并冻结物品
- **撮合阶段**：撮合时验证价格，符合条件的订单成交
- **公示透明**：最低价对用户公开，便于制定策略

#### 最高价（参考价）
- **撮合验证**：用户买入物品价格必须 **高于或等于** 系统设置的最高价才能成交
- **挂单阶段**：挂单时不验证价格，所有订单都可以挂单并冻结资金
- **撮合阶段**：撮合时验证价格，符合条件的订单成交
- **价格发现**：最高价仅作为参考，实际成交价格由市场决定

#### 价格精度
- **小数支持**：挂单价格支持5位小数精度
- **精确计算**：确保价格计算的准确性和公平性

### 2. 撮合交易机制

#### 基于系统仓库的撮合
- **非订单撮合**：不是基于用户挂单的直接撮合
- **系统中介**：所有交易都通过系统仓库进行
- **防止转移**：避免用户通过多账号进行资产转移

#### 撮合队列规则（仅适用于用户买入物品订单）
- **MySQL查询筛选**：
  - 状态为"等待"
  - 价格 ≥ 最高价（价格符合条件）
  - 数量 ≤ 保护阈值（不超量订单）
- **二级排序优先级**：
  1. 价格优先（用户买入物品价格高者优先）
  2. 时间优先（价格相同时，挂单时间早者优先）
- **整单成交**：所有订单不拆单（要么全成交，要么不成交）
- **库存不足处理**：结束本次撮合，避免无效循环

### 3. 订单数量保护（仅适用于用户买入物品订单）

#### 保护阈值设置
- **后台配置**：管理员可设置订单数量保护阈值（如300个）
- **挂单规则**：所有订单都可以正常挂单并冻结资金，不管是否超过保护阈值
- **撮合规则**：超过阈值的用户买入物品订单不参与撮合成交
- **防止操控**：防止大户通过大额订单操控市场

#### 隐藏机制
- **不对外展示**：保护阈值不向用户公开
- **防止做局**：用户无法通过已知阈值进行市场操控
- **大单卡小单**：超量订单会阻止后续小额订单参与撮合，这是有意设计的保护机制

### 4. 计划任务执行

#### 分离撮合任务
- **用户买入物品撮合任务**：专门处理用户买入物品订单
- **用户卖出物品撮合任务**：专门处理用户卖出物品订单
- **执行频率**：每5-10分钟分别执行两个撮合任务
- **独立处理**：两个任务独立运行，互不干扰
- **系统稳定**：避免实时撮合对系统性能的影响

### 5. 交易大厅显示

#### 成交记录展示
- **只显示成功**：交易大厅只显示已成交的订单
- **不显示等待**：等待中的订单不在大厅显示
- **用户昵称**：显示交易用户昵称和交易详情

#### 价格透明度
- **成交价格**：显示实际成交价格
- **市场发现**：用户可通过成交记录了解市场真实价格
- **策略调整**：帮助用户调整交易策略

### 6. 市场调控机制

#### 管理员干预工具
- **隐形操作**：管理员可进行不显示在交易大厅的买卖操作
- **市场调节**：通过增加或减少市场供应量调控价格
- **优先级设置**：管理员操作具有更高优先级

#### 操作方式
- **卖出调控**：向市场投放商品，增加供应量
- **买入调控**：从市场回收商品，减少供应量
- **日志记录**：所有调控操作都有详细日志记录

## 技术实现架构

### 1. 数据库表结构设计
- **订单表（mex_orders）**：记录用户买卖订单信息
- **系统仓库表（mex_warehouse）**：记录系统商品库存
- **成交记录表（mex_transactions）**：记录所有成交信息
- **价格配置表（mex_price_configs）**：存储商品的最低价和最高价配置
- **市场调控记录表（mex_admin_operations）**：记录管理员市场调控操作

### 1.1 系统账户体系设计
- **仓库账户（USER_ID: 15）**：系统核心账户，负责所有交易的资金和物品中转
- **调控账户（USER_ID: 16）**：管理员市场调控专用账户，用于市场供需调节
- **账户安全机制**：系统保留账户，禁止普通用户操作，确保数据一致性

### 2. 核心算法实现
- **挂单阶段**：无价格验证，所有订单都冻结资金或物品
- **撮合阶段价格验证**：用户卖出物品价格≤最低价，用户买入物品价格≥最高价
- **撮合查询算法**：MySQL查询时完成筛选和二级排序（价格→时间）
- **数量保护算法**：挂单不受限制，撮合时过滤超量的用户买入物品订单
- **整单匹配算法**：库存充足完全成交，不足则结束本次撮合

### 3. 安全机制与风控
- **防刷单机制**：用户订单频率限制，异常交易行为监控
- **防操控机制**：大额订单保护阈值，价格异常波动预警
- **数据一致性保证**：数据库事务确保原子性
- **异常处理机制**：撮合失败回滚，系统异常订单状态恢复

### 4. 性能优化策略
- **计划任务优化**：批量处理减少数据库连接，分页处理避免内存溢出
- **数据库索引优化**：订单表复合索引，成交表时间索引
- **缓存策略**：价格配置缓存，系统库存缓存

### 5. 监控与日志
- **业务监控指标**：订单成交率统计，平均撮合时间监控，系统库存变化趋势
- **操作日志记录**：用户下单日志，撮合执行日志，管理员操作日志
- **异常告警机制**：撮合任务执行失败告警，价格异常波动告警

## 业务流程

### 用户卖出物品流程（包含账户流转）
1. **订单提交**：用户提交卖出物品订单（商品ID、数量、价格）
2. **物品检查**：验证用户是否有足够的物品数量
3. **物品冻结**：冻结用户对应数量的物品
4. **创建挂单**：创建挂单记录，进入撮合队列等待
5. **撮合处理**：用户卖出物品撮合任务处理
6. **价格验证**：撮合时验证 `用户卖出物品价格 ≤ 最低价`
7. **物品转移**：物品从用户冻结状态转入仓库账户（USER_ID: 15）
8. **资金结算**：资金从仓库账户（USER_ID: 15）转出到用户账户
9. **库存更新**：更新系统仓库商品数量
10. **记录生成**：创建成交记录，显示在交易大厅

### 用户买入物品流程（包含账户流转）
1. **订单提交**：用户提交买入物品订单（商品ID、数量、价格）
2. **资金检查**：验证用户是否有足够的资金购买
3. **资金冻结**：冻结用户账户对应资金（所有订单都冻结，不管是否超过保护阈值）
4. **创建挂单**：创建挂单记录，进入撮合队列等待
5. **撮合处理**：用户买入物品撮合任务处理
6. **MySQL筛选**：查询符合条件的订单（价格≥最高价 AND 数量≤保护阈值）
7. **库存匹配**：检查系统仓库库存是否充足
8. **成交处理**：库存充足则执行成交，不足则结束本次撮合
9. **资金转移**：冻结资金从用户账户转入仓库账户（USER_ID: 15）
10. **物品转移**：物品从仓库账户（USER_ID: 15）转出到用户账户
11. **库存更新**：扣减系统仓库商品数量
12. **记录生成**：创建成交记录，显示在交易大厅

### 撮合执行流程

#### 用户买入物品撮合任务
1. **任务启动**：用户买入物品撮合任务定时启动（5-10分钟间隔）
2. **MySQL查询筛选**：获取符合条件的订单（状态=等待 AND 价格≥最高价 AND 数量≤保护阈值）
3. **二级排序**：按价格DESC，时间ASC排序
4. **库存匹配**：逐个匹配系统仓库库存
5. **整单成交**：库存充足则整单成交，不足则结束本次撮合
6. **状态更新**：更新订单状态和系统库存
7. **记录生成**：生成成交记录供交易大厅展示

#### 用户卖出物品撮合任务
1. **任务启动**：用户卖出物品撮合任务定时启动（5-10分钟间隔）
2. **订单获取**：获取所有状态为"等待"的用户卖出物品订单
3. **价格验证**：验证用户卖出物品价格≤最低价
4. **成交处理**：符合条件的订单执行成交
5. **状态更新**：更新订单状态和系统库存
6. **记录生成**：生成成交记录供交易大厅展示

## 模块结构设计

```
app/Module/Mex/
├── Models/              # 数据模型
│   ├── MexOrder.php     # 订单模型
│   ├── MexWarehouse.php # 仓库模型
│   ├── MexTransaction.php # 成交记录模型
│   ├── MexPriceConfig.php # 价格配置模型
│   └── MexAdminOperation.php # 管理员操作记录模型
├── Services/            # 服务层
│   ├── MexOrderService.php # 订单服务
│   ├── MexMatchService.php # 撮合服务
│   └── MexWarehouseService.php # 仓库服务
├── Logic/               # 逻辑层
│   ├── MexOrderLogic.php # 订单逻辑
│   └── MexMatchLogic.php # 撮合逻辑
├── Commands/            # 计划任务
│   ├── MexUserBuyItemMatchCommand.php  # 用户买入物品撮合任务
│   └── MexUserSellItemMatchCommand.php # 用户卖出物品撮合任务
├── Controllers/         # 控制器
│   ├── Admin/           # 后台管理
│   └── Api/             # API接口
├── Handlers/            # 处理器
│   ├── MexOrderHandler.php # 订单处理器
│   └── MexQueryHandler.php # 查询处理器
├── Databases/           # 数据库文件
│   └── GenerateSql/     # SQL文件
├── Enums/               # 枚举类
│   ├── OrderType.php    # 订单类型枚举
│   └── OrderStatus.php  # 订单状态枚举
└── docs/                # 文档目录
    ├── README.md        # 系统概述文档
    └── 2.md             # 详细交易规则文档
```

## 模块定位说明

- **逻辑模块**：Mex模块为纯逻辑模块，不提供API接口
- **服务提供**：仅为其他模块提供服务层接口
- **内部调用**：通过Service层方法供其他模块调用
- **数据访问**：通过Repository层提供后台管理数据访问

## 部署与运维

### 计划任务配置
```bash
# 添加到 crontab
# 用户买入物品撮合任务
*/5 * * * * php artisan mex:user-buy-item-match >> /var/log/mex-user-buy-item-match.log 2>&1
# 用户卖出物品撮合任务
*/5 * * * * php artisan mex:user-sell-item-match >> /var/log/mex-user-sell-item-match.log 2>&1
```

### 监控指标
- 撮合任务执行时间
- 订单积压数量
- 成交成功率
- 系统库存水位

## 注意事项

1. **挂单机制**：所有订单都可以挂单并冻结资金/物品，不受保护阈值限制
2. **价格验证时机**：挂单时不验证价格，撮合时才验证价格
3. **保护阈值作用**：只影响用户买入物品订单的撮合成交，不影响挂单
4. **大单卡小单**：超量的用户买入物品订单会阻止后续订单成交，这是有意设计
5. **时间延迟**：撮合交易存在5-10分钟的延迟
6. **整单原则**：所有订单不拆分，确保交易完整性
7. **分离任务**：用户买入物品和用户卖出物品分别处理
8. **库存不足处理**：遇到库存不足时结束本次撮合，避免无效循环

## 开发指南

### 实现优先级
1. **第一阶段**：基础数据模型和数据库表结构
2. **第二阶段**：核心撮合算法和订单处理逻辑
3. **第三阶段**：API接口和前端交互功能
4. **第四阶段**：后台管理和市场调控功能
5. **第五阶段**：监控告警和性能优化

### 测试策略
- 单元测试：核心算法和业务逻辑
- 集成测试：API接口和数据库操作
- 压力测试：撮合性能和并发处理
- 业务测试：完整交易流程验证

---

**文档生成时间**：2025年06月12日 15:35
**基于文档**：`/app/Module/Mex/docs/2.md`
**文档版本**：v2.8
**文档状态**：已同步最新交易规则和流程
**更新内容**：
- 明确关键词：'买入' → '用户买入物品'，'卖出' → '用户卖出物品'
- 修正挂单机制：所有订单都要冻结资金或物品，不管是否超过保护阈值
- 明确保护阈值作用：只影响撮合成交，不影响挂单创建
- 移除系统总量守恒验证：因为交易期间会产生新的物品/资金
- 分离撮合任务：用户买入物品和用户卖出物品分别处理
- 优化撮合算法：MySQL查询时完成筛选和二级排序
- 修正交易流程：挂单阶段无价格验证，撮合阶段才进行价格验证
- 完善库存不足处理机制：结束本次撮合避免无效循环