# 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 密钥等），在生产环境部署前请务必修改这些配置。