# 店铺今日订单数接口文档

## 接口信息

### 接口名称
获取店铺今日订单数

### 接口路径
`GET /storeManage/getTodayOrderCount`

### 接口描述
查询指定店铺今日的有效订单数量（排除待支付、已取消、已过期状态的订单）

---

## 请求参数

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| storeId | Integer | 是 | 店铺ID |

### 请求示例

```http
GET /storeManage/getTodayOrderCount?storeId=102
```

---

## 响应参数

### 响应数据结构

```json
{
    "code": 200,
    "success": true,
    "data": 15,
    "msg": "查询成功"
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 响应状态码，200表示成功 |
| success | Boolean | 是否成功 |
| data | Integer | 今日有效订单数量 |
| msg | String | 响应消息 |

---

## 业务逻辑说明

### 1. 订单统计规则
- **时间范围**：当天 00:00:00 至 23:59:59
- **排除状态**：
  - 待支付 (0)
  - 已取消 (4)
  - 已过期 (3)
- **包含状态**：
  - 已支付/待使用 (1)
  - 已核销 (2)
  - 已退款 (5)
  - 退款失败 (6)
  - 已完成 (7)

### 2. 查询条件
```java
// 查询今日的订单
wrapper.eq(LifeUserOrder::getStoreId, storeId)
       .notIn(LifeUserOrder::getStatus, 
              OrderStatusEnum.CANCEL.getStatus(),      // 4-已取消
              OrderStatusEnum.WAIT_PAY.getStatus(),    // 0-待支付
              OrderStatusEnum.EXPIRE.getStatus())      // 3-已过期
       .between(LifeUserOrder::getBuyTime, 
                today + " 00:00:00", 
                today + " 23:59:59");
```

### 3. 数据来源
- **数据表**：`life_user_order`
- **关联实体**：`LifeUserOrder`
- **Mapper**：`LifeUserOrderMapper`

---

## 技术实现

### Controller 层
**文件路径**：`alien-store-platform/src/main/java/shop/alien/storeplatform/controller/StoreManageController.java`

```java
@ApiOperation("获取店铺今日订单数")
@ApiOperationSupport(order = 6)
@ApiImplicitParams({
    @ApiImplicitParam(name = "storeId", value = "店铺ID", 
                     dataType = "Integer", paramType = "query", required = true)
})
@GetMapping("/getTodayOrderCount")
public R<Integer> getTodayOrderCount(@RequestParam("storeId") Integer storeId) {
    log.info("StoreManageController.getTodayOrderCount?storeId={}", storeId);
    try {
        Integer count = storeManageService.getTodayOrderCount(storeId);
        return R.data(count, "查询成功");
    } catch (Exception e) {
        log.error("StoreManageController.getTodayOrderCount ERROR: {}", 
                 e.getMessage(), e);
        return R.fail(e.getMessage());
    }
}
```

### Service 层
**文件路径**：`alien-store-platform/src/main/java/shop/alien/storeplatform/service/StoreManageService.java`

```java
/**
 * 获取店铺今日订单数
 *
 * @param storeId 店铺ID
 * @return 今日订单数
 */
Integer getTodayOrderCount(Integer storeId);
```

### Service 实现层
**文件路径**：`alien-store-platform/src/main/java/shop/alien/storeplatform/service/impl/StoreManageServiceImpl.java`

```java
@Override
public Integer getTodayOrderCount(Integer storeId) {
    log.info("StoreManageServiceImpl.getTodayOrderCount - 查询店铺今日订单数: storeId={}", 
             storeId);
    
    // 1. 构建查询条件
    LambdaQueryWrapper<LifeUserOrder> wrapper = new LambdaQueryWrapper<>();
    LocalDate today = LocalDate.now();
    
    // 2. 查询今日的订单，排除待支付、已取消、已过期状态
    wrapper.eq(LifeUserOrder::getStoreId, storeId)
           .notIn(LifeUserOrder::getStatus, 
                  OrderStatusEnum.CANCEL.getStatus(), 
                  OrderStatusEnum.WAIT_PAY.getStatus(), 
                  OrderStatusEnum.EXPIRE.getStatus())
           .between(LifeUserOrder::getBuyTime, 
                    today + " 00:00:00", 
                    today + " 23:59:59");
    
    // 3. 统计订单数量
    Integer count = lifeUserOrderMapper.selectCount(wrapper);
    
    log.info("StoreManageServiceImpl.getTodayOrderCount - 查询完成: storeId={}, 今日订单数={}", 
             storeId, count);
    return count;
}
```

---

## 依赖注入

### Service 实现类新增依赖
```java
private final LifeUserOrderMapper lifeUserOrderMapper;
```

### 新增导入
```java
import shop.alien.entity.store.LifeUserOrder;
import shop.alien.util.common.constant.OrderStatusEnum;
```

---

## 原接口对比

### 原接口信息
- **服务**：alien-store（app端商户）
- **路径**：`/alienStore/storeIncomeDetailsRecord/todayOrderCount`
- **Controller**：`StoreIncomeDetailsRecordController`
- **Service**：`StoreIncomeDetailsRecordService`

### 新接口信息
- **服务**：alien-store-platform（web端商户）
- **路径**：`/storeManage/getTodayOrderCount`
- **Controller**：`StoreManageController`
- **Service**：`StoreManageService`

### 命名对比
| 原接口 | 新接口 | 说明 |
|--------|--------|------|
| todayOrderCount | getTodayOrderCount | 符合web端命名规范 |
| /storeIncomeDetailsRecord/ | /storeManage/ | 统一归类到店铺管理模块 |

---

## 错误处理

### 异常情况
1. **参数错误**：storeId 为空或无效
2. **数据库异常**：查询失败

### 错误响应示例
```json
{
    "code": 500,
    "success": false,
    "data": null,
    "msg": "查询失败：数据库连接异常"
}
```

---

## 测试建议

### 测试场景
1. **正常场景**：查询有订单的店铺
2. **空数据场景**：查询今日无订单的店铺（应返回0）
3. **边界场景**：查询不存在的店铺ID（应返回0）
4. **状态过滤**：验证待支付、已取消、已过期订单是否被排除

### 测试数据
```sql
-- 查询店铺今日订单（用于验证）
SELECT 
    COUNT(*) AS order_count
FROM life_user_order
WHERE store_id = 102
  AND status NOT IN (0, 3, 4)  -- 排除待支付、已过期、已取消
  AND buy_time BETWEEN '2025-11-12 00:00:00' AND '2025-11-12 23:59:59'
  AND delete_flag = 0;
```

---

## 相关接口

- **今日收益接口**：`GET /storeManage/getTodayIncome`
- **店铺详情接口**：`GET /storeManage/getStoreDetail`
- **店铺入住申请**：`POST /storeManage/applyStore`

---

## 注意事项

1. **订单状态枚举**：使用 `OrderStatusEnum` 确保状态码一致性
2. **时间范围**：使用 `LocalDate.now()` 获取当天日期，确保时区正确
3. **性能优化**：订单数量统计使用 `selectCount` 而非查询全部数据
4. **逻辑删除**：MyBatis-Plus 自动处理 `delete_flag` 字段
5. **日志记录**：记录查询参数和结果，便于问题追踪

---

## 更新日志

### 2025-11-12
- ✅ 完成接口迁移：从 alien-store 迁移到 alien-store-platform
- ✅ Controller 层：添加 `getTodayOrderCount` 接口
- ✅ Service 层：添加 `getTodayOrderCount` 方法定义
- ✅ Service 实现层：实现今日订单数查询逻辑
- ✅ 依赖注入：添加 `LifeUserOrderMapper` 和 `OrderStatusEnum` 导入
- ✅ Linter 检查：无错误
- ✅ 业务逻辑：完全复用原接口逻辑
- ✅ 命名规范：符合web端命名规范

---

## 开发者信息

- **迁移时间**：2025-11-12
- **原服务**：alien-store（app端商户）
- **目标服务**：alien-store-platform（web端商户）
- **技术栈**：Spring Boot + MyBatis-Plus + Java 8