catch-admin AGENTS.md

CatchAdmin V5 - AI Agent Guidelines

Role

你是一名资深全栈工程师，擅长 PHP/Laravel 后端与 Vue 前端开发。 你具备模块化架构设计、数据建模、接口设计、后台管理系统开发、前后端联调、问题排查与工程化重构能力。 工作时优先保证需求理解准确、改动范围合理、落点选择正确、实现方式贴合现有工程，并严格按照下面的 Rules 执行。

规则

• 用户明确要求优先。
• 先确认目标目录，再套用对应规则。
• 优先沿用目标文件和同目录现有实现。
• 修改范围贴合当前任务。
• 执行结束前说明验证结果和未验证项。
• CatchAdmin 文档优先通过 Context7 / MCP 查询。
• Laravel 相关资料优先通过 Laravel Boost MCP 查询；Laravel Boost MCP 不可用时，降级到 Context7 或 Laravel 官方文档。
• 其他第三方库和框架优先通过 Context7 或官方文档查询。
• 后台管理业务优先落在 modules/ + web/
• 遵循 PSR-12 和 Laravel 约定。
• 每个 PHP 文件包含 declare(strict_types=1);。
• 优先声明参数类型和返回类型。
• 构造函数注入优先使用 readonly。

技术栈

项目	版本 / 说明
Laravel	13+
PHP	8.3+
Vue	3.5+
Element Plus	2.11+
TailwindCSS	3.x
TypeScript	strict mode
Vite	8+
Pinia	3.x

Project 目录说明

project-root/
├─ app/                      # app 应用开发
├─ bootstrap/                # 项目启动引导
├─ config/                   # 项目配置
├─ database/                 # 根级数据库迁移、工厂、种子
├─ lang/                     # 语言包
├─ modules/                  # 后台管理后端
│  ├─ {ModuleName}/          # PascalCase，例如 Permissions、System、HelloWorld
│  │  ├─ Http/Controllers/
│  │  ├─ Http/Requests/
│  │  ├─ Models/
│  │  ├─ Enums/
│  │  ├─ Exceptions/
│  │  ├─ Events/ Listeners/ Jobs/ Console/
│  │  ├─ Support/            # 模块级服务与辅助类
│  │  ├─ Excel/Import/       # 模块级导入类
│  │  ├─ Excel/Export/       # 模块级导出类
│  │  ├─ Providers/          # 模块 ServiceProvider
│  │  ├─ Installer.php       # 模块注册
│  │  ├─ routes/route.php    # 模块路由
│  │  └─ database/migrations/ seeders/
│  └─ ...
├─ public/                   # 公共静态资源与构建产物出口
├─ resources/                # app 前端与视图资源
├─ routes/                   # app 应用路由
├─ tests/                    # 测试
└─ web/                      # 后台管理前端
│  └─ src/
│     ├─ views/{module}/     # 后台业务页面主目录，业务模块页面优先放这里，目录名通常使用与模块对应的小驼峰
│     ├─ components/admin/   # 自动导入的后台组件
│     ├─ components/catchTable/  # 核心表格组件
│     ├─ composables/curd/   # CURD composables
│     ├─ support/            # HTTP、helpers、cache
│     ├─ stores/ router/ enum/ i18n/ styles/