WEB/stock-stockWarehouse-query-rules.md

2.7 KiB
Raw Blame History

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:操作符,默认 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 结构不合法时,返回示例:

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