# Admin Framework 使用说明

一个基于 Vue2 的通用后台管理系统框架，包含完整的系统功能、登录、路由管理、布局等核心功能。

## 📦 框架特性

### ✨ 核心功能
- ✅ **简化的 API** - 只需调用 `createApp()` 即可完成所有初始化
- ✅ **模块化设计** - 组件、路由、状态管理等功能按模块组织
- ✅ **完整的系统管理页面** - 用户、角色、菜单、日志等管理
- ✅ **登录和权限管理** - 完整的登录流程和权限控制
- ✅ **动态路由管理** - 基于权限菜单的动态路由生成
- ✅ **Vuex 状态管理** - 用户、应用状态管理
- ✅ **全局组件库** - Tables、Editor、Upload、TreeGrid、FieldRenderer 等
- ✅ **工具库** - HTTP、日期、Token、Cookie 等工具
- ✅ **内置样式** - base.less、animate.css、iconfont 等
- ✅ **响应式布局** - 支持移动端适配

### 🎯 内置页面组件
- **主页组件** (`HomePage`) - 欢迎页面，显示系统标题
- **系统管理页面** (`SysUser`, `SysRole`, `SysLog`, `SysParamSetup`)
- **高级管理页面** (`SysMenu`, `SysControl`, `SysTitle`)
- **登录页面** (`LoginPage`)
- **错误页面** (`Page401`, `Page404`, `Page500`)

### 🛠️ 内置工具
- **HTTP 工具** (`http`) - 封装了 axios，支持拦截器
- **UI 工具** (`uiTool`) - 删除确认、树形转换、响应式设置
- **功能工具** (`funTool`) - 文件下载等
- **通用工具** (`tools`) - 日期格式化、UUID 生成、Cookie 操作

## 🚀 快速开始

### 方式一：使用 Demo 项目（推荐）

我们提供了一个完整的 demo 项目，可以直接运行查看效果：

```bash
# 1. 进入 demo 项目
cd demo

# 2. 安装依赖
npm install

# 3. 启动开发服务器
npm run dev
```

浏览器会自动打开 `http://localhost:8080`，查看：
- `/login` - 登录页面
- `/home` - 主页
- `/system/user` - 用户管理
- `/ball/games` - 业务示例页面

### 方式二：构建框架

```bash
# 1. 安装依赖
npm install

# 2. 构建框架
npm run build

# 3. 产物在 dist/admin-framework.js
```

## 🎯 极简使用方式

### 只需 3 步即可完成集成！

#### 1. 引入框架
```javascript
import AdminFramework from './admin-framework.js'
```

#### 2. 创建应用
```javascript
const app = AdminFramework.createApp({
  title: '我的管理系统',
  apiUrl: 'http://localhost:9098/admin_api/',
  componentMap: {
    'business/product': ProductComponent,
    'business/order': OrderComponent
  }
})
```

#### 3. 挂载应用
```javascript
app.$mount('#app')
```

**就这么简单！** 框架会自动完成所有初始化工作。

## 📖 完整使用指南

### 1. 项目结构准备

```
your-project/
├── src/
│   ├── config/
│   │   └── index.js          # 配置文件
│   ├── libs/
│   │   └── admin-framework.js # 框架文件
│   ├── views/
│   │   └── business/         # 业务页面
│   ├── api/
│   │   └── business/         # 业务 API
│   ├── App.vue
│   └── main.js
├── package.json
└── webpack.config.js
```

### 2. 安装依赖

```bash
npm install vue vue-router vuex view-design axios dayjs js-cookie vuex-persistedstate
```

### 3. 创建配置文件

在 `src/config/index.js` 中：

```javascript
module.exports = {
  title: '你的系统名称',
  homeName: '首页',
  apiUrl: 'http://localhost:9090/admin_api/',
  uploadUrl: 'http://localhost:9090/admin_api/upload',
  cookieExpires: 7,
  uploadMaxLimitSize: 10,
  oss: {
    region: 'oss-cn-shanghai',
    accessKeyId: 'your-key',
    accessKeySecret: 'your-secret',
    bucket: 'your-bucket',
    url: 'http://your-bucket.oss-cn-shanghai.aliyuncs.com',
    basePath: 'your-path/'
  }
}
```

### 4. 创建 main.js（新版本 - 推荐）

```javascript
import AdminFramework from './libs/admin-framework.js'

// 导入业务组件（根据权限菜单接口的 component 字段）
import GamesComponent from './views/ball/games.vue'
import PayOrdersComponent from './views/order/pay_orders.vue'

// 🎉 只需一行代码！框架自动完成所有初始化
const app = AdminFramework.createApp({
  title: '我的管理系统',
  apiUrl: 'http://localhost:9098/admin_api/',
  componentMap: {
    'ball/games': GamesComponent,
    'order/pay_orders': PayOrdersComponent
    // 添加更多业务组件...
  },
  onReady() {
    console.log('应用已启动!')
    // 应用启动完成后的回调
  }
})

// 挂载应用
app.$mount('#app')
```


### 5. 创建 App.vue

```vue
<template>
  <div id="app">
    <router-view/>
  </div>
</template>

<script>
export default {
  name: 'App'
}
</script>
```

## 🔧 API 使用指南

### 框架实例方法

#### createApp(config) - 推荐使用
创建应用实例（新版本 API）

```javascript
const app = AdminFramework.createApp({
  title: '我的管理系统',           // 应用标题（必需）
  apiUrl: 'http://localhost:9098/admin_api/', // API 基础地址（必需）
  uploadUrl: 'http://localhost:9098/admin_api/upload', // 上传地址（可选，默认为 apiUrl + 'upload'）
  componentMap: {                // 业务组件映射（可选）
    'business/product': ProductComponent,
    'business/order': OrderComponent
  },
  onReady() {                    // 应用启动完成回调（可选）
    console.log('应用已启动!')
  }
})
```
### 工具库使用

#### HTTP 工具
```javascript
// 在组件中使用
export default {
  async mounted() {
    // GET 请求
    const res = await this.$http.get('/api/users', { page: 1 })
    
    // POST 请求
    const result = await this.$http.post('/api/users', { name: 'test' })
    
    // 文件导出
    await this.$http.fileExport('/api/export', { type: 'excel' })
  }
}

// 在非 Vue 组件中使用
import AdminFramework from './libs/admin-framework.js'
const res = await AdminFramework.http.get('/api/users')
```

#### UI 工具
```javascript
// 在组件中使用
export default {
  methods: {
    handleDelete() {
      // 删除确认
      this.$uiTool.delConfirm(() => {
        // 执行删除逻辑
      })
      
      // 设置响应式字体
      this.$uiTool.setRem()
      
      // 树形转换
      const treeData = this.$uiTool.transformTree(flatData)
    }
  }
}
```

#### 功能工具
```javascript
// 在组件中使用
export default {
  methods: {
    downloadFile() {
      // 文件下载
      this.$funTool.downloadFile(response, 'filename.csv')
    }
  }
}
```

#### 通用工具
```javascript
// 在组件中使用
export default {
  methods: {
    formatDate() {
      // 日期格式化
      return this.$tools.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')
    },
    
    generateId() {
      // UUID 生成
      return this.$tools.generateUUID()
    },
    
    setCookie() {
      // Cookie 操作
      this.$tools.setCookie('name', 'value')
      const value = this.$tools.getCookie('name')
    }
  }
}
```

### Store 模块使用

#### user 模块
```javascript
// 登录
await this.$store.dispatch('user/handleLogin', {
  userFrom: { username, password },
  Main: AdminFramework.Main,
  ParentView: AdminFramework.ParentView,
  Page404: AdminFramework.Page404
})

// 登出
this.$store.dispatch('user/handleLogOut')

// 设置权限菜单
this.$store.dispatch('user/setAuthorityMenus', {
  Main: AdminFramework.Main,
  ParentView: AdminFramework.ParentView,
  Page404: AdminFramework.Page404
})

// 获取用户信息
const userName = this.$store.getters['user/userName']
const token = this.$store.state.user.token
```

#### app 模块
```javascript
// 设置面包屑
this.$store.commit('app/setBreadCrumb', route)

// 获取系统标题
this.$store.dispatch('app/getSysTitle', {
  defaultTitle: '系统名称',
  defaultLogo: '/logo.png'
})

// 获取系统配置
const sysFormModel = this.$store.getters['app/sysFormModel']
```

## 🗂️ 组件映射配置

### 业务组件映射

当后端权限菜单接口返回组件路径时，需要配置映射表：

```javascript
// 1. 导入业务组件
import GamesComponent from './views/ball/games.vue'
import PayOrdersComponent from './views/order/pay_orders.vue'

// 2. 配置映射
const componentMap = {
  'ball/games': GamesComponent,
  'ball/games.vue': GamesComponent,  // 支持带 .vue 后缀
  'order/pay_orders': PayOrdersComponent,
  'order/pay_orders.vue': PayOrdersComponent
}

// 3. 在 Vue.use 时传入
Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  componentMap  // 传入组件映射表
})
```

### 框架已自动映射的系统组件

以下组件**无需配置**，框架已自动映射：
- ✅ `home/index` - 主页
- ✅ `system/sys_user` - 用户管理
- ✅ `system/sys_role` - 角色管理
- ✅ `system/sys_log` - 日志管理
- ✅ `system/sys_param_setup` - 参数设置
- ✅ `system/sys_menu` - 菜单管理
- ✅ `system/sys_control` - 控制器管理
- ✅ `system/sys_title` - 系统标题设置

## 🌐 全局访问

### window.framework

框架实例会自动暴露到全局，可以在任何地方访问：

```javascript
// 在非 Vue 组件中使用
const http = window.framework.http
const uiTool = window.framework.uiTool
const config = window.framework.config

// HTTP 请求
const res = await window.framework.http.get('/api/users')

// UI 工具
window.framework.uiTool.delConfirm(() => {
  // 删除逻辑
})
```

### Vue 原型方法

在 Vue 组件中可以直接使用：

```javascript
export default {
  methods: {
    async loadData() {
      // 直接使用 this.$xxx
      const res = await this.$http.get('/api/users')
      this.$uiTool.delConfirm(() => {})
      this.$tools.formatDate(new Date())
      this.$funTool.downloadFile(response, 'file.csv')
    }
  }
}
```

## 📝 业务开发示例

### 创建业务页面

```vue
<!-- src/views/business/product.vue -->
<template>
  <div>
    <h1>产品管理</h1>
    <Button @click="loadData">加载数据</Button>
    <Tables :columns="columns" :data="list" />
  </div>
</template>

<script>
export default {
  data() {
    return {
      list: [],
      columns: [
        { title: 'ID', key: 'id' },
        { title: '名称', key: 'name' },
        { title: '价格', key: 'price' }
      ]
    }
  },
  async mounted() {
    await this.loadData()
  },
  methods: {
    async loadData() {
      // 使用框架提供的 http 工具
      const res = await this.$http.get('/product/list', { page: 1 })
      this.list = res.data
    },
    
    async handleDelete(id) {
      // 使用框架提供的 UI 工具
      this.$uiTool.delConfirm(async () => {
        await this.$http.post('/product/delete', { id })
        this.$Message.success('删除成功')
        await this.loadData()
      })
    }
  }
}
</script>
```

### 创建业务 API

```javascript
// src/api/business/productServer.js
// 注意：不需要 import http，直接使用 http

class ProductServer {
  async getList(params) {
    return await http.get('/product/list', params)
  }
  
  async save(data) {
    return await http.post('/product/save', data)
  }
  
  async delete(id) {
    return await http.post('/product/delete', { id })
  }
  
  async exportCsv(params) {
    return await http.fileExport('/product/export', params)
  }
}

export default new ProductServer()
```

## ❓ 常见问题

### Q1: 打包后文件太大怎么办？

A: 框架已经将 Vue、VueRouter、Vuex、ViewUI、Axios 设置为外部依赖，不会打包进去。确保在项目中单独安装这些依赖。

### Q2: 如何只使用部分功能？

A: 可以按需导入：
```javascript
import { http, uiTool, tools } from './libs/admin-framework.js'
```

### Q3: 权限菜单中的业务页面显示 404 怎么办？

A: 需要配置组件映射表：
```javascript
Vue.use(AdminFramework, {
  // ... 其他配置
  componentMap: {
    'ball/games': GamesComponent,
    'order/pay_orders': PayOrdersComponent
  }
})
```

### Q4: 如何自定义配置？

A: 修改 `config/index.js` 文件：
```javascript
module.exports = {
  title: '你的系统名称',
  apiUrl: 'http://your-api-url/',
  // ... 其他配置
}
```

### Q5: 如何使用登录功能？

A: 在组件中：
```javascript
export default {
  methods: {
    async login() {
      await this.$store.dispatch('user/handleLogin', {
        userFrom: { username: 'admin', password: '123456' },
        Main: AdminFramework.Main,
        ParentView: AdminFramework.ParentView,
        Page404: AdminFramework.Page404
      })
      this.$router.push({ name: 'home' })
    }
  }
}
```

### Q6: 需要单独引入样式文件吗？

A: **不需要！** 框架已内置所有样式：
- ✅ `base.less` - 基础样式
- ✅ `animate.css` - 动画样式
- ✅ `ivewExpand.less` - ViewUI 扩展样式
- ✅ `iconfont.css` - 字体图标样式

只需引入框架即可：
```javascript
import AdminFramework from './libs/admin-framework.js'
Vue.use(AdminFramework, { ... })
```

## 📦 技术栈

- Vue 2.6+
- Vue Router 3.x
- Vuex 3.x
- View Design (iView) 4.x
- Axios
- Less
- Webpack 5

## 📄 许可证

MIT License

## 👨‍💻 作者

light

---

**祝开发愉快！** 🎉

如有问题，请查看 Demo 项目示例或联系开发团队。