# 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 请求示例

```http
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 响应示例

**成功响应：**
```json
{
  "code": 200,
  "success": true,
  "msg": "店铺入住申请已提交",
  "data": {
    "id": 12345
  }
}
```

**失败响应：**
```json
{
  "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：完整信息提交

```bash
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：包含可选字段

```bash
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` 注解
- 任何异常都会触发事务回滚
- 确保数据一致性

---

## 十一、技术亮点

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

---

## 十二、部署检查清单

- [ ] 确认数据库表结构完整
  - [ ] `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