alien_cloud/alien-store-platform/doc

Web端基础数据查询接口开发文档

一、接口概述

本次开发在 alien-store-platform 服务中新增了基础数据查询接口，将原 alien-store 服务中分散在不同 Controller 的基础数据查询接口统一整合到一个 BaseDataController 中，方便 web 端商户平台统一管理和调用。

二、接口列表

2.1 根据关键词获取地址提示

接口路径： GET /baseData/getAddressPrompt

接口说明： 根据输入的地址关键词，返回高德地图的地址提示列表，支持按城市过滤

原接口路径： /alienStore/gaode/getInputPrompt

请求参数：

参数名	类型	必填	说明	示例
addressName	String	是	地址关键词	"中关村"
city	String	否	城市名称	"北京市"

请求示例：

GET /baseData/getAddressPrompt?addressName=中关村&city=北京市

响应示例：

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": {
    "status": "1",
    "info": "OK",
    "infocode": "10000",
    "count": "10",
    "tips": [
      {
        "id": "B000A8XZL4",
        "name": "中关村",
        "district": "北京市海淀区",
        "adcode": "110108",
        "location": "116.313676,39.982718",
        "address": "中关村大街",
        "typecode": "190301"
      }
    ]
  }
}

---

2.2 获取行政区划数据

接口路径： GET /baseData/getDistrict

接口说明： 根据行政区划代码获取省市区数据，支持级联查询

原接口路径： /alienStore/gaode/getDistrict

请求参数：

参数名	类型	必填	说明	默认值	示例
adCode	String	否	行政区划代码	100000	"100000"

行政区划代码说明：

• 100000：中国（返回所有省级数据）
• 410000：河南省（返回河南省所有市级数据）
• 410300：洛阳市（返回洛阳市所有区县数据）

请求示例：

# 查询所有省份
GET /baseData/getDistrict?adCode=100000

# 查询河南省所有城市
GET /baseData/getDistrict?adCode=410000

# 查询洛阳市所有区县
GET /baseData/getDistrict?adCode=410300

响应示例：

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": {
    "status": "1",
    "info": "OK",
    "infocode": "10000",
    "districts": [
      {
        "citycode": [],
        "adcode": "100000",
        "name": "中华人民共和国",
        "center": "116.3683244,39.915085",
        "level": "country",
        "districts": [
          {
            "citycode": "010",
            "adcode": "110000",
            "name": "北京市",
            "center": "116.405285,39.904989",
            "level": "province"
          }
        ]
      }
    ]
  }
}

---

2.3 获取经营板块基础数据

接口路径： GET /baseData/getBusinessSection

接口说明： 获取所有经营板块数据，用于商户选择经营类型

原接口路径： /alienStore/store/info/getBusinessSection

请求参数： 无

请求示例：

GET /baseData/getBusinessSection

响应示例：

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "typeName": "business_section",
      "dictId": "1",
      "dictDetail": "餐饮美食",
      "parentId": 0
    },
    {
      "id": 2,
      "typeName": "business_section",
      "dictId": "2",
      "dictDetail": "休闲娱乐",
      "parentId": 0
    },
    {
      "id": 3,
      "typeName": "business_section",
      "dictId": "3",
      "dictDetail": "生活服务",
      "parentId": 0
    }
  ]
}

---

2.4 获取经营种类基础数据

接口路径： GET /baseData/getBusinessTypes

接口说明： 根据经营板块ID获取该板块下的所有经营种类

原接口路径： /alienStore/store/info/getBusinessSectionTypes

请求参数：

参数名	类型	必填	说明	示例
parentId	String	是	经营板块ID（dictId）	"1"

请求示例：

GET /baseData/getBusinessTypes?parentId=1

响应示例：

{
  "code": 200,
  "success": true,
  "msg": "操作成功",
  "data": [
    {
      "id": 101,
      "typeName": "business_section",
      "dictId": "101",
      "dictDetail": "中餐",
      "parentId": 1
    },
    {
      "id": 102,
      "typeName": "business_section",
      "dictId": "102",
      "dictDetail": "西餐",
      "parentId": 1
    },
    {
      "id": 103,
      "typeName": "business_section",
      "dictId": "103",
      "dictDetail": "火锅",
      "parentId": 1
    },
    {
      "id": 104,
      "typeName": "business_section",
      "dictId": "104",
      "dictDetail": "烧烤",
      "parentId": 1
    }
  ]
}

---

三、业务流程说明

3.1 地址搜索流程

用户输入地址关键词
    ↓
调用 /baseData/getAddressPrompt 接口
    ↓
系统查询城市编码（如果指定城市）
    ↓
调用高德地图输入提示接口
    ↓
返回地址提示列表

3.2 行政区划级联查询流程

1. 查询所有省份
   GET /baseData/getDistrict?adCode=100000
   
2. 用户选择省份（例如：河南省，adCode=410000）
   GET /baseData/getDistrict?adCode=410000
   
3. 用户选择城市（例如：洛阳市，adCode=410300）
   GET /baseData/getDistrict?adCode=410300
   
4. 用户选择区县完成

3.3 经营板块和种类选择流程

1. 获取所有经营板块
   GET /baseData/getBusinessSection
   
2. 用户选择经营板块（例如：餐饮美食，dictId=1）
   GET /baseData/getBusinessTypes?parentId=1
   
3. 用户选择经营种类完成

---

四、Nacos 配置要求

在 Nacos 配置中心的 alien-store-platform.yml 配置文件中，需要添加以下高德地图相关配置：

# 高德地图配置
gaode:
  # 高德地图API Key
  key: your_gaode_api_key_here
  
  # 地理编码URL（地址转经纬度）
  geoUrl: https://restapi.amap.com/v3/geocode/geo?address=%s&key=%s
  
  # 输入提示URL
  geoListUrl: https://restapi.amap.com/v3/assistant/inputtips?keywords=%s&key=%s&city=%s
  
  # 行政区划URL
  getDistrict: https://restapi.amap.com/v3/config/district?key=%s&keywords=%s&subdistrict=1
  
  # 距离计算URL
  distanceUrl: https://restapi.amap.com/v3/direction/driving?origin=%s,%s&destination=%s,%s&key=%s
  
  # 直线距离URL
  distanceTypeUrl: https://restapi.amap.com/v3/direction/driving?origin=%s,%s&destination=%s,%s&key=%s&strategy=%s
  
  # 周边搜索URL
  nearUrl: https://restapi.amap.com/v3/place/around?location=%s,%s&key=%s&radius=%s&offset=%s&page=%s
  
  # 地铁站查询URL
  subwayUrl: https://restapi.amap.com/v3/place/text?key=%s&location=%s,%s&keywords=%s&radius=%s&types=%s
  
  # 逆地理编码URL（经纬度转地址）
  addressUrl: https://restapi.amap.com/v3/geocode/regeo?location=%s,%s&key=%s&radius=%s&extensions=%s

注意事项：

• 需要在高德地图开放平台申请 API Key
• 配置值可以从 alien-store 服务的 Nacos 配置中获取
• 确保 API Key 有足够的调用额度

---

五、数据库依赖

5.1 essential_city_code 表

存储城市编码信息，用于地址搜索时的城市过滤。

表结构：

CREATE TABLE `essential_city_code` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `area_code` varchar(20) DEFAULT NULL COMMENT '行政区划代码',
  `area_name` varchar(100) DEFAULT NULL COMMENT '区域名称',
  `city_code` varchar(20) DEFAULT NULL COMMENT '城市编码',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

5.2 store_dictionary 表

存储经营板块和经营种类的字典数据。

表结构：

CREATE TABLE `store_dictionary` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `type_name` varchar(50) DEFAULT NULL COMMENT '字典类型名称',
  `dict_id` varchar(20) DEFAULT NULL COMMENT '字典ID',
  `dict_detail` varchar(200) DEFAULT NULL COMMENT '字典详情',
  `parent_id` int(11) DEFAULT NULL COMMENT '父节点ID',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

数据说明：

• type_name = 'business_section' 表示经营板块/经营种类
• dict_id = '0' 表示根节点（不显示）
• dict_id != '0' AND parent_id = 根节点ID 表示经营板块
• parent_id = 经营板块ID 表示经营种类

---

六、代码结构

6.1 新增文件列表

alien-store-platform/
├── src/main/java/shop/alien/storeplatform/
│   ├── controller/
│   │   └── BaseDataController.java               # 基础数据查询控制器
│   ├── service/
│   │   ├── BaseDataService.java                  # 基础数据服务接口
│   │   └── impl/
│   │       └── BaseDataServiceImpl.java          # 基础数据服务实现
│   └── util/
│       └── GaoDeMapApiUtil.java                  # 高德地图API工具类

6.2 核心类说明

1. BaseDataController

• 提供4个基础数据查询接口
• 统一的接口路径前缀 /baseData
• 完整的 Swagger API 文档

2. BaseDataService & BaseDataServiceImpl

• 实现基础数据查询业务逻辑
• 调用高德地图API和数据库查询
• 数据格式转换和封装

3. GaoDeMapApiUtil

• 封装高德地图API调用
• 支持地址提示和行政区划查询
• HTTP请求处理和JSON解析

---

七、接口对比表

功能	原接口（alien-store）	新接口（alien-store-platform）
地址提示	/gaode/getInputPrompt	/baseData/getAddressPrompt
行政区划	/gaode/getDistrict	/baseData/getDistrict
经营板块	/store/info/getBusinessSection	/baseData/getBusinessSection
经营种类	/store/info/getBusinessSectionTypes	/baseData/getBusinessTypes

---

八、测试用例

8.1 地址提示测试

# 测试1：不指定城市
curl -X GET "http://localhost:8080/baseData/getAddressPrompt?addressName=中关村"

# 测试2：指定城市
curl -X GET "http://localhost:8080/baseData/getAddressPrompt?addressName=中关村&city=北京市"

8.2 行政区划测试

# 测试1：查询所有省份
curl -X GET "http://localhost:8080/baseData/getDistrict?adCode=100000"

# 测试2：查询河南省所有城市
curl -X GET "http://localhost:8080/baseData/getDistrict?adCode=410000"

# 测试3：查询洛阳市所有区县
curl -X GET "http://localhost:8080/baseData/getDistrict?adCode=410300"

8.3 经营数据测试

# 测试1：查询所有经营板块
curl -X GET "http://localhost:8080/baseData/getBusinessSection"

# 测试2：查询板块ID为1的所有经营种类
curl -X GET "http://localhost:8080/baseData/getBusinessTypes?parentId=1"

---

九、技术亮点

1. 接口统一管理：将分散的基础数据查询接口统一到一个 Controller 中
2. 命名规范化：采用更符合 web 端语义的接口路径命名
3. 代码复用：复用原有业务逻辑，保证数据一致性
4. 服务解耦：独立的工具类实现，不依赖 alien-store 服务
5. 文档完整：提供详细的接口文档和使用说明

---

十、部署检查清单

• 确认 Nacos 配置中已添加高德地图相关配置
• 确认高德地图 API Key 有效且有调用额度
• 确认数据库中 essential_city_code 表数据完整
• 确认数据库中 store_dictionary 表数据完整
• 确认 alien-entity 模块版本一致
• 确认接口权限配置正确

---

十一、常见问题

Q1: 高德地图API返回为空怎么办？

A: 检查以下几点：

1. API Key 是否有效
2. 网络连接是否正常
3. 调用次数是否超限
4. 请求参数是否正确

Q2: 行政区划数据查询不准确？

A: 确保 adCode 参数正确，可以参考高德地图的行政区划代码表

Q3: 经营种类查询为空？

A: 检查 parentId 是否正确，确认数据库中该板块下是否有经营种类数据

---

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