138 行
4.5 KiB
Markdown
138 行
4.5 KiB
Markdown
# 小程序评价 - `/mp/review/target` 接口 targetId 改为可选（支持"全部评论"页）
|
||
|
||
- **日期**: 2026-04-20
|
||
- **PR**: [#951](https://git.1814.love:8443/wx/HL/pulls/951) (Closes #949)
|
||
- **类型**: FEATURE（兼容性增强，请求参数收紧 → 放宽）
|
||
- **服务**: hl-user-service（review 模块合并在 user 库 / user 服务，路由 `/mp/review/**`）
|
||
- **前端是否需要改动**: **无强制改动**（旧调用方式继续可用），新页面"全部评论"可直接复用本接口
|
||
|
||
---
|
||
|
||
## 一、背景
|
||
|
||
小程序新增"全部评论"列表页：在某个 `targetType`（产品 / 攻略 / 酒店 / 景点 / ...）下展示**全部已通过审核的评价**，不限定具体的目标对象 ID。
|
||
|
||
原接口 `GET /mp/review/target` 此前要求 `targetId` 必填，前端无法用同一个接口实现"全部评论"页，只能等后端再开一个新接口或自己拼。
|
||
|
||
本次后端把 `targetId` 由必填改为可选，**同接口同时支持两种语义**，前端不用再要新接口。
|
||
|
||
---
|
||
|
||
## 二、变更接口
|
||
|
||
| # | 方法 | 路径 | 变更类型 |
|
||
|---|------|------|---------|
|
||
| 1 | GET | `/mp/review/target` | 请求参数 `targetId` 由必填改为可选；响应结构不变 |
|
||
|
||
---
|
||
|
||
## 三、请求参数变化
|
||
|
||
| 参数 | 类型 | 之前 | 现在 | 说明 |
|
||
|------|------|------|------|------|
|
||
| `targetType` | String | **必填** | **必填**（不变） | 评价目标类型，字典 `review_target_type`（如 `PRODUCT` / `STRATEGY` / `HOTEL` / `SCENIC` / ...） |
|
||
| `targetId` | Long | **必填** | **可选** | 不传 → 返回该 targetType 下所有已通过评价；传 → 按该 ID 过滤（行为不变） |
|
||
| `pageNo` / `pageSize` | Integer | 可选（分页默认值） | 同左 | 不变 |
|
||
|
||
---
|
||
|
||
## 四、行为对照
|
||
|
||
| 调用方式 | 返回内容 |
|
||
|---|---|
|
||
| `GET /mp/review/target?targetType=PRODUCT&targetId=1001` | 商品 1001 的全部已通过评价（**行为完全不变**） |
|
||
| `GET /mp/review/target?targetType=PRODUCT` | 全部商品的所有已通过评价（**新支持**） |
|
||
| `GET /mp/review/target`（缺 targetType） | 仍返回参数校验错误（targetType 仍必填） |
|
||
|
||
---
|
||
|
||
## 五、响应结构（不变）
|
||
|
||
`PageResult<MpReviewVO>`，字段沿用既有结构：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"total": 128,
|
||
"records": [
|
||
{
|
||
"id": 9001,
|
||
"targetType": "PRODUCT",
|
||
"targetId": 1001,
|
||
"userId": 88,
|
||
"nickname": "***",
|
||
"avatar": "https://...",
|
||
"rating": 5,
|
||
"content": "服务很好，下次还来",
|
||
"images": ["https://..."],
|
||
"createTime": "2026-04-15 12:30:00"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
> 字段名、类型、嵌套结构与原接口**完全一致**，前端拿到的 records 结构无变化。
|
||
|
||
---
|
||
|
||
## 六、前端使用建议
|
||
|
||
### 场景 A：商品/攻略详情页"评价"模块（旧场景）
|
||
|
||
**不用改**。原本就传 `targetType + targetId`，行为不变。
|
||
|
||
### 场景 B：小程序"全部评论"列表页（新场景）
|
||
|
||
```js
|
||
// 全部商品评论（按 targetType 过滤）
|
||
const res = await request({
|
||
url: '/mp/review/target',
|
||
method: 'GET',
|
||
data: {
|
||
targetType: 'PRODUCT', // 必填
|
||
pageNo: 1,
|
||
pageSize: 20
|
||
// targetId 不传
|
||
}
|
||
});
|
||
// res.data.records 即整个 targetType 下的所有评价
|
||
```
|
||
|
||
### ⚠️ 注意
|
||
|
||
- `targetType` 仍**必填**，不传会被参数校验拦截
|
||
- 不传 `targetId` 时，返回的 records 里每条都有自己的 `targetId`，前端可据此跳到对应详情
|
||
- 评价审核状态过滤（已通过 / 待审核）逻辑后端处理，前端无感
|
||
|
||
---
|
||
|
||
## 七、不兼容变更
|
||
|
||
**无**。仅放宽请求参数约束（必填 → 可选），既有调用方式继续按原语义工作。
|
||
|
||
---
|
||
|
||
## 八、回归验证
|
||
|
||
测试环境部署完成后，用 mp token 调用：
|
||
|
||
```bash
|
||
# 1. 旧用法（带 targetId）行为不变
|
||
curl "https://api.test.1814.love/mp/review/target?targetType=PRODUCT&targetId=1001&pageNo=1&pageSize=10" \
|
||
-H "Authorization: Bearer {mp-token}" \
|
||
| jq '.data | {total, sample: .records[0]}'
|
||
|
||
# 2. 新用法（不带 targetId，全部评论）
|
||
curl "https://api.test.1814.love/mp/review/target?targetType=PRODUCT&pageNo=1&pageSize=10" \
|
||
-H "Authorization: Bearer {mp-token}" \
|
||
| jq '.data | {total, sample: .records[0]}'
|
||
|
||
# 3. 缺 targetType（应报参数错误）
|
||
curl "https://api.test.1814.love/mp/review/target?pageNo=1&pageSize=10" \
|
||
-H "Authorization: Bearer {mp-token}"
|
||
```
|
||
|
||
**预期**：场景 1 与改动前一致；场景 2 返回的 total 应 ≥ 场景 1；场景 3 返回参数校验错误。
|