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:
1 parent
ca6f9397e0
commit
cda8069630
11 files changed
+475
-512
No files matched your search
+7
-50
@@ -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`,避免客户端继续依赖已撤下的接口。
|
||||
Reference in new issue
Block a user