# 首页模块管理 API 文档

本文档描述了首页模块管理及其配置相关的接口规范。

## 1. 全局响应结构

所有接口的返回值均由 `GlobalResponseWrapper` 统一包装，遵循以下 JSON 结构：

```json
{
  "code": 200,          // 状态码 (200: 成功, 其他: 失败)
  "message": "success", // 响应消息
  "success": true,      // 成功标识
  "data": { ... },      // 具体业务数据
  "timestamp": 1709628736123 // 响应时间戳
}
```

---

## 2. 新增/更新模块 (包含配置项)

*   **URL**: `/v2/module/add`
*   **Method**: `POST`
*   **Content-Type**: `application/json`
*   **描述**: 新增或更新模块信息。若提供了 `configs`，则会将这些配置项绑定到该模块下（会覆盖旧的配置）。

### 请求参数

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `id` | integer | 否 | 模块ID (更新时必填，新增时无需传) |
| `name` | string | 否 | 模块名称 |
| `subTitle` | string | 否 | 子标题 |
| `moduleType` | string | 否 | 模块类型 1:幻灯片 2:列表 3:卡片 4:条幅 5:标签 6:vip类型 7:排版1 8:排版2 9:排版3 |
| `sort` | integer | 否 | 排序 |
| `lang` | string | 否 | 语言包 (JSON字符串) |
| `configs` | array | 否 | 模块配置列表 |

#### configs 结构

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `type` | integer | 是 | 类型 1:标签 2:风格 3:条幅 4:vip框 |
| `tagId` | integer | 否 | 标签id |
| `styleId` | integer | 否 | 风格id |
| `effectId` | integer | 否 | 滤镜id |
| `coverImg` | string | 否 | 封面图 |
| `cardCoverImg` | string | 否 | 卡片模块下封面图 |
| `sort` | integer | 否 | 排序 |
| `linkType` | integer | 否 | 链接类型 1:打开标签详情 2:打开风格详情 3: 打开网页 |
| `url` | string | 否 | 跳转URL |
| `tagName` | string | 否 | 标签名称 |
| `tagDescribe` | string | 否 | 标签描述 |
| `styleName` | string | 否 | 风格名称 |
| `styleDescribe` | string | 否 | 风格描述 |
| `effectName` | string | 否 | 滤镜名称 |
| `effectDescribe` | string | 否 | 滤镜描述 |
| `urlTitle` | string | 否 | url标题 |
| `content` | string | 否 | 内容 |
| `description` | string | 否 | 内容描述 |

### 响应参数

| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `data` | boolean | 是否成功 |

---

## 3. 批量更新排序

*   **URL**: `/v2/module/sort`
*   **Method**: `POST`
*   **Content-Type**: `application/json`
*   **描述**: 批量更新模块的排序值。

### 请求参数 (数组)

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `id` | integer | 是 | 模块ID |
| `sort` | integer | 是 | 排序值 |

**请求示例**:

```json
[
  { "id": 1, "sort": 1 },
  { "id": 2, "sort": 2 },
  { "id": 3, "sort": 3 }
]
```

### 响应参数

| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `data` | boolean | 是否成功 |

---

## 4. 删除模块

*   **URL**: `/v2/module/delete/{id}`
*   **Method**: `DELETE`
*   **描述**: 根据 ID 删除模块，同时会删除该模块下的所有配置项。

### 请求参数

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `id` | integer | 是 | 模块ID |

### 响应参数

| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `data` | boolean | 是否成功 |

---

## 5. 获取单个模块详情

*   **URL**: `/v2/module/get/{id}`
*   **Method**: `GET`
*   **描述**: 根据 ID 获取模块详情（包含配置项）。返回的数据结构与新增/更新接口的请求参数结构完全一致，方便前端回显和再次提交。

### 请求参数

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `id` | integer | 是 | 模块ID |

### 响应参数 (`data` 字段)

| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `id` | integer | 模块ID |
| `name` | string | 模块名称 |
| `subTitle` | string | 子标题 |
| `moduleType` | string | 模块类型 |
| `sort` | integer | 排序 |
| `lang` | string | 语言包 |
| `configs` | array | 关联的配置列表 (结构同请求参数中的 configs) |

---

## 6. 获取所有模块列表

*   **URL**: `/v2/module/list`
*   **Method**: `GET`
*   **描述**: 获取所有模块列表（包含配置项），已按 `sort` 字段升序排序。返回的数据结构与新增/更新接口的请求参数结构完全一致。

### 响应参数 (`data` 字段)

| 字段名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `data` | array | 模块详情列表 (结构同单个模块详情) |