# WonderQ MiniAPP Public API

本文档是 `WonderQ-MiniAPP` 当前使用的 Public API 契约。接口只提供站点内容、登录和出行需求提交能力。

## 基础约定

- API 前缀：`/api/public`。
- 响应使用 JSON；时间使用 ISO 8601 字符串。
- H5 本地开发通过 `/api` 代理访问后端。
- 内容接口失败时，MiniAPP 使用 `src/content.ts` 的本地兜底内容。

## 接口清单

| 方法 | 路径 | 鉴权 | 用途 |
| --- | --- | --- | --- |
| `GET` | `/health` | 否 | 服务健康检查 |
| `GET` | `/api/public/site-config` | 否 | 获取启用的站点内容 |
| `POST` | `/api/public/auth/phone-login` | 否 | 微信手机号登录 |
| `GET` | `/api/public/auth/me` | Customer JWT | 获取当前客户 |
| `POST` | `/api/public/leads` | 否 | 提交出行需求 |

## 站点配置

`GET /api/public/site-config` 返回以下稳定数组字段：

```ts
type SiteConfig = {
  heroSlides: HeroSlide[];
  destinationHero: DestinationHero[];
  vehicleOptions: VehicleOption[];
  demandHero: DemandHero[];
  demandFeatureCards: DemandFeatureCard[];
  demandForm: DemandForm[];
};
```

Public 响应只返回启用内容，其余模块按 `isActive` 过滤。

### 通用字段

站点模块通常包含 `id`、`createdAt`、`updatedAt`、`isActive` 和 `sortOrder`。客户端按 `sortOrder` 消费排序模块，不依赖固定 ID。

### 需求配置

```ts
type DemandHero = {
  id: string;
  title: string;
  kicker: string | null;
  description: string | null;
  steps: string[];
  isActive: boolean;
  sortOrder: number;
};

type DemandFeatureCard = {
  id: string;
  title: string;
  description: string | null;
  isActive: boolean;
  sortOrder: number;
};

type DemandForm = {
  id: string;
  destinationLabel: string;
  destinationPlaceholder: string | null;
  phoneLabel: string;
  phonePlaceholder: string | null;
  noteLabel: string;
  notePlaceholder: string | null;
  submitLabel: string;
  chips: string[];
  isActive: boolean;
};
```

## 登录接口

### `POST /api/public/auth/phone-login`

请求：

```json
{ "code": "wechat-phone-code" }
```

成功响应：

```json
{
  "token": "<customer-jwt>",
  "customer": { "id": "customer-id", "phoneMasked": "138****0000" }
}
```

### `GET /api/public/auth/me`

请求头：`Authorization: Bearer <customer-jwt>`。

成功响应：

```json
{ "id": "customer-id", "phoneMasked": "138****0000" }
```

## 出行需求

### `POST /api/public/leads`

请求字段：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `destination` | `string` | 否 | 目的地或玩法 |
| `phone` | `string` | 是 | 联系方式，长度 2-64 |
| `travelDate` | `datetime` | 否 | 支持 `YYYY-MM-DD` |
| `peopleCount` | `number` | 否 | 大于 0 |
| `budgetMin` | `number` | 否 | 不小于 0 |
| `budgetMax` | `number` | 否 | 不小于 0 |
| `note` | `string` | 否 | 最长 1000 字符 |
| `sourcePage` | `string` | 否 | 来源页面标识 |

成功响应：

```json
{ "id": "lead-id", "status": "new" }
```

## 错误约定

- 未登录访问客户接口：`401`，消息为“请先登录”。
- 参数校验失败：`422`。
- 微信登录未配置：`503`。
- 微信登录凭证无效：`400`。

## MiniAPP 依赖

- 启动时只请求 `GET /api/public/site-config`。
- 首页使用 `heroSlides` 与 `vehicleOptions`。
- 需求提交只通过 `POST /api/public/leads`，失败时显示统一错误状态并保留本地表单内容。

## 验证建议

- 验证 `site-config` 的模块字段始终为数组。
- 验证 Public 内容只返回启用状态的数据。
- 验证需求请求不接受未知关联字段，并覆盖日期、联系方式和预算校验。
- 验证旧内容路径返回 `404`，避免客户端继续依赖已撤下的接口。