228 lines
10 KiB
Markdown
228 lines
10 KiB
Markdown
---
|
||
name: PHP用例写法规则
|
||
overview: 在用户级 Cursor 新增 `php-use-case-style.mdc`，约束 slot 后端所有 PHP 业务代码（Controller/Logic/Service/Model/Command 等）的表达力与可维护性；并扩展 verify-slot-backend.sh 对 diff 中所有 touched 的 app/**/*.php 做轻量检查。仅约束本次 diff，不强制全盘重构历史代码。
|
||
todos:
|
||
- id: create-mdc
|
||
content: 创建 ~/.cursor/rules/php-use-case-style.mdc（全层 MUST/禁止、BAD/GOOD、按层对照表）
|
||
status: completed
|
||
- id: update-gate-rule
|
||
content: 在 agent-completion-gate.mdc 增加对 php-use-case-style 的引用（任意 PHP 改动）
|
||
status: completed
|
||
- id: extend-verify
|
||
content: 扩展 verify-slot-backend.sh：所有 app/**/*.php diff 检查 + @use-case-exempt
|
||
status: completed
|
||
- id: smoke-verify
|
||
content: 分别在 Logic/Controller/Service diff 触发自测 PASS/FAIL/豁免
|
||
status: completed
|
||
- id: merge-php-code
|
||
content: 用例写法合并进 php-code.mdc，修 frontmatter/强制要求/命名
|
||
status: completed
|
||
- id: fix-gate-refs
|
||
content: agent-completion-gate 引用改为 php-code
|
||
status: completed
|
||
- id: smoke-rules
|
||
content: 确认规则生效 + verify PASS
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# PHP 代码写法规则 + Verify 门禁（全层）
|
||
|
||
## 目标
|
||
|
||
让 AI 在改 **任意 slot 后端 PHP 业务代码** 时默认产出：**编排清晰、职责单一、业务异常语义正确、状态变更有条件更新与幂等键**，并对齐仓库内参照实现。
|
||
|
||
适用范围（规则 + verify 一致）：
|
||
|
||
- `app/api/controller/**`
|
||
- `app/api/logic/**`、`app/innerapi/logic/**`、`app/napi/logic/**`
|
||
- `app/service/**`
|
||
- `app/model/**`
|
||
- `app/command/**`
|
||
- 其它 `app/**` 下业务 PHP（`validate`、`entity` 等按条适用）
|
||
|
||
**不覆盖**：`vendor/`、`tests/`（除非 diff 触及且单独约定）、纯配置/SQL 文件。
|
||
|
||
## 默认范围
|
||
|
||
- **规则文件**：用户级 [`~/.cursor/rules/php-use-case-style.mdc`](~/.cursor/rules/php-use-case-style.mdc)
|
||
- **生效方式**：`alwaysApply: true`（任意对话均注入；与 `backend-layering` 同级，避免只开 Logic 文件时漏规则）
|
||
- **门禁脚本**：[`~/.cursor/hooks/verify-slot-backend.sh`](~/.cursor/hooks/verify-slot-backend.sh)（仅 `git diff` + 路径 `app/`）
|
||
- **不在本阶段**：强制重构历史代码（如 `DailyRebateLogic::claim`）；可另开样板 PR
|
||
|
||
## 1. 新增规则 `php-use-case-style.mdc`
|
||
|
||
**Frontmatter**：
|
||
|
||
```yaml
|
||
---
|
||
description: Slot PHP 写法——表达力、可维护、全层通用（Controller/Logic/Service/Model/Command）
|
||
alwaysApply: true
|
||
---
|
||
```
|
||
|
||
### 1.1 全层通用 MUST
|
||
|
||
| 条目 | 要求 |
|
||
|------|------|
|
||
| 单一职责 | 一个 public 方法只做一件事；编排方法目标 ≤25 行，超出拆 private |
|
||
| if 墙 | 禁止同一方法内连续 ≥4 个 `if (...) throw/return error`；合并为 `assert*` / `ensure*` |
|
||
| 业务异常 | 可预期业务失败用 `support\exception\BusinessException`；禁止用 `RuntimeException` 表示业务态（未开启、不可领、已过期等） |
|
||
| 魔法值 | 状态/类型用 Model 常量或 enum；禁止裸 `1/2/3` 散落（diff 新增代码） |
|
||
| 命名 | 方法名表达意图（`assertClaimable`、`markClaimedIfClaimable`），禁止 `doClaim`、`handle` 等空泛名（新增代码） |
|
||
| 参照 | 领取/入账编排：[`FreeCreditsLogic::claim`](slot_console/app/api/logic/FreeCreditsLogic.php)；Controller：[`FreeCreditsController`](slot_console/app/api/controller/FreeCreditsController.php) |
|
||
|
||
### 1.2 按层补充（与 backend-layering 互补，不重复分层表）
|
||
|
||
| 分层 | 写法 MUST | 禁止 |
|
||
|------|-----------|------|
|
||
| **Controller** | 仅：Validate → 调 Logic/Service → `success/errorCode`；`catch BusinessException` 映射业务码 | 业务 if 墙、直接 `Db::`、直接 `gift()` |
|
||
| **Logic** | 用例编排：`buildContext` → `assert*` → `perform*` → `format*`；事务边界在此 | 纯转发 Model 无编排、跨服务裸 curl |
|
||
| **Service** | 可复用能力封装；外部系统（wallet/sdk）隔离；稳定 `biz_id` | Logic 型 Service（单用例整条流水线） |
|
||
| **Model** | 查询/写入 + `scope`/`mark*If*` 条件更新；金额字段注释单位（厘） | 业务编排、调 Wallet |
|
||
| **Command** | 薄入口：参数解析 → 调 Logic；日志 phase 结构化 | 复制 Logic 大段 if 墙 |
|
||
| **Validate** | 格式/必填/枚举 | 业务规则（「是否可领」应在 Logic assert） |
|
||
|
||
### 1.3 领取 / 入账 / 状态变更（凡涉及处均适用）
|
||
|
||
- MUST：条件更新（`where status = expected` 再 `update`），鼓励 Model 方法 `mark*If*`
|
||
- MUST：钱包/外部入账带稳定 `biz_id`（如 `daily_rebate:{uid}:{statDate}`）
|
||
- Controller：禁止 `catch (\RuntimeException)` 后一律 `PARAMS_ERROR`
|
||
|
||
### 1.4 BAD / GOOD（规则内各一段，≤8 行）
|
||
|
||
- BAD：Controller `catch RuntimeException` + Logic 5 连 throw + Service 仅 `return Model::find()`
|
||
- GOOD：Controller 捕 `BusinessException`；Logic `assert*` + 条件更新；Service 封装 wallet + biz_id
|
||
|
||
### 1.5 与现有规则关系
|
||
|
||
- 分层职责：仍服从 [`backend-layering.mdc`](~/.cursor/rules/backend-layering.mdc)
|
||
- 文档：仍服从 [`php-doc.mdc`](~/.cursor/rules/php-doc.mdc)
|
||
- [`agent-completion-gate.mdc`](~/.cursor/rules/agent-completion-gate.mdc) 增加：**任意改动 `app/**/*.php` 须遵守 `php-use-case-style`**
|
||
|
||
## 2. 扩展 `verify-slot-backend.sh`
|
||
|
||
对 **`CHANGED_PHP` 且路径匹配 `*/app/*`** 的文件检查（不再限定 `/logic/`）：
|
||
|
||
```bash
|
||
# 1) diff 新增行含 throw new \RuntimeException（业务态误用）
|
||
# 豁免：文件含 @use-case-exempt
|
||
|
||
# 2) Controller（*/app/**/controller/*）diff 新增行：
|
||
# catch (\RuntimeException 且同文件/邻近行 PARAMS_ERROR → fail
|
||
|
||
# 3) 已有：BaseController、banlist、deleted class — 保持不变
|
||
```
|
||
|
||
**原则**：
|
||
|
||
- 只 FAIL **diff 新增行**（`git diff -U0` / `git diff --cached -U0`），不扫历史行
|
||
- `@use-case-exempt` 在文件前 5 行内则跳过该文件全部 use-case 检查
|
||
- 首期不 FAIL：方法行数、biz_id 参数名（写在规则 MUST，verify 二期）
|
||
|
||
## 3. 数据流
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph agent [Agent 改任意 app PHP]
|
||
rule[php-use-case-style alwaysApply]
|
||
layers[Controller Logic Service Model Command]
|
||
end
|
||
subgraph gate [完成前]
|
||
verify[verify-slot-backend app/** diff]
|
||
hook[stop hook followup]
|
||
end
|
||
rule --> layers
|
||
layers --> verify
|
||
verify -->|FAIL| hook
|
||
verify -->|PASS| done[可声称完成]
|
||
```
|
||
|
||
## 4. 验收
|
||
|
||
1. 打开任意 `app/service/*.php` 或 `DailyRebateController.php`，规则均应生效（alwaysApply）
|
||
2. 在 Controller diff 新增 `catch (\RuntimeException` + `PARAMS_ERROR` → verify FAIL
|
||
3. 在 Service diff 新增 `throw new \RuntimeException('活动未开')` → verify FAIL
|
||
4. 加 `@use-case-exempt` → 该文件跳过
|
||
5. `~/.cursor/hooks/verify-slot-backend.sh` 输出 PASS
|
||
|
||
## 5. 后续可选（本计划不含）
|
||
|
||
- 样板 PR：重构 `DailyRebateLogic::claim` + `DailyRebateController::claim`
|
||
- verify 二期：`gift(` / wallet 调用邻近 biz_id 检测；public 方法行数 WARN
|
||
|
||
---
|
||
|
||
## 6. 阶段二：合并进 `php-code.mdc`（待执行）
|
||
|
||
用户已将 PHPDoc 并入 [`php-code.mdc`](~/.cursor/rules/php-code.mdc)；`php-use-case-style.mdc` 已不存在。verify 已具备 use-case 检查，但规则与 gate 引用断裂。本阶段只做规则对齐，不改业务代码。
|
||
|
||
### 6.1 修改 `php-code.mdc`
|
||
|
||
**Frontmatter**（删空 `globs:`）：
|
||
|
||
```yaml
|
||
---
|
||
description: PHP 全局工程规范（PHPDoc + 用例写法 + AI 纪律）
|
||
alwaysApply: true
|
||
---
|
||
```
|
||
|
||
**在「代码原则」后插入新章节「用例写法（app/**）」**（约 35 行）：
|
||
|
||
- MUST：业务失败 `support\exception\BusinessException`；禁止 `RuntimeException` 表业务态
|
||
- MUST：编排 public 方法 ≤25 行；同一方法禁止连续 ≥4 个 `if (...) throw` → 抽 `assert*`
|
||
- MUST：状态变更条件更新；钱包入账稳定 `biz_id`（`daily_rebate:{uid}:{date}`）
|
||
- 按层表（与 backend-layering 互补）：Controller 禁止业务 if 墙 / 直接 gift；Logic 编排结构；禁止 Logic 型 Service
|
||
- 参照：`slot_console/app/api/logic/FreeCreditsLogic.php` :: `claim()`；`FreeCreditsController.php`
|
||
- BAD/GOOD 各一段（RuntimeException vs BusinessException；Controller catch）
|
||
- 豁免：文件前 5 行 `@use-case-exempt`（与 verify 一致）
|
||
|
||
**改写「强制要求」**（L84–92）为 diff 范围：
|
||
|
||
```markdown
|
||
## 强制要求（本次 diff 新增/修改须符合）
|
||
|
||
- PHP 8+；新增/修改的方法须有 typed parameter 与 return
|
||
- 新增类属性须 typed property
|
||
- 新建文件或本次 diff 触及的文件顶部可加 `declare(strict_types=1);`，禁止为达标改无关历史文件
|
||
```
|
||
|
||
**微调「命名规范」**：
|
||
|
||
- 禁止 `$tmp`、`$a`、`$b`、无业务含义的 `$data`/`$list`
|
||
- **删除** blanket 禁止 `$info`（与 `UserInfoEntity` 等冲突）；改为禁止「无上下文的 `$info` 临时变量」
|
||
|
||
**文末增加「与 verify 对齐」**：
|
||
|
||
- diff 新增 `throw new RuntimeException`（业务态）→ verify FAIL
|
||
- Controller diff 新增 `catch RuntimeException` + `PARAMS_ERROR` → verify FAIL
|
||
|
||
### 6.2 修改 `agent-completion-gate.mdc`
|
||
|
||
```diff
|
||
- 3. 修改 PHP 后，最终回复含 `PHPDoc: checked`（见 php-doc 规则）。
|
||
- 4. 改动 `app/**/*.php` 须遵守 `php-use-case-style`（表达力、BusinessException、按层写法）。
|
||
+ 3. 修改 PHP 后，最终回复含 `PHPDoc: checked`（见 php-code 规则 PHPDoc 章节）。
|
||
+ 4. 改动 `app/**/*.php` 须遵守 `php-code` 用例写法章节（BusinessException、按层写法）。
|
||
```
|
||
|
||
### 6.3 不改动
|
||
|
||
- `verify-slot-backend.sh`（已含 use-case 检查）
|
||
- `backend-layering.mdc`、`cross-service-sdk.mdc`
|
||
|
||
### 6.4 验收
|
||
|
||
1. `~/.cursor/rules/` 仅一份 PHP 总规范 `php-code.mdc`，无悬空 `php-doc` / `php-use-case-style` 引用
|
||
2. 新开 Agent 对话，改 `app/**` PHP 时应看到用例写法 + PHPDoc
|
||
3. `~/.cursor/hooks/verify-slot-backend.sh` → PASS
|
||
|
||
### 6.5 执行 todos
|
||
|
||
| id | 内容 |
|
||
|----|------|
|
||
| merge-php-code | 按 6.1 更新 php-code.mdc |
|
||
| fix-gate-refs | 按 6.2 更新 agent-completion-gate.mdc |
|
||
| smoke-rules | 打开 DailyRebateLogic + 跑 verify |
|