1

完整使用文档.md

@@ -165,6 +165,7 @@ import createPersistedState from 'vuex-persistedstate'
 import AdminFramework from './libs/admin-framework.js'
 import App from './App.vue'
 import config from './config'
+import HomePage from './views/home/index.vue'  // 可选：自定义首页组件
 
 // 🎉 只需这一行！框架自动完成所有初始化
 Vue.use(AdminFramework, {
@@ -172,7 +173,8 @@ Vue.use(AdminFramework, {
   ViewUI,
   VueRouter,
   Vuex,
-  createPersistedState
+  createPersistedState,
+  HomePage  // 可选：传入自定义首页组件（不传则使用框架内置组件）
 })
 
 // 创建 Vue 实例
@@ -183,11 +185,17 @@ window.rootVue = new Vue({
   render: h => h(App),
   mounted() {
     AdminFramework.uiTool.setRem()
-    this.$store.dispatch('user/setAuthorityMenus', {
-      Main: AdminFramework.Main,
-      ParentView: AdminFramework.ParentView,
-      Page404: AdminFramework.Page404
-    })
+
+    // 只在已登录时获取系统标题
+    const token = this.$store.state.user.token
+    if (token) {
+      this.$store.dispatch('app/getSysTitle', {
+        defaultTitle: 'Demo 管理系统',
+        defaultLogo: ''
+      })
+    } else {
+      document.title = 'Demo 管理系统'
+    }
   }
 })
 
@@ -202,11 +210,10 @@ window.addEventListener('resize', AdminFramework.uiTool.setRem)
 - ✅ 注册 Vuex（自动调用 `Vue.use(Vuex)`）
 - ✅ 创建 Store（包含用户、应用模块）
 - ✅ 创建 Router（包含所有基础路由和动态路由）
-- ✅ **提前注册 home 路由**（确保登录后能正常跳转）
 - ✅ 初始化 HTTP
-- ✅ 设置 API 服务
 - ✅ 注册全局组件
 - ✅ 配置路由守卫
+- ✅ 支持自定义首页组件（通过 HomePage 参数传入）
 
 #### 3. 安装依赖
 
@@ -354,16 +361,18 @@ Vue.use(AdminFramework, {
   ViewUI: ViewUI,
   VueRouter: VueRouter,
   Vuex: Vuex,
-  createPersistedState: createPersistedState
+  createPersistedState: createPersistedState,
+  HomePage: HomePage  // 可选：自定义首页组件
 })
 ```
 
 **参数说明：**
-- `config`: 项目配置对象
-- `ViewUI`: ViewUI 实例
-- `VueRouter`: VueRouter 类
-- `Vuex`: Vuex 类
-- `createPersistedState`: vuex-persistedstate 插件
+- `config`: 项目配置对象（必需）
+- `ViewUI`: ViewUI 实例（必需）
+- `VueRouter`: VueRouter 类（必需）
+- `Vuex`: Vuex 类（必需）
+- `createPersistedState`: vuex-persistedstate 插件（必需）
+- `HomePage`: 自定义首页组件（可选，不传则使用框架内置组件）
 
 #### initHttp(config, store)
 初始化 HTTP 配置
@@ -375,20 +384,6 @@ AdminFramework.initHttp({
 }, store)
 ```
 
-#### setUserServer(userServer)
-设置用户服务实例
-
-```javascript
-AdminFramework.setUserServer(userServer)
-```
-
-#### setParamSetupServer(paramSetupServer)
-设置参数设置服务实例
-
-```javascript
-AdminFramework.setParamSetupServer(paramSetupServer)
-```
-
 #### createRouter(Router, components, customRoutes, ViewUI, homeName)
 创建路由实例
 
@@ -955,7 +950,9 @@ export default {
 
 ### Q11: 主页 HomePage 组件说明
 
-A: **框架已内置主页组件，自动显示系统标题欢迎信息。**
+A: **框架支持两种方式使用首页组件：使用内置组件或传入自定义组件。**
+
+#### 方式一：使用框架内置的主页组件（默认）
 
 **默认主页组件**：
 ```vue
@@ -973,27 +970,176 @@ A: **框架已内置主页组件，自动显示系统标题欢迎信息。**
 **特性**：
 - ✅ 自动从 Vuex Store 获取系统标题（`app/sysFormModel`）
 - ✅ 优雅的欢迎页面样式
-- ✅ home 路由已在创建 Router 时注册，确保登录后能正常跳转
+- ✅ 无需额外配置
 
-**如何使用**：
-框架会自动创建 home 路由并使用内置的 HomePage 组件：
+**使用方式**：
 ```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
 {
-  path: '/home',
-  name: 'home',
-  meta: { title: '首页', notCache: true },
-  component: AdminFramework.HomePage  // 框架内置的主页组件
+  "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
 }
 ```
 
-**自定义主页**：
-如果后端返回的权限菜单中包含 home 路由配置，会优先使用权限菜单的配置。
-
-**直接使用 HomePage 组件**：
+**组件映射规则**：
 ```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: 需要单独引入样式文件吗？