# stock.stockWarehouse 前端查询规则 ## 目的 本文档约束 `stock.stockWarehouse` 的 `where` 构造格式,便于前端统一构建查询条件,并与后端解析器保持一致。 ## 接口入口 - 路由:`POST /system` - method:`stock.stockWarehouse` ## 请求体结构 ```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.` 支持: - `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。 - 对空输入不构造条件,减少无效查询。