feat: update claude files

2025-12-02 13:39:17 +08:00
parent ac0a17a943
commit 839e0617ee
3 changed files with 117 additions and 551 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -142,95 +142,12 @@ plus-ui/
 4. **HTTP 客户端**: Axios 1.8.4
 5. **表格组件**: vxe-table 4.13.7
 6. **接口加密**: RSA + AES 动态加密
-7. **原子化CSS**: UnoCSS
+7. **原子化CSS**: UnoCSS 66.5.2

-## 项目特定技术规范
+## 常用命令

-### 后端开发规范
+### 后端开发

-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
@@ -245,7 +162,8 @@ mvn test
 mvn clean package -Pprod -DskipTests
 ```

-**前端开发**:
+### 前端开发
+
 ```bash
 # 安装依赖
 cd plus-ui && npm install --registry=https://registry.npmmirror.com
@@ -265,12 +183,12 @@ npm run prettier

 ### 自定义斜杠命令

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

 ## 配置说明

@@ -344,6 +262,67 @@ VITE_APP_CONTEXT_PATH = /
 - 支持本部门、本部门及以下、仅本人等权限范围
 - 通过 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 栅格系统
+
 ## 监控与运维

 ### 服务端口
@@ -385,95 +364,33 @@ VITE_APP_CONTEXT_PATH = /
  - 符合项目规范的代码风格
  - 生成后需根据业务需求调整

-### 项目特定注意事项
+## 项目特定注意事项

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

-2. **权限控制**:
-   - 使用 Sa-Token 进行权限认证
-   - 权限字符串格式: `模块:功能:操作` (如 `system:user:add`)
-   - 菜单权限在数据库 `sys_menu` 表管理
+- **核心业务逻辑**: 位于 `ruoyi-modules/ruoyi-inspection`
+- **主要功能**: 设备点位管理、巡检任务、缺陷记录、AR 技术集成
+- **修改建议**: 涉及核心业务,修改需谨慎
+- **依赖模块**: 依赖所有 ruoyi-common 核心模块

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

-4. **多租户支持**:
-   - 框架内置多租户功能
-   - 通过 `@TenantIgnore` 注解排除租户过滤
+- 使用 Sa-Token 进行权限认证
+- 权限字符串格式: `模块:功能:操作` (如 `system:user:add`)
+- 菜单权限在数据库 `sys_menu` 表管理
+- 使用 `@SaCheckPermission("system:user:list")` 注解控制接口权限

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

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

-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")` - 排除的测试
+- 框架内置多租户功能
+- 通过 `@TenantIgnore` 注解排除租户过滤
+- 租户隔离在数据库层面自动实现

 ### Docker 部署

@@ -488,108 +405,41 @@ docker-compose up -d
 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
+- **单元测试**: JUnit 5 + Spring Boot Test
+- **运行测试**: `mvn test`
+- **测试分组**: 通过 `@Tag` 注解标记,根据环境执行
+  - `@Tag("dev")` - 开发环境测试
+  - `@Tag("prod")` - 生产环境测试
+  - `@Tag("exclude")` - 排除的测试

-### 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
+- 检查数据库连接配置
+- 检查 Redis 是否启动
+- 查看日志: `logs/sys-console.log`

-### 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
+- 删除 `node_modules` 重新安装
+- 检查 Node.js 版本 >= 18.18.0
+- 检查端口 80 是否被占用

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