# sapit-ui base framework guide and business usage > Applies to: sapit-ui-framework (the base / sources), sapit-ui-plus (published artifact), sapit-base-template (business sample). > > This document is also the data source of the built-in `/docs` page and the `/components` page. > > Prop defaults in the base source are written in Chinese and translated at render time, so the tables below show their English rendering. --- ## Contents - [1. Overview](#docs-1Overview) - [2. What the base provides](#docs-2Whatthebaseprovides) - [3. Layout and height rules](#docs-3Layoutandheightrules) - [4. Build and configuration](#docs-4Buildandconfiguration) - [5. Business project integration](#docs-5Businessprojectintegration) - [6. Caveats](#docs-6Caveats) - [7. Global method quick reference](#docs-7Globalmethodquickreference) - [8. Online documentation entry](#docs-8Onlinedocumentationentry) --- ## 1. Overview ### 1.1 The five pieces | Project | Role | Description | | --------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- | | `sapit-ui-framework` | Base (sources) | Library project holding the built-in components and common dependencies, packed in Vite lib mode | | `sapit-ui-plus` | Published artifact | The git repository that receives the base `dist` (`lib/`, `docs/`, `vite-plugins/`) | | `sapit-base-template` | Business consumer | Builds business pages and configuration on top of the `sapit-ui-plus` git dependency | ```text sapit-ui-framework --(npm run build)--> dist/lib --(git push)--> sapit-ui-plus(git) --> sapit-base-template ``` ### 1.2 Directory structure (base) ```text sapit-ui-framework/ ├─ packages/ # published content source (entry dependency graph) │ ├─ index.js # library entry, exports registerGlobalConfig │ ├─ components/ # built-in S* components │ ├─ layouts/ # BasicLayout / BlankLayout / UserLayout / RouteView / PageView │ ├─ router/ # constant routes + dynamic routes + static routes + guards │ ├─ store/ api/ utils/ locales/ static/ style/ │ └─ pages-components/ # login, workplace, todo, message, 404/403/500, docs pages ├─ docs/ # this document (rendered by the built-in /docs) ├─ vite-plugins/ # docs-viewer plugin ├─ src/ # the base's own debug shell └─ vite.config.js / package.json ``` --- ## 2. What the base provides ### 2.1 Global components `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. ``, ``). | Category | Components | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Layout | `SSkeletonLayout` (skeleton layout: title + button group + content, see 2.16), `SListLayout`, `SListCardLayout`, `SListTableTreeLayout`, `SSuperListLayout`, `SFormLayout`, `SPanelLayout`, `SCollapses`/`SCollapsesItem`, `SDrawer` | | Overlay | `SModal`, `SModalTemplate`, `ModalHeader`, `SIconModal`, `SImportModal` (bulk import, see 2.11) | | 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) | | Upload | `SFileUpload`, `SDraggerUpload`, `SCopperUpload`, `CropperModal` | | Display / others | `SEditor`, `SEmpty`, `SIcon`, `SSvg`, `SAnchor`, `SColorPicker`, `SToggleLanguage`, `SettingFilter`, `SettingColumns`, `SSideMenu`/`STopMenu` | > 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). > > Registration rule: `components/**/*.vue` is registered globally **by file name** (`SForm.vue` → ``, **not kebab-case**); the later one wins on conflict. > `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` (`` works without any import). > All `@ant-design/icons-vue` icons are registered globally and exposed as `$icons`. > Some helper components are internal only: `ModalHeader` (SModal), `CropperModal` (SCopperUpload), `CustomInput`/`SettingColumns`/`SettingFilter` (SSuperListLayout). ### 2.1.1 Choosing a layout component | Scenario | Use | | --------------------------------------- | -------------------------------------------------------------------------------------- | | Title + buttons + custom content (no table / pagination / form) | `SSkeletonLayout` (see 2.16, ships with a title bar and permission-aware buttons) | | Ordinary list page | `SListLayout` | | Card list | `SListCardLayout` | | List + left tree | `SListTableTreeLayout` (the left tree container class must be `.side.s-side-tree`, see 3.5) | | List with advanced search / table | `SSuperListLayout` | | Add / edit / detail (routed) | `SFormLayout` (`#form` slot holds `SForm`; `#footer-callback` receives `save`/`cancel`/`prev`/`next`) | | Form as modal content | `SModal` (do not nest `SFormLayout`) | | Dynamic form driven by backend fields | `SExtendFieldsForm` (`data` + `defaultValue`; the ref exposes `validate/clearValidate/getModel`) | | Data-permission scope selection | `SDataRangeTreeSelect` (`autoSysConfig` manages the system `dataScope` config) | ### 2.2 Global properties / methods Available after `$registerGlobalConfig` runs (`this.$xxx` / `$xxx` in templates / `window.$xxx`): | Name | Description | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `$registerGlobalConfig(config, pages)` | Initialization entry (see 5.2) | | `$utils` | Utility collection: `$utils.env` / `$utils.ls` / `$utils.http` plus general helpers | | `env` | Merged environment configuration (= `$utils.env`) | | `$i18n` / `$l(name, key)` | Internationalization (see 2.7). Lives on `globalProperties`: usable **directly in templates** as `$l('xx')`; inside ` ``` | props | Type | Default | Description | | ------------ | --------------- | ---------------- | ------------------------------------------------------------------------ | | `value` | Boolean | `false` | Visibility (`v-model:value`) | | `title` | String | `Bulk import` | Modal title | | `width` | String / Number | `1000` | Modal width | | `uploadUrl` | String | `''` | Upload endpoint (full gateway address, e.g. `/monitor/DeviceInfo/Uploader`) | | `columns` | Array | `[]` | Preview / result table columns `[{ title, dataIndex, width }]` | | `apis` | Object | `{}` | The four import APIs (see below) | | `typeSelect` | Object | `null` | `{ options, placeholder, loading }`; omit when no business parameter is needed | | `extraKey` | String | `'deviceTypeId'` | Field name used to submit the `typeSelect` value | | events | Description | | -------------- | -------------------------------------------------- | | `update:value` | Visibility change (`v-model`) | | `reload` | List must be refreshed after a successful import / close | | methods (via ref) | Description | | ----------------- | ------------------------------------ | | `show()` | Open the modal and reset its state | API contract (all return a Promise; the component accepts both `{ code, data }` and plain data): | API | Input | Output | | --------------------- | ------------------------------ | ---------------------------------------------------- | | `templateDownload` | `{ ...extraParams }` | `{ url }` (the component triggers the download) | | `importPreview` | `{ fileName, ...extra }` | `{ dataRow: [] }` | | `importData` | `{ list, ...extra }` | `{ resultType, snum, fnum, failResult: [] }` | | `exportExceptionData` | `{ list, ...extra }` | `{ url }` | | Upload (internal) | `FormData(file)` → `uploadUrl` | `{ name }` / `{ fileName }` (later APIs receive fileName) | > ⚠️ `SImportModal` is **three-step** (upload → preview/edit → result/exception export). > 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`), > 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. ### 2.12 SDataRangeTreeSelect — data permission scope tree Selects a data permission scope (organization / campus / unit); internally calls `findOfficeList` / `getOfficeByIds` / `getSysConfigByCode('dataScope')`. ```vue ``` Common 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`. events: `update:value`, `change` (both emit an **array of ids**). > ⚠️ The template hard-codes `label-in-value` + `tree-check-strictly`, so antd requires `value` to be an array of `{ label, value }` objects. > 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. ### 2.13 SExtendFieldsForm — dynamic extra field form The backend delivers field configuration (`fillModeConfig` is a JSON string containing `showType` / `config`) and the front end renders from it. ```vue ``` | props | Type | Default | Description | | -------------- | ------ | ------- | ---------------------------------------------------- | | `data` | Array | `[]` | Field definitions (`fieldCode/fieldName/fillModeConfig`) | | `type` | String | `'add'` | `add` / `edit` / `view` (`view` skips validation) | | `defaultValue` | Array | `[]` | Values echoed in edit mode `[ { fieldCode, value } ]` | | `cols` | Number | `2` | Columns per row (non-full-width fields take `100/cols%`) | | `labelWidth` | String | `auto'` | Label width | `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. ### 2.14 SChooseUser — user picker modal (with data permission) Modal 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.** How it differs from `SUserSelect` (the criteria for choosing between them): | Aspect | `SUserSelect` | `SChooseUser` | | ----------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Shape | Read-only input plus an integrated modal | Pure modal; visibility controlled by the business | | Data permission | Tree / list APIs carry no data permission | Uses `levelOneChildrenWithAuth` / `levelTwoChildrenWithAuth` / `findUsersWithAuth`, **filtered by the logged-in user's permission** | | User type | No filter | Built-in staff / student / external filter | | 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** | ```vue ``` | props | Type | Default | Description | | ------------------- | ------- | --------------------------------- | ----------------------------------------------------------------------------- | | `value` | Boolean | `false` | Modal visibility (`v-model:value`) | | `title` | String | `Select users` | Modal title | | `multiple` | Boolean | `false` | Multiple selection (the selected list appears on the right) | | `searchPlaceholder` | String | `Search by name, employee/student number or phone` | Search box placeholder | | `required` | Boolean | `false` | When nothing is selected, confirming warns and does not close | | `selectedIds` | Array | `[]` | Echoed id array for multi-select (`v-model:selectedIds`); `getBUseryIds` loads objects | | `selectedId` | String | `''` | Echoed id for single select (`v-model:selectedId`); `getUserById` loads the object | | events | Description | | -------------------- | ------------------------------------------------------------------------ | | `update:value` | Modal closed (both confirm and cancel set it to `false`, no manual close needed) | | `update:selectedIds` | Two-way binding of the selected id array | | `update:selectedId` | Selected id in single-select mode | | `callback` | On confirm emits the selected objects **array**; nothing on close | > ⚠️ 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). ### 2.15 SBelowChoosePosition — position picker modal Modal **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. How 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). ```vue ``` The props match `SChooseUser` (`title` defaults to `Select position`, `searchPlaceholder` to `Search by position name or code`), plus one component-specific prop: | props | Type | Default | Description | | -------- | ------ | ------- | -------------------------------------------------------------------------- | | `rootId` | String | `''` | Left tree root id, which defines the data scope; changing it reloads the tree, `'-1'` is used when omitted | | methods (via ref) | Description | | ---------------------- | ------------------------------ | | `initLeftTreeData(id)` | Manually reload the left tree | | events | Description | | -------------------- | -------------------------------------------------------------------------- | | `update:value` | Set to `false` only on cancel; **confirm does not close the modal** | | `update:selectedIds` | Two-way binding of the selected position ids (echo uses `getPositionByIds`) | | `update:selectedId` | Single-select id (echo uses `getPositionById`) | | `callback` | Confirm emits `{ selectedList }` / `{ selected }`; close emits `false` | > ⚠️ 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. --- ### 2.16 SSkeletonLayout — skeleton layout (title + button group + content) > 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. ```vue
...
``` | props | Type | Default | Description | | --------- | ------ | ------- | -------------------------------------------------- | | `title` | String | — | **Required** title bar text | | `buttons` | Array | `[]` | Button config array, see below | | `bgColor` | String | `''` | Root background colour | Each `buttons` item: | Field | Type | Description | | ---------- | ----------------- | ---------------------------------------------------------------------------------------------------- | | `key` | String | Unique key, emitted on click; `'add'` makes the button `primary` by default | | `name` | String | Button label (passed through `$l`, so the source Chinese text is fine) | | `icon` | String \| Boolean | String = icon component name (e.g. `'PlusOutlined'`); `true` = look up the built-in iconMap by `key`; omit for no icon | | `action` | String | `v-action` permission code, defaults to `key` (real permission filtering — unauthorised buttons are removed) | | `show` | Boolean | Default `true`; `false` hides via `v-show` (keeps layout, still permission-registered) | | `disabled` | Boolean | Greyed out | | `type` | String | Overrides `a-button`'s `type` | | slots | Description | | ----------- | ---------------------------------------- | | default | Content area (`.skeleton-layout-main`) | | `otherBtns` | Appended to the right of the button group | | `other` | Bottom area | | events | Description | | ------------- | ------------------------------------------- | | `btnCallback` | Emits the clicked button's `key` | | methods (via ref) | Description | | -------------------- | ----------------------------------------------------------------- | | — | **None.** Height is allocated by flex; no method call is needed (see below) | Built-in iconMap keys: `add` / `edit` / `delete` / `remove` / `import` / `export` / `assign` / `execute` / `pause` / `resume` / `approve` / `setting` / `TopOfType` / `TOP` / `synchronize`. > **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. > > 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. > > 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`). --- ### 2.17 Error pages (301 / 403 / 404 / 500) The 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. | Path | Component | Status sources | Accent | | --- | --- | --- | --- | | `/403` | `pages-components/403.vue` | API 403 (no permission), API 301 (address changed), page without permission | Orange `#fa8c16` | | `/404` | `pages-components/404.vue` | No route matched (catch-all `/:pathMatch(.*)*`), API 404 | Primary color `var(--s-color)` | | `/500` | `pages-components/500.vue` | Reachable directly only; **API 5xx does not redirect**, it still shows a notification | Red `#f5222d` | **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. **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. **API status mapping** (`packages/utils/request.js`): | HTTP status | Behaviour | Target URL | | --- | --- | --- | | 301 | Go to the 403 page with the "API address changed" wording | `/403?api=&status=301&from=` | | 403 | Go to the 403 page with the "no API permission" wording | `/403?api=&status=403&from=` | | 404 | Go to the 404 page with the "API does not exist" wording | `/404?api=&status=404&from=` | | Anything else (incl. 5xx) | **No redirect**, a notification is shown as before | — | **Query parameters**: | Parameter | Meaning | | --- | --- | | `api` | Failing API address. **Its presence switches to the API wording**; page-level failures omit it | | `status` | Original status code; `301` gets its own "API address changed" wording | | `from` | Source page address (with `VITE_APP_BASE_URL` stripped), rendered as the "source address" line | Wording matrix: | Source | 403 page | 404 page | | --- | --- | --- | | Page (no `api`) | Insufficient page permission | Page not found | | API (with `api`) | No API permission | API does not exist | | API 301 | API address changed | — | The 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. **Skipping the redirect** (polling, auxiliary requests — keeps one failing side request from taking over the whole page): ```js // the third argument accepts { skipErrorPage: true } (also readable from the request meta) window.$utils.http.post(url, data, { skipErrorPage: true }) ``` **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. **Changing colors / wording**: - All wording lives in i18n entries (`packages/pages-components/i18n.js`, namespace `pages-components`). - 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`. - 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. > 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. ### 2.18 Menu palette (side / top) Menu 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. | Part | CSS variable | Derivation | | --- | --- | --- | | Top-level background | `--s-menu-bg` | Primary hue + capped saturation + configured lightness | | Submenu panel | `--s-menu-sub-bg` | Same hue, one step lighter than the top level | | Hovered item | `--s-menu-hover-bg` | Same hue, 6 lightness points darker than the top level | | Selected item | `--s-menu-active-bg` | Primary blended with white, ratio driven by `VITE_APP_MENU_BG_ACTIVE_MIX` | | Normal text | `--s-menu-text` | Solved against the background for a contrast ratio >= 4.6 | | Hover / selected text | `--s-menu-text-hover`, `--s-menu-text-active` | Same rule | Config (defaults in `packages/config/web-config.js`; overridable from the business `.env` or the deployed `config.json`): | Config | Default | Description | | --- | --- | --- | | `VITE_APP_MENU_BG` | `theme` | `theme` follows the primary color / `dark` = antd `#001529` / `#RRGGBB` uses that color | | `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** | | `VITE_APP_MENU_BG_SATURATION` | `30` | Max saturation 0-100: lower is closer to grey, `0` gives pure grey | | `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | Share of the primary color in the selected background, 0-100 | | `VITE_APP_MENU_THEME` | `dark` | Menu appearance; the text color actually follows the **background luminance**, not this value alone | | `VITE_APP_MENU_BAR` | `left` | `left` sidebar / `top` top bar; both share the same palette | **Per-part color overrides** (for when a derived color is not what you want; leave empty to keep deriving, regardless of what `VITE_APP_MENU_BG` is set to — valid for `theme` / `dark` / custom colors alike): | Config | Default | Part overridden | CSS variable | | --- | --- | --- | --- | | `VITE_APP_MENU_SUB_BG` | empty | Submenu panel background | `--s-menu-sub-bg` | | `VITE_APP_MENU_HOVER_BG` | empty | Hovered item background | `--s-menu-hover-bg` | | `VITE_APP_MENU_ACTIVE_BG` | empty | Selected item background | `--s-menu-active-bg` | | `VITE_APP_MENU_TEXT` | empty | Normal text | `--s-menu-text` | | `VITE_APP_MENU_TEXT_HOVER` | empty | Hover text | `--s-menu-text-hover` | | `VITE_APP_MENU_TEXT_ACTIVE` | empty | Selected text | `--s-menu-text-active`, `--s-menu-active-text` | | `VITE_APP_MENU_GROUP_TITLE` | empty | Group title text | `groupTitle` in the returned object | - Values accept `#RGB` / `#RRGGBB` / `rgb()` / `rgba()` and are normalised to solid `#rrggbb` — an `rgba()` input has its **alpha dropped**, keeping the palette alpha-free. - An invalid value logs a `[menu] VITE_APP_MENU_XXX ...` warning and is ignored; the remaining overrides still apply, so one typo cannot break the whole menu. - Overrides are applied **before** the antd `Menu` tokens and the `:root` CSS variables are produced, so tokens, CSS variables and components all see the final values. Default palettes per theme (lightness 93 / saturation 30 / active mix 16, measured): | Theme | Top-level | Submenu | Hover | Selected | Text | | --- | --- | --- | --- | --- | --- | | blue | `#e8ecf3` | `#f5f7fa` | `#d4dce8` | `#dae9ff` | `#344051` | | green | `#ebf3e8` | `#f7faf5` | `#dbe8d4` | `#e3f6da` | `#3d5134` | | orange | `#f3ede8` | `#faf7f5` | `#e8ded4` | `#feedda` | `#514334` | | red | `#f3e8e8` | `#faf5f5` | `#e8d4d5` | `#fddcdd` | `#513435` | | purple | `#ece8f3` | `#f7f5fa` | `#dcd4e8` | `#e8def8` | `#403451` | | cyan | `#e8f3f3` | `#f5fafa` | `#d4e8e8` | `#d9f5f5` | `#345151` | Common tweaks: ```js // business web-config.js / deployed config.json VITE_APP_MENU_BG_LIGHTNESS: 97, // 1) lighter (100 is near white) VITE_APP_MENU_BG_SATURATION: 0, // 2) drop the tint entirely, pure grey VITE_APP_MENU_BG_ACTIVE_MIX: 30, // 3) a more prominent selected item VITE_APP_MENU_BG: 'dark', // 4) back to the classic antd #001529 VITE_APP_MENU_BG: '#213045' // 5) pin a custom color, no longer theme-driven // 6) custom background + a fully custom palette: give the colors you do not want derived VITE_APP_MENU_BG: '#213045', VITE_APP_MENU_SUB_BG: '#1b2637', VITE_APP_MENU_HOVER_BG: '#2a3b52', VITE_APP_MENU_ACTIVE_BG: '#2b6cd4', VITE_APP_MENU_TEXT: '#c9d4e2', VITE_APP_MENU_TEXT_HOVER: '#ffffff', VITE_APP_MENU_TEXT_ACTIVE: '#ffffff', VITE_APP_MENU_GROUP_TITLE: '#8fa3bd' ``` > Overriding only one or two parts is fine (for example only `VITE_APP_MENU_TEXT`, the rest stays derived); an empty string, a missing key or an invalid value all mean "do not override". > Notes > > 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; if a derived color is not what you want, override it with the 7 `VITE_APP_MENU_XXX` keys above — overrides always win. > 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`. > 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. > 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). ## 3. Layout and height rules > 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. ### 3.1 Heights: prefer CSS flex fill; when dynamic calculation is needed, follow the three constraints > **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. **The wrong way** (both `SListLayout` and `SFormLayout` did this early on): ```js // ❌ compute the main area height by subtracting offsetHeight values this.layoutHeight = this.$refs.layout.offsetHeight - toolsH - footerH - tabsH - 16 ``` Why 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: - with less than a full page of data the pagination floats in the middle, leaving 15–588px of empty space at the bottom; - the table/form area overflows its container by 1–N px, adding an extra page scrollbar; - changing one magic number (e.g. `tpH = 103`) skews every other page. **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. **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: 1. **One place only**: a single `calcXxxHeight()` per layout, never a magic number per page 2. **Follow the container**: recalculate with `ResizeObserver` on the parent container, not just `window.resize` 3. **Never read `$parent.$el`**: it breaks as soon as the parent DOM changes — use a `ref` on your own container **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). ### 3.2 The table fill chain (what keeps pagination pinned to the bottom) `STable`'s body gets its remaining height through flex, and **a single missing level in the chain prevents the fill**: ```less .table-content { flex: 1; display: flex; flex-direction: column; min-height: 0; } .tabs-wrap { flex: 0 0 auto; } .table-container { flex: 1 1 auto; min-height: 0; display: flex; flex-direction: column; } .table-wrapper { flex: 1 1 auto; ...; } /* STable's root node — omit it and the whole chain breaks */ .ant-table-wrapper { flex: 1 1 auto; ...; } .ant-spin-nested-loading .ant-spin-container .ant-table .ant-table-container { margin-left: 10px; } /* indent the table with margin, not padding */ .ant-table-header { flex: 0 0 auto; } .ant-table-body { flex: 1 1 auto; min-height: 0; max-height: none !important; } .ant-table-pagination { margin-bottom: 0; flex: 0 0 auto; } /* one margin off is a 15–16px gap */ ``` Key points: 1. **`.table-wrapper` must not be missed** — it is `STable`'s root node; measurement shows the body will not fill without it; 2. the `max-height` written by `scroll.y` must be overridden with `none !important`, otherwise it fights flex; 3. pagination needs `margin-bottom: 0`, otherwise a permanent margin separates it from the container edge; 4. indent the table with `:deep(.ant-table-container){margin-left:10px}`, **never** `padding-left` (it distorts the body width calculation). ### 3.3 The `.tools` header bar is uniformly 60px Every layout's `.tools` (title + button bar) is: ```less .tools { height: 60px; display: flex; justify-content: space-between; align-items: center; padding: 0 16px; box-sizing: border-box; border-bottom: 1px solid #f0f2f5; } .list-filter-wrap { padding: 10px 16px; box-sizing: border-box; } ``` > ⚠️ 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. ### 3.4 Form layout SFormLayout `.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: ```less .form-layout { height: 100%; overflow: hidden; :deep(.ant-spin-nested-loading), :deep(.ant-spin-container) { /* a-spin's wrappers must each fill, otherwise form-layout cannot resolve its height */ height: 100%; display: flex; flex-direction: column; min-height: 0; } } .tools, .step-wrap, .tabs-wrap, .modal, .form-fixed-footer { flex: 0 0 auto; } .form-layout-main { flex: 1 1 auto; min-height: 0; overflow: hidden auto; } .form-fixed-footer { height: 60px; } ``` ### 3.5 Uniform left tree container height (`.s-side-tree`) The `.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. The rule lives in the **global** `packages/style/tree.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: - ① a standard ``: the root is `.s-tree-common`, `height:100%`; - ② a native ``: 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`. > ⚠️ 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 ①. ### 3.6 STree self-sizing and horizontal ellipsis `STree`'s `height` prop default must be `undefined` (**never a hard-coded 300**): ```js height: { type: Number, default: undefined } ``` Reason: 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. Horizontal text never wraps, overflows into an ellipsis, and the width follows the parent — these structural rules now live in one place, `packages/style/tree.less`. **Components and business pages must not keep scoped copies**: ```less /* packages/style/tree.less (excerpt) */ .s-tree-common { height: 100%; width: 100%; overflow-x: hidden; overflow-y: auto; } .ant-tree, .ant-tree-list, .ant-tree-list-holder, .ant-tree-list-holder-inner { width: 100%; min-width: 0; } .ant-tree-node-content-wrapper { min-width: 0; overflow: hidden; } .ant-tree-title, .ant-tree-title > .node-title { display: block; width: 100%; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; } ``` > `.node-title` is a generic class name, so the global rule is scoped to `.ant-tree-title > .node-title` and cannot leak into business code. ### 3.7 Unified tree style file and theme variables (`packages/style/tree.less`) All tree styles live in that single file, pulled in by `common.less` via `@import './tree.less'`. The rules previously spread over `STree.vue` (scoped), `SBelowChoosePosition.vue` (scoped copy) and `common.less` (global) have all been folded in. Covered tree types: | Type | Selector root | Used by | | ----------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------ | | Directory / plain tree (`a-directory-tree`, `a-tree`) | `.s-tree-common`, `.ant-tree*` | `STree`, `SBelowChoosePosition`, native `` in business pages | | Tree-select dropdown (`a-tree-select`) | `.s-tree-select-popup` | `STreeSelect`, `SDataRangeTreeSelect` (`popup-class-name`) | | Sidebar tree container height | `.s-side-tree` | `SListLayout` / `SListTableTreeLayout` / `SListCardLayout` | Every colour and size is a `--s-tree-*` variable; the defaults equal the previous hard-coded values, so the visuals are unchanged: | Variable | Default | Meaning | | ----------------------------------- | ------------------------- | ---------------------------------------------------- | | `--s-tree-node-height` | `30px` | Node row height (dropdown uses it too) | | `--s-tree-node-line-height` | `32px` | Tree title line height | | `--s-tree-node-padding-x` | `4px` | Dropdown node horizontal padding | | `--s-tree-row-gap` | `4px` | Row gap (leaves a seam in the row background) | | `--s-tree-node-radius` | `8px` | Row corner radius (hover + selected, painted on `::before`) | | `--s-tree-switcher-color` | `#000000a6` | Expand arrow colour | | `--s-tree-hover-bg` | `rgba(0,0,0,.04)` | Row hover background | | `--s-tree-selected-bg` | `var(--s-color, #1677ff)` | Selected row background, **already follows the theme primary colour** | | `--s-tree-selected-text` | `#fff` | Selected row text / arrow colour | | `--s-tree-directory-selected-bg` | `#bae7ff` | Directory-tree selected row (antd blue-2) | | `--s-tree-directory-selected-text` | `#000000a6` | Directory-tree selected text colour | | `--s-tree-icon-color` | `#fff` | Node type icon glyph colour | | `--s-tree-icon-bg` | `transparent` | Default node icon background | | `--s-tree-icon-bg-g` / `-c` / `-d` | `#a9a9f5` / `#d3b403` / `#f09191` | Node icon G/C/D backgrounds | Override per theme instead of touching the components: ```css /* pure CSS theme: the base already puts theme-xxx on body (see 2.8) */ body.theme-green { --s-tree-selected-bg: #00b96b; --s-tree-directory-selected-bg: #d9f7e9; --s-tree-directory-selected-text: #1f1f1f; } /* global size tweak */ :root { --s-tree-node-height: 32px; --s-tree-row-gap: 6px; } ``` Two caveats: 1. `--s-tree-selected-bg` defaults to `var(--s-color, #1677ff)`, so it follows the theme primary colour automatically; the light variant `--s-tree-directory-selected-bg` still defaults to antd blue-2 — override it explicitly if it should follow. 2. Variables hold a colour/length only, never a whole declaration (e.g. `--x: background:red`). ### 3.8 The iron rule for diagnosing rendering issues **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.** ```js // measure: container height, main height, bottom bar offset, document overflow const r = await page.evaluate(() => { const q = (s) => document.querySelector(s) const box = (s) => { const el = q(s) if (!el) return null const b = el.getBoundingClientRect() return { h: el.offsetHeight, top: Math.round(b.top), bottom: Math.round(b.bottom) } } return { container: box('.list-layout-main'), tableContent: box('.table-content'), pagination: box('.ant-table-pagination'), docOverflowY: document.documentElement.scrollHeight - document.documentElement.clientHeight } }) ``` Acceptance criteria (all must be 0): | Metric | Pass condition | | --------------------------------------- | ------------------------------------------------- | | `documentOverflowY` | `0` (no page scrollbar) | | `pagination.bottom` minus container bottom | `0` (pagination sits exactly at the viewport bottom) | | table body overflow beyond the container | `0` | Spot-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. --- ## 4. Build and configuration ### 4.1 Build and release ```bash npm run dev # base local development npm run build # lib build + copy docs/vite-plugins/package.json into dist + git push npm run lint ``` > 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. Output: 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"]`. ### 4.2 Configuration sources and priority ```text base defaultEnv < business web-config.js < .env.[sapit-base-template] (written into config.json at build time) < deployed config.json (runtime override) ``` - `web-config.js`: may hold defaults or `import.meta.env.VITE_APP_*`; - `.env` / `.env.[sapit-base-template]`: one set per environment (dev/test/uat/prod), written into `config.json` by the business `vite.config.js`; - `config.json`: at the site root (or `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. Common switches (the business may override them; checks use `!== false`, so an unset value keeps the base default): | Option | Default | Description | | -------------------------- | ------------------------------- | ------------------------------------------------------------------------------ | | `VITE_APP_FOOTER_VISIBLE` | `false` | Whether to show the footer | | `VITE_APP_MESSAGE_VISIBLE` | `true` | Whether to show the message bell at the top right (set `false` to hide) | | `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 | | `VITE_APP_SOCKET_PATH` | `/apig/ws/websocket` | socket.io handshake path, must match the backend | | `VITE_APP_LANG_ENABLE` | `false` | Whether internationalization is enabled | | `VITE_APP_MENU_BAR` | `left` | Menu layout: `left` / `top` | | `VITE_APP_MENU_THEME` | `dark` | Menu theme: `dark` / `light` | | `VITE_APP_MENU_BG` | `theme` | Menu background: `theme` follows the primary color / `dark` = `#001529` / `#RRGGBB` custom | | `VITE_APP_MENU_BG_LIGHTNESS` | `93` | Background lightness 0-100: higher is lighter | | `VITE_APP_MENU_BG_SATURATION` | `30` | Max saturation of the menu palette 0-100 | | `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | Share of the primary color in the selected background 0-100 | | `VITE_APP_MENU_SUB_BG` | empty | Submenu panel background; empty = derived from the primary color (see 2.18) | | `VITE_APP_MENU_HOVER_BG` | empty | Hovered item background; empty = derived | | `VITE_APP_MENU_ACTIVE_BG` | empty | Selected item background; empty = derived | | `VITE_APP_MENU_TEXT` | empty | Normal text color; empty = derived from the background | | `VITE_APP_MENU_TEXT_HOVER` | empty | Hover text color; empty = derived from the background | | `VITE_APP_MENU_TEXT_ACTIVE` | empty | Selected text color; empty = derived from the background | | `VITE_APP_MENU_GROUP_TITLE` | empty | Group title color; empty = derived from the background | How 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. ### 4.3 Starting a business project (`npm start`) A business project's (`sapit-base-template`) `npm start` runs the bundled script `refresh-sapit-base-template.ps1`: 1. 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`); 2. `npm install` to pull the latest published `sapit-ui-plus`; 3. run `npm run dev` automatically. > 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. > This command is normally needed only when the base project has been updated. ## 5. Business project integration ### 5.1 Install ```json { "dependencies": { "sapit-ui-plus": "git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git" } } ``` ### 5.2 Entry `main.js` ```js import { createApp } from 'vue' import App from './App.vue' import config from './config/web-config' import appConfig from './config/app-config' import SapitUiPlus from 'sapit-ui-plus' import 'sapit-ui-plus/lib/css/style.css' async function init() { const pages = import.meta.glob('@/views/**/*.vue') const app = createApp(App) app.use(SapitUiPlus) await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages) app.mount('#app') } init() ``` - `config`: environment configuration (web-config); - `appConfig`: build-time configuration (login/home overrides, static routes, language packs) that **never enters config.json**; - `pages`: every business page, used by dynamic routing to match `hrefs`. ### 5.3 Login page / home override `app-config.js`: ```js export default { components: { login: () => import('@/views/login/index.vue'), home: () => import('@/views/home/index.vue') } } ``` When not configured, the base defaults are used (`pages-components/login.vue`, `todo.vue`). ### 5.4 Static pages `staticRoutes` ```js export default { staticRoutes: [ { path: '/help', name: 'Help', component: () => import('@/views/help/index.vue'), meta: { title: 'Help' } // hidden: not in the menu; public: no login required } ] } ``` `layout: false` / `raw: true` skips `BasicLayout`; a business route with the same `path` overrides the built-in one. ### 5.5 Business pages and menus Backend 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. ### 5.6 Internationalization / theme - i18n: put `views//i18n.js` (flat `{ '': 'English' }`) and call `this.useI18n('')` in the page's `created` hook, then use `$l('')` 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). - theme: only change `VITE_APP_THEME_VALUE`; style with `var(--s-*)` or `.s-theme-*`. ### 5.7 Sub-path deployment (example `/monitor/`) 1. `.env`: `VITE_APP_BASE_URL=/monitor/`; 2. business `vite.config.js`: `base: getViteEnv(res.mode, 'VITE_APP_BASE_URL') || '/'`; 3. the base router base, `$push`/`$open`, `redirectLogin` and `parseAppUrl` all read that value and prefix automatically; 4. nginx: ```nginx location /monitor/ { alias /home/project/tmp/dist/; index index.html; try_files $uri $uri/ /monitor/index.html; } location = /monitor/config.json { alias /home/project/tmp/dist/config.json; add_header Cache-Control "no-store"; } ``` > `createWebHistory` base, the Vite `base` and every `window.location` jump must all be `/monitor/` (with the trailing slash). ### 5.8 Using components and permissions ```html ``` After the backend delivers `permissions` the base writes `permission`, and `v-action:xxx` controls button-level permission. Documentation is available at `/docs` and `/components`. --- ### 5.9 Built-in dependencies (ready to use in a business project) The `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`). | Dependency | Version | Purpose | | ------------------------------------------------ | ----------------- | -------------------------------------------------------------- | | `dayjs` | ^1.11.12 | Date formatting (recommended, also used inside `$utils`) | | `axios` | ^1.7.3 | Requests (wrapped as `window.$utils.http`, rarely used directly) | | `qs` | ^6.13.0 | Parameter serialization (`stringify`) | | `lodash.get` / `lodash.clonedeep` | ^4.4.2 / ^4.5.0 | Safe access / deep clone | | `crypto-js` | ^4.2.0 | Encryption / decryption | | `js-base64` | ^3.7.2 | Base64 encode/decode | | `jsencrypt` | ^3.3.2 | RSA encryption | | `moment` | ^2.30.1 | Dates (legacy compatibility; use dayjs for new code) | | `html2canvas` | ^1.4.1 | Page screenshots | | `nprogress` | ^0.2.0 | Top loading progress bar | | `@vueuse/core` | ^11.0.3 | Composition utilities | | `vue-cropper` | ^1.1.4 | Image cropping (used by SCopperUpload) | | `vuedraggable` | ^4.1.0 | Drag-and-drop sorting | | `v-clipboard` | ^3.0.0-next.1 | Copy to clipboard (`v-clipboard` directive) | | `vue-ls` | ^4.2.0 | localStorage wrapper (already exposed as `$utils.ls`) | | `jodit` | 3.24.7 | Rich text editor (SEditor) | | `less` / `less-loader` | ^4.2.0 / ^12.2.0 | Style compilation | | `vite-plugin-html` / `vite-plugin-generate-file` | ^3.2.2 / ^0.2.0 | Build plugins (generate config.json etc.) | | `@ant-design/icons-vue` | follows ant-design-vue | Icons, **all registered globally as components** | **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): | Dependency | Version | | ---------------- | ------- | | `vue` | ^3.4.29 | | `vue-router` | ^4.3.3 | | `pinia` | ^2.1.7 | | `vue-i18n` | ^9.14.0 | | `ant-design-vue` | 4.x | > 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. ### 5.10 Global injection (no import needed) | Name | Description | | ------------------------------------------ | ------------------------------------------------------------------------------ | | `$utils` | Utilities: `$utils.http` (requests), `$utils.ls` (local storage), `$utils.env` (config), etc. | | `$message` / `$modal` / `$notice` | ant-design-vue message / Modal / notification | | `$push` / `$open` | In-app navigation / new window (deployment base prefixed automatically) | | `$l` | i18n lookup (`$l('')`) | | `$theme` | Current theme variables; CSS variables such as `--s-color` | | `$icons` | All antd icon components | | `$socket` / `$filter` / `$pinia` / `$i18n` | websocket / filters / user store / i18n instance | | `env` | Same as `$utils.env` | | `$staticRoutes` | Static page routes (including business-defined ones) | --- ## 6. Caveats ### 6.1 On the business side 1. Dependencies are prebuilt artifacts: 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. 2. Lock files pin the old commit: delete `package-lock.json`, `yarn.lock` and `node_modules/.package-lock.json` before updating. 3. Sub-path: keep `VITE_APP_BASE_URL` and the Vite `base` identical and trailing-slashed. 4. Global component naming: registered by file name (`SForm.vue` → ``, not kebab-case); the later one wins on conflict. 5. Theme / i18n: defined in the base; the business only selects a theme and writes copy. 6. Deep imports into base internals are not allowed: 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`). 7. Feature parity: 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. ### 6.2 Development / build 8. **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: ```bash # the base dist is exactly the npm package content (the build script copies package.json + docs + vite-plugins into dist) cp -r /dist/lib /dist/docs /dist/vite-plugins /dist/package.json /node_modules/sapit-ui-plus/ cp -r /packages/sso /packages/static /node_modules/sapit-ui-plus/ ``` 9. **`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). 10. **Never run two base builds or two business installs concurrently**, to avoid cache contamination. 11. **`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. 12. **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: ```bash npm i git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git --registry=https://registry.npmmirror.com ``` 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. 13. **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**. 14. **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`. ### 6.3 Business dictionary / form conventions (hy-monitor) 15. **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}`. 16. **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). 17. **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=''`). 18. **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`. 19. **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=&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: ```js this.$utils.http.post('/api/msg/count', {}, { skipErrorPage: true }) ``` --- ## 7. Global method quick reference | Call | Purpose | | --------------------------------------------------------- | ------------------------------------------------ | | `$l(''[, key])` | Internationalization | | `$push(path, query)` / `$open(path, query)` | Navigate / open a new window (base prefixed) | | `$message.*` / `$modal.*` / `$notice.*` / `$confirm(...)` | Toast / modal / notification / confirm dialog | | `this.$utils.ls.get/set/clear` | Local storage | | `this.$utils.http(config)` | Send a request (POST by default) | | `$filter.dateFormat(v, fmt)` | Date formatting | | `v-action:code` | Button-level permission (exact `button_code` match) | | `$utils.hasAction(code)` | Button-level permission (functional, supports OR / AND) | | `$utils.iconOf('info-circle')` | Legacy antd v1 `type` name → icon component | | `$utils.messageFormat(str, values)` | `{0}` / `{name}` placeholder substitution | | `$utils.filterSelectOption(iv, opt)` | antd4-ready select filter | | `$utils.randomDrawerPlacement()` | Random drawer direction | | `$utils.getTableHeight()` | Legacy list table height (window − search − offset) | | `var(--s-color)` / `.s-theme-color` | Theme color (CSS variable / utility class) | --- ## 8. Online documentation entry | Address | Content | | ------------------- | ---------------------------------------------------------------- | | `/docs` | This guide | | `/components` | s components (built-in components: left menu + preview + source) |