479 lines
13 KiB
Markdown
479 lines
13 KiB
Markdown
# FT546MWS 项目说明
|
||
|
||
## 项目概述
|
||
|
||
FT546MWS 是一个基于 **若依（RuoYi）** 框架定制的制造执行系统（MES）和仓库管理系统（WMS），采用前后端分离架构。项目基于若依 v3.9.0 进行二次开发，集成了工业物联网（IIoT）功能和 AI 能力。
|
||
|
||
### 核心技术栈
|
||
|
||
#### 后端技术
|
||
- **框架**: Spring Boot 3.5.4
|
||
- **Java 版本**: Java 17
|
||
- **数据库**: SQL Server 2019 (主库), MariaDB (从库, 可选)
|
||
- **ORM**: MyBatis 3.0.4 + MyBatis-Plus 3.5.14
|
||
- **连接池**: Druid 1.2.23
|
||
- **缓存**: Redis
|
||
- **权限认证**: JWT + Spring Security
|
||
- **API 文档**: SpringDoc OpenAPI (Swagger)
|
||
- **定时任务**: Quartz
|
||
- **代码生成**: Velocity 模板引擎
|
||
- **工业通信**: HslCommunication 3.7.0 (支持 PLC、Modbus 等工业协议)
|
||
- **AI 集成**: Spring AI 1.0.1 (OpenAI 兼容接口, 向量数据库)
|
||
- **MCP 协议**: Spring AI MCP Client
|
||
- **工具库**: Hutool 5.8.27, FastJSON2 2.0.57, POI 4.1.2
|
||
|
||
#### 前端技术
|
||
- **框架**: Vue 2.6.12
|
||
- **UI 组件库**: Element UI 2.15.14
|
||
- **状态管理**: Vuex 3.6.0
|
||
- **路由**: Vue Router 3.4.9
|
||
- **图表**: ECharts 5.4.0
|
||
- **国际化**: Vue I18n 7.3.2
|
||
- **构建工具**: Vue CLI 4.4.6
|
||
- **其他**: Axios, Quill (富文本编辑器), VueCropper (图片裁剪)
|
||
|
||
### 项目架构
|
||
|
||
这是一个典型的前后端分离的 Maven 多模块项目，包含以下模块：
|
||
|
||
```
|
||
FT546MWS/
|
||
├── ruoyi-admin/ # Web 服务入口模块（启动类、控制器）
|
||
├── ruoyi-framework/ # 框架核心模块（安全配置、拦截器、工具类）
|
||
├── ruoyi-system/ # 系统管理模块（用户、角色、菜单、部门等）
|
||
├── ruoyi-common/ # 通用工具模块（工具类、常量、注解）
|
||
├── ruoyi-generator/ # 代码生成器模块
|
||
├── ruoyi-quartz/ # 定时任务模块
|
||
├── ruoyi-ui/ # 前端 Vue 项目
|
||
├── sql/ # 数据库脚本
|
||
├── bin/ # 批处理脚本（构建、运行、清理）
|
||
└── pom.xml # Maven 父 POM 配置
|
||
```
|
||
|
||
### 业务模块
|
||
|
||
前端业务模块（位于 `ruoyi-ui/src/views/`）：
|
||
- **system**: 系统管理（用户、角色、菜单、部门、岗位、字典、参数、通知）
|
||
- **monitor**: 系统监控（在线用户、操作日志、登录日志、服务监控、缓存监控、定时任务）
|
||
- **tool**: 系统工具（表单构建、代码生成、系统接口）
|
||
- **bas**: 基础数据管理
|
||
- **in**: 入库管理
|
||
- **out**: 出库管理
|
||
- **stock**: 库存管理
|
||
- **check**: 盘点管理
|
||
- **job**: 作业管理
|
||
- **kpi**: 绩效管理
|
||
- **ai**: AI 功能集成
|
||
- **search**: 搜索功能
|
||
- **requestInterface**: 接口请求管理
|
||
- **dashboard**: 仪表盘/数据看板
|
||
|
||
## 环境配置
|
||
|
||
### 数据库配置
|
||
|
||
#### 主数据库（SQL Server）
|
||
- **地址**: 172.16.2.170:1433
|
||
- **数据库名**: FT546-wms
|
||
- **用户名**: sa
|
||
- **密码**: Flrd0914.
|
||
- **驱动**: com.microsoft.sqlserver.jdbc.SQLServerDriver
|
||
|
||
#### 从数据库（MariaDB）- 已禁用
|
||
- **地址**: 172.16.2.170:3307
|
||
- **数据库名**: mydb
|
||
- **用户名**: root
|
||
- **密码**: Flrd0914.
|
||
|
||
### Redis 配置
|
||
- **地址**: 172.16.2.170:6379
|
||
- **数据库索引**: 0
|
||
- **密码**: 123456
|
||
- **超时**: 10s
|
||
|
||
### AI 配置
|
||
- **提供商**: SiliconFlow (OpenAI 兼容)
|
||
- **Base URL**: https://api.siliconflow.cn
|
||
- **对话模型**: deepseek-ai/DeepSeek-V3.1
|
||
- **嵌入模型**: Qwen/Qwen3-Embedding-8B (1024 维度)
|
||
- **向量数据库**: MariaDB (已配置但未完全启用)
|
||
|
||
### Druid 监控
|
||
- **访问地址**: http://localhost:8080/druid/
|
||
- **用户名**: ruoyi
|
||
- **密码**: 123456
|
||
|
||
### API 文档
|
||
- **Swagger UI**: http://localhost:8080/swagger-ui.html
|
||
- **OpenAPI JSON**: http://localhost:8080/v3/api-docs
|
||
|
||
## 构建和运行
|
||
|
||
### 后端构建和运行
|
||
|
||
#### 方式一：使用 Maven 命令
|
||
|
||
```bash
|
||
# 进入项目根目录
|
||
cd D:\workSpace\PROJECT_SPACE\FT546\FT546MWS
|
||
|
||
# 清理并编译
|
||
mvn clean compile
|
||
|
||
# 打包（跳过测试）
|
||
mvn clean package -DskipTests
|
||
|
||
# 运行
|
||
java -jar ruoyi-admin/target/ruoyi-admin.jar
|
||
|
||
# 或使用 JVM 参数运行
|
||
java -Dname=ruoyi-admin.jar -Duser.timezone=Asia/Shanghai -Xms512m -Xmx1024m -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=512m -jar ruoyi-admin/target/ruoyi-admin.jar
|
||
```
|
||
|
||
#### 方式二：使用批处理脚本
|
||
|
||
```bash
|
||
# 进入 bin 目录
|
||
cd bin
|
||
|
||
# 启动服务
|
||
ry.bat
|
||
# 选择 [1] 启动 ruoyi-admin.jar
|
||
|
||
# 停止服务
|
||
ry.bat
|
||
# 选择 [2] 关闭 ruoyi-admin.jar
|
||
|
||
# 重启服务
|
||
ry.bat
|
||
# 选择 [3] 重启 ruoyi-admin.jar
|
||
|
||
# 查看状态
|
||
ry.bat
|
||
# 选择 [4] 查看状态
|
||
```
|
||
|
||
#### 方式三：使用 IDE
|
||
1. 使用 IntelliJ IDEA 或 Eclipse 导入项目（Maven 项目）
|
||
2. 找到启动类：`com.ruoyi.RuoYiApplication`（位于 ruoyi-admin 模块）
|
||
3. 运行启动类
|
||
|
||
### 前端构建和运行
|
||
|
||
#### 开发环境
|
||
|
||
```bash
|
||
# 进入前端目录
|
||
cd ruoyi-ui
|
||
|
||
# 安装依赖（使用 npm 镜像加速）
|
||
npm install --registry=https://registry.npmmirror.com
|
||
|
||
# 或直接安装
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
前端服务启动后，浏览器访问：http://localhost:80
|
||
|
||
默认账号：
|
||
- 用户名: admin
|
||
- 密码: admin123
|
||
|
||
#### 生产环境构建
|
||
|
||
```bash
|
||
# 构建测试环境
|
||
npm run build:stage
|
||
|
||
# 构建生产环境
|
||
npm run build:prod
|
||
```
|
||
|
||
构建产物将输出到 `ruoyi-ui/dist` 目录。
|
||
|
||
#### 使用批处理脚本
|
||
|
||
```bash
|
||
# 进入前端 bin 目录
|
||
cd ruoyi-ui\bin
|
||
|
||
# 运行前端开发服务器
|
||
run-web.bat
|
||
|
||
# 打包前端
|
||
package.bat
|
||
|
||
# 清理构建产物
|
||
clean.bat
|
||
```
|
||
|
||
## 开发规范
|
||
|
||
### 后端开发规范
|
||
|
||
#### 包结构规范
|
||
```
|
||
com.ruoyi
|
||
├── common/ # 通用模块
|
||
│ ├── annotation/ # 自定义注解
|
||
│ ├── constant/ # 常量定义
|
||
│ ├── core/ # 核心配置
|
||
│ ├── enums/ # 枚举类
|
||
│ ├── exception/ # 异常处理
|
||
│ └── utils/ # 工具类
|
||
├── framework/ # 框架核心
|
||
│ ├── aspectj/ # 切面
|
||
│ ├── config/ # 配置类
|
||
│ ├── interceptor/ # 拦截器
|
||
│ ├── security/ # 安全相关
|
||
│ └── web/ # Web 配置
|
||
├── system/ # 系统管理
|
||
│ ├── controller/ # 控制器
|
||
│ ├── domain/ # 实体类
|
||
│ ├── mapper/ # 数据访问层
|
||
│ └── service/ # 业务逻辑层
|
||
│ └── impl/ # 业务实现
|
||
└── web/ # Web 控制器（其他业务模块）
|
||
```
|
||
|
||
#### 代码生成规范
|
||
项目使用代码生成器（`ruoyi-generator` 模块）快速生成 CRUD 代码：
|
||
|
||
1. 在数据库中创建表
|
||
2. 登录系统 → 系统工具 → 代码生成
|
||
3. 导入表并配置生成信息
|
||
4. 生成代码并下载
|
||
5. 将生成的代码复制到对应模块
|
||
|
||
生成的代码包括：
|
||
- Java 实体类（domain）
|
||
- Mapper 接口和 XML（mapper）
|
||
- Service 接口和实现（service/impl）
|
||
- Controller 控制器（controller）
|
||
- Vue 页面（前端 views）
|
||
- API 接口定义（前端 api）
|
||
|
||
#### 控制器规范
|
||
- 使用 `@RestController` 注解
|
||
- 统一返回格式：`AjaxResult`（包装 success、error、data）
|
||
- 权限控制：使用 `@PreAuthorize("@ss.hasPermi('system:user:list')")`
|
||
- 操作日志：使用 `@Log(title = "用户管理", businessType = BusinessType.INSERT)`
|
||
- 分页查询：使用 `startPage()` 方法（继承 BaseController）
|
||
|
||
#### Service 规范
|
||
- 接口定义在 `service` 包
|
||
- 实现类在 `service/impl` 包
|
||
- 使用 `@Service` 注解
|
||
- 业务逻辑方法命名：`selectXxxList`（查询）、`insertXxx`（新增）、`updateXxx`（修改）、`deleteXxxByIds`（删除）
|
||
- 缓存注解：`@Cacheable`（查询）、`@CacheEvict`（更新/删除）
|
||
|
||
#### Mapper 规范
|
||
- 使用 MyBatis-Plus 注解或 XML 配置
|
||
- XML 文件位于 `resources/mapper/` 目录
|
||
- 继承 `BaseMapper<T>` 接口
|
||
- 复杂查询使用 XML 文件编写 SQL
|
||
|
||
### 前端开发规范
|
||
|
||
#### 目录结构规范
|
||
```
|
||
src/
|
||
├── api/ # API 接口定义
|
||
│ ├── login.js # 登录相关
|
||
│ ├── system/ # 系统管理
|
||
│ ├── monitor/ # 监控模块
|
||
│ └── ... # 其他业务模块
|
||
├── assets/ # 静态资源
|
||
│ ├── images/ # 图片
|
||
│ ├── icons/ # 图标
|
||
│ ├── logo/ # Logo
|
||
│ └── styles/ # 样式文件
|
||
├── components/ # 公共组件
|
||
│ ├── Pagination/ # 分页组件
|
||
│ ├── RightToolbar/ # 工具栏
|
||
│ ├── Editor/ # 富文本编辑器
|
||
│ └── ... # 其他组件
|
||
├── directive/ # 自定义指令
|
||
├── layout/ # 布局组件
|
||
├── plugins/ # 插件
|
||
├── router/ # 路由配置
|
||
├── store/ # Vuex 状态管理
|
||
├── utils/ # 工具函数
|
||
├── views/ # 页面组件
|
||
│ ├── system/ # 系统管理页面
|
||
│ ├── monitor/ # 监控页面
|
||
│ └── ... # 其他业务页面
|
||
├── App.vue # 根组件
|
||
├── main.js # 入口文件
|
||
├── permission.js # 权限控制
|
||
└── settings.js # 全局配置
|
||
```
|
||
|
||
#### 组件命名规范
|
||
- 组件名使用 PascalCase（大驼峰）
|
||
- 文件名与组件名保持一致
|
||
- 例如：`UserList.vue`
|
||
|
||
#### API 调用规范
|
||
- API 接口定义在 `src/api/` 目录
|
||
- 使用 Axios 发送请求（已封装）
|
||
- 请求路径配置在 `.env.development` 等环境变量文件中
|
||
- 统一使用 `request.js` 封装的请求方法
|
||
|
||
#### 路由规范
|
||
- 路由配置在 `src/router/index.js`
|
||
- 使用 Vue Router 的路由懒加载
|
||
- 需要权限的路由在路由配置中添加 `meta` 字段
|
||
- 例如：`meta: { title: '用户管理', icon: 'user', noCache: true }`
|
||
|
||
#### 样式规范
|
||
- 使用 SCSS 预处理器
|
||
- 全局样式放在 `src/assets/styles/` 目录
|
||
- 组件样式使用 `<style scoped>` 限定作用域
|
||
- 遵循 BEM 命名规范
|
||
|
||
## 测试
|
||
|
||
### 后端测试
|
||
```bash
|
||
# 运行所有测试
|
||
mvn test
|
||
|
||
# 运行指定测试类
|
||
mvn test -Dtest=UserServiceTest
|
||
|
||
# 运行指定测试方法
|
||
mvn test -Dtest=UserServiceTest#testGetUser
|
||
```
|
||
|
||
### 前端测试
|
||
目前项目未配置前端单元测试，建议添加 Jest 或 Mocha。
|
||
|
||
## 部署
|
||
|
||
### 后端部署
|
||
```bash
|
||
# 打包
|
||
mvn clean package -DskipTests
|
||
|
||
# 生成的 JAR 文件位于：ruoyi-admin/target/ruoyi-admin.jar
|
||
|
||
# 上传到服务器后，使用脚本或命令启动
|
||
nohup java -jar ruoyi-admin.jar > app.log 2>&1 &
|
||
|
||
# 或使用提供的脚本
|
||
./ry.bat # Windows
|
||
./ry.sh # Linux
|
||
```
|
||
|
||
### 前端部署
|
||
```bash
|
||
# 构建生产版本
|
||
npm run build:prod
|
||
|
||
# 生成的静态文件位于：dist/ 目录
|
||
|
||
# 将 dist 目录内容部署到 Nginx 或其他 Web 服务器
|
||
# Nginx 配置示例：
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
root /path/to/dist;
|
||
index index.html;
|
||
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
location /prod-api/ {
|
||
proxy_pass http://backend-server:8080/;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 1. 端口冲突
|
||
- 后端默认端口：8080
|
||
- 前端默认端口：80
|
||
- 如需修改，请编辑 `application.yml`（后端）和 `vue.config.js`（前端）
|
||
|
||
### 2. 数据库连接失败
|
||
- 检查数据库服务是否启动
|
||
- 检查 `application-druid.yml` 中的数据库配置
|
||
- 确保网络可访问数据库服务器
|
||
|
||
### 3. Redis 连接失败
|
||
- 检查 Redis 服务是否启动
|
||
- 检查 `application.yml` 中的 Redis 配置
|
||
- 确保网络可访问 Redis 服务器
|
||
|
||
### 4. 前端跨域问题
|
||
- 开发环境已配置代理（`vue.config.js` 中的 `proxy`）
|
||
- 生产环境需要在 Nginx 或后端配置 CORS
|
||
|
||
### 5. 代码生成器无法使用
|
||
- 确保数据库表已创建
|
||
- 检查表是否有主键
|
||
- 检查字段注释是否完整
|
||
|
||
### 6. 文件上传失败
|
||
- 检查 `application.yml` 中的文件路径配置
|
||
- 确保目录存在且有写入权限
|
||
- 检查文件大小限制（默认 20MB）
|
||
|
||
## 项目特色
|
||
|
||
### 1. 工业物联网集成
|
||
- 使用 HslCommunication 库支持多种工业协议
|
||
- 可与 PLC、Modbus 设备通信
|
||
- 适用于制造业数据采集和设备控制
|
||
|
||
### 2. AI 能力
|
||
- 集成 Spring AI 框架
|
||
- 支持 OpenAI 兼容的大模型接口
|
||
- 支持向量数据库和文档检索
|
||
- 可用于智能问答、数据分析等场景
|
||
|
||
### 3. MCP 协议支持
|
||
- 支持 MCP（Model Context Protocol）客户端
|
||
- 可连接 MCP 服务进行上下文管理
|
||
|
||
### 4. 多数据库支持
|
||
- 主数据库：SQL Server
|
||
- 从数据库：MariaDB（可选）
|
||
- 支持主从读写分离
|
||
|
||
### 5. 代码生成器
|
||
- 一键生成前后端 CRUD 代码
|
||
- 支持自定义模板
|
||
- 大幅提升开发效率
|
||
|
||
### 6. 完善的权限控制
|
||
- 基于 RBAC 的权限模型
|
||
- 支持数据权限控制
|
||
- 支持按钮级别的权限控制
|
||
|
||
### 7. 系统监控
|
||
- 在线用户监控
|
||
- 操作日志记录
|
||
- 系统性能监控
|
||
- 缓存监控
|
||
- 定时任务管理
|
||
|
||
## 联系方式
|
||
|
||
- 若依官方文档：http://doc.ruoyi.vip
|
||
- 若依官方演示：http://vue.ruoyi.vip
|
||
- 项目仓库：http://106.13.86.63:10082/zyr/FT546MWS.git
|
||
|
||
## 许可证
|
||
|
||
本项目基于 MIT 许可证开源，详见 [LICENSE](LICENSE) 文件。
|
||
|
||
---
|
||
|
||
**注意**: 本项目包含敏感信息（数据库密码、API 密钥等），在生产环境部署前请务必修改这些配置。 |