cattleTransportation/牛只运输功能模块整理.md

# 牛只运输功能模块整理

本文档基于当前工作区两个文件夹（pc-cattle-transportation 前端、tradeCattle 后端）的代码与文档，梳理“活牛运输”相关的现有功能模块、接口与前后端对接情况，并提出后续完善建议。

更新日期：2025-10-10

## 1. 范围说明
- 前端：pc-cattle-transportation/src
- 后端：tradeCattle/aiotagro-cattle-trade、aiotagro-core

## 2. 前端已有模块（活牛运输相关）

2.1 运送清单/运单管理
- 页面与交互
  - views/entry/details.vue：运单详情页，展示基础信息（运单号、订单标题、资金方、采购商、车牌号、司机、起始地/目的地、预计送达时间、创建时间等），支持主机定位弹窗、轨迹回放、耳标/项圈日志查看。
  - 状态注释：1 境外预检；2 已入境待隔离（检疫成功）；3 已入隔离场；4 隔离场出场。
- 核心接口（api/abroad.js）
  - /delivery/pageQueryList（后台运送清单-分页）inspectionList
  - /delivery/detail（后台运单详情）waybillDetail
  - /delivery/downloadZip（下载运单打包文件）downloadZip
  - /jbqServer/serverLocation（主机定位）hostLocation
  - /jbqServer/serverTrack（主机轨迹）hostTrack
  - /jbqClientLog/jbqLogList（耳标运单期间日志）earLogList
  - /xqClient/pageXqListByDeliveryId、/xqClientLog/xqLogList（项圈相关接口：前端已定义，后端当前仓库未检索到对应实现）

2.2 运输/装车管理（装车订单）
- 核心接口（api/shipping.js）
  - /delivery/pageDeliveryOrderList（装车订单列表）orderList
  - /delivery/addDeliveryOrder（新增装车订单）orderAdd
  - /delivery/deleteDelivery（删除）orderDel
  - /delivery/updateDeliveryInfo（编辑）orderEdit
  - /deliveryDevice/pageJbqList（查看耳标设备）deviceEarList
  - /jbqClient/pageQuery（分配设备列表）deviceList
  - /delivery/arrangeJbq（分配耳标设备）deviceAssign
  - /delivery/viewDeliveryOrder（订单详情）orderDetail
  - /wechatDelivery/carLoadInfo（装车详情）orderLoadDetail
  - /wechatDelivery/updateLoadInfo（装车保存）orderLoadSave
  - 说明：上述多数接口在后端当前仓库未发现同名 Controller/方法，疑似旧版接口或后端尚未接入该命名；需与后端统一命名或补齐实现。

2.3 入境检疫/核验与扫码记录（数据录入）
- 核心接口（api/isolationQuarantine.js）
  - /inspection/submit（运单管理-确定入场）waybillSubmit
  - /inspection/logList（入/出场扫描记录）scanList
  - /inspection/sheepList（隔离场羊只信息列表）sheepList
  - /device/serverTrack（主机轨迹）hostTrack（与 /jbqServer/serverTrack 存在路由差异）
  - 说明：/inspection/* 相关接口在后端当前仓库未检索到对应 Controller，可能在其他项目或待实现。

2.4 设备定位与轨迹可视化
- views/entry/details.vue：主机定位弹窗与轨迹回放。
- 接口：api/abroad.js 的 hostLocation、hostTrack。

2.5 耳标/项圈设备与日志
- 接口：api/abroad.js 的 earList（耳标运单期间列表）、earLogList（耳标日志）、collarList、collarLogList（项圈相关）。
- 说明：耳标日志已在后端对应实现；项圈相关接口未在后端当前仓库检索到。

2.6 用户与司机管理（运输支撑）
- 接口：api/userManage.js（司机管理）driverList、driverAdd、driverEdit。
- 页面：views/userManage/driverDetailDialog.vue（司机证件/备案码等详情展示）。

2.7 菜单与权限（支撑运输模块）
- store/permission.js：动态路由与侧边菜单生成（import.meta.glob 方式加载 views）。
- components/layout/component/left-menu.vue：左侧菜单（标题“牛只运输跟踪系统”）。
- router/index.ts：基础路由（login、entry/details、system/post 等）。

## 3. 后端已有模块（活牛运输相关）

3.1 运送清单（Delivery）
- Controller：DeliveryController（/delivery）
  - POST /pageQuery（小程序运送清单-分页）
  - GET  /view（小程序运送清单-查询详情）
  - POST /submitCheck（小程序运送清单-核验提交）
  - POST /pageQueryList（后台系统运送清单-分页）
  - GET  /detail（后台运单详情）
- Service：IDeliveryService、DeliveryServiceImpl（含 pageQuery、detail、pageQueryListLog 等）。
- Entity：Delivery（字段包括 delivery_number、license_plate、start/end_location、estimated_delivery_time、driver_name、registered_jbq_count 等）。
- Mapper：DeliveryMapper.xml（字段映射）。

3.2 主机设备（JbqServer）
- Controller：JbqServerController（/jbqServer）
  - POST /serverLocation（主机单个定位）
  - POST /serverTrack（主机轨迹）
- Service：IJbqServerService、JbqServerServiceImpl（含经纬度转换与时间窗过滤）。
- 日志：JbqServerLogController（类存在但未提供接口方法）。

3.3 耳标设备与日志（JbqClient、JbqClientLog）
- Controller：JbqClientController（/jbqClient）
  - POST /list（耳标列表分页）
- Controller：JbqClientLogController（/jbqClientLog）
  - POST /jbqLogList（耳标日志分页，按运单时间窗查询）
- Service：IJbqClientService、IJbqClientLogService（含实现）。

3.4 运单预警（Warning）
- Controller：WarningLogController
  - /warningCount（预警统计）
  - POST /queryList（预警记录-分页）
  - GET /warningDetail（预警记录详情）
  - POST /pageQuery（后台系统预警记录-分页，委托 deliveryService.pageQueryList）
- Job：AutoNumWarningJob（自动盘点与预警计算，基于耳标与主机日志）。

3.5 运单设备绑定（DeliveryDevice）
- Controller：DeliveryDeviceController（类存在，未实现接口）。
- Mapper/Service：DeliveryDeviceMapper、IDeliveryDeviceService（接口存在，未见具体实现方法）。

## 4. 前后端接口对接一览

4.1 已对接一致（可工作）
- 前端 api/abroad.js → 后端 DeliveryController
  - /delivery/pageQueryList → DeliveryController.pageQueryList
  - /delivery/detail → DeliveryController.detail
- 前端 api/abroad.js → 后端 JbqServerController
  - /jbqServer/serverLocation → JbqServerController.serverLocation
  - /jbqServer/serverTrack → JbqServerController.serverTrack
- 前端 api/abroad.js → 后端 JbqClientLogController
  - /jbqClientLog/jbqLogList → JbqClientLogController.jbqLogList
- 后端预警接口已具备（前端视图未在本次检索中明确列出，但可按需接入）。

4.2 存在缺口或命名不一致（需统一或补齐）
- 前端 api/shipping.js（装车订单与设备分配）与后端当前仓库接口不一致：
  - /delivery/addDeliveryOrder、/delivery/pageDeliveryOrderList、/delivery/arrangeJbq、/delivery/viewDeliveryOrder 等后端未找到对应实现。
  - /jbqClient/pageQuery（前端使用）后端当前为 /jbqClient/list（命名不一致）。
- 前端 api/abroad.js 的项圈相关接口：
  - /xqClient/pageXqListByDeliveryId、/xqClientLog/xqLogList 后端未检索到对应 Controller。
- 前端 api/isolationQuarantine.js 的检疫模块：
  - /inspection/*（submit、logList、sheepList）后端当前仓库未检索到对应实现。
- 前端 api/isolationQuarantine.js 的主机轨迹：
  - /device/serverTrack 与后端 /jbqServer/serverTrack 路由不一致（需统一）。
- 后端 DeliveryDevice（运单设备绑定）
  - Controller/Service 已存在，但缺少分配、查询等具体 API，难以支撑前端“分配耳标设备”“查看耳标设备”等功能。

## 5. 现状结论
- 已具备的运输核心功能（端到端可联通）
  - 后台运送清单分页与详情查询。
  - 主机设备定位与运单时间窗内轨迹回放。
  - 耳标日志按运单时间窗查询。
  - 预警统计与预警记录（后端已具备接口）。
- 运输相关支撑模块（前端已具备）
  - 用户与司机管理、菜单与权限（动态路由与侧边栏）。
- 主要缺口
  - 装车订单与设备分配（shipping.js）后端接口未对齐或缺失。
  - 检疫模块（inspection）与项圈模块（xqClient/xqClientLog）后端接口缺失，需补齐或统一。
  - 运单设备绑定（DeliveryDevice）需要提供具体分配/查询 API。

## 6. 建议与后续工作
1) 接口命名统一：统一 /jbqClient/pageQuery → /jbqClient/list；/device/serverTrack → /jbqServer/serverTrack。
2) 补齐装车订单与设备分配接口：在后端新增或对齐 /delivery/addDeliveryOrder、/delivery/pageDeliveryOrderList、/delivery/viewDeliveryOrder、/deliveryDevice/pageJbqList、/delivery/arrangeJbq 等。
3) 检疫模块落库：实现 /inspection/submit、/inspection/logList、/inspection/sheepList 等 Controller 与 Service。
4) 项圈模块落库：实现 /xqClient/pageXqListByDeliveryId、/xqClientLog/xqLogList 的 Controller 与 Service。
5) 运单设备绑定完善：补充 DeliveryDevice Controller 的分配、查询、解绑等 API，以支持前端设备绑定流程。
6) 文档化对接清单：在后端生成 Swagger 文档或在前端维护“接口对接表”，确保多端一致性与联调效率。

## 7. 附录：参考文件
- 前端文档：pc-cattle-transportation/README.md、REQUIREMENTS.md、DEVELOPMENT_PLAN.md、DATA_STRUCTURE.md、ARCHITECTURE.md
- 前端关键代码：api/abroad.js、api/shipping.js、api/isolationQuarantine.js、views/entry/details.vue、store/permission.js、router/index.ts
- 后端关键代码：DeliveryController、JbqServerController、JbqClientController、JbqClientLogController、WarningLogController、AutoNumWarningJob、DeliveryDeviceController