# 站点设置模块 (business-site-setting)

## 模块概述

站点设置模块提供站点设置相关的业务功能，包括意见反馈、关于我们、帮助中心等功能。

---

## 模块结构

```
business-site-setting/
├── business-site-setting-bean/              # Bean层（Entity、DTO、VO、Convert）
│   └── src/main/java/com/jeesharp/business/modules/setting/
│       ├── convert/                          # 转换器
│       │   ├── FeedbackConvert.java             # 意见反馈转换器
│       │   └── AboutUsConvert.java              # 关于我们转换器
│       ├── dto/                              # 数据传输对象
│       │   ├── FeedbackSubmitDTO.java            # 意见反馈提交DTO
│       │   ├── FeedbackHandleDTO.java           # 意见反馈处理DTO
│       │   └── AboutUsSaveDTO.java              # 关于我们保存DTO
│       ├── entity/                           # 实体类
│       │   ├── Feedback.java                    # 意见反馈实体
│       │   └── AboutUs.java                    # 关于我们实体
│       └── vo/                               # 视图对象
│           ├── FeedbackQueryVO.java             # 意见反馈查询VO
│           ├── FeedbackVO.java                  # 意见反馈VO
│           ├── AboutUsQueryVO.java              # 关于我们查询VO
│           └── AboutUsVO.java                    # 关于我们VO
│
├── business-site-setting-service/          # Service层（Service、Mapper）
│   └── src/main/java/com/jeesharp/business/modules/setting/
│       ├── mapper/                           # MyBatis Mapper
│       │   ├── FeedbackMapper.java               # 意见反馈Mapper
│       │   ├── AboutUsMapper.java                # 关于我们Mapper
│       │   └── xml/                             # Mapper XML
│       │       ├── FeedbackMapper.xml
│       │       └── AboutUsMapper.xml
│       └── service/                          # 领域服务
│           ├── FeedbackService.java              # 意见反馈服务接口
│           ├── AboutUsService.java              # 关于我们服务接口
│           └── impl/                             # 服务实现
│               ├── FeedbackServiceImpl.java
│               └── AboutUsServiceImpl.java
│
├── business-site-setting-application/      # Application层（应用服务）
│   └── src/main/java/com/jeesharp/business/modules/setting/
│       └── application/
│           ├── FeedbackApplicationService.java  # 意见反馈应用服务
│           └── AboutUsApplicationService.java   # 关于我们应用服务
│
├── business-site-setting-controller/       # Controller层（控制器，后台管理用）
│   └── src/main/java/com/jeesharp/business/modules/setting/
│       └── controller/
│           ├── FeedbackController.java          # 意见反馈管理控制器
│           └── AboutUsController.java           # 关于我们管理控制器
│
├── site_setting_sql_index.sql               # SQL 执行说明与推荐顺序
├── site_setting_schema.sql                  # 全量建表（新建库）
├── site_setting_alter.sql                   # 已有库增量 ALTER
├── site_setting_mock_data.sql               # 演示/种子数据（可选）
└── site_setting_menu_permission.sql         # 管理端菜单与权限
```

### 模块依赖关系

```
后台管理Controller → Application → Service → Bean
    │                    │            │         │
    └────────────────────┴────────────┴─────────┴──→ jeesharp-spring-boot-starter-mybatis

移动端接口（business-mobile-gateway）→ Application → Service → Bean
```

**注意**：
- `business-site-setting-controller` 是给**后台管理**使用的，提供管理后台的接口
- `business-mobile-gateway` 是给**移动端**使用的，提供APP/小程序/H5的接口

---

## 功能特性

### 意见反馈

- **提交反馈**：用户可提交功能建议、问题反馈等
- **反馈列表**：查看自己的反馈历史记录
- **反馈详情**：查看反馈的详细信息和处理结果
- **状态跟踪**：反馈状态包括待处理、处理中、已处理、已关闭

### 关于我们

- **多应用支持**：支持不同应用（APP/微信小程序/微信公众号/H5等）配置不同的关于我们信息
- **富文本内容**：支持富文本编辑，展示公司介绍、联系方式等信息
- **完整信息**：包含公司名称、地址、联系方式、版权信息、ICP备案号等
- **版本管理**：支持版本号管理，便于版本追踪

### 帮助中心

- **分类管理**：支持多级分类，便于组织帮助内容
- **文章管理**：支持富文本编辑，包含标题、内容、摘要、封面图片等
- **常见问题**：支持标记常见问题，方便用户快速查找
- **多应用支持**：不同应用可配置不同的帮助内容
- **数据统计**：支持浏览次数、点赞次数统计
- **搜索功能**：支持按标题、内容搜索帮助文章

---

## API 接口

### 移动端接口（business-mobile-gateway）

**接口基础路径**：`/mobile/setting/feedback`

| 接口 | 方法 | URL | 说明 |
|------|------|-----|------|
| 提交反馈 | POST | `/submit` | 提交意见反馈 |
| 获取详情 | GET | `/detail?id=xxx` | 获取反馈详细信息 |
| 我的反馈列表 | POST | `/myList` | 分页查询我的反馈列表 |
| 我的反馈列表（简化） | GET | `/myListSimple` | 获取我的反馈列表（不分页） |

#### 关于我们

**接口基础路径**：`/mobile/setting/aboutUs`

| 接口 | 方法 | URL | 说明 |
|------|------|-----|------|
| 获取关于我们 | GET | `/info?app=xxx` | 根据应用标识获取关于我们信息 |

#### 帮助中心

**接口基础路径**：`/mobile/setting/helpCenter`

| 接口 | 方法 | URL | 说明 |
|------|------|-----|------|
| 获取分类列表 | GET | `/categories?app=xxx` | 根据应用标识获取帮助分类列表 |
| 获取文章列表 | GET | `/articles?app=xxx&categoryId=xxx` | 获取帮助文章列表（可选分类筛选） |
| 获取文章详情 | GET | `/article/detail?id=xxx` | 获取帮助文章详情（自动增加浏览次数） |
| 获取常见问题 | GET | `/faq?app=xxx` | 获取常见问题列表 |
| 点赞文章 | POST | `/article/like?id=xxx` | 点赞文章（增加点赞次数） |
| 获取首页数据 | GET | `/index?app=xxx` | 获取帮助中心首页数据（分类+常见问题） |

### 后台管理接口（business-site-setting-controller）

#### 首页/商城轮播图

**接口基础路径**：`${jeesharp.web.adminPath}/setting/homeBanner/v1`

| 接口 | 方法 | URL | 说明 | 权限标识 |
|------|------|-----|------|----------|
| 详情 | GET | `/info?id=xxx` | 含跳转字段与 `resolvedLinkUrl` 预览 | `setting:homeBanner:info` |
| 分页列表 | POST | `/list` | 支持按 `bannerPosition`（HOME/MALL）、平台、状态筛选 | `setting:homeBanner:list` |
| 保存 | POST | `/save` | 新增/编辑；保存时校验跳转目标并回写 `linkUrl` | `setting:homeBanner:save` |
| 删除 | GET | `/delete?ids=xxx` | 批量删除 | `setting:homeBanner:delete` |
| 跳转目标搜索 | GET | `/jumpBizOptions?bizType=&keyword=` | 配置业务详情时远程搜索候选项 | `setting:homeBanner:info` |

**跳转类型 `jumpType`**：0-不跳转、1-业务详情、2-业务列表、3-自定义小程序路径、4-H5外链。

**业务场景 `bizType`**（节选）：`TICKET_VENUE`、`SCENIC_POI`、`HERITAGE`、`HOTEL`、`FOOD_RESTAURANT`、`LEISURE_VENUE`、`VILLAGE_DEST`、`EXPLAIN_PACKAGE`、`STUDY_PLAN`、`YEARCARD`、`CULTURE_ACTIVITY`、`TRAVEL_STRATEGY`、`TRAVEL_NEWS`、`MALL_SPU`、`COUPON`、`ROUTE`、`MARKETING`、`HOME_GRID_INTRO`（详见 `HomeBannerBizTypeEnum`）。

**管理端前端路由**：列表 `/business/setting/homeBanner`，编辑 `/business/setting/homeBanner/editor`（`TravelWebFrontProject` 业务仓 `asyncRouter` 注册，编辑页不在 `sys_menu` 中单独建菜单）。

#### 移动端轮播（business-mobile-gateway，免登录）

| 接口 | 方法 | URL | 说明 |
|------|------|-----|------|
| 首页壳层轮播 | GET | `/mobile/home/shell` 或 `/mobile/home/banners` | 返回 `MiniHomeBannerItemVO` 列表（含 `linkUrl`、`jumpType`） |
| 按位置轮播 | GET | `/mobile/setting/homeBanner/list?position=HOME\|MALL` | 同上 |
| 商城轮播 | GET | `/mobile/mall/banners` | `banner_position=MALL` 的轮播项（含跳转字段） |

#### 意见反馈管理

**接口基础路径**：`${jeesharp.web.adminPath}/setting/feedback/v1`

| 接口 | 方法 | URL | 说明 | 权限标识 |
|------|------|-----|------|----------|
| 获取详情 | GET | `/info?id=xxx` | 获取反馈详细信息 | `setting:feedback:info` |
| 获取列表 | POST | `/list` | 分页查询反馈列表 | `setting:feedback:list` |
| 删除反馈 | GET | `/delete?ids=xxx` | 批量删除反馈 | `setting:feedback:delete` |
| 处理反馈 | POST | `/handle` | 标记反馈为处理中 | `setting:feedback:handle` |
| 完成处理 | POST | `/complete` | 标记反馈为已处理 | `setting:feedback:complete` |
| 关闭反馈 | GET | `/close?id=xxx` | 关闭反馈 | `setting:feedback:close` |

#### 关于我们管理

**接口基础路径**：`${jeesharp.web.adminPath}/setting/aboutUs/v1`

| 接口 | 方法 | URL | 说明 | 权限标识 |
|------|------|-----|------|----------|
| 获取详情 | GET | `/info?id=xxx` | 获取关于我们详细信息 | `setting:aboutUs:info` |
| 获取列表 | POST | `/list` | 分页查询关于我们列表 | `setting:aboutUs:list` |
| 保存 | POST | `/save` | 新增或更新关于我们 | `setting:aboutUs:save` |
| 删除 | GET | `/delete?ids=xxx` | 批量删除关于我们 | `setting:aboutUs:delete` |
| 禁用 | GET | `/disable?id=xxx` | 禁用关于我们 | `setting:aboutUs:disable` |
| 启用 | GET | `/enable?id=xxx` | 启用关于我们 | `setting:aboutUs:enable` |

#### 帮助分类管理

**接口基础路径**：`${jeesharp.web.adminPath}/setting/helpCategory/v1`

| 接口 | 方法 | URL | 说明 | 权限标识 |
|------|------|-----|------|----------|
| 获取详情 | GET | `/info?id=xxx` | 获取帮助分类详细信息 | `setting:helpCategory:info` |
| 获取列表 | POST | `/list` | 分页查询帮助分类列表 | `setting:helpCategory:list` |
| 保存 | POST | `/save` | 新增或更新帮助分类 | `setting:helpCategory:save` |
| 删除 | GET | `/delete?ids=xxx` | 批量删除帮助分类 | `setting:helpCategory:delete` |
| 禁用 | GET | `/disable?id=xxx` | 禁用帮助分类 | `setting:helpCategory:disable` |
| 启用 | GET | `/enable?id=xxx` | 启用帮助分类 | `setting:helpCategory:enable` |

#### 帮助文章管理

**接口基础路径**：`${jeesharp.web.adminPath}/setting/helpArticle/v1`

| 接口 | 方法 | URL | 说明 | 权限标识 |
|------|------|-----|------|----------|
| 获取详情 | GET | `/info?id=xxx` | 获取帮助文章详细信息 | `setting:helpArticle:info` |
| 获取列表 | POST | `/list` | 分页查询帮助文章列表 | `setting:helpArticle:list` |
| 保存 | POST | `/save` | 新增或更新帮助文章 | `setting:helpArticle:save` |
| 删除 | GET | `/delete?ids=xxx` | 批量删除帮助文章 | `setting:helpArticle:delete` |
| 禁用 | GET | `/disable?id=xxx` | 禁用帮助文章 | `setting:helpArticle:disable` |
| 启用 | GET | `/enable?id=xxx` | 启用帮助文章 | `setting:helpArticle:enable` |

---

## 数据库表设计

### 关于我们表 (app_about_us)

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | VARCHAR(64) | 主键ID |
| app | VARCHAR(32) | 应用标识（APP/WECHAT_MINI/WECHAT_MP/H5等） |
| title | VARCHAR(100) | 标题 |
| content | TEXT | 内容（支持富文本） |
| version | VARCHAR(32) | 版本号 |
| company_name | VARCHAR(100) | 公司名称 |
| company_address | VARCHAR(255) | 公司地址 |
| contact_phone | VARCHAR(50) | 联系电话 |
| contact_email | VARCHAR(100) | 联系邮箱 |
| official_website | VARCHAR(255) | 官方网站 |
| wechat_official_account | VARCHAR(100) | 微信公众号 |
| wechat_mini_program_name | VARCHAR(100) | 微信小程序名称 |
| copyright | VARCHAR(255) | 版权信息 |
| icp_license | VARCHAR(100) | ICP备案号 |
| sort_order | INT | 排序号 |
| status | TINYINT | 状态：0-禁用 1-启用 |

**索引设计**：

| 索引名 | 字段 | 说明 |
|--------|------|------|
| idx_app | app | 应用标识查询 |
| idx_status | status | 状态筛选 |
| idx_sort_order | sort_order | 排序查询 |

### 意见反馈表 (app_feedback)

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | VARCHAR(64) | 主键ID |
| member_id | VARCHAR(64) | 会员ID |
| feedback_type | TINYINT | 反馈类型：1-功能建议 2-问题反馈 3-其他 |
| title | VARCHAR(100) | 反馈标题 |
| content | TEXT | 反馈内容 |
| contact | VARCHAR(50) | 联系方式（手机号或邮箱） |
| images | TEXT | 图片URL列表（JSON数组格式） |
| status | TINYINT | 反馈状态：0-待处理 1-处理中 2-已处理 3-已关闭 |
| handler_id | VARCHAR(64) | 处理人ID |
| handler_name | VARCHAR(64) | 处理人姓名 |
| handle_date | DATETIME | 处理时间 |
| handle_result | TEXT | 处理结果/回复内容 |
| device_info | TEXT | 设备信息（JSON格式） |
| app_version | VARCHAR(32) | 应用版本号 |
| os_version | VARCHAR(32) | 操作系统版本 |

**索引设计**：

| 索引名 | 字段 | 说明 |
|--------|------|------|
| idx_member_id | member_id | 会员反馈查询 |
| idx_feedback_type | feedback_type | 反馈类型筛选 |
| idx_status | status | 状态筛选 |
| idx_create_date | create_date | 时间排序 |

### 帮助分类表 (app_help_category)

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | VARCHAR(64) | 主键ID |
| app | VARCHAR(32) | 应用标识（APP/WECHAT_MINI/WECHAT_MP/H5等） |
| category_name | VARCHAR(50) | 分类名称 |
| icon | VARCHAR(500) | 分类图标 |
| description | VARCHAR(255) | 分类描述 |
| sort_order | INT | 排序号 |
| status | TINYINT | 状态：0-禁用 1-启用 |

**索引设计**：

| 索引名 | 字段 | 说明 |
|--------|------|------|
| idx_app | app | 应用标识查询 |
| idx_status | status | 状态筛选 |
| idx_sort_order | sort_order | 排序查询 |

### 帮助文章表 (app_help_article)

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | VARCHAR(64) | 主键ID |
| app | VARCHAR(32) | 应用标识（APP/WECHAT_MINI/WECHAT_MP/H5等） |
| category_id | VARCHAR(64) | 分类ID |
| title | VARCHAR(200) | 文章标题 |
| content | TEXT | 文章内容（支持富文本） |
| summary | VARCHAR(500) | 文章摘要 |
| cover_image | VARCHAR(500) | 封面图片 |
| is_faq | TINYINT | 是否常见问题：0-否 1-是 |
| view_count | INT | 浏览次数 |
| like_count | INT | 点赞次数 |
| sort_order | INT | 排序号 |
| status | TINYINT | 状态：0-禁用 1-启用 |

**索引设计**：

| 索引名 | 字段 | 说明 |
|--------|------|------|
| idx_app | app | 应用标识查询 |
| idx_category_id | category_id | 分类查询 |
| idx_is_faq | is_faq | 常见问题筛选 |
| idx_status | status | 状态筛选 |
| idx_sort_order | sort_order | 排序查询 |
| idx_view_count | view_count | 热门文章排序 |

---

## 使用说明

### 执行 SQL

```bash
# 新建库：先读 site_setting_sql_index.sql，再按需执行，例如：
mysql -u root -p your_database < site_setting_schema.sql
mysql -u root -p your_database < site_setting_mock_data.sql
mysql -u root -p your_database < site_setting_menu_permission.sql

# 已有库补字段（按需）：
mysql -u root -p your_database < site_setting_alter.sql
```

### 注意事项

1. **多租户支持**：所有表均包含 `tenant_id` 和 `tenant_code` 字段
2. **图片存储**：图片URL列表以JSON数组格式存储，建议使用OSS等对象存储服务
3. **设备信息**：设备信息以JSON格式存储，可包含设备型号、系统版本等信息

---

## 版本记录

| 版本 | 日期 | 说明 |
|------|------|------|
| 1.1.0 | 2026-07-03 | 轮播图结构化跳转（jump_type/biz_type/biz_id）、管理端 homeBanner 页面、商城轮播含跳转 |
| 1.0.0 | 2026-02-05 | 初始版本，包含意见反馈、关于我们和帮助中心功能 |