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

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 数据完整、无评价产品返零态,均已实测确认。