168 lines
2.7 KiB
Markdown
168 lines
2.7 KiB
Markdown
# stock.warehouse.list 前端查询规则
|
||
|
||
## 目的
|
||
|
||
本文档约束 `stock.warehouse.list` 的 `where` 构造格式,便于前端统一构建查询条件,并与后端解析器保持一致。
|
||
|
||
## 接口入口
|
||
|
||
- 路由:`POST /system`
|
||
- method:`stock.warehouse.list`
|
||
|
||
## 请求体结构
|
||
|
||
```json
|
||
{
|
||
"pagination": {
|
||
"page": 1,
|
||
"pageSize": 20
|
||
},
|
||
"where": {
|
||
"item_code": {
|
||
"operator": "like",
|
||
"value": "SKU",
|
||
"type": "text"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## where 字段规则
|
||
|
||
`where` 必须是对象,且每个字段值也必须是对象。
|
||
|
||
正确示例:
|
||
|
||
```json
|
||
{
|
||
"where": {
|
||
"item_name": {
|
||
"operator": "like",
|
||
"value": "鞋",
|
||
"type": "text"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
错误示例(会返回解析失败原因):
|
||
|
||
```json
|
||
{
|
||
"where": {
|
||
"item_name": "鞋"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 条件对象结构
|
||
|
||
每个 `where.<field>` 支持:
|
||
|
||
- `operator`:操作符,默认 `eq`
|
||
- `value`:查询值
|
||
- `type`:值类型(可选)
|
||
- `field`:映射到真实字段(一般不需要前端传)
|
||
|
||
### 支持操作符
|
||
|
||
- `eq`
|
||
- `ne`
|
||
- `like` / `contains`
|
||
- `startswith`
|
||
- `endswith`
|
||
- `gt`
|
||
- `lt`
|
||
- `ge`
|
||
- `le`
|
||
- `in`
|
||
- `notin`
|
||
- `between`
|
||
- `notbetween`
|
||
- `isnull`
|
||
- `isnotnull`
|
||
- `regexp`
|
||
- `notregexp`
|
||
|
||
### 支持 type
|
||
|
||
- `boolean`:转换为 `Y/N`
|
||
- `number`:转换为数字
|
||
- `date`:日期字符串归一化
|
||
- `daterange`:日期数组归一化
|
||
- `text`:逗号分隔字符串拆分数组
|
||
|
||
## 特殊字段说明
|
||
|
||
### barcode
|
||
|
||
- 在条码表中先匹配,再回灌 `stock_id` 过滤主表。
|
||
- 推荐:`operator=eq|like`。
|
||
|
||
### prohibited_type
|
||
|
||
- 传入的是违禁品类型 `id`。
|
||
- 后端会映射到关联模型进行过滤。
|
||
|
||
## 空值处理
|
||
|
||
以下值会被视为“空条件”并跳过:
|
||
|
||
- `null`
|
||
- `undefined`
|
||
- `""`
|
||
- `[]`
|
||
|
||
## 排序规则
|
||
|
||
后端只接受以下排序字段:
|
||
|
||
- `id`
|
||
- `item_code`
|
||
- `item_name`
|
||
- `quantity`
|
||
- `locked_quantity`
|
||
- `tag_price`
|
||
- `retail_price`
|
||
- `create_at`
|
||
- `update_at`
|
||
|
||
当传入非法排序字段时,会回退为:
|
||
|
||
- `sortField=create_at`
|
||
- `sortOrder=DESC`
|
||
|
||
## 失败返回(解构失败)
|
||
|
||
当 `where` 结构不合法时,返回示例:
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "筛选条件解析失败: 字段 item_code 条件必须是对象",
|
||
"data": {
|
||
"list": [],
|
||
"pagination": {
|
||
"page": 1,
|
||
"pageSize": 20,
|
||
"total": 0,
|
||
"totalPages": 0,
|
||
"hasPrevious": false,
|
||
"hasNext": false
|
||
},
|
||
"summary": {
|
||
"total_quantity": 0,
|
||
"total_locked": 0,
|
||
"total_available": 0,
|
||
"total_items": 0
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 前端建议
|
||
|
||
- 对 `in/notin/between/notbetween` 先做数组校验,再发请求。
|
||
- 对 `where` 做 schema 校验,避免后端 400。
|
||
- 对空输入不构造条件,减少无效查询。
|