microservice / sl-express · Commits

Commit f41f20914dbb3d7852f9e64c96b7d50c0ef1c0a0

Authored by jiangyong
1 parent e8a5eae7
build: skipped

docs(api): 添加sl-express接口说明文档 

- 整理了用户端、快递员端、司机端、管理后台四大业务模块的接口文档
- 详细描述了网关路由约定和各模块的访问前缀配置
- 汇总了通用请求头、统一响应结构和分页结构规范
- 记录了各业务模块的核心接口包括用户认证、地址簿、订单管理、任务管理等功能
- 包含了管理后台的工作台、排班、机构人员、运力线路、订单运单等完整接口清单
- 补充了Swagger文档访问方式和关键请求对象参考信息
Inline Side-by-side
Showing 1 changed file with 408 additions and 0 deletions
docs/接口说明文档.md 0 → 100644
  View file @f41f209
  1 +# sl-express 接口说明文档
  2 +
  3 +## 1. 文档范围
  4 +
  5 +本文档基于当前仓库代码整理，覆盖项目主要对外入口模块：
  6 +
  7 +- `sl-express-ms-web-customer`
  8 +- `sl-express-ms-web-courier`
  9 +- `sl-express-ms-web-driver`
  10 +- `sl-express-ms-web-manager`
  11 +
  12 +网关统一由 `sl-express-gateway` 转发，对外访问建议统一走网关。
  13 +
  14 +## 2. 网关路由约定
  15 +
  16 +根据网关配置 `sl-express-gateway/src/main/resources/bootstrap-local.yml`：
  17 +
  18 +| 业务模块 | 服务名 | 网关前缀 |
  19 +|---|---|---|
  20 +| 用户端 | `sl-express-ms-web-customer` | `/customer` |
  21 +| 快递员端 | `sl-express-ms-web-courier` | `/courier` |
  22 +| 司机端 | `sl-express-ms-web-driver` | `/driver` |
  23 +| 管理后台 | `sl-express-ms-web-manager` | `/manager` |
  24 +| 支付回调 | `sl-express-ms-trade` | `/trade/notify` |
  25 +
  26 +说明：
  27 +
  28 +- 网关使用了 `StripPrefix=1`
  29 +- 因此实际对外地址 = `网关前缀 + Controller 路径`
  30 +- 例如用户登录接口实际访问路径为：`/customer/user/login`
  31 +
  32 +## 3. 通用约定
  33 +
  34 +### 3.1 请求头
  35 +
  36 +| Header | 说明 |
  37 +|---|---|
  38 +| `token` | 业务访问令牌，大部分已登录接口必传 |
  39 +| `refresh_token` | 用户端刷新令牌接口使用 |
  40 +
  41 +说明：
  42 +
  43 +- `token` 由统一拦截器 `TokenInterceptor` 从请求头读取
  44 +- 用户端登录/刷新、司机端登录、快递员端登录、管理端登录、验证码、Swagger 相关接口默认放行
  45 +
  46 +### 3.2 统一响应结构
  47 +
  48 +统一返回对象为 `R<T>`，结构如下：
  49 +
  50 +```json
  51 +{
  52 + "code": 200,
  53 + "msg": "ok",
  54 + "data": {}
  55 +}
  56 +```
  57 +
  58 +字段说明：
  59 +
  60 +| 字段 | 类型 | 说明 |
  61 +|---|---|---|
  62 +| `code` | `Integer` | `200` 表示成功，非 `200` 表示失败 |
  63 +| `msg` | `String` | 响应消息 |
  64 +| `data` | `T` | 业务数据 |
  65 +
  66 +### 3.3 分页结构
  67 +
  68 +分页统一使用 `PageResponse<T>`：
  69 +
  70 +```json
  71 +{
  72 + "counts": 100,
  73 + "pageSize": 10,
  74 + "pages": 10,
  75 + "page": 1,
  76 + "items": []
  77 +}
  78 +```
  79 +
  80 +## 4. 用户端接口
  81 +
  82 +网关前缀：`/customer`
  83 +
  84 +### 4.1 用户相关
  85 +
  86 +| 接口名称 | 方法 | 路径 | 说明 | 鉴权 |
  87 +|---|---|---|---|---|
  88 +| 用户登录 | `POST` | `/customer/user/login` | 小程序/微信登录 | 否 |
  89 +| 刷新 token | `POST` | `/customer/user/refresh` | 使用 `refresh_token` 换新令牌 | 否 |
  90 +| 更新个人资料 | `PUT` | `/customer/user/profile` | 修改当前登录用户资料 | 是 |
  91 +| 我的资料 | `GET` | `/customer/user/profile` | 查询当前登录用户资料 | 是 |
  92 +| 注销/删除我的资料 | `DELETE` | `/customer/user/profile` | 删除当前登录用户资料 | 是 |
  93 +| 实名认证 | `POST` | `/customer/user/realNameVerify` | 实名校验 | 是 |
  94 +
  95 +关键对象：
  96 +
  97 +- 登录请求：`UserLoginRequestVO`
  98 +- 登录响应：`UserLoginVO`
  99 +- 用户资料：`MemberVO`
  100 +- 实名认证：`RealNameVerifyVO`
  101 +
  102 +### 4.2 地址簿
  103 +
  104 +| 接口名称 | 方法 | 路径 | 说明 |
  105 +|---|---|---|---|
  106 +| 地址分页查询 | `GET` | `/customer/address/page` | 参数：`page`、`pageSize`、`keyword`、`type` |
  107 +| 默认地址 | `POST` | `/customer/address/defaultAddress` | 获取默认地址 |
  108 +| 新增地址 | `POST` | `/customer/address` | 新增地址簿记录 |
  109 +| 修改地址 | `PUT` | `/customer/address` | 修改地址簿记录 |
  110 +| 删除地址 | `DELETE` | `/customer/address` | 请求体传 `List<Long>` |
  111 +| 地址详情 | `GET` | `/customer/address/detail/{id}` | 查询单条地址详情 |
  112 +| 下单地址保存 | `PUT` | `/customer/address/orderAddress` | 保存订单地址但不入地址簿 |
  113 +
  114 +### 4.3 行政区划
  115 +
  116 +| 接口名称 | 方法 | 路径 | 说明 |
  117 +|---|---|---|---|
  118 +| 查询下级区域 | `GET` | `/customer/areas/children` | 参数：`parentId`，默认 `0` |
  119 +
  120 +### 4.4 货品管理
  121 +
  122 +| 接口名称 | 方法 | 路径 | 说明 |
  123 +|---|---|---|---|
  124 +| 新增货品 | `POST` | `/customer/order-manager/cargo` | 新增订单货品 |
  125 +| 货品列表 | `GET` | `/customer/order-manager/cargo` | 参数：`orderId` |
  126 +| 修改货品 | `PUT` | `/customer/order-manager/cargo/{id}` | 修改货品信息 |
  127 +| 删除货品 | `DELETE` | `/customer/order-manager/cargo/{id}` | 删除货品 |
  128 +| 常用货品 | `GET` | `/customer/order-manager/cargo/hot` | 参数：`name` 可选 |
  129 +| 最近货品 | `GET` | `/customer/order-manager/cargo/last` | 参数：`name` 可选 |
  130 +
  131 +### 4.5 订单管理
  132 +
  133 +| 接口名称 | 方法 | 路径 | 说明 |
  134 +|---|---|---|---|
  135 +| 订单分页查询 | `POST` | `/customer/order-manager/order/page` | 请求体：`OrderQueryVO` |
  136 +| 订单详情 | `GET` | `/customer/order-manager/order/{id}` | 查询订单详情 |
  137 +| 更新订单 | `POST` | `/customer/order-manager/order/{id}` | 代码中存在，语义与更新一致 |
  138 +| 预估总价 | `POST` | `/customer/order-manager/order/totalPrice` | 请求体：`MailingSaveVO` |
  139 +| 下单 | `POST` | `/customer/order-manager/order` | 请求体：`MailingSaveVO` |
  140 +| 修改订单 | `PUT` | `/customer/order-manager/order/{id}` | 请求体：`OrderVO` |
  141 +| 订单支付 | `PUT` | `/customer/order-manager/order/pay` | 请求体：`TradeLaunchVO` |
  142 +| 取消订单 | `PUT` | `/customer/order-manager/order/cancel/{id}` | 取消订单 |
  143 +| 删除订单 | `PUT` | `/customer/order-manager/order/del/{id}` | 逻辑删除 |
  144 +| 订单数量统计 | `GET` | `/customer/order-manager/order/count` | 返回不同状态数量 |
  145 +| 运单轨迹详情 | `GET` | `/customer/order-manager/order/track/{id}` | 查询轨迹 |
  146 +
  147 +## 5. 快递员端接口
  148 +
  149 +网关前缀：`/courier`
  150 +
  151 +### 5.1 登录与用户
  152 +
  153 +| 接口名称 | 方法 | 路径 | 说明 | 鉴权 |
  154 +|---|---|---|---|---|
  155 +| 账号登录 | `POST` | `/courier/login/account` | 请求体：`AccountLoginVO` | 否 |
  156 +| 当前用户信息 | `GET` | `/courier/users/get` | 通过 token 获取 | 是 |
  157 +| 同网点快递员分页 | `GET` | `/courier/users/sameAgency` | 参数：`page`、`pageSize`、`keyword` | 是 |
  158 +| 作业范围 | `GET` | `/courier/users/scope` | 获取当前人员服务范围 | 是 |
  159 +
  160 +### 5.2 区域与定位
  161 +
  162 +| 接口名称 | 方法 | 路径 | 说明 |
  163 +|---|---|---|---|
  164 +| 查询下级区域 | `GET` | `/courier/areas/children` | 参数：`parentId` |
  165 +| 上报位置 | `PUT` | `/courier/track/upload` | 参数：`lng`、`lat` |
  166 +
  167 +### 5.3 任务管理
  168 +
  169 +| 接口名称 | 方法 | 路径 | 说明 |
  170 +|---|---|---|---|
  171 +| 任务详情 | `GET` | `/courier/tasks/get/{id}` | 取件/派件详情 |
  172 +| 任务分页 | `GET` | `/courier/tasks/page` | 任务列表 |
  173 +| 取消任务 | `POST` | `/courier/tasks/cancel` | 请求体：`TasksCancelVO` |
  174 +| 删除任务 | `DELETE` | `/courier/tasks/{id}` | 删除单条任务 |
  175 +| 批量删除 | `DELETE` | `/courier/tasks/batch` | 请求体：`TaskBatchVO` |
  176 +| 批量转单 | `POST` | `/courier/tasks/transfer/batch` | 请求体：`TaskBatchTransferVO` |
  177 +| 身份校验 | `POST` | `/courier/tasks/idCard/check` | 请求体：`TaskIdCardCheckVO` |
  178 +| 取件 | `PUT` | `/courier/tasks/pickup` | 请求体：`TaskPickupVO` |
  179 +| 用户拒收 | `PUT` | `/courier/tasks/reject/{id}` | 拒收处理 |
  180 +| 签收 | `PUT` | `/courier/tasks/sign` | 请求体：`TaskSignVO` |
  181 +| 最近查找列表 | `GET` | `/courier/tasks/recentSearch` | 最近检索记录 |
  182 +| 标记最近查找 | `GET` | `/courier/tasks/markRecent/{transportOrderId}` | 标记运单 |
  183 +| 清空最近查找 | `DELETE` | `/courier/tasks/recentSearch` | 清空记录 |
  184 +| 运费计算 | `POST` | `/courier/tasks/calculate` | 请求体：`CarriageCalculateVO` |
  185 +| 订单轨迹 | `GET` | `/courier/tasks/tracks/{id}` | 查询运单轨迹 |
  186 +| 今日任务统计 | `GET` | `/courier/tasks/taskStatistics` | 首页统计 |
  187 +| 搜索任务 | `POST` | `/courier/tasks/search` | 请求体：`TaskSearchVO` |
  188 +
  189 +### 5.4 消息、推送、支付
  190 +
  191 +| 接口名称 | 方法 | 路径 | 说明 |
  192 +|---|---|---|---|
  193 +| 首页消息 | `GET` | `/courier/messages/home/get` | 首页消息聚合 |
  194 +| 最新公告 | `GET` | `/courier/messages/notice/new/get` | 最新通知 |
  195 +| 标记已读 | `PUT` | `/courier/messages/{id}` | 单条已读 |
  196 +| 全部已读 | `PUT` | `/courier/messages/readAll/{contentType}` | 按类型全部已读 |
  197 +| 消息分页 | `GET` | `/courier/messages/page` | 分页查询消息 |
  198 +| 保存极光设备 | `POST` | `/courier/jpush/saveDevice` | 请求体：`JPushVO` |
  199 +| 获取收款二维码 | `POST` | `/courier/pays/qrCode/get` | 请求体：`TradeLaunchVO` |
  200 +| 查询支付状态 | `GET` | `/courier/pays/status/{productOrderNo}` | 查询支付结果 |
  201 +
  202 +## 6. 司机端接口
  203 +
  204 +网关前缀：`/driver`
  205 +
  206 +### 6.1 登录、用户、车辆
  207 +
  208 +| 接口名称 | 方法 | 路径 | 说明 | 鉴权 |
  209 +|---|---|---|---|---|
  210 +| 账号登录 | `POST` | `/driver/login/account` | 请求体：`AccountLoginVO` | 否 |
  211 +| 当前司机信息 | `GET` | `/driver/users` | 获取个人信息 | 是 |
  212 +| 当前车辆信息 | `GET` | `/driver/users/truck` | 获取车辆信息 | 是 |
  213 +| 任务报表 | `GET` | `/driver/users/taskReport` | 参数：`year`、`month` | 是 |
  214 +
  215 +### 6.2 任务管理
  216 +
  217 +| 接口名称 | 方法 | 路径 | 说明 |
  218 +|---|---|---|---|
  219 +| 任务列表 | `GET` | `/driver/tasks/list` | 参数：`page`、`pageSize`、`status`、`startTime`、`endTime`、`transportTaskId` |
  220 +| 任务详情 | `GET` | `/driver/tasks/details/{jobId}` | 查询运输任务详情 |
  221 +| 运单列表 | `GET` | `/driver/tasks/orders` | 参数：`page`、`pageSize`、`taskId`、`transportOrderId` |
  222 +| 提货登记 | `POST` | `/driver/tasks/takeDelivery` | 请求体：`DriverPickUpVO` |
  223 +| 延迟交付 | `PUT` | `/driver/tasks/delay` | 请求体：`DriverDelayDeliveryVO` |
  224 +| 交付登记 | `POST` | `/driver/tasks/deliver` | 请求体：`DriverDeliverVO` |
  225 +| 回单/回车登记 | `POST` | `/driver/tasks/truckRegistration` | 请求体：`DriverReturnRegisterVO` |
  226 +| 调度中心电话 | `GET` | `/driver/tasks/dispatchCenterPhone` | 获取联系电话 |
  227 +
  228 +### 6.3 消息、定位、文件
  229 +
  230 +| 接口名称 | 方法 | 路径 | 说明 |
  231 +|---|---|---|---|
  232 +| 消息分页 | `GET` | `/driver/messages/page` | 参数：`contentType`、`page`、`pageSize` |
  233 +| 消息已读 | `PUT` | `/driver/messages/{id}` | 标记已读 |
  234 +| 消息数量统计 | `GET` | `/driver/messages/countType/{contentType}` | 按类型统计 |
  235 +| 上报位置 | `PUT` | `/driver/track/upload` | 参数：`lng`、`lat` |
  236 +| 文件上传 | `POST` | `/driver/files/upload` | `multipart/form-data`，字段名 `file` |
  237 +| 图片上传 | `POST` | `/driver/files/imageUpload` | `multipart/form-data`，字段名 `file` |
  238 +
  239 +## 7. 管理后台接口
  240 +
  241 +网关前缀：`/manager`
  242 +
  243 +管理端接口数量较多，下面按业务域整理核心接口。
  244 +
  245 +### 7.1 认证与基础能力
  246 +
  247 +| 接口名称 | 方法 | 路径 | 说明 | 鉴权 |
  248 +|---|---|---|---|---|
  249 +| 登录 | `POST` | `/manager/login` | 请求体：`LoginParamDTO` | 否 |
  250 +| 菜单 | `GET` | `/manager/menus` | 获取当前用户菜单 | 是 |
  251 +| 验证码 | `GET` | `/manager/captcha?key=xxx` | 返回 PNG 图片 | 否 |
  252 +| 文件上传 | `POST` | `/manager/files/upload` | `multipart/form-data` | 是 |
  253 +| 图片上传 | `POST` | `/manager/files/imageUpload` | `multipart/form-data` | 是 |
  254 +| 区域下级查询 | `GET` | `/manager/areas/children` | 参数：`parentId` | 是 |
  255 +
  256 +### 7.2 工作台与排班
  257 +
  258 +| 接口名称 | 方法 | 路径 | 说明 |
  259 +|---|---|---|---|
  260 +| 保存工作台数据 | `POST` | `/manager/workspace` | 请求体：`WorkbenchAddVO` |
  261 +| 保存月订单数 | `POST` | `/manager/workspace/saveOrderNumber` | 请求体：`List<MonthlyOrderAddVO>` |
  262 +| 获取工作台数据 | `GET` | `/manager/workspace` | 工作台查询 |
  263 +| 清空工作台 | `DELETE` | `/manager/workspace/deleteAll` | 删除全部 |
  264 +| 排班查询 | `GET` | `/manager/work-schedulings` | 排班列表 |
  265 +| 删除排班 | `DELETE` | `/manager/work-schedulings/{id}/{operator}` | 删除指定排班 |
  266 +| 更新排班 | `PUT` | `/manager/work-schedulings` | 请求体：`WorkSchedulingVO` |
  267 +| 批量新增排班 | `POST` | `/manager/work-schedulings` | 请求体：`WorkSchedulingAddVO` |
  268 +| 下载模板 | `GET` | `/manager/work-schedulings/downExcelTemplate` | Excel 模板 |
  269 +| 上传排班 Excel | `POST` | `/manager/work-schedulings/uploadExcel` | 文件上传 |
  270 +| 班次全部 | `GET` | `/manager/work-patterns/all` | 班次列表 |
  271 +| 班次分页 | `GET` | `/manager/work-patterns/page` | 分页查询 |
  272 +| 班次详情 | `GET` | `/manager/work-patterns/{id}` | 查询单条 |
  273 +| 新增班次 | `POST` | `/manager/work-patterns` | 新增 |
  274 +| 修改班次 | `PUT` | `/manager/work-patterns` | 修改 |
  275 +| 删除班次 | `DELETE` | `/manager/work-patterns/{id}` | 删除 |
  276 +
  277 +### 7.3 机构与人员
  278 +
  279 +| 接口名称 | 方法 | 路径 | 说明 |
  280 +|---|---|---|---|
  281 +| 机构树 | `GET` | `/manager/business-hall/tree` | 机构树结构 |
  282 +| 机构详情 | `GET` | `/manager/business-hall/{id}` | 查询机构 |
  283 +| 新增/保存机构 | `POST` | `/manager/business-hall` | 请求体：`AgencyUpdateVO` |
  284 +| 员工详情 | `GET` | `/manager/business-hall/user/{id}` | 员工信息 |
  285 +| 员工分页 | `GET` | `/manager/business-hall/user/page` | 查询员工 |
  286 +| 快递员分页 | `GET` | `/manager/business-hall/courier/page` | 查询快递员 |
  287 +| 快递员详情 | `GET` | `/manager/business-hall/courier/{id}` | 查询快递员 |
  288 +| 删除服务范围 | `DELETE` | `/manager/business-hall/scope/{id}/{type}` | 删除服务范围 |
  289 +| 保存服务范围 | `POST` | `/manager/business-hall/scope` | 请求体：`ServiceScopeVO` |
  290 +| 查询服务范围 | `GET` | `/manager/business-hall/scope/{id}/{type}` | 查询服务范围 |
  291 +| 根据网点查快递员 | `GET` | `/manager/business-hall/courier/findByAgencyId/{agencyId}` | 查询快递员列表 |
  292 +
  293 +### 7.4 运力、线路、车辆、司机
  294 +
  295 +| 接口名称 | 方法 | 路径 | 说明 |
  296 +|---|---|---|---|
  297 +| 运费模板查询 | `GET` | `/manager/carriages` | 运费模板列表 |
  298 +| 运费模板保存 | `POST` | `/manager/carriages` | 请求体：`CarriageDTO` |
  299 +| 运费模板删除 | `DELETE` | `/manager/carriages/{id}` | 删除模板 |
  300 +| 调度配置保存 | `POST` | `/manager/dispatch-configuration-manager` | 请求体：`DispatchConfigurationVO` |
  301 +| 调度配置查询 | `GET` | `/manager/dispatch-configuration-manager` | 查询当前配置 |
  302 +| 成本配置保存 | `POST` | `/manager/cost-configuration-manager` | 请求体：`List<CostConfigurationVO>` |
  303 +| 成本配置查询 | `GET` | `/manager/cost-configuration-manager` | 查询配置 |
  304 +| 线路新增 | `POST` | `/manager/transportLine` | 请求体：`TransportLineVO` |
  305 +| 线路修改 | `PUT` | `/manager/transportLine/{id}` | 修改线路 |
  306 +| 线路分页 | `POST` | `/manager/transportLine/page` | 分页查询 |
  307 +| 线路详情 | `GET` | `/manager/transportLine/{id}` | 查询详情 |
  308 +| 线路删除 | `DELETE` | `/manager/transportLine/{id}` | 删除线路 |
  309 +| 车次新增 | `POST` | `/manager/transportLine/trips` | 请求体：`TransportTripsUpdateVO` |
  310 +| 车次修改 | `PUT` | `/manager/transportLine/trips/{id}` | 修改车次 |
  311 +| 车次列表 | `GET` | `/manager/transportLine/trips` | 参数：`transportLineId` |
  312 +| 车次详情 | `GET` | `/manager/transportLine/trips/{id}` | 查询详情 |
  313 +| 车次删除 | `DELETE` | `/manager/transportLine/trips/{id}` | 删除车次 |
  314 +| 车次绑定车辆 | `POST` | `/manager/transportLine/trips/{id}/truckDrivers` | 绑定车辆/司机 |
  315 +| 车次绑定查询 | `GET` | `/manager/transportLine/trips/truckDrivers` | 查询绑定信息 |
  316 +| 车型简表 | `GET` | `/manager/truckType/simple` | 简单列表 |
  317 +| 车型新增 | `POST` | `/manager/truckType` | 新增车型 |
  318 +| 车型修改 | `PUT` | `/manager/truckType/{id}` | 修改车型 |
  319 +| 车型分页 | `GET` | `/manager/truckType/page` | 分页查询 |
  320 +| 车型详情 | `GET` | `/manager/truckType/{id}` | 查询详情 |
  321 +| 车型删除 | `DELETE` | `/manager/truckType/{id}` | 删除 |
  322 +| 车辆新增 | `POST` | `/manager/truck` | 新增车辆 |
  323 +| 车辆修改 | `PUT` | `/manager/truck/{id}` | 修改车辆 |
  324 +| 车辆分页 | `GET` | `/manager/truck/page` | 分页查询 |
  325 +| 车辆详情 | `GET` | `/manager/truck/{id}` | 查询详情 |
  326 +| 车辆数量统计 | `GET` | `/manager/count` | 车辆统计 |
  327 +| 车辆禁用 | `PUT` | `/manager/disable/{id}` | 禁用 |
  328 +| 车辆启用 | `PUT` | `/manager/enable/{id}` | 启用 |
  329 +| 车辆删除 | `DELETE` | `/manager/del/{id}` | 删除 |
  330 +| 保存行驶证 | `POST` | `/manager/truck/{id}/license` | 请求体：`TruckLicenseVO` |
  331 +| 行驶证详情 | `GET` | `/manager/truck/{id}/license` | 查询证件 |
  332 +| 车辆车次 | `GET` | `/manager/truck/{id}/transportTrips` | 查询车次 |
  333 +| 已绑定司机 | `GET` | `/manager/bindingDrivers/{truckId}` | 司机列表 |
  334 +| 未绑定司机 | `GET` | `/manager/unBindingDrivers/` | 司机列表 |
  335 +| 在岗车辆 | `GET` | `/manager/workingTrucks` | 车辆列表 |
  336 +| 非在岗车辆 | `GET` | `/manager/unWorkingTrucks` | 车辆列表 |
  337 +| 车辆绑定司机 | `POST` | `/manager/truck/truckDrivers` | 请求体：`BindingDriversVO` |
  338 +| 司机分页 | `GET` | `/manager/driver/page` | 分页查询 |
  339 +| 司机详情 | `GET` | `/manager/driver/{id}` | 查询详情 |
  340 +| 司机修改 | `PUT` | `/manager/driver/{id}` | 请求体：`DriverUpdateVO` |
  341 +| 保存驾驶证 | `POST` | `/manager/driverLicense` | 请求体：`DriverLicenseVO` |
  342 +| 驾驶证详情 | `GET` | `/manager/driverLicense/{id}` | 查询证件 |
  343 +| 司机绑定车辆 | `POST` | `/manager/driver/truckDrivers` | 请求体：`BindingDriversVO` |
  344 +| 回单登记分页 | `POST` | `/manager/truck-return-register/pageQuery` | 请求体：`TruckReturnRegisterPageQueryVO` |
  345 +| 回单登记详情 | `GET` | `/manager/truck-return-register/detail/{id}` | 查询详情 |
  346 +
  347 +### 7.5 订单、运单、任务
  348 +
  349 +| 接口名称 | 方法 | 路径 | 说明 |
  350 +|---|---|---|---|
  351 +| 管理端订单分页 | `POST` | `/manager/order-manager/order/page` | 请求体：`OrderQueryVO` |
  352 +| 管理端订单详情 | `GET` | `/manager/order-manager/order/{id}` | 查询详情 |
  353 +| 管理端订单修改 | `POST` | `/manager/order-manager/order/{id}` | 更新订单 |
  354 +| 管理端货品新增 | `POST` | `/manager/order-manager/cargo` | 请求体：`OrderCargoUpdateVO` |
  355 +| 管理端货品列表 | `GET` | `/manager/order-manager/cargo?orderId=xxx` | 查询货品 |
  356 +| 管理端货品修改 | `PUT` | `/manager/order-manager/cargo/{id}` | 修改货品 |
  357 +| 管理端货品删除 | `DELETE` | `/manager/order-manager/cargo/{id}` | 删除货品 |
  358 +| 运输任务分页 | `POST` | `/manager/transport-task-manager/page` | 请求体：`TaskTransportQueryVO` |
  359 +| 运输任务详情 | `GET` | `/manager/transport-task-manager/{id}` | 查询详情 |
  360 +| 运输任务节点 | `GET` | `/manager/transport-task-manager/point/{id}` | 查询轨迹点 |
  361 +| 运输任务调整 | `PUT` | `/manager/transport-task-manager/adjust/{id}` | 请求体：`TaskTransportUpdateVO` |
  362 +| 运输任务统计 | `GET` | `/manager/transport-task-manager/count` | 数量统计 |
  363 +| 运输任务取消 | `PUT` | `/manager/transport-task-manager/cancel/{id}` | 取消任务 |
  364 +| 运单分页 | `POST` | `/manager/transport-order-manager/page` | 请求体：`TransportOrderQueryVO` |
  365 +| 运单详情 | `GET` | `/manager/transport-order-manager/{id}` | 查询详情 |
  366 +| 运单统计 | `GET` | `/manager/transport-order-manager/count` | 数量统计 |
  367 +| 运单轨迹 | `GET` | `/manager/transport-order-manager/track/{id}` | 查询跟踪 |
  368 +| 取派件任务分页 | `POST` | `/manager/pickup-dispatch-task-manager/page` | 请求体：`TaskPickupDispatchQueryVO` |
  369 +| 分配快递员 | `PUT` | `/manager/pickup-dispatch-task-manager/{courierId}` | 请求体：`List<String>` 任务 ID |
  370 +
  371 +## 8. Swagger/Knife4j 说明
  372 +
  373 +项目已启用 Swagger/Knife4j 配置，各 `web` 模块都配置了扫描包。若服务已启动，可优先通过 Swagger 页面查看字段细节与示例。
  374 +
  375 +常见地址通常为：
  376 +
  377 +- `/swagger-ui.html`
  378 +- `/v2/api-docs`
  379 +
  380 +如果通过网关访问，建议按模块前缀拼接，例如：
  381 +
  382 +- `/customer/swagger-ui.html`
  383 +- `/courier/swagger-ui.html`
  384 +- `/driver/swagger-ui.html`
  385 +- `/manager/swagger-ui.html`
  386 +
  387 +实际可用性以部署环境网关转发规则为准。
  388 +
  389 +## 9. 关键请求对象参考
  390 +
  391 +如需补全字段级接口文档，可优先查看以下对象：
  392 +
  393 +- 用户端登录：`sl-express-ms-web-customer/src/main/java/com/sl/ms/web/customer/vo/user/UserLoginRequestVO.java`
  394 +- 用户端下单：`sl-express-ms-web-customer/src/main/java/com/sl/ms/web/customer/vo/oms/MailingSaveVO.java`
  395 +- 用户端订单查询：`sl-express-ms-web-customer/src/main/java/com/sl/ms/web/customer/vo/oms/OrderQueryVO.java`
  396 +- 快递员登录：`sl-express-ms-web-courier/src/main/java/com/sl/ms/web/courier/vo/login/AccountLoginVO.java`
  397 +- 快递员任务：`sl-express-ms-web-courier/src/main/java/com/sl/ms/web/courier/vo/task/`
  398 +- 司机登录：`sl-express-ms-web-driver/src/main/java/com/sl/ms/web/driver/vo/request/AccountLoginVO.java`
  399 +- 司机任务：`sl-express-ms-web-driver/src/main/java/com/sl/ms/web/driver/vo/request/`
  400 +- 管理端机构：`sl-express-ms-web-manager/src/main/java/com/sl/ms/web/manager/vo/agency/`
  401 +- 管理端车辆：`sl-express-ms-web-manager/src/main/java/com/sl/ms/web/manager/vo/baseTruck/`
  402 +- 管理端订单与任务：`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/`
  403 +
  404 +## 10. 说明
  405 +
  406 +- 本文档依据当前代码静态整理，不包含运行态返回样例
  407 +- 少数字段说明存在中文注释编码问题，接口语义以路径、方法名、VO/DTO 命名和 Service 调用逻辑为准
  408 +- 管理端部分接口未设置类级统一前缀，而是直接定义在 Controller 方法路径上，已按代码实际路径整理
... ...