# notice(评价): /mp/product reviewSummary 全量字段契约 + 空数据态告知(前端按 totalCount 判空)

> **类型**: notice(汇总告知,接口契约已稳定,本条不含新代码)
> **关联 PR**: #2984(reviewSummary 契约修复) + #2981(source 字段) + #2989(topReview 补 source/sourceLabel) + #2991(sourceLabel 字典化)
> **日期**: 2026-05-25
> **影响接口**: `GET /mp/product/{id}` 的 `reviewSummary` 字段
> **接收方**: mmg
> **前端**: **需调整空态判断逻辑(详见「前端必做」)**

---

## 🎯 背景

此前 `/mp/product/{id}` 的 `reviewSummary` 4 个字段(avgScore/totalCount/topReview/tags)**恒为 null**(契约 bug,Feign 声明强类型但后端返 Map,字段名零匹配)。该问题已由 PR #2984 彻底修复:后端改强类型 DTO,Assembler 窄化为前端契约。

**现在 `reviewSummary` 已稳定返回结构化对象**。但「对象非 null」不等于「有评价」——产品没评价时返回的是零值对象,不是 null。这点前端务必区分(见下)。

---

## 📋 reviewSummary 字段契约

| 字段 | 类型 | 有评价 | 无评价 |
|------|------|--------|--------|
| `avgScore` | number | 平均分(如 5.0) | **0** |
| `totalCount` | int | 评价总数(如 159) | **0** |
| `topReview` | object \| null | 精选评价对象 | **null** |
| `tags` | string[] \| null | 当前后端暂未输出,恒 null | null |

`topReview` 子字段(精选取 topRated 优先,缺则 topLiked):

| 字段 | 说明 |
|------|------|
| `reviewId` | 评价ID |
| `nickname` / `avatarUrl` | 昵称 / 头像 |
| `score` | 评分(1-5) |
| `content` | 评价内容 |
| `images` | 图片数组(可空) |
| `likeCount` | 点赞数 |
| `reviewTime` | 评价时间 |
| `source` | 来源(MINIPROGRAM=小程序 / YOUZAN=有赞),字典 review_source |
| `sourceLabel` | 来源中文(小程序 / 有赞),运维改字典即时生效 |

---

## ✅ 测试服实测(真实数据)

**情形 1 — 有评价(数据正常)**

产品 `2045716022098264066`「额吉的故乡V9·7天6晚旷野版」,159 条:

```json
"reviewSummary": {
  "avgScore": 5.0,
  "totalCount": 159,
  "topReview": {
    "nickname": "汪***", "score": 5,
    "content": "行程安排很舒服，避开了拥堵，人少景美…",
    "images": ["…4张…"],
    "source": "YOUZAN", "sourceLabel": "有赞"
  },
  "tags": null
}
```

产品 `2045749044617084929`「额吉的故乡6天5晚」172 条,数据同样完整(avgScore=5.0、topReview 含内容+图片+来源)。

**情形 2 — 无评价(空态正常,非 bug)**

产品 `2056966973370707970`,DB 实测 0 条评价(任何状态):

```json
"reviewSummary": {
  "avgScore": 0,
  "totalCount": 0,
  "topReview": null,
  "tags": null
}
```

---

## ⚠️ 前端必做

1. **用 `totalCount === 0` 判空**,渲染「暂无评价」空态。**不要**因为 `reviewSummary` 非 null 就认为有评价。
2. **`topReview` 可能为 null**(无评价产品),渲染前判空,勿直接取 `topReview.nickname` 等导致报错。
3. **`avgScore` 空态为 0**,空态请隐藏评分,不要显示「0.0 分 / 0 星」误导用户。
4. **`topReview` 新增 `source` / `sourceLabel`**,可在精选评价上展示来源标识(如「来自有赞」)。
5. `tags` 当前恒 null,暂不要依赖。

---

## 🔧 部署状态

测试服 hl-order-service-v2 / hl-product-service-v2 均已部署最新 dev。有评价产品 reviewSummary 数据完整、无评价产品返零态,均已实测确认。
