ar-inspection/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个基于 RuoYi-Vue-Plus 5.5.1 框架的 AR 智能巡检平台,采用前后端分离架构:

• 后端: Spring Boot 3.5.7 + Java 17 + Maven 多模块
• 前端: Vue 3.5.13 + TypeScript 5.8.3 + Vite 6.3.2
• 数据库: MySQL / PostgreSQL / Oracle + MyBatis-Plus 3.5.14
• 缓存: Redis + Redisson 3.51.0 (非 Lettuce)
• 认证: Sa-Token 1.44.0 (非 Spring Security)

开发环境要求

后端环境:

• JDK 17 或 JDK 21
• Maven 3.6+
• MySQL 5.7+ / PostgreSQL / Oracle / SQL Server
• Redis 5.0+

前端环境:

• Node.js >= 18.18.0
• npm >= 8.9.0

项目架构详解

后端模块结构

ar-inspection/
├── ruoyi-admin/              # 主应用模块,Web服务入口
├── ruoyi-common/             # 通用功能模块(插件化架构)
│   ├── ruoyi-common-core/       # 核心工具包
│   ├── ruoyi-common-mybatis/    # MyBatis-Plus 集成
│   ├── ruoyi-common-security/   # Sa-Token 安全认证
│   ├── ruoyi-common-redis/      # Redis 缓存
│   ├── ruoyi-common-oss/        # 对象存储(S3/MinIO)
│   ├── ruoyi-common-doc/        # SpringDoc API文档
│   ├── ruoyi-common-web/        # Web 配置
│   ├── ruoyi-common-json/       # Jackson 序列化
│   ├── ruoyi-common-log/        # 操作日志
│   ├── ruoyi-common-job/        # SnailJob 定时任务
│   ├── ruoyi-common-translation/# 数据翻译
│   ├── ruoyi-common-encrypt/    # 数据加解密
│   ├── ruoyi-common-sensitive/  # 数据脱敏
│   ├── ruoyi-common-idempotent/ # 幂等处理
│   ├── ruoyi-common-ratelimiter/# 限流
│   ├── ruoyi-common-social/     # 第三方登录
│   ├── ruoyi-common-sms/        # 短信服务
│   ├── ruoyi-common-mail/       # 邮件服务
│   └── ruoyi-common-websocket/  # WebSocket/SSE
├── ruoyi-modules/            # 业务功能模块
│   ├── ruoyi-system/            # 系统管理模块
│   ├── ruoyi-inspection/        # AR智能巡检模块
│   ├── ruoyi-generator/         # 代码生成器
│   ├── ruoyi-demo/              # 演示案例
│   ├── ruoyi-workflow/          # 工作流模块(Warm-Flow)
│   └── ruoyi-job/               # 任务调度
└── ruoyi-extend/             # 扩展模块
    ├── ruoyi-monitor-admin/     # Spring Boot Admin 监控
    └── ruoyi-snailjob-server/   # SnailJob 调度中心

前端目录结构

plus-ui/
├── src/
│   ├── api/                  # API 接口定义
│   │   ├── demo/                # 演示模块
│   │   ├── monitor/             # 监控模块
│   │   ├── system/              # 系统管理
│   │   ├── tool/                # 工具模块
│   │   └── workflow/            # 工作流
│   ├── assets/               # 静态资源
│   ├── components/           # 公共组件
│   ├── directive/            # 自定义指令
│   ├── hooks/                # 组合式函数
│   ├── layout/               # 布局组件
│   ├── lang/                 # 国际化
│   ├── plugins/              # 插件封装
│   ├── router/               # 路由配置
│   ├── store/                # Pinia 状态管理
│   ├── types/                # TypeScript 类型定义
│   ├── utils/                # 工具函数
│   └── views/                # 页面视图
├── vite/                     # Vite 插件配置
└── vite.config.ts            # Vite 配置文件

核心技术架构

后端核心组件

1. 权限认证: Sa-Token + JWT (非 Spring Security)

   • 支持登录校验、角色校验、权限校验、二级认证
   • 支持复杂权限表达式 (AND/OR)
   • 轻量级,性能优于 Spring Security

2. ORM 框架: MyBatis-Plus

   • 雪花ID主键 (ASSIGN_ID)
   • 多租户插件 (默认启用)
   • 数据权限插件
   • 分页插件
   • 逻辑删除支持

3. 缓存方案: Redisson (非 Lettuce)

   • 支持分布式锁 (Lock4j)
   • 支持 Spring Cache 注解
   • 更强大的分布式特性

4. 多数据源: Dynamic-Datasource

   • 支持异构数据库动态切换
   • 支持多主多从、混合模式

5. 任务调度: SnailJob (非 Quartz)

   • 分布式任务调度
   • 支持分片、重试、DAG 任务流
   • 可视化管理界面

6. 工作流引擎: Warm-Flow

   • 国产工作流引擎
   • 支持复杂审批流程
   • 轻量级,易于扩展

7. 文件存储: MinIO / AWS S3

   • 支持七牛、阿里云、腾讯云等
   • 统一的 OSS 抽象接口

8. API 文档: SpringDoc (非 Springfox)

   • 基于 javadoc 注释自动生成
   • 零注解入侵
   • 符合 OpenAPI 3.0 规范

前端核心特性

1. UI 框架: Element Plus 2.9.8
2. 状态管理: Pinia 3.0.2 (非 Vuex)
3. 路由: Vue Router 4.5.0
4. HTTP 客户端: Axios 1.8.4
5. 表格组件: vxe-table 4.13.7
6. 接口加密: RSA + AES 动态加密
7. 原子化CSS: UnoCSS 66.5.2

常用命令

后端开发

# 构建项目(跳过测试)
mvn clean install -DskipTests

# 启动后端服务
cd ruoyi-admin && mvn spring-boot:run -Dspring-boot.run.profiles=dev

# 运行测试
mvn test

# 打包生产环境
mvn clean package -Pprod -DskipTests

前端开发

# 安装依赖
cd plus-ui && npm install --registry=https://registry.npmmirror.com

# 启动开发服务器
npm run dev

# 构建生产环境
npm run build:prod

# 代码检查和修复
npm run lint:eslint:fix

# 代码格式化
npm run prettier

自定义斜杠命令

• /build - 构建整个 Maven 项目并运行测试
• /start-backend - 启动后端 Spring Boot 应用
• /start-frontend - 启动前端 Vue3 开发服务器
• /new-module - 创建新的业务模块(Controller, Service, Mapper, Domain)
• /analyze - 分析项目结构并生成架构文档
• /lint - 运行前端代码检查和格式化

配置说明

后端配置

主配置文件: ruoyi-admin/src/main/resources/application.yml

环境配置文件:

• application-dev.yml - 开发环境
• application-prod.yml - 生产环境
• application-local.yml - 本地环境

多环境切换: 通过 Maven Profile 切换

# 开发环境(默认)
mvn spring-boot:run -Pdev

# 本地环境
mvn spring-boot:run -Plocal

# 生产环境
mvn spring-boot:run -Pprod

重要配置项

1. 多租户: tenant.enable=true (默认开启)
2. 接口加密: api-decrypt.enabled=true
3. 数据加密: mybatis-encryptor.enable=false (默认关闭)
4. WebSocket: 默认关闭,推荐使用 SSE
5. 验证码: captcha.enable=true
6. 逻辑删除: mybatis-plus.enableLogicDelete=true

前端配置

环境变量: .env.development / .env.production

# 应用标题
VITE_APP_TITLE = AR智能巡检平台

# 后端接口地址
VITE_APP_BASE_API = /dev-api

# 应用访问路径
VITE_APP_CONTEXT_PATH = /

代理配置: vite.config.ts 中配置后端代理,默认代理到 http://localhost:8080

数据库设计

主键策略

• 使用 雪花ID (ASSIGN_ID),不使用数据库自增
• 分布式友好,全局唯一
• 64位长整型

逻辑删除

• 默认启用逻辑删除
• 删除字段: del_flag (0=正常, 1=删除)
• 查询时自动过滤已删除数据

多租户设计

• 自动添加 tenant_id 字段
• 支持租户隔离
• 排除表在配置中指定
• 使用 @TenantIgnore 注解排除租户过滤

数据权限

• 基于部门和角色的数据权限
• 支持本部门、本部门及以下、仅本人等权限范围
• 通过 MyBatis-Plus 插件实现

开发规范

后端代码分层

controller/   # 控制器层,处理HTTP请求
service/      # 业务逻辑层接口
service/impl/ # 业务逻辑实现
mapper/       # 数据访问层
domain/       # 实体类
vo/           # 视图对象
bo/           # 业务对象

必须遵循的规范

1. 实体类: 继承 BaseEntity 并使用 Lombok 注解
2. Mapper 接口: 继承 BaseMapperPlus<实体类Mapper, 实体类, VO类>
3. Service 实现: 使用 @RequiredArgsConstructor 注入依赖
4. Controller 返回: 统一返回 R<T> 类型
5. 权限控制: 使用 @SaCheckPermission 注解
6. API 文档: 添加 @Tag, @Operation, @Parameters 注解

命名约定

• 实体类: XxxEntity 或直接 Xxx
• Mapper: XxxMapper
• Service: IXxxService (接口) / XxxServiceImpl (实现)
• Controller: XxxController
• VO: XxxVo
• BO: XxxBo

数据库操作

• 优先使用 MyBatis-Plus 的内置方法
• 复杂查询在 Mapper XML 中编写
• 使用 LambdaQueryWrapper 构建动态查询
• 分页使用 TableDataInfo<T> 和 PageQuery

前端开发规范

1. 组件开发:

   • 使用 Vue 3 Composition API (<script setup lang="ts">)
   • 优先使用 Element Plus 组件
   • 表单使用 el-form + 表单验证规则
   • 表格使用 vxe-table 或 el-table

2. API 调用:

   • API 定义在 src/api/ 目录,按模块分文件
   • 使用 request 工具发起请求
   • 统一错误处理,使用 ElMessage 显示提示

3. 状态管理:

   • 使用 Pinia 管理全局状态
   • Store 文件放在 src/store/modules/

4. 样式规范:

   • 使用 <style scoped lang="scss">
   • 优先使用 UnoCSS 原子类
   • 响应式布局使用 Element Plus 栅格系统

监控与运维

服务端口

• 后端应用: 8080
• 前端应用: 80
• Spring Boot Admin: 9090
• SnailJob Server: 8800
• SnailJob Client: 28080

监控工具

1. 应用监控: Spring Boot Admin

   • 访问地址: http://localhost:9090/admin
   • 用户名/密码: 在 application.yml 中配置
   • 功能: 应用健康检查、日志查看、环境信息

2. 任务调度中心: SnailJob

   • 访问地址: http://localhost:8800/snail-job
   • 功能: 任务管理、执行日志、任务编排

3. API 文档: SpringDoc

   • 开发环境: http://localhost:8080/doc.html
   • 生产环境: 根据需要启用/禁用
   • 零注解,基于 Javadoc 自动生成

4. 日志管理

   • 日志路径: ./logs/sys-console.log
   • 使用 Logback
   • 支持在线日志查看(通过监控中心)

代码生成器

• 位置: 系统管理 -> 代码生成
• 访问: http://localhost:8080/tool/gen
• 功能:
  • 支持多数据源代码生成
  • 自动生成 Controller、Service、Mapper、Vue 页面
  • 符合项目规范的代码风格
  • 生成后需根据业务需求调整

项目特定注意事项

AR 巡检业务模块 (ruoyi-inspection)

• 核心业务逻辑: 位于 ruoyi-modules/ruoyi-inspection
• 主要功能: 设备点位管理、巡检任务、缺陷记录、AR 技术集成
• 修改建议: 涉及核心业务,修改需谨慎
• 依赖模块: 依赖所有 ruoyi-common 核心模块

权限控制

• 使用 Sa-Token 进行权限认证
• 权限字符串格式: 模块:功能:操作 (如 system:user:add)
• 菜单权限在数据库 sys_menu 表管理
• 使用 @SaCheckPermission("system:user:list") 注解控制接口权限

文件存储

• 使用 OSS 进行文件存储(支持 MinIO, 阿里云OSS等)
• 配置在 application-*.yml 中的 oss 节点
• 统一的文件上传下载接口

多租户支持

• 框架内置多租户功能
• 通过 @TenantIgnore 注解排除租户过滤
• 租户隔离在数据库层面自动实现

Docker 部署

# 使用 docker-compose 启动所有服务
cd script/docker
docker-compose up -d

# 包含: MySQL + Redis + Nginx + 应用服务

# 停止所有服务
docker-compose down

测试

• 单元测试: JUnit 5 + Spring Boot Test
• 运行测试: mvn test
• 测试分组: 通过 @Tag 注解标记,根据环境执行
  • @Tag("dev") - 开发环境测试
  • @Tag("prod") - 生产环境测试
  • @Tag("exclude") - 排除的测试

问题排查

后端启动失败

• 检查数据库连接配置
• 检查 Redis 是否启动
• 查看日志: logs/sys-console.log

前端启动失败

• 删除 node_modules 重新安装
• 检查 Node.js 版本 >= 18.18.0
• 检查端口 80 是否被占用

接口调用失败

• 检查后端服务是否启动
• 检查跨域配置
• 查看浏览器控制台和网络请求

框架技术注意事项

1. 插件化架构: 各 ruoyi-common-* 模块相互独立,可按需引入
2. 编码规范: 严格遵守 Alibaba Java 编码规范
3. 对象转换: 使用 MapStruct-Plus 进行对象转换
4. 数据库连接池: HikariCP (非 Druid)
5. Web 容器: Undertow (非 Tomcat)
6. JSON 序列化: Jackson (非 Fastjson)
7. 接口加密: 前后端需同时开启/关闭