docs.js 163 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145
  1. import { resolveComponent as k, openBlock as _, createElementBlock as T, createElementVNode as p, createTextVNode as m, toDisplayString as g, createVNode as y, withCtx as v } from "vue";
  2. import { n as P } from "./index2.js";
  3. const f = (r = "") => String(r).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"), E = (r = "") => String(r).replace(/[^\w\u4e00-\u9fa5-]/g, ""), c = (r = "") => {
  4. const n = [], i = [];
  5. let e = String(r);
  6. return e = e.replace(/`([^`]+)`/g, (t, o) => (n.push(`<code>${f(o)}</code>`), `\0C${n.length - 1}\0`)), e = e.replace(/<\/?span[^>]*>/g, (t) => (i.push(t), `\0S${i.length - 1}\0`)), e = f(e), e = e.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>'), e = e.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>"), e = e.replace(/\u0000C(\d+)\u0000/g, (t, o) => n[+o]), e = e.replace(/\u0000S(\d+)\u0000/g, (t, o) => i[+o]), e;
  7. }, w = (r = "") => r.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((n) => n.trim()), I = (r = "") => /^\s*\|?[\s:|-]+\|?\s*$/.test(r) && r.includes("-"), S = (r = "") => {
  8. const n = String(r).replace(/\r\n/g, `
  9. `).split(`
  10. `), i = n.length;
  11. let e = 0, t = "", o = null;
  12. const s = () => {
  13. o && (t += `</${o}>
  14. `, o = null);
  15. };
  16. for (; e < i; ) {
  17. const a = n[e], b = a.match(/^```(\w*)\s*$/);
  18. if (b) {
  19. s();
  20. const l = b[1];
  21. e++;
  22. const d = [];
  23. for (; e < i && !/^```\s*$/.test(n[e]); )
  24. d.push(n[e]), e++;
  25. e++, t += `<pre class="docs-code" data-lang="${l}"><code>${f(d.join(`
  26. `))}</code></pre>
  27. `;
  28. continue;
  29. }
  30. if (/^\s*$/.test(a)) {
  31. s(), e++;
  32. continue;
  33. }
  34. if (/^-{3,}\s*$/.test(a)) {
  35. s(), t += `<hr/>
  36. `, e++;
  37. continue;
  38. }
  39. const u = a.match(/^(#{1,6})\s+(.*)$/);
  40. if (u) {
  41. s();
  42. const l = u[1].length, d = u[2].trim();
  43. t += `<h${l} id="docs-${E(d)}">${c(d)}</h${l}>
  44. `, e++;
  45. continue;
  46. }
  47. if (/^>\s?/.test(a)) {
  48. s();
  49. const l = [];
  50. for (; e < i && /^>\s?/.test(n[e]); )
  51. l.push(n[e].replace(/^>\s?/, "")), e++;
  52. t += `<blockquote>${S(l.join(`
  53. `))}</blockquote>
  54. `;
  55. continue;
  56. }
  57. if (/^\s*\|/.test(a) && e + 1 < i && I(n[e + 1])) {
  58. s();
  59. const l = w(a);
  60. e += 2;
  61. const d = [];
  62. for (; e < i && /^\s*\|/.test(n[e]); )
  63. d.push(w(n[e])), e++;
  64. t += "<table><thead><tr>" + l.map((h) => `<th>${c(h)}</th>`).join("") + "</tr></thead><tbody>" + d.map((h) => "<tr>" + h.map((x) => `<td>${c(x)}</td>`).join("") + "</tr>").join("") + `</tbody></table>
  65. `;
  66. continue;
  67. }
  68. if (/^\s*[-*]\s+/.test(a)) {
  69. o !== "ul" && (s(), t += `<ul>
  70. `, o = "ul"), t += `<li>${c(a.replace(/^\s*[-*]\s+/, ""))}</li>
  71. `, e++;
  72. continue;
  73. }
  74. if (/^\s*\d+\.\s+/.test(a)) {
  75. o !== "ol" && (s(), t += `<ol>
  76. `, o = "ol"), t += `<li>${c(a.replace(/^\s*\d+\.\s+/, ""))}</li>
  77. `, e++;
  78. continue;
  79. }
  80. s(), t += `<p>${c(a.trim())}</p>
  81. `, e++;
  82. }
  83. return s(), t;
  84. }, A = "# sapit-ui 基座说明与业务使用文档\r\n\r\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>(业务示例)\r\n>\r\n> 本文档也是基座内置文档页 `/docs` 与组件页 `/components` 的数据源。\r\n\r\n---\r\n\r\n## 目录\r\n\r\n- [一、总览](#docs-一总览)\r\n- [二、基座提供的内容](#docs-二基座提供的内容)\r\n- [三、布局与高度规范](#docs-三布局与高度规范)\r\n- [四、构建与配置](#docs-四构建与配置)\r\n- [五、业务项目接入](#docs-五业务项目接入)\r\n- [六、注意事项](#docs-六注意事项)\r\n- [七、常见全局方法速查](#docs-七常见全局方法速查)\r\n- [八、在线文档入口](#docs-八在线文档入口)\r\n\r\n---\r\n\r\n## 一、总览\r\n\r\n### 1.1 五者关系\r\n\r\n| 工程 | 角色 | 说明 |\r\n| --------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |\r\n| `sapit-ui-framework` | <span style=\"color:#d4380d\">基座(源码)</span> | 内置组件与常用依赖的库工程,Vite lib 模式打包 |\r\n| `sapit-ui-plus` | <span style=\"color:#d46b08\">发布产物</span> | 基座 `dist` 推送后的 git 仓库(`lib/`、`docs/`、`vite-plugins/`) |\r\n| `sapit-base-template` | <span style=\"color:#389e0d\">业务使用者</span> | 以 `sapit-ui-plus` git 依赖为底层,编写业务页面/配置 |\r\n\r\n```text\r\nsapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template\r\n```\r\n\r\n### 1.2 目录结构(基座)\r\n\r\n```text\r\nsapit-ui-framework/\r\n├─ packages/ # 发布内容来源(入口依赖图)\r\n│ ├─ index.js # 库入口,导出 registerGlobalConfig\r\n│ ├─ components/ # 内置组件 S*\r\n│ ├─ layouts/ # BasicLayout / BlankLayout / UserLayout / RouteView / PageView\r\n│ ├─ router/ # 常量路由 + 动态路由 + 静态路由 + 守卫\r\n│ ├─ store/ api/ utils/ locales/ static/ style/\r\n│ └─ pages-components/ # 登录、工作台、待办、消息、404/403/500、docs 文档页\r\n├─ docs/ # 本文档(供内置 /docs 渲染)\r\n├─ vite-plugins/ # docs-viewer 插件\r\n├─ src/ # 基座自身调试壳\r\n└─ vite.config.js / package.json\r\n```\r\n\r\n---\r\n\r\n## 二、基座提供的内容\r\n\r\n### 2.1 全局组件\r\n\r\n`packages/index.js` 用 `import.meta.glob('./components/**/*.vue')` 把 `components/**/*.vue` **按文件名全局注册**,模板直接以文件名标签使用(如 `<s-modal>`、`<s-user-select>`)。\r\n\r\n| 分类 | 组件 |\r\n| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| 布局类 | `SSkeletonLayout`(骨架布局:标题 + 按钮组 + 内容区,见 2.16)、`SListLayout`、`SListCardLayout`、`SListTableTreeLayout`、`SSuperListLayout`、`SFormLayout`、`SPanelLayout`、`SCollapses`/`SCollapsesItem`、`SDrawer` |\r\n| 弹层类 | `SModal`、`SModalTemplate`、`ModalHeader`、`SIconModal`、`SImportModal`(批量导入,见 2.11) |\r\n| 表单/筛选 | `SForm`、`SFormItem`、`SExtendFieldsForm`/`SExtendFieldsFormItem`(动态扩展字段)、`SFilterWrap`、`SFilterItem`、`SCascader`、`STree`、`STreeSelect`、`SDataRangeTreeSelect`(数据权限范围树)、`SUserSelect`、`SUserSelectButton`、`SChooseUser`(带数据权限选人弹窗,见 2.14)、`SBelowChoosePosition`(选岗位弹窗,见 2.15)、`SOfficeSelect`、`SIconSelect`(图标选择) |\r\n| 上传类 | `SFileUpload`、`SDraggerUpload`、`SCopperUpload`、`CropperModal` |\r\n| 展示/其它 | `SEditor`、`SEmpty`、`SIcon`、`SSvg`、`SAnchor`、`SColorPicker`、`SToggleLanguage`、`SettingFilter`、`SettingColumns`、`SSideMenu`/`STopMenu` |\r\n\r\n> 组件用法见内置组件页 **`/components`**(含「s组件」「工具/配置」两个标签页;「工具/配置」列出 web-config 全部配置项与 `$utils` 全部方法)。\r\n>\r\n> 注册规则:`components/**/*.vue` 按**文件名**全局注册(`SForm.vue` → `<SForm>`,**不是 kebab-case**),冲突后者覆盖。\r\n> `Table/index.jsx` 是 `.jsx`、`import.meta.glob` 匹配不到,基座在`packages/index.js` 里**单独注册为全局 `STable`**(`<s-table>` 可直接用,无需 import)。\r\n> `@ant-design/icons-vue` 图标全部全局注册并挂到 `$icons`。\r\n> 另有内部辅助组件不对外使用:`ModalHeader`(SModal)、`CropperModal`(SCopperUpload)、`CustomInput`/`SettingColumns`/`SettingFilter`(SSuperListLayout)。\r\n\r\n### 2.1.1 布局组件选择\r\n\r\n| 场景 | 用哪个 |\r\n| ------------------------- | -------------------------------------------------------------------------------------------- |\r\n| 标题 + 按钮 + 自定义内容(无表格/分页/表单) | `SSkeletonLayout`(见 2.16,自带标题条与权限按钮) |\r\n| 普通列表页 | `SListLayout` |\r\n| 卡片列表 | `SListCardLayout` |\r\n| 列表 + 左侧树 | `SListTableTreeLayout`(左侧树容器类名必须是 `.side.s-side-tree`,见 3.5) |\r\n| 带高级搜索/高级表格的列表 | `SSuperListLayout` |\r\n| 新增/编辑/详情(路由式) | `SFormLayout`(`#form` 插槽放 `SForm`,`#footer-callback` 收 `save`/`cancel`/`prev`/`next`) |\r\n| 表单作为弹窗内容 | `SModal`(不要套 `SFormLayout`) |\r\n| 后端下发字段的动态表单 | `SExtendFieldsForm`(`data` + `defaultValue`,ref 调 `validate/clearValidate/getModel`) |\r\n| 数据权限范围选择 | `SDataRangeTreeSelect`(`autoSysConfig` 托管系统 `dataScope` 配置) |\r\n\r\n### 2.2 全局属性 / 方法\r\n\r\n`$registerGlobalConfig` 执行后可用(`this.$xxx` / 模板 `$xxx` / `window.$xxx`):\r\n\r\n| 名称 | 说明 |\r\n| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\r\n| `$registerGlobalConfig(config, pages)` | 初始化入口(见 5.2) |\r\n| `$utils` | 工具类集合:`$utils.env` / `$utils.ls` / `$utils.http` 及通用方法 |\r\n| `env` | 合并后的环境配置(= `$utils.env`) |\r\n| `$i18n` / `$l(name, key)` | 国际化(见 2.7)。挂在 `globalProperties` 上:**模板里直接用** `$l('xx')`;`<script setup>` **脚本内**必须写 `window.$l('xx')`(setup 作用域没有 `this`) |\r\n| `$theme` / `$staticRoutes` / `$pinia` | 主题对象 / 静态路由列表 / 用户 store 实例 |\r\n| `$modal` / `$message` / `$notice` / `$confirm` | antd 的 `Modal` / `message` / `notification` / `Modal.confirm`(列表组件按钮 api 分支会调 `this.$confirm`) |\r\n| `$push(path, query)` / `$open(...)` | 站内跳转 / 新窗口(自动拼 `VITE_APP_BASE_URL`) |\r\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 名 |\r\n\r\n### 2.3 布局\r\n\r\n`packages/layouts/index.js`:`BasicLayout`(头部+侧边菜单+内容区)、`BlankLayout`、`UserLayout`(登录)、`RouteView`、`PageView`。\r\n\r\n`BasicLayout` 的高度链路(**业务布局组件必须与它对齐**,详见第三章):\r\n\r\n```text\r\n.basic-layout-common (100vh)\r\n→ .ant-layout\r\n→ .main-content\r\n→ .container (height = mainHeight = clientHeight - headerHeight)\r\n └─ 有页脚时再减 footerHeight(56)\r\n → router-view (height = contentHeight, overflow: hidden auto)\r\n → 业务布局组件(.list-layout / .form-layout,flex:1)\r\n```\r\n\r\n> `mainHeight` / `contentHeight` 用**真实 `header.offsetHeight`**(不是写死 58)计算,避免与实际渲染不一致产生溢出滚动条。\r\n\r\n### 2.4 路由\r\n\r\n**常量路由**(`packages/router/index.js`):\r\n\r\n| 路径 | 说明 |\r\n| ------------------------------------------ | ------------------------------------------------------------------- |\r\n| `/login/index` | 登录页(默认基座,可被业务覆盖,见 5.3) |\r\n| `/workplace/index` | 默认首页(`VITE_APP_DEFAULT_PATH`,可被覆盖) |\r\n| `/workbench/index`、`/message/index` | 工作台 / 消息 |\r\n| `/docs`、`/components` | 内置文档 / 组件页(`public` 免登录、`hidden` 不进菜单) |\r\n| `/404`、`/403`、`/500`、`/:pathMatch(.*)*` | 错误页;通配渲染 404(**不用 redirect**,保证刷新动态路由不掉 404)。四者都挂在 `BasicLayout` 下,**只在内容区 `router-view` 内切换**,侧边菜单与顶栏保持不变 |\r\n\r\n> 错误页的触发规则、URL 参数、文案口径与改色方法见 [2.17 错误页](#docs-217错误页301403404500)。\r\n\r\n**静态路由**(`staticRoutes`,不依赖后端菜单):见 5.4。基座内置 `/docs`、`/components`。\r\n\r\n**动态路由**(`packages/router/generator-routers.js`):登录后按后端 `menus` 生成树,根节点 `BasicLayout`;叶子节点用 `item.hrefs` 匹配业务 `pages`(`import.meta.glob('@/views/**/*.vue')` 的 key),匹配不到回退 404。注册在守卫中完成(内存标记,刷新重注册)。\r\n\r\n**守卫**:公开页(`meta.public`)直接放行;实时读 token;未登录跳登录;已登录访问登录页/根跳默认首页;取用户信息失败清理并回登录页(避免 pending)。URL 带 `code` 时在守卫里换取 token(见 5.8 权限与 6.1)。\r\n\r\n### 2.5 状态管理(pinia)\r\n\r\n`packages/store/user.js`(`useUserStore`):state `user/menus/permissions/clients/dynamicRouter/menuOpenKeys`;actions `Info()`(拉取并写 localStorage)、`setDynamicRouter()`、`setMenuOpenKeys()`;localStorage 持久化。\r\n\r\n### 2.6 工具类(`$utils`)\r\n\r\n| 模块 | 说明 |\r\n| ---------------------------------- | ------------------------------------------------------------------ |\r\n| `$utils.env` | 环境配置对象 |\r\n| `$utils.ls` | 本地存储(命名空间 `VITE_APP_SYS_SERVER_NAME`) |\r\n| `$utils.http` | axios 实例(token/`client-id` 注入、响应解包、登录超时、文件下载) |\r\n| `parseAppUrl` / `innerRedirect` 等 | 站内地址拼 base(支持子路径),外部 http(s) 原样 |\r\n| `messageFormat(str, values)` | `{0}` / `{name}` 占位符替换,用于确认弹窗等文案 |\r\n| `filterSelectOption(iv, opt)` | antd4 版 `:filterOption`(读 `option.label` / `option.value`) |\r\n| `randomDrawerPlacement()` | 随机返回 `left` / `right` / `top` / `bottom`(源项目交互保留) |\r\n| `iconOf(type)` | antd v1 `<a-icon type=\"info-circle\">` 遗留写法的换算:kebab / snake / Pascal 入参 → 图标组件。用法 `<component :is=\"$utils.iconOf('info-circle')\" />` |\r\n| `hasAction(name)` | 按钮级权限**函数式**判断,与 `v-action` 同源;用于 `v-if` 里的「或 / 且」、算 `disabled` |\r\n| 其它 | 类型判断、日期、数组、url、dom、防抖节流、金额、手机号校验等 |\r\n\r\n> ⚠️ **类型判断 ≠ 格式校验**:`$utils.isNumber` / `isInt` / `isDate` 是 `Object.prototype.toString` 类型判断(`$utils.isNumber('123')` 恒 `false`),**不是**字符串格式校验。业务侧的正则版同名方法(如 `isNumber(str)` 用 `/^(?:-?\\d+|...)/`)**不可**按名字替换过来。\r\n>\r\n> 同理 `$utils.uuid(len)` 是纯随机串,与「时间戳 + 随机数」型 `getUUID()` 产出格式不同,涉后端主键时不可换。\r\n\r\n`v-action:xxx` 按钮级权限指令:`<a-button v-action=\"'add'\">添加</a-button>`。\r\n\r\n- 内部直接调用 `$utils.hasAction(actionName)`,**指令与函数只有一套判定逻辑**\r\n- 数据源优先级:`permission`(**单数**,`router/index.js` 守卫写入的「当前路由按钮数组」)→ 取不到再回退 `permissions`(**复数**,`store/user.js` 写入的全量「路由 → 按钮」map)+ `CURRENT_ROUTER_KEY`\r\n- 匹配规则:`String(button_code) === String(actionName)`,**整体相等**(`add` 不会命中 `batchAdd`)\r\n- 函数式用法:`<a-button v-if=\"$utils.hasAction('add') || $utils.hasAction('edit')\">`\r\n\r\n\r\n### 2.7 国际化\r\n\r\n语言包文件名统一为 `i18n.js`,放在模块的**一级文件夹**下,不带任何前缀,结构是扁平字典:\r\n\r\n```js\r\n// src/views/user/i18n.js -> 命名空间 user\r\nexport default {\r\n '取消': 'Cancel'\r\n}\r\n```\r\n\r\n命名空间取 `views/` 或 `packages/` 之后的第一段目录名(`views/user/i18n.js` → `user`,`packages/components/i18n.js` → `components`)。构建期由 `import.meta.glob` 统一聚合,新增文件、新增目录都不用改任何代码。\r\n\r\n页面里**不用注册**也能翻译:`$l('中文')` 会自动找该页面**所在目录**的 `i18n.js`(路由加载组件时按源文件路径打标 `__i18nNs`,取不到再用路由 path 首段)。需要强制指定别的命名空间时才显式注册:\r\n\r\n```js\r\nexport default {\r\n created() {\r\n this.useI18n('user') // Options API,显式指定,优先级最高\r\n }\r\n}\r\n```\r\n\r\n```js\r\n// <script setup>:可显式传,也可不传(不传就按当前目录自动推断)\r\nconst { $l } = useI18n() // 自动\r\nconst { $l } = useI18n('user') // 显式\r\n```\r\n\r\n`$l(name)` 查找顺序:**当前命名空间(显式注册 > 同目录 i18n > 路由首段)→ `components` 通用词 → 全局兜底字典(`packages/locales/lang/dict.js`)→ 原样返回 + `console.warn`(同一个词只提示一次)**。命名空间不存在时 `useI18n` 也会 `console.warn`,不阻断渲染。\r\n\r\n| 调用位置 | 写法 | 是否带命名空间 |\r\n|---|---|---|\r\n| 模板 / 组件内 `this.$l(...)` | `{{ $l('取消') }}` | 带,自动按上述优先级解析 |\r\n| 组件内 `const { $l } = useI18n()` | `$l('取消')` | 带,同上 |\r\n| 组件外 JS(api / utils) | `window.$l('取消')` | **不带**,只查 `components` + 全局字典 |\r\n\r\n排查用:控制台执行 `$i18nDebug()`,会打印已加载的全部命名空间、当前组件解析到的命名空间及其词条数;`$i18nNamespaces` 是命名空间全量对象。\r\n\r\n中文模式直接返回原文;英文模式查不到译文时原样返回中文并告警。antd 自身语言由 `a-config-provider` 的 `locale` 控制。\r\n\r\n### 2.8 主题\r\n\r\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` 会被忽略。\r\n\r\n生效方式:\r\n\r\n1. **antd**:`a-config-provider` token(`colorPrimary`/`colorLink`)。\r\n2. **CSS 变量**:启动时把选中主题写入 `:root`:`--s-color`、`--s-light-color`、`--s-dark-color`、`--s-border-color`、`--s-bg-color`;并内置工具类 `.s-theme-bg`、`.s-theme-color`、`.s-theme-border`、`.s-theme-border-top`、`.s-theme-icon-bg`。\r\n3. **body 类**:`theme-<VITE_APP_THEME_VALUE>`(如 `theme-blue`)。\r\n4. **菜单配色**:启动时按当前主题色推导整套菜单色(一级底 / 子菜单底 / hover / 选中 / 文字),**全部输出实色 `#rrggbb`,不含透明度**,写入 `:root` 的 `--s-menu-bg`、`--s-menu-sub-bg`、`--s-menu-text`、`--s-menu-text-hover`、`--s-menu-text-active`、`--s-menu-hover-bg`、`--s-menu-active-bg`、`--s-menu-active-text`,同时写入 `window.$menuTheme`(含 antd `Menu` token,`isLightBg` 标记实际明暗)。\r\n\r\n菜单默认是**浅色系**(blue 主题一级底 `#e8ecf3`),四个部位的底色由同一份参数算出,改一个参数整套一起变。**完整色板、配置项说明与各主题实测值见 [2.18 菜单配色](#docs-218菜单配色侧边顶部)**。\r\n\r\n> 底色亮度降到 50 以下会自动切换成「深色底 + 浅色文字」体系,文字与底色的对比度按 WCAG 反解保证 ≥ 4.6,不用手工调文字色。侧边菜单、顶部菜单(`VITE_APP_MENU_BAR: 'top'`)、logo 明暗、顶栏文字色共用这一套判断。\r\n\r\n```css\r\n.my-box {\r\n color: var(--s-color);\r\n background: var(--s-bg-color);\r\n}\r\n```\r\n\r\n> 新增主题:基座 `VITE_APP_THEME` 加一套,业务 `VITE_APP_THEME_VALUE` 选它,antd 与 `var(--s-*)` 自动跟随。\r\n\r\n### 2.9 API / 页面组件 / 其它\r\n\r\n- `packages/api`:`login.js`(登录、`getCode`、`verify`、`rsaPublicKey`、`getLoginConfig` 等)、`common.js`、`upload.js`、`workbench.js`。\r\n- `packages/pages-components`:`login.vue`、`login-common/LoginForm.vue`、`workbench.vue`、`todo.vue`、`message.vue`、`403/404/500.vue`、`docs.vue`、`components-doc.vue`。\r\n- 静态资源 `packages/static/*`;样式 `packages/style/*`;antd 图标、axios、dayjs、moment、pinia、vue-router、vue-i18n、jodit、vue-cropper、vuedraggable、html2canvas、crypto-js、jsencrypt、nprogress、qs、lodash.\\* 等已内置。\r\n\r\n### 2.10 登录 / 单点\r\n\r\n- 登录页 `/login/index`:账号密码登录;登录失败达 `getLoginConfig` 策略(`enabled` + `codeThreshold`)时出现**图片验证码**(`/user/verify`),`verificationCode` 原文提交 + `verificationCodeId`。\r\n- 单点回调:URL 带 `code` 时由**守卫**调 `getCode(code)` 换 token → 存 `$utils.ls` → 去掉 code 整页刷新(与参照项目一致)。\r\n- 关联配置:`VITE_APP_CLIENT_ID` 必须等于业务在认证中心的 client;接口网关用 `VITE_APP_PORTAL_SERVER_NAME`。\r\n\r\n**SSO 静态资源已收编进基座**:源在 `packages/sso/`(`sso.js` / `sso.html`),随 npm 包分发(`files` 加 `sso`,build 拷 `dist/sso`)。业务项目**不再维护 `public/` 下的 sso 文件**,只需在 `vite.config.js` 里:\r\n\r\n```js\r\nimport ssoPlugin from 'sapit-ui-plus/vite-plugins/sso-plugin.js'\r\nssoPlugin()\r\n```\r\n\r\ndev 由插件中间件提供(注册在内部中间件前,用包内版本遮蔽 `public`)。`sso.html` 换token 读的是**同源 localStorage**(vue-ls 包装),跨 origin 的平台 sso 不能直接用。\r\n\r\n> `redirect_uri` 三种处理(`sso.js`):\r\n> 1. 含 `{token}` → 用本地 token 直接替换回跳,不换 code。\r\n> 2. **跳回当前应用自身**(`client_id` = 本应用自己的 client,`redirect_uri` 同源、且无 `{code}` 占位符)→ 账密登录场景,本地已有登录态,**不调用单点**(不校验授权、不换 code),直接回跳。\r\n> 3. **第三方跳转**(功能模块弹窗跳别的 client / 系统)→ 走完整授权码流程:`authorizationCodeValidate` 校验 + `oauth2/code` 换码;有 `{code}` 就替换,无占位符则自动追加 `?code=xxx`。\r\n>\r\n> 「当前应用自己的 client」用本应用 base 定位 namespace(`loginHref` 为锚点)精确读取,不走 key 后缀模糊匹配 —— 同 origin 多应用共用 localStorage 时才不会取到别的应用的 `clientId`。\r\n\r\n### 2.11 SImportModal 通用批量导入弹窗\r\n\r\n三步式导入:**上传文件 → 数据预览(可编辑/删除行)→ 导入结果(含异常数据导出)**。文件限制:`.xls/.xlsx`、≤ 500KB。\r\n\r\n```vue\r\n<s-import-modal\r\n ref=\"importModalRef\"\r\n :upload-url=\"IMPORT_UPLOAD_URL\"\r\n :columns=\"importColumns\"\r\n :apis=\"importApis\"\r\n :type-select=\"importTypeSelect\"\r\n @reload=\"handChange\"\r\n/>\r\n\r\n<script setup>\r\nimportModalRef.value.show() // 打开(内部会重置状态)\r\n\r\nconst importApis = { templateDownload, importPreview, importData, exportExceptionData }\r\nconst importColumns = [{ title: '设备SN码', dataIndex: 'sn', width: 150 }]\r\n// 可选:导入时附带的业务参数下拉,选中值以 extraKey 随各接口一起提交\r\nconst importTypeSelect = computed(() => ({\r\n options: [{ label: '摄像头', value: '1' }],\r\n placeholder: '选择设备分类'\r\n}))\r\n<\/script>\r\n```\r\n\r\n| props | 类型 | 默认值 | 说明 |\r\n| ------------ | --------------- | ---------------- | ----------------------------------------------------------- |\r\n| `value` | Boolean | `false` | 显隐(`v-model:value`) |\r\n| `title` | String | `'批量导入'` | 弹窗标题 |\r\n| `width` | String / Number | `1000` | 弹窗宽度 |\r\n| `uploadUrl` | String | `''` | 上传地址(完整网关地址,如 `/monitor/DeviceInfo/Uploader`) |\r\n| `columns` | Array | `[]` | 预览/结果表格列 `[{ title, dataIndex, width }]` |\r\n| `apis` | Object | `{}` | 四个导入接口(见下) |\r\n| `typeSelect` | Object | `null` | `{ options, placeholder, loading }`,不需要业务参数时不传 |\r\n| `extraKey` | String | `'deviceTypeId'` | `typeSelect` 选中值提交时的字段名 |\r\n\r\n| events | 说明 |\r\n| -------------- | --------------------------- |\r\n| `update:value` | 显隐变化(`v-model`) |\r\n| `reload` | 导入成功/关闭后需要刷新列表 |\r\n\r\n| methods(ref 调用) | 说明 |\r\n| ------------------- | ------------------ |\r\n| `show()` | 打开弹窗并重置状态 |\r\n\r\n接口约定(均返回 Promise,组件内部兼容 `{ code, data }` 与直接返回数据两种格式):\r\n\r\n| 接口 | 入参 | 返回 |\r\n| --------------------- | ------------------------------ | ---------------------------------------------------- |\r\n| `templateDownload` | `{ ...extraParams }` | `{ url }`(组件用 `url` 触发下载) |\r\n| `importPreview` | `{ fileName, ...extra }` | `{ dataRow: [] }` |\r\n| `importData` | `{ list, ...extra }` | `{ resultType, snum, fnum, failResult: [] }` |\r\n| `exportExceptionData` | `{ list, ...extra }` | `{ url }` |\r\n| 上传(内部) | `FormData(file)` → `uploadUrl` | `{ name }` / `{ fileName }`(后续接口回传 fileName) |\r\n\r\n> ⚠️ `SImportModal` 是**三步式**(上传 → 预览编辑 → 结果/异常导出)。\r\n> 业务项目里如果存在「选文件即导入」的**单步式**导入组件(如 hy-monitor 的 `views/people/components/ImportModal.vue`、`views/basicData/components/ImportModal.vue`),\r\n> 两者在布局、API、事件、调用页契约上都不同,**不能当同一个组件替换**,仍按各自实现保留。\r\n\r\n### 2.12 SDataRangeTreeSelect 数据权限范围树\r\n\r\n数据权限(组织/校区/单位)范围选择,内部走 `findOfficeList` / `getOfficeByIds` / `getSysConfigByCode('dataScope')`。\r\n\r\n```vue\r\n<s-data-range-tree-select v-model:value=\"ids\" :auto-sys-config=\"true\" />\r\n```\r\n\r\n常用 props:`value`(id 数组) / `multiple` / `treeCheckable` / `allowClear` / `placeholder` / `maxTagCount` / `disabledGroup`(`'1'`组织 `'2'`校区 `'3'`单位,可传数组)/ `showOnlyOrganization` / `treeSelectData`(传数组则不请求接口)/ `isDataScopeFilter` / `autoSysConfig` / `defaultValue`。\r\nevents:`update:value`、`change`(均输出 **id 数组**)。\r\n\r\n> ⚠️ 模板写死了 `label-in-value` + `tree-check-strictly`,antd 要求内部 `value` 必须是 `{ label, value }` 对象数组。\r\n> 因此**回显必须先 `getOfficeByIds(ids)` 转成节点对象**再赋值,直接赋裸 id 字符串会触发 `Invalid prop value` 警告且输入框显示成裸数字 ID。\r\n\r\n### 2.13 SExtendFieldsForm 动态扩展字段表单\r\n\r\n后端下发字段配置(`fillModeConfig` 为 JSON 串,含 `showType` / `config`),前端按配置渲染。\r\n\r\n```vue\r\n<s-extend-fields-form ref=\"extRef\" :data=\"fields\" :default-value=\"values\" type=\"edit\" :cols=\"2\" />\r\n<script setup>\r\n// ref 暴露三个方法\r\nextRef.value.validate() // Promise<boolean>\r\nextRef.value.clearValidate()\r\nextRef.value.getModel() // [{ fieldCode, value }](对象值已 JSON.stringify)\r\n<\/script>\r\n```\r\n\r\n| props | 类型 | 默认值 | 说明 |\r\n| -------------- | ------ | ------- | ---------------------------------------------------- |\r\n| `data` | Array | `[]` | 扩展字段定义(`fieldCode/fieldName/fillModeConfig`) |\r\n| `type` | String | `'add'` | `add` / `edit` / `view`(`view` 不校验) |\r\n| `defaultValue` | Array | `[]` | 编辑态回显值 `[ { fieldCode, value } ]` |\r\n| `cols` | Number | `2` | 每行列数(非整行字段按 `100/cols%` 宽) |\r\n| `labelWidth` | String | `auto'` | label 宽度 |\r\n\r\n自动占满整行的 `showType`:`textarea`、`upload`、`select` 且 `config.multiple`。默认值按 `showType` 转类型:`datePicker` → dayjs 对象、`number` → Number、`select` 多选 → 逗号切数组。\r\n\r\n### 2.14 SChooseUser 选择人员弹窗(带数据权限)\r\n\r\n弹窗式人员选择:左侧组织树 + 右侧人员列表(头像/姓名/工号 + 单位),搜索区内置**人员类型过滤**(全部/教职工/学生/校外人员),支持单选/多选、滚动分页加载、全选/反选、多选时右侧已选清单。确认后**自动关闭弹窗**。\r\n\r\n与 `SUserSelect` 的差异(选型依据):\r\n\r\n| 对比项 | `SUserSelect` | `SChooseUser` |\r\n| -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |\r\n| 形态 | 只读输入框 + 弹窗一体 | 纯弹窗,显隐由业务控制 |\r\n| 数据权限 | 组织树/列表接口不带数据权限 | 走 `levelOneChildrenWithAuth` / `levelTwoChildrenWithAuth` / `findUsersWithAuth`,**按登录人权限过滤** |\r\n| 人员类型 | 无过滤 | 内置教职工/学生/校外人员过滤 |\r\n| 取值契约 | `v-model:value` 直接绑 id(单选字符串/多选数组) | `v-model:value` 控显隐;`v-model:selectedIds`/`selectedId` 绑已选 id;`@callback` 回抛**选中对象列表** |\r\n\r\n```vue\r\n<s-choose-user\r\n v-model:value=\"userScopeVisible\"\r\n v-model:selectedIds=\"userScopeIds\"\r\n :multiple=\"true\"\r\n @callback=\"userScopeCallback\"\r\n/>\r\n<script setup>\r\n// 确认(单选/多选): payload = [{ id, name, cover, userid, company, department }](单选也是单元素数组)\r\n// 取消/关闭: payload = undefined\r\nconst userScopeCallback = (payload) => {\r\n if (payload) userNames.value = payload.map((u) => u.name).join(',')\r\n userScopeVisible.value = false\r\n}\r\n<\/script>\r\n```\r\n\r\n| props | 类型 | 默认值 | 说明 |\r\n| ------------------- | ------- | --------------------------------- | ----------------------------------------------------------------------------- |\r\n| `value` | Boolean | `false` | 弹窗显隐(`v-model:value`) |\r\n| `title` | String | `'选择人员'` | 弹窗标题 |\r\n| `multiple` | Boolean | `false` | 多选(右侧出现已选清单) |\r\n| `searchPlaceholder` | String | `'按姓名、工号/学号、手机号搜索'` | 搜索框占位 |\r\n| `required` | Boolean | `false` | 确认时未选则提示且不关闭 |\r\n| `selectedIds` | Array | `[]` | 多选回显 id 数组(`v-model:selectedIds`),内部 `getBUseryIds` 拉对象渲染已选 |\r\n| `selectedId` | String | `''` | 单选回显 id(`v-model:selectedId`),内部 `getUserById` 拉对象 |\r\n\r\n| events | 说明 |\r\n| -------------------- | ----------------------------------------------------- |\r\n| `update:value` | 关闭弹窗(确认/取消均自动置 `false`,业务无需手动关) |\r\n| `update:selectedIds` | 已选 id 数组双向绑定 |\r\n| `update:selectedId` | 单选 id |\r\n| `callback` | 确认回抛选中对象**数组**;关闭时无参 |\r\n\r\n> ⚠️ 接口全部内置在基座 `packages/api/common.js`(`findUsersWithAuth` = `/user/users/authorized` 等),业务无需传接口;无后端的预览环境树/列表为空属正常。列表中 `userid` 展示的是 `loginName`(工号/学号)。\r\n\r\n### 2.15 SBelowChoosePosition 选择岗位弹窗\r\n\r\n弹窗式**岗位**选择(源自业务项目 `/components/BelowChoosePosition`,已收编进基座):左侧树用 `getBelowUnit` 一次性拉「根节点及其以下所有单位」的完整树(范围由 `rootId` 决定),右侧列表查岗位(`findJobs`),支持单选/多选。\r\n\r\n与基座其它选择器的差异:`SOfficeSelect`/`SUserSelect` 查组织/人员且左树递归懒加载;本组件查**岗位**、左树一次性全量。**确认后不自动关闭弹窗**,业务需在 `callback` 中手动关闭(与源项目行为一致)。\r\n\r\n```vue\r\n<s-below-choose-position\r\n v-model:value=\"visible\"\r\n v-model:selectedIds=\"positionIds\"\r\n multiple\r\n :root-id=\"campusId\"\r\n @callback=\"onCallback\"\r\n/>\r\n<script setup>\r\n// 确认(多选): payload = { selectedList: [{ id, name, deptName, nameOrCount }] }\r\n// 确认(单选): payload = { selected: { id, name, ... } }\r\n// 取消/关闭: payload = false\r\nconst onCallback = (payload) => {\r\n if (payload && payload.selectedList) {\r\n names.value = payload.selectedList.map((i) => i.name).join(',')\r\n }\r\n visible.value = false // 确认后组件不自动关闭,必须手动关\r\n}\r\n<\/script>\r\n```\r\n\r\nprops 与 `SChooseUser` 相同(`title` 默认 `'选择岗位'`、`searchPlaceholder` 默认 `'按岗位名称、岗位编号搜索'`),另有一个专有 prop:\r\n\r\n| props | 类型 | 默认值 | 说明 |\r\n| -------- | ------ | ------ | --------------------------------------------------------------------- |\r\n| `rootId` | String | `''` | 左树根节点 id,决定树的数据范围;变化时自动重载左树,未传按 `'-1'` 查 |\r\n\r\n| methods(ref 调用) | 说明 |\r\n| ---------------------- | ------------------ |\r\n| `initLeftTreeData(id)` | 手动重载左侧组织树 |\r\n\r\n| events | 说明 |\r\n| -------------------- | ------------------------------------------------------------------- |\r\n| `update:value` | 仅取消时置 `false`;**确认不关窗**,业务手动关 |\r\n| `update:selectedIds` | 已选岗位 id 数组双向绑定(回显走 `getPositionByIds`) |\r\n| `update:selectedId` | 单选 id(回显走 `getPositionById`) |\r\n| `callback` | 确认回抛 `{ selectedList }` / `{ selected }` 对象;关闭回抛 `false` |\r\n\r\n> ⚠️ `callback` 载荷形态与 `SChooseUser` **不同**(对象 `{ selectedList }` vs 数组),且确认后关窗行为相反,两个组件的 callback 写法不可混用。\r\n\r\n---\r\n\r\n### 2.16 SSkeletonLayout 骨架布局(标题 + 按钮组 + 内容区)\r\n\r\n> 2026-10-28 新增。用于页面级「标题条 + 操作按钮 + 内容区」的骨架外观,与 `SListLayout` / `SFormLayout` 同级但更轻:**不带表格、不带表单、不带分页**,内容区完全由插槽决定。\r\n\r\n```vue\r\n<s-skeleton-layout\r\n :title=\"$l('采集任务')\"\r\n :buttons=\"[\r\n { key: 'add', name: '新增', icon: true },\r\n { key: 'remove', name: '删除', disabled: true },\r\n { key: 'export', name: '导出', icon: 'DownloadOutlined' }\r\n ]\"\r\n bg-color=\"#fff\"\r\n @btnCallback=\"onBtnClick\"\r\n>\r\n <div class=\"my-content\">...</div>\r\n <template #otherBtns><a-button>自定义</a-button></template>\r\n <template #other>底部内容</template>\r\n</s-skeleton-layout>\r\n```\r\n\r\n| props | 类型 | 默认 | 说明 |\r\n| --------- | ------ | ---- | ------------------------------------------------------------- |\r\n| `title` | String | — | **必填**,标题条文本 |\r\n| `buttons` | Array | `[]` | 按钮配置数组,见下表 |\r\n| `bgColor` | String | `''` | 根节点背景色 |\r\n\r\n`buttons` 每项字段:\r\n\r\n| 字段 | 类型 | 说明 |\r\n| ---------- | ------------------ | ---------------------------------------------------------------------------------------- |\r\n| `key` | String | 唯一键,点击时回抛该值;`'add'` 时按钮自动为 `primary` |\r\n| `name` | String | 按钮文案(内部走 `$l`,可直接写源中文) |\r\n| `icon` | String \\| Boolean | 字符串 = 图标组件名(如 `'PlusOutlined'`);`true` = 按 `key` 查内置 iconMap;缺省不出图标 |\r\n| `action` | String | `v-action` 权限码,缺省用 `key`(会真正做权限过滤,无权限时按钮被移除) |\r\n| `show` | Boolean | 默认 `true`;`false` 时 `v-show` 隐藏(仍占位、仍注册权限) |\r\n| `disabled` | Boolean | 置灰 |\r\n| `type` | String | 覆盖 `a-button` 的 `type` |\r\n\r\n| slots | 说明 |\r\n| ----------- | -------------------------------- |\r\n| 默认 | 内容区(`.skeleton-layout-main`) |\r\n| `otherBtns` | 按钮组右侧追加内容 |\r\n| `other` | 底部区域 |\r\n\r\n| events | 说明 |\r\n| ------------- | --------------------------- |\r\n| `btnCallback` | 回抛被点击按钮的 `key` |\r\n\r\n| methods(ref 调用) | 说明 |\r\n| ------------------- | ------------------------------------------------------------- |\r\n| — | **无**。高度由 flex 自动分配,不需要业务调任何方法(见下) |\r\n\r\n内置 iconMap 的 key:`add` / `edit` / `delete` / `remove` / `import` / `export` / `assign` / `execute` / `pause` / `resume` / `approve` / `setting` / `TopOfType` / `TOP` / `synchronize`。\r\n\r\n> **高度实现(2026-10-28 修订)**:根节点 `height:100%; display:flex; flex-direction:column`,标题条 `flex:0 0 60px`,内容区 `flex:1 1 auto; min-height:0; overflow:hidden auto`,底部槽 `flex:0 0 auto`。**零 JS、零 resize 监听**,窗口缩放 / 侧栏折叠自动跟随。\r\n>\r\n> 前提:父容器要有确定高度。基座 `BasicLayout` 的 `router-view` 已带 `:style=\"{ height: contentHeight + 'px' }\"`,会透传到页面根组件,通常无需额外处理;若页面外层是自己写的 `height:auto` 容器,需给该容器一个确定高度。\r\n>\r\n> 旧版本的 `initLayoutHeight()` 方法**已移除**,`layoutHeight` 也不再暴露(原实现是 `parentNode.offsetHeight - 76` 且只在 `mounted` 算一次)。\r\n\r\n### 2.17 错误页(301 / 403 / 404 / 500)\r\n\r\n基座内置三张错误页,**同一张页面承接「页面本身出错」和「接口报错」两种来源**,靠 URL 上的 `?api=` 区分文案。\r\n\r\n| 路径 | 组件 | 状态码来源 | 主色 |\r\n| --- | --- | --- | --- |\r\n| `/403` | `pages-components/403.vue` | 接口 403 无权限、接口 301 地址变更、页面无权限 | 橙色 `#fa8c16` |\r\n| `/404` | `pages-components/404.vue` | 路由没命中(通配 `/:pathMatch(.*)*`)、接口 404 | 主题色 `var(--s-color)` |\r\n| `/500` | `pages-components/500.vue` | 仅可直接访问;**接口 5xx 不跳转**,仍走通知 | 红色 `#f5222d` |\r\n\r\n**渲染位置**:`buildErrorRoute()` 把三页统一包在 `BasicLayout` 下,作为 `children: [{ path: '' }]` 的嵌套子路由——跳转时**只替换内容区 `router-view`**,侧边菜单、顶栏、页脚保持原样。页面 404(通配)与接口 404 共用同一套结构,表现完全一致。\r\n\r\n**免登录**:`/403`、`/404`、`/500` 带 `meta.public`(接口报错时 token 可能已失效,不能让它再卡在登录守卫里);通配 `/:pathMatch(.*)*` **不带** `public`,未登录访问不存在的地址仍回登录页。\r\n\r\n**接口报错的映射**(`packages/utils/request.js`):\r\n\r\n| HTTP 状态 | 行为 | 目标 URL |\r\n| --- | --- | --- |\r\n| 301 | 跳 403 页,文案「接口地址已变更」 | `/403?api=<接口>&status=301&from=<出错页>` |\r\n| 403 | 跳 403 页,文案「接口无权限」 | `/403?api=<接口>&status=403&from=<出错页>` |\r\n| 404 | 跳 404 页,文案「接口不存在」 | `/404?api=<接口>&status=404&from=<出错页>` |\r\n| 其它(含 5xx) | **不跳**,照旧弹通知 | — |\r\n\r\n**URL 参数**:\r\n\r\n| 参数 | 含义 |\r\n| --- | --- |\r\n| `api` | 报错接口地址。**有它即切「接口口径」文案**;页面自身出错时不带 |\r\n| `status` | 原始状态码;`301` 单独走「接口地址已变更」这一档文案 |\r\n| `from` | 出错来源页面地址(已剥掉 `VITE_APP_BASE_URL`),页面显示为「出错地址」 |\r\n\r\n文案口径:\r\n\r\n| 来源 | 403 页 | 404 页 |\r\n| --- | --- | --- |\r\n| 页面(无 `api`) | 页面权限不足 | 页面走丢了 |\r\n| 接口(有 `api`) | 接口无权限 | 接口不存在 |\r\n| 接口 301 | 接口地址已变更 | — |\r\n\r\n两个按钮:「返回首页」走 `VITE_APP_DEFAULT_PATH`(默认 `/workplace/index`);「返回上一页」用 `router.back()`,没有历史记录时自动退回首页,避免点了没反应。\r\n\r\n**跳过跳转**(后台轮询、辅助接口等非主流程请求,避免一条辅助接口失败把整页顶掉):\r\n\r\n```js\r\n// 第三个参数支持 { skipErrorPage: true }(也可写在请求 meta 里)\r\nwindow.$utils.http.post(url, data, { skipErrorPage: true })\r\n```\r\n\r\n**并发与兜底**:错误页跳转是**串行排队、后到优先**,同时来 403 和 404 不会互相取消;导航结束后回读 `currentRoute` 校验是否真的到达(兼容目标被 redirect 改写路径),没到达重试 2 次,仍失败才 `location.replace` 整页兜底,保证用户一定看到错误页。已经在错误页且已带 `api` 时不再覆盖,防止错误页自身挂的辅助接口把真实原因顶掉。\r\n\r\n**改颜色 / 改文案**:\r\n\r\n- 文案全部走 i18n 词条(`packages/pages-components/i18n.js`,命名空间 `pages-components`),改词条即改三页文字。\r\n- 403 / 500 各自在根节点定义了 `--e-color`(主色)、`--e-light-color`(浅色)、`--e-border-color`(虚线边框),业务侧用同名变量覆盖即可换色;404 用主题色 `--s-color`,跟随 `VITE_APP_THEME_VALUE`。\r\n- 三页根节点都是 `height:100%; overflow:hidden`,装饰光斑包在 `__deco` 里自裁,超出部分只在卡片内部滚动,不会撑出页面滚动条。\r\n\r\n> 错误页挂在 `BasicLayout` 下,布局层会带发 `getSystemIcon` 与消息计数两个请求。这两个接口若是本身会失败的辅助接口,建议加 `skipErrorPage: true`,否则可能从 403 再跳到 404。\r\n\r\n### 2.18 菜单配色(侧边 / 顶部)\r\n\r\n菜单颜色**不在样式里写死**:启动时由 `packages/utils/menu-theme.js` 按当前主题色算出整套色板,全部输出实色 `#rrggbb`(**不含 rgba / 透明度**),写入 `:root` 的 CSS 变量,同时挂到 `window.$menuTheme`。改主题色或改参数,四处底色一起变。\r\n\r\n| 部位 | CSS 变量 | 计算方式 |\r\n| --- | --- | --- |\r\n| 一级菜单底 | `--s-menu-bg` | 主题色相 + 饱和度上限 + 指定亮度 |\r\n| 子菜单展开区 | `--s-menu-sub-bg` | 同色相,比一级底亮一档 |\r\n| 悬停项 | `--s-menu-hover-bg` | 同色相,比一级底暗 6 个亮度 |\r\n| 选中项 | `--s-menu-active-bg` | 主题色兑白,占比由 `VITE_APP_MENU_BG_ACTIVE_MIX` 控制 |\r\n| 普通文字 | `--s-menu-text` | 按底色反解,保证对比度 ≥ 4.6 |\r\n| 悬停 / 选中文字 | `--s-menu-text-hover`、`--s-menu-text-active` | 同上 |\r\n\r\n配置项(默认值见 `packages/config/web-config.js`,业务 `.env` 或部署目录 `config.json` 可覆盖):\r\n\r\n| 配置 | 默认 | 说明 |\r\n| --- | --- | --- |\r\n| `VITE_APP_MENU_BG` | `theme` | `theme` 跟随主题色 / `dark` 用 antd `#001529` / `#RRGGBB` 直接用该色 |\r\n| `VITE_APP_MENU_BG_LIGHTNESS` | `93` | 一级底亮度 0-100:越大越白,越小越深;**低于 50 自动切深色底 + 浅色文字** |\r\n| `VITE_APP_MENU_BG_SATURATION` | `30` | 饱和度上限 0-100:越小越接近灰白,`0` 得纯灰 |\r\n| `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | 选中块里主题色的占比 0-100:越大越显眼 |\r\n| `VITE_APP_MENU_THEME` | `dark` | 菜单外观模式;文字色实际按**底色明暗**自动切换,不只依赖这个值 |\r\n| `VITE_APP_MENU_BAR` | `left` | `left` 侧边 / `top` 顶部,两者共用同一套色板 |\r\n\r\n各主题默认色(亮度 93 / 饱和 30 / 选中 16,均为实测值):\r\n\r\n| 主题 | 一级底 | 子菜单底 | 悬停 | 选中块 | 普通文字 |\r\n| --- | --- | --- | --- | --- | --- |\r\n| blue | `#e8ecf3` | `#f5f7fa` | `#d4dce8` | `#dae9ff` | `#344051` |\r\n| green | `#ebf3e8` | `#f7faf5` | `#dbe8d4` | `#e3f6da` | `#3d5134` |\r\n| orange | `#f3ede8` | `#faf7f5` | `#e8ded4` | `#feedda` | `#514334` |\r\n| red | `#f3e8e8` | `#faf5f5` | `#e8d4d5` | `#fddcdd` | `#513435` |\r\n| purple | `#ece8f3` | `#f7f5fa` | `#dcd4e8` | `#e8def8` | `#403451` |\r\n| cyan | `#e8f3f3` | `#f5fafa` | `#d4e8e8` | `#d9f5f5` | `#345151` |\r\n\r\n常用调法:\r\n\r\n```js\r\n// 业务 web-config.js / 部署目录 config.json\r\nVITE_APP_MENU_BG_LIGHTNESS: 97, // 1) 想更白(100 接近纯白)\r\nVITE_APP_MENU_BG_SATURATION: 0, // 2) 去掉色调,走纯灰白\r\nVITE_APP_MENU_BG_ACTIVE_MIX: 30, // 3) 选中块更明显\r\nVITE_APP_MENU_BG: 'dark', // 4) 回到 antd 经典深蓝黑 #001529\r\nVITE_APP_MENU_BG: '#213045' // 5) 固定一个自定义色,不再跟随主题\r\n```\r\n\r\n> 注意事项\r\n>\r\n> 1. `VITE_APP_MENU_BG` 传 `#RRGGBB` 时,子菜单底 / 悬停 / 选中 / 文字仍在该色基础上推导,不会出现「主底换了、文字看不清」。\r\n> 2. 底色亮度 < 50 进入深色体系:文字转浅、logo 自动换浅色版、顶栏文字转白。判据是 `window.$menuTheme.isLightBg`,不是 `VITE_APP_MENU_THEME`。\r\n> 3. 业务样式不要写死 `#001529`、`rgba(255,255,255,.1)` 这类菜单色,直接用 `var(--s-menu-*)`,否则换主题会割裂。\r\n> 4. `.menu-wrap .ant-menu.ant-menu-dark` 已用上述变量兜住一级项、子菜单、hover、选中四类节点(antd 4.2.6 的 Menu token 覆盖不到的部分)。\r\n\r\n## 三、布局与高度规范\r\n\r\n> 本章是**基座内部布局组件的强制约定**。业务页面只管用 layout,不要自己写高度;如果要新增布局组件,必须先满足本章规则。\r\n\r\n### 3.1 高度:优先 CSS flex 撑满;需要动态计算时按三条约束做\r\n\r\n> **2026-10-28 修订**:旧标题「禁止 JS 减法算高度」已作废。业务内容区需要出滚动条时,**高度就该动态计算**,只是必须按下面的约束写,不能每页抄魔数。\r\n\r\n\r\n**错误做法**(早期 `SListLayout` / `SFormLayout` 都犯过):\r\n\r\n```js\r\n// ❌ 用 offsetHeight 减法算子区域高度\r\nthis.layoutHeight = this.$refs.layout.offsetHeight - toolsH - footerH - tabsH - 16\r\n```\r\n\r\n为什么必错:`offsetHeight` 读的是**当前渲染结果**,而这个结果又取决于你即将写入的 `height` —— 循环依赖。表现是:\r\n\r\n- 数据不满页时分页浮在中间,底部空 15~588px;\r\n- 表格/表单区溢出容器 1~N px,页面多出一条滚动条;\r\n- 改一个固定魔数(如 `tpH = 103`)其它页面全歪。\r\n\r\n**首选做法(零 JS)**:父容器 `height:100%` + `display:flex; flex-direction:column`,主体区 `flex:1 1 auto; min-height:0; overflow:auto`,底部条 `flex:0 0 auto`。列表页、表单页绝大多数场景用这个就够。\r\n\r\n**需要 JS 动态计算的情形**(内容区要出滚动条、容器高度随窗口或兄弟节点变化):**允许并推荐动态计算**,但必须满足三条:\r\n\r\n1. **收敛到一处**:同一种布局只留一个 `calcXxxHeight()`,不要每页一份魔数\r\n2. **跟着容器走**:用 `ResizeObserver` 观察父容器重算,别只监听 `window.resize`\r\n3. **不读 `$parent.$el`**:父级 DOM 结构一变就错,用 `ref` 取自己的容器\r\n\r\n**仍然禁止的错法**:拿「自己即将写入 height 的那个祖先」的 `offsetHeight` 做减法 —— 循环依赖。要读就读**不依赖自身高度**的量(`window.innerHeight`、上级固定头/脚节点的高度)。\r\n\r\n\r\n### 3.2 表格区撑满链路(列表页分页贴底的关键)\r\n\r\n`STable` 的 body 要靠 flex 拿到剩余高度,链路上**任何一层漏掉都会导致撑不开**:\r\n\r\n```less\r\n.table-content {\r\n flex: 1;\r\n display: flex;\r\n flex-direction: column;\r\n min-height: 0;\r\n}\r\n.tabs-wrap {\r\n flex: 0 0 auto;\r\n}\r\n.table-container {\r\n flex: 1 1 auto;\r\n min-height: 0;\r\n display: flex;\r\n flex-direction: column;\r\n}\r\n.table-wrapper {\r\n flex: 1 1 auto;\r\n ...;\r\n} /* STable 组件根节点,漏它整条链断 */\r\n.ant-table-wrapper {\r\n flex: 1 1 auto;\r\n ...;\r\n}\r\n.ant-spin-nested-loading .ant-spin-container .ant-table .ant-table-container {\r\n margin-left: 10px;\r\n} /* 表格缩进走 margin,不走 padding */\r\n.ant-table-header {\r\n flex: 0 0 auto;\r\n}\r\n.ant-table-body {\r\n flex: 1 1 auto;\r\n min-height: 0;\r\n max-height: none !important;\r\n}\r\n.ant-table-pagination {\r\n margin-bottom: 0;\r\n flex: 0 0 auto;\r\n} /* 差一个 margin 就是 15~16px 空隙 */\r\n```\r\n\r\n要点:\r\n\r\n1. **`.table-wrapper` 不能漏** —— 它是 `STable` 组件根节点,实测漏掉它 body 就撑不开;\r\n2. `scroll.y` 写入的 `max-height` 必须 `none !important` 覆盖掉,否则和 flex 打架;\r\n3. 分页 `margin-bottom: 0`,否则分页与容器底边恒差一个 margin;\r\n4. 表格缩进用 `:deep(.ant-table-container){margin-left:10px}`,**不要**用 `padding-left`(会挤压 body 宽度计算)。\r\n\r\n### 3.3 `.tools` 头部条统一 60px\r\n\r\n所有布局的 `.tools`(标题 + 按钮条)统一:\r\n\r\n```less\r\n.tools {\r\n height: 60px;\r\n display: flex;\r\n justify-content: space-between;\r\n align-items: center;\r\n padding: 0 16px;\r\n box-sizing: border-box;\r\n border-bottom: 1px solid #f0f2f5;\r\n}\r\n.list-filter-wrap {\r\n padding: 10px 16px;\r\n box-sizing: border-box;\r\n}\r\n```\r\n\r\n> ⚠️ 若某天调整了 `.tools` 高度,所有布局里 `initTable()` 的减数(如 `- 76`)必须同步改,否则全站列表页一起歪。\r\n\r\n### 3.4 表单布局 SFormLayout\r\n\r\n`.form-layout` 用同一套 flex 撑满,`initStyle()` 里**只算 footer 宽度**(collapses + anchor 场景要避开右侧锚点),不再算高度:\r\n\r\n```less\r\n.form-layout {\r\n height: 100%;\r\n overflow: hidden;\r\n :deep(.ant-spin-nested-loading),\r\n :deep(.ant-spin-container) {\r\n /* a-spin 包裹层必须逐层撑满,否则 form-layout 高度取不到 */\r\n height: 100%;\r\n display: flex;\r\n flex-direction: column;\r\n min-height: 0;\r\n }\r\n}\r\n.tools,\r\n.step-wrap,\r\n.tabs-wrap,\r\n.modal,\r\n.form-fixed-footer {\r\n flex: 0 0 auto;\r\n}\r\n.form-layout-main {\r\n flex: 1 1 auto;\r\n min-height: 0;\r\n overflow: hidden auto;\r\n}\r\n.form-fixed-footer {\r\n height: 60px;\r\n}\r\n```\r\n\r\n### 3.5 左侧树容器高度统一(`.s-side-tree`)\r\n\r\n`SListLayout` / `SListTableTreeLayout` / `SListCardLayout` 的 `.side` 都带 `padding: 10px 0`,树容器高度必须等于「`.side` 盒高 − 上下 padding」,否则双滚动条或树被截断。\r\n\r\n规则写在**全局** `packages/style/common.less` 的 `.s-side-tree`(`.side` 的唯一化追加类,避免通用名被业务覆盖),业务页面 scoped 里**禁止再写副本**。覆盖两种树来源:\r\n\r\n- ① 标准 `<s-tree>`:根节点即 `.s-tree-common`,`height:100%`;\r\n- ② 原生 `<a-spin><a-tree>`:逐层撑高 `.ant-spin-container → .ant-tree → .ant-tree-list → .ant-tree-list-holder`,由 `.ant-tree-list-holder` 承担 `overflow-y:auto`。\r\n\r\n> ⚠️ ② 的分支必须用 `>` 从 `.s-side-tree` 直接起算,**不能写成后代选择器** —— `STree` 内部同样是 `.ant-tree`,后代写法会误伤 ①。\r\n\r\n### 3.6 STree 自适应与横向省略\r\n\r\n`STree` 的 `height` prop 默认值必须是 `undefined`(**不能写死 300**):\r\n\r\n```js\r\nheight: { type: Number, default: undefined }\r\n```\r\n\r\n原因:antd 的 `Tree` 会把 `height` 转成虚拟列表 holder 的行内 `max-height:300px`,导致树被截断且自身产生内层滚动条。\r\n\r\n横向文字不换行、超出省略、宽度随父容器拉伸:\r\n\r\n```less\r\n.s-tree-common {\r\n height: 100%;\r\n width: 100%;\r\n overflow-x: hidden;\r\n overflow-y: auto;\r\n}\r\n:deep(.ant-tree),\r\n:deep(.ant-tree-list),\r\n:deep(.ant-tree-list-holder),\r\n:deep(.ant-tree-list-holder-inner) {\r\n width: 100%;\r\n min-width: 0;\r\n}\r\n:deep(.ant-tree-node-content-wrapper) {\r\n min-width: 0;\r\n overflow: hidden;\r\n}\r\n:deep(.ant-tree-title),\r\n.node-title {\r\n display: block;\r\n width: 100%;\r\n overflow: hidden;\r\n white-space: nowrap;\r\n text-overflow: ellipsis;\r\n}\r\n```\r\n\r\n### 3.7 排查渲染问题的铁律\r\n\r\n**页面渲染/高度问题必须用 puppeteer 登录后量真实 `offsetHeight`/`offsetLeft`/盒模型,禁止静态读代码猜根因。**\r\n\r\n```js\r\n// 量:容器高、主体高、底部条位置差、文档溢出\r\nconst r = await page.evaluate(() => {\r\n const q = (s) => document.querySelector(s)\r\n const box = (s) => {\r\n const el = q(s)\r\n if (!el) return null\r\n const b = el.getBoundingClientRect()\r\n return { h: el.offsetHeight, top: Math.round(b.top), bottom: Math.round(b.bottom) }\r\n }\r\n return {\r\n container: box('.list-layout-main'),\r\n tableContent: box('.table-content'),\r\n pagination: box('.ant-table-pagination'),\r\n docOverflowY: document.documentElement.scrollHeight - document.documentElement.clientHeight\r\n }\r\n})\r\n```\r\n\r\n验收标准(全部为 0 才算过):\r\n\r\n| 指标 | 通过条件 |\r\n| ---------------------------- | --------------------------- |\r\n| `documentOverflowY` | `0`(页面不出现滚动条) |\r\n| `pagination.bottom` 减容器底 | `0`(分页刚好卡在视口底部) |\r\n| 表格主体溢出容器 | `0` |\r\n\r\n多视口抽查(建议 1920×1080 / 1600×900 / 1440×900 / 1366×768 / 1280×720 / 2560×1440)全过才算改完。\r\n\r\n---\r\n\r\n## 四、构建与配置\r\n\r\n### 4.1 构建与发布\r\n\r\n```bash\r\nnpm run dev # 基座本地开发\r\nnpm run build # lib 构建 + 复制 docs/vite-plugins/package.json 到 dist + git push\r\nnpm run lint\r\n```\r\n\r\n> 基座构建 **不 drop console**(`$utils`/i18n 调试输出由运行时 `VITE_CONFIG_sapit-base-template` 控制);业务构建才 drop。\r\n\r\n产物:入口 `./packages/index.js`,`vue` external,输出 `dist/lib`,打包内容为**入口依赖图**(不是整个项目);`package.json` 的 `files: [\"lib\",\"docs\",\"vite-plugins\"]`。\r\n\r\n### 4.2 配置来源与优先级\r\n\r\n```text\r\n基座默认 defaultEnv < 业务 web-config.js < .env.[sapit-base-template](构建时写入 config.json) < 部署 config.json(运行时覆盖)\r\n```\r\n\r\n- `web-config.js`:可写默认值或 `import.meta.env.VITE_APP_*`;\r\n- `.env` / `.env.[sapit-base-template]`:各环境一套(dev/test/uat/prod),由业务 `vite.config.js` 写入 `config.json`;\r\n- `config.json`:站点根(子路径为 `<base>config.json`),启动时 `loadRemoteConfig()` 拉取并覆盖,**部署后可直接改、无需重打包**;`.env` 值为字符串,基座会把 `\"true\"/\"false\"` 归一为布尔。\r\n\r\n常用开关(业务可按需覆盖;判断统一用 `!== false`,即未配置时取基座默认值):\r\n\r\n| 配置项 | 默认值 | 说明 |\r\n| -------------------------- | ------------------------------- | ----------------------------------------------------------------------------- |\r\n| `VITE_APP_FOOTER_VISIBLE` | `false` | 是否显示页脚 |\r\n| `VITE_APP_MESSAGE_VISIBLE` | `true` | 是否显示右上角消息铃铛(设 `false` 隐藏) |\r\n| `VITE_APP_SOCKET_URL` | `ws://127.0.0.1:8080/websocket` | 消息推送 socket 地址;为空或 `/` 时走同源;本地占位地址在非本机环境下自动跳过 |\r\n| `VITE_APP_SOCKET_PATH` | `/apig/ws/websocket` | socket.io 握手路径,需与后端一致 |\r\n| `VITE_APP_LANG_ENABLE` | `false` | 是否启用国际化 |\r\n| `VITE_APP_MENU_BAR` | `left` | 菜单布局:`left` / `top` |\r\n| `VITE_APP_MENU_THEME` | `dark` | 菜单主题:`dark` / `light` |\r\n| `VITE_APP_MENU_BG` | `theme` | 菜单底色:`theme` 跟随主题色 / `dark` 用 `#001529` / `#RRGGBB` 自定义 |\r\n| `VITE_APP_MENU_BG_LIGHTNESS` | `93` | 菜单底亮度 0-100:越大越白 |\r\n| `VITE_APP_MENU_BG_SATURATION` | `30` | 菜单配色饱和度上限 0-100 |\r\n| `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | 选中块里主题色的占比 0-100 |\r\n\r\n右上角消息铃铛的数量逻辑:进入系统先调 `message/center/counts` 取 `totalCount`,之后由 socket 推送的 `wsEvent` 触发重新拉取。socket 连接为单例(`packages/utils/message-socket.js`),连上后 `emit('sendUserId', userId)`,后端按用户推送。业务侧无需额外注册,只要 `VITE_APP_SOCKET_URL` / `VITE_APP_SOCKET_PATH` 配到消息服务即可。\r\n\r\n### 4.3 业务项目启动(`npm start`)\r\n\r\n业务项目(`sapit-base-template`)的 `npm start` 执行内置脚本 `refresh-sapit-base-template.ps1`:\r\n\r\n1. 清理 `node_modules/.vite`、`node_modules/sapit-ui-plus` 及锁文件(`package-lock.json`/`yarn.lock`/`pnpm-lock.yaml`/`node_modules/.package-lock.json`);\r\n2. `npm install` 拉取 `sapit-ui-plus` 最新发布版本;\r\n3. 自动执行 `npm run dev` 启动。\r\n\r\n> 作用:清理依赖缓存,更新业务依赖并一键启动。也可双击 `refresh-sapit-base-template.cmd`;`-NoStart` 仅更新不启动。\r\n> 这个命令通常在基座项目有更新时才会用到。\r\n\r\n## 五、业务项目接入\r\n\r\n### 5.1 安装\r\n\r\n```json\r\n{ \"dependencies\": { \"sapit-ui-plus\": \"git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git\" } }\r\n```\r\n\r\n### 5.2 入口 `main.js`\r\n\r\n```js\r\nimport { createApp } from 'vue'\r\nimport App from './App.vue'\r\nimport config from './config/web-config'\r\nimport appConfig from './config/app-config'\r\nimport SapitUiPlus from 'sapit-ui-plus'\r\nimport 'sapit-ui-plus/lib/css/style.css'\r\n\r\nasync function init() {\r\n const pages = import.meta.glob('@/views/**/*.vue')\r\n const app = createApp(App)\r\n app.use(SapitUiPlus)\r\n await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages)\r\n app.mount('#app')\r\n}\r\ninit()\r\n```\r\n\r\n- `config`:环境配置(web-config);\r\n- `appConfig`:构建期配置(登录/首页覆盖、静态路由、语言包),**不进入 config.json**;\r\n- `pages`:业务所有页面,用于动态路由按 `hrefs` 匹配。\r\n\r\n### 5.3 登录页 / 首页覆盖\r\n\r\n`app-config.js`:\r\n\r\n```js\r\nexport default {\r\n components: {\r\n login: () => import('@/views/login/index.vue'),\r\n home: () => import('@/views/home/index.vue')\r\n }\r\n}\r\n```\r\n\r\n不配置则用基座默认(`pages-components/login.vue`、`todo.vue`)。\r\n\r\n### 5.4 静态页面 `staticRoutes`\r\n\r\n```js\r\nexport default {\r\n staticRoutes: [\r\n {\r\n path: '/help',\r\n name: 'Help',\r\n component: () => import('@/views/help/index.vue'),\r\n meta: { title: '帮助' } // hidden: 不进菜单;public: 免登录\r\n }\r\n ]\r\n}\r\n```\r\n\r\n`layout: false` / `raw: true` 时不包 `BasicLayout`;同 `path` 时业务覆盖基座内置。\r\n\r\n### 5.5 业务页面与菜单\r\n\r\n后端菜单 `hrefs` 需匹配业务 `views` 路径(或组件名);页面放 `src/views/**` 即可被动态路由识别。侧边菜单渲染「动态菜单 + `staticRoutes`」,基座常量菜单不进菜单。\r\n\r\n### 5.6 国际化 / 主题\r\n\r\n- 国际化:各模块放 `views/<模块>/i18n.js`(扁平 `{ '中文': 'English' }`),页面**不用写** `useI18n`,`$l('中文')` 自动按页面所在目录命中;要跨目录强制指定时再 `this.useI18n('<模块>')`。业务自己的 `i18n.js` 在业务 `main.js` 里 glob 一次传给 `$registerGlobalConfig({ locales })`,即与基座合并(同名业务优先)。\r\n- 主题:只改 `VITE_APP_THEME_VALUE`;样式用 `var(--s-*)` 或 `.s-theme-*`。\r\n\r\n### 5.7 子路径部署(示例 `/monitor/`)\r\n\r\n1. `.env`:`VITE_APP_BASE_URL=/monitor/`;\r\n2. 业务 `vite.config.js`:`base: getViteEnv(res.sapit-base-template, 'VITE_APP_BASE_URL') || '/'`;\r\n3. 基座路由 base、`$push`/`$open`、`redirectLogin`、`parseAppUrl` 均读该值自动带前缀;\r\n4. nginx:\r\n\r\n```nginx\r\nlocation /monitor/ {\r\n alias /home/project/tmp/dist/;\r\n index index.html;\r\n try_files $uri $uri/ /monitor/index.html;\r\n}\r\nlocation = /monitor/config.json {\r\n alias /home/project/tmp/dist/config.json;\r\n add_header Cache-Control \"no-store\";\r\n}\r\n```\r\n\r\n> `createWebHistory` base、Vite `base`、`window.location` 跳转三者必须都是 `/monitor/`(带尾斜杠)。\r\n\r\n### 5.8 使用组件与权限\r\n\r\n```html\r\n<template>\r\n <s-list-layout :columns=\"columns\" :loadData=\"page\" title=\"示例\" />\r\n <s-user-select v-sapit-base-templatel:value=\"ids\" />\r\n <a-button v-action=\"'add'\">添加</a-button>\r\n</template>\r\n```\r\n\r\n后端下发 `permissions` 后基座写入 `permission`,用 `v-action:xxx` 控制按钮级权限。文档访问:`<业务base>/docs`、`<业务base>/components`。\r\n\r\n---\r\n\r\n### 5.9 内置依赖(业务开箱即用)\r\n\r\n`sapit-ui-plus` 的 `dependencies` 会随基座一起装进业务 `node_modules`,业务**无需再装即可直接 import**(业务 `package.json` 里通常只见 `sapit-ui-plus` 一项)。\r\n\r\n| 依赖 | 版本 | 用途 |\r\n| ------------------------------------------------ | ----------------- | ----------------------------------------------------- |\r\n| `dayjs` | ^1.11.12 | 日期格式化(推荐,`$utils` 内也用) |\r\n| `axios` | ^1.7.3 | 请求(已封装为 `window.$utils.http`,一般不用直接用) |\r\n| `qs` | ^6.13.0 | 参数序列化(`stringify`) |\r\n| `lodash.get` / `lodash.clonedeep` | ^4.4.2 / ^4.5.0 | 安全取值 / 深拷贝 |\r\n| `crypto-js` | ^4.2.0 | 加解密 |\r\n| `js-base64` | ^3.7.2 | Base64 编解码 |\r\n| `jsencrypt` | ^3.3.2 | RSA 加密 |\r\n| `moment` | ^2.30.1 | 日期(老代码兼容,新代码用 dayjs) |\r\n| `html2canvas` | ^1.4.1 | 页面截图 |\r\n| `nprogress` | ^0.2.0 | 顶部加载进度条 |\r\n| `@vueuse/core` | ^11.0.3 | 组合式工具函数 |\r\n| `vue-cropper` | ^1.1.4 | 图片裁剪(SCopperUpload 用它) |\r\n| `vuedraggable` | ^4.1.0 | 拖拽排序 |\r\n| `v-clipboard` | ^3.0.0-next.1 | 复制到剪贴板(`v-clipboard` 指令) |\r\n| `vue-ls` | ^4.2.0 | localStorage 封装(已包成 `$utils.ls`) |\r\n| `jodit` | 3.24.7 | 富文本编辑器(SEditor) |\r\n| `less` / `less-loader` | ^4.2.0 / ^12.2.0 | 样式编译 |\r\n| `vite-plugin-html` / `vite-plugin-generate-file` | ^3.2.2 / ^0.2.0 | 构建插件(生成 config.json 等) |\r\n| `@ant-design/icons-vue` | 随 ant-design-vue | 图标,**全部已全局注册为组件** |\r\n\r\n**单例依赖:基座不做打包,业务必须自己安装**(`vite.config.js` 的 `external`),否则会出现两个模块实例(路由注入不上、pinia 对不上、主题/消息上下文丢失):\r\n\r\n| 依赖 | 版本 |\r\n| ---------------- | ------- |\r\n| `vue` | ^3.4.29 |\r\n| `vue-router` | ^4.3.3 |\r\n| `pinia` | ^2.1.7 |\r\n| `vue-i18n` | ^9.14.0 |\r\n| `ant-design-vue` | 4.x |\r\n\r\n> 用法:`import dayjs from 'dayjs'` 直接可用;但**不要**在业务里再装一份与基座不同大版本的 `vue`/`ant-design-vue`/`pinia`,版本以基座为准。\r\n\r\n### 5.10 全局注入(无需 import)\r\n\r\n| 名称 | 说明 |\r\n| ------------------------------------------ | ------------------------------------------------------------------------------ |\r\n| `$utils` | 工具类:`$utils.http`(请求)、`$utils.ls`(本地存储)、`$utils.env`(配置)等 |\r\n| `$message` / `$modal` / `$notice` | ant-design-vue 的 message / Modal / notification |\r\n| `$push` / `$open` | 站内跳转 / 新窗口打开(自动拼接部署 base) |\r\n| `$l` | 国际化取词(`$l('中文')`) |\r\n| `$theme` | 当前主题变量;CSS 变量 `--s-color` 等 |\r\n| `$icons` | 全部 antd 图标组件 |\r\n| `$socket` / `$filter` / `$pinia` / `$i18n` | websocket / 过滤器 / 用户 store / i18n 实例 |\r\n| `env` | 同 `$utils.env` |\r\n| `$staticRoutes` | 静态页面路由(含业务自定义) |\r\n\r\n---\r\n\r\n## 六、注意事项\r\n\r\n### 6.1 业务侧\r\n\r\n1. <span style=\"color:#d4380d;font-weight:700\">依赖是预构建产物</span>:基座改动需 `npm run build` 推送且业务重装依赖才生效;基座 dev 立即生效。\r\n2. <span style=\"color:#d4380d;font-weight:700\">锁文件会钉住旧提交</span>:更新前删 `package-lock.json`、`yarn.lock`、`node_modules/.package-lock.json`。\r\n3. <span style=\"color:#d46b08;font-weight:700\">子路径</span>:`VITE_APP_BASE_URL` 与 Vite `base` 保持一致且带尾斜杠。\r\n4. <span style=\"color:#d46b08;font-weight:700\">全局组件命名</span>:按文件名注册(`SForm.vue` → `<SForm>`,不是 kebab-case);冲突后者覆盖。\r\n5. <span style=\"color:#d46b08;font-weight:700\">主题 / 国际化</span>:定义在基座,业务只选主题、只写文案。\r\n6. <span style=\"color:#d46b08;font-weight:700\">不能深路径 import 基座内部模块</span>:lib 产物只有 `lib/js/index.js` 一个入口,内部模块被 rollup 打进 chunk。想让业务用某能力,必须挂全局属性(`$utils` / `$modal` 那样)。\r\n7. <span style=\"color:#d4380d;font-weight:700\">功能去留</span>:源码(老 Vue2 项目)有的我们就有,源码没有的不要\"顺手补齐\"。新增功能前先确认参照实现。\r\n\r\n### 6.2 开发 / 构建\r\n\r\n8. **不要并发跑两个 `vite build`**:会报 `Rollup failed to resolve import \"sapit-ui-plus\"`,是缓存冲突的假报错,串行重跑即恢复。若串行仍报错,检查 `node_modules/sapit-ui-plus` 是否被清空(npm 重装常清掉)——恢复方式:\r\n\r\n ```bash\r\n # 基座 dist 就是 npm 包内容(build 脚本把 package.json + docs + vite-plugins 拷进 dist)\r\n cp -r <基座>/dist/lib <基座>/dist/docs <基座>/dist/vite-plugins <基座>/dist/package.json <业务>/node_modules/sapit-ui-plus/\r\n cp -r <基座>/packages/sso <基座>/packages/static <业务>/node_modules/sapit-ui-plus/\r\n ```\r\n\r\n9. **`vite build --emptyOutDir false`**:清空 `dist` 会被批量删除守卫拦截;只验证编译时用这个参数,**不要**为了验证去执行会 `git push` 内网仓库的 `npm run build`(对外发布动作,须先确认)。\r\n10. **不要并发跑两个基座构建 / 业务安装**,避免缓存互相污染。\r\n11. **`vite build` 不检查未定义变量**:模板/脚本里引用不存在的变量照样通过。改完大段代码必须 `git diff` 复核增删行,配合未使用 import 扫描发现误删。\r\n12. **npm 国内网络**:`registry.npmjs.org` 基本不通,装 `sapit-ui-plus` 会卡在大包上(最重的是 `ant-design-vue` 解压 78MB、`jodit` 23MB)。装包指定国内源:\r\n\r\n ```bash\r\n npm i git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git --registry=https://registry.npmmirror.com\r\n ```\r\n\r\n 若 npm 进程内的 `git ls-remote` 返回 403(沙箱/网络拦截,手工 `git ls-remote` 却通),只能临时摘掉该 git 依赖装其余包,再按第 8 条从基座本地 `dist` 恢复。\r\n\r\n13. **npm 包必须含根级 `static/`**:lib 构建不重写 `new URL('../../static/...', import.meta.url)`,运行时从 `lib/js/*.js` 解析到包根 `static/`。缺它业务 dev 登录页图片全 404,而基座自身 dev 正常、生产正常,**极具迷惑性**。\r\n14. **lib 构建图片**:Vite 对 `build.lib` 强制内联所有资产 → 产物可能出现 MB 级 base64 data URI(超 Chrome URL 上限)。`vite-plugins/sso-plugin` 的 `closeBundle` 会把 >100KB 的 data URI 抽为 `lib/img/` 真实文件;源码资产引用一律改 `import`。\r\n\r\n### 6.3 业务字典 / 表单约定(hy-monitor)\r\n\r\n15. **下拉 value / 文案一律取字典项的 `value`(字典值),绝不用 `id`(主键)**。字典调`mapByDictTypes('a','b')` 一次性取多个,按**下划线转驼峰**取返回值(`recycle_status` → `res.recycleStatus`),项为 `{label, value, id}`。\r\n16. **`a-select` 的 placeholder 只在值为 `undefined`/`null` 时显示**,空字符串 `''` 会被视为已有值。所有下拉类字段(搜索参数、表单字段)初始值一律 `undefined`,**禁用 `''`**(多选绑定 `[]` 正常)。\r\n17. **时间范围参数统一传毫秒时间戳**(`dayjs(x).valueOf()`),不是 unix 秒。依据:源码 `DateRange` 的 onChange 输出 `date.map(o => dayjs(o).valueOf())`,`useFormValues.fieldMapToTime` 默认 `format=''` 原样透传。\r\n18. **接口请求不写 `catch`**(错误由全局拦截器统一提示)。但三类 catch 必须保留:① 表单校验链 `.catch(() => {})`;② `try { await validate() } catch { return }`;③ `JSON.parse` 解析容错。\r\n19. **接口报错会跳内置错误页**:HTTP 403(含 301)→ `/403`、404 → `/404`,**在内容区 `router-view` 内切换**(保留侧边菜单与顶栏,不整页顶掉外壳),且不再叠加通知。跳转 URL 带 `?api=<接口地址>&status=<原始状态码>`,错误页据此切换成接口口径文案(403「接口无权限」、301「接口地址已变更」、404「接口不存在」)并显示接口地址;不带 `?api=` 时仍是页面口径(页面无权限 / 页面不存在)。**5xx 不跳错误页**,仍走原来的通知提示(`/500` 页面保留,可直接访问)。后台轮询等非主流程请求若要保住当前页面,可传 `{ skipErrorPage: true }` 跳过跳转:\r\n\r\n ```js\r\n this.$utils.http.post('/api/msg/count', {}, { skipErrorPage: true })\r\n ```\r\n\r\n---\r\n\r\n## 七、常见全局方法速查\r\n\r\n| 调用 | 作用 |\r\n| --------------------------------------------------------- | ----------------------------- |\r\n| `$l('中文'[, key])` | 国际化 |\r\n| `$push(path, query)` / `$open(path, query)` | 跳转 / 新窗口(自动拼 base) |\r\n| `$message.*` / `$modal.*` / `$notice.*` / `$confirm(...)` | 轻提示 / 弹窗 / 通知 / 确认框 |\r\n| `this.$utils.ls.get/set/clear` | 本地存储 |\r\n| `this.$utils.http(config)` | 发起请求(默认 POST) |\r\n| `$filter.dateFormat(v, fmt)` | 日期格式化 |\r\n| `v-action:code` | 按钮级权限(按 `button_code` 全等匹配) |\r\n| `$utils.hasAction(code)` | 按钮级权限(函数式,可做「或 / 且」) |\r\n| `$utils.iconOf('info-circle')` | antd v1 `type` 写法换图标组件 |\r\n| `$utils.messageFormat(str, values)` | `{0}` / `{name}` 占位符替换 |\r\n| `$utils.filterSelectOption(iv, opt)` | antd4 版下拉过滤 |\r\n| `$utils.randomDrawerPlacement()` | 随机抽屉方向 |\r\n| `var(--s-color)` / `.s-theme-color` | 主题色(CSS 变量 / 工具类) |\r\n\r\n---\r\n\r\n## 八、在线文档入口\r\n\r\n| 地址 | 内容 |\r\n| ------------------- | ------------------------------------------- |\r\n| `<base>/docs` | 说明文档(本文) |\r\n| `<base>/components` | s组件(基座内置组件:左菜单 + 预览 + 源码) |\r\n", j = "# sapit-ui base framework guide and business usage\r\n\r\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).\r\n>\r\n> This document is also the data source of the built-in `/docs` page and the `/components` page.\r\n>\r\n> Prop defaults in the base source are written in Chinese and translated at render time, so the tables below show their English rendering.\r\n\r\n---\r\n\r\n## Contents\r\n\r\n- [1. Overview](#docs-1Overview)\r\n- [2. What the base provides](#docs-2Whatthebaseprovides)\r\n- [3. Layout and height rules](#docs-3Layoutandheightrules)\r\n- [4. Build and configuration](#docs-4Buildandconfiguration)\r\n- [5. Business project integration](#docs-5Businessprojectintegration)\r\n- [6. Caveats](#docs-6Caveats)\r\n- [7. Global method quick reference](#docs-7Globalmethodquickreference)\r\n- [8. Online documentation entry](#docs-8Onlinedocumentationentry)\r\n\r\n---\r\n\r\n## 1. Overview\r\n\r\n### 1.1 The five pieces\r\n\r\n| Project | Role | Description |\r\n| --------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- |\r\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 |\r\n| `sapit-ui-plus` | <span style=\"color:#d46b08\">Published artifact</span> | The git repository that receives the base `dist` (`lib/`, `docs/`, `vite-plugins/`) |\r\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 |\r\n\r\n```text\r\nsapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template\r\n```\r\n\r\n### 1.2 Directory structure (base)\r\n\r\n```text\r\nsapit-ui-framework/\r\n├─ packages/ # published content source (entry dependency graph)\r\n│ ├─ index.js # library entry, exports registerGlobalConfig\r\n│ ├─ components/ # built-in S* components\r\n│ ├─ layouts/ # BasicLayout / BlankLayout / UserLayout / RouteView / PageView\r\n│ ├─ router/ # constant routes + dynamic routes + static routes + guards\r\n│ ├─ store/ api/ utils/ locales/ static/ style/\r\n│ └─ pages-components/ # login, workplace, todo, message, 404/403/500, docs pages\r\n├─ docs/ # this document (rendered by the built-in /docs)\r\n├─ vite-plugins/ # docs-viewer plugin\r\n├─ src/ # the base's own debug shell\r\n└─ vite.config.js / package.json\r\n```\r\n\r\n---\r\n\r\n## 2. What the base provides\r\n\r\n### 2.1 Global components\r\n\r\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>`).\r\n\r\n| Category | Components |\r\n| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| Layout | `SSkeletonLayout` (skeleton layout: title + button group + content, see 2.16), `SListLayout`, `SListCardLayout`, `SListTableTreeLayout`, `SSuperListLayout`, `SFormLayout`, `SPanelLayout`, `SCollapses`/`SCollapsesItem`, `SDrawer` |\r\n| Overlay | `SModal`, `SModalTemplate`, `ModalHeader`, `SIconModal`, `SImportModal` (bulk import, see 2.11) |\r\n| Form / filter | `SForm`, `SFormItem`, `SExtendFieldsForm`/`SExtendFieldsFormItem` (dynamic extra fields), `SFilterWrap`, `SFilterItem`, `SCascader`, `STree`, `STreeSelect`, `SDataRangeTreeSelect` (data-permission scope tree), `SUserSelect`, `SUserSelectButton`, `SChooseUser` (user picker with data permission, see 2.14), `SBelowChoosePosition` (position picker, see 2.15), `SOfficeSelect`, `SIconSelect` (icon picker) |\r\n| Upload | `SFileUpload`, `SDraggerUpload`, `SCopperUpload`, `CropperModal` |\r\n| Display / others | `SEditor`, `SEmpty`, `SIcon`, `SSvg`, `SAnchor`, `SColorPicker`, `SToggleLanguage`, `SettingFilter`, `SettingColumns`, `SSideMenu`/`STopMenu` |\r\n\r\n> Component usage lives in the built-in component page **`/components`** (two tabs: \"s components\" and \"tools / config\"; the latter lists every web-config option and every `$utils` method).\r\n>\r\n> Registration rule: `components/**/*.vue` is registered globally **by file name** (`SForm.vue` → `<SForm>`, **not kebab-case**); the later one wins on conflict.\r\n> `Table/index.jsx` is a `.jsx` file that `import.meta.glob` cannot match, so the base **registers it separately as the global `STable`** in `packages/index.js` (`<s-table>` works without any import).\r\n> All `@ant-design/icons-vue` icons are registered globally and exposed as `$icons`.\r\n> Some helper components are internal only: `ModalHeader` (SModal), `CropperModal` (SCopperUpload), `CustomInput`/`SettingColumns`/`SettingFilter` (SSuperListLayout).\r\n\r\n### 2.1.1 Choosing a layout component\r\n\r\n| Scenario | Use |\r\n| --------------------------------------- | -------------------------------------------------------------------------------------- |\r\n| Title + buttons + custom content (no table / pagination / form) | `SSkeletonLayout` (see 2.16, ships with a title bar and permission-aware buttons) |\r\n| Ordinary list page | `SListLayout` |\r\n| Card list | `SListCardLayout` |\r\n| List + left tree | `SListTableTreeLayout` (the left tree container class must be `.side.s-side-tree`, see 3.5) |\r\n| List with advanced search / table | `SSuperListLayout` |\r\n| Add / edit / detail (routed) | `SFormLayout` (`#form` slot holds `SForm`; `#footer-callback` receives `save`/`cancel`/`prev`/`next`) |\r\n| Form as modal content | `SModal` (do not nest `SFormLayout`) |\r\n| Dynamic form driven by backend fields | `SExtendFieldsForm` (`data` + `defaultValue`; the ref exposes `validate/clearValidate/getModel`) |\r\n| Data-permission scope selection | `SDataRangeTreeSelect` (`autoSysConfig` manages the system `dataScope` config) |\r\n\r\n### 2.2 Global properties / methods\r\n\r\nAvailable after `$registerGlobalConfig` runs (`this.$xxx` / `$xxx` in templates / `window.$xxx`):\r\n\r\n| Name | Description |\r\n| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |\r\n| `$registerGlobalConfig(config, pages)` | Initialization entry (see 5.2) |\r\n| `$utils` | Utility collection: `$utils.env` / `$utils.ls` / `$utils.http` plus general helpers |\r\n| `env` | Merged environment configuration (= `$utils.env`) |\r\n| `$i18n` / `$l(name, key)` | 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`) |\r\n| `$theme` / `$staticRoutes` / `$pinia` | Theme object / static route list / user store instance |\r\n| `$modal` / `$message` / `$notice` / `$confirm` | antd `Modal` / `message` / `notification` / `Modal.confirm` (list component button api branch calls `this.$confirm`) |\r\n| `$push(path, query)` / `$open(...)` | In-app navigation / new window (automatically prefixes `VITE_APP_BASE_URL`) |\r\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 |\r\n\r\n### 2.3 Layouts\r\n\r\n`packages/layouts/index.js`: `BasicLayout` (header + side menu + content), `BlankLayout`, `UserLayout` (login), `RouteView`, `PageView`.\r\n\r\nThe height chain of `BasicLayout` (**business layout components must match it**, see chapter 3):\r\n\r\n```text\r\n.basic-layout-common (100vh)\r\n→ .ant-layout\r\n→ .main-content\r\n→ .container (height = mainHeight = clientHeight - headerHeight)\r\n └─ minus footerHeight(56) when the footer is shown\r\n → router-view (height = contentHeight, overflow: hidden auto)\r\n → business layout component (.list-layout / .form-layout, flex:1)\r\n```\r\n\r\n> `mainHeight` / `contentHeight` are computed from the **real `header.offsetHeight`** (not a hard-coded 58) so the layout cannot disagree with the actual rendering and produce overflow scrollbars.\r\n\r\n### 2.4 Routes\r\n\r\n**Constant routes** (`packages/router/index.js`):\r\n\r\n| Path | Description |\r\n| ------------------------------------------ | ------------------------------------------------------------------------------------ |\r\n| `/login/index` | Login page (base default, can be overridden by the business, see 5.3) |\r\n| `/workplace/index` | Default home (`VITE_APP_DEFAULT_PATH`, overridable) |\r\n| `/workbench/index`, `/message/index` | Workbench / messages |\r\n| `/docs`, `/components` | Built-in docs / component pages (`public` = no login, `hidden` = not in the menu) |\r\n| `/404`, `/403`, `/500`, `/:pathMatch(.*)*` | Error pages; the catch-all renders 404 (**no redirect**, so refreshing dynamic routes never lands on a 404). All four sit under `BasicLayout` and swap **only the content-area `router-view`**, keeping the sidebar and header untouched |\r\n\r\n> Redirect rules, query parameters, wording and color overrides for the error pages are documented in [2.17 Error pages](#docs-217Errorpages301403404500).\r\n\r\n**Static routes** (`staticRoutes`, independent of backend menus): see 5.4. The base ships `/docs` and `/components`.\r\n\r\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).\r\n\r\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 5.8 permissions and 6.1).\r\n\r\n### 2.5 State management (pinia)\r\n\r\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.\r\n\r\n### 2.6 Utilities (`$utils`)\r\n\r\n| Module | Description |\r\n| ----------------------------------- | ------------------------------------------------------------------------------- |\r\n| `$utils.env` | Environment configuration object |\r\n| `$utils.ls` | Local storage (namespace `VITE_APP_SYS_SERVER_NAME`) |\r\n| `$utils.http` | axios instance (token/`client-id` injection, response unwrapping, login timeout, file download) |\r\n| `parseAppUrl` / `innerRedirect` etc.| Build in-app URLs with the base (sub-path aware); external http(s) URLs are kept as-is |\r\n| `messageFormat(str, values)` | `{0}` / `{name}` placeholder substitution (confirm dialogs etc.) |\r\n| `filterSelectOption(iv, opt)` | antd4-ready `:filterOption` (reads `option.label` / `option.value`) |\r\n| `randomDrawerPlacement()` | Randomly returns `left` / `right` / `top` / `bottom` (kept from the source project) |\r\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')\" />` |\r\n| `hasAction(name)` | Functional button-level permission check, same source as `v-action`; for `v-if` OR / AND logic and `disabled` computation |\r\n| Others | Type checks, dates, arrays, url, dom, debounce/throttle, money, phone validation, etc. |\r\n\r\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.\r\n>\r\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.\r\n\r\n`v-action:xxx` is the button-level permission directive: `<a-button v-action=\"'add'\">Add</a-button>`.\r\n\r\n- It delegates to `$utils.hasAction(actionName)` — the directive and the function share **one** decision path\r\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`\r\n- Matching rule: `String(button_code) === String(actionName)`, **exact equality** (`add` no longer matches `batchAdd`)\r\n- Functional usage: `<a-button v-if=\"$utils.hasAction('add') || $utils.hasAction('edit')\">`\r\n\r\n\r\n### 2.7 Internationalization\r\n\r\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:\r\n\r\n```js\r\n// src/views/user/i18n.js -> namespace user\r\nexport default {\r\n '<source text>': 'Cancel'\r\n}\r\n```\r\n\r\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.\r\n\r\nRegister the namespace inside the page, then call `$l('<source text>')` directly — never `$l('user.<source text>')`:\r\n\r\n```js\r\nexport default {\r\n created() {\r\n this.useI18n('user') // Options API\r\n }\r\n}\r\n```\r\n\r\n```js\r\n// also works inside <script setup>\r\nconst { $l } = useI18n('user')\r\n```\r\n\r\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.\r\n\r\n| Call site | Usage | Namespace |\r\n|---|---|---|\r\n| Template / inside a component, `this.$l(...)` | `{{ $l('<source text>') }}` | yes, the one registered via `useI18n` first |\r\n| Plain JS outside components (api / utils) | `window.$l('<source text>')` | no, global dictionary only |\r\n\r\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`.\r\n\r\n### 2.8 Theme\r\n\r\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.\r\n\r\nHow it takes effect:\r\n\r\n1. **antd**: `a-config-provider` tokens (`colorPrimary`/`colorLink`).\r\n2. **CSS variables**: on startup the selected theme is written to `:root` as `--s-color`, `--s-light-color`, `--s-dark-color`, `--s-border-color`, `--s-bg-color`; the utility classes `.s-theme-bg`, `.s-theme-color`, `.s-theme-border`, `.s-theme-border-top`, `.s-theme-icon-bg` are built in.\r\n3. **body class**: `theme-<VITE_APP_THEME_VALUE>` (e.g. `theme-blue`).\r\n4. **Menu palette**: on startup the whole menu palette (top-level background / submenu background / hover / selected / text) is derived from the primary color and **emitted as solid `#rrggbb` only — no alpha**. It is written to `:root` as `--s-menu-bg`, `--s-menu-sub-bg`, `--s-menu-text`, `--s-menu-text-hover`, `--s-menu-text-active`, `--s-menu-hover-bg`, `--s-menu-active-bg`, `--s-menu-active-text`, plus `window.$menuTheme` (carrying the antd `Menu` tokens and an `isLightBg` flag).\r\n\r\nThe menu is **light by default** (the `blue` theme yields `#e8ecf3` for the top level), and all four backgrounds come from one set of parameters, so tuning one changes the whole menu. **The full palette, config reference and measured values per theme live in [2.18 Menu palette](#docs-218Menupalettesidetop)**.\r\n\r\n> Below 50% lightness the palette flips to \"dark background + light text\" automatically, with a WCAG contrast ratio solved to stay >= 4.6 — no manual text tuning needed. The side menu, the top menu (`VITE_APP_MENU_BAR: 'top'`), the logo variant and the header text color all share this single decision.\r\n\r\n```css\r\n.my-box {\r\n color: var(--s-color);\r\n background: var(--s-bg-color);\r\n}\r\n```\r\n\r\n> Adding a theme: append a set to the base `VITE_APP_THEME`, select it with the business `VITE_APP_THEME_VALUE`, and antd plus `var(--s-*)` follow automatically.\r\n\r\n### 2.9 API / page components / others\r\n\r\n- `packages/api`: `login.js` (login, `getCode`, `verify`, `rsaPublicKey`, `getLoginConfig`, ...), `common.js`, `upload.js`, `workbench.js`.\r\n- `packages/pages-components`: `login.vue`, `login-common/LoginForm.vue`, `workbench.vue`, `todo.vue`, `message.vue`, `403/404/500.vue`, `docs.vue`, `components-doc.vue`.\r\n- Static assets live in `packages/static/*`, styles in `packages/style/*`; antd icons, axios, dayjs, moment, pinia, vue-router, vue-i18n, jodit, vue-cropper, vuedraggable, html2canvas, crypto-js, jsencrypt, nprogress, qs, lodash.\\* and more are already bundled.\r\n\r\n### 2.10 Login / SSO\r\n\r\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`.\r\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).\r\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`.\r\n\r\n**SSO static assets are now part of the base**: the sources live in `packages/sso/` (`sso.js` / `sso.html`) and ship with the npm package (`sso` is listed in `files`, and the build copies `dist/sso`). Business projects **no longer maintain sso files under `public/`**; just add this to `vite.config.js`:\r\n\r\n```js\r\nimport ssoPlugin from 'sapit-ui-plus/vite-plugins/sso-plugin.js'\r\nssoPlugin()\r\n```\r\n\r\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.\r\n\r\n> ⚠️ `redirect_uri` supports the `{code}` placeholder; **without the placeholder the jump is raw and the code is not exchanged**.\r\n> The platform standard requires `?code={code}` — keep that in the portal client's `redirectUri`, do not \"optimize\" the placeholder away.\r\n\r\n### 2.11 SImportModal — generic bulk import modal\r\n\r\nThree-step import: **upload file → data preview (rows editable / deletable) → import result (with exception export)**. File limits: `.xls/.xlsx`, ≤ 500KB.\r\n\r\n```vue\r\n<s-import-modal\r\n ref=\"importModalRef\"\r\n :upload-url=\"IMPORT_UPLOAD_URL\"\r\n :columns=\"importColumns\"\r\n :apis=\"importApis\"\r\n :type-select=\"importTypeSelect\"\r\n @reload=\"handChange\"\r\n/>\r\n\r\n<script setup>\r\nimportModalRef.value.show() // open the modal (it resets its own state)\r\n\r\nconst importApis = { templateDownload, importPreview, importData, exportExceptionData }\r\nconst importColumns = [{ title: 'Device SN', dataIndex: 'sn', width: 150 }]\r\n// optional: a business-parameter dropdown passed with the import; its value is submitted with every API call via extraKey\r\nconst importTypeSelect = computed(() => ({\r\n options: [{ label: 'Camera', value: '1' }],\r\n placeholder: 'Select device category'\r\n}))\r\n<\/script>\r\n```\r\n\r\n| props | Type | Default | Description |\r\n| ------------ | --------------- | ---------------- | ------------------------------------------------------------------------ |\r\n| `value` | Boolean | `false` | Visibility (`v-model:value`) |\r\n| `title` | String | `Bulk import` | Modal title |\r\n| `width` | String / Number | `1000` | Modal width |\r\n| `uploadUrl` | String | `''` | Upload endpoint (full gateway address, e.g. `/monitor/DeviceInfo/Uploader`) |\r\n| `columns` | Array | `[]` | Preview / result table columns `[{ title, dataIndex, width }]` |\r\n| `apis` | Object | `{}` | The four import APIs (see below) |\r\n| `typeSelect` | Object | `null` | `{ options, placeholder, loading }`; omit when no business parameter is needed |\r\n| `extraKey` | String | `'deviceTypeId'` | Field name used to submit the `typeSelect` value |\r\n\r\n| events | Description |\r\n| -------------- | -------------------------------------------------- |\r\n| `update:value` | Visibility change (`v-model`) |\r\n| `reload` | List must be refreshed after a successful import / close |\r\n\r\n| methods (via ref) | Description |\r\n| ----------------- | ------------------------------------ |\r\n| `show()` | Open the modal and reset its state |\r\n\r\nAPI contract (all return a Promise; the component accepts both `{ code, data }` and plain data):\r\n\r\n| API | Input | Output |\r\n| --------------------- | ------------------------------ | ---------------------------------------------------- |\r\n| `templateDownload` | `{ ...extraParams }` | `{ url }` (the component triggers the download) |\r\n| `importPreview` | `{ fileName, ...extra }` | `{ dataRow: [] }` |\r\n| `importData` | `{ list, ...extra }` | `{ resultType, snum, fnum, failResult: [] }` |\r\n| `exportExceptionData` | `{ list, ...extra }` | `{ url }` |\r\n| Upload (internal) | `FormData(file)` → `uploadUrl` | `{ name }` / `{ fileName }` (later APIs receive fileName) |\r\n\r\n> ⚠️ `SImportModal` is **three-step** (upload → preview/edit → result/exception export).\r\n> If a business project has a **single-step** import component that imports as soon as a file is chosen (e.g. hy-monitor's `views/people/components/ImportModal.vue`, `views/basicData/components/ImportModal.vue`),\r\n> the two differ in layout, API, events and the contract with the calling page, so **they must not be swapped for one another** — keep each implementation.\r\n\r\n### 2.12 SDataRangeTreeSelect — data permission scope tree\r\n\r\nSelects a data permission scope (organization / campus / unit); internally calls `findOfficeList` / `getOfficeByIds` / `getSysConfigByCode('dataScope')`.\r\n\r\n```vue\r\n<s-data-range-tree-select v-model:value=\"ids\" :auto-sys-config=\"true\" />\r\n```\r\n\r\nCommon props: `value` (array of ids) / `multiple` / `treeCheckable` / `allowClear` / `placeholder` / `maxTagCount` / `disabledGroup` (`'1'` organization, `'2'` campus, `'3'` unit; an array is allowed) / `showOnlyOrganization` / `treeSelectData` (pass an array to skip the request) / `isDataScopeFilter` / `autoSysConfig` / `defaultValue`.\r\nevents: `update:value`, `change` (both emit an **array of ids**).\r\n\r\n> ⚠️ The template hard-codes `label-in-value` + `tree-check-strictly`, so antd requires `value` to be an array of `{ label, value }` objects.\r\n> Therefore **echoing back a value must first convert ids with `getOfficeByIds(ids)`**; assigning raw id strings raises an `Invalid prop value` warning and the input shows bare numeric ids.\r\n\r\n### 2.13 SExtendFieldsForm — dynamic extra field form\r\n\r\nThe backend delivers field configuration (`fillModeConfig` is a JSON string containing `showType` / `config`) and the front end renders from it.\r\n\r\n```vue\r\n<s-extend-fields-form ref=\"extRef\" :data=\"fields\" :default-value=\"values\" type=\"edit\" :cols=\"2\" />\r\n<script setup>\r\n// the ref exposes three methods\r\nextRef.value.validate() // Promise<boolean>\r\nextRef.value.clearValidate()\r\nextRef.value.getModel() // [{ fieldCode, value }] (object values are already JSON.stringify'd)\r\n<\/script>\r\n```\r\n\r\n| props | Type | Default | Description |\r\n| -------------- | ------ | ------- | ---------------------------------------------------- |\r\n| `data` | Array | `[]` | Field definitions (`fieldCode/fieldName/fillModeConfig`) |\r\n| `type` | String | `'add'` | `add` / `edit` / `view` (`view` skips validation) |\r\n| `defaultValue` | Array | `[]` | Values echoed in edit mode `[ { fieldCode, value } ]` |\r\n| `cols` | Number | `2` | Columns per row (non-full-width fields take `100/cols%`) |\r\n| `labelWidth` | String | `auto'` | Label width |\r\n\r\n`showType` values that automatically take the whole row: `textarea`, `upload`, and `select` with `config.multiple`. Default values are converted per `showType`: `datePicker` → dayjs object, `number` → Number, multi-select `select` → comma-split array.\r\n\r\n### 2.14 SChooseUser — user picker modal (with data permission)\r\n\r\nModal user picker: organization tree on the left, user list on the right (avatar / name / employee or student number + unit). The search area contains a **user-type filter** (all / staff / student / external), and it supports single or multiple selection, scroll paging, select-all / invert, and a selected list on the right in multi-select mode. **The modal closes automatically after confirming.**\r\n\r\nHow it differs from `SUserSelect` (the criteria for choosing between them):\r\n\r\n| Aspect | `SUserSelect` | `SChooseUser` |\r\n| ----------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |\r\n| Shape | Read-only input plus an integrated modal | Pure modal; visibility controlled by the business |\r\n| Data permission | Tree / list APIs carry no data permission | Uses `levelOneChildrenWithAuth` / `levelTwoChildrenWithAuth` / `findUsersWithAuth`, **filtered by the logged-in user's permission** |\r\n| User type | No filter | Built-in staff / student / external filter |\r\n| Value contract | `v-model:value` binds ids directly (string for single, array for multiple) | `v-model:value` controls visibility; `v-model:selectedIds`/`selectedId` bind selected ids; `@callback` emits the **list of selected objects** |\r\n\r\n```vue\r\n<s-choose-user\r\n v-model:value=\"userScopeVisible\"\r\n v-model:selectedIds=\"userScopeIds\"\r\n :multiple=\"true\"\r\n @callback=\"userScopeCallback\"\r\n/>\r\n<script setup>\r\n// confirm (single or multiple): payload = [{ id, name, cover, userid, company, department }] (a single pick is a one-element array)\r\n// cancel / close: payload = undefined\r\nconst userScopeCallback = (payload) => {\r\n if (payload) userNames.value = payload.map((u) => u.name).join(',')\r\n userScopeVisible.value = false\r\n}\r\n<\/script>\r\n```\r\n\r\n| props | Type | Default | Description |\r\n| ------------------- | ------- | --------------------------------- | ----------------------------------------------------------------------------- |\r\n| `value` | Boolean | `false` | Modal visibility (`v-model:value`) |\r\n| `title` | String | `Select users` | Modal title |\r\n| `multiple` | Boolean | `false` | Multiple selection (the selected list appears on the right) |\r\n| `searchPlaceholder` | String | `Search by name, employee/student number or phone` | Search box placeholder |\r\n| `required` | Boolean | `false` | When nothing is selected, confirming warns and does not close |\r\n| `selectedIds` | Array | `[]` | Echoed id array for multi-select (`v-model:selectedIds`); `getBUseryIds` loads objects |\r\n| `selectedId` | String | `''` | Echoed id for single select (`v-model:selectedId`); `getUserById` loads the object |\r\n\r\n| events | Description |\r\n| -------------------- | ------------------------------------------------------------------------ |\r\n| `update:value` | Modal closed (both confirm and cancel set it to `false`, no manual close needed) |\r\n| `update:selectedIds` | Two-way binding of the selected id array |\r\n| `update:selectedId` | Selected id in single-select mode |\r\n| `callback` | On confirm emits the selected objects **array**; nothing on close |\r\n\r\n> ⚠️ All APIs live in the base `packages/api/common.js` (`findUsersWithAuth` = `/user/users/authorized`, etc.), so the business passes none; an empty tree/list in a backend-less preview environment is expected. In the list, `userid` shows `loginName` (employee / student number).\r\n\r\n### 2.15 SBelowChoosePosition — position picker modal\r\n\r\nModal **position** picker (originally from the business project's `/components/BelowChoosePosition`, now part of the base): the left tree loads the whole tree of \"the root node and every unit below it\" in one call (`getBelowUnit`, scope determined by `rootId`), while the right list queries positions (`findJobs`); single and multiple selection are supported.\r\n\r\nHow it differs from the other base selectors: `SOfficeSelect`/`SUserSelect` query organizations/users with a lazily loaded left tree, whereas this component queries **positions** with a fully loaded tree. **It does not close automatically after confirming**; the business must close it in `callback` (same behaviour as the source project).\r\n\r\n```vue\r\n<s-below-choose-position\r\n v-model:value=\"visible\"\r\n v-model:selectedIds=\"positionIds\"\r\n multiple\r\n :root-id=\"campusId\"\r\n @callback=\"onCallback\"\r\n/>\r\n<script setup>\r\n// confirm (multiple): payload = { selectedList: [{ id, name, deptName, nameOrCount }] }\r\n// confirm (single): payload = { selected: { id, name, ... } }\r\n// cancel / close: payload = false\r\nconst onCallback = (payload) => {\r\n if (payload && payload.selectedList) {\r\n names.value = payload.selectedList.map((i) => i.name).join(',')\r\n }\r\n visible.value = false // the component does not close on confirm, so close it manually\r\n}\r\n<\/script>\r\n```\r\n\r\nThe props match `SChooseUser` (`title` defaults to `Select position`, `searchPlaceholder` to `Search by position name or code`), plus one component-specific prop:\r\n\r\n| props | Type | Default | Description |\r\n| -------- | ------ | ------- | -------------------------------------------------------------------------- |\r\n| `rootId` | String | `''` | Left tree root id, which defines the data scope; changing it reloads the tree, `'-1'` is used when omitted |\r\n\r\n| methods (via ref) | Description |\r\n| ---------------------- | ------------------------------ |\r\n| `initLeftTreeData(id)` | Manually reload the left tree |\r\n\r\n| events | Description |\r\n| -------------------- | -------------------------------------------------------------------------- |\r\n| `update:value` | Set to `false` only on cancel; **confirm does not close the modal** |\r\n| `update:selectedIds` | Two-way binding of the selected position ids (echo uses `getPositionByIds`) |\r\n| `update:selectedId` | Single-select id (echo uses `getPositionById`) |\r\n| `callback` | Confirm emits `{ selectedList }` / `{ selected }`; close emits `false` |\r\n\r\n> ⚠️ The `callback` payload shape differs from `SChooseUser` (an object `{ selectedList }` versus an array) and the close-on-confirm behaviour is the opposite, so the two callbacks are not interchangeable.\r\n\r\n---\r\n\r\n### 2.16 SSkeletonLayout — skeleton layout (title + button group + content)\r\n\r\n> Added 2026-10-28. A page-level \"title bar + action buttons + content area\" shell. Same tier as `SListLayout` / `SFormLayout` but lighter: **no table, no form, no pagination** — the content area is entirely up to the slot.\r\n\r\n```vue\r\n<s-skeleton-layout\r\n :title=\"$l('Collection jobs')\"\r\n :buttons=\"[\r\n { key: 'add', name: 'Add', icon: true },\r\n { key: 'remove', name: 'Delete', disabled: true },\r\n { key: 'export', name: 'Export', icon: 'DownloadOutlined' }\r\n ]\"\r\n bg-color=\"#fff\"\r\n @btnCallback=\"onBtnClick\"\r\n>\r\n <div class=\"my-content\">...</div>\r\n <template #otherBtns><a-button>Custom</a-button></template>\r\n <template #other>Footer content</template>\r\n</s-skeleton-layout>\r\n```\r\n\r\n| props | Type | Default | Description |\r\n| --------- | ------ | ------- | -------------------------------------------------- |\r\n| `title` | String | — | **Required** title bar text |\r\n| `buttons` | Array | `[]` | Button config array, see below |\r\n| `bgColor` | String | `''` | Root background colour |\r\n\r\nEach `buttons` item:\r\n\r\n| Field | Type | Description |\r\n| ---------- | ----------------- | ---------------------------------------------------------------------------------------------------- |\r\n| `key` | String | Unique key, emitted on click; `'add'` makes the button `primary` by default |\r\n| `name` | String | Button label (passed through `$l`, so the source Chinese text is fine) |\r\n| `icon` | String \\| Boolean | String = icon component name (e.g. `'PlusOutlined'`); `true` = look up the built-in iconMap by `key`; omit for no icon |\r\n| `action` | String | `v-action` permission code, defaults to `key` (real permission filtering — unauthorised buttons are removed) |\r\n| `show` | Boolean | Default `true`; `false` hides via `v-show` (keeps layout, still permission-registered) |\r\n| `disabled` | Boolean | Greyed out |\r\n| `type` | String | Overrides `a-button`'s `type` |\r\n\r\n| slots | Description |\r\n| ----------- | ---------------------------------------- |\r\n| default | Content area (`.skeleton-layout-main`) |\r\n| `otherBtns` | Appended to the right of the button group |\r\n| `other` | Bottom area |\r\n\r\n| events | Description |\r\n| ------------- | ------------------------------------------- |\r\n| `btnCallback` | Emits the clicked button's `key` |\r\n\r\n| methods (via ref) | Description |\r\n| -------------------- | ----------------------------------------------------------------- |\r\n| — | **None.** Height is allocated by flex; no method call is needed (see below) |\r\n\r\nBuilt-in iconMap keys: `add` / `edit` / `delete` / `remove` / `import` / `export` / `assign` / `execute` / `pause` / `resume` / `approve` / `setting` / `TopOfType` / `TOP` / `synchronize`.\r\n\r\n> **Height implementation (revised 2026-10-28)**: root `height:100%; display:flex; flex-direction:column`, title bar `flex:0 0 60px`, content area `flex:1 1 auto; min-height:0; overflow:hidden auto`, bottom slot `flex:0 0 auto`. **Zero JS, no resize listener** — follows window resize / sidebar collapse automatically.\r\n>\r\n> Prerequisite: the parent container must have a definite height. The base `BasicLayout` already renders `router-view` with `:style=\"{ height: contentHeight + 'px' }\"`, which falls through to the page root component, so usually nothing extra is needed; a custom `height:auto` wrapper must be given a definite height.\r\n>\r\n> The old `initLayoutHeight()` method **has been removed**, and `layoutHeight` is no longer exposed (the previous implementation was `parentNode.offsetHeight - 76`, computed only once on `mounted`).\r\n\r\n---\r\n\r\n### 2.17 Error pages (301 / 403 / 404 / 500)\r\n\r\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.\r\n\r\n| Path | Component | Status sources | Accent |\r\n| --- | --- | --- | --- |\r\n| `/403` | `pages-components/403.vue` | API 403 (no permission), API 301 (address changed), page without permission | Orange `#fa8c16` |\r\n| `/404` | `pages-components/404.vue` | No route matched (catch-all `/:pathMatch(.*)*`), API 404 | Primary color `var(--s-color)` |\r\n| `/500` | `pages-components/500.vue` | Reachable directly only; **API 5xx does not redirect**, it still shows a notification | Red `#f5222d` |\r\n\r\n**Where they render**: `buildErrorRoute()` wraps all three under `BasicLayout` as nested children (`children: [{ path: '' }]`) — navigation **replaces only the content-area `router-view`**, leaving the sidebar, header and footer untouched. The route-miss 404 (catch-all) and the API 404 share the same structure and behave identically.\r\n\r\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.\r\n\r\n**API status mapping** (`packages/utils/request.js`):\r\n\r\n| HTTP status | Behaviour | Target URL |\r\n| --- | --- | --- |\r\n| 301 | Go to the 403 page with the \"API address changed\" wording | `/403?api=<api>&status=301&from=<page>` |\r\n| 403 | Go to the 403 page with the \"no API permission\" wording | `/403?api=<api>&status=403&from=<page>` |\r\n| 404 | Go to the 404 page with the \"API does not exist\" wording | `/404?api=<api>&status=404&from=<page>` |\r\n| Anything else (incl. 5xx) | **No redirect**, a notification is shown as before | — |\r\n\r\n**Query parameters**:\r\n\r\n| Parameter | Meaning |\r\n| --- | --- |\r\n| `api` | Failing API address. **Its presence switches to the API wording**; page-level failures omit it |\r\n| `status` | Original status code; `301` gets its own \"API address changed\" wording |\r\n| `from` | Source page address (with `VITE_APP_BASE_URL` stripped), rendered as the \"source address\" line |\r\n\r\nWording matrix:\r\n\r\n| Source | 403 page | 404 page |\r\n| --- | --- | --- |\r\n| Page (no `api`) | Insufficient page permission | Page not found |\r\n| API (with `api`) | No API permission | API does not exist |\r\n| API 301 | API address changed | — |\r\n\r\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.\r\n\r\n**Skipping the redirect** (polling, auxiliary requests — keeps one failing side request from taking over the whole page):\r\n\r\n```js\r\n// the third argument accepts { skipErrorPage: true } (also readable from the request meta)\r\nwindow.$utils.http.post(url, data, { skipErrorPage: true })\r\n```\r\n\r\n**Concurrency and fallback**: error-page navigation is **serialised, last one wins**, so a 403 and a 404 arriving together no longer cancel each other. After navigating it re-reads `currentRoute` to verify the arrival (tolerating a redirect that rewrites the path), retries twice, and only then falls back to a full-page `location.replace`, so the user always ends up on the error page. When already on the error page with an `api` parameter the reason is not overwritten — otherwise an auxiliary request fired by the error page itself would replace the real cause.\r\n\r\n**Changing colors / wording**:\r\n\r\n- All wording lives in i18n entries (`packages/pages-components/i18n.js`, namespace `pages-components`).\r\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`.\r\n- Every root node is `height:100%; overflow:hidden`, and the decorative glows are clipped by `__deco`, so overflow only scrolls inside the card and never creates a page scrollbar.\r\n\r\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.\r\n\r\n### 2.18 Menu palette (side / top)\r\n\r\nMenu colors are **not hard-coded in stylesheets**: on startup `packages/utils/menu-theme.js` derives the whole palette from the primary color, emits solid `#rrggbb` only (**no rgba / alpha**), writes it to `:root` CSS variables and exposes it as `window.$menuTheme`. Change the primary color or a parameter and all four backgrounds move together.\r\n\r\n| Part | CSS variable | Derivation |\r\n| --- | --- | --- |\r\n| Top-level background | `--s-menu-bg` | Primary hue + capped saturation + configured lightness |\r\n| Submenu panel | `--s-menu-sub-bg` | Same hue, one step lighter than the top level |\r\n| Hovered item | `--s-menu-hover-bg` | Same hue, 6 lightness points darker than the top level |\r\n| Selected item | `--s-menu-active-bg` | Primary blended with white, ratio driven by `VITE_APP_MENU_BG_ACTIVE_MIX` |\r\n| Normal text | `--s-menu-text` | Solved against the background for a contrast ratio >= 4.6 |\r\n| Hover / selected text | `--s-menu-text-hover`, `--s-menu-text-active` | Same rule |\r\n\r\nConfig (defaults in `packages/config/web-config.js`; overridable from the business `.env` or the deployed `config.json`):\r\n\r\n| Config | Default | Description |\r\n| --- | --- | --- |\r\n| `VITE_APP_MENU_BG` | `theme` | `theme` follows the primary color / `dark` = antd `#001529` / `#RRGGBB` uses that color |\r\n| `VITE_APP_MENU_BG_LIGHTNESS` | `93` | Top-level lightness 0-100: higher is lighter; **below 50 it flips to a dark background with light text** |\r\n| `VITE_APP_MENU_BG_SATURATION` | `30` | Max saturation 0-100: lower is closer to grey, `0` gives pure grey |\r\n| `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | Share of the primary color in the selected background, 0-100 |\r\n| `VITE_APP_MENU_THEME` | `dark` | Menu appearance; the text color actually follows the **background luminance**, not this value alone |\r\n| `VITE_APP_MENU_BAR` | `left` | `left` sidebar / `top` top bar; both share the same palette |\r\n\r\nDefault palettes per theme (lightness 93 / saturation 30 / active mix 16, measured):\r\n\r\n| Theme | Top-level | Submenu | Hover | Selected | Text |\r\n| --- | --- | --- | --- | --- | --- |\r\n| blue | `#e8ecf3` | `#f5f7fa` | `#d4dce8` | `#dae9ff` | `#344051` |\r\n| green | `#ebf3e8` | `#f7faf5` | `#dbe8d4` | `#e3f6da` | `#3d5134` |\r\n| orange | `#f3ede8` | `#faf7f5` | `#e8ded4` | `#feedda` | `#514334` |\r\n| red | `#f3e8e8` | `#faf5f5` | `#e8d4d5` | `#fddcdd` | `#513435` |\r\n| purple | `#ece8f3` | `#f7f5fa` | `#dcd4e8` | `#e8def8` | `#403451` |\r\n| cyan | `#e8f3f3` | `#f5fafa` | `#d4e8e8` | `#d9f5f5` | `#345151` |\r\n\r\nCommon tweaks:\r\n\r\n```js\r\n// business web-config.js / deployed config.json\r\nVITE_APP_MENU_BG_LIGHTNESS: 97, // 1) lighter (100 is near white)\r\nVITE_APP_MENU_BG_SATURATION: 0, // 2) drop the tint entirely, pure grey\r\nVITE_APP_MENU_BG_ACTIVE_MIX: 30, // 3) a more prominent selected item\r\nVITE_APP_MENU_BG: 'dark', // 4) back to the classic antd #001529\r\nVITE_APP_MENU_BG: '#213045' // 5) pin a custom color, no longer theme-driven\r\n```\r\n\r\n> Notes\r\n>\r\n> 1. With `VITE_APP_MENU_BG: '#RRGGBB'` the submenu, hover, selected and text colors are still derived from that color, so a new background never leaves unreadable text.\r\n> 2. Below 50 lightness the palette flips to dark: text turns light, the logo switches to its light variant and the header text turns white. The decision comes from `window.$menuTheme.isLightBg`, not `VITE_APP_MENU_THEME`.\r\n> 3. Do not hard-code menu colors such as `#001529` or `rgba(255,255,255,.1)` in business styles — use `var(--s-menu-*)`, otherwise a theme switch breaks the look.\r\n> 4. `.menu-wrap .ant-menu.ant-menu-dark` already backs the top-level, submenu, hover and selected nodes with these variables (the parts antd 4.2.6 Menu tokens miss).\r\n\r\n## 3. Layout and height rules\r\n\r\n> This chapter is a **mandatory contract for the base's internal layout components**. Business pages only use the layouts and never compute heights themselves; any new layout component must satisfy these rules first.\r\n\r\n### 3.1 Heights: prefer CSS flex fill; when dynamic calculation is needed, follow the three constraints\r\n\r\n> **Revised 2026-10-28**: the old title \"never compute heights via JS subtraction\" is **deprecated**. When a business content area needs its own scrollbar, the height **should** be computed dynamically — it just has to follow the constraints below instead of copying magic numbers per page.\r\n\r\n\r\n**The wrong way** (both `SListLayout` and `SFormLayout` did this early on):\r\n\r\n```js\r\n// ❌ compute the main area height by subtracting offsetHeight values\r\nthis.layoutHeight = this.$refs.layout.offsetHeight - toolsH - footerH - tabsH - 16\r\n```\r\n\r\nWhy it is always wrong: `offsetHeight` reads the **current rendering result**, and that result depends on the `height` you are about to write — a circular dependency. Symptoms:\r\n\r\n- with less than a full page of data the pagination floats in the middle, leaving 15–588px of empty space at the bottom;\r\n- the table/form area overflows its container by 1–N px, adding an extra page scrollbar;\r\n- changing one magic number (e.g. `tpH = 103`) skews every other page.\r\n\r\n**Preferred (zero JS)**: parent `height:100%` + `display:flex; flex-direction:column`, main area `flex:1 1 auto; min-height:0; overflow:auto`, footer bar `flex:0 0 auto`. This covers the vast majority of list and form pages.\r\n\r\n**When dynamic JS calculation is needed** (the content area must scroll, or its height follows the window / sibling nodes): **it is allowed and recommended**, but must satisfy three constraints:\r\n\r\n1. **One place only**: a single `calcXxxHeight()` per layout, never a magic number per page\r\n2. **Follow the container**: recalculate with `ResizeObserver` on the parent container, not just `window.resize`\r\n3. **Never read `$parent.$el`**: it breaks as soon as the parent DOM changes — use a `ref` on your own container\r\n\r\n**Still forbidden**: subtracting the `offsetHeight` of the very ancestor whose `height` you are about to write — a circular dependency. Read only values that do not depend on your own height (`window.innerHeight`, the height of a fixed header/footer node).\r\n\r\n\r\n### 3.2 The table fill chain (what keeps pagination pinned to the bottom)\r\n\r\n`STable`'s body gets its remaining height through flex, and **a single missing level in the chain prevents the fill**:\r\n\r\n```less\r\n.table-content {\r\n flex: 1;\r\n display: flex;\r\n flex-direction: column;\r\n min-height: 0;\r\n}\r\n.tabs-wrap {\r\n flex: 0 0 auto;\r\n}\r\n.table-container {\r\n flex: 1 1 auto;\r\n min-height: 0;\r\n display: flex;\r\n flex-direction: column;\r\n}\r\n.table-wrapper {\r\n flex: 1 1 auto;\r\n ...;\r\n} /* STable's root node — omit it and the whole chain breaks */\r\n.ant-table-wrapper {\r\n flex: 1 1 auto;\r\n ...;\r\n}\r\n.ant-spin-nested-loading .ant-spin-container .ant-table .ant-table-container {\r\n margin-left: 10px;\r\n} /* indent the table with margin, not padding */\r\n.ant-table-header {\r\n flex: 0 0 auto;\r\n}\r\n.ant-table-body {\r\n flex: 1 1 auto;\r\n min-height: 0;\r\n max-height: none !important;\r\n}\r\n.ant-table-pagination {\r\n margin-bottom: 0;\r\n flex: 0 0 auto;\r\n} /* one margin off is a 15–16px gap */\r\n```\r\n\r\nKey points:\r\n\r\n1. **`.table-wrapper` must not be missed** — it is `STable`'s root node; measurement shows the body will not fill without it;\r\n2. the `max-height` written by `scroll.y` must be overridden with `none !important`, otherwise it fights flex;\r\n3. pagination needs `margin-bottom: 0`, otherwise a permanent margin separates it from the container edge;\r\n4. indent the table with `:deep(.ant-table-container){margin-left:10px}`, **never** `padding-left` (it distorts the body width calculation).\r\n\r\n### 3.3 The `.tools` header bar is uniformly 60px\r\n\r\nEvery layout's `.tools` (title + button bar) is:\r\n\r\n```less\r\n.tools {\r\n height: 60px;\r\n display: flex;\r\n justify-content: space-between;\r\n align-items: center;\r\n padding: 0 16px;\r\n box-sizing: border-box;\r\n border-bottom: 1px solid #f0f2f5;\r\n}\r\n.list-filter-wrap {\r\n padding: 10px 16px;\r\n box-sizing: border-box;\r\n}\r\n```\r\n\r\n> ⚠️ If the `.tools` height ever changes, the subtrahend in every layout's `initTable()` (e.g. `- 76`) must change with it, otherwise every list page in the product skews at once.\r\n\r\n### 3.4 Form layout SFormLayout\r\n\r\n`.form-layout` fills with the same flex approach; `initStyle()` **only computes the footer width** (the collapses + anchor scenario must dodge the right-hand anchor) and no longer computes heights:\r\n\r\n```less\r\n.form-layout {\r\n height: 100%;\r\n overflow: hidden;\r\n :deep(.ant-spin-nested-loading),\r\n :deep(.ant-spin-container) {\r\n /* a-spin's wrappers must each fill, otherwise form-layout cannot resolve its height */\r\n height: 100%;\r\n display: flex;\r\n flex-direction: column;\r\n min-height: 0;\r\n }\r\n}\r\n.tools,\r\n.step-wrap,\r\n.tabs-wrap,\r\n.modal,\r\n.form-fixed-footer {\r\n flex: 0 0 auto;\r\n}\r\n.form-layout-main {\r\n flex: 1 1 auto;\r\n min-height: 0;\r\n overflow: hidden auto;\r\n}\r\n.form-fixed-footer {\r\n height: 60px;\r\n}\r\n```\r\n\r\n### 3.5 Uniform left tree container height (`.s-side-tree`)\r\n\r\nThe `.side` of `SListLayout` / `SListTableTreeLayout` / `SListCardLayout` all carry `padding: 10px 0`, so the tree container height must equal \"`.side` box height − top/bottom padding\", otherwise you get double scrollbars or a clipped tree.\r\n\r\nThe rule lives in the **global** `packages/style/common.less` under `.s-side-tree` (a unique extra class on `.side`, so a generic name cannot be overridden by business styles); writing a copy inside a business page's scoped style is **forbidden**. It covers two tree sources:\r\n\r\n- ① a standard `<s-tree>`: the root is `.s-tree-common`, `height:100%`;\r\n- ② a native `<a-spin><a-tree>`: each level is stretched (`.ant-spin-container → .ant-tree → .ant-tree-list → .ant-tree-list-holder`) and `.ant-tree-list-holder` takes `overflow-y:auto`.\r\n\r\n> ⚠️ Branch ② must start from `.s-side-tree` with `>`, **it must not be written as a descendant selector** — `STree` also renders `.ant-tree` internally and a descendant selector would hit branch ①.\r\n\r\n### 3.6 STree self-sizing and horizontal ellipsis\r\n\r\n`STree`'s `height` prop default must be `undefined` (**never a hard-coded 300**):\r\n\r\n```js\r\nheight: { type: Number, default: undefined }\r\n```\r\n\r\nReason: antd's `Tree` turns `height` into an inline `max-height:300px` on the virtual-list holder, which clips the tree and adds an inner scrollbar.\r\n\r\nHorizontal text never wraps, overflows into an ellipsis, and the width follows the parent:\r\n\r\n```less\r\n.s-tree-common {\r\n height: 100%;\r\n width: 100%;\r\n overflow-x: hidden;\r\n overflow-y: auto;\r\n}\r\n:deep(.ant-tree),\r\n:deep(.ant-tree-list),\r\n:deep(.ant-tree-list-holder),\r\n:deep(.ant-tree-list-holder-inner) {\r\n width: 100%;\r\n min-width: 0;\r\n}\r\n:deep(.ant-tree-node-content-wrapper) {\r\n min-width: 0;\r\n overflow: hidden;\r\n}\r\n:deep(.ant-tree-title),\r\n.node-title {\r\n display: block;\r\n width: 100%;\r\n overflow: hidden;\r\n white-space: nowrap;\r\n text-overflow: ellipsis;\r\n}\r\n```\r\n\r\n### 3.7 The iron rule for diagnosing rendering issues\r\n\r\n**Rendering/height problems must be measured on the real page after logging in, using puppeteer to read `offsetHeight`/`offsetLeft`/box metrics — never guess the root cause by reading code statically.**\r\n\r\n```js\r\n// measure: container height, main height, bottom bar offset, document overflow\r\nconst r = await page.evaluate(() => {\r\n const q = (s) => document.querySelector(s)\r\n const box = (s) => {\r\n const el = q(s)\r\n if (!el) return null\r\n const b = el.getBoundingClientRect()\r\n return { h: el.offsetHeight, top: Math.round(b.top), bottom: Math.round(b.bottom) }\r\n }\r\n return {\r\n container: box('.list-layout-main'),\r\n tableContent: box('.table-content'),\r\n pagination: box('.ant-table-pagination'),\r\n docOverflowY: document.documentElement.scrollHeight - document.documentElement.clientHeight\r\n }\r\n})\r\n```\r\n\r\nAcceptance criteria (all must be 0):\r\n\r\n| Metric | Pass condition |\r\n| --------------------------------------- | ------------------------------------------------- |\r\n| `documentOverflowY` | `0` (no page scrollbar) |\r\n| `pagination.bottom` minus container bottom | `0` (pagination sits exactly at the viewport bottom) |\r\n| table body overflow beyond the container | `0` |\r\n\r\nSpot-check several viewports (1920×1080 / 1600×900 / 1440×900 / 1366×768 / 1280×720 / 2560×1440); the change is only done when all of them pass.\r\n\r\n---\r\n\r\n## 4. Build and configuration\r\n\r\n### 4.1 Build and release\r\n\r\n```bash\r\nnpm run dev # base local development\r\nnpm run build # lib build + copy docs/vite-plugins/package.json into dist + git push\r\nnpm run lint\r\n```\r\n\r\n> The base build **does not drop console** (`$utils`/i18n debug output is controlled at runtime by `VITE_CONFIG_sapit-base-template`); only business builds drop it.\r\n\r\nOutput: entry `./packages/index.js`, `vue` external, output `dist/lib`, and the bundle contains the **entry dependency graph** (not the whole project); `package.json` declares `files: [\"lib\",\"docs\",\"vite-plugins\"]`.\r\n\r\n### 4.2 Configuration sources and priority\r\n\r\n```text\r\nbase defaultEnv < business web-config.js < .env.[sapit-base-template] (written into config.json at build time) < deployed config.json (runtime override)\r\n```\r\n\r\n- `web-config.js`: may hold defaults or `import.meta.env.VITE_APP_*`;\r\n- `.env` / `.env.[sapit-base-template]`: one set per environment (dev/test/uat/prod), written into `config.json` by the business `vite.config.js`;\r\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.\r\n\r\nCommon switches (the business may override them; checks use `!== false`, so an unset value keeps the base default):\r\n\r\n| Option | Default | Description |\r\n| -------------------------- | ------------------------------- | ------------------------------------------------------------------------------ |\r\n| `VITE_APP_FOOTER_VISIBLE` | `false` | Whether to show the footer |\r\n| `VITE_APP_MESSAGE_VISIBLE` | `true` | Whether to show the message bell at the top right (set `false` to hide) |\r\n| `VITE_APP_SOCKET_URL` | `ws://127.0.0.1:8080/websocket` | Message push socket address; empty or `/` means same origin; the local placeholder is skipped automatically outside a local machine |\r\n| `VITE_APP_SOCKET_PATH` | `/apig/ws/websocket` | socket.io handshake path, must match the backend |\r\n| `VITE_APP_LANG_ENABLE` | `false` | Whether internationalization is enabled |\r\n| `VITE_APP_MENU_BAR` | `left` | Menu layout: `left` / `top` |\r\n| `VITE_APP_MENU_THEME` | `dark` | Menu theme: `dark` / `light` |\r\n| `VITE_APP_MENU_BG` | `theme` | Menu background: `theme` follows the primary color / `dark` = `#001529` / `#RRGGBB` custom |\r\n| `VITE_APP_MENU_BG_LIGHTNESS` | `93` | Background lightness 0-100: higher is lighter |\r\n| `VITE_APP_MENU_BG_SATURATION` | `30` | Max saturation of the menu palette 0-100 |\r\n| `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | Share of the primary color in the selected background 0-100 |\r\n\r\nHow the top-right message badge counts: on entering the system it calls `message/center/counts` for `totalCount`, and afterwards every `wsEvent` pushed over the socket triggers a refetch. The socket connection is a singleton (`packages/utils/message-socket.js`) that emits `sendUserId` with the user id once connected, and the backend pushes per user. The business registers nothing extra — just point `VITE_APP_SOCKET_URL` / `VITE_APP_SOCKET_PATH` at the message service.\r\n\r\n### 4.3 Starting a business project (`npm start`)\r\n\r\nA business project's (`sapit-base-template`) `npm start` runs the bundled script `refresh-sapit-base-template.ps1`:\r\n\r\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`);\r\n2. `npm install` to pull the latest published `sapit-ui-plus`;\r\n3. run `npm run dev` automatically.\r\n\r\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.\r\n> This command is normally needed only when the base project has been updated.\r\n\r\n## 5. Business project integration\r\n\r\n### 5.1 Install\r\n\r\n```json\r\n{ \"dependencies\": { \"sapit-ui-plus\": \"git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git\" } }\r\n```\r\n\r\n### 5.2 Entry `main.js`\r\n\r\n```js\r\nimport { createApp } from 'vue'\r\nimport App from './App.vue'\r\nimport config from './config/web-config'\r\nimport appConfig from './config/app-config'\r\nimport SapitUiPlus from 'sapit-ui-plus'\r\nimport 'sapit-ui-plus/lib/css/style.css'\r\n\r\nasync function init() {\r\n const pages = import.meta.glob('@/views/**/*.vue')\r\n const app = createApp(App)\r\n app.use(SapitUiPlus)\r\n await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages)\r\n app.mount('#app')\r\n}\r\ninit()\r\n```\r\n\r\n- `config`: environment configuration (web-config);\r\n- `appConfig`: build-time configuration (login/home overrides, static routes, language packs) that **never enters config.json**;\r\n- `pages`: every business page, used by dynamic routing to match `hrefs`.\r\n\r\n### 5.3 Login page / home override\r\n\r\n`app-config.js`:\r\n\r\n```js\r\nexport default {\r\n components: {\r\n login: () => import('@/views/login/index.vue'),\r\n home: () => import('@/views/home/index.vue')\r\n }\r\n}\r\n```\r\n\r\nWhen not configured, the base defaults are used (`pages-components/login.vue`, `todo.vue`).\r\n\r\n### 5.4 Static pages `staticRoutes`\r\n\r\n```js\r\nexport default {\r\n staticRoutes: [\r\n {\r\n path: '/help',\r\n name: 'Help',\r\n component: () => import('@/views/help/index.vue'),\r\n meta: { title: 'Help' } // hidden: not in the menu; public: no login required\r\n }\r\n ]\r\n}\r\n```\r\n\r\n`layout: false` / `raw: true` skips `BasicLayout`; a business route with the same `path` overrides the built-in one.\r\n\r\n### 5.5 Business pages and menus\r\n\r\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.\r\n\r\n### 5.6 Internationalization / theme\r\n\r\n- i18n: put `views/<module>/i18n.js` (flat `{ '<source text>': 'English' }`) and call `this.useI18n('<module>')` in the page's `created` hook, then use `$l('<source text>')` directly. The business's own `i18n.js` files are aggregated in the business `main.js` and passed to `$registerGlobalConfig({ locales })`, which merges them with the base (business wins on duplicates).\r\n- theme: only change `VITE_APP_THEME_VALUE`; style with `var(--s-*)` or `.s-theme-*`.\r\n\r\n### 5.7 Sub-path deployment (example `/monitor/`)\r\n\r\n1. `.env`: `VITE_APP_BASE_URL=/monitor/`;\r\n2. business `vite.config.js`: `base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/'`;\r\n3. the base router base, `$push`/`$open`, `redirectLogin` and `parseAppUrl` all read that value and prefix automatically;\r\n4. nginx:\r\n\r\n```nginx\r\nlocation /monitor/ {\r\n alias /home/project/tmp/dist/;\r\n index index.html;\r\n try_files $uri $uri/ /monitor/index.html;\r\n}\r\nlocation = /monitor/config.json {\r\n alias /home/project/tmp/dist/config.json;\r\n add_header Cache-Control \"no-store\";\r\n}\r\n```\r\n\r\n> `createWebHistory` base, the Vite `base` and every `window.location` jump must all be `/monitor/` (with the trailing slash).\r\n\r\n### 5.8 Using components and permissions\r\n\r\n```html\r\n<template>\r\n <s-list-layout :columns=\"columns\" :loadData=\"page\" title=\"Example\" />\r\n <s-user-select v-model:value=\"ids\" />\r\n <a-button v-action=\"'add'\">Add</a-button>\r\n</template>\r\n```\r\n\r\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`.\r\n\r\n---\r\n\r\n### 5.9 Built-in dependencies (ready to use in a business project)\r\n\r\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`).\r\n\r\n| Dependency | Version | Purpose |\r\n| ------------------------------------------------ | ----------------- | -------------------------------------------------------------- |\r\n| `dayjs` | ^1.11.12 | Date formatting (recommended, also used inside `$utils`) |\r\n| `axios` | ^1.7.3 | Requests (wrapped as `window.$utils.http`, rarely used directly) |\r\n| `qs` | ^6.13.0 | Parameter serialization (`stringify`) |\r\n| `lodash.get` / `lodash.clonedeep` | ^4.4.2 / ^4.5.0 | Safe access / deep clone |\r\n| `crypto-js` | ^4.2.0 | Encryption / decryption |\r\n| `js-base64` | ^3.7.2 | Base64 encode/decode |\r\n| `jsencrypt` | ^3.3.2 | RSA encryption |\r\n| `moment` | ^2.30.1 | Dates (legacy compatibility; use dayjs for new code) |\r\n| `html2canvas` | ^1.4.1 | Page screenshots |\r\n| `nprogress` | ^0.2.0 | Top loading progress bar |\r\n| `@vueuse/core` | ^11.0.3 | Composition utilities |\r\n| `vue-cropper` | ^1.1.4 | Image cropping (used by SCopperUpload) |\r\n| `vuedraggable` | ^4.1.0 | Drag-and-drop sorting |\r\n| `v-clipboard` | ^3.0.0-next.1 | Copy to clipboard (`v-clipboard` directive) |\r\n| `vue-ls` | ^4.2.0 | localStorage wrapper (already exposed as `$utils.ls`) |\r\n| `jodit` | 3.24.7 | Rich text editor (SEditor) |\r\n| `less` / `less-loader` | ^4.2.0 / ^12.2.0 | Style compilation |\r\n| `vite-plugin-html` / `vite-plugin-generate-file` | ^3.2.2 / ^0.2.0 | Build plugins (generate config.json etc.) |\r\n| `@ant-design/icons-vue` | follows ant-design-vue | Icons, **all registered globally as components** |\r\n\r\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):\r\n\r\n| Dependency | Version |\r\n| ---------------- | ------- |\r\n| `vue` | ^3.4.29 |\r\n| `vue-router` | ^4.3.3 |\r\n| `pinia` | ^2.1.7 |\r\n| `vue-i18n` | ^9.14.0 |\r\n| `ant-design-vue` | 4.x |\r\n\r\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.\r\n\r\n### 5.10 Global injection (no import needed)\r\n\r\n| Name | Description |\r\n| ------------------------------------------ | ------------------------------------------------------------------------------ |\r\n| `$utils` | Utilities: `$utils.http` (requests), `$utils.ls` (local storage), `$utils.env` (config), etc. |\r\n| `$message` / `$modal` / `$notice` | ant-design-vue message / Modal / notification |\r\n| `$push` / `$open` | In-app navigation / new window (deployment base prefixed automatically) |\r\n| `$l` | i18n lookup (`$l('<source text>')`) |\r\n| `$theme` | Current theme variables; CSS variables such as `--s-color` |\r\n| `$icons` | All antd icon components |\r\n| `$socket` / `$filter` / `$pinia` / `$i18n` | websocket / filters / user store / i18n instance |\r\n| `env` | Same as `$utils.env` |\r\n| `$staticRoutes` | Static page routes (including business-defined ones) |\r\n\r\n---\r\n\r\n## 6. Caveats\r\n\r\n### 6.1 On the business side\r\n\r\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.\r\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.\r\n3. <span style=\"color:#d46b08;font-weight:700\">Sub-path</span>: keep `VITE_APP_BASE_URL` and the Vite `base` identical and trailing-slashed.\r\n4. <span style=\"color:#d46b08;font-weight:700\">Global component naming</span>: registered by file name (`SForm.vue` → `<SForm>`, not kebab-case); the later one wins on conflict.\r\n5. <span style=\"color:#d46b08;font-weight:700\">Theme / i18n</span>: defined in the base; the business only selects a theme and writes copy.\r\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`).\r\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.\r\n\r\n### 6.2 Development / build\r\n\r\n8. **Never run two `vite build` at the same time**: it reports `Rollup failed to resolve import \"sapit-ui-plus\"`, which is a false cache-conflict error; rerun serially and it recovers. If it persists serially, check whether `node_modules/sapit-ui-plus` was emptied (npm reinstall often clears it) — restore it with:\r\n\r\n ```bash\r\n # the base dist is exactly the npm package content (the build script copies package.json + docs + vite-plugins into dist)\r\n cp -r <base>/dist/lib <base>/dist/docs <base>/dist/vite-plugins <base>/dist/package.json <business>/node_modules/sapit-ui-plus/\r\n cp -r <base>/packages/sso <base>/packages/static <business>/node_modules/sapit-ui-plus/\r\n ```\r\n\r\n9. **`vite build --emptyOutDir false`**: emptying `dist` is blocked by the bulk-delete guard; use this flag when only verifying compilation, and **do not** run the `npm run build` that pushes to the internal git repository just to verify (that is a release action and needs confirmation first).\r\n10. **Never run two base builds or two business installs concurrently**, to avoid cache contamination.\r\n11. **`vite build` does not check undefined variables**: referencing a non-existent variable in a template or script still compiles. After a large edit, review added and removed lines with `git diff` and scan for unused imports to catch accidental deletions.\r\n12. **npm network in China**: `registry.npmjs.org` is basically unreachable and installing `sapit-ui-plus` stalls on the big packages (`ant-design-vue` unpacks to 78MB, `jodit` to 23MB). Use a domestic registry:\r\n\r\n ```bash\r\n npm i git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git --registry=https://registry.npmmirror.com\r\n ```\r\n\r\n If `git ls-remote` inside the npm process returns 403 (sandbox/network interception, while a manual `git ls-remote` works), temporarily remove that git dependency, install the rest, then restore it from the local base `dist` as in item 8.\r\n\r\n13. **The npm package must contain a root-level `static/`**: the lib build does not rewrite `new URL('../../static/...', import.meta.url)`, and at runtime it resolves from `lib/js/*.js` to `static/` at the package root. Without it every login-page image 404s in the business dev server while the base's own dev and production are fine — **extremely misleading**.\r\n14. **Images in the lib build**: Vite forces every asset inline for `build.lib`, so the output can contain MB-sized base64 data URIs (beyond Chrome's URL limit). `closeBundle` in `vite-plugins/sso-plugin` extracts data URIs larger than 100KB into real files under `lib/img/`; always reference source assets through `import`.\r\n\r\n### 6.3 Business dictionary / form conventions (hy-monitor)\r\n\r\n15. **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}`.\r\n16. **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).\r\n17. **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=''`).\r\n18. **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`.\r\n19. **API failures navigate to the built-in error pages**: HTTP 403 (301 included) → `/403`, 404 → `/404`, swapped **inside the content-area `router-view`** (sidebar and header stay, the shell is never replaced) with no notification stacked on top. The URL carries `?api=<endpoint>&status=<original status>`, so the page switches to the API wording (403 \"no permission for this API\", 301 \"API endpoint moved\", 404 \"API not found\") and shows the endpoint; without `?api=` it stays on the page wording (no page permission / page not found). **5xx does not navigate** — it keeps the normal notification (`/500` stays available by direct URL). Background polling and other auxiliary requests can pass `{ skipErrorPage: true }` to keep the current page:\r\n\r\n ```js\r\n this.$utils.http.post('/api/msg/count', {}, { skipErrorPage: true })\r\n ```\r\n\r\n---\r\n\r\n## 7. Global method quick reference\r\n\r\n| Call | Purpose |\r\n| --------------------------------------------------------- | ------------------------------------------------ |\r\n| `$l('<source text>'[, key])` | Internationalization |\r\n| `$push(path, query)` / `$open(path, query)` | Navigate / open a new window (base prefixed) |\r\n| `$message.*` / `$modal.*` / `$notice.*` / `$confirm(...)` | Toast / modal / notification / confirm dialog |\r\n| `this.$utils.ls.get/set/clear` | Local storage |\r\n| `this.$utils.http(config)` | Send a request (POST by default) |\r\n| `$filter.dateFormat(v, fmt)` | Date formatting |\r\n| `v-action:code` | Button-level permission (exact `button_code` match) |\r\n| `$utils.hasAction(code)` | Button-level permission (functional, supports OR / AND) |\r\n| `$utils.iconOf('info-circle')` | Legacy antd v1 `type` name → icon component |\r\n| `$utils.messageFormat(str, values)` | `{0}` / `{name}` placeholder substitution |\r\n| `$utils.filterSelectOption(iv, opt)` | antd4-ready select filter |\r\n| `$utils.randomDrawerPlacement()` | Random drawer direction |\r\n| `var(--s-color)` / `.s-theme-color` | Theme color (CSS variable / utility class) |\r\n\r\n---\r\n\r\n## 8. Online documentation entry\r\n\r\n| Address | Content |\r\n| ------------------- | ---------------------------------------------------------------- |\r\n| `<base>/docs` | This guide |\r\n| `<base>/components` | s components (built-in components: left menu + preview + source) |\r\n\r\n\r\n", $ = () => {
  85. var r, n;
  86. try {
  87. return ((n = (r = window.$utils) == null ? void 0 : r.ls) == null ? void 0 : n.get("lang")) === "en";
  88. } catch (i) {
  89. return !1;
  90. }
  91. }, C = {
  92. name: "DocsPage",
  93. data() {
  94. return {
  95. html: ""
  96. };
  97. },
  98. mounted() {
  99. this.render();
  100. },
  101. methods: {
  102. render() {
  103. this.html = S($() ? j : A);
  104. }
  105. }
  106. }, L = { class: "s-docs-page" }, B = { class: "docs-header" }, U = { class: "brand" }, M = { class: "nav" }, R = ["innerHTML"];
  107. function V(r, n, i, e, t, o) {
  108. const s = k("router-link");
  109. return _(), T("div", L, [
  110. p("header", B, [
  111. p("div", U, [
  112. n[0] || (n[0] = p("span", { class: "logo" }, "S", -1)),
  113. m(" " + g(r.$l("sapit-ui 文档")), 1)
  114. ]),
  115. p("nav", M, [
  116. y(s, {
  117. class: "nav-item active",
  118. to: "/docs"
  119. }, {
  120. default: v(() => [
  121. m(g(r.$l("说明文档")), 1)
  122. ]),
  123. _: 1
  124. }),
  125. y(s, {
  126. class: "nav-item",
  127. to: "/components"
  128. }, {
  129. default: v(() => [
  130. m(g(r.$l("s组件")), 1)
  131. ]),
  132. _: 1
  133. })
  134. ])
  135. ]),
  136. p("div", {
  137. class: "docs-body",
  138. innerHTML: t.html
  139. }, null, 8, R)
  140. ]);
  141. }
  142. const D = /* @__PURE__ */ P(C, [["render", V], ["__scopeId", "data-v-d2a8495e"]]);
  143. export {
  144. D as default
  145. };