kknongchang_2506/app/Module/Mex/docs/2.md

农贸市场交易规则

1. 价格机制

• 最低价（保底价）：
  • 系统设定，公示给用户
  • 卖出价格必须≤最低价才能成交
• 最高价：
  • 系统设定，作为参考价
  • 买入价格必须≥最高价才有可能成交
  • 实际成交价可能高于公示的最高价
• 价格精度：
  • 挂单价格支持5位小数

2. 交易撮合规则

• 执行方式：
  • 计划任务定时执行（每5-10分钟）
  • 价格优先原则：买方出价高者优先成交
• 成交逻辑：
  • 交易对象：
  • 卖家：商品卖给系统仓库（非用户间交易）
  • 买家：从系统仓库购买商品
  • 执行方式：
  • 卖方挂单即与系统完成交易
  • 买方挂单进入撮合队列

3. 撮合队列规则

• 排序优先级：
  1. 价格优先（买价高者优先）
  2. 时间优先（价格相同时，挂单时间早者优先）
  3. 数量优先（价格和时间相同时，订单数量小者优先）
• 队列处理流程：
  1. 过滤超量订单（超过数量保护阈值）
  2. 按价格从高到低排序
  3. 价格相同则按挂单时间从早到晚排序
  4. 价格和时间相同则按订单数量从小到大排序
  5. 整单匹配库存（不拆单）
  6. 记录成交订单并更新库存

4. 特殊情况处理

• 整单成交原则：所有订单不拆单（要么全成交，要么不成交）
• 价格相同场景：
  1. 检查订单量是否超过保护阈值（超量订单不参与撮合）
  2. 剩余订单按挂单时间顺序整单成交
• 供不应求时：按价格优先级整单成交，无法成交的订单排队
• 供过于求时：满足条件的订单全部整单成交

5. 订单保护机制

• 数量保护阈值：
  • 后台设置（如300个）
  • 处理规则：在撮合前检查，超量订单不进入撮合队列（保留挂单状态）
• 目的：
  • 防止大额订单操控市场
  • 避免市场流动性枯竭

6. 市场调控功能（管理员）

• 物品注入：
  • 选择品种+方向（卖出）
  • 设置数量→确认
  • 效果：增加市场供应
• 物品回收：
  • 选择品种+方向（买入）
  • 设置数量→确认→销毁
  • 效果：减少市场库存
• 优先级：管理员操作>>用户订单

7. 信息展示规则（客户端）

• 交易大厅显示：
  • 仅展示已成交订单
  • 包含：用户昵称、商品、数量、成交价
  • 不显示未成交挂单
• 用户界面：
  • 个人可查看自己的未成交订单
  • 通过历史成交价推测合理报价

8. 数据库表结构设计

• 订单表（mex_orders）：
  • 记录用户买卖订单信息
  • 包含：用户ID、商品ID、订单类型（买/卖）、数量、价格、状态、创建时间等
• 系统仓库表（mex_warehouse）：
  • 记录系统商品库存
  • 包含：商品ID、库存数量、更新时间等
• 成交记录表（mex_transactions）：
  • 记录所有成交信息
  • 包含：买方ID、卖方ID、商品ID、成交数量、成交价格、成交时间等
• 价格配置表（mex_price_configs）：
  • 存储商品的最低价和最高价配置
  • 包含：商品ID、最低价、最高价、保护阈值、状态等
• 市场调控记录表（mex_admin_operations）：
  • 记录管理员市场调控操作
  • 包含：操作类型、商品ID、数量、操作员ID、操作时间等

9. 核心算法实现要点

• 价格验证算法：
  • 卖单价格验证：price ≤ min_price
  • 买单价格验证：price ≥ max_price
• 撮合排序算法：
  • 一级排序：按价格从高到低（DESC）
  • 二级排序：按创建时间从早到晚（ASC）
  • 三级排序：按订单数量从小到大（ASC）
• 数量保护算法：
  • 撮合前过滤：quantity > protection_threshold 的订单不参与
  • 保护阈值对用户隐藏，防止恶意操控
• 整单匹配算法：
  • 库存充足：订单完全成交
  • 库存不足：订单保持等待状态，不拆分

10. 安全机制与风控

• 防刷单机制：
  • 用户订单频率限制
  • 异常交易行为监控
• 防操控机制：
  • 大额订单保护阈值
  • 价格异常波动预警
• 数据一致性保证：
  • 数据库事务确保原子性
  • 库存扣减与订单状态同步更新
• 异常处理机制：
  • 撮合失败回滚机制
  • 系统异常时的订单状态恢复

11. 性能优化策略

• 计划任务优化：
  • 批量处理减少数据库连接
  • 分页处理大量订单避免内存溢出
• 数据库索引优化：
  • 订单表：(status, price, created_at) 复合索引
  • 成交表：(created_at) 时间索引用于展示
• 缓存策略：
  • 价格配置缓存（Redis）
  • 系统库存缓存（定期同步）

12. 监控与日志

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

13. 业务流程详细说明

13.1 卖出流程

1. 订单提交：用户提交卖出订单（商品ID、数量、价格）
2. 价格验证：系统验证 卖出价格 ≤ 最低价
3. 立即成交：满足条件的订单立即与系统成交
4. 库存更新：商品数量增加到系统仓库
5. 记录生成：创建成交记录，显示在交易大厅
6. 资金结算：用户账户增加对应资金

13.2 买入流程

1. 订单提交：用户提交买入订单（商品ID、数量、价格）
2. 价格验证：系统验证 买入价格 ≥ 最高价
3. 数量检查：验证订单数量是否超过保护阈值
4. 进入队列：通过验证的订单进入撮合队列
5. 等待撮合：订单等待计划任务执行撮合
6. 成交处理：撮合成功后扣减系统库存，完成交易

13.3 撮合执行流程

1. 任务启动：计划任务定时启动（5-10分钟间隔）
2. 订单获取：获取所有状态为"等待"的买入订单
3. 数量过滤：过滤掉超过保护阈值的大额订单
4. 排序处理：按价格→时间→数量进行三级排序
5. 库存匹配：逐个匹配系统仓库库存
6. 整单成交：库存充足则整单成交，不足则继续等待
7. 状态更新：更新订单状态和系统库存
8. 记录生成：生成成交记录供交易大厅展示

14. 技术实现架构

14.1 模块结构

app/Module/Mex/
├── Models/              # 数据模型
│   ├── MexOrder.php     # 订单模型
│   ├── MexWarehouse.php # 仓库模型
│   ├── MexTransaction.php # 成交记录模型
│   └── MexPriceConfig.php # 价格配置模型
├── Services/            # 服务层
│   ├── MexOrderService.php # 订单服务
│   ├── MexMatchService.php # 撮合服务
│   └── MexWarehouseService.php # 仓库服务
├── Logic/               # 逻辑层
│   ├── MexOrderLogic.php # 订单逻辑
│   └── MexMatchLogic.php # 撮合逻辑
├── Commands/            # 计划任务
│   └── MexMatchCommand.php # 撮合任务
├── Controllers/         # 控制器
│   └── Admin/           # 后台管理
└── Databases/           # 数据库文件
    └── GenerateSql/     # SQL文件

14.2 关键接口设计

• 下单接口：POST /api/mex/order（创建买卖订单）
• 订单查询：GET /api/mex/orders（查询用户订单）
• 交易大厅：GET /api/mex/transactions（获取成交记录）
• 价格查询：GET /api/mex/prices（获取商品价格信息）

15. 部署与运维

15.1 计划任务配置

# 添加到 crontab
*/5 * * * * php artisan mex:match >> /var/log/mex-match.log 2>&1

15.2 监控指标

• 撮合任务执行时间
• 订单积压数量
• 成交成功率
• 系统库存水位

15.3 运维注意事项

• 定期清理历史成交记录
• 监控系统库存异常变化
• 关注价格配置的合理性调整
• 保护阈值的动态调整

---

文档版本：v2.0 最后更新：2025年06月11日 20:34 文档状态：已补充完整