diry 1 miesiąc temu
rodzic
commit
d8077a7d94
5 zmienionych plików z 192 dodań i 392 usunięć
  1. 147 346
      docs/sapit-ui-基座说明与业务使用.md
  2. 1 1
      lib/config.json
  3. 0 0
      lib/css/style.css
  4. 44 45
      lib/js/docs.js
  5. 0 0
      lib/js/index.js

+ 147 - 346
docs/sapit-ui-基座说明与业务使用.md

@@ -2,7 +2,7 @@
 
 > 适用工程:<span style="color:#1677ff;font-weight:700">sapit-ui-framework</span>(基座/源码)、<span style="color:#1677ff;font-weight:700">sapit-ui-plus</span>(发布产物)、<span style="color:#1677ff;font-weight:700">mode</span>(业务示例)
 >
-> 本文档同时是基座内置文档页 `/docs` 的数据源(`packages/pages-components/docs.vue` 在构建时用 `?raw` 内联本文件并渲染成 HTML)。
+> 本文档也是基座内置文档页 `/docs` 与组件页 `/components` 的数据源。
 
 ---
 
@@ -10,7 +10,7 @@
 
 - [一、总览](#一总览)
 - [二、基座提供的内容](#二基座提供的内容)
-- [三、构建与发布](#三构建与发布)
+- [三、构建与配置](#三构建与配置)
 - [四、业务项目接入](#四业务项目接入)
 - [五、注意事项](#五注意事项)
 - [六、常见全局方法速查](#六常见全局方法速查)
@@ -21,41 +21,31 @@
 
 ### 1.1 三者关系
 
-| 工程 | 角色 | 说明 |
-| --- | --- | --- |
-| `sapit-ui-framework` | <span style="color:#d4380d">基座(源码)</span> | 内置组件与常用依赖的库工程,Vite lib 模式打包 |
-| `sapit-ui-plus` | <span style="color:#d46b08">发布产物</span> | 基座 `dist` 推送后的 git 仓库(含 `lib/`、`docs/`、`vite-plugins/`、`package.json`) |
-| `mode` | <span style="color:#389e0d">业务使用者</span> | 以 `sapit-ui-plus` git 依赖为底层,编写业务页面/配置 |
-
-数据流:
+| 工程                 | 角色                                            | 说明                                                              |
+| -------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
+| `sapit-ui-framework` | <span style="color:#d4380d">基座(源码)</span> | 内置组件与常用依赖的库工程,Vite lib 模式打包                     |
+| `sapit-ui-plus`      | <span style="color:#d46b08">发布产物</span>     | 基座 `dist` 推送后的 git 仓库(`lib/`、`docs/`、`vite-plugins/`) |
+| `mode`               | <span style="color:#389e0d">业务使用者</span>   | 以 `sapit-ui-plus` git 依赖为底层,编写业务页面/配置              |
 
 ```text
-sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git)
-                                                                      |
-                                                        mode: npm install 安装依赖
+sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> mode
 ```
 
 ### 1.2 目录结构(基座)
 
 ```text
 sapit-ui-framework/
-├─ packages/                 # 打包入口依赖图(发布内容来源)
+├─ packages/                 # 发布内容来源(入口依赖图)
 │  ├─ index.js               # 库入口,导出 registerGlobalConfig
-│  ├─ components/            # 内置组件 S*(*.vue 全局注册)
-│  ├─ layouts/               # 布局(BasicLayout/BlankLayout/UserLayout/RouteView/PageView)
-│  ├─ router/                # 常量路由 + 动态路由生成 + 静态路由 + 全局守卫
-│  ├─ store/                 # pinia(user)
-│  ├─ api/                   # login/common/upload/workbench 接口
-│  ├─ utils/                 # http/ls/filter/socket/rsa/action/markdown 等
-│  ├─ locales/               # 国际化聚合与中文->英文兜底字典
-│  ├─ pages-components/      # 登录、工作台、待办、消息、404/403/500、docs 文档页
-│  ├─ static/                # 图片/svg 资源
-│  └─ style/                 # common.less / theme.less / nprogress.less
-├─ docs/                     # 说明文档(同时供内置 /docs 页面渲染)
-├─ vite-plugins/             # docs-viewer 插件(独立 HTML 预览 + 控制台提示)
-├─ src/                      # 基座自身的调试壳(不全部打包,见 3.2)
-├─ vite.config.js            # lib 构建配置
-└─ package.json              # name: sapit-ui-plus
+│  ├─ components/            # 内置组件 S*
+│  ├─ layouts/               # BasicLayout / BlankLayout / UserLayout / RouteView / PageView
+│  ├─ router/                # 常量路由 + 动态路由 + 静态路由 + 守卫
+│  ├─ store/ api/ utils/ locales/ static/ style/
+│  └─ pages-components/      # 登录、工作台、待办、消息、404/403/500、docs 文档页
+├─ docs/                     # 本文档(供内置 /docs 渲染)
+├─ vite-plugins/             # docs-viewer 插件
+├─ src/                      # 基座自身调试壳
+└─ vite.config.js / package.json
 ```
 
 ---
@@ -64,279 +54,151 @@ sapit-ui-framework/
 
 ### 2.1 全局组件
 
-`packages/index.js` 通过 `import.meta.glob('./components/**/*.vue')` 将 `components` 下所有 `.vue` 组件 **按文件名全局注册**(异步组件),可直接以文件名作为标签使用(如 `<s-modal>`、`<s-user-select>`、`<s-file-upload>`)。
+`packages/index.js` 用 `import.meta.glob('./components/**/*.vue')` 把 `components/**/*.vue` **按文件名全局注册**,模板直接以文件名标签使用(如 `<s-modal>`、`<s-user-select>`)。
 
-| 分类 | 组件 |
-| --- | --- |
-| 布局类 | `SListLayout`、`SListCardLayout`、`SListTableTreeLayout`、`SSuperListLayout`、`SFormLayout`、`SPanelLayout`、`SCollapses`/`SCollapsesItem`、`SDrawer` |
-| 弹层类 | `SModal`、`SModalTemplate`、`ModalHeader`、`SIconModal` |
+| 分类      | 组件                                                                                                                                                  |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 布局类    | `SListLayout`、`SListCardLayout`、`SListTableTreeLayout`、`SSuperListLayout`、`SFormLayout`、`SPanelLayout`、`SCollapses`/`SCollapsesItem`、`SDrawer` |
+| 弹层类    | `SModal`、`SModalTemplate`、`ModalHeader`、`SIconModal`                                                                                               |
 | 表单/筛选 | `SForm`、`SFormItem`、`SFilterWrap`、`SFilterItem`、`SCascader`、`STree`、`STreeSelect`、`SUserSelect`、`SOfficeSelect`、`SIconSelect`、`CustomInput` |
-| 上传类 | `SFileUpload`、`SDraggerUpload`、`SCopperUpload`、`CropperModal` |
-| 展示/其它 | `SEditor`、`SEmpty`、`SIcon`、`SSvg`、`SAnchor`、`SToggleLanguage`、`SettingFilter`、`SettingColumns`、菜单 `SSideMenu`/`STopMenu` |
-
-> <span style="color:#d46b08;font-weight:700">注意</span>:`components/Table/index.jsx` 是 `.jsx`,<span style="color:#d4380d;font-weight:700">不在全局注册范围内</span>,需按需 `import`。
+| 上传类    | `SFileUpload`、`SDraggerUpload`、`SCopperUpload`、`CropperModal`                                                                                      |
+| 展示/其它 | `SEditor`、`SEmpty`、`SIcon`、`SSvg`、`SAnchor`、`SToggleLanguage`、`SettingFilter`、`SettingColumns`、`SSideMenu`/`STopMenu`                         |
 
-同时,`@ant-design/icons-vue` 的所有图标会被全局注册,并挂到 `$icons`。
+> 组件用法见内置组件页 **`/components`**。
+>
+> <span style="color:#d4380d;font-weight:700">注意</span>:`components/Table/index.jsx` 是 `.jsx`,**不在全局注册范围**,需手动 `import`。`@ant-design/icons-vue` 图标全部全局注册并挂到 `$icons`。
 
 ### 2.2 全局属性 / 方法
 
-在 `$registerGlobalConfig` 执行后,组件内可 `this.$xxx`,模板内可 `$xxx`,也可通过 `window.$xxx` 使用:
-
-| 名称 | 说明 |
-| --- | --- |
-| `$registerGlobalConfig(config, pages)` | 初始化入口(见第四节) |
-| `$utils` | 工具类集合,含 `$utils.env`、`$utils.ls`、`$utils.http` 及大量通用方法 |
-| `env` | 合并后的环境配置(等同 `$utils.env`) |
-| `$pinia` | 用户 store 实例 |
-| `$socket` | websocket 封装 |
-| `$filter` | 日期格式化:`dayJsFormat` / `dayFormat` / `dateFormatDay` / `dateFormat` |
-| `$i18n` | vue-i18n 实例 |
-| `$l(name, key)` | 国际化方法(见 2.7) |
-| `$theme` | 当前主题配置对象(见 2.8;组件内已改用 CSS 变量,一般不直接使用) |
-| `$staticRoutes` | 当前注册的静态页面路由列表 |
-| `$modal` / `$message` / `$notice` | 对应 ant-design-vue 的 `Modal` / `message` / `notification` |
-| `$push(path, query)` | 站内跳转(自动拼接 `VITE_APP_BASE_URL`) |
-| `$open(path, query)` | 新窗口打开(自动拼接 base) |
-| `$icons` | 全部 antd 图标集合 |
+`$registerGlobalConfig` 执行后可用(`this.$xxx` / 模板 `$xxx` / `window.$xxx`):
+
+| 名称                                   | 说明                                                              |
+| -------------------------------------- | ----------------------------------------------------------------- |
+| `$registerGlobalConfig(config, pages)` | 初始化入口(见 4.2)                                              |
+| `$utils`                               | 工具类集合:`$utils.env` / `$utils.ls` / `$utils.http` 及通用方法 |
+| `env`                                  | 合并后的环境配置(= `$utils.env`)                                |
+| `$i18n` / `$l(name, key)`              | 国际化(见 2.7)                                                  |
+| `$theme` / `$staticRoutes` / `$pinia`  | 主题对象 / 静态路由列表 / 用户 store 实例                         |
+| `$modal` / `$message` / `$notice`      | antd 的 `Modal` / `message` / `notification`                      |
+| `$push(path, query)` / `$open(...)`    | 站内跳转 / 新窗口(自动拼 `VITE_APP_BASE_URL`)                   |
+| `$filter` / `$icons` / `$socket`       | 日期格式化 / 图标集合 / websocket 封装                            |
 
 ### 2.3 布局
 
-`packages/layouts/index.js` 导出:`BasicLayout`(含头部/侧边菜单/内容区)、`BlankLayout`、`UserLayout`(登录,渲染 `<router-view/>`)、`RouteView`(二级内容区)、`PageView`(面包屑 + 内容区)。
+`packages/layouts/index.js`:`BasicLayout`(头部+侧边菜单+内容区)、`BlankLayout`、`UserLayout`(登录)、`RouteView`、`PageView`。
 
 ### 2.4 路由
 
 **常量路由**(`packages/router/index.js`):
 
-| 路径 | 说明 |
-| --- | --- |
-| `/login/index` | 登录页(默认基座登录页,<span style="color:#d46b08">可被业务覆盖</span>,见 4.5) |
-| `/workplace/index` | 默认首页(`VITE_APP_DEFAULT_PATH`;默认基座首页,<span style="color:#d46b08">可被业务覆盖</span>) |
-| `/workbench/index` | 工作台 |
-| `/message/index` | 消息 |
-| `/docs` | <span style="color:#389e0d">内置文档页</span>(免登录、不进菜单,见 2.11) |
-| `/404`、`/403`、`/500` | 错误页 |
-| `/:pathMatch(.*)*` | 通配,渲染 404 组件(<span style="color:#d4380d;font-weight:700">不用 redirect</span>,保证刷新动态路由时守卫能拿到真实地址) |
-
-**静态路由**(`staticRoutes`,不依赖后端菜单):见 4.6。基座内置静态页 `builtinStaticRoutes` 已包含 `/docs`。
+| 路径                                       | 说明                                                                |
+| ------------------------------------------ | ------------------------------------------------------------------- |
+| `/login/index`                             | 登录页(默认基座,可被业务覆盖,见 4.5)                            |
+| `/workplace/index`                         | 默认首页(`VITE_APP_DEFAULT_PATH`,可被覆盖)                       |
+| `/workbench/index`、`/message/index`       | 工作台 / 消息                                                       |
+| `/docs`、`/components`                     | 内置文档 / 组件页(`public` 免登录、`hidden` 不进菜单)             |
+| `/404`、`/403`、`/500`、`/:pathMatch(.*)*` | 错误页;通配渲染 404(**不用 redirect**,保证刷新动态路由不掉 404) |
 
-**动态路由**(`packages/router/generator-routers.js`):
+**静态路由**(`staticRoutes`,不依赖后端菜单):见 4.6。基座内置 `/docs`、`/components`。
 
-- 登录后按后端返回的 `menus` 生成路由树,根节点用 `BasicLayout`;
-- 组件匹配规则:先按菜单层级(`parent.id`、是否有 `children`)决定 `PageView`/`RouteView`;叶子节点用 `item.hrefs` 去匹配业务传入的 `pages`(`import.meta.glob('@/views/**/*.vue')` 的 key),匹配不到则回退 404 组件;
-- 路由注册在全局守卫中完成(<span style="color:#1677ff">仅内存标记</span>,刷新后重新注册,避免持久化导致的路由丢失)。
+**动态路由**(`packages/router/generator-routers.js`):登录后按后端 `menus` 生成树,根节点 `BasicLayout`;叶子节点用 `item.hrefs` 匹配业务 `pages`(`import.meta.glob('@/views/**/*.vue')` 的 key),匹配不到回退 404。注册在守卫中完成(内存标记,刷新重注册)。
 
-**全局守卫**能力:
-
-- 公开页面(`meta.public`,如 `/docs`)<span style="color:#389e0d">直接放行,不校验 token/权限</span>;
-- 每次导航实时读取 token,避免快照失效;
-- 未登录仅放行登录页,其余跳登录;
-- 已登录访问登录页/根路径跳默认首页;
-- 拉取用户信息失败时清理并回登录页,避免守卫 pending 卡死;
-- 常量路由支持业务覆盖登录页/首页(见 4.5)。
+**守卫**:公开页(`meta.public`)直接放行;实时读 token;未登录跳登录;已登录访问登录页/根跳默认首页;取用户信息失败清理并回登录页(避免 pending)。URL 带 `code` 时在守卫里换取 token(见 4.8 单点)。
 
 ### 2.5 状态管理(pinia)
 
-`packages/store/user.js`(`useUserStore`):
-
-- state:`user`、`menus`、`permissions`、`clients`、`dynamicRouter`、`menuOpenKeys`
-- getters:`dynamics`(= dynamicRouter)、`openKeys`
-- actions:`Info()`(拉取用户信息/菜单/权限并写入 localStorage)、`setDynamicRouter()`、`setMenuOpenKeys()`
-- 开启持久化(localStorage)
+`packages/store/user.js`(`useUserStore`):state `user/menus/permissions/clients/dynamicRouter/menuOpenKeys`;actions `Info()`(拉取并写 localStorage)、`setDynamicRouter()`、`setMenuOpenKeys()`;localStorage 持久化。
 
 ### 2.6 工具类(`$utils`)
 
-| 模块 | 说明 |
-| --- | --- |
-| `$utils.env` | 环境配置对象 |
-| `$utils.ls` | 本地存储(命名空间为 `VITE_APP_SYS_SERVER_NAME`),含 `get/set/clear` 等 |
-| `$utils.http` | axios 实例(已封装:token 注入、响应结构解包、401/`status:-1` 登录超时处理、文件下载) |
-| `parseAppUrl(url)` | 站内地址拼接 base(支持子路径部署),外部 http(s) 原样返回 |
-| `innerRedirect` / `innerReplace` / `innerOpen` | 基于 `parseAppUrl` 的站内跳转 |
-| 其它 | 类型判断、日期、数组、url、dom、防抖节流、金额/千分位、手机号校验等(见 `packages/utils/utils.js`) |
+| 模块                               | 说明                                                               |
+| ---------------------------------- | ------------------------------------------------------------------ |
+| `$utils.env`                       | 环境配置对象                                                       |
+| `$utils.ls`                        | 本地存储(命名空间 `VITE_APP_SYS_SERVER_NAME`)                    |
+| `$utils.http`                      | axios 实例(token/`client-id` 注入、响应解包、登录超时、文件下载) |
+| `parseAppUrl` / `innerRedirect` 等 | 站内地址拼 base(支持子路径),外部 http(s) 原样                   |
+| 其它                               | 类型判断、日期、数组、url、dom、防抖节流、金额、手机号校验等       |
 
-另提供:`v-action:xxx` 权限指令(`packages/utils/action.js`),无权限时移除元素。用法:
-
-```html
-<a-button v-action="'add'">添加</a-button>
-<a v-action:edit>修改</a>
-```
+`v-action:xxx` 按钮级权限指令:`<a-button v-action="'add'">添加</a-button>`。
 
 ### 2.7 国际化
 
-- 语言包聚合:构建时扫描并合并
-  - `/packages/pages-components/*-i18n.js`
-  - `/packages/components/*-i18n.js`
-  - `/packages/layouts/*-i18n.js`
-  - `/src/views/**/*-i18n.js`
-  - key 取文件名前缀,例如 `layouts.add`、`components.upload`。
-- `$l(name, key)` 规则:
+语言包构建时聚合 `packages/**/*-i18n.js` 与 `src/views/**/*-i18n.js`,key 为文件名前缀(如 `layouts.add`、`components.upload`)。
 
-```text
-中文模式 / 未开启国际化  ->  返回 name(中文)
-英文模式 + 传了 key       ->  先取 lang.en[key],取不到则把 key 当英文返回
-英文模式 + 未传 key       ->  走中文->英文兜底字典(packages/locales/lang/dict.js)
-```
-
-- 基座已完成常用文案的兜底字典,业务 <span style="color:#389e0d;font-weight:700">无需处理</span> 即可切换英文。
-- antd 组件自身的国际化由 `a-config-provider` 的 `locale` 控制(`BasicLayout`/`App.vue`)。
+`$l(name, key)`:中文/未开启国际化 → 返回 `name`;英文模式传了 `key` → 取 `lang.en[key]`,取不到把 `key` 当英文;未传 `key` → 走中文→英文兜底字典(`packages/locales/lang/dict.js`)。
 
 ```html
-<span>{{ $l('添加') }}</span>
-<!-- 中文:添加 / 英文:Add -->
-<span>{{ $l('账户密码登录', 'account password') }}</span>
+<span>{{ $l('添加') }}</span> <span>{{ $l('账户密码登录', 'account password') }}</span>
 ```
 
-> <span style="color:#d46b08;font-weight:700">提示</span>:第二个参数若是 key 路径(如 `page-components.xxx`),必须先在对应 `*-i18n.js` 里定义;否则会<span style="color:#d4380d">原样显示该 key 字符串</span>。直接写英文字面量则无需定义。
+> `key` 为路径时需先在对应 `*-i18n.js` 定义,否则原样显示该 key。antd 自身语言由 `a-config-provider` 的 `locale` 控制。
 
 ### 2.8 主题
 
-主题分为两套并用,**颜色定义只由基座维护**:
-
-- 定义(基座):`packages/config/web-config.js` 的 `VITE_APP_THEME`(每套含 `color/lightColor/darkColor/borderColor/bgColor`)。
-- 选择(业务):`VITE_APP_THEME_VALUE`(如 `blue`/`green`/`orange`)。基座会强制以自身 `VITE_APP_THEME` 为准,业务/config.json 传入的 `VITE_APP_THEME` 会被忽略。
+定义只由基座维护:`packages/config/web-config.js` 的 `VITE_APP_THEME`(每套含 `color/lightColor/darkColor/borderColor/bgColor`);业务只用 `VITE_APP_THEME_VALUE` 选(`blue`/`green`/`orange`)。业务/config.json 传入的 `VITE_APP_THEME` 会被忽略。
 
 生效方式:
 
-1. **antd 组件**:由 `a-config-provider` 的 token(`colorPrimary`/`colorLink`)驱动,来源为选中主题的 `color`。
-2. **CSS 变量 + class**:启动时自动把选中主题写入 `:root` 变量:
-
-```text
---s-color        主题主色
---s-light-color  浅色
---s-dark-color   深色
---s-border-color 边框色
---s-bg-color     背景色
-```
-
-并提供现成工具类(`packages/style/theme.less`):
-
-```less
-.s-theme-bg          { background-color: var(--s-bg-color); }
-.s-theme-color       { color: var(--s-color); }
-.s-theme-border      { border-color: var(--s-bg-color); }
-.s-theme-border-top  { border-top-color: var(--s-color); }
-.s-theme-icon-bg     { background-color: var(--s-border-color); }
-```
-
-3. **body 主题类**:`body` 会加上 `theme-<VITE_APP_THEME_VALUE>`(如 `theme-blue`),供自定义 CSS 使用。
-
-业务自定义样式直接使用变量即可:
+1. **antd**:`a-config-provider` token(`colorPrimary`/`colorLink`)。
+2. **CSS 变量**:启动时把选中主题写入 `:root`:`--s-color`、`--s-light-color`、`--s-dark-color`、`--s-border-color`、`--s-bg-color`;并内置工具类 `.s-theme-bg`、`.s-theme-color`、`.s-theme-border`、`.s-theme-border-top`、`.s-theme-icon-bg`。
+3. **body 类**:`theme-<VITE_APP_THEME_VALUE>`(如 `theme-blue`)。
 
 ```css
 .my-box {
   color: var(--s-color);
   background: var(--s-bg-color);
-  border: 1px solid var(--s-border-color);
 }
 ```
 
-> <span style="color:#389e0d;font-weight:700">新增主题</span>:在基座 `VITE_APP_THEME` 里加一套(如 `purple`),业务把 `VITE_APP_THEME_VALUE` 设为 `purple`,antd 与 `var(--s-*)` 会自动跟随,无需改 less。
-
-### 2.9 API(`packages/api`)
-
-| 文件 | 内容 |
-| --- | --- |
-| `login.js` | `login`、`info`、`getCode`、`verify`、`rsaPublicKey`、验证码/短信/登录配置等 |
-| `common.js` | 组织树、字典分页、用户/岗位按 id 查询、文件预览地址等 |
-| `upload.js` | 上传/下载/在线预览 |
-| `workbench.js` | 工作台示例分页/导出/导入等 |
-
-### 2.10 页面组件(`packages/pages-components`)
-
-`login.vue`、`login-common/LoginForm.vue`、`workbench.vue`、`todo.vue`、`message.vue`、`403.vue`、`404.vue`、`500.vue`、`docs.vue`。
-
-### 2.11 内置文档(HTML)
+> 新增主题:基座 `VITE_APP_THEME` 加一套,业务 `VITE_APP_THEME_VALUE` 选它,antd 与 `var(--s-*)` 自动跟随。
 
-基座内置了一个文档页,数据源就是本文件 `docs/*.md`:
+### 2.9 API / 页面组件 / 其它
 
-- **应用内页面**:路由 `/docs`,`packages/pages-components/docs.vue` 用 `?raw` 内联 md 并渲染。该路由 `meta: { public: true, hidden: true }` 且 `layout: false`:
+- `packages/api`:`login.js`(登录、`getCode`、`verify`、`rsaPublicKey`、`getLoginConfig` 等)、`common.js`、`upload.js`、`workbench.js`。
+- `packages/pages-components`:`login.vue`、`login-common/LoginForm.vue`、`workbench.vue`、`todo.vue`、`message.vue`、`403/404/500.vue`、`docs.vue`、`components-doc.vue`。
+- 静态资源 `packages/static/*`;样式 `packages/style/*`;antd 图标、axios、dayjs、moment、pinia、vue-router、vue-i18n、jodit、vue-cropper、vuedraggable、html2canvas、crypto-js、jsencrypt、nprogress、qs、lodash.\* 等已内置。
 
-  - <span style="color:#389e0d">免登录、无权限控制</span>;
-  - <span style="color:#d46b08">不显示在侧边菜单</span>;
-  - 应用启动时会在**浏览器控制台**打印其地址(`公开页面地址: <origin>/docs`,且会拼接 `VITE_APP_BASE_URL`)。
+### 2.10 登录 / 单点
 
-- **独立 HTML 预览**(开发/预览服务):`vite-plugins/docs-viewer.js` 在 `/docs-preview` 提供整页 HTML 预览(方便直接浏览器打开)。
-
-- <span style="color:#1677ff">业务同样可用</span>:`/docs` 是基座内置静态页,随依赖提供,业务重装依赖后自动拥有,访问地址为 `<业务base>/docs`。
-
-### 2.12 其它
-
-- 静态资源:`packages/static/img`、`packages/static/svg`(SVG 通过 `vite-plugin-svg-icons` 以 `icon-[name]` 注入)。
-- 样式:`packages/style/common.less`、`theme.less`、`nprogress.less`;构建时全局注入 `src/assets/main.less`。
-- 第三方依赖(基座内置,<span style="color:#389e0d">业务无需重复安装</span>):ant-design-vue、axios、dayjs、moment、pinia、vue-router、vue-i18n、jodit、vue-cropper、vuedraggable、html2canvas、crypto-js、jsencrypt、nprogress、qs、lodash.* 等。
+- 登录页 `/login/index`:账号密码登录;登录失败达 `getLoginConfig` 策略(`enabled` + `codeThreshold`)时出现**图片验证码**(`/user/verify`),`verificationCode` 原文提交 + `verificationCodeId`。
+- 单点回调:URL 带 `code` 时由**守卫**调 `getCode(code)` 换 token → 存 `$utils.ls` → 去掉 code 整页刷新(与参照项目一致)。
+- 关联配置:`VITE_APP_CLIENT_ID` 必须等于业务在认证中心的 client;接口网关用 `VITE_APP_PORTAL_SERVER_NAME`。
 
 ---
 
-## 三、构建与发布
+## 三、构建与配置
 
-### 3.1 构建
+### 3.1 构建与发布
 
 ```bash
-npm run dev      # 本地开发(基座自身调试壳)
-npm run build    # 生产构建 + 复制产物 + 推送 git
-npm run lint     # eslint
+npm run dev      # 基座本地开发
+npm run build    # lib 构建 + 复制 docs/vite-plugins/package.json 到 dist + git push
+npm run lint
 ```
 
-> 基座构建 <span style="color:#d4380d;font-weight:700">不 drop console</span>,因为 `$utils`、i18n 等调试输出由运行时 `VITE_CONFIG_MODE` 控制;若构建期 drop,会把业务 dev 需要的输出一起删掉。业务侧构建才 drop console。
+> 基座构建 **不 drop console**(`$utils`/i18n 调试输出由运行时 `VITE_CONFIG_MODE` 控制);业务构建才 drop。
 
-### 3.2 构建产物(`vite.config.js`,lib 模式)
+产物:入口 `./packages/index.js`,`vue` external,输出 `dist/lib`,打包内容为**入口依赖图**(不是整个项目);`package.json` 的 `files: ["lib","docs","vite-plugins"]`。
 
-- 入口:`./packages/index.js`;`vue` 为 external;
-- 输出目录:`dist/lib`;
-- 打包内容 = <span style="color:#d4380d;font-weight:700">入口依赖图</span>(`packages/` 被引用部分 + `src/assets/main.less` + `public` 静态文件),<span style="color:#d4380d;font-weight:700">不是整个项目</span>;`src/` 其余演示代码、`index.html`、`vite.config.js` 不打包;
-- 产物结构:
+### 3.2 配置来源与优先级
 
 ```text
-dist/
-├─ lib/
-│  ├─ js/            # 入口与异步 chunk(index.js、docs.js、SEditor.js 等)
-│  ├─ css/style.css  # 含主题工具类 .s-theme-* 与 --s-* 兜底
-│  ├─ config.json    # 构建时生成(默认环境)
-│  └─ favicon.ico
-├─ docs/             # 说明文档
-├─ vite-plugins/     # docs-viewer 插件
-└─ package.json
+基座默认 defaultEnv  <  业务 web-config.js  <  .env.[mode](构建时写入 config.json)  <  部署 config.json(运行时覆盖)
 ```
 
-`package.json` 的 `files: ["lib", "docs", "vite-plugins"]`。
-
-### 3.3 config.json(运行时配置)
-
-- 业务构建时由 `vite-plugin-generate-file` 生成:`{ _hash, ...web-config字段, ...loadEnv(.env*), VITE_CONFIG_MODE }`;
-- 输出到站点根目录(子路径部署时为 `<base>config.json`);
-- 应用启动时 `loadRemoteConfig()` 会 `fetch` 它并覆盖 `web-config`(见 4.4),部署后可直接修改而 <span style="color:#389e0d">无需重新打包</span>;
-- `.env` 的值都是字符串,基座启动时会把 `"true"/"false"` 自动归一为布尔,避免 `"false"` 被当成真值。
-
-### 3.4 发布
-
-`npm run build` 会依次执行:`vite build` → 复制 `package.json`/`docs`/`vite-plugins` 到 `dist/` → 在 `dist/` 内 `git init/add/commit` → `git push -f` 到 `sapit-ui-plus` 仓库。业务方通过 git 依赖安装。
-
-### 3.5 一键更新脚本
-
-工程根目录提供:
-
-- `update-and-start.ps1` / `update-and-start.cmd`(Win)
-- 功能:① 基座构建并推送;② 清理业务 `node_modules/.vite`、`node_modules/sapit-ui-plus` 及各种锁文件(`package-lock.json`/`yarn.lock`/`pnpm-lock.yaml`/`node_modules/.package-lock.json`);③ `npm install`。
-- <span style="color:#d4380d;font-weight:700">不会自动启动项目</span>,需自行 `npm run dev`。
-- 参数:`-SkipBuild`(跳过构建)、`-CleanCache`(额外清 npm 缓存)。
-
-> <span style="color:#d4380d;font-weight:700">注意</span>:锁文件会把 git 依赖钉在旧 commit,脚本每次都会删除;手动更新时也要删,否则 `npm install` 装回旧包。
-
----
+- `web-config.js`:可写默认值或 `import.meta.env.VITE_APP_*`;
+- `.env` / `.env.[mode]`:各环境一套(dev/test/uat/prod),由业务 `vite.config.js` 写入 `config.json`;
+- `config.json`:站点根(子路径为 `<base>config.json`),启动时 `loadRemoteConfig()` 拉取并覆盖,**部署后可直接改、无需重打包**;`.env` 值为字符串,基座会把 `"true"/"false"` 归一为布尔。
 
 ## 四、业务项目接入
 
 ### 4.1 安装
 
 ```json
-{
-  "dependencies": {
-    "sapit-ui-plus": "git+http://124.93.235.117:6010/sapit/sapit-ui-plus.git"
-  }
-}
+{ "dependencies": { "sapit-ui-plus": "git+http://124.93.235.117:6010/sapit/sapit-ui-plus.git" } }
 ```
 
-> 地址用**单斜杠**(`...:6010/sapit/...`);双斜杠会报 `repository not found`。
+> 地址用**单斜杠**;双斜杠会 `repository not found`。
 
 ### 4.2 入口 `main.js`
 
@@ -352,34 +214,19 @@ async function init() {
   const pages = import.meta.glob('@/views/**/*.vue')
   const app = createApp(App)
   app.use(SapitUiPlus)
-  // app-config 为构建期配置(含组件/函数),与 web-config 合并后交给基座
   await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages)
   app.mount('#app')
 }
 init()
 ```
 
-- `config`:环境配置(见 4.3);
-- `appConfig`:登录/首页覆盖、静态路由、语言包(见 4.5/4.6/4.8),**不进入 config.json**;
-- `pages`:业务所有页面,用于动态路由按 `hrefs` 匹配组件。
-
-### 4.3 配置来源与优先级
-
-```text
-基座默认 defaultEnv  <  业务 web-config.js  <  业务 .env.[mode](构建时写入 config.json)  <  部署 config.json(运行时覆盖)
-```
-
-- `web-config.js`:可放默认值,也可引用 `import.meta.env.VITE_APP_*`;
-- `.env` / `.env.[mode]`:按打包环境给值(dev/test/uat/prod 各一套),构建时由 `vite.config.js` 写入 `config.json`;
-- <span style="color:#d46b08">注意</span>:`VITE_APP_THEME`(主题定义)只由基座提供,业务只写 `VITE_APP_THEME_VALUE`。
-
-### 4.4 运行时配置 config.json
-
-应用启动时自动请求 `${VITE_APP_BASE_URL}config.json`(3 秒超时,失败静默回退),命中后覆盖前述配置。适合运维按环境调整且无需重新打包。<span style="color:#389e0d">请求失败不影响启动。</span>
+- `config`:环境配置(web-config);
+- `appConfig`:构建期配置(登录/首页覆盖、静态路由、语言包),**不进入 config.json**;
+- `pages`:业务所有页面,用于动态路由按 `hrefs` 匹配。
 
-### 4.5 自定义登录页 / 首页
+### 4.3 登录页 / 首页覆盖
 
-在 `src/config/app-config.js`:
+`app-config.js`:
 
 ```js
 export default {
@@ -390,12 +237,9 @@ export default {
 }
 ```
 
-- 默认:基座登录页(`pages-components/login.vue`)与基座首页(`pages-components/todo.vue`);
-- 配置了就用自己的,<span style="color:#d46b08">不配置则用基座默认</span>。
+不配置则用基座默认(`pages-components/login.vue`、`todo.vue`)。
 
-### 4.6 静态页面 `staticRoutes`
-
-不依赖后端菜单的前端页面,在 `app-config.js` 配置:
+### 4.4 静态页面 `staticRoutes`
 
 ```js
 export default {
@@ -404,120 +248,77 @@ export default {
       path: '/help',
       name: 'Help',
       component: () => import('@/views/help/index.vue'),
-      meta: { title: '帮助' } // hidden: true 不在菜单显示;public: true 免登录
+      meta: { title: '帮助' } // hidden: 不进菜单;public: 免登录
     }
   ]
 }
 ```
 
-可选字段:
-
-- `meta.title`:菜单名(不填用 `name`);
-- `meta.hidden`:不在侧边菜单显示;
-- `meta.public`:免登录、无权限(守卫直接放行);
-- `layout: false` 或 `raw: true`:不包 `BasicLayout`(页面自带布局时用,如 `/docs`);
-- 与基座内置同 `path` 时,业务的配置覆盖基座内置。
-
-### 4.7 业务页面与菜单(动态路由)
-
-- 后端菜单的 `hrefs` 需能匹配到业务 `views` 的路径(或组件名),匹配到即用业务页面渲染,匹配不到回退 404;
-- 页面组件放在 `src/views/**`,通过 `pages` 传入即可被动态路由识别;
-- 侧边菜单渲染「后端菜单生成的动态路由 + `staticRoutes`」;基座常量菜单(工作台/待办/消息)默认不进入侧边菜单。
-
-### 4.8 国际化
-
-- 继承:基座语言包随依赖提供,业务可直接用基座 key,例如 `$l('添加', 'layouts.add')`、`$l('点击上传', 'components.upload')`;
-- 使用:`this.$l(...)`、全局 `$l(...)`、`this.$i18n.global.t(...)` 均可;
-- 扩展:在 `app-config.js` 传 `locales`(深合并),用法 `$l('标题','custom.title')`;
-- <span style="color:#d4380d;font-weight:700">说明</span>:业务自身的 `*-i18n.js` **不会**被基座聚合(聚合发生在基座构建时),如需模块化聚合,业务可在入口自行 `import.meta.glob` 后作为 `locales` 传入。
-
-### 4.9 主题
-
-- 业务 <span style="color:#d46b08">只需选主题</span>:`.env` 里 `VITE_APP_THEME_VALUE=blue|green|orange`;
-- 自定义样式用 `var(--s-color)`、`var(--s-bg-color)` 等,或直接用 `.s-theme-bg` 等工具类;
-- 主题定义(`VITE_APP_THEME`)只在基座改;业务/config.json 传入的会被忽略。
-
-### 4.10 子路径部署(示例 `/monitor/`)
-
-1. `.env`(及对应环境文件):
-   ```env
-   VITE_APP_BASE_URL=/monitor/
-   ```
-2. 业务 `vite.config.js` 的资源前缀自动取该值:
-   ```js
-   base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/'
-   ```
-3. 基座路由 history base、`$push`/`$open`、`redirectLogin`、`parseAppUrl` 都会读取 `VITE_APP_BASE_URL`,自动带上 `/monitor/`;
-4. nginx(站点目录示例 `/home/project/tmp/dist`):
-   ```nginx
-   location /monitor/ {
-       alias /home/project/tmp/dist/;
-       index index.html;
-       try_files $uri $uri/ /monitor/index.html;
-   }
-   location = /monitor/config.json {
-       alias /home/project/tmp/dist/config.json;
-       add_header Cache-Control "no-store";
-   }
-   ```
-5. 访问 `http://<服务器>:<port>/monitor/`;前端路由(如 `/monitor/docs`)刷新靠 `try_files` 回退。
-
-> <span style="color:#d4380d;font-weight:700">要点</span>:`createWebHistory` 的 base、Vite 的 `base`、`window.location` 跳转三者必须都用 `/monitor/`,否则资源或跳转 404。
-
-### 4.11 使用基座组件与全局方法
+`layout: false` / `raw: true` 时不包 `BasicLayout`;同 `path` 时业务覆盖基座内置。
+
+### 4.5 业务页面与菜单
+
+后端菜单 `hrefs` 需匹配业务 `views` 路径(或组件名);页面放 `src/views/**` 即可被动态路由识别。侧边菜单渲染「动态菜单 + `staticRoutes`」,基座常量菜单不进菜单。
+
+### 4.6 国际化 / 主题
+
+- 国际化:继承基座语言包,直接用 `$l('中文','English')` 或基座 key;扩展在 `appConfig` 传 `locales`(深合并)。业务自身 `*-i18n.js` 不会被基座聚合。
+- 主题:只改 `VITE_APP_THEME_VALUE`;样式用 `var(--s-*)` 或 `.s-theme-*`。
+
+### 4.7 子路径部署(示例 `/monitor/`)
+
+1. `.env`:`VITE_APP_BASE_URL=/monitor/`;
+2. 业务 `vite.config.js`:`base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/'`;
+3. 基座路由 base、`$push`/`$open`、`redirectLogin`、`parseAppUrl` 均读该值自动带前缀;
+4. nginx:
+
+```nginx
+location /monitor/ {
+    alias /home/project/tmp/dist/;
+    index index.html;
+    try_files $uri $uri/ /monitor/index.html;
+}
+location = /monitor/config.json {
+    alias /home/project/tmp/dist/config.json;
+    add_header Cache-Control "no-store";
+}
+```
+
+> `createWebHistory` base、Vite `base`、`window.location` 跳转三者必须都是 `/monitor/`(带尾斜杠)。
+
+### 4.8 使用组件与权限
 
 ```html
 <template>
   <s-list-layout :columns="columns" :loadData="page" title="示例" />
   <s-user-select v-model:value="ids" />
   <a-button v-action="'add'">添加</a-button>
-  <span class="s-theme-color">{{ $l('添加') }}</span>
 </template>
 ```
 
-```js
-export default {
-  mounted() {
-    this.$message.success('ok')
-    this.$utils.http({ url: '/xxx' })
-    this.$filter.dateFormat(Date.now())
-    this.$push('/detail', { id: 1 }) // 自动拼接 base
-  }
-}
-```
-
-### 4.12 权限
-
-后端下发 `permissions` 后,基座写入 `permission`,模板用 `v-action:xxx` 控制按钮级权限。
+后端下发 `permissions` 后基座写入 `permission`,用 `v-action:xxx` 控制按钮级权限。文档访问:`<业务base>/docs`、`<业务base>/components`。
 
 ---
 
 ## 五、注意事项
 
-> <span style="color:#d4380d;font-weight:700">以下为高频踩坑点,务必注意。</span>
-
-1. <span style="color:#d4380d;font-weight:700">依赖是预构建产物</span>:业务使用的是 `sapit-ui-plus` 的 `lib`,基座改动必须 `npm run build` 推送并在业务重新安装依赖后才生效;基座自身 `npm run dev` 立即生效。
-2. <span style="color:#d4380d;font-weight:700">锁文件会钉住旧提交</span>:更新依赖前删掉 `package-lock.json`、`yarn.lock`、`node_modules/.package-lock.json`,否则 `npm install` 装回旧包。
-3. <span style="color:#d4380d;font-weight:700">git 依赖地址用单斜杠</span>:`...:6010/sapit/sapit-ui-plus.git`。
-4. <span style="color:#d46b08;font-weight:700">路由刷新</span>:通配路由不使用 redirect,守卫在注册动态路由后重新导航,保证刷新动态地址不掉 404。
-5. <span style="color:#d46b08;font-weight:700">子路径部署</span>:`VITE_APP_BASE_URL` 与 Vite `base` 必须一致(如 `/monitor/`),且带尾斜杠。
-6. <span style="color:#d46b08;font-weight:700">运行时 config.json</span>:来源是 `web-config + .env*`;部署后改它可覆盖;`.env` 值为字符串,布尔已在基座归一。
-7. <span style="color:#d46b08;font-weight:700">全局组件命名</span>:按文件名注册,命名冲突时后者覆盖;`.jsx` 组件(如 `Table`)需手动引入。
-8. <span style="color:#389e0d;font-weight:700">国际化</span>:基座已内置中文→英文兜底字典,常规文案无需业务处理;新增文案建议用 `$l('中文','English')` 或业务 `locales`。
-9. <span style="color:#d46b08;font-weight:700">主题</span>:只改 `VITE_APP_THEME_VALUE`;定义在基座。组件取色用 `var(--s-*)`/`.s-theme-*`,antd 由 `a-config-provider` token 驱动。
+1. <span style="color:#d4380d;font-weight:700">依赖是预构建产物</span>:基座改动需 `npm run build` 推送且业务重装依赖才生效;基座 dev 立即生效。
+2. <span style="color:#d4380d;font-weight:700">锁文件会钉住旧提交</span>:更新前删 `package-lock.json`、`yarn.lock`、`node_modules/.package-lock.json`。
+3. <span style="color:#d46b08;font-weight:700">子路径</span>:`VITE_APP_BASE_URL` 与 Vite `base` 保持一致且带尾斜杠。
+4. <span style="color:#d46b08;font-weight:700">全局组件命名</span>:按文件名注册,冲突后者覆盖;`.jsx`(如 `Table`)需手动引入。
+5. <span style="color:#d46b08;font-weight:700">主题 / 国际化</span>:定义在基座,业务只选主题、只写文案。
 
 ---
 
 ## 六、常见全局方法速查
 
-| 调用 | 作用 |
-| --- | --- |
-| `$l('中文'[, key])` | 国际化 |
+| 调用                                        | 作用                         |
+| ------------------------------------------- | ---------------------------- |
+| `$l('中文'[, key])`                         | 国际化                       |
 | `$push(path, query)` / `$open(path, query)` | 跳转 / 新窗口(自动拼 base) |
-| `$message.*` / `$modal.*` / `$notice.*` | 轻提示 / 弹窗 / 通知 |
-| `this.$utils.ls.get/set/clear` | 本地存储 |
-| `this.$utils.http(config)` | 发起请求 |
-| `$filter.dateFormat(v, fmt)` | 日期格式化 |
-| `v-action:code` | 按钮级权限 |
-| `var(--s-color)` / `.s-theme-color` | 主题色(CSS 变量 / 工具类) |
-| `$staticRoutes` | 当前静态页面路由 |
+| `$message.*` / `$modal.*` / `$notice.*`     | 轻提示 / 弹窗 / 通知         |
+| `this.$utils.ls.get/set/clear`              | 本地存储                     |
+| `this.$utils.http(config)`                  | 发起请求(默认 POST)        |
+| `$filter.dateFormat(v, fmt)`                | 日期格式化                   |
+| `v-action:code`                             | 按钮级权限                   |
+| `var(--s-color)` / `.s-theme-color`         | 主题色(CSS 变量 / 工具类)  |

+ 1 - 1
lib/config.json

@@ -1 +1 @@
-{"_hash":1789892660593,"VITE_APP_PROJECT_NAME":"前端项目架构","VITE_APP_VERSION":"v1.0","VITE_APP_JSS_LICENSE":"","VITE_APP_TITLE":"平台","VITE_APP_BASE_URL":"/","VITE_APP_FOOTER_VISIBLE":false,"VITE_APP_LANG_ENABLE":false,"VITE_APP_LANG":"zh","VITE_APP_API_PATH":"/apig","VITE_APP_SYS_SERVER_NAME":"monitor","VITE_APP_MESSAGE_SERVER_NAME":"message","VITE_APP_PORTAL_SERVER_NAME":"portal","VITE_APP_FLOW_SERVER_NAME":"flow","VITE_APP_CLIENT_ID":"mm0001","VITE_APP_PREVIEW_ONLINE":"/filePreview/onlinePreview?url=","VITE_APP_WEB_SITE":"https://sapit.com.cn/#/home","VITE_APP_LOGIN_CASE_NAME":"辽ICP备14008719号-2","VITE_APP_BASE_CASE_NAME":"辽ICP备14008719号-2","VITE_APP_SOCKET_URL":"/","VITE_CONFIG_MODE":false,"VITE_APP_API_BASE_URL":"http://192.168.200.6:7022","VITE_APP_API_FILE_URL":"/","VITE_APP_MENU_THEME":"dark","VITE_APP_MENU_BAR":"left","VITE_APP_LOGIN_PATH_THEME":"3","VITE_APP_THEME_VALUE":"blue","VITE_APP_THEME":{"blue":{"name":"blue","color":"#1677FF","lightColor":"\t#6495ED","darkColor":"#00008B","borderColor":"#B0C4DE","bgColor":"#f0f2f5"},"green":{"name":"green","color":"#00b96b","lightColor":"#90EE90","darkColor":"#3CB371","borderColor":"#98FB98","bgColor":"#F0FFF0"},"orange":{"name":"orange","color":"#FFA500","lightColor":"\t#FFE4B5","darkColor":"#FF8C00","borderColor":"#FFDEAD","bgColor":"#FFEFD5"}},"VITE_APP_LOGIN_PATH":"/login","VITE_APP_DEFAULT_PATH":"/workplace/index","VITE_USER_NODE_ENV":"production"}
+{"_hash":1789894405204,"VITE_APP_PROJECT_NAME":"前端项目架构","VITE_APP_VERSION":"v1.0","VITE_APP_JSS_LICENSE":"","VITE_APP_TITLE":"平台","VITE_APP_BASE_URL":"/","VITE_APP_FOOTER_VISIBLE":false,"VITE_APP_LANG_ENABLE":false,"VITE_APP_LANG":"zh","VITE_APP_API_PATH":"/apig","VITE_APP_SYS_SERVER_NAME":"monitor","VITE_APP_MESSAGE_SERVER_NAME":"message","VITE_APP_PORTAL_SERVER_NAME":"portal","VITE_APP_FLOW_SERVER_NAME":"flow","VITE_APP_CLIENT_ID":"mm0001","VITE_APP_PREVIEW_ONLINE":"/filePreview/onlinePreview?url=","VITE_APP_WEB_SITE":"https://sapit.com.cn/#/home","VITE_APP_LOGIN_CASE_NAME":"辽ICP备14008719号-2","VITE_APP_BASE_CASE_NAME":"辽ICP备14008719号-2","VITE_APP_SOCKET_URL":"/","VITE_CONFIG_MODE":false,"VITE_APP_API_BASE_URL":"http://192.168.200.6:7022","VITE_APP_API_FILE_URL":"/","VITE_APP_MENU_THEME":"dark","VITE_APP_MENU_BAR":"left","VITE_APP_LOGIN_PATH_THEME":"3","VITE_APP_THEME_VALUE":"blue","VITE_APP_THEME":{"blue":{"name":"blue","color":"#1677FF","lightColor":"\t#6495ED","darkColor":"#00008B","borderColor":"#B0C4DE","bgColor":"#f0f2f5"},"green":{"name":"green","color":"#00b96b","lightColor":"#90EE90","darkColor":"#3CB371","borderColor":"#98FB98","bgColor":"#F0FFF0"},"orange":{"name":"orange","color":"#FFA500","lightColor":"\t#FFE4B5","darkColor":"#FF8C00","borderColor":"#FFDEAD","bgColor":"#FFEFD5"}},"VITE_APP_LOGIN_PATH":"/login","VITE_APP_DEFAULT_PATH":"/workplace/index","VITE_USER_NODE_ENV":"production"}

Plik diff jest za duży
+ 0 - 0
lib/css/style.css


Plik diff jest za duży
+ 44 - 45
lib/js/docs.js


Plik diff jest za duży
+ 0 - 0
lib/js/index.js


Niektóre pliki nie zostały wyświetlone z powodu dużej ilości zmienionych plików