@nocobase/app-skills 0.1.0-beta.58 → 0.1.0-beta.59
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/skills/nocobase-app-development/SKILL.md +4 -4
- package/skills/nocobase-app-development/references/frontend/references/child-routes.md +1 -1
- package/skills/nocobase-app-development/references/frontend/references/page.md +20 -25
- package/skills/nocobase-app-development/references/frontend/references/shell.md +2 -1
- package/skills/nocobase-app-development/references/frontend/references/ui-library.md +2 -2
- package/skills/nocobase-app-development/references/lifecycle-ui.md +3 -3
- package/skills/nocobase-app-development/references/lifecycle.md +1 -1
- package/skills/nocobase-app-development/references/organization/settings-page.md +8 -4
- package/skills/nocobase-app-development/references/settings-navigation.md +72 -0
- package/skills/nocobase-app-development/references/system-administration.md +4 -4
- package/skills/nocobase-app-development/references/system-settings.md +8 -4
- package/skills/nocobase-app-upgrade/SKILL.md +4 -0
- package/skills/nocobase-app-upgrade/references/notification-template-upgrade.md +12 -0
- package/skills/nocobase-app-upgrade/references/settings-navigation-upgrade.md +35 -0
package/package.json
CHANGED
|
@@ -97,9 +97,9 @@ When the application already depends on `@nocobase/app-plugin-demo-mode`, a chan
|
|
|
97
97
|
|
|
98
98
|
## Deliver system administration by default
|
|
99
99
|
|
|
100
|
-
When a user asks you to build a complete application, deliver
|
|
100
|
+
When a user asks you to build a complete application, deliver the System settings structure ([System settings navigation](references/settings-navigation.md)) and administration pages alongside the business features, unless the user explicitly excludes them or requests a narrower deliverable such as an API-only service or a prototype explicitly limited to business screens. Users do not need to request administration pages individually. Include user management and role and permission management by default. Register workflow management, background tasks and other applicable administration as module cards of the System settings home; show execution status, failures and supported recovery actions within each capability's pages, without an additional Operational monitoring group. Reuse existing pages and installed plugins, and implement missing application-owned pages. Read [system administration](references/system-administration.md) for the baseline, capability-specific pages and acceptance criteria. For a focused feature change, extend existing administration where that feature requires it.
|
|
101
101
|
|
|
102
|
-
Whenever application requirements include a process to develop, deliver its workflow management pages by default, even when the user mentions only the business process. Reuse the installed `workflow-management` UI Library block, or install it with `yes n | pnpm exec shadcn add @nocobase/workflow-management`. Follow [Lifecycle UI](references/lifecycle-ui.md) for installation, application adapters and the default layout: one Workflow management
|
|
102
|
+
Whenever application requirements include a process to develop, deliver its workflow management pages by default, even when the user mentions only the business process. Reuse the installed `workflow-management` UI Library block, or install it with `yes n | pnpm exec shadcn add @nocobase/workflow-management`. Follow [Lifecycle UI](references/lifecycle-ui.md) for installation, application adapters and the default layout: one Workflow management settings card with in-page Definitions and Executions tabs, definition diagrams with visible parameter forms, and execution details with history and effects. The two tab views use URL-backed child routes without sidebar `navigation`. Extend an existing management area rather than adding a duplicate. Follow the scope exceptions in [system administration](references/system-administration.md#default-delivery).
|
|
103
103
|
|
|
104
104
|
For process management, distinguish administrator-adjustable reviewers, departments, thresholds and other [lifecycle parameters](references/lifecycle-parameters.md) from workflow structure, which remains defined in source unless a supported visual designer is explicitly required.
|
|
105
105
|
|
|
@@ -115,7 +115,7 @@ Replace `/main` with the application's `APP_BASE_PATH`. Swagger UI for people is
|
|
|
115
115
|
|
|
116
116
|
## Include administration by default
|
|
117
117
|
|
|
118
|
-
For every application feature, apply [system settings delivery](references/system-settings.md): keep unused business settings disabled in a newly created application while retaining its restricted App Foundation entry; as the application develops beyond that basic shell, reconcile the template's prepared Users and Roles and permissions routes and the management surfaces for each capability actually used. Inspect this on every build or iteration, enable missing routes once and preserve already enabled pages, including workflow definitions, diagrams, configuration and authorized execution history. When building process rules, proactively declare appropriate thresholds and reviewer choices as validated, authorized business parameters and provide visible parameter forms in workflow management, with optional diagram-bound shortcuts to the same editor; the user need not ask for configurability. Apply the same check to non-workflow business policy, mutable dictionaries, business document numbering, important operation records and the other used capabilities in that reference. Follow its [business administration recipes](references/business-administration.md) for application-owned implementations and acceptance. The real execution must consume the saved values; source/deployment configuration retains its owner. This is part of implementing the feature, not a separate user request.
|
|
118
|
+
For every application feature, apply [system settings delivery](references/system-settings.md) and place every administration surface in the [System settings navigation](references/settings-navigation.md) (one sidebar entry, a home of cards by category, tabs inside a module): keep unused business settings disabled in a newly created application while retaining its restricted App Foundation entry; as the application develops beyond that basic shell, reconcile the template's prepared Users and Roles and permissions routes and the management surfaces for each capability actually used. Inspect this on every build or iteration, enable missing routes once and preserve already enabled pages, including workflow definitions, diagrams, configuration and authorized execution history. When building process rules, proactively declare appropriate thresholds and reviewer choices as validated, authorized business parameters and provide visible parameter forms in workflow management, with optional diagram-bound shortcuts to the same editor; the user need not ask for configurability. Apply the same check to non-workflow business policy, mutable dictionaries, business document numbering, important operation records and the other used capabilities in that reference. Follow its [business administration recipes](references/business-administration.md) for application-owned implementations and acceptance. The real execution must consume the saved values; source/deployment configuration retains its owner. This is part of implementing the feature, not a separate user request.
|
|
119
119
|
|
|
120
120
|
For initialization prerequisites introduced by the feature, apply [setup readiness](references/setup-readiness.md): wire real required-role membership and applicable business relationship checks with the standard contextual hint. Users should see what configuration is missing and an authorized path to fix it. Installed plugins, read failures and missing business configuration are different states; keep the bare app and its protected App Foundation entry unchanged.
|
|
121
121
|
|
|
@@ -193,7 +193,7 @@ Everything else — `client/routing/`, `client/layouts/`, `client/theme/`, the s
|
|
|
193
193
|
|
|
194
194
|
When the built-in mechanism genuinely cannot express the requirement, changing that structure is a legitimate answer. Comment what you changed and why the built-in path did not fit, and in the same change record the application-specific guidance in the matching `.agents/rules/<topic>.md`, adding its entry to the `AGENTS.md` index, so the guidance still describes the real application. Do not write the detail into `AGENTS.md` itself: it is a small always-on index of at most 32 KB that every agent loads on every start. The synchronized NocoBase Skills are package-owned; propose a change to their source package when the shared framework guidance itself is wrong.
|
|
195
195
|
|
|
196
|
-
When you do change the shell (`client/layouts/`, `client/routing/`), keep the behaviors listed in [customizing the shell](references/frontend/references/shell.md#1-behaviors-to-keep): a single App shell with administration pages
|
|
196
|
+
When you do change the shell (`client/layouts/`, `client/routing/`), keep the behaviors listed in [customizing the shell](references/frontend/references/shell.md#1-behaviors-to-keep): a single App shell with administration pages under its one System settings entry rather than a separate settings layout, the language submenu, navigation group state, permission refresh and sign-out handling.
|
|
197
197
|
|
|
198
198
|
## Ownership
|
|
199
199
|
|
|
@@ -638,7 +638,7 @@ A page that shows a record whose detail is a page of its own — an orders list'
|
|
|
638
638
|
|
|
639
639
|
## 7. Settings pages
|
|
640
640
|
|
|
641
|
-
- A settings page is an ordinary App page
|
|
641
|
+
- A settings page is an ordinary App page in the System settings structure ([section 5 of `page.md`](page.md#5-settings-pages)); a settings module with several views uses URL-backed tabs through `SettingsModulePage` ([System settings navigation](../../settings-navigation.md)).
|
|
642
642
|
- Tabs in settings pages also use child routes ([section 4](#4-page-tabs)); nested details and tabs usually have no `navigation`.
|
|
643
643
|
- A settings page checks its settings item; its child pages and tabs inherit that check or declare another action or item of their own, never a page grant.
|
|
644
644
|
- Navigation groups carry no page permission. Access checks in the browser do not replace server authorization.
|
|
@@ -90,7 +90,7 @@ Rules:
|
|
|
90
90
|
- **Write import paths with the `.js` extension**, even when the source file is `.tsx`. This is how this project resolves modules, not a typo.
|
|
91
91
|
- **Paths are internal to the application**: do not write the deployment base path `/main`. The application is mounted under a base path (`/main` by default), and the runtime adds it automatically: `/projects` is `/main/projects` in the browser.
|
|
92
92
|
- **Reserved paths**: `/login`, `/register`, `/forgot-password` and `/reset-password` can only use `auth: 'guest'`. They are already declared in `client/routes.ts`, and their pages are in `client/pages/auth/`.
|
|
93
|
-
- Every page shares one path space. Registration rejects a path that another route already uses. Administration pages are ordinary App pages ([section 5](#5-settings-pages)); there is no
|
|
93
|
+
- Every page shares one path space. Registration rejects a path that another route already uses. Administration pages are ordinary App pages in the System settings structure ([section 5](#5-settings-pages)); there is no separate settings layout or `/dev` surface.
|
|
94
94
|
|
|
95
95
|
## 2. The page component
|
|
96
96
|
|
|
@@ -212,32 +212,27 @@ Provide English and Chinese text without unresolved interpolation placeholders.
|
|
|
212
212
|
|
|
213
213
|
## 5. Settings pages
|
|
214
214
|
|
|
215
|
-
There is one kind of client route, `defineAppRoutes()
|
|
215
|
+
There is one kind of client route, `defineAppRoutes()`, and plugins contribute no settings pages of their own: a page that configures something is an ordinary App page. Place it in the application's System settings structure — one sidebar entry opening a home page of cards by category, with tabs inside a module — by registering it with `parent` naming a settings category, as [System settings navigation](../../settings-navigation.md) describes. Add the icons to the `lucide-react` import at the top of the file (here `SlidersHorizontal`):
|
|
216
216
|
|
|
217
217
|
```ts
|
|
218
|
-
// Appended to the
|
|
218
|
+
// Appended to the routes in client/routes.ts, beside the template's settings shell.
|
|
219
219
|
{
|
|
220
|
-
// A
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
},
|
|
237
|
-
// The group's path is a prefix: this page is at /settings/projects.
|
|
238
|
-
path: '/projects',
|
|
239
|
-
},
|
|
240
|
-
],
|
|
220
|
+
// A card in the Business configuration category of the System settings home.
|
|
221
|
+
parent: 'settingsBusiness',
|
|
222
|
+
// Opens for identities granted read on the project-settings item; the endpoints check the same item.
|
|
223
|
+
authz: {
|
|
224
|
+
resource: { type: 'settings', id: 'project-settings' },
|
|
225
|
+
action: 'read',
|
|
226
|
+
},
|
|
227
|
+
componentLoader: () => import('./pages/settings/projects/index.js'),
|
|
228
|
+
name: 'project-settings',
|
|
229
|
+
navigation: {
|
|
230
|
+
title: 'navigation.projectSettings',
|
|
231
|
+
description: 'navigation.projectSettingsDescription',
|
|
232
|
+
icon: SlidersHorizontal,
|
|
233
|
+
},
|
|
234
|
+
// In Default the settings group's path is a prefix: this page is at /settings/projects.
|
|
235
|
+
path: '/projects',
|
|
241
236
|
},
|
|
242
237
|
```
|
|
243
238
|
|
|
@@ -245,7 +240,7 @@ A configuration page checks a **settings item** rather than a page grant: a name
|
|
|
245
240
|
|
|
246
241
|
- **Register the item on the server** in the `boot()` of the provider that owns the feature, with the service resolved from `authorizationToken`: `authz.settings.add({ id: 'project-settings', title, actions: [{ name: 'read' }, { name: 'update' }] })`, placed in the permission workspace with `authz.ui.place` (after `authz.ui.sections.add` when it needs a subsection of its own); an unplaced item is listed under "Other" with a startup warning. The server denies an item or action nobody registered, so an unregistered item keeps the page closed. The endpoints check the same item per action, `read` for loading and `update` for saving; see ["Authorization, when identity is not enough" in `../../server-routes.md`](../../server-routes.md#authorization-when-identity-is-not-enough). Actions are business actions (`read`, `update`); there is no conversion such as `list`, `show` or `edit`. Read the `nocobase-app-plugin-authorization` Skill before designing several items or actions.
|
|
247
242
|
- **Gate the write controls on the write action**: `useCan({ resource: { type: 'settings', id: 'project-settings' }, action: 'update' })` ([section 8](#8-show-actions-by-permission-usecan)). Without it, render the values read-only instead of hiding the page.
|
|
248
|
-
- `authz` is checked before the page loads; without permission
|
|
243
|
+
- `authz` is checked before the page loads; without permission its card disappears from the settings home, and opening its URL directly does not load the component either. A category or module group whose pages are all denied disappears with them.
|
|
249
244
|
- `navigation.order` sets the position in the menu; lower numbers come first.
|
|
250
245
|
- For tabs and detail child pages, see [`child-routes.md`](child-routes.md).
|
|
251
246
|
|
|
@@ -4,11 +4,12 @@ The shell is `client/routing/` and `client/layouts/`, with the header, sidebar a
|
|
|
4
4
|
|
|
5
5
|
## 1. Behaviors to keep
|
|
6
6
|
|
|
7
|
-
- There is no settings
|
|
7
|
+
- There is no separate settings layout and no Settings or Inbox entry in the header: every signed-in page renders inside `AppLayout`. Administration pages are ordinary routes under the System settings group, which the navigation transform (`client/lib/navigation-transform.ts`) folds into one sidebar entry opening the settings home; it stays selected on every page below the group, and the breadcrumb's System settings level links back to the home ([System settings navigation](../../settings-navigation.md)). Do not add a second layout, a resident settings sidebar or a router split for settings. The shell shares its single page permission check with pages through `RouteTreeProvider`'s `access` (`useRouteAccess`); the settings home and module tabs read it rather than checking again.
|
|
8
8
|
- The account menu's language control (`client/layouts/components/language-switcher.tsx`) is a submenu with radio items and must stay inside `DropdownMenuContent`, which provides its keyboard navigation and selected state.
|
|
9
9
|
- Collapsible navigation groups keep their expanded or collapsed state while the navigation tree stays mounted; opening a new page expands its ancestor groups without collapsing the others.
|
|
10
10
|
- The sidebar is shadcn's `Sidebar`, composed in `client/layouts/components/app-sidebar.tsx` (provider, desktop sidebar, phone sheet, header toggle) and `navigation-menu.tsx` (the route tree as `SidebarMenu*` entries: a top-level group with no page is a section under a heading, its entries always shown; clickable parents and nested groups are controlled `Collapsible` sub-menus; counts beside entries come from the layout through its `badges`, [`page.md`](page.md#a-count-beside-an-entry)). Keep `client/components/ui/sidebar.tsx` as the shadcn CLI writes it and change the sidebar from these two files: the widths are set through the provider's `style` in spacing units (`--sidebar-width`, `--sidebar-width-icon`) so they follow the density preset; the phone sheet is rendered in `app-sidebar.tsx` with a translated title instead of the primitive's own; and the provider's Ctrl/Cmd+B shortcut is stopped by a `document` keydown listener, so the key stays with editors.
|
|
11
11
|
- The desktop sidebar can collapse to icons: leaf entries then show their label in a tooltip without delay and section headings hide and their entries keep their icons, collapsible groups open in a popover on hover or keyboard focus, keeping the filtered entries, parent-page links, nested groups and the highlight of the group holding the current page. The collapsed state is shared through `useSidebarPreference` under `nocobase:sidebar:collapsed` by every application on the same origin, while whether the phone sheet is open stays local to each layout.
|
|
12
|
+
- Keep `RouteLeaveBoundary` in `AppLayout` outside every page Activity, including nested routes. Settings forms register with this shell boundary so navigation, confirmation dialogs and `beforeunload` protection remain active during permission checks. A final denial or session change removes the retained form guards. Activity restores Effects after a successful check, so mounted data hooks re-fetch; count those requests when assessing refresh cost.
|
|
12
13
|
- The authorization provider clears the permission snapshot before rendering a new session; route navigation and page guards subscribe to the authorization revision, so account switches and permission changes take effect without a reload.
|
|
13
14
|
- When signing out, the account menu checks the result from Better Auth and shows a localized error message on failure; do not treat navigating away as having signed out.
|
|
14
15
|
|
|
@@ -285,10 +285,10 @@ Read-only React Flow canvas with ELK orthogonal routing for directed graphs, inc
|
|
|
285
285
|
|
|
286
286
|
- Kind: component
|
|
287
287
|
- Install: `yes n | pnpm exec shadcn add @nocobase/flow-diagram`
|
|
288
|
-
- Installs to: `client/components/flow-diagram.tsx`, `client/components/flow-layout.ts`, `client/components/flow-diagram-css.d.ts`
|
|
288
|
+
- Installs to: `client/components/flow-diagram.tsx`, `client/components/flow-layout.ts`, `client/components/flow-diagram-css.d.ts`, `client/components/body-portal.tsx`
|
|
289
289
|
- Plugin dependencies: none
|
|
290
290
|
- Example: `@nocobase/flow-diagram-demo` (`pnpm exec shadcn view @nocobase/flow-diagram-demo`)
|
|
291
|
-
- After installing: Pass nodes and edges with unique ids, an ariaLabel and either a bounded canvas height or autoHeight. Use direction DOWN with autoHeight for detailed page diagrams; height follows the full layout including outer routes and labels. The default node is 232×104 canvas units; set width/height for richer renderNode content. direction is RIGHT or DOWN. nodeDescription and nodeActions add supporting summaries and configuration controls. For bounded canvases, initialMinZoom=0.8 preserves initial readability and showMiniMap provides overview navigation; Fit still shows the whole graph. Translate flowDiagram.overview when using the minimap. onNodeClick/onEdgeClick open your details; onLayoutError reports invalid graph or layout failures. Translate flowDiagram.empty, loading, failed, nodeHelp and edgeHelp; see the components README. Includes React Flow CSS. Uses application primary/card/foreground/border tokens in light and dark themes. Ordinary edges are subdued, solid and labeled directly on the route. Set visited on nodes/edges for actual history and highlighted for the current node or available edges; current nodes have a stronger fill and ring. ELK optimizes port order to reduce crossings. Decorative nodes/edges are not focusable or selectable.
|
|
291
|
+
- After installing: Pass nodes and edges with unique ids, an ariaLabel and either a bounded canvas height or autoHeight. Use direction DOWN with autoHeight for detailed page diagrams; height follows the full layout including outer routes and labels. The default node is 232×104 canvas units; set width/height for richer renderNode content. direction is RIGHT or DOWN. nodeDescription and nodeActions add supporting summaries and configuration controls. For bounded canvases, initialMinZoom=0.8 preserves initial readability and showMiniMap provides overview navigation; Fit still shows the whole graph. Translate flowDiagram.overview when using the minimap. onNodeClick/onEdgeClick open your details; onLayoutError reports invalid graph or layout failures. Translate flowDiagram.empty, loading, failed, nodeHelp and edgeHelp; see the components README. Includes React Flow CSS. Uses application primary/card/foreground/border tokens in light and dark themes. Ordinary edges are subdued, solid and labeled directly on the route. Set visited on nodes/edges for actual history and highlighted for the current node or available edges; current nodes have a stronger fill and ring. ELK optimizes port order to reduce crossings. Decorative nodes/edges are not focusable or selectable. Body portals detach when React Activity hides the diagram, retaining component state without leaving fullscreen content visible during permission rechecks.
|
|
292
292
|
|
|
293
293
|
### lifecycle-diagram
|
|
294
294
|
|
|
@@ -8,7 +8,7 @@ For approval-specific requests, tasks and decisions, first follow [approval plug
|
|
|
8
8
|
|
|
9
9
|
Use the UI Library `workflow-management` block as the default starting point; it extracts the existing workflow example's layout and interactions. Adapt its business labels, data sources and supported operations to the application; do not require its example plugins as production dependencies. The sidebar has one clickable entry, System management → Workflow management. Its landing page has one Workflow management header and in-page Definitions and Executions tabs; these are two views of the same management page, not separate sidebar entries or a sidebar submenu. Definitions lead to full detail pages with a process diagram and visible parameter settings beside it; executions lead to full detail pages with a diagram, transition history, effect status and recorded parameter information. Include implemented workflows even when there is only one. Show an explicit empty state for definitions without adjustable parameters and for workflows without executions; add category management when classification is useful.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Register Workflow management as one module card in the Business configuration category of System settings ([System settings navigation](settings-navigation.md)), alongside the Users, Permission management, Background tasks and other applicable administration cards. Keep workflow execution inspection inside Workflow management; do not add an intermediate Operational monitoring group. Deliver real catalog and execution data, initial administrator grants and working page/API authorization alongside the process. Follow [system administration](system-administration.md) for the complete application's administration baseline and authenticated acceptance checks. Workflow configuration stays separate from business submit, approve and fulfil pages, and does not imply a visual workflow designer.
|
|
12
12
|
|
|
13
13
|
## Install and connect the block
|
|
14
14
|
|
|
@@ -20,9 +20,9 @@ Render the preinstalled `LifecycleDiagram` through the diagram slot/callback by
|
|
|
20
20
|
|
|
21
21
|
## Navigation and ownership
|
|
22
22
|
|
|
23
|
-
Separate business work (submit, approve, fulfil) from administration (definitions, categories, parameters, executions).
|
|
23
|
+
Separate business work (submit, approve, fulfil) from administration (definitions, categories, parameters, executions). Register the single Workflow management module in System settings; definitions, categories, parameters and executions are views or controls within it. Use separate read and update permissions. Configuration permission does not grant business approval permission. Use the real authenticated identity rather than demonstration identity switchers.
|
|
24
24
|
|
|
25
|
-
Within the workflow route subtree, declare `navigation` only on the Workflow management route. Implement Definitions and Executions as URL-backed child routes without `navigation`; their breadcrumb declarations do not make them sidebar entries. Render the child list through `Outlet` beneath the shared page header and line-style Tabs, using the URL to select the active tab and navigating on tab changes. Redirect the parent to its default accessible child. The example uses `/workflows`, `/workflows/definitions` and `/workflows/executions`; adapt the route prefix to the application. Preserve direct links, reloads and browser back/forward behavior. Keep the
|
|
25
|
+
Within the workflow route subtree, declare `navigation` only on the Workflow management route. Implement Definitions and Executions as URL-backed child routes without `navigation`; their breadcrumb declarations do not make them sidebar entries. Render the child list through `Outlet` beneath the shared page header and line-style Tabs, using the URL to select the active tab and navigating on tab changes. Redirect the parent to its default accessible child. The example uses `/workflows`, `/workflows/definitions` and `/workflows/executions`; adapt the route prefix to the application. Preserve direct links, reloads and browser back/forward behavior. Keep the System settings sidebar entry active across both tabs and their detail pages. Give diagram-heavy details full child pages through Outlet; suppress the parent's list header, filters and tabs while a detail is open. Use the shell breadcrumb trail: System settings → Workflow management → Definitions or Executions → current item. Preserve the list's query parameters in its breadcrumb instead of adding a competing Back link.
|
|
26
26
|
|
|
27
27
|
## Definition catalog
|
|
28
28
|
|
|
@@ -14,7 +14,7 @@ The lifecycle examples below illustrate state transitions, guards and effects, n
|
|
|
14
14
|
|
|
15
15
|
## Deliver workflow management by default
|
|
16
16
|
|
|
17
|
-
Whenever application requirements include a process to develop, include workflow management pages alongside its business operations; users do not need to request a console separately. Reuse or extend existing management pages with the UI Library `workflow-management` block and follow [Lifecycle UI](lifecycle-ui.md) for the default layout and organization based on the workflow example. Deliver one Workflow management
|
|
17
|
+
Whenever application requirements include a process to develop, include workflow management pages alongside its business operations; users do not need to request a console separately. Reuse or extend existing management pages with the UI Library `workflow-management` block and follow [Lifecycle UI](lifecycle-ui.md) for the default layout and organization based on the workflow example. Deliver one Workflow management card in System settings with in-page Definitions and Executions tabs, definition details with diagrams and declared parameter settings, and execution details with history and effects. The tab views have URL-backed child routes without sidebar `navigation`. Follow the scope exceptions in [system administration](system-administration.md#default-delivery). Keep workflow structure in source; management pages do not imply a visual designer.
|
|
18
18
|
|
|
19
19
|
## Choose it or something else
|
|
20
20
|
|
|
@@ -90,16 +90,20 @@ A department an administrator creates stores its title as plain text. A seeded d
|
|
|
90
90
|
|
|
91
91
|
## Settings page
|
|
92
92
|
|
|
93
|
-
Declare one page in `client/routes.ts` with `defineAppRoutes`, titled with the same key and placed
|
|
93
|
+
Declare one page in `client/routes.ts` with `defineAppRoutes`, titled with the same key and placed as a card in the Accounts and permissions category of System settings ([System settings navigation](../settings-navigation.md)); the department details are a child route, so they inherit the entry page's `authz`:
|
|
94
94
|
|
|
95
95
|
```ts
|
|
96
96
|
defineAppRoutes([
|
|
97
97
|
{
|
|
98
|
-
//
|
|
99
|
-
parent: '
|
|
98
|
+
// A card in the Accounts and permissions category; in Default the page is at /settings/departments.
|
|
99
|
+
parent: 'settingsAccount',
|
|
100
100
|
name: 'departments',
|
|
101
101
|
path: '/departments',
|
|
102
|
-
navigation: {
|
|
102
|
+
navigation: {
|
|
103
|
+
title: 'navigation.departments',
|
|
104
|
+
description: 'navigation.departmentsDescription',
|
|
105
|
+
icon: Network,
|
|
106
|
+
},
|
|
103
107
|
authz: {
|
|
104
108
|
resource: { type: 'settings', id: 'departments' },
|
|
105
109
|
action: 'read',
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# System settings navigation
|
|
2
|
+
|
|
3
|
+
Every administration surface of an application lives under one System settings entry in the sidebar. Opening it shows a home page of cards grouped by category; a card opens one module; a module with several views shows them as tabs. Build every administration page into this structure without the user asking for it, and keep everyday business entries — the inbox, approval to-dos, a team's mailbox, a knowledge base people read — in the business navigation even when their names sound administrative.
|
|
4
|
+
|
|
5
|
+
## The structure is the route tree
|
|
6
|
+
|
|
7
|
+
The templates register the structure in `client/routes.ts` (Default: `client/pages/settings/shell-routes.ts`; Examples: its `systemManagement` group) and the navigation transform in `client/lib/navigation-transform.ts` renders it. Nothing is hand-written per card: the home page and the tabs read the registered routes through the shell's single permission check.
|
|
8
|
+
|
|
9
|
+
| Level | Route | Shown as |
|
|
10
|
+
| -------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
11
|
+
| Settings group | the group holding `settingsHome` (`settings` in Default, `systemManagement` in Examples) | one sidebar entry, selected on every page below it |
|
|
12
|
+
| Category | a direct child group: `settingsAccount`, `settingsBusiness`, `settingsAi`, `settingsSystem` | a heading on the home page, hidden while the viewer can open nothing in it |
|
|
13
|
+
| Module | a page or a group inside a category | one card: icon, `navigation.title`, `navigation.description`, arrow |
|
|
14
|
+
| Tab | a page with `navigation` inside a module group | a URL-backed tab in `SettingsModulePage` |
|
|
15
|
+
|
|
16
|
+
- Register a module with `parent` naming its category, and give it `navigation.title`, `navigation.description` (one sentence on what it is for, translated like the title) and an icon. A card without a description is incomplete.
|
|
17
|
+
- A module with one view is a page; it renders its content directly, with no single tab. A module with several views is a group with `breadcrumb` whose pages each declare `navigation` and `authz`; wrap each view in `SettingsModulePage` from `client/pages/settings/settings-module-page.tsx`, which derives the tabs, hides the ones the viewer may not open and drops the tab bar when only one remains. The card opens the first tab the viewer may open. A module whose page already has its own tabs, such as workflow management's definitions and executions layout, stays a page.
|
|
18
|
+
- Categories are application-owned: rename, reorder (`navigation.order`), add or remove them in the same place. A page registered directly under the settings group, as a plugin's settings page is (App Foundation), is shown in `settingsSystem`.
|
|
19
|
+
- Never add another sidebar entry, a second settings layout, a resident settings sidebar or a hand-written card list. Never register a placeholder card for a capability the application does not use, and never put a dead link or a page that only says "coming soon" in a category.
|
|
20
|
+
- The home page (`settingsHome`) is `authz: 'skip'`: it grants nothing and lists only what the viewer may open. Hiding a card is presentation; every module keeps its own `authz` and its server checks.
|
|
21
|
+
|
|
22
|
+
## URLs, breadcrumbs and permissions
|
|
23
|
+
|
|
24
|
+
Each module and tab keeps a URL of its own, so refresh, bookmarks and Back and Forward work, and the trail reads System settings → module → view with System settings linking back to the home. Moving an existing page into the structure changes its `parent` only: keep its route `name`, `path` and `authz`, so its page id, stored grants and deep links keep working. A pathless group adds nothing to its children's URLs; in Default the settings group's `/settings` prefix is already part of the existing settings URLs. If a URL must change, keep the old one working with a redirect route and say so in the delivery.
|
|
25
|
+
|
|
26
|
+
## Standard modules
|
|
27
|
+
|
|
28
|
+
| Module | Route | Views |
|
|
29
|
+
| --------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| Users | `settingsUsers` in `settingsAccount` (`client/pages/settings/routes.ts`) | one page |
|
|
31
|
+
| Permission management | `permissionManagement` group in `settingsAccount` | Roles and permissions (`settingsRoles`), Default data scopes (`settingsDefaultAccess`) |
|
|
32
|
+
| Workflow management | `workflows` page in `settingsBusiness` | its own definitions and executions tabs |
|
|
33
|
+
| Notifications | `notificationManagement` group in `settingsSystem`, path prefix `/notifications` | the views the application actually has: Delivery logs (`notificationLogs`, the UI Library `notification-logs-ui` page); Notification templates (`notificationTemplates`) when the application provides the catalogue |
|
|
34
|
+
| App Foundation | the Foundation plugin's `foundation` page, shown in `settingsSystem` | one page |
|
|
35
|
+
|
|
36
|
+
The templates' `includeNotificationTemplateRoutes` (`client/pages/settings/notification-routes.ts`) adds the Notification templates view (`/settings/notifications/templates`, `page:notification.templates`) to an existing `notificationManagement` group exactly once, or creates the group in `settingsSystem` when notification business is in use. Register Delivery logs and any later notification view in the same group rather than as another card, adding its title key to the application's locales:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
defineAppRoutes([
|
|
40
|
+
{
|
|
41
|
+
parent: 'settingsSystem',
|
|
42
|
+
name: 'notificationManagement',
|
|
43
|
+
navigation: {
|
|
44
|
+
title: 'settings.notificationManagement',
|
|
45
|
+
description: 'settings.notificationManagementDescription',
|
|
46
|
+
icon: Bell,
|
|
47
|
+
},
|
|
48
|
+
breadcrumb: { title: 'settings.notificationManagement' },
|
|
49
|
+
children: [
|
|
50
|
+
{
|
|
51
|
+
// Default: /settings/notifications/logs. The page checks the same grant as GET /api/notifications/logs.
|
|
52
|
+
name: 'notificationLogs',
|
|
53
|
+
path: '/notifications/logs',
|
|
54
|
+
auth: 'required',
|
|
55
|
+
authz: {
|
|
56
|
+
resource: { type: 'page', id: 'notification.logs' },
|
|
57
|
+
action: 'access',
|
|
58
|
+
},
|
|
59
|
+
navigation: { title: 'settings.notificationLogs' },
|
|
60
|
+
breadcrumb: { title: 'settings.notificationLogs' },
|
|
61
|
+
componentLoader: () => import('./pages/settings/notification-logs.js'),
|
|
62
|
+
},
|
|
63
|
+
],
|
|
64
|
+
},
|
|
65
|
+
]);
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Install the block with `yes n | pnpm exec shadcn add @nocobase/notification-logs-ui`. While Delivery logs is the module's only view, the page renders `NotificationLogsPage` from `#extensions/nocobase-notification-logs-ui/index` in a `PageContainer`; the block brings its own heading. When a second view such as Notification templates joins the group, render each view inside `SettingsModulePage` (titled with the module) and drop the block's own heading in the installed source, so the module has one heading above its tabs.
|
|
69
|
+
|
|
70
|
+
## Checks
|
|
71
|
+
|
|
72
|
+
Cover the structure in the application's tests: the sidebar has one settings entry selected on every settings URL, the home groups the expected cards with their descriptions, an empty category is hidden, a restricted viewer sees only the cards and tabs their grants open, and the existing URLs and `authz` of moved pages are unchanged. `tests/client/settings-navigation.test.ts` and `tests/client/settings-home.test.tsx` in the templates are the starting point.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Default delivery
|
|
4
4
|
|
|
5
|
-
A complete application includes System
|
|
5
|
+
A complete application includes the System settings structure and working administration pages by default. Users asking for a CRM, an order system or another business application do not need to enumerate its administrative infrastructure. Follow explicit exclusions and narrower deliverables such as API-only services or prototypes explicitly limited to business screens. For an individual feature, integrate its administration into the existing application.
|
|
6
6
|
|
|
7
7
|
Inspect existing routes, pages, plugin registrations and plugin Skills before implementing administration. Reuse installed capabilities and existing management pages; create application-owned pages for missing interfaces. Deliver real data, actions and initial permission configuration, rather than empty menu entries or placeholder pages. Follow the normal plugin installation workflow when a required capability is missing.
|
|
8
8
|
|
|
@@ -19,9 +19,9 @@ Add management pages for the capabilities the application uses: organizations an
|
|
|
19
19
|
|
|
20
20
|
## Navigation and access
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
Place administrative capabilities in the application's System settings structure, separate from business navigation: one sidebar entry, a home page of cards by category, and tabs inside a module ([System settings navigation](settings-navigation.md)). Management pages use the application's normal layout. Use the UI Library `workflow-management` block for workflow administration, following [Lifecycle UI](lifecycle-ui.md) for installation, navigation and application-owned data/permission adapters.
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
Register User management, Permission management, Workflow management, Background tasks and other applicable capabilities as module cards in the System settings categories. Include capability-specific cards only when the application uses those capabilities. Do not introduce an Operational monitoring card or category. Workflow management is a single card whose page switches between Definitions and Executions with in-page tabs. These views retain URL-backed child routes without sidebar `navigation`; background task pages own their task status, execution history, failures and supported recovery actions. Notification management similarly owns delivery records, and later notification views join its tabs.
|
|
25
25
|
|
|
26
26
|
Configure initial administrator access through the supported authentication and authorization mechanisms. A signed-in administrator must be able to discover and use the management section. Distinguish administrative read and update access, and keep configuration permissions separate from business operations such as approvals. Enforce access in menu visibility, direct page access and server-side operations. Ordinary users receive only explicitly granted access.
|
|
27
27
|
|
|
@@ -29,4 +29,4 @@ Configure initial administrator access through the supported authentication and
|
|
|
29
29
|
|
|
30
30
|
Verify with a real authenticated administrator that the management entry appears, its pages load actual data, and permitted management operations succeed. Verify with an ordinary user that restricted menus, direct URLs and API operations are protected. Where read-only administration is supported, verify that reading succeeds and updates are denied.
|
|
31
31
|
|
|
32
|
-
Verify that applicable management
|
|
32
|
+
Verify that the sidebar has one System settings entry, that applicable management modules are cards of its home in the right categories, and that execution records and failures are accessible inside each capability. When the application includes workflows, verify that Workflow management has one card and that Definitions and Executions appear only as tabs within its page. For workflows, verify that implemented definitions and business executions appear in management, parameter changes respect their effective timing, and execution history and failures remain inspectable. Use the [Lifecycle UI verification guidance](lifecycle-ui.md#source-examples-and-verification) for detail navigation and presentation. Report any unverified behavior and its missing prerequisites explicitly.
|
|
@@ -4,9 +4,9 @@ A usable application includes administration for the capabilities it uses. Do no
|
|
|
4
4
|
|
|
5
5
|
## Baseline
|
|
6
6
|
|
|
7
|
-
A newly created Default application shows Home and
|
|
7
|
+
A newly created Default application shows Home and, for an unrestricted administrator, one System settings entry whose home page holds the protected App Foundation card. Other users do not see that entry. It does not enable business settings or their prerequisite checks merely because plugins are installed. The template includes reusable application-owned Users and Permission management page modules, ready to enable as the application develops. Examples is already a built application and registers them. Every administration surface joins the System settings structure — one sidebar entry, a home page of cards by category, tabs inside a module — described in [System settings navigation](settings-navigation.md); follow it for every module this reference asks for.
|
|
8
8
|
|
|
9
|
-
As business capabilities are developed, automatically supply core user and permission administration and any management surfaces those capabilities need. If the core settings routes are still absent, import `systemSettingsRoutes` from `./pages/settings/routes.js` in `client/routes.ts` and append it once to the exported route contribution array: `const routes: readonly AppClientRouteContribution[] = [appRoutes, systemSettingsRoutes]`.
|
|
9
|
+
As business capabilities are developed, automatically supply core user and permission administration and any management surfaces those capabilities need. If the core settings routes are still absent, import `systemSettingsRoutes` from `./pages/settings/routes.js` in `client/routes.ts` and append it once to the exported route contribution array after the settings shell: `const routes: readonly AppClientRouteContribution[] = [appRoutes, settingsShellRoutes, systemSettingsRoutes]`. Its routes join the shell's Accounts and permissions category through `parent: 'settingsAccount'`. Reuse an existing registration instead of duplicating it, and never register a second settings group: Users, Permission management, Workflow management and other administration modules appear as cards of the one System settings home while retaining their URLs and permission ids. Do not make the user ask for user or permission settings separately, and do not grant access to ordinary users as a side effect. Existing applications that predate these modules should install or build equivalent real management pages as part of the current development task when needed. Preserve already enabled pages and their server authorization on every iteration. Do not use a first-build flag, a one-time setup stage, or the number of development rounds as the trigger. Reuse UsersClient and AuthorizationClient; the plugins own accounts, role scopes, grants, protected sets and their invariants. Keep personal account and appearance controls in the existing account/header surfaces.
|
|
10
10
|
|
|
11
11
|
## Reconcile administration on every iteration
|
|
12
12
|
|
|
@@ -86,7 +86,7 @@ For approval policy, default to snapshot semantics for a formal submission unles
|
|
|
86
86
|
|
|
87
87
|
Check every applicable row above, not just the capability named by the user. Include a concise delivery map in the development report: capability, working entry, owning persistence/API, permission, execution consumer, and observed evidence or explicit limitation. Read [acceptance scenarios](business-administration.md#acceptance-scenarios) for blind-prompt and iteration checks. This is development evidence, not implementation detail to display to application users.
|
|
88
88
|
|
|
89
|
-
Before finishing, map each used capability to its working management entry, route, real API, server-side permission and verification evidence.
|
|
89
|
+
Before finishing, map each used capability to its working management entry, route, real API, server-side permission and verification evidence. Place entries as cards of the System settings home ([System settings navigation](settings-navigation.md)), with workflow definitions and executions as page tabs rather than sibling cards; an empty category is hidden after permission filtering. Repeated additions reconcile missing entries only: no duplicate menus, role seeds or configuration. Preserve existing stable route ids and unrelated administrator grants. Verify an authorized administrator, a user without management access, direct API denial, loading/empty/error states, write failure, deep links, Chinese/English, dark/light and narrow layouts. Keep execution data current through the existing realtime mechanism or a working Refresh action. For inferred threshold and reviewer parameters, save a different valid configuration and prove that a new eligible business execution uses it; also verify invalid values, an unauthorized update, snapshot preservation and repeated iterations without duplicate fields or bindings.
|
|
90
90
|
|
|
91
91
|
## Role list presentation
|
|
92
92
|
|
|
@@ -100,7 +100,7 @@ For Create actions, use `hiddenActionScopes` to omit a selector for the new reco
|
|
|
100
100
|
|
|
101
101
|
## Default data scope administration
|
|
102
102
|
|
|
103
|
-
When the application exposes role management and uses the Default Access plugin, include the template's `/default-access` system settings contribution and its create/details child routes. The default template supplies this in `client/pages/settings/routes.ts`; Examples registers it under System management. Show one Permission management
|
|
103
|
+
When the application exposes role management and uses the Default Access plugin, include the template's `/default-access` system settings contribution and its create/details child routes. The default template supplies this in `client/pages/settings/routes.ts`; Examples registers it under System management. Show one Permission management card with Roles and permissions and Default data scopes as URL-backed tabs (`SettingsModulePage`), leaving Users as a sibling card. The card opens the first readable tab, and a viewer who may open only one of them sees it without a tab bar. Keep existing paths, route ids and authorization requirements; do not add placeholder entries for rule editors the application does not expose. The list and form call `authorization/defaultAccess` and `/options`, with the existing `settings:authorization.default-access` read/create/update/delete requirements. Read permission allows full inspection; only create/update/delete permit writes. Use the Registry `default-access-editor` for the controlled fields and `PermissionFilter` for native custom conditions. Explain that baseline ranges apply to identities already holding an operation and remain subject to restrictions. Never equate a baseline rule with granting the operation itself.
|
|
104
104
|
|
|
105
105
|
On template upgrades reconcile the editor, list/form/model, route contribution, filter-label helper and locales. Preserve stored rule keys, resources, actions, record IDs and filter parameters; do not seed, rewrite or select All records during browsing or upgrades. Unknown metadata stays visible and read-only. The existing API has no atomic revision precondition, so re-read the target before replacing actions or deleting and refuse a detected stale edit.
|
|
106
106
|
|
|
@@ -117,3 +117,7 @@ Reuse the prepared Users page for role membership rather than creating another m
|
|
|
117
117
|
The prepared lists keep paging and sorting in URL state through `#hooks/use-table-url-state`. Preserve query strings in child links, close destinations and contextual configuration links. Correct pages beyond the last loaded page after a successful write/refetch; never clamp using stale rows while a query is loading or failed. Return destinations are application-relative and validated with `client/lib/return-to.ts`; never navigate to an arbitrary external URL. On success update the displayed record from the response and refresh the owning list; on failure/conflict retain the draft and require explicit confirmation before discarding it. Verify filtered list → detail/edit → failed save → successful save → close/return and browser history, not merely a successful toast.
|
|
118
118
|
|
|
119
119
|
`WorkflowDefinitionList.onSort` is optional: omit it when the adapter cannot actually order results instead of passing a no-op. Omit `name` when there is no useful secondary identifier; a linked title should not be accompanied by the same display name again. Registry components and template copies evolve together, and template upgrades merge these integrations without replacing application-specific routes, grants or edited policy.
|
|
120
|
+
|
|
121
|
+
## Notification template directory
|
|
122
|
+
|
|
123
|
+
When notification business is used, include the existing Notification plugin’s source-owned read-only directory and synthetic preview in the same delivery. Read its `references/template-directory.md`, enumerate actual send call sites, register the shared real renderers and explicitly document dynamic or unregistered messages. Mount `notificationTemplates` in the existing `notificationManagement` module; use the template’s `includeNotificationTemplateRoutes` on the complete host route composition once, or insert its `notificationTemplateRoute` when that module already exists. Preserve the app-owned server bootstrap provider and Default runtime route factory: a configured built-in invitation mailer automatically enables the directory after restart, and an unused bare Default stays empty. Keep `page:notification.templates/access` restricted on both page and APIs. Distinguish a definition, channel configuration and business activation. Do not add an empty menu to a bare application with no notification business.
|
|
@@ -124,6 +124,8 @@ When the target adds standard form feedback, follow [form feedback source upgrad
|
|
|
124
124
|
|
|
125
125
|
When the template changes the permission workspace, follow [Permission editor source upgrades](references/edge-cases.md#permission-editor-source-upgrades). Merge copied permission models and translations while preserving application-specific descriptions, grants and role behavior; a dependency update alone does not update them.
|
|
126
126
|
|
|
127
|
+
When the template introduces or changes the System settings structure (one settings entry, a home page of cards, tabs inside a module), follow [System settings navigation upgrades](references/settings-navigation-upgrade.md). Merge the navigation transform, routing, settings pages and locales, and move existing administration pages into categories without changing their names, paths or authorization; updating dependencies alone keeps the old navigation.
|
|
128
|
+
|
|
127
129
|
When the template changes list-return behavior, read [list navigation upgrades](references/list-navigation-upgrade.md). Merge the routing context, breadcrumb and back-link sources together, and examine application-owned detail links and forms; updating dependencies alone does not update these copied sources.
|
|
128
130
|
|
|
129
131
|
When the template changes loading, empty, filtered or failed list feedback, follow [list feedback source upgrades](references/list-feedback-upgrade.md). Reconcile copied components, request owners, translations and business empty content together, and verify both new and upgraded applications with retained permissions and records.
|
|
@@ -208,3 +210,5 @@ Compare BASE directly with TARGET and merge the resulting changes once. Check th
|
|
|
208
210
|
When the target adds or changes the standard process UI sources, also follow [standard process management source upgrades](references/edge-cases.md#standard-process-management-source-upgrades): confirm existing process pages actually consume the merged components, while preserving explicit user customizations, parameters, grants and history.
|
|
209
211
|
|
|
210
212
|
When the target introduces standard submission protection, follow [submission source upgrades](references/submission-upgrade.md) during planning and reconciliation. Dependency or version-marker changes alone do not update copied forms, custom actions or the application's receipt migrations. Verify both a fresh application and retained customized data.
|
|
213
|
+
|
|
214
|
+
For a target that adds notification template administration, follow [notification template source reconciliation](references/notification-template-upgrade.md) in the same version-selected upgrade, preserving business renderers, workflows, permissions and channel configuration.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Reconcile notification template administration
|
|
2
|
+
|
|
3
|
+
Follow the version-selected upgrade entry point in the parent Skill. Fetch BASE and TARGET template tarballs and TARGET's compatible `@nocobase/app-skills` first. This reference applies only when TARGET contains `client/pages/settings/notification-routes.ts` and the Notification package exposes `notificationTemplateRegistryToken` plus `client/templates`. A dependency update alone does not replace application source or register this page. Before a target release is published, candidate-package checks are useful but do not establish a published upgrade pass.
|
|
4
|
+
|
|
5
|
+
1. Record the clean application checkpoint, template package and baseline version. Preserve a representative business page, custom notification renderer/fixture, notification workflows, channel/mailer configuration, stored grants and business records for comparison. Keep secrets out of evidence.
|
|
6
|
+
2. Compare BASE → TARGET and BASE → application. Bring in compatible package ranges through TARGET's manifest. Reconcile `client/pages/settings/notification-templates.tsx`, `notification-routes.ts`, the route composition, `client/runtime.ts`, `server/providers/notification-management.ts`, its provider registration and English/Chinese settings labels. Preserve custom route names, page permission IDs and existing deep links. Default's runtime route factory consumes the provider's derived `client.notificationTemplates.invitationConfigured` boolean, so a configured built-in invitation mailer enables the real directory automatically after restart. The provider and Users directory use the exported safe `describeInvitationEmailChannel` projection; never publish mailer credentials or copy a full server configuration into `client`. A bare application without notification business keeps the menu absent.
|
|
7
|
+
3. Reuse the application's existing `notificationManagement` group under System settings. Apply `includeNotificationTemplateRoutes` to the complete host route contributions, or insert `notificationTemplateRoute` once into the existing module. Keep its path relative to any path-bearing ancestors so the stable application URL remains `/settings/notifications/templates`; do not register a second module. If applying the newer settings navigation source in the same upgrade, follow its upgrade reference and attach the group to its existing system category. Preserve the host's module container and log view. Do not invent channel-editing or test-send tabs.
|
|
8
|
+
4. Reconcile application-owned send call sites into source registration. Preserve custom content and sender selection; extract a pure shared builder only when needed. Keep callback-based or non-enumerable messages explicitly listed as uncovered. Never replace business workflows with Examples or force a direct invitation mailer through persistent notification storage.
|
|
9
|
+
5. Synchronize Skills through the upgraded CLI. Verify list/detail/preview as an administrator and direct API denial as a restricted user. Check actual language policy, configured/missing/disabled channels, synthetic-only rendering, search/category/channel filters and desktop/narrow layout. Browse and preview must leave notification history, business data and configuration unchanged.
|
|
10
|
+
6. Verify retained custom content, records, grants, workflow behavior and old deep links after restart. Run affected application checks and record exact BASE/TARGET versions, tarball integrity, dependency resolution, source conflict decisions and results. Advance `nocobase.defaultTemplateVersion` only after this reconciliation and the retained-data checks succeed.
|
|
11
|
+
|
|
12
|
+
There are no new tables or migrations for this directory. Rolling back source and compatible packages removes the view and registrations without deleting notification history or custom business state. Do not roll back or rewrite existing executed migrations.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# System settings navigation upgrades
|
|
2
|
+
|
|
3
|
+
Use this reference when BASE → TARGET introduces the System settings structure: one sidebar entry, a home page of cards by category, and tabs inside a module ([System settings navigation](../../nocobase-app-development/references/settings-navigation.md)). The structure is application-owned source. Updating `@nocobase/*` dependencies alone leaves the old navigation in place and working: `navigation.description` is optional and ignored by an older shell, and no route, URL or permission changes. Do not report the navigation as upgraded until the source below is merged and verified.
|
|
4
|
+
|
|
5
|
+
## Merge the source
|
|
6
|
+
|
|
7
|
+
Three-way merge each file from the BASE template, the application and the TARGET template; never copy TARGET over the application.
|
|
8
|
+
|
|
9
|
+
| Source | What TARGET adds |
|
|
10
|
+
| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| `client/lib/navigation-transform.ts` | `organizeNavigation`, `collapseSettingsNavigation`, `settingsCatalog`, `settingsHomeRoute` and the settings constants; `transformNavigation` now also takes the route tree |
|
|
12
|
+
| `client/routing/route-navigation.ts`, `route-context.tsx`, `route-tree.tsx`, `app-router.tsx` | `buildSettingsCatalog`; relative path nesting shared by the router and route matching; `filterRouteTree`, moved out of `app-router.tsx`, now keeping groups declared empty such as categories waiting for modules; and the shared `access` (`useRouteTree`, `useRouteAccess`) |
|
|
13
|
+
| `client/layouts/app-layout.tsx`, `client/components/breadcrumbs.tsx` | passing `access` to `RouteTreeProvider`; the System settings breadcrumb linking to the home |
|
|
14
|
+
| `client/pages/settings/shell-routes.ts` (Default) or the settings group in `client/routes.ts` (Examples) | the settings group with `settingsHome` and the four categories |
|
|
15
|
+
| `client/pages/settings/settings-home.tsx`, `settings-module-page.tsx`, `permission-management-page.tsx`, `routes.ts` | the home page, the module tab frame, Permission management on that frame, and `parent: 'settingsAccount'` on Users and Permission management |
|
|
16
|
+
| `client/locales/system/settings-*.ts` | `settings.home`, `settings.categories` and module descriptions |
|
|
17
|
+
|
|
18
|
+
Keep the application's own changes to these files and say in a comment why each remains.
|
|
19
|
+
|
|
20
|
+
Also merge `client/routing/route-leave-boundary.tsx`, its `AppLayout` wrapper and the `useSettingsLeave` re-export in `client/pages/settings/hooks.tsx`, as well as `client/routing/client-route.tsx`, `client/components/body-portal.tsx` and the `BodyPortal` use in `client/components/flow-diagram.tsx`. The route guard retains an already loaded page in React Activity while permissions are pending, then unmounts it on denial. Body portals detach their DOM in a layout Effect cleanup so hidden pages cannot leave a visible diagram or overlay behind. The leave boundary must sit outside every route Activity, including nested routes: Activity disconnects page Effects, so registering navigation and beforeunload guards inside the hidden page loses protection during a permission request. Keep confirmation UI in the boundary and clear retained guards on final denial, unmount or session change. Restoring visible Activity content restarts its Effects; existing list hooks re-fetch once per mounted request, in addition to the permission refresh. Keep the existing session boundary that clears page state when the signed-in identity changes. Review application-owned body portals for the same cleanup; field-error portals inside their form need no separate body container.
|
|
21
|
+
|
|
22
|
+
## Place the application's administration
|
|
23
|
+
|
|
24
|
+
1. Keep the application's settings group name. Default uses `settings`; Examples uses `systemManagement`; an application that renamed it sets `SETTINGS_GROUP` to its actual name rather than renaming the route, because its children's ids and grants do not depend on it but its customizations may.
|
|
25
|
+
2. Add `settingsHome` under that group. In a group with a path it is `path: '/'`; in a pathless group pick a free path such as `/settings` and confirm no route uses it.
|
|
26
|
+
3. Move each administration page into a category by changing only its `parent` (or its position in the tree): keep its `name`, `path` and `authz`. Add `navigation.description` keys in the application's locale files. Keep the application's custom categories, names and order; rename or add categories in the settings group rather than forcing the template's four.
|
|
27
|
+
4. Turn sibling pages that are views of one capability into a module group with `breadcrumb`, and wrap each view in `SettingsModulePage`. Leave a page that already has its own tabs as it is.
|
|
28
|
+
5. Move everyday business entries that had been placed in the settings group, such as a knowledge base people read, back to the business navigation without changing their URLs.
|
|
29
|
+
6. Remove any application-specific sidebar collapse made redundant by the settings entry (the template's former `collapsePermissionNavigation`), and the template's old `systemSettingsRoutes` re-parenting in Examples-derived applications.
|
|
30
|
+
|
|
31
|
+
If a URL has to change, keep the old path working with a redirect route and list it in the upgrade record.
|
|
32
|
+
|
|
33
|
+
## Verify
|
|
34
|
+
|
|
35
|
+
Run the application's navigation and settings tests, then check in the browser as an administrator and as a restricted user: one System settings entry selected on every settings page; the home shows the expected cards with descriptions and no empty category; each old deep link and bookmark opens the same page; tabs switch by URL, refresh and Back keep the view; the breadcrumb returns to the home; a restricted user sees only the cards and tabs their grants open and is still refused by direct URLs and APIs; list filters, unsaved-change guards and business data are unchanged. Trigger a permission refresh while editing: content and overlays must be hidden while pending, the same draft must return if access remains allowed, and denial or a different signed-in identity must remove the previous content. While the permission request remains pending, cancel leaving through the breadcrumb and browser Back, check that the URL and draft remain, and check the native beforeunload prompt; confirm leaving and check the destination. Cancel leaving through module tabs and the home breadcrumb and check that the draft remains; confirm leaving and check the final destination.
|