mzl92
35d98c16e9
- 新增 ApiKeyAuth 中间件（hash_equals 防时序攻击） - 新增 PublicApiController（piList/vinList 两个只读接口） - 仅返回已审批通过（approval_status=2）的数据，支持分页和模糊搜索 - LIKE 通配符已转义，异常信息不暴露内部细节 - 附对接文档 docs/public-stock-api.md Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
175 lines
3.3 KiB
Markdown
175 lines
3.3 KiB
Markdown
# 备货单公共 API 对接文档
|
||
|
||
## 基础信息
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| Base URL | `https://your-domain.com` |
|
||
| 鉴权方式 | 请求头 `Fdesk-Api-Key` |
|
||
| 响应格式 | JSON |
|
||
|
||
## 鉴权
|
||
|
||
所有请求必须携带 API Key 请求头：
|
||
|
||
```
|
||
Fdesk-Api-Key: <your-api-key>
|
||
```
|
||
|
||
缺少或无效时返回：
|
||
|
||
```json
|
||
{
|
||
"status": "fail",
|
||
"code": 401,
|
||
"message": "无效的 API Key",
|
||
"data": []
|
||
}
|
||
```
|
||
|
||
## 通用响应结构
|
||
|
||
```json
|
||
{
|
||
"status": "success | fail",
|
||
"code": 200,
|
||
"message": "描述信息",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
| code | 含义 |
|
||
|------|------|
|
||
| 200 | 成功 |
|
||
| 400 | 查询失败 |
|
||
| 401 | API Key 无效或缺失 |
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. PI 号列表
|
||
|
||
查询已审批通过的备货单 PI 号，含关联的车架号和车型。
|
||
|
||
**请求**
|
||
|
||
```
|
||
GET /common/public/pi/list
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | int | 否 | 页码，默认 1 |
|
||
| page_size | int | 否 | 每页条数，默认 20，最大 200 |
|
||
| pi_no | string | 否 | PI 号筛选，模糊匹配 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"code": 200,
|
||
"message": "请求成功",
|
||
"data": {
|
||
"total": 150,
|
||
"per_page": 20,
|
||
"current_page": 1,
|
||
"data": [
|
||
{
|
||
"pi_no": "PI20250601001",
|
||
"vins": ["LSVAU2A39N2123456", "LSVAU2A39N2123457"],
|
||
"model_names": ["BYD Song Plus DM-i", "BYD Seal"]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| pi_no | string | 备货单 PI 号 |
|
||
| vins | string[] | 该 PI 下所有车架号 |
|
||
| model_names | string[] | 该 PI 下所有车型名称（与 vins 一一对应） |
|
||
|
||
---
|
||
|
||
### 2. VIN 号列表
|
||
|
||
查询已审批通过的备货单车架号及对应车型。
|
||
|
||
**请求**
|
||
|
||
```
|
||
GET /common/public/vin/list
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| page | int | 否 | 页码，默认 1 |
|
||
| page_size | int | 否 | 每页条数，默认 20，最大 200 |
|
||
| vin | string | 否 | 车架号筛选，模糊匹配 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"code": 200,
|
||
"message": "请求成功",
|
||
"data": {
|
||
"total": 500,
|
||
"per_page": 20,
|
||
"current_page": 1,
|
||
"data": [
|
||
{
|
||
"vin": "LSVAU2A39N2123456",
|
||
"model_name": "BYD Song Plus DM-i"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| vin | string | 车架号 |
|
||
| model_name | string | 车型名称 |
|
||
|
||
---
|
||
|
||
## 调用示例
|
||
|
||
```bash
|
||
# 查询 PI 列表（第一页，每页10条）
|
||
curl -H "Fdesk-Api-Key: your-api-key" \
|
||
"https://your-domain.com/common/public/pi/list?page=1&page_size=10"
|
||
|
||
# 按 PI 号搜索
|
||
curl -H "Fdesk-Api-Key: your-api-key" \
|
||
"https://your-domain.com/common/public/pi/list?pi_no=PI202506"
|
||
|
||
# 查询 VIN 列表（第一页，每页50条）
|
||
curl -H "Fdesk-Api-Key: your-api-key" \
|
||
"https://your-domain.com/common/public/vin/list?page=1&page_size=50"
|
||
|
||
# 按 VIN 号搜索
|
||
curl -H "Fdesk-Api-Key: your-api-key" \
|
||
"https://your-domain.com/common/public/vin/list?vin=LSVAU2A3"
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- 两个接口仅返回审批状态为"已通过"（approval_status=2）的备货单数据
|
||
- 已删除的备货单不会出现在查询结果中
|
||
- 接口为只读，不支持新增、修改、删除操作
|
||
- `pi_no` 和 `vin` 筛选参数支持模糊匹配（包含即可）
|