# 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

## 项目特定技术规范

### 后端开发规范

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

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

3. **必须遵循的规范**:
   - 实体类必须继承 `BaseEntity` 并使用 Lombok 注解
   - Mapper 接口继承 `BaseMapperPlus<实体类Mapper, 实体类, VO类>`
   - Service 实现类使用 `@RequiredArgsConstructor` 注入依赖
   - Controller 统一返回 `R<T>` 类型
   - 使用 `@SaCheckPermission` 进行权限控制
   - 所有 API 添加 Swagger 注解: `@Tag`, `@Operation`, `@Parameters`

4. **命名约定**:
   - 实体类: `XxxEntity` 或直接 `Xxx`
   - Mapper: `XxxMapper`
   - Service: `IXxxService` (接口) / `XxxServiceImpl` (实现)
   - Controller: `XxxController`
   - VO: `XxxVo`
   - BO: `XxxBo`

5. **数据库操作**:
   - 优先使用 MyBatis-Plus 的内置方法
   - 复杂查询在 Mapper XML 中编写
   - 使用 `LambdaQueryWrapper` 构建动态查询
   - 分页使用 `TableDataInfo<T>` 和 `PageQuery`

### 前端开发规范

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

2. **组件开发**:
   - 使用 Vue 3 Composition API (`<script setup lang="ts">`)
   - 优先使用 Element Plus 组件
   - 表单使用 `el-form` + 表单验证规则
   - 表格使用 `vxe-table` 或 `el-table`
   - 使用 `useRouter`, `useRoute` 进行路由操作

3. **API 调用规范**:
   - API 定义在 `src/api/` 目录,按模块分文件
   - 使用 `request` 工具发起请求
   - 统一错误处理,使用 `ElMessage` 显示提示
   - 类型定义使用 TypeScript interface

4. **状态管理**:
   - 使用 Pinia 管理全局状态
   - Store 文件放在 `src/store/modules/`
   - 使用组合式 API: `defineStore`

5. **样式规范**:
   - 使用 `<style scoped lang="scss">`
   - 优先使用 UnoCSS 原子类
   - 遵循 BEM 命名规范
   - 响应式布局使用 Element Plus 的栅格系统

### 常用命令

**后端开发**:
```bash
# 构建项目(跳过测试)
mvn clean install -DskipTests

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

# 运行测试
mvn test

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

**前端开发**:
```bash
# 安装依赖
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 切换
```bash
# 开发环境(默认)
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`

```bash
# 应用标题
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

### 监控工具

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 页面
  - 符合项目规范的代码风格
  - 生成后需根据业务需求调整

### 项目特定注意事项

1. **AR 巡检业务模块** (`ruoyi-inspection`):
   - 核心业务逻辑,修改需谨慎
   - 涉及设备点位、巡检任务、缺陷记录等核心功能
   - 修改前先阅读业务设计文档: `AR-INSPECTION-DESIGN.md`

2. **权限控制**:
   - 使用 Sa-Token 进行权限认证
   - 权限字符串格式: `模块:功能:操作` (如 `system:user:add`)
   - 菜单权限在数据库 `sys_menu` 表管理

3. **文件存储**:
   - 使用 OSS 进行文件存储(支持 MinIO, 阿里云OSS等)
   - 配置在 `application-*.yml` 中的 `oss` 节点

4. **多租户支持**:
   - 框架内置多租户功能
   - 通过 `@TenantIgnore` 注解排除租户过滤

5. **代码生成器**:
   - 访问 http://localhost:8080/tool/gen
   - 可快速生成 CRUD 代码
   - 生成后需根据业务需求调整

### 问题排查

1. **后端启动失败**:
   - 检查数据库连接配置
   - 检查 Redis 是否启动
   - 查看日志: `logs/sys-console.log`

2. **前端启动失败**:
   - 删除 `node_modules` 重新安装
   - 检查 Node.js 版本 >= 18.18.0
   - 检查端口 80 是否被占用

3. **接口调用失败**:
   - 检查后端服务是否启动
   - 检查跨域配置
   - 查看浏览器控制台和网络请求

## 框架技术注意事项

### 架构特点

1. **插件化架构**
   - 各 `ruoyi-common-*` 模块相互独立
   - 可按需引入功能模块
   - 易于扩展和维护

2. **编码规范**
   - 严格遵守 Alibaba Java 编码规范
   - 使用 Lombok 简化代码
   - IDE 需要安装 Lombok 插件

3. **对象转换**
   - 使用 MapStruct-Plus 进行对象转换
   - 避免使用 BeanUtils.copyProperties
   - 性能优于反射方式

### 技术选型说明

1. **数据库连接池**: HikariCP (非 Druid)
   - 性能更优
   - Spring Boot 默认连接池

2. **Web 容器**: Undertow (非 Tomcat)
   - 非阻塞 IO
   - 内存占用更小
   - 高并发性能更好

3. **JSON 序列化**: Jackson (非 Fastjson)
   - 安全性更高
   - Spring Boot 默认选择

4. **接口加密**
   - 前后端需同时开启/关闭
   - RSA + AES 混合加密
   - 开发环境建议关闭

### 测试

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

### Docker 部署

```bash
# 使用 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
1. Pull latest changes from main branch
2. Create a new feature branch
3. Review existing code and architecture
4. Plan the implementation approach

### During Development
1. Make incremental commits with clear messages
2. Run tests frequently to catch issues early
3. Follow established coding standards
4. Update documentation as needed

### Before Submitting
1. Run full test suite
2. Check code quality and formatting
3. Update documentation if necessary
4. 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