# logistics_system **Repository Path**: Vespa/logistics_system ## Basic Information - **Project Name**: logistics_system - **Description**: 本功能点列表基于物流核心逻辑设计，覆盖C端用户小程序、B端管理后台、车辆GPS对接、支付结算、网点运营等全维度，技术栈适配SpringBoot3+Vue3+Antdv+MySQL8+UNIAPP，可直接作为开发落地依据。 - **Primary Language**: Unknown - **License**: AGPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-12-05 - **Last Updated**: 2025-12-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: 物流系统, 仓储, 寄快递 ## README # 物流系统项目结构设计 ## 1. 项目整体架构 ### 1.1 技术栈 | 分类 | 技术 | 版本 | |------|------|------| | 后端 | SpringBoot | 3.x | | 后端 | MySQL | 8.0 | | 后端 | MyBatis-Plus | 3.x | | 后端 | Redis | 7.x | | 后端 | JWT | - | | 前端 | Vue | 3.x | | 前端 | Ant Design Vue | 4.x | | 前端 | Vite | 5.x | | 前端 | Axios | 1.x | ### 1.2 架构设计 - **前后端分离架构**：前端和后端通过RESTful API进行通信 - **模块化设计**：前后端均采用模块化设计，便于维护和扩展 - **微服务思想**：后端采用模块化设计，为后续拆分为微服务做准备 - **统一认证授权**：使用JWT进行接口鉴权，统一管理用户权限 ## 2. 后端项目结构 ### 2.1 目录结构 ``` logistics-system-backend/ ├── logistics-common/ # 公共模块 │ ├── src/main/java/ │ │ └── com/logistics/common/ │ │ ├── annotation/ # 自定义注解 │ │ ├── config/ # 公共配置 │ │ ├── constant/ # 常量定义 │ │ ├── enums/ # 枚举类型 │ │ ├── exception/ # 异常处理 │ │ ├── model/ # 公共模型 │ │ ├── utils/ # 工具类 │ │ └── validator/ # 数据校验 │ └── pom.xml ├── logistics-user/ # 用户中心模块 │ ├── src/main/java/ │ │ └── com/logistics/user/ │ │ ├── controller/ # 控制器 │ │ ├── mapper/ # 数据访问层 │ │ ├── model/ # 数据模型 │ │ ├── service/ # 业务逻辑层 │ │ └── vo/ # 视图模型 │ └── pom.xml ├── logistics-order/ # 订单模块 │ ├── src/main/java/ │ │ └── com/logistics/order/ │ │ ├── controller/ # 控制器 │ │ ├── mapper/ # 数据访问层 │ │ ├── model/ # 数据模型 │ │ ├── service/ # 业务逻辑层 │ │ └── vo/ # 视图模型 │ └── pom.xml ├── logistics-network/ # 网点管理模块 │ ├── src/main/java/ │ │ └── com/logistics/network/ │ │ ├── controller/ # 控制器 │ │ ├── mapper/ # 数据访问层 │ │ ├── model/ # 数据模型 │ │ ├── service/ # 业务逻辑层 │ │ └── vo/ # 视图模型 │ └── pom.xml ├── logistics-vehicle/ # 车辆与GPS管理模块 │ ├── src/main/java/ │ │ └── com/logistics/vehicle/ │ │ ├── controller/ # 控制器 │ │ ├── mapper/ # 数据访问层 │ │ ├── model/ # 数据模型 │ │ ├── service/ # 业务逻辑层 │ │ └── vo/ # 视图模型 │ └── pom.xml ├── logistics-auth/ # 权限管理模块 │ ├── src/main/java/ │ │ └── com/logistics/auth/ │ │ ├── controller/ # 控制器 │ │ ├── mapper/ # 数据访问层 │ │ ├── model/ # 数据模型 │ │ ├── service/ # 业务逻辑层 │ │ └── vo/ # 视图模型 │ └── pom.xml ├── logistics-interface/ # 接口对接模块 │ ├── src/main/java/ │ │ └── com/logistics/interface/ │ │ ├── controller/ # 控制器 │ │ ├── mapper/ # 数据访问层 │ │ ├── model/ # 数据模型 │ │ ├── service/ # 业务逻辑层 │ │ └── vo/ # 视图模型 │ └── pom.xml ├── logistics-msg/ # 消息通知模块 │ ├── src/main/java/ │ │ └── com/logistics/msg/ │ │ ├── controller/ # 控制器 │ │ ├── mapper/ # 数据访问层 │ │ ├── model/ # 数据模型 │ │ ├── service/ # 业务逻辑层 │ │ └── vo/ # 视图模型 │ └── pom.xml ├── logistics-admin/ # 管理端模块 │ ├── src/main/java/ │ │ └── com/logistics/admin/ │ │ ├── controller/ # 控制器 │ │ ├── mapper/ # 数据访问层 │ │ ├── model/ # 数据模型 │ │ ├── service/ # 业务逻辑层 │ │ └── vo/ # 视图模型 │ └── pom.xml ├── logistics-app/ # 小程序端模块 │ ├── src/main/java/ │ │ └── com/logistics/app/ │ │ ├── controller/ # 控制器 │ │ ├── mapper/ # 数据访问层 │ │ ├── model/ # 数据模型 │ │ ├── service/ # 业务逻辑层 │ │ └── vo/ # 视图模型 │ └── pom.xml └── pom.xml # 父项目POM ``` ### 2.2 模块职责 | 模块 | 职责 | |------|------| | logistics-common | 公共模块，提供枚举类型、工具类、常量等基础组件 | | logistics-user | 用户中心模块，处理用户注册登录、实名认证、地址簿管理等 | | logistics-order | 订单模块，处理寄件订单、物流轨迹、支付结算等 | | logistics-network | 网点管理模块，处理网点信息、人员管理、物料管理等 | | logistics-vehicle | 车辆与GPS管理模块，处理车辆信息、司机管理、GPS监控等 | | logistics-auth | 权限管理模块，处理角色管理、账号管理等 | | logistics-interface | 接口对接模块，处理GPS接口、支付接口、地图接口等 | | logistics-msg | 消息通知模块，处理消息模板、用户消息、管理端消息等 | | logistics-admin | 管理端模块，提供管理端API | | logistics-app | 小程序端模块，提供小程序API | ## 3. 前端项目结构 ### 3.1 目录结构 ``` logistics-system-frontend/ ├── src/ │ ├── assets/ # 静态资源 │ │ ├── css/ # 样式文件 │ │ ├── fonts/ # 字体文件 │ │ ├── icons/ # 图标文件 │ │ └── images/ # 图片文件 │ ├── components/ # 公共组件 │ ├── composables/ # 组合式函数 │ ├── config/ # 配置文件 │ ├── layouts/ # 布局组件 │ ├── modules/ # 业务模块 │ │ ├── admin/ # 管理端模块 │ │ │ ├── components/ # 管理端组件 │ │ │ ├── pages/ # 管理端页面 │ │ │ ├── router/ # 管理端路由 │ │ │ └── store/ # 管理端状态管理 │ │ ├── app/ # 小程序端模块 │ │ │ ├── components/ # 小程序组件 │ │ │ ├── pages/ # 小程序页面 │ │ │ ├── router/ # 小程序路由 │ │ │ └── store/ # 小程序状态管理 │ │ ├── user/ # 用户中心模块 │ │ ├── order/ # 订单模块 │ │ ├── search/ # 查快递模块 │ │ └── payment/ # 支付结算模块 │ ├── router/ # 路由配置 │ ├── services/ # API服务 │ ├── store/ # 状态管理 │ ├── utils/ # 工具类 │ ├── App.vue # 根组件 │ └── main.ts # 入口文件 ├── public/ # 公共静态资源 ├── .gitignore # Git忽略文件 ├── index.html # HTML模板 ├── package.json # 项目依赖 ├── tsconfig.json # TypeScript配置 ├── vite.config.ts # Vite配置 └── README.md # 项目说明 ``` ### 3.2 模块职责 | 模块 | 职责 | |------|------| | user | 用户中心模块，处理登录注册、实名认证、地址簿管理等 | | order | 订单模块，处理寄件订单、物流轨迹等 | | search | 查快递模块，处理单号查询、订单列表、轨迹详情等 | | payment | 支付结算模块，处理运费计算、支付功能、账单管理等 | | admin | 管理端模块，处理订单管理、网点管理、车辆管理等 | | app | 小程序端模块，处理小程序相关功能 | ## 4. API设计规范 ### 4.1 RESTful API设计原则 1. **资源命名**：使用名词表示资源，如`/api/users`、`/api/orders` 2. **HTTP方法**：使用HTTP方法表示操作类型 - GET：获取资源 - POST：创建资源 - PUT：更新资源 - DELETE：删除资源 - PATCH：部分更新资源 3. **状态码**：使用标准HTTP状态码表示响应状态 - 200 OK：请求成功 - 201 Created：资源创建成功 - 400 Bad Request：请求参数错误 - 401 Unauthorized：未授权 - 403 Forbidden：禁止访问 - 404 Not Found：资源不存在 - 500 Internal Server Error：服务器内部错误 4. **响应格式**：统一使用JSON格式响应 ```json { "code": 200, "message": "success", "data": {} } ``` ### 4.2 API版本管理 使用URL路径进行版本管理，如`/api/v1/users`、`/api/v2/orders` ### 4.3 API安全 1. **认证授权**：使用JWT进行接口鉴权 2. **参数校验**：对所有API请求参数进行校验 3. **防SQL注入**：使用参数化查询 4. **防XSS攻击**：对输入输出进行转义 5. **接口防刷**：限制API请求频率 ## 5. 前后端交互流程 1. **用户登录**：用户通过前端页面输入账号密码，前端调用登录API，后端验证成功后返回JWT token 2. **API请求**：前端在后续请求中携带JWT token，后端验证token合法性 3. **数据处理**：后端处理请求，返回JSON格式响应 4. **前端渲染**：前端接收响应，渲染页面 ## 6. 数据库设计 数据库设计详见`db/init.sql`文件，包括表结构、索引设计、初始化数据等。 ## 7. 部署架构 ### 7.1 开发环境 - **后端**：本地开发，使用IntelliJ IDEA等IDE - **前端**：本地开发，使用VS Code等IDE - **数据库**：本地MySQL数据库 - **Redis**：本地Redis服务 ### 7.2 测试环境 - **后端**：部署到测试服务器，使用Docker容器化部署 - **前端**：部署到测试服务器，使用Nginx作为静态资源服务器 - **数据库**：测试环境MySQL数据库 - **Redis**：测试环境Redis服务 ### 7.3 生产环境 - **后端**：部署到生产服务器，使用Docker容器化部署，配合Kubernetes进行容器编排 - **前端**：部署到CDN，使用Nginx作为静态资源服务器 - **数据库**：生产环境MySQL数据库，使用主从复制、读写分离 - **Redis**：生产环境Redis集群，提高可用性 - **负载均衡**：使用Nginx或云负载均衡器进行请求分发 - **监控告警**：使用Prometheus+Grafana进行监控，使用ELK进行日志管理 ## 8. 开发规范 ### 8.1 后端开发规范 1. **代码风格**：遵循阿里巴巴Java开发规范 2. **命名规范**：使用驼峰命名法，类名首字母大写，方法名、变量名首字母小写 3. **注释规范**：对类、方法、重要代码块添加注释 4. **异常处理**：统一处理异常，返回友好的错误信息 5. **日志规范**：使用SLF4J+Logback进行日志管理，对重要操作记录日志 ### 8.2 前端开发规范 1. **代码风格**：遵循Vue3官方开发规范 2. **命名规范**：使用驼峰命名法，组件名使用PascalCase，变量名使用camelCase 3. **注释规范**：对组件、方法、重要代码块添加注释 4. **组件设计**：遵循单一职责原则，组件粒度适中 5. **状态管理**：使用Pinia进行状态管理，合理划分状态模块 ## 9. 测试规范 1. **单元测试**：对核心业务逻辑进行单元测试，使用JUnit、Mockito等测试框架 2. **集成测试**：对模块间的交互进行集成测试 3. **接口测试**：对API接口进行测试，使用Postman、Swagger等工具 4. **UI测试**：对前端页面进行UI测试，使用Cypress等测试框架 5. **性能测试**：对系统进行性能测试，使用JMeter等工具 ## 10. 文档规范 1. **接口文档**：使用Swagger或Knife4j生成API接口文档 2. **技术文档**：编写技术设计文档，包括架构设计、模块设计、数据库设计等 3. **用户文档**：编写用户操作手册，包括功能说明、操作步骤等 4. **部署文档**：编写部署手册，包括环境要求、部署步骤、配置说明等 ## 11. 版本管理 1. **Git分支管理**：使用Git Flow工作流，包括master、develop、feature、release、hotfix等分支 2. **版本号规范**：使用语义化版本号，如1.0.0、1.1.0、1.1.1等 3. **发布流程**：严格按照测试流程进行发布，包括测试、灰度发布、正式发布等 ## 12. 安全规范 1. **数据安全**：对敏感数据进行加密存储，如密码使用BCrypt加密 2. **接口安全**：使用HTTPS协议，防止数据传输过程中被窃取 3. **权限控制**：实现细粒度的权限控制，确保用户只能访问授权资源 4. **漏洞扫描**：定期进行漏洞扫描，及时修复安全漏洞 5. **安全审计**：对重要操作进行审计，记录操作日志 ## 13. 性能优化 1. **数据库优化**：合理设计索引，优化SQL查询，使用缓存减少数据库访问 2. **代码优化**：优化算法，减少不必要的计算和IO操作 3. **缓存优化**：使用Redis缓存热点数据，提高访问速度 4. **前端优化**：使用懒加载、代码分割、图片压缩等技术优化前端性能 5. **服务器优化**：优化服务器配置，提高并发处理能力 ## 14. 扩展性设计 1. **模块化设计**：采用模块化设计，便于后续扩展新功能 2. **接口设计**：设计灵活的接口，便于后续扩展新的业务逻辑 3. **数据库设计**：设计可扩展的数据库结构，便于后续添加新字段和表 4. **架构设计**：采用微服务思想，便于后续拆分为微服务 ## 15. 可靠性设计 1. **错误处理**：统一处理错误，返回友好的错误信息 2. **重试机制**：对重要操作实现重试机制，提高成功率 3. **容错设计**：实现服务降级、熔断等容错机制，提高系统可靠性 4. **备份恢复**：定期备份数据库，确保数据安全 5. **监控告警**：实现监控告警机制，及时发现和处理问题 ## 16. 可维护性设计 1. **代码规范**：遵循统一的代码规范，提高代码可读性和可维护性 2. **文档齐全**：编写齐全的文档，便于后续维护 3. **测试覆盖**：提高测试覆盖率，确保代码质量 4. **日志管理**：完善的日志管理，便于排查问题 5. **注释规范**：添加必要的注释，提高代码可读性 ## 17. 总结 本项目结构设计遵循了模块化、可扩展、可维护、高性能、高可靠的原则，采用了前后端分离架构，便于后续开发和维护。后端采用SpringBoot3框架，前端采用Vue3+Antdv框架，使用RESTful API进行通信，确保了系统的灵活性和扩展性。