kknongchang_2506/app/Module/Mex/docs

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

概述

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层提供后台管理数据访问

部署与运维

计划任务配置

# 添加到 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查询时完成筛选和二级排序
• 修正交易流程：挂单阶段无价格验证，撮合阶段才进行价格验证
• 完善库存不足处理机制：结束本次撮合避免无效循环