|
|
@@ -134,6 +134,8 @@ The height chain of `BasicLayout` (**business layout components must match it**,
|
|
|
| `/docs`, `/components` | Built-in docs / component pages (`public` = no login, `hidden` = not in the menu) |
|
|
|
| `/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 |
|
|
|
|
|
|
+> Redirect rules, query parameters, wording and color overrides for the error pages are documented in [2.17 Error pages](#docs-217Errorpages301403404500).
|
|
|
+
|
|
|
**Static routes** (`staticRoutes`, independent of backend menus): see 5.4. The base ships `/docs` and `/components`.
|
|
|
|
|
|
**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).
|
|
|
@@ -219,21 +221,7 @@ How it takes effect:
|
|
|
3. **body class**: `theme-<VITE_APP_THEME_VALUE>` (e.g. `theme-blue`).
|
|
|
4. **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).
|
|
|
|
|
|
-The menu is **light by default**: the primary hue is kept, saturation capped at 30% and lightness set to 93% — the `blue` theme yields `#e8ecf3`. All four backgrounds come from one source, so tuning a single parameter changes the entire menu instead of leaving submenu/selected items dark.
|
|
|
-
|
|
|
-| Config | Default | Description |
|
|
|
-|---|---|---|
|
|
|
-| `VITE_APP_MENU_THEME` | `dark` | Menu appearance; text color still follows the actual background luminance |
|
|
|
-| `VITE_APP_MENU_BG` | `theme` | `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 0-100: lower is closer to grey |
|
|
|
-| `VITE_APP_MENU_BG_ACTIVE_MIX` | `16` | Share of the primary color in the selected item background, 0-100 |
|
|
|
-
|
|
|
-```js
|
|
|
-// business web-config.js / deployed config.json
|
|
|
-VITE_APP_MENU_BG_LIGHTNESS: 88, // raise for a lighter menu, 100 is near white
|
|
|
-VITE_APP_MENU_BG_SATURATION: 20, // lower for a greyer menu
|
|
|
-```
|
|
|
+The 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)**.
|
|
|
|
|
|
> 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.
|
|
|
|
|
|
@@ -529,6 +517,117 @@ Built-in iconMap keys: `add` / `edit` / `delete` / `remove` / `import` / `export
|
|
|
|
|
|
---
|
|
|
|
|
|
+### 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=<api>&status=301&from=<page>` |
|
|
|
+| 403 | Go to the 403 page with the "no API permission" wording | `/403?api=<api>&status=403&from=<page>` |
|
|
|
+| 404 | Go to the 404 page with the "API does not exist" wording | `/404?api=<api>&status=404&from=<page>` |
|
|
|
+| 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 |
|
|
|
+
|
|
|
+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
|
|
|
+```
|
|
|
+
|
|
|
+> 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.
|
|
|
+> 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.
|