# 页面模块配置 Admin API 契约

本文档约束 `WonderQ-Admin-UI` 对站点结构模块的 CRUD、排序和字段白名单。

## 适用模块

| 模块 | 用途 |
| --- | --- |
| `heroSlides` | 首页顶部轮播 |
| `destinationHero` | 目的地页主视觉 |
| `demandHero` | 需求页主视觉 |
| `demandFeatureCards` | 需求页能力卡片 |
| `demandForm` | 需求提交表单 |
| `vehicleOptions` | 万趣用车卡片 |

## 通用规则

- 路径：`/api/admin/site-config/{module}`。
- 所有模块项都使用字符串 `id`；排序项使用整数 `sortOrder`。
- 创建、更新、删除和排序均需要后台 JWT。
- 后端只接受模块字段白名单，未知字段会被忽略。
- `demandForm` 是单例模块，重复创建返回 `409`。
- `demandForm` 不支持排序；其他模块支持排序。
- 所有变更写入审计日志，并在成功提交后返回最新模块项。

## 类型

```ts
type SiteModule =
  | "heroSlides"
  | "destinationHero"
  | "demandHero"
  | "demandFeatureCards"
  | "demandForm"
  | "vehicleOptions"

type SiteItemPatch = {
  title?: string;
  kicker?: string | null;
  image?: string | null;
  description?: string | null;
  steps?: string[];
  destinationLabel?: string;
  destinationPlaceholder?: string | null;
  phoneLabel?: string;
  phonePlaceholder?: string | null;
  noteLabel?: string;
  notePlaceholder?: string | null;
  submitLabel?: string;
  chips?: string[];
  targetType?: string | null;
  targetValue?: string | null;
  isActive?: boolean;
  sortOrder?: number;
};
```

## 获取完整配置

### `GET /api/admin/site-config`

返回所有模块数组，包括停用项：

```ts
{
  heroSlides: unknown[];
  destinationHero: unknown[];
  demandHero: unknown[];
  demandFeatureCards: unknown[];
  demandForm: unknown[];
  vehicleOptions: unknown[];
}
```

空模块必须返回 `[]`，不能返回 `null` 或省略字段。

## CRUD

### 新增

```http
POST /api/admin/site-config/{module}
Authorization: Bearer <admin-jwt>
Content-Type: application/json
```

请求体使用 `SiteItemPatch`。成功返回 `201` 和新建模块项。各模块的主字段如下：

| 模块 | 主字段 |
| --- | --- |
| `heroSlides` | `title` |
| `destinationHero` | `title` |
| `demandHero` | `title` |
| `demandFeatureCards` | `title` |
| `demandForm` | `submitLabel` |
| `vehicleOptions` | `title` |

缺少主字段返回 `422 MODULE_CONFIG_VALIDATION_ERROR`。模块不存在返回 `400 MODULE_CONFIG_FORBIDDEN`。

### 更新

```http
PATCH /api/admin/site-config/{module}/{id}
```

只更新该模块允许的字段；不存在的 ID 返回 `404 MODULE_CONFIG_NOT_FOUND`。

### 删除

```http
DELETE /api/admin/site-config/{module}/{id}
```

成功返回 `{ "id": "..." }`。删除后，排序模块会重新从 0 开始编号。

### 排序

```http
PATCH /api/admin/site-config/{module}/reorder
Content-Type: application/json

{ "itemIds": ["id-2", "id-1"] }
```

`itemIds` 必须刚好包含当前模块的全部 ID，且不能重复。否则返回 `400 MODULE_CONFIG_REORDER_INVALID`。不支持排序的模块返回 `400 MODULE_CONFIG_REORDER_UNSUPPORTED`。

## 模块字段补充

- `demandForm` 的 `chips` 会过滤空白值；表单只保留一条配置。

## 删除范围边界

模块配置只维护站点内容，不负责客户、线索或订单数据。接口变更必须同步 `src/api.ts`、`src/types/admin.ts` 和本文档。