Files

duanshuwen cda8069630 docs: 清理过时文档，新增首页API契约并更新相关内容

- 删除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适配类型与归一化函数

2026-08-18 20:00:25 +08:00

2.6 KiB

Raw Blame History

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 返回以下稳定数组字段：

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

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

通用字段

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

需求配置

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`

请求：

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

成功响应：

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

`GET /api/public/auth/me`

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