neo-admin: Instructions file for Claude Code

CLAUDE.md

Neo Admin 项目开发指南：架构、目录约定与运行时规范。

---

项目简介

Neo Admin 是一套面向可治理、可审计、可扩展场景的后台管理系统：

• 后端：PHP 8.2+，Laravel 12
• 前端：Vue 3（IIFE）、Element Plus、Axios
• 数据库：MySQL 5.7+（示例配置）
• 架构：Laravel + Blade 服务端渲染为主，Vue 做页面交互增强（非 SPA）
• 构建：不使用 Vite / Webpack / npm 构建链；静态资源本地化

---

核心原则

1. 保持 Laravel + Blade 架构 — Vue 仅用于交互增强，不构建 SPA
2. 轻量、低依赖 — 禁止引入 npm 构建、CDN 外链、.vue 单文件组件
3. 标准 CRUD + 权限 + 统一响应 — 后台模块遵循固定分层
4. 配置中心统一读取 — 动态配置禁止散落查表或硬编码密钥
5. 最小改动 — 只改任务相关代码，不批量重构、不修改 vendor

---

目录结构

neo-admin/
├── app/
│   ├── Console/Commands/Admin/     # 运维命令（密码、2FA 等）
│   ├── Http/
│   │   ├── Controllers/Admin/
│   │   │   ├── Api/                # JSON API（CRUD）
│   │   │   ├── Auth/               # 登录、2FA
│   │   │   ├── Content/            # 页面 Controller（__invoke）
│   │   │   └── Concerns/           # ApiResponse、AppliesListFilters
│   │   └── Middleware/             # admin.auth / admin.perm / admin.log
│   ├── Models/                     # Eloquent 模型
│   │   └── Concerns/RecyclesToBin  # 回收站 Trait
│   ├── Services/                   # 业务服务（2FA、回收站、验证码等）
│   ├── Support/                    # ConfigCenter、AdminPermission 等
│   └── helpers.php                 # config_center() 助手函数
├── bootstrap/app.php               # 路由与中间件注册
├── config/
│   ├── admin.php                   # 后台主题、品牌、侧栏等
│   └── upload.php                  # 上传场景配置
├── database/
│   ├── migrations/
│   └── seeders/Admin/              # 菜单、权限、演示数据
├── docs/                           # 回收站、菜单 Seeder 等专题文档
├── public/
│   ├── assets/admin-static/        # Vue、Element Plus、Jodit、ECharts 等
│   └── js/                         # neo-table、neo-upload、neo-richtext 等
├── resources/views/admin/          # Blade 模板
│   ├── layouts/content.blade.php   # 内容页布局（iframe 内页）
│   ├── shell.blade.php             # 后台外壳（侧栏 + iframe）
│   └── content/                    # 各业务页面
├── routes/
│   ├── admin.php                   # ★ 所有后台路由（唯一入口）
│   └── web.php                     # 非 admin 路由（勿写后台业务）