59 lines
3.3 KiB
Markdown
59 lines
3.3 KiB
Markdown
# 首页站点配置 API 契约
|
||
|
||
本文档约束 `WonderQ-Admin` 与 `WonderQ-Admin-UI-Vue` 对首页站点模块的维护。旧目的地主视觉、需求页主视觉、需求页特色卡片、需求表单、独立体验推荐、旧团队共创/极境视界页面和旧发布重置配置不再属于当前契约。
|
||
|
||
## 接口清单
|
||
|
||
除登录接口外，所有接口需要 `Authorization: Bearer <admin-jwt>`。
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/admin/site-config` | 获取顶部轮播和万趣用车配置 |
|
||
| `POST` | `/api/admin/site-config/{module}` | 新增配置项，成功 `201` |
|
||
| `PATCH` | `/api/admin/site-config/{module}/{id}` | 更新配置项 |
|
||
| `DELETE` | `/api/admin/site-config/{module}/{id}` | 删除配置项 |
|
||
| `PATCH` | `/api/admin/site-config/{module}/reorder` | 按完整 ID 列表排序 |
|
||
| `GET` | `/api/admin/home/play-recommendations` | 获取首页玩法推荐 |
|
||
| `GET` | `/api/admin/home/team-buildings` | 获取首页团队共创 |
|
||
| `GET` | `/api/admin/home/wild-archives` | 获取首页极境视界 |
|
||
|
||
允许的站点 `module` 只有：`heroSlides`、`vehicleOptions`。
|
||
|
||
首页工作台的五个业务区域为：顶部轮播、玩法推荐、万趣用车、团队共创、极境视界。后面四项使用各自首页内容接口或玩法领域接口维护，不再通过旧的单例站点模块承载。
|
||
|
||
## 响应约定
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"heroSlides": [],
|
||
"vehicleOptions": []
|
||
}
|
||
}
|
||
```
|
||
|
||
创建接口返回：
|
||
|
||
```json
|
||
{
|
||
"code": 201,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": "module-item-001"
|
||
}
|
||
}
|
||
```
|
||
|
||
排序请求必须提交当前模块的完整 `itemIds`，不能重复；成功返回 `data: { "items": [] }`。删除成功返回 `data: { "id": "..." }`。参数错误、资源不存在和服务异常分别使用统一契约的 `400`、`404` 和 `500` 响应。
|
||
|
||
## 字段边界
|
||
|
||
- `GET /api/admin/site-config` 返回启用和停用的完整记录，前端负责显示状态。
|
||
- `sortOrder` 为从 `0` 开始的非负整数，后端负责重新规范化。
|
||
- 图片字段保存最终公网 HTTP(S) URL，不接受 base64；管理端上传组件通过媒体上传接口先取得 URL，再提交配置。后端使用 `OSS_ENDPOINT` 上传、使用 `OSS_PUBLIC_BASE_URL` 生成客户端访问地址，不能持久化 OSS 内网 Host。OSS 私有读场景下，接口响应会为 OSS 图片 URL 临时追加短时 GET 签名，供管理端和 Public API 回显；后端会在每次响应时重新签名，签名参数不应由客户端自行拼接或长期缓存。历史内网 URL 在响应时会自动切换到公网 Host。
|
||
- `POST /api/admin/media-assets/upload` 只创建素材库记录，不会自动修改 `heroSlides` 或 `vehicleOptions`。将图片用于首页配置时，必须把返回的 `data.url` 写入对应编辑表单，并继续提交对应的 `POST` 或 `PATCH /api/admin/site-config/{module}/{id}`；成功后才会在 `GET /api/admin/site-config` 中返回该图片。
|
||
- 首页玩法推荐、团队共创和极境视界保留独立的新增、编辑、删除、启停和排序能力，保存后由 Public API 直接提供给 MiniAPP。
|
||
- 旧需求页主视觉、特色卡片、需求表单、体验推荐、用车服务说明等表结构已由后续 Alembic 迁移删除，不能在新代码中重新声明或调用。
|