From ac5be63d1f3525e46ac401845b8b9df0e74acdbe Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Mon, 25 May 2026 15:14:34 +0800
Subject: [PATCH] =?UTF-8?q?notice(=E8=AF=84=E4=BB=B7):=20reviewSummary=20?=
 =?UTF-8?q?=E5=85=A8=E9=87=8F=E5=AD=97=E6=AE=B5=E5=A5=91=E7=BA=A6=20+=20?=
 =?UTF-8?q?=E7=A9=BA=E6=95=B0=E6=8D=AE=E6=80=81=E5=91=8A=E7=9F=A5=E5=89=8D?=
 =?UTF-8?q?=E7=AB=AF(=E6=8C=89=20totalCount=20=E5=88=A4=E7=A9=BA)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...eview_summary_full_spec_and_empty_state.md | 94 +++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 changelogs/2026-05/25_notice_review_summary_full_spec_and_empty_state.md

diff --git a/changelogs/2026-05/25_notice_review_summary_full_spec_and_empty_state.md b/changelogs/2026-05/25_notice_review_summary_full_spec_and_empty_state.md
new file mode 100644
index 0000000..6e2a6db
--- /dev/null
+++ b/changelogs/2026-05/25_notice_review_summary_full_spec_and_empty_state.md
@@ -0,0 +1,94 @@
+# 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 数据完整、无评价产品返零态,均已实测确认。