aitori-bi-v2/doc/MODULE_API.md

首页模块管理 API 文档

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

1. 全局响应结构

所有接口的返回值均由 GlobalResponseWrapper 统一包装，遵循以下 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	是	排序值

请求示例:

[
  { "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	模块详情列表 (结构同单个模块详情)