根据手机号获取商户用户信息接口文档

概述

本文档描述了从 alien-store（app端商户）迁移到 alien-store-platform（web端商户）的根据手机号获取商户用户信息接口。

接口详情

根据手机号获取商户用户信息

接口描述：根据商户手机号查询商户用户的完整信息，包括基本信息、账户状态、余额等，如果用户处于注销中状态，会返回注销倒计时。

原接口

服务：alien-store（app端商户）
路径：GET /alienStore/store/user/getUserByPhone?phone=15242687180
Controller：StoreUserController.getUserByPhone()
Service：StoreUserServiceImpl.getUserByPhone()

新接口

服务：alien-store-platform（web端商户）
路径：GET /alienStorePlatform/merchantUser/getMerchantByPhone?phone=15242687180
Controller：MerchantUserController.getMerchantByPhone()
Service：MerchantUserServiceImpl.getMerchantByPhone()

请求参数

Query 参数：

参数名	类型	必填	说明
phone	String	是	商户手机号

请求示例：

GET /alienStorePlatform/merchantUser/getMerchantByPhone?phone=15242687180

响应参数

成功响应（用户存在）：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 123,
    "phone": "15242687180",
    "name": "张三",
    "nickName": "店铺老板",
    "headImg": "https://example.com/avatar.jpg",
    "accountBlurb": "这是一家优质店铺",
    "storeId": 102,
    "status": 1,
    "money": 10000,
    "moneyStr": "100.00",
    "payPassword": "******",
    "idCard": "410***********1234",
    "realName": "张三",
    "logoutFlag": 0,
    "logoutTime": null,
    "logoutReason": null,
    "countdown": 0,
    "createdTime": "2024-01-01 10:00:00",
    "updatedTime": "2025-01-15 14:30:00"
  },
  "success": true
}

成功响应（用户不存在）：

{
  "code": 500,
  "msg": "手机号不存在",
  "data": null,
  "success": false
}

成功响应（用户注销中）：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 123,
    "phone": "15242687180",
    "name": "张三",
    "status": -1,
    "money": 10000,
    "moneyStr": "100.00",
    "logoutFlag": 1,
    "logoutTime": "2025-01-15 10:00:00",
    "logoutReason": "个人原因",
    "countdown": 518400000,
    "createdTime": "2024-01-01 10:00:00",
    "updatedTime": "2025-01-15 10:00:00"
  },
  "success": true
}

失败响应（查询错误）：

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

响应字段说明

基本信息字段

字段名	类型	说明
id	Integer	商户用户ID
phone	String	手机号
name	String	真实姓名
nickName	String	昵称
headImg	String	头像URL
accountBlurb	String	账户简介
storeId	Integer	绑定的店铺ID
idCard	String	身份证号
realName	String	实名

状态相关字段

字段名	类型	说明
status	Integer	账户状态（-1:注销中, 1:正常, 0:禁用）
logoutFlag	Integer	注销标记（0:正常, 1:已申请注销）
logoutTime	DateTime	注销申请时间
logoutReason	String	注销原因
countdown	Long	注销倒计时（毫秒），仅当status=-1时有值

财务相关字段

字段名	类型	说明
money	Integer	账户余额（单位：分）
moneyStr	String	账户余额（单位：元，格式化后）
payPassword	String	支付密码（脱敏）

时间相关字段

字段名	类型	说明
createdTime	DateTime	创建时间
updatedTime	DateTime	更新时间

业务逻辑

1. 用户查询

LambdaQueryWrapper<StoreUser> queryWrapper = new LambdaQueryWrapper<>();
queryWrapper.eq(StoreUser::getPhone, phone);
StoreUser user = storeUserMapper.selectOne(queryWrapper);

根据手机号查询 store_user 表
使用 MyBatis-Plus 的 LambdaQueryWrapper
查询条件：phone 字段精确匹配

2. 用户不存在处理

if (user == null) {
    return new StoreUserVo();  // 返回空对象
}

如果查询结果为空，返回空的 StoreUserVo 对象
Controller 层判断 id 是否为空，返回"手机号不存在"

3. 注销倒计时计算（仅当 status=-1）

if (user.getStatus() == -1) {
    // 获取注销申请时间
    LocalDateTime logoutDateTime = user.getLogoutTime()
            .toInstant()
            .atZone(ZoneId.systemDefault())
            .toLocalDateTime();
    
    // 计算7天后的时间（冷静期结束时间）
    LocalDateTime futureDateTime = logoutDateTime.plusDays(7);
    
    // 获取当前时间
    LocalDateTime nowDateTime = LocalDateTime.now();
    
    // 计算剩余时间
    Duration duration = Duration.between(nowDateTime, futureDateTime);
    
    // 转换为毫秒
    long countdownMillis = duration.toMillis();
    
    storeUserVo.setCountdown(countdownMillis);
}

注销倒计时说明：

触发条件：status = -1（账户注销中）
计算逻辑：
- 冷静期：7天
- 起始时间：logoutTime（注销申请时间）
- 结束时间：logoutTime + 7天
- 倒计时：结束时间 - 当前时间
单位：毫秒（milliseconds）
示例：
- 注销申请时间：2025-01-15 10:00:00
- 冷静期结束时间：2025-01-22 10:00:00
- 当前时间：2025-01-16 10:00:00
- 倒计时：6天 = 518400000毫秒

4. 金额格式转换

String moneyStr = new BigDecimal(user.getMoney())
        .divide(new BigDecimal(100), 2, RoundingMode.DOWN)
        .toString();
storeUserVo.setMoneyStr(moneyStr);

输入：money 字段（单位：分，Integer类型）
输出：moneyStr 字段（单位：元，String类型）
转换规则：
- 除以100转换为元
- 保留2位小数
- 舍入模式：DOWN（向下舍入）
示例：
- money = 10000 → moneyStr = "100.00"
- money = 12345 → moneyStr = "123.45"
- money = 12346 → moneyStr = "123.46"

5. 返回结果

使用 BeanUtils.copyProperties() 复制用户基本信息
设置 moneyStr 字段
如果是注销中状态，设置 countdown 字段
返回完整的 StoreUserVo 对象

业务场景

场景 1：正常用户查询

请求：

GET /alienStorePlatform/merchantUser/getMerchantByPhone?phone=15242687180

用户状态：

status = 1（正常）
logoutFlag = 0（未申请注销）

响应特点：

✅ 返回完整用户信息
✅ countdown 为 0（未计算）
✅ moneyStr 为格式化后的金额

场景 2：注销中的用户

请求：

GET /alienStorePlatform/merchantUser/getMerchantByPhone?phone=15242687180

用户状态：

status = -1（注销中）
logoutFlag = 1（已申请注销）
logoutTime = 2025-01-15 10:00:00

响应特点：

✅ 返回完整用户信息
✅ countdown 为剩余冷静期时间（毫秒）
⚠️ 用户在冷静期内可以撤销注销
⚠️ 冷静期结束后账户将被永久注销

场景 3：用户不存在

请求：

GET /alienStorePlatform/merchantUser/getMerchantByPhone?phone=99999999999

响应：

{
  "code": 500,
  "msg": "手机号不存在",
  "data": null,
  "success": false
}

数据库表结构

store_user（商户用户表）

字段名	类型	说明
id	INT	主键，自增
phone	VARCHAR(11)	手机号（唯一）
name	VARCHAR(50)	真实姓名
nick_name	VARCHAR(50)	昵称
head_img	VARCHAR(255)	头像URL
account_blurb	TEXT	账户简介
store_id	INT	绑定的店铺ID
status	INT	账户状态（-1:注销中, 0:禁用, 1:正常）
money	INT	账户余额（单位：分）
pay_password	VARCHAR(100)	支付密码（加密）
id_card	VARCHAR(18)	身份证号
real_name	VARCHAR(50)	实名
logout_flag	INT	注销标记（0:正常, 1:已申请注销）
logout_time	DATETIME	注销申请时间
logout_reason	VARCHAR(255)	注销原因
delete_flag	INT	删除标记（0:未删除, 1:已删除）
created_time	DATETIME	创建时间
updated_time	DATETIME	更新时间

重要索引：

PRIMARY KEY (id)
UNIQUE KEY uk_phone (phone)

测试建议

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

curl -X GET "http://localhost:8080/alienStorePlatform/merchantUser/getMerchantByPhone?phone=15242687180"

期望结果：

返回完整用户信息
status = 1
logoutFlag = 0
countdown = 0
moneyStr 格式正确（如："100.00"）

测试用例 2：查询注销中的用户

前置条件：

用户已申请注销
status = -1

logoutTime 在过去7天内

curl -X GET "http://localhost:8080/alienStorePlatform/merchantUser/getMerchantByPhone?phone=15242687180"

期望结果：

返回用户信息
status = -1
logoutFlag = 1
countdown > 0（倒计时为正数）
logoutTime 和 logoutReason 有值

测试用例 3：查询不存在的用户

curl -X GET "http://localhost:8080/alienStorePlatform/merchantUser/getMerchantByPhone?phone=99999999999"

期望结果：

{
  "code": 500,
  "msg": "手机号不存在",
  "data": null,
  "success": false
}

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

测试不同金额值的转换：

原始值（分）	期望值（元）
0	"0.00"
100	"1.00"
12345	"123.45"
99999	"999.99"

测试用例 5：注销倒计时计算

场景：用户在不同时间点查询倒计时

注销申请时间	查询时间	期望倒计时
2025-01-15 10:00:00	2025-01-16 10:00:00	6天 = 518400000ms
2025-01-15 10:00:00	2025-01-22 09:00:00	1小时 = 3600000ms
2025-01-15 10:00:00	2025-01-22 10:00:00	0ms（冷静期结束）
2025-01-15 10:00:00	2025-01-23 10:00:00	负数（已超期）

注意事项

1. 账户状态说明

status 值	状态	说明
-1	注销中	冷静期内，可撤销注销
0	禁用	账户被管理员禁用
1	正常	账户正常使用

2. 注销冷静期机制

⚠️ 冷静期时长：7天（从申请注销时间开始计算）
⚠️ 冷静期内：
- 账户 status = -1
- logoutFlag = 1
- 用户可以撤销注销申请
- 返回 countdown 倒计时（毫秒）
⚠️ 冷静期结束后：
- 账户将被永久注销
- 所有数据将被清除
- 无法恢复

3. 金额字段处理

⚠️ 存储单位：分（Integer）
⚠️ 展示单位：元（String）
⚠️ 转换规则：
- 分 ÷ 100 = 元
- 保留2位小数
- 向下舍入（RoundingMode.DOWN）
⚠️ 示例：10000分 = 100.00元

4. 手机号查询

⚠️ 查询字段：phone（手机号字段）
⚠️ 唯一性：手机号在数据库中是唯一的
⚠️ 查询结果：
- 如果存在：返回唯一的用户记录
- 如果不存在：返回 null

5. 空对象处理

if (user == null) {
    return new StoreUserVo();  // 返回空对象，不是null
}

Service 层返回空对象（不是 null）
Controller 层通过 id 字段判断是否为空
避免空指针异常

6. 时区处理

LocalDateTime localDateTime = logoutTime
    .toInstant()
    .atZone(ZoneId.systemDefault())
    .toLocalDateTime();

使用系统默认时区
确保时间计算的准确性
避免时区转换错误

接口对比

功能	原接口（alien-store）	新接口（alien-store-platform）
根据手机号查询	`/alienStore/store/user/getUserByPhone`	`/alienStorePlatform/merchantUser/getMerchantByPhone`
返回类型	`R<StoreUser>`	`R<StoreUserVo>`

主要变化：

✅ 接口路径更符合web端命名规范
✅ Controller和Service命名更清晰（MerchantUser）
✅ 返回类型统一为 StoreUserVo（扩展字段更丰富）
✅ 代码结构更清晰，注释更完善

版本记录

版本	日期	说明	作者
1.0.0	2025-01-xx	初始版本，迁移商户用户查询功能	ssk

联系方式

如有问题，请联系：

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

API_MERCHANT_USER.md 13 KB لینک دائمی تاريخچه خام

根据手机号获取商户用户信息接口文档

概述

接口详情

根据手机号获取商户用户信息

原接口

新接口

请求参数

响应参数

响应字段说明

基本信息字段

状态相关字段

财务相关字段

时间相关字段

业务逻辑

1. 用户查询

2. 用户不存在处理

3. 注销倒计时计算（仅当 status=-1）

4. 金额格式转换

5. 返回结果

业务场景

场景 1：正常用户查询

场景 2：注销中的用户

场景 3：用户不存在

数据库表结构

store_user（商户用户表）

相关文件

Controller 层

Service 层

Entity/Mapper 层

测试建议

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

测试用例 2：查询注销中的用户

测试用例 3：查询不存在的用户

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

测试用例 5：注销倒计时计算

注意事项

1. 账户状态说明

2. 注销冷静期机制

3. 金额字段处理

4. 手机号查询

5. 空对象处理

6. 时区处理

接口对比

版本记录

联系方式

API_MERCHANT_USER.md 13 KB

لینک دائمی تاريخچه خام