sqxp/docs/接口校验规则.md

叁强鲜配 - 接口输入校验规则

目录

• 一、校验规则概述
• 二、通用校验规则
• 三、用户模块校验规则
• 四、地址模块校验规则
• 五、商品模块校验规则
• 六、订单模块校验规则
• 七、配送模块校验规则
• 八、询价报价模块校验规则
• 九、价格模块校验规则
• 十、结算模块校验规则
• 十一、支付模块校验规则
• 十二、其他模块校验规则

---

一、校验规则概述

1.1 校验层次

层次	说明	执行位置
前端校验	提升用户体验，减轻服务器压力	前端页面
后端校验	确保数据安全性和完整性	后端API
数据库校验	最后一道防线，确保数据一致性	数据库约束

1.2 校验类型

类型	说明	示例
必填校验	参数不能为空	username不能为空
类型校验	参数类型正确	page必须为整数
格式校验	参数格式正确	phone必须为11位手机号
范围校验	参数在允许范围内	quantity必须大于0
业务规则校验	符合业务逻辑	价格版本必须生效
权限校验	用户有操作权限	只有运营能创建用户

1.3 错误响应格式

{
  "code": 400,
  "message": "参数校验失败",
  "errors": [
    {
      "field": "username",
      "message": "用户名不能为空"
    }
  ]
}

---

二、通用校验规则

2.1 字符串类型校验

规则	说明	示例
非空	不能为空字符串、null、undefined	-
长度范围	在最小和最大长度之间	4-20字符
格式	符合特定格式	手机号、邮箱、身份证
枚举	在允许的值列表中	admin/supplier/client/deliver

2.2 数值类型校验

规则	说明	示例
非空	不能为null、undefined	-
数值范围	在最小和最大值之间	0-999999
精度	小数位数不超过指定值	最多4位小数
整数	必须为整数	page必须是整数

2.3 数组类型校验

规则	说明	示例
非空	数组不能为空	items.length > 0
元素类型	数组元素类型一致	items中每个都是对象
元素数量	元素数量在范围内	1-100个

2.4 日期类型校验

规则	说明	示例
非空	不能为空	-
格式	符合ISO 8601格式	2026-03-19T10:00:00+08:00
范围	在允许的时间范围内	不能早于当前时间

---

三、用户模块校验规则

3.1 登录接口 POST /api/web/auth/login

参数	类型	必填	校验规则	错误提示
username	string	是	非空，4-20字符	"用户名不能为空" / "用户名长度必须在4-20字符之间"
password	string	是	非空，6-20字符	"密码不能为空" / "密码长度必须在6-20字符之间"

3.2 修改密码接口 POST /api/web/user/change-password

参数	类型	必填	校验规则	错误提示
oldPassword	string	是	非空，6-20字符，与原密码一致	"原密码不能为空" / "原密码错误"
newPassword	string	是	非空，6-20字符，不能与原密码相同，复杂度符合要求	"新密码不能为空" / "新密码长度必须在6-20字符之间" / "新密码不能与原密码相同" / "密码复杂度不足"

密码复杂度要求

• 简单：仅字母或仅数字
• 中等：字母+数字
• 复杂：字母+数字+特殊字符

3.3 创建用户接口 POST /api/web/users

参数	类型	必填	校验规则	错误提示
username	string	是	非空，4-20字符，唯一性	"用户名不能为空" / "用户名已被注册"
realName	string	是	非空，2-50字符	"姓名不能为空" / "姓名长度必须在2-50字符之间"
phone	string	是	非空，11位手机号，格式正确	"手机号不能为空" / "手机号格式不正确"
role	string	是	枚举值：admin/supplier/client/deliver	"角色不正确"
regionId	string	否	当role为supplier/client/deliver时必填，对应区域存在	"区域不存在"

3.4 更新用户接口 PUT /api/web/users/{userId}

参数	类型	必填	校验规则	错误提示
realName	string	否	2-50字符	"姓名长度必须在2-50字符之间"
phone	string	否	11位手机号，格式正确	"手机号格式不正确"
regionId	string	否	对应区域存在	"区域不存在"
isActive	boolean	否	true/false	"状态值不正确"

3.5 用户列表查询 GET /api/web/users

参数	类型	必填	校验规则	错误提示
page	int	否	大于等于1	"页码必须大于等于1"
pageSize	int	否	1-100	"每页条数必须在1-100之间"
role	string	否	枚举值	"角色筛选值不正确"
isActive	boolean	否	true/false	"状态筛选值不正确"

---

四、地址模块校验规则

4.1 创建地址接口 POST /api/mini/client/addresses

参数	类型	必填	校验规则	错误提示
addressType	string	是	枚举值：pickup/delivery/both	"地址类型不正确"
contactPerson	string	是	非空，2-20字符	"联系人不能为空" / "联系人长度必须在2-20字符之间"
contactPhone	string	是	非空，11位手机号	"联系电话不能为空" / "手机号格式不正确"
province	string	是	非空	"省份不能为空"
city	string	是	非空	"城市不能为空"
district	string	否	-	-
detailAddress	string	是	非空，5-500字符	"详细地址不能为空" / "详细地址长度必须在5-500字符之间"
isDefault	boolean	否	true/false	-

4.2 地址类型说明

值	说明	适用场景
pickup	取货地址	供应商/客户设置取货点
delivery	配送地址	客户设置收货点
both	两者皆是	地址同时作为取货和配送点

---

五、商品模块校验规则

5.1 创建商品分类 POST /api/web/product-categories

参数	类型	必填	校验规则	错误提示
name	string	是	非空，2-100字符，唯一性	"分类名称不能为空" / "分类名称已存在"
parentId	string	否	对应分类存在或为空	"父分类不存在"
sortOrder	int	否	大于等于0	"排序值必须大于等于0"

5.2 创建商品单位 POST /api/web/product-units

参数	类型	必填	校验规则	错误提示
name	string	是	非空，1-50字符，唯一性	"单位名称不能为空" / "单位名称已存在"
code	string	是	非空，1-20字符，唯一性	"单位编码不能为空" / "单位编码已存在"

5.3 创建商品 POST /api/web/products

参数	类型	必填	校验规则	错误提示
name	string	是	非空，2-200字符	"商品名称不能为空" / "商品名称长度必须在2-200字符之间"
categoryId	string	是	对应分类存在	"商品分类不存在"
unitId	string	是	对应单位存在	"商品单位不存在"
description	string	否	最大1000字符	"商品描述长度不能超过1000字符"
imageUrl	string	否	合法的URL格式	"图片URL格式不正确"

5.4 查询商品列表 GET /api/web/products

参数	类型	必填	校验规则	错误提示
page	int	否	大于等于1	"页码必须大于等于1"
pageSize	int	否	1-100	"每页条数必须在1-100之间"
categoryId	string	否	对应分类存在	"商品分类不存在"
isActive	boolean	否	true/false	"状态筛选值不正确"

---

六、订单模块校验规则

6.1 订单预览 POST /api/mini/client/orders/preview

参数	类型	必填	校验规则	错误提示
priceListId	string	是	对应价格清单存在且状态为active	"价格清单不存在或已失效"
items	array	是	非空数组	"订单商品不能为空"
items[].productId	string	是	对应商品存在	"商品不存在"
items[].quantity	number	是	大于0，最多4位小数	"商品数量必须大于0"
addressId	string	是	对应地址存在且属于当前用户	"收货地址不存在"

6.2 创建订单 POST /api/mini/client/orders

参数	类型	必填	校验规则	错误提示
priceListId	string	是	对应价格清单存在且状态为active	"价格清单不存在或已失效"
items	array	是	非空数组	"订单商品不能为空"
items[].productId	string	是	对应商品存在	"商品不存在"
items[].unitId	string	是	对应单位存在	"单位不存在"
items[].quantity	number	是	大于0，最多4位小数	"商品数量必须大于0"
items[].unitPrice	number	是	大于0，2位小数，与价格清单一致	"商品价格不匹配"
addressId	string	是	对应地址存在且属于当前用户	"收货地址不存在"
paymentMethod	string	是	枚举值：wechat/offline	"支付方式不正确"
remark	string	否	最大500字符	"备注长度不能超过500字符"

6.3 从购物车创建订单 POST /api/mini/client/orders/from-cart

参数	类型	必填	校验规则	错误提示
priceListId	string	是	对应价格清单存在且状态为active	"价格清单不存在或已失效"
cartIds	array	是	非空数组，元素为购物车ID	"请选择要结算的商品"
addressId	string	是	对应地址存在且属于当前用户	"收货地址不存在"
paymentMethod	string	是	枚举值：wechat/offline	"支付方式不正确"
remark	string	否	最大500字符	"备注长度不能超过500字符"

6.4 取消订单

直接取消（未支付）POST /api/mini/client/orders/{orderId}/direct-cancel

参数	类型	必填	校验规则	错误提示
reason	string	否	最大200字符	"取消原因长度不能超过200字符"

申请取消（已支付）POST /api/mini/client/orders/{orderId}/cancel

参数	类型	必填	校验规则	错误提示
reason	string	是	非空，2-200字符	"取消原因不能为空" / "取消原因长度必须在2-200字符之间"

6.5 运营审核取消 POST /api/web/orders/{orderId}/review-cancel

参数	类型	必填	校验规则	错误提示
approved	boolean	是	true/false	"审核结果不正确"
reviewNote	string	否	最大200字符	"审核备注长度不能超过200字符"

6.6 运营分配配送 POST /api/web/orders/{orderId}/assign-delivery

参数	类型	必填	校验规则	错误提示
deliverId	string	是	对应配送员存在、状态正常、属于当前区域	"配送员不存在或不可用"

6.7 运营调整订单 POST /api/web/orders/{orderId}/adjust

参数	类型	必填	校验规则	错误提示
items	array	是	非空数组	"调整项不能为空"
items[].orderItemId	string	是	对应订单项存在	"订单项不存在"
items[].quantity	number	否	大于0，最多4位小数	"调整后数量必须大于0"
items[].status	string	否	枚举值：normal/reduced/deleted/substituted	"调整状态不正确"
items[].note	string	否	最大200字符	"备注长度不能超过200字符"
reason	string	是	非空，2-200字符	"调整原因不能为空" / "调整原因长度必须在2-200字符之间"
refundAmount	number	否	大于等于0，不超过已支付金额	"退款金额不正确"

6.8 催单 POST /api/mini/client/orders/{orderId}/urge

参数	类型	必填	校验规则	错误提示
-	-	-	订单状态为delivering或pending_confirm	"当前状态不允许催单"
-	-	-	当天催单次数小于3	"超出催单次数限制"

---

七、配送模块校验规则

7.1 运营分配配送任务 POST /api/web/delivery-tasks/assign

参数	类型	必填	校验规则	错误提示
orderId	string	是	对应订单存在、状态为pending_delivery	"订单不存在或状态不正确"
deliverId	string	是	对应配送员存在、状态正常、属于同一区域	"配送员不存在或不可用"

7.2 批量分配配送任务 POST /api/web/delivery-tasks/assign-batch

参数	类型	必填	校验规则	错误提示
assignments	array	是	非空数组，1-50个元素	"分配任务不能为空" / "批量分配数量不能超过50个"
assignments[].orderId	string	是	对应订单存在、状态为pending_delivery	"订单状态不正确"
assignments[].deliverId	string	是	对应配送员存在、状态正常	"配送员不存在或不可用"

7.3 配送员确认取货 POST /api/mini/deliverer/tasks/{taskId}/pickup

参数	类型	必填	校验规则	错误提示
remark	string	否	最大200字符	"备注长度不能超过200字符"
imageUrls	array	否	最多10个，每个为合法URL	"图片数量不能超过10张" / "图片URL格式不正确"

7.4 配送员确认送达 POST /api/mini/deliverer/tasks/{taskId}/deliver

参数	类型	必填	校验规则	错误提示
items	array	是	非空数组	"配送明细不能为空"
items[].taskItemId	string	是	对应配送明细存在	"配送明细不存在"
items[].deliveredQuantity	number	是	大于等于0，不超过原数量	"送达数量不正确"
remark	string	否	最大200字符	"备注长度不能超过200字符"
imageUrls	array	否	最多10个，每个为合法URL	"图片数量不能超过10张"

7.5 配送员取消任务 POST /api/mini/deliverer/tasks/{taskId}/cancel

参数	类型	必填	校验规则	错误提示
reason	string	是	非空，2-200字符	"取消原因不能为空" / "取消原因长度必须在2-200字符之间"
images	array	否	最多5个，每个为合法URL	"图片数量不能超过5张"

7.6 配送员换班交接 POST /api/mini/deliverer/handover

参数	类型	必填	校验规则	错误提示
handoverType	string	是	枚举值：shift_out/shift_in	"交接类型不正确"
targetDeliverId	string	条件	handoverType为shift_out时必填	对应配送员存在、状态正常
remark	string	否	最大200字符	"备注长度不能超过200字符"
taskIds	array	是	非空数组，元素为配送任务ID	"请选择要交接的任务"

7.7 供应商确认取货 POST /api/mini/supplier/pickup-tasks/{taskId}/confirm

参数	类型	必填	校验规则	错误提示
remark	string	否	最大200字符	"备注长度不能超过200字符"
imageUrls	array	否	最多10个，每个为合法URL	"图片数量不能超过10张"

---

八、询价报价模块校验规则

8.1 创建询价单 POST /api/web/inquiries

参数	类型	必填	校验规则	错误提示
title	string	是	非空，2-100字符	"询价单标题不能为空" / "标题长度必须在2-100字符之间"
regionId	string	是	对应区域存在	"区域不存在"
productIds	array	是	非空数组，元素为商品ID	"请选择询价商品"
expireTime	datetime	否	ISO 8601格式，晚于当前时间	"截止时间必须晚于当前时间"
remark	string	否	最大500字符	"备注长度不能超过500字符"

8.2 发布询价单 POST /api/web/inquiries/{inquiryId}/publish

参数	类型	必填	校验规则	错误提示
-	-	-	询价单状态为draft	"当前状态不允许发布"
-	-	-	询价单中至少有一个商品	"询价单中至少需要一个商品"

8.3 关闭询价单 POST /api/web/inquiries/{inquiryId}/close

参数	类型	必填	校验规则	错误提示
-	-	-	询价单状态为published	"当前状态不允许关闭"

8.4 供应商提交报价 POST /api/mini/supplier/quotations

参数	类型	必填	校验规则	错误提示
inquiryId	string	是	对应询价单存在、状态为published、未过期	"询价单不存在或已截止"
items	array	是	非空数组	"报价项不能为空"
items[].productId	string	是	对应商品在询价单中存在	"商品不在询价范围内"
items[].unitId	string	是	对应单位存在	"单位不存在"
items[].price	number	是	大于0，2位小数	"价格必须大于0"
remark	string	否	最大500字符	"备注长度不能超过500字符"

8.5 审核报价 POST /api/web/quotations/{quotationId}/review

参数	类型	必填	校验规则	错误提示
status	string	是	枚举值：approved/rejected	"审核结果不正确"
reviewNote	string	否	最大200字符	"审核备注长度不能超过200字符"

---

九、价格模块校验规则

9.1 创建价格清单 POST /api/web/price-lists

参数	类型	必填	校验规则	错误提示
regionId	string	是	对应区域存在	"区域不存在"
supplierId	string	是	对应供应商存在且在同一区域	"供应商不存在或不在该区域"
effectiveTime	datetime	是	ISO 8601格式	"生效时间格式不正确"
effectiveType	string	是	枚举值：immediate/scheduled	"生效方式不正确"
expireTime	datetime	否	ISO 8601格式，晚于effectiveTime	"失效时间必须晚于生效时间"
items	array	是	非空数组	"价格项不能为空"
items[].productId	string	是	对应商品存在	"商品不存在"
items[].unitId	string	是	对应单位存在	"单位不存在"
items[].price	number	是	大于0，2位小数	"价格必须大于0"
remark	string	否	最大500字符	"备注长度不能超过500字符"

9.2 发布价格清单 POST /api/web/price-lists/{priceListId}/publish

参数	类型	必填	校验规则	错误提示
-	-	-	价格清单状态为draft或pending	"当前状态不允许发布"
-	-	-	价格清单中至少有一个商品	"价格清单中至少需要一个商品"

---

十、结算模块校验规则

10.1 确认线下结算 POST /api/web/settlements

参数	类型	必填	校验规则	错误提示
orderId	string	是	对应订单存在、支付方式为offline、状态正确	"订单不存在或状态不正确"
settlementMethod	string	是	枚举值：transfer/cash/other	"结算方式不正确"
settlementTime	datetime	是	ISO 8601格式	"结算时间格式不正确"
settlementNote	string	否	最大200字符	"结算备注长度不能超过200字符"
attachmentUrl	string	否	合法URL	"附件URL格式不正确"

10.2 批量确认结算 POST /api/web/settlements/batch

参数	类型	必填	校验规则	错误提示
orderIds	array	是	非空数组，1-50个元素	"请选择要结算的订单"
settlementMethod	string	是	枚举值：transfer/cash/other	"结算方式不正确"
settlementTime	datetime	是	ISO 8601格式	"结算时间格式不正确"

10.3 微信退款 POST /api/web/refunds/wechat-refund/{orderId}

参数	类型	必填	校验规则	错误提示
refundAmount	number	是	大于0，不超过已支付金额	"退款金额不正确"
reason	string	否	最大200字符	"退款原因长度不能超过200字符"

---

十一、支付模块校验规则

11.1 发起微信支付 POST /api/mini/client/orders/{orderId}/wechat-pay

参数	类型	必填	校验规则	错误提示
-	-	-	订单状态为pending_payment	"当前状态不允许支付"
-	-	-	订单支付方式为wechat	"该订单不支持微信支付"

11.2 微信支付回调 POST /api/web/pay/wechat-notify

参数	类型	必填	校验规则	错误提示
return_code	string	是	SUCCESS/FAIL	-
transaction_id	string	条件	return_code为SUCCESS时必填	微信订单号
out_trade_no	string	条件	return_code为SUCCESS时必填	商户订单号

---

十二、其他模块校验规则

12.1 发票管理

接口	参数	校验规则	错误提示
开具发票	amount	大于0，不超过订单已支付金额	"开票金额不正确"
开具发票	taxRate	枚举值：3/6/9/13	"税率不正确"
开具发票	clientTaxNo	当发票类型为vat时必填	"税号不能为空"

12.2 消息通知

参数	校验规则	错误提示
title	非空，最大100字符	"消息标题不能为空" / "标题长度不能超过100字符"
content	非空，最大1000字符	"消息内容不能为空" / "内容长度不能超过1000字符"
receiverIds	当receiverType为指定类型时必填	"请选择接收者"

12.3 文件上传

参数	校验规则	错误提示
file	必填	"请选择要上传的文件"
file.size	不超过10MB	"文件大小不能超过10MB"
file.type	在允许的类型列表中	"不支持的文件类型"

允许的文件类型

• 图片：jpg、jpeg、png、gif、webp
• 文档：pdf、doc、docx、xls、xlsx
• 压缩包：zip、rar

---

附录：校验错误码汇总

错误码	说明	适用场景
40001	必填参数为空	缺少必填参数
40002	参数类型错误	参数类型不匹配
40003	参数格式错误	格式不符合要求
40004	参数长度超限	超出长度限制
40005	参数值不在范围内	超出允许范围
40006	枚举值不正确	不在允许列表中
40007	URL格式错误	不是合法的URL
40008	日期格式错误	不是合法的日期格式
40009	金额格式错误	小数位数超出限制
40010	数量精度错误	小数位数超出限制