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

概述

本文档描述了从 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

响应参数

成功响应：

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

说明：

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

失败响应：

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

业务逻辑

1. 查询今日收入记录

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. 计算总收益

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. 金额格式转换

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

计算过程：

查询今日收入记录：3条
累加金额：5000 + 8000 + 3456 = 16456（分）
转换为元：16456 ÷ 100 = 164.56（元）

响应：

{
  "code": 200,
  "msg": "查询成功",
  "data": "164.56",
  "success": true
}

场景 2：今日无收益

请求：

GET /alienStorePlatform/storeManage/getTodayIncome?storeId=102

数据库数据：

今日（2025-01-15）无收入记录

响应：

{
  "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）：

{
  "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（元）

响应：

{
  "code": 200,
  "msg": "查询成功",
  "data": "150.00",
  "success": true
}

测试建议

测试用例 1：正常查询

前置条件：

店铺ID存在

今日有收入记录

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

期望结果：

返回今日总收益（元）
格式：字符串，保留两位小数
示例："123.45"

测试用例 2：今日无收益

前置条件：

店铺ID存在

今日无收入记录

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

期望结果：

{
  "code": 200,
  "data": "0.00",
  "success": true
}

测试用例 3：跨天查询

测试步骤：

在 23:50 查询今日收益
在 00:10 查询今日收益（第二天）
对比两次结果

期望结果：

两次查询结果不同
第二次查询应该是新的一天的收益

测试用例 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. 性能优化

数据库索引：

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. 按收入类型统计

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

2. 查询指定日期收益

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

3. 查询日期范围收益

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

4. 今日收益明细

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

版本记录

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

联系方式

如有问题，请联系：

开发团队：Alien Cloud Team
邮箱：dev@alien.shop

API_TODAY_INCOME.md 13 KB Permalink Istoric Crud

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

概述

接口详情

获取店铺今日收益

原接口

新接口

请求参数

响应参数

业务逻辑

1. 查询今日收入记录

2. 计算总收益

3. 金额格式转换

数据库表结构

store_income_details_record（商户收入明细表）

业务场景

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

场景 2：今日无收益

场景 3：跨天收益统计

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

相关文件

Controller 层

Service 层

Entity/Mapper 层

测试建议

测试用例 1：正常查询

测试用例 2：今日无收益

测试用例 3：跨天查询

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

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

注意事项

1. 时间范围

2. 金额单位

3. 收入类型

4. 手续费处理

5. 逻辑删除

6. 性能优化

7. 数据一致性

接口对比

扩展功能建议

1. 按收入类型统计

2. 查询指定日期收益

3. 查询日期范围收益

4. 今日收益明细

版本记录

联系方式

API_TODAY_INCOME.md 13 KB

Permalink Istoric Crud