first commit

rules/php-doc.mdc

@@ -0,0 +1,60 @@
+---
+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 检查已完成，若有例外必须列出原因