eric/ar-inspection

Fork 0

Files

YANG JIANKUAN f118cc1e9b feat: opt claude

2025-12-01 23:57:09 +08:00

18 KiB

Raw Blame History

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 配置文件

核心技术架构

后端核心组件

权限认证: Sa-Token + JWT (非 Spring Security)
- 支持登录校验、角色校验、权限校验、二级认证
- 支持复杂权限表达式 (AND/OR)
- 轻量级,性能优于 Spring Security
ORM 框架: MyBatis-Plus
- 雪花ID主键 (ASSIGN_ID)
- 多租户插件 (默认启用)
- 数据权限插件
- 分页插件
- 逻辑删除支持
缓存方案: Redisson (非 Lettuce)
- 支持分布式锁 (Lock4j)
- 支持 Spring Cache 注解
- 更强大的分布式特性
多数据源: Dynamic-Datasource
- 支持异构数据库动态切换
- 支持多主多从、混合模式
任务调度: SnailJob (非 Quartz)
- 分布式任务调度
- 支持分片、重试、DAG 任务流
- 可视化管理界面
工作流引擎: Warm-Flow
- 国产工作流引擎
- 支持复杂审批流程
- 轻量级,易于扩展
文件存储: MinIO / AWS S3
- 支持七牛、阿里云、腾讯云等
- 统一的 OSS 抽象接口
API 文档: SpringDoc (非 Springfox)
- 基于 javadoc 注释自动生成
- 零注解入侵
- 符合 OpenAPI 3.0 规范

前端核心特性

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

项目特定技术规范

后端开发规范

模块结构:
- ruoyi-admin/ - 主应用入口,负责启动和全局配置
- ruoyi-common/ - 通用功能模块(不要随意修改)
- ruoyi-modules/ - 业务模块目录
  - ruoyi-system/ - 系统管理模块
  - ruoyi-inspection/ - AR巡检核心业务模块
  - 其他业务模块按功能划分

代码分层:

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

必须遵循的规范:
- 实体类必须继承 BaseEntity 并使用 Lombok 注解
- Mapper 接口继承 BaseMapperPlus<实体类Mapper, 实体类, VO类>
- Service 实现类使用 @RequiredArgsConstructor 注入依赖
- Controller 统一返回 R<T> 类型
- 使用 @SaCheckPermission 进行权限控制
- 所有 API 添加 Swagger 注解: @Tag, @Operation, @Parameters
命名约定:
- 实体类: XxxEntity 或直接 Xxx
- Mapper: XxxMapper
- Service: IXxxService (接口) / XxxServiceImpl (实现)
- Controller: XxxController
- VO: XxxVo
- BO: XxxBo
数据库操作:
- 优先使用 MyBatis-Plus 的内置方法
- 复杂查询在 Mapper XML 中编写
- 使用 LambdaQueryWrapper 构建动态查询
- 分页使用 TableDataInfo<T> 和 PageQuery

前端开发规范

目录结构:

plus-ui/
├── src/
│   ├── api/          # API接口定义
│   ├── views/        # 页面视图
│   ├── components/   # 可复用组件
│   ├── store/        # Pinia状态管理
│   ├── router/       # 路由配置
│   ├── utils/        # 工具函数
│   └── types/        # TypeScript类型定义

组件开发:
- 使用 Vue 3 Composition API (<script setup lang="ts">)
- 优先使用 Element Plus 组件
- 表单使用 el-form + 表单验证规则
- 表格使用 vxe-table 或 el-table
- 使用 useRouter, useRoute 进行路由操作
API 调用规范:
- API 定义在 src/api/ 目录,按模块分文件
- 使用 request 工具发起请求
- 统一错误处理,使用 ElMessage 显示提示
- 类型定义使用 TypeScript interface
状态管理:
- 使用 Pinia 管理全局状态
- Store 文件放在 src/store/modules/
- 使用组合式 API: defineStore
样式规范:
- 使用 <style scoped lang="scss">
- 优先使用 UnoCSS 原子类
- 遵循 BEM 命名规范
- 响应式布局使用 Element Plus 的栅格系统

常用命令

后端开发:

# 构建项目(跳过测试)
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 开发服务器
/lint - 运行前端代码检查和格式化
/new-module - 创建新的业务模块脚手架
/analyze - 分析项目架构和依赖关系

配置说明

后端配置

主配置文件: 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

重要配置项

多租户: tenant.enable=true (默认开启)
接口加密: api-decrypt.enabled=true
数据加密: mybatis-encryptor.enable=false (默认关闭)
WebSocket: 默认关闭,推荐使用 SSE
验证码: captcha.enable=true
逻辑删除: 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 插件实现

监控与运维

服务端口

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

监控工具

应用监控: Spring Boot Admin
- 访问地址: http://localhost:9090/admin
- 用户名/密码: 在 application.yml 中配置
- 功能: 应用健康检查、日志查看、环境信息
任务调度中心: SnailJob
- 访问地址: http://localhost:8800/snail-job
- 功能: 任务管理、执行日志、任务编排
API 文档: SpringDoc
- 开发环境: http://localhost:8080/doc.html
- 生产环境: 根据需要启用/禁用
- 零注解,基于 Javadoc 自动生成
日志管理
- 日志路径: ./logs/sys-console.log
- 使用 Logback
- 支持在线日志查看(通过监控中心)

代码生成器

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

项目特定注意事项

AR 巡检业务模块 (ruoyi-inspection):
- 核心业务逻辑,修改需谨慎
- 涉及设备点位、巡检任务、缺陷记录等核心功能
- 修改前先阅读业务设计文档: AR-INSPECTION-DESIGN.md
权限控制:
- 使用 Sa-Token 进行权限认证
- 权限字符串格式: 模块:功能:操作 (如 system:user:add)
- 菜单权限在数据库 sys_menu 表管理
文件存储:
- 使用 OSS 进行文件存储(支持 MinIO, 阿里云OSS等)
- 配置在 application-*.yml 中的 oss 节点
多租户支持:
- 框架内置多租户功能
- 通过 @TenantIgnore 注解排除租户过滤
代码生成器:
- 访问 http://localhost:8080/tool/gen
- 可快速生成 CRUD 代码
- 生成后需根据业务需求调整

问题排查

后端启动失败:
- 检查数据库连接配置
- 检查 Redis 是否启动
- 查看日志: logs/sys-console.log
前端启动失败:
- 删除 node_modules 重新安装
- 检查 Node.js 版本 >= 18.18.0
- 检查端口 80 是否被占用
接口调用失败:
- 检查后端服务是否启动
- 检查跨域配置
- 查看浏览器控制台和网络请求

框架技术注意事项

架构特点

插件化架构
- 各 ruoyi-common-* 模块相互独立
- 可按需引入功能模块
- 易于扩展和维护
编码规范
- 严格遵守 Alibaba Java 编码规范
- 使用 Lombok 简化代码
- IDE 需要安装 Lombok 插件
对象转换
- 使用 MapStruct-Plus 进行对象转换
- 避免使用 BeanUtils.copyProperties
- 性能优于反射方式

技术选型说明

数据库连接池: HikariCP (非 Druid)
- 性能更优
- Spring Boot 默认连接池
Web 容器: Undertow (非 Tomcat)
- 非阻塞 IO
- 内存占用更小
- 高并发性能更好
JSON 序列化: Jackson (非 Fastjson)
- 安全性更高
- Spring Boot 默认选择
接口加密
- 前后端需同时开启/关闭
- RSA + AES 混合加密
- 开发环境建议关闭

测试

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

Docker 部署

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

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

# 停止所有服务
docker-compose down

Universal Development Guidelines

Code Quality Standards

Write clean, readable, and maintainable code
Follow consistent naming conventions across the project
Use meaningful variable and function names
Keep functions focused and single-purpose
Add comments for complex logic and business rules

Git Workflow

Use descriptive commit messages following conventional commits format
Create feature branches for new development
Keep commits atomic and focused on single changes
Use pull requests for code review before merging
Maintain a clean commit history

Documentation

Keep README.md files up to date
Document public APIs and interfaces
Include usage examples for complex features
Maintain inline code documentation
Update documentation when making changes

Testing Approach

Write tests for new features and bug fixes
Maintain good test coverage
Use descriptive test names that explain the expected behavior
Organize tests logically by feature or module
Run tests before committing changes

Security Best Practices

Never commit sensitive information (API keys, passwords, tokens)
Use environment variables for configuration
Validate input data and sanitize outputs
Follow principle of least privilege
Keep dependencies updated

Project Structure Guidelines

File Organization

Group related files in logical directories
Use consistent file and folder naming conventions
Separate source code from configuration files
Keep build artifacts out of version control
Organize assets and resources appropriately

Configuration Management

Use configuration files for environment-specific settings
Centralize configuration in dedicated files
Use environment variables for sensitive or environment-specific data
Document configuration options and their purposes
Provide example configuration files

Development Workflow

Before Starting Work

Pull latest changes from main branch
Create a new feature branch
Review existing code and architecture
Plan the implementation approach

During Development

Make incremental commits with clear messages
Run tests frequently to catch issues early
Follow established coding standards
Update documentation as needed

Before Submitting

Run full test suite
Check code quality and formatting
Update documentation if necessary
Create clear pull request description

Common Patterns

Error Handling

Use appropriate error handling mechanisms for the language
Provide meaningful error messages
Log errors appropriately for debugging
Handle edge cases gracefully
Don't expose sensitive information in error messages

Performance Considerations

Profile code for performance bottlenecks
Optimize database queries and API calls
Use caching where appropriate
Consider memory usage and resource management
Monitor and measure performance metrics

Code Reusability

Extract common functionality into reusable modules
Use dependency injection for better testability
Create utility functions for repeated operations
Design interfaces for extensibility
Follow DRY (Don't Repeat Yourself) principle

Review Checklist

Before marking any task as complete:

Code follows established conventions
Tests are written and passing
Documentation is updated
Security considerations are addressed
Performance impact is considered
Code is reviewed for maintainability

18 KiB Raw Blame History