# Admin Framework 完整使用文档

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

---

## 🎯 Demo 项目

📦 **已提供完整的示例项目**：`demo/`

一个开箱即用的完整示例，包含：
- ✅ 框架集成配置
- ✅ 登录页面
- ✅ 主页欢迎页
- ✅ 业务页面示例（产品列表 CRUD）
- ✅ Webpack 配置
- ✅ 详细使用说明

**快速体验**：
```bash
cd demo
npm install
npm run dev
```

详细说明：[demo/README.md](./demo/README.md)

---

## 📑 目录

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

---

## ✨ 特性

✅ **极简 API** - 只需调用 `createApp()` 即可完成所有初始化  
✅ **模块化设计** - 组件、路由、状态管理等功能按模块组织  
✅ **主页组件**（欢迎页面，自动显示系统标题）  
✅ **系统管理页面**（sys 开头的所有页面和功能）  
✅ **系统 API**（system 和 system 所有 API）  
✅ **全局组件**（Tables、Editor、Upload、FieldRenderer、FloatPanel 等）  
✅ **布局组件**（Main、ParentView）  
✅ **文件下载**（支持 CSV 等格式，自动处理换行符）  
✅ **登录和错误页面**（Login、401、404、500）  
✅ **用户登录和权限管理**  
✅ **动态路由管理**  
✅ **工具库**（HTTP、日期、Token、Cookie 等）  
✅ **Vuex 状态管理**  
✅ **路由守卫**  
✅ **内置样式**（base.less、animate.css、ivewExpand.less、iconfont）  

---

## 🚀 快速开始

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

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

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

# 2. 安装依赖
npm install

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

浏览器会自动打开 `http://localhost:8080`，查看：
- `/login` - 登录页面
- `/home` - 主页
- `/business/product` - 业务示例页面

**详细说明**：查看 `demo/README.md`

---

### 🔧 方式二：手动集成到项目

### 一、打包框架

#### 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. 框架已包含的内容

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

✅ **已包含**：
- **主页组件**（HomePage - 欢迎页面，显示系统标题）
- 所有系统页面（system、system）
- 所有系统 API（system、system）
- 所有全局组件（Tables、Editor、Upload、FieldRenderer 等）
- 布局组件（Main、ParentView）
- 登录和错误页面
- 工具库和 Store 模块
- **所有样式文件**（base.less、animate.css、ivewExpand.less）
- **字体图标文件**（iconfont）

**只需准备**：
```
├── App.vue                   # 应用根组件（可选）
```

#### 2. 创建 main.js（新版本 - 只需 8 行代码！）

```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
    // 添加更多业务组件...
  },
  
  HomePage: CustomHomePage,  // 可选：自定义首页组件，覆盖整个首页
  onReady() {
    console.log('应用已启动!')
  }
})

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

#### 2.1 传统方式（兼容旧版本）

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

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

// 🎉 只需这一行！框架自动完成所有初始化
Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  // ✅ 可选：配置业务组件映射（用于权限菜单）
  componentMap: {
    'ball/games': GamesComponent,
    'order/pay_orders': PayOrdersComponent
    // 添加更多业务组件...
  }
})

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

    // 只在已登录时获取系统标题
    const token = this.$store.state.user.token
    if (token) {
      this.$store.dispatch('app/getSysTitle', {
        defaultTitle: 'Demo 管理系统',
        defaultLogo: ''
      })
    } else {
      document.title = 'Demo 管理系统'
    }
  }
})

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

**就这么简单！** 框架会自动：
- ✅ 注册 ViewUI（自动调用 `Vue.use(ViewUI)`）
- ✅ 注册 VueRouter（自动调用 `Vue.use(VueRouter)`）
- ✅ 注册 Vuex（自动调用 `Vue.use(Vuex)`）
- ✅ 创建 Store（包含用户、应用模块）
- ✅ 创建 Router（包含所有基础路由和动态路由）
- ✅ 初始化 HTTP
- ✅ 注册全局组件
- ✅ 配置路由守卫
- ✅ 支持自定义首页组件（通过 HomePage 参数传入）

#### 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，直接使用 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 })
  }
}

export default new ProductServer()
```

---

## 📚 API 文档

### 框架实例方法

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

```javascript
Vue.use(AdminFramework, {
  config: yourConfig,
  ViewUI: ViewUI,
  VueRouter: VueRouter,
  Vuex: Vuex,
  createPersistedState: createPersistedState,
  HomePage: HomePage  // 可选：自定义首页组件
})
```

**参数说明：**
- `config`: 项目配置对象（必需）
- `ViewUI`: ViewUI 实例（必需）
- `VueRouter`: VueRouter 类（必需）
- `Vuex`: Vuex 类（必需）
- `createPersistedState`: vuex-persistedstate 插件（必需）
- `HomePage`: 自定义首页组件（可选，不传则使用框架内置组件）

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

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

#### 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

### 已包含的系统页面

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

#### 主页
```javascript
import {
  HomePage         // 主页欢迎页面（显示系统标题）
} from 'admin-framework'
```

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

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

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

const routes = [
  {
    path: '/home',
    name: 'home',
    component: HomePage  // 框架自动注册，也可手动使用
  },
  {
    path: '/system/user',
    name: 'sys_user',
    component: SysUser
  },
  {
    path: '/system/role',
    name: 'sys_role',
    component: SysRole
  },
  {
    path: '/system/menu',
    name: 'sys_menu',
    component: SysMenu
  },
  {
    path: '/system/log',
    name: 'sys_log',
    component: SysLog
  },
  {
    path: '/system/log_operate',
    name: 'sys_log_operate',
    component: SysLogOperate
  }
]
```

### 已包含的系统 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 API（所有 API 都在 systemApi 中）
```javascript
import { systemApi } from 'admin-framework'

// 使用示例
const {
  userServer,
  roleServer,
  sysLogServe,
  fileServe,
  menuServer,
  paramSetupServer,
  modelServer,
  formServer,
  formFieldServer,
  modelFieldServer,
  tableServer,
  rolePermissionServer,
  sysControlTypeServer,
  sysModuleServer,
  sysAddressServer,
  systemTypeServer,
  plaAccountServer,
  // ... 其他 API
} = systemApi

// 调用 API
const users = await userServer.getList({ page: 1 })
const roles = await roleServer.getList()
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" />
    <FloatPanel ref="floatPanel" title="详情面板" position="right" />
  </div>
</template>
```

#### FloatPanel - 浮动面板组件

`FloatPanel` 是一个浮动在父窗体上的面板组件，类似于抽屉效果，调用方式和 `AsyncModal` 类似。

**基本使用：**

```vue
<template>
  <div>
    <Button @click="showPanel">打开浮动面板</Button>
    
    <FloatPanel
      ref="floatPanel"
      title="详情面板"
      position="right"
      :show-back="true"
      back-text="返回"
      @back="handleBack"
    >
      <div>这里是面板内容</div>
    </FloatPanel>
  </div>
</template>

<script>
export default {
  methods: {
    showPanel() {
      this.$refs.floatPanel.show()
    },
    hidePanel() {
      this.$refs.floatPanel.hide()
    },
    handleBack() {
      console.log('返回按钮被点击')
      this.hidePanel()
    },
    handleSave() {
      console.log('保存')
      this.hidePanel()
    }
  }
}
</script>
```

**调用方式（类似 AsyncModal）：**

```vue
<template>
  <div>
    <Button @click="openPanel">打开面板</Button>
    
    <FloatPanel ref="floatPanel" title="详情" position="right">
      <div>内容</div>
    </FloatPanel>
  </div>
</template>

<script>
export default {
  methods: {
    openPanel() {
      // 通过 ref 调用 show 方法
      this.$refs.floatPanel.show()
    },
    closePanel() {
      // 通过 ref 调用 hide 方法
      this.$refs.floatPanel.hide()
    }
  }
}
</script>
```

**属性说明：**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `title` | String | `''` | 面板标题 |
| `width` | String/Number | `'100%'` | 面板宽度（字符串或数字），默认占满父容器 |
| `height` | String/Number | `'100%'` | 面板高度（字符串或数字），默认占满父容器 |
| `position` | String | `'right'` | 面板位置：`left`、`right`、`top`、`bottom`、`center` |
| `showBack` | Boolean | `true` | 是否显示返回按钮 |
| `showClose` | Boolean | `false` | 是否显示关闭按钮 |
| `backText` | String | `'返回'` | 返回按钮文字 |
| `closeOnClickBackdrop` | Boolean | `false` | 点击遮罩是否关闭 |
| `mask` | Boolean | `false` | 是否显示遮罩（默认不显示） |
| `zIndex` | Number | `1000` | 层级 |

**方法：**

| 方法 | 说明 | 参数 |
|------|------|------|
| `show(callback)` | 显示面板 | `callback`: 可选的回调函数 |
| `hide()` | 隐藏面板 | - |

**事件：**

| 事件 | 说明 | 参数 |
|------|------|------|
| `back` | 点击返回按钮时触发 | - |

**插槽：**

| 插槽 | 说明 |
|------|------|
| `default` | 面板主体内容 |
| `header-right` | 头部右侧内容 |

**位置说明：**

- `left`: 从左侧滑入
- `right`: 从右侧滑入（默认）
- `top`: 从顶部滑入
- `bottom`: 从底部滑入
- `center`: 居中显示，带缩放动画

**特性说明：**

- ✅ 基于父元素定位，不会遮挡菜单
- ✅ 宽度和高度默认 100%，占满父容器
- ✅ 无遮罩背景，完全浮在父页面上
- ✅ 路由切换或组件销毁时自动关闭
- ✅ 支持多种位置和动画效果

---

## 🛠️ 开发指南

### 开发模式

```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: 如何使用文件下载功能？

A: 框架提供了便捷的文件下载方法：

```javascript
// 在 Vue 组件中使用
export default {
  methods: {
    exportData() {
      // 调用 API 获取数据
      this.$http.fileExport('/api/export', params).then(res => {
        // 下载文件（自动处理换行符）
        this.$uiTool.downloadFile(res, '数据导出.csv')
        this.$Message.success('导出成功！')
      }).catch(error => {
        this.$Message.error('导出失败：' + error.message)
      })
    }
  }
}
```

**特性：**
- ✅ 自动处理 CSV 换行符
- ✅ 支持多种文件格式
- ✅ 浏览器兼容性好
- ✅ 自动清理临时 URL 对象

### Q7: 如何扩展 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: 报错 `must call Vue.use(Vuex) before creating a store instance` 怎么办？

A: **这个问题已在框架 v1.0.0+ 中修复！**

如果你使用的是旧版本框架，请重新构建：
```bash
cd admin-framework
npm run build
```

然后将新的 `dist/admin-framework.js` 复制到项目中替换旧文件。

新版本框架会自动调用 `Vue.use(Vuex)` 和 `Vue.use(VueRouter)`，无需手动注册！

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

### Q11: 主页 HomePage 组件说明

A: **框架支持两种方式使用首页组件：使用内置组件或传入自定义组件。**

#### 方式一：使用框架内置的主页组件（默认）

**默认主页组件**：
```vue
<!-- 已内置在框架中 -->
<template>
  <div class="content-view">
    <h1 class="home-title">
      <span class="hy">欢迎登陆， </span>
      {{ sysFormModel.title }}
    </h1>
  </div>
</template>
```

**特性**：
- ✅ 自动从 Vuex Store 获取系统标题（`app/sysFormModel`）
- ✅ 优雅的欢迎页面样式
- ✅ 无需额外配置

**使用方式**：
```javascript
// 不传入 HomePage，框架会使用内置组件
Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState
})
```

#### 方式二：传入自定义首页组件（推荐）

**创建自定义首页组件**：
```vue
<!-- src/views/home/index.vue -->
<template>
  <div class="custom-home">
    <h1>欢迎使用 {{ sysFormModel.title }}</h1>
    <p>这是自定义的首页内容</p>
    <!-- 你的自定义内容 -->
  </div>
</template>

<script>
import { mapGetters } from 'vuex'

export default {
  computed: {
    ...mapGetters({
      sysFormModel: 'app/sysFormModel'
    })
  }
}
</script>

<style scoped>
.custom-home {
  padding: 20px;
}
</style>
```

**传入自定义组件**：
```javascript
import HomePage from './views/home/index.vue'

Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  HomePage  // ✅ 传入自定义首页组件
})
```

#### 首页路由配置

**重要说明**：
- ⚠️ **首页路由完全由后端权限菜单返回**
- ⚠️ 后端必须返回 `path: '/home'` 的菜单配置
- ⚠️ 后端返回的 `component` 字段会映射到实际组件

**后端菜单配置示例**：
```json
{
  "id": 1,
  "name": "首页",
  "path": "/home",
  "component": "home/index",  // 映射到 src/views/home/index.vue
  "parent_id": 0,
  "type": "页面",
  "is_show_menu": 1,
  "icon": "md-home",
  "sort": 1
}
```

**组件映射规则**：
```javascript
// 后端返回: "component": "home/index"
// 实际加载: src/views/home/index.vue

// 后端返回: "component": "system/user"
// 实际加载: src/views/system/user.vue
```

#### 降级方案

如果后端接口失败，框架会使用默认菜单配置（`src/config/menuConfig.js`）：
```javascript
export const defaultMenus = [
  {
    id: 1,
    name: '首页',
    path: '/home',
    component: 'home/index',
    parent_id: 0,
    type: '页面',
    is_show_menu: 1,
    icon: 'md-home',
    sort: 1
  },
  // ... 其他菜单
]
```

#### 直接使用 HomePage 组件

```javascript
// 获取框架内置的 HomePage 组件
import AdminFramework from './libs/admin-framework.js'
const HomePage = AdminFramework.HomePage

// 在路由中使用
const routes = [
  {
    path: '/home',
    name: 'home',
    component: HomePage
  }
]
```

#### 最佳实践

**推荐做法**：
1. ✅ 创建自定义首页组件 `src/views/home/index.vue`
2. ✅ 在 `Vue.use()` 时传入 `HomePage` 参数
3. ✅ 确保后端返回首页菜单配置
4. ✅ 在 `defaultMenus` 中包含首页配置作为降级方案

**完整示例**：
```javascript
// main.js
import HomePage from './views/home/index.vue'

Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  HomePage  // 传入自定义首页组件
})

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

    // 只在已登录时获取系统标题
    const token = this.$store.state.user.token
    if (token) {
      this.$store.dispatch('app/getSysTitle', {
        defaultTitle: 'Demo 管理系统',
        defaultLogo: ''
      })
    } else {
      document.title = 'Demo 管理系统'
    }
  }
})
```

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

A: **不需要！框架已内置所有样式。**

框架打包时已自动包含以下样式：
- ✅ `base.less` - 基础样式
- ✅ `animate.css` - 动画样式
- ✅ `ivewExpand.less` - ViewUI 扩展样式
- ✅ `iconfont.css` - 字体图标样式

**无需在项目中**：
```javascript
// ❌ 不需要这些导入
import 'admin-framework/assets/css/base.less'
import 'admin-framework/assets/css/animate.css'
```

**只需引入框架即可**：
```javascript
// ✅ 样式已自动包含
import AdminFramework from './libs/admin-framework.js'
Vue.use(AdminFramework, { ... })
```

框架使用时样式会自动注入到页面中，无需任何额外配置！

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

A: **需要配置组件映射表。**

**问题原因**：
后端权限菜单接口返回的组件路径（如 `ball/games.vue`）需要映射到实际组件。

**解决方案**：

#### 方式一：在 Vue.use 时配置（推荐）

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

// 2. 配置映射
Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  // ✅ 配置组件映射
  componentMap: {
    'ball/games': GamesComponent,
    'order/pay_orders': PayOrdersComponent
    // 根据权限菜单接口的 component 字段添加...
  }
})
```

#### 方式二：使用 addComponentMap 方法

```javascript
// 先使用框架
Vue.use(AdminFramework, { config, ViewUI, VueRouter, Vuex, createPersistedState })

// 然后添加映射
AdminFramework.addComponentMap({
  'ball/games': GamesComponent,
  'order/pay_orders': PayOrdersComponent
})
```

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

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

#### 配置技巧

**路径规则**：
- 后端返回：`"component": "ball/games.vue"`
- 配置映射：`'ball/games': GamesComponent`（不需要 `.vue` 后缀）
- 框架会自动处理带和不带 `.vue` 的路径

**完整示例**：
```javascript
// 根据你的权限菜单接口，导入所有可能用到的组件
import GamesComponent from './views/ball/games.vue'
import WchUsersComponent from './views/ball/wch_users.vue'
import PayOrdersComponent from './views/order/pay_orders.vue'

Vue.use(AdminFramework, {
  config,
  ViewUI,
  VueRouter,
  Vuex,
  createPersistedState,
  componentMap: {
    'ball/games': GamesComponent,
    'ball/wch_users': WchUsersComponent,
    'order/pay_orders': PayOrdersComponent
  }
})
```

**未映射的组件**：
会显示友好提示：`页面组件未加载: xxx.vue，请在项目中创建此组件或在组件映射表中注册`

---

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

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

**说明**：
- 框架已内置所有系统样式，无需创建 `assets/css` 目录
- 只需要准备你自己的业务图片和业务样式（如有需要）

---

## 📝 版本信息

**当前版本**: 1.0.0

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

---

## 📄 许可证

MIT License

---

## 💬 技术支持

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

---

## 🎯 快速参考

### 最小化代码示例

```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(ViewUI/VueRouter/Vuex)
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')
```

---

**祝开发愉快！** 🎉