From d7c07ecb7760cb1bbb8351f3f4a06c88b6029c0e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E6=88=90?= <light@qq.com>
Date: Wed, 15 Apr 2026 15:23:01 +0800
Subject: [PATCH] 1

---
 README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 81 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 7c5e6bf..b4ecf10 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,19 @@ import AdminFramework from './vendor/admin-framework.js'
 | `HomePage` | `Vue` 组件 | 可选，自定义首页；默认框架内置欢迎页 |
 | `onReady` | `function` | 可选，根实例 `created` 末尾调用，`this` 为 Vue 根实例 |
 
+### 3.2 `createApp` 执行流程（源码行为）
+
+1. 自动补齐 `uploadUrl`（未传时按 `apiUrl` 拼接 `/upload`）。
+2. 注册 `ViewUI`、`VueRouter`、`Vuex`。
+3. 注入全局原型：`$config`、`$http`、`$tools`、`$uiTool`、`$framework`。
+4. 全局注册组件（`registerGlobalComponents`）。
+5. 建立 `componentMap`（内置系统页 + 业务传入映射）。
+6. 创建 Store 并初始化 HTTP。
+7. 创建 Router（基础路由 + 动态主路由），并挂守卫。
+8. 创建根 Vue；恢复菜单与系统标题；最后执行 `onReady`。
+
+> 注意：框架实例是单例，`store/router` 初始化后会复用；通常整个应用只调用一次 `createApp`。
+
 **示例：**
 
 ```javascript
@@ -113,6 +126,13 @@ app.$mount('#app')
 | `storeModules` | 默认 `user`、`app` 模块描述，扩展 Store 时可参考 |
 | `createBaseRoutes` / `setupRouterGuards` / `registerComponents` | 高级自定义路由/组件时使用 |
 
+### 4.4 运行时全局对象
+
+浏览器环境下，框架会暴露：
+
+- `window.framework`：框架单例。
+- `window.rootVue`：`createApp` 创建的根实例（便于调试）。
+
 ### 4.2 `addComponentMap(customMap)`
 
 在运行时追加组件映射（与 `createApp` 里的 `componentMap` 语义相同）。
@@ -151,6 +171,7 @@ AdminFramework.initHttp(
 
 - 成功：后端 JSON 需 `code === 0`，否则走全局错误提示并 `reject`。
 - `401`：清空 token，并跳转登录路由（依赖 `window.framework.router`）。
+- 请求参数会做预处理：递归移除对象中值为 `''` 的键，并自动格式化 `Date`。
 
 ### 5.3 方法说明
 
@@ -188,6 +209,12 @@ export default {
 await this.$http.get('/xxx', { id: 1 }, { hideLoad: true })
 ```
 
+### 5.4 常见注意点
+
+- `post(url, body, config)` 当前实现固定会显示 loading（`showLoad`），`hideLoad` 只在 `get` 内部判断。
+- `postFormData` 使用 `application/x-www-form-urlencoded`。
+- `fileExport` 返回 `blob` 响应；`is_down=false` 时可自行处理文件流。
+
 ---
 
 ## 6. uiTool 模块
@@ -260,20 +287,47 @@ AdminFramework.createApp({
 
 框架内置已注册一批系统页（如 `system/sys_menu` 等），见 `src/views/index.js` 中 `setupComponentMap`；业务模块在 `componentMap` 中追加即可。
 
+### 7.1 内置映射（默认可用）
+
+默认已注入以下路径（可直接在后端菜单配置里使用）：
+
+- `home/index`
+- `system/sys_log`
+- `system/sys_log_operate`
+- `system/sys_param_setup`
+- `system/sys_role`
+- `system/sys_user`
+- `system/sys_tenant`
+- `system/sys_control`
+- `system/sys_menu`
+- `system/sys_title`
+
 ---
 
 ## 8. 系统 API（`systemApi`）
 
-`AdminFramework.systemApi` 聚合导出 `src/api/system` 下各 `*Server`，例如：
+`AdminFramework.systemApi` 聚合导出 `src/api/system/index.js` 中的服务（以下为当前版本完整导出）：
 
 | 导出名 | 模块文件 | 典型用途 |
 |--------|----------|----------|
+| `fileServe` | `fileServe.js` | 文件上传下载 |
+| `plaAccountServer` | `pla_account_server.js` | 平台账号管理 |
+| `rolePermissionServer` | `rolePermissionServer.js` | 角色权限 |
+| `roleServer` | `roleServer.js` | 角色管理 |
+| `sysAddressServer` | `sysAddressServer.js` | 地址字典 |
+| `sysModuleServer` | `sysModuleServer.js` | 模块管理 |
+| `sysLogServe` | `sys_log_serve.js` | 系统日志 |
+| `systemTypeServer` | `systemType_server.js` | 系统类型配置 |
+| `tableServer` | `tableServer.js` | 表结构相关 |
 | `userServer` | `userServer.js` | 登录、用户 CRUD、权限菜单 |
+| `formFieldServer` | `formFieldServer.js` | 表单字段 |
+| `formServer` | `formServer.js` | 表单模型 |
 | `menuServer` | `menuServer.js` | 菜单管理 |
-| `roleServer` / `rolePermissionServer` | 角色与权限 |
-| `paramSetupServer` | 系统参数（如站点标题、Logo） |
-| `fileServe` | 文件上传下载 |
-| `modelServer` / `tableServer` / `formServer` 等 | 低代码/表单相关 |
+| `modelFieldServer` | `modelFieldServer.js` | 数据模型字段 |
+| `modelServer` | `modelServer.js` | 数据模型 |
+| `paramSetupServer` | `paramSetupServer.js` | 系统参数（标题、Logo） |
+| `sysControlTypeServer` | `sysControlTypeServer.js` | 控件类型 |
+| `sysTenantServer` | `sysTenantServer.js` | 租户管理 |
 
 **调用示例：**
 
@@ -290,19 +344,36 @@ async function login() {
 
 实际请求仍走全局配置的 `http`（`apiUrl`、token 头）。
 
+> 说明：`src/api/system` 中若存在未在 `index.js` 聚合导出的文件（例如实验性模块），不会出现在 `AdminFramework.systemApi`。
+
 ---
 
 ## 9. Vuex（`this.$store`）
 
 默认模块：
 
+### 9.0 `createStore`（扩展自定义模块）
+
+框架导出 `createStore(Vuex, customModules, createPersistedState)`，可在默认 `user/app` 基础上合并业务模块：
+
+```javascript
+import Vuex from 'vuex'
+// 源码工程示例：按项目结构从 store 导入 createStore
+import { createStore } from '@/store'
+import foo from './store/foo'
+
+const store = createStore(Vuex, { foo }, null)
+```
+
+`createPersistedState` 传入后会启用本地持久化插件（`window.localStorage`）。
+
 ### 9.1 `user`（`namespaced: true`）
 
 | 项 | 说明 |
 |----|------|
-| `state` | `token`、`userName`、`authorityMenus`、`menuList` 等 |
-| `mutations` | `setToken`、`setUserName`、`setAuthorityMenus`、`setMenuList` |
-| `actions` | `setAuthorityMenus`：拉取或传入菜单 JSON，生成动态路由并写入 `localStorage` |
+| `state` | `token`、`userName`、`avatorImgPath`、`authorityMenus`、`menuList`、`currentTenant` |
+| `mutations` | `setToken`、`setUserName`、`setAuthorityMenus`、`setMenuList`、`setCurrentTenant` |
+| `actions` | `setAuthorityMenus`（生成动态路由）、`handleLogin`、`handleLogOut` |
 
 **登录后刷新菜单示例：**
 
@@ -322,7 +393,8 @@ await this.$store.dispatch('user/setAuthorityMenus', {
 | 项 | 说明 |
 |----|------|
 | `state` | `sysFormModel`（标题、Logo）、面包屑、首页路由 |
-| `actions` | `getSysTitle`：根据参数与接口更新站点标题与 Logo |
+| `mutations` | `setBreadCrumb`、`setHomeRoute`、`setSysTitle` |
+| `actions` | `getSysTitle`：根据登录状态和参数接口更新站点标题与 Logo |
 
 ```javascript
 await this.$store.dispatch('app/getSysTitle', {