mzl92
b89ac48dd8
- PublicApiController 新增 staffList()：通过 user_roles 关联筛选业务人员 - 返回 id/name/sn/phone/email，支持 keyword 模糊匹配，不分页全量返回 - 路由组新增 /common/public/staff/list - .gitignore 忽略 docs/*.sql（数据导出文件，不入库） Co-Authored-By: Claude <noreply@anthropic.com>
226 lines
4.2 KiB
Markdown
226 lines
4.2 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 | 车型名称 |
|
||
|
||
---
|
||
|
||
### 3. 业务人员列表
|
||
|
||
查询业务人员（角色 role_id=2，在职），全量返回。
|
||
|
||
**请求**
|
||
|
||
```
|
||
GET /common/public/staff/list
|
||
```
|
||
|
||
**参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| keyword | string | 否 | 关键词，模糊匹配姓名/编号/电话/邮箱 |
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"code": 200,
|
||
"message": "请求成功",
|
||
"data": [
|
||
{
|
||
"id": 17,
|
||
"name": "张三",
|
||
"sn": "S0017",
|
||
"phone": "13800138000",
|
||
"email": "zhangsan@example.com"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**字段说明**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | int | 用户ID |
|
||
| name | string | 姓名 |
|
||
| sn | string | 编号 |
|
||
| phone | string | 电话 |
|
||
| email | 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"
|
||
|
||
# 查询业务人员列表
|
||
curl -H "Fdesk-Api-Key: your-api-key" \
|
||
"https://your-domain.com/common/public/staff/list?page=1&page_size=50"
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- 两个接口仅返回审批状态为"已通过"（approval_status=2）的备货单数据
|
||
- 已删除的备货单不会出现在查询结果中
|
||
- 接口为只读，不支持新增、修改、删除操作
|
||
- `pi_no` 和 `vin` 筛选参数支持模糊匹配（包含即可）
|