# 产品详情页自定义区块（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存储