madong-code / madong-aura

# MaDong-Aura
> English → README.en.md
---
**MaDong-Aura** 是 MaDong Admin 后端框架的配套前端 UI，同时也是一个可独立运行的后台管理模版。业务层结构、请求契约、插件机制与参考项目 madong-single 完全一致，仅取 art-design-pro 的框体布局，支持双 UI 维护与插件无缝复用。
- 🏠 **项目仓库：** 
### ✨ 特性
- **🔌 插件系统** — 插件目录（`src/plugin/`）支持通过后端菜单动态注册，或在开发环境通过 `routes/index.ts` 静态声明，业务组件、API、Mock 均可按插件独立打包
- **🎯 独立模版** — 内置 Nitro Mock 服务器（端口 5320），接口契约与真实后端完全对齐，无需启动后端即可完整运行和学习
- **🧩 CRUD 组件** — 开箱即用的列表/表单/弹窗/抽屉组件，支持 vxe-table 高级功能（虚拟滚动、单元格编辑、树形表格等）
- **🎨 设计器** — 集成 VForm3 表单设计器（UMD）和 LogicFlow 流程设计器（ESM），开箱即用
- **🌐 多语言** — 完整的 zh-CN / en-US 双语支持，插件 i18n 按目录自动加载
- **🔐 权限控制** — 前端/后端两种权限模式，支持角色权限码、按钮级鉴权（v-access / v-roles 指令）
- **📦 双模式构建** — 支持独立域名（`pnpm build`）和同域子路径（`pnpm build:integrated`）两种部署方式
### 🛠 技术栈
| 类别 | 技术 |
| --- | --- |
| 框架 | Vue 3.5 · TypeScript · Vite 7 |
| 状态管理 | Pinia 3 |
| UI | Element Plus 2.13（按需）· Tailwind CSS v4 · ReKa UI |
| 表格 | vxe-table 4 |
| 图表 | ECharts 6 |
| 富文本 | Tiptap 3 · WangEditor 5 |
| 流程图 | LogicFlow |
| 表单设计 | VForm3（UMD）|
| 国际化 | Vue I18n 11 |
| Mock | Nitro 2（API 契约对齐 adminapi）|
| 路由 | Vue Router 4 |
| 网络 | Axios |
### 🚀 快速开始
**环境要求：** Node.js >= 22 · pnpm >= 10
 [code] 
**默认登录：** `admin / 123456`（用户名参数为 `user_name`）
手动 Mock 命令：
 [code] 
### 📦 构建与部署
| 模式 | 命令 | base | API | 场景 |
| --- | --- | --- | --- | --- |
| 开发 | `pnpm dev` | `/` | Mock `:5320` | 本地开发 · 学习 |
| 生产（独立域名） | `pnpm build` | `/` | `/adminapi`（网关转发） | 独立部署 |
| 生产（同域） | `pnpm build:integrated` | `/admin/` | 相对 `/adminapi` | 嵌入 PHP 项目子路径 |
**切换真实后端：** 将 `.env.development` 中的 `VITE_NITRO_MOCK` 设为 `false`，代理目标指向真实后端（默认 `http://127.0.0.1:8500`），无需修改前端代码。
### 📂 目录结构
 [code] 
### 🔌 插件系统
插件放置于 `src/plugin/ /` 目录，结构如下：
 [code] 
**component 路径解析支持以下格式（按优先级匹配）：**
| 格式 | 示例 | 解析结果 |
| --- | --- | --- |
| 完整标准路径 | `plugin/demo/views/crud/basic` | `src/plugin/demo/views/crud/basic/index.vue` |
| 冒号简写 | `demo:crud/basic` | `src/plugin/demo/views/crud/basic/index.vue` |
| `{module}/views/` 形态 | `demo/views/crud/basic` | `src/plugin/demo/views/crud/basic/index.vue` |
| 最简写法 + `meta.module` | `crud/basic`（module=`demo`） | `src/plugin/demo/views/crud/basic/index.vue` |
| BasicLayout | `BasicLayout` | 框架内置布局（根节点专用，**不得带 `meta.module`**） |
**生产环境：** 后端安装插件时自动写入 `sys_menu` 并注入 `meta.module = ' '`，前端从 `GET /system/auth/user-menus` 获取菜单后由插件扫描器动态加载组件。
**开发环境：** 插件可在 `routes/index.ts` 中静态声明路由（见 demo 插件），无需后端配置即可预览。
**插件市场 API：** `src/api/app/plugin/market/` 提供模块市场列表、安装、购买等接口类型。
### 🧪 Mock 开发
本项目使用 Nitro 提供完整的 Mock 服务，接口契约与 MaDong Admin 真实后端（adminapi）完全对齐，切换后端时无需修改前端代码。
详细约定与开发指南请参考 tooling/mock/README.md。
核心要点：
- **响应信封：** `{ code: 0, msg: 'ok', data: ... }`，列表接口返回 `{ items, total }`
- **查询参数：** `EQ_xxx` 精确匹配、`LIKE_xxx` 模糊匹配、`keyword` 多字段搜索
- **新增 CRUD：** 在 `handlers/` 中使用 `crudRoutes()` 工厂，自动获得完整增删改查
- **菜单种子：** 菜单结构仅修改 `menu-seed.json`，权限码定义在 `menu-data.ts`
### ⚙️ 环境变量
关键配置在 .env 中定义：
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `VITE_PORT` | `5500` | 前端开发端口 |
| `VITE_BASE_URL` | `/` | 部署基础路径（同域部署需改为 `/admin/`）|
| `VITE_ACCESS_MODE` | `backend` | 权限模式（`frontend` / `