Web端商户店铺入住接口开发文档

一、接口概述

本次开发在 alien-store-platform 服务中新增了商户店铺入住申请接口，将原 alien-store 服务中的 /store/info/saveStoreInfo 接口迁移到 web 端商户平台，实现相同的业务逻辑。

二、接口信息

2.1 基本信息

接口路径： POST /storeManage/applyStore

原接口路径： POST /alienStore/store/info/saveStoreInfo

接口说明： 商户提交店铺入住申请，创建店铺信息并进入审批流程

Content-Type： application/json

2.2 请求参数（StoreInfoDto）

参数名	类型	必填	说明	示例
storeName	String	是	店铺名称	"张三烧烤店"
storeContact	String	是	联系人	"张三"
storePhone	String	是	联系电话	"13800138000"
storeAddress	String	是	店铺地址	"北京市朝阳区xxx街道"
storePositionLongitude	String	是	经度	"116.4074"
storePositionLatitude	String	是	纬度	"39.9042"
businessSection	Integer	是	经营板块ID	1
businessTypes	List<String>	是	经营种类ID列表	["101", "102"]
administrativeRegionProvinceAdcode	String	是	省份行政区划代码	"110000"
administrativeRegionCityAdcode	String	是	城市行政区划代码	"110100"
administrativeRegionDistrictAdcode	String	是	区县行政区划代码	"110105"
businessLicenseAddress	List<String>	是	营业执照图片URL列表	["https://xxx/license.jpg"]
contractImageList	List<String>	否	合同图片URL列表	["https://xxx/contract.jpg"]
foodLicenceUrl	String	否	经营许可证图片URL	"https://xxx/licence.jpg"
storePass	String	否	店铺密码（默认123456）	"123456"
storeStatus	Integer	是	店铺状态	1
userAccount	String	是	商户用户ID	"1001"
idCard	String	否	身份证号	"110101199001011234"
commissionRate	String	否	抽成比例（默认3%）	"3"

2.3 请求示例

POST /storeManage/applyStore
Content-Type: application/json

{
  "storeName": "张三烧烤店",
  "storeContact": "张三",
  "storePhone": "13800138000",
  "storeAddress": "北京市朝阳区xxx街道100号",
  "storePositionLongitude": "116.4074",
  "storePositionLatitude": "39.9042",
  "businessSection": 1,
  "businessTypes": ["101", "102"],
  "administrativeRegionProvinceAdcode": "110000",
  "administrativeRegionCityAdcode": "110100",
  "administrativeRegionDistrictAdcode": "110105",
  "businessLicenseAddress": ["https://example.com/license.jpg"],
  "contractImageList": ["https://example.com/contract1.jpg"],
  "foodLicenceUrl": "https://example.com/food-licence.jpg",
  "storePass": "888888",
  "storeStatus": 1,
  "userAccount": "1001",
  "idCard": "110101199001011234",
  "commissionRate": "3"
}

2.4 响应示例

成功响应：

{
  "code": 200,
  "success": true,
  "msg": "店铺入住申请已提交",
  "data": {
    "id": 12345
  }
}

失败响应：

{
  "code": 500,
  "success": false,
  "msg": "经营板块不存在：99",
  "data": null
}

三、业务流程说明

3.1 完整业务流程

1. 接收店铺入住申请数据
   ↓
2. 查询经营板块信息
   ↓
3. 查询经营种类信息
   ↓
4. 构建店铺信息对象
   ├─ 设置店铺基本信息
   ├─ 设置经纬度
   ├─ 设置店铺密码（默认123456）
   ├─ 设置经营板块和类型
   ├─ 设置审批状态为"待审批"
   └─ 设置行政区域信息
   ↓
5. 插入店铺信息到数据库
   ↓
6. 添加地理位置到Redis（用于附近商家搜索）
   ↓
7. 更新商户用户绑定关系
   ↓
8. 保存店铺相关图片
   ├─ 营业执照图片（imgType=14）
   ├─ 合同图片（imgType=15）
   └─ 经营许可证图片（imgType=25）
   ↓
9. 初始化店铺标签
   ↓
10. 发送入住申请通知给商户
   ↓
11. 返回店铺ID

3.2 关键业务规则

1. 店铺密码规则

默认密码：123456
如果用户设置密码且不为默认密码，则使用用户密码
passType=0：初始密码，passType=1：已修改密码

2. 审批状态

新提交的店铺统一设置为 storeApplicationStatus=0（待审批）
状态说明：
- 0：待审批
- 1：审批通过
- 2：审批失败

3. 抽成比例

默认抽成比例：3%
如果未指定，自动设置为3

4. 行政区域处理

根据行政区划代码（adCode）自动填充省市区名称
查询 essential_city_code 表获取区域名称

5. 地理位置存储

将店铺经纬度存储到 Redis GEO 数据结构
用于后续"附近商家"功能
存储Key：geo:store:primary

四、数据库操作

4.1 插入操作

store_info 表

插入店铺基本信息
包含：名称、地址、经纬度、经营信息、审批状态等

store_img 表

插入3种类型的图片：
- imgType=14：营业执照
- imgType=15：合同图片
- imgType=25：经营许可证

tag_store_relation 表

初始化店铺标签关系
用于后续标签功能

life_notice 表

发送入住申请通知消息

4.2 更新操作

store_user 表

更新商户用户的 storeId（绑定店铺）
更新联系人姓名（storeContact）
更新身份证号（idCard）

4.3 查询操作

store_dictionary 表

查询经营板块信息
查询经营种类信息

essential_city_code 表

查询省市区名称

五、Redis操作

5.1 GEO地理位置存储

Key： geo:store:primary

操作：

GEOADD geo:store:primary 经度 纬度 店铺ID

示例：

GEOADD geo:store:primary 116.4074 39.9042 "12345"

用途：

支持"附近商家"功能
根据用户位置搜索周边店铺

六、通知消息

6.1 入住申请通知

接收人： store_{商户手机号}

消息内容：

您在2025-01-15 14:30:00提交的入驻店铺申请，平台已受理，1-3个工作日将审核结果发送至应用内的消息-通知中，请注意查收。

通知类型： noticeType=1（系统通知）

发送人： system

七、代码结构

7.1 新增文件列表

alien-store-platform/
├── controller/
│   └── StoreManageController.java         # 店铺管理控制器
├── service/
│   ├── StoreManageService.java            # 店铺管理服务接口
│   └── impl/
│       └── StoreManageServiceImpl.java    # 店铺管理服务实现
└── util/
    └── NearMeUtil.java                     # 附近商家地理位置工具类

7.2 依赖注入

StoreManageServiceImpl 依赖：

StoreInfoMapper：店铺信息Mapper
StoreDictionaryMapper：字典Mapper
EssentialCityCodeMapper：城市编码Mapper
StoreUserMapper：商户用户Mapper
StoreImgMapper：店铺图片Mapper
TagStoreRelationMapper：标签关系Mapper
LifeNoticeMapper：通知消息Mapper
NearMeUtil：地理位置工具类

NearMeUtil 依赖：

StringRedisTemplate：Redis操作模板

八、图片类型说明

8.1 店铺图片类型（img_type）

类型值	类型名称	说明	是否必填
14	营业执照	店铺营业执照图片	✅ 必填
15	合同图片	店铺与平台的合同图片	❌ 可选
25	经营许可证	食品经营许可证等	❌ 可选

8.2 图片存储说明

图片URL应该是已上传到OSS的地址
营业执照可以有多张
合同图片可以有多张
经营许可证只能有一张

九、测试用例

测试用例1：完整信息提交

curl -X POST "http://localhost:8080/storeManage/applyStore" \
  -H "Content-Type: application/json" \
  -d '{
    "storeName": "测试烧烤店",
    "storeContact": "测试联系人",
    "storePhone": "13800138000",
    "storeAddress": "北京市朝阳区测试街道100号",
    "storePositionLongitude": "116.4074",
    "storePositionLatitude": "39.9042",
    "businessSection": 1,
    "businessTypes": ["101", "102"],
    "administrativeRegionProvinceAdcode": "110000",
    "administrativeRegionCityAdcode": "110100",
    "administrativeRegionDistrictAdcode": "110105",
    "businessLicenseAddress": ["https://example.com/license.jpg"],
    "storeStatus": 1,
    "userAccount": "1001"
  }'

测试用例2：包含可选字段

curl -X POST "http://localhost:8080/storeManage/applyStore" \
  -H "Content-Type: application/json" \
  -d '{
    "storeName": "测试餐厅",
    "storeContact": "张经理",
    "storePhone": "13900139000",
    "storeAddress": "上海市浦东新区测试路200号",
    "storePositionLongitude": "121.4737",
    "storePositionLatitude": "31.2304",
    "businessSection": 1,
    "businessTypes": ["101"],
    "administrativeRegionProvinceAdcode": "310000",
    "administrativeRegionCityAdcode": "310100",
    "administrativeRegionDistrictAdcode": "310115",
    "businessLicenseAddress": ["https://example.com/license.jpg"],
    "contractImageList": ["https://example.com/contract.jpg"],
    "foodLicenceUrl": "https://example.com/food.jpg",
    "storePass": "888888",
    "storeStatus": 1,
    "userAccount": "1002",
    "idCard": "310101199001011234",
    "commissionRate": "5"
  }'

十、异常处理

10.1 常见异常

异常情况	错误信息	处理建议
经营板块不存在	"经营板块不存在：{id}"	检查businessSection参数
商户用户不存在	"未找到商户用户"	检查userAccount参数
行政区划代码错误	查询结果为空	检查adCode参数
Redis连接失败	地理位置添加失败（仅警告）	不影响主流程
数据库操作失败	事务回滚	检查数据完整性

10.2 事务处理

使用 @Transactional 注解
任何异常都会触发事务回滚
确保数据一致性

十一、技术亮点

代码复用：完全复用原接口业务逻辑
事务管理：使用声明式事务确保数据一致性
异常处理：完善的异常捕获和日志记录
解耦设计：工具类独立，便于测试和维护
Redis集成：支持地理位置搜索功能
消息通知：自动发送入住申请通知

十二、部署检查清单

确认数据库表结构完整
- store_info
- store_img
- store_user
- store_dictionary
- essential_city_code
- tag_store_relation
- life_notice
确认Redis可用
确认所有Mapper已注册
确认事务配置正确
测试地理位置存储功能
测试通知消息发送功能

十三、接口对比

对比项	原接口	新接口
服务	alien-store	alien-store-platform
路径	`/store/info/saveStoreInfo`	`/storeManage/applyStore`
方法	POST	POST
参数	StoreInfoDto	StoreInfoDto
返回	StoreInfoVo	StoreInfoVo
业务逻辑	✅ 完全一致	✅ 完全一致

开发完成时间： 2025-01-xx
开发人员： AI Assistant
版本号： v1.0.0

API_STORE_APPLY.md 11 KB Permalink History Raw