WonderQ-Project/docs/public-api.md

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>。

成功响应：

{ "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	否	来源页面标识

成功响应：

{ "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，避免客户端继续依赖已撤下的接口。