cda8069630
- 删除backend-plan.md、backend-api-service.md等多份过时项目文档 - 新增home-api.md规范首页三类内容的Admin API补充契约 - 更新docs/README.md的文档清单与展示格式 - 优化integration-workflow.md、admin-api-requirements.md等文档的表格与内容 - 为WonderQ-MiniAPP的homeExperienceData.ts新增API适配类型与归一化函数
106 lines
2.6 KiB
Markdown
106 lines
2.6 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" }
|
||
```
|