owl-admin/.cursorrules

@owl-admin 目录是基于php语言的laraval框架的owl-admin快速开发框架的后端项目，对于这个项目请使用如下规则：

您是 Laravel、PHP 及相关网络开发技术的专家。

## git commit 注释始终用中文语言，注释前缀约定：
    - feat: 新功能（feature）
    - fix: 修复bug
    - docs: 文档修改
    - style: 代码格式修改（不影响代码运行的变动）
    - refactor: 重构（既不是新增功能，也不是修复bug的代码变动）
    - perf: 性能优化
    - test: 增加测试
    - chore: 构建过程或辅助工具的变动
    - revert: 回退
    - build: 打包
    - ci: 持续集成

## 核心原则
- 编写简洁、技术性的回答，并提供准确的 PHP/Laravel 示例。
- 优先考虑面向对象编程和清晰架构的 SOLID 原则。
- 遵循 PHP 和 Laravel 的最佳实践，确保一致性和可读性。
- 为可扩展性和可维护性设计，确保系统能够轻松成长。
- 倾向于迭代和模块化而不是重复，以促进代码复用。
- 为变量、方法和类使用一致和描述性的名称，以提高可读性。

## 依赖
- Composer 用于依赖管理
- PHP 8.2+
- Laravel 11.0+
- owl-admin Laravel后台管理框架

## PHP 和 Laravel 标准
- 在适当的情况下利用 PHP 8.2+ 的特性（例如，类型属性、匹配表达式）。
- 遵守 PSR-12 编码标准，以保持代码风格的一致性。
- 始终使用严格类型：declare(strict_types=1);
- 利用 Laravel 的内置功能和助手，以最大化效率。
- 遵循 Laravel 的目录结构和文件命名约定。
- 实施健壮的错误处理和日志记录：
- 适合处理前置条件验证的优先请使用abort_if
- 使用 Laravel 的异常处理和日志记录功能。
- 在必要时创建自定义异常。
- 对预期的异常使用 try-catch 块。
- 使用 Laravel 的验证功能处理表单和请求数据。
- 实施中间件进行请求过滤和修改。
- 利用 Laravel 的 Eloquent ORM 进行数据库交互。
- 使用 Laravel 的查询构建器进行复杂的数据库操作。
- 创建和维护适当的数据库迁移和种子文件。

## Laravel 最佳实践
- 在可能的情况下使用 Eloquent ORM 和查询构建器代替原始 SQL 查询
- 实施仓库和服务模式，以获得更好的代码组织和可复用性
- 利用 Laravel 的内置身份验证和授权功能（Sanctum）
- 利用 Laravel 的缓存机制（Redis）提高性能
- 使用任务队列处理长时间运行的任务和后台处理
- 使用 API 资源和版本控制构建健壮且可维护的 API
- 使用 Laravel 的异常处理程序和日志门面实现适当的错误处理和日志记录
- 利用 Laravel 的验证功能，包括表单请求，确保数据完整性
- 实施数据库索引并使用 Laravel 的查询优化功能提高性能
- 实施适当的安全措施，包括 CSRF 保护、XSS 防范和输入消毒

##  代码架构

### 命名约定：
- 文件夹、类和文件使用一致的命名约定。
- 遵循 Laravel 的约定：模型使用单数，控制器使用复数（例如，User.php，UsersController.php）。
- 类名使用 PascalCase，方法名使用 camelCase，数据库列使用 snake_case。

### 控制器设计：
- 控制器应该是 final 类，以防止继承。
- 控制器应该是只读的（即，没有属性变异）。
- 避免直接在控制器中注入依赖。相反，使用方法注入或服务类。

### 模型设计：
- 模型应该是 final 类，以确保数据完整性并防止继承导致意外行为。
- 不要自定义模型和字段，如果不确定请参照 doc/系统设计/数据库设计/物理模型/xiaoding_test.md 寻找，仍然无法确定，请告知我。

### 服务：
- 在 app 目录中创建一个 Services 文件夹。
- 将服务组织成特定于模型的服务和其他所需服务。
- 服务类应该是 final 和只读的。
- 使用服务处理复杂的业务逻辑，保持控制器轻薄。

### 路由：
- 保持路由的一致性和组织性。
- 为每个主要模型或功能区域创建单独的路由文件。
- 将相关路由分组在一起（例如，所有与用户相关的路由在 routes/user.php 中）。
- 路由位置约定：
    - 用户端路由应在routes/api.php文件中client前缀下
    - 技师端路由应在routes/api.php文件中coach前缀下
    - 管理端路由应在routes/web.php文件中，分别在admin前缀和admin-api前缀中添加

### 类型声明：
- 方法和方法总是使用显式的返回类型声明。
- 使用适当的 PHP 类型提示作为方法参数。
- 在必要时利用 PHP 8.1+ 的特性，如联合类型和可空类型。

### 数据类型一致性：
- 在整个代码库中保持数据类型声明的一致性和明确性。
- 使用类型提示属性、方法参数和返回类型。
- 利用 PHP 的严格类型早期捕获类型相关错误。

### 错误处理：
- 使用 Laravel 的异常处理和日志记录功能处理异常。
- 在必要时创建自定义异常。
- 对预期的异常使用 try-catch 块。
- 以优雅的方式处理异常并返回适当的响应。

### 关键点
- 遵循 Laravel 的 MVC 架构，明确分离业务逻辑、数据和表示层。
- 使用表单请求实现请求验证

### 业务代码位置约定
- 用户端
    - controller代码目录位置是： app/Http/Controllers/Client
    - service代码目录位置是： app/Services/Client
- 技师端
    - controller代码目录位置是： app/Http/Controllers/Coach
    - service代码目录位置是： app/Services/Coach
- 管理端
    - controller代码目录位置是： app/Admin/Controllers
    - service代码目录位置是： app/Services

### 枚举使用规则
- 尽可能利用 app/Enums 目录下的枚举，而不是数字。

### 注解优化规则
－ Controller层API文档注解优化规则：
    - 生成scribe的API文档注解时，确保方法注释名称前添加分组名，格式为分组名-方法名。
    - 不使用@group注解关键字，而是在方法注释中明确分组信息。
    - 添加@description注解，详细描述API功能。
    - 对于请求参数，使用@param注解，并提供参数类型、描述和默认值（Example）。
    - 对于响应，使用@response注解，并提供响应类型、描述和示例数据。

- Service层PHPDoc注解优化规则：
    - 为Service层的每个方法添加PHPDoc注解，包括方法功能描述、参数说明、返回值说明等。

- 方法体内逻辑注解优化规则：
    - 在每个方法体内，对每行逻辑代码添加详细注解，说明该行代码的功能和目的。

- 注解中文字符串空格检查优化规则：
    - 检查所有中文注解字符串，确保不包含空格，避免中文编码问题。

### 事务处理规则详细说明
- 检测增删改方法：识别哪些方法涉及数据的增加、删除或修改，并自动添加事务开始的代码，并在方法结束前添加事务提交的代码。
- 同时，确保在事务中捕获所有可能的异常，并在异常发生时回滚事务，并记录日志。

## 代码保护规则

1. 关键逻辑保护:
- 删除代码块前必须分析其重要性
- 保护业务逻辑实现
- 维护验证规则
- 保留安全相关代码
- 保持错误处理模式

2. 文档完整性:
- 保护架构决策说明
- 维护业务规则解释
- 保持实现指南
- 保留配置规范

3. 差异分析:
- 审查所有被删除的内容
- 评估删除的影响
- 考虑依赖关系
- 评估上下文相关性

4. 恢复机制:
- 记录重要的被删除内容
- 建议恢复关键部分
- 提供保护的理由
- 突出删除的潜在风险

核心指令: "在删除任何代码或文档之前，必须彻底分析其重要性，以防止丢失关键逻辑、业务规则或重要的实现细节。"