fastadmin_tailored/docs/OrderValidator_使用说明.md

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. 通过商品规格创建订单

// 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. 计算订单（通过商品规格）

// 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. 计算订单（通过购物车）

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

4. 通过购物车创建订单

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

5. 订单支付

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

6. 取消订单

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

7. 订单详情

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

自定义验证规则

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

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

错误消息

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

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

控制器集成

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

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接口都有统一、规范的参数验证，提高系统的安全性和稳定性。