# API模块订单验证器使用说明

## 概述

`app\api\validate\Order` 验证器类为订单相关的API接口提供了完整的参数验证功能，确保请求参数的正确性和安全性。

## 验证器功能

### 支持的验证场景

1. **create** - 通过购物车创建订单
2. **createByGoods** - 通过商品规格创建订单
3. **calculate** - 计算订单（支持购物车和商品规格两种模式）
4. **detail** - 订单详情、确认收货、查询物流
5. **cancel** - 取消订单
6. **pay** - 订单支付

### 验证规则

#### 基础参数
- `address_id`: 收货地址ID，必须，整数，大于0
- `user_coupon_id`: 优惠券ID，可选，整数，大于0
- `memo`: 备注，可选，最大500字符

#### 购物车相关
- `ids`: 购物车商品选择ID，必须，数组
- `cart_ids`: 购物车ID列表，必须，数组

#### 商品列表相关
- `goods_list`: 商品列表，必须，数组，包含自定义验证
  - `goods_id`: 商品ID，必须，整数，大于0
  - `goods_sku_id`: 商品规格ID，可选，整数，大于等于0
  - `nums`: 购买数量，必须，整数，大于0

#### 计算类型
- `type`: 计算类型，必须，支持: cart（购物车模式）, goods（商品规格模式）

#### 订单操作相关
- `order_sn`: 订单号，必须，字母数字
- `paytype`: 支付方式，必须，支持: alipay, wechat, unionpay, balance
- `method`: 支付方法，必须，支持: web, wap, app, miniapp, mp, mini

## 使用示例

### 1. 通过商品规格创建订单

```php
// API接口: POST /api/order/createByGoods
$data = [
    'goods_list' => [
        [
            'goods_id' => 1,
            'goods_sku_id' => 5,
            'nums' => 2
        ],
        [
            'goods_id' => 2,
            'nums' => 1
        ]
    ],
    'address_id' => 1,
    'user_coupon_id' => 10,
    'memo' => '请尽快发货'
];

// 验证器会自动验证这些参数
```

### 2. 计算订单（通过商品规格）

```php
// API接口: POST /api/order/calculate
$data = [
    'type' => 'goods',       // 计算类型：商品规格模式
    'goods_list' => [
        [
            'goods_id' => 1,
            'goods_sku_id' => 5,
            'nums' => 2
        ]
    ],
    'address_id' => 1,
    'user_coupon_id' => 10
];
```

### 3. 计算订单（通过购物车）

```php
// API接口: POST /api/order/calculate
$data = [
    'type' => 'cart',        // 计算类型：购物车模式
    'cart_ids' => [1, 2, 3], // 购物车ID
    'address_id' => 1,
    'user_coupon_id' => 10
];
```

### 4. 通过购物车创建订单

```php
// API接口: POST /api/order/create
$data = [
    'ids' => [1, 2, 3],  // 购物车商品选择ID
    'address_id' => 1,
    'user_coupon_id' => 10,
    'memo' => '备注信息'
];
```

### 5. 订单支付

```php
// API接口: POST /api/order/pay
$data = [
    'order_sn' => 'O202412270001',
    'paytype' => 'wechat',
    'method' => 'miniapp'
];
```

### 6. 取消订单

```php
// API接口: POST /api/order/cancel
$data = [
    'order_sn' => 'O202412270001'
];
```

### 7. 订单详情

```php
// API接口: GET /api/order/detail?order_sn=O202412270001
// 或者 POST /api/order/detail
$data = [
    'order_sn' => 'O202412270001'
];
```

## 自定义验证规则

验证器包含一个自定义验证方法 `checkGoodsList`，用于验证商品列表的格式：

```php
protected function checkGoodsList($value, $rule, $data)
{
    // 验证商品列表是否为数组
    // 验证每个商品项的必要字段
    // 验证商品ID和数量的有效性
    // 验证可选字段的格式
}
```

## 错误消息

验证器提供了详细的中文错误消息，包括：

- 参数缺失提示
- 参数格式错误提示
- 参数值范围错误提示
- 商品列表格式错误的具体位置提示

## 控制器集成

在订单控制器中的使用方式：

```php
public function createByGoods()
{
    // 验证请求参数
    $validate = new \app\api\validate\Order();
    if (!$validate->scene('createByGoods')->check($this->request->post())) {
        $this->error($validate->getError());
    }
    
    // 业务逻辑处理
    // ...
}
```

## 注意事项

1. 验证器会自动检查商品列表的格式和内容
2. 所有必填参数都会被严格验证
3. 支付方式和方法的选项会根据系统配置动态调整
4. 错误消息会准确指出问题的具体位置
5. 验证器与OrderService服务类配合使用，提供完整的订单处理流程

## API接口列表

| 接口 | 方法 | 验证场景 | 说明 |
|------|------|----------|------|
| `/api/order/create` | POST | create | 通过购物车创建订单 |
| `/api/order/createByGoods` | POST | createByGoods | 通过商品规格创建订单 |
| `/api/order/calculate` | POST | calculate | 计算订单（支持两种模式） |
| `/api/order/detail` | GET/POST | detail | 获取订单详情 |
| `/api/order/cancel` | POST | cancel | 取消订单 |
| `/api/order/pay` | POST | pay | 订单支付 |
| `/api/order/receipt` | POST | detail | 确认收货 |
| `/api/order/logistics` | GET | detail | 查询物流 |

通过这个验证器，可以确保所有订单相关的API接口都有统一、规范的参数验证，提高系统的安全性和稳定性。