# Admin Framework 完整使用文档

通用后台管理系统框架 - 包含系统功能、登录、路由管理、布局等核心功能

---

## 📑 目录

- [特性](#特性)
- [快速开始](#快速开始)
- [完整使用示例](#完整使用示例)
- [API 文档](#api-文档)
- [系统页面和 API](#系统页面和-api)
- [开发指南](#开发指南)
- [常见问题](#常见问题)

---

## ✨ 特性

✅ **系统管理页面**（sys 开头的所有页面和功能）  
✅ **系统 API**（system 和 system_high 所有 API）  
✅ **全局组件**（Tables、Editor、Upload 等）  
✅ **布局组件**（Main、ParentView）  
✅ **登录和错误页面**（Login、401、404、500）  
✅ **用户登录和权限管理**  
✅ **动态路由管理**  
✅ **工具库**（HTTP、日期、Token、Cookie 等）  
✅ **Vuex 状态管理**  
✅ **路由守卫**  

---

## 🚀 快速开始

### 一、打包框架

#### 1. 进入框架目录
```bash
cd admin-framework
```

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

#### 3. 打包
```bash
npm run build
```

打包完成后，会在 `dist` 目录生成 `admin-framework.js` 文件（约 200-300KB）。

### 二、在新项目中使用

#### 方式一：直接复制打包文件（推荐）

1. 将 `dist/admin-framework.js` 复制到新项目的 `src/libs/` 目录

2. 在 `main.js` 中引入：
```javascript
import AdminFramework from './libs/admin-framework.js'
```

#### 方式二：作为 npm 包使用

1. 在 `admin-framework` 目录执行：
```bash
npm link
```

2. 在新项目目录执行：
```bash
npm link admin-framework
```

3. 在 `main.js` 中引入：
```javascript
import AdminFramework from 'admin-framework'
```

### 三、最小化使用示例

#### 1. 框架已包含的内容

**无需从原项目复制**：

✅ **已包含**：
- 所有系统页面（system、system_high）
- 所有系统 API（system、system_high）
- 所有全局组件（Tables、Editor、Upload 等）
- 布局组件（Main、ParentView）
- 登录和错误页面
- 工具库和 Store 模块

**只需准备**：
```
├── config/index.js           # 配置文件（根据你的项目修改）
└── App.vue                   # 应用根组件
```

#### 2. 创建 main.js（只需 10 行代码！）22222222222333

```javascript
import Vue from 'vue'
import VueRouter from 'vue-router'
import Vuex from 'vuex'
import ViewUI from 'view-design'
import createPersistedState from 'vuex-persistedstate'
import AdminFramework from './libs/admin-framework.js'
import App from './App.vue'
import config from './config'

// 🎉 只需这一行！框架自动完成所有初始化
Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState
})

// 创建 Vue 实例
window.rootVue = new Vue({
  el: '#app',
  router: AdminFramework.router,  // 使用框架自动创建的 router
  store: AdminFramework.store,    // 使用框架自动创建的 store
  render: h => h(App),
  mounted() {
    AdminFramework.uiTool.setRem()
    this.$store.dispatch('user/setAuthorityMenus', {
      Main: AdminFramework.Main,
      ParentView: AdminFramework.ParentView,
      Page404: AdminFramework.Page404
    })
  }
})

// 响应式适配
window.addEventListener('load', AdminFramework.uiTool.setRem)
window.addEventListener('resize', AdminFramework.uiTool.setRem)
```

**就这么简单！** 框架会自动：
- ✅ 注册 ViewUI
- ✅ 创建 Store（包含用户、应用模块）
- ✅ 创建 Router（包含所有基础路由和动态路由）
- ✅ 初始化 HTTP
- ✅ 设置 API 服务
- ✅ 注册全局组件
- ✅ 配置路由守卫

#### 3. 安装依赖

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

#### 4. 运行项目

```bash
npm run dev
```

---

## 📖 完整使用示例

### 步骤 1: 准备项目结构

```
your-project/
├── src/
│   ├── config/
│   │   └── index.js
│   ├── libs/
│   │   └── admin-framework.js  ← 框架文件
│   ├── App.vue
│   └── main.js
├── package.json
└── webpack.config.js
```

### 步骤 2: 创建配置文件

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

```javascript
module.exports = {
  title: '你的系统名称',
  homeName: '首页',
  apiUrl: 'http://localhost:9090/admin_api/',
  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/'
  }
}
```

### 步骤 3: 创建 App.vue

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

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

### 步骤 4: 开发业务功能

#### 创建业务页面

```vue
<!-- src/view/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' }
      ]
    }
  },
  async mounted() {
    await this.loadData()
  },
  methods: {
    async loadData() {
      // 使用框架提供的 http 工具
      const res = await this.$http.get('/product/list', { page: 1 })
      this.list = res.data
    }
  }
}
</script>
```

#### 创建业务 API

```javascript
// src/api/business/productServer.js
import http from '@/utils/admin-framework.js'

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

export default new ProductServer()
```

---

## 📚 API 文档

### 框架实例方法

#### install(Vue, options)
安装 Vue 插件

```javascript
Vue.use(AdminFramework, {
  config: yourConfig,
  ViewUI: ViewUI,
  VueRouter: VueRouter,
  Vuex: Vuex,
  createPersistedState: createPersistedState
})
```

**参数说明：**
- `config`: 项目配置对象
- `ViewUI`: ViewUI 实例
- `VueRouter`: VueRouter 类
- `Vuex`: Vuex 类
- `createPersistedState`: vuex-persistedstate 插件

#### initHttp(config, store)
初始化 HTTP 配置

```javascript
AdminFramework.initHttp({
  apiUrl: 'http://localhost:9090/admin_api/',
  timeout: 300000
}, store)
```

#### setUserServer(userServer)
设置用户服务实例

```javascript
AdminFramework.setUserServer(userServer)
```

#### setParamSetupServer(paramSetupServer)
设置参数设置服务实例

```javascript
AdminFramework.setParamSetupServer(paramSetupServer)
```

#### createRouter(Router, components, customRoutes, ViewUI, homeName)
创建路由实例

```javascript
const router = AdminFramework.createRouter(
  VueRouter,
  { LoginPage, Page401, Page404, Page500 },
  customRoutes,  // 自定义业务路由
  ViewUI,
  'home'
)
```

#### createStore(Vuex, customModules, createPersistedState)
创建 Store 实例

```javascript
const store = AdminFramework.createStore(
  Vuex,
  { business: businessModule },  // 自定义业务模块
  createPersistedState
)
```

#### getRoutes(components)
获取动态路由

```javascript
const mainRoutes = AdminFramework.getRoutes({
  Main,
  ParentView,
  Page404
})
```

#### registerComponents(Vue, components)
注册全局组件

```javascript
AdminFramework.registerComponents(Vue, {
  'my-component': MyComponent
})
```

### 工具库

#### http - HTTP 请求工具

```javascript
// GET 请求
AdminFramework.http.get('/api/users', { page: 1 })

// POST 请求
AdminFramework.http.post('/api/users', { name: 'test' })

// 文件导出
AdminFramework.http.fileExport('/api/export', { type: 'excel' })
```

**在组件中使用：**
```javascript
export default {
  async mounted() {
    const res = await this.$http.get('/api/users')
  }
}
```

#### util - 工具函数

```javascript
// Token 管理
AdminFramework.util.setToken(token)
AdminFramework.util.getToken()

// 路由工具
AdminFramework.util.getBreadCrumbList(route, homeRoute)
AdminFramework.util.getHomeRoute(routes, 'home')
```

**在组件中使用：**
```javascript
export default {
  methods: {
    getToken() {
      return this.$util.getToken()
    }
  }
}
```

#### tools - 功能工具

```javascript
// 日期格式化
AdminFramework.tools.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss')

// UUID 生成
AdminFramework.tools.generateUUID()

// Cookie 操作
AdminFramework.tools.setCookie('name', 'value')
AdminFramework.tools.getCookie('name')
```

**在组件中使用：**
```javascript
export default {
  methods: {
    formatDate() {
      return this.$tools.formatDate(new Date(), 'YYYY-MM-DD')
    }
  }
}
```

#### uiTool - UI 工具

```javascript
// 设置响应式字体
AdminFramework.uiTool.setRem()

// 删除确认
AdminFramework.uiTool.delConfirm(() => {
  // 删除逻辑
})

// 树形转换
AdminFramework.uiTool.transformTree(treeData)
```

**在组件中使用：**
```javascript
export default {
  methods: {
    handleDelete() {
      this.$uiTool.delConfirm(() => {
        // 执行删除
      })
    }
  }
}
```

### Store 模块

#### user 模块

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

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

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

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

#### app 模块

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

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

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

---

## 🗂️ 系统页面和 API

### 已包含的系统页面

框架已内置所有系统管理页面，可直接从框架导入使用：

#### system 目录页面
```javascript
import {
  SysLog,          // 系统日志管理
  SysParamSetup,   // 参数设置
  SysRole,         // 角色管理
  SysUser,         // 用户管理
  WchCities,       // 城市管理
  WchProfessions   // 职业管理
} from 'admin-framework'
```

#### system_high 目录页面
```javascript
import {
  SysControl,      // 控制器管理
  SysMenu,         // 菜单管理
  SysTitle         // 系统标题设置
} from 'admin-framework'
```

#### 在路由中使用
```javascript
import { SysUser, SysRole, SysMenu } from 'admin-framework'

const routes = [
  {
    path: '/system/user',
    name: 'sys_user',
    component: SysUser
  },
  {
    path: '/system/role',
    name: 'sys_role',
    component: SysRole
  },
  {
    path: '/system_high/menu',
    name: 'sys_menu',
    component: SysMenu
  }
]
```

### 已包含的系统 API

#### system API
```javascript
import { systemApi } from 'admin-framework'

// 使用示例
const {
  userServer,
  roleServer,
  sysLogServe,
  fileServe,
  // ... 其他 API
} = systemApi

// 调用 API
const users = await userServer.getList({ page: 1 })
const roles = await roleServer.getList()
```

#### system_high API
```javascript
import { systemHighApi } from 'admin-framework'

// 使用示例
const {
  menuServer,
  paramSetupServer,
  modelServer,
  // ... 其他 API
} = systemHighApi

// 调用 API
const menus = await menuServer.getTree()
const params = await paramSetupServer.getOne('sys_title')
```

### 全局组件

框架已包含所有全局组件，打包后会自动注册：

```vue
<template>
  <div>
    <Tables :columns="columns" :data="data" />
    <Editor v-model="content" />
    <UploadSingle v-model="fileUrl" />
    <TreeGrid :data="treeData" />
  </div>
</template>
```

---

## 🛠️ 开发指南

### 开发模式

```bash
npm run dev
```

### 生产构建

```bash
npm run build
```

### 目录结构

```
admin-framework/
├── src/
│   ├── utils/              # 工具库
│   │   ├── tools.js      # 功能工具
│   │   ├── http.js         # HTTP 工具
│   │   ├── tools.js        # 通用工具
│   │   ├── uiTool.js       # UI 工具
│   │   └── util.js         # 工具函数
│   ├── store/              # Vuex 模块
│   │   ├── user.js         # 用户模块
│   │   ├── app.js          # 应用模块
│   │   └── index.js        # 导出
│   ├── router/             # 路由配置
│   │   └── index.js        # 路由配置
│   └── index.js            # 入口文件
├── dist/                   # 打包输出
│   └── admin-framework.js  # 打包后的文件
├── webpack.config.js       # Webpack 配置
├── package.json            # 依赖配置
└── README.md              # 说明文档
```

### 依赖说明

#### peerDependencies（需要在使用项目中安装）

- vue: ^2.6.0
- vue-router: ^3.0.0
- vuex: ^3.0.0
- view-design: ^4.0.0
- axios: ^0.21.0

#### dependencies

- dayjs: ^1.10.0
- js-cookie: ^2.2.1
- vuex-persistedstate: ^4.0.0

---

## ❓ 常见问题

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

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

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

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

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

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

### Q4: 如何添加业务路由？

A: 在创建路由时传入：
```javascript
const businessRoutes = [
  {
    path: '/business/product',
    component: () => import('@/view/business/product.vue')
  }
]

const router = AdminFramework.createRouter(
  VueRouter,
  { LoginPage, Page401, Page404, Page500 },
  businessRoutes,  // ← 传入业务路由
  ViewUI
)
```

### Q5: 如何自定义路由守卫？

A: 你可以在创建路由后添加自己的守卫：

```javascript
const router = AdminFramework.createRouter(...)

router.beforeEach((to, from, next) => {
  // 你的自定义逻辑
  next()
})
```

### Q6: 如何扩展 Store 模块？

A: 在创建 Store 时传入自定义模块：

```javascript
const store = AdminFramework.createStore(Vuex, {
  myModule: {
    namespaced: true,
    state: { ... },
    mutations: { ... },
    actions: { ... }
  }
})
```

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

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' })
    }
  }
}
```

### Q8: 需要复制哪些文件到新项目？

A: **框架已包含所有系统功能，只需准备：**
- `config/index.js` - 配置文件
- `App.vue` - 应用根组件
- `main.js` - 入口文件

其他所有系统页面、API、组件都已在框架中，无需复制！

### Q9: `this.$store.dispatch` 报错怎么办？

A: **常见原因和解决方案**：

**1. Store 未正确挂载**

确保在创建 Vue 实例时使用了框架的 store：
```javascript
new Vue({
  el: '#app',
  router: AdminFramework.router,
  store: AdminFramework.store,  // ✅ 必须挂载 store
  render: h => h(App)
})
```

**2. 命名空间路径错误**

框架的 store 模块都使用了 `namespaced: true`，必须带上模块名：
```javascript
// ❌ 错误 - 缺少命名空间
this.$store.dispatch('setAuthorityMenus', data)

// ✅ 正确 - 带上模块名 user/
this.$store.dispatch('user/setAuthorityMenus', data)

// ✅ 正确 - app 模块
this.$store.dispatch('app/getSysTitle', { defaultTitle: '系统' })
```

**3. Store 在 setup/install 时未创建**

确保在 Vue.use() 时传入了 Vuex：
```javascript
// ✅ 正确 - 框架会自动创建 store
Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,  // ✅ 必须传入 Vuex
  createPersistedState
})
```

**4. 可用的 Store Actions**

**user 模块**（需要加 `user/` 前缀）：
- `user/setAuthorityMenus` - 设置权限菜单
- `user/handleLogin` - 处理登录
- `user/handleLogOut` - 处理登出

**app 模块**（需要加 `app/` 前缀）：
- `app/getSysTitle` - 获取系统标题和 Logo

**完整示例**：
```javascript
export default {
  mounted() {
    // 设置权限菜单
    this.$store.dispatch('user/setAuthorityMenus', {
      Main: AdminFramework.Main,
      ParentView: AdminFramework.ParentView,
      Page404: AdminFramework.Page404
    })
    
    // 获取系统标题
    this.$store.dispatch('app/getSysTitle', {
      defaultTitle: '智能代码平台',
      defaultLogo: ''
    })
  },
  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' })
    },
    logout() {
      // 处理登出
      this.$store.dispatch('user/handleLogOut')
    }
  }
}
```

---

## 📦 完整的项目结构示例

```
your-project/
├── src/
│   ├── api/
│   │   └── business/           # 你的业务 API
│   ├── assets/
│   │   ├── css/                # 样式文件
│   │   └── images/             # 图片
│   ├── config/
│   │   └── index.js            # 配置文件
│   ├── libs/
│   │   └── admin-framework.js  # 框架文件
│   ├── view/
│   │   └── business/           # 你的业务页面
│   ├── App.vue
│   └── main.js
├── package.json
└── webpack.config.js
```

---

## 📝 版本信息

**当前版本**: 1.0.0

**更新日志**:
- v1.0.0 - 初始版本，包含所有核心功能

---

## 📄 许可证

MIT License

---

## 💬 技术支持

如有问题，请查看本文档或联系开发团队。

---

## 🎯 快速参考

### 最小化代码示例（10行）

```javascript
import Vue from 'vue'
import AdminFramework from './libs/admin-framework.js'
import App from './App.vue'
import config from './config'

Vue.use(AdminFramework, { config, ViewUI, VueRouter, Vuex, createPersistedState })

new Vue({
  el: '#app',
  router: AdminFramework.router,
  store: AdminFramework.store,
  render: h => h(App)
})
```

### 常用API速查

```javascript
// HTTP请求
this.$http.get(url, params)
this.$http.post(url, data)

// Token操作
this.$util.setToken(token)
this.$util.getToken()

// 日期格式化
this.$tools.formatDate(date, 'YYYY-MM-DD')

// 删除确认
this.$uiTool.delConfirm(() => { /* 删除逻辑 */ })

// 登录
this.$store.dispatch('user/handleLogin', { userFrom, Main, ParentView, Page404 })

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

---

**祝开发愉快！** 🎉