1

2026-04-15 15:26:17 +08:00
parent d7c07ecb77
commit 2c265bc93c
1 changed files with 106 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -4,6 +4,112 @@

 ---

+## 快速导航（按角色）
+
+### 框架使用者（接入业务项目）
+
+- 目标：最快把框架跑起来并完成菜单页面映射。
+- 建议阅读顺序：`§1 依赖与环境` → `§2 引入方式` → `§3 核心 API` → `§7 组件映射与动态路由` → `§12 组件使用说明`。
+- 最小落地步骤：
+  1. 安装 peer 依赖并引入 `admin-framework.js`。
+  2. 调用 `AdminFramework.createApp({ title, apiUrl, componentMap })`。
+  3. 在 `componentMap` 中注册业务页面路径并与后端菜单 `component` 字段对齐。
+
+### 业务开发者（写页面和接口联调）
+
+- 目标：在现有框架内开发业务页、调用接口、使用内置组件。
+- 建议阅读顺序：`§5 HTTP 模块` → `§6 uiTool/tools` → `§8 systemApi` → `§9 Vuex` → `§12 组件使用说明`。
+- 高频关注：
+  - 请求约定（`code === 0`、`401` 自动处理、参数预处理）。
+  - `this.$http` / `this.$uiTool` / `this.$tools` 的用法。
+  - 全局组件与按需组件边界（见 `§12.14` 索引）。
+
+### 二次封装维护者（改框架内核）
+
+- 目标：扩展框架能力（路由、Store、组件注册、系统 API 聚合等）。
+- 建议阅读顺序：`§3.2 createApp 执行流程` → `§4 框架实例` → `§7 动态路由` → `§8 systemApi` → `§9 createStore`。
+- 变更建议：
+  1. 先改 `src/index.js` 的初始化路径（插件、原型、Store、Router）。
+  2. 同步维护 `src/views/index.js` 的默认 `componentMap`。
+  3. 变更 `src/api/system` 时同步更新 `src/api/system/index.js` 聚合导出与 README `§8`。
+
+### 常见任务直达
+
+| 任务 | 直达章节 |
+|------|----------|
+| 第一次接入并启动 | `§1` + `§2` + `§3` |
+| 菜单点击后页面不显示 | `§7`（重点看 `componentMap`） |
+| 请求报错或 token 失效 | `§5` + `§9.1 user` |
+| 顶部标题/Logo 不正确 | `§9.2 app`（`getSysTitle`） |
+| 想知道组件怎么用 | `§12`（先看 `§12.14` 索引） |
+
+### 5分钟上手清单
+
+> 目标：5 分钟内把框架跑起来并看到一个业务页面。
+
+#### 第 1 步：安装依赖（1 分钟）
+
+在业务项目安装 peer 依赖：
+
+```bash
+npm i vue vue-router vuex view-design axios
+```
+
+#### 第 2 步：准备框架包（1 分钟）
+
+- 已有 `dist/admin-framework.js`：直接拷贝到业务项目（例如 `src/vendor/`）。
+- 没有构建产物：在框架项目根目录执行：
+
+```bash
+npm run build
+```
+
+#### 第 3 步：准备页面映射（1 分钟）
+
+创建一个业务页面并准备 `componentMap`：
+
+```javascript
+// 例如 src/router/component-map.js
+import DemoPage from '@/views/demo/index.vue'
+
+export default {
+  'demo/index': DemoPage,
+  'demo/index.vue': DemoPage
+}
+```
+
+#### 第 4 步：入口创建应用（1 分钟）
+
+```javascript
+import Vue from 'vue'
+import AdminFramework from '@/vendor/admin-framework.js'
+import componentMap from '@/router/component-map'
+
+const app = AdminFramework.createApp({
+  title: '后台管理系统',
+  apiUrl: 'http://127.0.0.1:3000/admin_api/',
+  componentMap
+})
+
+app.$mount('#app')
+```
+
+#### 第 5 步：验证（1 分钟）
+
+- 能进入登录页（或已有 token 时进入主框架页）。
+- 左侧菜单点击后，页面能正常渲染（无“页面组件未加载”提示）。
+- 打开浏览器控制台，确认可访问：
+  - `window.framework`
+  - `window.rootVue`
+
+#### 常见 3 个坑（上手必看）
+
+1. 后端菜单里的 `component` 路径必须和 `componentMap` 键一致（推荐同时写带 `.vue` 和不带 `.vue` 两种）。
+2. `apiUrl` 建议以 `/admin_api/` 结尾，避免接口前缀不一致。
+3. 若登录后菜单空白，优先检查 `authorityMenus` 返回格式与 `user/setAuthorityMenus` 动态路由是否执行。
+
+---
+
 ## 1. 依赖与环境

 ### 1.1 Peer 依赖（由业务项目安装）