ok

rules/php-clean-code.mdc

@@ -70,7 +70,7 @@ alwaysApply: true
 - 参数超过 3 个时，优先使用 DTO、Value Object 或专门数据结构。
 - 核心业务入参不要直接使用含糊的 `array`。
 - 返回 `array` 时必须结构明确，并用 PHPDoc 描述结构。
-- 私有方法也必须有清晰业务语义。
+- 私有方法也必须有清晰业务语义，并写中文 PHPDoc（见 §5；纯 getter/setter 除外）。
 - 复杂条件必须封装成有语义的方法。
 - 魔法数字必须变成常量或枚举。
 - 业务规则判断优先使用 `ensureXxx()` 方法。
@@ -98,7 +98,7 @@ alwaysApply: true
 
 - Logic 是业务用例入口，一个 public 方法通常对应一个业务用例。
 - Logic 主方法要像读业务流程。
-- Logic 私有方法必须有业务语义。
+- Logic 私有方法必须有业务语义与中文 PHPDoc（纯 getter/setter 除外）。
 - Logic 可以查业务主体、调用 Model、调用公共 Service、做业务判断、控制事务、写业务日志、组装返回结果。
 - 复杂查询条件应沉淀到 Model。
 - 涉及多表写入、钱包变动、订单状态变更、活动领取、返水领取、游戏下注 / 派奖时，事务边界必须放在 Logic。
@@ -164,9 +164,10 @@ class GameLaunchSessionModel extends Model
 
 ### 默认规则（必须）
 
-**Logic / Service / Model 的 `public` 方法必须写 PHPDoc**，首行用**中文**说明业务动作或结果（很多人看不懂英文方法名，英文命名不能替代 PHPDoc）。
+**Logic / Service / Model 的 `public` / `protected` / `private` 方法必须写 PHPDoc**，首行用**中文**说明业务动作或结果（很多人看不懂英文方法名，英文命名不能替代 PHPDoc）。
 
-`protected` 方法若承载业务步骤（非纯 getter/setter），同样必须写中文 PHPDoc。
+- `public`：一律必须（纯 getter/setter 除外，见下文）。
+- `protected` / `private`：Logic 与 Service 中凡承载业务步骤的方法必须写；Model 的 `private` 若仅为薄封装且无语义增量可省略，但 `find*` / `mark*` / 访问 DB/Redis 的 `private` 仍必须写。
 
 最小合格格式：
 
@@ -185,10 +186,11 @@ public static function findActiveBySessionId(string $sessionId): ?self
 
 ### 唯一豁免：纯 getter / setter
 
-仅以下方法可省略 PHPDoc：
+以下方法（含 `private`）可省略 PHPDoc：
 
 - 无业务分支、无事务、无外部调用、无查库写库的 `getXxx()` / `setXxx()`。
 - 只读或只写入**单个**属性或 DTO 字段。
+- 仅做字符串/ key 拼接、无业务判断的极简 accessor（如 `return $uid . '_' . $roundId`）。
 
 ```php
 // 可豁免
@@ -245,7 +247,7 @@ public static function findActiveBySessionId(string $sessionId): ?self
 ### 废话与行内注释
 
 - **禁止废话 PHPDoc**：无信息增量、纯英文复述签名 → 不合格。
-- **除纯 getter/setter 外一律必须**：不得以「方法名够清晰」为由省略 PHPDoc。
+- **除纯 getter/setter 外一律必须**：`public` / `protected` / `private` 均不得以「方法名够清晰」或「仅内部调用」为由省略 PHPDoc。
 - **行内注释**解释为什么，不解释做什么；方法 PHPDoc 首行仍要写「做什么」（中文）。复杂业务、幂等、分布式锁、状态流转、第三方兼容、历史兼容逻辑须在行内注释说明原因。
 
 ---
@@ -295,7 +297,7 @@ public static function findActiveBySessionId(string $sessionId): ?self
 - 是否泄露敏感信息？
 - 返回数据是否明确？
 - 是否直接返回 Model？
-- Logic / Service / Model 的 `public` 方法是否均有**中文** PHPDoc 首行（纯 getter/setter 除外）？
+- Logic / Service / Model 的 `public` / `protected` / `private` 方法是否均有**中文** PHPDoc 首行（纯 getter/setter 除外）？
 - 是否存在只有 `@param`/`@return` 类型、无中文业务说明的 PHPDoc？
 - 返回 array / 复杂数组参数 / 抛异常的方法，是否在通用 PHPDoc 之上补全了 `array{...}` 结构与 `@throws`？
 - 是否存在「仅用于日志」的多余参数？