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适配类型与归一化函数
This commit is contained in:
duanshuwen committed 2026-08-18 20:00:25 +08:00
1 parent ca6f9397e0
commit cda8069630
11 files changed
+475 -512

No files matched your search

+7 -50
View File
@@ -11,13 +11,13 @@
## 接口清单
| 方法 | 路径 | 鉴权 | 用途 |
| --- | --- | --- | --- |
| `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` | `/health` | 否 | 服务健康检查 |
| `GET` | `/api/public/site-config` | 否 | 获取启用的站点内容 |
| `POST` | `/api/public/auth/phone-login` | 否 | 微信手机号登录 |
| `GET` | `/api/public/auth/me` | Customer JWT | 获取当前客户 |
| `POST` | `/api/public/leads` | 否 | 提交出行需求 |
## 站点配置
@@ -103,46 +103,3 @@ type DemandForm = {
```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`,避免客户端继续依赖已撤下的接口。