ok

2026-05-29 17:23:17 +08:00
parent f71a5c59af
commit 1bcb6120dd
139 changed files with 4229 additions and 523 deletions
--- a/plans/phpdoc_规范收紧_f84cb482.plan.md
+++ b/plans/phpdoc_规范收紧_f84cb482.plan.md
@@ -0,0 +1,132 @@
+---
+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 豁免」。