cattleTransportation/需求文档.md

牛只运输管理系统需求文档（V1.0）

一、项目概述

• 目标：为牛只运输与检疫业务提供从账号权限、运单管理、设备定位与轨迹、隔离检疫、告警日志到司机与用户管理的全流程管理平台。
• 形态：前端 Web（Vue3 + Vite + Pinia + Element Plus），后端 Spring Boot（MyBatis-Plus + Sa-Token），MySQL 数据库，Redis 缓存，第三方短信（腾讯云），地图（百度地图）。

二、系统架构与部署

• 前端
  • 技术栈：Vue3、TypeScript、Pinia、Vue Router、Element Plus、Axios、Vite。
  • 路由：静态路由（登录/首页等）+ 动态路由（通过后端菜单驱动）。
  • 权限：路由守卫 + 自定义指令（按钮级权限），依赖用户权限集与角色集。
  • 开发服务：Vite 启动端口 8080，代理 /api 到 http://127.0.0.1:16200（vite.config.ts）。
• 后端
  • 技术栈：Java 1.8、Spring Boot 2.6.13、MyBatis-Plus、Sa-Token。
  • 应用参数：端口 16200，Context Path /api，dev profile。
  • 数据源：MySQL 129.211.213.226:3306/cattletrade（root/Aiotagro@741）。
  • 缓存：Redis 129.211.213.226:6379（Aiotagro@741）。
  • 短信：腾讯云（代码存在常量类与集成）。

三、用户角色与权限

• 角色（需确认）：司机、货源方、采购方、系统管理员、资金方（原文称“四个角色”，但列出了五类，待业务确认）。
• 其他潜在角色：企业管理员/普通操作员、检疫人员。
• 权限模型：基于 sys_user、sys_role、sys_menu 三表，支持路由级与按钮级权限控制。
• 前端控制：
  • 路由守卫：白名单 login；无 token 跳登录；已登录拉取菜单后动态生成路由。
  • 指令权限：hasPermi/hasRole 系列，控制页面元素显示与操作。

【新增需求】权限与数据可见性

• 菜单权限管理：由 sys_menu 维护菜单树与权限点；后端依据用户身份返回可见菜单；前端仅渲染可见节点。菜单权限调整后需支持动态生效（用户重新获取菜单即可生效）。
• 操作权限管理：基于权限码（permKey）控制页面按钮与接口访问；前端通过指令/工具（hasPermi/hasRole）进行显隐与禁用；后端控制器或网关层进行权限拦截与校验，避免越权调用。
• 登录识别 role_id 与数据范围：登录成功后读取 sys_user.role_id，并以此作为数据作用域依据；普通角色仅能访问本角色范围内的数据（列表、详情、统计等）。
• 超级管理员权限：超级管理员拥有最高权限与全数据可见性，可管理所有角色与菜单；建议以固定角色编码（如 ROLE_SUPER_ADMIN）或配置标识控制。

四、主要功能模块 1）登录与认证

• 密码登录与验证码登录（LoginDto.loginType 0/1）。
• Token 统一在请求拦截器注入 Authorization；401/650 触发重新登录。

2）运单管理与入场核验（Entry）

• 检疫列表与查询：inspectionList（attestation.vue）。
• 详情：waybillDetail（details.vue），展示运单基本信息、预警信息、关联设备。
• 视频：页面预留“核验装车过磅视频”展示位。
• 下载：支持文件直链下载。
• 【新增功能】新增运送清单：在“运送清单/列表页”增加“新增”按钮，打开运送清单表单对话框，支持创建运输单。
  • 权限要求：仅具备相应操作权限的角色可见与可操作（例如 hasPermi('delivery:add')）。
  • 表单字段（建议）：运单号、发货方、采购方、车牌号、司机信息、设备绑定（主机/耳标/项圈）、预计出发/到达时间、起点/目的地、牛只数量/重量、检疫信息（可选）、备注。
  • 校验规则：必填项校验、手机号/车牌/时间合法性校验、设备选择合法性校验。
  • 提交与反馈：提交至后端创建接口（POST /api/delivery/create 或同类接口，具体以后端为准），成功后刷新列表并提示；失败给出明确错误信息。

3）硬件设备与定位/轨迹（Hardware）

• 主机定位：hostLocation → 地图标注经纬度与时间（locationDialog.vue / details.vue）。
• 运动轨迹：hostTrack → 展示 polyline 与时间点集合（details.vue）。
• 设备台账：设备编号、类型（主机/耳标/项圈）、所属用户、佩戴状态等（shipping/lookDialog.vue）。

4）隔离检疫（Isolation/Quarantine）

• 隔离厂列表与管理（src/api/quarantine.js、isolationQuarantine.js）。
• 入场检疫与详情与运单联动（inspectionList、waybillDetail）。

5）预警日志（WarningLog）

• 列表与详情、分页查询与过滤。

6）用户与司机管理

• 用户账户与状态管理（src/api/sys.js）。
• 司机信息采集：姓名、手机号、车牌、驾驶证/行驶证/备案码、车头车身照片，表单校验与上传（userManage/driverDialog.vue）。

7）系统管理

• 岗位管理（/system/post 路由存在）。
• 菜单与权限管理（后端返回菜单驱动动态路由）。

8）支付与订单（如有）

• pay_order 表存在，具体功能启用情况待确认。

9）数据导出/下载与多媒体

• 文件下载直链。
• 视频播放组件位（过磅视频等）。

五、核心数据实体（初步）

• 系统与权限：sys_user、sys_role、sys_menu。
• 运单与运输：delivery、delivery_device（运单设备关联）。
• 硬件与定位：jbq_server、jbq_client、jbq_log；xq_client、xq_log；warning_log。
• 成员与司机：member_user、member_driver（需确认具体表名）。
• 支付与订单：pay_order（需确认是否启用）。

六、关键业务流程 1）登录流程

• 未登录访问非白名单路由 → 跳转登录。
• 登录成功 → 拉取菜单 → 生成动态路由 → 进入首页。

2）运单入场核验流程

• 检索检疫列表 inspectionList → 查看详情 waybillDetail → 查看主机定位 hostLocation 与轨迹 hostTrack → 下载/打印 → 返回列表。

3）设备定位与轨迹

• 选择设备 serverDeviceId → 后端返回经纬度与时间 → 前端在百度地图组件展示。

4）司机信息采集与审核

• 表单录入与资质图片上传 → 校验 → 提交 → 列表展示与状态维护。

5）权限菜单变更

• 后端更新菜单权限 → 前端用户登录拉取最新菜单 → 动态路由更新。

七、第三方与集成

• Redis：登录态与验证码缓存。
• 腾讯云短信：验证码登录或通知。
• 百度地图：vue-baidu-map-3x 与 BMap API。
• 视频播放：页面内嵌
• 文件下载：URL 跳转下载。

八、运行环境与配置

• 前端
  • 开发端口：8080。
  • 代理：/api → http://127.0.0.1:16200（vite.config.ts）。
  • Axios：utils/axios.ts 使用 VITE_API_DOMAIN；utils/request.js 使用 VITE_APP_BASE_API；建议统一为单一实例与变量。
• 后端
  • 端口：16200，Context Path：/api，profile：dev。
  • MySQL：129.211.213.226:3306/cattletrade（root / Aiotagro@741）。
  • Redis：129.211.213.226:6379（Aiotagro@741）。

九、非功能性需求

• 安全
  • Token 校验与过期处理；401/650 统一重登录。
  • 请求防重复提交；按钮级权限与路由级权限控制。
• 性能
  • 列表分页与筛选；地图轨迹懒加载；Vite 按需构建。
• 可靠性
  • 日志与告警完善；定位与轨迹异常提示与降级。
• 可维护性
  • 统一 API 模块与状态管理；动态菜单减少硬编码。

十、待确认事项

• 角色清单与职责范围：现有“司机、货源方、采购方、系统管理员、资金方”具体权限矩阵。
• 接口清单：逐一从 src/api 与后端 Controller/Mapper 编目，形成规范接口文档（URL/方法/入参/出参/状态码）。
• 数据字典与枚举：设备类型、运单状态、告警类型等统一字典。
• 文件/视频来源与存储策略：本地/云存储与访问鉴权。
• 后端启动提示“no MyBatis mapper found”原因与影响。

十一、下一步计划 1）统一 Axios 与环境变量，规范请求层。 2）拉取并整理后端接口清单，补齐字段说明与状态码约定。 3）梳理并输出 RBAC 权限矩阵（角色 × 权限点）。 4）补充关键流程的交互原型与边界条件。 5）完善前后端环境配置说明（.env.development / .env.production 与代理策略）。

附：已知接口示例（不完整，需对齐后端）

• GET /api/jbqServer/serverList → 主机服务列表。
• 登录接口：支持密码登录与验证码登录（参见 src/api/sys.js 与 LoginDto）。
• 动态菜单：getUserMenu → 生成前端动态路由。