| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175 |
- import { D as T } from "./docs-back-top.js";
- import { resolveComponent as v, openBlock as P, createElementBlock as S, Fragment as A, createVNode as c, withCtx as p, createElementVNode as _, createTextVNode as m, toDisplayString as f } from "vue";
- import { n as I } from "./index2.js";
- import { _ as L } from "./index16.js";
- const y = (n = "") => String(n).replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">"), x = (n = "") => String(n).replace(/[^\w\u4e00-\u9fa5-]/g, ""), u = (n = "") => {
- const t = [], r = [];
- let e = String(n);
- return e = e.replace(/`([^`]+)`/g, (o, i) => (t.push(`<code>${y(i)}</code>`), `\0C${t.length - 1}\0`)), e = e.replace(/<\/?span[^>]*>/g, (o) => (r.push(o), `\0S${r.length - 1}\0`)), e = y(e), e = e.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>'), e = e.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>"), e = e.replace(/\u0000C(\d+)\u0000/g, (o, i) => t[+i]), e = e.replace(/\u0000S(\d+)\u0000/g, (o, i) => r[+i]), e;
- }, w = (n = "") => n.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((t) => t.trim()), j = (n = "") => /^\s*\|?[\s:|-]+\|?\s*$/.test(n) && n.includes("-"), E = (n = "") => {
- const t = String(n).replace(/\r\n/g, `
- `).split(`
- `), r = t.length;
- let e = 0, o = "", i = null;
- const a = () => {
- i && (o += `</${i}>
- `, i = null);
- };
- for (; e < r; ) {
- const s = t[e], h = s.match(/^```(\w*)\s*$/);
- if (h) {
- a();
- const l = h[1];
- e++;
- const d = [];
- for (; e < r && !/^```\s*$/.test(t[e]); )
- d.push(t[e]), e++;
- e++, o += `<pre class="docs-code" data-lang="${l}"><code>${y(d.join(`
- `))}</code></pre>
- `;
- continue;
- }
- if (/^\s*$/.test(s)) {
- a(), e++;
- continue;
- }
- if (/^-{3,}\s*$/.test(s)) {
- a(), o += `<hr/>
- `, e++;
- continue;
- }
- const g = s.match(/^(#{1,6})\s+(.*)$/);
- if (g) {
- a();
- const l = g[1].length, d = g[2].trim();
- o += `<h${l} id="docs-${x(d)}">${u(d)}</h${l}>
- `, e++;
- continue;
- }
- if (/^>\s?/.test(s)) {
- a();
- const l = [];
- for (; e < r && /^>\s?/.test(t[e]); )
- l.push(t[e].replace(/^>\s?/, "")), e++;
- o += `<blockquote>${E(l.join(`
- `))}</blockquote>
- `;
- continue;
- }
- if (/^\s*\|/.test(s) && e + 1 < r && j(t[e + 1])) {
- a();
- const l = w(s);
- e += 2;
- const d = [];
- for (; e < r && /^\s*\|/.test(t[e]); )
- d.push(w(t[e])), e++;
- o += "<table><thead><tr>" + l.map((b) => `<th>${u(b)}</th>`).join("") + "</tr></thead><tbody>" + d.map((b) => "<tr>" + b.map((k) => `<td>${u(k)}</td>`).join("") + "</tr>").join("") + `</tbody></table>
- `;
- continue;
- }
- if (/^\s*[-*]\s+/.test(s)) {
- i !== "ul" && (a(), o += `<ul>
- `, i = "ul"), o += `<li>${u(s.replace(/^\s*[-*]\s+/, ""))}</li>
- `, e++;
- continue;
- }
- if (/^\s*\d+\.\s+/.test(s)) {
- i !== "ol" && (a(), o += `<ol>
- `, i = "ol"), o += `<li>${u(s.replace(/^\s*\d+\.\s+/, ""))}</li>
- `, e++;
- continue;
- }
- a(), o += `<p>${u(s.trim())}</p>
- `, e++;
- }
- return a(), o;
- }, C = "# sapit-ui 基座说明与业务使用文档\n\n> 适用工程:<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\">sapit-base-template</span>(业务示例)\n>\n> 本文档也是基座内置文档页 `/docs` 与组件页 `/components` 的数据源。\n\n---\n\n## 目录\n\n- [一、总览](#docs-一总览)\n- [二、基座提供的内容](#docs-二基座提供的内容)\n- [三、构建与配置](#docs-三构建与配置)\n- [四、业务项目接入](#docs-四业务项目接入)\n- [五、注意事项](#docs-五注意事项)\n- [六、在线文档入口](#docs-六在线文档入口)\n\n---\n\n## 一、总览\n\n### 1.1 五者关系\n\n| 工程 | 角色 | 说明 |\n| --------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |\n| `sapit-ui-framework` | <span style=\"color:#d4380d\">基座(源码)</span> | 内置组件与常用依赖的库工程,Vite lib 模式打包 |\n| `sapit-ui-plus` | <span style=\"color:#d46b08\">发布产物</span> | 基座 `dist` 推送后的 git 仓库(`lib/`、`docs/`、`vite-plugins/`) |\n| `sapit-base-template` | <span style=\"color:#389e0d\">业务使用者</span> | 以 `sapit-ui-plus` git 依赖为底层,编写业务页面/配置 |\n\n```text\nsapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template\n```\n\n### 1.2 依赖包结构\n\n业务装的 `sapit-ui-plus` 只有运行时需要的内容(不是基座源码工程):\n\n```text\nnode_modules/sapit-ui-plus/\n├─ lib/ # 编译产物:js / css / 图片,业务 import 的就是它\n├─ docs/ # 本文档,由内置 /docs 页渲染\n├─ vite-plugins/ # 业务 vite.config.js 里按需引入的插件(如 sso-plugin)\n├─ static/ # 静态资源(登录页图片等)\n└─ package.json\n```\n\n业务只需要引三处:入口 `sapit-ui-plus`、样式 `sapit-ui-plus/lib/css/style.css`、按需的 `vite-plugins/*`。\n\n---\n\n## 二、基座提供的内容\n\n### 2.1 全局组件\n\n组件全部由基座**全局注册**,业务页面直接写标签即可,不需要 `import`、也不需要局部注册(如 `<s-modal>`、`<s-user-select>`、`<s-table>`)。\n\n| 分类 | 组件 |\n| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 布局类 | `SSkeletonLayout`(骨架布局:标题 + 按钮组 + 内容区)、`SListLayout`、`SListCardLayout`(卡片列表)、`SListTableTreeLayout`、`SSuperListLayout`(高级列表:列设置 + 高级筛选)、`SFormLayout`、`SPanelLayout`、`SCollapses`/`SCollapsesItem`、`SDrawer` |\n| 弹层类 | `SModal`、`SModalTemplate`、`ModalHeader`、`SIconModal`、`SImportModal`(批量导入) |\n| 表单/筛选 | `SForm`、`SFormItem`(多列 + `full` 独占整行)、`SExtendFieldsForm`/`SExtendFieldsFormItem`(动态扩展字段)、`SFilterWrap`、`SFilterItem`(`full` 独占整行)、`SFilterToolbar`(查询区外壳:主区 + 更多筛选折叠 + 条件重置)、`STableToolbar`(表格区外壳:表体高度自动贴合内容区,与 `SFilterToolbar` 成对使用)、`SFilterTableToolbar`(查询区 + 表格区组合件)、`SCascader`、`STree`、`STreeSelect`、`SDataRangeTreeSelect`(数据权限范围树)、`SUserSelect`、`SUserSelectButton`、`SChooseUser`(带数据权限选人弹窗)、`SBelowChoosePosition`(选岗位弹窗)、`SOfficeSelect`、`SIconSelect`(图标下拉,可搜索/多选)、`SIconSelectPopover`(图标网格面板)、`SIconModal`(图标浏览弹窗) |\n| 上传类 | `SFileUpload`、`SDraggerUpload`、`SCopperUpload`、`CropperModal` |\n| 展示/其它 | `STab`/`STabItem`(标签栏,超出宽度自动出左右箭头)、`SEditor`、`SEmpty`、`SIcon`、`SSvg`、`SAnchor`、`SColorPicker`、`SToggleLanguage`、`SettingFilter`、`SettingColumns`、`SSideMenu`/`STopMenu` |\n\n> **每个组件的 props / 事件 / 方法 / 插槽、可运行预览与示例代码,统一看内置组件页 `/components`**(另有「工具/配置」标签页,列出 web-config 全部配置项与 `$utils` 全部方法)。\n>\n> 几条使用口径:\n>\n> - 组件注册名是 **PascalCase**(`SForm` / `STable`),模板里写 `<SForm>` 或 `<s-form>` 都能解析,保持一致即可。\n> - `@ant-design/icons-vue` 图标已全部全局注册,并把图标集合挂在 `$icons`。\n> - 基座内部有几个不对外使用的辅助组件(如 `ModalHeader`、`CropperModal`、`SettingColumns` / `SettingFilter`),业务不要直接引用。\n\n### 2.2 全局属性 / 方法\n\n`$registerGlobalConfig` 执行后可用(`this.$xxx` / 模板 `$xxx` / `window.$xxx`):\n\n| 名称 | 说明 |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `$registerGlobalConfig(config, pages)` | 初始化入口(见 4.2) |\n| `$utils` | 工具类集合:`$utils.env` / `$utils.ls` / `$utils.http` 及通用方法 |\n| `env` | 合并后的环境配置(= `$utils.env`) |\n| `$i18n` / `$l(name)` | 国际化(见 2.7)。挂在 `globalProperties` 上:**模板里直接用** `$l('xx')`;`<script setup>` **脚本内**必须写 `window.$l('xx')`(setup 作用域没有 `this`) |\n| `$theme` / `$staticRoutes` / `$pinia` | 主题对象 / 静态路由列表 / 用户 store 实例 |\n| `$modal` / `$message` / `$notice` / `$confirm` | antd 的 `Modal` / `message` / `notification` / `Modal.confirm`(列表组件按钮 api 分支会调 `this.$confirm`) |\n| `$push(path, query)` / `$open(...)` | 站内跳转 / 新窗口(自动拼 `VITE_APP_BASE_URL`) |\n| `$filter` / `$icons` / `$socket` | 日期格式化 / 图标集合 / websocket 封装。`$icons` 是 `@ant-design/icons-vue` 全量按 **Pascal 名**注册的映射(`InfoCircleOutlined`),**同时挂在 `window.$icons`**(供 `$utils.iconOf` 在非组件上下文取用)。`<a-icon type=\"info-circle\">` 这类 antd v1 写法用 `$utils.iconOf('info-circle')` 换算;`SIcon` 的 `name` 只吃 Pascal 名 |\n| `$getPdf({ el, title })` | 页面导出 PDF(老项目 `Vue.prototype.getPdf` 的 Vue3 版)。截图容器与文件名显式传:`<a-button @click=\"$getPdf({ el: '#pdfDom', title: htmlTitle })\">导出</a-button>`。内部**动态 import** `html2canvas` + `jsPDF`,不点按钮不加载;A4 自动分页,返回 `Promise<boolean>`。可选 `fileName` / `scale` / `backgroundColor` / `beforeCapture` / `afterCapture` / `onError`。同时挂了无 `$` 的 `getPdf` 兼容老写法(默认容器 `#pdfDom`、标题取 `document.title`) |\n\n> 按钮级权限(`v-action` 指令 / `$utils.hasAction`)与 `$utils` 各方法见 2.6;主题色变量与 `.s-theme-*` 工具类见 2.8。\n\n### 2.3 布局\n\n业务页面默认跑在 `BasicLayout` 的内容区里,外层布局有三种:\n\n| 布局 | 用途 |\n| ------------- | ------------------------------------------------------------- |\n| `BasicLayout` | 顶栏 + 侧边/顶部菜单 + 内容区(动态路由、静态路由都默认包它) |\n| `UserLayout` | 登录、扫码、找回密码、激活这类免登录页面 |\n| `BlankLayout` | 只要一个空壳,不要菜单与顶栏 |\n\n**业务页面高度**:内容区高度由 `BasicLayout` 算好并透传给 `router-view`,页面根节点写 `height: 100%` 就会自动撑满。**不要自己写 `calc(100vh - 58px)` 这类减法**:顶栏高度、页脚、页签都会让这个数对不上,表现就是分页浮在中间或多出一条滚动条。\n\n页面主体用布局组件(`SListLayout` / `SFormLayout` / `SSkeletonLayout` / `SPanelLayout` …),它们自己吃掉剩余高度并在内部滚动,业务只写内容。\n\n**页面主体布局组件怎么选**:\n\n| 场景 | 用哪个 |\n| -------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| 标题 + 按钮 + 自定义内容(无表格/分页/表单) | `SSkeletonLayout`(自带标题条与权限按钮) |\n| 普通列表页 | `SListLayout` |\n| 卡片列表 | `SListCardLayout`(卡片网格 + 三插槽) |\n| 列表 + 左侧树 | `SListTableTreeLayout`(左侧树容器类名必须是 `.side.s-side-tree`) |\n| 带高级搜索/高级表格的列表 | `SSuperListLayout`(列设置 + 高级筛选) |\n| 新增/编辑/详情(路由式) | `SFormLayout`(`#form` 插槽放 `SForm`,`#footer-callback` 收 `save`/`cancel`/`prev`/`next`) |\n| 表单作为弹窗内容 | `SModal`(不要套 `SFormLayout`) |\n| 后端下发字段的动态表单 | `SExtendFieldsForm`(`data` + `defaultValue`,ref 调 `validate/clearValidate/getModel`) |\n| 数据权限范围选择 | `SDataRangeTreeSelect`(`autoSysConfig` 托管系统 `dataScope` 配置) |\n\n### 2.4 路由\n\n**常量路由**(`packages/router/index.js`):\n\n| 路径 | 说明 |\n| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |\n| `/login/index` | 登录页(默认基座,可被业务覆盖,见 4.3) |\n| `/login/:officeCode` | 同上,带单位编码进入(编码写入 `$utils.ls` 的 `officeCode`,见 2.10) |\n| `/user/qrCode`、`/user/forgotPassword`、`/user/activate` | 扫码登录 / 找回密码 / 账号激活三张独立页,父级 `/user` 带 `meta.public`,**登录前可达**(见 2.10) |\n| `/workplace/index` | 默认首页(`VITE_APP_DEFAULT_PATH`,可被覆盖) |\n| `/workbench/index`、`/message/index` | 工作台 / 消息 |\n| `/docs`、`/components` | 内置文档 / 组件页(`public` 免登录、`hidden` 不进菜单) |\n| `/404`、`/403`、`/500`、`/:pathMatch(.*)*` | 错误页;通配渲染 404(**不用 redirect**,保证刷新动态路由不掉 404),渲染位置与文案见 2.11 |\n\n> 错误页的触发规则、URL 参数、文案口径与改色方法见 [2.11 错误页](#docs-211错误页301403404500)。\n\n**静态路由**(`staticRoutes`,不依赖后端菜单):见 4.4。基座内置 `/docs`、`/components`。\n\n**动态路由**:登录后按后端 `menus` 生成路由树,根节点是 `BasicLayout`;叶子节点用菜单的 `hrefs` 匹配业务 `src/views/**` 下的页面路径(或组件名),匹配不到回退 404。\n\n**守卫**:公开页(`meta.public`)直接放行;实时读 token;未登录跳登录;已登录访问登录页/根跳默认首页;取用户信息失败清理并回登录页(避免 pending)。URL 带 `code` 时在守卫里换取 token(见 4.7 权限)。\n\n### 2.5 状态管理(pinia)\n\n`packages/store/user.js`(`useUserStore`):state `user/menus/permissions/clients/dynamicRouter/menuOpenKeys`;actions `Info()`(拉取并写 localStorage)、`setDynamicRouter()`、`setMenuOpenKeys()`;localStorage 持久化。\n\n### 2.6 工具类(`$utils`)\n\n| 模块 | 说明 |\n| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `$utils.env` | 环境配置对象 |\n| `$utils.ls` | 本地存储(命名空间 `VITE_APP_SYS_SERVER_NAME`) |\n| `$utils.http` | axios 实例(token/`client-id` 注入、响应解包、登录超时、文件下载) |\n| `parseAppUrl` / `innerRedirect` 等 | 站内地址拼 base(支持子路径),外部 http(s) 原样 |\n| `messageFormat(str, values)` | `{0}` / `{name}` 占位符替换,用于确认弹窗等文案 |\n| `filterSelectOption(iv, opt)` | antd4 版 `:filterOption`(读 `option.label` / `option.value`) |\n| `randomDrawerPlacement()` | 随机返回 `left` / `right` / `top` / `bottom`(源项目交互保留) |\n| `getTableHeight({ selector, offset })` | 列表页表格高度 = 窗口高 − 搜索区高 − 偏移(默认 `.table-page-search-wrapper` / `320`,不传参即老项目原行为)。**老项目固定高度撑表才用**,基座 `SListLayout` 走 flex 自适应 |\n| `iconOf(type)` | antd v1 `<a-icon type=\"info-circle\">` 遗留写法的换算:kebab / snake / Pascal 入参 → 图标组件。用法 `<component :is=\"$utils.iconOf('info-circle')\" />` |\n| `hasAction(name)` | 按钮级权限**函数式**判断,与 `v-action` 同源;用于 `v-if` 里的「或 / 且」、算 `disabled` |\n| 其它 | 类型判断、日期、数组、url、dom、防抖节流、金额、手机号校验等 |\n\n> ⚠️ **类型判断 ≠ 格式校验**:`$utils.isNumber` / `isInt` / `isDate` 是 `Object.prototype.toString` 类型判断(`$utils.isNumber('123')` 恒 `false`),**不是**字符串格式校验。业务侧的正则版同名方法(如 `isNumber(str)` 用 `/^(?:-?\\d+|...)/`)**不可**按名字替换过来。\n>\n> 同理 `$utils.uuid(len)` 是纯随机串,与「时间戳 + 随机数」型 `getUUID()` 产出格式不同,涉后端主键时不可换。\n\n`v-action:xxx` 按钮级权限指令:`<a-button v-action=\"'add'\">添加</a-button>`。\n\n- 内部直接调用 `$utils.hasAction(actionName)`,**指令与函数只有一套判定逻辑**\n- 数据源优先级:`permission`(**单数**,`router/index.js` 守卫写入的「当前路由按钮数组」)→ 取不到再回退 `permissions`(**复数**,`store/user.js` 写入的全量「路由 → 按钮」map)+ `CURRENT_ROUTER_KEY`\n- 匹配规则:`String(button_code) === String(actionName)`,**整体相等**(`add` 不会命中 `batchAdd`)\n- 函数式用法:`<a-button v-if=\"$utils.hasAction('add') || $utils.hasAction('edit')\">`\n\n### 2.7 国际化\n\n语言包文件名统一为 `i18n.js`,放在模块的**一级文件夹**下,不带任何前缀,结构是扁平字典:\n\n```js\n// src/views/user/i18n.js -> 命名空间 user\nexport default {\n 取消: 'Cancel'\n}\n```\n\n命名空间取 `views/` 或 `packages/` 之后的第一段目录名(`views/user/i18n.js` → `user`,`packages/components/i18n.js` → `components`)。新增词条文件、新增目录都不用改任何代码,放进去即可。\n\n页面里**不用注册**也能翻译:`$l('中文')` 会自动找该页面**所在目录**的 `i18n.js`(路由加载组件时按源文件路径打标 `__i18nNs`,取不到再用路由 path 首段)。需要强制指定别的命名空间时才显式注册:\n\n```js\nexport default {\n created() {\n this.useI18n('user') // Options API,显式指定,优先级最高\n }\n}\n```\n\n```js\n// <script setup>:可显式传,也可不传(不传就按当前目录自动推断)\nconst { $l } = useI18n() // 自动\nconst { $l } = useI18n('user') // 显式\n```\n\n`$l(name)` 查找顺序:**当前命名空间(显式注册 > 同目录 i18n > 路由首段)→ `components` 通用词 → 全局兜底字典(`packages/locales/lang/dict.js`)→ 原样返回 + `console.warn`(同一个词只提示一次)**。命名空间不存在时 `useI18n` 也会 `console.warn`,不阻断渲染。\n\n| 调用位置 | 写法 | 是否带命名空间 |\n| --------------------------------- | ------------------- | -------------------------------------- |\n| 模板 / 组件内 `this.$l(...)` | `{{ $l('取消') }}` | 带,自动按上述优先级解析 |\n| 组件内 `const { $l } = useI18n()` | `$l('取消')` | 带,同上 |\n| 组件外 JS(api / utils) | `window.$l('取消')` | **不带**,只查 `components` + 全局字典 |\n\n排查用:控制台执行 `$i18nDebug()`,会打印已加载的全部命名空间、当前组件解析到的命名空间及其词条数;`$i18nNamespaces` 是命名空间全量对象。\n\n中文模式直接返回原文;英文模式查不到译文时原样返回中文并告警。antd 自身语言由 `a-config-provider` 的 `locale` 控制。\n\n**业务侧接入(只在这里讲一次)**\n\n1. 词条按上文放 `views/<模块>/i18n.js`,新增文件、新增目录都**不用改代码**。\n2. 在业务 `src/config/app-config.js` 里**聚合一次**,由 `main.js` 的 `{ ...config, ...appConfig }` 交给 `$registerGlobalConfig`:\n\n```js\n// src/config/app-config.js\nconst locales = import.meta.glob(['@/views/**/i18n.js', '@/locales/**/i18n.js'], { eager: true })\nexport default {\n // ...其它业务配置\n locales\n}\n```\n\n3. `src/locales/**` 用来**覆盖基座词条**:`src/locales/components/i18n.js` 对应命名空间 `components`(组件库通用词),业务同名优先。\n4. 语言切换器由 `.env` 的 `VITE_APP_LANG_ENABLE` 控制(`true` 显示);`false` 时词条照常工作,中文直出。\n5. 老写法 `home-i18n.js` / `login-i18n.js` 这类带前缀的文件名**已废弃**:一律用 `i18n.js`,否则推导出的命名空间是 `default/home`、`default/login` 这种不存在的名字,词条不会命中。\n\n### 2.8 主题\n\n定义只由基座维护:`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` 会被忽略。\n\n生效方式:\n\n1. **antd**:`a-config-provider` token(`colorPrimary`/`colorLink`)。\n2. **CSS 变量**:启动时把选中主题算成整套令牌写入 `:root`(主题色系 10 个 + 语义色 11 个 + 中性色 11 个),并内置工具类 `.s-theme-bg`、`.s-theme-color`、`.s-theme-border`、`.s-theme-border-top`、`.s-theme-icon-bg`。\n3. **body 类**:`theme-<VITE_APP_THEME_VALUE>`(如 `theme-blue`)。\n4. **菜单配色**:另有一套 `--s-menu-*` 变量,按主题色推导(`light`)或固定 antd 黑(`dark`),业务只选模式、改不了色值 —— 见 [2.12 菜单配色](#docs-212菜单配色侧边顶部)。\n\n```css\n.my-box {\n color: var(--s-color);\n background: var(--s-bg-color);\n}\n```\n\n**完整令牌清单**(由 `packages/utils/theme-vars.js` 启动时写入 `:root`,组件与业务只用 `var(--s-*)`,不写字面色值):\n\n| 分组 | 令牌 | 默认值(blue) | 说明 |\n| -------- | ------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------- |\n| 主题色系 | `--s-color` | `#1677ff` | 主色,取 `VITE_APP_THEME` |\n| | `--s-light-color`、`--s-dark-color`、`--s-border-color`、`--s-bg-color` | `#6495ed`、`#00008b`、`#b0c4de`、`#f0f2f5` | 取主题定义 |\n| | `--s-color-hover` / `--s-color-active` | `#4592ff` / `#146be6` | 悬停(混白 20%)/ 按下(混黑 10%) |\n| | `--s-color-bg` / `--s-color-bg-hover` / `--s-color-border` | `#e8f1ff` / `#d5e7ff` / `#adcfff` | 选中浅底 / 悬停浅底 / 浅边框 |\n| 语义色 | `--s-color-success`、`--s-color-warning`、`--s-color-error`、`--s-color-info` | `#52c41a`、`#faad14`、`#ff4d4f`、`#1677ff` | 状态语义,不随主题变 |\n| | `--s-color-success-bg`、`--s-color-warning-bg`、`--s-color-error-bg` | `#f6ffed`、`#fffbe6`、`#fff1f0` | 状态浅底 |\n| | `--s-color-warning-light` / `--s-color-error-light` | `#ffc069` / `#ff7875` | 状态浅色变体(错误页插图) |\n| | `--s-color-warning-border` / `--s-color-error-border` | `rgba(250,140,22,.42)` / `rgba(245,34,45,.42)` | 状态半透明描边 |\n| 中性色 | `--s-text-color` | `#262626` | 主要文字 |\n| | `--s-text-color-regular` | `#595959` | 常规文字 |\n| | `--s-text-color-secondary`、`--s-text-color-disabled`、`--s-text-color-inverse` | `#8c8c8c`、`#bfbfbf`、`#ffffff` | 次要 / 禁用 / 反白 |\n| | `--s-border-color-base`、`--s-border-color-light`、`--s-border-color-split` | `#d9d9d9`、`#e8e8e8`、`#f0f0f0` | 边框三级 |\n| | `--s-bg-color-container` / `--s-bg-color-hover` | `#ffffff` / `#f5f5f5` | 容器底 / 悬停底 |\n| | `--s-mask-color` | `rgba(0,0,0,.45)` | 遮罩 |\n\n> 业务样式一律用 `var(--s-*)`,不要写字面色值(`#1677ff` / `#e8e8e8` / `rgba(0,0,0,.65)` 这类):主色相关走主题令牌,灰阶走中性令牌,状态走语义令牌,换主题时才不用改代码。\n>\n> 主题色只有 `blue` / `green` / `orange` / `pink` / `customer` 这几套可选,业务只能选,不能自己加。\n\n### 2.9 其它内置能力\n\n| 内置 | 业务怎么用 |\n| ----------------------------------------------------------------- | ----------------------------------------------------------------------- |\n| 登录 / 单点 / 找回密码 / 激活 全套接口 | 走基座登录页即可,细节见 2.10,换版式见 4.3 |\n| 内置页面:工作台、待办、消息、403/404/500、`/docs`、`/components` | 直接访问;工作台 / 首页可用业务自己的页面覆盖 |\n| 静态资源、全局样式、主题令牌 | `packages/static`、`packages/style` 已随包发布,业务不需要复制 |\n| 常用依赖 | `sapit-ui-plus` 的 dependencies 已随包装好,业务直接 import,清单见 4.8 |\n\n### 2.10 登录 / 单点\n\n- 登录页 `/login/index`:账号密码登录;登录失败达 `getLoginConfig` 策略(`enabled` + `codeThreshold`)时出现**图片验证码**(`/user/verify`),`verificationCode` 原文提交 + `verificationCodeId`。\n- 单点回调:URL 带 `code` 时由**守卫**调 `getCode(code)` 换 token → 存 `$utils.ls` → 去掉 code 整页刷新(与参照项目一致)。\n- 关联配置:`VITE_APP_CLIENT_ID` 必须等于业务在认证中心的 client;接口网关用 `VITE_APP_PORTAL_SERVER_NAME`。\n\n**四套登录主题**(`VITE_APP_LOGIN_PATH_THEME`,取值 `1`~`4`,未配置或非法值回落 `1`):\n\n`packages/pages/login/index.vue` 只负责取主题编号、透传 `logo`/`sysName`、渲染语言切换,具体版式在 `login-themes/` 下的页面级组件里,**互不影响、可单独改**。\n\n| 编号 | 组件 | 版式 |\n| ---- | ----------------- | ---------------------------------------------------------------- |\n| 1 | `LoginTheme1.vue` | 左右分栏:左侧 `login-cover.png` + logo + 系统名,右侧表单 |\n| 2 | `LoginTheme2.vue` | 整屏 `login-cover-right.png`,表单靠左(`padding-left: 336px`) |\n| 3 | `LoginTheme3.vue` | 整屏 `login-cover-center.png`,表单居中(**web-config 默认值**) |\n| 4 | `LoginTheme4.vue` | 左深蓝品牌区 + 右白卡片,门户运营端同款(完整版,见下) |\n\n**主题 4 能力清单**(`login-themes/LoginTheme4.vue`):\n\n- 账号密码登录 + 记住我(存 `LOGIN_ACCOUNT`,只存账号不存密码)。\n- 图形验证码:登录失败达 `getLoginConfig` 阈值后出现,点击图片刷新。\n- 账号锁定倒计时:后端返回 `lockUser`(`lockEndTime`/`nowTime`)后按钮进入 `a-statistic-countdown`,结束前禁用登录。\n- 「激活账号」入口:由 `getSysAccountConfig` 的 `defaultActivateAccount` 控制显隐。\n- 「忘记密码」「扫码登录」:跳基座内置的 `/user/forgotPassword`、`/user/qrCode`。\n- 单位编码:`/login/:officeCode` 进入时写入 `$utils.ls` 的 `officeCode`。\n- 登录成功后:写 `token` / `USER-TOKEN`;带 `redirect_client_id` 时按客户端列表跳 `sso.html` 做客户端授权,否则回 `VITE_APP_DEFAULT_PATH`。\n- 右侧表单区用 **flex 弹性居中**(`align-items: safe center` + `justify-content: center`)。不用 `overflow-y: auto`:父级 `.login-page` 是 `overflow: hidden`,靠滚动救不了;`safe center` 让视口装不下时退化成顶部对齐,卡片顶部不会被顶出可视区。\n\n**登录辅助页**(`packages/pages/login/`,均为 `meta.public`,登录前可达):\n\n| 路由 | 组件 | 说明 |\n| ---------------------- | --------------------- | ------------------------------------------------------------------------------------------------- |\n| `/user/qrCode` | `qr-code.vue` | 扫码登录:`qrLogin/generate` 取 key,`a-qrcode` 渲染,有效期倒计时,过期遮罩 + 刷新 |\n| `/user/forgotPassword` | `forgot-password.vue` | 找回密码四步:选择方式 → 填账号 → 验证码校验(拿临时 token)→ 设新密码;密码策略取 `sysPwdConfig` |\n| `/user/activate` | `activate.vue` | 账号激活四步:身份核验(+图形验证码)→ 短信/邮箱验证码 → 设密码(强度条)→ 完成信息卡 |\n| `/user/login` | — | 重定向到 `VITE_APP_LOGIN_PATH`,供三张页面里的「返回登录」统一跳转 |\n\n**账号类接口**统一在 `packages/api/account.js`(登录前白名单链路,走 `VITE_APP_PORTAL_SERVER_NAME`):\n\n| 方法 | 说明 |\n| --------------------------------- | --------------------------------------------------------------------- |\n| `getSysAccountConfig` | 激活入口开关(`sysAccountConfig/listByActivate`) |\n| `getPwdConfig` | 密码策略(`sysPwdConfig/getFirstData`) |\n| `getLoginQrCodeKey` | 扫码登录 key(`qrLogin/generate`) |\n| `getValidationCodeWithoutToken` | 找回密码发送验证码 |\n| `checkValidationCodeWithoutToken` | 找回密码校验验证码 → 临时 `access_token` |\n| `updatePasswordWithoutToken` | 用临时 token 重置密码(账号/密码需 Base64,token 走 `user-token` 头) |\n| `checkUseInfo` | 激活身份核验 |\n| `getActivateValidationCode` | 激活发送验证码 |\n| `checkActivateValidationCode` | 激活校验验证码 |\n| `activateUpdatePassword` | 激活设置新密码 |\n\n**SSO 静态资源由基座提供**:业务项目**不用再维护 `public/` 下的 `sso.js` / `sso.html`**,只需在 `vite.config.js` 里引入插件:\n\n```js\nimport ssoPlugin from 'sapit-ui-plus/vite-plugins/sso-plugin.js'\nssoPlugin()\n```\n\n插件会在 dev 与构建时提供这两个文件。注意:`sso.html` 换 token 读的是**同源 localStorage**,跨 origin 的平台单点不能直接套用。\n\n> `redirect_uri` 三种处理(`sso.js`):\n>\n> 1. 含 `{token}` → 用本地 token 直接替换回跳,不换 code。\n> 2. **跳回当前应用自身**(`client_id` = 本应用自己的 client,`redirect_uri` 同源、且无 `{code}` 占位符)→ 账密登录场景,本地已有登录态,**不调用单点**(不校验授权、不换 code),直接回跳。\n> 3. **第三方跳转**(功能模块弹窗跳别的 client / 系统)→ 走完整授权码流程:`authorizationCodeValidate` 校验 + `oauth2/code` 换码;有 `{code}` 就替换,无占位符则自动追加 `?code=xxx`。\n>\n> 「当前应用自己的 client」用本应用 base 定位 namespace(`loginHref` 为锚点)精确读取,不走 key 后缀模糊匹配 —— 同 origin 多应用共用 localStorage 时才不会取到别的应用的 `clientId`。\n\n### 2.11 错误页(301 / 403 / 404 / 500)\n\n基座内置三张错误页,**同一张页面承接「页面本身出错」和「接口报错」两种来源**,靠 URL 上的 `?api=` 区分文案。\n\n| 路径 | 组件 | 状态码来源 | 主色 |\n| ------ | --------------- | ----------------------------------------------- | ----------------------- |\n| `/403` | `pages/403.vue` | 接口 403 无权限、接口 301 地址变更、页面无权限 | 橙色 `#fa8c16` |\n| `/404` | `pages/404.vue` | 路由没命中(通配 `/:pathMatch(.*)*`)、接口 404 | 主题色 `var(--s-color)` |\n| `/500` | `pages/500.vue` | 仅可直接访问;**接口 5xx 不跳转**,仍走通知 | 红色 `#f5222d` |\n\n**跳转表现**:错误页是在**内容区里切换**的 —— 侧边菜单、顶栏、页脚保持原样,不会整页顶掉外壳。页面 404(路由没命中)与接口 404 表现完全一致。\n\n**免登录**:`/403`、`/404`、`/500` 带 `meta.public`(接口报错时 token 可能已失效,不能让它再卡在登录守卫里);通配 `/:pathMatch(.*)*` **不带** `public`,未登录访问不存在的地址仍回登录页。\n\n**接口报错的映射**(`packages/utils/request.js`):\n\n| HTTP 状态 | 行为 | 目标 URL |\n| -------------- | --------------------------------- | ------------------------------------------ |\n| 301 | 跳 403 页,文案「接口地址已变更」 | `/403?api=<接口>&status=301&from=<出错页>` |\n| 403 | 跳 403 页,文案「接口无权限」 | `/403?api=<接口>&status=403&from=<出错页>` |\n| 404 | 跳 404 页,文案「接口不存在」 | `/404?api=<接口>&status=404&from=<出错页>` |\n| 其它(含 5xx) | **不跳**,照旧弹通知 | — |\n\n**URL 参数**:\n\n| 参数 | 含义 |\n| -------- | ---------------------------------------------------------------------- |\n| `api` | 报错接口地址。**有它即切「接口口径」文案**;页面自身出错时不带 |\n| `status` | 原始状态码;`301` 单独走「接口地址已变更」这一档文案 |\n| `from` | 出错来源页面地址(已剥掉 `VITE_APP_BASE_URL`),页面显示为「出错地址」 |\n\n文案口径:\n\n| 来源 | 403 页 | 404 页 |\n| ---------------- | -------------- | ---------- |\n| 页面(无 `api`) | 页面权限不足 | 页面走丢了 |\n| 接口(有 `api`) | 接口无权限 | 接口不存在 |\n| 接口 301 | 接口地址已变更 | — |\n\n两个按钮:「返回首页」走 `VITE_APP_DEFAULT_PATH`(默认 `/workplace/index`);「返回上一页」用 `router.back()`,没有历史记录时自动退回首页,避免点了没反应。\n\n**跳过跳转**(后台轮询、辅助接口等非主流程请求,避免一条辅助接口失败把整页顶掉):\n\n```js\n// 第三个参数支持 { skipErrorPage: true }(也可写在请求 meta 里)\nwindow.$utils.http.post(url, data, { skipErrorPage: true })\n```\n\n**改颜色 / 改文案**:\n\n- 文案全部走 i18n 词条(`packages/pages/i18n.js`,命名空间 `pages`),改词条即改三页文字。\n- 403 / 500 各自在根节点定义了 `--e-color`(主色)、`--e-light-color`(浅色)、`--e-border-color`(虚线边框),业务侧用同名变量覆盖即可换色;404 用主题色 `--s-color`,跟随 `VITE_APP_THEME_VALUE`。\n- 三页都按 `height:100%` 铺满内容区,内部超长只在卡片里滚动,不会撑出页面级滚动条。\n\n> 错误页挂在 `BasicLayout` 下,布局层会带发 `getSystemIcon` 与消息计数两个请求。这两个接口若是本身会失败的辅助接口,建议加 `skipErrorPage: true`,否则可能从 403 再跳到 404。\n\n### 2.12 菜单配色(侧边 / 顶部)\n\n菜单色板**由主题色推导**(`light`)或**固定 antd 黑**(`dark`),启动时 `packages/utils/menu-theme.js` 输出实色 `#rrggbb`(**不含 rgba / 透明度**),落到 `:root` 的 `--s-menu-*`,同时挂到 `window.$menuTheme`(含 antd `Menu` token 与 `isLightBg`)。改 `VITE_APP_THEME_VALUE` 换主题色,整套菜单跟着变,不再是写死的淡蓝。\n\n| 部位 | CSS 变量 | `light`(orange 默认) | `light`(blue) | `light`(green) | `dark` |\n| ------------ | ---------------------------------------------- | ---------------------- | --------------- | ---------------- | --------------------- |\n| 一级菜单底 | `--s-menu-bg` | `#f9f1e1` | `#e1ebf9` | `#e1f9ef` | `#001529` |\n| 子菜单展开区 | `--s-menu-sub-bg` | `#fcf9f2` | `#f2f7fc` | `#f2fcf8` | `#000c17` |\n| 悬停项 | `--s-menu-hover-bg` | `#f4e4c8` | `#c8daf4` | `#c8f4e1` | `#1a2c3e` |\n| 选中块 | `--s-menu-active-bg` | `#fff1d6` | `#dae9ff` | `#d6f4e7` | `#FFA500`(主题主色) |\n| 普通文字 | `--s-menu-text` | `#514734` | `#344051` | `#345145` | `#d7dde6` |\n| 悬停文字 | `--s-menu-text-hover` | `#825d17` | `#1f5aad` | `#14714a` | `#ffffff` |\n| 选中文字 | `--s-menu-text-active`、`--s-menu-active-text` | `#8b6318` | `#1a4d93` | `#157950` | `#ffffff` |\n| 分组标题文字 | `$menuTheme.groupTitle` | `#8a7a5c` | `#5c6f8a` | `#5c8a77` | `#737e89` |\n| `isLightBg` | — | `true` | `true` | `true` | `false` |\n\n> 三列 `light` 是**同一套规则**在不同主题色下的输出(`VITE_APP_MENU_BG: 'theme'`):色相取主题色、饱和度受 `_BG_SATURATION` 限制、亮度由 `_BG_LIGHTNESS` 定,文字色按对比度求解(≥ 4.6)。`dark` 的底色固定 antd 黑,不读 `VITE_APP_MENU_BG`,只有选中块跟主题色。\n\n**跟随系统深浅色**\n\n`VITE_APP_THEME_FOLLOW_SYSTEM`(默认 `true`)由 `packages/utils/color-scheme.js` 处理:监听 `prefers-color-scheme`,系统切深色时**立即**把菜单按 `dark` 重算、中性色令牌换成暗色版、`body` 加 `scheme-dark`,切回浅色全量还原 —— 运行时生效,不用刷新。\n\n| 令牌 | 浅色 | 深色 |\n| -------------------------- | --------- | ------------------------- |\n| `--s-text-color` | `#262626` | `#e8e8e8` |\n| `--s-text-color-secondary` | `#8c8c8c` | `#a6a6a6` |\n| `--s-bg-color-container` | `#ffffff` | `#1f1f1f` |\n| `--s-border-color-base` | `#d9d9d9` | `#3d3d3d` |\n| `--s-color-warning-bg` | `#fffbe6` | `#2b2413`(语义浅底压暗) |\n\n> ⚠️ 暗色令牌只对**用 `var(--s-*)` 取色**的地方生效。业务页面里硬编码的 `background: #fff` 不会自动变暗,要适配深色得换成 `var(--s-bg-color-container)`;也可以直接用 `body.scheme-dark` 写自己的覆盖。\n> 关掉跟随(`VITE_APP_THEME_FOLLOW_SYSTEM: false`)后深浅固定按 `VITE_APP_MENU_THEME` 走,业务本来配 `dark` 的不受影响。\n\n**业务只能选模式,不能改颜色**\n\n业务可选的只有 3 个:\n\n| 配置 | 默认 | 说明 |\n| ------------------------------ | ------- | -------------------------------------------- |\n| `VITE_APP_MENU_BAR` | `left` | `left` 侧边 / `top` 顶部(布局项) |\n| `VITE_APP_MENU_THEME` | `light` | `light` 跟主题色的浅色系 / `dark` 黑色 |\n| `VITE_APP_THEME_FOLLOW_SYSTEM` | `true` | 是否跟随系统深浅色(`prefers-color-scheme`) |\n\n下面 11 个颜色 / 调色键**由基座锁定,在基座启动时强制回填**,所以业务 `.env`、`src/config/web-config.js`、部署目录 `config.json` 三处写的菜单颜色全都无效 —— 所有业务项目的菜单外观与基座 demo 完全一致,这是有意为之:\n\n| 键 | 默认 | 作用 |\n| ------------------------------ | ------- | -------------------------------------------------- |\n| `VITE_APP_MENU_BG` | `theme` | 一级菜单底:`theme` 跟随主题色 / `#RRGGBB` 固定 |\n| `VITE_APP_MENU_BG_LIGHTNESS` | `93` | 一级底亮度 0-100 |\n| `VITE_APP_MENU_BG_SATURATION` | `66` | 饱和度上限 0-100 |\n| `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | 选中块里主题色的占比 0-100 |\n| `VITE_APP_MENU_SUB_BG` | 空 | 子菜单展开区底色;空 = 按主题色相推导 |\n| `VITE_APP_MENU_HOVER_BG` | 空 | 悬停项底色;空 = 按主题色相推导 |\n| `VITE_APP_MENU_ACTIVE_BG` | 空 | 选中块底色;空 = 主题色兑白(占比见 `_BG_ACTIVE_MIX`) |\n| `VITE_APP_MENU_TEXT` | 空 | 普通文字色;空 = 按主题色相推导 |\n| `VITE_APP_MENU_TEXT_HOVER` | 空 | 悬停文字色 |\n| `VITE_APP_MENU_TEXT_ACTIVE` | 空 | 选中文字色 |\n| `VITE_APP_MENU_GROUP_TITLE` | 空 | 分组标题文字色 |\n\n> 想自己验证一次:在业务 `config.json` 里写 `\"VITE_APP_MENU_BG\": \"#ff0000\"`,刷新后菜单还是按主题色推导的那套值。\n\n> 注意事项\n>\n> 1. `light` 下把 `VITE_APP_MENU_BG` 配成 `dark` 会被忽略并告警(黑底属于 `dark` 模式),仍按浅色推导。\n> 2. 单项颜色覆盖只对 `light` 生效,`dark` 保持纯黑体系,不会出现「黑底 + 淡蓝子菜单」。\n> 3. 业务样式不要写死 `#001529`、`rgba(255,255,255,.1)` 这类菜单色,直接 `var(--s-menu-*)`。\n> 4. 侧边菜单、顶部菜单(`VITE_APP_MENU_BAR: 'top'`)、logo 明暗、顶栏文字色共用 `window.$menuTheme.isLightBg` 判断,不看 `VITE_APP_MENU_THEME` —— 系统深色跟随会改写它,所以判断必须走这个字段。\n> 5. `window.$menuTheme` 是 `reactive` 对象:深浅色切换时只改属性不换引用,`SSideMenu` 的 `computed` 读 `window.$menuTheme.token` 会自动重算,antd `Menu` token 无需手动刷新。\n\n## 三、构建与配置\n\n### 3.1 基座更新后业务怎么拿到\n\n基座以 npm 包(`sapit-ui-plus`)的形式发布,业务用的是**预构建产物**,不是源码:\n\n| 场景 | 生效方式 |\n| -------------------------- | ----------------------------------------------------------------- |\n| 基座改了组件 / 配置 / 文案 | 基座发版 → 业务更新依赖(`npm start` 或删锁文件后 `npm i`)才生效 |\n| 只改了业务自己的页面 | 业务重启 dev 即可 |\n\n> 业务侧更新依赖时**必须删掉锁文件**(`package-lock.json` / `yarn.lock` / `node_modules/.package-lock.json`),否则会钉在旧提交上,看起来像「基座的新功能没生效」。\n\n### 3.2 配置来源与优先级\n\n```text\n基座默认 defaultEnv < 业务 web-config.js < .env.[sapit-base-template](构建时写入 config.json) < 部署 config.json(运行时覆盖)\n```\n\n- `web-config.js`:可写默认值或 `import.meta.env.VITE_APP_*`;\n- `.env` / `.env.[sapit-base-template]`:各环境一套(dev/test/uat/prod),由业务 `vite.config.js` 写入 `config.json`;\n- `config.json`:站点根(子路径为 `<base>config.json`),启动时 `loadRemoteConfig()` 拉取并覆盖,**部署后可直接改、无需重打包**;`.env` 值为字符串,基座会把 `\"true\"/\"false\"` 归一为布尔。\n\n常用开关(业务可按需覆盖;判断统一用 `!== false`,即未配置时取基座默认值):\n\n| 配置项 | 默认值 | 说明 |\n| ------------------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| `VITE_APP_FOOTER_VISIBLE` | `false` | 是否显示页脚 |\n| `VITE_APP_MESSAGE_VISIBLE` | `true` | 是否显示右上角消息铃铛(设 `false` 隐藏) |\n| `VITE_APP_SOCKET_URL` | `ws://127.0.0.1:8080/websocket` | socket 地址:**只写协议+主机+端口,不要带 `/apig/` 等路径**;为空或 `/` 时走同源;本地占位地址在非本机环境下自动跳过 |\n| `VITE_APP_SOCKET_PATH` | `/apig/ws/websocket` | socket.io 握手路径,需与后端一致(真正的服务路径只认这一项) |\n| `VITE_APP_LANG_ENABLE` | `false` | 是否启用国际化 |\n\n> 菜单配色相关的 14 个键(`VITE_APP_MENU_BAR` / `_THEME` / `THEME_FOLLOW_SYSTEM` 可选,其余 11 个由基座锁定)**统一列在 [2.12 菜单配色](#docs-212菜单配色侧边顶部)**,这里不重复。\n\nsocket 是**整站一条连接**(`packages/utils/socket.js`,单例,与源项目 `VueSocketIO` 只注册一次一致),消息与扫码登录共用同一个地址、同一个 `path`,只靠事件名区分:\n\n| 业务 | 上报事件 | 接收事件 | 模块 |\n| -------------- | ---------------------- | ----------- | ----------------------------------- |\n| 右上角消息铃铛 | `sendUserId`(userId) | `wsEvent` | `packages/utils/message-socket.js` |\n| 扫码登录 | `QRCodeKey`(qrId) | `QRWsEvent` | `packages/utils/qr-login-socket.js` |\n\n数量逻辑:进入系统先调 `message/center/counts` 取 `totalCount`,之后由 socket 推送的 `wsEvent` 触发重新拉取。业务侧无需注册任何东西,只要把 `VITE_APP_SOCKET_URL` / `VITE_APP_SOCKET_PATH` 配到网关即可。\n\n> `VITE_APP_SOCKET_URL` 里写了路径会踩坑:socket.io 把 URL 的 path 当 **namespace**(`io('http://h:50001/apig/')` → namespace `/apig/`),服务端回 `Invalid namespace`,握手成功但永远不 connect,也不报 `connect_error`。基座虽已在 `resolveSocketUrl` 里剥掉 path 兜底,配置仍建议规范写。\n\n### 3.3 业务项目启动(`npm start`)\n\n业务项目(`sapit-base-template`)的 `npm start` 执行内置脚本 `refresh-sapit-base-template.ps1`:\n\n1. 清理 `node_modules/.vite`、`node_modules/sapit-ui-plus` 及锁文件(`package-lock.json`/`yarn.lock`/`pnpm-lock.yaml`/`node_modules/.package-lock.json`);\n2. `npm install` 拉取 `sapit-ui-plus` 最新发布版本;\n3. 自动执行 `npm run dev` 启动。\n\n> 作用:清理依赖缓存,更新业务依赖并一键启动。也可双击 `refresh-sapit-base-template.cmd`;`-NoStart` 仅更新不启动。\n> 这个命令通常在基座项目有更新时才会用到。\n\n## 四、业务项目接入\n\n### 4.1 安装\n\n```json\n{ \"dependencies\": { \"sapit-ui-plus\": \"git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git\" } }\n```\n\n### 4.2 入口 `main.js`\n\n```js\nimport { createApp } from 'vue'\nimport App from './App.vue'\nimport config from './config/web-config'\nimport appConfig from './config/app-config'\nimport SapitUiPlus from 'sapit-ui-plus'\nimport 'sapit-ui-plus/lib/css/style.css'\n\nasync function init() {\n const pages = import.meta.glob('@/views/**/*.vue')\n const app = createApp(App)\n app.use(SapitUiPlus)\n await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages)\n app.mount('#app')\n}\ninit()\n```\n\n- `config`:环境配置(web-config);\n- `appConfig`:构建期配置(登录/首页覆盖、静态路由、语言包),**不进入 config.json**;\n- `pages`:业务所有页面,用于动态路由按 `hrefs` 匹配。\n\n### 4.3 登录页 / 首页覆盖\n\n`app-config.js`:\n\n```js\nexport default {\n components: {\n login: () => import('@/views/login/index.vue'),\n home: () => import('@/views/home/index.vue')\n }\n}\n```\n\n不配置则用基座默认(`pages/login.vue`、`todo.vue`)。\n\n### 4.4 静态页面 `staticRoutes`\n\n```js\nexport default {\n staticRoutes: [\n {\n path: '/help',\n name: 'Help',\n component: () => import('@/views/help/index.vue'),\n meta: { title: '帮助' } // hidden: 不进菜单;public: 免登录\n }\n ]\n}\n```\n\n`layout: false` / `raw: true` 时不包 `BasicLayout`;同 `path` 时业务覆盖基座内置。\n\n### 4.5 业务页面与菜单\n\n后端菜单 `hrefs` 需匹配业务 `views` 路径(或组件名);页面放 `src/views/**` 即可被动态路由识别。侧边菜单渲染「动态菜单 + `staticRoutes`」,基座常量菜单不进菜单。\n\n### 4.6 子路径部署(示例 `/monitor/`)\n\n1. `.env`:`VITE_APP_BASE_URL=/monitor/`;\n2. 业务 `vite.config.js`:`base: getViteEnv(res.sapit-base-template, 'VITE_APP_BASE_URL') || '/'`;\n3. 基座路由 base、`$push`/`$open`、`redirectLogin`、`parseAppUrl` 均读该值自动带前缀;\n4. nginx:\n\n```nginx\nlocation /monitor/ {\n alias /home/project/tmp/dist/;\n index index.html;\n try_files $uri $uri/ /monitor/index.html;\n}\nlocation = /monitor/config.json {\n alias /home/project/tmp/dist/config.json;\n add_header Cache-Control \"no-store\";\n}\n```\n\n> `createWebHistory` base、Vite `base`、`window.location` 跳转三者必须都是 `/monitor/`(带尾斜杠)。\n\n### 4.7 使用组件与权限\n\n```html\n<template>\n <s-list-layout :columns=\"columns\" :load-data=\"page\" title=\"示例\" />\n <s-user-select v-model:value=\"ids\" />\n <a-button v-action=\"'add'\">添加</a-button>\n</template>\n```\n\n后端下发 `permissions` 后基座写入 `permission`,用 `v-action:xxx` 控制按钮级权限。文档访问:`<业务base>/docs`、`<业务base>/components`。\n\n---\n\n### 4.8 内置依赖(业务开箱即用)\n\n`sapit-ui-plus` 的 `dependencies` 会随基座一起装进业务 `node_modules`,业务**无需再装即可直接 import**(业务 `package.json` 里通常只见 `sapit-ui-plus` 一项)。\n\n| 依赖 | 版本 | 用途 |\n| ------------------------------------------------ | ----------------- | ----------------------------------------------------- |\n| `dayjs` | ^1.11.12 | 日期格式化(推荐,`$utils` 内也用) |\n| `axios` | ^1.7.3 | 请求(已封装为 `window.$utils.http`,一般不用直接用) |\n| `qs` | ^6.13.0 | 参数序列化(`stringify`) |\n| `lodash.get` / `lodash.clonedeep` | ^4.4.2 / ^4.5.0 | 安全取值 / 深拷贝 |\n| `crypto-js` | ^4.2.0 | 加解密 |\n| `js-base64` | ^3.7.2 | Base64 编解码 |\n| `jsencrypt` | ^3.3.2 | RSA 加密 |\n| `moment` | ^2.30.1 | 日期(老代码兼容,新代码用 dayjs) |\n| `html2canvas` | ^1.4.1 | 页面截图 |\n| `nprogress` | ^0.2.0 | 顶部加载进度条 |\n| `@vueuse/core` | ^11.0.3 | 组合式工具函数 |\n| `vue-cropper` | ^1.1.4 | 图片裁剪(SCopperUpload 用它) |\n| `vuedraggable` | ^4.1.0 | 拖拽排序 |\n| `v-clipboard` | ^3.0.0-next.1 | 复制到剪贴板(`v-clipboard` 指令) |\n| `vue-ls` | ^4.2.0 | localStorage 封装(已包成 `$utils.ls`) |\n| `jodit` | 3.24.7 | 富文本编辑器(SEditor) |\n| `less` / `less-loader` | ^4.2.0 / ^12.2.0 | 样式编译 |\n| `vite-plugin-html` / `vite-plugin-generate-file` | ^3.2.2 / ^0.2.0 | 构建插件(生成 config.json 等) |\n| `@ant-design/icons-vue` | 随 ant-design-vue | 图标,**全部已全局注册为组件** |\n\n**单例依赖:基座不做打包,业务必须自己安装**(`vite.config.js` 的 `external`),否则会出现两个模块实例(路由注入不上、pinia 对不上、主题/消息上下文丢失):\n\n| 依赖 | 版本 |\n| ---------------- | ------- |\n| `vue` | ^3.4.29 |\n| `vue-router` | ^4.3.3 |\n| `pinia` | ^2.1.7 |\n| `vue-i18n` | ^9.14.0 |\n| `ant-design-vue` | 4.x |\n\n> 用法:`import dayjs from 'dayjs'` 直接可用;但**不要**在业务里再装一份与基座不同大版本的 `vue`/`ant-design-vue`/`pinia`,版本以基座为准。\n\n## 五、注意事项\n\n### 5.1 业务侧\n\n1. <span style=\"color:#d4380d;font-weight:700\">依赖是预构建产物</span>:基座改动需 `npm run build` 推送且业务重装依赖才生效;基座 dev 立即生效。\n2. <span style=\"color:#d4380d;font-weight:700\">锁文件会钉住旧提交</span>:更新前删 `package-lock.json`、`yarn.lock`、`node_modules/.package-lock.json`。\n3. <span style=\"color:#d46b08;font-weight:700\">子路径</span>:`VITE_APP_BASE_URL` 与 Vite `base` 保持一致且带尾斜杠。\n4. <span style=\"color:#d46b08;font-weight:700\">组件全局可用</span>:`S*` 组件、`STable` 都由基座全局注册,直接写标签,不要 import、不要重复局部注册。\n5. <span style=\"color:#d46b08;font-weight:700\">主题 / 菜单配色 / 国际化</span>:定义都在基座。业务只选 `VITE_APP_THEME_VALUE`、`VITE_APP_MENU_THEME`、`VITE_APP_THEME_FOLLOW_SYSTEM` 三个值,只写 i18n 文案;`VITE_APP_MENU_*` 色值写了也会被回填(见 2.7 / 2.8 / 2.12)。\n6. <span style=\"color:#d46b08;font-weight:700\">不能深路径 import 基座内部模块</span>:lib 产物只有 `lib/js/index.js` 一个入口,内部模块被 rollup 打进 chunk。想让业务用某能力,必须挂全局属性(`$utils` / `$modal` 那样)。\n7. <span style=\"color:#d4380d;font-weight:700\">功能去留</span>:源码(老 Vue2 项目)有的我们就有,源码没有的不要\"顺手补齐\"。新增功能前先确认参照实现。\n\n### 5.2 业务字典 / 表单约定(hy-monitor)\n\n15. **下拉 value / 文案一律取字典项的 `value`(字典值),绝不用 `id`(主键)**。字典调`mapByDictTypes('a','b')` 一次性取多个,按**下划线转驼峰**取返回值(`recycle_status` → `res.recycleStatus`),项为 `{label, value, id}`。\n16. **`a-select` 的 placeholder 只在值为 `undefined`/`null` 时显示**,空字符串 `''` 会被视为已有值。所有下拉类字段(搜索参数、表单字段)初始值一律 `undefined`,**禁用 `''`**(多选绑定 `[]` 正常)。\n17. **时间范围参数统一传毫秒时间戳**(`dayjs(x).valueOf()`),不是 unix 秒。依据:源码 `DateRange` 的 onChange 输出 `date.map(o => dayjs(o).valueOf())`,`useFormValues.fieldMapToTime` 默认 `format=''` 原样透传。\n18. **接口请求不写 `catch`**(错误由全局拦截器统一提示)。但三类 catch 必须保留:① 表单校验链 `.catch(() => {})`;② `try { await validate() } catch { return }`;③ `JSON.parse` 解析容错。\n19. **接口报错会跳内置错误页**:403(含 301)→ `/403`、404 → `/404`,在内容区 `router-view` 内切换且不再叠加通知;**5xx 不跳**,仍走通知。后台轮询等非主流程请求传 `{ skipErrorPage: true }` 可保住当前页面。URL 参数、文案口径与改色方法见 2.11:\n\n```js\nthis.$utils.http.post('/api/msg/count', {}, { skipErrorPage: true })\n```\n\n---\n\n## 六、在线文档入口\n\n| 地址 | 内容 |\n| ------------------- | ------------------------------------------- |\n| `<base>/docs` | 说明文档(本文) |\n| `<base>/components` | s组件(基座内置组件:左菜单 + 预览 + 源码) |\n", $ = "# sapit-ui base framework guide and business usage\n\n> Applies to: <span style=\"color:#1677ff;font-weight:700\">sapit-ui-framework</span> (the base / sources), <span style=\"color:#1677ff;font-weight:700\">sapit-ui-plus</span> (published artifact), <span style=\"color:#1677ff;font-weight:700\">sapit-base-template</span> (business sample).\n>\n> This document is also the data source of the built-in `/docs` page and the `/components` page.\n>\n> Prop defaults in the base source are written in Chinese and translated at render time, so the tables below show their English rendering.\n\n---\n\n## Contents\n\n- [1. Overview](#docs-1Overview)\n- [2. What the base provides](#docs-2Whatthebaseprovides)\n- [3. Build and configuration](#docs-3Buildandconfiguration)\n- [4. Business project integration](#docs-4Businessprojectintegration)\n- [5. Caveats](#docs-5Caveats)\n- [6. Online documentation entry](#docs-6Onlinedocumentationentry)\n\n---\n\n## 1. Overview\n\n### 1.1 The five pieces\n\n| Project | Role | Description |\n| --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |\n| `sapit-ui-framework` | <span style=\"color:#d4380d\">Base (sources)</span> | Library project holding the built-in components and common dependencies, packed in Vite lib mode |\n| `sapit-ui-plus` | <span style=\"color:#d46b08\">Published artifact</span> | The git repository that receives the base `dist` (`lib/`, `docs/`, `vite-plugins/`) |\n| `sapit-base-template` | <span style=\"color:#389e0d\">Business consumer</span> | Builds business pages and configuration on top of the `sapit-ui-plus` git dependency |\n\n```text\nsapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template\n```\n\n### 1.2 What the package contains\n\nThe `sapit-ui-plus` a business project installs carries only what runs at runtime (not the base source tree):\n\n```text\nnode_modules/sapit-ui-plus/\n├─ lib/ # build output: js / css / images — what the business actually imports\n├─ docs/ # this document, rendered by the built-in /docs page\n├─ vite-plugins/ # plugins referenced by the business vite.config.js (e.g. sso-plugin)\n├─ static/ # static assets (login page images, ...)\n└─ package.json\n```\n\nA business project only references three things: the entry `sapit-ui-plus`, the styles `sapit-ui-plus/lib/css/style.css`, and `vite-plugins/*` on demand.\n\n---\n\n## 2. What the base provides\n\n### 2.1 Global components\n\n`packages/index.js` uses `import.meta.glob('./components/**/*.vue')` to register every `components/**/*.vue` **by file name**, so templates can use the file name as the tag (e.g. `<s-modal>`, `<s-user-select>`).\n\n| Category | Components |\n| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Layout | `SSkeletonLayout` (skeleton layout: title + button group + content), `SListLayout`, `SListCardLayout` (card list), `SListTableTreeLayout`, `SSuperListLayout` (advanced list: column settings + advanced filter), `SFormLayout`, `SPanelLayout`, `SCollapses`/`SCollapsesItem`, `SDrawer` |\n| Overlay | `SModal`, `SModalTemplate`, `ModalHeader`, `SIconModal`, `SImportModal` (bulk import) |\n| Form / filter | `SForm`, `SFormItem` (multi-column + `full` for a whole row), `SExtendFieldsForm`/`SExtendFieldsFormItem` (dynamic extra fields), `SFilterWrap`, `SFilterItem` (`full` for a whole row), `SFilterToolbar` (filter area shell: main row + more-filters collapse + reset), `STableToolbar` (table area shell: body height auto-fits the content area; used as a pair with `SFilterToolbar`), `SCascader`, `STree`, `STreeSelect`, `SDataRangeTreeSelect` (data-permission scope tree), `SUserSelect`, `SUserSelectButton`, `SChooseUser` (user picker with data permission), `SBelowChoosePosition` (position picker), `SOfficeSelect`, `SIconSelect` (icon dropdown, searchable/multiple), `SIconSelectPopover` (icon grid panel), `SIconModal` (icon browser) |\n| Upload | `SFileUpload`, `SDraggerUpload`, `SCopperUpload`, `CropperModal` |\n| Display / others | `STab`/`STabItem` (tab bar: arrows + drag when the tabs overflow), `SEditor`, `SEmpty`, `SIcon`, `SSvg`, `SAnchor`, `SColorPicker`, `SToggleLanguage`, `SettingFilter`, `SettingColumns`, `SSideMenu`/`STopMenu` |\n\n> **Props / events / methods / slots, live previews and example code for every component live in the built-in component page `/components`** (it also has a \"tools / config\" tab listing every web-config option and every `$utils` method).\n>\n> A few usage notes:\n>\n> - Component names are **PascalCase** (`SForm` / `STable`); both `<SForm>` and `<s-form>` resolve in templates — just stay consistent.\n> - All `@ant-design/icons-vue` icons are registered globally, and the icon map is exposed as `$icons`.\n> - A few helper components are internal (e.g. `ModalHeader`, `CropperModal`, `SettingColumns` / `SettingFilter`) — do not reference them from business code.\n\n### 2.2 Global properties / methods\n\nAvailable after `$registerGlobalConfig` runs (`this.$xxx` / `$xxx` in templates / `window.$xxx`):\n\n| Name | Description |\n| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `$registerGlobalConfig(config, pages)` | Initialization entry (see 4.2) |\n| `$utils` | Utility collection: `$utils.env` / `$utils.ls` / `$utils.http` plus general helpers |\n| `env` | Merged environment configuration (= `$utils.env`) |\n| `$i18n` / `$l(name)` | Internationalization (see 2.7). Lives on `globalProperties`: usable **directly in templates** as `$l('xx')`; inside `<script setup>` **scripts** you must call `window.$l('xx')` (setup has no `this`) |\n| `$theme` / `$staticRoutes` / `$pinia` | Theme object / static route list / user store instance |\n| `$modal` / `$message` / `$notice` / `$confirm` | antd `Modal` / `message` / `notification` / `Modal.confirm` (list component button api branch calls `this.$confirm`) |\n| `$push(path, query)` / `$open(...)` | In-app navigation / new window (automatically prefixes `VITE_APP_BASE_URL`) |\n| `$filter` / `$icons` / `$socket` | Date formatting / icon collection / websocket wrapper. `$icons` maps every `@ant-design/icons-vue` icon by **Pascal name** (`InfoCircleOutlined`) and is **also exposed on `window.$icons`** (so `$utils.iconOf` works outside components). Legacy antd v1 `<a-icon type=\"info-circle\">` names convert via `$utils.iconOf('info-circle')`; `SIcon`'s `name` only accepts Pascal names |\n| `$getPdf({ el, title })` | Export the page to PDF (Vue3 port of the legacy `Vue.prototype.getPdf`). Pass the capture container and file name explicitly: `<a-button @click=\"$getPdf({ el: '#pdfDom', title: htmlTitle })\">Export</a-button>`. `html2canvas` + `jsPDF` are **imported dynamically**, so nothing loads until the button is clicked; A4 pagination is automatic and it returns `Promise<boolean>`. Optional `fileName` / `scale` / `backgroundColor` / `beforeCapture` / `afterCapture` / `onError`. A dollar-less `getPdf` alias is registered for legacy code (default container `#pdfDom`, title from `document.title`) |\n\n### 2.3 Layouts\n\nBusiness pages render inside the content area of `BasicLayout`. There are three shells:\n\n| Layout | Purpose |\n| ------------- | ---------------------------------------------------------------------------------------------- |\n| `BasicLayout` | Header + side/top menu + content (dynamic and static routes are both wrapped in it by default) |\n| `UserLayout` | Login, QR login, forgot password, activation — pages reachable before signing in |\n| `BlankLayout` | A bare shell without menu or header |\n\n**Page height**: the content height is computed by `BasicLayout` and passed down to `router-view`, so a page root with `height: 100%` fills the area automatically. **Never write `calc(100vh - 58px)`-style subtractions**: header height, footer and tabs all make that number wrong, and the symptom is pagination floating mid-page or an extra scrollbar.\n\nUse a layout component for the page body (`SListLayout` / `SFormLayout` / `SSkeletonLayout` / `SPanelLayout`, ...): they take the remaining height and scroll internally, so you only write the content.\n\n**Choosing a page layout component**:\n\n| Scenario | Use |\n| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |\n| Title + buttons + custom content (no table / paging / form) | `SSkeletonLayout` (ships with a title bar and permission-aware buttons) |\n| Standard list page | `SListLayout` |\n| Card list | `SListCardLayout` (card grid + three slots) |\n| List + left tree | `SListTableTreeLayout` (the left-tree container class must be `.side.s-side-tree`) |\n| List with advanced search / advanced table | `SSuperListLayout` (column settings + advanced filter) |\n| Create / edit / detail as a route | `SFormLayout` (`#form` slot holds `SForm`; `#footer-callback` receives `save`/`cancel`/`prev`/`next`) |\n| Form inside a modal | `SModal` (do not nest `SFormLayout`) |\n| Dynamic form driven by backend fields | `SExtendFieldsForm` (`data` + `defaultValue`; call `validate/clearValidate/getModel` via ref) |\n| Data-scope range picker | `SDataRangeTreeSelect` (`autoSysConfig` manages the system `dataScope` config) |\n\n### 2.4 Routes\n\n**Constant routes** (`packages/router/index.js`):\n\n| Path | Description |\n| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `/login/index` | Login page (base default, can be overridden by the business, see 4.3) |\n| `/login/:officeCode` | Same page entered with an office code (written to `$utils.ls` as `officeCode`, see 2.10) |\n| `/user/qrCode`, `/user/forgotPassword`, `/user/activate` | QR login / forgot password / account activation pages. The parent `/user` carries `meta.public`, so they are **reachable before login** (see 2.10) |\n| `/workplace/index` | Default home (`VITE_APP_DEFAULT_PATH`, overridable) |\n| `/workbench/index`, `/message/index` | Workbench / messages |\n| `/docs`, `/components` | Built-in docs / component pages (`public` = no login, `hidden` = not in the menu) |\n| `/404`, `/403`, `/500`, `/:pathMatch(.*)*` | Error pages; the catch-all renders 404 (**no redirect**, so refreshing dynamic routes never lands on a 404). Where they render and their wording: see 2.11 |\n\n> Redirect rules, query parameters, wording and color overrides for the error pages are documented in [2.11 Error pages](#docs-211Errorpages301403404500).\n\n**Static routes** (`staticRoutes`, independent of backend menus): see 4.4. The base ships `/docs` and `/components`.\n\n**Dynamic routes** (`packages/router/generator-routers.js`): after login a tree is generated from the backend `menus`, rooted at `BasicLayout`; leaf nodes use `item.hrefs` to match business `pages` (keys of `import.meta.glob('@/views/**/*.vue')`) and fall back to 404 when nothing matches. Registration happens inside the guard (memory flag, re-registered on refresh).\n\n**Guards**: public pages (`meta.public`) pass straight through; the token is read live; unauthenticated users are redirected to login; an authenticated user visiting the login page or the root is sent to the default home; a failed user-info fetch clears state and returns to login (so nothing stays pending). When the URL carries a `code`, the guard exchanges it for a token (see 4.7 permissions).\n\n### 2.5 State management (pinia)\n\n`packages/store/user.js` (`useUserStore`): state `user/menus/permissions/clients/dynamicRouter/menuOpenKeys`; actions `Info()` (fetch and write to localStorage), `setDynamicRouter()`, `setMenuOpenKeys()`; persisted in localStorage.\n\n### 2.6 Utilities (`$utils`)\n\n| Module | Description |\n| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `$utils.env` | Environment configuration object |\n| `$utils.ls` | Local storage (namespace `VITE_APP_SYS_SERVER_NAME`) |\n| `$utils.http` | axios instance (token/`client-id` injection, response unwrapping, login timeout, file download) |\n| `parseAppUrl` / `innerRedirect` etc. | Build in-app URLs with the base (sub-path aware); external http(s) URLs are kept as-is |\n| `messageFormat(str, values)` | `{0}` / `{name}` placeholder substitution (confirm dialogs etc.) |\n| `filterSelectOption(iv, opt)` | antd4-ready `:filterOption` (reads `option.label` / `option.value`) |\n| `randomDrawerPlacement()` | Randomly returns `left` / `right` / `top` / `bottom` (kept from the source project) |\n| `getTableHeight({ selector, offset })` | List table height = window height − search area − offset (defaults `.table-page-search-wrapper` / `320`; no-arg call keeps legacy behaviour). **Only for legacy fixed-height lists** — `SListLayout` uses flex sizing |\n| `iconOf(type)` | Converts legacy antd v1 `<a-icon type=\"info-circle\">` names: kebab / snake / Pascal in → icon component. Usage: `<component :is=\"$utils.iconOf('info-circle')\" />` |\n| `hasAction(name)` | Functional button-level permission check, same source as `v-action`; for `v-if` OR / AND logic and `disabled` computation |\n| Others | Type checks, dates, arrays, url, dom, debounce/throttle, money, phone validation, etc. |\n\n> ⚠️ **Type checks are not format validation**: `$utils.isNumber` / `isInt` / `isDate` use `Object.prototype.toString` (`$utils.isNumber('123')` is always `false`). They are **not** string-format validators; a business-side regex version with the same name must **not** be replaced by them.\n>\n> Likewise `$utils.uuid(len)` returns a purely random string, a different shape from a \"timestamp + random\" `getUUID()` — do not swap them when the value feeds backend keys.\n\n`v-action:xxx` is the button-level permission directive: `<a-button v-action=\"'add'\">Add</a-button>`.\n\n- It delegates to `$utils.hasAction(actionName)` — the directive and the function share **one** decision path\n- Source priority: `permission` (**singular**, the current route's button array written by the `router/index.js` guard) → falls back to `permissions` (**plural**, the full route → buttons map written by `store/user.js`) + `CURRENT_ROUTER_KEY`\n- Matching rule: `String(button_code) === String(actionName)`, **exact equality** (`add` no longer matches `batchAdd`)\n- Functional usage: `<a-button v-if=\"$utils.hasAction('add') || $utils.hasAction('edit')\">`\n\n### 2.7 Internationalization\n\nA language pack is a file named `i18n.js` placed directly in a module's top-level folder, with no prefix, and its shape is a flat dictionary:\n\n```js\n// src/views/user/i18n.js -> namespace user\nexport default {\n '<source text>': 'Cancel'\n}\n```\n\nThe namespace is the first path segment after `views/` or `packages/` (`views/user/i18n.js` → `user`, `packages/components/i18n.js` → `components`). Packs are aggregated at build time by `import.meta.glob`, so adding files or folders requires no code change.\n\nRegister the namespace inside the page, then call `$l('<source text>')` directly — never `$l('user.<source text>')`:\n\n```js\nexport default {\n created() {\n this.useI18n('user') // Options API\n }\n}\n```\n\n```js\n// also works inside <script setup>\nconst { $l } = useI18n('user')\n```\n\nLookup order for `$l(name)`: **namespace registered by the current component → global fallback dictionary (`packages/locales/lang/dict.js`) → the name itself**. `useI18n` logs a `console.warn` (non-blocking) when the namespace does not exist.\n\n| Call site | Usage | Namespace |\n| --------------------------------------------- | ---------------------------- | ------------------------------------------- |\n| Template / inside a component, `this.$l(...)` | `{{ $l('<source text>') }}` | yes, the one registered via `useI18n` first |\n| Plain JS outside components (api / utils) | `window.$l('<source text>')` | no, global dictionary only |\n\nIn Chinese mode the source text is returned as-is; in English mode, a missing translation falls back to the source text. antd's own locale is controlled by `a-config-provider`'s `locale`.\n\n**Business side setup (documented here only)**\n\n1. Drop dictionaries at `views/<module>/i18n.js` as described above; adding files or folders needs no code change.\n2. Aggregate them **once** in the business `src/config/app-config.js`; `main.js` spreads `{ ...config, ...appConfig }` into `$registerGlobalConfig`:\n\n```js\n// src/config/app-config.js\nconst locales = import.meta.glob(['@/views/**/i18n.js', '@/locales/**/i18n.js'], { eager: true })\nexport default {\n // ...other business config\n locales\n}\n```\n\n3. `src/locales/**` **overrides base entries**: `src/locales/components/i18n.js` maps to the `components` namespace (shared component-library words); the business wins on duplicates.\n4. The language switcher is controlled by `VITE_APP_LANG_ENABLE` in `.env` (`true` shows it); with `false` the dictionaries still work and Chinese renders as-is.\n5. Prefixed filenames such as `home-i18n.js` / `login-i18n.js` are **obsolete**: always use `i18n.js`, otherwise the derived namespace is a non-existent `default/home` / `default/login` and the entries never resolve.\n\n### 2.8 Theme\n\nDefinitions are maintained by the base only: `VITE_APP_THEME` in `packages/config/web-config.js` (each set carries `color/lightColor/darkColor/borderColor/bgColor`); the business only picks one with `VITE_APP_THEME_VALUE` (`blue`/`green`/`orange`). A `VITE_APP_THEME` coming from the business or `config.json` is ignored.\n\nHow it takes effect:\n\n1. **antd**: `a-config-provider` tokens (`colorPrimary`/`colorLink`).\n2. **CSS variables**: on startup the selected theme is resolved into the full token set and written to `:root` (10 primary-family + 11 semantic + 11 neutral tokens, see the table below); the utility classes `.s-theme-bg`, `.s-theme-color`, `.s-theme-border`, `.s-theme-border-top`, `.s-theme-icon-bg` are built in.\n3. **body class**: `theme-<VITE_APP_THEME_VALUE>` (e.g. `theme-blue`).\n4. **Menu palette**: a separate `--s-menu-*` set, derived from the primary color (`light`) or fixed antd black (`dark`); the business picks the mode and cannot change the values — see [2.12 Menu palette](#docs-212Menupalettesidetop).\n\n```css\n.my-box {\n color: var(--s-color);\n background: var(--s-bg-color);\n}\n```\n\n**Full token set** (resolved by `packages/utils/theme-vars.js` into `:root` on startup; components and business code use `var(--s-*)` only, never literal colors):\n\n| Group | Token | Default (blue) | Notes |\n| -------------- | ------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------- |\n| Primary family | `--s-color` | `#1677ff` | Primary color from `VITE_APP_THEME` |\n| | `--s-light-color`, `--s-dark-color`, `--s-border-color`, `--s-bg-color` | `#6495ed`, `#00008b`, `#b0c4de`, `#f0f2f5` | Taken straight from the theme |\n| | `--s-color-hover` / `--s-color-active` | `#4592ff` / `#146be6` | Hover (+20% white) / active (+10% black) |\n| | `--s-color-bg` / `--s-color-bg-hover` / `--s-color-border` | `#e8f1ff` / `#d5e7ff` / `#adcfff` | Selected tint / hover tint / light border |\n| Semantic | `--s-color-success`, `--s-color-warning`, `--s-color-error`, `--s-color-info` | `#52c41a`, `#faad14`, `#ff4d4f`, `#1677ff` | Status semantics, theme independent |\n| | `--s-color-success-bg`, `--s-color-warning-bg`, `--s-color-error-bg` | `#f6ffed`, `#fffbe6`, `#fff1f0` | Status tints |\n| | `--s-color-warning-light` / `--s-color-error-light` | `#ffc069` / `#ff7875` | Light status variants (error pages) |\n| | `--s-color-warning-border` / `--s-color-error-border` | `rgba(250,140,22,.42)` / `rgba(245,34,45,.42)` | Translucent status borders |\n| Neutral | `--s-text-color` | `#262626` | Primary text |\n| | `--s-text-color-regular` | `#595959` | Regular text |\n| | `--s-text-color-secondary`, `--s-text-color-disabled`, `--s-text-color-inverse` | `#8c8c8c`, `#bfbfbf`, `#ffffff` | Secondary / disabled / inverse |\n| | `--s-border-color-base`, `--s-border-color-light`, `--s-border-color-split` | `#d9d9d9`, `#e8e8e8`, `#f0f0f0` | Three border levels |\n| | `--s-bg-color-container` / `--s-bg-color-hover` | `#ffffff` / `#f5f5f5` | Container / hover background |\n| | `--s-mask-color` | `rgba(0,0,0,.45)` | Mask |\n\n> Business styles must use `var(--s-*)` instead of literal colors (`#1677ff` / `#e8e8e8` / `rgba(0,0,0,.65)` and the like): primary values come from the primary tokens, greys from the neutral tokens, statuses from the semantic tokens — that is what makes a theme switch a one-line change.\n>\n> Only `blue` / `green` / `orange` / `pink` / `customer` are available; a business project can select a theme but not add one.\n\n### 2.9 Other built-in capabilities\n\n| Built in | How a business project uses it |\n| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| Login / SSO / forgot-password / activation API set | Use the base login page; details in 2.10, visual override in 4.3 |\n| Built-in pages: workplace, todo, message, 403/404/500, `/docs`, `/components` | Open them directly; workplace / home can be overridden by business pages |\n| Static assets, global styles, theme tokens | Shipped inside `packages/static` and `packages/style` — nothing to copy |\n| Common dependencies | Already shipped in `sapit-ui-plus` dependencies, import directly; list in 4.8 |\n\n### 2.10 Login / SSO\n\n- Login page `/login/index`: account + password. Once failures reach the `getLoginConfig` policy (`enabled` + `codeThreshold`), an **image captcha** appears (`/user/verify`); `verificationCode` is submitted as plain text together with `verificationCodeId`.\n- SSO callback: when the URL carries a `code`, the **guard** calls `getCode(code)` to exchange it for a token → stores it via `$utils.ls` → strips the code and does a full page reload (same as the reference project).\n- Related configuration: `VITE_APP_CLIENT_ID` must equal the client registered in the auth center; the API gateway uses `VITE_APP_PORTAL_SERVER_NAME`.\n\n**Four login themes** (`VITE_APP_LOGIN_PATH_THEME`, `1`~`4`; an unset or invalid value falls back to `1`):\n\n`packages/pages/login/index.vue` only resolves the theme id, passes `logo`/`sysName` down and renders the language switcher. Each layout lives in its own page-level component under `login-themes/`, so they are independent and can be edited separately.\n\n| Id | Component | Layout |\n| --- | ----------------- | ----------------------------------------------------------------------------------- |\n| 1 | `LoginTheme1.vue` | Split screen: `login-cover.png` + logo + system name on the left, form on the right |\n| 2 | `LoginTheme2.vue` | Full-bleed `login-cover-right.png`, form pinned left (`padding-left: 336px`) |\n| 3 | `LoginTheme3.vue` | Full-bleed `login-cover-center.png`, form centred (**web-config default**) |\n| 4 | `LoginTheme4.vue` | Dark-blue brand panel + white card, same as the portal ops console (full version) |\n\n**Theme 4 capabilities** (`login-themes/LoginTheme4.vue`):\n\n- Account/password login + remember me (stores `LOGIN_ACCOUNT`, account only, never the password).\n- Image captcha: shown once failures reach the `getLoginConfig` threshold; click the image to refresh.\n- Account lock countdown: when the backend returns `lockUser` (`lockEndTime`/`nowTime`) the button switches to `a-statistic-countdown` and login stays disabled until it ends.\n- \"Activate account\" entry: visibility is driven by `defaultActivateAccount` from `getSysAccountConfig`.\n- \"Forgot password\" / \"QR login\": navigate to the built-in `/user/forgotPassword` and `/user/qrCode`.\n- Office code: entering via `/login/:officeCode` stores the code as `officeCode` in `$utils.ls`.\n- After a successful login: writes `token` / `USER-TOKEN`; when `redirect_client_id` is present it resolves the client list and hands over to `sso.html` for client authorization, otherwise it returns to `VITE_APP_DEFAULT_PATH`.\n- The form column is **flex-centred** (`align-items: safe center` + `justify-content: center`). It deliberately avoids `overflow-y: auto`: the parent `.login-page` is `overflow: hidden`, so scrolling cannot rescue a clipped card; `safe center` degrades to top alignment when the viewport is too short, so the top of the card is never pushed out of view.\n\n**Login helper pages** (`packages/pages/login/`, all `meta.public`, reachable before login):\n\n| Route | Component | Description |\n| ---------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `/user/qrCode` | `qr-code.vue` | QR login: fetches a key via `qrLogin/generate`, renders with `a-qrcode`, counts down validity, expired overlay + refresh |\n| `/user/forgotPassword` | `forgot-password.vue` | Four steps: pick method → account info → verify code (gets a temporary token) → set new password; policy from `sysPwdConfig` |\n| `/user/activate` | `activate.vue` | Four steps: identity check (+captcha) → SMS/email code → set password (strength bar) → completion summary card |\n| `/user/login` | — | Redirects to `VITE_APP_LOGIN_PATH`; used by the \"back to login\" links on the three pages |\n\n**Account APIs** live in `packages/api/account.js` (pre-login whitelist chain, gateway `VITE_APP_PORTAL_SERVER_NAME`):\n\n| Method | Description |\n| --------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| `getSysAccountConfig` | Activation entry switch (`sysAccountConfig/listByActivate`) |\n| `getPwdConfig` | Password policy (`sysPwdConfig/getFirstData`) |\n| `getLoginQrCodeKey` | QR login key (`qrLogin/generate`) |\n| `getValidationCodeWithoutToken` | Send reset-password verification code |\n| `checkValidationCodeWithoutToken` | Verify code → temporary `access_token` |\n| `updatePasswordWithoutToken` | Reset password with the temporary token (account/password Base64, token via the `user-token` header) |\n| `checkUseInfo` | Activation identity check |\n| `getActivateValidationCode` | Send activation code |\n| `checkActivateValidationCode` | Verify activation code |\n| `activateUpdatePassword` | Set the password during activation |\n\n**SSO static assets are provided by the base**: business projects **no longer maintain `sso.js` / `sso.html` under `public/`** — just import the plugin in `vite.config.js`:\n\n```js\nimport ssoPlugin from 'sapit-ui-plus/vite-plugins/sso-plugin.js'\nssoPlugin()\n```\n\nIn dev the plugin middleware serves them (registered before the internal middleware, shadowing `public` with the packaged version). `sso.html` reads the **same-origin localStorage** (wrapped by vue-ls) when exchanging the token, so a cross-origin platform SSO cannot be used directly.\n\n> ⚠️ `redirect_uri` supports the `{code}` placeholder; **without the placeholder the jump is raw and the code is not exchanged**.\n> The platform standard requires `?code={code}` — keep that in the portal client's `redirectUri`, do not \"optimize\" the placeholder away.\n\n### 2.11 Error pages (301 / 403 / 404 / 500)\n\nThe base ships three error pages. **One page serves both \"the page itself failed\" and \"an API failed\"**, and the wording is selected by the `?api=` query parameter.\n\n| Path | Component | Status sources | Accent |\n| ------ | --------------- | ------------------------------------------------------------------------------------- | ------------------------------ |\n| `/403` | `pages/403.vue` | API 403 (no permission), API 301 (address changed), page without permission | Orange `#fa8c16` |\n| `/404` | `pages/404.vue` | No route matched (catch-all `/:pathMatch(.*)*`), API 404 | Primary color `var(--s-color)` |\n| `/500` | `pages/500.vue` | Reachable directly only; **API 5xx does not redirect**, it still shows a notification | Red `#f5222d` |\n\n**How the jump shows**: the error page is switched **inside the content area** — the sidebar, header and footer stay as they are, the shell is never replaced. A page 404 (no route matched) and an API 404 behave exactly the same.\n\n**Login-free**: `/403`, `/404` and `/500` carry `meta.public` (an API failure may mean the token is already gone, and the page must not get stuck in the login guard); the catch-all `/:pathMatch(.*)*` **does not** — an unauthenticated visit to an unknown URL still goes to login.\n\n**API status mapping** (`packages/utils/request.js`):\n\n| HTTP status | Behaviour | Target URL |\n| ------------------------- | --------------------------------------------------------- | --------------------------------------- |\n| 301 | Go to the 403 page with the \"API address changed\" wording | `/403?api=<api>&status=301&from=<page>` |\n| 403 | Go to the 403 page with the \"no API permission\" wording | `/403?api=<api>&status=403&from=<page>` |\n| 404 | Go to the 404 page with the \"API does not exist\" wording | `/404?api=<api>&status=404&from=<page>` |\n| Anything else (incl. 5xx) | **No redirect**, a notification is shown as before | — |\n\n**Query parameters**:\n\n| Parameter | Meaning |\n| --------- | ---------------------------------------------------------------------------------------------- |\n| `api` | Failing API address. **Its presence switches to the API wording**; page-level failures omit it |\n| `status` | Original status code; `301` gets its own \"API address changed\" wording |\n| `from` | Source page address (with `VITE_APP_BASE_URL` stripped), rendered as the \"source address\" line |\n\nWording matrix:\n\n| Source | 403 page | 404 page |\n| ---------------- | ---------------------------- | ------------------ |\n| Page (no `api`) | Insufficient page permission | Page not found |\n| API (with `api`) | No API permission | API does not exist |\n| API 301 | API address changed | — |\n\nThe two buttons: \"Back to home\" uses `VITE_APP_DEFAULT_PATH` (default `/workplace/index`); \"Back\" calls `router.back()` and falls back to home when there is no history, so the button is never dead.\n\n**Skipping the redirect** (polling, auxiliary requests — keeps one failing side request from taking over the whole page):\n\n```js\n// the third argument accepts { skipErrorPage: true } (also readable from the request meta)\nwindow.$utils.http.post(url, data, { skipErrorPage: true })\n```\n\n**Changing colors / wording**:\n\n- All wording lives in i18n entries (`packages/pages/i18n.js`, namespace `pages`).\n- The 403 and 500 pages each declare `--e-color` (accent), `--e-light-color` (light accent) and `--e-border-color` (dashed border) on their root node, so the business can override them with the same variables; the 404 page uses the primary `--s-color` and follows `VITE_APP_THEME_VALUE`.\n- All three pages fill the content area at `height:100%`, so long content only scrolls inside the card and never creates a page-level scrollbar.\n\n> The error pages sit under `BasicLayout`, so the layout still fires the `getSystemIcon` and message-count requests. If those are auxiliary endpoints that can fail on their own, give them `skipErrorPage: true`; otherwise a 403 can bounce to the 404 page.\n\n### 2.12 Menu palette (side / top)\n\nThe palette is either **derived from the primary color** (`light`) or a **fixed antd black** (`dark`). On startup `packages/utils/menu-theme.js` emits solid `#rrggbb` values (**no rgba / alpha**), writes them to `:root` as `--s-menu-*` and exposes `window.$menuTheme` (antd `Menu` tokens + `isLightBg`). Switching `VITE_APP_THEME_VALUE` re-derives the whole menu — it is no longer a hard-coded pale blue.\n\n| Part | CSS variable | `light` (orange default) | `light` (blue) | `light` (green) | `dark` |\n| -------------------- | ---------------------------------------------- | ------------------------ | -------------- | --------------- | ------------------- |\n| Top-level background | `--s-menu-bg` | `#f9f1e1` | `#e1ebf9` | `#e1f9ef` | `#001529` |\n| Submenu panel | `--s-menu-sub-bg` | `#fcf9f2` | `#f2f7fc` | `#f2fcf8` | `#000c17` |\n| Hovered item | `--s-menu-hover-bg` | `#f4e4c8` | `#c8daf4` | `#c8f4e1` | `#1a2c3e` |\n| Selected item | `--s-menu-active-bg` | `#fff1d6` | `#dae9ff` | `#d6f4e7` | `#FFA500` (primary) |\n| Normal text | `--s-menu-text` | `#514734` | `#344051` | `#345145` | `#d7dde6` |\n| Hover text | `--s-menu-text-hover` | `#825d17` | `#1f5aad` | `#14714a` | `#ffffff` |\n| Selected text | `--s-menu-text-active`, `--s-menu-active-text` | `#8b6318` | `#1a4d93` | `#157950` | `#ffffff` |\n| Group title text | `$menuTheme.groupTitle` | `#8a7a5c` | `#5c6f8a` | `#5c8a77` | `#737e89` |\n| `isLightBg` | — | `true` | `true` | `true` | `false` |\n\n> The three `light` columns are **one set of rules** evaluated against different primary colors (`VITE_APP_MENU_BG: 'theme'`): hue from the primary, saturation capped by `_BG_SATURATION`, lightness from `_BG_LIGHTNESS`, and text colors solved for a contrast ratio >= 4.6. `dark` fixes the antd black background and ignores `VITE_APP_MENU_BG`; only the selected item follows the primary color.\n\n**Following the OS light / dark setting**\n\n`VITE_APP_THEME_FOLLOW_SYSTEM` (default `true`) is handled by `packages/utils/color-scheme.js`: it listens to `prefers-color-scheme`; when the OS goes dark it **immediately** recomputes the menu in `dark`, swaps the neutral tokens to their dark variants and adds `scheme-dark` to `body` — and restores everything when the OS goes light. No reload needed.\n\n| Token | Light | Dark |\n| -------------------------- | --------- | -------------------- |\n| `--s-text-color` | `#262626` | `#e8e8e8` |\n| `--s-text-color-secondary` | `#8c8c8c` | `#a6a6a6` |\n| `--s-bg-color-container` | `#ffffff` | `#1f1f1f` |\n| `--s-border-color-base` | `#d9d9d9` | `#3d3d3d` |\n| `--s-color-warning-bg` | `#fffbe6` | `#2b2413` (darkened) |\n\n> ⚠️ The dark tokens only affect places that **read `var(--s-*)`**. Hard-coded `background: #fff` in business pages will not darken on its own — switch those to `var(--s-bg-color-container)`, or write your own overrides under `body.scheme-dark`.\n> With the switch off (`VITE_APP_THEME_FOLLOW_SYSTEM: false`) the scheme stays as configured by `VITE_APP_MENU_THEME`; businesses that already set `dark` are unaffected.\n\n**The business picks the mode, never the colors**\n\nOnly three keys are optional:\n\n| Config | Default | Notes |\n| ------------------------------ | ------- | ------------------------------------------------------ |\n| `VITE_APP_MENU_BAR` | `left` | `left` sidebar / `top` top bar (a layout option) |\n| `VITE_APP_MENU_THEME` | `light` | `light` derived from the primary / `dark` black |\n| `VITE_APP_THEME_FOLLOW_SYSTEM` | `true` | Whether to follow the OS `prefers-color-scheme` |\n\nThe 11 color / tuning keys below **are force-written back on base startup**, so menu colors set in the business `.env`, `src/config/web-config.js` or the deployed `config.json` all have no effect — every business project matches the base demo exactly, by design:\n\n| Key | Default | Purpose |\n| ------------------------------ | ------- | ---------------------------------------------------------- |\n| `VITE_APP_MENU_BG` | `theme` | Top-level background: `theme` follows the primary / `#RRGGBB` |\n| `VITE_APP_MENU_BG_LIGHTNESS` | `93` | Top-level lightness, 0-100 |\n| `VITE_APP_MENU_BG_SATURATION` | `66` | Saturation ceiling, 0-100 |\n| `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | Share of the primary color in the selected block, 0-100 |\n| `VITE_APP_MENU_SUB_BG` | empty | Submenu panel background; empty = derived from the hue |\n| `VITE_APP_MENU_HOVER_BG` | empty | Hovered item background; empty = derived from the hue |\n| `VITE_APP_MENU_ACTIVE_BG` | empty | Selected block background; empty = primary mixed with white |\n| `VITE_APP_MENU_TEXT` | empty | Normal text color; empty = derived from the hue |\n| `VITE_APP_MENU_TEXT_HOVER` | empty | Hover text color |\n| `VITE_APP_MENU_TEXT_ACTIVE` | empty | Selected text color |\n| `VITE_APP_MENU_GROUP_TITLE` | empty | Group title color |\n\n> To verify the lock yourself: put `\"VITE_APP_MENU_BG\": \"#ff0000\"` into the business `config.json` and reload — the menu still uses the palette derived from the primary color.\n\n> Notes\n>\n> 1. `VITE_APP_MENU_BG: 'dark'` under `light` is ignored with a warning (a black background belongs to `dark` mode); the pale palette is still used.\n> 2. Per-part color overrides only apply to `light`; `dark` stays pure black, so a \"black background + pale blue submenu\" mix cannot happen.\n> 3. Do not hard-code menu colors such as `#001529` or `rgba(255,255,255,.1)` in business styles — use `var(--s-menu-*)`.\n> 4. The side menu, the top menu (`VITE_APP_MENU_BAR: 'top'`), the logo variant and the header text color all read `window.$menuTheme.isLightBg`, not `VITE_APP_MENU_THEME` — OS dark-mode following rewrites it, so always branch on this field.\n> 5. `window.$menuTheme` is a `reactive` object: light / dark switching only mutates its properties (same reference), so `SSideMenu`'s `computed` reading `window.$menuTheme.token` re-evaluates and the antd `Menu` tokens follow without any manual refresh.\n\n## 3. Build and configuration\n\n### 3.1 How a business project picks up base changes\n\nThe base is published as the npm package `sapit-ui-plus`, and business projects consume **pre-built output**, not source:\n\n| Scenario | How it takes effect |\n| ------------------------------------------- | -------------------------------------------------------------------------------------------------- |\n| The base changed components / config / copy | Base releases → business updates the dependency (`npm start`, or delete the lock file and `npm i`) |\n| Only business pages changed | Restart the business dev server |\n\n> When updating the dependency you **must delete the lock files** (`package-lock.json` / `yarn.lock` / `node_modules/.package-lock.json`), otherwise the install stays pinned to an old commit and it looks like \"the new base feature never arrived\".\n\n### 3.2 Configuration sources and priority\n\n```text\nbase defaultEnv < business web-config.js < .env.[sapit-base-template] (written into config.json at build time) < deployed config.json (runtime override)\n```\n\n- `web-config.js`: may hold defaults or `import.meta.env.VITE_APP_*`;\n- `.env` / `.env.[sapit-base-template]`: one set per environment (dev/test/uat/prod), written into `config.json` by the business `vite.config.js`;\n- `config.json`: at the site root (or `<base>config.json` for sub-path deploys), fetched and merged by `loadRemoteConfig()` at startup, **editable after deployment without rebuilding**; values in `.env` are strings and the base normalizes `\"true\"/\"false\"` to booleans.\n\nCommon switches (the business may override them; checks use `!== false`, so an unset value keeps the base default):\n\n| Option | Default | Description |\n| ------------------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `VITE_APP_FOOTER_VISIBLE` | `false` | Whether to show the footer |\n| `VITE_APP_MESSAGE_VISIBLE` | `true` | Whether to show the message bell at the top right (set `false` to hide) |\n| `VITE_APP_SOCKET_URL` | `ws://127.0.0.1:8080/websocket` | Socket address: **protocol + host + port only, no `/apig/` or any path**; empty or `/` means same origin; the local placeholder is skipped automatically outside a local machine |\n| `VITE_APP_SOCKET_PATH` | `/apig/ws/websocket` | socket.io handshake path, must match the backend (the only place the service path is defined) |\n| `VITE_APP_LANG_ENABLE` | `false` | Whether internationalization is enabled |\n\n> The 14 menu-palette keys (`VITE_APP_MENU_BAR` / `_THEME` / `THEME_FOLLOW_SYSTEM` are optional, the other 11 are locked by the base) are **listed once in [2.12 Menu palette](#docs-212Menupalettesidetop)**.\n\nThere is **one socket connection for the whole site** (`packages/utils/socket.js`, a singleton — same as the source project registering `VueSocketIO` once). Message badge and QR-code login share the same address and the same `path`, separated only by event names:\n\n| Feature | Emits | Listens to | Module |\n| ----------------------- | --------------------- | ----------- | ----------------------------------- |\n| Top-right message badge | `sendUserId` (userId) | `wsEvent` | `packages/utils/message-socket.js` |\n| QR-code login | `QRCodeKey` (qrId) | `QRWsEvent` | `packages/utils/qr-login-socket.js` |\n\nBadge logic: on entering the system it calls `message/center/counts` for `totalCount`, and afterwards every `wsEvent` pushed over the socket triggers a refetch. The business registers nothing extra — just point `VITE_APP_SOCKET_URL` / `VITE_APP_SOCKET_PATH` at the gateway.\n\n> Putting a path into `VITE_APP_SOCKET_URL` breaks the handshake: socket.io treats the URL path as the **namespace** (`io('http://h:50001/apig/')` → namespace `/apig/`), the server answers `Invalid namespace`, the WebSocket opens but the socket never connects and no `connect_error` is raised. The base strips the path in `resolveSocketUrl` as a fallback, but the config should still be written correctly.\n\n### 3.3 Starting a business project (`npm start`)\n\nA business project's (`sapit-base-template`) `npm start` runs the bundled script `refresh-sapit-base-template.ps1`:\n\n1. remove `node_modules/.vite`, `node_modules/sapit-ui-plus` and the lock files (`package-lock.json`/`yarn.lock`/`pnpm-lock.yaml`/`node_modules/.package-lock.json`);\n2. `npm install` to pull the latest published `sapit-ui-plus`;\n3. run `npm run dev` automatically.\n\n> Purpose: clear the dependency cache, update business dependencies and start in one step. You can also double-click `refresh-sapit-base-template.cmd`; `-NoStart` only updates without starting.\n> This command is normally needed only when the base project has been updated.\n\n## 4. Business project integration\n\n### 4.1 Install\n\n```json\n{ \"dependencies\": { \"sapit-ui-plus\": \"git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git\" } }\n```\n\n### 4.2 Entry `main.js`\n\n```js\nimport { createApp } from 'vue'\nimport App from './App.vue'\nimport config from './config/web-config'\nimport appConfig from './config/app-config'\nimport SapitUiPlus from 'sapit-ui-plus'\nimport 'sapit-ui-plus/lib/css/style.css'\n\nasync function init() {\n const pages = import.meta.glob('@/views/**/*.vue')\n const app = createApp(App)\n app.use(SapitUiPlus)\n await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages)\n app.mount('#app')\n}\ninit()\n```\n\n- `config`: environment configuration (web-config);\n- `appConfig`: build-time configuration (login/home overrides, static routes, language packs) that **never enters config.json**;\n- `pages`: every business page, used by dynamic routing to match `hrefs`.\n\n### 4.3 Login page / home override\n\n`app-config.js`:\n\n```js\nexport default {\n components: {\n login: () => import('@/views/login/index.vue'),\n home: () => import('@/views/home/index.vue')\n }\n}\n```\n\nWhen not configured, the base defaults are used (`pages/login.vue`, `todo.vue`).\n\n### 4.4 Static pages `staticRoutes`\n\n```js\nexport default {\n staticRoutes: [\n {\n path: '/help',\n name: 'Help',\n component: () => import('@/views/help/index.vue'),\n meta: { title: 'Help' } // hidden: not in the menu; public: no login required\n }\n ]\n}\n```\n\n`layout: false` / `raw: true` skips `BasicLayout`; a business route with the same `path` overrides the built-in one.\n\n### 4.5 Business pages and menus\n\nBackend menu `hrefs` must match the business `views` path (or the component name); any page under `src/views/**` is picked up by dynamic routing. The side menu renders \"dynamic menu + `staticRoutes`\" and the base's constant routes never appear in it.\n\n### 4.6 Sub-path deployment (example `/monitor/`)\n\n1. `.env`: `VITE_APP_BASE_URL=/monitor/`;\n2. business `vite.config.js`: `base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/'`;\n3. the base router base, `$push`/`$open`, `redirectLogin` and `parseAppUrl` all read that value and prefix automatically;\n4. nginx:\n\n```nginx\nlocation /monitor/ {\n alias /home/project/tmp/dist/;\n index index.html;\n try_files $uri $uri/ /monitor/index.html;\n}\nlocation = /monitor/config.json {\n alias /home/project/tmp/dist/config.json;\n add_header Cache-Control \"no-store\";\n}\n```\n\n> `createWebHistory` base, the Vite `base` and every `window.location` jump must all be `/monitor/` (with the trailing slash).\n\n### 4.7 Using components and permissions\n\n```html\n<template>\n <s-list-layout :columns=\"columns\" :load-data=\"page\" title=\"Example\" />\n <s-user-select v-model:value=\"ids\" />\n <a-button v-action=\"'add'\">Add</a-button>\n</template>\n```\n\nAfter the backend delivers `permissions` the base writes `permission`, and `v-action:xxx` controls button-level permission. Documentation is available at `<business base>/docs` and `<business base>/components`.\n\n---\n\n### 4.8 Built-in dependencies (ready to use in a business project)\n\nThe `dependencies` of `sapit-ui-plus` are installed into the business `node_modules` together with the base, so the business can **import them without installing anything** (a business `package.json` usually only lists `sapit-ui-plus`).\n\n| Dependency | Version | Purpose |\n| ------------------------------------------------ | ---------------------- | ---------------------------------------------------------------- |\n| `dayjs` | ^1.11.12 | Date formatting (recommended, also used inside `$utils`) |\n| `axios` | ^1.7.3 | Requests (wrapped as `window.$utils.http`, rarely used directly) |\n| `qs` | ^6.13.0 | Parameter serialization (`stringify`) |\n| `lodash.get` / `lodash.clonedeep` | ^4.4.2 / ^4.5.0 | Safe access / deep clone |\n| `crypto-js` | ^4.2.0 | Encryption / decryption |\n| `js-base64` | ^3.7.2 | Base64 encode/decode |\n| `jsencrypt` | ^3.3.2 | RSA encryption |\n| `moment` | ^2.30.1 | Dates (legacy compatibility; use dayjs for new code) |\n| `html2canvas` | ^1.4.1 | Page screenshots |\n| `nprogress` | ^0.2.0 | Top loading progress bar |\n| `@vueuse/core` | ^11.0.3 | Composition utilities |\n| `vue-cropper` | ^1.1.4 | Image cropping (used by SCopperUpload) |\n| `vuedraggable` | ^4.1.0 | Drag-and-drop sorting |\n| `v-clipboard` | ^3.0.0-next.1 | Copy to clipboard (`v-clipboard` directive) |\n| `vue-ls` | ^4.2.0 | localStorage wrapper (already exposed as `$utils.ls`) |\n| `jodit` | 3.24.7 | Rich text editor (SEditor) |\n| `less` / `less-loader` | ^4.2.0 / ^12.2.0 | Style compilation |\n| `vite-plugin-html` / `vite-plugin-generate-file` | ^3.2.2 / ^0.2.0 | Build plugins (generate config.json etc.) |\n| `@ant-design/icons-vue` | follows ant-design-vue | Icons, **all registered globally as components** |\n\n**Singleton dependencies: the base does not bundle them and the business must install them itself** (`external` in `vite.config.js`), otherwise two module instances appear (routes cannot be injected, pinia mismatches, theme/message context is lost):\n\n| Dependency | Version |\n| ---------------- | ------- |\n| `vue` | ^3.4.29 |\n| `vue-router` | ^4.3.3 |\n| `pinia` | ^2.1.7 |\n| `vue-i18n` | ^9.14.0 |\n| `ant-design-vue` | 4.x |\n\n> Usage: `import dayjs from 'dayjs'` just works; but **do not** install a second copy of `vue`/`ant-design-vue`/`pinia` with a different major version in the business — the base version wins.\n\n## 5. Caveats\n\n### 5.1 On the business side\n\n1. <span style=\"color:#d4380d;font-weight:700\">Dependencies are prebuilt artifacts</span>: a base change only takes effect after `npm run build` + push + reinstalling dependencies in the business; the base's own dev server reflects changes immediately.\n2. <span style=\"color:#d4380d;font-weight:700\">Lock files pin the old commit</span>: delete `package-lock.json`, `yarn.lock` and `node_modules/.package-lock.json` before updating.\n3. <span style=\"color:#d46b08;font-weight:700\">Sub-path</span>: keep `VITE_APP_BASE_URL` and the Vite `base` identical and trailing-slashed.\n4. <span style=\"color:#d46b08;font-weight:700\">Components are globally available</span>: every `S*` component and `STable` is registered by the base — just write the tag; do not import it and do not register it locally again.\n5. <span style=\"color:#d46b08;font-weight:700\">Theme / menu palette / i18n</span>: all defined in the base. The business only picks `VITE_APP_THEME_VALUE`, `VITE_APP_MENU_THEME` and `VITE_APP_THEME_FOLLOW_SYSTEM`, and writes i18n copy; `VITE_APP_MENU_*` color values are forced back (see 2.7 / 2.8 / 2.12).\n6. <span style=\"color:#d46b08;font-weight:700\">Deep imports into base internals are not allowed</span>: the lib output has a single entry, `lib/js/index.js`, and internal modules are rolled into chunks. To expose a capability to the business, attach it as a global property (like `$utils` / `$modal`).\n7. <span style=\"color:#d4380d;font-weight:700\">Feature parity</span>: whatever the reference (old Vue2) project has, we have; do not \"helpfully\" add what it does not have. Confirm the reference implementation before adding a feature.\n\n### 5.2 Business dictionary / form conventions (hy-monitor)\n\n8. **Always bind dropdown values and copy to the dictionary item's `value` (the dictionary value), never its `id` (primary key)**. Fetch several dictionaries at once with `mapByDictTypes('a','b')` and read the result with **underscores converted to camelCase** (`recycle_status` → `res.recycleStatus`); each item is `{label, value, id}`.\n9. **An `a-select` placeholder only shows when the value is `undefined`/`null`**; an empty string `''` counts as an existing value. Initialize every dropdown-like field (search parameters, form fields) to `undefined` and **never `''`** (multi-select binding to `[]` is fine).\n10. **Time range parameters are always millisecond timestamps** (`dayjs(x).valueOf()`), not unix seconds. Basis: the reference `DateRange` onChange emits `date.map(o => dayjs(o).valueOf())` and `useFormValues.fieldMapToTime` passes values through by default (`format=''`).\n11. **Do not add `catch` to API requests** (errors are reported by the global interceptor). Three kinds of catch must stay: ① the form validation chain `.catch(() => {})`; ② `try { await validate() } catch { return }`; ③ tolerant `JSON.parse`.\n12. **API failures navigate to the built-in error pages**: 403 (301 included) — `/403`, 404 — `/404`, swapped inside the content-area `router-view` with no notification stacked on top; **5xx does not navigate** and keeps the normal notification. Auxiliary requests (polling) can pass `{ skipErrorPage: true }` to keep the current page. Query parameters, wording and color overrides: see 2.11:\n\n```js\nthis.$utils.http.post('/api/msg/count', {}, { skipErrorPage: true })\n```\n\n---\n\n## 6. Online documentation entry\n\n| Address | Content |\n| ------------------- | ---------------------------------------------------------------- |\n| `<base>/docs` | This guide |\n| `<base>/components` | s components (built-in components: left menu + preview + source) |\n", V = () => {
- var n, t;
- try {
- return ((t = (n = window.$utils) == null ? void 0 : n.ls) == null ? void 0 : t.get("lang")) === "en";
- } catch (r) {
- return !1;
- }
- }, M = {
- name: "DocsPage",
- components: { DocsBackTop: T },
- data() {
- return {
- html: ""
- };
- },
- mounted() {
- this.render();
- },
- methods: {
- render() {
- this.html = E(V() ? $ : C);
- }
- }
- }, U = { class: "s-docs-page" }, R = ["innerHTML"];
- function O(n, t, r, e, o, i) {
- const a = v("router-link"), s = L, h = v("s-panel-layout"), g = v("docs-back-top");
- return P(), S(A, null, [
- c(h, {
- title: "sapit-ui 文档",
- headerSticky: !0,
- height: "100vh"
- }, {
- extra: p(() => [
- c(a, {
- class: "nav-item",
- to: "/"
- }, {
- default: p(() => [
- m(f(n.$l("首页")), 1)
- ]),
- _: 1
- }),
- c(s, { type: "vertical" }),
- c(a, {
- class: "nav-item active",
- to: "/docs"
- }, {
- default: p(() => [
- m(f(n.$l("说明文档")), 1)
- ]),
- _: 1
- }),
- c(s, { type: "vertical" }),
- c(a, {
- class: "nav-item",
- to: "/components"
- }, {
- default: p(() => [
- m(f(n.$l("组件")), 1)
- ]),
- _: 1
- }),
- c(s, { type: "vertical" }),
- c(a, {
- class: "nav-item",
- onClick: t[0] || (t[0] = (l) => n.view = "tools")
- }, {
- default: p(() => [
- m(f(n.$l("工具/配置")), 1)
- ]),
- _: 1
- })
- ]),
- default: p(() => [
- _("div", U, [
- _("div", {
- class: "docs-body",
- innerHTML: o.html
- }, null, 8, R)
- ])
- ]),
- _: 1
- }),
- c(g)
- ], 64);
- }
- const D = /* @__PURE__ */ I(M, [["render", O], ["__scopeId", "data-v-59499894"]]);
- export {
- D as default
- };
|