feat(product-v2): 产品详情页自定义区块接口changelog

changelogs/2026-04/2026-04-15_product-v2_detail_blocks.md

@@ -0,0 +1,143 @@
+# 产品详情页自定义区块（GROUP产品专用）
+
+- **日期**: 2026-04-15
+- **服务**: hl-product-service-v2
+- **PR**: #584
+- **类型**: feat (新功能)
+
+## 概述
+
+GROUP（小蒙马）产品的小程序详情页支持后台自定义设计，不再使用自动生成的页面。通过独立接口保存/读取一个大JSON，存储页面区块配置。
+
+## 新增接口
+
+### 1. 获取详情页区块
+
+```
+GET /admin/product/item/{productId}/detail-blocks
+```
+
+**响应示例**（未设置时data为null）：
+```json
+{
+  "code": 200,
+  "data": [
+    {
+      "id": "block_1",
+      "type": "hero",
+      "visible": true,
+      "data": {
+        "backgroundImage": "",
+        "brandTitle": "小 蒙 马 · XIAOMENGMA",
+        "mainTitle": "趁童年尚好\n陪孩子去草原撒个欢",
+        "subtitle": "呼伦贝尔 · 6天5夜亲子游学",
+        "videoUrl": "https://xxx.mp4",
+        "videoDuration": ""
+      },
+      "style": {
+        "height": 440,
+        "overlayGradient": ["#00000005", "#000000BB"]
+      }
+    },
+    {
+      "id": "block_2",
+      "type": "experiences",
+      "visible": true,
+      "data": {
+        "icon": "baby",
+        "title": "这些事，值得带孩子来一趟",
+        "subtitle": "听风、画云、策马、寻迹，每一程都是成长",
+        "items": [
+          {
+            "id": "item_1",
+            "image": "",
+            "icon": "music",
+            "title": "听 · 草原专属之声",
+            "description": "围坐草原，聆听马头琴与长调"
+          }
+        ]
+      },
+      "style": {
+        "background": "#FFF7ED",
+        "padding": [32, 20],
+        "gap": 16
+      }
+    }
+  ]
+}
+```
+
+### 2. 保存详情页区块
+
+```
+PUT /admin/product/item/{productId}/detail-blocks
+Content-Type: application/json
+```
+
+**请求体**：
+```json
+{
+  "detailBlocks": [
+    {
+      "id": "block_xxx",
+      "type": "hero|experiences|faq|yearReview|leaderIntro|photographer|safety",
+      "visible": true,
+      "data": { ... },
+      "style": { ... }
+    }
+  ]
+}
+```
+
+**响应**：
+```json
+{
+  "code": 200,
+  "message": "详情页区块保存成功"
+}
+```
+
+## 已有接口变更
+
+### 管理端产品详情
+
+```
+GET /admin/product/item/{productId}
+```
+
+响应新增字段：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `detailBlocks` | Array/null | 小程序详情页自定义区块JSON，仅GROUP产品使用 |
+
+### 小程序端产品详情
+
+```
+GET /mp/product/{productId}
+```
+
+响应新增字段：
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `detailBlocks` | Array/null | GROUP产品返回自定义区块数组，CORE产品为null |
+
+## 区块类型说明
+
+| type | 说明 |
+|------|------|
+| `hero` | 首屏大图/视频区 |
+| `experiences` | 体验亮点列表 |
+| `faq` | 常见问答 |
+| `yearReview` | 年度回顾视频 |
+| `leaderIntro` | 领队介绍 |
+| `photographer` | 跟拍摄影师介绍 |
+| `safety` | 安全保障 |
+
+区块结构由前端页面设计器定义，后端只负责整体存取，不校验内部结构。
+
+## 注意事项
+
+- 保存接口为**整体覆盖**，每次传完整的区块数组
+- `visible` 字段控制区块是否在小程序端展示
+- 仅GROUP产品使用此功能，CORE/CUSTOM产品该字段为null
+- 数据库字段为 `MEDIUMTEXT`，支持大JSON存储