hl-api-changelog/2026-03/17_0928/hl-user-service.md

用户服务 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»

---