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

name, description

name	description
slot-backend-completion-report	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. 跑统一脚本（推荐）

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 自查必须逐项过一遍。

最终回复必须包含的章节

## 检测结果

### 门禁脚本
（粘贴 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 报告，二者互补。