fdesk/docs/public-stock-api.md

# 备货单公共 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` 筛选参数支持模糊匹配（包含即可）