102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
---
|
||
name: slot-backend-completion-report
|
||
description: >-
|
||
Slot PHP 后端任务收尾自检：跑 verify 门禁、docker php -l、对照 php-clean-code
|
||
与 backend-layering 输出结构化检测报告。修改 app/**/*.php 后收尾前必读；用户说
|
||
「按规范检测」「检测代码」时也触发。
|
||
---
|
||
|
||
# Slot 后端完成前检测报告
|
||
|
||
用户级 Skill：**禁止写死** `slot-xxx`、`/app/www/ray/...` 等服务路径；一律从**当前工作区 + git 仓库根 + Docker 挂载**推导。
|
||
|
||
## 何时执行
|
||
|
||
- 本次对话改动了任意 `app/**/*.php`
|
||
- 用户要求「按规范检测 / 检测代码 / 出检测报告」
|
||
- 准备写「已完成 / 可以合并 / 验收通过」之前
|
||
|
||
## 步骤（按顺序）
|
||
|
||
### 1. 跑统一脚本（推荐）
|
||
|
||
```bash
|
||
SLOT_ROOT="${SLOT_ROOT:-<当前 Cursor 工作区根目录>}" \
|
||
~/.cursor/skills/slot-backend-completion-report/scripts/report.sh
|
||
```
|
||
|
||
- `SLOT_ROOT` 默认为当前工作区根（可能在 `www/ray`、`www/slot` 等不同 monorepo 下）
|
||
- 脚本会：
|
||
1. 调用 `~/.cursor/hooks/verify-slot-backend.sh`
|
||
2. 对 git diff 中每个改动 `.php` 执行 `docker php -l`
|
||
|
||
### 2. 路径映射规则（脚本已实现，Agent 手工跑命令时同样遵守）
|
||
|
||
对每个改动 PHP 文件 `$f`：
|
||
|
||
1. `repo=$(git -C "$(dirname "$f")" rev-parse --show-toplevel)`
|
||
2. 宿主机挂载根 → 容器根（见 `dev-environment`）：
|
||
- `SLOT_DOCKER_HOST_ROOT` 默认 `/Users/ray/Documents/project`
|
||
- `SLOT_DOCKER_CONTAINER_ROOT` 默认 `/app`
|
||
3. `container_wd="${SLOT_DOCKER_CONTAINER_ROOT}${repo#$SLOT_DOCKER_HOST_ROOT}"`
|
||
4. `docker exec -w "$container_wd" php82 php -l "${f#$repo/}"`
|
||
|
||
示例（由路径**推导**，非手写）：
|
||
|
||
| git 仓库根（宿主机） | 容器 `-w` |
|
||
|----------------------|-----------|
|
||
| `.../project/www/ray/slot-admin` | `/app/www/ray/slot-admin` |
|
||
| `.../project/www/slot/slot_wallet` | `/app/www/slot/slot_wallet` |
|
||
|
||
仓库不在 `SLOT_DOCKER_HOST_ROOT` 下 → 跳过 docker 语法检查并在报告中说明。
|
||
|
||
### 3. 规范对照（Agent 读 diff 后填表，脚本无法替代）
|
||
|
||
| 检查项 | 依据 | 做法 |
|
||
|--------|------|------|
|
||
| PHPDoc 中文首行 | `php-clean-code` §5 | 改动的方法均有中文说明 |
|
||
| 类常量注释 | `php-clean-code` §3 常量规则 | 所有 `const` 均有 `/** 中文说明 */` |
|
||
| Logic 参数与日志 | §3 参数与日志 | 无仅用于日志的多余参数 |
|
||
| 聚合 DTO | §3 编排上下文 | 无重复标量 / 双份拷贝 |
|
||
| Logic/Service 返回值 | `php-clean-code` §4 + `verify-slot-backend.sh` | 未返回 `array`；固定形状用 Entity |
|
||
| 分层 | `backend-layering` | Controller 薄、Logic 编排、无 Logic 型 Service |
|
||
| 业务异常 | `agent-completion-gate` | 不用 RuntimeException 表业务失败 |
|
||
|
||
改 `app/**/logic/**/*.php` 时，§3 参数与日志、聚合 DTO、§8 自查**必须**逐项过一遍。
|
||
|
||
## 最终回复必须包含的章节
|
||
|
||
```markdown
|
||
## 检测结果
|
||
|
||
### 门禁脚本
|
||
（粘贴 report.sh 或 verify-slot-backend.sh 完整输出，以 `=== verify-slot-backend ===` 或 `=== slot-backend-completion-report ===` 开头）
|
||
|
||
### PHP 语法（docker php -l）
|
||
（粘贴 php -l 输出；无改动 PHP 写「无改动 PHP」）
|
||
|
||
### 规范对照
|
||
| 项 | 结果 | 说明 |
|
||
|----|------|------|
|
||
| PHPDoc / 常量注释 | 通过/不通过 | … |
|
||
| Logic/Service 返回 Entity | 通过/不通过/不适用 | … |
|
||
| 分层 | 通过/不通过/不适用 | … |
|
||
| Logic §3 / §8（若改 Logic） | 通过/不适用 | … |
|
||
|
||
### 结论
|
||
通过 / 不通过（不通过须先修复再收尾）
|
||
|
||
PHPDoc: checked
|
||
```
|
||
|
||
## 禁止
|
||
|
||
- 未跑脚本、未对照规范就写「已完成」
|
||
- 只贴 `PASS` 一行、无规范对照表
|
||
- 在宿主机直接跑 `php` / `composer`（须 docker，见 `dev-environment`）
|
||
- 写死 `/app/www/ray/slot-xxx` 或假设固定 monorepo 目录
|
||
|
||
## 与 Hook 的关系
|
||
|
||
`~/.cursor/hooks.json` 的 `stop` 会自动跑 `verify-slot-backend.sh`；本 Skill 在此基础上补 **php -l** 与 **结构化 Markdown 报告**，二者互补。
|