diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e06f366 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,479 @@ +# 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` 接口 +- 复杂查询使用 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/` 目录 +- 组件样式使用 `