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