60 lines
2.1 KiB
Plaintext
60 lines
2.1 KiB
Plaintext
---
|
||
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 检查已完成，若有例外必须列出原因 |