1

demo-project/_doc/文档更新说明.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 参数说明
+- ✅ 完善了首页组件的使用方式
+- ✅ 提供了最佳实践和迁移指南
+