---
name: PHPDoc 规范收紧
overview: 调整 [`php-clean-code.mdc`](/Users/ray/.cursor/rules/php-clean-code.mdc) 第 5 节 PHPDoc 规则：除纯 getter/setter 外，Logic/Service/Model 的 public 方法一律必须写中文 PHPDoc；删除「方法名够清晰可不写」的豁免，并同步 Agent 自查清单。
todos:
  - id: revise-section-5
    content: 重写 php-clean-code.mdc §5：默认必须、getter/setter 豁免、中文首行、删除旧豁免句
    status: completed
  - id: tighten-must-list
    content: 将原「以下情况必须写」改为「附加要求」，避免被理解为可选项
    status: completed
  - id: update-agent-checklist
    content: 更新 §8 Agent 自查：中文 PHPDoc 全覆盖检查项
    status: completed
  - id: verify-consistency
    content: 通读 Model @property 小节与 §5，确认无冲突表述
    status: completed
isProject: false
---

# PHPDoc 规范收紧计划

## 背景

当前 [`php-clean-code.mdc`](/Users/ray/.cursor/rules/php-clean-code.mdc) 存在两条互相削弱的规则：

- 第 165 行：`Logic、Service、Model 的 public 方法**建议**写 PHPDoc`
- 第 167–174 行：仅列举部分场景「**必须**写」
- 第 203 行：`简单 getter/setter、方法名和类型已足够清晰时，**不强制** PHPDoc`

团队诉求：**除纯 getter/setter 外，其余方法都要写 PHPDoc，且以中文说明业务含义**（很多人看不懂英文方法名）。这与已存在的 [Model 类 `@property` 规范](/Users/ray/.cursor/rules/php-clean-code.mdc)（约 123–159 行）方向一致，需统一到同一套原则。

## 修改范围

**仅改规则文件**（不批量改历史代码）：

- [`/Users/ray/.cursor/rules/php-clean-code.mdc`](/Users/ray/.cursor/rules/php-clean-code.mdc) — §5 PHPDoc 与注释、§8 Agent 自查

[`agent-completion-gate.mdc`](/Users/ray/.cursor/rules/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()` |

示例（写入规范正文）：

```php
// 可豁免
public function getUid(): int { return $this->uid; }

// 不可豁免 — 必须中文 PHPDoc
public static function findActiveBySessionId(string $sessionId): ?self
```

### 3. 方法 PHPDoc 格式要求（中文优先）

规定最小合格格式（与现有 Model `@property` 风格一致）：

```php
/**
 * 按对外 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、状态流转等）改为 **「以下情况除满足通用要求外，还须额外写明…」**，避免读者误以为「不在列表里就可以不写」。

结构示意：

```mermaid
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 豁免」。