---
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` 无语法错误