WMS_MAIN/docs/stock-stockWarehouse-query-rules.md
2026-03-25 18:12:04 +08:00

168 lines
2.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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。
- 对空输入不构造条件,减少无效查询。