548f91c37f
- 移除后端产品、目的地、活动专题等废弃模块的数据库表与业务代码，删除冗余API接口 - 删除小程序端详情页、线路组件等冗余代码，移除搜索工具与测试用例，调整导航逻辑 - 清理管理端废弃的类型定义、编辑器与测试代码 - 更新项目文档，修正模块维护说明与接口文档内容
149 lines
3.7 KiB
Markdown
149 lines
3.7 KiB
Markdown
# 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`，避免客户端继续依赖已撤下的接口。
|