sl-express 接口说明文档

1. 文档范围

本文档基于当前仓库代码整理，覆盖项目主要对外入口模块：

• sl-express-ms-web-customer
• sl-express-ms-web-courier
• sl-express-ms-web-driver
• sl-express-ms-web-manager

网关统一由 sl-express-gateway 转发，对外访问建议统一走网关。

2. 网关路由约定

根据网关配置 sl-express-gateway/src/main/resources/bootstrap-local.yml：

业务模块	服务名	网关前缀
用户端	sl-express-ms-web-customer	/customer
快递员端	sl-express-ms-web-courier	/courier
司机端	sl-express-ms-web-driver	/driver
管理后台	sl-express-ms-web-manager	/manager
支付回调	sl-express-ms-trade	/trade/notify

说明：

• 网关使用了 StripPrefix=1
• 因此实际对外地址 = 网关前缀 + Controller 路径
• 例如用户登录接口实际访问路径为：/customer/user/login

3. 通用约定

3.1 请求头

Header	说明
token	业务访问令牌，大部分已登录接口必传
refresh_token	用户端刷新令牌接口使用

说明：

• token 由统一拦截器 TokenInterceptor 从请求头读取
• 用户端登录/刷新、司机端登录、快递员端登录、管理端登录、验证码、Swagger 相关接口默认放行

3.2 统一响应结构

统一返回对象为 R<T>，结构如下：

{
  "code": 200,
  "msg": "ok",
  "data": {}
}

字段说明：

字段	类型	说明
code	Integer	200 表示成功，非 200 表示失败
msg	String	响应消息
data	T	业务数据

3.3 分页结构

分页统一使用 PageResponse<T>：

{
  "counts": 100,
  "pageSize": 10,
  "pages": 10,
  "page": 1,
  "items": []
}

4. 用户端接口

网关前缀：/customer

4.1 用户相关

接口名称	方法	路径	说明	鉴权
用户登录	POST	/customer/user/login	小程序/微信登录	否
刷新 token	POST	/customer/user/refresh	使用 refresh_token 换新令牌	否
更新个人资料	PUT	/customer/user/profile	修改当前登录用户资料	是
我的资料	GET	/customer/user/profile	查询当前登录用户资料	是
注销/删除我的资料	DELETE	/customer/user/profile	删除当前登录用户资料	是
实名认证	POST	/customer/user/realNameVerify	实名校验	是

关键对象：

• 登录请求：UserLoginRequestVO
• 登录响应：UserLoginVO
• 用户资料：MemberVO
• 实名认证：RealNameVerifyVO

4.2 地址簿

接口名称	方法	路径	说明
地址分页查询	GET	/customer/address/page	参数：page、pageSize、keyword、type
默认地址	POST	/customer/address/defaultAddress	获取默认地址
新增地址	POST	/customer/address	新增地址簿记录
修改地址	PUT	/customer/address	修改地址簿记录
删除地址	DELETE	/customer/address	请求体传 List<Long>
地址详情	GET	/customer/address/detail/{id}	查询单条地址详情
下单地址保存	PUT	/customer/address/orderAddress	保存订单地址但不入地址簿

4.3 行政区划

接口名称	方法	路径	说明
查询下级区域	GET	/customer/areas/children	参数：parentId，默认 0

4.4 货品管理

接口名称	方法	路径	说明
新增货品	POST	/customer/order-manager/cargo	新增订单货品
货品列表	GET	/customer/order-manager/cargo	参数：orderId
修改货品	PUT	/customer/order-manager/cargo/{id}	修改货品信息
删除货品	DELETE	/customer/order-manager/cargo/{id}	删除货品
常用货品	GET	/customer/order-manager/cargo/hot	参数：name 可选
最近货品	GET	/customer/order-manager/cargo/last	参数：name 可选

4.5 订单管理

接口名称	方法	路径	说明
订单分页查询	POST	/customer/order-manager/order/page	请求体：OrderQueryVO
订单详情	GET	/customer/order-manager/order/{id}	查询订单详情
更新订单	POST	/customer/order-manager/order/{id}	代码中存在，语义与更新一致
预估总价	POST	/customer/order-manager/order/totalPrice	请求体：MailingSaveVO
下单	POST	/customer/order-manager/order	请求体：MailingSaveVO
修改订单	PUT	/customer/order-manager/order/{id}	请求体：OrderVO
订单支付	PUT	/customer/order-manager/order/pay	请求体：TradeLaunchVO
取消订单	PUT	/customer/order-manager/order/cancel/{id}	取消订单
删除订单	PUT	/customer/order-manager/order/del/{id}	逻辑删除
订单数量统计	GET	/customer/order-manager/order/count	返回不同状态数量
运单轨迹详情	GET	/customer/order-manager/order/track/{id}	查询轨迹

5. 快递员端接口

网关前缀：/courier

5.1 登录与用户

接口名称	方法	路径	说明	鉴权
账号登录	POST	/courier/login/account	请求体：AccountLoginVO	否
当前用户信息	GET	/courier/users/get	通过 token 获取	是
同网点快递员分页	GET	/courier/users/sameAgency	参数：page、pageSize、keyword	是
作业范围	GET	/courier/users/scope	获取当前人员服务范围	是

5.2 区域与定位

接口名称	方法	路径	说明
查询下级区域	GET	/courier/areas/children	参数：parentId
上报位置	PUT	/courier/track/upload	参数：lng、lat

5.3 任务管理

接口名称	方法	路径	说明
任务详情	GET	/courier/tasks/get/{id}	取件/派件详情
任务分页	GET	/courier/tasks/page	任务列表
取消任务	POST	/courier/tasks/cancel	请求体：TasksCancelVO
删除任务	DELETE	/courier/tasks/{id}	删除单条任务
批量删除	DELETE	/courier/tasks/batch	请求体：TaskBatchVO
批量转单	POST	/courier/tasks/transfer/batch	请求体：TaskBatchTransferVO
身份校验	POST	/courier/tasks/idCard/check	请求体：TaskIdCardCheckVO
取件	PUT	/courier/tasks/pickup	请求体：TaskPickupVO
用户拒收	PUT	/courier/tasks/reject/{id}	拒收处理
签收	PUT	/courier/tasks/sign	请求体：TaskSignVO
最近查找列表	GET	/courier/tasks/recentSearch	最近检索记录
标记最近查找	GET	/courier/tasks/markRecent/{transportOrderId}	标记运单
清空最近查找	DELETE	/courier/tasks/recentSearch	清空记录
运费计算	POST	/courier/tasks/calculate	请求体：CarriageCalculateVO
订单轨迹	GET	/courier/tasks/tracks/{id}	查询运单轨迹
今日任务统计	GET	/courier/tasks/taskStatistics	首页统计
搜索任务	POST	/courier/tasks/search	请求体：TaskSearchVO

5.4 消息、推送、支付

接口名称	方法	路径	说明
首页消息	GET	/courier/messages/home/get	首页消息聚合
最新公告	GET	/courier/messages/notice/new/get	最新通知
标记已读	PUT	/courier/messages/{id}	单条已读
全部已读	PUT	/courier/messages/readAll/{contentType}	按类型全部已读
消息分页	GET	/courier/messages/page	分页查询消息
保存极光设备	POST	/courier/jpush/saveDevice	请求体：JPushVO
获取收款二维码	POST	/courier/pays/qrCode/get	请求体：TradeLaunchVO
查询支付状态	GET	/courier/pays/status/{productOrderNo}	查询支付结果

6. 司机端接口

网关前缀：/driver

6.1 登录、用户、车辆

接口名称	方法	路径	说明	鉴权
账号登录	POST	/driver/login/account	请求体：AccountLoginVO	否
当前司机信息	GET	/driver/users	获取个人信息	是
当前车辆信息	GET	/driver/users/truck	获取车辆信息	是
任务报表	GET	/driver/users/taskReport	参数：year、month	是

6.2 任务管理

接口名称	方法	路径	说明
任务列表	GET	/driver/tasks/list	参数：page、pageSize、status、startTime、endTime、transportTaskId
任务详情	GET	/driver/tasks/details/{jobId}	查询运输任务详情
运单列表	GET	/driver/tasks/orders	参数：page、pageSize、taskId、transportOrderId
提货登记	POST	/driver/tasks/takeDelivery	请求体：DriverPickUpVO
延迟交付	PUT	/driver/tasks/delay	请求体：DriverDelayDeliveryVO
交付登记	POST	/driver/tasks/deliver	请求体：DriverDeliverVO
回单/回车登记	POST	/driver/tasks/truckRegistration	请求体：DriverReturnRegisterVO
调度中心电话	GET	/driver/tasks/dispatchCenterPhone	获取联系电话

6.3 消息、定位、文件

接口名称	方法	路径	说明
消息分页	GET	/driver/messages/page	参数：contentType、page、pageSize
消息已读	PUT	/driver/messages/{id}	标记已读
消息数量统计	GET	/driver/messages/countType/{contentType}	按类型统计
上报位置	PUT	/driver/track/upload	参数：lng、lat
文件上传	POST	/driver/files/upload	multipart/form-data，字段名 file
图片上传	POST	/driver/files/imageUpload	multipart/form-data，字段名 file

7. 管理后台接口

网关前缀：/manager

管理端接口数量较多，下面按业务域整理核心接口。

7.1 认证与基础能力

接口名称	方法	路径	说明	鉴权
登录	POST	/manager/login	请求体：LoginParamDTO	否
菜单	GET	/manager/menus	获取当前用户菜单	是
验证码	GET	/manager/captcha?key=xxx	返回 PNG 图片	否
文件上传	POST	/manager/files/upload	multipart/form-data	是
图片上传	POST	/manager/files/imageUpload	multipart/form-data	是
区域下级查询	GET	/manager/areas/children	参数：parentId	是

7.2 工作台与排班

接口名称	方法	路径	说明
保存工作台数据	POST	/manager/workspace	请求体：WorkbenchAddVO
保存月订单数	POST	/manager/workspace/saveOrderNumber	请求体：List<MonthlyOrderAddVO>
获取工作台数据	GET	/manager/workspace	工作台查询
清空工作台	DELETE	/manager/workspace/deleteAll	删除全部
排班查询	GET	/manager/work-schedulings	排班列表
删除排班	DELETE	/manager/work-schedulings/{id}/{operator}	删除指定排班
更新排班	PUT	/manager/work-schedulings	请求体：WorkSchedulingVO
批量新增排班	POST	/manager/work-schedulings	请求体：WorkSchedulingAddVO
下载模板	GET	/manager/work-schedulings/downExcelTemplate	Excel 模板
上传排班 Excel	POST	/manager/work-schedulings/uploadExcel	文件上传
班次全部	GET	/manager/work-patterns/all	班次列表
班次分页	GET	/manager/work-patterns/page	分页查询
班次详情	GET	/manager/work-patterns/{id}	查询单条
新增班次	POST	/manager/work-patterns	新增
修改班次	PUT	/manager/work-patterns	修改
删除班次	DELETE	/manager/work-patterns/{id}	删除

7.3 机构与人员

接口名称	方法	路径	说明
机构树	GET	/manager/business-hall/tree	机构树结构
机构详情	GET	/manager/business-hall/{id}	查询机构
新增/保存机构	POST	/manager/business-hall	请求体：AgencyUpdateVO
员工详情	GET	/manager/business-hall/user/{id}	员工信息
员工分页	GET	/manager/business-hall/user/page	查询员工
快递员分页	GET	/manager/business-hall/courier/page	查询快递员
快递员详情	GET	/manager/business-hall/courier/{id}	查询快递员
删除服务范围	DELETE	/manager/business-hall/scope/{id}/{type}	删除服务范围
保存服务范围	POST	/manager/business-hall/scope	请求体：ServiceScopeVO
查询服务范围	GET	/manager/business-hall/scope/{id}/{type}	查询服务范围
根据网点查快递员	GET	/manager/business-hall/courier/findByAgencyId/{agencyId}	查询快递员列表

7.4 运力、线路、车辆、司机

接口名称	方法	路径	说明
运费模板查询	GET	/manager/carriages	运费模板列表
运费模板保存	POST	/manager/carriages	请求体：CarriageDTO
运费模板删除	DELETE	/manager/carriages/{id}	删除模板
调度配置保存	POST	/manager/dispatch-configuration-manager	请求体：DispatchConfigurationVO
调度配置查询	GET	/manager/dispatch-configuration-manager	查询当前配置
成本配置保存	POST	/manager/cost-configuration-manager	请求体：List<CostConfigurationVO>
成本配置查询	GET	/manager/cost-configuration-manager	查询配置
线路新增	POST	/manager/transportLine	请求体：TransportLineVO
线路修改	PUT	/manager/transportLine/{id}	修改线路
线路分页	POST	/manager/transportLine/page	分页查询
线路详情	GET	/manager/transportLine/{id}	查询详情
线路删除	DELETE	/manager/transportLine/{id}	删除线路
车次新增	POST	/manager/transportLine/trips	请求体：TransportTripsUpdateVO
车次修改	PUT	/manager/transportLine/trips/{id}	修改车次
车次列表	GET	/manager/transportLine/trips	参数：transportLineId
车次详情	GET	/manager/transportLine/trips/{id}	查询详情
车次删除	DELETE	/manager/transportLine/trips/{id}	删除车次
车次绑定车辆	POST	/manager/transportLine/trips/{id}/truckDrivers	绑定车辆/司机
车次绑定查询	GET	/manager/transportLine/trips/truckDrivers	查询绑定信息
车型简表	GET	/manager/truckType/simple	简单列表
车型新增	POST	/manager/truckType	新增车型
车型修改	PUT	/manager/truckType/{id}	修改车型
车型分页	GET	/manager/truckType/page	分页查询
车型详情	GET	/manager/truckType/{id}	查询详情
车型删除	DELETE	/manager/truckType/{id}	删除
车辆新增	POST	/manager/truck	新增车辆
车辆修改	PUT	/manager/truck/{id}	修改车辆
车辆分页	GET	/manager/truck/page	分页查询
车辆详情	GET	/manager/truck/{id}	查询详情
车辆数量统计	GET	/manager/count	车辆统计
车辆禁用	PUT	/manager/disable/{id}	禁用
车辆启用	PUT	/manager/enable/{id}	启用
车辆删除	DELETE	/manager/del/{id}	删除
保存行驶证	POST	/manager/truck/{id}/license	请求体：TruckLicenseVO
行驶证详情	GET	/manager/truck/{id}/license	查询证件
车辆车次	GET	/manager/truck/{id}/transportTrips	查询车次
已绑定司机	GET	/manager/bindingDrivers/{truckId}	司机列表
未绑定司机	GET	/manager/unBindingDrivers/	司机列表
在岗车辆	GET	/manager/workingTrucks	车辆列表
非在岗车辆	GET	/manager/unWorkingTrucks	车辆列表
车辆绑定司机	POST	/manager/truck/truckDrivers	请求体：BindingDriversVO
司机分页	GET	/manager/driver/page	分页查询
司机详情	GET	/manager/driver/{id}	查询详情
司机修改	PUT	/manager/driver/{id}	请求体：DriverUpdateVO
保存驾驶证	POST	/manager/driverLicense	请求体：DriverLicenseVO
驾驶证详情	GET	/manager/driverLicense/{id}	查询证件
司机绑定车辆	POST	/manager/driver/truckDrivers	请求体：BindingDriversVO
回单登记分页	POST	/manager/truck-return-register/pageQuery	请求体：TruckReturnRegisterPageQueryVO
回单登记详情	GET	/manager/truck-return-register/detail/{id}	查询详情

7.5 订单、运单、任务

接口名称	方法	路径	说明
管理端订单分页	POST	/manager/order-manager/order/page	请求体：OrderQueryVO
管理端订单详情	GET	/manager/order-manager/order/{id}	查询详情
管理端订单修改	POST	/manager/order-manager/order/{id}	更新订单
管理端货品新增	POST	/manager/order-manager/cargo	请求体：OrderCargoUpdateVO
管理端货品列表	GET	/manager/order-manager/cargo?orderId=xxx	查询货品
管理端货品修改	PUT	/manager/order-manager/cargo/{id}	修改货品
管理端货品删除	DELETE	/manager/order-manager/cargo/{id}	删除货品
运输任务分页	POST	/manager/transport-task-manager/page	请求体：TaskTransportQueryVO
运输任务详情	GET	/manager/transport-task-manager/{id}	查询详情
运输任务节点	GET	/manager/transport-task-manager/point/{id}	查询轨迹点
运输任务调整	PUT	/manager/transport-task-manager/adjust/{id}	请求体：TaskTransportUpdateVO
运输任务统计	GET	/manager/transport-task-manager/count	数量统计
运输任务取消	PUT	/manager/transport-task-manager/cancel/{id}	取消任务
运单分页	POST	/manager/transport-order-manager/page	请求体：TransportOrderQueryVO
运单详情	GET	/manager/transport-order-manager/{id}	查询详情
运单统计	GET	/manager/transport-order-manager/count	数量统计
运单轨迹	GET	/manager/transport-order-manager/track/{id}	查询跟踪
取派件任务分页	POST	/manager/pickup-dispatch-task-manager/page	请求体：TaskPickupDispatchQueryVO
分配快递员	PUT	/manager/pickup-dispatch-task-manager/{courierId}	请求体：List<String> 任务 ID

8. Swagger/Knife4j 说明

项目已启用 Swagger/Knife4j 配置，各 web 模块都配置了扫描包。若服务已启动，可优先通过 Swagger 页面查看字段细节与示例。

常见地址通常为：

• /swagger-ui.html
• /v2/api-docs

如果通过网关访问，建议按模块前缀拼接，例如：

• /customer/swagger-ui.html
• /courier/swagger-ui.html
• /driver/swagger-ui.html
• /manager/swagger-ui.html

实际可用性以部署环境网关转发规则为准。

9. 关键请求对象参考

如需补全字段级接口文档，可优先查看以下对象：

• 用户端登录：sl-express-ms-web-customer/src/main/java/com/sl/ms/web/customer/vo/user/UserLoginRequestVO.java
• 用户端下单：sl-express-ms-web-customer/src/main/java/com/sl/ms/web/customer/vo/oms/MailingSaveVO.java
• 用户端订单查询：sl-express-ms-web-customer/src/main/java/com/sl/ms/web/customer/vo/oms/OrderQueryVO.java
• 快递员登录：sl-express-ms-web-courier/src/main/java/com/sl/ms/web/courier/vo/login/AccountLoginVO.java
• 快递员任务：sl-express-ms-web-courier/src/main/java/com/sl/ms/web/courier/vo/task/
• 司机登录：sl-express-ms-web-driver/src/main/java/com/sl/ms/web/driver/vo/request/AccountLoginVO.java
• 司机任务：sl-express-ms-web-driver/src/main/java/com/sl/ms/web/driver/vo/request/
• 管理端机构：sl-express-ms-web-manager/src/main/java/com/sl/ms/web/manager/vo/agency/
• 管理端车辆：sl-express-ms-web-manager/src/main/java/com/sl/ms/web/manager/vo/baseTruck/
• 管理端订单与任务：sl-express-ms-web-manager/src/main/java/com/sl/ms/web/manager/vo/oms/、sl-express-ms-web-manager/src/main/java/com/sl/ms/web/manager/vo/work/

10. 说明

• 本文档依据当前代码静态整理，不包含运行态返回样例
• 少数字段说明存在中文注释编码问题，接口语义以路径、方法名、VO/DTO 命名和 Service 调用逻辑为准
• 管理端部分接口未设置类级统一前缀，而是直接定义在 Controller 方法路径上，已按代码实际路径整理