# 阶段5：订单系统

## 阶段概述
**时间**: 3.5周  
**目标**: 实现完整的订单管理系统，包括多种商品类型下单、支付、订单状态管理、仓库管理、发货物流等功能  
**优先级**: P1 (高优先级)

## 详细任务清单

### 5.1 订单数据模型设计 (3天)

#### 任务描述
设计和实现订单相关的数据模型和基础服务

#### 具体工作
- [ ] 设计订单主表数据模型
- [ ] 设计订单详情表数据模型
- [ ] 设计支付记录表数据模型
- [ ] 设计订单状态枚举
- [ ] 实现基础的订单服务接口

#### 数据模型设计
```csharp
// 订单主表
public class Order
{
    public int Id { get; set; }
    public string OrderNo { get; set; }
    public int UserId { get; set; }
    public int GoodsId { get; set; }
    public int Num { get; set; }
    public string GoodsTitle { get; set; }
    public string GoodsImgUrl { get; set; }
    public int OrderType { get; set; }
    public decimal Price { get; set; }
    public decimal OrderTotal { get; set; }
    public decimal OrderZheTotal { get; set; }
    public decimal UseMoney { get; set; }
    public decimal UseIntegral { get; set; }
    public decimal UseMoney2 { get; set; }
    public int CouponId { get; set; }
    public decimal CouponMoney { get; set; }
    public int PayType { get; set; }
    public int Status { get; set; }
    public int PrizeNum { get; set; }
    public string PayNo { get; set; }
    public DateTime? PayTime { get; set; }
    public DateTime AddTime { get; set; }
    public DateTime? UpdateTime { get; set; }
}

// 订单详情表
public class OrderList
{
    public int Id { get; set; }
    public string OrderId { get; set; }
    public int UserId { get; set; }
    public int GoodsId { get; set; }
    public int Num { get; set; }
    public int GoodsListId { get; set; }
    public string GoodsListTitle { get; set; }
    public string GoodsListImgUrl { get; set; }
    public int ShangId { get; set; }
    public int OrderType { get; set; }
    public int Source { get; set; }
    public decimal Price { get; set; }
    public DateTime AddTime { get; set; }
}

// 支付记录表
public class ProfitPay
{
    public int Id { get; set; }
    public int UserId { get; set; }
    public decimal ChangeMoney { get; set; }
    public string Content { get; set; }
    public string OrderNo { get; set; }
    public int PayType { get; set; }
    public DateTime AddTime { get; set; }
}

// 订单状态枚举
public enum OrderStatus
{
    Pending = 0,    // 待支付
    Paid = 1,       // 已支付
    Cancelled = 2,  // 已取消
    Refunded = 3    // 已退款
}

// 支付类型枚举
public enum PayType
{
    Wechat = 1,     // 微信支付
    Balance = 2,    // 余额支付
    Integral = 3,   // 积分支付
    Mixed = 4       // 混合支付
}
```

### 5.2 订单金额计算 (4天)

#### 任务描述
实现订单金额计算功能，包括优惠券抵扣、余额抵扣、积分抵扣等

#### 具体工作
- [ ] 实现订单金额计算服务
- [ ] 实现优惠券抵扣逻辑
- [ ] 实现余额抵扣逻辑
- [ ] 实现积分抵扣逻辑
- [ ] 实现抽奖限制验证
- [ ] 实现购买限制验证

#### 核心接口实现

##### 订单金额计算接口
```http
POST /api/v1/order/calculate
Authorization: Bearer {token}
Content-Type: application/json

Request:
{
  "goods_id": 123,
  "goods_num": 1,
  "prize_num": 3,
  "use_money_is": 1,
  "use_integral_is": 1,
  "use_money2_is": 0,
  "coupon_id": 456
}

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "goods_info": {
      "id": 123,
      "title": "商品标题",
      "price": "10.00",
      "type": 1
    },
    "calculation": {
      "original_amount": "30.00",
      "coupon_discount": "5.00",
      "balance_deduction": "10.00",
      "integral_deduction": "5.00",
      "final_amount": "10.00",
      "wechat_pay_amount": "10.00"
    },
    "user_assets": {
      "balance": "100.00",
      "integral": "200.00",
      "money2": "50.00"
    },
    "available_coupons": [
      {
        "id": 456,
        "title": "优惠券标题",
        "discount": "5.00",
        "min_amount": "20.00"
      }
    ],
    "restrictions": {
      "can_purchase": true,
      "daily_limit": 10,
      "daily_used": 3,
      "global_limit": 100,
      "global_used": 50
    }
  }
}
```

#### 技术实现要点
```csharp
// 订单计算服务
public interface IOrderCalculationService
{
    Task<OrderCalculationResult> CalculateOrderAsync(OrderCalculationRequest request);
    Task<bool> ValidateOrderLimitsAsync(int userId, int goodsId, int prizeNum);
    Task<List<UserCouponDto>> GetAvailableCouponsAsync(int userId, decimal amount);
}

// 订单计算请求
public class OrderCalculationRequest
{
    public int UserId { get; set; }
    public int GoodsId { get; set; }
    public int GoodsNum { get; set; }
    public int PrizeNum { get; set; }
    public bool UseBalance { get; set; }
    public bool UseIntegral { get; set; }
    public bool UseMoney2 { get; set; }
    public int CouponId { get; set; }
}

// 订单计算结果
public class OrderCalculationResult
{
    public GoodsInfoDto GoodsInfo { get; set; }
    public CalculationDto Calculation { get; set; }
    public UserAssetsDto UserAssets { get; set; }
    public List<UserCouponDto> AvailableCoupons { get; set; }
    public RestrictionsDto Restrictions { get; set; }
}
```

### 5.3 订单创建和支付 (5天)

#### 任务描述
实现订单创建和支付处理功能，支持多种商品类型

#### 具体工作
- [ ] 实现一番赏订单创建接口
- [ ] 实现无限赏订单金额计算接口
- [ ] 实现无限赏订单创建接口
- [ ] 实现商城订单金额计算接口
- [ ] 实现库存扣减逻辑
- [ ] 实现支付处理逻辑
- [ ] 实现订单状态更新
- [ ] 实现事务处理机制
- [ ] 实现订单超时取消

#### 无限赏订单接口

##### 无限赏订单金额计算接口
```http
POST /api/v1/order/infinite/calculate
Authorization: Bearer {token}
Content-Type: application/json

Request:
{
  "goods_id": 1001,
  "prize_num": 1,
  "use_money_is": 2,
  "use_integral_is": 2,
  "use_money2_is": 2,
  "coupon_id": ""
}

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "goods_info": {},
    "calculation": {},
    "user_assets": {}
  }
}
```

##### 无限赏订单创建接口
```http
POST /api/v1/order/infinite/create
Authorization: Bearer {token}
Content-Type: application/json

Request:
{
  "goods_id": 1001,
  "prize_num": 1,
  "use_money_is": 2,
  "use_integral_is": 2,
  "use_money2_is": 2,
  "coupon_id": ""
}

Response:
{
  "status": 1,
  "msg": "订单创建成功",
  "data": {
    "order_no": "ORD202401010001",
    "pay_info": {}
  }
}
```

#### 商城订单接口

##### 商城订单金额计算接口
```http
POST /api/v1/order/mall/calculate
Authorization: Bearer {token}
Content-Type: application/json

Request:
{
  "goods_id": 1001,
  "prize_num": 1,
  "goods_num": 1,
  "use_money_is": 2,
  "use_integral_is": 2,
  "use_money2_is": 2
}

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "goods_info": {},
    "calculation": {},
    "user_assets": {}
  }
}
```

#### 核心接口实现

##### 创建订单接口
```http
POST /api/v1/order/create
Authorization: Bearer {token}
Content-Type: application/json

Request:
{
  "goods_id": 123,
  "goods_num": 1,
  "prize_num": 3,
  "use_money_is": 1,
  "use_integral_is": 1,
  "use_money2_is": 0,
  "coupon_id": 456,
  "pay_type": 1
}

Response:
{
  "status": 1,
  "msg": "订单创建成功",
  "data": {
    "order_no": "ORD202401010001",
    "order_id": 789,
    "pay_info": {
      "pay_type": 1,
      "amount": "10.00",
      "wechat_pay_params": {
        "appId": "wx1234567890",
        "timeStamp": "1704067200",
        "nonceStr": "abc123",
        "package": "prepay_id=wx123456789",
        "signType": "RSA",
        "paySign": "signature"
      }
    }
  }
}
```

##### 支付回调接口
```http
POST /api/v1/order/payment/callback
Content-Type: application/json

Request:
{
  "order_no": "ORD202401010001",
  "pay_no": "wx_pay_123456",
  "pay_status": "SUCCESS",
  "pay_amount": "10.00",
  "pay_time": "2024-01-01T12:00:00Z"
}

Response:
{
  "status": 1,
  "msg": "支付成功"
}
```

#### 技术实现要点
```csharp
// 订单服务
public interface IOrderService
{
    Task<CreateOrderResult> CreateOrderAsync(CreateOrderRequest request);
    Task<bool> ProcessPaymentAsync(PaymentCallbackRequest request);
    Task<bool> CancelExpiredOrdersAsync();
}

// 订单创建请求
public class CreateOrderRequest
{
    public int UserId { get; set; }
    public int GoodsId { get; set; }
    public int GoodsNum { get; set; }
    public int PrizeNum { get; set; }
    public bool UseBalance { get; set; }
    public bool UseIntegral { get; set; }
    public bool UseMoney2 { get; set; }
    public int CouponId { get; set; }
    public int PayType { get; set; }
}

// 订单创建结果
public class CreateOrderResult
{
    public string OrderNo { get; set; }
    public int OrderId { get; set; }
    public PaymentInfoDto PayInfo { get; set; }
}

// 订单创建服务实现
public class OrderService : IOrderService
{
    public async Task<CreateOrderResult> CreateOrderAsync(CreateOrderRequest request)
    {
        using var transaction = await _context.Database.BeginTransactionAsync();
        try
        {
            // 1. 验证商品和库存
            // 2. 计算订单金额
            // 3. 扣减用户资产
            // 4. 创建订单记录
            // 5. 处理支付
            
            await transaction.CommitAsync();
            return result;
        }
        catch
        {
            await transaction.RollbackAsync();
            throw;
        }
    }
}
```

### 5.4 订单查询管理 (3天)

#### 任务描述
实现订单查询和管理功能

#### 具体工作
- [ ] 实现订单列表查询接口
- [ ] 实现订单详情查询接口
- [ ] 实现订单状态筛选
- [ ] 实现订单搜索功能
- [ ] 实现订单统计功能

#### 核心接口实现

##### 订单列表接口
```http
GET /api/v1/user/orders
Authorization: Bearer {token}

Query Parameters:
- status: 订单状态 (0=待支付, 1=已支付, 2=已取消)
- page: 页码
- limit: 每页数量

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "data": [
      {
        "id": 789,
        "order_no": "ORD202401010001",
        "goods_title": "商品标题",
        "goods_imgurl": "https://example.com/goods.jpg",
        "order_total": "30.00",
        "final_amount": "10.00",
        "status": 1,
        "status_text": "已支付",
        "prize_num": 3,
        "pay_type": 1,
        "pay_type_text": "微信支付",
        "add_time": "2024-01-01 12:00:00",
        "pay_time": "2024-01-01 12:05:00"
      }
    ],
    "last_page": 5,
    "statistics": {
      "total_orders": 100,
      "total_amount": "1000.00",
      "pending_orders": 5,
      "paid_orders": 90,
      "cancelled_orders": 5
    }
  }
}
```

##### 订单详情接口
```http
GET /api/v1/order/{orderNo}
Authorization: Bearer {token}

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "order_info": {
      "id": 789,
      "order_no": "ORD202401010001",
      "goods_id": 123,
      "goods_title": "商品标题",
      "goods_imgurl": "https://example.com/goods.jpg",
      "goods_num": 1,
      "order_type": 1,
      "price": "10.00",
      "order_total": "30.00",
      "use_money": "10.00",
      "use_integral": "5.00",
      "coupon_money": "5.00",
      "final_amount": "10.00",
      "status": 1,
      "status_text": "已支付",
      "prize_num": 3,
      "pay_type": 1,
      "pay_type_text": "微信支付",
      "pay_no": "wx_pay_123456",
      "add_time": "2024-01-01 12:00:00",
      "pay_time": "2024-01-01 12:05:00"
    },
    "prize_list": [
      {
        "id": 456,
        "goodslist_title": "奖品标题",
        "goodslist_imgurl": "https://example.com/prize.jpg",
        "shang_id": 10,
        "shang_title": "A赏",
        "shang_color": "#FF0000",
        "price": "100.00"
      }
    ],
    "payment_records": [
      {
        "pay_type": 1,
        "pay_type_text": "微信支付",
        "amount": "10.00",
        "pay_time": "2024-01-01 12:05:00"
      }
    ]
  }
}
```

### 5.5 仓库/盒柜管理 (4天)

#### 任务描述
实现用户仓库（盒柜）管理功能，包括奖品回收、发货等

#### 具体工作
- [ ] 实现仓库首页接口
- [ ] 实现奖品回收接口
- [ ] 实现奖品发货接口
- [ ] 实现确认发货接口
- [ ] 实现发货记录查询
- [ ] 实现发货记录详情
- [ ] 实现回收记录查询
- [ ] 实现物流信息查询

#### 核心接口实现

##### 仓库首页接口
```http
POST /api/v1/warehouse/index
Authorization: Bearer {token}

Request:
{
  "page": 1,
  "status": 0
}

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "data": [
      {
        "id": 20001,
        "goodslist_title": "限定手办A",
        "goodslist_imgurl": "https://example.com/prize.jpg",
        "goodslist_price": "299.00",
        "goodslist_money": "150.00",
        "status": 0,
        "addtime": 1640995300
      }
    ]
  }
}
```

##### 回收奖品接口
```http
POST /api/v1/warehouse/recovery
Authorization: Bearer {token}

Request:
{
  "order_list_ids": "20001,20002"
}

Response:
{
  "status": 1,
  "msg": "回收成功",
  "data": {
    "recovery_amount": "300.00"
  }
}
```

##### 发货奖品接口
```http
POST /api/v1/warehouse/send
Authorization: Bearer {token}

Request:
{
  "order_list_ids": "20001,20002",
  "name": "张三",
  "mobile": "13800138000",
  "address": "北京市朝阳区xxx街道xxx号",
  "message": "请小心轻放"
}

Response:
{
  "status": 1,
  "msg": "发货申请成功",
  "data": {
    "delivery_id": 70001
  }
}
```

##### 确认发货接口
```http
POST /api/v1/warehouse/send/confirm
Authorization: Bearer {token}

Request:
{
  "id": 70001
}

Response:
{
  "status": 1,
  "msg": "确认成功"
}
```

##### 发货记录接口
```http
POST /api/v1/warehouse/send/records
Authorization: Bearer {token}

Request:
{
  "page": 1
}

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "data": [
      {
        "id": 70001,
        "name": "张三",
        "mobile": "138****8000",
        "address": "北京市朝阳区xxx",
        "status": 1,
        "addtime": "2024-01-01 12:00:00"
      }
    ],
    "last_page": 3
  }
}
```

##### 发货记录详情接口
```http
POST /api/v1/warehouse/send/detail
Authorization: Bearer {token}

Request:
{
  "id": 70001
}

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "id": 70001,
    "name": "张三",
    "mobile": "13800138000",
    "address": "北京市朝阳区xxx街道xxx号",
    "status": 1,
    "items": [],
    "logistics": {}
  }
}
```

##### 回收记录接口
```http
POST /api/v1/warehouse/recovery/records
Authorization: Bearer {token}

Request:
{
  "page": 1
}

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "data": [],
    "last_page": 1
  }
}
```

##### 物流信息接口
```http
POST /api/v1/warehouse/logistics
Authorization: Bearer {token}

Request:
{
  "id": 70001
}

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "company": "顺丰速运",
    "tracking_no": "SF1234567890",
    "status": "已签收",
    "traces": [
      {
        "time": "2024-01-03 10:00:00",
        "content": "已签收"
      }
    ]
  }
}
```

### 5.6 订单取消和退款 (3天)

#### 任务描述
实现订单取消和退款功能

#### 具体工作
- [ ] 实现订单取消接口
- [ ] 实现退款处理逻辑
- [ ] 实现库存回滚机制
- [ ] 实现资产退还逻辑
- [ ] 实现退款状态跟踪

#### 核心接口实现

##### 取消订单接口
```http
POST /api/v1/order/{orderNo}/cancel
Authorization: Bearer {token}
Content-Type: application/json

Request:
{
  "reason": "用户主动取消"
}

Response:
{
  "status": 1,
  "msg": "订单取消成功",
  "data": {
    "refund_info": {
      "refund_amount": "10.00",
      "refund_balance": "10.00",
      "refund_integral": "5.00",
      "refund_coupon": true
    }
  }
}
```

##### 申请退款接口
```http
POST /api/v1/order/{orderNo}/refund
Authorization: Bearer {token}
Content-Type: application/json

Request:
{
  "reason": "商品质量问题",
  "description": "详细说明"
}

Response:
{
  "status": 1,
  "msg": "退款申请提交成功",
  "data": {
    "refund_no": "REF202401010001",
    "estimated_time": "1-3个工作日"
  }
}
```

### 5.6 订单统计和报表 (3天)

#### 任务描述
实现订单统计和报表功能

#### 具体工作
- [ ] 实现订单统计接口
- [ ] 实现销售报表功能
- [ ] 实现用户消费统计
- [ ] 实现商品销售排行
- [ ] 实现数据导出功能

#### 核心接口实现

##### 订单统计接口
```http
GET /api/v1/order/statistics
Authorization: Bearer {token}

Query Parameters:
- start_date: 开始日期
- end_date: 结束日期
- type: 统计类型 (daily, weekly, monthly)

Response:
{
  "status": 1,
  "msg": "请求成功",
  "data": {
    "summary": {
      "total_orders": 1000,
      "total_amount": "10000.00",
      "total_users": 500,
      "avg_order_amount": "10.00"
    },
    "daily_data": [
      {
        "date": "2024-01-01",
        "orders": 50,
        "amount": "500.00",
        "users": 30
      }
    ],
    "top_goods": [
      {
        "goods_id": 123,
        "goods_title": "热门商品",
        "orders": 100,
        "amount": "1000.00"
      }
    ]
  }
}
```

## 库存管理机制

### 库存扣减策略
```csharp
public class InventoryService
{
    // 预扣库存
    public async Task<bool> ReserveInventoryAsync(int goodsId, int goodsNum, int quantity)
    {
        using var transaction = await _context.Database.BeginTransactionAsync();
        try
        {
            // 1. 检查库存
            var goods = await _context.Goods.FindAsync(goodsId);
            if (goods.Stock - goods.SaleStock < quantity)
            {
                return false;
            }
            
            // 2. 扣减库存
            goods.SaleStock += quantity;
            await _context.SaveChangesAsync();
            
            // 3. 记录库存变更
            await RecordInventoryChangeAsync(goodsId, -quantity, "订单预扣");
            
            await transaction.CommitAsync();
            return true;
        }
        catch
        {
            await transaction.RollbackAsync();
            throw;
        }
    }
    
    // 确认扣减库存
    public async Task ConfirmInventoryAsync(string orderNo)
    {
        // 订单支付成功后确认扣减
        // 无需额外操作，预扣已完成
    }
    
    // 回滚库存
    public async Task RollbackInventoryAsync(string orderNo)
    {
        // 订单取消时回滚库存
        var order = await _context.Orders.FirstOrDefaultAsync(o => o.OrderNo == orderNo);
        if (order != null)
        {
            var goods = await _context.Goods.FindAsync(order.GoodsId);
            goods.SaleStock -= order.PrizeNum;
            await _context.SaveChangesAsync();
        }
    }
}
```

### 分布式锁机制
```csharp
public class DistributedLockService
{
    public async Task<T> ExecuteWithLockAsync<T>(string lockKey, Func<Task<T>> action, TimeSpan expiry)
    {
        var lockValue = Guid.NewGuid().ToString();
        var acquired = await _redis.SetAsync(lockKey, lockValue, expiry, When.NotExists);
        
        if (!acquired)
        {
            throw new InvalidOperationException("无法获取锁，请稍后重试");
        }
        
        try
        {
            return await action();
        }
        finally
        {
            // 释放锁
            await ReleaseLockAsync(lockKey, lockValue);
        }
    }
}
```

## 支付集成方案

### 微信支付集成
```csharp
public class WechatPayService
{
    public async Task<WechatPayResult> CreatePaymentAsync(CreatePaymentRequest request)
    {
        var unifiedOrderRequest = new UnifiedOrderRequest
        {
            AppId = _config.AppId,
            MchId = _config.MchId,
            Body = request.Description,
            OutTradeNo = request.OrderNo,
            TotalFee = (int)(request.Amount * 100), // 转换为分
            SpbillCreateIp = request.ClientIp,
            NotifyUrl = _config.NotifyUrl,
            TradeType = "JSAPI",
            OpenId = request.OpenId
        };
        
        var response = await _wechatPayClient.UnifiedOrderAsync(unifiedOrderRequest);
        
        return new WechatPayResult
        {
            AppId = response.AppId,
            TimeStamp = DateTimeOffset.Now.ToUnixTimeSeconds().ToString(),
            NonceStr = GenerateNonceStr(),
            Package = $"prepay_id={response.PrepayId}",
            SignType = "RSA",
            PaySign = GeneratePaySign(/* parameters */)
        };
    }
}
```

## 验收标准

### 功能验收
- [ ] 一番赏订单创建流程完整可用
- [ ] 无限赏订单创建流程完整可用
- [ ] 商城订单创建流程完整可用
- [ ] 订单金额计算准确
- [ ] 支付流程正常
- [ ] 订单查询功能正常
- [ ] 订单取消和退款功能正常
- [ ] 库存管理机制正确
- [ ] 仓库/盒柜管理功能正常
- [ ] 奖品回收功能正常
- [ ] 奖品发货功能正常
- [ ] 物流信息查询正常

### 性能验收
- [ ] 订单创建接口响应时间 < 1000ms
- [ ] 订单查询接口响应时间 < 300ms
- [ ] 支持并发下单 > 50 QPS
- [ ] 库存扣减准确率 100%

### 数据一致性验收
- [ ] 订单金额计算准确性 100%
- [ ] 库存扣减一致性 100%
- [ ] 支付状态同步准确性 100%
- [ ] 用户资产变更准确性 100%

## 风险点和注意事项

### 技术风险
1. **并发控制**: 高并发下单时的库存超卖问题
2. **事务处理**: 复杂业务逻辑的事务一致性
3. **支付安全**: 支付接口的安全性和可靠性
4. **数据一致性**: 订单和库存数据的一致性

### 解决方案
1. **分布式锁**: 使用Redis分布式锁控制并发
2. **事务管理**: 合理使用数据库事务
3. **支付验证**: 严格的支付回调验证机制
4. **监控告警**: 关键业务指标的实时监控

## 下一阶段准备

### 为阶段6准备的内容
- [ ] 微信支付SDK集成
- [ ] 支付安全机制
- [ ] 支付回调处理
- [ ] 退款处理机制

### 交接文档
- [ ] 订单系统架构说明
- [ ] 库存管理机制文档
- [ ] 支付流程说明
- [ ] 数据一致性保障方案

---

**阶段5完成标志**: 订单系统功能完整，包括订单创建、支付、查询、取消等功能正常运行，库存管理准确，数据一致性得到保障。