2.7 KiB
2.7 KiB
stock.stockWarehouse 前端查询规则
目的
本文档约束 stock.stockWarehouse 的 where 构造格式,便于前端统一构建查询条件,并与后端解析器保持一致。
接口入口
- 路由:
POST /system - method:
stock.stockWarehouse
请求体结构
{
"pagination": {
"page": 1,
"pageSize": 20
},
"where": {
"item_code": {
"operator": "like",
"value": "SKU",
"type": "text"
}
}
}
where 字段规则
where 必须是对象,且每个字段值也必须是对象。
正确示例:
{
"where": {
"item_name": {
"operator": "like",
"value": "鞋",
"type": "text"
}
}
}
错误示例(会返回解析失败原因):
{
"where": {
"item_name": "鞋"
}
}
条件对象结构
每个 where.<field> 支持:
operator:操作符,默认eqvalue:查询值type:值类型(可选)field:映射到真实字段(一般不需要前端传)
支持操作符
eqnelike/containsstartswithendswithgtltgeleinnotinbetweennotbetweenisnullisnotnullregexpnotregexp
支持 type
boolean:转换为Y/Nnumber:转换为数字date:日期字符串归一化daterange:日期数组归一化text:逗号分隔字符串拆分数组
特殊字段说明
barcode
- 在条码表中先匹配,再回灌
stock_id过滤主表。 - 推荐:
operator=eq|like。
prohibited_type
- 传入的是违禁品类型
id。 - 后端会映射到关联模型进行过滤。
空值处理
以下值会被视为“空条件”并跳过:
nullundefined""[]
排序规则
后端只接受以下排序字段:
iditem_codeitem_namequantitylocked_quantitytag_priceretail_pricecreate_atupdate_at
当传入非法排序字段时,会回退为:
sortField=create_atsortOrder=DESC
失败返回(解构失败)
当 where 结构不合法时,返回示例:
{
"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。 - 对空输入不构造条件,减少无效查询。