142 lines
6.3 KiB
Markdown
142 lines
6.3 KiB
Markdown
---
|
||
name: PHPDoc Cursor 规则
|
||
overview: 在 Cursor 全局规则中新增 PHP PHPDoc 严格规范（类、方法、常量全覆盖），与现有 backend-layering 规则并列，并明确适用范围与模板，避免与「不写显而易见注释」的原则冲突。
|
||
todos:
|
||
- id: create-php-doc-mdc
|
||
content: "新建 /Users/ray/.cursor/rules/php-doc.mdc（globs: **/*.php，严格 PHPDoc 正文 + 示例）"
|
||
status: completed
|
||
- id: verify-rule-active
|
||
content: 在 Cursor 中打开任意 .php 文件，确认规则被注入；用 WalletLogic 缺注释方法做一次试写验证
|
||
status: completed
|
||
- id: optional-readme-sync
|
||
content: （可选）将 PHPDoc §3.4 同步到 slot_wallet 等 README，与 Cursor 规则保持一致
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# 新增 PHPDoc 严格 Cursor 规则
|
||
|
||
## 结论：要加，但不要写成「所有符号一刀切」的空话
|
||
|
||
你选择了 **严格全覆盖**。建议在 Cursor 里加一条 **独立规则文件**，与现有的 [`backend-layering.mdc`](/Users/ray/.cursor/rules/backend-layering.mdc) 并列，而不是塞进 layering 里（职责不同：一个管分层，一个管文档）。
|
||
|
||
**不建议**写成模糊的「所有都要 PHPDoc」——应写清 **哪些符号、最少哪些 tag、何时可写短句**。否则 Agent 会在 trivial 代码上堆 `@param int $uid uid` 这类无意义注释，与 [`slot_agent/README.md`](/Users/ray/Documents/project/www/slot/slot_agent/README.md) 第 9.3 节「不解释显而易见语句」打架。
|
||
|
||
## 现状
|
||
|
||
| 来源 | PHPDoc 要求 |
|
||
|------|-------------|
|
||
| [`.cursor/rules/`](/Users/ray/.cursor/rules/) | 仅有 layering + dev-environment，**无 PHPDoc** |
|
||
| [`slot_agent/README.md`](/Users/ray/Documents/project/www/slot/slot_agent/README.md) §6.2 | 已要求：业务类说明、公开方法说明、参数/返回值说明 |
|
||
| 实际代码（如 [`WalletLogic.php`](/Users/ray/Documents/project/www/slot/slot_wallet/app/api/logic/WalletLogic.php)） | **不一致**：`run`/`register` 有块注释，`initWalletWithoutMoney`、`getBalance` 无 |
|
||
|
||
终端里曾出现给 `slot_wallet/README.md` 增加 §3.4 PHPDoc 的 diff，但当前 README **尚未落地**该节——规范应优先进 **Cursor rule**（Agent 每次都会读），README 可作为人类文档二次同步（可选）。
|
||
|
||
## 推荐规则文件
|
||
|
||
**路径**：[`/Users/ray/.cursor/rules/php-doc.mdc`](/Users/ray/.cursor/rules/php-doc.mdc)
|
||
|
||
**Frontmatter 建议**：
|
||
|
||
```yaml
|
||
---
|
||
description: PHP PHPDoc requirements for all classes, methods, and constants
|
||
globs: "**/*.php"
|
||
alwaysApply: false
|
||
---
|
||
```
|
||
|
||
- 用 `globs: **/*.php`：编辑 PHP 时自动注入，不污染 Vue/TS 会话
|
||
- `alwaysApply: false`：与 layering 的 `true` 区分，减少非 PHP 任务 token
|
||
|
||
## 规则正文（严格版，建议写入 mdc）
|
||
|
||
### 1. 适用范围
|
||
|
||
- **新增或修改**的 PHP 文件中的：**class / interface / trait / enum**、**所有方法**（`public` / `protected` / `private`）、**所有类常量**（`const`）
|
||
- 适用目录：`slot_*`、`backend/**` 下 PHP 业务代码
|
||
- **不追溯**改历史未动代码；但 **本次 diff 触及的符号** 若缺 PHPDoc，须一并补齐
|
||
|
||
### 2. 最低 PHPDoc 内容
|
||
|
||
| 符号 | 必须包含 |
|
||
|------|----------|
|
||
| 类 / 接口 / Trait | 一行职责说明；复杂类可加 `@package`（可选） |
|
||
| 方法 | 职责说明 + 每个参数的 `@param` + `@return`；有 `throw` 的须 `@throws` |
|
||
| 类常量 | 一行说明业务含义（单位、枚举语义、与配置/表字段对应关系） |
|
||
| 属性（若新增） | `@var` 或 typed property + 一行说明（仅当类型/语义不直观时） |
|
||
|
||
已有 **PHP 8+ 标量/对象类型声明** 时，`@param`/`@return` 仍要保留（与你选的 strict 一致），但 **描述句可短**，禁止空块或只复制类型名。
|
||
|
||
### 3. 禁止项（与 slot_agent 注释原则对齐）
|
||
|
||
- 禁止无 `@param` / `@return` 的空 `/** */`
|
||
- 禁止 `@param int $id id` 式同义反复；语义、单位、边界写进描述
|
||
- 禁止用 PHPDoc 替代 Validate / Logic 里的业务校验说明
|
||
|
||
### 4. 分层补充（与 layering 一致）
|
||
|
||
对以下层 **额外** 要求写清业务语义（不仅是类型）：
|
||
|
||
- **Controller**：接口用途、幂等/鉴权前提（若有）
|
||
- **Logic**：用例步骤、事务边界、失败时行为
|
||
- **Service**：复用场景、调用方约束
|
||
- **Model**：查询条件、分表键、金额字段单位
|
||
- **DTO / Validate**：字段含义、与上游参数映射
|
||
|
||
### 5. 示例模板（写入规则供 Agent 照抄）
|
||
|
||
```php
|
||
/**
|
||
* 首充前冻结免费余额。
|
||
*
|
||
* @return WalletEntity|null 成功返回钱包实体；无需冻结时返回 null
|
||
* @throws WalletException 余额不足或钱包不存在
|
||
*/
|
||
public function freeCreditsFreeze(): ?WalletEntity
|
||
```
|
||
|
||
```php
|
||
/** 释放档位：单位分，对应配置 free_credits.release_tiers */
|
||
public const RELEASE_TIER_MIN = 100;
|
||
```
|
||
|
||
## 与工具链的关系（可选，本期可不做的）
|
||
|
||
Cursor rule **不能**在 CI 里自动 fail。若以后要机器 enforce，再单独加：
|
||
|
||
- PHPStan + `phpstan/phpdoc-parser` 或
|
||
- PHPCS `Squiz.Commenting` / 自定义 sniff
|
||
|
||
本期仅 Cursor 规则即可满足「Agent 写码时遵守」。
|
||
|
||
## 实施步骤
|
||
|
||
1. 新建 [`php-doc.mdc`](/Users/ray/.cursor/rules/php-doc.mdc)，按上文写入 frontmatter + 正文
|
||
2. 在 Cursor Settings → Rules 确认该规则对 PHP 文件生效（`globs` 匹配）
|
||
3. （可选）把相同 §3.4 同步进 [`slot_wallet/README.md`](/Users/ray/Documents/project/www/slot/slot_wallet/README.md) 与其它服务 README，供人工 review 对照
|
||
4. 用一次小改动验证：例如在 `WalletLogic` 给无注释的 `getBalance` 补 PHPDoc，看 Agent 是否自动遵循
|
||
|
||
## 风险与预期
|
||
|
||
- **Diff 变大**：strict 下每个新方法多 5–15 行注释，属预期成本
|
||
- **历史债**：全库补 doc 工作量巨大；规则应写明 **仅 touch 到的符号**，避免 Agent 一次性重构整文件
|
||
- **类型重复**：strict 仍保留 `@param`/`@return` 类型，利于 IDE/静态分析；描述聚焦「为什么/单位/边界」
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph rules [Cursor Rules]
|
||
layering[backend-layering.mdc]
|
||
phpdoc[php-doc.mdc]
|
||
devenv[dev-environment.mdc]
|
||
end
|
||
subgraph code [PHP 改动]
|
||
edit[编辑 PHP 文件]
|
||
agent[Agent 生成/修改代码]
|
||
end
|
||
edit --> phpdoc
|
||
edit --> layering
|
||
agent --> phpdoc
|
||
agent --> layering
|
||
```
|