初始化

.cursor/skills/api-scaffold/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: api-scaffold
+version: 3.0.0
+description: "生成 Hyperf API 端点脚手架（Controller/Service/FormRequest/路由）。当需要新建 API 接口或 CRUD 资源时使用。含分级异常体系。"
+---
+
+> ⚠️ 核心执行流程已在 `.cursor/rules/skill-backend-scaffold.mdc` 中由 Cursor 自动注入。
+> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
+
+# Hyperf API Endpoint Scaffold
+
+## 触发条件
+
+用户要求创建新 API 端点、路由、接口、REST 资源或 CRUD 操作。
+
+## 执行流程
+
+### 0. 加载规范（⚠️ 必须最先执行）
+
+依次使用 `Read` 工具读取：
+- `.cursor/rules/013-backend.mdc` — ApiResponse 格式、FormRequest、路由、认证
+- `.cursor/rules/019-modular.mdc` — Controller→Service→Repository→Model 依赖方向、各层职责
+
+### 1. 确认端点规格
+
+| 字段 | 必填 | 默认值 |
+|------|------|--------|
+| 资源名称 | ✅ | — |
+| HTTP 方法 | ✅ | — |
+| 路由路径 | ✅ | — |
+| 请求体结构 | GET 除外 | — |
+| 响应结构 | ✅ | — |
+| 需要认证？ | ❌ | true |
+| 需要权限？ | ❌ | true |
+| 分页？ | ❌ | GET 列表自动加 |
+
+### 2. 生成文件
+
+生成 Controller、Service、FormRequest、Model（如不存在）、路由。分层约定与完整模板见 **Tier 3**。
+
+### 3. 遵循项目约定
+
+生成前扫描：`app/Controller/` 现有模式、`AbstractController` 基类、`AppExceptionHandler`、中间件注册方式。
+
+### 4. 异常体系
+
+- `BusinessException` — 404/403/409/422 等可预期业务错误
+- `ValidationException` — FormRequest 校验失败
+- `SystemException` — 500 系统故障，记录堆栈并通知运维
+
+异常选择决策与 `AppExceptionHandler` 实现见 **Tier 3**。
+
+## 验证
+
+1. [ ] `php -l` 编译无错误
+2. [ ] FormRequest rules 覆盖所有请求字段
+3. [ ] 错误处理覆盖 400/401/403/404/422/500
+4. [ ] Service 使用事务包裹写操作
+5. [ ] 路由遵循 RESTful 命名（复数名词、kebab-case）
+6. [ ] 中间件正确挂载（认证 + 权限）
+7. [ ] 可预期错误使用 `BusinessException`
+8. [ ] 不可预期错误使用 `SystemException`
+9. [ ] `SystemException` 不向客户端暴露内部细节
+10. [ ] `AppExceptionHandler` 已注册在 `config/autoload/exceptions.php`
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/code-templates.md` | Controller/Service/FormRequest/路由完整模板 |
+| `references/exception-handling.md` | 分级异常体系与 AppExceptionHandler 实现 |