146 lines
8.6 KiB
Markdown
146 lines
8.6 KiB
Markdown
|
牛只运输管理系统需求文档（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。
|
|||
|
|
- 视频播放：页面内嵌 <video> 播放器。
|
|||
|
|
- 文件下载：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 → 生成前端动态路由。
|