docs: 管理端首页工作台模块完整前端对接指南（6角色×6接口）
这个提交包含在：
API Changelog Bot
父节点
245cb6b13c
当前提交
5ed6bd8883
@ -0,0 +1,853 @@
|
|||||||
|
# 管理端首页工作台模块 - 前端对接指南
|
||||||
|
|
||||||
|
> **日期**: 2026-03-18
|
||||||
|
> **后端状态**: ✅ 已完成，可直接对接
|
||||||
|
> **页面路由**: `/dashboard`（首页工作台）
|
||||||
|
> **核心特性**: 同一个接口，按登录角色自动返回不同的工作台数据
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 页面功能说明
|
||||||
|
|
||||||
|
管理端首页工作台根据当前登录管理员的**角色**自动展示不同内容。前端只需调用同一个接口 `GET /admin/profile/dashboard`，后端根据角色路由到对应的工作台数据。
|
||||||
|
|
||||||
|
**支持的角色及工作台类型**：
|
||||||
|
|
||||||
|
| 角色 role_key | 角色中文名 | 工作台类型 | 数据特点 |
|
||||||
|
|---------------|-----------|-----------|---------|
|
||||||
|
| `SUPER_ADMIN` | 超级管理员 | 全局管理台 | 全平台数据概览 + 团队排行 + 用户/产品统计 |
|
||||||
|
| `ADMIN` | 管理员 | 全局管理台 | 同超级管理员 |
|
||||||
|
| `CUSTOMIZER` | 定制师 | 个人工作台 | 个人业绩 + 转化漏斗 + 快捷入口 + 评价/客户/产品统计 |
|
||||||
|
| `ROOM_MANAGER` | 房务管理员 | 房务工作台 | 酒店/房型统计 + 待安排住宿 + 即将入住 |
|
||||||
|
| `VEHICLE_MANAGER` | 车务管理员 | 车务工作台 | 车辆/车型统计 + 待安排车辆 + 即将用车 |
|
||||||
|
| `FINANCE` | 财务 | 财务工作台 | 收支概览 + 退款待审 + 尾款逾期 + 收支趋势 |
|
||||||
|
| `MATERIAL_ADMIN` | 素材管理员 | 素材工作台 | 素材统计 + 分类分布 |
|
||||||
|
| 其他角色 | — | 全局管理台 | 降级使用管理员工作台 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 接口清单
|
||||||
|
|
||||||
|
| # | 接口 | 方法 | 路径 | 说明 |
|
||||||
|
|---|------|------|------|------|
|
||||||
|
| 1 | 工作台仪表盘 | GET | `/admin/profile/dashboard` | **核心接口**，按角色返回不同数据结构 |
|
||||||
|
| 2 | 获取个人资料 | GET | `/admin/profile/me` | 工作台顶部展示用户信息 |
|
||||||
|
| 3 | 更新个人资料 | PUT | `/admin/profile/me` | 定制师编辑个人简介等 |
|
||||||
|
| 4 | 我的评价列表 | GET | `/admin/profile/reviews` | 定制师查看收到的评价（分页） |
|
||||||
|
| 5 | 我的订单列表 | GET | `/admin/profile/orders` | 定制师查看关联订单（分页） |
|
||||||
|
| 6 | 我的产品列表 | GET | `/admin/profile/products` | 定制师查看关联产品（分页） |
|
||||||
|
|
||||||
|
> 所有接口都需要管理员登录认证（Header 传 `Authorization: Bearer {token}`）。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 接口 1：工作台仪表盘（核心接口）
|
||||||
|
|
||||||
|
**使用场景**：首页加载时调用，后端自动根据登录角色返回对应数据结构。前端根据返回的数据结构渲染不同的工作台布局。
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /admin/profile/dashboard?period=today
|
||||||
|
```
|
||||||
|
|
||||||
|
### 请求参数
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| period | String | 否 | 时间范围，默认 `today`。可选值：`today`=今日、`week`=本周、`month`=本月 |
|
||||||
|
|
||||||
|
> **前端判断角色**：调用 接口2 `GET /admin/profile/me` 获取 `role` 字段，用于决定渲染哪种工作台布局。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1A. 超级管理员/管理员工作台（SUPER_ADMIN / ADMIN）
|
||||||
|
|
||||||
|
**返回类型**: `AdminDashboardVO`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"overview": {
|
||||||
|
"orderCount": 15,
|
||||||
|
"orderCountDiff": 3,
|
||||||
|
"orderCountDiffRate": 0.25,
|
||||||
|
"gmv": 128000.00,
|
||||||
|
"gmvDiffRate": 0.18,
|
||||||
|
"newUserCount": 42,
|
||||||
|
"newUserCountDiffRate": 0.15,
|
||||||
|
"visitorCount": 380,
|
||||||
|
"visitorCountDiffRate": -0.05,
|
||||||
|
"period": "today"
|
||||||
|
},
|
||||||
|
"todos": {
|
||||||
|
"totalActive": 8,
|
||||||
|
"CONFIRM_ORDER": 3,
|
||||||
|
"INSURANCE": 1,
|
||||||
|
"CONTRACT": 2,
|
||||||
|
"ARRANGE_ROOM": 1,
|
||||||
|
"ARRANGE_VEHICLE": 1,
|
||||||
|
"CONFIRM_CHECKLIST": 0,
|
||||||
|
"PROCESS_REFUND": 0,
|
||||||
|
"pendingRefund": 2,
|
||||||
|
"upcomingDeparture": 5,
|
||||||
|
"overdueBalance": 1
|
||||||
|
},
|
||||||
|
"trend": [
|
||||||
|
{ "date": "2026-03-12", "orderCount": 10, "gmv": 85000.00 },
|
||||||
|
{ "date": "2026-03-13", "orderCount": 8, "gmv": 62000.00 }
|
||||||
|
],
|
||||||
|
"ranking": [
|
||||||
|
{ "customizerId": "2025607151170445301", "customizerName": "李明", "gmv": 320000.00, "orderCount": 28 },
|
||||||
|
{ "customizerId": "2025607151170445302", "customizerName": "张丽", "gmv": 285000.00, "orderCount": 22 }
|
||||||
|
],
|
||||||
|
"upcomingTrips": [
|
||||||
|
{
|
||||||
|
"orderId": "2025607151170445401",
|
||||||
|
"orderNo": "HL20260318001",
|
||||||
|
"departureDate": "2026-03-20",
|
||||||
|
"productName": "呼伦贝尔5日深度游",
|
||||||
|
"headcount": 4,
|
||||||
|
"status": "PAID",
|
||||||
|
"statusLabel": "已全额支付"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"totalMiniAppUsers": 1580,
|
||||||
|
"totalAdmins": 12,
|
||||||
|
"totalProducts": 45,
|
||||||
|
"publishedProducts": 28
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 响应字段
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| **overview** | Object | 数据概览卡片 |
|
||||||
|
| overview.orderCount | Long | 当期订单数 |
|
||||||
|
| overview.orderCountDiff | Long | 与前一期订单数差值（正=增长，负=下降） |
|
||||||
|
| overview.orderCountDiffRate | BigDecimal | 订单数环比增长率（小数，0.25=25%） |
|
||||||
|
| overview.gmv | BigDecimal | 当期GMV（成交金额，元） |
|
||||||
|
| overview.gmvDiffRate | BigDecimal | GMV环比增长率 |
|
||||||
|
| overview.newUserCount | Long | 当期新增C端用户数 |
|
||||||
|
| overview.newUserCountDiffRate | BigDecimal | 新增用户环比增长率 |
|
||||||
|
| overview.visitorCount | Long | 当期活跃C端用户数 |
|
||||||
|
| overview.visitorCountDiffRate | BigDecimal | 活跃用户环比增长率 |
|
||||||
|
| overview.period | String | 当前时间范围（today/week/month） |
|
||||||
|
| **todos** | Map | 待办汇总（key→数量） |
|
||||||
|
| todos.totalActive | Integer | 活跃待办总数 |
|
||||||
|
| todos.CONFIRM_ORDER | Integer | 待确认订单数 |
|
||||||
|
| todos.INSURANCE | Integer | 待配置保险数 |
|
||||||
|
| todos.CONTRACT | Integer | 待签合同数 |
|
||||||
|
| todos.ARRANGE_ROOM | Integer | 待安排住宿数 |
|
||||||
|
| todos.ARRANGE_VEHICLE | Integer | 待安排车辆数 |
|
||||||
|
| todos.CONFIRM_CHECKLIST | Integer | 待确认清单数 |
|
||||||
|
| todos.PROCESS_REFUND | Integer | 待处理退款数 |
|
||||||
|
| todos.pendingRefund | Integer | 退款审核待处理 |
|
||||||
|
| todos.upcomingDeparture | Integer | 即将出发订单数 |
|
||||||
|
| todos.overdueBalance | Integer | 尾款逾期数 |
|
||||||
|
| **trend** | List | 数据趋势（默认7天，每天一条） |
|
||||||
|
| trend[].date | String | 日期（yyyy-MM-dd） |
|
||||||
|
| trend[].orderCount | Integer | 当日订单数 |
|
||||||
|
| trend[].gmv | BigDecimal | 当日GMV |
|
||||||
|
| **ranking** | List | 定制师业绩排行（当月） |
|
||||||
|
| ranking[].customizerId | String | 定制师ID（雪花ID字符串） |
|
||||||
|
| ranking[].customizerName | String | 定制师姓名 |
|
||||||
|
| ranking[].gmv | BigDecimal | 当月GMV |
|
||||||
|
| ranking[].orderCount | Integer | 当月订单数 |
|
||||||
|
| **upcomingTrips** | List | 即将出行列表（最多5条） |
|
||||||
|
| upcomingTrips[].orderId | String | 订单ID |
|
||||||
|
| upcomingTrips[].orderNo | String | 订单编号 |
|
||||||
|
| upcomingTrips[].departureDate | String | 出发日期（yyyy-MM-dd） |
|
||||||
|
| upcomingTrips[].productName | String | 产品名称 |
|
||||||
|
| upcomingTrips[].headcount | Integer | 出行人数 |
|
||||||
|
| upcomingTrips[].status | String | 订单状态（关联字典 `order_status`） |
|
||||||
|
| upcomingTrips[].statusLabel | String | 订单状态中文 |
|
||||||
|
| **totalMiniAppUsers** | Integer | C端小程序用户总数 |
|
||||||
|
| **totalAdmins** | Integer | 管理员总数 |
|
||||||
|
| **totalProducts** | Integer | 全局产品总数 |
|
||||||
|
| **publishedProducts** | Integer | 已上架产品数 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1B. 定制师工作台（CUSTOMIZER）
|
||||||
|
|
||||||
|
**返回类型**: `DesignerDashboardVO`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"overview": {
|
||||||
|
"orderCount": 5,
|
||||||
|
"orderCountDiff": 2,
|
||||||
|
"gmv": 45000.00,
|
||||||
|
"gmvDiffRate": 0.30,
|
||||||
|
"period": "today"
|
||||||
|
},
|
||||||
|
"todos": {
|
||||||
|
"totalActive": 4,
|
||||||
|
"CONFIRM_ORDER": 2,
|
||||||
|
"INSURANCE": 1,
|
||||||
|
"CONTRACT": 1,
|
||||||
|
"ARRANGE_ROOM": 0,
|
||||||
|
"ARRANGE_VEHICLE": 0,
|
||||||
|
"CONFIRM_CHECKLIST": 0,
|
||||||
|
"PROCESS_REFUND": 0,
|
||||||
|
"pendingRefund": 1,
|
||||||
|
"upcomingDeparture": 3,
|
||||||
|
"overdueBalance": 0
|
||||||
|
},
|
||||||
|
"shortcuts": [
|
||||||
|
{ "name": "新建产品", "icon": "product-add", "path": "/product/create" },
|
||||||
|
{ "name": "我的订单", "icon": "order", "path": "/admin/profile/orders" },
|
||||||
|
{ "name": "我的评价", "icon": "review", "path": "/admin/profile/reviews" },
|
||||||
|
{ "name": "素材库", "icon": "material", "path": "/material/list" }
|
||||||
|
],
|
||||||
|
"trend": [
|
||||||
|
{ "date": "2026-03-12", "orderCount": 3, "gmv": 28000.00 },
|
||||||
|
{ "date": "2026-03-13", "orderCount": 2, "gmv": 18000.00 }
|
||||||
|
],
|
||||||
|
"funnel": {
|
||||||
|
"ordered": 20,
|
||||||
|
"paid": 16,
|
||||||
|
"departed": 12,
|
||||||
|
"completed": 10
|
||||||
|
},
|
||||||
|
"upcomingTrips": [
|
||||||
|
{
|
||||||
|
"orderId": "2025607151170445401",
|
||||||
|
"orderNo": "HL20260318001",
|
||||||
|
"departureDate": "2026-03-20",
|
||||||
|
"productName": "呼伦贝尔5日深度游",
|
||||||
|
"headcount": 4,
|
||||||
|
"status": "PAID",
|
||||||
|
"statusLabel": "已全额支付"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"ranking": [
|
||||||
|
{ "customizerId": "2025607151170445301", "customizerName": "李明", "gmv": 320000.00, "orderCount": 28 }
|
||||||
|
],
|
||||||
|
"calendarEvents": [
|
||||||
|
{ "date": "2026-03-20", "type": "departure", "label": "出团", "count": 2 },
|
||||||
|
{ "date": "2026-03-25", "type": "return", "label": "回程", "count": 1 }
|
||||||
|
],
|
||||||
|
"reviewStats": {
|
||||||
|
"totalReviews": 86,
|
||||||
|
"averageRating": 4.7,
|
||||||
|
"goodRate": 92.5
|
||||||
|
},
|
||||||
|
"productStats": {
|
||||||
|
"totalProducts": 12,
|
||||||
|
"publishedProducts": 8
|
||||||
|
},
|
||||||
|
"customerStats": {
|
||||||
|
"customerAddCount": 5,
|
||||||
|
"customerLossCount": 1
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 响应字段
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| **overview** | Object | 个人数据概览 |
|
||||||
|
| overview.orderCount | Long | 我的当期订单数 |
|
||||||
|
| overview.orderCountDiff | Long | 与前一期差值 |
|
||||||
|
| overview.gmv | BigDecimal | 我的当期GMV（元） |
|
||||||
|
| overview.gmvDiffRate | BigDecimal | GMV环比增长率 |
|
||||||
|
| overview.period | String | 当前时间范围 |
|
||||||
|
| **todos** | Map | 我的待办汇总（结构同管理员，但数据只包含自己的） |
|
||||||
|
| **shortcuts** | List | 快捷入口列表 |
|
||||||
|
| shortcuts[].name | String | 入口名称（中文） |
|
||||||
|
| shortcuts[].icon | String | 图标标识（前端自行映射图标组件） |
|
||||||
|
| shortcuts[].path | String | 跳转路径 |
|
||||||
|
| **trend** | List | 我的数据趋势（7天） |
|
||||||
|
| trend[].date | String | 日期 |
|
||||||
|
| trend[].orderCount | Integer | 当日订单数 |
|
||||||
|
| trend[].gmv | BigDecimal | 当日GMV |
|
||||||
|
| **funnel** | Map | 转化漏斗（当月） |
|
||||||
|
| funnel.ordered | Integer | 下单数 |
|
||||||
|
| funnel.paid | Integer | 已支付数 |
|
||||||
|
| funnel.departed | Integer | 已出行数（含TRAVELLING+COMPLETED） |
|
||||||
|
| funnel.completed | Integer | 已完成数 |
|
||||||
|
| **upcomingTrips** | List | 我的即将出行（最多5条，结构同管理员） |
|
||||||
|
| **ranking** | List | 月度业绩排行（含自己的排名，用于自我定位） |
|
||||||
|
| **calendarEvents** | List | 日历事件（当月出团/回程事件） |
|
||||||
|
| calendarEvents[].date | String | 事件日期 |
|
||||||
|
| calendarEvents[].type | String | 事件类型（departure=出团, return=回程） |
|
||||||
|
| calendarEvents[].label | String | 事件中文标签 |
|
||||||
|
| calendarEvents[].count | Integer | 当日事件数量 |
|
||||||
|
| **reviewStats** | Object | 评价统计 |
|
||||||
|
| reviewStats.totalReviews | Integer | 评价总数 |
|
||||||
|
| reviewStats.averageRating | BigDecimal | 平均评分（1.0~5.0） |
|
||||||
|
| reviewStats.goodRate | BigDecimal | 好评率（百分比，如92.5=92.5%） |
|
||||||
|
| **productStats** | Object | 产品统计 |
|
||||||
|
| productStats.totalProducts | Integer | 我的产品总数 |
|
||||||
|
| productStats.publishedProducts | Integer | 已上架产品数 |
|
||||||
|
| **customerStats** | Object | 客户统计 |
|
||||||
|
| customerStats.customerAddCount | Integer | 新增客户数 |
|
||||||
|
| customerStats.customerLossCount | Integer | 流失客户数 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1C. 房务管理员工作台（ROOM_MANAGER）
|
||||||
|
|
||||||
|
**返回类型**: `HousekeepingDashboardVO`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"totalHotels": 8,
|
||||||
|
"totalRoomTypes": 24,
|
||||||
|
"pendingArrangeRoom": 3,
|
||||||
|
"upcomingTrips": [
|
||||||
|
{
|
||||||
|
"orderId": "2025607151170445401",
|
||||||
|
"orderNo": "HL20260318001",
|
||||||
|
"departureDate": "2026-03-20",
|
||||||
|
"productName": "呼伦贝尔5日深度游",
|
||||||
|
"headcount": 4,
|
||||||
|
"status": "PAID",
|
||||||
|
"statusLabel": "已全额支付"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 响应字段
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| totalHotels | Integer | 酒店总数 |
|
||||||
|
| totalRoomTypes | Integer | 房型总数 |
|
||||||
|
| pendingArrangeRoom | Integer | 待安排住宿的订单数（红色角标提醒） |
|
||||||
|
| upcomingTrips | List | 近7天即将入住的订单列表（结构同管理员的upcomingTrips） |
|
||||||
|
|
||||||
|
> **注意**：`period` 参数对房务工作台无效，数据始终为全局统计。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1D. 车务管理员工作台（VEHICLE_MANAGER）
|
||||||
|
|
||||||
|
**返回类型**: `LogisticsDashboardVO`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"totalVehicles": 15,
|
||||||
|
"totalVehicleModels": 6,
|
||||||
|
"pendingArrangeVehicle": 2,
|
||||||
|
"upcomingTrips": [
|
||||||
|
{
|
||||||
|
"orderId": "2025607151170445401",
|
||||||
|
"orderNo": "HL20260318001",
|
||||||
|
"departureDate": "2026-03-20",
|
||||||
|
"productName": "呼伦贝尔5日深度游",
|
||||||
|
"headcount": 4,
|
||||||
|
"status": "PAID",
|
||||||
|
"statusLabel": "已全额支付"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 响应字段
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| totalVehicles | Integer | 车辆总数 |
|
||||||
|
| totalVehicleModels | Integer | 车型总数 |
|
||||||
|
| pendingArrangeVehicle | Integer | 待安排车辆的订单数（红色角标提醒） |
|
||||||
|
| upcomingTrips | List | 近7天即将用车的订单列表（结构同管理员的upcomingTrips） |
|
||||||
|
|
||||||
|
> **注意**：`period` 参数对车务工作台无效。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1E. 财务工作台（FINANCE）
|
||||||
|
|
||||||
|
**返回类型**: `FinanceDashboardVO`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"periodIncome": 128000.00,
|
||||||
|
"periodRefund": 5600.00,
|
||||||
|
"monthIncome": 890000.00,
|
||||||
|
"monthRefund": 32000.00,
|
||||||
|
"pendingRefundCount": 3,
|
||||||
|
"overdueBalanceCount": 2,
|
||||||
|
"trend": [
|
||||||
|
{ "date": "2026-02-17", "income": 35000.00, "refund": 2000.00 },
|
||||||
|
{ "date": "2026-02-18", "income": 42000.00, "refund": 1500.00 }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 响应字段
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| periodIncome | BigDecimal | 当期收入（元，受period参数影响） |
|
||||||
|
| periodRefund | BigDecimal | 当期退款（元） |
|
||||||
|
| monthIncome | BigDecimal | 本月总收入（始终为本月） |
|
||||||
|
| monthRefund | BigDecimal | 本月总退款 |
|
||||||
|
| pendingRefundCount | Integer | 待审核退款申请数（红色角标） |
|
||||||
|
| overdueBalanceCount | Integer | 尾款逾期提醒数（红色角标） |
|
||||||
|
| trend | List | 收支趋势（30天，每天一条） |
|
||||||
|
| trend[].date | String | 日期 |
|
||||||
|
| trend[].income | BigDecimal | 当日收入 |
|
||||||
|
| trend[].refund | BigDecimal | 当日退款 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 1F. 素材管理员工作台（MATERIAL_ADMIN）
|
||||||
|
|
||||||
|
**返回类型**: `MaterialDashboardVO`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"totalMaterials": 1280,
|
||||||
|
"monthNewCount": 56,
|
||||||
|
"totalRefCount": 3420,
|
||||||
|
"categoryCount": 12,
|
||||||
|
"categoryDistribution": [
|
||||||
|
{ "categoryName": "风景照片", "count": 450 },
|
||||||
|
{ "categoryName": "酒店图片", "count": 320 },
|
||||||
|
{ "categoryName": "活动素材", "count": 280 }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 响应字段
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| totalMaterials | Integer | 素材总数 |
|
||||||
|
| monthNewCount | Integer | 本月新增素材数 |
|
||||||
|
| totalRefCount | Integer | 素材总引用次数 |
|
||||||
|
| categoryCount | Integer | 素材分类总数 |
|
||||||
|
| categoryDistribution | List | 各分类素材数量分布 |
|
||||||
|
| categoryDistribution[].categoryName | String | 分类名称 |
|
||||||
|
| categoryDistribution[].count | Integer | 该分类下素材数量 |
|
||||||
|
|
||||||
|
> **注意**：`period` 参数对素材工作台无效。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 接口 2：获取个人资料
|
||||||
|
|
||||||
|
**使用场景**：页面加载时获取当前用户信息，用于工作台顶部展示姓名/头像，以及判断角色决定渲染哪种工作台。
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /admin/profile/me
|
||||||
|
```
|
||||||
|
|
||||||
|
### 请求参数
|
||||||
|
|
||||||
|
无（从登录Token中自动获取）。
|
||||||
|
|
||||||
|
### 响应示例
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"adminId": "2025607151170445301",
|
||||||
|
"role": "CUSTOMIZER",
|
||||||
|
"roleName": "定制师",
|
||||||
|
"name": "李明",
|
||||||
|
"avatar": "https://oss.example.com/avatar/liming.jpg",
|
||||||
|
"phone": "13800138001",
|
||||||
|
"contactQrUrl": "https://work.weixin.qq.com/qr/xxx",
|
||||||
|
"description": "10年+呼伦贝尔定制旅行专家",
|
||||||
|
"motto": "让每一次旅行都值得回忆",
|
||||||
|
"experience": 10,
|
||||||
|
"certLevel": "gold",
|
||||||
|
"certified": true,
|
||||||
|
"specialties": ["亲子游", "深度游", "摄影游"],
|
||||||
|
"serviceAreas": ["呼伦贝尔", "阿尔山", "漠河"],
|
||||||
|
"sortOrder": 1,
|
||||||
|
"isFeatured": true,
|
||||||
|
"createdAt": "2025-06-01T10:00:00",
|
||||||
|
"updatedAt": "2026-03-15T14:30:00"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 响应字段
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| adminId | String | 管理员ID（雪花ID字符串） |
|
||||||
|
| role | String | 角色标识，见下方角色枚举 |
|
||||||
|
| roleName | String | 角色中文名 |
|
||||||
|
| name | String | 姓名 |
|
||||||
|
| avatar | String | 头像URL，可能为null |
|
||||||
|
| phone | String | 手机号，可能为null |
|
||||||
|
| contactQrUrl | String | 企微联系二维码URL，可能为null |
|
||||||
|
| description | String | 个人简介（**仅定制师有值**，其他角色为null） |
|
||||||
|
| motto | String | 座右铭（仅定制师） |
|
||||||
|
| experience | Integer | 从业年限（仅定制师） |
|
||||||
|
| certLevel | String | 认证等级（仅定制师）：none/bronze/silver/gold/diamond |
|
||||||
|
| certified | Boolean | 是否已认证（仅定制师） |
|
||||||
|
| specialties | List\<String\> | 擅长领域（仅定制师），如 ["亲子游","深度游"] |
|
||||||
|
| serviceAreas | List\<String\> | 服务区域（仅定制师），如 ["呼伦贝尔","阿尔山"] |
|
||||||
|
| sortOrder | Integer | 展示排序（仅定制师） |
|
||||||
|
| isFeatured | Boolean | 是否推荐定制师（仅定制师） |
|
||||||
|
| createdAt | String | 创建时间（ISO 8601） |
|
||||||
|
| updatedAt | String | 更新时间（ISO 8601） |
|
||||||
|
|
||||||
|
### 前端实现建议
|
||||||
|
- 页面加载时先调此接口，拿到 `role` 后再调 `dashboard` 接口
|
||||||
|
- 用 `role` 判断渲染哪种工作台布局（switch-case）
|
||||||
|
- 顶部显示 `name` + `avatar` + `roleName`
|
||||||
|
- 定制师额外展示认证徽章（根据 `certLevel`）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 接口 3：更新个人资料
|
||||||
|
|
||||||
|
**使用场景**：定制师编辑个人简介、擅长领域等信息。
|
||||||
|
|
||||||
|
```
|
||||||
|
PUT /admin/profile/me
|
||||||
|
Content-Type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
### 请求参数
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"description": "10年+呼伦贝尔定制旅行专家",
|
||||||
|
"motto": "让每一次旅行都值得回忆",
|
||||||
|
"experience": 10,
|
||||||
|
"certLevel": "gold",
|
||||||
|
"certified": true,
|
||||||
|
"specialties": ["亲子游", "深度游", "摄影游"],
|
||||||
|
"serviceAreas": ["呼伦贝尔", "阿尔山", "漠河"],
|
||||||
|
"sortOrder": 1,
|
||||||
|
"isFeatured": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| description | String | 否 | 个人简介，最多500字 |
|
||||||
|
| motto | String | 否 | 座右铭，最多200字 |
|
||||||
|
| experience | Integer | 否 | 从业年限（0~99） |
|
||||||
|
| certLevel | String | 否 | 认证等级：none/bronze/silver/gold/diamond |
|
||||||
|
| certified | Boolean | 否 | 是否已认证 |
|
||||||
|
| specialties | List\<String\> | 否 | 擅长领域列表 |
|
||||||
|
| serviceAreas | List\<String\> | 否 | 服务区域列表 |
|
||||||
|
| sortOrder | Integer | 否 | 展示排序（最小0） |
|
||||||
|
| isFeatured | Boolean | 否 | 是否推荐 |
|
||||||
|
|
||||||
|
### 响应
|
||||||
|
|
||||||
|
返回更新后的 `ProfileVO`，结构同接口2。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 接口 4：我的评价列表
|
||||||
|
|
||||||
|
**使用场景**：定制师查看客户对自己的评价，支持按好评/中评/差评筛选。
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /admin/profile/reviews?page=1&pageSize=20&ratingLevel=GOOD
|
||||||
|
```
|
||||||
|
|
||||||
|
### 请求参数
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| page | Integer | 否 | 页码，默认1 |
|
||||||
|
| pageSize | Integer | 否 | 每页条数，默认20 |
|
||||||
|
| ratingLevel | String | 否 | 评价等级筛选，见下方枚举 |
|
||||||
|
|
||||||
|
### 评价等级枚举（ratingLevel）— 关联字典 `rating_level`
|
||||||
|
|
||||||
|
| 值 | 中文 | 说明 |
|
||||||
|
|----|------|------|
|
||||||
|
| `GOOD` | 好评 | 4~5星 |
|
||||||
|
| `MEDIUM` | 中评 | 3星 |
|
||||||
|
| `BAD` | 差评 | 1~2星 |
|
||||||
|
|
||||||
|
### 响应示例
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"list": [
|
||||||
|
{
|
||||||
|
"reviewId": "2025607151170445501",
|
||||||
|
"orderId": "2025607151170445401",
|
||||||
|
"orderNo": "HL20260318001",
|
||||||
|
"productName": "呼伦贝尔5日深度游",
|
||||||
|
"userName": "张三",
|
||||||
|
"userAvatar": "https://oss.example.com/avatar/user1.jpg",
|
||||||
|
"rating": 5,
|
||||||
|
"ratingLevel": "GOOD",
|
||||||
|
"content": "定制师很专业，行程安排非常合理！",
|
||||||
|
"createdAt": "2026-03-16T14:00:00"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 86,
|
||||||
|
"page": 1,
|
||||||
|
"pageSize": 20
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 接口 5：我的订单列表
|
||||||
|
|
||||||
|
**使用场景**：定制师查看自己负责的订单，支持按状态筛选和关键词搜索。
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /admin/profile/orders?page=1&pageSize=20&status=PAID&keyword=呼伦贝尔
|
||||||
|
```
|
||||||
|
|
||||||
|
### 请求参数
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| page | Integer | 否 | 页码，默认1 |
|
||||||
|
| pageSize | Integer | 否 | 每页条数，默认20 |
|
||||||
|
| status | String | 否 | 订单状态筛选，见下方枚举 |
|
||||||
|
| keyword | String | 否 | 搜索关键词（匹配订单号、产品名、联系人名） |
|
||||||
|
|
||||||
|
### 订单状态枚举（status）— 关联字典 `order_status`
|
||||||
|
|
||||||
|
| 值 | 中文 | 说明 |
|
||||||
|
|----|------|------|
|
||||||
|
| `PENDING_PAY` | 待支付 | 订单已创建，等待支付 |
|
||||||
|
| `DEPOSIT_PAID` | 已付定金 | 已支付定金 |
|
||||||
|
| `PAID` | 已全额支付 | 全额支付完成 |
|
||||||
|
| `CONFIRMED` | 已确认 | 订单已确认 |
|
||||||
|
| `PENDING_BALANCE` | 待付尾款 | 等待支付尾款 |
|
||||||
|
| `PENDING_DEPARTURE` | 待出行 | 一切就绪，等待出发 |
|
||||||
|
| `TRAVELLING` | 旅行中 | 正在旅行 |
|
||||||
|
| `COMPLETED` | 已完成 | 行程结束 |
|
||||||
|
| `AFTER_SALES` | 售后中 | 售后处理中 |
|
||||||
|
| `CANCELLED` | 已取消 | 订单已取消 |
|
||||||
|
| `REFUNDING` | 退款中 | 退款处理中 |
|
||||||
|
| `REFUNDED` | 已退款 | 退款完成 |
|
||||||
|
|
||||||
|
### 响应示例
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"list": [
|
||||||
|
{
|
||||||
|
"orderId": "2025607151170445401",
|
||||||
|
"orderNo": "HL20260318001",
|
||||||
|
"productName": "呼伦贝尔5日深度游",
|
||||||
|
"contactName": "张三",
|
||||||
|
"contactPhone": "13800138000",
|
||||||
|
"headcount": 4,
|
||||||
|
"totalAmount": 12800.00,
|
||||||
|
"status": "PAID",
|
||||||
|
"statusLabel": "已全额支付",
|
||||||
|
"departureDate": "2026-03-20",
|
||||||
|
"createdAt": "2026-03-10T10:00:00"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 28,
|
||||||
|
"page": 1,
|
||||||
|
"pageSize": 20
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 接口 6：我的产品列表
|
||||||
|
|
||||||
|
**使用场景**：定制师查看自己创建的产品，支持按状态筛选和关键词搜索。
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /admin/profile/products?page=1&pageSize=20&status=PUBLISHED&keyword=呼伦贝尔
|
||||||
|
```
|
||||||
|
|
||||||
|
### 请求参数
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 说明 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| page | Integer | 否 | 页码，默认1 |
|
||||||
|
| pageSize | Integer | 否 | 每页条数，默认20 |
|
||||||
|
| status | String | 否 | 产品状态筛选，见下方枚举 |
|
||||||
|
| keyword | String | 否 | 搜索关键词（匹配产品名称） |
|
||||||
|
|
||||||
|
### 产品状态枚举（status）— 关联字典 `product_status`
|
||||||
|
|
||||||
|
| 值 | 中文 | 说明 |
|
||||||
|
|----|------|------|
|
||||||
|
| `DRAFT` | 草稿 | 未提交 |
|
||||||
|
| `PENDING_REVIEW` | 待审核 | 已提交审核 |
|
||||||
|
| `REVIEWED` | 已审核 | 审核通过 |
|
||||||
|
| `REJECTED` | 已驳回 | 审核驳回 |
|
||||||
|
| `PUBLISHED` | 已上架 | 小程序可见 |
|
||||||
|
| `UNPUBLISHED` | 已下架 | 已下架 |
|
||||||
|
| `COMPLETED` | 已完成 | 产品周期结束 |
|
||||||
|
|
||||||
|
### 响应示例
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "成功",
|
||||||
|
"data": {
|
||||||
|
"list": [
|
||||||
|
{
|
||||||
|
"productId": "2025607151170445601",
|
||||||
|
"productName": "呼伦贝尔5日深度游",
|
||||||
|
"status": "PUBLISHED",
|
||||||
|
"statusLabel": "已上架",
|
||||||
|
"coverImage": "https://oss.example.com/product/cover1.jpg",
|
||||||
|
"priceRange": "3200-4800",
|
||||||
|
"orderCount": 15,
|
||||||
|
"createdAt": "2026-02-01T10:00:00"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"total": 12,
|
||||||
|
"page": 1,
|
||||||
|
"pageSize": 20
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 待办类型枚举 — 关联字典 `order_todo_type`
|
||||||
|
|
||||||
|
| 值 | 中文 | 适用角色 | 说明 |
|
||||||
|
|----|------|----------|------|
|
||||||
|
| `CONFIRM_ORDER` | 确认订单 | 定制师/管理员 | 新订单需确认 |
|
||||||
|
| `INSURANCE` | 配置保险 | 定制师/管理员 | 需为订单配置保险 |
|
||||||
|
| `CONTRACT` | 签订合同 | 定制师/管理员 | 合同待签署 |
|
||||||
|
| `ARRANGE_ROOM` | 安排住宿 | 房务管理员/管理员 | 需安排酒店房间 |
|
||||||
|
| `ARRANGE_VEHICLE` | 安排车辆 | 车务管理员/管理员 | 需安排用车 |
|
||||||
|
| `CONFIRM_CHECKLIST` | 确认清单 | 定制师/管理员 | 出行清单待确认 |
|
||||||
|
| `PROCESS_REFUND` | 处理退款 | 财务/管理员 | 退款申请待处理 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 角色枚举（role）
|
||||||
|
|
||||||
|
| 值 | 中文名 | 工作台类型 |
|
||||||
|
|----|--------|-----------|
|
||||||
|
| `SUPER_ADMIN` | 超级管理员 | AdminDashboardVO |
|
||||||
|
| `ADMIN` | 管理员 | AdminDashboardVO |
|
||||||
|
| `CUSTOMIZER` | 定制师 | DesignerDashboardVO |
|
||||||
|
| `ROOM_MANAGER` | 房务管理员 | HousekeepingDashboardVO |
|
||||||
|
| `VEHICLE_MANAGER` | 车务管理员 | LogisticsDashboardVO |
|
||||||
|
| `FINANCE` | 财务 | FinanceDashboardVO |
|
||||||
|
| `MATERIAL_ADMIN` | 素材管理员 | MaterialDashboardVO |
|
||||||
|
| `OPERATOR` | 运营 | AdminDashboardVO（降级） |
|
||||||
|
| `CUSTOMER_SERVICE` | 客服 | AdminDashboardVO（降级） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 前端实现建议 — 页面布局
|
||||||
|
|
||||||
|
### 整体架构
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────────────────────────────────────────────┐
|
||||||
|
│ [头像] 李明 定制师 ⚙️ 编辑资料 │ ← GET /admin/profile/me
|
||||||
|
├──────────────────────────────────────────────────┤
|
||||||
|
│ 时间范围： [今日] [本周] [本月] │ ← period 参数切换
|
||||||
|
├──────────────────────────────────────────────────┤
|
||||||
|
│ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
|
||||||
|
│ │订单 15│ │GMV 12W│ │新用户42│ │访客380│ │ ← overview 数据卡片
|
||||||
|
│ │ +3 ▲ │ │+18% ▲ │ │+15% ▲ │ │-5% ▼ │ │ 数字+趋势箭头+百分比
|
||||||
|
│ └───────┘ └───────┘ └───────┘ └───────┘ │
|
||||||
|
├──────────────────────────────────────────────────┤
|
||||||
|
│ 待办事项 │
|
||||||
|
│ 确认订单(3) 配置保险(1) 签合同(2) │ ← todos Map
|
||||||
|
│ 安排住宿(1) 安排车辆(1) │ 数值>0 显示红色角标
|
||||||
|
├──────────────────────────────────────────────────┤
|
||||||
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||||
|
│ │ 数据趋势(7天) │ │ 转化漏斗 │ │ ← trend + funnel
|
||||||
|
│ │ 折线图/柱状图 │ │ 漏斗图 │ │ （漏斗仅定制师有）
|
||||||
|
│ └──────────────────┘ └──────────────────┘ │
|
||||||
|
├──────────────────────────────────────────────────┤
|
||||||
|
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||||
|
│ │ 即将出行(5条) │ │ 业绩排行 │ │
|
||||||
|
│ │ 卡片列表 │ │ 排行列表 │ │
|
||||||
|
│ └──────────────────┘ └──────────────────┘ │
|
||||||
|
└──────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 核心逻辑
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// 1. 获取个人资料（判断角色）
|
||||||
|
const { data: profile } = await request.get('/admin/profile/me')
|
||||||
|
const role = profile.role // "CUSTOMIZER" / "SUPER_ADMIN" / ...
|
||||||
|
|
||||||
|
// 2. 获取工作台数据（同一接口，后端按角色返回不同结构）
|
||||||
|
const { data: dashboard } = await request.get('/admin/profile/dashboard', {
|
||||||
|
params: { period: 'today' }
|
||||||
|
})
|
||||||
|
|
||||||
|
// 3. 根据 role 渲染不同布局
|
||||||
|
switch (role) {
|
||||||
|
case 'SUPER_ADMIN':
|
||||||
|
case 'ADMIN':
|
||||||
|
// 渲染全局管理台：overview + todos + trend + ranking + upcomingTrips + 统计数字
|
||||||
|
break
|
||||||
|
case 'CUSTOMIZER':
|
||||||
|
// 渲染定制师工作台：overview + todos + shortcuts + trend + funnel + upcomingTrips
|
||||||
|
// + ranking + calendarEvents + reviewStats + productStats + customerStats
|
||||||
|
break
|
||||||
|
case 'ROOM_MANAGER':
|
||||||
|
// 渲染房务工作台：totalHotels + totalRoomTypes + pendingArrangeRoom + upcomingTrips
|
||||||
|
break
|
||||||
|
case 'VEHICLE_MANAGER':
|
||||||
|
// 渲染车务工作台：totalVehicles + totalVehicleModels + pendingArrangeVehicle + upcomingTrips
|
||||||
|
break
|
||||||
|
case 'FINANCE':
|
||||||
|
// 渲染财务工作台：periodIncome/Refund + monthIncome/Refund + pending + trend
|
||||||
|
break
|
||||||
|
case 'MATERIAL_ADMIN':
|
||||||
|
// 渲染素材工作台：totalMaterials + monthNewCount + totalRefCount + categoryDistribution
|
||||||
|
break
|
||||||
|
default:
|
||||||
|
// 降级使用管理员工作台
|
||||||
|
break
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 注意事项
|
||||||
|
- **雪花ID**：所有 ID 字段都是字符串（超过 JS Number 安全范围），用 `String` 接收
|
||||||
|
- **金额字段**：BigDecimal 序列化为数字（非字符串），前端用 `Number` 或 `toFixed(2)` 处理
|
||||||
|
- **增长率**：小数格式（0.25 = 25%），前端需 `×100` 再展示百分比
|
||||||
|
- **空值安全**：部分字段可能为 null（如远程服务不可用时），做好默认值处理
|
||||||
|
- **时间范围切换**：切换 period 时重新调用 dashboard 接口，局部刷新数据
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户