ok

skills/slot-backend-completion-report/SKILL.md

@@ -0,0 +1,101 @@
+---
+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 报告**，二者互补。