d42f69bd47
- 新增后台用车服务配置模块，支持维护服务简介、优势与使用流程 - 新增需求线索管理页面，支持筛选、查看与更新用车线索状态 - 新增小程序用车需求页面，优化登录路径与回跳逻辑 - 优化车型卡片跳转与用车需求提交功能 - 新增服务端API与数据处理逻辑，完善权限校验 - 更新全站配置与API文档，新增相关测试用例
61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
# 页面模块配置 API 契约
|
||
|
||
本文档补充 `WonderQ-Admin` 和 `WonderQ-Admin-UI` 对站点页面模块的维护约定。接口路径保持现有实现不变，所有 JSON 响应遵循 [三端统一 API 响应契约](./api-response-contract.md)。
|
||
|
||
## 接口清单
|
||
|
||
除登录接口外，所有接口需要 `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 列表排序 |
|
||
|
||
允许的 `module`：`heroSlides`、`destinationHero`、`demandHero`、`demandFeatureCards`、`demandForm`、`vehicleOptions`、`vehicleService`。
|
||
|
||
## 响应约定
|
||
|
||
列表、详情、删除和排序的业务字段放在 `data` 内：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"heroSlides": [],
|
||
"destinationHero": [],
|
||
"demandHero": [],
|
||
"demandFeatureCards": [],
|
||
"demandForm": [],
|
||
"vehicleOptions": [],
|
||
"vehicleService": []
|
||
}
|
||
}
|
||
```
|
||
|
||
创建接口返回：
|
||
|
||
```json
|
||
{
|
||
"code": 201,
|
||
"msg": "success",
|
||
"data": {
|
||
"id": "module-item-001"
|
||
}
|
||
}
|
||
```
|
||
|
||
排序请求必须提交当前模块的完整 `itemIds`，不能重复；成功返回 `data: { "items": [] }`。删除成功返回 `data: { "id": "..." }`。参数错误、资源不存在和服务异常分别使用统一契约的 `400`、`404` 和 `500` 响应。
|
||
|
||
## 字段边界
|
||
|
||
- `GET` 返回启用和停用的完整记录，前端负责显示状态。
|
||
- `sortOrder` 为从 `0` 开始的非负整数，后端负责重新规范化。
|
||
- 图片字段保存最终 HTTP(S) URL，不接受 base64。
|
||
- `demandForm` 为单例模块，不执行无意义的排序。
|
||
- `vehicleService` 为单例用车服务配置，不支持排序；`serviceSections`、`processSteps` 使用 `{title, description}` 数组，`advantages` 使用字符串数组。
|
||
- 站点模块只负责站点配置；首页内容、玩法、详情、管家和客片案例使用各自领域文档。
|