1

demo-project/文档更新说明.md

@@ -0,0 +1,362 @@
+# 文档更新说明
+
+## 📝 更新内容
+
+已更新 `完整使用文档.md`，主要修改如下：
+
+### 1. 移除已废弃的方法
+
+**移除的方法**：
+- ❌ `setUserServer(userServer)` - 已废弃
+- ❌ `setParamSetupServer(paramSetupServer)` - 已废弃
+
+**原因**：
+- 框架已改为直接导入 API 模块
+- 不再使用依赖注入模式
+- 简化了代码结构
+
+### 2. 添加 HomePage 参数说明
+
+**新增内容**：
+
+#### install 方法参数
+
+```javascript
+Vue.use(AdminFramework, {
+  config: yourConfig,
+  ViewUI: ViewUI,
+  VueRouter: VueRouter,
+  Vuex: Vuex,
+  createPersistedState: createPersistedState,
+  HomePage: HomePage  // ✅ 新增：可选的自定义首页组件
+})
+```
+
+**参数说明**：
+- `HomePage`: 自定义首页组件（可选，不传则使用框架内置组件）
+
+### 3. 完善 Q11: 主页 HomePage 组件说明
+
+**新增两种使用方式**：
+
+#### 方式一：使用框架内置的主页组件（默认）
+
+```javascript
+// 不传入 HomePage，框架会使用内置组件
+Vue.use(AdminFramework, {
+  config,
+  ViewUI,
+  VueRouter,
+  Vuex,
+  createPersistedState
+})
+```
+
+**内置组件特性**：
+- ✅ 自动从 Vuex Store 获取系统标题
+- ✅ 优雅的欢迎页面样式
+- ✅ 无需额外配置
+
+#### 方式二：传入自定义首页组件（推荐）
+
+**创建自定义首页**：
+```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>
+```
+
+**传入自定义组件**：
+```javascript
+import HomePage from './views/home/index.vue'
+
+Vue.use(AdminFramework, {
+  config,
+  ViewUI,
+  VueRouter,
+  Vuex,
+  createPersistedState,
+  HomePage  // ✅ 传入自定义首页组件
+})
+```
+
+### 4. 重要说明：首页路由配置
+
+**关键点**：
+- ⚠️ **首页路由完全由后端权限菜单返回**
+- ⚠️ 后端必须返回 `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
+```
+
+### 5. 降级方案
+
+如果后端接口失败，框架会使用默认菜单配置（`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
+  },
+  // ... 其他菜单
+]
+```
+
+### 6. 更新快速开始示例
+
+**新的 main.js 示例**：
+```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'
+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 管理系统'
+    }
+  }
+})
+```
+
+## 📊 更新对比
+
+### 旧版本（已废弃）
+
+```javascript
+// ❌ 旧版本：使用依赖注入
+import { systemApi, systemHighApi } from 'admin-framework'
+
+AdminFramework.setUserServer(systemApi.userServer)
+AdminFramework.setParamSetupServer(systemHighApi.paramSetupServer)
+
+// ❌ 旧版本：首页路由硬编码在框架中
+// 无法自定义首页组件
+```
+
+### 新版本（当前）
+
+```javascript
+// ✅ 新版本：直接导入 API
+import userServer from '../api/system/userServer'
+import paramSetupServer from '../api/system_high/paramSetupServer'
+
+// ✅ 新版本：支持自定义首页组件
+import HomePage from './views/home/index.vue'
+
+Vue.use(AdminFramework, {
+  config,
+  ViewUI,
+  VueRouter,
+  Vuex,
+  createPersistedState,
+  HomePage  // 可选：传入自定义首页组件
+})
+```
+
+## 🎯 最佳实践
+
+### 推荐做法
+
+1. **创建自定义首页组件**
+   ```bash
+   src/views/home/index.vue
+   ```
+
+2. **在 Vue.use() 时传入 HomePage 参数**
+   ```javascript
+   import HomePage from './views/home/index.vue'
+   
+   Vue.use(AdminFramework, {
+     config,
+     ViewUI,
+     VueRouter,
+     Vuex,
+     createPersistedState,
+     HomePage  // 传入自定义首页组件
+   })
+   ```
+
+3. **确保后端返回首页菜单配置**
+   ```json
+   {
+     "id": 1,
+     "name": "首页",
+     "path": "/home",
+     "component": "home/index",
+     "parent_id": 0,
+     "type": "页面",
+     "is_show_menu": 1
+   }
+   ```
+
+4. **在 defaultMenus 中包含首页配置作为降级方案**
+   ```javascript
+   // src/config/menuConfig.js
+   export const defaultMenus = [
+     {
+       id: 1,
+       name: '首页',
+       path: '/home',
+       component: 'home/index',
+       // ...
+     }
+   ]
+   ```
+
+### 不推荐的做法
+
+1. ❌ 使用已废弃的 `setUserServer` 和 `setParamSetupServer` 方法
+2. ❌ 在代码中硬编码首页路由
+3. ❌ 不提供降级方案（defaultMenus）
+
+## 📝 迁移指南
+
+### 从旧版本迁移到新版本
+
+**步骤 1：移除废弃的方法调用**
+
+```javascript
+// ❌ 删除这些代码
+AdminFramework.setUserServer(systemApi.userServer)
+AdminFramework.setParamSetupServer(systemHighApi.paramSetupServer)
+```
+
+**步骤 2：创建自定义首页组件**
+
+```bash
+# 创建首页组件文件
+mkdir -p src/views/home
+touch src/views/home/index.vue
+```
+
+**步骤 3：更新 main.js**
+
+```javascript
+// 添加 HomePage 导入
+import HomePage from './views/home/index.vue'
+
+// 在 Vue.use() 时传入
+Vue.use(AdminFramework, {
+  config,
+  ViewUI,
+  VueRouter,
+  Vuex,
+  createPersistedState,
+  HomePage  // 新增
+})
+```
+
+**步骤 4：确保后端返回首页配置**
+
+检查后端 `authorityMenus` 接口是否返回首页配置。
+
+**步骤 5：测试**
+
+```bash
+npm run dev
+```
+
+登录后应该能看到自定义的首页。
+
+## ✅ 验证清单
+
+- ✅ 移除了 `setUserServer` 和 `setParamSetupServer` 的调用
+- ✅ 创建了自定义首页组件 `src/views/home/index.vue`
+- ✅ 在 `Vue.use()` 时传入了 `HomePage` 参数
+- ✅ 后端返回了首页菜单配置
+- ✅ `defaultMenus` 中包含了首页配置
+- ✅ 登录后能正常跳转到首页
+- ✅ 首页显示正确的内容
+
+## 📚 相关文档
+
+- `完整使用文档.md` - 完整的框架使用文档
+- `demo-project/README.md` - Demo 项目说明
+- `demo-project/登录跳转首页修复说明.md` - 登录跳转逻辑说明
+- `demo-project/移除硬编码首页说明.md` - 移除硬编码首页的说明
+
+---
+
+**文档已更新完成！** 🎉
+
+现在文档更准确地反映了框架的当前实现，包括：
+- ✅ 移除了已废弃的方法
+- ✅ 添加了 HomePage 参数说明
+- ✅ 完善了首页组件的使用方式
+- ✅ 提供了最佳实践和迁移指南
+

完整使用文档.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,
+    const token = this.$store.state.user.token
-      Page404: AdminFramework.Page404
+    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`: 项目配置对象
+- `config`: 项目配置对象（必需）
-- `ViewUI`: ViewUI 实例
+- `ViewUI`: ViewUI 实例（必需）
-- `VueRouter`: VueRouter 类
+- `VueRouter`: VueRouter 类（必需）
-- `Vuex`: Vuex 类
+- `Vuex`: Vuex 类（必需）
-- `createPersistedState`: vuex-persistedstate 插件
+- `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',
+  "id": 1,
-  name: 'home',
+  "name": "首页",
-  meta: { title: '首页', notCache: true },
+  "path": "/home",
-  component: AdminFramework.HomePage  // 框架内置的主页组件
+  "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: 需要单独引入样式文件吗？