1

2025-11-19 22:37:07 +08:00
parent ce7916c097
commit ff2d6004b6
4 changed files with 8 additions and 265 deletions
--- a/_doc/使用说明.md
+++ b/_doc/使用说明.md
@@ -0,0 +1,621 @@
+# 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`) - 删除确认、树形转换、响应式设置、文件下载
+- **通用工具** (`tools`) - 日期格式化、UUID 生成、Cookie 操作、深拷贝等
+- **文件下载** - 支持 CSV 等格式的文件下载，自动处理换行符
+
+## 🚀 快速开始
+
+### 方式一：使用 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.$uiTool.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.$uiTool.downloadFile(response, 'file.csv')
+    }
+  }
+}
+```
+
+## 📁 文件下载功能
+
+### 使用 downloadFile 方法
+
+框架提供了便捷的文件下载功能，支持 CSV 等格式：
+
+```javascript
+// 在 Vue 组件中使用
+export default {
+  methods: {
+    // 导出数据
+    exportData() {
+      // 调用 API 获取数据
+      this.$http.fileExport('/api/export', params).then(res => {
+        // 使用 downloadFile 下载
+        this.$uiTool.downloadFile(res, '数据导出.csv')
+        this.$Message.success('导出成功！')
+      }).catch(error => {
+        this.$Message.error('导出失败：' + error.message)
+      })
+    }
+  }
+}
+```
+
+### 支持的数据格式
+
+- **CSV 格式**：自动处理换行符，保持表格格式
+- **Blob 对象**：支持二进制文件下载
+- **文本数据**：支持纯文本文件下载
+
+### 自动处理特性
+
+- ✅ **换行符保持**：CSV 文件的换行符会被正确保持
+- ✅ **文件名处理**：自动清理文件名中的特殊字符
+- ✅ **浏览器兼容**：支持所有现代浏览器
+- ✅ **内存管理**：自动清理临时 URL 对象
+
+## 📝 业务开发示例
+
+### 创建业务页面
+
+```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 项目示例或联系开发团队。