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

## 概述

本文档描述了从 `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字符串）|

**请求示例**：

```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\"]"
}
```

#### 响应参数

**成功响应**：

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

**失败响应**：

```json
{
  "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
```

#### 响应参数

**成功响应（有草稿）**：

```json
{
  "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
}
```

**成功响应（无草稿）**：

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

**失败响应**：

```json
{
  "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：完整信息保存**
```bash
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：部分信息保存（草稿功能）**
```bash
curl -X POST http://localhost:8080/alienStorePlatform/storeManage/saveStoreDraft \
  -H "Content-Type: application/json" \
  -d '{
    "storeUserId": 123,
    "storeName": "测试餐厅"
  }'
```

**测试用例 3：空字段处理**
```bash
curl -X POST http://localhost:8080/alienStorePlatform/storeManage/saveStoreDraft \
  -H "Content-Type: application/json" \
  -d '{
    "storeUserId": 123,
    "storeName": "测试餐厅",
    "businessLicenseUrl": "",
    "contractUrl": "",
    "foodLicenceUrl": ""
  }'
```

### 2. 查询草稿接口测试

**测试用例 1：查询存在的草稿**
```bash
curl -X GET http://localhost:8080/alienStorePlatform/storeManage/getStoreDraft?storeUserId=123
```

**测试用例 2：查询不存在的草稿**
```bash
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