# OrderService 订单服务使用说明

## 概述

OrderService 是一个封装了订单创建逻辑的服务类，支持两种创建订单的方式：
1. **通过购物车创建订单**（原有功能）
2. **直接通过商品规格创建订单**（新增功能）

## 新增API接口

### 1. 直接创建订单 - `POST /api/order/createByGoods`

直接通过商品和规格信息创建订单，无需经过购物车。

#### 请求参数

```json
{
    "goods_list": [
        {
            "goods_id": 1,           // 商品ID（必填）
            "goods_sku_id": 5,       // 商品规格ID（可选，单规格商品为0或不传）
            "nums": 2                // 购买数量（必填）
        },
        {
            "goods_id": 2,
            "goods_sku_id": 0,       // 单规格商品
            "nums": 1
        }
    ],
    "address_id": 10,               // 收货地址ID（必填）
    "user_coupon_id": 3,            // 优惠券ID（可选）
    "memo": "订单备注"              // 订单备注（可选）
}
```

#### 响应数据

```json
{
    "code": 1,
    "msg": "下单成功！",
    "data": {
        "order_sn": "20241215142312000000011234",
        "paystate": 0
    }
}
```

### 2. 计算订单预览 - `POST /api/order/calculate`

在创建订单前预览价格、运费等信息，支持两种模式。

#### 商品规格模式

```json
{
    "type": "goods",                // 计算类型：商品规格模式
    "goods_list": [
        {
            "goods_id": 1,
            "goods_sku_id": 5,
            "nums": 2
        }
    ],
    "address_id": 10,               // 收货地址ID（可选，用于计算运费）
    "user_coupon_id": 3             // 优惠券ID（可选）
}
```

#### 购物车模式

```json
{
    "type": "cart",                 // 计算类型：购物车模式
    "cart_ids": [1, 2, 3],          // 购物车ID列表
    "address_id": 10,               // 收货地址ID（可选，用于计算运费）
    "user_coupon_id": 3             // 优惠券ID（可选）
}
```

#### 响应数据

```json
{
    "code": 1,
    "msg": "获取成功",
    "data": {
        "coupons": [                // 可用优惠券列表
            {
                "id": 1,
                "title": "满100减10",
                "condition": 100,
                "money": 10
            }
        ],
        "goods_list": [             // 商品详情列表
            {
                "goods_id": 1,
                "goods_sku_id": 5,
                "nums": 2,
                "goods": {
                    "id": 1,
                    "title": "商品名称",
                    "image": "商品图片",
                    "price": "99.00"
                },
                "sku": {
                    "id": 5,
                    "price": "99.00",
                    "image": "规格图片"
                },
                "sku_attr": "颜色:红色,尺寸:XL"
            }
        ],
        "order_info": {             // 订单价格信息
            "goodsprice": "198.00", // 商品金额
            "shippingfee": "10.00", // 运费
            "discount": "10.00",    // 优惠金额
            "amount": "208.00",     // 总金额（含运费）
            "saleamount": "198.00"  // 应付金额
        },
        "couponTotalPrice": 198.00  // 可用于优惠券的金额
    }
}
```

## 服务类方法

### OrderService::createOrderByGoods()

直接通过商品规格创建订单。

```php
use app\common\Service\OrderService;

try {
    $order = OrderService::createOrderByGoods(
        $address_id,    // 地址ID
        $user_id,       // 用户ID
        $goods_list,    // 商品列表
        $user_coupon_id, // 优惠券ID（可选）
        $memo           // 备注（可选）
    );
    
    echo "订单创建成功，订单号：" . $order->order_sn;
} catch (Exception $e) {
    echo "创建失败：" . $e->getMessage();
}
```

### OrderService::createOrderByCart()

通过购物车创建订单（原有功能的封装）。

```php
use app\common\Service\OrderService;

try {
    $order = OrderService::createOrderByCart(
        $address_id,     // 地址ID
        $user_id,        // 用户ID
        $cart_ids,       // 购物车ID数组
        $user_coupon_id, // 优惠券ID（可选）
        $memo            // 备注（可选）
    );
    
    echo "订单创建成功，订单号：" . $order->order_sn;
} catch (Exception $e) {
    echo "创建失败：" . $e->getMessage();
}
```

### OrderService::calculateOrderByGoods()

通过商品规格计算订单明细（用于预览）。

```php
use app\common\Service\OrderService;

try {
    $result = OrderService::calculateOrderByGoods(
        $goods_list,     // 商品列表
        $user_id,        // 用户ID
        $area_id,        // 地区ID（可选）
        $user_coupon_id  // 优惠券ID（可选）
    );
    
    $orderInfo = $result['orderInfo'];    // 订单价格信息
    $goodsList = $result['goodsList'];    // 商品详情
    $orderItem = $result['orderItem'];    // 订单商品项
    $userCoupon = $result['userCoupon'];  // 优惠券信息
    
} catch (Exception $e) {
    echo "计算失败：" . $e->getMessage();
}
```

### OrderService::calculateOrderByCart()

通过购物车计算订单明细（用于预览）。

```php
use app\common\Service\OrderService;

try {
    $result = OrderService::calculateOrderByCart(
        $cart_ids,       // 购物车ID数组
        $user_id,        // 用户ID
        $area_id,        // 地区ID（可选）
        $user_coupon_id  // 优惠券ID（可选）
    );
    
    $orderInfo = $result['orderInfo'];    // 订单价格信息
    $goodsList = $result['goodsList'];    // 商品详情
    $orderItem = $result['orderItem'];    // 订单商品项
    $userCoupon = $result['userCoupon'];  // 优惠券信息
    
} catch (Exception $e) {
    echo "计算失败：" . $e->getMessage();
}
```

## 商品列表格式说明

`goods_list` 参数是一个数组，每个元素包含以下字段：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| goods_id | int | 是 | 商品ID |
| goods_sku_id | int | 否 | 商品规格ID，单规格商品可以不传或传0 |
| nums | int | 是 | 购买数量，必须大于0 |

### 示例

```json
[
    {
        "goods_id": 1,      // 多规格商品
        "goods_sku_id": 5,
        "nums": 2
    },
    {
        "goods_id": 2,      // 单规格商品
        "goods_sku_id": 0,  // 或者不传此字段
        "nums": 1
    }
]
```

## 错误处理

服务会抛出以下类型的异常：

- **商品验证错误**：商品不存在、已下架等
- **库存不足错误**：商品或规格库存不足
- **地址错误**：收货地址不存在或不属于用户
- **优惠券错误**：优惠券不可用或已使用
- **参数错误**：商品列表格式错误等

## 使用场景

### 1. 立即购买功能
用户在商品详情页点击"立即购买"，直接跳转到订单确认页面：

```javascript
// 前端代码示例
function buyNow(goodsId, skuId, nums) {
    const goodsList = [{
        goods_id: goodsId,
        goods_sku_id: skuId,
        nums: nums
    }];
    
    // 先计算预览
    calculateOrder(goodsList).then(result => {
        // 显示订单确认页面
        showOrderConfirm(result);
    });
}

function createOrder(goodsList, addressId, couponId, memo) {
    // 创建订单
    fetch('/api/order/createByGoods', {
        method: 'POST',
        body: JSON.stringify({
            goods_list: goodsList,
            address_id: addressId,
            user_coupon_id: couponId,
            memo: memo
        })
    }).then(response => {
        // 跳转到支付页面
    });
}
```

### 2. 批量购买功能
选择多个商品进行批量购买：

```php
// 后端处理示例
$goodsList = [
    ['goods_id' => 1, 'goods_sku_id' => 5, 'nums' => 2],
    ['goods_id' => 2, 'goods_sku_id' => 0, 'nums' => 1],
    ['goods_id' => 3, 'goods_sku_id' => 8, 'nums' => 3]
];

try {
    $order = OrderService::createOrderByGoods(
        $addressId, 
        $userId, 
        $goodsList, 
        $couponId, 
        $memo
    );
    
    // 返回成功结果
    return json(['code' => 1, 'msg' => '下单成功', 'data' => $order]);
} catch (Exception $e) {
    return json(['code' => 0, 'msg' => $e->getMessage()]);
}
```

## 注意事项

1. **库存校验**：创建订单时会自动校验库存并扣减，请确保并发处理的安全性
2. **价格计算**：支持运费计算、优惠券折扣等完整的价格体系
3. **事务处理**：订单创建过程在数据库事务中执行，确保数据一致性
4. **日志记录**：自动记录订单操作日志
5. **性能优化**：避免在循环中调用订单创建方法，建议批量处理