# 用户服务 API 文档

**服务**: `hl-user-service`
**接口总数**: 135

## 目录

- **Banner管理接口** (5 个接口)
- **个人中心** (6 个接口)
- **个人中心（旧路径，已废弃）** (5 个接口)
- **企业微信同步接口** (7 个接口)
- **前端配置管理接口** (8 个接口)
- **字典管理接口** (12 个接口)
- **定时任务接口** (8 个接口)
- **客户管理接口** (4 个接口)
- **小程序接口** (21 个接口)
- **常见问题管理接口** (8 个接口)
- **探索分类管理接口** (5 个接口)
- **用户协议管理接口** (5 个接口)
- **管理员管理接口** (8 个接口)
- **管理员认证接口** (14 个接口)
- **联系我们管理接口** (5 个接口)
- **菜单管理接口** (7 个接口)
- **角色管理接口** (7 个接口)

---

## Banner管理接口

### `GET` /admin/banner

**Banner列表**

分页查询Banner列表，支持按关键词和状态筛选。

**关联字典**：
- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keyword` | `string` |  | 搜索关键词 |  |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `status` | `integer(int32)` |  | 状态 |  |

**响应** `统一响应结果«分页结果«Banner VO»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«Banner VO»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `Banner VO[]` |  | 数据列表 |
|     `createdAt` | `string` |  | 创建时间 |
|     `endTime` | `string` |  | 展示结束时间 |
|     `id` | `string` |  | Banner ID |
|     `imageUrl` | `string` |  | 图片URL（图片类型为图片，视频类型为封面图） |
|     `linkId` | `string` |  | 链接目标ID（PRODUCT/SCENIC/ACTIVITY/HOTEL时有值） |
|     `linkTargetName` | `string` |  | 链接目标名称（用于后台展示） |
|     `linkType` | `string` |  | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 |
|     `linkUrl` | `string` |  | 链接URL（PAGE时为路由名，WEBVIEW时为完整URL） |
|     `materialId` | `long` |  | 素材库关联ID |
|     `mediaType` | `string` |  | 媒体类型: IMAGE/VIDEO |
|     `sortOrder` | `int` |  | 排序号 |
|     `startTime` | `string` |  | 展示开始时间 |
|     `status` | `int` |  | 状态：0=下线 1=上线 |
|     `subtitle` | `string` |  | 副标题 |
|     `tags` | `string[]` |  | 标签列表 |
|     `title` | `string` |  | 标题 |
|     `videoUrl` | `string` |  | 视频URL（媒体类型为VIDEO时有值） |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/banner

**创建Banner**

创建新的首页轮播图，包括标题、封面图、跳转链接、排序等。

**权限**：需要管理员登录。
**注意**：创建后默认为启用状态，小程序端将按排序展示。

**请求体** `Banner请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `endTime` | `string` |  | 展示结束时间 |
| `imageUrl` | `string` | 是 | Banner图片URL（图片类型时为图片，视频类型时为封面图） |
| `linkId` | `string` |  | 链接目标ID（linkType=PRODUCT时为产品ID） |
| `linkTargetName` | `string` |  | 链接目标名称（用于后台展示） |
| `linkType` | `string` |  | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 |
| `linkUrl` | `string` |  | 链接URL（linkType=WEBVIEW/PAGE时生效） |
| `materialId` | `long` |  | 素材库关联ID（从素材库选择时传入） |
| `mediaType` | `string` |  | 媒体类型: IMAGE/VIDEO |
| `sortOrder` | `int` |  | 排序号（越小越靠前） |
| `startTime` | `string` |  | 展示开始时间 |
| `status` | `int` |  | 状态：0=下线 1=上线 |
| `subtitle` | `string` |  | 副标题 |
| `tags` | `string` |  | 标签（逗号分隔） |
| `title` | `string` | 是 | Banner标题 |
| `videoUrl` | `string` |  | 视频URL（媒体类型为VIDEO时必填） |

**响应** `统一响应结果«Banner VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `Banner VO` |  | 响应数据 |
|   `createdAt` | `string` |  | 创建时间 |
|   `endTime` | `string` |  | 展示结束时间 |
|   `id` | `string` |  | Banner ID |
|   `imageUrl` | `string` |  | 图片URL（图片类型为图片，视频类型为封面图） |
|   `linkId` | `string` |  | 链接目标ID（PRODUCT/SCENIC/ACTIVITY/HOTEL时有值） |
|   `linkTargetName` | `string` |  | 链接目标名称（用于后台展示） |
|   `linkType` | `string` |  | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 |
|   `linkUrl` | `string` |  | 链接URL（PAGE时为路由名，WEBVIEW时为完整URL） |
|   `materialId` | `long` |  | 素材库关联ID |
|   `mediaType` | `string` |  | 媒体类型: IMAGE/VIDEO |
|   `sortOrder` | `int` |  | 排序号 |
|   `startTime` | `string` |  | 展示开始时间 |
|   `status` | `int` |  | 状态：0=下线 1=上线 |
|   `subtitle` | `string` |  | 副标题 |
|   `tags` | `string[]` |  | 标签列表 |
|   `title` | `string` |  | 标题 |
|   `videoUrl` | `string` |  | 视频URL（媒体类型为VIDEO时有值） |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/banner/{id}

**Banner详情**

获取指定Banner的详细信息，包括标题、图片、跳转链接、排序等。

**权限**：需要管理员登录。

**关联字典**：
- common_status（通用状态）：返回字段status（0=禁用, 1=启用）

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 轮播图ID |

**响应** `统一响应结果«Banner VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `Banner VO` |  | 响应数据 |
|   `createdAt` | `string` |  | 创建时间 |
|   `endTime` | `string` |  | 展示结束时间 |
|   `id` | `string` |  | Banner ID |
|   `imageUrl` | `string` |  | 图片URL（图片类型为图片，视频类型为封面图） |
|   `linkId` | `string` |  | 链接目标ID（PRODUCT/SCENIC/ACTIVITY/HOTEL时有值） |
|   `linkTargetName` | `string` |  | 链接目标名称（用于后台展示） |
|   `linkType` | `string` |  | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 |
|   `linkUrl` | `string` |  | 链接URL（PAGE时为路由名，WEBVIEW时为完整URL） |
|   `materialId` | `long` |  | 素材库关联ID |
|   `mediaType` | `string` |  | 媒体类型: IMAGE/VIDEO |
|   `sortOrder` | `int` |  | 排序号 |
|   `startTime` | `string` |  | 展示开始时间 |
|   `status` | `int` |  | 状态：0=下线 1=上线 |
|   `subtitle` | `string` |  | 副标题 |
|   `tags` | `string[]` |  | 标签列表 |
|   `title` | `string` |  | 标题 |
|   `videoUrl` | `string` |  | 视频URL（媒体类型为VIDEO时有值） |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/banner/{id}

**更新Banner**

更新指定Banner的标题、封面图、跳转链接、排序、状态等信息。

**权限**：需要管理员登录。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 轮播图ID |

**请求体** `Banner请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `endTime` | `string` |  | 展示结束时间 |
| `imageUrl` | `string` | 是 | Banner图片URL（图片类型时为图片，视频类型时为封面图） |
| `linkId` | `string` |  | 链接目标ID（linkType=PRODUCT时为产品ID） |
| `linkTargetName` | `string` |  | 链接目标名称（用于后台展示） |
| `linkType` | `string` |  | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 |
| `linkUrl` | `string` |  | 链接URL（linkType=WEBVIEW/PAGE时生效） |
| `materialId` | `long` |  | 素材库关联ID（从素材库选择时传入） |
| `mediaType` | `string` |  | 媒体类型: IMAGE/VIDEO |
| `sortOrder` | `int` |  | 排序号（越小越靠前） |
| `startTime` | `string` |  | 展示开始时间 |
| `status` | `int` |  | 状态：0=下线 1=上线 |
| `subtitle` | `string` |  | 副标题 |
| `tags` | `string` |  | 标签（逗号分隔） |
| `title` | `string` | 是 | Banner标题 |
| `videoUrl` | `string` |  | 视频URL（媒体类型为VIDEO时必填） |

**响应** `统一响应结果«Banner VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `Banner VO` |  | 响应数据 |
|   `createdAt` | `string` |  | 创建时间 |
|   `endTime` | `string` |  | 展示结束时间 |
|   `id` | `string` |  | Banner ID |
|   `imageUrl` | `string` |  | 图片URL（图片类型为图片，视频类型为封面图） |
|   `linkId` | `string` |  | 链接目标ID（PRODUCT/SCENIC/ACTIVITY/HOTEL时有值） |
|   `linkTargetName` | `string` |  | 链接目标名称（用于后台展示） |
|   `linkType` | `string` |  | 链接类型：NONE=无链接 PRODUCT=产品 SCENIC=景区 ACTIVITY=活动 HOTEL=酒店 PAGE=小程序页面 WEBVIEW=网页 |
|   `linkUrl` | `string` |  | 链接URL（PAGE时为路由名，WEBVIEW时为完整URL） |
|   `materialId` | `long` |  | 素材库关联ID |
|   `mediaType` | `string` |  | 媒体类型: IMAGE/VIDEO |
|   `sortOrder` | `int` |  | 排序号 |
|   `startTime` | `string` |  | 展示开始时间 |
|   `status` | `int` |  | 状态：0=下线 1=上线 |
|   `subtitle` | `string` |  | 副标题 |
|   `tags` | `string[]` |  | 标签列表 |
|   `title` | `string` |  | 标题 |
|   `videoUrl` | `string` |  | 视频URL（媒体类型为VIDEO时有值） |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/banner/{id}

**删除Banner**

删除指定的Banner记录（软删除）。

**权限**：需要管理员登录。
**注意**：删除后小程序首页将不再展示该Banner。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 轮播图ID |

**响应** `统一响应结果«Void»`

---

## 个人中心

### `GET` /admin/profile/dashboard

**工作台仪表盘（角色分发，支持时间范围）**

根据当前管理员角色返回不同的仪表盘数据。CUSTOMIZER（定制师）：待处理订单数、产品数、评价统计等。SUPER_ADMIN/ADMIN：全局概览（订单、收入、用户增长等）。ROOM_MANAGER（客房管理）：房间分配概览。VEHICLE_MANAGER（车辆管理）：车辆调度概览。FINANCE（财务）：收支统计。MATERIAL_ADMIN（素材管理）：素材库概览。period取值：today=今日 week=本周 month=本月。需要管理员认证。

**关联字典**：
- order_status（订单状态）：仪表盘中订单统计按状态分组展示

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `period` | `string` |  | 时间范围: today/week/month |  |

**响应** `统一响应结果«object»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `object` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/profile/me

**获取我的个人资料**

获取当前登录管理员的个人资料，根据角色返回不同的资料内容。
定制师角色会返回认证等级、个人简介、擅长领域等附加信息。

**权限**：需要管理员登录。

**关联字典**：
- designer_cert_level（认证等级）：返回字段certLevel（none/bronze/silver/gold/diamond）

**响应** `统一响应结果«个人资料VO（角色感知）»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `个人资料VO（角色感知）` |  | 响应数据 |
|   `adminId` | `string` |  | 管理员用户ID |
|   `avatar` | `string` |  | 头像URL |
|   `certLevel` | `string` |  | 认证等级（定制师专属） |
|   `certified` | `boolean` |  | 是否已认证（定制师专属） |
|   `contactQrUrl` | `string` |  | 企业微信联系二维码URL |
|   `createdAt` | `string` |  | 创建时间 |
|   `description` | `string` |  | 个人简介（定制师专属） |
|   `experience` | `int` |  | 从业年限（定制师专属） |
|   `isFeatured` | `boolean` |  | 是否推荐（定制师专属） |
|   `motto` | `string` |  | 座右铭（定制师专属） |
|   `name` | `string` |  | 姓名 |
|   `phone` | `string` |  | 手机号 |
|   `role` | `string` |  | 当前角色key |
|   `roleName` | `string` |  | 角色中文名 |
|   `serviceAreas` | `string[]` |  | 服务区域（定制师专属） |
|   `sortOrder` | `int` |  | 展示排序（定制师专属） |
|   `specialties` | `string[]` |  | 擅长领域（定制师专属） |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/profile/me

**更新我的个人资料**

更新当前登录管理员的个人资料，支持修改昵称、头像、个人简介等。
定制师角色可额外更新擅长领域、服务区域等信息。

**权限**：需要管理员登录。

**请求体** `更新定制师个人资料请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `certLevel` | `string` |  | 认证等级：none/bronze/silver/gold/diamond |
| `certified` | `boolean` |  | 是否已认证 |
| `description` | `string` |  | 个人简介 |
| `experience` | `int` |  | 从业年限 |
| `isFeatured` | `boolean` |  | 是否推荐 |
| `motto` | `string` |  | 座右铭 |
| `serviceAreas` | `string[]` |  | 服务区域列表 |
| `sortOrder` | `int` |  | 展示排序 |
| `specialties` | `string[]` |  | 擅长领域列表 |

**响应** `统一响应结果«个人资料VO（角色感知）»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `个人资料VO（角色感知）` |  | 响应数据 |
|   `adminId` | `string` |  | 管理员用户ID |
|   `avatar` | `string` |  | 头像URL |
|   `certLevel` | `string` |  | 认证等级（定制师专属） |
|   `certified` | `boolean` |  | 是否已认证（定制师专属） |
|   `contactQrUrl` | `string` |  | 企业微信联系二维码URL |
|   `createdAt` | `string` |  | 创建时间 |
|   `description` | `string` |  | 个人简介（定制师专属） |
|   `experience` | `int` |  | 从业年限（定制师专属） |
|   `isFeatured` | `boolean` |  | 是否推荐（定制师专属） |
|   `motto` | `string` |  | 座右铭（定制师专属） |
|   `name` | `string` |  | 姓名 |
|   `phone` | `string` |  | 手机号 |
|   `role` | `string` |  | 当前角色key |
|   `roleName` | `string` |  | 角色中文名 |
|   `serviceAreas` | `string[]` |  | 服务区域（定制师专属） |
|   `sortOrder` | `int` |  | 展示排序（定制师专属） |
|   `specialties` | `string[]` |  | 擅长领域（定制师专属） |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/profile/orders

**订单列表**

查询当前定制师的订单列表，支持按状态筛选。

**关联字典**：
- order_status（订单状态）：请求参数status和返回字段status

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keyword` | `string` |  | 搜索关键词 |  |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `status` | `string` |  | 订单状态 |  |

**响应** `统一响应结果«分页结果«Map«string,object»»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«Map«string,object»»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `Map«string,object»[]` |  | 数据列表 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/profile/products

**产品列表**

查询当前定制师的产品列表，支持按状态筛选。

**关联字典**：
- product_status（产品状态）：请求参数status和返回字段status

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keyword` | `string` |  | 搜索关键词 |  |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `status` | `string` |  | 产品状态 |  |

**响应** `统一响应结果«分页结果«Map«string,object»»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«Map«string,object»»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `Map«string,object»[]` |  | 数据列表 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/profile/reviews

**我的评价列表**

查询当前定制师收到的评价列表，支持按评价等级筛选。

**关联字典**：
- rating_level（评价等级）：GOOD=好评, MEDIUM=中评, BAD=差评（筛选条件+列表展示）


**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `ratingLevel` | `string` |  | 评价等级: GOOD/MEDIUM/BAD |  |

**响应** `统一响应结果«分页结果«Map«string,object»»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«Map«string,object»»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `Map«string,object»[]` |  | 数据列表 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

## 个人中心（旧路径，已废弃）

### `GET` /admin/designer/dashboard

**工作台概览（已废弃，请使用 /admin/profile/dashboard）**

已废弃接口，请迁移至 GET /admin/profile/dashboard。

**权限**：需要管理员登录。

**响应** `统一响应结果«定制师工作台VO（重构版）»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `定制师工作台VO（重构版）` |  | 响应数据 |
|   `calendarEvents` | `Map«string,object»[]` |  | 日历事件 |
|   `customerStats` | `客户统计` |  | 客户统计 |
|     `customerAddCount` | `int` |  | 新增客户数 |
|     `customerLossCount` | `int` |  | 客户流失数 |
|   `funnel` | `object` |  | 转化漏斗 |
|   `overview` | `数据概览` |  | 数据概览 |
|     `gmv` | `number` |  | 当期GMV |
|     `gmvDiffRate` | `number` |  | 与前一期GMV增长率 |
|     `orderCount` | `long` |  | 当期订单数 |
|     `orderCountDiff` | `long` |  | 与前一期订单数差值 |
|     `period` | `string` |  | 当期时间范围 |
|   `productStats` | `产品统计` |  | 产品统计 |
|     `publishedProducts` | `int` |  | 已上架产品数 |
|     `totalProducts` | `int` |  | 产品总数 |
|   `ranking` | `Map«string,object»[]` |  | 本月业绩排行 |
|   `reviewStats` | `评价统计` |  | 评价统计 |
|     `averageRating` | `number` |  | 平均评分(1-5) |
|     `goodRate` | `number` |  | 好评率(%) |
|     `totalReviews` | `int` |  | 评价总数 |
|   `shortcuts` | `快捷入口[]` |  | 快捷入口列表 |
|     `icon` | `string` |  | 图标 |
|     `name` | `string` |  | 名称 |
|     `path` | `string` |  | 路径 |
|   `todos` | `object` |  | 待办汇总 |
|   `trend` | `Map«string,object»[]` |  | 数据趋势（按天） |
|   `upcomingTrips` | `Map«string,object»[]` |  | 即将出行列表 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/designer/orders

**我的订单列表（已废弃，请使用 /admin/profile/orders）**

已废弃接口。

**关联字典**：
- order_status（订单状态）：请求参数status和返回字段status

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keyword` | `string` |  | keyword |  |
| `page` | `integer(int32)` |  | page |  |
| `pageSize` | `integer(int32)` |  | pageSize |  |
| `status` | `string` |  | status |  |

**响应** `统一响应结果«分页结果«Map«string,object»»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«Map«string,object»»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `Map«string,object»[]` |  | 数据列表 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/designer/products

**我的产品列表（已废弃，请使用 /admin/profile/products）**

已废弃接口。

**关联字典**：
- product_status（产品状态）：请求参数status和返回字段status

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keyword` | `string` |  | keyword |  |
| `page` | `integer(int32)` |  | page |  |
| `pageSize` | `integer(int32)` |  | pageSize |  |
| `status` | `string` |  | status |  |

**响应** `统一响应结果«分页结果«Map«string,object»»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«Map«string,object»»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `Map«string,object»[]` |  | 数据列表 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/designer/profile

**获取我的个人资料（已废弃，请使用 /admin/profile/me）**

已废弃接口。

**关联字典**：
- designer_cert_level（认证等级）：返回字段certLevel（none/bronze/silver/gold/diamond）

**响应** `统一响应结果«定制师个人资料VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `定制师个人资料VO` |  | 响应数据 |
|   `adminId` | `string` |  | 管理员用户ID |
|   `avatar` | `string` |  | 头像URL |
|   `certLevel` | `string` |  | 认证等级：none/bronze/silver/gold/diamond |
|   `certified` | `boolean` |  | 是否已认证 |
|   `contactQrUrl` | `string` |  | 企业微信联系二维码URL |
|   `createdAt` | `string` |  | 创建时间 |
|   `description` | `string` |  | 个人简介 |
|   `experience` | `int` |  | 从业年限 |
|   `isFeatured` | `boolean` |  | 是否推荐 |
|   `motto` | `string` |  | 座右铭 |
|   `name` | `string` |  | 姓名（优先取企微名称，否则管理员用户名） |
|   `phone` | `string` |  | 手机号 |
|   `serviceAreas` | `string[]` |  | 服务区域列表 |
|   `sortOrder` | `int` |  | 展示排序 |
|   `specialties` | `string[]` |  | 擅长领域列表 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/designer/profile

**更新我的个人资料（已废弃，请使用 PUT /admin/profile/me）**

已废弃接口，请迁移至 PUT /admin/profile/me。

**权限**：需要管理员登录。

**请求体** `更新定制师个人资料请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `certLevel` | `string` |  | 认证等级：none/bronze/silver/gold/diamond |
| `certified` | `boolean` |  | 是否已认证 |
| `description` | `string` |  | 个人简介 |
| `experience` | `int` |  | 从业年限 |
| `isFeatured` | `boolean` |  | 是否推荐 |
| `motto` | `string` |  | 座右铭 |
| `serviceAreas` | `string[]` |  | 服务区域列表 |
| `sortOrder` | `int` |  | 展示排序 |
| `specialties` | `string[]` |  | 擅长领域列表 |

**响应** `统一响应结果«定制师个人资料VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `定制师个人资料VO` |  | 响应数据 |
|   `adminId` | `string` |  | 管理员用户ID |
|   `avatar` | `string` |  | 头像URL |
|   `certLevel` | `string` |  | 认证等级：none/bronze/silver/gold/diamond |
|   `certified` | `boolean` |  | 是否已认证 |
|   `contactQrUrl` | `string` |  | 企业微信联系二维码URL |
|   `createdAt` | `string` |  | 创建时间 |
|   `description` | `string` |  | 个人简介 |
|   `experience` | `int` |  | 从业年限 |
|   `isFeatured` | `boolean` |  | 是否推荐 |
|   `motto` | `string` |  | 座右铭 |
|   `name` | `string` |  | 姓名（优先取企微名称，否则管理员用户名） |
|   `phone` | `string` |  | 手机号 |
|   `serviceAreas` | `string[]` |  | 服务区域列表 |
|   `sortOrder` | `int` |  | 展示排序 |
|   `specialties` | `string[]` |  | 擅长领域列表 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

## 企业微信同步接口

### `GET` /admin/wechat/departments

**部门列表（部门管理页面）**

获取已同步的所有企业微信部门列表（平铺结构），用于部门管理页面展示。
包含部门ID、名称、上级部门ID、排序等信息。

**权限**：需要管理员登录。

**响应** `统一响应结果«List«WechatDepartment»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `WechatDepartment[]` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `deptId` | `long` |  |  |
|   `deptName` | `string` |  |  |
|   `orderIndex` | `int` |  |  |
|   `parentId` | `long` |  |  |
|   `status` | `string` |  |  |
|   `syncedAt` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/wechat/departments/tree

**部门树（下拉筛选）**

以树形结构返回企业微信部门数据。用于部门筛选下拉框，每个节点包含id/label/children。需要管理员认证。

**响应** `统一响应结果«List«Map«string,object»»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `Map«string,object»[]` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/wechat/sync/all

**手动同步全部（部门+用户）**

一键同步企业微信的部门和用户数据，先同步部门再同步用户。推荐使用此接口而非单独同步，确保部门和用户数据一致性。同步过程为异步执行，接口立即返回成功。需要SUPER_ADMIN角色。

**响应** `统一响应结果«Void»`

---

### `POST` /admin/wechat/sync/departments

**手动同步部门**

从企业微信拉取最新的部门列表并同步到本地数据库。通常在企业微信后台调整组织架构后手动触发。也可通过定时任务自动执行。需要SUPER_ADMIN角色。

**响应** `统一响应结果«Void»`

---

### `GET` /admin/wechat/sync/status

**同步状态（最后同步时间）**

获取企业微信数据的最后同步时间和状态。
返回部门和用户各自的最后同步时间，用于管理页面展示同步状态。

**权限**：需要管理员登录。

**响应** `统一响应结果«Map«string,object»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `object` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/wechat/sync/users

**手动同步用户**

从企业微信拉取所有部门的成员列表并同步到本地数据库。包括姓名、手机号、职位、部门归属等信息。需先同步部门再同步用户，或直接使用[同步全部]接口。需要SUPER_ADMIN角色。

**响应** `统一响应结果«Void»`

---

### `GET` /admin/wechat/users

**查询企业微信用户（分页+搜索）**

分页查询已同步的企业微信用户列表。支持按姓名/手机号/职位关键词搜索，按部门ID和状态筛选。status取值：1=已激活 2=已禁用 4=未关注。用于管理员绑定企微账号时选择企微用户。需要管理员认证。

**关联字典**：
- wechat_user_status（企微用户状态）：请求参数status和返回字段status（1=已激活, 2=已禁用, 4=未关注）

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `deptId` | `integer(int64)` |  | 部门ID筛选 |  |
| `keyword` | `string` |  | 关键词搜索（姓名/手机/职位） |  |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `status` | `integer(int32)` |  | 状态筛选(1=已激活,2=已禁用,4=未关注) |  |

**响应** `统一响应结果«分页结果«WechatUser»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«WechatUser»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `WechatUser[]` |  | 数据列表 |
|     `avatar` | `string` |  |  |
|     `createdAt` | `string` |  |  |
|     `deptIds` | `string` |  |  |
|     `deptNames` | `string` |  |  |
|     `email` | `string` |  |  |
|     `gender` | `int` |  |  |
|     `mobile` | `string` |  |  |
|     `name` | `string` |  |  |
|     `position` | `string` |  |  |
|     `status` | `int` |  |  |
|     `syncedAt` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|     `userid` | `string` |  |  |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

## 前端配置管理接口

### `GET` /admin/frontend-config

**配置列表**

分页查询前端配置列表，支持按关键词、分组和状态筛选。

**关联字典**：
- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `configGroup` | `string` |  | 配置分组 |  |
| `keyword` | `string` |  | 搜索关键词 |  |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `status` | `integer(int32)` |  | 状态 |  |

**响应** `统一响应结果«分页结果«前端配置 VO»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«前端配置 VO»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `前端配置 VO[]` |  | 数据列表 |
|     `configGroup` | `string` |  | 配置分组: COLOR/PAGE/SECRET/GENERAL |
|     `configKey` | `string` |  | 配置键 |
|     `configType` | `string` |  | 值类型 |
|     `configValue` | `string` |  | 配置值(SECRET类型脱敏) |
|     `createdAt` | `string` |  | 创建时间 |
|     `description` | `string` |  | 配置项描述 |
|     `id` | `string` |  | 配置ID |
|     `label` | `string` |  | 配置项中文名称 |
|     `sortOrder` | `int` |  | 排序号 |
|     `status` | `int` |  | 状态: 0=禁用 1=启用 |
|     `updatedAt` | `string` |  | 更新时间 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/frontend-config

**创建配置**

创建新的前端配置项，用于控制前端页面的展示和行为。

**权限**：需要管理员登录。
**注意**：configKey 必须全局唯一，不能与已有配置重复。可通过 sensitive 字段标记是否为敏感配置（敏感配置不会通过公开接口暴露给小程序）。

**请求体** `前端配置请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `configGroup` | `string` | 是 | 配置分组 |
| `configKey` | `string` | 是 | 配置键 |
| `configType` | `string` | 是 | 值类型 |
| `configValue` | `string` |  | 配置值 |
| `description` | `string` |  | 配置项描述 |
| `label` | `string` | 是 | 配置项中文名称 |
| `sortOrder` | `int` |  | 排序号 |
| `status` | `int` |  | 状态: 0=禁用 1=启用 |

**响应** `统一响应结果«前端配置 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `前端配置 VO` |  | 响应数据 |
|   `configGroup` | `string` |  | 配置分组: COLOR/PAGE/SECRET/GENERAL |
|   `configKey` | `string` |  | 配置键 |
|   `configType` | `string` |  | 值类型 |
|   `configValue` | `string` |  | 配置值(SECRET类型脱敏) |
|   `createdAt` | `string` |  | 创建时间 |
|   `description` | `string` |  | 配置项描述 |
|   `id` | `string` |  | 配置ID |
|   `label` | `string` |  | 配置项中文名称 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态: 0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/frontend-config/all

**配置列表（不分页）**

获取所有前端配置项的完整列表（不分页），支持按分组和状态筛选。
适用于需要一次性加载全部配置的场景。

**权限**：需要管理员登录。

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `configGroup` | `string` |  | 配置分组 |  |
| `status` | `integer(int32)` |  | 状态 |  |

**响应** `统一响应结果«List«前端配置 VO»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `前端配置 VO[]` |  | 响应数据 |
|   `configGroup` | `string` |  | 配置分组: COLOR/PAGE/SECRET/GENERAL |
|   `configKey` | `string` |  | 配置键 |
|   `configType` | `string` |  | 值类型 |
|   `configValue` | `string` |  | 配置值(SECRET类型脱敏) |
|   `createdAt` | `string` |  | 创建时间 |
|   `description` | `string` |  | 配置项描述 |
|   `id` | `string` |  | 配置ID |
|   `label` | `string` |  | 配置项中文名称 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态: 0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/frontend-config/by-key/{key}

**按key查询配置**

根据配置键（configKey）获取指定的前端配置项。
configKey为全局唯一标识，如 app_name、primary_color 等。

**权限**：需要管理员登录。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `key` | `string` |  | 配置键 |

**响应** `统一响应结果«前端配置 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `前端配置 VO` |  | 响应数据 |
|   `configGroup` | `string` |  | 配置分组: COLOR/PAGE/SECRET/GENERAL |
|   `configKey` | `string` |  | 配置键 |
|   `configType` | `string` |  | 值类型 |
|   `configValue` | `string` |  | 配置值(SECRET类型脱敏) |
|   `createdAt` | `string` |  | 创建时间 |
|   `description` | `string` |  | 配置项描述 |
|   `id` | `string` |  | 配置ID |
|   `label` | `string` |  | 配置项中文名称 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态: 0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/frontend-config/groups

**获取所有分组**

获取前端配置中所有已使用的分组名称列表。
用于配置管理页面的分组筛选下拉框。

**权限**：需要管理员登录。

**响应** `统一响应结果«List«string»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `string[]` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/frontend-config/{id}

**配置详情**

根据配置ID获取指定前端配置项的详细信息，包括key、value、分组、描述等。

**权限**：需要管理员登录。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 配置ID |

**响应** `统一响应结果«前端配置 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `前端配置 VO` |  | 响应数据 |
|   `configGroup` | `string` |  | 配置分组: COLOR/PAGE/SECRET/GENERAL |
|   `configKey` | `string` |  | 配置键 |
|   `configType` | `string` |  | 值类型 |
|   `configValue` | `string` |  | 配置值(SECRET类型脱敏) |
|   `createdAt` | `string` |  | 创建时间 |
|   `description` | `string` |  | 配置项描述 |
|   `id` | `string` |  | 配置ID |
|   `label` | `string` |  | 配置项中文名称 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态: 0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/frontend-config/{id}

**更新配置**

更新指定前端配置项的值、分组、描述、状态等信息。

**权限**：需要管理员登录。
**注意**：修改后前端会实时使用新值（如有缓存需等待刷新）。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 配置ID |

**请求体** `前端配置请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `configGroup` | `string` | 是 | 配置分组 |
| `configKey` | `string` | 是 | 配置键 |
| `configType` | `string` | 是 | 值类型 |
| `configValue` | `string` |  | 配置值 |
| `description` | `string` |  | 配置项描述 |
| `label` | `string` | 是 | 配置项中文名称 |
| `sortOrder` | `int` |  | 排序号 |
| `status` | `int` |  | 状态: 0=禁用 1=启用 |

**响应** `统一响应结果«前端配置 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `前端配置 VO` |  | 响应数据 |
|   `configGroup` | `string` |  | 配置分组: COLOR/PAGE/SECRET/GENERAL |
|   `configKey` | `string` |  | 配置键 |
|   `configType` | `string` |  | 值类型 |
|   `configValue` | `string` |  | 配置值(SECRET类型脱敏) |
|   `createdAt` | `string` |  | 创建时间 |
|   `description` | `string` |  | 配置项描述 |
|   `id` | `string` |  | 配置ID |
|   `label` | `string` |  | 配置项中文名称 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态: 0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/frontend-config/{id}

**删除配置**

删除指定的前端配置项（软删除）。

**权限**：需要管理员登录。
**注意**：删除后前端将无法获取该配置，可能影响页面展示，请确认无引用后再删除。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 配置ID |

**响应** `统一响应结果«Void»`

---

## 字典管理接口

### `GET` /admin/dict/all

**获取所有字典数据**

获取系统全部字典类型及其字典数据，按字典类型分组返回。用于后台管理系统初始化时一次性加载所有下拉选项。返回结果包含dictType编码、dictName名称、dataList数据列表。需要管理员认证。

**字典层级说明**：
- 字典类型（SysDictType）：一级分类，如 admin_status、order_status、id_card_type 等
- 字典数据（SysDictData）：二级选项，归属于某个字典类型，如 admin_status 下的 ACTIVE/LOCKED/DISABLED
- 前端通过 dictType 编码查找对应的 dataList，用 dictValue 匹配实际数据进行翻译展示


**响应** `统一响应结果«List«字典VO»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `字典VO[]` |  | 响应数据 |
|   `dataList` | `字典数据项VO[]` |  | 字典数据列表 |
|     `dictLabel` | `string` |  | 字典标签 |
|     `dictValue` | `string` |  | 字典值 |
|     `sort` | `int` |  | 排序号 |
|   `dictName` | `string` |  | 字典名称 |
|   `dictType` | `string` |  | 字典类型标识 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/dict/data

**创建字典数据**

在指定字典类型下新增一条字典数据项。dictValue为前端匹配的值（如ACTIVE），dictLabel为前端展示的标签（如'启用'）。支持树形字典数据（通过parentId设置父级）。

**请求体** `创建字典数据请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dictLabel` | `string` | 是 | 字典标签 |
| `dictType` | `string` | 是 | 字典类型 |
| `dictValue` | `string` | 是 | 字典值 |
| `remark` | `string` |  | 备注 |
| `sortOrder` | `int` |  | 排序号 |

**响应** `统一响应结果«SysDictData»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysDictData` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `dictDataId` | `long` |  |  |
|   `dictLabel` | `string` |  |  |
|   `dictType` | `string` |  |  |
|   `dictValue` | `string` |  |  |
|   `remark` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/dict/data/detail/{dictDataId}

**根据ID获取字典数据详情**

获取单个字典数据项的详细信息，包括dictValue、dictLabel、cssClass等。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dictDataId` | `integer` |  | 字典数据ID |

**响应** `统一响应结果«SysDictData»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysDictData` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `dictDataId` | `long` |  |  |
|   `dictLabel` | `string` |  |  |
|   `dictType` | `string` |  |  |
|   `dictValue` | `string` |  |  |
|   `remark` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/dict/data/tree/{dictTypeId}

**按类型查询字典数据（树形结构）**

根据字典类型ID查询其下所有字典数据，以树形结构返回（支持父子级字典数据）。用于多级联动下拉框场景（如省市区）。需要管理员认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dictTypeId` | `integer` |  | 字典类型ID |

**响应** `统一响应结果«List«SysDictData»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysDictData[]` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `dictDataId` | `long` |  |  |
|   `dictLabel` | `string` |  |  |
|   `dictType` | `string` |  |  |
|   `dictValue` | `string` |  |  |
|   `remark` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/dict/data/{dictType}

**按类型查询字典数据**

根据字典类型编码（如order_status）查询其下所有字典数据（平铺列表）。用于单层下拉框场景。需要管理员认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dictType` | `string` |  | 字典类型编码 |

**响应** `统一响应结果«List«SysDictData»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysDictData[]` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `dictDataId` | `long` |  |  |
|   `dictLabel` | `string` |  |  |
|   `dictType` | `string` |  |  |
|   `dictValue` | `string` |  |  |
|   `remark` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/dict/data/{id}

**更新字典数据**

更新字典数据项的标签、样式类型、排序号等。dictValue建议不修改以免影响已有业务数据。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 字典数据ID |

**请求体** `更新字典数据请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dictLabel` | `string` |  | 字典标签 |
| `dictValue` | `string` |  | 字典值 |
| `remark` | `string` |  | 备注 |
| `sortOrder` | `int` |  | 排序号 |
| `status` | `string` |  | 状态：ACTIVE=启用 DISABLED=禁用 |

**响应** `统一响应结果«SysDictData»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysDictData` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `dictDataId` | `long` |  |  |
|   `dictLabel` | `string` |  |  |
|   `dictType` | `string` |  |  |
|   `dictValue` | `string` |  |  |
|   `remark` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/dict/data/{id}

**删除字典数据**

删除指定字典数据项（软删除）。删除后不影响已引用该字典值的业务数据。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 字典数据ID |

**响应** `统一响应结果«Void»`

---

### `GET` /admin/dict/type

**分页查询字典类型**

分页查询字典类型列表，支持按分类（category）筛选。字典类型是字典数据的上级分组，管理字典类型即管理有哪些可供前端使用的下拉选项组。

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `category` | `string` |  | 字典分类 |  |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |

**响应** `统一响应结果«分页结果«SysDictType»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«SysDictType»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `SysDictType[]` |  | 数据列表 |
|     `category` | `string` |  |  |
|     `createdAt` | `string` |  |  |
|     `dictName` | `string` |  |  |
|     `dictType` | `string` |  |  |
|     `dictTypeId` | `long` |  |  |
|     `remark` | `string` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/dict/type

**创建字典类型**

新建一个字典类型（如：订单状态、证件类型等）。字典类型编码（dictType）全局唯一，创建后不可修改。需要管理员认证，建议仅SUPER_ADMIN/ADMIN角色操作。

**已有字典类型示例**：
- admin_status（管理员状态）、common_status（通用状态）、login_status（登录状态）
- order_status（订单状态）、product_status（产品状态）、rating_level（评价等级）
- id_card_type（证件类型）、gender（性别）、traveler_type（出行人类型）
- contact_channel_type（联系方式渠道类型）、favorite_resource_type（收藏资源类型）、footprint_resource_type（足迹资源类型）


**请求体** `创建字典类型请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `category` | `string` |  | 字典分类 |
| `dictName` | `string` | 是 | 字典名称 |
| `dictType` | `string` | 是 | 字典类型标识 |
| `remark` | `string` |  | 备注 |

**响应** `统一响应结果«SysDictType»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysDictType` |  | 响应数据 |
|   `category` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `dictName` | `string` |  |  |
|   `dictType` | `string` |  |  |
|   `dictTypeId` | `long` |  |  |
|   `remark` | `string` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/dict/type/{dictTypeId}

**根据ID获取字典类型详情**

获取单个字典类型的详细信息，包括编码、名称、分类、状态等。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dictTypeId` | `integer` |  | 字典类型ID |

**响应** `统一响应结果«SysDictType»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysDictType` |  | 响应数据 |
|   `category` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `dictName` | `string` |  |  |
|   `dictType` | `string` |  |  |
|   `dictTypeId` | `long` |  |  |
|   `remark` | `string` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/dict/type/{id}

**更新字典类型**

更新字典类型的名称、分类、备注等信息。字典类型编码（dictType）不可修改。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 字典类型ID |

**请求体** `更新字典类型请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `dictName` | `string` |  | 字典名称 |
| `remark` | `string` |  | 备注 |
| `status` | `string` |  | 状态：ACTIVE=启用 DISABLED=禁用 |

**响应** `统一响应结果«SysDictType»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysDictType` |  | 响应数据 |
|   `category` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `dictName` | `string` |  |  |
|   `dictType` | `string` |  |  |
|   `dictTypeId` | `long` |  |  |
|   `remark` | `string` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/dict/type/{id}

**删除字典类型**

删除字典类型及其下所有字典数据（软删除）。如果该字典类型已被业务引用，删除后不影响已有数据，但新的表单将无法选择该字典值。需要管理员认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 字典类型ID |

**响应** `统一响应结果«Void»`

---

## 定时任务接口

### `GET` /admin/job

**分页查询定时任务**

分页查询定时任务列表。

**关联字典**：
- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步
- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发
- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |

**响应** `统一响应结果«分页结果«定时任务信息»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«定时任务信息»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `定时任务信息[]` |  | 数据列表 |
|     `concurrent` | `boolean` |  | 是否允许并发执行 |
|     `createdAt` | `string` |  | 创建时间 |
|     `cronExpression` | `string` |  | Cron表达式 |
|     `invokeTarget` | `string` |  | 调用目标（Bean名称.方法名） |
|     `jobGroup` | `string` |  | 任务分组 |
|     `jobId` | `long` |  | 任务ID |
|     `jobName` | `string` |  | 任务名称 |
|     `misfirePolicy` | `string` |  | 计划执行策略 |
|     `remark` | `string` |  | 备注 |
|     `status` | `string` |  | 任务状态 |
|     `updatedAt` | `string` |  | 更新时间 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/job

**创建定时任务**

创建新的定时任务。invokeTarget格式为'Bean名称.方法名'（如wechatSyncService.syncAll），方法必须是无参公开方法。cronExpression为标准6位Cron表达式（秒 分 时 日 月 周）。创建后任务默认为暂停状态（PAUSED），需手动调用[恢复任务]接口启用。

**关联字典**：
- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步
- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发
- job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停

需要SUPER_ADMIN角色。

**请求体** `创建定时任务请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `concurrent` | `boolean` |  | 是否允许并发执行 |
| `cronExpression` | `string` | 是 | Cron表达式，标准6位（秒 分 时 日 月 周） |
| `invokeTarget` | `string` | 是 | 调用目标（Bean名称.方法名），方法必须是无参公开方法 |
| `jobGroup` | `string` |  | 任务分组，字典类型：job_group（DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步） |
| `jobName` | `string` | 是 | 任务名称 |
| `misfirePolicy` | `string` |  | 计划执行策略，字典类型：job_misfire_policy（DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发） |
| `remark` | `string` |  | 备注 |

**响应** `统一响应结果«定时任务信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `定时任务信息` |  | 响应数据 |
|   `concurrent` | `boolean` |  | 是否允许并发执行 |
|   `createdAt` | `string` |  | 创建时间 |
|   `cronExpression` | `string` |  | Cron表达式 |
|   `invokeTarget` | `string` |  | 调用目标（Bean名称.方法名） |
|   `jobGroup` | `string` |  | 任务分组 |
|   `jobId` | `long` |  | 任务ID |
|   `jobName` | `string` |  | 任务名称 |
|   `misfirePolicy` | `string` |  | 计划执行策略 |
|   `remark` | `string` |  | 备注 |
|   `status` | `string` |  | 任务状态 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/job/{jobId}

**更新定时任务**

更新指定定时任务的名称、Cron表达式、调用目标等信息。
修改Cron表达式后任务将按新的计划执行。

**关联字典**：
- job_group（任务分组）：DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步
- job_misfire_policy（执行策略）：DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发

**权限**：需要SUPER_ADMIN角色。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `jobId` | `integer` |  | 定时任务ID |

**请求体** `更新定时任务请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `concurrent` | `boolean` |  | 是否允许并发执行 |
| `cronExpression` | `string` |  | Cron表达式，标准6位（秒 分 时 日 月 周） |
| `invokeTarget` | `string` |  | 调用目标（Bean名称.方法名），方法必须是无参公开方法 |
| `jobGroup` | `string` |  | 任务分组，字典类型：job_group（DEFAULT=默认分组, SYSTEM=系统任务, WECHAT=企微同步, INSURANCE=保险同步） |
| `jobName` | `string` |  | 任务名称 |
| `misfirePolicy` | `string` |  | 计划执行策略，字典类型：job_misfire_policy（DEFAULT=默认策略, FIRE_ONCE=立即触发一次, DO_NOTHING=不触发） |
| `remark` | `string` |  | 备注 |

**响应** `统一响应结果«定时任务信息»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `定时任务信息` |  | 响应数据 |
|   `concurrent` | `boolean` |  | 是否允许并发执行 |
|   `createdAt` | `string` |  | 创建时间 |
|   `cronExpression` | `string` |  | Cron表达式 |
|   `invokeTarget` | `string` |  | 调用目标（Bean名称.方法名） |
|   `jobGroup` | `string` |  | 任务分组 |
|   `jobId` | `long` |  | 任务ID |
|   `jobName` | `string` |  | 任务名称 |
|   `misfirePolicy` | `string` |  | 计划执行策略 |
|   `remark` | `string` |  | 备注 |
|   `status` | `string` |  | 任务状态 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/job/{jobId}

**删除定时任务**

删除指定的定时任务（软删除），同时从调度器中移除该任务。

**权限**：需要SUPER_ADMIN角色。
**注意**：删除后任务将不再执行，但历史执行日志仍可查看。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `jobId` | `integer` |  | 定时任务ID |

**响应** `统一响应结果«Void»`

---

### `GET` /admin/job/{jobId}/logs

**查询任务日志**

分页查询指定定时任务的执行日志，按执行时间倒序排列。日志包含执行状态（成功/失败）、执行耗时、异常信息等。

**关联字典**：job_log_status（日志状态）：SUCCESS=成功, FAIL=失败

需要管理员认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `jobId` | `integer` |  | 定时任务ID |

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |

**响应** `统一响应结果«分页结果«定时任务执行日志»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«定时任务执行日志»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `定时任务执行日志[]` |  | 数据列表 |
|     `createdAt` | `string` |  | 创建时间 |
|     `endTime` | `string` |  | 结束时间 |
|     `invokeTarget` | `string` |  | 调用目标 |
|     `jobId` | `long` |  | 任务ID |
|     `jobLogId` | `long` |  | 日志ID |
|     `jobName` | `string` |  | 任务名称 |
|     `message` | `string` |  | 执行结果/异常信息 |
|     `startTime` | `string` |  | 开始时间 |
|     `status` | `string` |  | 执行状态 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/job/{jobId}/pause

**暂停任务**

暂停指定的定时任务，任务状态变为PAUSED。暂停后任务不再按Cron计划执行，但可通过[恢复任务]接口重新启用。

**关联字典**：job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停

需要SUPER_ADMIN角色。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `jobId` | `integer` |  | 定时任务ID |

**响应** `统一响应结果«Void»`

---

### `POST` /admin/job/{jobId}/resume

**恢复任务**

恢复已暂停的定时任务，任务状态变为ACTIVE。恢复后任务按Cron计划继续执行。

**关联字典**：job_status（任务状态）：ACTIVE=启用, PAUSED=已暂停

需要SUPER_ADMIN角色。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `jobId` | `integer` |  | 定时任务ID |

**响应** `统一响应结果«Void»`

---

### `POST` /admin/job/{jobId}/trigger

**立即执行一次**

立即触发一次定时任务的执行，不影响原有的Cron计划。无论任务当前状态是ACTIVE还是PAUSED，都可以手动触发。执行结果可在任务日志中查看。需要SUPER_ADMIN角色。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `jobId` | `integer` |  | 定时任务ID |

**响应** `统一响应结果«Void»`

---

## 客户管理接口

### `GET` /admin/customer

**客户列表**

分页查询小程序注册的C端用户（客户）列表。支持按昵称/手机号/真实姓名关键词搜索，按状态筛选。status取值：ACTIVE=正常 BANNED=已封禁。需要管理员认证。

**关联字典**：
- user_status（用户状态）：请求参数status和返回字段status（ACTIVE=正常, BANNED=已封禁）
- gender（性别）：返回字段gender（0=女, 1=男）
- id_card_type（证件类型）：返回字段idCardType

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keyword` | `string` |  | 搜索关键词 |  |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `status` | `string` |  | 状态 |  |

**响应** `统一响应结果«分页结果«客户信息VO（管理端）»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«客户信息VO（管理端）»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `客户信息VO（管理端）[]` |  | 数据列表 |
|     `avatar` | `string` |  | 头像URL |
|     `createdAt` | `string` |  | 创建时间 |
|     `nickname` | `string` |  | 昵称 |
|     `phone` | `string` |  | 手机号（不脱敏） |
|     `status` | `string` |  | 状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁 |
|     `updatedAt` | `string` |  | 更新时间 |
|     `userId` | `long` |  | 用户ID |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/customer/{userId}

**客户详情**

获取指定客户的详细信息。

**关联字典**：
- user_status（用户状态）：返回字段status
- gender（性别）：返回字段gender
- id_card_type（证件类型）：返回字段idCardType

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `userId` | `integer` |  | 用户ID |

**响应** `统一响应结果«客户信息VO（管理端）»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `客户信息VO（管理端）` |  | 响应数据 |
|   `avatar` | `string` |  | 头像URL |
|   `createdAt` | `string` |  | 创建时间 |
|   `nickname` | `string` |  | 昵称 |
|   `phone` | `string` |  | 手机号（不脱敏） |
|   `status` | `string` |  | 状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁 |
|   `updatedAt` | `string` |  | 更新时间 |
|   `userId` | `long` |  | 用户ID |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/customer/{userId}/ban

**封禁客户**

封禁指定的C端用户，状态变为BANNED。封禁后该用户无法登录小程序，已有的Token将失效。封禁操作不会删除用户数据，可通过[解封客户]接口恢复。需要管理员认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `userId` | `integer` |  | 用户ID |

**响应** `统一响应结果«Void»`

---

### `POST` /admin/customer/{userId}/unban

**解封客户**

解封已封禁的C端用户，状态恢复为ACTIVE。解封后用户可正常登录小程序。需要管理员认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `userId` | `integer` |  | 用户ID |

**响应** `统一响应结果«Void»`

---

## 小程序接口

### `GET` /dict/all

**获取所有字典数据（公开接口）**

获取系统全部字典类型及其字典数据，供小程序C端使用。无需认证即可调用。返回格式与管理端 /admin/dict/all 一致。

**字典层级说明**：
- 每个元素包含 dictType（编码）、dictName（名称）、dataList（字典数据列表）
- 前端通过 dictType 匹配业务字段，用 dataList 中的 dictValue/dictLabel 做翻译展示
- 常用字典：order_status、product_status、id_card_type、gender、traveler_type、favorite_resource_type、footprint_resource_type


**响应** `统一响应结果«List«字典VO»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `字典VO[]` |  | 响应数据 |
|   `dataList` | `字典数据项VO[]` |  | 字典数据列表 |
|     `dictLabel` | `string` |  | 字典标签 |
|     `dictValue` | `string` |  | 字典值 |
|     `sort` | `int` |  | 排序号 |
|   `dictName` | `string` |  | 字典名称 |
|   `dictType` | `string` |  | 字典类型标识 |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /user/account

**注销账号**

永久注销当前用户账号（软删除）。注销后该账号的openid和手机号将被释放，可用于重新注册。注销操作不可撤销，请谨慎调用。需要小程序用户认证。

**响应** `统一响应结果«Void»`

---

### `GET` /user/favorite

**收藏列表**

分页查询当前用户的所有收藏记录，按收藏时间倒序排列。返回收藏记录的基础信息（不包含资源详情），需前端根据targetType和targetId再查详情。需要小程序用户认证。

**关联字典**：
- favorite_resource_type（收藏资源类型）：返回字段targetType，前端据此判断跳转到哪种资源详情页


**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |

**响应** `统一响应结果«分页结果«Favorite»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«Favorite»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `Favorite[]` |  | 数据列表 |
|     `createdAt` | `string` |  |  |
|     `deletedAt` | `string` |  |  |
|     `favoriteId` | `long` |  |  |
|     `targetId` | `long` |  |  |
|     `targetType` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|     `userId` | `long` |  |  |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /user/favorite

**添加收藏**

将指定资源添加到当前用户的收藏列表。同一用户对同一资源不可重复收藏，重复收藏会报错。targetType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT/EXPLORE等。需要小程序用户认证。

**关联字典**：
- favorite_resource_type（收藏资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索（请求参数targetType）


**请求体** `收藏请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `targetId` | `long` | 是 | 收藏目标ID |
| `targetType` | `string` | 是 | 收藏类型，关联字典favorite_resource_type |

**响应** `统一响应结果«Favorite»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `Favorite` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `deletedAt` | `string` |  |  |
|   `favoriteId` | `long` |  |  |
|   `targetId` | `long` |  |  |
|   `targetType` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `userId` | `long` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /user/favorite/check

**检查是否已收藏**

检查当前用户是否已收藏指定类型的资源。返回true=已收藏，false=未收藏。targetType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT/EXPLORE等。需要小程序用户认证。

**关联字典**：
- favorite_resource_type（收藏资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品, EXPLORE=探索（请求参数targetType）


**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `targetId` | `integer(int64)` |  | 目标资源ID |  |
| `targetType` | `string` |  | 目标类型 |  |

**响应** `统一响应结果«boolean»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `boolean` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /user/favorite/{favoriteId}

**删除收藏**

根据收藏记录ID取消收藏。只能删除自己的收藏记录，删除他人的收藏会报权限错误。需要小程序用户认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `favoriteId` | `integer` |  | 收藏ID |

**响应** `统一响应结果«Void»`

---

### `GET` /user/footprint

**足迹列表**

分页查询当前用户的浏览足迹，按浏览时间倒序排列。需要小程序用户认证。

**关联字典**：
- footprint_resource_type（足迹资源类型）：返回字段resourceType，前端据此判断跳转到哪种资源详情页


**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |

**响应** `统一响应结果«分页结果«Footprint»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«Footprint»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `Footprint[]` |  | 数据列表 |
|     `createdAt` | `string` |  |  |
|     `deletedAt` | `string` |  |  |
|     `footprintId` | `long` |  |  |
|     `resourceId` | `long` |  |  |
|     `resourceType` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|     `userId` | `long` |  |  |
|     `visitTime` | `string` |  |  |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /user/footprint

**添加足迹**

记录用户浏览资源的足迹。同一用户对同一资源多次浏览只保留最新一条记录（更新时间）。resourceType取值：SCENIC_SPOT/ACTIVITY/HOTEL/PRODUCT等。通常由前端在进入资源详情页时自动调用。需要小程序用户认证。

**关联字典**：
- footprint_resource_type（足迹资源类型）：SCENIC_SPOT=景区, ACTIVITY=活动, HOTEL=酒店, PRODUCT=产品（请求参数resourceType）


**请求体** `足迹请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `resourceId` | `long` | 是 | 资源ID |
| `resourceType` | `string` | 是 | 资源类型，关联字典footprint_resource_type |

**响应** `统一响应结果«Footprint»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `Footprint` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `deletedAt` | `string` |  |  |
|   `footprintId` | `long` |  |  |
|   `resourceId` | `long` |  |  |
|   `resourceType` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `userId` | `long` |  |  |
|   `visitTime` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /user/footprint/{footprintId}

**删除足迹**

根据足迹记录ID删除单条浏览足迹。只能删除自己的足迹记录。需要小程序用户认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `footprintId` | `integer` |  | 足迹ID |

**响应** `统一响应结果«Void»`

---

### `POST` /user/login

**微信登录**

小程序用户通过微信授权码（wx.login获取的code）登录。可选传入phoneCode用于获取手机号绑定，avatar和nickname用于设置头像昵称。首次登录自动注册，返回JWT Token。needProfile=true表示需补充实名信息。无需认证即可调用。

**请求体** `微信小程序登录请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `avatar` | `string` |  | 用户头像URL |
| `code` | `string` | 是 | 微信登录授权码 |
| `nickname` | `string` |  | 用户昵称 |
| `phoneCode` | `string` |  | 手机号授权码（用于获取手机号） |

**响应** `统一响应结果«用户登录响应»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `用户登录响应` |  | 响应数据 |
|   `avatar` | `string` |  | 头像URL |
|   `isNewUser` | `boolean` |  | 是否新用户 |
|   `needProfile` | `boolean` |  | 是否需要完善资料（realName为空时为true） |
|   `nickname` | `string` |  | 昵称 |
|   `phone` | `string` |  | 手机号 |
|   `token` | `string` |  | 登录令牌 |
|   `userId` | `long` |  | 用户ID |
| `message` | `string` |  | 响应消息 |

---

### `POST` /user/login/sms

**手机号验证码登录**

小程序用户通过手机号+短信验证码登录。首次登录自动注册账号，返回JWT Token。登录成功后若needProfile=true，表示需要补充个人信息（实名认证），前端应跳转到信息补充页。无需认证即可调用。

**请求体** `短信验证码登录请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `string` | 是 | 短信验证码（6位数字） |
| `phone` | `string` | 是 | 手机号 |

**响应** `统一响应结果«用户登录响应»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `用户登录响应` |  | 响应数据 |
|   `avatar` | `string` |  | 头像URL |
|   `isNewUser` | `boolean` |  | 是否新用户 |
|   `needProfile` | `boolean` |  | 是否需要完善资料（realName为空时为true） |
|   `nickname` | `string` |  | 昵称 |
|   `phone` | `string` |  | 手机号 |
|   `token` | `string` |  | 登录令牌 |
|   `userId` | `long` |  | 用户ID |
| `message` | `string` |  | 响应消息 |

---

### `POST` /user/logout

**用户登出**

清除当前用户的登录状态并使Token失效。需要小程序用户认证。

**响应** `统一响应结果«Void»`

---

### `GET` /user/profile

**获取用户信息**

获取当前登录用户的个人资料，包括昵称、头像、手机号（脱敏）、实名信息等。手机号返回脱敏格式（如138****0000），证件号同样脱敏处理。需要小程序用户认证（Token中的userId）。

**关联字典**：
- id_card_type（证件类型）：ID_CARD=身份证, PASSPORT=护照
- gender（性别）：0=女, 1=男


**响应** `统一响应结果«用户信息VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `用户信息VO` |  | 响应数据 |
|   `avatar` | `string` |  | 头像URL |
|   `birthday` | `string` |  | 出生日期 |
|   `createdAt` | `string` |  | 创建时间 |
|   `email` | `string` |  | 邮箱 |
|   `gender` | `int` |  | 性别，关联字典gender：0=女, 1=男 |
|   `idCardNo` | `string` |  | 证件号码 |
|   `idCardType` | `string` |  | 证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照 |
|   `nationality` | `string` |  | 国籍 |
|   `needProfile` | `boolean` |  | 是否需要完善资料（realName为空时为true） |
|   `nickname` | `string` |  | 昵称 |
|   `phone` | `string` |  | 手机号（脱敏） |
|   `realName` | `string` |  | 真实姓名 |
|   `status` | `string` |  | 状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁 |
|   `updatedAt` | `string` |  | 更新时间 |
|   `userId` | `long` |  | 用户ID |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /user/profile

**更新用户信息**

更新当前用户的个人资料。首次登录补充信息时realName/idCardType/idCardNo为必填（使用ProfileCompletion验证组）。如果传入身份证号，后端自动解析性别和出生日期。更新手机号后会自动绑定匹配的待绑定订单。需要小程序用户认证。

**关联字典**：
- id_card_type（证件类型）：ID_CARD=身份证, PASSPORT=护照（请求参数idCardType）
- gender（性别）：0=女, 1=男


**请求体** `更新用户资料请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `avatar` | `string` |  | 头像URL |
| `birthday` | `string` |  | 出生日期（从身份证号自动解析） |
| `email` | `string` |  | 邮箱 |
| `gender` | `string` |  | 性别：MALE=男 FEMALE=女（从身份证号自动解析） |
| `idCardNo` | `string` |  | 证件号码（首次登录必填） |
| `idCardType` | `string` |  | 证件类型：ID_CARD=身份证 PASSPORT=护照（首次登录必填） |
| `nationality` | `string` |  | 国籍（默认中国） |
| `nickname` | `string` |  | 昵称 |
| `phone` | `string` |  | 手机号 |
| `realName` | `string` |  | 真实姓名（首次登录必填） |

**响应** `统一响应结果«用户信息VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `用户信息VO` |  | 响应数据 |
|   `avatar` | `string` |  | 头像URL |
|   `birthday` | `string` |  | 出生日期 |
|   `createdAt` | `string` |  | 创建时间 |
|   `email` | `string` |  | 邮箱 |
|   `gender` | `int` |  | 性别，关联字典gender：0=女, 1=男 |
|   `idCardNo` | `string` |  | 证件号码 |
|   `idCardType` | `string` |  | 证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照 |
|   `nationality` | `string` |  | 国籍 |
|   `needProfile` | `boolean` |  | 是否需要完善资料（realName为空时为true） |
|   `nickname` | `string` |  | 昵称 |
|   `phone` | `string` |  | 手机号（脱敏） |
|   `realName` | `string` |  | 真实姓名 |
|   `status` | `string` |  | 状态，关联字典user_status：ACTIVE=正常, BANNED=已封禁 |
|   `updatedAt` | `string` |  | 更新时间 |
|   `userId` | `long` |  | 用户ID |
| `message` | `string` |  | 响应消息 |

---

### `POST` /user/sms/send

**发送短信验证码**

向指定手机号发送6位数字短信验证码，用于小程序手机号登录。同一手机号60秒内不可重复发送，每日最多发送10次。验证码有效期5分钟。无需认证即可调用。

**请求体** `发送短信验证码请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `phone` | `string` | 是 | 手机号 |

**响应** `统一响应结果«Void»`

---

### `GET` /user/traveler

**出行人列表**

获取当前用户的所有出行人列表。如果用户已完成实名认证（realName不为空），列表首项会自动注入一个'本人'虚拟出行人（travelerId=0）。默认出行人排在前面，其余按创建时间排序。需要小程序用户认证。

**关联字典**：
- gender（性别）：返回字段gender
- id_card_type（证件类型）：返回字段idCardType
- traveler_type（出行人类型）：返回字段travelerType

**响应** `统一响应结果«List«Traveler»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `Traveler[]` |  | 响应数据 |
|   `birthday` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `deletedAt` | `string` |  |  |
|   `email` | `string` |  |  |
|   `emergencyContact` | `string` |  |  |
|   `emergencyPhone` | `string` |  |  |
|   `gender` | `int` |  |  |
|   `idCardNo` | `string` |  |  |
|   `idCardType` | `string` |  |  |
|   `isDefault` | `int` |  |  |
|   `name` | `string` |  |  |
|   `nationality` | `string` |  |  |
|   `phone` | `string` |  |  |
|   `travelerId` | `long` |  |  |
|   `travelerType` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `userId` | `long` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `POST` /user/traveler

**新增出行人**

为当前用户添加一位出行人信息，用于下单时选择。出行人类型（成人/儿童/婴儿）根据出生日期自动判断，无需手动传入。如果传入身份证号，后端自动校验格式并解析性别。每个用户最多可添加20位出行人。需要小程序用户认证。

**关联字典**：
- gender（性别）：请求/返回字段gender（0=女, 1=男）
- id_card_type（证件类型）：请求/返回字段idCardType（ID_CARD=身份证, PASSPORT=护照等）
- traveler_type（出行人类型）：返回字段travelerType（ADULT=成人, CHILD=儿童, INFANT=婴儿，自动计算）

**请求体** `出行人请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `birthday` | `string` | 是 | 出生日期（必填，后端根据此字段自动判断人员类型） |
| `email` | `string` |  | 邮箱 |
| `emergencyContact` | `string` |  | 紧急联系人姓名 |
| `emergencyPhone` | `string` |  | 紧急联系人电话 |
| `gender` | `int` |  | 性别，关联字典gender：0=女, 1=男 |
| `idCardNo` | `string` |  | 证件号码 |
| `idCardType` | `string` |  | 证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照 |
| `isDefault` | `boolean` |  | 是否设为默认出行人 |
| `name` | `string` | 是 | 出行人姓名 |
| `nationality` | `string` |  | 国籍 |
| `phone` | `string` |  | 手机号 |

**响应** `统一响应结果«Traveler»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `Traveler` |  | 响应数据 |
|   `birthday` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `deletedAt` | `string` |  |  |
|   `email` | `string` |  |  |
|   `emergencyContact` | `string` |  |  |
|   `emergencyPhone` | `string` |  |  |
|   `gender` | `int` |  |  |
|   `idCardNo` | `string` |  |  |
|   `idCardType` | `string` |  |  |
|   `isDefault` | `int` |  |  |
|   `name` | `string` |  |  |
|   `nationality` | `string` |  |  |
|   `phone` | `string` |  |  |
|   `travelerId` | `long` |  |  |
|   `travelerType` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `userId` | `long` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /user/traveler/{travelerId}

**出行人详情**

获取指定出行人的详细信息。

**关联字典**：
- gender（性别）：返回字段gender
- id_card_type（证件类型）：返回字段idCardType
- traveler_type（出行人类型）：返回字段travelerType

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `travelerId` | `integer` |  | 出行人ID |

**响应** `统一响应结果«Traveler»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `Traveler` |  | 响应数据 |
|   `birthday` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `deletedAt` | `string` |  |  |
|   `email` | `string` |  |  |
|   `emergencyContact` | `string` |  |  |
|   `emergencyPhone` | `string` |  |  |
|   `gender` | `int` |  |  |
|   `idCardNo` | `string` |  |  |
|   `idCardType` | `string` |  |  |
|   `isDefault` | `int` |  |  |
|   `name` | `string` |  |  |
|   `nationality` | `string` |  |  |
|   `phone` | `string` |  |  |
|   `travelerId` | `long` |  |  |
|   `travelerType` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `userId` | `long` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /user/traveler/{travelerId}

**更新出行人**

更新指定出行人的信息。

**关联字典**：
- gender（性别）：请求/返回字段gender
- id_card_type（证件类型）：请求/返回字段idCardType
- traveler_type（出行人类型）：返回字段travelerType（自动计算）

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `travelerId` | `integer` |  | 出行人ID |

**请求体** `出行人请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `birthday` | `string` | 是 | 出生日期（必填，后端根据此字段自动判断人员类型） |
| `email` | `string` |  | 邮箱 |
| `emergencyContact` | `string` |  | 紧急联系人姓名 |
| `emergencyPhone` | `string` |  | 紧急联系人电话 |
| `gender` | `int` |  | 性别，关联字典gender：0=女, 1=男 |
| `idCardNo` | `string` |  | 证件号码 |
| `idCardType` | `string` |  | 证件类型，关联字典id_card_type：ID_CARD=身份证, PASSPORT=护照 |
| `isDefault` | `boolean` |  | 是否设为默认出行人 |
| `name` | `string` | 是 | 出行人姓名 |
| `nationality` | `string` |  | 国籍 |
| `phone` | `string` |  | 手机号 |

**响应** `统一响应结果«Traveler»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `Traveler` |  | 响应数据 |
|   `birthday` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `deletedAt` | `string` |  |  |
|   `email` | `string` |  |  |
|   `emergencyContact` | `string` |  |  |
|   `emergencyPhone` | `string` |  |  |
|   `gender` | `int` |  |  |
|   `idCardNo` | `string` |  |  |
|   `idCardType` | `string` |  |  |
|   `isDefault` | `int` |  |  |
|   `name` | `string` |  |  |
|   `nationality` | `string` |  |  |
|   `phone` | `string` |  |  |
|   `travelerId` | `long` |  |  |
|   `travelerType` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `userId` | `long` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /user/traveler/{travelerId}

**删除出行人**

删除指定的出行人记录（软删除）。

**权限**：需要小程序用户认证。
**注意**：如果该出行人已关联到未完成的订单，删除不影响订单中的出行人快照数据。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `travelerId` | `integer` |  | 出行人ID |

**响应** `统一响应结果«Void»`

---

### `PUT` /user/traveler/{travelerId}/default

**设为默认出行人**

将指定出行人设为默认。每个用户只能有一个默认出行人，设置新的默认会自动取消原来的默认。默认出行人在下单时会被自动选中。需要小程序用户认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `travelerId` | `integer` |  | 出行人ID |

**响应** `统一响应结果«Void»`

---

## 常见问题管理接口

### `GET` /admin/faq/categories

**分类列表**

获取所有FAQ分类的完整列表（不分页）。
每个分类包含名称、排序号、状态等信息。

**权限**：需要管理员登录。

**响应** `统一响应结果«List«常见问题分类VO»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `常见问题分类VO[]` |  | 响应数据 |
|   `createdAt` | `string` |  | 创建时间 |
|   `id` | `long` |  | 分类ID |
|   `items` | `常见问题条目VO[]` |  | 条目列表（仅内部接口返回） |
|     `answer` | `string` |  | 回答 |
|     `categoryId` | `long` |  | 所属分类ID |
|     `createdAt` | `string` |  | 创建时间 |
|     `id` | `long` |  | 条目ID |
|     `question` | `string` |  | 问题 |
|     `sortOrder` | `int` |  | 排序号 |
|     `status` | `int` |  | 状态：0=禁用 1=启用 |
|     `updatedAt` | `string` |  | 更新时间 |
|   `name` | `string` |  | 分类名称 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态：0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/faq/categories

**创建分类**

创建新的FAQ分类，用于对常见问题进行归类。

**权限**：需要管理员登录。
**注意**：分类名称不能重复。

**请求体** `常见问题分类请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 是 | 分类名称 |
| `sortOrder` | `int` |  | 排序号 |
| `status` | `int` |  | 状态：0=禁用 1=启用 |

**响应** `统一响应结果«常见问题分类VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `常见问题分类VO` |  | 响应数据 |
|   `createdAt` | `string` |  | 创建时间 |
|   `id` | `long` |  | 分类ID |
|   `items` | `常见问题条目VO[]` |  | 条目列表（仅内部接口返回） |
|     `answer` | `string` |  | 回答 |
|     `categoryId` | `long` |  | 所属分类ID |
|     `createdAt` | `string` |  | 创建时间 |
|     `id` | `long` |  | 条目ID |
|     `question` | `string` |  | 问题 |
|     `sortOrder` | `int` |  | 排序号 |
|     `status` | `int` |  | 状态：0=禁用 1=启用 |
|     `updatedAt` | `string` |  | 更新时间 |
|   `name` | `string` |  | 分类名称 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态：0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/faq/categories/{id}

**更新分类**

更新指定FAQ分类的名称、排序号、状态等信息。

**权限**：需要管理员登录。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 分类ID |

**请求体** `常见问题分类请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `name` | `string` | 是 | 分类名称 |
| `sortOrder` | `int` |  | 排序号 |
| `status` | `int` |  | 状态：0=禁用 1=启用 |

**响应** `统一响应结果«常见问题分类VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `常见问题分类VO` |  | 响应数据 |
|   `createdAt` | `string` |  | 创建时间 |
|   `id` | `long` |  | 分类ID |
|   `items` | `常见问题条目VO[]` |  | 条目列表（仅内部接口返回） |
|     `answer` | `string` |  | 回答 |
|     `categoryId` | `long` |  | 所属分类ID |
|     `createdAt` | `string` |  | 创建时间 |
|     `id` | `long` |  | 条目ID |
|     `question` | `string` |  | 问题 |
|     `sortOrder` | `int` |  | 排序号 |
|     `status` | `int` |  | 状态：0=禁用 1=启用 |
|     `updatedAt` | `string` |  | 更新时间 |
|   `name` | `string` |  | 分类名称 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态：0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/faq/categories/{id}

**删除分类**

删除指定的FAQ分类（软删除）。

**权限**：需要管理员登录。
**注意**：删除分类不会删除其下的条目，但条目将变为无分类状态。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 分类ID |

**响应** `统一响应结果«Void»`

---

### `GET` /admin/faq/items

**条目列表**

查询FAQ条目列表，支持按分类ID筛选。
返回问题标题、回答内容（富文本）、排序号等。

**权限**：需要管理员登录。

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `categoryId` | `integer(int64)` |  | 分类ID（可选） |  |

**响应** `统一响应结果«List«常见问题条目VO»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `常见问题条目VO[]` |  | 响应数据 |
|   `answer` | `string` |  | 回答 |
|   `categoryId` | `long` |  | 所属分类ID |
|   `createdAt` | `string` |  | 创建时间 |
|   `id` | `long` |  | 条目ID |
|   `question` | `string` |  | 问题 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态：0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/faq/items

**创建条目**

创建一条常见问题，包含问题标题和回答（支持富文本）。

**权限**：需要管理员登录。
**注意**：需指定所属分类ID，排序号越小越靠前。

**请求体** `常见问题条目请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `answer` | `string` |  | 回答（支持富文本） |
| `categoryId` | `long` | 是 | 所属分类ID |
| `question` | `string` | 是 | 问题 |
| `sortOrder` | `int` |  | 排序号 |
| `status` | `int` |  | 状态：0=禁用 1=启用 |

**响应** `统一响应结果«常见问题条目VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `常见问题条目VO` |  | 响应数据 |
|   `answer` | `string` |  | 回答 |
|   `categoryId` | `long` |  | 所属分类ID |
|   `createdAt` | `string` |  | 创建时间 |
|   `id` | `long` |  | 条目ID |
|   `question` | `string` |  | 问题 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态：0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/faq/items/{id}

**更新条目**

更新指定FAQ条目的问题标题、回答内容、排序号等信息。

**权限**：需要管理员登录。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 条目ID |

**请求体** `常见问题条目请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `answer` | `string` |  | 回答（支持富文本） |
| `categoryId` | `long` | 是 | 所属分类ID |
| `question` | `string` | 是 | 问题 |
| `sortOrder` | `int` |  | 排序号 |
| `status` | `int` |  | 状态：0=禁用 1=启用 |

**响应** `统一响应结果«常见问题条目VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `常见问题条目VO` |  | 响应数据 |
|   `answer` | `string` |  | 回答 |
|   `categoryId` | `long` |  | 所属分类ID |
|   `createdAt` | `string` |  | 创建时间 |
|   `id` | `long` |  | 条目ID |
|   `question` | `string` |  | 问题 |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态：0=禁用 1=启用 |
|   `updatedAt` | `string` |  | 更新时间 |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/faq/items/{id}

**删除条目**

删除指定的FAQ条目（软删除）。

**权限**：需要管理员登录。
**注意**：删除后小程序FAQ页面将不再展示该条目。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 条目ID |

**响应** `统一响应结果«Void»`

---

## 探索分类管理接口

### `GET` /admin/explore/category

**探索分类列表**

分页查询探索分类列表，支持按关键词和状态筛选。

**关联字典**：
- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keyword` | `string` |  | 搜索关键词 |  |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `status` | `integer(int32)` |  | 状态 |  |

**响应** `统一响应结果«分页结果«探索分类 VO»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«探索分类 VO»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `探索分类 VO[]` |  | 数据列表 |
|     `coverUrl` | `string` |  | 封面图URL |
|     `createdAt` | `string` |  | 创建时间 |
|     `favoriteCount` | `int` |  | 收藏数 |
|     `iconUrl` | `string` |  | 图标URL |
|     `id` | `string` |  | 分类ID |
|     `likeCount` | `int` |  | 点赞数 |
|     `resourceCount` | `int` |  | 关联资源数量 |
|     `sortOrder` | `int` |  | 排序号 |
|     `status` | `int` |  | 状态：0=下线 1=上线 |
|     `subtitle` | `string` |  | 副标题 |
|     `title` | `string` |  | 分类标题 |
|     `viewCount` | `int` |  | 浏览量 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/explore/category

**创建探索分类**

创建新的探索分类，用于小程序探索页面的分类展示。
可关联多个景区资源，设置封面图和描述文字。

**权限**：需要管理员登录。

**请求体** `探索分类请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `coverUrl` | `string` | 是 | 封面图URL |
| `description` | `string` |  | 分类描述 |
| `iconUrl` | `string` |  | 图标URL |
| `resources` | `探索分类资源请求[]` |  | 关联资源列表 |
|   `coverUrl` | `string` |  | 封面图URL |
|   `description` | `string` |  | 资源简介(支持HTML) |
|   `resourceId` | `long` |  | 资源ID |
|   `resourceName` | `string` |  | 资源名称 |
|   `resourceType` | `string` |  | 资源类型 |
| `sortOrder` | `int` |  | 排序号（越小越靠前） |
| `status` | `int` |  | 状态：0=下线 1=上线 |
| `subtitle` | `string` |  | 副标题 |
| `title` | `string` | 是 | 分类标题 |

**响应** `统一响应结果«Void»`

---

### `GET` /admin/explore/category/{id}

**探索分类详情**

获取指定探索分类的详细信息，包括标题、封面图、描述、关联的景区资源列表等。

**权限**：需要管理员登录。

**关联字典**：
- common_status（通用状态）：返回字段status（0=禁用, 1=启用）

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 分类ID |

**响应** `统一响应结果«探索分类详情 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `探索分类详情 VO` |  | 响应数据 |
|   `coverUrl` | `string` |  | 封面图URL |
|   `createdAt` | `string` |  | 创建时间 |
|   `description` | `string` |  | 分类描述 |
|   `favoriteCount` | `int` |  | 收藏数 |
|   `iconUrl` | `string` |  | 图标URL |
|   `id` | `string` |  | 分类ID |
|   `isFavorited` | `boolean` |  | 当前用户是否已收藏 |
|   `isLiked` | `boolean` |  | 当前用户是否已点赞 |
|   `likeCount` | `int` |  | 点赞数 |
|   `resources` | `探索分类关联资源项[]` |  | 关联资源列表 |
|     `coverUrl` | `string` |  | 封面图URL |
|     `description` | `string` |  | 资源简介(支持HTML) |
|     `resourceId` | `string` |  | 资源ID |
|     `resourceName` | `string` |  | 资源名称 |
|     `resourceType` | `string` |  | 资源类型 |
|     `sortOrder` | `int` |  | 排序号 |
|   `subtitle` | `string` |  | 副标题 |
|   `title` | `string` |  | 分类标题 |
|   `viewCount` | `int` |  | 浏览量 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/explore/category/{id}

**更新探索分类**

更新指定探索分类的标题、封面图、描述、关联资源、状态等信息。

**权限**：需要管理员登录。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 分类ID |

**请求体** `探索分类请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `coverUrl` | `string` | 是 | 封面图URL |
| `description` | `string` |  | 分类描述 |
| `iconUrl` | `string` |  | 图标URL |
| `resources` | `探索分类资源请求[]` |  | 关联资源列表 |
|   `coverUrl` | `string` |  | 封面图URL |
|   `description` | `string` |  | 资源简介(支持HTML) |
|   `resourceId` | `long` |  | 资源ID |
|   `resourceName` | `string` |  | 资源名称 |
|   `resourceType` | `string` |  | 资源类型 |
| `sortOrder` | `int` |  | 排序号（越小越靠前） |
| `status` | `int` |  | 状态：0=下线 1=上线 |
| `subtitle` | `string` |  | 副标题 |
| `title` | `string` | 是 | 分类标题 |

**响应** `统一响应结果«Void»`

---

### `DELETE` /admin/explore/category/{id}

**删除探索分类**

删除指定的探索分类（软删除），同时清除关联的资源绑定关系。

**权限**：需要管理员登录。
**注意**：删除后小程序探索页面将不再展示该分类。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 分类ID |

**响应** `统一响应结果«Void»`

---

## 用户协议管理接口

### `GET` /admin/agreement

**协议列表**

分页查询用户协议列表，支持按关键词和状态筛选。

**关联字典**：
- common_status（通用状态）：请求参数status和返回字段status（0=禁用, 1=启用）

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keyword` | `string` |  | 搜索关键词 |  |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `status` | `integer(int32)` |  | 状态 |  |

**响应** `统一响应结果«分页结果«协议 VO»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«协议 VO»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `协议 VO[]` |  | 数据列表 |
|     `content` | `string` |  | 协议内容（HTML富文本） |
|     `createTime` | `string` |  | 创建时间 |
|     `id` | `string` |  | 协议ID |
|     `sortOrder` | `int` |  | 排序号 |
|     `status` | `int` |  | 状态：0=下线 1=上线 |
|     `title` | `string` |  | 协议标题 |
|     `type` | `string` |  | 协议类型标识 |
|     `updateTime` | `string` |  | 更新时间 |
|     `version` | `string` |  | 版本号 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/agreement

**新增协议**

创建新的用户协议，如用户服务协议、隐私政策等。

**权限**：需要管理员登录。
**注意**：协议类型（type）需唯一，同一类型不能重复创建。内容支持富文本。

**请求体** `协议请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `content` | `string` | 是 | 协议内容（HTML富文本） |
| `sortOrder` | `int` |  | 排序号（越小越靠前） |
| `status` | `int` |  | 状态：0=下线 1=上线 |
| `title` | `string` | 是 | 协议标题 |
| `type` | `string` | 是 | 协议类型标识（唯一） |
| `version` | `string` |  | 版本号 |

**响应** `统一响应结果«协议 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `协议 VO` |  | 响应数据 |
|   `content` | `string` |  | 协议内容（HTML富文本） |
|   `createTime` | `string` |  | 创建时间 |
|   `id` | `string` |  | 协议ID |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态：0=下线 1=上线 |
|   `title` | `string` |  | 协议标题 |
|   `type` | `string` |  | 协议类型标识 |
|   `updateTime` | `string` |  | 更新时间 |
|   `version` | `string` |  | 版本号 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/agreement/{id}

**协议详情**

获取指定用户协议的详细信息，包括标题、内容（富文本）、版本号等。

**权限**：需要管理员登录。

**关联字典**：
- common_status（通用状态）：返回字段status（0=禁用, 1=启用）

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 协议ID |

**响应** `统一响应结果«协议 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `协议 VO` |  | 响应数据 |
|   `content` | `string` |  | 协议内容（HTML富文本） |
|   `createTime` | `string` |  | 创建时间 |
|   `id` | `string` |  | 协议ID |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态：0=下线 1=上线 |
|   `title` | `string` |  | 协议标题 |
|   `type` | `string` |  | 协议类型标识 |
|   `updateTime` | `string` |  | 更新时间 |
|   `version` | `string` |  | 版本号 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/agreement/{id}

**编辑协议**

更新指定用户协议的标题、内容、状态等信息。

**权限**：需要管理员登录。
**注意**：修改后小程序端会实时展示新内容。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 协议ID |

**请求体** `协议请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `content` | `string` | 是 | 协议内容（HTML富文本） |
| `sortOrder` | `int` |  | 排序号（越小越靠前） |
| `status` | `int` |  | 状态：0=下线 1=上线 |
| `title` | `string` | 是 | 协议标题 |
| `type` | `string` | 是 | 协议类型标识（唯一） |
| `version` | `string` |  | 版本号 |

**响应** `统一响应结果«协议 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `协议 VO` |  | 响应数据 |
|   `content` | `string` |  | 协议内容（HTML富文本） |
|   `createTime` | `string` |  | 创建时间 |
|   `id` | `string` |  | 协议ID |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态：0=下线 1=上线 |
|   `title` | `string` |  | 协议标题 |
|   `type` | `string` |  | 协议类型标识 |
|   `updateTime` | `string` |  | 更新时间 |
|   `version` | `string` |  | 版本号 |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/agreement/{id}

**删除协议**

删除指定的用户协议记录（软删除）。

**权限**：需要管理员登录。
**注意**：删除后小程序端将无法查看该协议。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 协议ID |

**响应** `统一响应结果«Void»`

---

## 管理员管理接口

### `GET` /admin/user

**管理员列表**

分页查询管理员列表，支持按角色、状态、企微绑定状态筛选。status取值：ACTIVE=正常 LOCKED=已锁定 DISABLED=已禁用。wechatBound：true=已绑定企业微信 false=未绑定。需要管理员认证。

**关联字典**：
- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用（筛选条件+列表展示）


**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `roleId` | `integer(int64)` |  | 角色ID |  |
| `status` | `string` |  | 状态 |  |
| `wechatBound` | `boolean` |  | 是否绑定企业微信: true=已绑定, false=未绑定 |  |

**响应** `统一响应结果«分页结果«AdminUser»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«AdminUser»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `AdminUser[]` |  | 数据列表 |
|     `adminId` | `long` |  |  |
|     `avatar` | `string` |  |  |
|     `contactQrUrl` | `string` |  |  |
|     `createdAt` | `string` |  |  |
|     `currentRoleId` | `long` |  |  |
|     `effectiveAvatar` | `string` |  |  |
|     `enterpriseWechatDeptNames` | `string` |  |  |
|     `enterpriseWechatId` | `string` |  |  |
|     `enterpriseWechatName` | `string` |  |  |
|     `failedLoginCount` | `int` |  |  |
|     `lockedUntil` | `string` |  |  |
|     `passwordChangedAt` | `string` |  |  |
|     `roleKey` | `string` |  |  |
|     `roleName` | `string` |  |  |
|     `roles` | `SysRole[]` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|     `username` | `string` |  |  |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/user

**创建管理员**

创建新的后台管理员账号。默认密码为Admin@123456，管理员首次登录后建议修改密码。可通过roleIds分配多个角色，也兼容旧的单角色roleId参数。需要SUPER_ADMIN或ADMIN角色。

**关联字典**：
- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用


**请求体** `创建管理员请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roleId` | `long` |  | 角色ID（已废弃，请使用roleIds） |
| `roleIds` | `long[]` |  | 角色ID列表（多角色） |
| `username` | `string` | 是 | 用户名 |

**响应** `统一响应结果«AdminUser»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `AdminUser` |  | 响应数据 |
|   `adminId` | `long` |  |  |
|   `avatar` | `string` |  |  |
|   `contactQrUrl` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `currentRoleId` | `long` |  |  |
|   `effectiveAvatar` | `string` |  |  |
|   `enterpriseWechatDeptNames` | `string` |  |  |
|   `enterpriseWechatId` | `string` |  |  |
|   `enterpriseWechatName` | `string` |  |  |
|   `failedLoginCount` | `int` |  |  |
|   `lockedUntil` | `string` |  |  |
|   `passwordChangedAt` | `string` |  |  |
|   `roleKey` | `string` |  |  |
|   `roleName` | `string` |  |  |
|   `roles` | `SysRole[]` |  |  |
|     `createdAt` | `string` |  |  |
|     `remark` | `string` |  |  |
|     `roleId` | `long` |  |  |
|     `roleKey` | `string` |  |  |
|     `roleName` | `string` |  |  |
|     `sortOrder` | `int` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `username` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/user/{adminId}

**获取管理员详情**

获取指定管理员的完整信息。

**关联字典**：
- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用


**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adminId` | `integer` |  | 管理员ID |

**响应** `统一响应结果«AdminUser»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `AdminUser` |  | 响应数据 |
|   `adminId` | `long` |  |  |
|   `avatar` | `string` |  |  |
|   `contactQrUrl` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `currentRoleId` | `long` |  |  |
|   `effectiveAvatar` | `string` |  |  |
|   `enterpriseWechatDeptNames` | `string` |  |  |
|   `enterpriseWechatId` | `string` |  |  |
|   `enterpriseWechatName` | `string` |  |  |
|   `failedLoginCount` | `int` |  |  |
|   `lockedUntil` | `string` |  |  |
|   `passwordChangedAt` | `string` |  |  |
|   `roleKey` | `string` |  |  |
|   `roleName` | `string` |  |  |
|   `roles` | `SysRole[]` |  |  |
|     `createdAt` | `string` |  |  |
|     `remark` | `string` |  |  |
|     `roleId` | `long` |  |  |
|     `roleKey` | `string` |  |  |
|     `roleName` | `string` |  |  |
|     `sortOrder` | `int` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `username` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/user/{adminId}

**更新管理员**

更新管理员信息，包括用户名、状态、角色分配等。

**关联字典**：
- admin_status（管理员状态）：ACTIVE=启用, LOCKED=锁定, DISABLED=禁用


**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adminId` | `integer` |  | 管理员ID |

**请求体** `更新管理员请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `enterpriseWechatId` | `string` |  | 企业微信用户ID |
| `roleId` | `long` |  | 角色ID（已废弃，请使用roleIds） |
| `roleIds` | `long[]` |  | 角色ID列表（多角色） |

**响应** `统一响应结果«AdminUser»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `AdminUser` |  | 响应数据 |
|   `adminId` | `long` |  |  |
|   `avatar` | `string` |  |  |
|   `contactQrUrl` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `currentRoleId` | `long` |  |  |
|   `effectiveAvatar` | `string` |  |  |
|   `enterpriseWechatDeptNames` | `string` |  |  |
|   `enterpriseWechatId` | `string` |  |  |
|   `enterpriseWechatName` | `string` |  |  |
|   `failedLoginCount` | `int` |  |  |
|   `lockedUntil` | `string` |  |  |
|   `passwordChangedAt` | `string` |  |  |
|   `roleKey` | `string` |  |  |
|   `roleName` | `string` |  |  |
|   `roles` | `SysRole[]` |  |  |
|     `createdAt` | `string` |  |  |
|     `remark` | `string` |  |  |
|     `roleId` | `long` |  |  |
|     `roleKey` | `string` |  |  |
|     `roleName` | `string` |  |  |
|     `sortOrder` | `int` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `username` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/user/{adminId}

**删除管理员**

删除指定管理员账号（软删除）。不能删除自己的账号，不能删除SUPER_ADMIN角色的账号（除非操作者也是SUPER_ADMIN）。删除后该管理员的登录状态自动失效。需要SUPER_ADMIN或ADMIN角色。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adminId` | `integer` |  | 管理员ID |

**响应** `统一响应结果«Void»`

---

### `POST` /admin/user/{adminId}/reset-password

**重置密码**

将指定管理员的密码重置为默认密码（Admin@123456）。用于管理员忘记密码时由上级管理员操作重置。重置后管理员可用默认密码登录，建议立即修改。需要SUPER_ADMIN或ADMIN角色。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adminId` | `integer` |  | 管理员ID |

**响应** `统一响应结果«Void»`

---

### `POST` /admin/user/{adminId}/unlock

**解锁管理员**

解锁因登录失败次数过多而被锁定的管理员账号。管理员连续5次登录失败后账号自动锁定30分钟，此接口可立即解锁。需要SUPER_ADMIN或ADMIN角色。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adminId` | `integer` |  | 管理员ID |

**响应** `统一响应结果«Void»`

---

### `PUT` /admin/user/{adminId}/wechat-binding

**修改企业微信绑定（支持换绑）**

为管理员绑定或更换企业微信账号。绑定后管理员可通过企业微信扫码登录，并可接收审批通知。如果目标企微ID已被其他管理员绑定，需设置forceRebind=true强制换绑。需要管理员认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `adminId` | `integer` |  | 管理员ID |

**请求体** `企业微信绑定请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `enterpriseWechatId` | `string` |  | 企业微信ID（为空则解绑） |
| `forceRebind` | `boolean` |  | 是否强制换绑（当ID已被其他管理员占用时） |

**响应** `统一响应结果«Map«string,object»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `object` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

## 管理员认证接口

### `GET` /admin/auth/2fa/callback

**2FA企微扫码回调**

企业微信OAuth回调地址，用户扫码授权后微信服务器回调此接口。此接口由微信服务器调用，非前端直接调用。回调成功后将state对应的会话标记为已扫码，前端轮询 /2fa/check 即可获取结果。返回HTML页面（成功/失败提示），不返回JSON。

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `code` | `string` |  | 授权码 |  |
| `state` | `string` |  | 会话状态 |  |

**响应** `string`

---

### `GET` /admin/auth/2fa/check

**查询2FA扫码状态**

前端轮询此接口检查2FA扫码验证是否完成。返回status字段：PENDING=等待扫码，SCANNED=已完成验证（附带token和用户信息）。建议轮询间隔2秒，超过5分钟未扫码会话自动失效。无需认证即可调用（登录流程中使用）。

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `state` | `string` |  | 会话状态 |  |

**响应** `统一响应结果«Map«string,object»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `object` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/auth/2fa/confirm

**手动确认扫码（内网穿透环境workaround，默认关闭）**

在内网穿透环境下，企微回调可能无法正常到达，此接口作为手动替代方案。
需在Nacos配置中开启 auth.2fa-confirm-enabled=true 才可使用。

**权限**：无需认证（登录流程中使用）。
**注意**：生产环境应保持关闭，仅限开发/测试时使用。

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `adminId` | `string` |  | 管理员ID |  |
| `state` | `string` |  | 会话状态 |  |

**响应** `统一响应结果«Void»`

---

### `GET` /admin/auth/2fa/qrcode

**生成2FA扫码会话**

生成企业微信扫码二维码的会话信息，用于新设备二次验证。返回包含qrcodeUrl（二维码链接）和state（会话标识）。前端展示二维码后通过轮询 /2fa/check 接口检查扫码状态。无需认证即可调用（登录流程中使用）。

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `adminId` | `integer(int64)` |  | 管理员ID |  |

**响应** `统一响应结果«Map«string,object»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `object` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/auth/avatar

**更新头像**

管理员更新自己的头像。需先通过文件服务上传图片获取OSS URL和fileId，再调用此接口绑定。旧头像的文件引用会自动解绑。需要管理员认证。

**请求体** `头像更新请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `avatar` | `string` | 是 | 头像URL |
| `fileId` | `long` |  | 文件ID |

**响应** `统一响应结果«Void»`

---

### `GET` /admin/auth/info

**获取当前管理员信息**

获取当前登录管理员的完整信息，包括用户名、头像、角色列表、当前角色、菜单权限等。前端页面初始化时调用此接口获取用户信息和权限数据。需要管理员认证。

**响应** `统一响应结果«管理员登录响应»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `管理员登录响应` |  | 响应数据 |
|   `adminId` | `long` |  | 管理员ID |
|   `avatar` | `string` |  | 头像URL |
|   `requireTwoFa` | `boolean` |  | 是否需要二次验证 |
|   `requireWechatBind` | `boolean` |  | 是否需要绑定企业微信 |
|   `role` | `string` |  | 角色标识（主角色） |
|   `roleName` | `string` |  | 角色名称（主角色） |
|   `roles` | `角色信息[]` |  | 角色列表（多角色） |
|     `roleId` | `long` |  | 角色ID |
|     `roleKey` | `string` |  | 角色标识 |
|     `roleName` | `string` |  | 角色名称 |
|   `token` | `string` |  | 登录令牌 |
|   `username` | `string` |  | 用户名 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/auth/login

**管理员登录**

管理员通过用户名+密码登录后台管理系统。首次在新设备登录时需要进行企业微信扫码二次验证（2FA），返回needTwoFa=true。登录失败5次后账号将被锁定30分钟。无需认证即可调用。

**请求体** `管理员登录请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `password` | `string` | 是 | 密码 |
| `username` | `string` | 是 | 用户名 |

**响应** `统一响应结果«管理员登录响应»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `管理员登录响应` |  | 响应数据 |
|   `adminId` | `long` |  | 管理员ID |
|   `avatar` | `string` |  | 头像URL |
|   `requireTwoFa` | `boolean` |  | 是否需要二次验证 |
|   `requireWechatBind` | `boolean` |  | 是否需要绑定企业微信 |
|   `role` | `string` |  | 角色标识（主角色） |
|   `roleName` | `string` |  | 角色名称（主角色） |
|   `roles` | `角色信息[]` |  | 角色列表（多角色） |
|     `roleId` | `long` |  | 角色ID |
|     `roleKey` | `string` |  | 角色标识 |
|     `roleName` | `string` |  | 角色名称 |
|   `token` | `string` |  | 登录令牌 |
|   `username` | `string` |  | 用户名 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/auth/logout

**管理员登出**

清除管理员的登录状态并使当前Token失效。前端应在登出后清除本地存储的Token和用户信息。需要管理员认证。

**响应** `统一响应结果«Void»`

---

### `PUT` /admin/auth/password

**修改密码**

管理员修改自己的登录密码。需验证旧密码正确后才能设置新密码，新密码须满足复杂度要求（8-128位，含大小写字母和数字）。修改成功后当前Token仍然有效，无需重新登录。需要管理员认证（Token中的adminId）。

**请求体** `修改密码请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `newPassword` | `string` | 是 | 新密码（8-128位，须含大小写字母和数字） |
| `oldPassword` | `string` | 是 | 旧密码 |

**响应** `统一响应结果«Void»`

---

### `POST` /admin/auth/switch-role

**切换当前角色**

多角色管理员切换当前活跃角色。切换后返回新的Token和角色对应的菜单权限，前端需更新本地Token并刷新菜单。只能切换到该管理员已分配的角色，否则报错。需要管理员认证。

**请求体** `角色切换请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roleId` | `long` | 是 | 目标角色ID |

**响应** `统一响应结果«管理员登录响应»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `管理员登录响应` |  | 响应数据 |
|   `adminId` | `long` |  | 管理员ID |
|   `avatar` | `string` |  | 头像URL |
|   `requireTwoFa` | `boolean` |  | 是否需要二次验证 |
|   `requireWechatBind` | `boolean` |  | 是否需要绑定企业微信 |
|   `role` | `string` |  | 角色标识（主角色） |
|   `roleName` | `string` |  | 角色名称（主角色） |
|   `roles` | `角色信息[]` |  | 角色列表（多角色） |
|     `roleId` | `long` |  | 角色ID |
|     `roleKey` | `string` |  | 角色标识 |
|     `roleName` | `string` |  | 角色名称 |
|   `token` | `string` |  | 登录令牌 |
|   `username` | `string` |  | 用户名 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/auth/wechat-qr

**生成企业微信扫码登录会话**

生成企业微信扫码直接登录的会话信息（非2FA验证，而是扫码替代密码登录）。返回包含qrcodeUrl和state。前端展示二维码后通过轮询 /wechat-qr/status 检查登录状态。无需认证即可调用。

**响应** `统一响应结果«Map«string,object»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `object` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/auth/wechat-qr/callback

**企业微信扫码登录回调**

企业微信OAuth回调地址，扫码登录授权后微信服务器回调此接口。此接口由微信服务器调用，非前端直接调用。回调后标记会话为已扫码，前端通过轮询 /wechat-qr/status 获取登录结果。返回HTML页面，不返回JSON。

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `code` | `string` |  | 授权码 |  |
| `state` | `string` |  | 会话状态 |  |

**响应** `string`

---

### `GET` /admin/auth/wechat-qr/status

**查询企业微信扫码登录状态**

前端轮询此接口检查扫码登录是否完成。返回status字段：PENDING=等待扫码，SCANNED=已扫码登录成功（附带token和用户信息）。建议轮询间隔2秒，超过5分钟未扫码会话自动失效。无需认证即可调用。

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `state` | `string` |  | 会话状态 |  |

**响应** `统一响应结果«Map«string,object»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `object` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/auth/wechat/verify-2fa

**2FA验证**

新设备登录时的企业微信二次验证。管理员登录返回needTwoFa=true后，前端调用此接口提交验证码完成登录。验证通过后设备将被标记为可信设备，后续登录不再需要2FA。无需认证即可调用。

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `adminId` | `integer(int64)` |  | 管理员ID |  |

**请求体** `二次验证请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `string` | 是 | 验证码 |

**响应** `统一响应结果«管理员登录响应»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `管理员登录响应` |  | 响应数据 |
|   `adminId` | `long` |  | 管理员ID |
|   `avatar` | `string` |  | 头像URL |
|   `requireTwoFa` | `boolean` |  | 是否需要二次验证 |
|   `requireWechatBind` | `boolean` |  | 是否需要绑定企业微信 |
|   `role` | `string` |  | 角色标识（主角色） |
|   `roleName` | `string` |  | 角色名称（主角色） |
|   `roles` | `角色信息[]` |  | 角色列表（多角色） |
|     `roleId` | `long` |  | 角色ID |
|     `roleKey` | `string` |  | 角色标识 |
|     `roleName` | `string` |  | 角色名称 |
|   `token` | `string` |  | 登录令牌 |
|   `username` | `string` |  | 用户名 |
| `message` | `string` |  | 响应消息 |

---

## 联系我们管理接口

### `GET` /admin/contact

**联系方式列表**

分页查询联系方式列表，支持按关键词和状态筛选。

**关联字典**：
- contact_channel_type（联系渠道类型）：返回字段channelType（PHONE=电话, WECHAT=微信, EMAIL=邮箱等）
- common_status（通用状态）：请求参数status和返回字段status

**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `keyword` | `string` |  | 搜索关键词 |  |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `status` | `integer(int32)` |  | 状态 |  |

**响应** `统一响应结果«分页结果«联系我们 VO»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«联系我们 VO»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `联系我们 VO[]` |  | 数据列表 |
|     `channelType` | `string` |  | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 |
|     `content` | `string` |  | 富文本内容（关于我们类型使用） |
|     `createdAt` | `string` |  | 创建时间 |
|     `icon` | `string` |  | 图标URL |
|     `id` | `string` |  | 联系方式ID |
|     `sortOrder` | `int` |  | 排序号 |
|     `status` | `int` |  | 状态，关联字典common_status：0=下线, 1=上线 |
|     `subtitle` | `string` |  | 副标题/描述 |
|     `title` | `string` |  | 标题 |
|     `value` | `string` |  | 渠道值 |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/contact

**创建联系方式**

新增一条联系方式记录。

**关联字典**：
- contact_channel_type（联系渠道类型）：请求字段channelType

**请求体** `联系我们请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `channelType` | `string` | 是 | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 |
| `content` | `string` |  | 富文本内容（关于我们类型使用） |
| `icon` | `string` |  | 图标URL |
| `sortOrder` | `int` |  | 排序号（越小越靠前） |
| `status` | `int` |  | 状态，关联字典common_status：0=下线, 1=上线 |
| `subtitle` | `string` |  | 副标题/描述 |
| `title` | `string` | 是 | 标题 |
| `value` | `string` |  | 渠道值（电话号码/客服链接等） |

**响应** `统一响应结果«联系我们 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `联系我们 VO` |  | 响应数据 |
|   `channelType` | `string` |  | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 |
|   `content` | `string` |  | 富文本内容（关于我们类型使用） |
|   `createdAt` | `string` |  | 创建时间 |
|   `icon` | `string` |  | 图标URL |
|   `id` | `string` |  | 联系方式ID |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态，关联字典common_status：0=下线, 1=上线 |
|   `subtitle` | `string` |  | 副标题/描述 |
|   `title` | `string` |  | 标题 |
|   `value` | `string` |  | 渠道值 |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/contact/{id}

**联系方式详情**

获取指定联系方式的详细信息。

**关联字典**：
- contact_channel_type（联系渠道类型）：返回字段channelType
- common_status（通用状态）：返回字段status

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 联系方式ID |

**响应** `统一响应结果«联系我们 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `联系我们 VO` |  | 响应数据 |
|   `channelType` | `string` |  | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 |
|   `content` | `string` |  | 富文本内容（关于我们类型使用） |
|   `createdAt` | `string` |  | 创建时间 |
|   `icon` | `string` |  | 图标URL |
|   `id` | `string` |  | 联系方式ID |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态，关联字典common_status：0=下线, 1=上线 |
|   `subtitle` | `string` |  | 副标题/描述 |
|   `title` | `string` |  | 标题 |
|   `value` | `string` |  | 渠道值 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/contact/{id}

**更新联系方式**

更新指定联系方式记录。

**关联字典**：
- contact_channel_type（联系渠道类型）：请求字段channelType

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 联系方式ID |

**请求体** `联系我们请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `channelType` | `string` | 是 | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 |
| `content` | `string` |  | 富文本内容（关于我们类型使用） |
| `icon` | `string` |  | 图标URL |
| `sortOrder` | `int` |  | 排序号（越小越靠前） |
| `status` | `int` |  | 状态，关联字典common_status：0=下线, 1=上线 |
| `subtitle` | `string` |  | 副标题/描述 |
| `title` | `string` | 是 | 标题 |
| `value` | `string` |  | 渠道值（电话号码/客服链接等） |

**响应** `统一响应结果«联系我们 VO»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `联系我们 VO` |  | 响应数据 |
|   `channelType` | `string` |  | 渠道类型，关联字典contact_channel_type：ABOUT=关于我们, ONLINE_CS=在线客服, PHONE=电话咨询 |
|   `content` | `string` |  | 富文本内容（关于我们类型使用） |
|   `createdAt` | `string` |  | 创建时间 |
|   `icon` | `string` |  | 图标URL |
|   `id` | `string` |  | 联系方式ID |
|   `sortOrder` | `int` |  | 排序号 |
|   `status` | `int` |  | 状态，关联字典common_status：0=下线, 1=上线 |
|   `subtitle` | `string` |  | 副标题/描述 |
|   `title` | `string` |  | 标题 |
|   `value` | `string` |  | 渠道值 |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/contact/{id}

**删除联系方式**

删除指定的联系方式记录（软删除）。

**权限**：需要管理员登录。
**注意**：删除后小程序端将不再展示该联系方式。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `id` | `integer` |  | 联系方式ID |

**响应** `统一响应结果«Void»`

---

## 菜单管理接口

### `POST` /admin/menu

**创建菜单**

创建新的菜单/目录/按钮。menuType取值：DIRECTORY=目录（含子菜单） MENU=页面菜单 BUTTON=操作按钮。目录和菜单需设置path路由路径，菜单还需设置component组件路径。按钮类型需设置permissionCode权限标识（如system:user:add）。需要SUPER_ADMIN角色。

**关联字典**：
- menu_type（菜单类型）：请求/返回字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮）
- common_status（通用状态）：返回字段status

**请求体** `创建菜单请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `component` | `string` |  | 组件路径 |
| `icon` | `string` |  | 菜单图标 |
| `isCache` | `boolean` |  | 是否缓存(true=缓存 false=不缓存) |
| `menuName` | `string` | 是 | 菜单名称 |
| `menuType` | `string` | 是 | 菜单类型：DIRECTORY=目录 MENU=菜单 BUTTON=按钮 |
| `parentId` | `long` |  | 父菜单ID（顶级菜单为空） |
| `path` | `string` |  | 路由路径 |
| `permissionCode` | `string` |  | 权限标识 |
| `sortOrder` | `int` |  | 排序号 |
| `visible` | `boolean` |  | 是否可见 |

**响应** `统一响应结果«SysMenu»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysMenu` |  | 响应数据 |
|   `children` | `SysMenu[]` |  |  |
|     `children` | `SysMenu[]` |  |  |
|     `component` | `string` |  |  |
|     `createdAt` | `string` |  |  |
|     `icon` | `string` |  |  |
|     `isCache` | `boolean` |  |  |
|     `menuId` | `long` |  |  |
|     `menuName` | `string` |  |  |
|     `menuType` | `string` |  |  |
|     `parentId` | `long` |  |  |
|     `path` | `string` |  |  |
|     `permissionCode` | `string` |  |  |
|     `sortOrder` | `int` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|     `visible` | `boolean` |  |  |
|   `component` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `icon` | `string` |  |  |
|   `isCache` | `boolean` |  |  |
|   `menuId` | `long` |  |  |
|   `menuName` | `string` |  |  |
|   `menuType` | `string` |  |  |
|   `parentId` | `long` |  |  |
|   `path` | `string` |  |  |
|   `permissionCode` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `visible` | `boolean` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/menu/my

**获取当前管理员菜单**

获取当前登录管理员的菜单树（基于其当前角色的权限）。SUPER_ADMIN角色返回完整菜单树，其他角色返回已授权的菜单子集。前端登录后调用此接口动态生成路由和侧边栏菜单。需要管理员认证。

**响应** `统一响应结果«List«SysMenu»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysMenu[]` |  | 响应数据 |
|   `children` | `SysMenu[]` |  |  |
|     `children` | `SysMenu[]` |  |  |
|     `component` | `string` |  |  |
|     `createdAt` | `string` |  |  |
|     `icon` | `string` |  |  |
|     `isCache` | `boolean` |  |  |
|     `menuId` | `long` |  |  |
|     `menuName` | `string` |  |  |
|     `menuType` | `string` |  |  |
|     `parentId` | `long` |  |  |
|     `path` | `string` |  |  |
|     `permissionCode` | `string` |  |  |
|     `sortOrder` | `int` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|     `visible` | `boolean` |  |  |
|   `component` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `icon` | `string` |  |  |
|   `isCache` | `boolean` |  |  |
|   `menuId` | `long` |  |  |
|   `menuName` | `string` |  |  |
|   `menuType` | `string` |  |  |
|   `parentId` | `long` |  |  |
|   `path` | `string` |  |  |
|   `permissionCode` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `visible` | `boolean` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/menu/tree

**获取完整菜单树**

获取系统所有菜单的完整树形结构。用于角色权限配置页面展示完整的菜单树供勾选。仅SUPER_ADMIN可查看完整菜单树。需要管理员认证。

**关联字典**：
- menu_type（菜单类型）：返回字段menuType
- common_status（通用状态）：返回字段status

**响应** `统一响应结果«List«SysMenu»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysMenu[]` |  | 响应数据 |
|   `children` | `SysMenu[]` |  |  |
|     `children` | `SysMenu[]` |  |  |
|     `component` | `string` |  |  |
|     `createdAt` | `string` |  |  |
|     `icon` | `string` |  |  |
|     `isCache` | `boolean` |  |  |
|     `menuId` | `long` |  |  |
|     `menuName` | `string` |  |  |
|     `menuType` | `string` |  |  |
|     `parentId` | `long` |  |  |
|     `path` | `string` |  |  |
|     `permissionCode` | `string` |  |  |
|     `sortOrder` | `int` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|     `visible` | `boolean` |  |  |
|   `component` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `icon` | `string` |  |  |
|   `isCache` | `boolean` |  |  |
|   `menuId` | `long` |  |  |
|   `menuName` | `string` |  |  |
|   `menuType` | `string` |  |  |
|   `parentId` | `long` |  |  |
|   `path` | `string` |  |  |
|   `permissionCode` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `visible` | `boolean` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/menu/tree/role/{roleId}

**获取角色菜单树**

获取指定角色已分配的菜单树形结构。
用于角色权限配置页面，展示该角色已拥有的菜单权限。

**权限**：需要管理员登录。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roleId` | `integer` |  | 角色ID |

**响应** `统一响应结果«List«SysMenu»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysMenu[]` |  | 响应数据 |
|   `children` | `SysMenu[]` |  |  |
|     `children` | `SysMenu[]` |  |  |
|     `component` | `string` |  |  |
|     `createdAt` | `string` |  |  |
|     `icon` | `string` |  |  |
|     `isCache` | `boolean` |  |  |
|     `menuId` | `long` |  |  |
|     `menuName` | `string` |  |  |
|     `menuType` | `string` |  |  |
|     `parentId` | `long` |  |  |
|     `path` | `string` |  |  |
|     `permissionCode` | `string` |  |  |
|     `sortOrder` | `int` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|     `visible` | `boolean` |  |  |
|   `component` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `icon` | `string` |  |  |
|   `isCache` | `boolean` |  |  |
|   `menuId` | `long` |  |  |
|   `menuName` | `string` |  |  |
|   `menuType` | `string` |  |  |
|   `parentId` | `long` |  |  |
|   `path` | `string` |  |  |
|   `permissionCode` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `visible` | `boolean` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/menu/{menuId}

**获取菜单详情**

获取指定菜单的详细信息，包括名称、路径、组件、图标、排序、权限标识等。

**权限**：需要管理员登录。

**关联字典**：
- menu_type（菜单类型）：返回字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮）
- common_status（通用状态）：返回字段status

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `menuId` | `integer` |  | 菜单ID |

**响应** `统一响应结果«SysMenu»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysMenu` |  | 响应数据 |
|   `children` | `SysMenu[]` |  |  |
|     `children` | `SysMenu[]` |  |  |
|     `component` | `string` |  |  |
|     `createdAt` | `string` |  |  |
|     `icon` | `string` |  |  |
|     `isCache` | `boolean` |  |  |
|     `menuId` | `long` |  |  |
|     `menuName` | `string` |  |  |
|     `menuType` | `string` |  |  |
|     `parentId` | `long` |  |  |
|     `path` | `string` |  |  |
|     `permissionCode` | `string` |  |  |
|     `sortOrder` | `int` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|     `visible` | `boolean` |  |  |
|   `component` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `icon` | `string` |  |  |
|   `isCache` | `boolean` |  |  |
|   `menuId` | `long` |  |  |
|   `menuName` | `string` |  |  |
|   `menuType` | `string` |  |  |
|   `parentId` | `long` |  |  |
|   `path` | `string` |  |  |
|   `permissionCode` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `visible` | `boolean` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/menu/{menuId}

**更新菜单**

更新指定菜单的名称、路径、组件、图标、排序、状态等信息。

**权限**：需要SUPER_ADMIN角色。
**注意**：修改后需清除 Redis 菜单缓存才能生效。

**关联字典**：
- menu_type（菜单类型）：请求字段menuType（DIRECTORY=目录, MENU=菜单, BUTTON=按钮）
- common_status（通用状态）：请求字段status

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `menuId` | `integer` |  | 菜单ID |

**请求体** `更新菜单请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `component` | `string` |  | 组件路径 |
| `icon` | `string` |  | 菜单图标 |
| `isCache` | `boolean` |  | 是否缓存(true=缓存 false=不缓存) |
| `menuName` | `string` |  | 菜单名称 |
| `menuType` | `string` |  | 菜单类型：DIRECTORY=目录 MENU=菜单 BUTTON=按钮 |
| `parentId` | `long` |  | 父菜单ID |
| `path` | `string` |  | 路由路径 |
| `permissionCode` | `string` |  | 权限标识 |
| `sortOrder` | `int` |  | 排序号 |
| `status` | `string` |  | 状态：ACTIVE=启用 DISABLED=禁用 |
| `visible` | `boolean` |  | 是否可见 |

**响应** `统一响应结果«SysMenu»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysMenu` |  | 响应数据 |
|   `children` | `SysMenu[]` |  |  |
|     `children` | `SysMenu[]` |  |  |
|     `component` | `string` |  |  |
|     `createdAt` | `string` |  |  |
|     `icon` | `string` |  |  |
|     `isCache` | `boolean` |  |  |
|     `menuId` | `long` |  |  |
|     `menuName` | `string` |  |  |
|     `menuType` | `string` |  |  |
|     `parentId` | `long` |  |  |
|     `path` | `string` |  |  |
|     `permissionCode` | `string` |  |  |
|     `sortOrder` | `int` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|     `visible` | `boolean` |  |  |
|   `component` | `string` |  |  |
|   `createdAt` | `string` |  |  |
|   `icon` | `string` |  |  |
|   `isCache` | `boolean` |  |  |
|   `menuId` | `long` |  |  |
|   `menuName` | `string` |  |  |
|   `menuType` | `string` |  |  |
|   `parentId` | `long` |  |  |
|   `path` | `string` |  |  |
|   `permissionCode` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
|   `visible` | `boolean` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/menu/{menuId}

**删除菜单**

删除指定的菜单/目录/按钮（软删除）。

**权限**：需要SUPER_ADMIN角色。
**注意**：如果该菜单有子菜单，需先删除子菜单才能删除父菜单。删除后需清除 Redis 菜单缓存才能生效。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `menuId` | `integer` |  | 菜单ID |

**响应** `统一响应结果«Void»`

---

## 角色管理接口

### `GET` /admin/role

**分页查询角色**

分页查询系统角色列表，支持按状态筛选。

**关联字典**：
- common_status（通用状态）：ACTIVE=启用, DISABLED=禁用（筛选条件+列表展示）


**查询参数**

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `page` | `integer(int32)` |  | 页码 |  |
| `pageSize` | `integer(int32)` |  | 每页条数 |  |
| `status` | `string` |  | 状态 |  |

**响应** `统一响应结果«分页结果«SysRole»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `分页结果«SysRole»` |  | 响应数据 |
|   `page` | `int` |  | 当前页码 |
|   `pageSize` | `int` |  | 每页条数 |
|   `records` | `SysRole[]` |  | 数据列表 |
|     `createdAt` | `string` |  |  |
|     `remark` | `string` |  |  |
|     `roleId` | `long` |  |  |
|     `roleKey` | `string` |  |  |
|     `roleName` | `string` |  |  |
|     `sortOrder` | `int` |  |  |
|     `status` | `string` |  |  |
|     `updatedAt` | `string` |  |  |
|   `total` | `int` |  | 总记录数 |
| `message` | `string` |  | 响应消息 |

---

### `POST` /admin/role

**创建角色**

创建新的系统角色。角色标识（roleKey）全局唯一，创建后不可修改，用于代码中的权限判断。创建后需通过[分配菜单权限]接口为角色授权菜单。需要SUPER_ADMIN角色。

**请求体** `创建角色请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `remark` | `string` |  | 备注 |
| `roleKey` | `string` | 是 | 角色标识 |
| `roleName` | `string` | 是 | 角色名称 |
| `sortOrder` | `int` |  | 排序号 |

**响应** `统一响应结果«SysRole»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysRole` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `remark` | `string` |  |  |
|   `roleId` | `long` |  |  |
|   `roleKey` | `string` |  |  |
|   `roleName` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/role/all

**获取所有角色(下拉)**

获取所有状态正常的角色列表，用于下拉选择框。不分页，返回全部角色。创建管理员、筛选管理员列表时使用。需要管理员认证。

**响应** `统一响应结果«List«SysRole»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysRole[]` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `remark` | `string` |  |  |
|   `roleId` | `long` |  |  |
|   `roleKey` | `string` |  |  |
|   `roleName` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `GET` /admin/role/{roleId}

**获取角色详情(含菜单ID)**

获取角色基本信息及其已分配的菜单ID列表。返回role对象和menuIds数组，用于角色编辑页面回显已勾选的菜单。需要管理员认证。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roleId` | `integer` |  | 角色ID |

**响应** `统一响应结果«Map«string,object»»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `object` |  | 响应数据 |
| `message` | `string` |  | 响应消息 |

---

### `PUT` /admin/role/{roleId}

**更新角色**

更新角色名称、状态等信息。角色标识（roleKey）不可修改。

**关联字典**：
- common_status（通用状态）：ACTIVE=启用, DISABLED=禁用


**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roleId` | `integer` |  | 角色ID |

**请求体** `更新角色请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `remark` | `string` |  | 备注 |
| `roleName` | `string` |  | 角色名称 |
| `sortOrder` | `int` |  | 排序号 |
| `status` | `string` |  | 状态：ACTIVE=启用 DISABLED=禁用 |

**响应** `统一响应结果«SysRole»`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | `int` |  | 状态码 |
| `data` | `SysRole` |  | 响应数据 |
|   `createdAt` | `string` |  |  |
|   `remark` | `string` |  |  |
|   `roleId` | `long` |  |  |
|   `roleKey` | `string` |  |  |
|   `roleName` | `string` |  |  |
|   `sortOrder` | `int` |  |  |
|   `status` | `string` |  |  |
|   `updatedAt` | `string` |  |  |
| `message` | `string` |  | 响应消息 |

---

### `DELETE` /admin/role/{roleId}

**删除角色**

删除指定角色（软删除）。如果该角色下还有关联的管理员，将无法删除，需先解除绑定关系。内置角色（SUPER_ADMIN等）不可删除。需要SUPER_ADMIN角色。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roleId` | `integer` |  | 角色ID |

**响应** `统一响应结果«Void»`

---

### `PUT` /admin/role/{roleId}/menus

**分配菜单权限**

为指定角色分配菜单权限（全量覆盖模式）。传入的menuIds将完全替换该角色原有的菜单权限。分配后该角色的所有在线管理员下次请求 /admin/menu/my 时会获取到新的菜单树。注意：需同步清除Redis中的菜单缓存，否则前端拿到的是旧菜单。需要SUPER_ADMIN角色。

**路径参数**

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roleId` | `integer` |  | 角色ID |

**请求体** `分配菜单权限请求`

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `menuIds` | `long[]` | 是 | 菜单ID列表 |

**响应** `统一响应结果«Void»`

---