ok

2026-05-29 11:21:40 +08:00
parent 5d6d482efe
commit f71a5c59af
447 changed files with 32245 additions and 116 deletions
--- a/plans/php用例写法规则_01c4ae1f.plan.md
+++ b/plans/php用例写法规则_01c4ae1f.plan.md
@@ -0,0 +1,227 @@
+---
+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 |