docs: 小蒙马报价增强 + 产品操作日志前端对接指南
这个提交包含在：
API Changelog Bot
父节点
901a4fcd05
当前提交
898c59b90f
@ -0,0 +1,322 @@
|
|||||||
|
# 小蒙马报价增强 + 产品操作日志 - 前端对接指南
|
||||||
|
|
||||||
|
> **日期**: 2026-03-18
|
||||||
|
> **后端状态**: ✅ 已完成，可直接对接
|
||||||
|
> **涉及模块**: 产品管理（管理端）、C端产品（小程序端）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 一、功能说明
|
||||||
|
|
||||||
|
### 1. 产品操作日志（管理端）
|
||||||
|
|
||||||
|
产品服务全部管理接口已补全 `@OperationLog` 注解，管理端产品列表页右侧的"操作日志"面板现在能正常显示操作记录。
|
||||||
|
|
||||||
|
**覆盖的模块**（共 73 个写操作接口）：
|
||||||
|
- 产品管理：保存/创建/更新/删除/复制/移动/分享/路径图/状态变更
|
||||||
|
- 拼团批次管理：创建主批次/子批次/更新/删除/开启报名/关闭报名/解散/服务人员/复制人员
|
||||||
|
- 定价公式管理：公式组CRUD/激活 + 步骤CRUD/启停/回滚 + 测试 + 变量CRUD
|
||||||
|
- 定价与费用管理：定价规则/价格日历/费用项/额外成本/自定义费用
|
||||||
|
- 行程管理：行程天/节点/住宿/餐饮/物资/人员配置
|
||||||
|
- 产品线管理/文件夹管理/家庭分组管理/报价计算
|
||||||
|
|
||||||
|
**前端无需改动**，操作日志面板已接入 `/admin/monitor/operation-logs` 接口，后端开始写入日志后自动显示。
|
||||||
|
|
||||||
|
### 2. 小蒙马(GROUP)产品报价增强
|
||||||
|
|
||||||
|
GROUP 产品报价接口新增空床补差计算和房间数参数，算价公式更精确。
|
||||||
|
|
||||||
|
### 3. 团期批次新增 `adultsPerRoom` 字段
|
||||||
|
|
||||||
|
创建/更新批次时可配置每间房入住成人数（默认2），影响单房差和空床补差计算。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 二、接口清单
|
||||||
|
|
||||||
|
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||||||
|
|---|------|------|------|----------|------|
|
||||||
|
| 1 | GROUP产品报价 | GET | `/admin/product/item/{productId}/group-quote` | 参数+响应新增 | 新增 childCount、roomCount 参数和多个响应字段 |
|
||||||
|
| 2 | 创建主批次 | POST | `/admin/product/item/{productId}/batch` | 请求新增 | 新增 adultsPerRoom 字段 |
|
||||||
|
| 3 | 更新批次 | PUT | `/admin/product/item/{productId}/batch/{batchId}` | 请求新增 | 新增 adultsPerRoom 字段 |
|
||||||
|
| 4 | 批次列表/详情 | GET | 批次相关接口 | 响应新增 | 返回中新增 adultsPerRoom 字段 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、接口详细定义
|
||||||
|
|
||||||
|
### 接口 1：GROUP产品报价（管理端）
|
||||||
|
|
||||||
|
**使用场景**：管理端产品详情页 → 报价计算面板，输入人数和房间数查看GROUP产品的完整报价。
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /admin/product/item/{productId}/group-quote?batchId=xxx&adultCount=2&childCount=1&roomCount=1
|
||||||
|
```
|
||||||
|
|
||||||
|
### 请求参数
|
||||||
|
|
||||||
|
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||||
|
|------|------|------|--------|------|
|
||||||
|
| productId | Long | 是 | - | 产品ID（路径参数） |
|
||||||
|
| batchId | Long | 是 | - | 团期批次ID |
|
||||||
|
| adultCount | Integer | 否 | 2 | 成人人数 |
|
||||||
|
| childCount | Integer | 否 | 0 | 儿童人数（🆕 新增） |
|
||||||
|
| roomCount | Integer | 否 | 1 | 房间数（🆕 新增） |
|
||||||
|
|
||||||
|
### 响应示例
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"message": "操作成功",
|
||||||
|
"data": {
|
||||||
|
"code": 0,
|
||||||
|
"message": null,
|
||||||
|
"singleRoomSupplement": 200.00,
|
||||||
|
"perPersonCost": 800.00,
|
||||||
|
"adultCostPrice": 1000.00,
|
||||||
|
"childCostPrice": 800.00,
|
||||||
|
"adultSellPrice": 1500.00,
|
||||||
|
"childSellPrice": 1300.00,
|
||||||
|
"hotelCostTotal": 600.00,
|
||||||
|
"adultsPerRoom": 2,
|
||||||
|
"roomCount": 1,
|
||||||
|
"adultCount": 2,
|
||||||
|
"childCount": 1,
|
||||||
|
"emptyBedSupplement": 0.00,
|
||||||
|
"totalSellPrice": 4300.00,
|
||||||
|
"extraCostTotal": 200.00,
|
||||||
|
"extraCostPerPerson": 66.67,
|
||||||
|
"extraCostItems": [
|
||||||
|
{
|
||||||
|
"costItemId": "2026...",
|
||||||
|
"costItemName": "保险费",
|
||||||
|
"unitPrice": 50.00,
|
||||||
|
"quantity": 1,
|
||||||
|
"totalPrice": 50.00
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"dayCosts": [...],
|
||||||
|
"profitMode": "PERCENT",
|
||||||
|
"warnings": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 响应字段说明
|
||||||
|
|
||||||
|
| 字段 | 类型 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| code | Integer | 返回码: 0=成功, 1=非GROUP产品, 2=错误 |
|
||||||
|
| message | String | 错误信息（code!=0时） |
|
||||||
|
| singleRoomSupplement | BigDecimal | 单房差 = 成人售价 - 儿童售价（🆕 含义变更） |
|
||||||
|
| perPersonCost | BigDecimal | 每人成本（不含酒店） |
|
||||||
|
| adultCostPrice | BigDecimal | 成人成本价 = 单房差 + 每人费用 |
|
||||||
|
| childCostPrice | BigDecimal | 儿童成本价 = 每人费用（不含酒店） |
|
||||||
|
| adultSellPrice | BigDecimal | 成人售价 |
|
||||||
|
| childSellPrice | BigDecimal | 儿童售价 |
|
||||||
|
| hotelCostTotal | BigDecimal | 酒店总成本 |
|
||||||
|
| adultsPerRoom | Integer | 🆕 每间房入住成人数 |
|
||||||
|
| roomCount | Integer | 🆕 选择的房间数 |
|
||||||
|
| adultCount | Integer | 🆕 成人数 |
|
||||||
|
| childCount | Integer | 🆕 儿童数 |
|
||||||
|
| emptyBedSupplement | BigDecimal | 🆕 空床补差 = (房间数×每房成人数 - 成人数) × 单房差 |
|
||||||
|
| totalSellPrice | BigDecimal | 🆕 总售价 = 成人价×成人数 + 儿童价×儿童数 + 空床补差 |
|
||||||
|
| extraCostTotal | BigDecimal | 额外成本总额（团队） |
|
||||||
|
| extraCostPerPerson | BigDecimal | 额外成本（人均） |
|
||||||
|
| extraCostItems | Array | 额外成本明细列表 |
|
||||||
|
| dayCosts | Array | 每日成本明细 |
|
||||||
|
| profitMode | String | 利润模式 |
|
||||||
|
| warnings | Array[String] | 警告信息 |
|
||||||
|
|
||||||
|
### 算价公式
|
||||||
|
|
||||||
|
```
|
||||||
|
单房差 = 酒店总成本 ÷ 每房成人数
|
||||||
|
成人成本价 = 单房差 + 人均成本（不含酒店）
|
||||||
|
儿童成本价 = 人均成本（不含酒店）
|
||||||
|
成人售价 = 成人成本价 × (1 + 利润率)
|
||||||
|
儿童售价 = 儿童成本价 × (1 + 利润率)
|
||||||
|
空床补差 = (房间数 × 每房成人数 - 成人数) × 单房差
|
||||||
|
总售价 = 成人售价 × 成人数 + 儿童售价 × 儿童数 + 空床补差
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 接口 2/3：创建/更新团期批次
|
||||||
|
|
||||||
|
**变更**：新增 `adultsPerRoom` 字段。
|
||||||
|
|
||||||
|
#### 创建批次请求（新增字段）
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /admin/product/item/{productId}/batch
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"batchLabel": "五一团",
|
||||||
|
"batchName": "2026年五一黄金周第一批",
|
||||||
|
"departureDate": "2026-05-01",
|
||||||
|
"endDate": "2026-05-05",
|
||||||
|
"enrollmentDeadline": "2026-04-25",
|
||||||
|
"minParticipants": 10,
|
||||||
|
"maxParticipants": 30,
|
||||||
|
"adultsPerRoom": 2,
|
||||||
|
"remark": "备注"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 更新批次请求（新增字段）
|
||||||
|
|
||||||
|
```
|
||||||
|
PUT /admin/product/item/{productId}/batch/{batchId}
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"batchLabel": "五一团（更新）",
|
||||||
|
"adultsPerRoom": 3,
|
||||||
|
"maxParticipants": 35
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 新增字段说明
|
||||||
|
|
||||||
|
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||||||
|
|------|------|------|--------|------|
|
||||||
|
| adultsPerRoom | Integer | 否 | 2 | 每间房入住成人数（影响单房差和空床补差计算） |
|
||||||
|
|
||||||
|
### 批次列表/详情响应（新增字段）
|
||||||
|
|
||||||
|
批次列表和详情接口返回的 `GroupTourBatchVO` 新增 `adultsPerRoom` 字段：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"batchId": "2026280000000000001",
|
||||||
|
"productId": "2026270000000000001",
|
||||||
|
"batchLabel": "五一团",
|
||||||
|
"departureDate": "2026-05-01",
|
||||||
|
"enrolledCount": 15,
|
||||||
|
"adultsPerRoom": 2,
|
||||||
|
"batchStatus": "ENROLLING",
|
||||||
|
"remainingSlots": 15,
|
||||||
|
"subBatches": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、关联字典
|
||||||
|
|
||||||
|
### batch_status（批次状态）
|
||||||
|
|
||||||
|
| 值 | 中文 | 说明 |
|
||||||
|
|----|------|------|
|
||||||
|
| PENDING | 待开放 | 创建后默认状态 |
|
||||||
|
| ENROLLING | 报名中 | 用户可报名 |
|
||||||
|
| CONFIRMED | 已成团 | 达到最低人数 |
|
||||||
|
| FULL | 已满员 | 达到最大人数 |
|
||||||
|
| CLOSED | 已关闭 | 不再接受报名 |
|
||||||
|
| IN_PROGRESS | 进行中 | 已出发 |
|
||||||
|
| FINISHED | 已结束 | 行程结束 |
|
||||||
|
| DISBANDED | 已解散 | 批次取消 |
|
||||||
|
|
||||||
|
### product_type（产品类型）
|
||||||
|
|
||||||
|
| 值 | 中文 | 说明 |
|
||||||
|
|----|------|------|
|
||||||
|
| CORE | 核心产品 | 标准产品，按人头计价 |
|
||||||
|
| GROUP | 小蒙马 | 拼团产品，按人头+房间计价 |
|
||||||
|
| CUSTOM | 定制产品 | 按单计价 |
|
||||||
|
| ROUTE | 线路产品 | 预设线路，按单计价 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、前端实现建议
|
||||||
|
|
||||||
|
### 1. GROUP报价面板
|
||||||
|
|
||||||
|
在团期详情或报价页面，增加"房间数"输入框：
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────┐
|
||||||
|
│ GROUP产品报价 │
|
||||||
|
├────────────────────────────────────────┤
|
||||||
|
│ 团期: [五一团 ▼] │
|
||||||
|
│ 成人: [2] 儿童: [1] 房间: [1] │
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────────────────────┐ │
|
||||||
|
│ │ 成人售价: ¥1,500/人 │ │
|
||||||
|
│ │ 儿童售价: ¥1,300/人 │ │
|
||||||
|
│ │ 空床补差: ¥0.00 │ │
|
||||||
|
│ │ ───────────────────── │ │
|
||||||
|
│ │ 总售价: ¥4,300.00 │ │
|
||||||
|
│ └──────────────────────────────┘ │
|
||||||
|
└────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**参数变更**：调用 `group-quote` 接口时需传 `childCount` 和 `roomCount`。
|
||||||
|
|
||||||
|
### 2. 批次创建/编辑表单
|
||||||
|
|
||||||
|
新增"每间房入住成人数"字段（默认2，下拉或数字输入框）：
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────┐
|
||||||
|
│ 创建团期 │
|
||||||
|
├────────────────────────────────────────┤
|
||||||
|
│ 批次标签: [五一团 ] │
|
||||||
|
│ 出发日期: [2026-05-01 ] │
|
||||||
|
│ 结束日期: [2026-05-05 ] │
|
||||||
|
│ 最少成团: [10] 最大人数: [30] │
|
||||||
|
│ 每房成人数: [2 ▼] │
|
||||||
|
│ 报名截止: [2026-04-25 ] │
|
||||||
|
└────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 操作日志面板
|
||||||
|
|
||||||
|
无需前端改动。后端已为产品服务所有 POST/PUT/DELETE 接口添加操作日志，查看产品操作日志的面板将自动展示数据。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 六、调用示例（JavaScript）
|
||||||
|
|
||||||
|
### GROUP产品报价
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// 查询GROUP产品报价（含房间数和儿童）
|
||||||
|
const res = await request.get(`/admin/product/item/${productId}/group-quote`, {
|
||||||
|
params: {
|
||||||
|
batchId: selectedBatchId,
|
||||||
|
adultCount: 2,
|
||||||
|
childCount: 1, // 新增
|
||||||
|
roomCount: 1 // 新增
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
if (res.data.code === 0) {
|
||||||
|
const quote = res.data
|
||||||
|
console.log('成人售价:', quote.adultSellPrice)
|
||||||
|
console.log('儿童售价:', quote.childSellPrice)
|
||||||
|
console.log('空床补差:', quote.emptyBedSupplement) // 新增
|
||||||
|
console.log('总售价:', quote.totalSellPrice) // 新增
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 创建团期批次（含每房成人数）
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const res = await request.post(`/admin/product/item/${productId}/batch`, {
|
||||||
|
batchLabel: '五一团',
|
||||||
|
batchName: '2026年五一黄金周第一批',
|
||||||
|
departureDate: '2026-05-01',
|
||||||
|
endDate: '2026-05-05',
|
||||||
|
enrollmentDeadline: '2026-04-25',
|
||||||
|
minParticipants: 10,
|
||||||
|
maxParticipants: 30,
|
||||||
|
adultsPerRoom: 2, // 新增：每间房入住成人数
|
||||||
|
remark: ''
|
||||||
|
})
|
||||||
|
```
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户