# 供应商申诉筛选

> 运营后台「供应商申诉」页新增订单号筛选（全部申诉 Tab）与售后单号筛选（售后申诉 Tab），列表与导出共用 POST /order/complain/list

- 类型：前端对接
- 分类：供应商
- 端：运营后台
- 后端服务：admin
- 状态：已上测
- 测试分支：bulky-test/admin
- 需求单：XYLZ-3628
- 更新：2026-10-28
- 网页版：https://doc.xfun.fun/supplier-appeal-filter-api

## 总览

运营后台「供应商申诉」页（商品申诉 / 售后申诉 / 处罚申诉 / 农资售后申诉 四个 Tab）的筛选栏新增两个输入框：

- **订单号**：四个 Tab 都展示。
- **售后单号**：仅「售后申诉」Tab 展示，按售后 ID 检索，即列表「关联订单/商品/售后」列里的「售后ID」。

只涉及一个接口，列表与导出共用，**出参不变**，只新增两个入参。

| # | 接口 | 用途 | 何时调用 |
|----|----|----|----|
| ① | `POST /order/complain/list` | 申诉列表 / 导出（`exportFlag=1`） | 进入页面、切换 Tab、点「搜索」「导出」 |

## 通用约定

- 服务：运营后台 admin；需登录 token，未登录返回 `{ "code": 2, "msg": "登录失效，请重新登录~" }`。
- `POST` + JSON，返回 `{ "code": 0, "msg": "success", "data": … }`；`code != 0` 时 `msg` 直接 toast。
- 分页入参 `index`（页码，从 1 开始，不传默认 1）、`size`（每页条数，不传默认 10）、`searchCount`（是否查总数，默认 true，可不传）。
- 分页出参为 `{ index, size, searchCount, total, records, other }`，记录在 `records`，总数在 `total`；`other` 为附加数据，本接口通常为 null。

## 枚举

#### 申诉类型 complainType

1 商品申诉 · 2 售后申诉（退款支出） · 3 处罚申诉 · 5 农资售后申诉 · 6 缺货赔付申诉 · 4 为历史保留值，不可传

#### 各 Tab 的类型入参

| Tab | 类型入参 | 展示「订单号」输入框 | 展示「售后单号」输入框 |
|----|----|----|----|
| 商品申诉 | `complainTypeList: [1, 2, 6]` | 是 | 否 |
| 售后申诉 | `complainType: 2` | 是 | 是 |
| 处罚申诉 | `complainType: 3`（可带 `punishType`） | 是 | 否 |
| 农资售后申诉 | `complainType: 5` | 是（填农资订单号） | 否 |

## 接口

### POST /order/complain/list · 申诉列表

**变更**：新增入参 `orderSn`、`refundId`，其余入参与出参不变。

#### 请求参数（本次新增）

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| `orderSn` | String | 否 | 订单号，**精确匹配**，前后空格自动忽略，最长 64 字，超长提示「订单号不能超过64字」。农资售后申诉 Tab 填农资订单号 |
| `refundId` | Long | 否 | 售后ID，**精确匹配**，正整数，小于 1 提示「售后ID参数错误」。仅类型 2、5 生效 |

其余已有入参（`index`、`size`、`complainType`、`complainTypeList`、`punishType`、`status`、`startTime`、`endTime`、`supplierName`、`userId`、`wareFlag`、`wareId`、`wareIdList`、`partnerId`、`partnerIdList`、`supplierTag`、`exportFlag`）含义不变。

#### 请求示例

```json
{
  "index": 1,
  "size": 10,
  "complainType": 2,
  "orderSn": "20261020664485772268",
  "refundId": 5181760
}
```

#### 响应

出参结构不变；没有符合条件的记录时返回空分页（`total` 为 0，`records` 为空数组），不报错。

#### 响应示例（无匹配）

```json
{
  "code": 0,
  "msg": "success",
  "data": { "index": 1, "size": 10, "total": 0, "records": [] }
}
```

#### 规则

- `orderSn` 与 `refundId` 同时填写时是「且」关系，两个都满足才返回。
- 两个新条件与已有条件（状态、时间、供应商、渠道、基地等）也是「且」关系。
- `orderSn`：在当前 Tab 的申诉类型范围内，按关联订单号匹配；处罚申诉里没有订单号的处罚（质检、行政处罚等）按订单号查不到，属正常。
- `refundId`：只在售后申诉（2）和农资售后申诉（5）里匹配。在「商品申诉」Tab 传 `refundId` 不会命中评价或缺货赔付申诉，「处罚申诉」Tab 传则返回空列表。前端只在「售后申诉」Tab 传该字段，其他 Tab 不要透传。
- `orderSn` 和 `refundId` 为空字符串或不传时，等同于不筛选。
- 导出（`exportFlag=1`）使用同一组筛选条件，导出结果与列表一致；无匹配时导出空表。
- 时间区间校验照常进行：开始、结束时间不合法时仍返回参数错误，不会因为订单号查不到而变成空列表。

#### 错误码 / 失败文案

- 订单号不能超过64字
- 售后ID参数错误

## 联调注意

- 测试环境：运营后台 admin 测试服已部署，分支 `bulky-test/admin`。
- 「售后单号」输入框内容用列表「售后ID」列展示的数字即可，例如 `5181760`。
- 订单号请输入完整订单号，不支持模糊匹配。