ok
This commit is contained in:
ray zhou
26
rules/agent-completion-gate.mdc
Normal file
26
rules/agent-completion-gate.mdc
Normal file
@@ -0,0 +1,26 @@
|
||||
---
|
||||
description: Agent 完成前门禁：校验脚本 + Hooks 兜底
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Agent 完成前门禁
|
||||
|
||||
## 禁止
|
||||
|
||||
- 未跑校验脚本前，不得写「已完成」「可以合并」「验收通过」等收尾表述。
|
||||
|
||||
## 必须
|
||||
|
||||
1. 任务收尾前执行：`~/.cursor/hooks/verify-slot-backend.sh`
|
||||
2. 在最终回复粘贴完整输出（以 `=== verify-slot-backend ===` 开头）。
|
||||
3. 修改 PHP 后，最终回复含 `PHPDoc: checked`（见 `php-code` 规则 PHPDoc 章节）。
|
||||
4. 改动 `app/**/*.php` 须遵守 `php-code` 用例写法章节（BusinessException、按层写法）。
|
||||
|
||||
## Hooks（用户级 `~/.cursor/hooks.json`）
|
||||
|
||||
- **宿主机 `php` / `composer`**：被 `block-host-php.sh` 拦截；须 `docker exec ... php`。
|
||||
- **Agent 结束 `stop`**：自动跑 `verify-slot-backend.sh`；`FAIL` 时注入 `followup_message` 要求继续修复。
|
||||
|
||||
## 扫描范围
|
||||
|
||||
**仅** `git diff` / `git diff --cached` 里、且磁盘上仍存在的改动文件；干净仓库跳过。不做全仓库 grep。无改动 → `PASS (no changed files)`。
|
||||
@@ -20,3 +20,10 @@ alwaysApply: true
|
||||
- 只有当某段能力具备跨场景复用价值、公共计算价值、公共配置访问、外部系统封装等公共属性时，才应抽到 Service。
|
||||
- 不应创建只做中转的 Service 方法，例如 Logic 调用 Service，Service 再原样调用 Model 或另一个 Logic，且没有封装公共能力。
|
||||
- 如果确实需要中转层，必须在代码或 PR 说明中解释原因，例如兼容历史接口、统一事务边界、隔离第三方 SDK、收敛跨模块依赖等。
|
||||
|
||||
## Agent 完成前 MUST
|
||||
|
||||
1. **重命名/删除类**：对本次 diff 中删除的 `*.php`，类名不得出现在**其它已改动**的 PHP 文件中。
|
||||
2. **新建/大改 `app/api/controller/*`**：必须 `extends \slotLib\basic\BaseController`，构造注入对应 `*Logic` + `*Validator`；参照 `slot_console/app/api/controller/FreeCreditsController.php`。
|
||||
3. **禁止 Logic 型 Service**：不得新建以单业务用例编排为主、仅转发 Model/Logic 的 `app/service/*Service`（`*CalcService` 等公共计算除外）。
|
||||
4. **声称完成前**：必须执行 `~/.cursor/hooks/verify-slot-backend.sh`，在最终回复粘贴脚本输出（`PASS` 或 `FAIL` 明细）。
|
||||
|
||||
218
rules/php-clean-code.mdc
Normal file
218
rules/php-clean-code.mdc
Normal file
@@ -0,0 +1,218 @@
|
||||
---
|
||||
description: PHP clean code rules for readable, maintainable and clear backend code
|
||||
globs:
|
||||
- "**/*.php"
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# PHP Clean Code Rules
|
||||
|
||||
目标：生成和修改 PHP 后端代码时，优先保证 **可读、可维护、清晰、简单、易排查**。
|
||||
|
||||
分层职责遵循 `Backend Layering Rules`。本规则只约束代码写法质量。
|
||||
|
||||
---
|
||||
|
||||
## 1. 核心原则
|
||||
|
||||
- 优先清晰，不写炫技代码。
|
||||
- 一个方法只表达一个明确动作。
|
||||
- 代码应像业务流程一样容易阅读。
|
||||
- 复杂逻辑必须拆成有业务语义的私有方法。
|
||||
- 不要为了减少行数牺牲可读性。
|
||||
- 不允许用注释弥补糟糕命名。
|
||||
- 禁止无意义的 `Helper`、`Util`、`CommonService`、`Manager`。
|
||||
- 禁止创建只做转发、没有业务价值的中间层。
|
||||
|
||||
---
|
||||
|
||||
## 2. 命名规则
|
||||
|
||||
禁止用模糊变量名承载核心业务数据：
|
||||
|
||||
- `$data`
|
||||
- `$list`
|
||||
- `$info`
|
||||
- `$tmp`
|
||||
- `$row`
|
||||
- `$result`
|
||||
- `$res`
|
||||
- `$arr`
|
||||
|
||||
变量、方法、类名必须表达业务含义。
|
||||
|
||||
推荐命名风格：
|
||||
|
||||
- `$userInfo`
|
||||
- `$rebateConfig`
|
||||
- `$walletTransaction`
|
||||
- `$validBetAmount`
|
||||
- `$claimResult`
|
||||
- `getEnabledUser()`
|
||||
- `ensureCanClaim()`
|
||||
- `createWalletTransaction()`
|
||||
- `claimRebateInTransaction()`
|
||||
|
||||
布尔变量必须表达真假语义，例如 `$isEnabled`、`$isClaimed`、`$hasPermission`、`$canWithdraw`。
|
||||
|
||||
避免无意义方法名：`handle()`、`process()`、`doSomething()`、`getData()`、`getList()`。
|
||||
|
||||
如果必须使用 `handle()` / `process()`，需要有明确上下文，例如 `handlePaymentCallback()`、`processSettledBet()`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 方法规则
|
||||
|
||||
- 方法长度建议不超过 50 行。
|
||||
- 方法嵌套不超过 3 层。
|
||||
- 优先使用 early return / early throw。
|
||||
- 方法参数一般不超过 3 个。
|
||||
- 参数超过 3 个时，优先使用 DTO、Value Object 或专门数据结构。
|
||||
- 核心业务入参不要直接使用含糊的 `array`。
|
||||
- 返回 `array` 时必须结构明确，并用 PHPDoc 描述结构。
|
||||
- 私有方法也必须有清晰业务语义。
|
||||
- 复杂条件必须封装成有语义的方法。
|
||||
- 魔法数字必须变成常量或枚举。
|
||||
- 业务规则判断优先使用 `ensureXxx()` 方法。
|
||||
- 不要把查询、判断、写入、返回组装全部堆在一个大方法里。
|
||||
|
||||
---
|
||||
|
||||
## 4. Logic / Service / Model 写法
|
||||
|
||||
### Logic
|
||||
|
||||
- Logic 是业务用例入口，一个 public 方法通常对应一个业务用例。
|
||||
- Logic 主方法要像读业务流程。
|
||||
- Logic 私有方法必须有业务语义。
|
||||
- Logic 可以查业务主体、调用 Model、调用公共 Service、做业务判断、控制事务、写业务日志、组装返回结果。
|
||||
- 复杂查询条件应沉淀到 Model。
|
||||
- 涉及多表写入、钱包变动、订单状态变更、活动领取、返水领取、游戏下注 / 派奖时，事务边界必须放在 Logic。
|
||||
- 事务内禁止请求第三方接口、发送 MQ、发送短信、发送邮件、大量循环处理、复杂远程调用。
|
||||
|
||||
### Service
|
||||
|
||||
- Service 只放公共能力，例如第三方 SDK、center 调用、公共配置、公共计算、跨业务复用逻辑、基础设施封装。
|
||||
- Service 禁止承载单业务用例编排。
|
||||
- Service 禁止只做 Model 转发或 Logic 转发。
|
||||
- Service 禁止为每张表创建一个 Service。
|
||||
- 如果一个 Service 方法没有封装公共能力，不应创建。
|
||||
|
||||
### Model
|
||||
|
||||
- Model 负责数据查询和写入。
|
||||
- Model 可以包含查询条件封装、scope、搜索器、关联关系、简单数据写入、常用查询方法。
|
||||
- Model 禁止写复杂业务流程、控制事务、调用第三方接口、编排多个业务步骤。
|
||||
- Model 方法命名必须表达查询或写入意图，例如 `findEnabledById()`、`existsClaimedRecord()`、`sumValidBetAmount()`、`createClaimRecord()`。
|
||||
- 避免 `getData()`、`getList()`、`handle()`、`process()`。
|
||||
|
||||
---
|
||||
|
||||
## 5. PHPDoc 与注释
|
||||
|
||||
Logic、Service、Model 的 public 方法建议写 PHPDoc。
|
||||
|
||||
以下情况必须写 PHPDoc：
|
||||
|
||||
- 返回 `array`
|
||||
- 参数是复杂 `array`
|
||||
- 可能抛出业务异常
|
||||
- 涉及状态流转
|
||||
- 涉及钱包、订单、活动、游戏交易
|
||||
- 方法语义不是一眼能看懂
|
||||
|
||||
返回 array 必须写结构：
|
||||
|
||||
```php
|
||||
/**
|
||||
* @return array{
|
||||
* user_id: int,
|
||||
* nickname: string,
|
||||
* balance: int
|
||||
* }
|
||||
*/
|
||||
```
|
||||
|
||||
复杂 array 参数必须写结构：
|
||||
|
||||
```php
|
||||
/**
|
||||
* @param array{
|
||||
* user_id: int,
|
||||
* amount: int,
|
||||
* order_no: string,
|
||||
* remark?: string
|
||||
* } $data
|
||||
*/
|
||||
```
|
||||
|
||||
涉及异常必须写 `@throws`。
|
||||
|
||||
不要写废话 PHPDoc。简单 getter/setter、方法名和类型已足够清晰时，不强制 PHPDoc。
|
||||
|
||||
注释解释为什么，不解释做什么。复杂业务、幂等处理、分布式锁、状态流转、第三方接口兼容、历史兼容逻辑必须有注释。
|
||||
|
||||
---
|
||||
|
||||
## 6. 异常、日志、返回
|
||||
|
||||
- 禁止返回 `false` 表示业务失败。
|
||||
- 业务失败应抛出业务异常。
|
||||
- 禁止吞异常。
|
||||
- 捕获异常后必须记录必要上下文；如无法处理，必须继续抛出。
|
||||
- 业务异常和系统异常要区分。
|
||||
- 异常信息必须清晰，不能只写 `error`、`failed`。
|
||||
- 关键业务必须打日志，例如钱包变动、游戏下注、游戏派奖、支付回调、活动领取、返水领取、第三方接口异常、风控命中、重要状态变更。
|
||||
- 日志必须包含关键上下文，例如 `user_id`、`order_no`、`provider_code`、`provider_tx_id`、`round_id`、`amount`、`status`、`error`。
|
||||
- 日志禁止记录密码、token、secret、私钥、支付密钥、银行卡完整号码、用户隐私数据、第三方签名密钥。
|
||||
- 返回结构必须明确。
|
||||
- 不直接返回 Model 对象。
|
||||
- 不返回临时调试字段、SQL、异常堆栈、内部配置、secret、token、sign。
|
||||
|
||||
---
|
||||
|
||||
## 7. 幂等要求
|
||||
|
||||
涉及重复请求风险必须考虑幂等，包括第三方回调、钱包加减款、订单支付、活动领取、返水领取、游戏下注、游戏派奖、MQ 消费。
|
||||
|
||||
优先使用唯一索引保证幂等，并在代码中保留明确幂等判断。
|
||||
|
||||
---
|
||||
|
||||
## 8. Agent 自查
|
||||
|
||||
完成代码前必须自查：
|
||||
|
||||
- 命名是否清晰？
|
||||
- 方法是否过长？
|
||||
- 嵌套是否过深？
|
||||
- 是否有魔法数字或魔法字符串？
|
||||
- Logic 是否表达清晰业务流程？
|
||||
- Service 是否确实是公共能力？
|
||||
- Model 是否只做数据访问？
|
||||
- 多表写入是否有事务？
|
||||
- 是否需要幂等？
|
||||
- 是否吞异常？
|
||||
- 日志是否有关键上下文？
|
||||
- 是否泄露敏感信息？
|
||||
- 返回数据是否明确？
|
||||
- 是否直接返回 Model？
|
||||
- 返回 array 的方法是否写清楚 PHPDoc？
|
||||
- 复杂数组参数是否写清楚 PHPDoc？
|
||||
- 涉及异常的方法是否写了 `@throws`？
|
||||
|
||||
---
|
||||
|
||||
## 9. 优先级
|
||||
|
||||
当规则冲突时，按以下优先级处理：
|
||||
|
||||
1. 正确性
|
||||
2. 安全性
|
||||
3. 数据一致性
|
||||
4. 可读性
|
||||
5. 可维护性
|
||||
6. 简洁性
|
||||
7. 性能
|
||||
|
||||
除非已有明确性能瓶颈，否则不要为了性能牺牲可读性。
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
description: "Use this rule whenever creating or modifying PHP files. Enforce PHPDoc for changed classes, interfaces, traits, enums, methods, class constants, and newly added properties."
|
||||
globs:
|
||||
- "slot_*/**/*.php"
|
||||
- "backend/**/*.php"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# PHP PHPDoc 规范（严格）
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 新增或修改的 PHP 文件中的：
|
||||
- class / interface / trait / enum
|
||||
- 所有方法：public / protected / private
|
||||
- 所有类常量：const
|
||||
- 新增属性
|
||||
- 只处理本次 diff 触及的符号
|
||||
- 不追溯未改动的历史代码
|
||||
- 但本次 diff 触及的符号若缺 PHPDoc，必须一并补齐
|
||||
|
||||
## 最低 PHPDoc 内容
|
||||
|
||||
| 符号 | 必须包含 |
|
||||
| --- | --- |
|
||||
| 类 / 接口 / Trait / Enum | 一行职责说明 |
|
||||
| 方法 | 职责说明 + 每个参数的 `@param` + `@return`；有 `throw` 的须 `@throws` |
|
||||
| 类常量 | 一行说明业务含义：单位、枚举语义、与配置/表字段对应关系 |
|
||||
| 属性 | typed property + 一行说明；类型不直观时加 `@var` |
|
||||
|
||||
已有 PHP 8+ 类型声明时，`@param` / `@return` 仍须保留。
|
||||
|
||||
## 禁止项
|
||||
|
||||
- 禁止空 `/** */`
|
||||
- 禁止无 `@param` / `@return` 的方法 PHPDoc
|
||||
- 禁止 `@param int $id id` 式同义反复
|
||||
- 禁止用 PHPDoc 替代 Validate / Logic 里的业务校验说明
|
||||
- 禁止为显而易见语句写冗长注释
|
||||
|
||||
## 分层补充
|
||||
|
||||
| 分层 | PHPDoc 额外要求 |
|
||||
| --- | --- |
|
||||
| Controller | 接口用途；幂等/鉴权前提 |
|
||||
| Logic | 用例步骤；事务边界；失败时行为 |
|
||||
| Service | 复用场景；调用方约束 |
|
||||
| Model | 查询条件；分表键；金额字段单位 |
|
||||
| DTO / Validate | 字段含义；与上游参数映射 |
|
||||
|
||||
## Agent 执行要求
|
||||
|
||||
修改 PHP 文件后，必须检查本次 diff：
|
||||
|
||||
1. 每个新增或修改的 class / interface / trait / enum 是否有 PHPDoc
|
||||
2. 每个新增或修改的方法是否有职责说明、`@param`、`@return`
|
||||
3. 每个新增或修改的类常量是否有业务含义说明
|
||||
4. 新增属性是否有 typed property 和说明
|
||||
5. 不要为了补 PHPDoc 改动无关历史代码
|
||||
6. 最终回复中说明：PHPDoc 检查已完成，若有例外必须列出原因
|
||||
Reference in New Issue
Block a user