# 获取店铺今日收益接口文档

## 概述

本文档描述了从 `alien-store`（app端商户）迁移到 `alien-store-platform`（web端商户）的获取店铺今日收益接口。

## 接口详情

### 获取店铺今日收益

**接口描述**：查询指定店铺在当天（00:00:00 至 23:59:59）的总收益，包括所有收入类型（代金券、团购等），返回格式化后的金额（单位：元）。

#### 原接口
- **服务**：alien-store（app端商户）
- **路径**：`GET /alienStore/storeIncomeDetailsRecord/todayIncome?storeId=102`
- **Controller**：`StoreIncomeDetailsRecordController.todayIncome()`
- **Service**：`StoreIncomeDetailsRecordServiceImpl.todayIncome()`

#### 新接口
- **服务**：alien-store-platform（web端商户）
- **路径**：`GET /alienStorePlatform/storeManage/getTodayIncome?storeId=102`
- **Controller**：`StoreManageController.getTodayIncome()`
- **Service**：`StoreManageServiceImpl.getTodayIncome()`

#### 请求参数

**Query 参数**：

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

**请求示例**：

```
GET /alienStorePlatform/storeManage/getTodayIncome?storeId=102
```

#### 响应参数

**成功响应**：

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

**说明**：
- `data` 字段为字符串类型
- 单位：元（人民币）
- 格式：保留两位小数
- 示例值：
  - `"0.00"` - 今日无收益
  - `"123.45"` - 今日收益123.45元
  - `"10000.00"` - 今日收益10000元

**失败响应**：

```json
{
  "code": 500,
  "msg": "{错误信息}",
  "data": null,
  "success": false
}
```

#### 业务逻辑

##### 1. 查询今日收入记录

```java
LambdaQueryWrapper<StoreIncomeDetailsRecord> wrapper = new LambdaQueryWrapper<>();
LocalDate today = LocalDate.now();

wrapper.eq(StoreIncomeDetailsRecord::getStoreId, storeId)
       .ge(StoreIncomeDetailsRecord::getCreatedTime, today + " 00:00:00")
       .le(StoreIncomeDetailsRecord::getCreatedTime, today + " 23:59:59");

List<StoreIncomeDetailsRecord> incomeList = storeIncomeDetailsRecordMapper.selectList(wrapper);
```

**查询条件**：
- **storeId**：店铺ID精确匹配
- **createdTime**：
  - 大于等于（>=）：今日 00:00:00
  - 小于等于（<=）：今日 23:59:59
- **deleteFlag**：自动过滤已删除记录（MyBatis-Plus逻辑删除）

**时间范围说明**：
- 以数据库服务器时间为准
- 包含今日的所有时刻（00:00:00 - 23:59:59）
- 跨天的收入记录按 `createdTime` 归属日期

##### 2. 计算总收益

```java
int totalIncome = 0;
if (incomeList != null && !incomeList.isEmpty()) {
    totalIncome = incomeList.stream()
            .mapToInt(StoreIncomeDetailsRecord::getMoney)
            .sum();
}
```

**计算规则**：
- 遍历所有今日收入记录
- 累加 `money` 字段（单位：分）
- 包含所有收入类型：
  - 代金券收入（incomeType=1）
  - 团购收入（incomeType=2）
  - 其他收入（incomeType=0或其他值）

**空值处理**：
- 如果今日无收入记录 → `totalIncome = 0`
- 如果查询结果为空列表 → `totalIncome = 0`

##### 3. 金额格式转换

```java
String incomeStr = new BigDecimal(totalIncome)
        .divide(new BigDecimal(100), 2, RoundingMode.DOWN)
        .toString();
```

**转换规则**：
- **输入**：`totalIncome`（单位：分，int类型）
- **输出**：`incomeStr`（单位：元，String类型）
- **转换公式**：分 ÷ 100 = 元
- **精度**：保留2位小数
- **舍入模式**：DOWN（向下舍入/截断）

**示例**：

| 原始值（分） | 转换后（元） | 说明 |
|-------------|-------------|------|
| 0 | "0.00" | 无收益 |
| 100 | "1.00" | 1元 |
| 12345 | "123.45" | 123.45元 |
| 123456 | "1234.56" | 1234.56元 |
| 99999 | "999.99" | 999.99元 |
| 1000099 | "10000.99" | 10000.99元 |

**舍入示例**：

| 原始值（分） | DOWN模式 | HALF_UP模式（对比）|
|-------------|----------|-------------------|
| 12344 | "123.44" | "123.44" |
| 12345 | "123.45" | "123.45" |
| 12346 | "123.46" | "123.46" |

注：本接口使用 DOWN 模式，直接截断小数部分，不进行四舍五入。

---

## 数据库表结构

### store_income_details_record（商户收入明细表）

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | INT | 主键，自增 |
| store_id | INT | 店铺ID |
| income_type | INT | 收入类型（0:全部, 1:代金, 2:团购）|
| business_id | INT | 业务ID（优惠券ID或团购ID）|
| money | INT | 收入金额（单位：分）|
| commission | INT | 手续费（单位：分）|
| user_order_id | INT | 用户订单ID |
| cash_out_id | INT | 提现记录ID（提现后才有值）|
| delete_flag | INT | 删除标记（0:未删除, 1:已删除）|
| created_time | DATETIME | 创建时间（收益到账时间）|
| updated_time | DATETIME | 更新时间 |

**重要索引**：
- PRIMARY KEY (`id`)
- INDEX `idx_store_created` (`store_id`, `created_time`)
- INDEX `idx_created_time` (`created_time`)

**说明**：
- `money` 字段存储的是收入金额（不含手续费）
- `commission` 字段存储的是平台手续费
- 实际到账金额 = `money` - `commission`
- 本接口统计的是 `money` 字段总和（收入金额）

---

## 业务场景

### 场景 1：正常查询今日收益

**请求**：
```
GET /alienStorePlatform/storeManage/getTodayIncome?storeId=102
```

**数据库数据**（假设今天是2025-01-15）：

| id | store_id | income_type | money（分）| created_time |
|----|----------|-------------|-----------|--------------|
| 1  | 102      | 1           | 5000      | 2025-01-15 10:30:00 |
| 2  | 102      | 2           | 8000      | 2025-01-15 14:20:00 |
| 3  | 102      | 1           | 3456      | 2025-01-15 18:45:00 |

**计算过程**：
1. 查询今日收入记录：3条
2. 累加金额：5000 + 8000 + 3456 = 16456（分）
3. 转换为元：16456 ÷ 100 = 164.56（元）

**响应**：
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": "164.56",
  "success": true
}
```

---

### 场景 2：今日无收益

**请求**：
```
GET /alienStorePlatform/storeManage/getTodayIncome?storeId=102
```

**数据库数据**：
- 今日（2025-01-15）无收入记录

**响应**：
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": "0.00",
  "success": true
}
```

---

### 场景 3：跨天收益统计

**说明**：收益按 `created_time` 归属日期

**数据库数据**：

| id | store_id | money（分）| created_time |
|----|----------|-----------|--------------|
| 1  | 102      | 5000      | 2025-01-14 23:59:59 |
| 2  | 102      | 8000      | 2025-01-15 00:00:00 |
| 3  | 102      | 3456      | 2025-01-15 23:59:59 |
| 4  | 102      | 2000      | 2025-01-16 00:00:00 |

**2025-01-15 的收益**：
- 包含记录：id=2, id=3
- 总金额：8000 + 3456 = 11456（分）= 114.56（元）

**响应**（查询日期：2025-01-15）：
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": "114.56",
  "success": true
}
```

---

### 场景 4：包含不同收入类型

**数据库数据**：

| id | store_id | income_type | money（分）| created_time | 说明 |
|----|----------|-------------|-----------|--------------|------|
| 1  | 102      | 1           | 5000      | 2025-01-15 10:00:00 | 代金券 |
| 2  | 102      | 2           | 8000      | 2025-01-15 14:00:00 | 团购 |
| 3  | 102      | 0           | 2000      | 2025-01-15 18:00:00 | 其他 |

**统计结果**：
- 所有类型都统计：5000 + 8000 + 2000 = 15000（分）= 150.00（元）

**响应**：
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": "150.00",
  "success": true
}
```

---

## 相关文件

### Controller 层
- `alien-store-platform/src/main/java/shop/alien/storeplatform/controller/StoreManageController.java`

### Service 层
- `alien-store-platform/src/main/java/shop/alien/storeplatform/service/StoreManageService.java`
- `alien-store-platform/src/main/java/shop/alien/storeplatform/service/impl/StoreManageServiceImpl.java`

### Entity/Mapper 层
- `alien-entity/src/main/java/shop/alien/entity/store/StoreIncomeDetailsRecord.java`
- `alien-entity/src/main/java/shop/alien/mapper/StoreIncomeDetailsRecordMapper.java`

---

## 测试建议

### 测试用例 1：正常查询

**前置条件**：
- 店铺ID存在
- 今日有收入记录

```bash
curl -X GET "http://localhost:8080/alienStorePlatform/storeManage/getTodayIncome?storeId=102"
```

**期望结果**：
- 返回今日总收益（元）
- 格式：字符串，保留两位小数
- 示例：`"123.45"`

---

### 测试用例 2：今日无收益

**前置条件**：
- 店铺ID存在
- 今日无收入记录

```bash
curl -X GET "http://localhost:8080/alienStorePlatform/storeManage/getTodayIncome?storeId=102"
```

**期望结果**：
```json
{
  "code": 200,
  "data": "0.00",
  "success": true
}
```

---

### 测试用例 3：跨天查询

**测试步骤**：
1. 在 23:50 查询今日收益
2. 在 00:10 查询今日收益（第二天）
3. 对比两次结果

**期望结果**：
- 两次查询结果不同
- 第二次查询应该是新的一天的收益

---

### 测试用例 4：多种收入类型

**前置条件**：
- 今日有代金券收入
- 今日有团购收入
- 今日有其他类型收入

**期望结果**：
- 返回所有类型收入的总和

---

### 测试用例 5：金额格式验证

**验证不同金额的格式化**：

| 数据库值（分） | API返回（元） |
|---------------|--------------|
| 0 | "0.00" |
| 1 | "0.01" |
| 10 | "0.10" |
| 100 | "1.00" |
| 999 | "9.99" |
| 12345 | "123.45" |
| 1000000 | "10000.00" |

---

## 注意事项

### 1. 时间范围

- ⚠️ **查询范围**：今日 00:00:00 至 23:59:59
- ⚠️ **时区**：使用数据库服务器时间
- ⚠️ **跨天处理**：按 `created_time` 归属日期，不受查询时间影响

### 2. 金额单位

- ⚠️ **数据库存储**：分（Integer）
- ⚠️ **接口返回**：元（String）
- ⚠️ **转换规则**：分 ÷ 100 = 元
- ⚠️ **精度**：保留2位小数
- ⚠️ **舍入模式**：DOWN（向下截断）

### 3. 收入类型

本接口统计所有收入类型：

| income_type | 说明 |
|-------------|------|
| 0 | 全部/其他 |
| 1 | 代金券 |
| 2 | 团购 |

- ⚠️ 不区分收入类型，全部统计
- ⚠️ 如需按类型统计，需要调用其他接口

### 4. 手续费处理

- ⚠️ 本接口统计的是 `money` 字段（收入金额）
- ⚠️ **不扣除** `commission` 字段（手续费）
- ⚠️ 实际到账金额需要减去手续费

**示例**：
```
收入金额（money）: 10000分 = 100.00元
手续费（commission）: 300分 = 3.00元
实际到账: 9700分 = 97.00元

本接口返回: "100.00"（收入金额）
```

### 5. 逻辑删除

- ⚠️ MyBatis-Plus 自动过滤 `delete_flag=1` 的记录
- ⚠️ 已删除的收入记录不会被统计
- ⚠️ 确保业务逻辑正确处理删除标记

### 6. 性能优化

**数据库索引**：
```sql
CREATE INDEX idx_store_created ON store_income_details_record(store_id, created_time);
```

**查询优化**：
- ✅ 使用复合索引（store_id + created_time）
- ✅ 时间范围查询使用字符串拼接（与数据库格式一致）
- ✅ Stream API 高效计算总和

### 7. 数据一致性

- ⚠️ 收益数据可能存在延迟（如T+3到账）
- ⚠️ 本接口统计的是 `created_time`（记录创建时间）
- ⚠️ 实际收益到账时间可能与统计时间不同

---

## 接口对比

| 功能 | 原接口（alien-store） | 新接口（alien-store-platform） |
|------|----------------------|-------------------------------|
| 今日收益 | `/alienStore/storeIncomeDetailsRecord/todayIncome` | `/alienStorePlatform/storeManage/getTodayIncome` |
| Controller | `StoreIncomeDetailsRecordController` | `StoreManageController` |
| Service | `StoreIncomeDetailsRecordService` | `StoreManageService` |

**主要变化**：
- ✅ 接口路径更符合web端命名规范
- ✅ 整合到 `StoreManageController` 统一管理
- ✅ 代码注释更完善，逻辑更清晰

---

## 扩展功能建议

### 1. 按收入类型统计

```java
public Map<Integer, String> getTodayIncomeByType(Integer storeId) {
    // 按 incomeType 分组统计
}
```

### 2. 查询指定日期收益

```java
public String getIncomeByDate(Integer storeId, String date) {
    // 查询指定日期的收益
}
```

### 3. 查询日期范围收益

```java
public String getIncomeByDateRange(Integer storeId, String startDate, String endDate) {
    // 查询日期范围的总收益
}
```

### 4. 今日收益明细

```java
public List<StoreIncomeDetailsRecord> getTodayIncomeDetails(Integer storeId) {
    // 返回今日所有收入记录
}
```

---

## 版本记录

| 版本 | 日期 | 说明 | 作者 |
|------|------|------|------|
| 1.0.0 | 2025-01-xx | 初始版本，迁移今日收益查询功能 | ssk |

---

## 联系方式

如有问题，请联系：
- 开发团队：Alien Cloud Team
- 邮箱：dev@alien.shop