# 农贸市场交易规则

## 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 计划任务配置
```bash
# 添加到 crontab
*/5 * * * * php artisan mex:match >> /var/log/mex-match.log 2>&1
```

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

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

---

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