# 首页站点配置 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 私有读场景下，接口响应会为 OSS 图片 URL 临时追加短时 GET 签名，供管理端和 Public API 回显；后端会在每次响应时重新签名，签名参数不应由客户端自行拼接或长期缓存。
- `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 迁移删除，不能在新代码中重新声明或调用。