---
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 报告**，二者互补。