5.7 KiB
5.7 KiB
name, overview, todos, isProject
| name | overview | todos | isProject | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| PHPDoc 规范收紧 | 调整 [`php-clean-code.mdc`](/Users/ray/.cursor/rules/php-clean-code.mdc) 第 5 节 PHPDoc 规则：除纯 getter/setter 外，Logic/Service/Model 的 public 方法一律必须写中文 PHPDoc；删除「方法名够清晰可不写」的豁免，并同步 Agent 自查清单。 |
|
false |
PHPDoc 规范收紧计划
背景
当前 php-clean-code.mdc 存在两条互相削弱的规则：
- 第 165 行：
Logic、Service、Model 的 public 方法**建议**写 PHPDoc - 第 167–174 行：仅列举部分场景「必须写」
- 第 203 行：
简单 getter/setter、方法名和类型已足够清晰时，**不强制** PHPDoc
团队诉求：除纯 getter/setter 外，其余方法都要写 PHPDoc，且以中文说明业务含义（很多人看不懂英文方法名）。这与已存在的 Model 类 @property 规范（约 123–159 行）方向一致，需统一到同一套原则。
修改范围
仅改规则文件（不批量改历史代码）：
/Users/ray/.cursor/rules/php-clean-code.mdc— §5 PHPDoc 与注释、§8 Agent 自查
agent-completion-gate.mdc 仍引用「php-code PHPDoc 章节」，无需改路径；完成门禁时 Agent 按更新后的 §5 执行即可。
§5 改写要点
1. 默认规则：从「建议」改为「必须」
将第 165 行改为明确默认值：
Logic / Service / Model 的
public方法必须写 PHPDoc（首行中文说明业务动作）；protected方法若承载业务步骤，同样必须。
2. 唯一豁免：纯 getter / setter
用白名单定义豁免，替代原第 203 行「方法名够清晰可不写」：
| 可豁免 | 不可豁免 |
|---|---|
无业务分支、无事务、无外部调用的 getXxx() / setXxx() |
findActiveBySessionId、createActiveSession、launchWithSession 等 |
| 只读/写入单个属性或 DTO 字段 | 名称像 getter 但含查询、状态判断、写入库表 |
isXxx() / hasXxx() / ensureXxx() / markXxx() |
示例（写入规范正文）：
// 可豁免
public function getUid(): int { return $this->uid; }
// 不可豁免 — 必须中文 PHPDoc
public static function findActiveBySessionId(string $sessionId): ?self
3. 方法 PHPDoc 格式要求（中文优先）
规定最小合格格式（与现有 Model @property 风格一致）：
/**
* 按对外 session_id 查询未过期且有效的 Launch Session。
*
* @throws BusinessException 当 ...
*/
public static function findActiveBySessionId(string $sessionId): ?self
- 首行必须是中文，说明「做什么 / 业务结果」，不能只重复英文方法名。
- 保留现有硬性要求：
array结构、@throws、状态流转等（作为附加要求，不是唯一触发条件）。 - 禁止废话：禁止只写
/** get user */、/** @param int $uid */而无中文业务说明；禁止与签名完全重复的英文复述。
4. 删除 / 替换第 203 行
删除：
不要写废话 PHPDoc。简单 getter/setter、方法名和类型已足够清晰时，不强制 PHPDoc。
替换为两条并列原则：
- 禁止废话：无信息增量、纯英文复述签名 → 不合格。
- 除纯 getter/setter 外一律必须：英文命名不能替代中文 PHPDoc。
保留第 205 行「注释解释为什么，不解释做什么」——仅适用于行内注释；方法 PHPDoc 首行仍要写「做什么」（中文），复杂处再用行内注释写「为什么」。
5. 收紧原「以下情况必须写」列表
原列表（返回 array、状态流转等）改为 「以下情况除满足通用要求外，还须额外写明…」，避免读者误以为「不在列表里就可以不写」。
结构示意：
flowchart TD
method[public方法] --> isGetter{纯getter/setter?}
isGetter -->|是| exempt[可省略PHPDoc]
isGetter -->|否| required[必须中文PHPDoc首行]
required --> extra{array或throws等?}
extra -->|是| addTags[补充结构或throws]
§8 Agent 自查增补
在 §8 增加 / 调整检查项（约 245 行后）：
- Logic / Service / Model 的
public方法是否均有中文 PHPDoc（除纯 getter/setter）？ - 是否存在「只有
@param/@return类型、无中文业务说明」的 PHPDoc？
可将原「返回 array / 复杂数组 / throws」三条合并表述为「在通用要求之上是否满足附加结构」，避免清单过长。
不纳入本次范围
- 不批量给存量 PHP 文件补 PHPDoc（体量大，另开重构任务）。
- 不强制 Controller / Validate / DTO 全量 PHPDoc（当前 §5 范围是 Logic/Service/Model；若需扩大可后续单独立项）。
- 不新增 CI 自动检测脚本（可选后续：
scripts/check-phpdoc.sh）。
验收
php-clean-code.mdc§5 不再出现「方法名够清晰可不写 PHPDoc」。- 新规则与 Model
@property小节无矛盾。 - Agent 自查清单覆盖「中文 PHPDoc + getter/setter 豁免」。