初始化

.cursor/rules/skill-module-scaffold.mdc

@@ -0,0 +1,82 @@
+---
+description: >
+  Hyperf 模块化脚手架技能。在 modules/ 下新建业务模块、创建 module、
+  添加模块化功能时激活。基于 Composer path repository + ConfigProvider 机制。
+globs:
+  - "**/modules/*/src/**/*.php"
+  - "**/modules/*/composer.json"
+alwaysApply: false
+---
+
+# Module Scaffold
+
+> 本文件是精简执行摘要。完整流程、模板和深度参考见：
+> Read `.cursor/skills/module-scaffold/SKILL.md`
+
+> **适用性**（双模式）：
+> - **新建**模块：走完整执行流程（Step 1-7）
+> - **修改**已有模块代码：跳过脚手架步骤，完成后走「验证」清单
+
+## 执行流程
+
+1. 确认模块规格（名称、描述、接口类型：`api` / `admin` / `both`、所需子层）
+2. 生成目录结构（**Controller 按接口类型分子目录，见下方规则**）
+3. 生成模块 `composer.json`（name: `modules/{kebab-case}`, namespace: `Modules\{PascalCase}`, extra.hyperf.config）
+4. 生成 `ConfigProvider.php`（注册 dependencies + annotations scan + publish）
+5. 生成 Controller（根据接口类型选择正确子目录和模板）
+6. **配置依赖检查**（使用事件/队列/缓存时必须检查）：
+   - 使用异步队列：检查主项目 `config/autoload/async_queue.php` 是否存在
+   - 使用 Redis 缓存：检查主项目 `config/autoload/redis.php` 连接池配置
+   - 使用 JWT：检查主项目 `config/autoload/jwt.php` 和环境变量 `JWT_SECRET`
+7. **无需修改主项目 `composer.json`**：ModuleLoader 在启动时自动扫描发现
+8. 验证：`require vendor/autoload.php` 后检查 ConfigProvider 是否被发现
+
+## Controller 与 Request 目录规则（核心）
+
+根据接口路由前缀，Controller 和 Request **均须放入对应子目录**：
+
+| 接口类型 | 路由前缀 | Controller 目录 | Request 目录 | 类名规范 |
+|----------|----------|-----------------|--------------|----------|
+| 用户端 | `/api/{module}` | `Http/Controller/Api/` | `Http/Request/Api/` | `{Name}Controller` / `{Name}Request` |
+| 管理端 | `/admin/{module}` | `Http/Controller/Admin/` | `Http/Request/Admin/` | `{Name}Controller` / `{Name}Request` |
+| 两者 | 各自前缀 | 两组子目录都创建 | 两组子目录都创建 | 各自子目录，类名相同 |
+
+**额外约定**：
+- `Admin/` 下的控制器**自动添加** `#[Middleware(JwtAuthMiddleware::class)]` 注解
+- **类名不加接口类型前缀**，`Api/` 和 `Admin/` 下同名类通过命名空间区分
+- Controller 中 `use` 的 Request 路径必须与子目录命名空间一致
+- 路由前缀中 `/api/` 和 `/admin/` 是判断依据，不能混放
+- 未明确时，**主动询问**接口类型而不是猜测
+
+## 命名约定
+
+| 位置 | 格式 | 示例 |
+|------|------|------|
+| 目录名 | PascalCase | `modules/UserCenter/` |
+| Composer 包名 | kebab-case | `modules/user-center` |
+| PHP 命名空间 | PascalCase | `Modules\UserCenter` |
+| 用户端路由前缀 | `/api/kebab-case` | `/api/user-center` |
+| 管理端路由前缀 | `/admin/kebab-case` | `/admin/user-center` |
+
+## 关键机制
+
+- **ModuleLoader 自动发现**：`app/Support/ModuleLoader.php` 注册在 `autoload.files`，在 `vendor/autoload.php` 执行时扫描 `modules/*/composer.json`，通过反射注入 `Hyperf\Support\Composer::$extra`，让 `ProviderConfig::load()` 发现模块 ConfigProvider。**无需修改 `composer.json` require**
+- **composer-merge-plugin**：合并模块 `composer.json` 的 `autoload` 和第三方 `require` 到主项目（仅在模块有外部依赖时才需要 `composer update`）
+- **ConfigProvider**：模块自注册 DI 绑定、注解扫描路径、可发布配置
+
+## 验证
+
+- [ ] **Controller 按接口类型放入正确子目录**（`Api/` 或 `Admin/`，不能平铺在 `Controller/` 根目录）
+- [ ] **Request 按接口类型放入正确子目录**（`Request/Api/` 或 `Request/Admin/`，不能平铺在 `Request/` 根目录）
+- [ ] Controller 命名空间含 `\Controller\Api\` 或 `\Controller\Admin\`
+- [ ] Request 命名空间含 `\Request\Api\` 或 `\Request\Admin\`
+- [ ] Controller 中 `use` 的 Request 路径与子目录命名空间一致
+- [ ] `Admin/` 下：Controller 自动加 `JwtAuthMiddleware`；类名与 `Api/` 保持一致，**不加 `Admin` 前缀**
+- [ ] 模块结构完整（composer.json + ConfigProvider.php + Http/Controller/{Api|Admin}/ + Http/Request/{Api|Admin}/）
+- [ ] composer.json name 为 `modules/{kebab-case}`
+- [ ] namespace 为 `Modules\{PascalCase}`
+- [ ] ConfigProvider 注册 `__DIR__` 扫描路径
+- [ ] extra.hyperf.config 指向正确 ConfigProvider
+- [ ] **无需修改主 composer.json**，ModuleLoader 自动发现
+- [ ] Hyperf ProviderConfig 能发现模块 ConfigProvider
+- [ ] `php -l` 无语法错误