alien_cloud/alien-store-platform/doc/API_STORE_DRAFT.md

店铺入住申请草稿接口文档

概述

本文档描述了从 alien-store（app端商户）迁移到 alien-store-platform（web端商户）的店铺入住申请草稿相关接口。

接口列表

1. 保存店铺入住申请草稿

接口描述：保存商户填写的店铺入住申请草稿信息，支持随时保存，方便商户分多次填写。

原接口

• 服务：alien-store（app端商户）
• 路径：POST /alienStore/store/info/saveStoreInfoDraft
• Controller：StoreInfoController.saveStoreInfoDraft()
• Service：StoreInfoServiceImpl.saveStoreInfoDraft()

新接口

• 服务：alien-store-platform（web端商户）
• 路径：POST /alienStorePlatform/storeManage/saveStoreDraft
• Controller：StoreManageController.saveStoreDraft()
• Service：StoreManageServiceImpl.saveStoreDraft()

请求参数

Content-Type: application/json

Body 参数：StoreInfoDraft 对象

参数名	类型	必填	说明
storeUserId	Integer	是	商家用户ID（store_user 表 id）
storeName	String	否	门店名称
businessStatus	Integer	否	营业状态（见字典表 businessStatus）
storeTel	String	否	门店电话
storeCapacity	Integer	否	容纳人数
storeArea	Integer	否	门店面积（见字典表 storeArea）
storeAddress	String	否	门店地址
storeBlurb	String	否	门店简介
storeType	String	否	门店类型，多选（见字典表 storeType）
isChain	Integer	否	是否连锁（0:否, 1:是）
storePosition	String	否	经度,纬度
storePass	String	否	门店密码
passType	Integer	否	密码状态（0:初始密码, 1:已修改）
storeStatus	Integer	否	门店状态（见字典表 storeStatus）
businessSection	Integer	否	经营板块ID（词典表 business_section）
businessSectionName	String	否	经营板块名称
businessTypes	String	否	经营种类IDs（逗号分隔）
businessTypesName	String	否	经营种类名称（逗号分隔）
queryAddress	String	否	查询经纬度时查询地点存储
administrativeRegionProvinceName	String	否	行政区域省名称（自动填充）
administrativeRegionProvinceAdcode	String	否	行政区域省adcode
administrativeRegionCityName	String	否	行政区域市名称（自动填充）
administrativeRegionCityAdcode	String	否	行政区域市adcode
administrativeRegionDistrictName	String	否	行政区域区名称（自动填充）
administrativeRegionDistrictAdcode	String	否	行政区域区adcode
businessLicenseUrl	String	否	营业执照地址（JSON字符串）
contractUrl	String	否	合同地址（JSON字符串）
foodLicenceUrl	String	否	经营许可证地址（JSON字符串）

请求示例：

{
  "storeUserId": 123,
  "storeName": "张三的餐厅",
  "storeTel": "0371-12345678",
  "storeAddress": "河南省郑州市金水区某某路123号",
  "administrativeRegionProvinceAdcode": "410000",
  "administrativeRegionCityAdcode": "410100",
  "administrativeRegionDistrictAdcode": "410105",
  "businessSection": 1,
  "businessTypes": "1,2,3",
  "storePosition": "113.625368,34.746599",
  "businessLicenseUrl": "[\"https://example.com/license1.jpg\"]"
}

响应参数

成功响应：

{
  "code": 200,
  "msg": "草稿保存成功",
  "data": true,
  "success": true
}

失败响应：

{
  "code": 500,
  "msg": "草稿保存失败",
  "data": null,
  "success": false
}

业务逻辑

1. 行政区域处理：

   • 根据省/市/区的 adcode 自动查询并填充对应的名称
   • 使用 EssentialCityCodeMapper 从 essential_city_code 表查询

2. 空字段处理：

   • 对于 businessLicenseUrl、contractUrl、foodLicenceUrl
   • 如果为空字符串，则设置为 null

3. 数据插入：

   • 使用 StoreInfoDraftMapper 插入草稿数据
   • MyBatis-Plus 自动填充 createdTime、updatedTime 等字段

---

2. 查询店铺入住申请草稿

接口描述：查询指定商户用户最新保存的店铺入住申请草稿。

原接口

• 服务：alien-store（app端商户）
• 路径：GET /alienStore/store/info/selectDraftByUserId
• Controller：StoreInfoController.selectDraftByUserId()
• Service：StoreInfoServiceImpl.selectDraftByUserId()

新接口

• 服务：alien-store-platform（web端商户）
• 路径：GET /alienStorePlatform/storeManage/getStoreDraft
• Controller：StoreManageController.getStoreDraft()
• Service：StoreManageServiceImpl.getStoreDraft()

请求参数

Query 参数：

参数名	类型	必填	说明
storeUserId	int	是	商户用户ID

请求示例：

GET /alienStorePlatform/storeManage/getStoreDraft?storeUserId=123

响应参数

成功响应（有草稿）：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "storeUserId": 123,
    "storeName": "张三的餐厅",
    "storeTel": "0371-12345678",
    "storeAddress": "河南省郑州市金水区某某路123号",
    "administrativeRegionProvinceName": "河南省",
    "administrativeRegionProvinceAdcode": "410000",
    "administrativeRegionCityName": "郑州市",
    "administrativeRegionCityAdcode": "410100",
    "administrativeRegionDistrictName": "金水区",
    "administrativeRegionDistrictAdcode": "410105",
    "businessSection": 1,
    "businessSectionName": "餐饮",
    "businessTypes": "1,2,3",
    "businessTypesName": "中餐,西餐,快餐",
    "storePosition": "113.625368,34.746599",
    "businessLicenseUrl": "[\"https://example.com/license1.jpg\"]",
    "createdTime": "2025-01-15 10:30:00",
    "updatedTime": "2025-01-15 14:20:00"
  },
  "success": true
}

成功响应（无草稿）：

{
  "code": 200,
  "msg": "success",
  "data": null,
  "success": true
}

失败响应：

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

业务逻辑

1. 查询条件：

   • 根据 storeUserId 查询草稿记录
   • 按 createdTime 降序排序
   • 返回最新的一条记录

2. 数据返回：

   • 如果没有草稿记录，返回 null
   • 如果有多条记录，返回最新的一条

3. 软删除处理：

   • MyBatis-Plus 自动过滤 deleteFlag=1 的记录

---

数据库表结构

store_info_draft（门店草稿表）

字段名	类型	说明
id	INT	主键，自增
store_user_id	INT	商家用户ID（store_user 表 id）
store_name	VARCHAR(100)	门店名称
business_status	INT	营业状态
store_tel	VARCHAR(20)	门店电话
store_capacity	INT	容纳人数
store_area	INT	门店面积
store_address	VARCHAR(255)	门店地址
store_blurb	TEXT	门店简介
store_type	VARCHAR(50)	门店类型
is_chain	INT	是否连锁
expiration_time	DATETIME	到期时间
store_position	VARCHAR(50)	经度,纬度
store_pass	VARCHAR(50)	门店密码
pass_type	INT	密码状态
store_status	INT	门店状态
business_section	INT	经营板块ID
business_section_name	VARCHAR(50)	经营板块名称
business_types	VARCHAR(255)	经营种类IDs
business_types_name	VARCHAR(255)	经营种类名称
store_application_status	INT	店铺申请审核状态
query_address	VARCHAR(255)	查询经纬度时查询地点
administrative_region_province_name	VARCHAR(50)	行政区域省名称
administrative_region_province_adcode	VARCHAR(20)	行政区域省adcode
administrative_region_city_name	VARCHAR(50)	行政区域市名称
administrative_region_city_adcode	VARCHAR(20)	行政区域市adcode
administrative_region_district_name	VARCHAR(50)	行政区域区名称
administrative_region_district_adcode	VARCHAR(20)	行政区域区adcode
logout_flag	INT	注销账号（0:正常，1：已注销）
logout_reason	VARCHAR(255)	注销原因
logout_time	DATETIME	注销时间
business_license_url	TEXT	营业执照地址（JSON）
contract_url	TEXT	合同地址（JSON）
food_licence_url	TEXT	经营许可证地址（JSON）
delete_flag	INT	删除标记（0:未删除, 1:已删除）
created_time	DATETIME	创建时间
created_user_id	INT	创建人ID
updated_time	DATETIME	修改时间
updated_user_id	INT	修改人ID

---

相关文件

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 层

• alien-entity/src/main/java/shop/alien/entity/store/StoreInfoDraft.java
• alien-entity/src/main/java/shop/alien/mapper/StoreInfoDraftMapper.java

---

测试建议

1. 保存草稿接口测试

测试用例 1：完整信息保存

curl -X POST http://localhost:8080/alienStorePlatform/storeManage/saveStoreDraft \
  -H "Content-Type: application/json" \
  -d '{
    "storeUserId": 123,
    "storeName": "测试餐厅",
    "storeTel": "0371-12345678",
    "storeAddress": "河南省郑州市金水区测试路123号",
    "administrativeRegionProvinceAdcode": "410000",
    "administrativeRegionCityAdcode": "410100",
    "administrativeRegionDistrictAdcode": "410105",
    "businessSection": 1,
    "businessTypes": "1,2",
    "storePosition": "113.625368,34.746599"
  }'

测试用例 2：部分信息保存（草稿功能）

curl -X POST http://localhost:8080/alienStorePlatform/storeManage/saveStoreDraft \
  -H "Content-Type: application/json" \
  -d '{
    "storeUserId": 123,
    "storeName": "测试餐厅"
  }'

测试用例 3：空字段处理

curl -X POST http://localhost:8080/alienStorePlatform/storeManage/saveStoreDraft \
  -H "Content-Type: application/json" \
  -d '{
    "storeUserId": 123,
    "storeName": "测试餐厅",
    "businessLicenseUrl": "",
    "contractUrl": "",
    "foodLicenceUrl": ""
  }'

2. 查询草稿接口测试

测试用例 1：查询存在的草稿

curl -X GET http://localhost:8080/alienStorePlatform/storeManage/getStoreDraft?storeUserId=123

测试用例 2：查询不存在的草稿

curl -X GET http://localhost:8080/alienStorePlatform/storeManage/getStoreDraft?storeUserId=999999

3. 业务流程测试

场景 1：分步填写

1. 第一次保存：仅填写基本信息（storeName, storeTel）
2. 第二次保存：补充地址信息（storeAddress, 行政区域）
3. 第三次保存：补充经营信息（businessSection, businessTypes）
4. 查询草稿：验证最新记录包含所有信息

场景 2：多次保存覆盖

1. 保存草稿 A（基本信息）
2. 保存草稿 B（完整信息）
3. 查询草稿：验证返回最新的草稿 B

场景 3：行政区域自动填充

1. 保存草稿时提供 adcode
2. 查询草稿
3. 验证省/市/区名称已自动填充

---

注意事项

1. 字段处理

• ⚠️ 行政区域名称会根据 adcode 自动查询填充
• ⚠️ 空字符串的图片URL字段会被设置为 null
• ⚠️ 草稿数据不会进行完整性校验，允许部分字段为空

2. 数据查询

• ⚠️ 查询草稿时按创建时间降序，返回最新的一条
• ⚠️ 软删除的草稿记录会被自动过滤
• ⚠️ 如果没有草稿记录，返回 null 而不是报错

3. 业务场景

• ⚠️ 草稿可以多次保存，每次保存都会创建新记录
• ⚠️ 查询时只返回最新的草稿记录
• ⚠️ 草稿数据不会影响正式的店铺入住申请

4. 与正式申请的关系

• 草稿保存：saveStoreDraft - 保存未完成的申请信息
• 正式申请：applyStore - 提交完整的入住申请并进入审核流程
• 两者使用不同的表：store_info_draft vs store_info

---

版本记录

版本	日期	说明	作者
1.0.0	2025-01-xx	初始版本，迁移草稿功能	ssk

---

联系方式

如有问题，请联系：

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