@nocobase/app-skills 0.1.0-beta.37 → 0.1.0-beta.38

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.
Files changed (20) hide show
  1. package/package.json +1 -1
  2. package/skills/nocobase-app-development/SKILL.md +20 -7
  3. package/skills/nocobase-app-development/references/frontend/references/page.md +6 -0
  4. package/skills/nocobase-app-development/references/frontend/references/testing.md +11 -59
  5. package/skills/nocobase-app-development/references/frontend/references/ui-library.md +28 -1
  6. package/skills/nocobase-app-development/references/lifecycle-parameters.md +10 -4
  7. package/skills/nocobase-app-development/references/lifecycle-ui.md +122 -0
  8. package/skills/nocobase-app-development/references/lifecycle.md +9 -5
  9. package/skills/nocobase-app-development/references/system-administration.md +32 -0
  10. package/skills/nocobase-app-development/references/system-settings.md +4 -4
  11. package/skills/nocobase-app-development/references/testing/cli/command.md +157 -0
  12. package/skills/nocobase-app-development/references/testing/cli/files.md +258 -0
  13. package/skills/nocobase-app-development/references/testing/client/page.md +301 -0
  14. package/skills/nocobase-app-development/references/testing/database/migration.md +50 -0
  15. package/skills/nocobase-app-development/references/testing/database/repository.md +160 -0
  16. package/skills/nocobase-app-development/references/testing/playwright/login.md +147 -0
  17. package/skills/nocobase-app-development/references/testing/server/routes.md +178 -0
  18. package/skills/nocobase-app-development/references/testing.md +53 -0
  19. package/skills/nocobase-app-upgrade/SKILL.md +2 -0
  20. package/skills/nocobase-app-upgrade/references/edge-cases.md +12 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.37",
3
+ "version": "0.1.0-beta.38",
4
4
  "description": "Agent Skills for developing, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: nocobase-app-development
3
3
  description: >-
4
- Primary entry for developing features and UI in a NocoBase 3 application:
5
- pages, routes, components, endpoints, data, permissions, services, translations, and tests.
4
+ Primary entry for building complete NocoBase 3 applications and individual features:
5
+ business and administration pages, routes, components, endpoints, data, permissions, services, translations, and tests.
6
6
  Use this application-local workflow instead of globally installed NocoBase 2
7
7
  Skills. Do not use for a published NocoBase 3 plugin package.
8
8
  metadata:
@@ -11,7 +11,7 @@ metadata:
11
11
 
12
12
  # NocoBase 3 application development
13
13
 
14
- Use this Skill when building a feature in this application: a page, an endpoint, a table, a service, or the tests covering them.
14
+ Use this Skill when building a complete application or an individual feature: business and administration pages, endpoints, data, services and their tests.
15
15
 
16
16
  Do not use it to develop a published plugin package. Plugin development has its own protocol and lives in a separate repository.
17
17
 
@@ -59,6 +59,14 @@ For notification configuration or sending, follow the notification plugin Skill:
59
59
 
60
60
  Install, update and customize plugins, and remove a direct NocoBase package, as [plugins](references/plugins.md) describes: `pnpm nocobase plugin register`, `plugin update` and `package remove` keep the manifest, the lockfile, the composition roots and the synchronized Skills consistent, so never hand-edit only one of them.
61
61
 
62
+ ## Deliver system administration by default
63
+
64
+ When a user asks you to build a complete application, deliver a usable System management navigation section 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. Place workflow management, background tasks and other applicable administration entries directly under System management as siblings; 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.
65
+
66
+ 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 sidebar entry 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).
67
+
68
+ 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.
69
+
62
70
  ## Learn the endpoints from the API document
63
71
 
64
72
  The running application describes every `/api` endpoint it serves — its own routes, every installed plugin's, the data endpoints and Better Auth's `/api/auth/...` — in an OpenAPI 3.1 document. Before calling an endpoint or building on one, fetch that document instead of reading route sources:
@@ -71,7 +79,7 @@ Replace `/main` with the application's `APP_BASE_PATH`. Swagger UI for people is
71
79
 
72
80
  ## Include administration by default
73
81
 
74
- For every application feature, apply [system settings delivery](references/system-settings.md): keep a newly created, Home-only application free of settings; 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 bound click-to-edit entries; 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.
82
+ For every application feature, apply [system settings delivery](references/system-settings.md): keep a newly created, Home-only application free of settings; 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.
75
83
 
76
84
  ## Frontend work
77
85
 
@@ -99,9 +107,10 @@ Read the page for the task in front of you. Do not read all of them.
99
107
  | Design who gets what across departments, heads and cross-department work | [organisation permission design](references/organization/permission-design.md) |
100
108
  | Add a reusable service, share it across routes, run background or scheduled work | [services and jobs](references/services-and-jobs.md) |
101
109
  | A record that moves through stages defined in code: approvals, tickets, orders, timeouts, effects after a state change | [record lifecycles](references/lifecycle.md) |
102
- | Administrator-adjustable approval departments, reviewers, thresholds or business values in a code-defined lifecycle | [configurable lifecycle parameters](references/lifecycle-parameters.md); keep workflow structure in source. When building process pages with node-related parameters, prefer an editing dialog opened from the corresponding diagram node or transition. |
110
+ | Administrator-adjustable approval departments, reviewers, thresholds or business values in a code-defined lifecycle | [configurable lifecycle parameters](references/lifecycle-parameters.md); keep workflow structure in source. For management forms and optional diagram-bound editing, see [Lifecycle UI](references/lifecycle-ui.md). |
111
+ | Lifecycle definition catalogs, execution lists, process details, history or parameter settings | [Lifecycle UI](references/lifecycle-ui.md) |
103
112
  | Flowcharts, process diagrams or lifecycle state diagrams | Use UI Library `@nocobase/flow-diagram` for generic graphs and `@nocobase/lifecycle-diagram` for lifecycle descriptions; see [diagram guidance](references/lifecycle.md#draw-an-interactive-lifecycle-diagram) and the [UI catalog](references/frontend/references/ui-library.md#diagrams). Preserve their application theme tokens. |
104
- | Write server and migration tests, choose a test layer, verify before finishing | [testing and verification](references/testing.md) |
113
+ | Use `@nocobase/app-testing` for database, server, client or CLI tests; verify before finishing | [testing and verification](references/testing.md) |
105
114
  | Run a CLI command: configure, migrate, manage plugins, read the data model | [the command line](references/cli.md) |
106
115
  | Add or change an application command under `cli/commands/` | [adding an application command](references/commands.md) |
107
116
  | Where a file goes, how the client and server are composed, configuration, changing the framework structure | [application structure](references/app-structure.md) |
@@ -140,7 +149,7 @@ Everything else — `client/routing/`, `client/layouts/`, `client/theme/`, the s
140
149
 
141
150
  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.
142
151
 
143
- 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 no settings area, the language submenu, navigation group state, permission refresh and sign-out handling.
152
+ 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 in the main sidebar rather than a separate settings layout, the language submenu, navigation group state, permission refresh and sign-out handling.
144
153
 
145
154
  ## Ownership
146
155
 
@@ -218,3 +227,7 @@ Authentication diagnostics use the application `auth` logger unless an explicit
218
227
  ## Storage
219
228
 
220
229
  Standalone source and compiled entries share the deployment directory's storage; `APP_STORAGE_DIR` selects another storage directory, and explicit storage paths take precedence over it. Embedded applications use Host-provided paths. Expanded releases live at `appRevisionsDir/<appId>/<sha256>` and restart recovery requires their installed metadata. Build archives use `storage/exports/dist.tar.gz`.
230
+
231
+ ## Process UI delivery gate
232
+
233
+ When adding a business process, read [Lifecycle UI](references/lifecycle-ui.md#default-diagram-and-configuration-contract) before selecting a renderer. Current templates already ship the standard React Flow components and workflow-management parts. Preserve their default style unless the user explicitly requests another style; declare and connect suitable business parameters and contextual configuration automatically. UI Registry entries are not npm packages: an npm 404 is not installation failure. Acceptance must compare actual component use and configuration behavior to the original requirement, even if an intermediate design approved a fallback.
@@ -204,6 +204,12 @@ A page and the endpoints it calls must agree: the example's `/api/projects` is o
204
204
 
205
205
  **The resource id is the permission identifier**: the permission set page lists every route whose `authz` checks `page` `access`, keyed by `authz.resource.id` (deduplicated), under the Pages entry with its navigation groups in menu order. Stored grants reference that id, so changing it requires migrating them; renaming the route alone does not.
206
206
 
207
+ ### Permission display names
208
+
209
+ Every application route that resolves to a `page` permission needs a non-empty, translated display name, including URL-addressable forms, dialogs, drawers and detail pages. Navigation/breadcrumb titles provide it where already appropriate. For a page that intentionally has neither (especially an overlay), add its existing application route `name` and a static application translation key to `client/pages/settings/page-permission-titles.ts`. This mapping labels permissions only; do not add a menu/breadcrumb or change a route name, `authz.resource.id`, inheritance, `'skip'` or stored grants to repair copy. Plugin routes retain their owning namespace and are not overridden by an application's same-named route.
210
+
211
+ Provide English and Chinese text without unresolved interpolation placeholders. The permission catalog uses `pagePermissionResources()` and a localized unnamed-page/path fallback instead of exposing technical ids. That fallback is a diagnostic, not successful delivery: `tests/logic/page-permission-titles.test.ts` must pass against the application's actual resolved routes and locales; it rejects missing labels, stale mapping keys and untranslated keys. When fixing an existing app, preserve the complete resource/action identity list and grants, and verify display labels without rewriting authorization data.
212
+
207
213
  ## 5. Settings pages
208
214
 
209
215
  There is one kind of client route, `defineAppRoutes()`. The application has no separate settings area and no `/settings` or `/dev` prefix, and plugins contribute no settings pages: a page that configures something is an ordinary App page in the main navigation. Put such pages under a navigation group of their own, such as a Settings group at the end of the sidebar, and add the icons to the `lucide-react` import at the top of the file (here `Settings` and `SlidersHorizontal`):
@@ -23,7 +23,11 @@ Tests never go beside the source. Vitest discovers `tests/**/*.test.{ts,tsx}` an
23
23
 
24
24
  ## Building the test harness
25
25
 
26
- **For a page, copy `tests/components/page-harness.test.tsx`.** It renders a small list page with a child-route `RouteDialog` in a memory router inside the real, strict i18n runtime (next section), and mocks only what the page reaches outside itself for: `useApiClient` (keeping the real `ApiClientError`), `useCan` and `useToaster`, all created with `vi.hoisted`. Its tests are the shapes to repeat: the request the page sends, a 403 without "Retry", a 401 that offers "Sign in again", an action shown with permission and hidden without it, and a child route opened from its URL and closed back to the list. It also mocks `useAuthentication` for the 401 case. Replace its inline page with your page and its child routes, drop the `copy` the harness defines for its inline page, since your page's keys are in `client/locales/`, keep the setup, and put the file in `tests/components/` (the template's own overlay test happens to sit in `tests/logic/`).
26
+ Also run `tests/logic/page-permission-titles.test.ts` when adding or changing routes. It requires translated names for every application page permission, including overlays without navigation/breadcrumbs, and preserves the complete resource/action identity list. See [permission display names](page.md#permission-display-names).
27
+
28
+ For a page or component that uses application services, start from the [complete `@nocobase/app-testing/client` example](../../testing/client/page.md). `renderWithApp()` supplies the real API client, router, translations and toaster. Supply HTTP responses through `answerApi()`, load the application's locale map, and assert visible state and `view.toasts()`. Register the client plugins or service doubles that the page actually consumes; avoid mocking the whole `@nocobase/app-client` module.
29
+
30
+ Existing `tests/components/page-harness.test.tsx` files can still illustrate which states to cover: a request payload, a `403` without retry, a `401` offering sign-in, an action shown or hidden with permission, and a child route opened by URL. When adapting those cases, import the real page and use the application fixture for its service context. Put new files in the application's current test layout; the worked example uses `tests/client/` with an explicit React config.
27
31
 
28
32
  For anything else, start from the test that already sets it up:
29
33
 
@@ -32,7 +36,7 @@ For anything else, start from the test that already sets it up:
32
36
  - **A UI Library item**: it passes its English as `defaultValue`, but the strict runtime still fails on a key `client/locales/` lacks, so add the keys the item's README lists before testing a page that renders it.
33
37
 
34
38
  - Assert what the user can see: text, roles and accessible names, the result of a click (`@testing-library/react`, `@testing-library/user-event` and the jest-dom assertions are set up). Do not assert internal state.
35
- - To assert a toast, mock `useToaster` as the harness does, returning one shared `{ show: vi.fn(), close: vi.fn() }`, and assert what `show` was called with: its `type`, `title` and `description`, not how Base UI renders them. A component rendered without a registered toaster still renders; its toasts are logged to the console instead of shown.
39
+ - To assert a toast from `renderWithApp()`, use `await waitFor(() => expect(view.toasts()).toMatchObject([...]))` with the expected `type`, `title` or `description`. The fixture registers a test toaster and also renders its messages as text; assertions do not depend on Base UI internals.
36
40
  - When a button contains a `Spinner`, the spinner's "Loading" label becomes part of the button's name, so use a regular expression when you query by name.
37
41
  - An open `RouteDialog` or `RouteDrawer` hides the page behind it from the accessibility tree, so a role query for something behind it, such as the selected tab, passes `hidden: true`: `getByRole('link', { name: 'Orders', hidden: true })`.
38
42
  - A `Button` rendered as a `Link` (`nativeButton={false}`) has the `button` role, not `link`; query "New project" with `getByRole('button', …)`. Test an absence together with the presence case, as the harness does, so the assertion can fail.
@@ -41,72 +45,20 @@ For anything else, start from the test that already sets it up:
41
45
 
42
46
  ## A minimal component test
43
47
 
44
- Render with the real i18n runtime and the application's own locale files, a router, and one shared mock of each hook that reaches outside the component. `tests/components/` in the application holds more examples to follow.
45
-
46
- ```tsx
47
- import {
48
- TestI18nProvider,
49
- createTestI18nRuntime,
50
- } from '@nocobase/i18n/testing';
51
- import { render, screen } from '@testing-library/react';
52
- import userEvent from '@testing-library/user-event';
53
- import { MemoryRouter } from 'react-router';
54
- import { expect, it, vi } from 'vitest';
55
-
56
- import packageMetadata from '../../package.json' with { type: 'json' };
57
- import enUS from '../../client/locales/en-US.js';
58
- import OrdersPage from '../../client/pages/orders.js';
59
-
60
- // One object for the whole file, so effects that depend on `api` do not refetch on every render.
61
- const api = { request: vi.fn() };
62
- const toaster = { show: vi.fn(), close: vi.fn() };
63
- vi.mock('@nocobase/app-client', async (importOriginal) => ({
64
- ...(await importOriginal<typeof import('@nocobase/app-client')>()),
65
- useApiClient: () => api,
66
- useToaster: () => toaster,
67
- }));
68
-
69
- it('creates an order and confirms it', async () => {
70
- api.request
71
- .mockResolvedValueOnce({
72
- data: [],
73
- meta: { page: 1, pageSize: 20, total: 0 },
74
- })
75
- .mockResolvedValueOnce({ data: { id: '1' } });
76
- const runtime = await createTestI18nRuntime({
77
- application: { namespace: packageMetadata.name, resources: enUS },
78
- });
79
-
80
- render(
81
- <TestI18nProvider runtime={runtime} namespace={packageMetadata.name}>
82
- <MemoryRouter>
83
- <OrdersPage />
84
- </MemoryRouter>
85
- </TestI18nProvider>,
86
- );
87
- await userEvent.click(
88
- await screen.findByRole('button', { name: enUS.orders.create }),
89
- );
90
-
91
- expect(api.request).toHaveBeenLastCalledWith(
92
- expect.objectContaining({ path: 'orders', method: 'POST' }),
93
- );
94
- expect(toaster.show).toHaveBeenCalledWith(
95
- expect.objectContaining({ type: 'success' }),
96
- );
97
- });
98
- ```
48
+ The [complete component example](../../testing/client/page.md) includes the React config, component, English and Chinese locale files, and five cases covering bilingual submission and retry, plus pending state. Reuse that setup for a component that calls `useApiClient()`, `useTranslation()` or `useToaster()`.
49
+
50
+ For a primitive that needs translations alone, `createTestI18nRuntime()` and `TestI18nProvider` from `@nocobase/i18n/testing` can provide the smaller context. Give that runtime the application's actual namespace and locale resources and keep its strict translation checks enabled. Keep this narrower setup for components that do not consume application services.
99
51
 
100
52
  - **Do not mock `@nocobase/i18n/client`.** A mocked `t` returns what the test told it to, so a misspelt key, a key the locale file lacks, or a component reading the wrong namespace all pass. The test runtime is strict: a key missing from the whole fallback chain throws, even when the call passes a `defaultValue`.
101
53
  - When a strict runtime throws, fix the locale file or the component, not the test. Pass `strict: false` only for strings that are not keys, such as route titles passed through as their own `defaultValue`.
102
54
  - Omit `namespace` on `TestI18nProvider` for a component a plugin exports for the application to render, so the test proves the component names its own namespace.
103
- - To check a second language, pass the `client/locales/index.ts` loader map instead of a resource and call `runtime.changeLanguage('zh-CN')` inside `act`.
55
+ - To check a second language with `renderWithApp()`, pass the loader map in `namespaces` and set `locale: 'zh-CN'`. With a directly created i18n runtime, pass the loader map instead of one resource and call `runtime.changeLanguage('zh-CN')` inside `act`.
104
56
 
105
57
  `packages/libs/i18n/README.md` in the `@nocobase/i18n` package documents every option.
106
58
 
107
59
  ## Running tests
108
60
 
109
- Run only the related test files, then lint them: `tests/` is outside every tsconfig and only ESLint checks it (`tests/playwright/` is covered by `tsconfig.node.json`):
61
+ Run the related test files with the application's matching React configuration, then lint them. Inspect its tsconfig includes before claiming the tests were typechecked; many templates exclude Vitest tests from their build configs. The complete client example uses `--config vitest.client.config.ts`:
110
62
 
111
63
  ```bash
112
64
  pnpm exec vitest run <related-test-files>
@@ -251,7 +251,7 @@ Theme-aware, read-only lifecycle diagram using React Flow and ELK. Shows the cur
251
251
  - Plugin dependencies: none
252
252
  - Also installs: `@nocobase/flow-diagram`
253
253
  - Example: `@nocobase/lifecycle-diagram-demo` (`pnpm exec shadcn view @nocobase/lifecycle-diagram-demo`)
254
- - After installing: Pass description.description from useLifecycle/createLifecycleHook, currentState from view.record, availableTransitions filtered from view.available, and history from view.history.transitions. History matches the exact transition/source/destination; current state alone never implies a visited path. Pass a translated endLabel for separate decorative markers on explicit final states. Defaults to direction DOWN and autoHeight for vertical page reading. Override direction and autoHeight explicitly for compact canvases. stateActions supplies explicit configuration buttons; nodeDescription displays real policy summaries. Translate ariaLabel, stateLabel and transitionLabel; append a gear to automatic transition labels if needed. Edges are solid with inline labels and subdued neutral strokes; current/visited/available highlights use the application primary theme token. Current nodes have a stronger fill and ring, visited nodes a light fill, with no extra visited label. onStateClick/onTransitionClick open details and never fire transitions. Keep toMermaid for documentation/export.
254
+ - After installing: Pass description.description from useLifecycle/createLifecycleHook, currentState from view.record, availableTransitions filtered from view.available, and history from view.history.transitions. History matches the exact transition/source/destination; current state alone never implies a visited path. Pass a translated endLabel for separate decorative markers on explicit final states. Defaults to direction DOWN, autoHeight and initialMinZoom 0.7 for readable vertical page reading. The Fit control still shows the entire graph; an explicit initialMinZoom overrides the default. Override direction and autoHeight explicitly for compact canvases. stateActions supplies explicit configuration buttons; nodeDescription displays real policy summaries. Translate ariaLabel, stateLabel and transitionLabel; append a gear to automatic transition labels if needed. Edges are solid with inline labels and subdued neutral strokes; current/visited/available highlights use the application primary theme token. Current nodes have a stronger border and ring; icons, top accents and status footers distinguish current, visited and configurable nodes using theme tokens. onStateClick/onTransitionClick open details and never fire transitions. Keep toMermaid for documentation/export. Pass configuration={label, canConfigure, onConfigure} for automatic Configure buttons on authorized bound states and configuration selection on bound transitions. onConfigure receives the exact target and permitted bound fields grouped by native parameter key; connect the existing real editor and API. canConfigure is required and is only a UI affordance. Explicit direction/style overrides are reserved for user-requested customization; Mermaid is documentation/export only.
255
255
 
256
256
  ## Inbox
257
257
 
@@ -278,6 +278,19 @@ A header button linking to the inbox, with an amber badge for what waits on the
278
278
  - Example: `@nocobase/inbox-button-demo` (`pnpm exec shadcn view @nocobase/inbox-button-demo`)
279
279
  - After installing: Render <InboxButton badge={inboxBadge(waiting, unread)} /> inside a TooltipProvider, with inboxBadge from #components/inbox-badge, waiting what your inbox counts as waiting (0 without decisions) and unread from useInboxUnreadCount() of @nocobase/app-plugin-notification-in-app/client/inbox; useDocumentTitleBadge(badge?.text ?? null) prefixes the tab title. Add the inboxButton.* keys its README lists to client/locales/.
280
280
 
281
+ ## Other
282
+
283
+ ### data-table
284
+
285
+ Standard TanStack Table v8 table with controlled server pagination and sorting, selection and column visibility.
286
+
287
+ - Kind: component
288
+ - Install: `yes n | pnpm exec shadcn add @nocobase/data-table`
289
+ - Installs to: `client/components/data-table/column-header.tsx`, `client/components/data-table/data-table.tsx`, `client/components/data-table/index.ts`, `client/components/data-table/pagination.tsx`, `client/components/data-table/view-options.tsx`
290
+ - Plugin dependencies: none
291
+ - Example: `@nocobase/data-table-demo` (`pnpm exec shadcn view @nocobase/data-table-demo`)
292
+ - After installing: Use DataTable with typed columns and getRowId. Server data must use manualPagination and manualSorting with controlled state; never sort or paginate only a fetched page locally. pagination=false renders every supplied row and leaves pagination to the caller.
293
+
281
294
  ## Page layout
282
295
 
283
296
  ### page-container
@@ -408,3 +421,17 @@ A child route presented as a non-modal page covering the content area, keeping t
408
421
  - Plugin dependencies: none
409
422
  - Example: `@nocobase/route-child-page-demo` (`pnpm exec shadcn view @nocobase/route-child-page-demo`)
410
423
  - After installing: Return RouteChildPage from the component of a child route. It covers the nearest positioned ancestor, so render a page's own outlet beside its container rather than inside it. A child page that can only render inside another one, such as the child page of a tab, covers that one whole.
424
+
425
+ ## Workflows
426
+
427
+ ### workflow-management
428
+
429
+ Workflow administration as presentational parts: one management page with Definitions and Executions tabs, a categorized definition list, a filtered execution list, definition diagram and parameter layout, and execution history inspection beside a diagram. Wire it to application-owned routes, data and permissions.
430
+
431
+ - Kind: block
432
+ - Install: `yes n | pnpm exec shadcn add @nocobase/workflow-management`
433
+ - Installs to: `client/extensions/nocobase-workflow-management/`
434
+ - Plugin dependencies: none
435
+ - Also installs: `@nocobase/page-container`, `@nocobase/page-header`, `@nocobase/data-table`
436
+ - Example: `@nocobase/workflow-management-demo` (`pnpm exec shadcn view @nocobase/workflow-management-demo`)
437
+ - After installing: Install @nocobase/workflow-management and read @nocobase/workflow-management-demo. Render WorkflowManagementLayout around the application Outlet with URL-controlled Definitions and Executions tabs; declare sidebar navigation only on the Workflow management parent. Pass adapted rows, translated labels, search/category controls, status/empty content and callbacks to WorkflowDefinitionList and WorkflowExecutionList. WorkflowDefinitionDetail places the diagram beside an application-owned parameter form. WorkflowExecutionDetail takes transition/effect records and a renderDiagram callback receiving the selected history prefix and current state; render with @nocobase/lifecycle-diagram or an existing compatible diagram. It never executes transitions or saves configuration. Keep API fetching, URL query state, permissions, parameter persistence, recovery actions and breadcrumbs in the application. All wording comes from props; no example plugin or backend is installed. Lifecycle diagrams are preinstalled in current app templates. Omit parameters to give a node-configured diagram full width, and open the same editor from LifecycleDiagram.configuration; supplying parameters retains the existing two-column layout.
@@ -72,17 +72,17 @@ Register selectors with `resolveReviewerSelections(choices, { scope, applicantId
72
72
 
73
73
  On task creation resolve the snapshot or live rule against current organization data and persist candidates on the task. Existing candidates stay fixed. A single approver field is not a multi-person approval system. To demonstrate multiple candidates, declare a separate finite “any candidate can decide” workflow and use version checks so only one concurrent decision succeeds. Real approval plugins need their own compatibility verification for action replay, settings previews, task construction and opinion reuse; fixed current-round tasks or inherited opinions cannot stand in for rule configuration.
74
74
 
75
- ## Default configuration interfaces
75
+ ## Management pages and contextual editors
76
76
 
77
- Deliver a configuration entry as part of the process application, without waiting for a separate request. Reuse the existing settings surface and standard definition diagram; explicitly requested API-only work or an explicit omission needs no UI. Keep workflow structure source-owned.
77
+ When application requirements include a process to develop, deliver workflow management pages by default as [Lifecycle UI](lifecycle-ui.md) describes, reusing the existing management area when present. Insert declared parameter forms into the `workflow-management` block's definition-detail parameter slot; users do not need to request these pages separately. Follow the scope exceptions in [system administration](system-administration.md#default-delivery); API-only work and explicitly excluded UI need no configuration page or diagram. Declared, authorized bindings receive contextual configuration by default; management pages do not introduce a second workflow-design system.
78
78
 
79
- When building a page with configurable parameters tied to business process nodes, provide an editing entry on the corresponding diagram node or transition. For example, clicking a finance-review node can open a dialog for its reviewer rules and approval threshold, so users can adjust those values in their process context. If the page already includes a diagram, incorporate this entry as part of the page design; include the standard definition diagram and its bound editing entries as part of system settings delivery without requiring the user to ask. Parameters with no node or transition relationship can stay in an embedded form or settings page.
79
+ For workflow management pages, prefer a visible parameter form beside the process diagram, grouped by business state or transition. Show shared fields once without changing their storage/save boundaries. Use the [Lifecycle UI reference](lifecycle-ui.md) for list, detail and administration composition. Provide contextual node or transition editing for declared, authorized bindings without requiring an explicit user request; keep the same editor and save contract and do not make diagram icons the only way to discover settings.
80
80
 
81
81
  For save request IDs, follow the [browser request ID guidance](lifecycle.md#5-the-page): use an HTTP-compatible generator and retain the key for retries of the same save.
82
82
 
83
83
  The example plugin exports `ParameterEditor`, `parameterApi` and `boundParameterGroups` from `@nocobase/app-plugin-lifecycle-example/client`. They illustrate a shared editor with an injected API, complete-version CAS saves, read-only mode and preserved drafts on conflicts. They are example exports, not an automatically installed platform settings service. Applications can implement the same contracts in their own UI.
84
84
 
85
- For a working reference in the NocoBase source repository, inspect `packages/examples/app-plugin-lifecycle-example/client/pages/parameters.tsx` and `client/components/parameter-binding-editor.tsx` in the same package: `useParameterBindingEditor` connects diagram bindings to a dialog containing the shared `ParameterEditor` and refreshes the page after saving. Reuse the same editor and save contract for diagram and settings entries when both exist.
85
+ For a working management page in the NocoBase source repository, inspect `packages/templates/app-template-examples/client/pages/workflows/definition.tsx`, `parameters.tsx` and `parameter-sections.ts` in that directory. They place the parameter editor beside the diagram and map bound fields into business sections. The example plugin's `client/components/parameter-binding-editor.tsx` remains a reference for a diagram-bound dialog. These source paths are examples, not installed application imports.
86
86
 
87
87
  For click-to-edit diagrams, derive groups from description.parameterConfiguration.groups and bindings referencing the clicked state or transition name. One entry can bind several fields or groups. Intercept only bound entries; unbound entries retain the component's ordinary details. In the example, ProcessDiagram's onParameterBinding(kind, name) returns true when the shared editor handles the click. Clicking opens configuration and never fires a transition. Use the diagram component's actual node/edge callbacks rather than assuming an event API.
88
88
 
@@ -93,3 +93,9 @@ Show field titles, units, validation, read mode and effective timing. Snapshot c
93
93
  Test complete schemas and cross-field constraints, CAS/replay, reference scope and authorization before validation. Prove draft previews create no facts, first submission freezes every snapshot field, failed transactions/savepoints remove it, resubmission retains it, and missing historical fields fail. Check same-record actions/nested transitions share values while different records do not. Prove fresh live retries preserve business idempotency and record each attempt's facts.
94
94
 
95
95
  Exercise reviewer intersections/unions, duplicate and inactive/applicant filtering, changed department choices, changed organization membership and fixed existing candidates. Test simultaneous decisions. For the delivered UI entry points verify shared save behavior, read-only rendering, preserved conflict drafts, multi-field bindings, untouched unbound entries and distinct current/history labels in the running application. Use the normal testing helpers and run skills sync after installation so this reference is reachable from the normal Skill entry.
96
+
97
+ ## Contextual entry defaults
98
+
99
+ When a declared business parameter has a state/transition binding and the administrator may update it, connect `LifecycleDiagram.configuration` by default to the same authoritative editor used by the management form. Follow [the default diagram contract](lifecycle-ui.md#default-diagram-and-configuration-contract). The filtered callback selection identifies fields to focus, not a complete replacement group: preserve other values through an authorized read/merge/save with the expected revision. The server independently checks field/group permissions and validates the complete group. A node button is never evidence of runtime configurability without storage and a real consumer.
100
+
101
+ When reviewers resolve from an existing organization relationship or role membership, provide an authorized `stateActions` entry on that approval node to the existing profile/role editor, as [Lifecycle UI](lifecycle-ui.md#default-diagram-and-configuration-contract) describes. Keep those identities in their authoritative service; do not duplicate them as workflow parameters. Verify the saved relationship/membership changes the candidates for an eligible new record/task while existing fixed candidates remain unchanged.
@@ -0,0 +1,122 @@
1
+ # Lifecycle UI
2
+
3
+ Use this reference for management pages built around `@nocobase/lifecycle`. Read [record lifecycles](lifecycle.md) for runtime integration, [configurable parameters](lifecycle-parameters.md) for storage and snapshot/live semantics, and the [frontend workflow](frontend/ui-workflow.md) for UI implementation. Whenever application requirements include a process to develop, deliver its workflow management pages by default, even if the user mentions only business operations. Extend existing management pages when present. Follow the scope exceptions in [system administration](system-administration.md#default-delivery); these defaults do not add a console to API-only work or explicitly excluded UI.
4
+
5
+ ## Default management structure
6
+
7
+ 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.
8
+
9
+ Create the System management group if it is missing, or reuse the application's existing Settings group. Place Workflow management directly under that group, alongside User management, Roles and permissions, Background tasks and other applicable administration entries. 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.
10
+
11
+ ## Install and connect the block
12
+
13
+ Check `client/extensions/nocobase-workflow-management/` for an installed copy first. If missing, read `@nocobase/workflow-management-demo` with `pnpm exec shadcn view @nocobase/workflow-management-demo`, then install with `yes n | pnpm exec shadcn add @nocobase/workflow-management`. Follow the [UI Library installation guidance](frontend/references/styling.md#3-use-shadcn) for dependency placement. Read the installed README for component props and route integration. The block supplies source files; it registers no route, server service, database or permission.
14
+
15
+ Use `WorkflowManagementLayout` for the shared header and URL-controlled tabs, `WorkflowDefinitionList` and `WorkflowExecutionList` for lists, `WorkflowDefinitionDetail` for diagram/parameter cards, and `WorkflowExecutionDetail` for the diagram/history/effects composition. Pass translated labels, adapted display rows with application router links, category/search controls, loading/error/empty content and controlled callbacks. The application owns API requests, URL query state, IME-aware search, server pagination, category CRUD, breadcrumbs and authorization. Keep parameter schemas, complete-group persistence, CAS conflict handling and effective timing in the application's editor, inserted into the definition detail's parameter slot.
16
+
17
+ Render the preinstalled `LifecycleDiagram` through the diagram slot/callback by default. Preserve its standard React Flow + ELK visual language unless the user explicitly requests a different diagram style; an existing Mermaid renderer is not a compatible default. If neither is installed, add the diagram with `yes n | pnpm exec shadcn add @nocobase/lifecycle-diagram`; the block accepts a caller-supplied diagram. `WorkflowExecutionDetail` supplies the selected history prefix and resulting state to `renderDiagram`; selection is display-only. Keep recorded parameters separate from current settings and pass their display through the parameter slot. Do not add business actions or recovery requests to history selection. Remount the detail on record changes or explicit refresh to clear historical selection, following the example adapter.
18
+
19
+ ## Navigation and ownership
20
+
21
+ Separate business work (submit, approve, fulfil) from administration (definitions, categories, parameters, executions). Place the single Workflow management entry under the existing System management or Settings group; 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.
22
+
23
+ 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 single Workflow management sidebar item 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 management → Workflow management → Definitions or Executions → current item. Preserve the list's query parameters in its breadcrumb instead of adding a competing Back link.
24
+
25
+ ## Definition catalog
26
+
27
+ When classification is useful, place a category rail beside a compact table, with search and refresh above the main column. Collapse or reposition the rail on narrow screens. Lead rows with translated business titles; show technical keys below in muted text only when useful. Put execution activity in a right-aligned column: a count linking to filtered executions and a subdued latest-execution time, or an explicit never-executed state. Expose sort direction with aria-sort; sort on the client only when all results are loaded.
28
+
29
+ Keep category creation, rename, color and deletion beside the filter. Use restrained palette colors with text labels and provide keyboard reorder actions alongside dragging. Deleting the active category clears its filter and reloads affected data. Categories classify definitions without changing workflow structure.
30
+
31
+ Search business titles and supported technical names on the server. Keep a local input draft and submit on Enter outside IME composition, preserving the caret. Store applied search and category in the URL. Distinguish an empty catalog, unmatched filters, loading and errors with retry.
32
+
33
+ ## Execution list
34
+
35
+ Show workflow name, business record identity, current node/status and relevant timestamps, linking to detail. Definition activity links apply an exact workflow filter; display its label and a clear action. Use server pagination with a total, search before pagination and deterministic ordering. Reset the page when filters change; deliberately clear an exact workflow filter if a new text search supersedes it.
36
+
37
+ Keep search, workflow filter, ordering and page in query parameters, preserving them through detail and return navigation. Translate business node/state names and disable refresh while loading.
38
+
39
+ ## Definition detail
40
+
41
+ Use one PageHeader with the business title, compact category assignment and execution-count link, followed by a short business description. When categories are enabled, let administrators with update permission change or clear the assignment from the colored tag beside the title; read-only administrators see the tag without an edit control. Keep assignment and category CRUD in application adapters, following the installable demo. Category action menus use concise Edit and Delete labels. Avoid repeated titles and demonstration hints.
42
+
43
+ Place the diagram and Parameter settings in two columns on wide screens, stacking on smaller screens. Use min-w-0 children, a consistent gap and items-start so cards size independently. Give each card a heading and keep wide tables or structured values scrollable within it.
44
+
45
+ Prefer a visible parameter form beside the diagram. Group fields by business state or transition; render shared fields once in a deterministic section, with unbound fields under a workflow-level section. Visual regrouping must preserve configuration group identities, complete-group saves and revisions. Show an explicit empty state when there are no parameters.
46
+
47
+ Provide contextual controls for declared, authorized bindings by default, sharing the same editor and save contract. Do not make tiny gear icons the only way to discover settings. Inspection and editing clicks never execute transitions.
48
+
49
+ ## Diagram sizing and visual language
50
+
51
+ React Flow needs a definite sized ancestor; min-height alone inside unconstrained flex parents may collapse or oversize the canvas. Choose autoHeight for content-sized diagrams or a bounded canvas with pan/zoom and refitting after layout or container resizing. The examples use a 720px definition canvas and matching execution minimum; adapt this to the graph and viewport rather than prescribing it universally.
52
+
53
+ Fit the full graph, including outer edge routes and labels. Prefer top-to-bottom direction for tall details, readable spacing, subdued ordinary edges and labels on their routes. Give the current node a strong marker and actual history lighter highlights, retaining the diagram's textual status and icons. Keep current state, visited path and available actions distinct; infer no traversed edge from reachable states or endpoints alone. Use the shared theme tokens and translated accessible labels.
54
+
55
+ ## Execution detail
56
+
57
+ Identify workflow and business record in the title with a compact, labeled refresh action. Place a large diagram card beside a stack of History, Effects and recorded parameter information; stack on narrow screens. items-stretch can align the diagram with a taller history column when the canvas has a supported height.
58
+
59
+ Order transitions by authoritative sequence with stable tie-breakers. Show step, transition, source, destination, actor and time. Use step buttons with aria-pressed and visible selection. Selecting a step displays only the history prefix through that step and its resulting state. Label the historical view and provide a return to the latest state. Refresh diagram and history coherently.
60
+
61
+ Show effect status, attempts and errors separately: a completed transition and a failed effect are different facts. Distinguish historical snapshots/usage from current configuration, showing Not recorded for missing historical facts. Never fill gaps with today's settings or edit recorded snapshots. Prefer business labels and units; reserve JSON for diagnostics.
62
+
63
+ ## Parameter form behavior
64
+
65
+ Use business labels, units, validation and effective timing. Distinguish drafts, saved values and effective values. Follow [parameter consistency rules](lifecycle-parameters.md#snapshot-live-and-execution-consistency) for snapshot/live timing and existing task candidates rather than inventing UI-specific semantics.
66
+
67
+ Preserve drafts on revision conflicts and incidental refreshes; require a deliberate reload/retry or confirmation before discarding them. Read-only administrators see configured values without active save controls. Use the runtime's complete-group validation and concurrency contract even when the page visually regroups fields.
68
+
69
+ ## Component reuse
70
+
71
+ Check installed source first, then inspect missing items through the [UI Library catalog](frontend/references/ui-library.md) and [installation guidance](frontend/references/styling.md#3-use-shadcn).
72
+
73
+ | Need | Reuse |
74
+ | ------------------------ | ------------------------------------------------------------ |
75
+ | Page spacing and heading | `@nocobase/page-container`, `@nocobase/page-header` |
76
+ | Lifecycle graph | `@nocobase/lifecycle-diagram` |
77
+ | Other directed graphs | `@nocobase/flow-diagram` |
78
+ | Sections and controls | Existing shadcn Card, Table, Tabs, Empty, Button and Tooltip |
79
+ | Parameters | Installed runtime's editor, or an application-owned form |
80
+
81
+ Follow [diagram integration](lifecycle.md#draw-an-interactive-lifecycle-diagram) for props and demos. Example ProcessDiagram remains an application adapter, not a dependency or platform-wide API of the block. Installing Registry source does not register a runtime or backend service.
82
+
83
+ Keep fetching, authorization, mutations, catalog aggregation and parameter storage in the application. Use the workflow-management block's existing props and composition slots before creating another abstraction. Keep additional business-specific rendering in the application.
84
+
85
+ ## Source examples and verification
86
+
87
+ In a NocoBase source checkout, inspect `packages/templates/app-template-examples/client/routes.ts` for the management hierarchy, `packages/templates/app-template-examples/client/pages/workflows/index.tsx` for the shared header, URL-backed tabs and detail-mode Outlet, and the other files in that directory for list/detail page composition. Inspect `client/hooks/use-url-search.ts` in that template for Enter-submitted search with IME handling. Its `server/providers/workflow-management.ts` and `server/routes/workflows.ts` illustrate permissions and aggregation. These private paths are not package exports and may not exist in a generated application. Example plugin components are optional references, not required dependencies.
88
+
89
+ Verify that an authenticated administrator can discover Workflow management and inspect the implemented definitions and executions, and that ordinary users cannot access restricted pages or APIs. Verify that the sidebar contains exactly one Workflow management entry and no Definitions or Executions entries, that both in-page tabs select the correct URL and content, and that reloads and browser back/forward preserve the selected view. Verify direct detail URLs, filter-preserving return navigation, read-only access, empty/error/retry states and keyboard controls. Prove historical selection changes only the display. Check long labels, dense history, graph fitting after resizing and narrow screens in a browser; run checks scoped to changed packages and consumers.
90
+
91
+ ## Default diagram and configuration contract
92
+
93
+ Current Default and Examples templates preinstall `#components/lifecycle-diagram`, `#components/flow-diagram` and the workflow-management block source. Check those local files first; bind real data rather than selecting a new graph library. A bare template still has no workflow menu or business registration. A requested visual customization normally adjusts the same React Flow component; it does not imply permission to replace the renderer or remove configuration/history behavior. When upgrading an existing application, reconcile the template source through the upgrade Skill; do not overwrite a customized graph or editor wholesale. An explicit user request to retain or customize a visual takes precedence; otherwise bring a legacy Mermaid management view onto the standard component while preserving its business data and routes.
94
+
95
+ For older templates missing a component, use `pnpm exec shadcn view @nocobase/lifecycle-diagram-demo` and `yes n | pnpm exec shadcn add @nocobase/lifecycle-diagram`. These names identify **shadcn UI Registry items**, not npm packages: `npm view` or `pnpm view` returning 404 says nothing about their availability. Check `components.json` and the configured registry URL. Report an actual shadcn/registry failure with the command and error; do not silently substitute Mermaid, an image, a raw SVG or a custom canvas. Keep Mermaid for documentation/export only.
96
+
97
+ Use `LifecycleDiagram.configuration` to derive contextual controls from `description.parameterConfiguration.groups[*].fields[*].bindings`. Supply translated `label(target)`, an explicit `canConfigure(group, fieldKey, field)` based on real read/update permissions, and `onConfigure(selection)` opening the authoritative parameter editor. The callback receives the exact state/transition and permitted bound fields grouped by native key; it never executes a transition. A state gets a button for its own bindings and declared policies on its outgoing transitions. A single outgoing policy opens that transition's editor directly; several targets use a compact chooser. Existing state controls stay direct, with additional transition choices beside them. The selection retains the exact native target and fields; no binding or parameter is invented. Bound edges still open the same editor on selection. Unbound/denied elements retain inspection, and record-history diagrams normally omit this adapter. Keep `stateActions` for additional business-specific controls. If the editor is contextual only, omit `WorkflowDefinitionDetail.parameters` for a full-width diagram; the existing parameter slot remains available for the same editor beside the canvas.
98
+
99
+ ```tsx
100
+ <LifecycleDiagram
101
+ description={definition.description}
102
+ ariaLabel={t('processes.definition')}
103
+ stateLabel={(state) => t(`expenses.states.${state.name}`)}
104
+ transitionLabel={(transition) => t(`expenses.transitions.${transition.name}`)}
105
+ configuration={{
106
+ label: () => t('processes.configure'),
107
+ canConfigure: (group, key) =>
108
+ permissions.canUpdateParameter(group.key, key),
109
+ onConfigure: (selection) => openParameterEditor(selection),
110
+ }}
111
+ />
112
+ ```
113
+
114
+ `permissions` and `openParameterEditor` above are application-owned adapters, not framework exports. Implement them against the installed authenticated parameter service/editor. Preserve fields outside the selected binding when saving a complete group; fetch the authorized save context and revision rather than sending the filtered selection as a replacement. If partial group editing cannot preserve restricted fields safely, require group update permission and expose no edit control until the server supports it. Handle validation errors and revision conflicts without discarding drafts; read the saved version back and refresh the current policy summary. Use the field's native `number`, `boolean`, `string`, `reviewers` or declared object schema with appropriate business controls, not a JSON textarea for approver identities. Configuration updates require independent server authorization and audit.
115
+
116
+ On every process-building iteration, identify administrator-owned business policy: approval thresholds and reviewer selection are typical defaults, even if the request never says configurable. Declare their native parameter metadata, meaningful state/transition bindings, validation, permissions, storage and actual runtime consumers together. Use existing organization relationships for direct supervisors. When reviewer resolution is owned by member profiles or role membership rather than workflow parameters, expose an authorized, translated `stateActions` link/button on the corresponding approval node to open those authoritative settings. Check the destination's read/update permissions; hide mutation entries from read-only and history views. Reuse that editor and service, explain when changes affect new versus existing records/tasks, and preserve return navigation. Do not invent a duplicate workflow parameter merely to get a configuration button. Do not add fake editable fields for secrets, topology, unsupported timing or code-only constants. Preserve snapshot/live timing and historical task candidates as [parameter configuration](lifecycle-parameters.md) defines.
117
+
118
+ ## Acceptance against the original requirement
119
+
120
+ A design approval does not prove component availability or authorize a fallback based on an npm 404. Reviewers must compare the implementation to this default contract and the user's original requirements, not just the amended design. Inspect actual rendered component imports, the canvas and the bound editor. Business tests alone do not establish standard component reuse.
121
+
122
+ For release acceptance, start a clean published-template app and use only business prompts (no hints to use React Flow, system settings or configurable nodes). Verify Home-only before business work; then the single management entry, definition directory even for one process, standard graph, authorized bound controls and execution history. Save a threshold/reviewer through a node's editor (or its authoritative organization-settings entry), reload it, submit a new record and verify the actual branch/candidate change. Verify organization-derived reviewer nodes link to the real profile/role editor, not just a descriptive label or a second identity store. Check an earlier submitted record retains its snapshot, a read-only user has no mutation controls, and direct unauthorized API writes fail. Check light/dark, narrow layouts and long labels. Record any untested browser or Agent-generation behavior explicitly; never call it passed on static imports alone.
@@ -4,6 +4,10 @@ Use `@nocobase/lifecycle` when a business record moves through stages that devel
4
4
 
5
5
  Administrators can adjust code-declared business parameters without editing workflow structure. Proactively declare suitable approval departments, reviewer choices and thresholds as business parameters, even without an explicit configurability request. For declarations, snapshot/live reads and shared configuration editors, read [configurable lifecycle parameters](lifecycle-parameters.md).
6
6
 
7
+ ## Deliver workflow management by default
8
+
9
+ 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 sidebar entry 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.
10
+
7
11
  ## Choose it or something else
8
12
 
9
13
  | The requirement | Use |
@@ -439,13 +443,13 @@ The installed package's README lists its entries; the full guide, design notes a
439
443
 
440
444
  ## Draw an interactive lifecycle diagram
441
445
 
442
- When building a process page whose configurable business parameters relate to nodes or transitions, provide an entry on the corresponding diagram element that opens a parameter-editing dialog. Map the clicked state's or transition's stable name through code-declared parameter bindings and open the same editor used by the settings page or embedded form, if present. A bound entry can expose several groups; unbound entries keep their ordinary details. Read [configurable lifecycle parameters](lifecycle-parameters.md#default-configuration-interfaces) for the working example, authorization, CAS conflicts and current-versus-historical values.
446
+ For workflow management lists, definition and execution details, diagram sizing and parameter form placement, read [Lifecycle UI](lifecycle-ui.md). Prefer a visible parameter form beside the diagram on management pages; provide contextual configuration for declared, authorized bindings by default through `LifecycleDiagram.configuration`, opening the same editor. Use the same editor and save contract for both. Read [configurable lifecycle parameters](lifecycle-parameters.md#management-pages-and-contextual-editors) for authorization, CAS conflicts and current-versus-historical values.
443
447
 
444
- When a page needs a lifecycle diagram, use the UI Library's `@nocobase/lifecycle-diagram` component (React Flow + ELK) instead of building a canvas or turning Mermaid source into an interactive view. Read `pnpm exec shadcn view @nocobase/lifecycle-diagram-demo`, then install with `yes n | pnpm exec shadcn add @nocobase/lifecycle-diagram` and format the created files. It includes `@nocobase/flow-diagram`, which is also available alone for a generic directed graph. Follow [the UI Library guidance](frontend/references/styling.md#3-use-shadcn) and its [offline catalog](frontend/references/ui-library.md) for discovery and installation.
448
+ When a page needs a lifecycle diagram, first reuse the template's preinstalled `#components/lifecycle-diagram`; otherwise install the UI Library's `@nocobase/lifecycle-diagram` component (React Flow + ELK) instead of building a canvas or turning Mermaid source into an interactive view. Read `pnpm exec shadcn view @nocobase/lifecycle-diagram-demo`, then install with `yes n | pnpm exec shadcn add @nocobase/lifecycle-diagram` and format the created files. It includes `@nocobase/flow-diagram`, which is also available alone for a generic directed graph. Follow [the UI Library guidance](frontend/references/styling.md#3-use-shadcn) and its [offline catalog](frontend/references/ui-library.md) for discovery and installation.
445
449
 
446
450
  Import `LifecycleDiagram` from `#components/lifecycle-diagram`. Pass the hook's `description.description`, an `ariaLabel`, `currentState: view.record.status` (use the lifecycle's own state field), and `availableTransitions: view.available.filter((item) => item.allowed).map((item) => item.name)`. Translate labels by stable state/transition names with `stateLabel` and `transitionLabel`; add the shared `flowDiagram` keys to your locale resources. Use `onStateClick` and `onTransitionClick` to open details, including effects, triggers and continuations from the description. Definitions remain in source and clicking the diagram never fires a transition; action buttons still follow `view.available`. Pass `history={view.history.transitions}` for visited paths; the component matches the exact transition, source and destination, including retries. `visitedStates` supplements node highlights only; never infer a traversed edge from the current state or visited endpoints. Pass a translated `endLabel` to display a separate decorative end marker after each explicit final state, without treating every state lacking outgoing transitions as final. Keep `toMermaid()` for documentation and export.
447
451
 
448
- `LifecycleDiagram` defaults to `direction="DOWN" autoHeight`. For direct `FlowDiagram` composition on a process page, set those props explicitly: the canvas grows with the full layout, including outer routes and labels. A wide graph fitted into a short fixed-height panel makes its labels unreadable. Check the actual lifecycle definition in the target page, rather than judging a simple preview alone.
452
+ `LifecycleDiagram` defaults to `direction="DOWN" autoHeight`. For direct `FlowDiagram` composition on a process page, set those props explicitly. Choose automatic height for a content-sized diagram, or a deliberately bounded canvas for the side-by-side management layouts in [Lifecycle UI](lifecycle-ui.md#diagram-sizing-and-visual-language). Fit the full routed graph, including outer edges and labels. A wide graph fitted into a short fixed-height panel makes its labels unreadable; verify the actual lifecycle in the target page.
449
453
 
450
454
  The label callbacks receive description objects, not name strings. Read `state.name` in `stateLabel` and `transition.name` in `transitionLabel` when building translation keys:
451
455
 
@@ -456,6 +460,6 @@ transitionLabel={(transition) => t(`leaves.transitions.${transition.name}`)}
456
460
 
457
461
  Adapt the translation key prefix to the feature.
458
462
 
459
- Preserve the component’s application theme tokens: `--primary` for current, visited and available highlights, subdued neutral strokes for other edges, and card/foreground/border tokens for the canvas and labels. Current nodes have a stronger fill and ring, visited nodes a light fill, with no extra “visited” label. Labels stay on the routes; automatic transitions remain solid and may show `⚙` through `transitionLabel`. Do not introduce a separate palette or hard-coded accent color. Check light/dark themes and a changed application primary color when customizing the rendering.
463
+ Preserve the component’s application theme tokens: `--primary` for current, visited and available highlights, subdued neutral strokes for other edges, and card/foreground/border tokens for the canvas and labels. Current nodes use an accent border and ring, visited nodes a subtler accent border, and both retain the upstream textual status and icon so execution state does not rely on color alone. Labels stay on the routes; automatic transitions remain solid and may show `⚙` through `transitionLabel`. Do not introduce a separate palette or hard-coded accent color. Check light/dark themes and a changed application primary color when customizing the rendering.
460
464
 
461
- For narrow layouts, use `initialMinZoom={0.8}` to preserve readable node content, with pan and a full-graph Fit control. Do not add a minimap to standard process pages by default; `showMiniMap` remains opt-in for consumers that need it. `stateActions` on LifecycleDiagram (or `nodeActions` on FlowDiagram) exposes explicit configuration buttons; `nodeDescription` adds real policy summaries. Supply enough fixed node height for the content. Definition views show the latest configured policy, while record views identify their submission snapshot. Never invent reviewer names, policy values or execution highlights. Standard business process pages omit system-only technical edit paths without adding a technical display toggle; retain every business approval, rejection, withdrawal and resubmission path. Technical diagnostic views may expose the complete source description separately when explicitly needed.
465
+ For narrow layouts, use `initialMinZoom={0.8}` to preserve readable node content, with pan and a full-graph Fit control. Do not add a minimap to standard process pages by default; `showMiniMap` remains opt-in for consumers that need it. `configuration` on LifecycleDiagram automatically exposes declared, authorized bindings through the real editor; `stateActions` (or `nodeActions` on FlowDiagram) adds custom controls; `nodeDescription` adds real policy summaries. Supply enough fixed node height for the content. Definition views show the latest configured policy, while record views identify their submission snapshot. Never invent reviewer names, policy values or execution highlights. Standard business process pages omit system-only technical edit paths without adding a technical display toggle; retain every business approval, rejection, withdrawal and resubmission path. Technical diagnostic views may expose the complete source description separately when explicitly needed.
@@ -0,0 +1,32 @@
1
+ # System administration
2
+
3
+ ## Default delivery
4
+
5
+ A complete application includes System management navigation 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
+
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
+
9
+ ## Administration baseline
10
+
11
+ | Capability | Default outcome |
12
+ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13
+ | User management | Administrators can list and manage application users, their active status and supported account lifecycle operations through the installed user and authentication capabilities. |
14
+ | Roles and permissions | Administrators can manage roles, assign users and configure the application's supported page, action and data access permissions. |
15
+
16
+ For implemented workflows, background tasks and notifications, deliver status, execution or delivery records, failure reasons and supported recovery actions within their respective management pages. Reuse installed execution capabilities and add missing application-owned views. Do not invent telemetry or offer recovery actions the runtime cannot perform. Infrastructure dashboards and external observability platforms require relevant scope.
17
+
18
+ Add management pages for the capabilities the application uses: organizations and departments, business reference data, integration and notification settings, background tasks, and workflow definitions, parameters and executions. Whenever requirements include a process to develop, include its workflow management pages by default following [Lifecycle UI](lifecycle-ui.md), even if the user did not separately request a management console.
19
+
20
+ ## Navigation and access
21
+
22
+ Group administrative capabilities under a consistent System management or Settings section, separate from business navigation. Reuse an existing group and follow [settings pages](frontend/references/page.md#5-settings-pages); 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
+
24
+ Place User management, Roles and permissions, Workflow management, Background tasks and other applicable capabilities directly under System management as sibling menu entries. Include capability-specific entries only when the application uses those capabilities. Do not introduce an Operational monitoring menu or an intermediate monitoring group. Workflow management is a single clickable sidebar entry 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. Follow the same structure under an existing Settings section.
25
+
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
+
28
+ ## Acceptance
29
+
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
+
32
+ Verify that applicable management entries are siblings directly under System management, with execution records and failures accessible inside each capability. When the application includes workflows, verify that Workflow management has one sidebar entry 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.